The decision in one paragraph
Screens stay HTML and CSS, restricted to a subset, exactly the model Meta ships as React Strict DOM for Facebook and Instagram on web, native and VR. Styles are authored in StyleX-style typed objects (Meta, 10.5k★) that compile to atomic CSS on web and to style tables on native. Layout everywhere is Yoga (Meta, 19k★, React Native's and Valdi's engine). About six components exist where HTML has no portable meaning (Rail, Player, Focusable, Sheet, Icon, Image), and each is built on a proven library per platform: @solidtv / Lightning focus on web TVs (we already ship it), UICollectionView / RecyclerView natively, @roku-sdk/solid on Roku. The renderer is a swappable adapter: DOM today, Valdi for native now, anything later.
First, an honest check: is the browser-specific code worth keeping?
The scan found 1,413 direct browser-API uses in 157 of 278 UI files. Most of the heaviest are measured device work, not speculation:
| Code | What it fixes | Evidence in the repo |
|---|---|---|
| Hero carousel pauses during the Detail open | the carousel scrolled and read layout every frame on the thread the open needs | IosHeroPager.tsx:244: "S21: 26 ms"; :75: a 50–80 ms first-time task on the S21 (HOI-4027) |
| Tab deck layer promotion | fling jank | commit: realme 8 Pro fling 66–86% → 28–46% janky frames |
| Press feedback | double activation, restyle storm | WebKit sent two clicks 42 ms apart on 2 of 16 presses; a poster load restyled every card |
| Tab bar icons | blank icons on switch | WebKit blanked a swapped img until it re-decoded |
What that means for the port
These are WebView workarounds: a native renderer doesn't have the problem, so they stay as web-only internals of the matching component (the carousel pause becomes Rail's job on web), not code to rewrite. What crosses platforms is a small set of intents ("Detail is opening", "measure this card"), which become ports. The scan counts calls, it doesn't judge them: some may be stale (October's diagnosis found blur was a minor cost, yet blur workarounds remain), so each is re-measured before it is moved or deleted.
HTML/CSS subset, or our own component language?
| HTML/CSS subset + mapping | Own component layer | |
|---|---|---|
| Screens are written in | div / span / img and CSS | our components and props |
| Cost on web (our main platform) | zero: real DOM and CSS | a wrapper per component; some CSS tooling lost |
| Migrating today's code | small: 93% of tags and 88% of CSS already fit | rewrite every screen's markup |
| Enforcing what native can draw | lint and compiler errors | by construction |
| Swapping renderers | each adapter implements the subset | each adapter implements N components |
| Precedent | React Strict DOM (Meta: Facebook, Instagram, VR) | React Native core, Tamagui, our tv-kit |
| Option | Verdict | Why |
|---|---|---|
| Own UI component language for everything | reject | a full markup rewrite, and a language only we know, to solve what a subset solves |
| Full HTML/CSS, translated at runtime | reject | that is a browser engine (Blitz, Servo): no native views, no native feel |
| **HTML/CSS subset for layout and text + ~6 components where HTML has no portable meaning** | adopt | Meta's production model; zero web cost; 93% of markup already fits; renderers stay plug-and-play behind one adapter boundary |
The battle-tested parts, layer by layer
Solid screens + view models HTML subset (div, span, img, button, a, ul/li, svg icon)
│ + StyleX-style typed styles + ~6 components
│
┌─────┴──────────── adapter boundary (one interface, swappable) ─────────────────────┐
│ DOM (web, Android TV, LG, │ Valdi (Android, iOS, tvOS) │ Roku │
│ Samsung): real DOM + atomic │ ops → native views, style │ @roku-sdk/solid → │
│ CSS; today's measured perf │ tables, Yoga, Hermes bytecode │ SceneGraph │
│ tricks live here │ (fork patches in PR #640) │ │
└─────────────────────────────┴────────────────────────────────┴──────────────────────┘
core / api / store / i18n (already platform-free, 34k lines) · kwry services (player, DRM, network, OTA)| Layer | Borrow | Production evidence | What we write |
|---|---|---|---|
| Subset definition (which tags, which CSS) | React Strict DOM's published subset and compatibility tables (MIT, 3.6k★) | Meta: "the way Meta develops interfaces for Facebook, Instagram, Threads"; Facebook and Instagram on VR | a Solid port of the subset rules (RSD is React-only); its 233-property CSS table is the starting point |
| Styles | StyleX compiler model (MIT, 10.5k★): typed css.create() objects, atomic CSS on web, static resolution | Meta production web (Facebook, Instagram, WhatsApp web) | a native emitter: StyleX objects → style tables (our compiler step) |
| Layout | Yoga (MIT, 19k★) | React Native, Litho, Valdi, ComponentKit | nothing: the engine already embeds it |
| CSS parsing for build-time checks | Lightning CSS (MPL-2.0, 7.7k★) | Vite, Parcel, Next.js toolchains | the subset lint over existing .css while it migrates |
| Behaviour of interactive pieces (sheet, menu, focus traps) | Zag state machines (MIT, 5.3k★): framework- and DOM-agnostic machines with Solid adapters | Chakra UI, Ark UI | the view half per renderer; the logic is shared |
| Virtualised rails on web | TanStack Virtual (MIT, 7.2k★), headless, Solid adapter | TanStack ecosystem, wide use | nothing new; native uses RecyclerView / UICollectionView |
| TV focus on web TVs | @solidtv/solid + Lightning renderer (already in tv-kit) | our shipping TV apps; Lightning in RDK set-top boxes | nothing: keep it |
| tvOS focus | UIKit's focus engine via our bridge (proven: 19/19 walk) | every tvOS app | the bridge, already written |
| Roku | @roku-sdk/solid (Roku's own Solid renderer) | Roku's official SDK (beta; GA targeted Fall 2027) | the six components on SceneGraph nodes |
| Native engine | Valdi today (Snap production only, pre-1.0) — swappable | Snap apps, 8 years per its README | the adapter and our fork patches; replaceable |
The six components (and why only six)
| Component | Why HTML can't express it portably | Web | Native | Roku |
|---|---|---|---|---|
| Rail | focus order, virtualisation, snap, carousel pause during transitions | TanStack Virtual + today's measured tricks; SolidTV Row on TV | RecyclerView / UICollectionView | flex-grid |
| Player | a platform media surface | kwry player island | kwry player island | Video node |
| Focusable | D-pad focus and focus memory | SolidTV focus | UIFocus bridge / Android focus | SceneGraph focus |
| Sheet | modal presentation, gestures, dismissal | Zag dialog machine + CSS | Zag machine + native view | Zag machine + group |
| Icon | SVG isn't drawn by native views | inline SVG | vector drawable / SF-style image | poster |
| Image | decode at cell size, caching, priority | <img> + our decode policy | native image loader | poster |
Everything else (layout, text, colour, borders, transforms, simple transitions) is the HTML/CSS subset. A new renderer is: implement the subset mapping and these six. That is the plug-and-play surface.
Where React Strict DOM's tables tell us to be careful
RSD documents what its native side supports today (233 CSS properties: 102 native ✅, 67 polyfilled 🟡, 62 unsupported ❌). The unsupported list matches our own audit, which is a useful cross-check rather than a surprise:
Unsupported in RSD native (and in our subset)
display: grid, inline flow (inline,inline-block),position: fixed / stickycalc(),clamp(),min()/max()- CSS
@keyframesanimations (transitions are polyfilled) backdropFilter,clipPath, masks- scroll snap,
overflowX/Ysplit,objectPosition
How we cover them
- grid → a Grid layout in the Rail/Grid component; fixed → an overlay root; sticky → a component
calc()/var()→ resolved at build time per theme and breakpoint (our style compiler)- keyframes → native animation blocks (Valdi's begin/end animation ops, proven in the spike)
- blur / clip → design decision: pre-blurred images or dropped (1.8% of our CSS)
- scroll snap → Rail
Order of work
1 · Pin the subset
Adopt RSD's tag and CSS tables as the starting subset, amended with our audit (scan/conformance.mjs). Lint it in CI over packages/mweb and tv-kit.
- Pass
- the scan runs in CI and reports per-file conformance
2 · Styles as typed objects
StyleX-style objects for the hot path, compiled to atomic CSS on web (pixel-identical) and to style tables for native.
- Pass
- web pixel-identical on Home and Detail; native tables generated from the same source
3 · The six components
Rail, Player, Focusable, Sheet, Icon, Image on the DOM adapter first, absorbing today's measured web tricks; then on the Valdi adapter (from PR #640).
- Pass
- web behaviour and frame numbers unchanged; components render on native
4 · Browser access behind ports
The 861 browser-API uses in mweb screens and lib move into components or ports; each re-measured, dead workarounds deleted.
- Pass
- hot-path screens have zero direct browser access
5 · Real Home → Detail on native
The real screens through the Valdi adapter, measured on the S21 FE against the WebView and Viewlift (the spike's rig).
- Go
- frame gate met; under ~20% of those screens' lines changed
- Stop
- steps 1–4 still pay off: cleaner, testable, Roku- and tvOS-ready
Sources and checks method
GitHub API on 2026-11-16 for stars and activity: react-strict-dom 3.6k, stylex 10.5k, lightningcss 7.7k, yoga 19k, zag 5.3k, TanStack Virtual 7.2k, solid 36k, solid-primitives 1.6k, @solidtv/solid (in tv-kit), Lynx 15.3k.
Read from its docs in the repo: the Meta production statement (learn/index.md), the HTML compatibility table (api/03-html) and the 233-row CSS compatibility table (api/02-css). It is React-only, so we adopt its subset and approach, not its code.
Measurement claims for the DOM-heavy files are quoted from commit messages and comments in packages/mweb; the conformance numbers are from scan/conformance.mjs over packages/mweb, ui and tv-kit.