Portfolio pass: fix Node/Chromium simulation drift, add tests, CI and a README built from real renders

[matuskalis]

What changed

Most important first.

1. A determinism bug in the headline claim, found by measuring and fixed. The notes come from simulate() in Node, the picture from simulate() in the Chromium that Remotion renders with. I hashed the complete simulation result in both. 32 of the 34 shipped scenes agreed. scenes/swarm.json did not (the two split at frame 70; Node counts 380 notes where the picture implies 393; only 33 of the first 380 note times agree) and neither did scenes/infinite-loop.json. Cause: Node 24 (V8 13.6) and Chrome 149 differ by one ulp on about 3 percent of Math.cos and Math.sin inputs, and every launched ball turns a random angle into a velocity with them. src/sim/trig.ts now does those calls in exact BigInt arithmetic and rounds once. No existing picture changes: the new simulation equals the old Chromium one on all 34 scenes, and Node now equals Chromium on all 35. npm run parity and npm run probe:trig reproduce the measurements.

2. validate catches what the engine silently ignored. A scene with "phyiscs", "gravity": "fast" and "instrument": "kazoo" used to print VALID. It now reports unknown field "phyiscs", did you mean "physics"?, names the wrong type and lists the valid instruments. A scene name containing / or \ is refused, because it becomes the output file name and ../../x would write outside the project. A duration under half a frame no longer prints VALID and then crashes. A spiral scene is no longer told its ball "never cleared every ring" (that preset keeps the rings on purpose).

3. 273 tests (vitest), a typecheck script and golden output. The physics step is checked against the closed form of semi-implicit Euler; a ball released from the exact centre without gravity travels along a diameter, so every bounce and note time has a closed form to test against. Also covered: restitution and the 55 px/s resting threshold, every effect, rings, ball-to-ball collisions, the seeded generator, exact cos and sin against 66 bc references, pitch, the WAV header, the MIDI reader, validation, the CLIs, every JSON example in the docs, and a SHA-256 of the full simulation and WAV of all 35 scenes. Eleven deliberate mutations of the physics each fail at least one test.

4. README and docs from real renders. A four-panel GIF (1.6 MB) and a contact sheet of one frame per preset, captioned with scene name, preset and seed, both cut from renders made with npm run make at 360x640; a 200 KB clip with sound; a worked prompt-to-frame example whose outputs are real; docs/engine.md (every constant, the collision math, the instrument formulas, frame timing) and docs/determinism.md (what was hashed, what matched, what did not). npm run docs:assets regenerates the pictures, and two full runs give byte-identical files.

5. CI (.github/workflows/ci.yml, pinned to ubuntu-24.04): typecheck and tests on Node 22 and 24, and a job that renders one second of scenes/readme-demo.json at quarter size (uploaded as an artifact) and runs npm run parity. One of the five runs so far failed in the render job with ECONNRESET while downloading Chrome Headless Shell from remotion.media; the job now caches the browser and retries npx remotion browser ensure three times, and the run after that change passed with a cache hit.

6. Smaller. make now hands unknown flags to remotion render (--scale=0.25 --frames=0-299 is a 5 s preview; its usage line said --out out/x.mp4 while the parser wants --out=out/x.mp4). AGENTS.md gained the missing growToFillAtEnd field, a table for reading validate output and measured render costs in place of an unreproduced "7 seconds". scenes/purple-escape.json is the contract's second worked example. .gitignore covers .env*, CLAUDE.local.md and coverage. Two transitive dev advisories (fast-uri, js-yaml) are patched with the in-range npm audit fix (six lockfile lines), audit reports 0. The old docs/demo.gif is replaced by docs/hero.gif.

Behaviour changes to review in code

• src/sim/trig.ts, src/sim/simulate.ts: launch direction and initial placement use cosSin(). Audio for swarm and infinite-loop changes (it now matches their pictures); nothing else does.
• src/sim/collide.ts: reflect() and collidePair() moved out of simulate() with the same statements in the same order. The SHA-256 of the complete output and of the WAV for all 34 scenes that existed is identical before and after.
• src/scene/resolve.ts: validateScene rejects unknown fields, wrong types, unknown arena.kind and music.instrument, and durations under one frame. All 35 shipped scenes pass. A scene with a typo that used to validate now fails, which is the intent.
• src/cli/make.ts: extra flags pass through to Remotion; assignNotes() replaces one inline line.

How I checked it

• CI on the last commit, all three jobs green: typecheck and 273 tests on Node 22 and 24, and the render job (about a minute): a clip rendered on Linux and npm run parity 35 of 35 with the Linux build of Chrome Headless Shell 149.
• Fresh clone of this branch on my laptop: npm ci 12.5 s, npm run typecheck clean, npm test 270 passed (273 after the later name check), npm run make -- scenes/readme-demo.json wrote out/readme-demo.mp4 (2,934,889 bytes).
• Three full renders of that scene (Node 24 with 5 and with 2 workers, Node 22) and the fresh-clone render are byte-identical (MP4 md5 4459c552f450b5328e82542bcfc4b1d6, WAV md5 1ffb3531d42e1401a0ba9cdc7adfaa21). 60 PNG frames match across worker counts and between a range render and a full render.
• The golden record (simulation and WAV hashes of 35 scenes) was written on macOS arm64 with Node 24.5.0 and passes on Node 22.22.2 there and on Ubuntu x86_64 in CI.
• Not identical, and documented in docs/determinism.md: the same quarter-size preview rendered on macOS and on Linux differs in all 60 frames (average PSNR 44.8 dB), and the audio in an MP4 trails the WAV by 42.7 ms (two AAC frames, constant, the same with ffmpeg and CoreAudio).
• npm run dev starts Remotion Studio (HTTP 200 on a private port, then stopped).

Not checked

• The natural-language step: no model is called by any test or demo here.
• Windows, Safari and Firefox previews, Node 18 and 20.
• A listening test of the sound clip. It was never played; its level was measured (mean -19.1 dB, peak -8.8 dB).

For Matúš

• No LICENSE file added.
• origin/main is one commit ahead of the local checkout (ee33f54, 4 Sep, a README GIF). This PR replaces that GIF; pull before building on the branch.
• Decision: the MP4 audio is 42.7 ms late because of Remotion's AAC encoder. Pre-shifting the WAV by 2048 samples at 48 kHz would cancel it and change all 35 golden hashes.

🤖 Generated with Claude Code