mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
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.
4.4 KiB
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
- Surface —
npx hyperframes keyframes [dir|file](defaults to./index.html+ sub-compositions). - Read the path shape + keyframe list (or
--jsonfor exact data). - Edit the
keyframes/x/yvalues in the composition source. - Verify — re-run
npx hyperframes keyframesto confirm the new shape, thennpx 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 (keyframesmulti-stop,flat2-point,motionPatharc).@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 onlyS→Eare marked and the path is traced with·. --jsongives exact{ pct, time, properties }per keyframe + the rawpathpoints — 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 flatto("#el", { x })toto("#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@startshifts; 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) andrenderto ship.