Motion direction

How to make motion worth watching. HyperFrames is the engine: the composition contract, the CLI, GSAP adapters and the catalog are in the vendored hyperframes, hyperframes-core, hyperframes-cli and hyperframes-animation skills, and this skill does not repeat them. The storyboard comes first (storyboard); a 1-3 minute film with helpers runs through launch-film; the sound is made with sound. This is the director's judgment that sits across all of them.

Everything here is a default to weigh unless it names its evidence. The brand pack outranks it.

The one difference

A deck is a sequence of frames. A film is a sequence of frames with something crossing between them. A film is an argument with a turn, and a frame asks for at most two things at once. Everything below serves that.

1. The idea, before any code

• One sentence a stranger could repeat after one viewing. If you cannot say it, there is no film yet. Read the beats aloud as one continuous sentence: if each beat is a self-contained label, you have a deck.
• The concept gate (brand-design): a real thing shown, a specific idea, or bold type. Decorative nodes, dots and glows are never the idea.
• The hook is complete inside the first second: something on frame 0 already moving, the statement readable with the sound off. Frame 0 is also the poster. artifact-contract's --allow-blank-ends is for a fade from or to a flat ground the person asked for, never to get a blank opening past the gate.
• The turn is the one concrete thing the film pivots on, as an image: a before and after, many becoming one, the impossible made possible.
• Proof on screen: the real product surface, the real number with its source. A claim with no proof on screen is a slide.
• The final frame is big and calm: the logo or the one line, landing on a downbeat or the last word, held long enough to read.
• One motif threads the film and resolves on the last frame. Moves come from the subject: derive each move from what the product does, never from the last film's moves.

Decide early whether the film is voiceover-led (cut to the words; copy lands on or just before its word) or music-led (cut to the beat grid; something visible changes on the beats). A film with a voiceover is cut to the voiceover, not the music. Details: directing.

2. The grid: one clock for picture and sound

Write the timing down before you animate, as a named beat table at the top of the composition's script for a short piece, or as timeline.js in the project when there is a soundtrack grid or more than one file. It holds the frame rate and length, the tempo and beats (or the voiceover's word starts), the cuts, the hits, the storyboard frame times, and the holds you mean (AUDIT, below). Scenes read their times from it and never type them, so a re-time is one number.

• From a reference film or a supplied track: film-breakdown drafts it (breakdown.mjs writes timeline.draft.js; analyze-audio.mjs --js writes the grid of a track).
• From a mood: pick a tempo (cinematic around 60-80 BPM, smooth 90-110, kinetic 115-128) and fill whole bars: BPM = 240 × bars ÷ seconds.
• Holds are arithmetic: settled hold = next event start − (entrance start + entrance duration). Run it on every beat before defending the pacing; a reading hold follows reading speed (design-wiki, type on screen over time).
• AUDIT = { preset, holds: [[t0, t1, "reason"]] } declares the stillness the film means: an end card, a copy read. The preset (reel, launch, explainer, loop) says how much stillness its format expects (directing). video-score reports frozen runs and shots that never develop; a finding inside a declared hold is named in the delivery note, any other is a fix.

3. Build it in HyperFrames

• Search before you author: hyperframes catalog --query "<the move in plain words>", then hyperframes add; write by hand only when nothing fits (hyperframes-registry).
• One paused timeline per composition, seek-driven; scenes as sub-compositions mounted by a thin index.html (hyperframes-core). Elements a later move needs get stable ids, scene-prefixed (#s3-card), and a carrier that crosses scenes is unprefixed (#carrier-report) on its own track.
• One easing family per film. scripts/motion-presets.js holds the frame presets and five families (silk, snap, spring, float, pulse) with enter, exit, a seeded hash, log-space zoom and frame snapping; copy it next to the composition and load it after GSAP.
• Offline: copy GSAP and every asset next to the composition (media-production says where GSAP lives); HyperFrames examples that load from a CDN fail in the sandbox.
• Brand: tokens from /workspace/brand/tokens.css, the real logo from /workspace/brand/logos/, fonts through local @font-face (hyperframes lint requires it).

4. Sound on the same grid

Every event the eye follows gets its own designed sound on the same timeline constant; silence is a choice. With a voiceover, generate the lines first (generate_voiceover) and cut to their word timings. Mixing, levels, mastering to -14 LUFS and the audio-lint gate are sound's job; what to put where is references/sound.md.

5. Look, render, look again

The loop you run on code, run on pixels:

1. Before any render: node /workspace/tools/video-gate.mjs projects/<slug>/index.html at zero errors, node /workspace/tools/brand-lint.mjs projects/<slug>/index.html, and hyperframes check in the project folder (it lints first; a lint error turns its layout and contrast audits off). The gates take paths relative to /workspace.
2. Strips through every cut, not settled frames: hyperframes snapshot --at <t−0.06>,<t+0.10>,<t+0.28> around each boundary, tiled with review-thumb.mjs --sheet, then one look per sheet. A perfect endpoint can hide a broken journey.
3. The artifact: node /workspace/tools/video-score.mjs projects/<slug>/index.html measures what is on screen at every sample: blank or thin frames, cuts that carry nothing, shots that never develop or never rest, crops, collisions, flat hierarchy. Its six axis numbers are a reading aid, never a target.
4. A draft render with start_render_job (hyperframes render --quality draft): it outlives your turn and wakes you when it exits. Then frames from the file (film-breakdown/scripts/grab.mjs --sheet), and against a reference or the animatic, compare.mjs.
5. Review against the rubric. For anything over about 30 s, or any film you are not sure of, have a helper review it with the critic brief (launch-film/briefs/critic.md, xhigh) before delivery.
6. The final only after the person approved the preview (hyperframes-cli), then artifact-contract.mjs --expect <file>:<W>x<H>@<seconds> and audio-lint. Deliver with upload_files and one line naming the calls they would not expect.

Iterating on your own sheets and draft renders is how a film gets made, not a correction round; the two-round stop is for notes from people.

Formats

16:9 at 1920×1080 by default; 9:16 and 1:1 are re-laid out on the same grid and score, never cropped from 16:9. HyperFrames renders at 30 fps unless told otherwise; render a film that matches a reference at the reference's rate, and prefer 30 fps for long films (60 doubles the render). The aspect presets are in motion-presets.js; placement specs in design-wiki.

When something is off