dsh-hyperframes 0.3.2 → 0.4.1

package/skills/hyperframes-core/references/composition-patterns.md

@@ -1,6 +1,6 @@
 # Composition Patterns
 
-How to architect a project — when to inline everything in one HTML, when to split into sub-compositions, what the `index.html` orchestrator looks like at scale, and the common sub-composition archetypes seen in real projects. Pair with `minimal-composition.md` (single-file shape) and `sub-compositions.md` (mechanics of a sub-comp file).
+How to architect a project: the `index.html` orchestrator at scale, and the common sub-composition archetypes. Pair with `minimal-composition.md` (single-file shape) and `sub-compositions.md` (mechanics of a sub-comp file).
 
 ## Two Architectures
 
@@ -13,27 +13,6 @@ How to architect a project — when to inline everything in one HTML, when to sp
 
 Both architectures use the same runtime contract — `data-*` attributes + `window.__timelines[id]`. The choice is structural, not behavioral.
 
-### Pick monolithic when
-
-- The whole video is one continuous scene with no hard cuts.
-- Scenes share heavy state (one canvas/WebGL context spanning the whole video, a single SVG that morphs across all beats).
-- Total scope is small (~200–400 lines of markup + script).
-- No scene is reused across projects.
-
-### Pick modular when
-
-- The video has clear scene cuts — each scene is its own segment of the timeline.
-- Some scenes are large (>100 lines of markup or significant scripted animation).
-- A scene is reusable (kinetic intro, end-card logo lockup, a transition).
-- The video has a continuous audio track over multiple visual segments. Keep audio at the root, visual segments as sub-comps.
-- You want to author/iterate on scenes in isolation (preview a single sub-comp file directly).
-
-### Refactor between them
-
-Conversion is mechanical and reversible. To lift a monolithic scene into a sub-comp: wrap the scene's markup + scoped CSS + its slice of the parent timeline into a `<template>`, save as `compositions/<scene>.html`, replace the inline content in `index.html` with a slot `<div data-composition-src="compositions/<scene>.html">`, and have the sub-comp register its own timeline at `window.__timelines["<scene>"]`. The parent timeline shrinks accordingly.
-
-If a monolithic project is approaching three or more scene cuts, prefer modularizing _before_ adding the next scene. Mixed projects where some scenes are inline and siblings are in `compositions/` are the hardest to maintain.
-
 ## Modular Orchestrator Pattern
 
 When using sub-compositions, `index.html` should be **thin**. Its job is to declare slots, lay them out in time, mount the audio track, and register a (usually empty) root timeline. All scene animation lives inside the sub-comps.
@@ -51,8 +30,8 @@ When using sub-compositions, `index.html` should be **thin**. Its job is to decl
       }
       #root {
         position: relative;
-        width: 1920px;
-        height: 1080px;
+        width: 100%;
+        height: 100%;
         overflow: hidden;
       }
       /* Sub-comp slots stretch to fill the root. */
@@ -110,7 +89,6 @@ When using sub-compositions, `index.html` should be **thin**. Its job is to decl
     </div>
 
     <script>
-      window.__timelines = window.__timelines || {};
       window.__timelines["root"] = gsap.timeline({ paused: true });
     </script>
   </body>
