chore: import upstream snapshot with attribution

2026-07-13 12:58:35 +08:00
commit 85453da49f
4031 changed files with 710987 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Text Effects — Reference
+
+For deterministic text-animation specs (e.g., `typewriter` at exact `240ms / 46ms stagger / steps(1, end) easing`), this skill defers to the separate **`animate-text`** skill maintained by Pixel Point at [github.com/pixel-point/animate-text](https://github.com/pixel-point/animate-text). It provides a catalog of 24 named text effects with portable contracts and per-library implementation recipes (GSAP, Anime.js, WAAPI).
+
+**We do NOT ship the catalog inside this repo.** Pixel Point's `animate-text` is the source of truth; vendoring its files here would violate the upstream's licensing (no explicit license declared upstream as of this writing). Loading the skill separately keeps the legal picture clean while giving you the same catalog.
+
+## How to use it
+
+When a beat needs a deterministic text animation, load the upstream skill alongside this one:
+
+```bash
+# In your project root, install the upstream skill into .agents/skills/
+npx skills add pixel-point/animate-text
+```
+
+Or in a skill-aware agent runtime, the skill is invoked by name:
+
+```
+/animate-text
+```
+
+Once installed, the specs live at:
+
+```
+.agents/skills/animate-text/assets/effects/<id>.json   # per-library implementation recipe
+.agents/skills/animate-text/assets/specs/<id>.json     # portable motion contract
+```
+
+Sub-agents reading those files get exact GSAP timings, easing strings, DOM split rules, and stagger algorithms — no creative invention needed.
+
+## When you don't need the upstream skill
+
+If a beat's text animation is simple enough to describe in prose ("headline fades up word-by-word, 80ms stagger"), implement it inline using the GSAP knowledge already in these skills (`hyperframes-creative` → `references/motion-principles.md` and `references/beat-direction.md`; `hyperframes-animation` → `techniques.md`, entry #4 "Per-Word Kinetic Typography"). The upstream catalog is most valuable when:
+
+- You want a specific NAMED effect across multiple beats (so they feel like one design system, not one-offs)
+- You're choosing between several similar effects (typewriter vs per-character-rise vs bottom-up-letters) and want to see all 24 in one place
+- You need layout-aware effects (`kinetic-center-build`, `short-slide-right`, `short-slide-down`) where parameters alone aren't enough — those ship with custom layout algorithms
+
+## Effect names — vocabulary (do NOT use this as the implementation source)
+
+For convenience while writing storyboards: the upstream skill provides 24 effects. Their IDs are listed here so you can name them in `STORYBOARD.md` even before loading the upstream skill. **The implementation specs are in the upstream skill, not here.**
+
+- **Per-character (7):** soft-blur-in, per-character-rise, typewriter, bottom-up-letters, top-down-letters, stagger-from-center, stagger-from-edges
+- **Per-word (8):** per-word-crossfade, spring-scale-in, shared-axis-y, blur-out-up, kinetic-center-build, short-slide-right, short-slide-down, depth-parallax-words
+- **Per-line (2):** mask-reveal-up, line-by-line-slide
+- **Whole element (7):** micro-scale-fade, shimmer-sweep, fade-through, shared-axis-z, scale-down-fade, focus-blur-resolve, shared-axis-x
+
+For descriptions, durations, easing curves, and the per-library recipes: load `/animate-text` and read its own catalog page.
+
+## In the storyboard
+
+Every text element in every beat can name an effect by ID, e.g.:
+
+```markdown
+**Text Animations:**
+
+- Main headline: `kinetic-center-build`
+- Eyebrow label: `soft-blur-in`
+- Body copy 3 lines: `mask-reveal-up`
+```
+
+Sub-agents implementing the beat will load `/animate-text` if it's not already loaded, then read the spec for each named effect from the upstream skill's files.
+
+If the upstream skill isn't available (offline build, network restrictions, agent runtime that doesn't support skill loading), sub-agents fall back to implementing the effect from the description alone — using GSAP knowledge plus the effect ID as a description of intent (e.g., "typewriter" = per-character stepped reveal with no interpolation).
@@ -0,0 +1,114 @@
+---
+name: hyperframes-animejs
+description: Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.
+---
+
+# Anime.js for HyperFrames
+
+HyperFrames can seek Anime.js instances through its `animejs` runtime adapter. The composition owns the animation objects; HyperFrames owns the clock.
+
+## Contract
+
+- Create animations or timelines synchronously during composition initialization.
+- Set `autoplay: false` so Anime.js does not advance on its own clock.
+- Register every returned animation or timeline on `window.__hfAnime`.
+- Use finite durations and loop counts.
+- Avoid callbacks that mutate DOM based on wall-clock time, network state, or unseeded randomness.
+
+The adapter seeks every registered instance with `instance.seek(timeMs)`, where `timeMs` is HyperFrames time in milliseconds.
+
+## Basic Pattern
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/animejs@4.0.2/lib/anime.iife.min.js"></script>
+<script>
+  const anim = anime({
+    targets: ".mark",
+    translateX: 280,
+    rotate: "1turn",
+    opacity: [0, 1],
+    duration: 1200,
+    easing: "easeOutExpo",
+    autoplay: false,
+  });
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(anim);
+</script>
+```
+
+## Timeline Pattern
+
+```html
+<script>
+  const tl = anime.timeline({
+    autoplay: false,
+    easing: "easeOutCubic",
+  });
+
+  tl.add({
+    targets: ".title",
+    translateY: [40, 0],
+    opacity: [0, 1],
+    duration: 650,
+  }).add(
+    {
+      targets: ".accent",
+      scaleX: [0, 1],
+      duration: 450,
+    },
+    250,
+  );
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(tl);
+</script>
+```
+
+## Module Builds
+
+If you use an ES module build, the adapter does not care how the instance was created. It only needs the returned object to expose `seek()`, `pause()`, and preferably `play()`:
+
+```html
+<script type="module">
+  import { animate } from "https://cdn.jsdelivr.net/npm/animejs/+esm";
+
+  const anim = animate(".chip", {
+    x: "18rem",
+    duration: 900,
+    autoplay: false,
+  });
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(anim);
+</script>
+```
+
+## Good Uses
+
+- Small SVG and DOM flourishes where Anime.js syntax is compact.
+- Imported Anime.js examples that can be made seek-driven.
+- Multiple independent micro-animations pushed into the same registry.
+
+Use GSAP for complex scene sequencing unless the user specifically asks for Anime.js. GSAP is still the primary HyperFrames authoring path.
+
+## Avoid
+
+- Leaving `autoplay` at the Anime.js default.
+- Depending on `anime.running` auto-discovery instead of explicit `window.__hfAnime.push(...)`.
+- Infinite loops. Compute a finite repeat count from the composition duration.
+- Building animations in timers, promises, event handlers, or after async asset loads.
+
+## Validation
+
+After editing a composition that uses Anime.js:
+
+```bash
+npx hyperframes lint
+npx hyperframes check
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/animejs.ts`.
+- Anime.js documentation for `autoplay`, `pause()`, and `seek()`: https://animejs.com/documentation/
@@ -0,0 +1,143 @@
+---
+name: hyperframes-css-animations
+description: CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.
+---
+
+# CSS Animations for HyperFrames
+
+HyperFrames can seek CSS keyframe animations through its `css` runtime adapter. Use this for simple repeated motifs, background motion, shimmer, glow, masks, and non-sequenced decoration.
+
+For scene choreography, GSAP is usually clearer. CSS animations work best when the motion belongs to one element and has a fixed duration.
+
+## Contract
+
+- Put the animated element in the DOM before runtime initialization finishes.
+- Give timed elements a `data-start` value so local animation time matches the clip.
+- Use finite `animation-duration` and `animation-iteration-count` because the negative-delay fallback cannot represent unbounded duration in environments without WAAPI-backed CSS animations.
+- Prefer `animation-fill-mode: both` so seeked states hold before and after active motion.
+- Avoid wall-clock JavaScript, hover-triggered state, and class toggles that depend on user events.
+
+The adapter discovers elements with computed `animation-name`, seeks their browser `Animation` handles when available, and falls back to pausing with negative `animation-delay`.
+
+## Basic Pattern
+
+```html
+<div
+  id="pulse-ring"
+  class="clip pulse-ring"
+  data-start="0"
+  data-duration="4"
+  data-track-index="2"
+></div>
+
+<style>
+  .pulse-ring {
+    width: 280px;
+    height: 280px;
+    border: 4px solid rgba(255, 255, 255, 0.7);
+    border-radius: 50%;
+    animation-name: pulse-ring;
+    animation-duration: 1200ms;
+    animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
+    animation-iteration-count: 3;
+    animation-fill-mode: both;
+  }
+
+  @keyframes pulse-ring {
+    from {
+      opacity: 0;
+      transform: scale(0.82);
+    }
+    35% {
+      opacity: 1;
+    }
+    to {
+      opacity: 0;
+      transform: scale(1.18);
+    }
+  }
+</style>
+```
+
+## Stagger Pattern
+
+Use CSS custom properties to avoid duplicating keyframes:
+
+```html
+<div class="clip dots" data-start="1" data-duration="3" data-track-index="3">
+  <span style="--i: 0"></span>
+  <span style="--i: 1"></span>
+  <span style="--i: 2"></span>
+</div>
+
+<style>
+  .dots span {
+    display: inline-block;
+    width: 18px;
+    height: 18px;
+    margin-right: 10px;
+    border-radius: 50%;
+    background: currentColor;
+    animation: dot-pop 900ms ease-out both;
+    animation-delay: calc(var(--i) * 120ms);
+  }
+
+  @keyframes dot-pop {
+    from {
+      opacity: 0;
+      transform: translateY(18px) scale(0.75);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0) scale(1);
+    }
+  }
+</style>
+```
+
+## Good Uses
+
+- Decorative loops with a known repeat count.
+- Mask, glow, shimmer, grain, and subtle parallax layers.
+- Simple one-element entrances where a full JS timeline would be excessive.
+
+## Avoid
+
+- Infinite CSS animations unless you have verified the browser exposes seekable WAAPI-backed CSS animation handles. Prefer a finite iteration count covering the visible duration. If you do use `infinite`, add `data-duration` to the root element — see Composition Duration below.
+- Animating layout properties like `top`, `left`, `width`, or `height` when transforms work.
+- Relying on hover, focus, scroll, or media queries to trigger render-critical motion.
+- Changing animation classes after startup unless another deterministic timeline controls that change.
+
+## Composition Duration
+
+The render engine needs to know the composition's total length. GSAP timelines report this automatically; CSS-only compositions have no timeline object, so the runtime infers duration from the longest running animation's computed end time (`animation-delay` + `animation-duration` × finite `animation-iteration-count`, per element with `data-start` added as an offset). `data-duration` on the root element is optional whenever every CSS animation on the page is finite — you don't need to add it just because the composition is CSS-driven.
+
+`animation-iteration-count: infinite` (or any unresolved/unbounded animation) has no finite end time, so it cannot be auto-inferred. If the composition's only animation is infinite, you **must** add `data-duration="<seconds>"` to the root `[data-composition-id]` element with your intended total length — `npx hyperframes lint` errors on this case (`root_composition_missing_duration_source`) precisely because there is nothing for the runtime to infer.
+
+```html
+<div
+  data-composition-id="root"
+  data-start="0"
+  data-duration="6"
+  data-width="1920"
+  data-height="1080"
+>
+  <div class="clip spinner" data-start="0" style="animation: spin 1s linear infinite"></div>
+</div>
+```
+
+## Validation
+
+After editing CSS animation compositions:
+
+```bash
+npx hyperframes lint
+npx hyperframes check
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/css.ts`.
+- Duration auto-inference: `packages/core/src/runtime/init.ts` (`resolveAdapterDurationFloorSeconds`), `getInferredDurationSeconds` in the adapter above.
+- MDN CSS animation documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation
+- MDN `animation-fill-mode`: https://developer.mozilla.org/en-US/docs/Web/CSS/animation-fill-mode
@@ -0,0 +1,199 @@
+# Easing, Stagger, and Function-Based Values
+
+## Easing
+
+Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`, `none`.
+
+Each has `.in`, `.out`, `.inOut` variants.
+
+| Ease                                       | Use for                                                                                         |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default. |
+| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                            |
+| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                             |
+| `back.out(1.7)`                            | Overshoot then settle. RARE — explicitly-playful register only, never a default.                |
+| `elastic.out(1, 0.3)`                      | Springy bounce. Same playful-only rule; prefer a baked spring (see Spring Eases below).         |
+| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                        |
+| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                        |
+
+Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
+
+**Smooth beats bouncy** — the motion doctrine (`rules/spring-pop-entrance.md`, the workflows' `motion-language.md`): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`) are a rare, explicitly-playful register, never the house style.
+
+## Easing Vocabulary (character & mood)
+
+Easings are tone of voice: a video that only whispers is boring; one that varies between whisper, normal, and punch is engaging. A composition should draw on ~3 easing characters across its beats — but vary **within the smooth families by energy** (`sine` / `power1` calm → `power3` standard → `power4` / `expo` punch); don't reach for overshoot to add variety. Overshoot is a _register_ (explicitly playful), not a spice. One ease everywhere reads flat; bounce everywhere reads cheap — the second failure is worse.
+
+The full palette by character (each family has `.in`, `.out`, `.inOut` variants):
+
+| Family               | Character                                                                    | Typical use                                                                                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | RARE — explicitly-playful register only, never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | RARE — same playful-only rule; the baked spring (below) is the physical version                                                              |
+| `bounce`             | Ball-drop bouncing                                                           | RARE — physical-comedy register only (something literally dropping)                                                                          |
+| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                   |
+| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                                                           |
+| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                              |
+| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                        |
+
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only on explicitly-playful beats. The storyboard's mood description should guide which character fits — not a formula.
+
+## Defaults
+
+```javascript
+const tl = gsap.timeline({
+  paused: true,
+  defaults: { duration: 0.6, ease: "power3.out" }, // the house settle — smooth beats bouncy
+});
+```
+
+Or globally:
+
+```javascript
+gsap.defaults({ duration: 0.6, ease: "power3.out" });
+```
+
+Setting defaults at timeline scope is preferred — it documents the motion language of that composition in one place.
+
+## Spring Eases (baked physics, seek-safe)
+
+The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for the rare playful register — bake the spring's closed-form solution into a function ease.
+
+Why not a real-time spring library: an interactive spring is a stateful integrator (velocity accumulates frame to frame), which cannot be seeked deterministically — you'd have to simulate frames 0…N−1 to render frame N. The closed form below is a **pure function of progress** — no state, nothing to desync, seek-safe by construction. This is also why interaction-lib spring solvers are banned in compositions.
+
+```javascript
+// springEase — a damped spring's exact position curve as a GSAP ease.
+// response         ≈ seconds one oscillation would take (0.3–0.6 for entrances)
+// dampingFraction  1.0       = critically damped — smooth settle, NO overshoot (house default)
+//                  0.80–0.85 ≈ the iOS system register — ~1–1.5% overshoot, felt not seen
+//                  0.60–0.70 = explicitly playful — ~5–10% overshoot (rare; replaces back.out)
+function springEase({ response = 0.5, dampingFraction = 1 } = {}) {
+  const w = (2 * Math.PI) / response; // undamped natural frequency
+  const z = dampingFraction;
+  let pos; // x(t): 0 → 1, starting at rest (v0 = 0)
+  if (z < 1) {
+    const wd = w * Math.sqrt(1 - z * z);
+    pos = (t) => 1 - Math.exp(-z * w * t) * (Math.cos(wd * t) + ((z * w) / wd) * Math.sin(wd * t));
+  } else if (z > 1) {
+    const wo = w * Math.sqrt(z * z - 1);
+    pos = (t) =>
+      1 - Math.exp(-z * w * t) * (Math.cosh(wo * t) + ((z * w) / wo) * Math.sinh(wo * t));
+  } else {
+    pos = (t) => 1 - Math.exp(-w * t) * (1 + w * t);
+  }
+  // Settle time: last moment the curve sits outside ±0.1% of target.
+  // Fixed-step scan, runs once at setup — deterministic (no Math.random / Date.now).
+  const EPS = 0.001;
+  const rate = z <= 1 ? z * w : (z - Math.sqrt(z * z - 1)) * w; // slowest decay mode
+  const SCAN = 12 / rate;
+  const N = 4800;
+  let T = SCAN;
+  for (let i = N; i >= 0; i--) {
+    const t = (i / N) * SCAN;
+    if (Math.abs(1 - pos(t)) > EPS) {
+      T = ((i + 1) / N) * SCAN;
+      break;
+    }
+  }
+  const xT = pos(T);
+  return {
+    duration: T, // use as the tween's duration — the settle time IS the physics
+    ease: (p) => pos(p * T) + p * (1 - xT), // normalized so ease(1) === 1 exactly
+  };
+}
+```
+
+Usage — take **both** the ease and the duration from the helper (the settle time is part of the physics; overriding the duration just re-times the same curve, so tune speed via `response` instead):
+
+```javascript
+const settle = springEase({ response: 0.4 }); // critically damped → duration ≈ 0.59s
+tl.fromTo(
+  "#hero",
+  { scale: 0, opacity: 0 },
+  { scale: 1, opacity: 1, duration: settle.duration, ease: settle.ease },
+  0.2,
+);
+```
+
+| dampingFraction   | overshoot       | register                                                                                                                                           |
+| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
+| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
+| 0.60–0.70         | ~5–10%          | Explicitly-playful ONLY (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
+| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
+
+| response  | duration (ζ=1) | feel                                                         |
+| --------- | -------------- | ------------------------------------------------------------ |
+| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
+| 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
+| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — check the `t ≤ 0.5s` visibility rule |
+
+Craft notes:
+
+- **ζ=1 vs `power3.out`**: the true spring front-loads harder (~67% vs ~58% travelled at quarter-time) and settles on a longer asymptotic tail; max shape difference ~11%. That long tail is the "premium" read — use it when the settle IS the shot (a wordmark landing, a final lockup).
+- **At ζ<1, overshooting curves go on transforms only** — never on `opacity` (it would push past 1) or color. Split opacity onto its own `power2.out` tween at the same timeline position.
+- **Doctrine unchanged**: ζ below ~0.8 is still the rare, explicitly-playful exception (`rules/spring-pop-entrance.md`). The default of this section is ζ=1 — real spring physics is not a license for bounce.
+
+## Stagger
+
+```javascript
+gsap.fromTo(".item", { y: 24, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, stagger: 0.08 });
+```
+
+Object form:
+
+```javascript
+gsap.fromTo(
+  ".item",
+  { y: 24, opacity: 0 },
+  {
+    y: 0,
+    opacity: 1,
+    stagger: {
+      each: 0.08, // delay between each
+      from: "center", // "start" | "end" | "center" | "edges" | "random" | index
+      amount: 0.6, // total stagger time (overrides each if both set)
+      grid: "auto", // for 2D stagger
+      axis: "x" | "y",
+    },
+  },
+);
+```
+
+Prefer `stagger` over N separate tweens with manual delays — it stays correct when the target count or order changes. Use `fromTo()` rather than `from()` so the start state is explicit (see `gsap-timeline-and-labels.md` → sub-composition entrances).
+
+## Function-Based Values
+
+Any var can be a function `(index, target, targets) => value`:
+
+```javascript
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  rotation: (i) => (i % 2 === 0 ? 5 : -5),
+  stagger: 0.1,
+});
+```
+
+Use this for per-element values that depend on index, attributes, or measured size. Cheaper and more idiomatic than building tweens in a loop.
+
+## gsap.matchMedia (preview only)
+
+`matchMedia` runs setup only when a media query matches and auto-reverts when it stops matching. It is useful for **preview** in the browser at different viewport sizes, and for `prefers-reduced-motion`. It is **not** a substitute for rendering at the composition's actual `data-width`/`data-height` — HyperFrames renders at a fixed viewport.
+
+```javascript
+let mm = gsap.matchMedia();
+mm.add(
+  {
+    isDesktop: "(min-width: 800px)",
+    reduceMotion: "(prefers-reduced-motion: reduce)",
+  },
+  (context) => {
+    const { isDesktop, reduceMotion } = context.conditions;
+    gsap.to(".box", {
+      rotation: isDesktop ? 360 : 180,
+      duration: reduceMotion ? 0 : 2,
+    });
+  },
+);
+```
@@ -0,0 +1,96 @@
+# Timelines and Labels
+
+HyperFrames is a seek-driven runtime. Build one paused timeline per composition, attach it to `window.__timelines["<composition-id>"]`, and let HyperFrames seek it. Never call `.play()` for render-critical motion.
+
+## Creating a Timeline
+
+```javascript
+const tl = gsap.timeline({
+  paused: true,
+  defaults: { duration: 0.5, ease: "power3.out" },
+});
+
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
+```
+
+Timeline options:
+
+- **paused: true** — required in HyperFrames. The framework drives the playhead.
+- **repeat**, **yoyo** — apply to the whole timeline. `repeat: -1` is forbidden; use finite counts.
+- **defaults** — vars merged into every child tween. Use this instead of repeating `ease` and `duration` on every line.
+
+## Position Parameter
+
+The third argument to `.to()`/`.from()`/`.fromTo()` controls placement on the timeline:
+
+| Form           | Meaning                              |
+| -------------- | ------------------------------------ |
+| `0`, `1.5`     | Absolute time in seconds             |
+| `"+=0.5"`      | 0.5s after the end of the timeline   |
+| `"-=0.2"`      | 0.2s before the end of the timeline  |
+| `"intro"`      | At the `intro` label                 |
+| `"intro+=0.3"` | 0.3s after the `intro` label         |
+| `"<"`          | Same start as the previous tween     |
+| `">"`          | Right after the previous tween ends  |
+| `"<0.2"`       | 0.2s after the previous tween starts |
+| `">-0.1"`      | 0.1s before the previous tween ends  |
+
+```javascript
+tl.to(".a", { x: 100 }, 0);
+tl.to(".b", { y: 50 }, "<"); // same start as .a
+tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts
+```
+
+Prefer the position parameter over `delay:` — it composes naturally and survives refactors that re-order tweens.
+
+## Labels
+
+```javascript
+tl.addLabel("intro", 0);
+tl.to(".a", { x: 100 }, "intro");
+
+tl.addLabel("outro", "+=0.5");
+tl.to(".a", { opacity: 0 }, "outro");
+```
+
+Labels make a long timeline readable and let multiple tweens converge on the same beat without re-typing absolute times.
+
+## Nesting Timelines
+
+```javascript
+const master = gsap.timeline({ paused: true });
+
+const child = gsap.timeline();
+child.to(".a", { x: 100 }).to(".b", { y: 50 });
+
+master.add(child, 0);
+```
+
+In HyperFrames, **do not** nest sub-composition timelines into the host. Sub-compositions loaded via `data-composition-src` are seeked independently by HyperFrames from their own `data-start`. Nesting is only for grouping pieces of the _same_ composition's timeline.
+
+## Inside Sub-Compositions: prefer `fromTo` over `from`
+
+For entrance tweens inside a sub-composition, prefer `gsap.fromTo()` over `gsap.from()`:
+
+```javascript
+// Sub-composition entrance — survives re-seek cleanly
+tl.fromTo(".title", { y: 60, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6 }, 0.2);
+```
+
+Why: HyperFrames re-seeks the sub-composition every time its host clip becomes visible. `gsap.from()` snapshots the starting state at **registration time** (page load); when the playhead jumps back past `data-start`, that snapshot can desync from the actual CSS state and the element renders in the wrong position. `gsap.fromTo()` declares both endpoints explicitly, so the seek-back always produces the same start state.
+
+In top-level (standalone) compositions either form works — there's no re-seek-through-mount cycle.
+
+## Playback Control (debug / preview only)
+
+```javascript
+tl.play();
+tl.pause();
+tl.reverse();
+tl.restart();
+tl.time(2);
+tl.progress(0.5);
+tl.kill();
+```
+
+These are useful when previewing in the browser. In rendered output HyperFrames calls `seek()` internally — your timeline must produce identical state for the same time value every time it is seeked.
@@ -0,0 +1,128 @@
+# Transforms and Performance
+
+## Transform Aliases
+
+Prefer GSAP's transform aliases over raw `transform` strings:
+
+| GSAP property               | Equivalent            |
+| --------------------------- | --------------------- |
+| `x`, `y`, `z`               | `translateX/Y/Z` (px) |
+| `xPercent`, `yPercent`      | `translateX/Y` in `%` |
+| `scale`, `scaleX`, `scaleY` | `scale`               |
+| `rotation`                  | `rotate` (deg)        |
+| `rotationX`, `rotationY`    | 3D rotate             |
+| `skewX`, `skewY`            | `skew`                |
+| `transformOrigin`           | `transform-origin`    |
+
+Aliases let GSAP track and interpolate each axis independently, which prevents accidental overwrites between separate tweens on the same element.
+
+## autoAlpha
+
+Prefer `autoAlpha` over `opacity` for show/hide:
+
+```javascript
+gsap.to(".panel", { autoAlpha: 0, duration: 0.4 });
+```
+
+`autoAlpha: 0` sets both `opacity: 0` and `visibility: hidden`, which removes the element from hit-testing and accessibility tree at zero alpha — closer to "gone" than plain `opacity: 0`.
+
+## clearProps
+
+Removes inline styles set by GSAP when the tween completes:
+
+```javascript
+gsap.to(".item", { x: 100, rotation: 45, clearProps: "all" });
+gsap.to(".item", { x: 100, rotation: 45, clearProps: "rotation,x" });
+```
+
+Useful at the end of an animation segment to hand the element back to CSS.
+
+## CSS Variables
+
+```javascript
+gsap.to(".chart", { "--hue": 180, duration: 1 });
+```
+
+Animate any custom property. Works for color, length, number — anything CSS will interpolate.
+
+## Relative and Directional Values
+
+- Relative: `"+=20"`, `"-=10"`, `"*=2"`.
+- Directional rotation: `"360_cw"`, `"-170_short"`, `"90_ccw"` — controls which way the angle takes when going between two values.
+
+## SVG Specifics
+
+- `svgOrigin` sets transform origin in the SVG's global coordinate space (not the element's local box). **Do not** combine `svgOrigin` with `transformOrigin` on the same element — pick one.
+- Animate SVG transform attributes via the same alias names (`x`, `y`, `rotation`) — GSAP handles the SVG-specific quirks.
+
+## Performance Rules
+
+### Animate transforms, not layout properties
+
+Animate `x`, `y`, `scale`, `rotation`, `opacity`. Never animate `left`, `right`, `top`, `bottom`, `width`, `height`, `margin*`, the text-reflow props `letterSpacing` / `wordSpacing` / `fontSize` — and never `roundProps`.
+
+This is a **render-correctness** rule in HyperFrames, not just a GPU-performance nicety. The renderer seeks frame-by-frame and screenshots each frame, and the browser compositor snaps layout properties to whole device pixels. On a fast tween the per-frame step is several pixels, so the snap is invisible; on a slow tween or a long ease-out tail the value moves less than a pixel per frame — it holds the same pixel for several frames, then jumps a whole one. The result is motion that looks smooth when fast but visibly stutters when slow. Transforms interpolate sub-pixel and stay smooth at any speed. `roundProps` forces the same integer snap onto a transform — don't use it.
+
+"Layout property" is broader than position: anything that triggers **reflow** snaps the same way. `letterSpacing` / `fontSize` are the common trap — a slow "settle" that crawls one of them by a fraction of a pixel per frame dwells on a handful of discrete glyph layouts (visible micro-stutter). The faithful smooth fix depends on which property — **do not reach for `scale` reflexively**:
+
+- **`fontSize`** → animate `scale`. Scaling text up/down is the same visual and stays sub-pixel smooth (no reflow).
+- **`letterSpacing` / `wordSpacing`** → uniform `scale` is **not** the same effect (it resizes the glyphs; it does not change the gaps between them). To animate spacing smoothly, split the text into per-character (or per-word) elements and animate each one's `x` — the glyph spread is a transform, sub-pixel smooth and visually identical to a letter-spacing tween. GSAP's `SplitText` does the split. If the spacing change is a minor flourish, hold the final value statically instead.
+
+Unlike positional props, reflow props snap during browser **layout** — upstream of the canvas raster — so they stutter even in html-in-canvas, and the exception below does **not** apply to them.
+
+#### Fixing a flagged animation — preserve the intent
+
+The lint rule tells you a property will stutter; it does **not** tell you the fix, and a fix that merely passes lint can silently change the look. Swapping a `letterSpacing` tighten for a uniform `scale` lints clean but animates a _different thing_ (it resizes the glyphs instead of closing the gaps). Two rules:
+
+1. **Reproduce the same visual** — same start/end state, same trajectory, only sub-pixel-smooth. Use the faithful equivalent (per-glyph `x` for spacing, `scale` for `fontSize`, `x`/`y` for position), not whichever transform is the least code.
+2. **Verify against the original, not against the linter.** Render the original and the fixed version and compare the motion at its key moments — the fix should differ only by the removed stutter, not by _where things end up_. Lint-clean-and-smooth is not the bar; faithful-and-smooth is.
+
+If the faithful fix is non-trivial (a per-glyph split, a measured offset), build it or surface the tradeoff — never downgrade to a cheaper, different effect just to satisfy the linter.
+
+**Convert a position animation to a transform** by leaving the element at its resting `left`/`top` in CSS and animating the _offset_ with `x`/`y`:
+
+```javascript
+// CSS: #card { left: 1340px; top: 540px }   ← resting position stays in CSS
+tl.to("#card", { left: 1340, top: 540, duration: 1 }); // ✗ stutters
+tl.fromTo("#card", { x: 640, y: 0 }, { x: 0, y: 0, duration: 1 }); // ✓ x/y = delta from CSS rest (640 = startLeft − 1340)
+```
+
+For a parent-relative `left: "100%"` sweep, use `xPercent: 100` only when the element is the full width of its container; otherwise convert to pixels (`x: containerWidth`).
+
+**The one exception:** elements drawn through the html-in-canvas API — those under a `<canvas layoutsubtree>` ancestor, e.g. the `liquid-glass-*` blocks. The canvas rasterizes from sub-pixel `getComputedStyle`, so layout props don't snap there and those elements keep `left`/`top`. Everything the browser lays out (plain DOM) follows the rule.
+
+The `gsap_non_transform_motion` lint rule is the backstop, not the teacher — reach for transforms from the start instead of animating layout props and waiting for lint to reject them.
+
+### will-change (sparingly)
+
+```css
+.title {
+  will-change: transform;
+}
+```
+
+Only on elements that _actually_ animate. Applied everywhere it becomes useless and burns memory.
+
+### gsap.quickTo for frequent updates (preview-only)
+
+For high-frequency updates driven by **events** — pointer move, scroll, audio scrub — `quickTo` reuses the same tween instead of creating a new one each frame:
+
+```javascript
+const xTo = gsap.quickTo("#cursor", "x", { duration: 0.4, ease: "power3" });
+const yTo = gsap.quickTo("#cursor", "y", { duration: 0.4, ease: "power3" });
+
+container.addEventListener("mousemove", (e) => {
+  xTo(e.pageX);
+  yTo(e.pageY);
+});
+```
+
+> **Render mode has no input events.** The renderer seeks frame-by-frame; `mousemove`, `scroll`, etc. never fire. `quickTo`'s main use case applies in **live preview** in the browser only. For audio-reactive motion in renders, pre-extract audio data and drive the timeline declaratively (see `../rules/gsap-effects.md`).
+
+### Stagger beats N tweens
+
+One tween with `stagger` beats N tweens with manual delays for both readability and runtime cost.
+
+### Cleanup
+
+In live preview, pause or `kill()` off-screen animations. Render mode is unaffected (the renderer drives time directly).
@@ -0,0 +1,105 @@
+---
+name: hyperframes-gsap-adapter
+description: GSAP animation API reference for HyperFrames. Use when writing seekable GSAP timelines in HyperFrames compositions, including gsap.to(), from(), fromTo(), set(), timeline position parameters, labels, easing, stagger, finite repeats, and transform performance.
+---
+
+# HyperFrames GSAP
+
+GSAP usage scoped to HyperFrames' seek-driven render model. This skill is the GSAP reference _as constrained by HyperFrames_ — for the framework's broader composition contract see `hyperframes-core`.
+
+## HyperFrames Contract
+
+HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
+  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
+
+  window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root
+</script>
+```
+
+- The registry key must match the composition root's `data-composition-id`.
+- Bracket and dot syntax both register: `window.__timelines["main"] = tl` and `window.__timelines.main = tl` are equivalent (the linter recognizes both). Bracket form is required when the id isn't a valid identifier (e.g. contains `-`).
+- Do not call `tl.play()` for render-critical motion.
+- Do not build timelines inside async code, timers, or event handlers.
+- Keep loops finite. HyperFrames renders finite video durations.
+- **Render duration comes from `data-duration` on the composition root, not from GSAP timeline length.** Do not pad the timeline with empty tweens like `tl.set({}, {}, 283)` to "extend" it. (Some external docs show this trick; in HyperFrames it conflicts with the seek-driven duration model — set `data-duration` instead.)
+
+## Core Tween Methods
+
+- **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
+- **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).
+- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.
+- **gsap.set(targets, vars)** — apply immediately (duration 0).
+
+Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).
+
+## Common vars (cheatsheet)
+
+- **duration** — seconds (default 0.5).
+- **delay** — seconds before start.
+- **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`. See `./gsap-easing-and-stagger.md`.
+- **stagger** — number or object. See `./gsap-easing-and-stagger.md`.
+- **repeat** — finite number; never `-1` in HyperFrames. Compute repeats from the visible duration.
+- **yoyo** — alternates direction with repeat.
+- **overwrite** — `false` (default), `true`, or `"auto"`.
+- **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element.
+- **onComplete**, **onStart**, **onUpdate** — callbacks.
+
+For transforms, autoAlpha, clearProps, and SVG specifics see `./gsap-transforms-and-perf.md`.
+
+## Animated Property Allowlist
+
+HyperFrames is stricter than vanilla GSAP. Animate only:
+
+- **Compositor-cheap**: `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`
+- **Visual fills**: `color`, `backgroundColor`, `borderColor`, `borderRadius`
+- **CSS variables**: `"--hue": 180` etc.
+- **Media `volume`** (on `<audio>` / `<video>`): animate for fades/ducking, e.g. `tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`. The runtime probes these keyframes from the timeline and drives them in both preview and render (they match). This sets the _author_ volume; `data-volume` is the static baseline when no tween touches the element.
+- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Equivalent to the `onUpdate`-proxy form in `../rules/counting-dynamic-scale.md`; prefer that proxy form when you must also drive font-size, locale formatting (`toLocaleString`), or a suffix in the same tween.
+
+**Avoid** (use the transform alias instead):
+
+- `width` / `height` / `top` / `left` / `right` / `bottom` / `margin*` / `padding*` — trigger layout reflows. Use `scaleX/Y` (with `transformOrigin`) or `x` / `y`.
+
+**Forbidden** (breaks the renderer or the clip lifecycle):
+
+- `display`, `visibility` — never tween these directly. Use `autoAlpha` (sets opacity + visibility together at endpoints, doesn't tween the discrete property).
+- Anything driven by `Math.random()`, `Date.now()`, `performance.now()`, or event handlers — animation state must be deterministic from time alone.
+
+> **Note**: `docs/guides/gsap-animation.mdx` lists `width`/`height`/`visibility` in its "Supported Properties" — that list is too permissive for HyperFrames composition rules. This allowlist is the canonical one. See `hyperframes-core/references/determinism-rules.md` for the full deterministic-render contract.
+
+## References
+
+- `./gsap-timeline-and-labels.md` — timeline creation, position parameter (`+=`, `<`, `>`), labels, nesting, sub-comp `fromTo` preference, playback control.
+- `./gsap-easing-and-stagger.md` — easing families, stagger objects, function-based values, `gsap.matchMedia()`, `gsap.defaults()`.
+- `./gsap-transforms-and-perf.md` — transform aliases, autoAlpha, `quickTo`, `will-change`, performance rules.
+- `../rules/gsap-effects.md` — drop-in recipes: typewriter (with cursor / backspace / word rotation) + audio visualizer (uses `skills/hyperframes-creative/scripts/extract-audio-data.py`).
+
+## Best Practices
+
+- Use camelCase property names; prefer transform aliases and autoAlpha.
+- Prefer timelines over chained tweens with delays; use the position parameter.
+- Add labels with `addLabel()` for readable sequencing.
+- Pass defaults into the timeline constructor.
+- Store the tween/timeline return value when controlling playback.
+
+## Do Not
+
+- Animate layout properties (`width`/`height`/`top`/`left`) when transforms suffice.
+- Use both `svgOrigin` and `transformOrigin` on the same SVG element.
+- Chain animations with `delay` when a timeline can sequence them.
+- Create tweens before the DOM exists.
+- Use infinite `repeat: -1` in HyperFrames compositions — use finite repeat counts computed from the visible duration.
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/gsap.ts`.
+- GSAP documentation: https://gsap.com/docs/v3/
+- GSAP timeline pause and seek behavior: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/
@@ -0,0 +1,507 @@
+# HTML-in-Canvas Patterns
+
+HyperFrames' most powerful visual capability. Capture ANY live HTML/CSS as a GPU texture, then render it through WebGL shaders, Three.js 3D scenes, or post-processing effects — at 60fps, pixel-perfect, with every CSS feature supported.
+
+**Read this file when a beat deserves cinematic treatment beyond flat GSAP animations.** Use for 1-3 hero beats per video, not every beat. The rest can use standard GSAP — the contrast between flat beats and HTML-in-Canvas beats IS part of the visual storytelling.
+
+---
+
+## Core Boilerplate (same in every HTML-in-Canvas composition)
+
+Every HTML-in-Canvas effect shares this structure. Learn this once, adapt it for any effect.
+
+```html
+<!-- 1. Source HTML — your content goes inside a layoutsubtree canvas -->
+<canvas
+  id="hic-source"
+  layoutsubtree
+  width="1920"
+  height="1080"
+  style="position:absolute;inset:0;opacity:0;"
+>
+  <div id="hic-content" style="width:1920px;height:1080px;">
+    <!-- YOUR HTML CONTENT HERE — text, images, cards, dashboards, anything -->
+  </div>
+</canvas>
+
+<!-- 2. Render target — the visible canvas that shows the effect -->
+<canvas id="hic-output" width="1920" height="1080" style="position:absolute;inset:0;"></canvas>
+```
+
+```js
+// 3. Feature detection — always check, always provide fallback
+function isHiCSupported() {
+  var tc = document.createElement("canvas");
+  if (!("layoutSubtree" in tc)) return false;
+  tc.setAttribute("layoutsubtree", "");
+  var ctx = tc.getContext("2d");
+  return ctx && typeof ctx.drawElementImage === "function";
+}
+var apiOk = isHiCSupported();
+
+// 4. Capture function — call this every frame in onUpdate
+var capCanvas = document.getElementById("hic-source");
+var capCtx = capCanvas.getContext("2d");
+function captureContent() {
+  if (apiOk) {
+    capCtx.drawElementImage(document.getElementById("hic-content"), 0, 0, 1920, 1080);
+  }
+}
+
+// 5. Drive from GSAP timeline — capture + render every frame
+tl.to(
+  proxy,
+  {
+    /* your animation properties */
+    duration: BEAT_DURATION,
+    ease: "sine.inOut",
+    onUpdate: function () {
+      captureContent();
+      // render your effect here (Three.js or WebGL2)
+    },
+  },
+  0,
+);
+```
+
+**Fallback:** When `drawElementImage` is not available (preview without Chrome flag), draw a solid-color placeholder or use Canvas 2D text. The HyperFrames renderer auto-enables the flag — the effect WILL work in the final video. See the liquid-glass block for a complete fallback example.
+
+---
+
+## Effect Catalog
+
+### 1. 3D Rotation with Bloom (Three.js)
+
+**What it looks like:** Content floats in 3D space, slowly rotating with cinematic glow around bright edges. Like a product screenshot displayed in a dark theater.
+
+**When to use:** Hero product showcase, feature reveal, CTA with premium feel.
+
+**Key Three.js components:** `PlaneGeometry` + `CanvasTexture` + `EffectComposer` + `UnrealBloomPass`
+
+```js
+// After the boilerplate above, add:
+var scene3d = new THREE.Scene();
+var camera = new THREE.PerspectiveCamera(45, 1920 / 1080, 0.1, 100);
+camera.position.set(0, 0, 4);
+
+var renderer = new THREE.WebGLRenderer({
+  canvas: document.getElementById("hic-output"),
+  antialias: true,
+  alpha: true,
+});
+renderer.setSize(1920, 1080);
+
+var texture = new THREE.CanvasTexture(capCanvas);
+var mesh = new THREE.Mesh(
+  new THREE.PlaneGeometry(3.6, 2.2),
+  new THREE.MeshBasicMaterial({ map: texture }),
+);
+scene3d.add(mesh);
+
+// Post-processing: bloom for cinematic glow.
+// EffectComposer / RenderPass / UnrealBloomPass are ES-module named imports
+// (see the import block below) — they're NOT properties of THREE in modern
+// versions. Three.js r150+ removed the UMD `examples/js/` globals.
+var composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene3d, camera));
+composer.addPass(new UnrealBloomPass(new THREE.Vector2(1920, 1080), 0.3, 0.4, 0.85));
+
+var proxy = { rotY: -0.12, zoom: 4.2 };
+tl.to(
+  proxy,
+  {
+    rotY: 0.12,
+    zoom: 3.6,
+    duration: BEAT_DURATION,
+    ease: "sine.inOut",
+    onUpdate: function () {
+      captureContent();
+      texture.needsUpdate = true;
+      mesh.rotation.y = proxy.rotY;
+      camera.position.z = proxy.zoom;
+      composer.render();
+    },
+  },
+  0,
+);
+```
+
+**Load Three.js and post-processing via ESM (use a `type="module"` script):**
+
+```html
+<script type="module">
+  import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm";
+  import { EffectComposer } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/EffectComposer.js";
+  import { RenderPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/RenderPass.js";
+  import { ShaderPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/ShaderPass.js";
+  import { UnrealBloomPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/UnrealBloomPass.js";
+  // ... rest of composition code using these imports
+</script>
+```
+
+The `examples/js/` path was removed in Three.js r152. Use `examples/jsm/` (ES modules) with `three@0.181.2` — the version used by the HyperFrames Three.js adapter.
+
+---
+
+### 2. Magnetic Cursor Distortion (Raw WebGL2)
+
+**What it looks like:** Content warps and bends toward a moving point, like a magnet pulling on pixels. Chromatic aberration splits RGB channels at the distortion site.
+
+**When to use:** Interactive feel, product demo with cursor, "look at THIS feature" moment.
+
+**Key technique:** Custom fragment shader with Gaussian warp + chromatic split. No Three.js needed — just raw WebGL2.
+
+```js
+// WebGL2 setup
+var gl = document.getElementById("hic-output").getContext("webgl2", {
+  alpha: false,
+  preserveDrawingBuffer: true,
+});
+
+// Vertex shader — full-screen quad
+var VS = `#version 300 es
+in vec2 a_pos;
+out vec2 v_uv;
+void main() {
+  v_uv = a_pos * 0.5 + 0.5;
+  gl_Position = vec4(a_pos, 0.0, 1.0);
+}`;
+
+// Fragment shader — magnetic warp + chromatic aberration
+var FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_tex;
+uniform vec2 u_cursor;   // cursor position (0-1)
+uniform float u_strength; // warp strength (0-1)
+
+void main() {
+  vec2 uv = v_uv;
+  vec2 delta = uv - u_cursor;
+  float dist = length(delta);
+  float warp = u_strength * exp(-dist * dist * 8.0);
+  vec2 warped = uv - delta * warp * 0.3;
+
+  // Chromatic aberration at distortion site
+  float aberration = warp * 0.008;
+  float r = texture(u_tex, warped + vec2(aberration, 0.0)).r;
+  float g = texture(u_tex, warped).g;
+  float b = texture(u_tex, warped - vec2(aberration, 0.0)).b;
+  fragColor = vec4(r, g, b, 1.0);
+}`;
+
+// Compile, link, setup quad geometry, upload texture...
+// (See registry/blocks/vfx-magnetic/vfx-magnetic.html for complete implementation)
+
+// Drive cursor position from GSAP
+var proxy = { cx: 0.2, cy: 0.5, strength: 0.0 };
+tl.to(
+  proxy,
+  {
+    cx: 0.8,
+    cy: 0.4,
+    strength: 1.0,
+    duration: BEAT_DURATION,
+    ease: "power2.inOut",
+    onUpdate: function () {
+      captureContent();
+      // Upload texture, set uniforms, draw
+      gl.uniform2f(cursorLoc, proxy.cx, proxy.cy);
+      gl.uniform1f(strengthLoc, proxy.strength);
+      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+    },
+  },
+  0,
+);
+```
+
+---
+
+### 3. Shatter / Fragment Explosion (Three.js)
+
+**What it looks like:** Content breaks into geometric fragments that fly apart, revealing what's behind.
+
+**When to use:** Dramatic transition, "breaking free" moment, tension release.
+
+**Key technique:** Subdivide the source texture into triangle mesh fragments using BufferGeometry, then animate each fragment's position/rotation with GSAP.
+
+Study `registry/blocks/vfx-shatter/vfx-shatter.html` for the complete 1156-line implementation. The core idea:
+
+```js
+// 1. Capture content to texture (same boilerplate)
+// Seeded PRNG for determinism — Math.random() is banned
+function mulberry32(seed) {
+  return function () {
+    seed |= 0;
+    seed = (seed + 0x6d2b79f5) | 0;
+    var t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+var rng = mulberry32(42);
+
+// 2. Create N triangle fragments from the texture
+var fragments = [];
+for (var i = 0; i < NUM_FRAGMENTS; i++) {
+  var geom = new THREE.BufferGeometry();
+  var mesh = new THREE.Mesh(geom, new THREE.MeshBasicMaterial({ map: texture }));
+  scene3d.add(mesh);
+  fragments.push({ mesh: mesh, targetPos: randomExplosionVector(rng), delay: rng() * 0.5 });
+}
+
+// 3. Animate: first hold still, then EXPLODE
+tl.to({}, { duration: holdTime }, 0);
+fragments.forEach(function (frag) {
+  tl.to(
+    frag.mesh.position,
+    {
+      x: frag.targetPos.x,
+      y: frag.targetPos.y,
+      z: frag.targetPos.z,
+      duration: 0.8,
+      ease: "power3.in",
+    },
+    holdTime + frag.delay,
+  );
+  tl.to(
+    frag.mesh.rotation,
+    { x: rng() * 4, y: rng() * 4, duration: 0.8, ease: "power2.in" },
+    holdTime + frag.delay,
+  );
+});
+```
+
+---
+
+### 4. Liquid / Fluid Surface (Three.js)
+
+**What it looks like:** Content floats above a rippling liquid surface with real-time wave dynamics. Or content IS the surface, undulating like water.
+
+**When to use:** Organic/premium feel, ambient background, "living" product showcase.
+
+**Key technique:** Subdivided PlaneGeometry with vertex displacement driven by noise functions in a vertex shader.
+
+Study `registry/blocks/vfx-liquid-background/vfx-liquid-background.html` for the 1244-line implementation. Core idea:
+
+```js
+// Custom vertex shader with wave displacement
+var vertexShader = `
+  varying vec2 vUv;
+  uniform float u_time;
+  void main() {
+    vUv = uv;
+    vec3 pos = position;
+    // Sine wave displacement
+    pos.z += sin(pos.x * 3.0 + u_time * 2.0) * 0.15;
+    pos.z += cos(pos.y * 2.5 + u_time * 1.5) * 0.1;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
+  }
+`;
+
+var mesh = new THREE.Mesh(
+  new THREE.PlaneGeometry(4, 3, 64, 64), // heavily subdivided for smooth waves
+  new THREE.ShaderMaterial({
+    vertexShader: vertexShader,
+    fragmentShader: `varying vec2 vUv; uniform sampler2D u_tex;
+      void main() { gl_FragColor = texture2D(u_tex, vUv); }`,
+    uniforms: {
+      u_tex: { value: texture },
+      u_time: { value: 0 },
+    },
+  }),
+);
+```
+
+---
+
+### 5. Portal / Dimensional Reveal (Three.js)
+
+**What it looks like:** A glowing circular portal opens and content emerges through it from another dimension.
+
+**When to use:** Product reveal, "entering the app" moment, hero feature introduction.
+
+Study `registry/blocks/vfx-portal/vfx-portal.html` for the complete 863-line implementation.
+
+---
+
+## When to Use HTML-in-Canvas vs Standard GSAP
+
+| Scenario                         | Use                                  | Why                                  |
+| -------------------------------- | ------------------------------------ | ------------------------------------ |
+| Hero product screenshot showcase | HTML-in-Canvas (3D rotation + bloom) | Makes flat UI feel cinematic         |
+| Feature list / stats             | Standard GSAP                        | Content-focused, doesn't need 3D     |
+| CTA / brand reveal               | HTML-in-Canvas (portal or magnetic)  | Makes the moment memorable           |
+| Social proof / logos             | Standard GSAP                        | Orderly cascade, trust is steady     |
+| Transition between acts          | HTML-in-Canvas (shatter)             | Dramatic act break                   |
+| Background atmosphere            | HTML-in-Canvas (liquid surface)      | Premium ambient feel                 |
+| Quick feature cards              | Standard GSAP                        | Speed matters, 3D would slow it down |
+
+---
+
+## More Effects You Can Build
+
+These aren't in the VFX blocks — build them yourself from the core boilerplate + a custom fragment shader. Each effect is a single GLSL function applied to the captured texture.
+
+### 6. Noise Dissolve
+
+Content dissolves into noise particles, revealing what's behind. Great for transitions.
+
+```glsl
+// Fragment shader — noise-based dissolve
+uniform float u_progress; // 0.0 = fully visible, 1.0 = fully dissolved
+uniform sampler2D u_tex;
+
+float hash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
+}
+
+void main() {
+  vec2 uv = v_uv;
+  float noise = hash(uv * 50.0);
+  float threshold = u_progress;
+  if (noise < threshold) {
+    // Edge glow at the dissolve boundary
+    float edge = smoothstep(threshold - 0.05, threshold, noise);
+    fragColor = vec4(1.0, 0.6, 0.2, 1.0) * (1.0 - edge); // orange edge glow
+  } else {
+    fragColor = texture(u_tex, uv);
+  }
+}
+```
+
+### 7. Holographic / Iridescent
+
+Content gets a rainbow-shifting holographic sheen that moves with time. Premium, futuristic feel.
+
+```glsl
+uniform float u_time;
+uniform sampler2D u_tex;
+
+void main() {
+  vec4 color = texture(u_tex, v_uv);
+  // Iridescent color shift based on position + time
+  float angle = v_uv.x * 6.28 + v_uv.y * 3.14 + u_time * 0.5;
+  vec3 holo = vec3(
+    sin(angle) * 0.5 + 0.5,
+    sin(angle + 2.094) * 0.5 + 0.5,
+    sin(angle + 4.189) * 0.5 + 0.5
+  );
+  // Blend holographic over content (subtle overlay)
+  fragColor = vec4(mix(color.rgb, holo, 0.15 + 0.1 * sin(u_time)), color.a);
+}
+```
+
+### 8. Scan Lines + CRT
+
+Retro CRT monitor look — scan lines, slight curvature, phosphor glow. Great for "code" or "terminal" beats.
+
+```glsl
+uniform sampler2D u_tex;
+uniform float u_time;
+
+void main() {
+  vec2 uv = v_uv;
+  // Barrel distortion (CRT curvature)
+  vec2 centered = uv - 0.5;
+  float dist = dot(centered, centered);
+  uv = uv + centered * dist * 0.15;
+
+  vec4 color = texture(u_tex, uv);
+  // Scan lines
+  float scanline = sin(uv.y * 800.0) * 0.04;
+  color.rgb -= scanline;
+  // Slight RGB offset (phosphor)
+  color.r = texture(u_tex, uv + vec2(0.001, 0.0)).r;
+  color.b = texture(u_tex, uv - vec2(0.001, 0.0)).b;
+  // Vignette
+  float vignette = 1.0 - dist * 2.0;
+  fragColor = vec4(color.rgb * vignette, 1.0);
+}
+```
+
+### 9. Frosted Glass Blur
+
+Content behind frosted glass — visible but softened, with subtle light refraction. Good for "behind the scenes" or "coming soon" moments.
+
+```glsl
+uniform sampler2D u_tex;
+uniform float u_blur; // 0.0 = clear, 1.0 = full frost
+
+void main() {
+  vec2 uv = v_uv;
+  vec4 color = vec4(0.0);
+  // Box blur with offset
+  float radius = u_blur * 0.015;
+  for (float x = -2.0; x <= 2.0; x += 1.0) {
+    for (float y = -2.0; y <= 2.0; y += 1.0) {
+      color += texture(u_tex, uv + vec2(x, y) * radius);
+    }
+  }
+  color /= 25.0;
+  // Add frost noise texture
+  float frost = fract(sin(dot(uv * 200.0, vec2(12.9898, 78.233))) * 43758.5453);
+  color.rgb += frost * 0.03 * u_blur;
+  fragColor = color;
+}
+```
+
+### 10. Pixel Sort / Glitch Art
+
+Pixels rearrange themselves in vertical or horizontal strips — digital art aesthetic. Great for tech/creative brands.
+
+```glsl
+uniform sampler2D u_tex;
+uniform float u_intensity; // 0-1
+
+void main() {
+  vec2 uv = v_uv;
+  // Random horizontal displacement per row
+  float row = floor(uv.y * 80.0);
+  float noise = fract(sin(row * 127.1) * 43758.5);
+  float displace = step(0.7, noise) * u_intensity * 0.1;
+  // Shift UV with RGB split
+  float r = texture(u_tex, uv + vec2(displace, 0.0)).r;
+  float g = texture(u_tex, uv).g;
+  float b = texture(u_tex, uv - vec2(displace * 0.5, 0.0)).b;
+  fragColor = vec4(r, g, b, 1.0);
+}
+```
+
+---
+
+## Creating ANY Custom Effect
+
+The fragment shaders above are templates. The pattern is always:
+
+1. **Capture your HTML content** with `drawElementImage` (the boilerplate at the top)
+2. **Upload the captured canvas as a WebGL texture**
+3. **Write a fragment shader** that reads from the texture and outputs modified colors
+4. **Drive shader uniforms from GSAP** via `onUpdate`
+
+Any GLSL effect from ShaderToy, The Book of Shaders, CodePen, or anywhere else can be adapted:
+
+1. Find an effect you like (search "GLSL [effect name]" or browse shadertoy.com)
+2. Copy the fragment shader
+3. Replace `iResolution` with `vec2(1920.0, 1080.0)`, `iTime` with your `u_time` uniform
+4. Add `uniform sampler2D u_tex;` for the captured content texture
+5. Wire the uniforms to GSAP proxy values
+
+**Geometry ideas beyond flat planes:**
+
+- `SphereGeometry` — content mapped onto a globe (world map, global reach)
+- `CylinderGeometry` — content on a rotating cylinder (carousel/scroll feel)
+- `TorusGeometry` — content wrapped around a ring (infinity, cycle)
+- `BoxGeometry` — content on a 3D box (product packaging, dice)
+- GLTF models — content mapped as screen texture on phone, laptop, monitor (see `vfx-iphone-device`)
+
+**Post-processing stacking** (Three.js EffectComposer):
+
+- Bloom + film grain = cinematic
+- Bloom + chromatic aberration = lens effect
+- Depth of field + vignette = focused attention
+- Film grain + scan lines = retro
+- Multiple passes stack — add as many as you want
+
+**You are not limited to the effects listed here.** If you can imagine a visual treatment, you can build it. The HTML-in-Canvas API gives you the source material (any HTML rendered as a texture), and WebGL/Three.js gives you unlimited creative control over how that material is presented.
@@ -0,0 +1,117 @@
+---
+name: hyperframes-lottie
+description: Lottie and dotLottie adapter patterns for HyperFrames. Use when embedding lottie-web JSON animations, .lottie files, @lottiefiles/dotlottie-web players, registering instances on window.__hfLottie, or making After Effects exports deterministic in HyperFrames.
+---
+
+# Lottie for HyperFrames
+
+HyperFrames can seek both `lottie-web` and dotLottie players through its `lottie` runtime adapter. Lottie is a strong fit because the animation timeline is already encoded in the asset; HyperFrames only needs a player object it can seek.
+
+## Contract
+
+- Load assets from local project files, usually under `assets/`.
+- Set `autoplay: false`.
+- Prefer `loop: false` unless the user explicitly wants a loop.
+- Register every returned animation or player on `window.__hfLottie`.
+- Keep the Lottie container dimensions stable with CSS.
+
+The adapter seeks `lottie-web` with `goToAndStop(timeMs, false)` and dotLottie with frame or percentage APIs depending on player shape.
+
+## lottie-web Pattern
+
+```html
+<div id="logo-lottie" class="lottie-layer"></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
+<script>
+  const anim = lottie.loadAnimation({
+    container: document.getElementById("logo-lottie"),
+    renderer: "svg",
+    loop: false,
+    autoplay: false,
+    path: "assets/logo-reveal.json",
+  });
+
+  window.__hfLottie = window.__hfLottie || [];
+  window.__hfLottie.push(anim);
+</script>
+```
+
+```css
+.lottie-layer {
+  width: 100%;
+  height: 100%;
+}
+```
+
+## dotLottie Pattern
+
+```html
+<canvas id="product-lottie" class="lottie-canvas"></canvas>
+<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script>
+<script>
+  const player = new DotLottie({
+    canvas: document.getElementById("product-lottie"),
+    src: "assets/product-flow.lottie",
+    autoplay: false,
+    loop: false,
+  });
+
+  window.__hfLottie = window.__hfLottie || [];
+  window.__hfLottie.push(player);
+</script>
+```
+
+```css
+.lottie-canvas {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+```
+
+## Multiple Animations
+
+Push each player into the same registry:
+
+```js
+window.__hfLottie = window.__hfLottie || [];
+window.__hfLottie.push(backgroundAnim);
+window.__hfLottie.push(iconAnim);
+window.__hfLottie.push(confettiAnim);
+```
+
+HyperFrames seeks them all to the same composition time.
+
+## Composition Duration
+
+The render engine needs the composition's total length. GSAP timelines report duration automatically; a Lottie-only composition has no timeline object, so the runtime reads the registered animation's native length directly — `totalFrames / frameRate` for `lottie-web`, or the player's own `duration` for dotLottie. `data-duration` on the root element is optional for Lottie compositions: as long as every animation is registered on `window.__hfLottie` (per the contract above), the runtime has a finite duration to work with even when you set `loop: true`.
+
+## Good Uses
+
+- After Effects exports that are already known to render correctly in lottie-web.
+- Logo reveals, icon loops, decorative accents, and product UI motion.
+- Translating Remotion Lottie usage into plain HyperFrames HTML.
+
+## Avoid
+
+- Relying on remote `path` URLs at render time.
+- Starting playback with `play()`.
+- Assuming unsupported After Effects effects will survive export. Test the JSON or `.lottie` file in a browser first.
+- Loading a player asynchronously and registering it after HyperFrames validation has already inspected the page.
+
+## Validation
+
+After editing a Lottie composition:
+
+```bash
+npx hyperframes lint
+npx hyperframes check
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/lottie.ts`.
+- Duration auto-inference: `packages/core/src/runtime/init.ts` (`resolveAdapterDurationFloorSeconds`), `getInferredDurationSeconds` in the adapter above.
+- lottie-web by Airbnb: https://github.com/airbnb/lottie-web
+- lottie-web `loadAnimation` options: https://github.com/airbnb/lottie-web/wiki/loadAnimation-options
+- dotLottie web player methods by LottieFiles: https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/methods
@@ -0,0 +1,131 @@
+---
+name: hyperframes-three
+description: Three.js and WebGL adapter patterns for HyperFrames. Use when creating deterministic Three.js scenes, WebGL canvas layers, AnimationMixer timelines, camera motion, shader-driven visuals, or canvas renders that respond to HyperFrames hf-seek events.
+---
+
+# Three.js for HyperFrames
+
+HyperFrames supports Three.js through its `three` runtime adapter. The adapter does not own your scene. It publishes HyperFrames time and dispatches a seek event so your composition can render the exact frame.
+
+## Contract
+
+- Create the scene, camera, renderer, materials, and assets synchronously when possible.
+- Render from HyperFrames time, not wall-clock time.
+- Listen for the `hf-seek` event and render exactly that time.
+- Load models, textures, and HDRIs before render-critical seeking. Do not fetch them at seek time.
+- Avoid `requestAnimationFrame` or `renderer.setAnimationLoop` as the source of truth for render-critical motion.
+- **Always set `data-duration="<seconds>"` on the root `[data-composition-id]` element.** Unlike CSS/WAAPI/Lottie, the `three` adapter has no duration auto-inference — it only forwards time via `hf-seek`/`__hfThreeTime`, it doesn't inspect your scene for an `AnimationClip`/`AnimationMixer` length. Without `data-duration` (and no GSAP timeline), the render engine has no way to know how long to capture and fails with "Composition has zero duration". `npx hyperframes lint` errors on this (`root_composition_missing_duration_source`).
+
+The adapter sets `window.__hfThreeTime` and dispatches `new CustomEvent("hf-seek", { detail: { time } })` on each seek.
+
+## Basic Pattern
+
+```html
+<canvas id="three-layer"></canvas>
+<script type="module">
+  import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm";
+
+  const canvas = document.getElementById("three-layer");
+  const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
+  // Match these to your composition's frame size.
+  renderer.setSize(1920, 1080, false);
+  renderer.setPixelRatio(1);
+
+  const scene = new THREE.Scene();
+  const camera = new THREE.PerspectiveCamera(35, 1920 / 1080, 0.1, 100);
+  camera.position.set(0, 0, 6);
+
+  const mesh = new THREE.Mesh(
+    new THREE.IcosahedronGeometry(1.4, 4),
+    new THREE.MeshStandardMaterial({ color: 0x64d2ff, roughness: 0.38 }),
+  );
+  scene.add(mesh);
+  scene.add(new THREE.HemisphereLight(0xffffff, 0x223344, 2));
+
+  function renderAt(time) {
+    mesh.rotation.y = time * 0.7;
+    mesh.rotation.x = Math.sin(time * 0.6) * 0.16;
+    renderer.render(scene, camera);
+  }
+
+  window.addEventListener("hf-seek", (event) => {
+    renderAt(event.detail.time);
+  });
+
+  renderAt(window.__hfThreeTime || 0);
+</script>
+```
+
+```css
+#three-layer {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+```
+
+## Loading Addons (`GLTFLoader`, `OrbitControls`, etc.)
+
+For anything under `three/addons/`, use an importmap so bare specifiers resolve. The HyperFrames lint recognizes both this form and the inline `+esm` import above — pick whichever your composition needs.
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "three": "https://cdn.jsdelivr.net/npm/three@0.181.2/build/three.module.js",
+      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/"
+    }
+  }
+</script>
+<script type="module">
+  import * as THREE from "three";
+  import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+  import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+  // ...
+</script>
+```
+
+Pin the `three` version in both entries to the same value. Mixing versions across the map and bare imports causes silent breakage.
+
+## AnimationMixer Pattern
+
+For GLTF or authored clip animation, seek the mixer directly:
+
+```js
+function renderAt(time) {
+  mixer.setTime(time);
+  renderer.render(scene, camera);
+}
+```
+
+If several mixers exist, seek all of them from the same `time`.
+
+## Good Uses
+
+- Deterministic 3D objects, product spins, particles with seeded data, and shader plates.
+- Camera moves derived from `time`.
+- GLTF animation clips when assets are local and loaded before validation completes.
+
+## Avoid
+
+- Using `Date.now()`, `performance.now()`, or clock deltas to update scene state.
+- Leaving render-critical work inside a free-running animation loop.
+- Loading remote models or textures at render time.
+- Device-pixel-ratio dependent output. Pin renderer size and pixel ratio for video renders.
+- Post-processing passes that depend on previous frame history unless you can reconstruct state from time.
+
+## Validation
+
+After editing a Three.js composition:
+
+```bash
+npx hyperframes lint
+npx hyperframes check
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/three.ts`.
+- Why `data-duration` is required here specifically (no auto-inference for this adapter): `packages/core/src/runtime/init.ts` (`resolveAdapterDurationFloorSeconds`) and the CSS/WAAPI/Lottie adapters' `getInferredDurationSeconds`, which the `three` adapter deliberately does not implement.
+- Three.js `WebGLRenderer` docs: https://threejs.org/docs/pages/WebGLRenderer.html
+- Three.js `AnimationMixer.setTime()` docs: https://threejs.org/docs/pages/AnimationMixer.html
@@ -0,0 +1,178 @@
+---
+name: hyperframes-typegpu
+description: TypeGPU and raw WebGPU adapter patterns for HyperFrames. Use when creating GPU-rendered compositions with TypeGPU, raw WebGPU, WGSL fragment shaders, compute pipelines, liquid glass effects, particle systems, or any canvas layer driven by navigator.gpu that responds to HyperFrames hf-seek events.
+---
+
+# TypeGPU / WebGPU for HyperFrames
+
+HyperFrames supports TypeGPU and raw WebGPU through its `typegpu` runtime adapter. The adapter does not own your pipeline. It publishes HyperFrames time and dispatches a seek event so your composition can render the exact GPU frame.
+
+## Render-environment prerequisite (WebGPU + html-in-canvas)
+
+The render engine auto-passes `--enable-unsafe-webgpu` and `--enable-features=CanvasDrawElement` to its Chrome launch args. Stock Chromium and the bundled headless-shell **do not** support WebGPU + `drawElementImage` together — the combo that liquid-glass blocks need (`ios26-liquid-glass`, `macos-tahoe-liquid-glass`, `liquid-glass-*`, `vfx-liquid-glass`). For those blocks, point the engine at Brave (or Chrome canary) by setting `PRODUCER_HEADLESS_SHELL_PATH` to the browser binary before running `npx hyperframes render` / `preview`. Plain TypeGPU layers without HTML-as-texture work in headless-shell — only the html-in-canvas + WebGPU combination needs the override.
+
+## Contract
+
+- Initialize WebGPU asynchronously (`await navigator.gpu.requestAdapter()`), but register all GSAP tweens **synchronously** — before any `await`. The HyperFrames player reads the timeline immediately at page load.
+- Render from HyperFrames time, not `performance.now()`.
+- Listen for the `hf-seek` event and re-render at exactly that time.
+- Guard against environments where WebGPU is unavailable — the adapter does not check for you.
+- For video renders, call `await device.queue.onSubmittedWorkDone()` after submitting GPU work to ensure the canvas is flushed before the frame is captured.
+
+The adapter sets `window.__hfTypegpuTime` and dispatches `new CustomEvent("hf-seek", { detail: { time } })` on each seek.
+
+## Basic Pattern
+
+```html
+<canvas id="gpu-layer"></canvas>
+<script>
+  (async () => {
+    if (!navigator.gpu) return;
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter) return;
+    const device = await adapter.requestDevice();
+    const canvas = document.getElementById("gpu-layer");
+    canvas.width = 1920;
+    canvas.height = 1080;
+    const ctx = canvas.getContext("webgpu");
+    const fmt = navigator.gpu.getPreferredCanvasFormat();
+    ctx.configure({ device, format: fmt, alphaMode: "opaque" });
+
+    // Build your pipeline, buffers, bind groups...
+    const timeUniform = new Float32Array([0]);
+    const timeBuf = device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+
+    function render(t) {
+      timeUniform[0] = t;
+      device.queue.writeBuffer(timeBuf, 0, timeUniform);
+      const enc = device.createCommandEncoder();
+      const pass = enc.beginRenderPass({
+        colorAttachments: [
+          {
+            view: ctx.getCurrentTexture().createView(),
+            loadOp: "clear",
+            clearValue: { r: 0, g: 0, b: 0, a: 1 },
+            storeOp: "store",
+          },
+        ],
+      });
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bindGroup);
+      pass.draw(3);
+      pass.end();
+      device.queue.submit([enc.finish()]);
+    }
+
+    render(0);
+    window.addEventListener("hf-seek", (e) => render(e.detail.time));
+  })();
+</script>
+```
+
+## Timeline Registration
+
+GSAP tweens that drive text, captions, or HTML elements must be registered **synchronously** — before any `await`:
+
+```js
+const tl = gsap.timeline({ paused: true });
+
+// Caption tweens: synchronous, added before WebGPU init
+gsap.set(".cap", { opacity: 0 });
+tl.to("#cap-1", { opacity: 1, duration: 0.3 }, 1.0);
+tl.to("#cap-1", { opacity: 0, duration: 0.2 }, 3.5);
+
+window.__timelines["my-comp"] = tl;
+
+// GPU-dependent tweens can go inside the async IIFE
+(async () => {
+  // ... WebGPU init ...
+  const proxy = { value: 0 };
+  tl.to(proxy, { value: 1, duration: 2, onUpdate: render }, 0.5);
+})();
+```
+
+## Video-Backed Effects (Liquid Glass, Distortion)
+
+To use a `<video>` as the GPU input texture:
+
+```js
+const videoEl = document.getElementById("aroll");
+
+// Wait for video metadata before creating the texture
+await new Promise((r) => {
+  if (videoEl.readyState >= 1) r();
+  else videoEl.addEventListener("loadedmetadata", r, { once: true });
+});
+
+// Create texture at the video's NATIVE resolution
+const vw = videoEl.videoWidth,
+  vh = videoEl.videoHeight;
+const bgTex = device.createTexture({
+  size: [vw, vh],
+  format: "rgba8unorm",
+  usage:
+    GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+});
+
+function render(t) {
+  try {
+    device.queue.copyExternalImageToTexture({ source: videoEl }, { texture: bgTex }, [vw, vh]);
+  } catch (_) {
+    /* frame not decoded yet */
+  }
+  // ... draw ...
+}
+```
+
+**Render-mode caveat:** headless Chrome may fail `copyExternalImageToTexture` for video elements. For production renders, pre-extract key frames via FFmpeg as PNGs and load them as image textures instead.
+
+## Frosted Blur via Downsample Pass
+
+A single-pass Gaussian kernel is too weak for glass-like frosted blur. Use a two-pass approach:
+
+1. **Pass 1 — Downsample:** render the full-res texture to a small texture (1/6 resolution). Bilinear filtering during the downsample naturally averages pixels.
+2. **Pass 2 — Glass composite:** sample the small texture for the frosted interior (bilinear upscale = heavy smooth blur) and the full-res texture for sharp areas and chromatic refraction.
+
+This matches TypeGPU's `textureSampleBias` mip-level approach without generating mipmaps.
+
+## Transparent vs Opaque Canvas
+
+- **`alphaMode: 'opaque'`** — the GPU canvas renders the full frame (video + effect). Use when the GPU pipeline handles all visual content.
+- **`alphaMode: 'premultiplied'`** — the GPU canvas is transparent where alpha = 0, letting HTML elements below show through. Use for overlays (particles, path animations) on top of a regular `<video>` element.
+
+## WGSL Full-Screen Triangle
+
+The standard vertex shader for full-screen effects (no vertex buffer needed):
+
+```wgsl
+struct Vo { @builtin(position) pos: vec4f, @location(0) uv: vec2f }
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> Vo {
+  let ps = array<vec2f, 3>(vec2f(-1., -1.), vec2f(3., -1.), vec2f(-1., 3.));
+  let ts = array<vec2f, 3>(vec2f(0., 1.), vec2f(2., 1.), vec2f(0., -1.));
+  return Vo(vec4f(ps[vi], 0., 1.), ts[vi]);
+}
+```
+
+Draw with `pass.draw(3)` — one triangle that covers the viewport.
+
+## Rounded-Rect SDF (Liquid Glass Pill)
+
+```wgsl
+fn sdf_box(p: vec2f, half_size: vec2f, corner_radius: f32) -> f32 {
+  let d = abs(p) - half_size + vec2f(corner_radius);
+  return length(max(d, vec2f(0.))) + min(max(d.x, d.y), 0.) - corner_radius;
+}
+```
+
+Use this to define inside/ring/outside zones for glass effects. Negative values are inside the shape.
+
+## Deterministic Rendering
+
+- No `Math.random()` — use a seeded PRNG.
+- No `requestAnimationFrame` for the render loop — render only in response to `hf-seek`.
+- No `performance.now()` for animation time — read `window.__hfTypegpuTime` or `e.detail.time`.
+- After GPU submit, call `await device.queue.onSubmittedWorkDone()` for render-mode frame capture.
@@ -0,0 +1,101 @@
+---
+name: hyperframes-waapi
+description: Web Animations API adapter patterns for HyperFrames. Use when authoring element.animate() motion, Animation currentTime seeking, document.getAnimations(), KeyframeEffect timing, fill modes, or native browser animations that must render deterministically in HyperFrames.
+---
+
+# Web Animations API for HyperFrames
+
+HyperFrames can seek Web Animations API animations through its `waapi` runtime adapter. WAAPI is useful when you want native browser keyframes with JavaScript-created timing and no GSAP dependency.
+
+## Contract
+
+- Create animations synchronously during composition initialization.
+- Use `element.animate(...)` with finite `duration` and `iterations`.
+- Use `fill: "both"` so seeked states persist.
+- Pause animations after creation or let the adapter pause them on first seek.
+- Avoid callbacks and promises for render-critical state.
+
+The adapter calls `document.getAnimations()`, sets each animation's `currentTime` to HyperFrames time in milliseconds, then pauses it.
+
+## Basic Pattern
+
+```html
+<div id="orb" class="clip orb" data-start="2" data-duration="3" data-track-index="2"></div>
+
+<script>
+  const orb = document.getElementById("orb");
+  const animation = orb.animate(
+    [
+      { transform: "translate3d(-160px, 0, 0) scale(0.8)", opacity: 0 },
+      { transform: "translate3d(0, 0, 0) scale(1)", opacity: 1, offset: 0.35 },
+      { transform: "translate3d(120px, 0, 0) scale(1.08)", opacity: 1 },
+    ],
+    {
+      duration: 3000,
+      delay: 2000,
+      easing: "cubic-bezier(0.2, 0, 0, 1)",
+      fill: "both",
+      iterations: 1,
+    },
+  );
+
+  animation.pause();
+</script>
+```
+
+## Stagger Pattern
+
+```js
+document.querySelectorAll(".token").forEach((token, index) => {
+  const animation = token.animate(
+    [
+      { transform: "translateY(24px)", opacity: 0 },
+      { transform: "translateY(0)", opacity: 1 },
+    ],
+    {
+      duration: 620,
+      delay: index * 80,
+      easing: "cubic-bezier(0.2, 0, 0, 1)",
+      fill: "both",
+      iterations: 1,
+    },
+  );
+  animation.pause();
+});
+```
+
+## Good Uses
+
+- Lightweight DOM motion where CSS keyframes are too rigid and GSAP is unnecessary.
+- Generated animations from structured data.
+- Simple timelines that can be represented as keyframes, delays, and offsets.
+
+## Composition Duration
+
+The render engine needs the composition's total length to know how many frames to capture. GSAP timelines report duration automatically; a WAAPI-only composition has no timeline object, so the runtime infers duration from every animation's `effect.getComputedTiming().endTime` (offset by when the animation was created relative to composition start). `data-duration` on the root element is optional as long as every `element.animate()` call uses finite `duration` and `iterations` — which the contract above already requires.
+
+Infinite `iterations` has no finite `endTime`, so it can't be auto-inferred — that's one more reason to avoid it (see Avoid below). If you must use it, add `data-duration="<seconds>"` to the root `[data-composition-id]` element or `npx hyperframes lint` will error (`root_composition_missing_duration_source`).
+
+## Avoid
+
+- Infinite `iterations`.
+- Depending on `animation.finished` to mutate render-critical DOM.
+- Running separate clocks with `requestAnimationFrame`, timers, or `performance.now()`.
+- Animating layout properties when transforms and opacity can express the motion.
+- Assuming clip-local start time is automatic. WAAPI adapter seeks document-level animation time; model clip offsets with `delay` or create the animation on an element whose visibility is controlled by HyperFrames timing.
+
+## Validation
+
+After editing a WAAPI composition:
+
+```bash
+npx hyperframes lint
+npx hyperframes check
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/waapi.ts`.
+- Duration auto-inference: `packages/core/src/runtime/init.ts` (`resolveAdapterDurationFloorSeconds`), `getInferredDurationSeconds` in the adapter above.
+- MDN Web Animations API guide: https://developer.mozilla.org/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API
+- MDN `Animation.currentTime`: https://developer.mozilla.org/en-US/docs/Web/API/Animation/currentTime