takomi 2.5.1 → 2.5.5

package/assets/.agent/skills/hyperframes-animation/adapters/typegpu.md

@@ -1,178 +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.
+---
+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.

package/assets/.agent/skills/hyperframes-animation/adapters/waapi.md

@@ -1,101 +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 validate
-```
-
-## 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
+---
+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 validate
+```
+
+## 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

package/assets/.agent/skills/hyperframes-animation/blueprints/comparison-split.md

@@ -1,27 +1,27 @@
-# comparison-split — Comparison Split-Cards
-
-**intent**: Two paired items of equal weight shown side-by-side with mirrored 3D "book-open" tilts — the eye reads them as a balanced comparison, then a pill badge lands at each card's inner edge to punctuate. The motion IS the symmetry: two cards arriving from opposite wings into a held spread.
-
-**roles served**
-
-- Key_Feature (from `comparison-split-cards`): when two complementary features / capabilities of equal weight should be presented **simultaneously, not sequentially** — an A/B, a "X + Y together," paired concepts the viewer must weigh side-by-side. Not for >2 items (use `grid-card-assemble`) or sequential steps.
-
-**duration**: 4–6s
-
-**shot structure** (a `[bg]` canvas carrying two faint ambient glow blooms — `[accent A]` near 30%, `[accent B]` near 70% — so each side owns a color identity across a 50% symmetry axis; equal-width cards under one shared perspective parent)
-
-- **Scene 1 (0.0–~0.8s) — title sets the concept.** A centered `[title line]` with an `[accent keyword]` slides DOWN into place from just above (a short smooth settle). The downward arrival is deliberate: it forms a non-conflicting T-shape against the cards, which arrive from the sides next.
-- **Scene 2 (~0.4–1.9s) — the split-tilt entry (signature move).** Two equal-width feature cards arrive from opposite wings — `[left card]` from the left, `[right card]` from the right ~0.2s behind — each carrying a **mirrored 3D `rotateY` tilt** (left faces right, right faces left, opening like a book) and scaling ~0.85→1 as it lands. The entry overlaps the title's tail so the whole thing reads as ONE arrival, not two beats. Each card holds `[image / label / subtitle]`; box-shadows fall **outward** from the tilt (left shadow right, right shadow left).
-- **Scene 3 (~1.9–end) — badges punctuate, then hold.** A pill `[badge]` lands at each card's **inner edge** (left then right, ~0.3s apart), overlapping its card ~15% so it reads as attached, not orbiting. This is the lone overshoot in the shot — it earns the punctuation. Settles and holds.
-
-**motion vocabulary**: title slide-down from above; mirrored opposite-wing card entry; static book-open `rotateY` tilt (`+tilt` left, `−tilt` right); tilt-matched outward box-shadow; inner-edge badge spring-pop; gentle phase-opposed idle float (left vs right, never synchronized) registered as subtle jitter; dual side-glow ambient.
-
-**rule mapping**
-
-- two cards entering from opposite wings with mirrored `rotateY` tilts + tilt-matched shadow → `split-tilt-cards` (the signature; keep the two-layer split so the entry `x`/`scale` and the idle never collide on one alias)
-- title slide-down settle → `gsap-effects` (translate + opacity on a long-tail `power3`)
-- inner-edge pill badge pop (the one overshoot) → `spring-pop-entrance` (overshoot register — earns the punctuation)
-- phase-opposed idle float on the pair → `sine-wave-loop` (low-amplitude register — subtle jitter, NOT lazy breathing; left `sin(t)`, right `sin(t+π)` so they never conveyor-belt)
-- the two faint side glows behind the cards → `ambient-glow-bloom` (un-triggered soft bloom, one per accent)
-
-**camera modifier**: camera-static by default — the symmetry is the subject and a move would break the balance.
+# comparison-split — Comparison Split-Cards
+
+**intent**: Two paired items of equal weight shown side-by-side with mirrored 3D "book-open" tilts — the eye reads them as a balanced comparison, then a pill badge lands at each card's inner edge to punctuate. The motion IS the symmetry: two cards arriving from opposite wings into a held spread.
+
+**roles served**
+
+- Key_Feature (from `comparison-split-cards`): when two complementary features / capabilities of equal weight should be presented **simultaneously, not sequentially** — an A/B, a "X + Y together," paired concepts the viewer must weigh side-by-side. Not for >2 items (use `grid-card-assemble`) or sequential steps.
+
+**duration**: 4–6s
+
+**shot structure** (a `[bg]` canvas carrying two faint ambient glow blooms — `[accent A]` near 30%, `[accent B]` near 70% — so each side owns a color identity across a 50% symmetry axis; equal-width cards under one shared perspective parent)
+
+- **Scene 1 (0.0–~0.8s) — title sets the concept.** A centered `[title line]` with an `[accent keyword]` slides DOWN into place from just above (a short smooth settle). The downward arrival is deliberate: it forms a non-conflicting T-shape against the cards, which arrive from the sides next.
+- **Scene 2 (~0.4–1.9s) — the split-tilt entry (signature move).** Two equal-width feature cards arrive from opposite wings — `[left card]` from the left, `[right card]` from the right ~0.2s behind — each carrying a **mirrored 3D `rotateY` tilt** (left faces right, right faces left, opening like a book) and scaling ~0.85→1 as it lands. The entry overlaps the title's tail so the whole thing reads as ONE arrival, not two beats. Each card holds `[image / label / subtitle]`; box-shadows fall **outward** from the tilt (left shadow right, right shadow left).
+- **Scene 3 (~1.9–end) — badges punctuate, then hold.** A pill `[badge]` lands at each card's **inner edge** (left then right, ~0.3s apart), overlapping its card ~15% so it reads as attached, not orbiting. This is the lone overshoot in the shot — it earns the punctuation. Settles and holds.
+
+**motion vocabulary**: title slide-down from above; mirrored opposite-wing card entry; static book-open `rotateY` tilt (`+tilt` left, `−tilt` right); tilt-matched outward box-shadow; inner-edge badge spring-pop; gentle phase-opposed idle float (left vs right, never synchronized) registered as subtle jitter; dual side-glow ambient.
+
+**rule mapping**
+
+- two cards entering from opposite wings with mirrored `rotateY` tilts + tilt-matched shadow → `split-tilt-cards` (the signature; keep the two-layer split so the entry `x`/`scale` and the idle never collide on one alias)
+- title slide-down settle → `gsap-effects` (translate + opacity on a long-tail `power3`)
+- inner-edge pill badge pop (the one overshoot) → `spring-pop-entrance` (overshoot register — earns the punctuation)
+- phase-opposed idle float on the pair → `sine-wave-loop` (low-amplitude register — subtle jitter, NOT lazy breathing; left `sin(t)`, right `sin(t+π)` so they never conveyor-belt)
+- the two faint side glows behind the cards → `ambient-glow-bloom` (un-triggered soft bloom, one per accent)
+
+**camera modifier**: camera-static by default — the symmetry is the subject and a move would break the balance.