video-3d

The lane for films where flat cards in space (video-moves' CSS 3D) are not enough: solids, light, real depth and occlusion, huge element counts, a rendered look. HyperFrames seeks frames out of order in parallel workers, so every visual state is computed from t alone.

Proven by private test films (they do not ship; their numbers, traps and fixes are in the references). Four finished looks: a logo film (extruded logo, PBR, lock-up landing), a globe film (15k dots, draw-on arcs, labels), a particles film (64k particles from a voice morphing into words), an ASCII film (a scene as glyphs, words resolving out of it). Seven capability reels (2026-10-14, one capability per section): materials, post, styles, models, camera-text, data, WebGPU. The labels are explained in the legend of references/capabilities.md.

video-studio orchestrates the film and its laws (../video-studio/references/laws.md, Picture: motion has a cause, no frozen holds, every frame postable, readable text); video-moves owns camera grammar (../video-moves/scripts/camera-kit.js); video-sound the sound; video-check the gates. Colours come from the film being made - no brand or film content is baked into this skill.

Input: the film's brief.md (../video-studio/references/brief.md). It owns copy, claims, tone, material, moments and private data; this skill owns the implementation. If the brief cannot be met, say so to video-studio - never change it silently.

Requirements

• HyperFrames CLI ≥ 0.8.156 (tested on 0.8.156; pin it in the film's package.json) and a GPU-capable browser for the render (--browser-gpu). WebGPU films need a hardware adapter. SwiftShader (--no-browser-gpu) renders WebGL only, ~6-10x slower.
• three.js 0.181.2 (r181), loaded from jsdelivr through an import map (three, three/addons/; WebGPU films also three/webgpu, three/tsl) - every recipe assumes this version. Other pins the recipes use: troika-three-text 0.52.4, d3-force 3.0.0, @dimforge/rapier3d-compat 0.19.3 (bakes in Node), world-atlas 2.0.2 (maps).
• Node 22+ for the Node tools (build-map.mjs, seek-order-test.mjs, your bakes). The seek-order test uses puppeteer-core and HyperFrames' cached chrome-headless-shell (it finds them in the npx cache).
• Python 3 with numpy and Pillow, plus ffmpeg, for the QA scripts.
• The upstream hyperframes skills (heygen-com/hyperframes) and the sibling video skills.

When 3D, when CSS

If flat layers can do it, prefer CSS: cheaper, check can see it, text stays DOM.

What is proven

references/capabilities.md is the catalogue: every useful capability by area (17 areas), how to keep it deterministic, traps, sketches, measured costs and a status - proven (film), proven, partial (film): what or never (not seek-safe as shipped, with the replacement). Only rendered capabilities are listed; the legend names what was left out (Gaussian splats, fracture, fluids, lightmaps, cascaded shadows, stencil portals, most WebGPU post). All proofs ran on the GPU path; SwiftShader was checked only in part. Never: GlitchPass, AfterimagePass, TAA/TRAA accumulation, VideoTexture, physics stepping in the page.

Anything not in the catalogue: render a 3-5 s probe and run the determinism protocol before promising it, then add it to capabilities.md with the probe film as its status.

Recipes and code

references/recipes.md - eleven proven kinds of scene with the pieces to lift. Reusable code, each folder with a README: assets/recipes/ascii/ (glyph pass), looks/ (toon hull, Sobel ink, halftone, dither, CRT, ink and paper, wipe), post/ (seeded AO, grain hash, SMAA wait, sub-frame motion blur, presenter, seeded glitch), materials/ (lathe vessels, GPU AO baker), models/ (seek-safe mixer, baked rigid bodies and VAT cloth), compositing/ (sub-composition time, alpha export), data/ (map builder, GPGPU replay/bake), webgpu/ (film clock, node frame, atomic density splat), qa/ (seek-order test, per-section comparison, blank/frozen check, exact shimmer).

Build

1. references/contract.md first - binding: the page (build hold, warm-up, visible failures, sub-compositions), time (everything from t, integer-frame decisions, seeded libraries, no frozen ends), picture (supersampling, culling, lines, text, colour, banding), post-processing, models and animation, render (determinism protocol, backends, bitrate), WebGPU.
2. Start from assets/scene-skeleton/ (index.html + assets/scene.js): a seek-driven renderer with camera helpers and a try/catch renderAt; fill in build() and renderAt(t).
3. Take the recipe and the capability entries the film needs; lift code from assets/recipes/ first, and write the rest from the recipe and the capability entries.
4. Camera moves and story time from video-moves (the same math; copy what you need into the module).
5. Light for the medium: measure hero colours (PBR) or cell luminance (glyph and grid looks) on a rendered frame before judging.

Check

references/qa-3d.md: hyperframes check is a lint only (it cannot see a canvas). Snapshots at every state change; the determinism protocol (--workers 4 vs --workers 1 - auto is one worker for ≥ 900 frames - plus the in-page shuffled/reverse seek-order test, PNGs per section when checksums differ); blank/magenta/frozen output; 1:1 crops; chunk seams; banding on the encoded file; hero colours; shimmer tools for quantised looks. Pin --browser-gpu (or --no-browser-gpu) for a deliverable and never mix the two. Then video-check's gates and its independent review.

Adapt it

• Your palette and brand objects: set the --film-* tokens from each film's brief, keep your logo SVGs, product models and fonts in one folder that films copy in, and measure your brand colours once under the light and tone mapping you use (capabilities.md 3) - write the numbers down.
• Your GPU and backend per deliverable: choose --browser-gpu (WebGL or WebGPU) or --no-browser-gpu (WebGL only) for each deliverable, write it into the render command, and never mix chunks. The costs here were measured on an M1 Max; time one film on your machine before you plan a long render.
• Adding a capability: render a 3-5 s probe film, run the determinism protocol and the seek-order test (qa-3d.md step 3), then add an entry to capabilities.md with its status, traps and costs, under a label for your probe film in the legend.
• Your asset policy: which sources and licences you accept, and whether the agent may download free assets without asking (capabilities.md 16).
• Upgrading three.js or HyperFrames: re-render one film per recipe you use and re-check the private node-frame API (contract.md, WebGPU) before you move the pins.