motion-lab
Make code-first motion (an animation that is a program, rendered frame by frame in a headless browser) look directed instead of generic, and check that sampled frames re-render identically. Ships the
SKILL.mdskills/video/motion-lab/SKILL.md
GitHubmotion-lab — directed, reproducible code-first motion
An LLM does not output pixels for an animation. It writes a program that draws each frame, and a headless browser records the frames. Three properties follow, and this skill is built to keep them:
- A frame is reproducible. Frame 84 rendered twice is the same image twice.
- An edit is cheap. Change one number and re-render. Nothing is re-rolled.
- The agent can check its own work. It reads stills and a contact sheet, and writes notes against frame numbers.
The one rule
Adjectives get defaults. Numbers get direction.
The generic look is what the model produces where the prompt left a value open. "Premium", "cool" and "modern" decide nothing, so the model decides for you: dark navy space, glow, bloom, particles, a spinning turntable. Every adjective you replace with a number is a decision you take back.
Pipeline
Pick the engine and the canvas first. Changing the canvas later means re-directing every shot.
Piece Engine one idea, under 10 s, 2D plain HTML + CSS / Canvas / SVG a series, a template, data-driven Remotion (load the remotionskill)thinks in web pages and GSAP timelines HyperFrames anything 3D three.js (pin the version: three@0.160.0)Sizes: 1920x1080 (16:9), 1080x1080 (1:1, safest in the feed), 1080x1350 (4:5), 1080x1920 (9:16).
Write the directed prompt. Fill every line of
assets/prompt-template.md: GOAL, OUTPUT, TIME, LOOK, MOTION, SHOTS, BANNED, QA. Paste the render contract (below) under it. Get every number fromreferences/motion-numbers.mdor compute it:python3 scripts/motion_math.py frames --seconds 6 --fps 60 --bpm 120 # 360 frames, loop closes on the music python3 scripts/motion_math.py beats --fps 30 --bpm 128 --count 32 # beat frames, rounded per beat python3 scripts/motion_math.py damping --stiffness 100 --damping 10 # zeta 0.5: playful python3 scripts/motion_math.py hold --words 2 --fps 24 # 27 frames minimumHand the model
assets/motion.jswith the line "use only these tokens, no inline numbers". It holds the easing curves, the durations, the stagger and a closed-form spring that needs no simulation, so frame 84 renders without computing frames 0 to 83.Lint before rendering. The static half of the contract:
python3 scripts/motion_lint.py anim.html # exit 1 on any ERRORRule Catches Level MC01 Date.now,Date(),new Date,performance.now,requestAnimationFrame, three.jssetAnimationLoop/Clock/getElapsedTime/getDelta,gsap.ticker.add,document.timelineERROR; a WARN when renderAtexists and a?t=guard appears to wrap the loop, and always ERROR insiderenderAtitself. The static guard check is a heuristic:render.mjsdecides at runtime (exit 7)MC02 setTimeout/setIntervalERROR MC03 Math.random(also aliased:const r = Math.random,Math["random"],const {random} = Math),getRandomValues,randomUUID, three.jsMathUtils.randFloat/randInt/randFloatSpreadERROR MC04 JS-driven motion (rAF, timers, three.js, GSAP; a canvas painted once does not count) with no window.renderAt(t), or arenderAtthe renderer cannot reach (aconst/let, or declared inside atype="module"script)ERROR MC05 a CSS transition with a non-zero duration, in CSS, a style=""attribute or set from JSERROR MC06 fetch/ XHR / WebSocket, or a loaded remote URL (src/href/poster/data/srcset quoted or not, SVG<image>,<object>,<embed>, importmap,url()in CSS or astyle=""attribute,@import, a JS import,.src =,.load(),new URL(), a JS string naming a loadable file) that is not a font host and not pinned toMAJOR.MINOR.PATCH. Any other remote URL in a JS string is a WARN; the SVG namespace is never checkedERROR MC07 a local src/href(not one self-contained file)WARN MC08 web fonts with no document.fonts.readywaitWARN MC09 @keyframesanimating width / height / top / leftWARN MC10 something on its own clock: GSAP with no paused timeline or seek, an autoplaying <video>/<audio>WARN It also lints code outside
<script>: inlineon*event handlers andsrcdocdocuments. It lints a bare.js/.tsxmodule (a Remotion component) too, where MC04 does not apply but MC01–MC03 and MC06 do. Font hosts are matched by exact hostname.Render stills, a contact sheet, and verify purity. From a project with Playwright installed (
npm i -D playwright && npx playwright install chromium):node scripts/render.mjs anim.html --seconds 6 --fps 24 --width 1080 --height 1080 --verifyIt writes
out/frames/0000.png…for frames 0..N-1,out/contact.png(up to 12 frames labelled with their numbers), andout/manifest.json. For each frame the renderer first seeks its animations (document.getAnimations()) and the SVG SMIL timelines (<animate>is not ingetAnimations()), then callsrenderAt(t)last, sorenderAtwins for anything it sets itself. Which animations are the page's is tested, not guessed: during the warm-up the renderer callsrenderAtat every frame time (no screenshots), and a paused animation whose timingrenderAtchanged between consecutive calls is driven by it (a scrub through a negativeanimation-delay, a WAAPI animation it positions, even one that starts late in the timeline) and is left alone (driven_by.page_owned). Every other animation is seeked to t, including CSS the page froze under?t=and animations inside open shadow roots.--verifyreloads the page and re-renders the first, middle and last frames; if any byte differs, a frame is not a pure function of t. This catches what the linter cannot, such as arenderAtthat reads a counter.--verify-allre-renders every frame, in reverse order: arenderAtthat depends on its call history replays identically when frames come in the same order, so an in-order check passes it. The manifest records the scope (sampled 3 of N framesorall N frames); if the check could not finish (a timeout),verify.pureisnulland the run exits 5.--every Nputs every Nth frame on the contact sheet and always ends it on frame N-1, the seam. Add--mp4for an H.264 file (needs ffmpeg).Exit Meaning 0 rendered 2 usage or runtime error (including a duration that rounds to zero frames) 3 --verifyfound an impure frame (listed in the manifest), or the frames change although nothing the renderer seeks drives them (motion on its own clock)4 --mp4failed5 the page threw, or a renderAtcall did not finish within 30 s (page_errorsin the manifest;MOTION_LAB_FRAME_TIMEOUT_MSoverrides)6 nothing drives motion, so every frame is the same image ( --allow-staticfor a still)7 a frozen frame keeps changing on its own: something still draws while the page is frozen at t(a preview loop its?t=guard does not stop, a timer chain, a worker, a transitionrenderAtstarts)When several apply, one code is reported by precedence 3 > 5 > 7 > 6 > 4 (
manifest.exit_code); the manifest lists every finding.Exit 7 is a drift check, not a code reading: the renderer seeks a frame, screenshots it, waits 250 ms, and screenshots again (
manifest.drift). It does this once right after load (catching an intro that plays for a while and then stops) and at frames 0, N/2 and N-1 after the render. A pixel that changes while frozen is what corrupts a render, and the check sees it however the loop is written:requestAnimationFrame, three.jssetAnimationLoop, asetTimeoutchain, a worker. A paused GSAP timeline keeps its ticker running but draws nothing, so it passes. A loop that only redraws slower than 250 ms can slip past;--verify-allis the backstop, and the manifest says so when the page scheduled frames but nothing drifted.manifest.loop_probestill counts the page'srequestAnimationFrameandsetIntervalcalls, as a diagnostic. ArenderAtthat throws for sometis recorded inpage_errors(exit 5) and the render continues; one that times out, in the warm-up or in any frame, stops the render there (aborted_at_frame), since a hung page hangs every later frame too, and the manifest is still written. Earliercontact.png,anim.mp4andmanifest.jsonin--outare removed first, so an aborted run never leaves a previous run's outputs looking current.The input is treated as untrusted: a
file://request is served only when it is a regular file whose real path (symlinks resolved) lies inside the real input file's directory, with no path segment below it starting with a dot (.env,.git). Directory URLs and everything else are blocked and listed inmanifest.blocked_requests. A symlinked input renders from its target's directory. Aframes/directory in--outthat is a symlink is refused before anything is deleted. Other files in that directory remain readable by the page, so render untrusted HTML from a directory that holds only its assets. OnlyNNNN.pngfiles are removed fromout/frames/before a render, and only after Playwright has loaded.Look, then fix with frame numbers. Read
contact.pngfirst, then only the frames a note needs. Write notes as numbers, never feelings:The note you have The note you send "make it pop" scale 1.0 → 1.08 → 1.0 over 6 frames, peak on the beat "make it feel premium" ease-out-quint entrances, springs at zeta 0.8, no overshoot on text "it drags" shorten each hold by one beat (12 frames at 120 BPM, 24 fps) "it feels busy" one hero move at a time; the rest start 150 ms later at 60% of its travel "it looks like AI" name every default it used, add each to BANNED, render again Send one or two notes per round; seven at once turns a fix into a rewrite. Two to four rounds is normal. If a fix does not hold, render the frames on either side of the problem and list every difference. More prompts that work are in
references/fixes.md.Sound (optional), measured not heard. The model cannot listen. Score from frame numbers, synthesize in code (Web Audio), land each hit 1 frame after its picture, mix to −14 LUFS with peaks at −1 dBTP, then check each hit by decoding the finished MP4. The picture must work muted first: the feed autoplays silent.
Export and check. Commands are in
references/motion-numbers.md. Then measure the GIF rather than trusting the encoder:python3 scripts/motion_math.py gif-check out/anim.gif --fps 24A GIF stores delays in hundredths of a second, so 24 fps (41.67 ms) cannot be stored exactly. An encoder that rounds every frame to 4 cs runs 4% fast and falls off the beat grid. ffmpeg 8.1 (macOS) and 6.1.1 (Ubuntu CI) were both measured alternating 4 and 5 cs and holding a 144-frame loop at exactly 6.00 s; the integration test
test_ffmpeg_gif_export_keeps_exact_loop_timingre-measures whatever ffmpeg is installed, so the claim is checked rather than remembered. Other encoders may differ.gif-delaysprints the exact schedule.
The render contract
Paste it under every motion prompt. Each line closes one way a render goes wrong.
Output one self-contained HTML file. Only the libraries the prompt names, pinned to a version.
No network requests except fonts and those pinned libraries.
Every frame must be a pure function of time t, in seconds.
If JavaScript drives any motion, expose window.renderAt(t) that draws exactly that frame.
With ?t= in the URL, draw that frame and never start requestAnimationFrame.
Animate with CSS keyframes, the Web Animations API, SVG, Canvas 2D or WebGL. No CSS transitions.
No Date.now, no setTimeout or setInterval starts, no unseeded Math.random.
Loops: render frames 0 to N-1 only, and frame N-1 must flow into frame 0.
If the page needs time to load (fonts, textures), set window.__ready = true when done.
When a fix works, add its line to the contract. The contract is the memory: every line is a failure you never have to see again.
The ban list
Start from this, then grow it after every first render by naming what the model used anyway:
- purple or blue gradients, glow, lens flares, bloom, neon
- floating particles as decoration
- dark void backgrounds (unless the brief asks for one)
- everything fading in at once; fade-and-slide-up on every element
- centered-everything layouts
- text that moves while it is being read
- spinning turntables
One hero move per shot. Secondary moves travel 50–70% as far and start 100–200 ms later. Ambient motion stays under 5% of the hero's travel.
What the gates cannot see
- The linter is static. It cannot tell whether
renderAtreads onlyt, whether a seeded generator is reseeded per frame, or a clock reached through an alias it does not know.render.mjs --verifyis the runtime check, and it samples three frames in one session, not all of them. A clock that changes slower than the verify window (the minute of the hour, say) passes both gates. - The linter scans JavaScript with a small tokenizer, not a parser. A regex literal
that contains a quote or a backtick (
s.replace(/`/g, "'")) can hide the code after it; the runtime checks still see what that code does. - The warm-up that keeps frame 0 pure guards a compositor race seen on macOS Chromium (24 of 25 cold runs failed without it). Ubuntu CI's headless Chromium never shows the race, so its mutation runs only on macOS.
--verifycompares bytes. WebGL on a different GPU or driver can differ by a few pixels between machines. Verify on the machine that renders.- Neither tool judges taste. The contact sheet and the frame-numbered notes are where judgment happens.
Composition
| With | How |
|---|---|
remotion / remotion-best-practices |
the engine for series and data-driven video; lint its components in module mode |
launch-video |
a Remotion recipe with a fixed Liquid Glass look (dark void, glow, particles). Those are on this ban list: use launch-video when that look is the brief, and this skill when the brief is your own direction |
adaptive-video-ingest (via checkit) |
the same contact-sheet instrument, used to read video rather than grade your own |
| Claude Motion (claude.ai artifact) | the hosted version of this paradigm; this skill is the in-harness path |
Tests
python3 -m pytest tests/ -q # lint + math (render tests skip without playwright)
MOTION_LAB_NODE_DIR=/path/with/playwright python3 -m pytest tests/ -q # + end-to-end render tests
python3 tests/mutation_proof.py # each listed mechanism has a test that fails without it
Provenance
Method, numbers and the render contract distilled from Florence (@flxrnc),
"Opus 5.5 Motion Lab: Make Claude Animate Like a Studio" (X Article, 2026-09-30,
https://x.com/flxrnc/status/2105311836190978392), assessed in the broomva
workspace note research/notes/2026-10-15-opus-motion-lab-render-contract-raw.md.
The linter, renderer changes (?t=0 load, animation warm-up, SMIL seeking,
--verify, exit codes, labelled sheet) and the GIF timing measurement are this
skill's own. BRO-3117.