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'| Primitive | DOM (web, LG, Samsung, Vidaa) | UIKit (Apple TV) | Roku SceneGraph |
|---|---|---|---|
| Renderer | SolidTV (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> + image | collection cell, Apple's focus lift | <poster loadWidth…> |
| Rail | <Row scroll> | UICollectionView (recycled) | @roku-sdk/flex-grid (pooled) |
| Focusable | SolidTV focus manager | tvOS focus engine | FocusBoundary (TS-routed) |
| Player | Shaka | AVPlayerViewController + FairPlay | <video> + drmParams (Widevine / PlayReady) |
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-writtenonUp/onDownleaves 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,SuspenseListare unavailable (EXPORTS.md). - Roku DRM: its
videonode fetches the licence itself fromlicenseServerURL(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.
| Take | From (pinned) | How battle-tested | Licence | How 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+ | MIT | Use as is (dependency). Our Roku primitives render through it. |
| Roku rails | @roku-sdk/flex-grid 3.x | Official; node pooling + 4 focus strategies | MIT | Use as is for Rail on Roku. |
| Roku focus | FocusBoundary in @roku-sdk/navigation | Official | MIT | Use as is for Focusable on Roku. |
| tvOS focus layer | react-native-tvos RCTViewComponentView.mm @ d930b93: focus guide 307–349, trap 693–707, didUpdateFocus + parallax 709–751 and 430–470 | The 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 source | MIT (keep the notice) | Transplant: port the tvOS branches into our HVView (Swift). Not a dependency: it is bound to React Fabric. |
| tvOS runtime | NativeScript tvOS @nativescript/[email protected] (already in feat/avijit/apple-tv) | NativeScript 25.7k★, active; the tvOS line is a prerelease tag | MIT | Use: JS engine + Objective-C bridge. It has no tvOS focus APIs, so focus comes from the transplant above. |
| Solid → native renderer pattern | nativescript-community/solid-js renderer.js | Small (73★), last commit 2025-09; the pattern is Solid's own createRenderer | MIT | Copy the pattern (~60 lines): createElement / setProperty / insertNode / removeNode → our UIKit node. Skip its DOMiNATIVE fake-DOM layer. |
| Recycled rails on tvOS | UIKit 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 posters | UIKit UIImageView.adjustsImageWhenAncestorFocused | Platform primitive (Apple TV home screen uses it) | — | Use directly: zero code (shown in the spike screenshot). |
| Per-platform metrics as data | Exact 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 repo | MIT | Borrow the idea: our own small table; no dependency. |
| DOM / web-TV renderer | SolidTV (@solidtv/solid, our tv-kit today) | In production on LG / Samsung / Vidaa for us | Apache-2.0 | Keep for web TVs; Apple TV leaves it. |
| Agent test driver with a seekable clock | Exact scripts/agent.mjs | Pre-1.0 | MIT | Borrow the idea for cross-platform screen tests later. |
Explored and not chosen
| Explored | Verdict | Why |
|---|---|---|
SolidTV + WebGL canvas on tvOS (feat/avijit/apple-tv today) | Rejected for Apple TV | One opaque view: no focus engine, VoiceOver, system text or player chrome (PLAN.md). No WebGL on Roku. |
| React Native tvOS, whole framework | Rejected (transplant its focus code only) | A React UI = a fourth UI stack sharing nothing with our Solid screens. |
| Exact (Expo) | Watch, not adopt | No 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) | Rejected | Own framework and renderer; no tvOS target found. |
| Valdi (Snap) | Rejected | Own framework; no tvOS target found. |
| whisker | Rejected | Rust UI, pre-alpha, no TV hosts; ideas only (island shapes). |
| GPUI (Zed) / gpuix | Rejected | Desktop-only GPU renderers; no tvOS, Roku or OTA. |
| Port general CSS everywhere (Taffy / Yoga as a layout core) | Not needed | TV 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) | Rejected | Forks the UI from the other TVs; every screen built twice. |
| BrightScript or a BrightScript shim for Roku | Not needed | Roku's TypeScript SDK runs Solid on Hermes and renders SceneGraph nodes directly. |
| DOMiNATIVE fake DOM for NativeScript | Rejected | An 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).
The shape
Only the primitive layer forks. Screens, data and decisions are shared with web, LG, Samsung and Vidaa.
Where the options land
| Apple TV | Roku | Shares our Solid UI? | Verdict | |
|---|---|---|---|---|
| A · SolidTV + WebGL canvas (today's branch) | Works; one opaque canvas: no focus engine, VoiceOver, system text | Impossible (no WebGL) | Yes | Dead end for native feel |
| B · Exact (Expo) | tvOS APIs refused, no DRM | None | No (Contract language) | Watch, don't adopt |
| C · React Native tvOS | Fully native | Separate | No (React) | Fourth UI stack |
| D · Native leaf behind Solid | UIKit views + native focus | @roku-sdk/solid + flex-grid | Yes | Propose |
How a remote press flows
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.
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.
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.
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.
| Option | Why not |
|---|---|
| Keep SolidTV + WebGL, polish it | Fixes 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 TV | Everything 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). |
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>
)
}- 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.
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.
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).
| Option | Why 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. |
} = 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- Screens that hand-wire
onUp/onDownrouting 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.
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.
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.
| Option | Why not |
|---|---|
| Keep SolidTV's JS focus manager and fake focus visuals | No VoiceOver, no touch-surface physics, every platform behaviour hand-built. |
| Write focus from scratch | The edge cases (guides, traps, pending destinations, unreachable previous item) are already solved in RN-tvOS; see the comment at 572-578. |
- (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];
}- 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.
<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.
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".
| Option | Why 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. |
const grid = createFlexGrid<MyItem>({
numRows: 30,
numCols: 7,
cellSize: [250, 350],
focus: {
horizontal: { strategy: fixedFocusStrategy },
vertical: { strategy: floatingFocusYStrategy }
},
getCellComponent: templateId => TEMPLATES[templateId]
});- 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.
Type ramp, focus scale, rail spacing, corner radius and colours live in one table; each renderer reads its own column (web, tvOS, Roku).
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.
| Option | Why not |
|---|---|
| Per-platform style overrides inside components | Spreads platform knowledge through every screen; drift is invisible. |
["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]]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.
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.
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.
| Option | Why 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). |
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)- NativeScript's tvOS line is a tagged prerelease (
9.2.0-tvos.0), notlatest: 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.
| # | Question | Measure | Pass when |
|---|---|---|---|
| E1 Focus parity on Home | tvOS focus engine drives every Home move (rails left/right, rail-to-rail, nav bar) with no JS routing | Scripted focus walk over 6 rails × 20 posters; count misses (focus did not land where asked) and per-move JS cost | 0 misses; focus→Solid handler round-trip under 4 ms p95 on device |
| E2 Frames on a real Apple TV | Native rails scroll at the display rate on an Apple TV 4K | CADisplayLink 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 cost | Batch ops from JS to UIKit stay cheap | Time to apply the Home mount batch and each focus-driven update batch | Mount < 50 ms on device; update batch < 2 ms |
| E4 Memory with recycling | Recycled cells keep memory flat as rails scroll | Resident memory and cells created before/after walking every poster | Cells created ≈ visible + 2 per rail; memory grows < 20 MB over the walk |
| E5 Bengali and system type | CoreText renders Bengali titles correctly at SF Pro TV sizes | Screenshot review of mixed Bengali/English titles; compare with the canvas build | No missing glyphs or broken conjuncts |
| E6 VoiceOver | Focused posters are announced with their title | VoiceOver on the simulator: focus walk reads titles | Every poster announced; rail titles announced as headers |
| E7 Roku Home | @roku-sdk/solid + flex-grid renders our Home rail on a real Roku | Home rail on a Roku device; focus timing and memory from rk perfetto | 60 fps rail scroll on a mid-range Roku; no node churn while scrolling |
PoC plan
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.
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.
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.

