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.md

GitHub

motion-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:

  1. A frame is reproducible. Frame 84 rendered twice is the same image twice.
  2. An edit is cheap. Change one number and re-render. Nothing is re-rolled.
  3. 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

  1. 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 remotion skill)
    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).

  2. 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 from references/motion-numbers.md or 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 minimum
    

    Hand the model assets/motion.js with 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.

  3. Lint before rendering. The static half of the contract:

    python3 scripts/motion_lint.py anim.html            # exit 1 on any ERROR
    
    Rule Catches Level
    MC01 Date.now, Date(), new Date, performance.now, requestAnimationFrame, three.js setAnimationLoop / Clock / getElapsedTime / getDelta, gsap.ticker.add, document.timeline ERROR; a WARN when renderAt exists and a ?t= guard appears to wrap the loop, and always ERROR inside renderAt itself. The static guard check is a heuristic: render.mjs decides at runtime (exit 7)
    MC02 setTimeout / setInterval ERROR
    MC03 Math.random (also aliased: const r = Math.random, Math["random"], const {random} = Math), getRandomValues, randomUUID, three.js MathUtils.randFloat/randInt/randFloatSpread ERROR
    MC04 JS-driven motion (rAF, timers, three.js, GSAP; a canvas painted once does not count) with no window.renderAt(t), or a renderAt the renderer cannot reach (a const/let, or declared inside a type="module" script) ERROR
    MC05 a CSS transition with a non-zero duration, in CSS, a style="" attribute or set from JS ERROR
    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 a style="" 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 to MAJOR.MINOR.PATCH. Any other remote URL in a JS string is a WARN; the SVG namespace is never checked ERROR
    MC07 a local src/href (not one self-contained file) WARN
    MC08 web fonts with no document.fonts.ready wait WARN
    MC09 @keyframes animating width / height / top / left WARN
    MC10 something on its own clock: GSAP with no paused timeline or seek, an autoplaying <video>/<audio> WARN

    It also lints code outside <script>: inline on* event handlers and srcdoc documents. It lints a bare .js / .tsx module (a Remotion component) too, where MC04 does not apply but MC01–MC03 and MC06 do. Font hosts are matched by exact hostname.

  4. 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 --verify
    

    It writes out/frames/0000.png… for frames 0..N-1, out/contact.png (up to 12 frames labelled with their numbers), and out/manifest.json. For each frame the renderer first seeks its animations (document.getAnimations()) and the SVG SMIL timelines (<animate> is not in getAnimations()), then calls renderAt(t) last, so renderAt wins for anything it sets itself. Which animations are the page's is tested, not guessed: during the warm-up the renderer calls renderAt at every frame time (no screenshots), and a paused animation whose timing renderAt changed between consecutive calls is driven by it (a scrub through a negative animation-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. --verify reloads 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 a renderAt that reads a counter. --verify-all re-renders every frame, in reverse order: a renderAt that 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 frames or all N frames); if the check could not finish (a timeout), verify.pure is null and the run exits 5. --every N puts every Nth frame on the contact sheet and always ends it on frame N-1, the seam. Add --mp4 for an H.264 file (needs ffmpeg).

    Exit Meaning
    0 rendered
    2 usage or runtime error (including a duration that rounds to zero frames)
    3 --verify found an impure frame (listed in the manifest), or the frames change although nothing the renderer seeks drives them (motion on its own clock)
    4 --mp4 failed
    5 the page threw, or a renderAt call did not finish within 30 s (page_errors in the manifest; MOTION_LAB_FRAME_TIMEOUT_MS overrides)
    6 nothing drives motion, so every frame is the same image (--allow-static for 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 transition renderAt starts)

    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.js setAnimationLoop, a setTimeout chain, 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-all is the backstop, and the manifest says so when the page scheduled frames but nothing drifted. manifest.loop_probe still counts the page's requestAnimationFrame and setInterval calls, as a diagnostic. A renderAt that throws for some t is recorded in page_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. Earlier contact.png, anim.mp4 and manifest.json in --out are 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 in manifest.blocked_requests. A symlinked input renders from its target's directory. A frames/ directory in --out that 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. Only NNNN.png files are removed from out/frames/ before a render, and only after Playwright has loaded.

  5. Look, then fix with frame numbers. Read contact.png first, 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.

  6. 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.

  7. 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 24
    

    A 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_timing re-measures whatever ffmpeg is installed, so the claim is checked rather than remembered. Other encoders may differ. gif-delays prints 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 renderAt reads only t, whether a seeded generator is reseeded per frame, or a clock reached through an alias it does not know. render.mjs --verify is 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.
  • --verify compares 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.