takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/hyperframes-core/references/data-attributes.md

@@ -1,70 +1,70 @@
-# Data Attributes Reference
-
-Every HyperFrames composition uses `data-*` attributes to declare timing and structure to the framework. This is the full attribute table — pair with `tracks-and-clips.md` for the rules behind `data-track-index`.
-
-## Composition Root
-
-Every renderable composition needs one root element:
-
-| Attribute                    | Required      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data-composition-id`        | Yes           | Unique ID. Must match the animation registry key on `window.__timelines`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `data-width` / `data-height` | Yes           | Pixel frame size. Common values: `1920x1080`, `1080x1920`, `1080x1080`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `data-duration`              | Conditional\* | Render duration in seconds (total length / frame count), not the GSAP timeline length. **Read once at compile time, like `data-width` / `data-height`**: a static root `data-duration` is locked before scripts run, so a script (`root.setAttribute("data-duration", ...)`) or a `--variables`-driven value cannot change the render length. To vary length per render, author the root `data-duration` directly. (A clip's `data-duration` is different: re-read from the live DOM, so scripts/variables can drive it.) Only when the root omits `data-duration` does the renderer derive total length from the live DOM / timeline after scripts run. |
-| `data-fps`                   | No            | Optional frame rate hint. CLI render flags can override output fps.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `data-composition-variables` | No            | JSON array of variable declarations (on `<html>`). See `variables-and-media.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-
-\*`data-duration` is optional whenever the runtime can auto-infer duration: a registered GSAP timeline, a finite CSS animation, a finite WAAPI `element.animate()`, or a registered Lottie animation. It is **required** for Three.js (no auto-inference), for infinite/unbounded CSS or WAAPI animations, and for any composition with no GSAP timeline and no animation signal at all. `npx hyperframes lint` enforces this (`root_composition_missing_duration_source`). See `determinism-rules.md` → "Duration Contract For Non-GSAP Runtimes" for the per-runtime breakdown.
-
-The root should be `position: relative`, have explicit pixel dimensions, and hide overflow unless intentionally composing outside the frame.
-
-## Clip Attributes
-
-Timed child elements are clips. **`class="clip"` is required on visible timed elements** (`<div>`, `<img>`, etc.) — without it the runtime keeps the element visible for the whole composition, ignoring `data-start` / `data-duration`. Omit on `<video>` (framework manages visibility directly) and `<audio>` (no visual).
-
-**Clips must be DIRECT children of the composition root.** A clip nested inside a wrapper `<div>` is not registered — most visibly, a `<video>` in a wrapper is never seeked/decoded and renders black. To wrap/transform a clip, put the wrapper _inside_ the clip, or animate the clip element itself; do not wrap the clip. (`<video>`/`<audio>` additionally must be at the **host** root, never in a sub-comp `<template>` — see `variables-and-media.md`.)
-
-| Attribute          | Required                                        | Meaning                                                                                                                           |
-| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `id`               | Yes                                             | Stable DOM ID for linting, timeline targets, and debugging.                                                                       |
-| `data-start`       | Yes                                             | Start time in seconds, or a supported clip-time reference.                                                                        |
-| `data-duration`    | Required for `div`, `img`, and sub-compositions | Duration in seconds. Video/audio can default to media duration when known.                                                        |
-| `data-track-index` | Yes                                             | Timeline track. Clips on the same track must not overlap.                                                                         |
-| `data-media-start` | No                                              | Offset into the media source, in seconds.                                                                                         |
-| `data-volume`      | No                                              | Static audio volume, `0` to `1`, default `1`. For fades, animate `volume` on the timeline instead (see `variables-and-media.md`). |
-| `data-has-audio`   | No (`<video>` only)                             | `"true"` to declare the video carries an audio track when auto-detection would miss it.                                           |
-
-**Visibility window is inclusive of both ends.** A clip shows while `start ≤ t ≤ start + duration` — it still renders at exactly `t = start + duration`, so the final frame holds the animation's resolved end state (the runtime does not hide it one frame early). A reveal/entrance that lands on `data-duration` is therefore visible on the last frame; you do not need to finish it _before_ `data-duration` just to guarantee the end state renders. (Climax-dwell guidance in `/hyperframes-animation` is about pacing, not this boundary.)
-
-## Sub-Composition Host Attributes
-
-When a clip is a sub-composition host (loads another composition file):
-
-| Attribute                    | Required | Meaning                                                                |
-| ---------------------------- | -------- | ---------------------------------------------------------------------- |
-| `data-composition-id`        | Yes      | The internal composition ID of the loaded file.                        |
-| `data-composition-src`       | Yes      | Path to the sub-composition HTML file.                                 |
-| `data-width` / `data-height` | Yes      | Render dimensions for the sub-composition instance.                    |
-| `data-variable-values`       | No       | Per-instance variable overrides as JSON. See `variables-and-media.md`. |
-
-See `sub-compositions.md` for the full wiring pattern.
-
-## Authoring Hints
-
-- `id="root"` — template convention used by scaffolds and the transition catalog so CSS can target the composition root with `#root` instead of `[data-composition-id="main"]`. Not required by the runtime, but consistent with the rest of the ecosystem.
-- `class="clip"` — required runtime visibility marker on visible timed elements (`<div>`, `<img>`, …). See Clip Attributes above.
-- `data-layout-allow-overflow` — tells `hyperframes inspect` that overflow on this element (or its descendants) is intentional. Notes:
-  - `inspect` measures `getBoundingClientRect` at sampled timestamps, not rendered pixels — `overflow: hidden` clips the visual but does **not** suppress an `inspect` overflow finding. This attribute is the escape hatch; CSS overflow is not.
-  - Can be set on the composition **root** as well as on any child. When the cited offender is `div.<comp>-root inside div.<comp>-root` (the root reports its own children's union as overflowing), the fix goes on the root, not on individual text descendants — shrinking font sizes will not converge.
-  - In a multi-scene `group_wN.html` (continue runs), every scene-local element stays in the DOM during the other scenes' time windows; the layout-box union almost always overflows the canvas during morph seams. Mark the root and every scene-local primary/supporting element with this attribute **at construction**, not after `inspect` flags it.
-  - **Blast radius — it silences more than `inspect`.** The attribute is inherited down the subtree (the perception probe walks ancestors), so it also suppresses the rendered-perception checks `text-clipping`, `content-cramped-container`, and `foreground-over-panel` for every descendant. Putting it on a persistent panel that also hosts real foreground content disables collision checks on that content for the panel's whole lifetime. Prefer the narrowest opt-out: scope it to the smallest decorative wrapper, or use per-element `data-layout-bleed="true"` for one intentional primary-text crop. The two canvas/edge checks `primary-offscreen` and `foreground-over-panel` deliberately run **even under** allow-overflow, so it cannot hide a wordmark sliced by the frame or text bleeding onto a panel edge.
-- `data-layout-ignore` — exclude this element from layout audits entirely.
-
-## Legacy / Removed Attributes
-
-These names appear in older projects and examples. Use the current names when authoring or editing:
-
-| Legacy name  | Use instead        |
-| ------------ | ------------------ |
-| `data-layer` | `data-track-index` |
-| `data-end`   | `data-duration`    |
+# Data Attributes Reference
+
+Every HyperFrames composition uses `data-*` attributes to declare timing and structure to the framework. This is the full attribute table — pair with `tracks-and-clips.md` for the rules behind `data-track-index`.
+
+## Composition Root
+
+Every renderable composition needs one root element:
+
+| Attribute                    | Required      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-composition-id`        | Yes           | Unique ID. Must match the animation registry key on `window.__timelines`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `data-width` / `data-height` | Yes           | Pixel frame size. Common values: `1920x1080`, `1080x1920`, `1080x1080`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `data-duration`              | Conditional\* | Render duration in seconds (total length / frame count), not the GSAP timeline length. **Read once at compile time, like `data-width` / `data-height`**: a static root `data-duration` is locked before scripts run, so a script (`root.setAttribute("data-duration", ...)`) or a `--variables`-driven value cannot change the render length. To vary length per render, author the root `data-duration` directly. (A clip's `data-duration` is different: re-read from the live DOM, so scripts/variables can drive it.) Only when the root omits `data-duration` does the renderer derive total length from the live DOM / timeline after scripts run. |
+| `data-fps`                   | No            | Optional frame rate hint. CLI render flags can override output fps.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `data-composition-variables` | No            | JSON array of variable declarations (on `<html>`). See `variables-and-media.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+\*`data-duration` is optional whenever the runtime can auto-infer duration: a registered GSAP timeline, a finite CSS animation, a finite WAAPI `element.animate()`, or a registered Lottie animation. It is **required** for Three.js (no auto-inference), for infinite/unbounded CSS or WAAPI animations, and for any composition with no GSAP timeline and no animation signal at all. `npx hyperframes lint` enforces this (`root_composition_missing_duration_source`). See `determinism-rules.md` → "Duration Contract For Non-GSAP Runtimes" for the per-runtime breakdown.
+
+The root should be `position: relative`, have explicit pixel dimensions, and hide overflow unless intentionally composing outside the frame.
+
+## Clip Attributes
+
+Timed child elements are clips. **`class="clip"` is required on visible timed elements** (`<div>`, `<img>`, etc.) — without it the runtime keeps the element visible for the whole composition, ignoring `data-start` / `data-duration`. Omit on `<video>` (framework manages visibility directly) and `<audio>` (no visual).
+
+**Clips must be DIRECT children of the composition root.** A clip nested inside a wrapper `<div>` is not registered — most visibly, a `<video>` in a wrapper is never seeked/decoded and renders black. To wrap/transform a clip, put the wrapper _inside_ the clip, or animate the clip element itself; do not wrap the clip. (`<video>`/`<audio>` additionally must be at the **host** root, never in a sub-comp `<template>` — see `variables-and-media.md`.)
+
+| Attribute          | Required                                        | Meaning                                                                                                                           |
+| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | Yes                                             | Stable DOM ID for linting, timeline targets, and debugging.                                                                       |
+| `data-start`       | Yes                                             | Start time in seconds, or a supported clip-time reference.                                                                        |
+| `data-duration`    | Required for `div`, `img`, and sub-compositions | Duration in seconds. Video/audio can default to media duration when known.                                                        |
+| `data-track-index` | Yes                                             | Timeline track. Clips on the same track must not overlap.                                                                         |
+| `data-media-start` | No                                              | Offset into the media source, in seconds.                                                                                         |
+| `data-volume`      | No                                              | Static audio volume, `0` to `1`, default `1`. For fades, animate `volume` on the timeline instead (see `variables-and-media.md`). |
+| `data-has-audio`   | No (`<video>` only)                             | `"true"` to declare the video carries an audio track when auto-detection would miss it.                                           |
+
+**Visibility window is inclusive of both ends.** A clip shows while `start ≤ t ≤ start + duration` — it still renders at exactly `t = start + duration`, so the final frame holds the animation's resolved end state (the runtime does not hide it one frame early). A reveal/entrance that lands on `data-duration` is therefore visible on the last frame; you do not need to finish it _before_ `data-duration` just to guarantee the end state renders. (Climax-dwell guidance in `/hyperframes-animation` is about pacing, not this boundary.)
+
+## Sub-Composition Host Attributes
+
+When a clip is a sub-composition host (loads another composition file):
+
+| Attribute                    | Required | Meaning                                                                |
+| ---------------------------- | -------- | ---------------------------------------------------------------------- |
+| `data-composition-id`        | Yes      | The internal composition ID of the loaded file.                        |
+| `data-composition-src`       | Yes      | Path to the sub-composition HTML file.                                 |
+| `data-width` / `data-height` | Yes      | Render dimensions for the sub-composition instance.                    |
+| `data-variable-values`       | No       | Per-instance variable overrides as JSON. See `variables-and-media.md`. |
+
+See `sub-compositions.md` for the full wiring pattern.
+
+## Authoring Hints
+
+- `id="root"` — template convention used by scaffolds and the transition catalog so CSS can target the composition root with `#root` instead of `[data-composition-id="main"]`. Not required by the runtime, but consistent with the rest of the ecosystem.
+- `class="clip"` — required runtime visibility marker on visible timed elements (`<div>`, `<img>`, …). See Clip Attributes above.
+- `data-layout-allow-overflow` — tells `hyperframes inspect` that overflow on this element (or its descendants) is intentional. Notes:
+  - `inspect` measures `getBoundingClientRect` at sampled timestamps, not rendered pixels — `overflow: hidden` clips the visual but does **not** suppress an `inspect` overflow finding. This attribute is the escape hatch; CSS overflow is not.
+  - Can be set on the composition **root** as well as on any child. When the cited offender is `div.<comp>-root inside div.<comp>-root` (the root reports its own children's union as overflowing), the fix goes on the root, not on individual text descendants — shrinking font sizes will not converge.
+  - In a multi-scene `group_wN.html` (continue runs), every scene-local element stays in the DOM during the other scenes' time windows; the layout-box union almost always overflows the canvas during morph seams. Mark the root and every scene-local primary/supporting element with this attribute **at construction**, not after `inspect` flags it.
+  - **Blast radius — it silences more than `inspect`.** The attribute is inherited down the subtree (the perception probe walks ancestors), so it also suppresses the rendered-perception checks `text-clipping`, `content-cramped-container`, and `foreground-over-panel` for every descendant. Putting it on a persistent panel that also hosts real foreground content disables collision checks on that content for the panel's whole lifetime. Prefer the narrowest opt-out: scope it to the smallest decorative wrapper, or use per-element `data-layout-bleed="true"` for one intentional primary-text crop. The two canvas/edge checks `primary-offscreen` and `foreground-over-panel` deliberately run **even under** allow-overflow, so it cannot hide a wordmark sliced by the frame or text bleeding onto a panel edge.
+- `data-layout-ignore` — exclude this element from layout audits entirely.
+
+## Legacy / Removed Attributes
+
+These names appear in older projects and examples. Use the current names when authoring or editing:
+
+| Legacy name  | Use instead        |
+| ------------ | ------------------ |
+| `data-layer` | `data-track-index` |
+| `data-end`   | `data-duration`    |

package/assets/.agent/skills/hyperframes-core/references/determinism-rules.md

@@ -1,68 +1,68 @@
-# Determinism, Animation Runtime, and Layout
-
-HyperFrames seeks compositions frame-by-frame. Every frame must be reproducible from its time value alone — same input time → same pixels. Three contracts enforce this: the **animation runtime contract**, the **determinism rules**, and the **layout contract**.
-
-## Animation Runtime Contract
-
-GSAP is the primary runtime. The core requirement is generic: animation state must be seekable from HyperFrames time.
-
-For GSAP:
-
-- Create the timeline **synchronously** during page initialization.
-- Use `gsap.timeline({ paused: true })`.
-- Register it on `window.__timelines["<composition-id>"]`.
-- The key must match `data-composition-id` on the composition root.
-- **Do not** call `tl.play()` for render-critical motion.
-- **Do not** build timelines inside `async`, `Promise`, `setTimeout`, or event handlers — the renderer can sample before they finish.
-- **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
-- **Do not** `gsap.set()` clip elements from later scenes — they are not in the DOM at page load. Use `tl.set(selector, vars, time)` inside the timeline at or after the clip's `data-start`.
-
-Use the `hyperframes-animation` skill for tween syntax, position parameters, eases, and performance rules.
-
-### Duration Contract For Non-GSAP Runtimes
-
-The render engine needs a positive total duration before it will capture a single frame — without one, capture fails outright with "Composition has zero duration." A GSAP timeline supplies this automatically. CSS, WAAPI, and Lottie compositions have no timeline object, so the runtime infers duration itself:
-
-- **CSS**: longest `animation-delay` + `animation-duration` × finite `animation-iteration-count` across animated elements (offset by each element's `data-start`). `animation-iteration-count: infinite` cannot be inferred.
-- **WAAPI**: longest `element.animate()` effect's `getComputedTiming().endTime`. Infinite `iterations` cannot be inferred.
-- **Lottie**: the registered animation's native length (`totalFrames / frameRate`, or the dotLottie player's own `duration`) — always finite regardless of `loop`.
-- **Three.js**: **not inferable**. The `three` adapter only forwards time via `hf-seek` — it has no `AnimationClip`/`AnimationMixer` inspection.
-
-`data-duration` on the root `[data-composition-id]` element is therefore optional whenever every non-GSAP animation on the page is finite (CSS/WAAPI with finite iteration counts, or Lottie). It is **required** when: the composition has an infinite/unbounded CSS or WAAPI animation, the composition uses Three.js, or there is no GSAP timeline and no animation signal at all for any adapter to discover. `npx hyperframes lint` enforces exactly this (`root_composition_missing_duration_source`) — see the runtime/adapter-specific docs under `hyperframes-animation/adapters/` for the full contract per runtime.
-
-## Determinism Rules
-
-Rendered frames must be reproducible from the requested time. Do **not** use any of the following for visual state:
-
-- `Date.now()`, `performance.now()`, or any render-time clock.
-- Unseeded `Math.random()`. Use a seeded PRNG if random-looking placement is needed.
-- Render-time network fetches for required assets. Inline or pre-bundle them.
-- Hover, scroll, pointer, or focus state. The renderer has no input events.
-- Infinite loops such as `repeat: -1`. Compute a finite count: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)` — **`floor`, not `ceil`** (`ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint; `max(0, …)` avoids a negative repeat = infinite).
-
-Also avoid:
-
-- Animating anything outside the visual-property allowlist: `opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms. Never animate `display` or `visibility` — use opacity/transforms and timed clip visibility instead.
-- Animating the same property on the same element from multiple timelines at the same time — GSAP's overwrite behavior is order-dependent and can flip between renders.
-
-## Layout Contract
-
-Build the visible end-state in static HTML and CSS first, then animate from/to that state.
-
-- The composition root has fixed pixel frame dimensions.
-- **The root composition's total duration (render length / frame count) is fixed at compile time**, read once from the static root `data-duration` before scripts run, like `data-width` / `data-height`. A script or `--variables` value that rewrites the root `data-duration` afterward is ignored. To vary render length per output, author the root `data-duration` directly. (A _clip's_ own `data-duration` is re-read from the live DOM, so scripts/variables can still drive clip lengths. Only when the root omits `data-duration` does the renderer probe the live DOM / timeline for total length.)
-- Scene containers should fill the scene with `width: 100%; height: 100%; box-sizing: border-box`.
-- Use padding, flex, grid, and `max-width` for layout. Avoid positioning main content with hardcoded `top`/`left` offsets when a layout container can do it.
-- Use `position: absolute` for layers and decorative elements, not as the default content-layout strategy.
-- Prefer transforms and opacity for animation.
-- Keep text inside its intended container. For dynamic text, use `max-width`, wrapping, or `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`.
-- For text measurement without DOM reflow, use `window.__hyperframes.pretext`: `pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)`. Pure arithmetic, ~0.0002 ms per call — safe for per-frame text reflow, shrinkwrap containers, and computing layout before render. `fitTextFontSize` is built on it.
-- **Do not** use `<br>` in body text. Forced breaks ignore the actual rendered font width and produce an extra break when the line already wraps naturally, causing overlap. Let text wrap via `max-width`. Exception: short display titles where each word is deliberately on its own line.
-- **Transformed elements must be block-level + sized.** `transform`/`scaleX`/`scaleY` is a no-op on an inline `<span>`, and scaling an auto-width (0px) element shows nothing → invisible bars/fills. Give them `display: block`/`inline-block`/flex-item **and** a real `width`/`height` (e.g. `width: 100%` inside a sized parent). _(silent — lint/inspect miss it.)_
-- **Absolutely-positioned decoratives that pulse or overshoot** (`yoyo` scale, `back.out`) need clearance at their **peak** size and must not straddle an `overflow: hidden` edge — else they overlap a neighbor or get clipped. Position for the largest frame, not the resting one. _(silent.)_
-
-## Why This Matters
-
-The renderer takes a time value and produces a pixel buffer. There is no notion of "playback" — every frame is a fresh seek. Any state that depends on having reached this frame _through_ a prior frame (timers, accumulated state, event-driven animations) will desync when the renderer samples out of order or in parallel.
-
-If you find yourself reaching for `setTimeout`, `requestAnimationFrame`, or `addEventListener` to drive a visual, rebuild it as a tween on the timeline instead.
+# Determinism, Animation Runtime, and Layout
+
+HyperFrames seeks compositions frame-by-frame. Every frame must be reproducible from its time value alone — same input time → same pixels. Three contracts enforce this: the **animation runtime contract**, the **determinism rules**, and the **layout contract**.
+
+## Animation Runtime Contract
+
+GSAP is the primary runtime. The core requirement is generic: animation state must be seekable from HyperFrames time.
+
+For GSAP:
+
+- Create the timeline **synchronously** during page initialization.
+- Use `gsap.timeline({ paused: true })`.
+- Register it on `window.__timelines["<composition-id>"]`.
+- The key must match `data-composition-id` on the composition root.
+- **Do not** call `tl.play()` for render-critical motion.
+- **Do not** build timelines inside `async`, `Promise`, `setTimeout`, or event handlers — the renderer can sample before they finish.
+- **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
+- **Do not** `gsap.set()` clip elements from later scenes — they are not in the DOM at page load. Use `tl.set(selector, vars, time)` inside the timeline at or after the clip's `data-start`.
+
+Use the `hyperframes-animation` skill for tween syntax, position parameters, eases, and performance rules.
+
+### Duration Contract For Non-GSAP Runtimes
+
+The render engine needs a positive total duration before it will capture a single frame — without one, capture fails outright with "Composition has zero duration." A GSAP timeline supplies this automatically. CSS, WAAPI, and Lottie compositions have no timeline object, so the runtime infers duration itself:
+
+- **CSS**: longest `animation-delay` + `animation-duration` × finite `animation-iteration-count` across animated elements (offset by each element's `data-start`). `animation-iteration-count: infinite` cannot be inferred.
+- **WAAPI**: longest `element.animate()` effect's `getComputedTiming().endTime`. Infinite `iterations` cannot be inferred.
+- **Lottie**: the registered animation's native length (`totalFrames / frameRate`, or the dotLottie player's own `duration`) — always finite regardless of `loop`.
+- **Three.js**: **not inferable**. The `three` adapter only forwards time via `hf-seek` — it has no `AnimationClip`/`AnimationMixer` inspection.
+
+`data-duration` on the root `[data-composition-id]` element is therefore optional whenever every non-GSAP animation on the page is finite (CSS/WAAPI with finite iteration counts, or Lottie). It is **required** when: the composition has an infinite/unbounded CSS or WAAPI animation, the composition uses Three.js, or there is no GSAP timeline and no animation signal at all for any adapter to discover. `npx hyperframes lint` enforces exactly this (`root_composition_missing_duration_source`) — see the runtime/adapter-specific docs under `hyperframes-animation/adapters/` for the full contract per runtime.
+
+## Determinism Rules
+
+Rendered frames must be reproducible from the requested time. Do **not** use any of the following for visual state:
+
+- `Date.now()`, `performance.now()`, or any render-time clock.
+- Unseeded `Math.random()`. Use a seeded PRNG if random-looking placement is needed.
+- Render-time network fetches for required assets. Inline or pre-bundle them.
+- Hover, scroll, pointer, or focus state. The renderer has no input events.
+- Infinite loops such as `repeat: -1`. Compute a finite count: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)` — **`floor`, not `ceil`** (`ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint; `max(0, …)` avoids a negative repeat = infinite).
+
+Also avoid:
+
+- Animating anything outside the visual-property allowlist: `opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms. Never animate `display` or `visibility` — use opacity/transforms and timed clip visibility instead.
+- Animating the same property on the same element from multiple timelines at the same time — GSAP's overwrite behavior is order-dependent and can flip between renders.
+
+## Layout Contract
+
+Build the visible end-state in static HTML and CSS first, then animate from/to that state.
+
+- The composition root has fixed pixel frame dimensions.
+- **The root composition's total duration (render length / frame count) is fixed at compile time**, read once from the static root `data-duration` before scripts run, like `data-width` / `data-height`. A script or `--variables` value that rewrites the root `data-duration` afterward is ignored. To vary render length per output, author the root `data-duration` directly. (A _clip's_ own `data-duration` is re-read from the live DOM, so scripts/variables can still drive clip lengths. Only when the root omits `data-duration` does the renderer probe the live DOM / timeline for total length.)
+- Scene containers should fill the scene with `width: 100%; height: 100%; box-sizing: border-box`.
+- Use padding, flex, grid, and `max-width` for layout. Avoid positioning main content with hardcoded `top`/`left` offsets when a layout container can do it.
+- Use `position: absolute` for layers and decorative elements, not as the default content-layout strategy.
+- Prefer transforms and opacity for animation.
+- Keep text inside its intended container. For dynamic text, use `max-width`, wrapping, or `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`.
+- For text measurement without DOM reflow, use `window.__hyperframes.pretext`: `pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)`. Pure arithmetic, ~0.0002 ms per call — safe for per-frame text reflow, shrinkwrap containers, and computing layout before render. `fitTextFontSize` is built on it.
+- **Do not** use `<br>` in body text. Forced breaks ignore the actual rendered font width and produce an extra break when the line already wraps naturally, causing overlap. Let text wrap via `max-width`. Exception: short display titles where each word is deliberately on its own line.
+- **Transformed elements must be block-level + sized.** `transform`/`scaleX`/`scaleY` is a no-op on an inline `<span>`, and scaling an auto-width (0px) element shows nothing → invisible bars/fills. Give them `display: block`/`inline-block`/flex-item **and** a real `width`/`height` (e.g. `width: 100%` inside a sized parent). _(silent — lint/inspect miss it.)_
+- **Absolutely-positioned decoratives that pulse or overshoot** (`yoyo` scale, `back.out`) need clearance at their **peak** size and must not straddle an `overflow: hidden` edge — else they overlap a neighbor or get clipped. Position for the largest frame, not the resting one. _(silent.)_
+
+## Why This Matters
+
+The renderer takes a time value and produces a pixel buffer. There is no notion of "playback" — every frame is a fresh seek. Any state that depends on having reached this frame _through_ a prior frame (timers, accumulated state, event-driven animations) will desync when the renderer samples out of order or in parallel.
+
+If you find yourself reaching for `setTimeout`, `requestAnimationFrame`, or `addEventListener` to drive a visual, rebuild it as a tween on the timeline instead.

