Hyperframes Keyframes

HyperFrames Keyframes

Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.

Use hyperframes-animation for broad scene recipes. Use hyperframes-cli for full command docs. Use references/keyframe-patterns.md only when choosing implementation mechanisms, not visual style.

Creator editing boundary

Keyframes own visual motion, not clip assembly. Source-range hard cuts, trim, splice, and reorder belong to /hyperframes-core: author one media element per kept range, place it with data-start and data-duration, and select its source offset with data-media-start. Adjacent ranges make a hard cut. A crossfade uses overlapping clips on different tracks plus visual opacity keyframes; sound fades use /hyperframes-audio.

When editing picture and sound together, load /hyperframes-core, this skill for visual motion, and /hyperframes-audio for fades, crossfades, volume automation, ducking/carve, or effects on the placed tracks.

A visual transition or cropping treatment is not a temporal source trim or splice. /hyperframes-core owns the timeline, clip timing, and source ranges; keyframes only animate the visible handoff or crop on wrappers inside those clips. For copyable combined picture/sound recipes, use /hyperframes-core → references/creator-editing-recipes.md.

Procedure

1. Identify the animated subject, visible states, final state, and runtime.
2. Choose the smallest mechanism that proves the prompt. Read references/keyframe-patterns.md only if the mechanism is unclear.
3. Author seek-safe keyframes in the declared runtime. Build synchronously and register the runtime instance.
4. Verify with hyperframes lint, hyperframes check, hyperframes keyframes, one focused --shot, and snapshots at proof times.
5. If proof fails, fix the source keyframes and rerun the smallest failing diagnostic before rendering.

Contract

• Name the moving subject.
• Name the poses needed to prove the intended motion, including the final state.
• Keyframe visible channels, not hidden helper state.
• Preserve object identity when continuity matters.
• Crossfade only when the intended motion is replacement or dissolve.
• Hold readable or semantic states long enough to see.
• Final frame is part of the animation, not cleanup.
• Do not reset to rest unless requested.
• Do not end on black unless requested.
• If editing a starter scene, preserve layout, copy, assets, colors, and final state unless asked to redesign.

Runtime Rules

GSAP:

• build synchronously at page load
• use gsap.timeline({ paused: true })
• register as window.__timelines[compositionId]
• registry key must match data-composition-id
• do not call tl.play() for render-critical motion
• keep repeats finite

CSS keyframes:

• finite duration and iteration count
• deterministic delay
• animation-fill-mode: both
• use data-start when 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 text surface does not list WAAPI; verify with --shot (it seeks WAAPI) and snapshots

Never use for render-critical motion:

• Date.now()
• performance.now()
• unseeded Math.random()
• hover/scroll triggers
• timers
• async-created timelines
• unregistered requestAnimationFrame
• infinite loops

GSAP Skeleton

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 = window.__timelines || {};
window.__timelines[compositionId] = tl;

Use labels for semantic states. Use position parameters instead of chained delays. Use immediateRender: false for later from()/fromTo() tweens touching the same property.

Keyframe Forms

• Array keyframes: pose ladder with per-step duration/ease.
• Percentage keyframes: exact timing inside one tween.
• Property arrays: compact multi-stop changes.
• ease: "none" on the parent when each stop carries its own easing.
• easeEach when every segment should share the same feel.