/motion-doctrine

name: motion-doctrine
description: "GATEWAY — load FIRST before composing any HyperFrames animation or video. The high-level motion law that makes a multi-scene video feel like ONE continuous camera move instead of a stack of independently-animated slides. Covers the vector law (how you exit determines how you enter, incl. the Z scale-sign rule), the film's current, carrier elements, causal motion, the Seam Gate (build-gate enforcement), the ban on idle wobble (motion must PERFORM, not breathe), stillness-before-climax, and the sustained-motion routes. Routes to the low-level technique skills (cut-the-curve — the full catalog incl. waterfall entry + nudge curve, oversized-cursor, seam-craft). These rules SUPERSEDE generic / upstream motion guidance. [continuity, direction, vector, momentum, seam, transition, ease, performance, idle-motion, narrative-motion, film-grammar]"

Motion Doctrine (Gateway)

Read this before composing any animation. It decides WHAT happens at every seam and how every scene performs; the technique skills implement it. These rules supersede generic / upstream motion guidance. The failure this prevents: scenes authored in isolation — the eye's momentum dies at every cut, and scenes wobble in place between entry and exit.

Route map

| Decision (this skill) | Implementation skill | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Seam transition choice + parameters + code | `cut-the-curve` §1–5 (the catalog) | | Text / element entry cascades | `cut-the-curve` §6 (waterfall entry) | | In-scene group repositioning (no cut) | `cut-the-curve` §7 (nudge curve) | | Cursor-led action / scene kickoff / morph ignition | `oversized-cursor` | | Seam render mechanics / white-flash guard | `seam-craft` | | Product-launch / explainer / caption work | overlays `text-beat-economics`, `brand-faithful`, `captions-overlay` on top of the upstream skill |

Authoring order: **vector ledger (`ledger.json`) → STAMP the master seams from it (`scripts/seam-stamp.mjs --ledger ledger.json --write index.html`) → sustained-motion route per phase → carriers and causes → build comps → VERIFY (`scripts/seam-gate.mjs`).** Hand-author only Tier-A morphs/match-cuts; stamped seams pass the gate by construction.

---

Part 1 — The Seam Law

The Vector Law

> How Scene A exits determines how Scene B enters: same axis, same direction, matched > speed, cut mid-motion on both sides.

1. **Axis** — x stays x, y stays y, Z stays Z. Never trade axes across a cut. 2. **Direction** — never mirror. On Z, direction = the SIGN of scale change: growing = push (camera forward), shrinking = pull (camera back). A receding exit answered by a grow-from-small entry is a mirrored vector — the most common violation, because grow-from-small is the default element entrance. 3. **Speed** — entry initial velocity ≈ exit final velocity, via mirrored eases (exit `power4.in` + entry `power4.out`, same distance and duration; the incoming side picks up ≥50% through the notional path). Mechanics in `cut-the-curve`. 4. **Phase** — the cut lands mid-motion on BOTH sides. Settling to rest before the cut, or starting from rest after it, is a dead beat.

The Current

Every film picks ONE dominant direction (house default: LEFT). Every ordinary seam uses it. Other vectors are RESERVED — spending one means something:

| Vector | Meaning | | ------------------------- | --------------------------------------------------------------- | | The current (LEFT) | "next beat" — neutral forward progress | | Upward | elevation — a conclusion or reveal rises above what came before | | Z forward (zoom-through) | pushing deeper into the same thought | | Z backward (inverse zoom) | ARRIVAL — something bigger lands | | Scale-burst (explode out) | leaving a world — a surface blasts past camera |

• Never run consecutive seams in opposing directions — ping-pong reads as an error.
• A direction change needs a visible cause (click / bounce / impact) or a chapter boundary.

The Vector Ledger

Write it before authoring any master timeline — as **`ledger.json` at the project root** (schema: `references/seam-gate.md`). One row per seam: cut time, exit and entry vectors (axis + signed direction; Z rows carry the scale sign), selectors, technique. Exit and entry must match; if a row mismatches, fix the plan, not the easing. The verifier checks row consistency statically before any runtime sampling.

Carriers

The eye follows objects, not abstractions. The strongest seams hand a concrete carrier across the cut at matched position AND velocity: a cursor mid-path, a container that shrinks/docks into the next layout, a mark that flies into its exact slot, the word group of a waterfall cut. With no natural carrier, the scene heroes carry it (partial travel + early fade, entry mid-flight). Never a crossfade — it has no carrier at all.

Causal Motion

Chain motion so each move is visibly launched by the last: click → squash → release spring → flight → impact → recoil → reveal.

• Effects start ON the causing frame — same timeline position, never "shortly after."
• Reactions scale with implied mass: big elements re