HyperFrames Keyframes

Keyframes are a pose contract: you name the visible states a subject must pass through, keep the subject's identity continuous between them, build them on a runtime the renderer can seek to any frame, and prove the motion from painted pixels rather than from the code. A finished move reads on the first frame, hits every proof pose, holds its final state long enough to see, and never relies on a clock, a timer or a hover.

When to use

• "Punch in on the button when the cursor clicks it, then back out."
• "Slow Ken Burns on the photo", "push the camera into the dashboard", "reframe to the speaker on the left".
• "Whip pan into the next scene", "match cut from the logo to the app icon" (with hyperframes-animation for the handoff choreography).
• "Draw the route on the map", "morph the circle into the logo", "the cards fly in with real depth".
• A move that looks wrong in a render: endpoint-only, jittery, fake 3D, wrong final frame, or not seekable.
• Reading npx hyperframes keyframes output or onion-skin shots.

What you need

• Your computer set up for HyperFrames: run the check in references/computer-setup.md first (Node 22+ and FFmpeg are not installed by default) and start every CLI call with its environment line.
• The project, passing npx hyperframes lint, and the composition file that holds the subject. Read it before editing.
• The subject's clip window (data-start, data-duration) from npx hyperframes timeline --json, so every pose lands inside it.
• The runtime the composition already uses (GSAP by default). Do not add a second runtime for one move.
• For clip structure and media rules, load hyperframes-core with skill_view; for which motion a scene should have, load hyperframes-animation.

Who owns what

Keyframes own visual motion, not clip assembly. Source cuts, trims, splices and reorders belong to hyperframes-core: one media element per kept range, placed with data-start and data-duration, its source offset chosen with data-media-start. Adjacent ranges make a hard cut. A crossfade is overlapping clips plus opacity keyframes; sound fades are hyperframes-audio.

Owner asks for	Truthful mechanism
Punch-in / punch-out	Keyframe scale with x/y or xPercent/yPercent on an untimed wrapper inside the clip. A set or very short tween is a hard punch; a longer tween is a smooth move.
Smooth multi-state zoom or reframe	Keep one subject wrapper alive and author the states as a pose ladder with per-segment easing.
Pan, reframe, Ken Burns, camera move	Wrapper translation plus scale. The geometry is authored by you: this is not face tracking or automatic reframing.
Chained camera moves	Labeled transform beats on one registered, seek-safe timeline.
Match cut or whip pan	hyperframes-animation owns the handoff, hyperframes-registry may supply a transition block, keyframes keep geometry, direction and velocity continuous. There is no automatic matching-frame finder.
Crop or mask reframe	Interpolate clip-path or a mask on an inner wrapper; source time does not change. Polygon keyframes can form a mask transition.
Directional wipe or iris reveal	Animate a mask or clip boundary across overlapping clips; hyperframes-animation owns the choreography.
Split-screen handoff	Core places both clips; you keyframe their inner crop wrappers and the divider.
Constant speed change	data-playback-rate (0.1 to 10) on the media element, owned by hyperframes-core; constant for the whole element.
Speed ramp	A rate lane in data-automation on the <video> or <audio> (t in clip seconds, v 0.1 to 10, log interpolation); it wins over the constant rate.
Freeze / hold	A pose, the final source frame or a finished sub-composition can hold. A mid-source freeze needs a still or a derived segment placed as its own clip (see media-use), then another source range.

A visual transition or crop is never a source trim. When picture and sound change together, load hyperframes-core, this skill and hyperframes-audio; copyable combined recipes are in hyperframes-core's creator-editing recipes.

Method

1. Name the move. Write down the subject (one selector), its visible states with times, its final state, and the runtime. Example: "#shot-punch-inner: wide at 0, punched on the button at 2.0 to 2.35 s, held, back to wide at 4.2 to 4.65 s, wide until the clip ends at 6 s."
2. Pick the smallest mechanism that proves the request from the table in references/keyframe-craft.md (shared element, path travel, stroke draw, shape interpolation, clip or mask, stagger, text subdivision, counter-transform, state machine, depth). Open references/keyframe-patterns.md only when the implementation is unclear.
3. Author seek-safe keyframes following the runtime rules below. Animate an untimed wrapper inside the clip, never the timed clip element or the <video> itself. Derive distances and times from this composition's geometry and duration; never copy numbers from an example. A worked, lint-clean example is references/example-punch-and-pan.md.
4. Prove it on your own computer with the CLI proof sequence below: lint, check, keyframes --json, one focused --shot, and snapshot --at the proof times. Look at every PNG with vision_analyze; batch them into one contact sheet where you can.
5. Fix in the source and rerun the smallest failing diagnostic, not the whole chain, until the proof holds. Trust painted pixels over logs.
6. Show the owner. The owner cannot open a preview on your computer. Attach the proof frames (or a contact sheet) and, when the feel of the motion matters, a --quality draft render, with MEDIA:/absolute/path in your reply.

