Reports · Shared client platform

Hoichoi client platform

How the new native-platform architecture fits together: one SolidJS app that makes every decision and ships over the air, thin Android/iOS/TV hosts that expose OS capabilities, and the generated kwry bridge between them. Every box and arrow below links to the code that proves it.

Mapped by Claude (agent) from source at a950df76e · kwry 29b36e1Public · every page in this group shares one access rule

The one-line model

JS is the brain, native is the hands. The page (core/decisions) decides boot, deep links, downloads, licences and billing. Native islands own OS resources and report raw facts. A single Kotlin contract (Contract.kt) generates both sides of the bridge, so a mismatch is a build error.

24@Island interfaces
Islands in the contract
92+ 17 observations
Bridge methods
116contract.lock.json
Versioned wire names
2026-12-p50 frozen releases
Contract tag
53lines (was 999)
Phone host MainActivity
4Android · TV · iOS · macOS
Hosts

Counts are from source at a950df76e: grep -c @Method -r contract/src/commonMain and the wire names in contract.lock.json; MainActivity length from MainActivity.kt.

The whole platform on one page

ArchitectureSystem overviewOpen full reader ↗
Hoichoi Shared Client Platform — system overviewfeat/SD/native-platform @ a950df76e · one SolidJS brain, thin native hosts over the kwry bridgeViewer · phone · TV · browser · Architecture componentViewerphone · TV · browserhoichoi-web · SSR · hoichoi.tv · Architecture componenthoichoi-webSSR · hoichoi.tvhoichoi-mobile · mobile.hoichoi.tv · Architecture componenthoichoi-mobilemobile.hoichoi.tvTV bundles · SolidTV · tv-kit · Architecture componentTV bundlesSolidTV · tv-kitSolid app UI · ui · mweb · tv-kit · JavaScript (ships over the air)Solid app UIui · mweb · tv-kitOTA shell · /boot /offline /update · JavaScript (ships over the air)OTA shell/boot /offline /updatepackages/core · decisions · vm · intents · JavaScript (ships over the air)packages/coredecisions · vm · intentsPorts (interfaces) · VmPorts · HostShell · JavaScript (ships over the air)Ports (interfaces)VmPorts · HostShellHoichoi APIs · core · contents · licence · Architecture componentHoichoi APIscore · contents · licenceshell-kwry · generated TS client · JavaScript (ships over the air)shell-kwrygenerated TS clientKotlin contract · 24 islands · 2026-12-p · Architecture componentKotlin contract24 islands · 2026-12-pkwry runtime · JSON-RPC · hello · OTA store · Native app binary (store release)kwry runtimeJSON-RPC · hello · OTA storeIslands (KMP) · player · downloads · cast · Native app binary (store release)Islands (KMP)player · downloads · casthost-core · origins · policy · floors · Native app binary (store release)host-coreorigins · policy · floorsAndroid phone · MainActivity · PhoneIslands · Native app binary (store release)Android phoneMainActivity · PhoneIslandsiOS host · Swift App → HoichoiHost · Native app binary (store release)iOS hostSwift App → HoichoiHostAndroid TV · TvActivity · Architecture componentAndroid TVTvActivityOS + SDKs · Media3 · AVPlayer · Play · Architecture componentOS + SDKsMedia3 · AVPlayer · PlayCI gates · Gate H · Gate A · Architecture componentCI gatesGate H · Gate AbrowserappTVSSROTA shelldecisionsbootStep()HTTPShost portsgeneratesJSON-RPCdispatchOS callsKwryAppHostIslandsfloorslock checkJavaScript (ships over the air)Native app binary (store release)LegendFrontendBackendCloudSecurityMessage busExternal

Two boundaries matter: everything inside JavaScript ships on the next web deploy; everything inside Native app binary needs a store release. Open the interactive version for guided views, hover-to-source and focus.

Explore every component

Pick any component to open its deep dive: what it is, why it is built this way, the alternatives rejected, a pinned code excerpt, what it talks to, gotchas and references.

Who owns what

LayerOwnsNever ownsLives in
Solid app + coreEvery product decision: boot, routing, intents, entitlement, licence protocol, downloads policy, billing offers, copyOS handles, threads, files outside storage islandpackages/core, packages/ui
OTA shellThe screens a native app needs without network: /splash /boot /update /offline /downloadsThe online app routesshell/main.tsx
shell-kwryThe page end of the bridge: one memoised connection, generated typed client, Solid bindingsAny hand-typed wire name (generated only)ports/client.ts
Kotlin contractThe list of islands, methods, observations, release tags, surfacesBehaviourSurfaces.kt
kwry runtimeTransport, hello handshake, budgets, cancellation, OTA bundle storeHoichoi product logicsubmodule apps/native/kwry @ 29b36e1
IslandsOne OS capability each: player engines, downloads, cast, billing, push, window, storage…Decisions; they apply what the page sentislands/
host-coreShared host floors: origins, update policy parsing, navigation table, payment guardPage statehost-core/
HostsWiring: which islands a surface installs, the WebView, splash, OS callbacksBusiness rules (Gate H)PhoneIslands.kt

