Why this spike exists
Apple TV is the one screen we ship to where apps get no browser engine: WKWebView is not available on tvOS. The TV leaf plan gets around that by rebuilding screens on about 12 native primitives (plan A). Blitz is an HTML/CSS engine *without* a browser around it: Firefox's CSS engine Stylo, Taffy for flex/grid/block layout, Parley for text, and Vello or Skia for drawing (README). If it can draw our real CSS on tvOS, Apple TV runs the same screens as the web build, and plan A becomes the fallback. This week finds out, cheaply.
What we are testing, and what it would replace
| System browser (web, Android TV, LG, Samsung, phones) | Electron | Blitz on tvOS (candidate) | |
|---|---|---|---|
| What it is | the OS's own WebKit or Chromium | a full Chromium plus Node in every app | only the part that turns HTML and CSS into pixels |
| JavaScript | built in, with JIT | V8 plus Node | none built in. Solid runs in our engine (V8 or JSC, no JIT on tvOS) and drives Blitz's DOM through a bridge |
Web APIs (fetch, storage, <video>, EME) | all | all | none. kwry's native services provide them, as they already do |
| CSS coverage | complete | complete | partial, beta (status page) |
| Animation model | compositor: transform and opacity move cached GPU layers off the main thread | same as Chromium | no compositor: every animating frame re-runs style, layout and paint for the whole document (document.rs:292) |
| Size | 0 (the OS ships it) | 100 MB or more | a few MB (measured on day 5) |
| Runs on tvOS | no | no | should, once Rust builds for tvOS (day 1 checks) |
If the spike passes, the integrated app looks like this. Only the tvOS column changes; every other platform keeps its system browser.
shared Solid app (screens, CSS, view models) — the same source as web
│ solid-js/web DOM calls
┌─────────────────┼───────────────────────────────────────────┐
web / Android TV tvOS Roku
LG / Samsung ┌──────────────────────────────┐ @roku-sdk/solid
system browser │ JS engine (V8 or JSC) │ → SceneGraph
(unchanged) │ └ DOM shim ── batched FFI ───┼─► blitz-dom (Rust)
│ kwry bridge: fetch, storage, │ Stylo → Taffy → Parley
│ player, DRM (unchanged) │ blitz-paint → anyrender
└──────────────────────────────┘ → CAMetalLayer
Swift host:
• UIViewController owning the Metal layer
• invisible focus views over focusable boxes → tvOS focus engine
• AVPlayerLayer under a transparent hole → video + FairPlay
• AccessKit tree → UIAccessibilityElement → VoiceOver (own spike)What we write if it passes
- DOM shim (JS, ~500 lines). The DOM calls Solid uses (
createElement,insertBefore,setAttribute, events), batched once per frame into one FFI call. Blitz's own list of DOM APIs Preact needs is the checklist. - C API over
blitz-dom.DocumentMutatoralready hascreate_element,set_attribute,insert_nodes_beforeandremove_node. We export them plusresolve,paintandhit_test. - Swift host. Replaces winit and
blitz-shell: the Metal layer, remote input, focus views, the video hole. - A CSS subset contract. Shared CSS stays inside what Blitz draws, enforced by a lint rule and screenshot comparisons in CI.
What stays exactly as it is
- Every platform except tvOS. The system browser keeps full CSS and its compositor.
- Roku. It can't run native code, so
@roku-sdk/solidstays. - kwry services. Network, storage, DRM and the player are already native and bridged.
- Plan A. The 12-primitive renderer remains the fallback until Blitz passes all gates.
Before you start
| Need | Where | Check |
|---|---|---|
| MacBook (M5 Pro, Xcode 27.2, tvOS 27.2 runtime) | admin@shabinders-mac-9, the same machine as the tv-leaf spike | xcrun simctl list runtimes | grep tvOS |
| Simulator "HV Spike ATV4K" | udid in ~/spike-tvos/udid | xcrun simctl boot $(cat ~/spike-tvos/udid) |
Rust nightly with rust-src (tvOS is a tier-3 target, so the standard library is built from source) | rustup | rustup toolchain install nightly --component rust-src |
| Blitz, pinned | ~/Tools/blitz (external repos live in ~/Tools) | git -C ~/Tools/blitz checkout f5ea1ca |
| tv-leaf spike app (Swift host plus the focus harness) | Hoichoi.Docs/plans/client-architecture/tv-leaf-spike/ | builds and runs the 120-poster walk |
| Test pages | TV Home markup from packages/tv-kit (SCP a950df76e) and the 9 report diagrams | saved as static HTML in ~/spike-blitz/pages/ |
| Quiet machine | close Android Studio, Gradle daemons, stray simulators | record uptime and memory_pressure before every reading; the tv-leaf run had a load average of 61 until the machine was cleaned up |
Day by day
Day 0 · Does it draw our CSS? (no tvOS yet) ½ day
Render each test page with Blitz's screenshot example on macOS at 1920 wide, and the same page in Chromium through the docs-site verify harness. Diff the two images per page.
List every CSS feature Blitz misses, then grep our CSS for how often each one is used.
Pass: ≥ 90 % of pixels match on Home and on 7 of the 9 diagrams. Kill: the gaps include grid,overflow scrolling or transform, and none can be fixed this week.Day 1 · Does it build for tvOS? 1 day
Cross-compile blitz-dom, blitz-html and blitz-paint with the CPU renderer (anyrender_vello_cpu) for aarch64-apple-tvos-sim. No winit and no blitz-shell.
Show the rendered RGBA buffer in a UIImageView inside the spike app.
Day 2 · GPU drawing and the C API 1 day
Draw through Vello (wgpu on Metal) into a CAMetalLayer. Fall back to anyrender_skia if wgpu won't build for tvOS.
Export the C API: doc_new, mutate_batch, resolve, paint, hit_test.
Day 3 · Solid drives it 1 day
Run Solid in V8 (NativeScript tvOS, as in the tv-leaf spike) or JSC. The DOM shim sends one batch of changes per frame across the C API.
Mount the spike's 120-poster rail.
Pass: mount ≤ 30 ms (the primitive renderer's baseline is 9–27 ms). Kill: more than 2× the primitives' mount time.Day 4 · tvOS focus 1 day
After each layout, place invisible UIFocusEnvironment views over every box with tabindex. The tvOS focus engine moves between them, and the host sends focus and blur to Solid and sets :focus in Blitz.
Rerun the tv-leaf focus walk unchanged.
Pass: 0/120 focus misses and focus-to-Solid p95 < 1 ms (the tv-leaf spike measured 0.58 ms).Day 5 · Text, video, cost, write-up 1 day
Bengali through Parley: conjuncts and matras compared against CoreText on the same strings.
Video: AVPlayerLayer under a transparent box, with Blitz drawing the overlay.
Measure app size added (release build, stripped), resident memory on Home, and a rail scroll as an animation.
Numbers go into the tv-leaf page. The decision goes to the team: start a VoiceOver spike, or close this candidate.Commands
# Day 0 — Blitz vs Chromium on our pages (macOS, no tvOS)
cd ~/Tools/blitz && git checkout f5ea1ca
for p in ~/spike-blitz/pages/*.html; do
cargo run --release --example screenshot -- "file://$p" 1920 # writes examples/output/*.png
done
# Chromium side: the docs repo's playwright-core, same 1920 width, then pixel-diff each pair
# Day 1 — tvOS simulator build of the engine crates, CPU renderer only
rustup toolchain install nightly --component rust-src
cargo +nightly build -Zbuild-std --release \
--target aarch64-apple-tvos-sim \
-p blitz-dom -p blitz-html -p blitz-paint -p anyrender_vello_cpu
# Failures here are the day's work: patch each crate that breaks and note it in the log
# Before EVERY reading (day 2 onward)
uptime; memory_pressure | tail -1; pgrep -fl 'gradle|Simulator' || true// Day 3 — the DOM shim's one hot path: batch, then one FFI call per frame
const ops: number[] = []; const strs: string[] = []
const s = (v: string) => (strs.push(v), strs.length - 1)
export const doc = {
createElement: (tag: string) => { const id = nextId++; ops.push(OP.CREATE, id, s(tag)); return node(id) },
setAttribute: (id: number, k: string, v: string) => ops.push(OP.ATTR, id, s(k), s(v)),
insertBefore: (parent: number, id: number, anchor = 0) => ops.push(OP.INSERT, parent, id, anchor),
remove: (id: number) => ops.push(OP.REMOVE, id),
}
requestAnimationFrame(function flush() {
if (ops.length) { blitz.mutateBatch(new Int32Array(ops), strs); ops.length = 0; strs.length = 0 }
requestAnimationFrame(flush)
})Would Blitz help the phone apps reach 120 fps?
No. On phones it would likely make heavy transitions slower.
Our home→detail open animation drops frames because it runs about 95 animations over roughly 13 large layers. Each blur, opacity group and clip nest forces the GPU to draw an offscreen pass. Chrome traces of the Fold open put most of the GPU time in FinishPaintRenderPass, about 1.5 passes per frame. Synthetic controls in the same WebView (full-screen transforms, 13 plain layers, a backdrop blur) all held ~120 fps. So the WebView is not the ceiling; the structure of the animation is. Blitz would not fix that, because it has no compositor at all. While anything animates, it re-runs style, layout and paint for the whole document every frame (document.rs:292), and opacity, clips and filters become isolated layers in its painter too (layers.rs). Chromium moves cached layers on its compositor thread; Blitz would redraw every pixel of the same structure each frame.
| Lever for phone 120 fps | Helps? | Why |
|---|---|---|
| Swap the WebView for Blitz | no | loses the compositor, JIT JS, native text input and full CSS; the same render passes remain |
| Flatten the open morph into 2–3 snapshot layers | yes, the measured fix | the 120 fps controls already show a few large transformed layers hold 8.3 ms frames |
| Warm Vulkan pipelines before the tap | yes, small | removes the ~60 ms VulkanCreateGraphicsPipelines stall measured during the open |
| Pre-decode posters before the first frame | yes, cold open only | image decode was 124 ms during the first open |
| Hand the transition to native (snapshot the departing card and arriving page as native layers, animate in Core Animation or HWUI) | yes, the ceiling | the native app never drops for this reason: about zero offscreen passes during its transition. kwry can host this without moving the screens out of the web |
So Blitz is a tvOS answer, not a phone answer. If day 2 passes, one optional measurement settles the phone question with numbers instead of reasoning: render a single frame of the open morph (the real DOM, mid-flight) in Blitz on the Mac, and time resolve plus paint per frame. Above 8.3 ms closes the question for phones. Below it is worth a second look only if the flattened WebView morph still misses its target.
Risks to watch during the week
Can kill it later
- VoiceOver. I found no AccessKit-to-UIKit adapter; Slint's winit backend enables only AccessKit's Linux adapter (Cargo.toml). Out of scope this week; it gets its own spike if the week passes.
- Scroll and focus animation without JIT. CSS transitions run in Rust, but with no compositor every animated frame is a full repaint. Rail scrolling on a real Apple TV must hold 60 fps.
- Beta churn. Pin
f5ea1ca, send fixes upstream, and carry no long-lived fork.
Cheap to check
- Bengali shaping through Parley instead of CoreText: a string-by-string comparison on day 5.
- Size and memory: measured on day 5, against a budget agreed before the day.
- CSS gaps: day 0 lists them before any tvOS work, at no cost to plan A.
How to record results so they can be trusted method
Log uptime, memory_pressure and the Blitz commit beside every number. Throw away readings taken with a load average above 4.
Focus and mount numbers use the tv-leaf harness unchanged (spike.log, CADisplayLink late-frame counter, mach_task_basic_info), so Blitz and the primitives are compared like for like.
Raw logs and images in Hoichoi.Docs/plans/client-architecture/blitz-spike/; the summary table and the go/no-go decision on this page and on the tv-leaf page.