Hoichoi client platform · tvOS · candidate renderer

Blitz spike runbook: real CSS on Apple TV

A one-week, gated spike to find out whether Blitz, an open-source HTML/CSS engine in Rust, can render our shared Solid screens and CSS on Apple TV, where no system browser exists. Each day has a command list, a pass line and a kill line. It also answers a second question: would Blitz help the phone apps reach 120 fps on heavy transitions? (Short answer: no, and the reason is below.)

Runbook by Claude (agent) from DioxusLabs/blitz f5ea1ca, Hoichoi.SharedClientPlatform a950df76e and the tv-leaf spikePublic · every page in this group shares one access rule

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.

5½days · one engineer + agents
Timebox
f5ea1ca2026-11-14 · Apache-2.0 / MIT
Blitz pin
4any one stops the spike
Kill lines
noneprimitives stay the fallback
Plan A at risk

What we are testing, and what it would replace

System browser (web, Android TV, LG, Samsung, phones)ElectronBlitz on tvOS (candidate)
What it isthe OS's own WebKit or Chromiuma full Chromium plus Node in every apponly the part that turns HTML and CSS into pixels
JavaScriptbuilt in, with JITV8 plus Nodenone 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)allallnone. kwry's native services provide them, as they already do
CSS coveragecompletecompletepartial, beta (status page)
Animation modelcompositor: transform and opacity move cached GPU layers off the main threadsame as Chromiumno compositor: every animating frame re-runs style, layout and paint for the whole document (document.rs:292)
Size0 (the OS ships it)100 MB or morea few MB (measured on day 5)
Runs on tvOSnonoshould, 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. DocumentMutator already has create_element, set_attribute, insert_nodes_before and remove_node. We export them plus resolve, paint and hit_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/solid stays.
  • 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

NeedWhereCheck
MacBook (M5 Pro, Xcode 27.2, tvOS 27.2 runtime)admin@shabinders-mac-9, the same machine as the tv-leaf spikexcrun simctl list runtimes | grep tvOS
Simulator "HV Spike ATV4K"udid in ~/spike-tvos/udidxcrun 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)rustuprustup 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 pagesTV Home markup from packages/tv-kit (SCP a950df76e) and the 9 report diagramssaved as static HTML in ~/spike-blitz/pages/
Quiet machineclose Android Studio, Gradle daemons, stray simulatorsrecord 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.

Pass: a static Home frame appears in the tvOS simulator. Kill: it needs more than about 3 patched crates to build.
↓

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.

Pass: Home renders at 1080p with resolve plus paint under 8 ms per frame on the Mac, measured as an idle repaint.
↓

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 fpsHelps?Why
Swap the WebView for Blitznoloses the compositor, JIT JS, native text input and full CSS; the same render passes remain
Flatten the open morph into 2–3 snapshot layersyes, the measured fixthe 120 fps controls already show a few large transformed layers hold 8.3 ms frames
Warm Vulkan pipelines before the tapyes, smallremoves the ~60 ms VulkanCreateGraphicsPipelines stall measured during the open
Pre-decode posters before the first frameyes, cold open onlyimage 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 ceilingthe 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.