feat(cli): motion command — surface GSAP motion + 3D onion-skin --shot by miguel-heygen · Pull Request #1603 · heygen-com/hyperframes

miguel-heygen · 2026-06-19T23:44:19Z

Problem

The PR originally introduced the motion-surfacing tool as hyperframes keyframes, but the intended product/skill name is now motion. Leaving the command, implementation files, and skill package named keyframes makes the public CLI surface feel narrower than what the tool actually does: inspect, debug, and improve rendered motion.

What this fixes

Exposes the CLI as npx hyperframes motion.
Renames the command implementation from keyframes*.ts to motion*.ts while preserving the keyframe data model inside the command where that term is still accurate.
Renames the shipped skill from hyperframes-keyframes to hyperframes-motion.
Expands the skill from a command reference into a motion-design workflow: reading motion, 3D angle verification, layered GSAP motion, one-shot reference reproduction, diagnostic checks, and eval-derived craft guidance.

Root cause

The original command name described one implementation detail: surfacing GSAP keyframes. The tool has grown into a broader motion-debugging loop with onion-skin screenshots, true-3D sampling, composed ancestor motion, multi-stroke traces, and motion-design critique. The source layout and skill name needed to match that broader behavior.

Verification

Local checks

git diff --cached --check
bunx oxfmt --check packages/cli/src/cli.ts packages/cli/src/commands/motion.ts packages/cli/src/commands/motion.test.ts packages/cli/src/commands/motionShot.ts packages/cli/src/commands/motionShotLayout.ts packages/cli/src/commands/motionShotLayout.test.ts
bunx oxlint packages/cli/src/cli.ts packages/cli/src/commands/motion.ts packages/cli/src/commands/motion.test.ts packages/cli/src/commands/motionShot.ts packages/cli/src/commands/motionShotLayout.ts packages/cli/src/commands/motionShotLayout.test.ts
bun run lint:skills
bun run test -- src/commands/motion.test.ts src/commands/motionShotLayout.test.ts from packages/cli (22 tests passed)
bun run typecheck from packages/cli
bun packages/cli/src/cli.ts motion --help

Pre-commit also ran lint, format, fallow, and typecheck successfully for the committed changes.

Browser verification

No browser app flow is affected by this CLI/skill rename. The user-visible smoke path is the CLI help output for hyperframes motion, verified locally.

Notes

The branch name is still feat/keyframes-cli; the PR title/body and code now use the motion product name.
Unrelated local package.json, bun.lock, and shots/ changes were left unstaged and were not pushed.

…shot Read-then-edit-source tool for GSAP motion. Surfaces every tween's keyframes as data; --shot renders a true-3D onion-skin of the real element (samples the live timeline at N steps; rotation/scale/opacity/colour/3D, not just x/y) for visual self-verify. Multi-stroke pen-up traces for holed/detached shapes. Framing: --layout strip (filmstrip), --from/--to (time window), --no-fit, --angle (orbit camera). Pure geometry+SVG in keyframesShotLayout.ts (unit-tested). Ships the hyperframes-keyframes skill. Depends only on what's already in main.

One viewpoint hides depth — a flip reads as a static stack head-on, a tumble looks flat. Mandate ≥3 angles (front+top+side/iso) for any 3D motion, and --layout strip for in-place/overlapping motion.

…t-write-wins) When a brief has channels independent in phase or rate (orbit + axial spin, path + flap, bounce + roll), layer them across nested elements (parent=trajectory, child=secondary) instead of cramming one tween; --shot --selector the leaf shows the composition.

…ent fix)

A nested child's rendered motion is composed with its animated ancestors, but the per-element text/JSON surface showed only the child's own tween — hiding a parent's path (a judge/agent reading text would miss it). Now each tween is annotated with its animated DOM ancestors and their motion EXTENT (per-property min..max, so a closed loop still reveals its travel).

…aligned squash vs spin, heading=tangent, per-channel check) + composed-surface note

…nel & motion-trail patterns

…eadless blank-render gotchas (perspective+SVG, attr-keyframes)

… absent from the reference

