takomi 2.1.45 → 2.5.4

package/assets/.agent/skills/hyperframes-animation/adapters/animate-text.md

@@ -1,64 +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).
+# 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).

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

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

package/assets/.agent/skills/hyperframes-animation/adapters/css-animations.md

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