The plan in one paragraph
TV forces us to build native renderers anyway: tvOS has no WebView and Roku has no web at all. So build them once, for every native target. Screens are written in Solid against a strict HTML/CSS subset. At build time a compiler turns the CSS into a style table and the keyframes into native animation ops. On device a borrowed native runtime lays out with Yoga and draws real UIView / android.view.View objects. The lead candidate is Snap's Valdi runtime, driven by our Solid renderer instead of Valdi's own components. The JS runs on its own thread as precompiled bytecode, and ships over the air in kwry's signed bundles. Web keeps the real CSS. The proof is Home → Detail on Android and iOS against two arms: today's kwry WebView and the native Viewlift app.
Results so far (spike branch)
Solid drives real native views through Valdi's runtime, on Android and iOS
Draft PR #640, branch perf/solid-native-spike off main (f1ad29532), package packages/solid-native. A solid-js/universal renderer writes Solid's operations straight into Valdi's render-request op buffer, one batch per microtask. The only Valdi component is a root that renders one host view and hands over its delegate; screens stay Solid. On an Android phone and emulator and the iOS simulator, the same bundle renders Home (hero + 6 rails × 20 posters) as real TextView / ImageView / ScrollView (and UIKit on iOS), with Bengali shaped by the OS, and Home → Detail opens with the card → hero flight as one native animation block. Our whole Solid app compiles to an 8.7 KB .valdimodule.
On a real phone at 120 Hz
| Home → Detail, Samsung S21 FE (Android 16, 120 Hz), interleaved, 8 runs each | Frames per 500 ms flight | Frame p50 | Frame p95 | Frame max | Gap p95 |
|---|---|---|---|---|---|
| Solid → Valdi, release, simple Detail | 53 | 6.0 ms | 10.6 ms | 11.2 ms | 8.4 ms |
| Solid → Valdi, release, production-sized Detail (127 elements, 21 images, ~13 animated layers) | 53 | 12.7 ms | 13.9 ms | 33.7 ms | 8.4 ms |
| Solid → Valdi (debug), JS thread blocked 150 ms after the tap | 52–53 | — | 10.8 ms | 17.1 ms | — |
| Viewlift native 4.0.17 (Play install) | 36 | 40.3 ms | 66.2 ms | 79.1 ms | 25.0 ms |
| kwry WebView (prod build) | 34 | 34.3 ms | 103.2 ms | 150.9 ms | 41.7 ms |
At 120 Hz the frame budget is 8.3 ms. Release Solid builds (lean Hermes bytecode, 10.4 MB APK) keep the full 120 Hz cadence through the flight: 53 frames in 500 ms and frames presented every 8.4 ms at p95. With the production-sized Detail (the real page's sections and the open morph's ~13 layers, minus blur) frames finish at p95 13.9 ms, inside two budgets, with one 33.7 ms frame in 8 runs. On the same tap and phone, Viewlift's own native app draws 36 frames (p95 66 ms) and the kwry WebView 34 (p95 103 ms). The flight also holds with the JS thread blocked for 150 ms, because JS runs off the UI thread and the flight is one native animation. Device load was ~15 throughout, recorded per run. Data and PR: results/s21fe-release, #640.
On an emulator, three apps
| Home → Detail, same emulator, same rig, 10 runs each | Frames per 500 ms flight | Frame p95 | Gap p95 | Long gaps / run | Tap → first frame |
|---|---|---|---|---|---|
| Viewlift native app 4.0.12 | 20 | 152 ms | 67 ms | 6.2 | 357 ms |
| kwry WebView (prod build) | 17.5 | 167 ms | 83 ms | 6.2 | 110 ms |
| Solid → Valdi (spike) | 26.5 | 50 ms | 33 ms | 1.9 | 77 ms |
Read these numbers as relative, not as gates
The emulator (Pixel 7, API 35, 60 Hz, -gpu host, on the idle mac-mini) throttles the GPU so heavily that even the native app drops most frames; the spike's Detail is simpler than either production app's; and the spike is a Valdi debug build against two release apps. They show the shape (fewer, shorter frames; one batch per interaction), not the device result. Headline G4–G6 numbers wait for the Fold and the Samsung A-series. Raw data: results/.
S2 kill lines
| Kill line | Result | Evidence |
|---|---|---|
| Seam needs Valdi's component model | pass | one host component; every screen is Solid writing ops through Valdi's own delegate |
| Bazel can't be wrapped | pass, with a known flag | builds on macOS with --noexperimental_collect_system_network_usage (Bazel's network-stats collector crashes on a Mac with many network interfaces); first build ~13k actions, incremental ~24 |
| iOS layer can't be made to build for tvOS | pass, running | the same Solid bundle runs natively on the Apple TV simulator (tvOS 27.2), release, Hermes bytecode, 6.5 MB app. A 19-move focus walk lands 19/19 with no misses (focus update p50 1.44 ms, p95 2.48 ms) and the rail scrolls natively (results/tvos). It took UIKit guards, tvOS build conditions, a Hermes patch (no fork/exec) and a focus bridge |
| Hermes can't run in an iOS release build | pass, fork patch | a -c opt production iOS build links lean Hermes (no JS compiler) and renders Home from precompiled Hermes bytecode; the app is 18 MB. Stock Valdi links Hermes only in debug, calls the debugger unguarded in lean builds, and precompiles JS for Android only: valdi-patches/ fixes all three (about 70 lines) |


