Files
hyperframes/skills/hyperframes-keyframes/SKILL.md
Miguel Ángel 90b9a18b70 feat(studio,cli): on-canvas GSAP motion-path editing + agent keyframes surfacing
STUDIO — edit a selected element's GSAP motion path directly on the canvas: a
dashed polyline through its x/y keyframes (or motionPath waypoints) with
draggable diamond nodes, in composition coordinates so it tracks GSAP transforms.
- Drag a node to rewrite its keyframe/waypoint; click to select a keyframe and
  park the playhead on it; double-click empty canvas to author a new motionPath;
  add/remove waypoints inline; right-click a keyframe node for the timeline's
  delete actions (remove keyframe / remove all).
- The overlay spills into the canvas margin without bleeding into the side panels.
- Keyframe add/remove key off the tween-relative percentage the GSAP writer
  expects, so edits from the Design panel, timeline, and motion path all persist
  and refresh consistently. Array-form keyframes (`keyframes: [...]`) are
  removable in both the acorn and recast writers.
- Dragging a GSAP-animated element folds the offset through gsap.set instead of a
  conflicting CSS translate; the drag intercept trusts the live runtime so a
  deleted animation can't be resurrected from a stale parse cache. Gated behind
  the keyframes flag.

CLI — `npx hyperframes keyframes [dir|file]` surfaces every GSAP tween, its
keyframes (with absolute times), and an ASCII motion-path drawing so agents can
read and edit motion as data instead of guessing at raw numbers. `--selector`,
`--json` (machine-readable), filters internal hold markers, draws the path only
for genuine multi-point/2-axis motion. Ships the `hyperframes-keyframes` skill
(surface → read → edit → verify loop).

PRODUCER — esbuild ESM banner also shims `__filename`/`__dirname` so bundled CJS
deps (e.g. wawoff2) don't throw "__dirname is not defined" during render.
2026-06-18 02:50:36 -04:00

4.4 KiB

name, description
name description
hyperframes-keyframes Read and edit GSAP keyframes and motion paths in a HyperFrames composition. Use whenever a task involves an element's MOTION over time — adding/removing/moving keyframes, refining a motion path, changing where or when something travels, debugging "why does it move there", or understanding an existing animation before editing it. Run `npx hyperframes keyframes` to surface every tween's keyframes + an ASCII motion-path so you can see and edit motion as data instead of guessing at raw numbers.

HyperFrames Keyframes

Editing motion by reading keyframes: [{x:0},{x:-260}] in source is guessing — you can't see the shape a tween traces, only opaque numbers. npx hyperframes keyframes surfaces every GSAP tween, its keyframes (with absolute times), and an ASCII motion-path drawing so you can reason about motion, then edit precisely and verify.

The loop

  1. Surface — npx hyperframes keyframes [dir|file] (defaults to ./index.html + sub-compositions).
  2. Read the path shape + keyframe list (or --json for exact data).
  3. Edit the keyframes / x/y values in the composition source.
  4. Verify — re-run npx hyperframes keyframes to confirm the new shape, then npx hyperframes inspect / render.
npx hyperframes keyframes                      # whole project
npx hyperframes keyframes --selector '#hero'   # one element
npx hyperframes keyframes compositions/s2.html # one composition file
npx hyperframes keyframes --json               # machine-readable (agents)

Reading the output

#puck-b position  to/keyframes  @1s→4.4s (3.4s)
  0% {x:0 y:0}  33% {x:-180 y:-60}  67% {x:-320 y:40}  100% {x:-460 y:-20}
  ┌──────────────────────┐
  │              1·       │
  │            ··  ··     │
  │ 3·       ··      ·0   │
  │    ·· ·2·             │
  └──────────────────────┘
  x -460..0   y -60..40 (gsap px; marks 0..n = keyframe order)
  • to/keyframes = method (to/from/fromTo/set) + shape (keyframes multi-stop, flat 2-point, motionPath arc).
  • @1s→4.4s = absolute timeline window; each % is tween-relative (0 % = tween start, 100 % = tween end).
  • Keyframe line = every stop with its properties.
  • ASCII grid = the position path in GSAP x/y offset pixels (the element's translate from its layout home; +x right, +y down). Marks 0,1,2,… are keyframes in order; on dense gesture paths only S→E are marked and the path is traced with ·.
  • --json gives exact { pct, time, properties } per keyframe + the raw path points — use it when you need to compute edits.

Editing keyframes (in source)

Percentages are tween-relative, and edits go in the composition's <script>:

  • Move a keyframe — change its x/y (or any prop) at that %.
  • Add a keyframe — insert a new "P%": { x, y } entry (object form) keeping ascending order; convert a flat to("#el", { x }) to to("#el", { keyframes: { "0%": {x:0}, "100%": {x} } }) first if needed.
  • Remove a keyframe — delete its "P%" entry; if fewer than two remain, collapse back to a flat tween.
  • Retime — change the tween's duration / position argument (the @start shifts; the %s stay).
// object-form keyframes (each value is the element's gsap x/y OFFSET from its CSS layout position)
tl.to("#hero", {
  keyframes: { "0%": { x: 0, y: 0 }, "50%": { x: 120, y: -80 }, "100%": { x: 240, y: 0 } },
  duration: 2, ease: "power1.inOut",
}, 1.0);

After any edit, re-run npx hyperframes keyframes --selector '#hero' — the new ASCII path is your confirmation the motion matches intent before you render.

Gotchas

  • x/y are offsets, not absolute canvas coords. {x:0,y:0} = the element's CSS layout spot; values are deltas from there.
  • Studio holds. A set("#el", { …, data: "hf-hold" }) is an internal position-hold the Studio injects before a position tween — it's filtered from the surface; don't author or edit it by hand.
  • Dynamic tweens (computed selectors / data-driven keyframes) can't be statically resolved; they show with fewer details. Author literal keyframes: {…} when you want them editable.
  • This is read-then-edit-source, not a mutation command — it never changes files. Pair it with inspect (layout/overflow over the timeline) and render to ship.