Walkthrough Film

A deterministic logical-clock HTML film: one page, one render(gt), N chapter scenes, rendered frame-by-frame and assembled offline. Built for the case a single-page explainer cannot survive — a 3+ minute walkthrough that ships in 9 versions across 2 brands, where a client reviews it frame by frame and each round must re-render only what moved.

What makes it different from explainer-video/smooth-render: the timeline is computed from voiceover word timestamps, not authored; each scene renders as its own MP4 by seek()+screenshot (zero dropped frames, re-render one scene in minutes); pacing is warped at assembly, not in the page; and the whole look is theme-token driven so a second brand is a URL parameter, not a fork.

When to use

• Chaptered product tours, platform walkthroughs, white-label demo films, launch films > 90 s.
• Anything that will go through review rounds: the per-scene render + VER versioning is the point.
• Not for: a 30-60 s single-idea explainer (use explainer-video), a pure CSS loop, a screen recording recut.

The one hard rule

Every visual is a pure function of time. A scene draws from its scene-local lt (and the ground from global gt) with no state carried between frames, no timers, no Date, no CSS transitions. Corollaries, each learned the expensive way:

• One easing curve per move. Never two writers on the same element's transform in one frame.
• Verify at 1/30 s. Shoot consecutive frames t, t+.033, t+.067 … across every move you touch and confirm the element advances monotonically by a similar delta. Pops and stalls are invisible at 0.5 s steps.
• Scrubbing to any t must produce the exact frame the render produces. If it doesn't, the render is not reproducible.

Method

1. Script and record VO first. Per-scene clips with word-level timestamps (see the vo-sync skill). The script is the spine; nothing gets animated before the words exist.
2. Compute the timeline (scripts/compute_timing.js): a CONFIG array of {id, cues:[[key, spokenWord]]} turns word timestamps into per-scene start, dur and named cues[]. Durations come from max(HEAD + voLength + TAIL, lastCue + 1.0, MIN[id]), so every chapter ends ~1 s after its last spoken word. Outputs timing.json + timing.js (window.__TIMING), VO events and sentence captions. CUT=a,b node compute_timing.js drops scenes to make a short cut without touching the page.
3. Build the page. engine.js owns the clock, the scene registry, layers, the theme flag and the per-frame hooks; each chapter is its own js/ch_<id>.js + css/ch_<id>.css exporting {layer, draw(lt,dur), enter?, exit?}. Scenes read their cue times from window.__TIMING — never hard-code a beat that a cue can anchor. See reference/PIPELINE.md.
4. Verify continuously. node scripts/play.mjs 14 (headless high-rate sweep) must end errors: 0; node scripts/shots.mjs <dir> <t…> for frames, and look at every JPEG — an error-free sweep proves nothing about layout.
5. Render per scene (scripts/render_scene_step.mjs): for each output frame, seek(start+(k+.5)/30), wait two rAFs, screenshot, then encode. Deterministic, no duplicated or dropped frames whatever the page's real-time speed. scripts/render_all.sh runs 3 workers and skips existing files, so a re-render is "delete the stale clips, run again".
6. Assemble the mix (scripts/build_mix.mjs): per-scene pacing warp, VO tempo-fit per segment, an SFX event table keyed off cues, a music bed beat-locked to one cue and sidechain-ducked under the voice, two-pass loudnorm, concat, output to Versions/<name>_${VER}_final.mp4.

Theme switching (one tree, many skins)

?theme=<name> → engine sets window.__THEME and adds theme-<name> to both <body> and <html> → CSS custom-property token blocks do the rest. Rules:

• All ink/ground/glass values are tokens (--bg --txt --dim --glass-bg --grad …). No hard-coded colour outside the token sheet.
• Card-scoped ink: when a surface is light on a dark ground (or vice versa), re-declare the ink tokens on the surface element itself, so text inside cards stays readable whatever the ground is doing.
• A ground that changes over time writes the dynamic tokens per frame from a GROUND3.update(gt) hook the engine calls before the scene draws. Ink should flip fast (a narrow smoothstep) while the ground crossfades slowly.
• Every change is gated (.theme-x selector or if (__THEME==='x')) so earlier versions stay pixel-identical. Prove it: run the sweep in the old themes too, and shoot one old-theme frame from your area.
• Assets are chosen per theme (dark vs light wordmark) at the point of use, not at parse time. See reference/THEMING.md.

Multi-version workflow

One VER env threads through everything: renders_${VER}/NN_id.mp4 → warped_${VER}/ → Versions/<name>_${VER}_final.mp4. To ship round N+1: change the page, delete only the affected NN_id.mp4 and its warped twin, re-run render_all.sh (it skips the rest), re-run the mix. Keep a SPEC.md decision log with one dated bullet per round — it is the only record of why a frame looks the way it does, and the client will ask.

Parallel builders

Rounds are large; split them. Write a brief (reference/SUBAGENT_BRIEF_TEMPLATE.md) that gives each owner an exclusive file set (two agents editing one file will clobber each other), the tokens to use, the exact frame times to check, and the standing rules. Every owner must also prove no regression: run the sweep in the other themes and shoot one frame from each of them in their own area. Collect deviations back into the spec.

Files

• reference/PIPELINE.md — timing → scenes → render → mix in detail, with the config shapes.
• reference/THEMING.md — token tables, card-scoped ink, the load-order trap, per-frame token lerp.
• reference/PITFALLS.md — 24 numbered gotchas, each of which cost a render cycle.
• reference/SUBAGENT_BRIEF_TEMPLATE.md — the parallel-builder brief.
• scripts/compute_timing.js — word timestamps + CONFIG → timing.json, cues, captions, VO events.
• scripts/render_scene_step.mjs — deterministic seek+screenshot render of one scene.
• scripts/render_all.sh — all scenes, N workers, skip-existing, VER → renders_${VER}.
• scripts/shots.mjs / scripts/play.mjs — frame shots and the error sweep (both honour THEME).
• scripts/build_mix.mjs — warp / SFX / music / duck / loudnorm / concat → final MP4.

Companions: vo-sync (word timestamps), smooth-render (real-time capture when frame-step is overkill), audio-stems (music + SFX generation), motion-graphics (the move vocabulary).