HyperFrames Keyframes

Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

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. Register the runtime instance only after the build completes; building inside document.fonts.ready is fine.
4. Verify with hyperframes check (it runs lint), 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 at page load or inside document.fonts.ready, and register only after the build completes
• 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
• a timeline registered before its async build finishes
• 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.

Do not copy numeric distances or timing from examples. Derive them from the actual composition geometry and duration.

For one subject moving between two boxes, prefer one continuous transform tween or FLIP. Split x/y/scale into multiple eased keyframes only when the viewer should feel distinct beats; every segment changes velocity and can read as a hitch.

Channels

Prefer compositor/visual channels: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masks, CSS vars, SVG path/dash values, camera transforms, shader uniforms.

Avoid layout/lifecycle channels: top/left/right/bottom, width/height, margin/padding, display, visibility, late DOM creation, helper overlays doing subject motion.

For visibility changes, use autoAlpha on the registered seekable GSAP timeline, or a zero-duration tl.set() at an explicit boundary. Target only a non-clip element or a wrapper inside the clip; never target .clip itself. Never duration-tween raw visibility, and never tween display.