The pose contract

• Name the moving subject and the poses that prove the motion, including the final state.
• Keyframe visible channels, not hidden helper state.
• Preserve object identity when continuity matters: one element travels; it is not swapped for a lookalike mid-move.
• Crossfade only when the intended motion is replacement or dissolve.
• Hold readable or meaningful states long enough to see.
• The final frame is part of the animation, not cleanup. Do not reset to rest or end on black unless asked.
• Editing a starter scene: keep its layout, copy, assets, colours and final state unless asked to redesign.

Runtime rules

• GSAP: build synchronously at page load; gsap.timeline({ paused: true }); register as window.__timelines[compositionId], the key equal to the root data-composition-id; never tl.play() for render-critical motion; finite repeats only.
• CSS keyframes: finite duration and iteration count, deterministic delay, animation-fill-mode: both, data-start when the timing belongs to a clip.
• Anime.js: create synchronously, autoplay: false, finite duration and loops, push every instance to window.__hfAnime.
• WAAPI: finite duration, fill: "both", deterministic construction. The keyframes text report does not list WAAPI; verify with --shot (it seeks WAAPI) and snapshots.
• Never for render-critical motion: Date.now(), performance.now(), unseeded Math.random(), hover or scroll triggers, timers, timelines created later in async code, unregistered requestAnimationFrame, infinite loops.

const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });

tl.addLabel("state-a", 0);
tl.to(".subject", {
  keyframes: [
    { x: 0, opacity: 1, duration: 0.2 },
    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
  ],
  ease: "none",
});

window.__timelines[compositionId] = tl;

Use labels for meaning and position parameters instead of chained delays. Use immediateRender: false on later from() / fromTo() tweens that touch a property an earlier tween also sets. Array keyframes give a pose ladder with per-step duration and ease; percentage keyframes give exact timing inside one tween; property arrays are compact multi-stop changes; put ease: "none" on the parent when each stop carries its own ease, or easeEach when every segment shares one feel. For one subject moving between two boxes, prefer one continuous tween or FLIP: every extra segment changes velocity and can read as a hitch.

CLI proof

npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>.png" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>.png" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>.png" --ghost --angle <angle>
npx hyperframes snapshot . --at <times> --describe false

Choose <selector> for the real animated subject. Choose <times> for the first frame, each proof pose, final minus hold, and the exact final frame. Use --angle (front, iso, top, side, rear-iso, or yaw,pitch) only when depth must be proven. How to read each tool's output, and what to do when proof fails, is in references/keyframe-craft.md.

Output

• The edited composition file(s), with the subject's poses written as fromTo or keyframe arrays at numeric positions.
• A short proof note for the owner or the teammate who asked:

Move: punch-in on the Export button (#shot-punch-inner), 2.0 to 2.35 s, held to 4.2 s, out by 4.65 s.
Proof: keyframes --json shows 2 tweens at 2.0 and 4.2 s; shot strip and snapshots at 0.5, 2.4, 4.0, 4.7, 5.9 s checked.
Final state: wide frame from 4.65 s to the end of the clip, no reset, no black tail.
Files: compositions/shot-punch.html. Frames attached.

Checks before you finish

• lint and check pass with no new findings.
• keyframes --json lists the tweens you meant, at the times you meant, on the real subject.
• One focused --shot shows the route, spacing and direction you intended.
• Snapshots at first frame, proof poses, final minus hold and exact final frame were looked at with vision_analyze.
• Motion is owned by the subject (no helper overlay faking it), no debug overlays remain, and the final state holds.

Pitfalls

• Animating the timed element. Tweening a .clip or a timed <video> fights the framework's visibility and fails lint. Wrap it and move the wrapper.
• Timing a wrapper and its video. A <video data-start> inside a plain element that also has data-start is a lint error with real symptoms. Time the video; leave the moving wrapper untimed, or make the shot a sub-composition.
• Endpoint-only moves. Two poses with nothing in between read as a jump. Add the middle poses and hold the peak.
• Trusting the text report alone. In the version tested (0.8.111) the keyframes text report placed label-positioned tweens at 0 s and showed a to() tween's start pose as its end pose. Use numeric positions and fromTo where you want the report to be exact, and confirm with --shot and snapshots.
• Scale as fake depth. Scaling alone is not 3D. Use perspective on a stable parent, z travel, rotation and occlusion, and prove it from an angle.
• Copying numbers. Distances and durations from an example never fit another frame. Derive them.