package/assets/.agent/skills/hyperframes-core/references/full-screen-motion.md

@@ -1,62 +1,62 @@
-# Full-Screen Motion Pattern
-
-For full-frame motion (continuous backgrounds, color washes, full-bleed visual states that span multiple clips), prefer a **shared background layer + transparent timed content layers** over stacked opaque scene backgrounds.
-
-## Why
-
-Stacking opaque scene divs means every scene change has to repaint the entire frame, every cross-scene visual continuity has to be faked, and every "global" state (a hue shift, a vignette, a film grain) has to be duplicated on every scene. A shared background layer driven by the seekable timeline gives you one continuous visual surface and makes scenes themselves cheap and transparent.
-
-## Pattern
-
-```html
-<div id="root" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
-  <!-- Shared background — NOT a clip. Always visible. Driven by the timeline. -->
-  <div id="bg" class="full-bleed"></div>
-
-  <!-- Timed content layers — transparent backgrounds. -->
-  <section
-    id="scene1"
-    class="clip transparent"
-    data-start="0"
-    data-duration="6"
-    data-track-index="1"
-  >
-    <!-- content -->
-  </section>
-  <section
-    id="scene2"
-    class="clip transparent"
-    data-start="6"
-    data-duration="14"
-    data-track-index="1"
-  >
-    <!-- content -->
-  </section>
-</div>
-
-<script>
-  window.__timelines = window.__timelines || {};
-  const tl = gsap.timeline({ paused: true });
-
-  // Drive the shared background from the seekable timeline.
-  tl.to("#bg", { backgroundColor: "#0a1530", duration: 6, ease: "sine.inOut" }, 0);
-  tl.to("#bg", { backgroundColor: "#1a0a30", duration: 14, ease: "sine.inOut" }, 6);
-
-  // Scene-local animations stay transparent on top.
-  tl.from("#scene1 h1", { y: 48, opacity: 0, duration: 0.6 }, 0.2);
-
-  window.__timelines["main"] = tl;
-</script>
-```
-
-## Rules
-
-- **The background is not a clip.** No `data-start` / `data-duration` / `data-track-index`. It exists for the whole composition.
-- **Content scenes have transparent backgrounds.** Whatever you put in the shared `#bg` shows through.
-- **Drive global state from the shared layer.** Hue shifts, vignettes, grain, film-look filters — animate them once on the shared layer, not per-scene.
-- **Do not animate visibility on `.clip` elements.** HyperFrames already shows/hides clips based on `data-start` and `data-duration`. Animating `display` / `visibility` on the clip itself races with the framework's own show/hide. Animate a _child wrapper_ inside the clip instead.
-- **Verify intentional overflow with snapshots.** Before adding `data-layout-allow-overflow` to silence an inspect warning, run `npx hyperframes snapshot` and confirm the overflow is what you want.
-
-## When Not to Use This Pattern
-
-If scenes really are visually disjoint — hard cuts between distinct color worlds with no continuity — the stacked-opaque pattern is fine. The shared-background pattern is for compositions where the background **is part of the motion language**, not just backdrop.
+# Full-Screen Motion Pattern
+
+For full-frame motion (continuous backgrounds, color washes, full-bleed visual states that span multiple clips), prefer a **shared background layer + transparent timed content layers** over stacked opaque scene backgrounds.
+
+## Why
+
+Stacking opaque scene divs means every scene change has to repaint the entire frame, every cross-scene visual continuity has to be faked, and every "global" state (a hue shift, a vignette, a film grain) has to be duplicated on every scene. A shared background layer driven by the seekable timeline gives you one continuous visual surface and makes scenes themselves cheap and transparent.
+
+## Pattern
+
+```html
+<div id="root" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
+  <!-- Shared background — NOT a clip. Always visible. Driven by the timeline. -->
+  <div id="bg" class="full-bleed"></div>
+
+  <!-- Timed content layers — transparent backgrounds. -->
+  <section
+    id="scene1"
+    class="clip transparent"
+    data-start="0"
+    data-duration="6"
+    data-track-index="1"
+  >
+    <!-- content -->
+  </section>
+  <section
+    id="scene2"
+    class="clip transparent"
+    data-start="6"
+    data-duration="14"
+    data-track-index="1"
+  >
+    <!-- content -->
+  </section>
+</div>
+
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // Drive the shared background from the seekable timeline.
+  tl.to("#bg", { backgroundColor: "#0a1530", duration: 6, ease: "sine.inOut" }, 0);
+  tl.to("#bg", { backgroundColor: "#1a0a30", duration: 14, ease: "sine.inOut" }, 6);
+
+  // Scene-local animations stay transparent on top.
+  tl.from("#scene1 h1", { y: 48, opacity: 0, duration: 0.6 }, 0.2);
+
+  window.__timelines["main"] = tl;
+</script>
+```
+
+## Rules
+
+- **The background is not a clip.** No `data-start` / `data-duration` / `data-track-index`. It exists for the whole composition.
+- **Content scenes have transparent backgrounds.** Whatever you put in the shared `#bg` shows through.
+- **Drive global state from the shared layer.** Hue shifts, vignettes, grain, film-look filters — animate them once on the shared layer, not per-scene.
+- **Do not animate visibility on `.clip` elements.** HyperFrames already shows/hides clips based on `data-start` and `data-duration`. Animating `display` / `visibility` on the clip itself races with the framework's own show/hide. Animate a _child wrapper_ inside the clip instead.
+- **Verify intentional overflow with snapshots.** Before adding `data-layout-allow-overflow` to silence an inspect warning, run `npx hyperframes snapshot` and confirm the overflow is what you want.
+
+## When Not to Use This Pattern
+
+If scenes really are visually disjoint — hard cuts between distinct color worlds with no continuity — the stacked-opaque pattern is fine. The shared-background pattern is for compositions where the background **is part of the motion language**, not just backdrop.

