Hoichoi client platform · architecture decision

One UI layer, many renderers: building on battle-tested parts

How to make the Solid UI portable to the web DOM, native views (Valdi or anything later), Apple TV and Roku without inventing a UI language and without betting on any one engine. Every layer is borrowed from something already in production at scale; what we write is only the glue and the measured web-only performance work we already have.

Analysis by Claude (agent) from Hoichoi.SharedClientPlatform perf/solid-native-spike 7d313e426, React Strict DOM, StyleX, Yoga, Lynx and the Solid TV stackPublic · every page in this group shares one access rule

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:

CodeWhat it fixesEvidence in the repo
Hero carousel pauses during the Detail openthe carousel scrolled and read layout every frame on the thread the open needsIosHeroPager.tsx:244: "S21: 26 ms"; :75: a 50–80 ms first-time task on the S21 (HOI-4027)
Tab deck layer promotionfling jankcommit: realme 8 Pro fling 66–86% → 28–46% janky frames
Press feedbackdouble activation, restyle stormWebKit sent two clicks 42 ms apart on 2 of 16 presses; a poster load restyled every card
Tab bar iconsblank icons on switchWebKit 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 + mappingOwn component layer
Screens are written indiv / span / img and CSSour components and props
Cost on web (our main platform)zero: real DOM and CSSa wrapper per component; some CSS tooling lost
Migrating today's codesmall: 93% of tags and 88% of CSS already fitrewrite every screen's markup
Enforcing what native can drawlint and compiler errorsby construction
Swapping rendererseach adapter implements the subseteach adapter implements N components
PrecedentReact Strict DOM (Meta: Facebook, Instagram, VR)React Native core, Tamagui, our tv-kit
OptionVerdictWhy
Own UI component language for everythingrejecta full markup rewrite, and a language only we know, to solve what a subset solves
Full HTML/CSS, translated at runtimerejectthat 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**adoptMeta'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)
LayerBorrowProduction evidenceWhat 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 VRa Solid port of the subset rules (RSD is React-only); its 233-property CSS table is the starting point
StylesStyleX compiler model (MIT, 10.5k★): typed css.create() objects, atomic CSS on web, static resolutionMeta production web (Facebook, Instagram, WhatsApp web)a native emitter: StyleX objects → style tables (our compiler step)
LayoutYoga (MIT, 19k★)React Native, Litho, Valdi, ComponentKitnothing: the engine already embeds it
CSS parsing for build-time checksLightning CSS (MPL-2.0, 7.7k★)Vite, Parcel, Next.js toolchainsthe 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 adaptersChakra UI, Ark UIthe view half per renderer; the logic is shared
Virtualised rails on webTanStack Virtual (MIT, 7.2k★), headless, Solid adapterTanStack ecosystem, wide usenothing 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 boxesnothing: keep it
tvOS focusUIKit's focus engine via our bridge (proven: 19/19 walk)every tvOS appthe 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 engineValdi today (Snap production only, pre-1.0) — swappableSnap apps, 8 years per its READMEthe adapter and our fork patches; replaceable

The six components (and why only six)

ComponentWhy HTML can't express it portablyWebNativeRoku
Railfocus order, virtualisation, snap, carousel pause during transitionsTanStack Virtual + today's measured tricks; SolidTV Row on TVRecyclerView / UICollectionViewflex-grid
Playera platform media surfacekwry player islandkwry player islandVideo node
FocusableD-pad focus and focus memorySolidTV focusUIFocus bridge / Android focusSceneGraph focus
Sheetmodal presentation, gestures, dismissalZag dialog machine + CSSZag machine + native viewZag machine + group
IconSVG isn't drawn by native viewsinline SVGvector drawable / SF-style imageposter
Imagedecode at cell size, caching, priority<img> + our decode policynative image loaderposter

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 / sticky
  • calc(), clamp(), min() / max()
  • CSS @keyframes animations (transitions are polyfilled)
  • backdropFilter, clipPath, masks
  • scroll snap, overflowX/Y split, 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.