HyperFrames Animation

All the motion knowledge for HyperFrames in one place: rules (atomic recipes), blueprints (multi-phase scene templates), transitions (scene to scene), techniques (broader motion-design patterns) and adapters (per-runtime APIs). The standard: every move is motivated, lands smooth rather than bouncy, reads in one beat, and renders identically on every seek, because HyperFrames renders by seeking one paused timeline frame by frame.

When to use

• "Animate this scene", "make the title land harder", "add a camera push", "this feels static / cheap / bouncy"
• Choreographing a launch video, explainer or promo scene by scene from a storyboard
• Choosing or building a transition between two scenes
• A named text effect in a storyboard (kinetic-center-build, mask-reveal-up, ...)
• Lottie, Three.js, Anime.js, CSS keyframes, WAAPI or WebGPU inside a composition
• Auditing an existing composition: dead zones, uneven staggers, elements off-frame, motion that collides

What you need

• Run the check in references/setup.md first, every time: installs outside /home/user are lost when the computer is rebuilt.
• The composition folder (index.html plus any compositions/*.html) in ~/Desktop/<your name> - Work space/<job>/, and the composition contract: load hyperframes-core with skill_view before writing composition HTML (data attributes, class="clip", sub-compositions, determinism).
• The brief or storyboard: each scene's role, duration, and the words the viewer must read and when (voiceover cues if there is narration). If the scene's purpose is unclear, ask the owner with clarify before animating.
• Brand assets (logo SVG, fonts, footage) from the owner's files, or sourced with the media-use skill. No accounts or paid services are needed: HyperFrames, GSAP and the other runtimes are open source.

Paths inside the reference files are relative to references/ (a rule pointing at ../adapters/gsap.md means references/adapters/gsap.md). With skill_view, use file_path references/<path>.

Default: compose 2 to 4 atomic rules

Pick 2 to 4 rules from references/rules-index.md and glue them together on one paused GSAP timeline. This is faster and produces less code than starting from a blueprint. Read the contract at the top of the rules index once; every rule assumes it.

Load a blueprint when

• The scene matches a pre-designed multi-phase template (brand reveal, social proof, cursor demo, data count-up...) and reusing its phase pipeline saves real authoring time.
• You want runnable ground truth for a complex 4 to 5 phase choreography.

Blueprints are listed in references/blueprints-index.md (by role: Hook, Problem, Product_Intro, Key_Feature, Benefits, Social_Proof, CTA, Brand_Outro). Each entry points to references/blueprints/<id>.md. Do not read one speculatively: load it once you have decided the scene needs scene-level orchestration. Keep its signature move; adapt the slots.

Routing

Want to	Read
Pick an atomic motion pattern by trigger / tag	references/rules-index.md
One rule's full HTML / CSS / GSAP recipe	references/rules/<name>.md
Pick a multi-phase scene template	references/blueprints-index.md
One blueprint's full recipe	references/blueprints/<id>.md
A scene transition (CSS or shader, between two clips)	references/transitions/overview.md, then references/transitions/catalog.md
Transitions stamped by the product-launch-video workflow	references/transitions/TRANSITION-REGISTRY.md
A broader motion-design technique (SVG draw, Canvas 2D, CSS 3D, kinetic type, variable fonts, audio-reactive)	references/techniques.md
Motion that reacts to music or voice: extraction, data format, seek-safe sampling	references/audio-reactive.md · scripts/extract-audio-data.py
Stats and numbers on screen: continuity, visual weight, real figures	references/data-in-motion.md
The deterministic-render contract every animation keeps (runtime, determinism, layout)	references/determinism-rules.md
Motion blur: shutter smear, and when not to use it	references/motion-blur.md
Audit an existing composition's choreography	scripts/animation-map.mjs (how to run: references/setup.md step 6)
GSAP API: timeline, tweens, position parameter	references/adapters/gsap.md
GSAP drop-in effect recipes (typewriter, audio visualizer)	references/rules/gsap-effects.md
GSAP transforms and performance	references/adapters/gsap-transforms-and-perf.md
GSAP eases, baked spring ease, stagger	references/adapters/gsap-easing-and-stagger.md
GSAP timeline and labels	references/adapters/gsap-timeline-and-labels.md
Lottie / dotLottie (After Effects exports, window.__hfLottie)	references/adapters/lottie.md
Character animation (walk cycle, mascot, jointed puppet, gestures)	references/adapters/lottie.md → Characters
Three.js / WebGL (3D scenes, AnimationMixer, hf-seek)	references/adapters/three.md
Anime.js v4 (window.__hfAnime)	references/adapters/animejs.md
CSS keyframes (animation-delay, play-state, fill-mode)	references/adapters/css-animations.md
Web Animations API (element.animate(), currentTime seek)	references/adapters/waapi.md
TypeGPU / WebGPU (navigator.gpu, WGSL, compute)	references/adapters/typegpu.md
HTML as a texture + WebGL post effects (drawElementImage)	references/adapters/html-in-canvas-patterns.md
The 24 named text effects	references/adapters/animate-text.md
Worked compositions to copy from	references/examples/*.html (the rules cite which)

Picking a runtime

• GSAP for 95% of motion work: timeline orchestration, transforms, easing, stagger. Every atomic rule here is GSAP-based.
• Lottie when an asset has its own pre-baked timeline (usually an After Effects export), including characters that walk, gesture or react.
• Three.js for 3D scenes, camera motion, shader-driven visuals.
• Anime.js for lightweight tweening when GSAP is overkill, and only when the owner asks for it.
• CSS keyframes for simple repeated motifs, decoration, shimmer, with no JavaScript animation cost.
• WAAPI for native browser keyframes without a GSAP dependency.
• TypeGPU / WebGPU for GPU canvases (particles, liquid glass, custom shaders). Your computer usually has no GPU: snapshot one frame early before committing a scene to it.

Several runtimes can coexist in one composition. Each registers its instances on its own global (window.__timelines, __hfLottie, __hfAnime, ...) so HyperFrames can seek all of them in one pass.

Critical constraints

Prerequisite: hyperframes-core's non-negotiable rules. One paused timeline per composition; data-duration governs length; no Math.random, Date.now or performance.now; no repeat: -1 without a finite root data-duration; no page-load gsap.set on later-scene clips; no display or raw visibility tweens; no timeline construction inside async, setTimeout or a Promise. GSAP autoAlpha and zero-duration visibility sets at explicit timeline boundaries are allowed, but only on non-clip elements or wrappers inside a clip: the framework owns .clip lifecycle.

Animation craft on top of that contract:

• Seek-safe in both directions. fromTo with explicit from-states, absolute values (never +=), state as a pure function of timeline time, no mutable trackers in onUpdate.
• Pre-calculated layout constants. Never derive positions from getBoundingClientRect() at tween time: the renderer samples frames in parallel, so tween-time measurements desync. Compute coordinates once at setup (single-scene compositions only) or use authored constants that match the CSS.
• Spatial motion uses transform aliases only (x, y, scale, rotation). Non-spatial paint properties (opacity, color, backgroundColor, borderRadius, filter) are fine. Never tween width, height, top, left, letterSpacing or fontSize: they snap to whole pixels and stutter on slow moves.

Method

1. Set up and read. Run the references/setup.md check. Read the composition and the storyboard; write a beat list per scene with times: what arrives, what the viewer must read, where the voiceover lands, and the one signature move. Use todo when there are more than three scenes.
2. Choose per scene. Default to 2 to 4 rules from the rules index; take a blueprint only by the rule above. Give each shot exactly one signature move; everything else supports it. Read only the rule, blueprint and adapter files you chose.
3. Set the motion language. Entrances settle on power3.out (or expo.out for a punchier front); repositioning on power2.inOut; camera landings on power4.out. Draw on about three easing characters across the video, varied by energy within the smooth families. Overshoot (back.out, a baked spring below ζ 0.8) only for an explicitly playful brief, and never on opacity. Group arrivals: items × stagger ≤ ~0.5s. Hold every hero element at least 1 s after it settles; give the final lockup 20 to 30% of the runtime.
4. Author. One timeline, built synchronously at setup, registered under the composition id:

   const tl = gsap.timeline({ paused: true, defaults: { duration: 0.6, ease: "power3.out" } });
   tl.fromTo("#title", { y: 40, opacity: 0 }, { y: 0, opacity: 1 }, 0.2);
   window.__timelines = window.__timelines || {};
   window.__timelines["<data-composition-id>"] = tl;
   

   Seed every "random" value from the index ((i * 9301 + 49297) % 233280-style hashes or the rules' prand(i)), and put camera state in one object written by one function.
5. Lint and check. npx hyperframes lint <dir>, then npx hyperframes check <dir>. Fix every error. Read every warning and fix it unless you can say why it does not apply (for example, a file-size advisory on a single-scene example).
6. Snapshot the key moments. npx hyperframes snapshot <dir> --at <t1,t2,...> at the end of each entrance, the peak of each signature move, mid-hold, and the last frame. Run vision_analyze on each PNG with pointed questions: is every word that should be readable fully on screen and legible; is anything clipped at the frame edge or by a mask; does anything overlap that should not; is the final frame the intended lockup.
7. Prove seek safety. Snapshot one mid-tween time in two separate runs, once on its own and once together with an earlier and a later time. The frames must match; compare them with vision_analyze or md5sum. A difference means Math.random, wall-clock time, a CSS transition, a relative tween or state accumulated in onUpdate.
8. Audit with the animation map. Copy and run scripts/animation-map.mjs (exact steps in references/setup.md step 6) and read animation-map.json:
   • deadZones: 1 s or more with nothing moving. Intentional hold, or a missing entrance?
   • flags: offscreen (left the frame), invisible (animating at opacity 0), degenerate (zero-size box), collision (over 30% overlap with another moving element), paced-fast (a move under 0.2 s), paced-slow (over 2 s: is it a drift or a stall?).
   • staggers with uneven intervals (drift over 30% of the average): fix the offsets or make them deliberately accelerating.
   • elements: anything with endsVisible: false that should still be on screen at the end.
9. Fix and repeat steps 5 to 8 until lint and check are clean, the snapshots read right, and every remaining map flag has a reason you can state.
10. Hand off. If the owner wants the video, render with the hyperframes-cli skill (npx hyperframes render, locally) and give them the file path plus show_card with type media. Otherwise report the composition as ready to render.

Output

• The edited composition files, in place.
• A motion note per scene: rules or blueprint used, the signature move, the key times (entrance end, peak, hold), and the easing choices.
• The snapshot PNG paths you checked, and the animation-map summary (tween count, dead zones, flags, and how each remaining flag is explained).
• The rendered video path and a show_card when a render was asked for.

Checks before you finish

• Lint shows 0 errors; check passes; warnings are fixed or explained.
• One paused timeline per composition, registered on window.__timelines; nothing built after an await.
• No Math.random, Date.now, performance.now, CSS transition on animated elements, += tweens, or layout-property tweens (search the files with search_files).
• Every scene's last snapshot shows its intended end state; the final frame holds the lockup.
• The two-run seek check matched.
• The animation map shows no unexplained dead zone, offscreen, invisible or collision.
• No exit animations before a transition, except in the final scene.

Pitfalls

• Bouncy by default. back.out is the most common reason agent-made motion looks cheap. Settle smoothly; keep overshoot for a playful brand, on transforms only.
• Random and clock values. Math.random() and Date.now() give a different video on every render. Use index-derived hashes and baked schedules.
• Measuring at tween time. getBoundingClientRect() inside onUpdate desyncs under parallel frame capture. Measure once at setup, or bake constants in a montage where later clips are not laid out yet.
• Width, height, top, left. They reflow and stutter. Use scale with transformOrigin, x/y, masks, or anchored-layout-expand for containers that grow.
• gsap.from() over CSS opacity: 0. It animates 0 to 0 and the element never appears. Use fromTo.
• Breathing as "life". Scaling things up and down to look alive is cheap. Reveal the next element on its cue instead; use sine-wave-loop last, with finite repeats.
• Exits before a transition. The transition is the exit. Fading content out first leaves the transition nothing to carry.
• Two writers on one transform. A camera wrapper tweened by two tweens, or drift written separately, fights itself. One state object, one applyCamera().
• The wrong zoom formula. coordinate-target-zoom counter-translates by -offset; viewport-change uses -offset × S. Mixing them lands the target off-center.
• Rotating thin SVG parts with CSS transform-origin. It resolves in the part's own bbox and the hand swings off-center. Use the SVG transform attribute with an explicit center.
• Motion blur everywhere. Blur one to three beats that snap; a smeared word cannot be read.
• Long cascades. A 40-letter per-character stagger takes two seconds to arrive. Drop to per-word.
• Runtime traps. Anime.js v4 has no callable anime(); Lottie players left on autoplay run on wall-clock time; a Three.js-only scene without data-duration fails as "zero duration".

See also

• hyperframes-core: composition structure, data attributes, sub-compositions, the determinism contract.
• hyperframes-creative: palettes, typography, narration, beat planning, audio-reactive visuals.
• hyperframes-keyframes: punch-ins, Ken Burns, path and SVG morphs, FLIP moves.
• hyperframes-cli: lint, check, snapshot, render.
• hyperframes-registry: installable blocks and components (including motion-blur).