Where the code lives

TreeRepository layoutOpen full reader ↗
Where the code livesRepository layout at a950df76e (selected folders)Hoichoi.SharedClientPlatform · pnpm + Gradle monorepo · RootHoichoi.SharedClientPlatformpnpm + Gradle monorepoapps/ · deployables · Branchapps/deployablespackages/ · shared TS layers · Branchpackages/shared TS layersapps/native/ · KMP hosts + islands · Branchapps/native/KMP hosts + islandsweb · SolidStart · phone build · shell · LeafwebSolidStart · phonebuild · shelltv · SolidTV DOM (LG/Samsung) · LeaftvSolidTV DOM (LG/Samsung)androidtv · tv-kit WebGL + kwry · Leafandroidtvtv-kit WebGL + kwryvidaa-tv · edge Worker · Leafvidaa-tvedge Workerinterfaces · ports + types · Leafinterfacesports + typescore · decisions · vm · intents · Leafcoredecisions · vm · intentsui / mweb · views + web port bindings · Leafui / mwebviews + web port bindingstv-kit · TV screens + ports · Leaftv-kitTV screens + portsplayer · Shaka web + native bridge · LeafplayerShaka web + native bridgeshell-kwry · generated kwry client · Leafshell-kwrygenerated kwry clientapi · auth · analytics … · I/O + telemetry · Leafapi · auth ·analytics …I/O + telemetrycontract · @Island interfaces · schema · Leafcontract@Island interfaces· schemaislands · OS capabilities (KMP) · LeafislandsOS capabilities (KMP)host-core · origins · policy · floors · Leafhost-coreorigins · policy · floorsvideoplayer-core · player-engine module · Leafvideoplayer-coreplayer-engine modulehosts/ · android · androidtv · ios · macos · Leafhosts/android · androidtv· ios · macoskwry (submodule) · bridge runtime + codegen · Leafkwry (submodule)bridge runtime + codegen20476Expand all

