Hoichoi client platform · Apple TV + Roku

TV leaf renderer: proposal and PoC

One Solid UI for every TV: the same screens render through DOM on web TVs, UIKit on Apple TV and SceneGraph on Roku, with only a thin layer of primitives per platform. This page shows how, why each decision was made, the code that inspired it, and the experiments that prove or kill it.

Proposal by Claude (agent) from Hoichoi.SharedClientPlatform a950df76e, apple-tv 87f92f1f3, react-native-tvos d930b93, exact 94b8671Public · every page in this group shares one access rule

Read this first: one UI, three renderers

We write every TV screen once, in Solid, against about 12 primitives (Screen, Text, Card, Rail, Focusable, Player…). The same screen source compiles three times, because all three targets use the same Solid compile mode, solid-js/universal. Only the primitives differ: DOM for web TVs (what we ship today), UIKit for Apple TV (new, spiked below), SceneGraph for Roku (Roku's own @roku-sdk/solid, checked in source). Screens, view models, core, api, routing and analytics are not forked.

Update: styling moves to a compiled CSS subset

The rule below that primitive props are "semantic, not CSS" is refined by Solid native: styling is written in a strict CSS subset and compiled to a style table at build time, while behaviour (focus, rails, selection) stays as semantic props on primitives. The same subset then renders natively on Android and iOS as well.

One screen source, three targets

// packages/tv-ui/screens/Home.tsx — shared, unchanged on DOM / UIKit / Roku
import { For } from 'solid-js'                     // aliased to @roku-sdk/solid on the Roku build
import { Screen, Rail, Card, Text } from '@hoichoi/tv-ui/primitives'

export function Home(p: { vm: HomeVm }) {
  return (
    <Screen>
      <Text role="hero">{p.vm.hero()}</Text>
      <For each={p.vm.rails()}>{(rail) =>
        <Rail title={rail.title} items={rail.items}
              onFocusItem={p.vm.focus} onSelectItem={p.vm.open}
              renderItem={(it) => <Card image={it.poster} title={it.title} />} />
      }</For>
    </Screen>
  )
}

The build picks the primitive set with one alias per target, so a screen never knows where it runs:

// vite (web + TV web):  '@hoichoi/tv-ui/primitives' → primitives/dom
// NativeScript tvOS:     '@hoichoi/tv-ui/primitives' → primitives/uikit
// rk build (Roku):       '@hoichoi/tv-ui/primitives' → primitives/roku,  'solid-js' → '@roku-sdk/solid'
PrimitiveDOM (web, LG, Samsung, Vidaa)UIKit (Apple TV)Roku SceneGraph
RendererSolidTV (exists)our solid-js/universal → UIView (spiked)@roku-sdk/solid (Roku's, nothing to write)
Screen / View<view>UIView<group>
Text<text>UILabel (CoreText)<label>
Card<view> + imagecollection cell, Apple's focus lift<poster loadWidth…>
Rail<Row scroll>UICollectionView (recycled)@roku-sdk/flex-grid (pooled)
FocusableSolidTV focus managertvOS focus engineFocusBoundary (TS-routed)
PlayerShakaAVPlayerViewController + FairPlay<video> + drmParams (Widevine / PlayReady)
~0.4klines · wrap today's tv-kit
Glue for DOM
~1.6klines · renderer + primitives
Glue for UIKit
~0.5klines · primitives + alias
Glue for Roku
everything elsescreens · VMs · core · api
Written once

Line counts are estimates from the spike (~400 lines) and the primitive list, not measured on finished code.

Four rules that keep the glue small

  • Screens import only primitives. No <view>, <poster> or UIView in a screen; an ESLint rule enforces it, as Gate H does for hosts.
  • Props are semantic, not CSS. role, size, focus scale; per-platform values come from the metrics table. A prop one target can't draw stays out of the contract.
  • Focus is declared, not routed. Screens say onFocusItem / onSelectItem; each target moves focus its own way. Hand-written onUp/onDown leaves the screens.
  • The player takes the page's decisions. Rendition, licence and token stay in core.

What differs on purpose, and open items

  • Look: SF Pro on tvOS, Roku fonts and safe areas, via the metrics table.
  • Roku runs Roku's Solid fork: import through @roku-sdk/solid; lazy, createDeferred, SuspenseList are unavailable (EXPORTS.md).
  • Roku DRM: its video node fetches the licence itself from licenseServerURL (content-node.props.ts), so the URL must carry a short-lived token minted by JS. Backend decision needed.
  • Roku OS 16+ only, SDK in beta (requirements): check our Roku install base.

Reuse map: what we take, from where

Nothing below is built from scratch if a maintained, licensed implementation exists. Use = a dependency; transplant = port the code with its licence notice; borrow the idea = no code taken. Commits are pinned so the line ranges stay valid. Links into hoichoitech/* are a private repo: they open for org members and 404 for everyone else.

TakeFrom (pinned)How battle-testedLicenceHow we use it
Roku Solid renderer@roku-sdk/solid v2.19.1, Roku Inc.Roku's official SDK; on npm; beta, needs Roku OS 16+MITUse as is (dependency). Our Roku primitives render through it.
Roku rails@roku-sdk/flex-grid 3.xOfficial; node pooling + 4 focus strategiesMITUse as is for Rail on Roku.
Roku focusFocusBoundary in @roku-sdk/navigationOfficialMITUse as is for Focusable on Roku.
tvOS focus layerreact-native-tvos RCTViewComponentView.mm @ d930b93: focus guide 307–349, trap 693–707, didUpdateFocus + parallax 709–751 and 430–470The maintained React Native fork for Apple TV and Android TV (1,430★, MIT, pushed 2026-11-09); which production apps ship it is unverified, no sourceMIT (keep the notice)Transplant: port the tvOS branches into our HVView (Swift). Not a dependency: it is bound to React Fabric.
tvOS runtimeNativeScript tvOS @nativescript/[email protected] (already in feat/avijit/apple-tv)NativeScript 25.7k★, active; the tvOS line is a prerelease tagMITUse: JS engine + Objective-C bridge. It has no tvOS focus APIs, so focus comes from the transplant above.
Solid → native renderer patternnativescript-community/solid-js renderer.jsSmall (73★), last commit 2025-09; the pattern is Solid's own createRendererMITCopy the pattern (~60 lines): createElement / setProperty / insertNode / removeNode → our UIKit node. Skip its DOMiNATIVE fake-DOM layer.
Recycled rails on tvOSUIKit UICollectionView (Apple)Platform primitive—Use directly (proven in the spike: 54 cells for 120 posters). ui-collectionview (62★, Apache-2.0) is a fallback wrapper if we want it from NativeScript JS.
Focus parallax on postersUIKit UIImageView.adjustsImageWhenAncestorFocusedPlatform primitive (Apple TV home screen uses it)—Use directly: zero code (shown in the spike screenshot).
Per-platform metrics as dataExact kernel/tables/schema.json (metrics, textStyles, controls with a column per platform)Pre-1.0, one author; the idea is sound and test-backed in their repoMITBorrow the idea: our own small table; no dependency.
DOM / web-TV rendererSolidTV (@solidtv/solid, our tv-kit today)In production on LG / Samsung / Vidaa for usApache-2.0Keep for web TVs; Apple TV leaves it.
Agent test driver with a seekable clockExact scripts/agent.mjsPre-1.0MITBorrow the idea for cross-platform screen tests later.

Explored and not chosen

ExploredVerdictWhy
SolidTV + WebGL canvas on tvOS (feat/avijit/apple-tv today)Rejected for Apple TVOne opaque view: no focus engine, VoiceOver, system text or player chrome (PLAN.md). No WebGL on Roku.
React Native tvOS, whole frameworkRejected (transplant its focus code only)A React UI = a fourth UI stack sharing nothing with our Solid screens.
Exact (Expo)Watch, not adoptNo JSX/Solid tier, tvOS APIs refused, no DRM, Android early, no Roku, pre-1.0 from one author; OTA of logic not supported.
Lynx (ByteDance)RejectedOwn framework and renderer; no tvOS target found.
Valdi (Snap)RejectedOwn framework; no tvOS target found.
whiskerRejectedRust UI, pre-alpha, no TV hosts; ideas only (island shapes).
GPUI (Zed) / gpuixRejectedDesktop-only GPU renderers; no tvOS, Roku or OTA.
Port general CSS everywhere (Taffy / Yoga as a layout core)Not neededTV UI is rails and cards; a fixed primitive set covers it. Yoga stays an option if a flex subset outgrows hand layout.
Hand-written SwiftUI screens (PLAN.md phase 4)RejectedForks the UI from the other TVs; every screen built twice.
BrightScript or a BrightScript shim for RokuNot neededRoku's TypeScript SDK runs Solid on Hermes and renders SceneGraph nodes directly.
DOMiNATIVE fake DOM for NativeScriptRejectedAn extra DOM-emulation layer between Solid and views; a direct universal renderer is smaller.

The proposal in one paragraph (details)

Keep packages/core, api and the Solid TV screens. Put a small set of TV primitives (Rail, Card, Text, Image, Button…) between screens and pixels, and give each platform its own primitive renderer: DOM for web TVs (today), UIKit for Apple TV (new), SceneGraph for Roku (Roku's own @roku-sdk/solid). tvOS owns focus; rails are native recycled lists; platform defaults come from one metrics table. Start with two 2-week spikes, gated on device numbers. A first simulator spike passed focus, recycling, Bengali and accessibility labels (results below).

1Solid screens for every TV
UI codebases
~12primitives + a focus class
New per-platform code
2 wkestimate · Home only
tvOS spike
1 wkestimate · Home rail
Roku spike
5–7 wkestimate · after the gate
Full Apple TV leaf

The shape

ArchitectureOne Solid UI, a renderer per platformOpen full reader ↗
TV leaf: one Solid UI, a renderer per platformScreens and logic stay shared; only the primitive layer forkspackages/core + api · decisions · data · VMs · Architecture componentpackages/core + apidecisions · data · VMstv-ui screens · Home · Details · Search · Architecture componenttv-ui screensHome · Details · Search~12 TV primitives · Rail · Card · Text · Image · Architecture component~12 TV primitivesRail · Card · Text · ImageMetrics table · one column per platform · Architecture componentMetrics tableone column per platformDOM renderer · web · LG · Samsung · Vidaa · Architecture componentDOM rendererweb · LG · Samsung · VidaaUIKit renderer · solid-js/universal → HVView · Architecture componentUIKit renderersolid-js/universal → HVViewSceneGraph renderer · @roku-sdk/solid + flex-grid · Architecture componentSceneGraph renderer@roku-sdk/solid + flex-gridtvOS focus engine · parallax · VoiceOver · Architecture componenttvOS focus engineparallax · VoiceOverUICollectionView rails · recycled cells · Architecture componentUICollectionView railsrecycled cellsRoku SceneGraph · focus strategies · pooling · Architecture componentRoku SceneGraphfocus strategies · poolingVM datacomposedefaultswebtvOSRokufocusable viewsrailsnodesLegendFrontendBackendDatabaseSecurity

Only the primitive layer forks. Screens, data and decisions are shared with web, LG, Samsung and Vidaa.

Where the options land

Apple TVRokuShares our Solid UI?Verdict
A · SolidTV + WebGL canvas (today's branch)Works; one opaque canvas: no focus engine, VoiceOver, system textImpossible (no WebGL)YesDead end for native feel
B · Exact (Expo)tvOS APIs refused, no DRMNoneNo (Contract language)Watch, don't adopt
C · React Native tvOSFully nativeSeparateNo (React)Fourth UI stack
D · Native leaf behind SolidUIKit views + native focus@roku-sdk/solid + flex-gridYesPropose

How a remote press flows

SequenceRemote press → native focus → Solid updateOpen full reader ↗
A remote press, native focus, Solid updatetvOS owns focus; Solid only reactsswipe rightdidUpdateFocusthe cell lifts, tilts and glaresnativelyonFocusItem(item)call handlerprop ops (hero text)apply to viewsNative, no JS on the pathSolid reactsSiri Remote · swipe / press · Sequence participantSiri Remoteswipe / presstvOS focus engine · geometry search · Sequence participanttvOS focus enginegeometry searchPoster cell · UICollectionView · Sequence participantPoster cellUICollectionViewRenderer bridge · events → JS · Sequence participantRenderer bridgeevents → JSSolid screen · signals · effects · Sequence participantSolid screensignals · effectsLegendmain requestreturnmessage

The lift and parallax happen natively before any JS runs; Solid only updates what depends on focus (the hero text).

Decisions

Each decision opens to its reason, the alternatives rejected, the code that inspired it (pinned to a commit), and gotchas.

6 items · click any row
Decision 1 · Render TV screens with native views, not a WebGL canvastvOScoreThe canvas is one opaque view to tvOS: no focus engine, VoiceOver, system text or player chrome.
What

On Apple TV every <view> and <text> becomes a real UIView/UILabel (via a Solid universal renderer) instead of a quad in SolidTV's WebGL scene.

Why this way

The branch's own analysis: "tvOS sees one opaque view, so none of UIKit's focus engine, text system, accessibility, keyboard or player chrome applies… the focus engine, VoiceOver and the system player can only come from native views" (PLAN.md). Native views also put Bengali through CoreText instead of an SDF atlas, and let the OS compositor do the scrolling.

Alternatives considered
OptionWhy not
Keep SolidTV + WebGL, polish itFixes the visible gaps (player, keyboard, parallax drawn in shaders) but can never give VoiceOver or real focus; does nothing for Roku (no WebGL).
React Native tvOS for Apple TVEverything native for free, but a React UI: a fourth UI stack sharing nothing with our Solid TV screens.
Exact (Expo)No JSX/Solid tier, tvOS APIs refused, no DRM, pre-1.0 from one author (README).
In the code
export function Rail(props: RailProps): JSX.Element {
  return (
    <view y={props.y} width={props.width} height={props.height} forwardFocus={1}>
      <text skipFocus x={10} fontSize={RAIL_TITLE_SIZE} color={RAIL_TITLE_COLOR}>
        {props.title ?? ''}
      </text>
      <Row y={props.title ? RAIL_TITLE_H : 0} scroll="auto">
        {props.children}
      </Row>
    </view>
  )
}
Talks to
tv-kit primitivesUIKitNativeScript tvOS runtime
Gotchas
  • Simulator fps is not a device number: the tvOS simulator rasterises GL on the CPU, so a canvas-vs-native fps race on the simulator is rigged (PLAN.md "What the simulator numbers mean").
  • Native views cost memory per node; rails must recycle (Decision 4).
Decision 2 · Keep Solid and the screens; fork only ~12 primitivessharedA renderer is ~10 functions; the screens never learn which one they run on.
What

Screens compose a fixed primitive set (Screen, Rail, Card, Text, Image, Button, Keypad, Focusable, Player…). Each platform implements the primitives; DOM for web TVs, UIKit for tvOS, SceneGraph for Roku.

Why this way

tv-kit already speaks a node vocabulary, not CSS: measured usage is mostly x y width height color (~1,500 uses) plus text, radius, images, a flex subset and focus handlers. A primitive layer keeps packages/core, api and the screens shared, so a new screen is written once. It is the same split Exact makes between its plan and its hosts (host/apple/src/lib.rs).

Alternatives considered
OptionWhy not
Port general CSS to every platform (a Taffy/Yoga layout core everywhere)TV UI is rails and cards; general CSS is effort without payoff, and Roku's SceneGraph has its own layout.
Write SwiftUI screens by hand (PLAN.md phase 4)UI forks from LG/Samsung/Vidaa; every screen costs twice.
In the code
} = createRenderer({
	createElement(string) {
		return document.createElement(string)
	},
	createTextNode(value) {
		return document.createTextNode(value)
	},
	replaceText(textNode, value) {
		textNode.nodeValue = value
	},
	setProperty(node, name, value, prev) {
		if (name === 'style') return Object.assign(node.style, value)
		if (value === prev) return
Talks to
packages/corepackages/apitv-kit screens
Gotchas
  • Screens that hand-wire onUp/onDown routing need small changes once tvOS owns focus (Decision 3).
  • 269 raw <view> uses in tv-kit should move onto primitives first (Phase 0).
Decision 3 · tvOS owns focus; Solid only reactstvOSfocusPort react-native-tvos's focus layer (MIT) instead of SolidTV's arrow-key routing.
What

Focusable primitives become views with canBecomeFocused = true; UIFocusGuide handles redirection, trapping and remembering the last focused child; Solid receives onFocus/onBlur/onSelect events after the native animation has started.

Why this way

Only the native engine gives geometry-based focus, touch-surface momentum, parallax, focus sounds and VoiceOver order. react-native-tvos is the most complete open-source implementation of exactly this for a JS-driven view tree, maintained (pushed this week) and MIT. Its view decides focusability, traps focus by heading, and re-points a container's focus guide at the last focused child.

Alternatives considered
OptionWhy not
Keep SolidTV's JS focus manager and fake focus visualsNo VoiceOver, no touch-surface physics, every platform behaviour hand-built.
Write focus from scratchThe edge cases (guides, traps, pending destinations, unreachable previous item) are already solved in RN-tvOS; see the comment at 572-578.
In the code
- (BOOL)shouldUpdateFocusInContext:(UIFocusUpdateContext *)context
{
  // This is  the `trapFocus*` logic that prevents the focus updates if
  // focus should be trapped and `nextFocusedItem` is not a child FocusEnv.
  if ((_trapFocusUp && context.focusHeading == UIFocusHeadingUp) ||
      (_trapFocusDown && context.focusHeading == UIFocusHeadingDown) ||
      (_trapFocusLeft && context.focusHeading == UIFocusHeadingLeft) ||
      (_trapFocusRight && context.focusHeading == UIFocusHeadingRight)) {
    // Checks if `nextFocusedItem` is a child `FocusEnvironment`.
    // If not, it returns false thus it keeps the focus inside.
    return [UIFocusSystem environment:self containsEnvironment:context.nextFocusedItem];
  }

  return [super shouldUpdateFocusInContext:context];
}
Talks to
UIFocusSystemUIFocusGuideSolid onFocus/onSelect
Gotchas
  • Focus is decided by geometry, not by arrow key: a screen that expects 'Down always goes to the next rail' must express it as layout or a focus guide.
  • Port the tvOS branches only: the file is 2,728 lines, mostly non-TV Fabric code.
Decision 4 · Rails are native recycled liststvOSRokuperfA rail is data handed to UICollectionView / flex-grid, not 20 Solid nodes.
What

<Rail items={…} renderItem> maps to a UICollectionView on tvOS (cells dequeued and reused) and to @roku-sdk/flex-grid on Roku; Solid binds item data, not one node per poster.

Why this way

Home has 6–12 rails × 20–40 items. Creating every poster as a view costs memory and layout; the OS list recycles a handful of cells and gives correct focus scrolling. Roku's SDK already ships exactly this pattern: "The engine recycles SceneGraph nodes instead of creating them for every scroll frame".

Alternatives considered
OptionWhy not
One Solid node per poster (what SolidTV does)Fine in a GPU scene graph, expensive as UIViews; and tvOS focus scrolling belongs to the collection view.
In the code
const grid = createFlexGrid<MyItem>({
    numRows: 30,
    numCols: 7,
    cellSize: [250, 350],
    focus: {
        horizontal: { strategy: fixedFocusStrategy },
        vertical: { strategy: floatingFocusYStrategy }
    },
    getCellComponent: templateId => TEMPLATES[templateId]
});
Talks to
UICollectionView@roku-sdk/flex-grid
Gotchas
  • Cell content must be a primitive that can re-bind to new data without remounting (no per-cell Solid owner leaks).
Decision 5 · One metrics table with a column per platformdesignExact's idea: measured platform defaults as data, not if-statements in components.
What

Type ramp, focus scale, rail spacing, corner radius and colours live in one table; each renderer reads its own column (web, tvOS, Roku).

Why this way

Exact keeps every look as data with measured per-platform values, and a test holds the code to the measurements (kernel/tables/schema.json). We get platform-correct defaults (SF Pro sizes on tvOS, Roku safe areas) without forking components.

Alternatives considered
OptionWhy not
Per-platform style overrides inside componentsSpreads platform knowledge through every screen; drift is invisible.
In the code
["title1", "-apple-system-title1", "title1", "title1",
  [400, 400, 400, 400],
  [22, 25, 26, 27, 28, 30, 32, 34, 38, 43, 48, 53, 58],
  [null, null, 1.1818, null]]
Talks to
tokens.tseach renderer
Decision 6 · Keep NativeScript tvOS as the runtimetvOSIt already runs the Apple TV branch and calls any UIKit API from JS; it lacks focus, which Decision 3 adds.
What

The UIKit renderer runs on NativeScript's tvOS runtime (already in feat/avijit/apple-tv), creating views through its Objective-C bridge; the focusable view class is a small native Swift/ObjC file in the app.

Why this way

No new runtime to adopt, and the branch's player, FairPlay, keyboard and Siri code keep working. The published @nativescript/[email protected] has no focus APIs (searched: no canBecomeFocused, didUpdateFocus or UIFocusGuide), so focus lives in our native class, not in NativeScript widgets.

Alternatives considered
OptionWhy not
A KMP/Swift host with JavaScriptCore (like the spike)Viable and lighter; keep as the fallback if NativeScript's bridge cost shows up in the readings (Experiment E3).
In the code
    func apply(_ json: String) {
        let t = CACurrentMediaTime()
        guard let ops = (try? JSONSerialization.jsonObject(with: Data(json.utf8))) as? [[Any]] else { return }
        for op in ops {
            switch op[0] as! String {
            case "c":
                let id = op[1] as! Int, kind = op[2] as! String
                let v: UIView
                switch kind {
                case "text": let l = UILabel(); l.numberOfLines = 1; v = l
                case "scroll": let s = UIScrollView(); s.clipsToBounds = false; v = s
                case "rail": let r = RailView(); bindRail(r, id: id); v = r
                default: v = UIView()
                }
                views[id] = v; kinds[id] = kind
            case "p": setProp(op[1] as! Int, op[2] as! String, op[3])
            case "i":
                guard let parent = views[op[1] as! Int], let child = views[op[2] as! Int] else { continue }
                parent.addSubview(child)
                if let s = parent as? UIScrollView { s.contentSize = CGSize(width: s.bounds.width, height: max(s.contentSize.height, child.frame.maxY)) }
            default: break
            }
            applied += 1
        }
        let ms = (CACurrentMediaTime() - t) * 1000
        batches += 1; totalMs += ms; maxBatchMs = max(maxBatchMs, ms)
Gotchas
  • NativeScript's tvOS line is a tagged prerelease (9.2.0-tvos.0), not latest: pin it and watch its releases.

Experiments that decide it

Every experiment has a pass line. If E1 or E2 fails on a device, the tvOS leaf stops and the canvas build gets polished instead.

#QuestionMeasurePass when
E1 Focus parity on HometvOS focus engine drives every Home move (rails left/right, rail-to-rail, nav bar) with no JS routingScripted focus walk over 6 rails × 20 posters; count misses (focus did not land where asked) and per-move JS cost0 misses; focus→Solid handler round-trip under 4 ms p95 on device
E2 Frames on a real Apple TVNative rails scroll at the display rate on an Apple TV 4KCADisplayLink late-frame count during a held-right scroll across all rails, on device (not simulator)< 1% frames late; no frame over 33 ms
E3 Bridge costBatch ops from JS to UIKit stay cheapTime to apply the Home mount batch and each focus-driven update batchMount < 50 ms on device; update batch < 2 ms
E4 Memory with recyclingRecycled cells keep memory flat as rails scrollResident memory and cells created before/after walking every posterCells created ≈ visible + 2 per rail; memory grows < 20 MB over the walk
E5 Bengali and system typeCoreText renders Bengali titles correctly at SF Pro TV sizesScreenshot review of mixed Bengali/English titles; compare with the canvas buildNo missing glyphs or broken conjuncts
E6 VoiceOverFocused posters are announced with their titleVoiceOver on the simulator: focus walk reads titlesEvery poster announced; rail titles announced as headers
E7 Roku Home@roku-sdk/solid + flex-grid renders our Home rail on a real RokuHome rail on a Roku device; focus timing and memory from rk perfetto60 fps rail scroll on a mid-range Roku; no node churn while scrolling

PoC plan

WorkflowFrom spike to shipped TV leafOpen full reader ↗
From spike to shipped TV leafEach gate is a go / no-go on measured numbers01 / Now: no renderer change02 / Spikes (2–3 weeks)03 / Build (if gates pass)Native player · AVPlayerViewController · Now: no renderer changeNative playerAVPlayerViewControllerExtract primitives · tv-kit, DOM only · Now: no renderer changeExtract primitivestv-kit, DOM onlytvOS Home spike · focus · rails · Bengali · Spikes (2–3 weeks)tvOS Home spikefocus · rails · BengaliRoku Home spike · @roku-sdk/solid · Spikes (2–3 weeks)Roku Home spike@roku-sdk/solidGo / no-go? · device numbers · Spikes (2–3 weeks)Go / no-go?device numbersRoku leaf · all screens · Spikes (2–3 weeks)Roku leafall screensUIKit leaf · all screens · Build (if gates pass)UIKit leafall screensRetire canvas · Apple TV ships native · Build (if gates pass)Retire canvasApple TV ships nativepasspassthenin parallelprimitives readyreadingsparityreadingsLegendBuildMeasureGateShip

The native player ships first because it needs no renderer change and is the biggest single native-feel gain.

Phase 0 · Native player + primitives ~3 wk

Present AVPlayerViewController from the current Apple TV app (PLAN.md phase 1). Move tv-kit screens off raw <view> (269 uses) onto the primitive set, DOM renderer only, no visual change.

Ships value now; makes every later renderer a primitive implementation.
↓

Phase 1 · tvOS Home spike ~2 wk

UIKit renderer for Rail, Card, Text, Image on NativeScript tvOS; focus class ported from RN-tvOS; run E1–E6 on an Apple TV 4K.

Go/no-go on native tvOS.
↓

Phase 1b · Roku Home spike ~1 wk

Primitives on @roku-sdk/solid + flex-grid; run E7 on a device.

Go/no-go on Roku via Solid.
↓

Phase 2 · Build the leaves 5–7 wk tvOS

Remaining primitives (Keypad, Button, Player chrome), all screens, VoiceOver labels, parity screenshots per primitive in CI.

Apple TV ships native; canvas retires.

Spike results (simulator)

The native leaf works end to end

A tvOS app ran a JS renderer in JavaScriptCore that sent batched ops to a Swift applier; rails were recycled UICollectionViews and the tvOS focus engine owned focus. A scripted walk visited all 120 posters across 6 rails. Apple TV 4K (3rd gen) simulator, tvOS 27.2, Xcode 27.2, Apple M5 Pro, 2026-11-10. Two runs; the second is quoted, the first agreed within noise.

0of 120 moves
Focus misses over the walk
0.58 msp95 (p50 0.46)
Focus → Solid handler → views
< 0.1 msp95, 1 op
Update batch apply
9–27 ms82 ops, 2 runs
Home mount (JS + apply)
54recycled
Cells created for 120 posters
0of 211
Late frames during the walk
tvOS simulator showing native rails with Bengali and English titles; the last poster lifted with Apple's focus glare
After the walk: Bengali titles shaped by CoreText (conjuncts intact), the focused poster lifted with Apple's own glare and shadow (adjustsImageWhenAncestorFocused, no code of ours). The hero text overlapping the rails is a spike layout bug (no header band), not an architecture issue.
ExperimentSimulator resultStatus
E1 Focus parity0 misses / 120 moves; focus→Solid p95 0.58 msPass (simulator)
E2 Device frames0 late / 211 frames on the simulator; not meaningful for a deviceOpen: needs an Apple TV 4K
E3 Bridge costMount 9–27 ms; update batch p95 < 0.1 msPass (simulator); re-measure under NativeScript
E4 Recycling + memory54 cells for 120 posters; resident 167→171–181 MB across the walkPass
E5 BengaliShaped correctly by CoreText (screenshot)Pass
E6 VoiceOver36/36 visible cells expose a label (21 Bengali); spoken output not yet checkedPartial: labels pass, listen on device
E7 RokuNot startedOpen: needs a Roku
How it was measured, and what to distrust method

The app logs to Documents/spike.log. A scripted walk asks the focus engine to move focus to each poster in turn (setNeedsFocusUpdate on a preferred environment), because simctl cannot inject remote presses. A CADisplayLink counts frames later than 1.5× their budget. Memory is mach_task_basic_info.resident_size.

Load average was 61 when the first attempt started (Android Studio indexing at ~1150% CPU); the quoted run started at load ~8. Timings are simulator CPU numbers, useful for relative cost, not device frame rates.

Device frame rate (E2), the cost of NativeScript's bridge instead of a direct JavaScriptCore call (E3), spoken VoiceOver order (E6), and Roku (E7).

A window-only app delegate traps at launch (UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption): adopt UIWindowSceneDelegate. UIScreen.focusedView asserts under scenes: use UIFocusSystem.focusSystem(for:).focusedItem.

Spike source: App.swift (op applier, focus, recycled rails, instrumentation), app.js (the JS renderer and Home screen), project.yml.

Who should own what

WorkSkillsProposed owner (to confirm)
Native player on Apple TVAVKit, FairPlayApple TV branch owner
Primitive extraction in tv-kitSolid, tv-kitTV web team
UIKit renderer + focus classUIKit focus, NativeScript bridgeAn iOS engineer
Roku spikeRoku SceneGraph, TypeScriptTV web team
Metrics table + parity screenshotsDesign tokens, CIPlatform team