package/assets/.agent/skills/hyperframes-core/references/minimal-composition.md

@@ -1,66 +1,66 @@
-# Minimal Composition
-
-The smallest renderable HyperFrames composition — a standalone (top-level) root with one clip and one tween:
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=1920, height=1080" />
-    <title>Minimal HyperFrames Composition</title>
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-    <style>
-      body {
-        margin: 0;
-        background: #0b0f14;
-        color: white;
-        font-family: Inter, system-ui, sans-serif;
-      }
-      #root {
-        position: relative;
-        width: 1920px;
-        height: 1080px;
-        overflow: hidden;
-      }
-      .clip {
-        position: absolute;
-        inset: 0;
-        display: grid;
-        place-items: center;
-      }
-      h1 {
-        margin: 0;
-        font-size: 96px;
-      }
-    </style>
-  </head>
-  <body>
-    <div
-      id="root"
-      data-composition-id="main"
-      data-width="1920"
-      data-height="1080"
-      data-duration="5"
-    >
-      <section id="title-card" class="clip" data-start="0" data-duration="5" data-track-index="1">
-        <h1 id="title">Hello HyperFrames</h1>
-      </section>
-    </div>
-    <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.2);
-      window.__timelines["main"] = tl;
-    </script>
-  </body>
-</html>
-```
-
-Required elements:
-
-- Root `<div>` with `data-composition-id`, `data-width`, `data-height`, `data-duration`
-- At least one clip (any element with `data-start`, `data-duration`, `data-track-index`)
-- GSAP timeline created paused, registered on `window.__timelines["<composition-id>"]`
-
-This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.
+# Minimal Composition
+
+The smallest renderable HyperFrames composition — a standalone (top-level) root with one clip and one tween:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Minimal HyperFrames Composition</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        background: #0b0f14;
+        color: white;
+        font-family: Inter, system-ui, sans-serif;
+      }
+      #root {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+      .clip {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+      }
+      h1 {
+        margin: 0;
+        font-size: 96px;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-width="1920"
+      data-height="1080"
+      data-duration="5"
+    >
+      <section id="title-card" class="clip" data-start="0" data-duration="5" data-track-index="1">
+        <h1 id="title">Hello HyperFrames</h1>
+      </section>
+    </div>
+    <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.2);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Required elements:
+
+- Root `<div>` with `data-composition-id`, `data-width`, `data-height`, `data-duration`
+- At least one clip (any element with `data-start`, `data-duration`, `data-track-index`)
+- GSAP timeline created paused, registered on `window.__timelines["<composition-id>"]`
+
+This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.