| Experiment | Simulator result | Status |
|---|---|---|
| E1 Focus parity | 0 misses / 120 moves; focus→Solid p95 0.58 ms | Pass (simulator) |
| E2 Device frames | 0 late / 211 frames on the simulator; not meaningful for a device | Open: needs an Apple TV 4K |
| E3 Bridge cost | Mount 9–27 ms; update batch p95 < 0.1 ms | Pass (simulator); re-measure under NativeScript |
| E4 Recycling + memory | 54 cells for 120 posters; resident 167→171–181 MB across the walk | Pass |
| E5 Bengali | Shaped correctly by CoreText (screenshot) | Pass |
| E6 VoiceOver | 36/36 visible cells expose a label (21 Bengali); spoken output not yet checked | Partial: labels pass, listen on device |
| E7 Roku | Not started | Open: 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
| Work | Skills | Proposed owner (to confirm) |
|---|---|---|
| Native player on Apple TV | AVKit, FairPlay | Apple TV branch owner |
| Primitive extraction in tv-kit | Solid, tv-kit | TV web team |
| UIKit renderer + focus class | UIKit focus, NativeScript bridge | An iOS engineer |
| Roku spike | Roku SceneGraph, TypeScript | TV web team |
| Metrics table + parity screenshots | Design tokens, CI | Platform team |