motion-doctrine

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

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:

• 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 rebound slower, small ones snap.
• A force is a license to change direction; an uncaused flip is a ping-pong.

The Seam Gate (build gate — run the verifier, exit 0 or the seam is not done)

node <SKILL_DIR>/scripts/seam-stamp.mjs --ledger ledger.json --write index.html  # generate
node <SKILL_DIR>/scripts/seam-gate.mjs  verify --ledger ledger.json --project .  # verify

The script (usage + ledger schema: references/seam-gate.md) numerically enforces, per seam: ledger-row consistency, exit still moving at the cut, entry mid-flight (never from rest), measured direction = ledger direction, entry/exit speed match (WARN), zero overlap (one side visible per frame — the cut is not a dissolve), the Z sign rule (d(scale)/dt same sign both sides; the incoming scene's own entrances are scanned for sign-fighting), and carrier rect continuity with ancestor scale included. Use seam-gate.mjs probe --t <cut> to find each seam's true carrier selectors when authoring the ledger.

Rules the script cannot check — still yours:

1. Edits re-open the seam. Any change to a scene's first/last ~1s (including re-timing to new VO) invalidates that boundary's audit — re-run the verifier.
2. Audio is the clock. Re-time scenes to the VO's real word timestamps; never rush a read to fit a slot. A VO regen re-opens its seams.
3. Clip-gating gotcha (the usual cause of a zero-overlap FAIL): a clip whose data-start precedes its entry tween is un-hidden at its initial opacity — set initial autoAlpha: 0 AND data-start = the cut time, never earlier.

Part 2 — Performance (the scene keeps performing)

No idle wobble

Idle sine loops (breathe, float, drift, glow pulse) are BANNED as sustained motion — they read as "the video is waiting." A scene that finishes entering with seconds left is a planning bug: add story, not wobble. Every phase between entry and exit is owned by one of these routes (name the route in the plan):

Test: pause at any second — something meaningful must be mid-flight (a reveal landing, the camera traveling, the UI doing what the narration says).

Stillness before climax

Schedule a 0.3–0.75s pause between the major action and its result — the dramatic comma. A scene that jumps straight from action to result loses it.

Timing intents

• Single entry ≤ ~800ms; longer buildup = multi-element stagger, not one slow element.
• Exit ≈ 75% of entry. Exception: cut-the-curve inverts this (entry ~127% of exit).
• Total stagger ≤ 500ms; with 8+ elements, tighten per-item delay or stagger the first few.
• Forbidden eases: bounce.out / elastic.out. Entry overshoot back.out(1.4–1.7) is fine.
• Similar elements share one ease+duration intent — never a unique pair per element.

Transition vocabulary

Use only 2–3 inter-scene transitions per film and repeat them; the default boundary is cut-the-curve in the current's direction. Hand-written shared-element morphs (intent: morph) don't count against the budget.

Anti-Patterns