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

[miguel-heygen]

Stack: GSAP keyframe + motion-path editing — CLI surface (#1553 → #1561).

What

Add a hyperframes keyframes CLI command that surfaces an element's GSAP keyframes and motion-path geometry from a composition, plus an agent skill documenting it.

Why

Lets users and agents inspect keyframe / motion-path data (and verify mutations) without opening the Studio UI — useful for scripting and for agent workflows.

How

• commands/keyframes.ts: parses the composition's GSAP timeline via the core parser and prints per-element keyframes / paths; wired into cli.ts.
• skills/hyperframes-keyframes/SKILL.md: documents the command for agents.

Test plan

• Manual CLI run against sample compositions
• Documentation (skill) added

[miguel-heygen]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(studio): keyframes flag, gesture recording + timeline/selection refinements #1561
• feat(studio): on-canvas motion-path overlay #1560
• feat(studio): motion-path geometry + commit helpers #1559
• feat(studio): GSAP drag/commit/bridge editing infra #1558
• feat(studio): GSAP runtime read layer + shared helpers #1557
• feat(cli): add keyframes command to surface motion paths #1556 👈 (View in Graphite)
• feat(core): route motion-path mutations through studio-api + fix clip stamping #1555
• feat(core): add GSAP keyframe + motion-path source mutations #1554
• chore(producer): shim __filename/__dirname in the CJS banner #1553
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Approved at 5e8cf5e0 per Rames D Jusso "stamp-ready with 1 test gap on CLI." CLI surface for the keyframes/motion-path workstream is clean.

Worth adding the test for the keyframes-command path (Rames D Jusso called the specific gap out in his review). Non-blocking — fine as a follow-up commit before merge. Also: PR body is the unfilled template; please fill in before merge per the stack-wide note.

[terencecho]

CLI surface + skill wiring axis

Verified

• hyperframes-keyframes skill correctly placed at skills/hyperframes-keyframes/SKILL.md, frontmatter has name + description per the canonical pattern, sits alongside the existing hyperframes-animation / hyperframes-cli / hyperframes-core siblings.
• Skill content documents the read-edit-verify loop, surfaces the --json output shape for agents, and gives both object-form and motionPath editing examples that match the actual CLI output. The ASCII path drawing is a nice touch for the "see motion as data" framing.
• CLI command typed cleanly with SurfacedTween / KeyframePoint / SurfacedComposition interfaces; registered in cli.ts commandLoaders with lazy import.
• pngDecodeBlitWorker removal cleanup is consistent — the env-var bootstrap was simplified to shader-only, and git grep confirms the real pngDecodeBlitWorker is gone from packages/producer/ (only a crashOnMessageWorker test fixture remains). No dead worker wiring.
• EPIPE suppression correctly runs before any stdout/stderr write (declared at top of file, before the worker-path bootstrap). The flag-set-then-exit-0 pattern preserves telemetry-failure attribution.

Note (non-blocking)

• Title undersells scope. "add keyframes command" misses the EPIPE handler, trackCommandFailures wrap, two additional commands (beats, cloudrun), and the pngDecodeBlitWorker cleanup. All look like legitimate improvements, but the title makes the CLI delta look smaller than +459/-0 actually is. A future bisect on EPIPE behavior won't land here from the title.

— Review by tai (pr-review)

[vanceingalls]

Concurring with the consolidated stack review at HEAD f6a0cbb9. One specific finding the structural pass didn't surface, plus a scope clarification:

Duplicate fork of the canonical hold-marker helper. packages/cli/src/commands/keyframes.ts:116-117 defines a local isHoldMarker:

function isHoldMarker(anim: GsapAnimation): boolean {
  return anim.properties?.data === "hf-hold" || anim.fromProperties?.data === "hf-hold";
}

But @hyperframes/core already exports the canonical isStudioHoldSet at packages/core/src/parsers/gsapParser.ts:1573 alongside the STUDIO_HOLD_MARKER constant. The two are subtly different: the canonical version additionally requires method === "set", while the local one matches any animation with data === "hf-hold" on either properties bag. Equivalent today, but the moment the Studio tags a non-set tween with hf-hold (a perfectly plausible extension of the marker), this surface silently drops it. Cheap to fix by importing the canonical helper.

Scope clarification. This PR's file list at HEAD is exactly three: packages/cli/src/cli.ts (single line of registration), packages/cli/src/commands/keyframes.ts, and skills/hyperframes-keyframes/SKILL.md. The EPIPE handler, trackCommandFailures wrap, beats/cloudrun commands, and pngDecodeBlitWorker cleanup items raised in a parallel review appear to belong to a different PR — none of those files are in #1556's diff at any point in its history.

Minor notes already standing from the consolidation (silenced parseGsapScript catch, literal-vs-CSS-selector docstring drift, the absent smoke test) all still apply.

Review by Via

[terencecho]

Retraction & correction crediting @via

My prior review on this PR overstated scope. I cited EPIPE suppression, trackCommandFailures, beats / cloudrun command additions, and a pngDecodeBlitWorker cleanup as findings on #1556. Via correctly pointed out that #1556's actual delta at HEAD f6a0cbb9 is exactly three files — packages/cli/src/cli.ts, packages/cli/src/commands/keyframes.ts, skills/hyperframes-keyframes/SKILL.md. Verified via gh pr view 1556 --json files: file count = 3, gh pr diff 1556 | grep -c EPIPE = 0.

What went wrong on my end: I used git diff $(git merge-base main pr-1556)..pr-1556 -- packages/cli/src/cli.ts, which is stack-cumulative (traverses back through #1553→#1555 to the common ancestor with main). The PR-specific delta needed gh pr diff 1556, which compares against the PR's actual base (#1555's head). The EPIPE / trackCommandFailures / beats / cloudrun / pngDecodeBlitWorker items I attributed here likely live in an earlier PR in the stack — not in #1556. Title-undersells-scope was the wrong finding; the actual scope IS exactly what the title says.

What stands from my prior review:

• hyperframes-keyframes skill correctly placed and frontmatter-correct ✓
• SKILL.md content matches CLI output shape ✓
• CLI command typing clean (SurfacedTween / KeyframePoint / SurfacedComposition interfaces) ✓
• keyframes registration in cli.ts commandLoaders ✓

Also concur with Via's separate finding on the isHoldMarker duplicate-fork of canonical isStudioHoldSet at keyframes.ts:116-117 — the method === "set" branch divergence is worth folding before merge.

— Review by tai (pr-review)

[jrusso1020]

Re-approved at f6a0cbb9 post-restack. CLI surface still clean.

Echoing Via's R2 finding: commands/keyframes.ts:116-117 has a local isHoldMarker that's a duplicate fork of the canonical isStudioHoldSet — subtly diverges on the method === "set" branch. Worth replacing with an import of the canonical helper to keep the hold-classification semantics in one place. Non-blocking, fine as a follow-up commit.

Plus: PR body still unfilled template; CLI test gap from R1 still applies.