Two terms, defined so the gates can be checked
"No interpretation, AOT compiled" means
- No CSS on device. No CSS parser, cascade or selector matching in the native runtime. Classes become attribute IDs and the cascade is resolved at build time into a style table, one variant per theme and breakpoint.
- JS ships as precompiled bytecode (Hermes or QuickJS), so there is no parse or compile at launch. Apple documents JIT on iOS only for browser engines and lists none for tvOS (JIT docs); we infer no JIT for an app like ours, so bytecode is the startup win there.
- Templates and keyframes are compiled. JSX becomes op-emitting code. Keyframes become native animation ops, not per-frame JS.
- It does not mean machine code. Native code can't ship over the air: Play forbids downloaded dex and
.sofiles, and Apple tolerates only interpreted code. True AOT and full OTA can't both hold, so this is the definition we gate on.
"Fully OTA updatable" means
- A screen, its styles, its animations and its assets all ship in one signed bundle: bytecode, style table and images.
- Bytecode is tied to the engine build. Hermes refuses any other bytecode version (
BCProvider.cpp:89-95). QuickJS checks nothing and must never load an unchecked file (quickjs docs). - So the kwry hello advertises
engine,bcVersion,abiand aruntimeVersionfingerprint of the native view surface. The server picks a matching artifact, or serves JS source as the fallback. The host checks the signature, then the header. - Policy: interpreted code may be downloaded (Apple DPLA 3.3.1(B)); Play exempts code run by an interpreter (policy). Neither text mentions bytecode, so treating it like source is our inference; Expo ships Hermes bytecode in its OTA updates (Expo docs). An OTA bundle never adds native capability.
The subset, derived from the tightest target outward
Roku SceneGraph and UIKit set the core tier: anything all native targets can draw. Phone-only extras form a capability tier, so a screen that uses one fails at compile time for a target without it. Everything else is web-only, and a lint rule rejects it on native screens. The audit ran over 11 files on the phone hot path at a950df76e: six of about thirty stylesheets, plus the morph's TypeScript (inline styles and keyframe objects). It classifies by property name only, so display: grid, position: fixed, gradients and mixed-unit calc() still count as "maps", and nothing was checked against Roku or UIKit yet. Step 1 replaces it with rule-usage coverage from a real Home → Detail run in DevTools, values included, plus the selector shapes the build-time cascade must resolve (descendant, attribute and root-state selectors such as data-route-motion).
| Class | Declarations | What's in it | On native |
|---|---|---|---|
| Maps directly | 1,711 | display (flex), sizes, position, inset, margin, padding, gap, flex, align, colour, background, border, radius, opacity, transform, font, line-height, text-align, line clamp, object-fit, shadow | core tier: a style-table attribute |
| Compiles away | 200 | transition, animation, will-change, content-visibility, pointer-events, touch-action, tap highlight, scrollbars, overscroll | build time: keyframes become animation ops, hints are dropped |
| Needs a primitive | 65 | SVG stroke and fill (icons), content (pseudo-element text), grid columns, scroll-snap, corner-shape | an Icon primitive, a Rail with snap, a Grid primitive |
| Rejected on native | 24 | filter 11 (10 in JS), clip-path 6 (all JS), backdrop-filter 1 (JS), masks, background-clip text | the morph's blur veils and clip nest. Rebuild natively or drop (design decides, step 1) |
| Unclassified | 11 | cssText writes in JS, SVG geometry | reviewed by hand in step 1 |
Values the compiler has to handle
var()541 andcalc()346: resolved at build time per theme and breakpoint. Mixed-unitcalc(such as100% - 16px) has no Yoga equivalent; step 1 counts it.%165, viewport units 9: Yoga handles percentages, and the host supplies the viewport.position: fixed10,sticky2,display: grid4: fixed maps to a root overlay, sticky to a primitive, grid to the Grid primitive.- Selectors: 18 pseudo-elements, 10
:has/:is/:where/:not, 7 child-position selectors, 37@media, 16@keyframes. Media queries become style variants; the rest become explicit elements or state classes.
TV is already close to the subset
- tv-kit has no CSS at all. It uses SolidTV's Lightning-style props: 269
<view>, 148<text>, and propswidth486,y351,color350,height338,x288,fontSize161,borderRadius99,gap70. - Absolute
x/ydominates there. The subset adds flex so TV and phone share one layout model. - This changes a tv-leaf rule. That page says primitive props are "semantic, not CSS". The resolution: styling is the CSS subset, compiled to the style table, and behaviour (focus, rail, selection) stays as semantic props on primitives. The tv-leaf page now links here.
Architecture
Solid screens (subset JSX + subset CSS) packages/core · api · view models (unchanged)
│ build
├─ web / web TVs ── solid-js/web → real DOM + real CSS (unchanged, full CSS allowed off the hot path)
└─ native ───────── style compiler: CSS subset → style table (attribute ids, theme/breakpoint variants)
keyframe compiler: @keyframes / transitions → native animation ops
solid-js/universal renderer → op buffer [create][setAttr][move][destroy][beginAnim]
bytecode (Hermes or QuickJS) + style table + assets → signed kwry bundle (OTA)
on device:
JS thread ─ Solid runs, batches ops once per frame ──► runtime (C++): Yoga layout · view pool · diff apply
UI thread ─ applies one batch per frame ─────────────► UIView / android.view.View / tvOS UIKit
animations ─ Core Animation (iOS, tvOS) · native animators on a UI thread kept free of JS (Android)
kwry ─ services, player, DRM, contract, hello (engine, bcVersion, abi, runtimeVersion)
Roku: the same screens compiled with @roku-sdk/solid (Roku's Solid renderer → SceneGraph)Correction to an earlier assumption
Earlier planning assumed Android's ViewPropertyAnimator runs on the RenderThread. It doesn't. It drives a ValueAnimator on the UI thread and writes the render node each frame (AOSP ViewPropertyAnimator.java:858). The true RenderThread animator, RenderNodeAnimator, is hidden API. Corner-radius and clip morphs are UI-thread too. So on Android the frame gate depends on keeping the UI thread free: JS on its own thread, no layout during the flight. iOS commits animations to the separate render-server process (Apple, hitches talk).
Borrow, don't build: the runtime under our renderer
| Candidate | Verdict | Why (read in code) |
|---|---|---|
| **Snap Valdi C++ runtime (MIT, 16.4k★, 8 years in Snap production per its README)** | lead, gated by S2 | Its element API is a mutable, batched, binary op stream (RenderRequest.d.ts), the shape Solid's renderer emits. The host interface is 8 methods we can implement ourselves (IRootComponentsManager.ts). Android Views are the default backend (ValdiViewLoaderManager.kt:451). Each frame's batch is dispatched to the main thread (Runtime.cpp:608). Also brings Yoga in C++, a global view pool, native text, and module bytes loadable from anywhere (IValdiCustomModuleProvider.kt). Costs: no tvOS or focus; Bazel build exported to an AAR/xcframework; .valdimodule archive format; public for about a year. Engines: release iOS builds link JavaScriptCore only, which runs JS source, not bytecode; Hermes is linked only in debug and desktop builds; Android release uses QuickJS, a plain interpreter (valdi/BUILD.bazel:68-107). Enabling Hermes in release builds is our change to make and prove in S2. |
| Lynx (ByteDance, Apache-2.0, 15.3k★, TikTok production) | fallback | Mutable element API Solid can drive (renderer.h), Maven and CocoaPods artifacts, native views and animations. Against: no tvOS, Android key events dropped, its own layout engine instead of Yoga, prebuilt bundle encoder, and OTA bundles must target the oldest installed SDK. |
| NativeScript runtime (what the tvOS spike uses) | reject as UI runtime | No Yoga, no view pool, and JS on the UI thread (Runtime.java:640), which stalls Android animations. Keep only as an FFI if tvOS needs quick native calls. |
| React Native Fabric without React | reject | A clone-to-root tree that fights Solid's fine-grained updates, and a JS contract marked "UNSTABLE WITH NO SEMVER GUARANTEES" (source). |
| Write our own runtime from scratch | reject | Yoga, a view pool, batched apply, native animation and text are years of battle-testing that Valdi already has under MIT. |
| Borrowed piece | From | Used for |
|---|---|---|
| Op buffer protocol, interned attribute IDs, view pool with reset-on-recycle | Valdi | every native target, even if Lynx wins |
| Solid universal renderer pattern | our tvOS spike, @roku-sdk/solid | one renderer, swappable op sinks |
| tvOS focus-engine integration | react-native-tvos RCTViewComponentView.mm (MIT), already transplanted in the tv-leaf spike | focus bridge on top of the runtime |
| Apply a JS op buffer in one native call | symbiote-native | fallback if the Valdi seam is too coupled |
| Bytecode runtime-version keying | expo-updates | kwry hello and bundle server |
How mature Valdi really is
| Signal | Value |
|---|---|
| Production use | Snap's own apps only ("8 years" per the README); no documented outside production app |
| Public since | 2025-11-06; still beta (beta-0.2.1, 2026-10-19), 4 releases |
| Community | 16.4k stars, 538 forks, 86 contributors (mostly Snap staff), 52 closed and 17 open issues |
| Native views | 18 iOS and ~40 Android view classes: view, label, text input, image, scroll, video, blur, pickers, shape; no virtualised collection, no tvOS focus, thin accessibility |
| Gaps we had to patch in two days | Hermes in iOS release, iOS bytecode, tvOS, a lean-Hermes link error, Bazel on multi-NIC macOS |
Treat the engine as replaceable
Valdi's core (op stream, view recycling, Yoga, Hermes integration) is good engineering and the device numbers back it, but it is single-vendor, pre-1.0 and Bazel-based, and we would own a fork. So screens must not depend on it: they stay HTML/CSS, and the engine sits behind a renderer adapter that can be swapped (Valdi today; Lynx, a thin custom renderer or a future engine later) without touching screens.
No new UI language: the HTML/CSS subset is the API
Screens keep writing HTML tags and CSS, restricted to the subset. On web that is just DOM and CSS, unchanged. On native, the build maps the subset onto the engine's elements (div → view, span/p → label, img → image, overflow → scroll) and compiles the CSS into style tables. The element mapping lives inside each renderer adapter, not in an API screens import. Only three components exist because HTML has no answer for them: a focusable, virtualised Rail, the Player, and Focusable for TV.
| Change | Over the air? |
|---|---|
| Screens, layout, styles, copy, animation timing, new screens from existing elements | yes: bytecode and style tables in the signed bundle |
| A CSS property or tag mapped onto an attribute the native view already has | yes |
| A new native element or native behaviour (new player control, new list type) | no, app release; older apps fall back because the bundle reads the host's capabilities from its hello |
| Engine fixes (Valdi, Hermes) | no, app release |
Conformance: how big the port is, measured
| Area | Files | Browser-API uses | Clean files | Rejected CSS |
|---|---|---|---|---|
| mweb screens and components | 47 | 438 | 18 | — |
| mweb lib (feed, motion, routing) | 32 | 423 | 0 | 4 |
| mweb CSS | 31 | — | 13 | 97 |
| ui (desktop web components) | 123 | 504 | 25 | 8 |
| tv-kit | 40 | 48 | 19 | — |
The markup and styles are not the problem; direct DOM access is. Moving it behind ports is the bulk of the work, and it pays off whatever engine wins. Scan: scan/conformance.mjs, data in results/conformance.
Stages, each worth it on its own
A · Decouple (worth doing regardless)
Run the conformance scan in CI; move the 1,413 browser-API uses behind ports, starting with mweb screens and lib; add the subset lint. Web output stays identical (pixel and behaviour tests).
- Pass
- web pixel-identical; DOM-access count trending to zero on the hot path
B · Real Home → Detail on native (decision point)
Compile the real Home and Detail through the subset to the engine adapter, behind a flag; measure lines changed, rejected CSS and device frames against the WebView and Viewlift.
- Go
- under ~20% of those screens' lines changed and the device frame gate met
- Stop
- keep stage A; phones stay on the WebView plus native transitions
C · Remaining screens, one at a time
Hottest first, each behind its flag; the WebView keeps everything not yet ported.
D · Roku and tvOS on the same source
Roku through Roku's Solid renderer, tvOS through the engine adapter with the focus bridge.
Gates
| Gate | Holds when | How it's checked |
|---|---|---|
| G1 · No CSS on device | the native runtime contains no CSS parser, cascade or selector code; styles arrive as table entries | symbol check on the release binary, plus a trace of a Detail open showing zero style resolution |
| G2 · Bytecode only | release builds on Android, iOS and tvOS run precompiled Hermes bytecode with no JS parse at launch; a source fallback is logged and counted. Valdi ships JavaScriptCore (source only) in release iOS builds, so this needs Hermes enabled there | engine stats on cold start; fallback counter in telemetry |
| G3 · OTA | a signed bundle changes Detail layout, colours and animation timing with no store build; a bytecode mismatch falls back to source; a bad bundle rolls back | scripted update on both platforms |
| G4 · Frames | Detail-open flight p95 ≤ 16.7 ms and no frame > 33 ms over 20 runs at 120 Hz; still true with a 150 ms block on the JS thread | Android gfxinfo framestats (first 500 ms after tap); iOS Instruments hitches |
| G5 · Tap to first motion | ≤ 16.7 ms from touch-up to the first moved frame. Detail is pre-mounted and laid out off screen while the card is pressed, so the flight starts on the next frame; Detail data fills in during the flight | same traces |
| G5b · Tap to Detail complete | Detail fully populated (text, poster, rails) no later than the kwry WebView arm, which has a JIT; Hermes and QuickJS don't | first-content marks in both arms |
| G6 · Cold start | ≤ 1.0 s to the Home rail visible on a low-end Samsung A-series (Discord's informal bar) | am start -W plus a first-rail mark; iOS launch trace |
| G7 · Memory | resident memory on Home and after 20 opens is no worse than the kwry WebView arm | dumpsys meminfo, mach_task_basic_info |
| G8 · Parity | the web build of the same source passes the existing pixel-fidelity gate; native matches the design checklist agreed in step 1 | fidelity script; side-by-side video review |
| G9 · Text and accessibility | Bengali conjuncts correct; TalkBack and VoiceOver read Home and Detail in order | string-by-string comparison; screen-reader walk |
Steps
0 · Baselines, three arms
Re-measure today's kwry WebView and the native Viewlift app on Home → Detail with the existing rig. The October readings predate the compositor rewrite of the open animation. The third arm, subset-native, joins from step 5.
- Pass
- both arms reproduce within run-to-run noise; host CPU and memory pressure recorded with every run
1 · Subset v0 and design parity
Turn the audit into a spec: core tier, phone capability tier, web-only. Add mixed-unit calc, pseudo-element and selector counts per file, so the rewrite cost is a list of lines, not a guess. Agree with design which parts of the morph survive natively: card → hero, radius, dim; blur veils become a pre-blurred image or are dropped.
- Pass
- every hot-path declaration classified; parity checklist signed off
2 · Runtime seam (S2)
Drive Valdi's runtime from a Solid universal renderer: our own root manager, ops written straight to the buffer, no Valdi components. Render one Rail screen on the Android AVD and the iOS simulator. Load the module from a file path, as OTA would. Consume it through valdi export into Gradle and Xcode. Because tvOS is the reason for this plan, S2 also compiles the iOS layer for the tvOS simulator with one focusable view, and builds an iOS release configuration with Hermes enabled.
- Pass
- no Valdi
Componentclasses in our bundle; one op batch per frame; module loaded from disk; builds from kwry's Gradle/Xcode - Kill
- the seam needs Valdi's component model; Bazel can't be wrapped; the iOS layer can't be made to build for tvOS; or Hermes can't run in an iOS release build. Run the same test on Lynx
3 · Style and keyframe compiler
A Vite plugin: subset CSS → style table with theme and breakpoint variants; @keyframes and transitions → animation ops; lint errors for rejected properties on native screens. The web build keeps the real CSS untouched.
- Pass
- G1 holds; the web build passes the pixel-fidelity gate unchanged
4 · Home, native
Home on Android and iOS with the real packages/core and api running in the engine, not mock data (the tvOS spike used mocks). Rails recycle; posters decode at cell size.
- Pass
- G6 cold start and G7 memory on the AVD as a relative A/B; scroll frames within G4
5 · Home → Detail, the hardest animation
Card → hero shared element as native animation ops: corner radius, dim and the hero image. Detail is pre-mounted off screen on press. Run two stresses: a 150 ms block on the JS thread, and a Detail mount landing mid-flight, because the runtime applies batches and runs Yoga on the main thread, where Android's animators also run.
- Pass
- G4 and G5 on the AVD; then the headline run on the real phones
- Kill
- flight p95 above the kwry WebView arm after flattening
6 · OTA end to end
Through kwry's signed bundles: change Detail layout and animation timing; ship a bundle built for the wrong bytecode version; ship a broken bundle.
- Pass
- G3: the update applies, the mismatch falls back to source, the broken bundle rolls back
7 · tvOS focus and Roku
Compile the runtime's iOS layer for tvOS and add the focus bridge; rerun the tv-leaf focus walk unchanged. Roku: compile the same screens with @roku-sdk/solid, Roku's own Solid renderer, swapping our primitives for SceneGraph nodes.
- Pass
- tvOS: 0/120 focus misses, focus-to-Solid p95 < 1 ms (the spike measured 0.58 ms)
- Kill
- focus misses or focus latency worse than the NativeScript spike; fall back to that spike's UIKit renderer for tvOS
8 · Go / no-go
Three-arm side-by-side video on the real phones: kwry WebView, subset-native, Viewlift native. All gates in one table.
- Go
- G1–G9 hold; screens move to the subset one at a time, hottest first
- No-go
- keep WebView plus native transitions on phones; the runtime still serves tvOS and Roku
Where it runs
MacBook (M5 Pro, 64 GB): build, function, relative A/B
- Android AVDs already there (
Pixel_10,sb_api34, others), iOS 26.5 and tvOS 27.2 simulators ("HV Spike ATV4K" booted), browsers and a GPU. - Good for every functional gate, the compiler, OTA, and relative A/B between arms on the same emulator.
- Load average was about 6 when checked. Record pressure before every reading, and close Android Studio, Gradle daemons and stray simulators first.
Real phones: headline frame and start-up numbers
- Emulator frame timing is not device frame timing; emulator-only evidence is why PR #465 (private repo) stayed a draft.
- G4–G6 headline numbers come from the Fold (120 Hz) and the Samsung A-series phone already chosen for PR #465.
- tvOS frame numbers come from a real Apple TV 4K.
How this plan was built method
A script classified every CSS declaration in the 11 hot-path files (stylesheets plus inline styles and keyframe objects in the motion TypeScript) and flagged values such as calc(), var(), position: fixed and blur(). tv-kit was scanned separately; it has no CSS.
Valdi, Lynx, NativeScript and React Native Fabric were each read in code against nine discriminators: separability from their component model, real native views, OTA loading, tvOS and focus, animation threading, JS threading, Gradle/Xcode integration, size and licence, and text. The key Valdi claims were checked again by hand.
Apple's licence agreement and review guidelines, Google Play policy, Hermes and QuickJS sources, AOSP animation code and Apple's JIT documentation, all cited inline.
Nothing has been built for this plan. Valdi's binary size, Bengali shaping on its text views, and how it behaves under our 150 ms JS-block stress are all unmeasured.