takomi 2.5.1 → 2.5.4

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

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

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

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