motion-doctrine
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]
1How It Works & Mechanism
Positioned as a GATEWAY: Must be read before composing any HyperFrames animation—it dictates what happens at every seam and how each scene performs, while technique skills handle implementation; furthermore, these rules supersede generic/upstream motion guidance. The failure mode it prevents is "isolated per-scene authoring"—where visual momentum dies at every cut point and scenes wobble idly in place between entry and exit.
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.
The routing table decouples "decision-making" from "implementation": Seam selection/parameters/code → cut-the-curve §1–5; text entry cascades → §6; group repositioning → §7; cursor motion/scene opening/morph triggers → oversized-cursor; seam rendering mechanics/flash-of-white guard → seam-craft; product releases/explainer videos/captions → layering text-beat-economics / brand-faithful / captions-overlay on top of upstream skills.
| Cursor-led action / scene kickoff / morph ignition | `oversized-cursor` | | Seam render mechanics / white-flash guard | `seam-craft` |
Mandates a strict creation order: Author the vector ledger `ledger.json` first → STAMP primary seams with it (`seam-stamp.mjs --write index.html`) → Select a sustained motion route per phase → Establish carriers and causes → Build comps → Validate using `seam-gate.mjs`; only Tier-A morph/match cuts require manual coding, whereas stamped seams pass the gate by construction.
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.
The Four Vector Laws: ① Axis invariance (x stays x, y stays y, Z stays Z); ② Direction invariance—the Z-axis direction is the **sign** of scale change (scaling up = push-in/camera forward, scaling down = pull-out/camera backward); "a shrinking exit paired with a growing entry" is the most common violation because grow-from-small is the default entry for elements; ③ Matched speed; ④ Phase—both sides of the cut land mid-motion; stopping before the cut or starting from zero velocity post-cut are dead beats.
2. **Direction** — never mirror. On Z, direction = the SIGN of scale change: growing = push (camera forward), shrinking = pull (camera back).
Speed-matching mechanics are codified into the law: Initial entry velocity ≈ terminal exit velocity, using mirrored eases (exit `power4.in` + entry `power4.out`, identical travel distance and duration, with the entry picking up at ≥50% along the hypothetical path); concrete mechanics reside in cut-the-curve.
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`.
The Current: Select a single dominant direction per film (house default is LEFT), applied to all ordinary seams; alternative vectors are reserved and make a statement when used—UP = elevation (conclusions/reveals rising higher), +Z = driving deeper into the same thought, -Z = arrival (something larger landing), scale burst = exiting a world. Consecutive reverse seams are banned (ping-ponging reads as an error), and direction changes require an observable cause (click/bounce/impact) or a chapter boundary.
Every film picks ONE dominant direction (house default: LEFT). Every ordinary seam uses it. Other vectors are RESERVED — spending one means something:
The Vector Ledger must be formalized in the project root as `ledger.json` before writing the master timeline, containing one row per seam: cut timestamp, exit and entry vectors (axis + signed direction, with scale signs for Z rows), selectors, and technique; entries and exits must match, and mismatched rows require amending the plan rather than tweaking easings; the verifier runs static row consistency checks before runtime sampling.
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.
Carriers and Causal Motion: The eye tracks objects rather than abstract spaces; the strongest seams pass a concrete carrier across the cut point with matched position and velocity (a cursor mid-path, a container docking/shrinking into the next layout, a token snapping into an exact slot, a word cluster in a waterfall cut); fallback to the scene's focal subject if no natural carrier exists; never use crossfade—it lacks a carrier entirely. Motion must form causal chains (click → squeeze → snap-release → fly-out → impact → recoil → reveal), effects must fire ON the causing frame, reactions scale by implicit mass, and physical force is the sole license to change direction.
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.
The Seam Gate acts as a build gate: Generate first (`seam-stamp.mjs --ledger ledger.json --write index.html`), then verify (`seam-gate.mjs verify --ledger ledger.json --project .`) with the rule "exit 0 or the seam is not done"; inspection items include ledger row consistency, exit still moving at the cut point, entry mid-motion (never starting from zero velocity), measured direction matching ledger direction, exit/entry speed match (WARN), zero overlap (only one side visible per frame—cuts are not dissolves), Z scale-sign rule (matching d(scale)/dt signs on both sides, while scanning for sign conflicts within the entering scene itself), and carrier bounding-box continuity (factoring in ancestor transforms).
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
Rules outside script verification remain the author's responsibility: ① Any edit to the first/last ~1s of a scene (including retiming to fit updated voiceover) invalidates prior boundary audits and requires re-running the verifier; ② Audio is the master clock—scenes must be retimed against real voiceover word timestamps and never rushed to fit fixed slots, as voiceover regeneration invalidates its seam; ③ The clip-gating trap (a common cause of zero-overlap FAILs)—clips whose `data-start` precedes the entry tween get unhidden at initial opacity, requiring `autoAlpha: 0` alongside setting `data-start` precisely to the cut timestamp.
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 two governs "Performance": Banning idle sine-wave loops (breathe/float/drift/glow pulse) disguised as continuous motion—they read as "the video is stalling"; leftover unchoreographed seconds after an entry finishes indicate planning flaws, requiring narrative progression rather than decorative wobbling. Every phase between entry and exit must follow one of five named routes specified in the plan (Staged Reveal / Intentional Camera / Sequenced UI Life / Animated Sequences / Cursor-Led Action); Self-check rule: pause at any second, and something meaningful must be mid-flight.
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.
Stillness before climax and timing intent: Insert a 0.3–0.75s pause (a dramatic comma) between a primary action and its consequence, as firing results immediately loses narrative impact; single-element entry ≤ ~800ms (longer build-ups must use staggered multi-element entrances rather than dragging out a single element); exit duration ≈ 75% of entry (exception: cut-the-curve reverses this, with entry at ~127% of exit); total stagger ≤ 500ms, tightening individual delays when handling 8+ elements; ease curves `bounce.out` and `elastic.out` are banned (entry overshoot `back.out(1.4–1.7)` permitted); homogeneous elements share a unified ease + duration intent rather than per-element custom configs.
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.
Transition vocabulary budget: Limit to 2–3 inter-scene transitions per video and reuse them consistently; the default boundary is "cut-the-curve along The Current"; manually authored shared-element morphs (`intent: morph`) do not count against this budget.
Use only 2–3 inter-scene transitions per film and repeat them; the default boundary is **cut-the-curve in the current's direction**.
Anti-pattern table compiles the aforementioned bans into an 11-row checklist (isolated entry authoring → author the ledger first; scene crossfades → cut-the-curve along The Current; switching scenes post-exit completion → cut mid-motion on both sides; starting from zero post-cut → enter at ≥50% along the path; Z-sign conflict → match signs per Seam Gate 7; pop-ins within entering scene → keep initial frame pre-composed or match signs; idle wobble padding → assign a continuous motion route or add story beats; uncaused direction reversal → expend a physical force; using reserved vectors for variation → follow The Current by default; reactions lagging causes by frames → trigger on the same frame; direct action-to-result link → insert stillness before climax).
| Inverse-zoom exit → grow-from-small entry (or push → oversized retraction) | Match the scale-velocity sign (Seam Gate 7) |
2Core Capabilities
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（preview 子命令；seam-gate 优先用仓库内 packages/cli/bin/hyperframes.mjs，skill 被复制出仓时才回退 npx --yes hyperframes） |
| package | chrome-headless-shell（经原始 CDP 驱动做帧采样；自动探测 CHROME_PATH → ~/.cache/puppeteer → 系统 Chrome） |
| network | 本地预览服务 HTTP 接口（仅 localhost：/api/projects 与 comp 预览页；非外网） |
| package | 兄弟 skill 依赖（被指名路由）：cut-the-curve、oversized-cursor、seam-craft，以及上游的 text-beat-economics / brand-faithful / captions-overlay |
| package | node ≥ 22（脚本头注明零 npm 依赖，仅用 node 内置模块 + 本机 Chrome） |
4Recommended Governance & Evidence
- scripts/: Executes local scripts or commands: node scripts/seam-stamp.mjs --ledger ledger.json [--write index.html] (reads ledger; -
- 外部 API: Performs external publishing, resource creation, or modification writes
- 环境变量 / API Key: Reads provider service keys: process.env.CHROME_PATH (used strictly to resolve the Chrome executable path, not a credential)
- 本地工作目录: File I/O and artifact generation: seam-stamp.mjs --write <target>: writes generated seam code back to index.html (via writeFileSync, single-file, reversible,
5Second-Pass Verification
- [ok] 是否存在被忽略的第三方数据外发（判蓝的关键反证点） — 对两脚本做 https?:// 全扫：seam-gate.mjs 命中 2 处，均为 `http://localhost:...`（注释示例与端口拼接）；seam-stamp.mjs 零命中。fetch 仅 2 处（httpOk 探活、/api/projects 取项目 id），目标都是 localhost。未发现任何远端域名、遥测、上报或 CDN 请求。判蓝成立。
- [ok] 凭证读取面（是否碰 KEY/TOKEN/cookie） — process.env 使用点只有 `process.env.CHROME_PATH`（渲染器路径）与 `const env = { ...process.env }` 后 delete HYPERFRAME_RUNTIME_URL 的整环境传递。全脚本无 GEMINI/OPENAI/AWS/HeyGen 等 key 名，无 keychain/.env 读取。判蓝（而非橙）成立。
- [ok] 写盘范围（是否可能误写用户仓库其他文件） — seam-stamp.mjs 只 writeFileSync(target, html)，target 来自 --write 参数（实践为 index.html），替换范围被 `// <seams:auto>` 标记限定；seam-gate.mjs 只读。无 rm/mkdir/unlink。风险为客户项目内的定点改写。
- [ok] 子进程与清理（是否留下孤儿进程或提权） — 预览服务以 detached: true spawn，并在 process.on('exit') 里 `process.kill(-child.pid, "SIGTERM")` 按进程组回收；SIGINT/SIGTERM 处理器以 exit 130 退出；chrome 子进程同样 detached 并在清理里 SIGKILL 进程组。未见 sudo/提权，未见沙箱或权限模式相关危险开关。
- [ok] SKILL.md 声称的闸门语义是否真由脚本实现（防吹牛） — SKILL.md 列出 8 类被强制的检查；references/seam-gate.md 给出「检查行 ↔ 规则」对照表；seam-gate.mjs 内可见 EPS_XY=15 / EPS_Z=0.04 / SPEED_RATIO=3 / CARRIER_POS_TOL=12 / CARRIER_SIZE_TOL=0.05 等阈值常量，与文档中「12px 中心 / 5% 尺寸容差」「速度比 >3 报警」一致。声称有实现支撑。
- [ok] 「盖章即合规」是否只是宣传语 — seam-stamp.mjs 从 ledger 生成基础态（首个场景 autoAlpha:1，其余 autoAlpha:0 且归零 transform）与逐缝 wrapper tween，并把 Z 入场按 dir 预设 scale（dir=-1 → 1.25 超大抵达；否则 0.78 从小到大），与接缝检查要求的方向/符号一致——生成端确实按构造满足被检查字段。仍有手写项（match-cut/morph 只给可见性集，载体交接手写），与 SKILL.md 自述一致。
- [unlocatable] prompt/内容注入面 — seam-gate 的 `--server-cmd` 允许调用者替换实际执行的 shell 命令（默认值安全）。是否存在其他调用方把外部输入拼进该参数，超出本 skill 目录范围（pin 内其他 skill 的调用点未逐一追查），故不在此断言；仅记录该开关的存在与其默认值。
6Verdict & Scenarios
9280ac3792a44afd…