+  let projectName: string;
+  let projectDir: string | undefined;
+  if (raw && raw.endsWith(".html") && existsSync(raw) && statSync(raw).isFile()) {
+    comps = [surfaceComposition(readFileSync(raw, "utf-8"), basename(raw), raw)];


Internal eval loop guidance, renderable timeline contract, honest diagnostics, explicit pen-up, geometry-morph rule, cursor causality.

- onUpdate/modifiers ARE seek-safe in HyperFrames (engine seeks with totalTime(t,false)); corrects the common 'onUpdate freezes on seek' folklore. Verified across core adapter, studio, runtime IIFE. - morph: trust the emitted geometry string (degenerate Beziers, clip-path+border-radius, corner>=edge magnitude). - 3D: no face-flat landing; backface-visibility on every rotating ancestor; don't compound perspective. - flythrough: drive size by translateZ, cap z<P (projection inverts).

- seek-safety corollaries: drive followers from tl.time() not construction order; own t=0 explicitly (fromTo immediate-renders its from-state at build); animate values through a real channel. - 3D: grouping properties (opacity<1/filter/clip-path/mask/overflow) flatten preserve-3d and break z-sort; orbit from one phase angle. V2: skill 87 vs baseline 74, skill won 10/10 (V1 was 6/10); both V1 losses (p2,p4) flipped to wins.

Make 'npx hyperframes motion' see motion it was blind to: - fold const expressions in keyframes (MemberExpression, array index, whitelisted Math.*) instead of emitting __raw: - seed gsap.set()/tl.set() pre-states as the following tween's start keyframe (fixes grow/fold/fade-from reading as flat X->X no-ops) - resolve addLabel() + label-relative positions to absolute times - bind toArray()/slice collection aliases to their selector - label proxy-onUpdate and empty dwell tweens instead of __unresolved__

window.__timelines = { 'comp-1': tl } now recognized as valid registration and its keys extracted, matching the keyed-assignment form.

The render path seeks window.__timelines[root data-composition-id]; a missing/mismatched id silently rendered frozen at t=0 while --shot (which seeks __timelines directly) looked fine. Surface a diagnostic + console.warn at render-ready instead of failing silently.

A selector matching a static .clip wrapper no longer errors with 'no animated element to sample'; it samples the root's animated descendants. Unblocks the documented '--selector .clip --angle iso' 3D verify command.

- render binds the timeline by the root's data-composition-id; register window.__timelines under that exact key or the render freezes at t=0 (while --shot still looks fine). The #1 'looks fine, ships broken' trap. - --shot shows an element's motion, not painted structure; use 'snapshot --at' for masked type / metaballs / 3D / layers.

github-advanced-security AI found potential problems Jun 19, 2026

View reviewed changes

Comment thread packages/cli/src/commands/motion.ts Fixed

miguel-heygen added 5 commits June 20, 2026 09:18

docs(skill): require verifying 3D motion from at least 3 camera angles

919cb2f

One viewpoint hides depth — a flip reads as a static stack head-on, a tumble looks flat. Mandate ≥3 angles (front+top+side/iso) for any 3D motion, and --layout strip for in-place/overlapping motion.

docs(skill): include the nested-elements layered-motion section (cont…

03028bc

…ent fix)

docs(skill): layered-motion patterns (fast channel own tween, ground-…

d46e7ba

…aligned squash vs spin, heading=tangent, per-channel check) + composed-surface note

miguel-heygen mentioned this pull request Jun 20, 2026

feat(cli): add keyframes command to surface motion paths #1556

Closed

2 tasks

miguel-heygen added 4 commits June 20, 2026 14:45

docs(skill): one-shot-from-reference methodology + deliver-named-chan…

66da2c9

…nel & motion-trail patterns

docs(skill): match-the-reference (anti over-interpretation) guard + h…

d086e0c

…eadless blank-render gotchas (perspective+SVG, attr-keyframes)

docs(skill): subtractive self-verify — delete anything in your output…

1f6ef88

… absent from the reference

feat(cli): rename keyframes command to motion

5d2e831

miguel-heygen changed the title ~~feat(cli): keyframes command — surface GSAP motion + 3D onion-skin --shot~~ feat(cli): motion command — surface GSAP motion + 3D onion-skin --shot Jun 22, 2026

github-advanced-security AI found potential problems Jun 22, 2026

View reviewed changes

Comment thread packages/cli/src/commands/motion.ts

let projectName: string;

let projectDir: string | undefined;

if (raw && raw.endsWith(".html") && existsSync(raw) && statSync(raw).isFile()) {

comps = [surfaceComposition(readFileSync(raw, "utf-8"), basename(raw), raw)];

miguel-heygen added 8 commits June 24, 2026 22:23

feat(skill): promote V0/V1 eval lessons into hyperframes-motion

21516fd

Internal eval loop guidance, renderable timeline contract, honest diagnostics, explicit pen-up, geometry-morph rule, cursor causality.

fix(core): lint accepts object-literal __timelines registration

0f06880

window.__timelines = { 'comp-1': tl } now recognized as valid registration and its keys extracted, matching the keyed-assignment form.

fix(cli): motion --shot --selector falls back to animated descendants

da6f479

A selector matching a static .clip wrapper no longer errors with 'no animated element to sample'; it samples the root's animated descendants. Unblocks the documented '--selector .clip --angle iso' 3D verify command.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(cli): motion command — surface GSAP motion + 3D onion-skin --shot#1603

feat(cli): motion command — surface GSAP motion + 3D onion-skin --shot#1603
miguel-heygen wants to merge 18 commits into
mainfrom
feat/keyframes-cli

miguel-heygen commented Jun 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

miguel-heygen commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

What this fixes

Root cause

Verification

Local checks

Browser verification

Notes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

miguel-heygen commented Jun 19, 2026 •

edited

Loading