pnpm workspace for apps/* and packages/* (pnpm-workspace.yaml); Gradle KMP build under apps/native, also opened from the repo root so the IDE indexes it (settings.gradle.kts).

How a request crosses the bridge

SequenceOne bridge call, end to endOpen full reader ↗
One bridge call: page → island → resulthostSolid().window.setOrientation({ orientation: 'landscape' })setOrientation(p)advertised v1? fit(p)encode + callJSON-RPC frameorient.lock()result / UNAVAILABLEdecodeEmptyOutcome {ok}Page side (OTA JS)Native side (app binary)ResultSolid page · mweb / player · Sequence participantSolid pagemweb / playergen/solid.ts · operation() + fit() · Sequence participantgen/solid.tsoperation() + fit()gen/client.ts · encode · gate · Sequence participantgen/client.tsencode · gatekwry Bridge · JSON-RPC · WebMessage · Sequence participantkwry BridgeJSON-RPC · WebMessageWindowIsland · generated dispatch · Sequence participantWindowIslandgenerated dispatchOS · orientation lock · Sequence participantOSorientation lockLegendmain requestreturnmessage

The page calls a generated operation; it checks the host advertised the wire in hello, encodes, sends JSON-RPC over WebMessage, and the KSP-generated dispatch calls the island. The result comes back as a typed Outcome. Deep dive: kwry bridge.

How the app starts

WorkflowCold startOpen full reader ↗
Cold start: host loads the shell, the shell decidesAndroid phone; iOS follows the same steps through Update.boot01 / Native host02 / OTA shell (JS)03 / App page (JS)Activity start · intent → intents buffer · Native hostActivity startintent → intents bufferBundleStore · seed + 2 OTA slots · Native hostBundleStoreseed + 2 OTA slotsrefreshShell() · stage next bundle · Native hostrefreshShell()stage next bundle/boot · shell.hoichoi.app · OTA shell (JS)/bootshell.hoichoi.appbootStep()? · update mode · network · OTA shell (JS)bootStep()?update mode · network/update · FORCE policy · OTA shell (JS)/updateFORCE policy/offline · downloads list · OTA shell (JS)/offlinedownloads listapp.load(url) · ShellLoader only · App page (JS)app.load(url)ShellLoader onlyApp ready · splash released · App page (JS)App readysplash releasedread factsonlineno networkFORCEopen seedbridge.readyserve /bootafter startLegendScreen / documentJS decisionGate / trustBridge callNetwork fetch

The host only serves the seeded shell's /boot from its bundle store. The shell's bootStep() decides update, offline or load; the host's only navigation path is ShellLoader. A newer shell is staged in the background (refreshShell).

How playback gets a licence

SequencePlayback and DRM licenceOpen full reader ↗
Playback + DRM licence: the page answers every key requestAndroid Media3 path; iOS FairPlay uses the same brokersession.open(Open)coordinator.openprepare(manifest)challenge bytesEffect.LicenseRequestPOST challenge + tokenlicenceCommand.ProvideLicenseprovide(id)state · QoS effectsOpen (JS chose rendition + DRM)Key request round-tripPlayingPlayer (JS) · native-main.ts · Sequence participantPlayer (JS)native-main.tsSessionWire · contract ↔ engine · Sequence participantSessionWirecontract ↔ engineSessionCoordinator · one surface · retry · Sequence participantSessionCoordinatorone surface · retryMedia3Engine · ExoPlayer + CDM · Sequence participantMedia3EngineExoPlayer + CDMLicenceBroker · timeout → NO_ANSWER · Sequence participantLicenceBrokertimeout → NO_ANSWERLicence server · Hoichoi contents API · Sequence participantLicence serverHoichoi contents APILegendmain requestreturnsecurityasync tracemessage

The CDM's challenge goes to the page as Effect.LicenseRequest; the page POSTs it with its own token logic (fetchPost) and answers with Command.ProvideLicense. No answer in time fails as LICENCE_NO_ANSWER (LicenceBroker).

How the bridge is generated

Data flowOne contract, two languagesOpen full reader ↗
One contract, generated into both languagesKotlin @Island interfaces → KSP + islandgen → Kotlin dispatch and TS client; CI fails on drift01 / Author02 / Generate03 / Artifacts04 / Consumers@Island interfaces · 24 islands · 01 / Author@Island interfaces24 islandsKSP processor · kwry bridge-gen · 02 / GenerateKSP processorkwry bridge-genislandgen · schema + TS · 02 / Generateislandgenschema + TSKotlin dispatch · *Dispatch · Containers · 03 / ArtifactsKotlin dispatch*Dispatch · Containersschema + lock · releases · breaking.toml · 03 / Artifactsschema + lockreleases · breaking.tomlTS client · shell-kwry/src/gen · 03 / ArtifactsTS clientshell-kwry/src/genNative hosts · install islands · 04 / ConsumersNative hostsinstall islandsCI checks · islandgenCheck · tsc · 04 / ConsumersCI checksislandgenCheck · tscPage code · hostSolid() ops · 04 / ConsumersPage codehostSolid() opsannotationswalk schemaKotlin coderelease JSONTS codecompileevolution checkimportLegendprimary datapolicy / PIIdata storedata flow

KSP emits the Kotlin dispatch and per-surface containers; islandgen writes the schema, the frozen release JSON and the TS client into shell-kwry/src/gen. CI fails on a stale TS client or an unapproved breaking change (breaking.toml).

Talks to what

FromToHowProof
Viewer (browser)hoichoi-web WorkerSSR + hydrate on hoichoi.tvwrangler.jsonc
Native WebViewhoichoi-mobile WorkerPhone build on mobile.hoichoi.tv, plus /shell/<id>/ OTA files and /.well-known/shell-policy.jsonwrangler.mobile.jsonc
PageHost islandsJSON-RPC 2.0 over WebMessageListener (Android) / WKScriptMessageHandler (Apple)connectKwry
PageHoichoi APIsHTTPS from the WebView, including every DRM licence POSTapi/client.ts
HostPageObservations (LATEST / LOSSLESS) and effects, e.g. telemetry.events.v2, intents.events.v1host-telemetry.ts
Phone pageTV receiverTyped peer bridge over the Cast text channel (castPeer)cast-peer.ts
IslandsOS / SDKsMedia3, AVPlayer, Play Billing, StoreKit 2, Cast, FCM, WorkManagerislands deps

Read next

kwry bridge

  • Wire protocol, hello, budgets, transports
  • Codegen and compile-time checks
  • OTA bundle store and trust

Native hosts and islands

  • Which islands each host installs
  • What each host still owns
  • Threading and scopes

JS layers and ports

  • Apps, packages, dependency direction
  • Where decisions live
  • Player, telemetry, deploy and CI

How the DRM licence works

  • Challenge sizes and caps
  • Why the page makes the call
  • Cost of the round-trip

Where networking happens

  • JS fetch vs native Ktor vs media engines
  • Every path, with the reason
  • What could still move to JS

Gaps and drift

  • Places the host still decides
  • Declared-but-unused contract rows
  • Doc and vendored-code drift