@@ -162,7 +140,6 @@ The reason to reach for it: a sub-comp timeline **cannot** drive host elements (
 
 <script>
   // MAIN timeline drives the host video. Global time: scene starts at 20.
-  window.__timelines = window.__timelines || {};
   const main = window.__timelines["main"];
   main.fromTo(
     "#final-video",
@@ -182,7 +159,6 @@ The reason to reach for it: a sub-comp timeline **cannot** drive host elements (
     style="position:absolute; inset:0; pointer-events:none;"
   >
     <script>
-      window.__timelines = window.__timelines || {};
       const tl = gsap.timeline({ paused: true });
       // animate ONLY this sub-comp's own elements here (labels, frame, overlays)
       window.__timelines["final-anim"] = tl;
@@ -216,7 +192,6 @@ When several beat-level scenes share continuous state — a chat thread that gro
     <div class="phase" id="phase-b">…</div>
     <div class="phase" id="phase-c">…</div>
     <script>
-      window.__timelines = window.__timelines || {};
       const tl = gsap.timeline({ paused: true });
       tl.set("#phase-a", { opacity: 1 }, 0);
       tl.to("#phase-a", { opacity: 0, duration: 0.4 }, 3.0);
@@ -247,17 +222,3 @@ Audio always lives at the host (`index.html`) as a root-level `<audio>` so playb
 | Audio at root                       | `data-track-index` well above visual tracks | `10` while visuals use `1`                 |
 
 The `-template` suffix on `<template>` is conventional but not required — the runtime extracts contents from whichever `<template>` is in `<body>`, regardless of id. The prefix on inner element ids is the only safeguard against id collisions when multiple sub-comps are mounted into the same host page at once.
-
-## Editing Existing Projects
-
-Before adding or modifying scenes, identify which architecture is in use:
-
-```bash
-ls compositions/ 2>/dev/null && echo "modular" || echo "monolithic"
-```
-
-- In a **monolithic** project, add new scenes as inline `<section class="clip">` elements with a deliberate `data-start` and a sensible `data-track-index`, and extend the existing single timeline.
-- In a **modular** project, match the pattern: add a new file under `compositions/`, add a slot in `index.html`, keep the root timeline thin. Do **not** start inlining new scenes into `index.html` when sibling scenes are sub-comps — the inconsistency is the worst of both worlds.
-- If a monolithic project needs a third or fourth scene cut, lift each scene into a sub-comp before adding more. The conversion is mechanical (see "Refactor between them" above).
-
-When picking the slot's `data-start`/`data-duration`, prefer continuing the existing sequencing convention (adjoining starts, deliberate overlaps for cross-fades). Don't introduce a new track index unless you actually need parallel visual layers — most sequential-scene projects use exactly one visual track.

package/skills/hyperframes-core/references/creator-editing-recipes.md

@@ -2,6 +2,8 @@
 
 Use these copyable contracts after `tracks-and-clips.md`. Global math: **consumed source = timeline duration × rate**; **natural timeline duration = remaining source / rate**.
 
+Before any edit, run `npx hyperframes timeline` (add `--json` for a machine-readable list) to see the project's tracks and clips instead of reading the HTML.
+
 These recipes keep sound on a separate `<audio>` element with the `<video>` muted, which is the pattern to reach for when picture and sound are cut independently. An unmuted `<video>` that declares `data-has-audio="true"` is also mixed, so a separate track is a choice, not a requirement.
 
 **Every `<video>` and `<audio>` below carries an `id`, and that is not cosmetic**: `lint` errors with `media_missing_id` on timed media without one, and an id-less `<audio>` is never picked up by the mixer, so the render comes out silent. Keep the ids when you copy a recipe.
@@ -47,7 +49,7 @@ These recipes keep sound on a separate `<audio>` element with the `<video>` mute
 ></audio>
 ```
 
-Timeline math: B starts at A start + duration. Source math: each range starts at `data-media-start`; consumed source = timeline duration × rate. Audio follows: duplicate matching `<audio>` ranges/timing. Owner: `/hyperframes-core`. Limit: adjacent windows only; author the two windows edge to edge.
+Timeline math: B starts at A start + duration. Source math: each range starts at `data-media-start`; consumed source = timeline duration × rate. Audio follows: duplicate matching `<audio>` ranges/timing. Owner: `/hyperframes-core`. Limit: adjacent windows only; author the two windows edge to edge. Same-track overlap is valid; both clips paint in CSS order.
 
 ## Trim in/out
 
@@ -227,7 +229,7 @@ Timeline math: the still owns its hold duration. Source math: final-source frame
 ></video>
 ```
 
-Timeline math: duration is authored timeline time. Source math: consumed source = timeline duration × rate; natural timeline duration = remaining source / rate. Audio follows: matching separate audio track uses the same constant rate. Owner: `/hyperframes-core`. Limit: normalized 0.1..5 constant only; no speed ramp envelope.
+Timeline math: duration is authored timeline time. Source math: consumed source = timeline duration × rate; natural timeline duration = remaining source / rate. Audio follows: matching separate audio track uses the same constant rate. Owner: `/hyperframes-core`. Limit: normalized 0.1..10. For a speed ramp put a `rate` lane in `data-automation`, e.g. `{"version":1,"lanes":[{"target":"rate","points":[{"t":0,"v":1},{"t":2,"v":4}]}]}`; it wins over the constant.
 
 ## Zoom / punch
 
@@ -314,11 +316,10 @@ Timeline math: overlap placed clips for the 0.5s handoff. Source math: each clip
 ></audio>
 <script>
   const tl = gsap.timeline({ paused: true });
-  tl.set("#b-visual", { autoAlpha: 0 }, 0)
-    .to("#a-visual", { autoAlpha: 0, duration: 0.5 }, 2.5)
-    .to("#b-visual", { autoAlpha: 1, duration: 0.5 }, 2.5);
-  window.__timelines = window.__timelines || {};
-  window.__timelines.main = tl;
+  tl.set("#b-visual", { opacity: 0 }, 0)
+    .to("#a-visual", { opacity: 0, duration: 0.5 }, 2.5)
+    .to("#b-visual", { opacity: 1, duration: 0.5 }, 2.5);
+  window.__timelines["main"] = tl;
 </script>
 ```
 
@@ -339,6 +340,8 @@ Timeline math: distinct tracks overlap by 0.5s with opposing opacity envelopes.
 
 Timeline math: lane `t` is clip-local authored time: fade-in 0–1, duck down 2–2.2, hold 2.2–3, duck up 3–3.2, fade-out 4–5. Source math: source selection still uses core attributes. Audio follows: the explicit down-hold-up envelope affects this separate audio track. Owner: `/hyperframes-audio`. Limit: automation is not source retiming.
 
+**One rule for volume over time: use the lane.** `lint` accepts a timeline tween on `volume` too, but when a track has both, the lane wins and the tween is ignored (`audio_volume_double_automation`). Never add a lane to a track that already has a `volume` tween, and never add a tween to a track that has a lane; edit the one that exists. To ramp 0.1 to 0.5 over ten seconds, write `{"t":0,"v":0.1},{"t":10,"v":0.5}`. `t` is seconds from the clip's own start, so a ramp past `data-duration` never finishes: check the clip's length before choosing the times. `data-volume` stays as the static level of the clip and combines with nothing else you author here.
+
 ## Audio alignment
 
 ```html
@@ -365,3 +368,124 @@ Timeline math: lane `t` is clip-local authored time: fade-in 0–1, duck down 2
 ```
 
 Timeline math: picture and sound share start/duration. Source math: both consume four source seconds. Audio follows: identical timing, range, and rate on the separate audio track. Owner: `/hyperframes-core` + `/hyperframes-audio`. Limit: no waveform auto-sync or drift correction.
+
+## Align a sound to an on-screen event
+
+```html
+<audio
+  id="sfx-click-3"
+  src="click.mp3"
+  data-start="7.48"
+  data-duration="0.07"
+  data-track-index="103"
+  data-volume="0.85"
+></audio>
+```
+
+Timeline math: an audio element in the root composition has `data-start` in absolute root time; audio inside a scene file uses scene-local time and the host's `data-start` is added for you. An event inside a sub-composition happens at the host's `data-start` plus the event's local time in that sub-composition's own timeline, so `data-start = host start + local time`. Move only the audio's `data-start`; leave the picture alone. Source math: if the sound's transient is not at the file's first sample, subtract that lead-in from `data-start` (or trim it with `data-media-start`). Audio follows: nothing links audio to picture, so re-derive after every retime of the host. Owner: `/hyperframes-core`. Limit: no waveform auto-sync; for a beat grid use `hyperframes beats` and place each start on a beat time.
+
+## Copy a group of clips to another time
+
+```html
+<audio
+  id="sfx-click-0"
+  src="click.mp3"
+  data-start="1.6"
+  data-duration="0.07"
+  data-track-index="100"
+></audio>
+<audio
+  id="sfx-type-0"
+  src="typenew.mp3"
+  data-start="7.8"
+  data-duration="0.57"
+  data-track-index="109"
+></audio>
+<audio
+  id="sfx-click-0-copy"
+  src="click.mp3"
+  data-start="41.6"
+  data-duration="0.07"
+  data-track-index="186"
+></audio>
+<audio
+  id="sfx-type-0-copy"
+  src="typenew.mp3"
+  data-start="47.8"
+  data-duration="0.57"
+  data-track-index="187"
+></audio>
+```
+
+Timeline math: pick the clips first and say which ones you picked (by id) if the request does not match the file exactly; then add one `delta` to every member's `data-start`, so relative spacing is preserved (here `delta = 40`). Give each copy a new unique `id` and the next unused `data-track-index`; keep `src`, `data-duration`, `data-media-start`, `data-volume` and any `data-automation` as they are. Leave the originals untouched. Check the copies still end inside the composition's duration. Owner: `/hyperframes-core`. Limit: copies of a `<video>` or a sub-composition host follow the same rule, and a copied sub-composition needs its own host `id`.
+
+## Add media (image, video, audio)
+
+Write what Studio writes when a person drops a file on the timeline, so an agent-added clip behaves the same as a dropped one; the one difference is that video and audio need no `data-duration`. Studio's source of truth is `DEFAULT_TIMELINE_ASSET_DURATION` in `packages/studio/src/utils/studioHelpers.ts` and `buildTimelineAssetInsertHtml` in `packages/studio/src/utils/timelineAssetDrop.ts`; a test keeps this section equal to them.
+
+- **Image: `data-duration` is optional and defaults to 3 seconds**, the same as a dropped image, because a still has no length of its own. Write it only for another length. A test keeps the 3 equal to the default in code.
+- **Video and audio: `data-start` is enough.** The length comes from the media itself. An authored `data-duration` shorter than the file is a trim, never a requirement; leave it out unless the request asks for a shorter clip.
+- **Start: the playhead or the requested time, never a silent `0`.** Studio's asset-panel Add uses the playhead time on track `0`; a drop uses the drop point.
+- Give every clip `id`, `class="clip"`, `data-start` and `data-track-index`. Video is `muted playsinline`; audio carries `data-volume="1"`.
+- Then make sure the root composition's `data-duration` is at least the clip's end (`data-start` plus its length: 3 for an image unless you set another, the media's length for video and audio): Studio raises a declared root duration to cover the new clip, so an agent must too, or the clip lies past the end and never plays.
+- **Images and video fill the whole frame**: absolutely positioned at `left: 0; top: 0`, `width` and `height` equal to the composition's `data-width` and `data-height`, `object-fit: contain`. Studio does not know a dropped file's natural size, so it does not centre a smaller one.
+- `z-index` is the number of top-level clips already in that file plus one (at least `1`); later clips stack above earlier ones.
+- Several files dropped together share the drop's track and run end to end.
+
+```html
+<img
+  id="photo"
+  class="clip"
+  src="assets/photo.png"
+  data-start="4"
+  data-track-index="1"
+  style="position: absolute; left: 0px; top: 0px; width: 1920px; height: 1080px; object-fit: contain; z-index: 2"
+/>
+```
+
+```html
+<video
+  id="broll"
+  class="clip"
+  src="assets/broll.mp4"
+  data-start="4"
+  data-track-index="2"
+  muted
+  playsinline
+  style="position: absolute; left: 0px; top: 0px; width: 1920px; height: 1080px; object-fit: contain; z-index: 3"
+></video>
+```
+
+```html
+<audio
+  id="whoosh"
+  class="clip"
+  src="assets/whoosh.mp3"
+  data-start="4"
+  data-track-index="3"
+  data-volume="1"
+></audio>
+```
+
+Inside a sub-composition file, `data-start` is scene-local (see `## Align a sound to an on-screen event`). Owner: `/hyperframes-core`.
+
+## Swap a media file
+
+```html
+<video
+  id="hero"
+  src="assets/product-v2.mp4"
+  data-start="2"
+  data-duration="4"
+  data-media-start="0"
+  data-track-index="0"
+  muted
+  playsinline
+></video>
+```
+
+Timeline math: change only `src`. Source math: reset `data-media-start` to the offset you want in the NEW file, and set `data-duration` no longer than the new file's remaining length (probe it with `ffprobe`). Audio follows: a separate `<audio>` that pointed at the old file needs the same `src` swap. Keep `id`, `data-start`, `data-track-index` and any `data-automation` so nothing else moves. Run `lint`: `audio_src_not_found` and `media_src_kind_mismatch` catch a wrong path or kind. Owner: `/hyperframes-core`. Limit: a still swapped for a video (or the reverse) is a tag change, not a swap.
+
+## Split a section and change its speed
+
+Timeline math: a section that is a sub-composition or a group of clips has no `data-playback-rate` of its own to set; split it by giving each half its own host or clips and shift everything after the cut by the length change. New length of a part = old length / rate. Every later `data-start` (clips, audio, root-timeline tweens) moves by the same delta. Source math: `<video>` and `<audio>` parts use `data-playback-rate` (0.1 to 10, constant) per the constant-speed recipe above, with matching audio. A speed ramp (a rate that changes within one clip) is a `rate` lane in `data-automation` on the `<video>`/`<audio>`; see `docs/reference/speed-ramps`. Say which you did.

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

@@ -14,7 +14,7 @@ Every renderable composition needs one root element:
 | `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.
+\*`data-duration` is optional whenever the runtime can auto-infer duration: a registered GSAP timeline, a finite CSS animation, a finite WAAPI `element.animate()`, a registered Lottie animation, or timed clips (the root then ends at its latest clip end, and lint only warns `root_composition_duration_derived`). It is **required** for Three.js (no auto-inference), for infinite/unbounded CSS or WAAPI animations, and for any composition with no GSAP timeline, no animation signal and no timed clip with a length. `npx hyperframes lint` enforces this (`root_composition_missing_duration_source`). Per-runtime inference lives in `hyperframes-animation/adapters/`.
 
 The root should be `position: relative`, have explicit pixel dimensions, and hide overflow unless intentionally composing outside the frame.
 
@@ -22,19 +22,19 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid
 
 **`data-start` is what makes an element a clip.** The runtime collects `[data-start]` and drives visibility off that attribute, so any element carrying it is timed.
 
-`class="clip"` is a **convention, not a requirement**: the runtime never reads it. Keep writing it, because the scaffold's shared `.clip { position: absolute; inset: 0 }` rule is what gives a scene its full-frame box, Studio uses it as an edit hint, and `lint` warns (`timed_element_missing_clip_class`) when a timed element lacks it. If you drop the class you must supply that layout yourself. Omit it on `<video>` and `<audio>`.
+`class="clip"` is a **convention, not a requirement**: the runtime never reads it. Keep writing it: drop it and the full-frame box collapses unless you supply that layout yourself, Studio uses it as an edit hint, and `lint` warns (`timed_element_missing_clip_class`) when a timed element lacks it. Omit it on `<video>` and `<audio>`.
 
 **Nesting is allowed.** A timed element inside a wrapper is still timed, and a timed ancestor clamps its descendants: a child cannot be visible while its timed ancestor is hidden. Direct children of the root get automatic layout (see "Root-level clips get automatic layout" below); nested ones do not, so give them their own positioning.
 
-| Attribute          | Required                                        | Meaning                                                                                                                                                                                                                                                                        |
-| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`               | Yes on `<video>`/`<audio>`, else recommended    | `lint` errors with `media_missing_id` on media without one, and an id-less `<audio>` is never mixed, so the render is **silent**. Elsewhere it is a warning (`studio_missing_editable_id`): Studio needs a stable edit target, and timeline targets reference it.              |
-| `data-start`       | Yes                                             | Start time in seconds, or a supported clip-time reference. This attribute is what marks the element as timed.                                                                                                                                                                  |
-| `data-duration`    | Required for `div`, `img`, and sub-compositions | Duration in seconds. Video/audio can default to media duration when known. Without any resolvable duration the element has no end and stays visible for the rest of the composition.                                                                                           |
-| `data-track-index` | No                                              | Studio timeline lane, display only. The render never reads it, and clips on one track may overlap in time. Absent, the parser defaults it and Studio lays out one lane per clip. Two `<audio>` elements on the same index that overlap in time raise a `lint` warning.         |
-| `data-media-start` | No                                              | Offset into the media source, in seconds.                                                                                                                                                                                                                                      |
-| `data-volume`      | No                                              | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades, animate `volume` on the timeline instead (see `variables-and-media.md`); a tween's own values replace this baseline entirely. |
-| `data-has-audio`   | No (`<video>` only)                             | `"true"` to declare the video carries an audio track when auto-detection would miss it.                                                                                                                                                                                        |
+| Attribute          | Required                                     | Meaning                                                                                                                                                                                                                                                                                            |
+| ------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | Yes on `<video>`/`<audio>`, else recommended | `lint` errors with `media_missing_id` on media without one, and an id-less `<audio>` is never mixed, so the render is **silent**. Elsewhere it is a warning (`studio_missing_editable_id`): Studio needs a stable edit target, and timeline targets reference it.                                  |
+| `data-start`       | Yes                                          | Start time in seconds, or a supported clip-time reference. This attribute is what marks the element as timed.                                                                                                                                                                                      |
+| `data-duration`    | Required for `div` and sub-compositions      | Duration in seconds. An `img` with `data-start` defaults to 3 s; video/audio default to the source length (less the playback offset, over the rate) once known; an authored value trims. Without any resolvable duration the element has no end and stays visible for the rest of the composition. |
+| `data-track-index` | No                                           | Studio timeline lane, display only. The render never reads it, and clips on one track may overlap in time. Absent, the parser defaults it and Studio lays out one lane per clip. Two `<audio>` elements on the same index that overlap in time raise a `lint` warning.                             |
+| `data-media-start` | No                                           | Offset into the media source, in seconds.                                                                                                                                                                                                                                                          |
+| `data-volume`      | No                                           | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades and ducking, use the `data-automation` volume lane (see `creator-editing-recipes.md`).                                                             |
+| `data-has-audio`   | No (`<video>` only)                          | `"true"` to declare the video carries an audio track when auto-detection would miss it.                                                                                                                                                                                                            |
 
 **The visibility window is half-open: `[start, start + duration)`.** A clip shows while `start ≤ t < start + duration` and is hidden at exactly `t = start + duration`. Land an animation's resolved end state slightly **before** `data-duration`, not on it, or its last frame is never rendered. Two clips can therefore be authored back to back (`b.start === a.start + a.duration`) with no overlapping frame.
 

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

@@ -15,18 +15,7 @@ For GSAP:
 - **Do not** call `tl.play()` for render-critical motion.
 - **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
 
-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.
+Use the `hyperframes-animation` skill for tween syntax, position parameters, eases, and performance rules. Non-GSAP duration inference lives in `hyperframes-animation/adapters/`.
 
 ## Determinism Rules
 
@@ -40,7 +29,7 @@ Rendered frames must be reproducible from the requested time. Do **not** use any
 
 Also avoid:
 
-- Tweening `display` or raw `visibility` **on a clip element**: HyperFrames timing owns a clip's visibility, and `lint` rejects it. Use GSAP `autoAlpha` (it interpolates opacity and flips visibility only at the hidden endpoint) or a zero-duration `tl.set(..., { visibility: "hidden" | "visible" })` at an explicit beat boundary for a deterministic hard kill. Animating a clip element's ordinary visual properties (`opacity`, transforms, `filter`, …) is fine and the shipped catalog does it constantly; what is forbidden is taking over its visibility.
+- Tweening `display`, raw `visibility`, or `autoAlpha` **on a clip element**: HyperFrames timing owns a clip's visibility, and `lint` rejects it (`gsap_animates_clip_element`). Fade with `opacity`, or tween a child wrapper. Do not tween `class="clip"`.
 - There is no fixed allowlist of animatable properties. `lint` enforces a **denylist**, so `filter`, `clipPath`, `strokeDashoffset`, `width`, `height` and similar are all legitimate targets. Prefer transforms and opacity where you have the choice, for performance rather than correctness. The per-runtime detail lives in `hyperframes-animation/adapters/`.
 - 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.
 
@@ -62,9 +51,3 @@ Build the visible end-state in static HTML and CSS first, then animate from/to t
 - **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 — automated gates may 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/skills/hyperframes-core/references/full-screen-motion.md

@@ -2,10 +2,6 @@
 
 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
@@ -48,7 +44,6 @@ Stacking opaque scene divs means every scene change has to repaint the entire fr
 </div>
 
 <script>
-  window.__timelines = window.__timelines || {};
   const tl = gsap.timeline({ paused: true });
 
   // Drive the shared background from the seekable timeline.
@@ -70,7 +65,3 @@ Stacking opaque scene divs means every scene change has to repaint the entire fr
 - **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/skills/hyperframes-core/references/minimal-composition.md

@@ -19,8 +19,8 @@ The smallest renderable HyperFrames composition — a standalone (top-level) roo
       }
       #root {
         position: relative;
-        width: 1920px;
-        height: 1080px;
+        width: 100%;
+        height: 100%;
         overflow: hidden;
       }
       .clip {

package/skills/hyperframes-core/references/sub-compositions.md

@@ -48,8 +48,7 @@ So `<template>` is not just a wrapper — it is the **transport container**. If
     <template>
       <!-- EVERYTHING the runtime needs goes here: styles, markup, scripts -->
       <style>
-        /* Root: style by #root, never a class. (At render the CSS is scoped to
-           data-composition-id, so a class on the root stops matching — see Pitfall 3.) */
+        /* Root: style by #root, never a class. lint: subcomposition_root_styled_by_class. See Pitfall 3. */
         #root {
           position: absolute;
           inset: 0;
@@ -63,7 +62,6 @@ So `<template>` is not just a wrapper — it is the **transport container**. If
       </div>
 
       <script>
-        window.__timelines = window.__timelines || {};
         const tl = gsap.timeline({ paused: true });
         // ... build timeline ...
         window.__timelines["data-chart"] = tl;
@@ -77,7 +75,7 @@ Contrast with **standalone** compositions, which put the root directly in `<body
 
 ## Common pitfalls that pass static checks but break at render
 
-Static file checks cannot prove the **cross-file mount contract**. These failures appear only when the runtime mounts the sub-composition. Watch for them at author time and verify with the pre-render snapshot checklist below.
+Static file checks cannot prove the **cross-file mount contract**. These failures appear only when the runtime mounts the sub-composition.
 
 ### Pitfall 1 — `<style>` in `<head>` instead of inside `<template>`
 
@@ -137,68 +135,7 @@ Static file checks cannot prove the **cross-file mount contract**. These failure
 
 ### Pitfall 3 — Styling the root by a class instead of `#root`
 
-```html
-<!-- ❌ WRONG — class on the root, stylesheet keyed off it -->
-<template>
-  <style>
-    .frame {
-      position: absolute;
-      inset: 0;
-      background: #faf9f5;
-    }
-    .frame .title {
-      font-size: 120px;
-    }
-  </style>
-  <div id="root" class="frame" data-composition-id="03-scene" ...>
-    <div class="title">…</div>
-  </div>
-</template>
-
-<!-- ✅ RIGHT — root styled by #root, descendants by plain selectors -->
-<template>
-  <style>
-    #root {
-      position: absolute;
-      inset: 0;
-      background: #faf9f5;
-    }
-    .title {
-      font-size: 120px;
-    }
-  </style>
-  <div id="root" data-composition-id="03-scene" ...>
-    <div class="title">…</div>
-  </div>
-</template>
-```
-
-**Why this happens:** when sub-compositions are inlined into one composited render, the compiler **scopes each file's CSS to its own `data-composition-id`** so scenes can't leak styles into each other: every rule `S` becomes `[data-composition-id="<id>"] S` (a _descendant_ selector). A rule whose leftmost selector is the **root's own class** (`.frame`) therefore becomes `[data-composition-id="<id>"] .frame`, which cannot match the scoped element itself. `#root` is special-cased by the scoper and keeps matching the root; plain descendant selectors (`.title`) match normally. The per-scene class namespace is also just redundant, since the `data-composition-id` scope already isolates each scene's styles.
-
-**What actually happens today:** the render no longer drops these rules. Since #1886 the producer preserves the authored root as a `data-hf-inner-root` wrapper _inside_ the scoped element, so a class on the root still matches as a descendant and preview and render agree. The regression is pinned by `packages/producer/tests/sub-comp-class-selector/`.
-
-**So why still use `#root`?** Because `lint` rejects the class form outright (`subcomposition_root_styled_by_class`, **error**), and it is the pattern the registry blocks model (e.g. `apple-money-count`). Treat this as a lint constraint you must satisfy, not as a render bug you are avoiding. If you inherited a composition that styles its root by class, it renders correctly; you still have to convert it to `#root` to get a green `lint`.
-
-### Verification checklist before render
-
-```bash
-# For every sub-composition file in compositions/:
-#   1) <style> + <script> + main markup all live INSIDE <template>
-grep -n "<style\|<script\|<template" compositions/<scene>.html
-#      → first <style>/<script>/<div data-composition-id> should be AFTER <template>, before </template>
-
-#   2) host data-composition-id == internal data-composition-id == window.__timelines key
-grep "data-composition-id" index.html
-grep "data-composition-id\|__timelines\[" compositions/<scene>.html
-#      → all three strings must match exactly per scene
-
-#   3) the root is styled by #root, not by a class on the data-composition-id element
-grep -n 'data-composition-id=' compositions/<scene>.html
-#      → that element should NOT also carry a class="…" that the <style> keys off
-#        (e.g. `.frame { … }`); scoping drops it. Style the root via #root. See Pitfall 3.
-```
-
-For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeball), see the **Visual smoke test** step in `hyperframes-cli`'s Minimum Completion Gate — that is the only gate that catches these three pitfalls.
+`lint` still errors (`subcomposition_root_styled_by_class`) if a sub-composition styles the host root's own class. Style the root with `#root`.
 
 ## What HyperFrames Does With the Sub-Composition
 

package/skills/hyperframes-core/references/tailwind.md

@@ -2,13 +2,6 @@
 
 HyperFrames `init --tailwind` uses the Tailwind browser runtime pinned by the scaffold. Treat it as Tailwind v4, not Studio's Tailwind v3 setup.
 
-## When To Use
-
-- The project was scaffolded with `npx hyperframes init --tailwind`.
-- `index.html` contains `window.__tailwindReady`.
-- The task asks for Tailwind utility classes, `@theme`, custom utilities, or v3-to-v4 fixes in a composition.
-- Rendered frames have missing Tailwind styles or frame-0 flashes.
-
 ## Version Contract
 
 - **Pinned: `@tailwindcss/browser@4.2.4`** (source of truth: `packages/cli/src/commands/init.ts` `TAILWIND_BROWSER_VERSION`).
@@ -44,7 +37,7 @@ Avoid v3-only patterns in browser-runtime compositions:
 
 Do not add `tailwind.config.js` only for composition colors, fonts, spacing, or utilities. Use `@theme` and `@utility`.
 
-**Migrating from v3?** Load an existing JS config explicitly: put `@config "./tailwind.config.js";` inside a `text/tailwindcss` block. v4 does **not** auto-detect v3 config files.
+**`@config` / `@plugin` abort the browser compile.** The pinned `@tailwindcss/browser` build does not support JS config or plugins. Theme and utilities stay in a `text/tailwindcss` block.
 
 ## Composition Pattern
 
@@ -109,15 +102,3 @@ npx hyperframes check
 # Render proof — frame 0 must NOT flash unstyled content. Preview alone can hide this.
 npx hyperframes render . --workers 1 --quality draft --output tailwind-proof.mp4
 ```
-
-## Quick Debug Checklist
-
-When Tailwind styles don't apply in a render, check in order:
-
-1. Project scaffolded with `npx hyperframes init --tailwind`?
-2. `index.html` `<head>` has `<script src="…@tailwindcss/browser@4.2.4…">` (not `cdn.tailwindcss.com`)?
-3. `window.__tailwindReady` Promise present in `<head>`?
-4. No v3 directives (`@tailwind base/components/utilities`) in the file?
-5. Tokens moved from `tailwind.config.js` to `@theme` (or `@config` reference for v3 migration)?
-6. Every render-critical class appears as a complete static token (no `bg-${color}-500` style assembly)?
-7. Re-run `npx hyperframes check`, then the render proof above.

package/skills/hyperframes-core/references/tracks-and-clips.md

@@ -10,7 +10,7 @@ A clip is any DOM element with `data-start` and, where required, `data-duration`
 - **Sub-composition hosts** — `<div>` with `data-composition-src`. Always require `data-duration`.
 - **Video clips** — `<video>` with `muted` and `playsinline`. Duration can default to media length.
 - **Audio clips** — `<audio>`. Duration can default to media length.
-- **Image clips** — `<img>`. Always require `data-duration`.
+- **Image clips** — `<img>`. `data-duration` is optional and defaults to 3 seconds; write it only for another length.
 
 Add `class="clip"` to authored visual clips. The runtime does not read it, but the scaffold's shared `.clip { position: absolute; inset: 0 }` rule is what gives a scene its full-frame box, Studio treats it as an edit hint, and `lint` warns without it.
 
@@ -28,11 +28,7 @@ The one place the value carries meaning: two `<audio>` elements that share a tra
 
 ## Picking a Track Index
 
-Purely a readability choice for whoever opens the file in Studio. Common patterns:
-
-- **Track 0** — base video (e.g. an A-roll).
-- **Track 1+** — visual scenes, overlays, captions.
-- **Higher tracks (e.g. 10+)**: audio clips, separated from visual tracks.
+Purely a readability choice for whoever opens the file in Studio. Common patterns, owned by `/hyperframes-studio` (one caption track, one element kind per track).
 
 When adding a clip to an existing composition, set its `data-start`/`data-duration` against the clips around it. You do not need to hunt for a free lane, and you never need to renumber tracks after a retime.
 

package/skills/hyperframes-core/references/variables-and-media.md

@@ -58,11 +58,11 @@ document.getElementById("title").textContent = title;
 ### Two JSON Shapes (Easy to Confuse)
 
 - `data-composition-variables` is an **array of declarations** (the schema): `[{id, type, label, default}, ...]`
-- `--variables` and `data-variable-values` are **objects keyed by id** (the values): `{ title: "Q4", accent: "#fff" }`
+- `--variables` and `data-variable-values` are **objects keyed by id** (the values): `{"title":"Q4","accent":"#fff"}`
 
 ## Media
 
-**`<video>`/`<audio>` work at any nesting depth, including inside a sub-composition `<template>` or a wrapper `<div>`.** The runtime discovers media with a flat `document.querySelectorAll("video, audio")`, resolves each element's host composition via `element.closest("[data-composition-id]")`, and rebases its local `data-start` by the accumulated absolute start of every ancestor composition (`packages/core/src/runtime/{media,startResolver}.ts`). So a scene-specific clip can live in its scene's sub-comp with scene-local `data-start`, and it seeks/decodes correctly. If a panel renders blank after a render, that is a real bug: capture a per-frame `snapshot` and treat it as render-blocking.
+**`<video>`/`<audio>` work at any nesting depth, including inside a sub-composition `<template>` or a wrapper `<div>`.** The runtime discovers media with a flat `document.querySelectorAll("video, audio")`, resolves each element's host composition via `element.closest("[data-composition-id]")`, and rebases its local `data-start` by the accumulated absolute start of every ancestor composition. A host at `2` with child media at `2` therefore starts that media at root time `4`, consistently in preview, snapshot, extraction, and render. Legacy projects that deliberately authored a media start in root time must mark that element with `data-hf-media-start-basis="global"`; never infer the basis from overlapping numbers. New compositions should always use scene-local `data-start`. If a panel renders blank after a render, capture a per-frame `snapshot` and treat it as render-blocking.
 
 The one real constraint is about **timelines, not media placement**: a sub-composition timeline **cannot reach or animate host elements** — neither `document.querySelector("#host-id")` nor a gsap selector string (`tl.to("#host-id", …)`) resolves across the boundary; a sub-comp timeline only drives its own subtree. So if a media element lives at the host root, **its per-scene motion (scale/opacity/morph/tilt/breathing) must be authored on the MAIN timeline in `index.html`, at GLOBAL time** (scene-local time + the scene slot's `data-start`). Keeping the media inside the scene sub-comp instead lets that sub-comp's own timeline animate it with scene-local time. For 3D tilt without a perspective parent, use gsap `transformPerspective` on the element. See `composition-patterns.md` archetype B.
 
@@ -100,7 +100,7 @@ Video elements must be muted and inline. Audio must be a separate `<audio>` elem
 - **Never** add `crossorigin` to `<video>`/`<audio>`. `lint` rejects it unconditionally (`media_crossorigin_breaks_preview`, error) because a media host without `Access-Control-Allow-Origin` then fails silently in preview while renders still work, hiding the bug. There is no suppression, so this holds even for the canvas/WebGL/WebAudio readback case.
 - **Every `<audio>` needs an `id`.** The mixer selects `audio[id][src]`, so an id-less `<audio>` is never mixed and the render is **silent**. `lint` catches it as `media_missing_id`.
 - Audio always lives on a separate `<audio>` element — even if its source file is the same as a `<video>`. The `<video>` is muted; the `<audio>` carries sound.
-- For volume fades/ducking, animate `volume` on the timeline (`tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`) rather than swapping `data-volume`. The runtime probes the timeline's volume keyframes and applies them identically in preview and render; `data-volume` is the static baseline for elements no tween touches. A tween's values REPLACE that baseline rather than scaling it, so on a clip whose gain is not `1` you scale the tween's targets instead (`{ volume: 1.95 }`, not `{ volume: 1 }`) — `lint` warns with `audio_volume_tween_overrides_gain` when the two disagree.
+- For volume fades and ducking, use the `data-automation` volume lane; the exact form is in `creator-editing-recipes.md`. `data-volume` is the static baseline. A timeline `volume` tween is ignored when a lane is present.
 
 For media duration: `<video>` and `<audio>` can omit `data-duration` if the media's intrinsic length is known and you want the full clip. Otherwise provide `data-duration` explicitly.
 

package/skills/hyperframes-creative/SKILL.md

@@ -3,6 +3,8 @@ name: hyperframes-creative
 description: Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 # HyperFrames Creative
 
 Brand, pacing, style, narration, and composition direction. Use after the technical contract from `hyperframes-core` is in place.