freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/skills/hyperframes-audio/references/presets.md

@@ -0,0 +1,216 @@
+# Presets, jobs and one-knob profiles
+
+Everything here is a shortcut to a chain you could have built by hand. A preset
+writes ordinary nodes tagged with `fromPreset`, a job writes one ordinary node
+with a name, and a profile is one control over several parameters of one effect.
+Nothing is opaque: open any of them and you find effects from
+[`fx-registry.md`](./fx-registry.md) with their parameters showing.
+
+Reach for one when it names the problem you actually have. Build by hand when
+none of them does — a preset applied because it was nearby is worse than three
+deliberate nodes.
+
+---
+
+## Diagnose first: what to listen for, and what fixes it
+
+Work from the symptom, not from the effect list. Most bad audio is one or two of
+these, and the fix is usually a job rather than a whole preset.
+
+| It sounds like                                | Where it lives | Reach for                                                    |
+| --------------------------------------------- | -------------- | ------------------------------------------------------------ |
+| Hum, rumble, traffic, footsteps, handling     | 20–80 Hz       | `rumble-cut` preset, or a `highpass` at 80 Hz                |
+| Boomy, chesty, too close to the mic           | 80–250 Hz      | **Tame Boominess** job (200 Hz, −4 dB)                       |
+| Muffled, like it is behind cardboard          | 250–600 Hz     | **Reduce Mud** job (250 Hz, −3 dB)                           |
+| Boxy, like a small room                       | ~400 Hz        | **Reduce Boxiness** job (400 Hz, −3 dB)                      |
+| Words hard to make out, sits behind the music | 2–5 kHz        | **Add Clarity** job (3 kHz, +2.5 dB), or carve the bed       |
+| Harsh, brittle, tiring over a whole listen    | 3–5 kHz        | **Soften Harshness** job (3.2 kHz, −3 dB)                    |
+| Sibilant — `s` sounds spitting                | 5–10 kHz       | Nothing shipped does this properly; see "Not covered" below  |
+| Dull, closed-in, lifeless                     | 10–20 kHz      | `highshelf` lift, or `voice-broadcast` which includes one    |
+| Some words much louder than others            | not a band     | **Evenness** profile on a `compressor`, or `levellingResult` |
+| Room tone audible between sentences           | not a band     | `room-gate` preset (**Tightness** profile)                   |
+| Peaks clipping or spiking                     | not a band     | `limiter` last in the chain — every voice preset ends in one |
+| Voice and music fighting each other           | 1–3 kHz mostly | **Voiceover carve**, not an EQ on either track               |
+| Dry, stuck to the speaker, recorded nowhere   | not a band     | `room-tight` or `room-natural`                               |
+
+**The band vocabulary** these map onto — the same names the rack shows:
+
+| Range          | Name     | What lives there             |
+| -------------- | -------- | ---------------------------- |
+| 20–80 Hz       | Rumble   | traffic, footsteps, handling |
+| 80–250 Hz      | Weight   | chest, body, warmth          |
+| 250–600 Hz     | Mud      | boxy, muffled, cardboard     |
+| 600–2000 Hz    | Middle   | the body of a voice          |
+| 2000–5000 Hz   | Presence | consonants, intelligibility  |
+| 5000–10000 Hz  | Edge     | sibilance, harshness         |
+| 10000–20000 Hz | Air      | sparkle, openness            |
+
+### Order of operations
+
+Diagnose in this order, because each step changes what the next one hears:
+
+1. **Subtract before you add.** Cut rumble and mud first. A voice that sounds
+   dull often has too much low-mid, not too little top — lifting the top of a
+   muddy voice makes it muddy _and_ harsh.
+2. **Level after you filter.** A compressor reacts to whatever is loudest, and
+   a rumble it can no longer see is a rumble it stops chasing.
+3. **Relationships after level.** Carve a bed against a voice once the voice
+   itself is settled, or the analysis measures a problem you are about to fix.
+4. **Character, then ceiling.** Saturation and space go late; a `limiter` goes
+   last, where it can actually act as a ceiling. Anything after it is not
+   bounded by it.
+
+---
+
+## Presets
+
+Four families, listed in full below. Apply one and it **appends** — stacking a character preset
+onto an already-cleaned voice is a real thing to want. Re-applying one that is
+already present replaces its own nodes in place, because position in the chain
+is signal order.
+
+### Voice — make a real voice sound like its better self
+
+| Preset            | Answers                         | Chain                                                                                               |
+| ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `voice-clean`     | "My voice sounds amateur"       | Remove Rumble → Reduce Mud → Even Out Loudness → Add Clarity → Peak Ceiling                         |
+| `voice-broadcast` | "I want it to sound like radio" | Remove Rumble → Reduce Boxiness → Even Out Loudness → Add Clarity → Add Air → Warmth → Peak Ceiling |
+| `voice-warm`      | "I want it intimate and close"  | Remove Rumble → Add Weight → Even Out Loudness → Add Clarity → Peak Ceiling                         |
+
+`voice-clean` is the default answer to "fix this voiceover". The other two are
+the same idea pushed in one direction: broadcast is denser and more forward,
+warm has body added rather than cut.
+
+### Repair — one problem, one node
+
+| Preset       | Answers                                 | Does                                                                        |
+| ------------ | --------------------------------------- | --------------------------------------------------------------------------- |
+| `rumble-cut` | "There's a hum or thump underneath"     | High-pass under the voice                                                   |
+| `room-gate`  | "I can hear the room between sentences" | Closes the pauses. **Does not remove noise** — room tone under speech stays |
+| `boom-tame`  | "My voice sounds boomy"                 | Cuts the chestiness of a too-close mic                                      |
+| `harsh-tame` | "It's harsh and tiring to listen to"    | Rounds a brittle upper-mid, broad and always-on                             |
+
+### Character — deliberate, not corrective
+
+`telephone`, `radio-am`, `megaphone`, `lofi-tape`, `pa-system` (Tannoy),
+`intercom`, `doofus-worble`.
+
+These are costumes. Each is a band restriction plus a resonance plus its own kind
+of dirt, and they are tuned to be distinguishable from one another — measured on
+a log sweep, no two sit closer than the signal itself. Do not stack two.
+
+### Space — put it somewhere
+
+`room-tight` (presence without wash), `room-natural` (recorded somewhere rather
+than nowhere), `hall` (far back and big), `slap-echo` (one quick repeat),
+`dub-throw` (repeats trailing well behind).
+
+Use these on whatever should sit _behind_ something else, and keep the wet amount
+lower than sounds right in isolation — a tail occupies the room a voice needs.
+
+### The whole preset as one control
+
+A preset's nodes are wrapped in a wet/dry blend, so `presetAmount` (0..1) fades
+the entire thing in or out, and `fx.preset.<id>` is an automation target that
+ramps it over time. This is the only way to automate a preset as a unit: its
+nodes share no common parameter, and worklet effects (compressor, limiter, gate,
+bitcrush) expose no automatable parameters at all.
+
+---
+
+## Jobs — the range IS the module
+
+Five named peaking filters with the frequency already chosen. Picking the job is
+picking the range, which is what makes a single "how much" knob honest.
+
+| Job              | Symptom                              | Sets                  |
+| ---------------- | ------------------------------------ | --------------------- |
+| Tame Boominess   | Too much chest — it booms            | 200 Hz, −4 dB, Q 1.4  |
+| Reduce Mud       | Muffled, like it is behind cardboard | 250 Hz, −3 dB, Q 1.2  |
+| Reduce Boxiness  | Sounds like a small room, or a box   | 400 Hz, −3 dB, Q 1.4  |
+| Add Clarity      | Words are hard to make out           | 3 kHz, +2.5 dB, Q 1   |
+| Soften Harshness | Harsh and tiring to listen to        | 3.2 kHz, −3 dB, Q 1.6 |
+
+Each is an ordinary `peaking` node underneath — the frequency is a starting
+point, not a cage. Prefer a job to a bare `peaking` when one matches: it arrives
+already aimed, and the rack names it for the work rather than the mechanism.
+
+Writing one by hand, **carry the name in `label`** — `{"type":"peaking","id":"n2",
+"label":"Reduce Mud","params":{"frequency":250,"gain":-3,"q":1.2}}`. The
+parameters alone are not the job. A chain with three unlabelled `peaking` nodes
+shows the author three identical rows, which is the exact problem jobs exist to
+dissolve.
+
+**Every job also ships inside a preset, at identical settings** — that is where
+the five came from. `boom-tame` _is_ Tame Boominess; `harsh-tame` _is_ Soften
+Harshness; `voice-clean` contains Reduce Mud and Add Clarity; `voice-broadcast`
+contains Reduce Boxiness. So check what a preset already contains before adding
+a job on top of it, or the cut lands twice — `voice-clean` plus a Reduce Mud job
+is −6 dB at 250 Hz where −3 was meant. The rack shows the contained nodes by
+name once the preset is expanded, which is the fastest way to see it.
+
+---
+
+## One-knob profiles
+
+Five effects have no single parameter that can honestly be their face — a
+compressor's threshold means nothing without its ratio. They get a derived
+control instead, 0..1, which sets several parameters together.
+
+| Effect       | Knob      | 0 → 1                                      | Sets                                      |
+| ------------ | --------- | ------------------------------------------ | ----------------------------------------- |
+| `compressor` | Evenness  | Barely touched → Very even, quite squashed | threshold, ratio, attack, release, makeup |
+| `gate`       | Tightness | Only true silence → Cuts quiet words too   | threshold, range, release                 |
+| `saturate`   | Warmth    | Just a sheen → Openly distorted            | threshold, output                         |
+| `reverb`     | Space     | A small tight room → A big open hall       | size, wet, dry                            |
+| `bitcrush`   | Crush     | Slightly gritty → Destroyed                | bits, samples, mix                        |
+
+**Evenness, Warmth and Space are level-matched** — the make-up gain, the output
+trim and the dry leg move with the drive, so turning the knob up does not also
+turn the track up or down. Those figures were solved by measurement, not chosen:
+the compressor originally left a track 2.5 dB _quieter_ at full evenness, and
+saturation's trim ran the wrong way entirely.
+
+Tightness and Crush are not level-matched, because neither has a trim to move —
+a gate only removes, and Crush's `mix` is the effect itself rather than a
+make-up.
+
+The chain stores the mechanism values, not the knob position; the knob is read
+back by inverting the curve. So hand-editing a parameter under a profile is
+allowed and will simply move the knob.
+
+---
+
+## Measuring scripts, not presets
+
+Two things measure the audio before they act, so they cannot be a fixed chain:
+
+- **Voiceover carve** — analyses the voice and cuts the bed in the bands the
+  voice occupies. The answer to "the music is fighting the voice". See the
+  carve section in `SKILL.md`.
+- **Even Out Levels** (`levellingResult`) — measures the track's own speaking
+  windows and writes a gain envelope. Its target is the 80th percentile of that
+  track, not an absolute level, so an already-even track is left alone. Use it
+  over a compressor when the problem is passages drifting over a whole take
+  rather than word-to-word dynamics.
+
+---
+
+## Not covered by anything shipped
+
+Name the gap rather than reaching for the nearest preset and calling it the
+thing — but then **ship the honest fallback anyway**, with its cost stated. An
+author who asked for a fix and got only an explanation has been told something
+true and handed nothing. Say what it is, say what it costs, apply it.
+
+- **De-essing.** `harsh-tame` is a broad always-on cut centred a band too low,
+  not a de-esser. A real one needs a detector faster than the analysis hop
+  available here. _Fallback:_ a narrow `peaking` cut in the Edge band — sweep
+  5–9 kHz to find where this voice actually spits, Q 3–4, −3 to −5 dB. It is
+  always on, so it costs a little air on every word; that trade is usually worth
+  it and is the author's to reject.
+- **Tone matching** one track to another. _Fallback:_ the Tone EQ by hand, which
+  is predictable in a way a match curve derived from two takes would not be.
+- **Noise removal.** `room-gate` closes the gaps; the noise under speech is
+  untouched. There is no fallback for hiss beneath the words — a source with
+  audible hiss needs a better source, and saying so is the whole answer.

package/dist/assets/design/skills/hyperframes-core/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: hyperframes-core
+description: The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
+---
+
+# HyperFrames Core
+
+**Agent pitfalls (read first):**
+
+- Center with flex/`inset`, not CSS `transform: translate(-50%,-50%)` on a node you then GSAP `x`/`y`. Lint: `gsap_css_transform_conflict`. Use `fromTo` or `xPercent`/`yPercent`.
+- Do not add a scene-exit `tl.set(..., {visibility:"hidden"})`. The runtime already hides timed clips. Opacity fades on inner nodes (or `opacity` on `.clip`) are enough. Caption hard-kills are a different rule.
+- `window.__timelines["id"]` must match the root `data-composition-id`.
+- After `render`, read the summary's second line: `beginframe` vs `screenshot`, GPU mode, stage timings. `screenshot` + `software gpu` on Linux is the slow path.
+
+HyperFrames renders video from HTML. A composition is an HTML file whose DOM declares timing with `data-*` attributes, whose animation runtime is seekable, and whose media playback is owned by the framework.
+
+This skill is the **technical contract** — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in `references/` (index next), read on demand. Process docs (brief, storyboard, review, production, dispatch, frame-worker) live in `/hyperframes` → `references/`. Other concerns live in the sibling domain skills — `hyperframes-animation`, `hyperframes-creative`, `media-use`, `hyperframes-cli`, `hyperframes-registry`. The capability map in `/hyperframes` says what each one covers.
+
+## References
+
+| File                                    | Read it to…                                                                                                                                                         |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/minimal-composition.md`     | start from the smallest renderable composition skeleton                                                                                                             |
+| `references/composition-patterns.md`    | choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype                                                                           |
+| `references/data-attributes.md`         | look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"`                                                                             |
+Use the freecodego_design_preview tool to list the tracks and clips of the project, rather than reading index.html and every sub-composition file.
+| `references/creator-editing-recipes.md` | copy truthful cut/trim/reorder/retime/freeze/camera/mask/crossfade/audio editing recipes and their limits                                                           |
+| `references/sub-compositions.md`        | wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it                                                                          |
+| `references/variables-and-media.md`     | declare variables; place `<video>`/`<audio>`, set volume, trim                                                                                                      |
+| `references/determinism-rules.md`       | build a seekable timeline; determinism bans; layout / text fit                                                                                                      |
+| `references/full-screen-motion.md`      | author full-frame motion with shared backgrounds                                                                                                                    |
+| `references/tailwind.md`                | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3)                                                                        |
+
+For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to `hyperframes-animation` → `adapters/<runtime>.md`.
+
+## Building a composition
+
+### Two root forms (not interchangeable)
+
+- **Standalone** (top-level `index.html`): root `<div data-composition-id="…">` sits directly in `<body>`, **no `<template>` wrapper**. Wrapping a standalone root hides all content and `lint` rejects it (`standalone_composition_wrapped_in_template`, error).
+- **Sub-composition** (loaded via `data-composition-src`): wrap the root in `<template>`. This is the shape to write: the loader also accepts a plain full document and falls back to its `<body>`, but the templated form is what the examples and tooling assume.
+
+> UNVERIFIABLE Transport rule: for a **templated** sub-composition the assembler drops the file's own `<head>` `<style>`/`<script>` (`packages/core/src/compiler/compositionAssembly.ts`, the `hasTemplate` gate), so put `<style>`/`<script>` **inside** the template. `<link>` is hoisted either way.
+> UNVERIFIABLE Host-id convention: give the host slot, the inner template, and the `window.__timelines["<id>"]` key the **same** id. A different local id is supported (the assembler falls back to the first root in the file) but the mismatch is silent, so match them unless you have a reason not to.
+
+File shape, host wiring, and the pre-render checklist → `references/sub-compositions.md`.
+
+### Root must be sized (silent layout bug)
+
+The standalone root authors `width`/`height: 100%`. Canvas size is `data-width`/`data-height`. The runtime stamps those pixels onto the composition root. Do not hardcode `1920px`/`1080px` on `#root`. Skeleton → `references/minimal-composition.md`.
+
+### One paused timeline
+
+Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`). Building it inside an async callback (`document.fonts.ready`) is supported; what matters is that you **register only after the build completes**. Render length is the root's `data-duration`, **not** the timeline's length: a timeline that runs past it is cut off, and one that ends early holds its last frame. Omit the root `data-duration` and the length is inferred instead (timeline, media window, or adapter). You do not need `window.__timelines = window.__timelines || {}`: the runtime creates the registry before your inline scripts run, and `lint` no longer asks for it. Don't manually nest sub-timelines into the host; the runtime auto-nests registered child timelines. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`.
+
+### First-pass lint gotchas (a guaranteed first build failure)
+
+Rules that `lint` **does** catch, but only after the fact. Write them right the first time:
+
+- Never pair a CSS initial `transform` with a GSAP tween on the **same** property — the CSS value and the tween's start fight and `lint` rejects it with `gsap_css_transform_conflict`. Set the initial state inside the tween with `gsap.fromTo(el, { x: -40 }, { x: 0 })` instead of a CSS `transform: translateX(-40px)`.
+- Never put `crossorigin` on `<video>`/`<audio>`. `lint` rejects it unconditionally with `media_crossorigin_breaks_preview` (error), including for canvas/WebGL/WebAudio readback. There is no suppression.
+- Never give a `<video data-start>` an ancestor that also carries `data-start`. `lint` rejects it with `video_nested_in_timed_element` (error). Time the wrapper **or** the video, not both.
+- Every `<audio>` needs an `id`. `lint` rejects it with `media_missing_id`, and an id-less `<audio>` is never picked up by the mixer, so the render is **silent**.
+- Never tween a `.clip` with `autoAlpha` or `visibility` — `lint` rejects it with `gsap_animates_clip_element`. Animate a child instead.
+- A named CSS `font-family` needs an in-file `@font-face` to a shipped local file, or `lint` fires `font_family_without_font_face`.
+- Sub-composition `#root` uses `width`/`height: 100%` (or `inset: 0`), not hardcoded `1920px`/`1080px`. Canvas size is `data-width`/`data-height`.
+
+A lint **error** also switches off the layout and contrast audits: `check` then reports `0 sample(s)` and `0/0 text checks`, which reads like a clean file but means nothing ran. Clear lint errors before you trust those numbers.
+
+### Non-negotiable rules (silent bugs automated gates may miss)
+
+Surfaced here; full rationale in the linked reference. Do not violate:
+
+- No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md`
+- Never tween `display`, `visibility`, or `autoAlpha` on a `.clip` element. The framework owns clip visibility, and `lint` rejects it (`gsap_animates_clip_element`). Animate a child instead. → `determinism-rules.md`
+- No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`
+- `<video>`/`<audio>` are found by a flat document query, so the framework seeks and decodes them at **any nesting depth** (including inside a sub-comp `<template>` or wrapper). One hard limit: `lint` errors if a `<video data-start>` sits inside another **plain** element that also has `data-start`, and the failure is real (wrong source frames, then the clip vanishes mid-slot), so put the timing on the wrapper or on the video, never both. Sub-composition hosts are exempt: media inside a sub-composition renders correctly. The other caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → `variables-and-media.md`
+- Keep every `id` unique across the **assembled** page (prefix sub-comp ids with the composition id, `#<id>-hero`) so your own `#id` CSS and `getElementById` calls resolve. Frame injection no longer depends on it: the compiler stamps a document-unique `data-hf-render-id` on every `video[src]`/`audio[src]`/`img[src]`. Media that uses `<source>` children instead of a `src` attribute is **not** stamped, so unique ids still matter there. → `composition-patterns.md`
+- A full-screen fill on the composition **root** is fine on a normal render. It is dropped only on the layered-composite path (HDR content, or a composition using shader transitions), where the engine forces every composition root transparent so the layer beneath shows through. If your composition uses shader transitions or HDR media, put the fill on a full-bleed **child** (`position:absolute; inset:0`). → `composition-patterns.md`
+
+## Editing existing compositions
+
+- Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
+Use the freecodego_design_preview tool to list the tracks and clips of the project, rather than reading index.html and every sub-composition file.
+- Match existing composition IDs and timeline keys.
+- Adding a clip: set its `data-start`/`data-duration` intentionally against the clips around it. `data-track-index` is a Studio display lane, not a timing constraint, so it does not need to be free.
+- `data-hidden` on any composition element hides it in BOTH preview and render, overriding its time window; it is non-destructive/reversible and toggled by Studio's timeline eye icon.
+- Adding a sub-composition: verify its internal `data-composition-id` before wiring the host.
+
+## Validation
+
+Use `hyperframes-cli` for command details
+
+- [ ] `freecodego_design_lint` passes (0 findings across lint, runtime, layout, motion, and contrast)
+- [ ] Projects with sub-compositions: `freecodego_design_snapshot` and eyeball each frame
+- [ ] `freecodego_design_preview` for review (the user can edit anything in Studio's timeline, and the server survives the invoking command)
+- [ ] `freecodego_design_render` only after the user approves

package/dist/assets/design/skills/hyperframes-core/references/composition-patterns.md

@@ -0,0 +1,224 @@
+# Composition Patterns
+
+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
+
+|                       | Monolithic (single file)                                | Modular (sub-compositions)                                                           |
+| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Project layout        | `index.html` only                                       | `index.html` + `compositions/<scene>.html` per scene                                 |
+| Where scenes live     | Inline `<section class="clip">` siblings under the root | Each scene is a separate file wrapped in `<template>`                                |
+| Timeline registration | One timeline keyed at the root's `data-composition-id`  | Root timeline (often near-empty) + one timeline per sub-comp, each keyed by its `id` |
+| Routing entry         | `references/minimal-composition.md`                     | `references/sub-compositions.md`                                                     |
+
+Both architectures use the same runtime contract — `data-*` attributes + `window.__timelines[id]`. The choice is structural, not behavioral.
+
+## 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.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        background: #000;
+      }
+      #root {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+      /* Sub-comp slots stretch to fill the root. */
+      [data-composition-id="root"] > div[data-composition-src] {
+        position: absolute;
+        inset: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="root"
+      data-width="1920"
+      data-height="1080"
+      data-duration="30"
+    >
+      <!-- Sequential scenes — each one a sub-composition slot. -->
+      <div
+        id="el-intro"
+        data-composition-id="intro"
+        data-composition-src="compositions/intro.html"
+        data-start="0"
+        data-duration="6"
+        data-track-index="1"
+      ></div>
+
+      <div
+        id="el-body"
+        data-composition-id="body"
+        data-composition-src="compositions/body.html"
+        data-start="6"
+        data-duration="18"
+        data-track-index="1"
+      ></div>
+
+      <div
+        id="el-outro"
+        data-composition-id="outro"
+        data-composition-src="compositions/outro.html"
+        data-start="24"
+        data-duration="6"
+        data-track-index="1"
+      ></div>
+
+      <!-- Continuous audio at the root — survives scene cuts. -->
+      <audio
+        id="el-bgm"
+        src="assets/bgm.mp3"
+        data-start="0"
+        data-duration="30"
+        data-track-index="10"
+        data-volume="0.6"
+      ></audio>
+    </div>
+
+    <script>
+      window.__timelines["root"] = gsap.timeline({ paused: true });
+    </script>
+  </body>
+</html>
+```
+
+Key properties of this layout:
+
+- **Visual scenes on the same `data-track-index`** (e.g. `1`), authored sequentially. For a cross-fade, overlap their times by the fade duration; giving the incoming scene its own track keeps Studio's timeline readable, but the render accepts an overlap either way.
+- **Audio on a separate, higher track index** (e.g. `10`). Keeps the linter's overlap rules clear of any visual collisions.
+- **Root timeline is near-empty.** All animation lives in the sub-comps. A root-level fade-to-black at the very end is fine; do not stage a parallel animation track from the root.
+- **Host slot ids** use `el-<name>` or `<scene-id>`. The slot's `data-composition-id` must still equal the sub-comp's internal id (see `sub-compositions.md`).
+
+## Sub-Composition Archetypes
+
+### A. Content scene (default)
+
+The sub-comp contains the scene's full DOM, scoped CSS, and timeline. This is the standard pattern in `sub-compositions.md` — most scenes are this.
+
+### B. Host media + main-timeline driver (one pattern for `<video>`/`<audio>`)
+
+`<video>`/`<audio>` seek and decode at any nesting depth, so a scene-specific clip can live inside its scene's sub-comp with scene-local `data-start` and be driven by that sub-comp's own timeline. Use this host-media pattern instead when you want the media's motion authored on the **main** timeline: put the `<video>`/`<audio>` as a host-root sibling positioned over the scene's frame.
+
+The reason to reach for it: a sub-comp timeline **cannot** drive host elements (a global selector or `document.querySelector` does not resolve across the boundary). So if the media lives at the host root, author its per-scene motion (scale/opacity/morph/tilt/breathing) on the **main timeline** in `index.html`, at **global time** = scene-local time + the scene slot's `data-start`.
+
+```html
+<!-- index.html (host) -->
+<div
+  id="el-final"
+  data-composition-id="final-anim"
+  data-composition-src="compositions/final-anim.html"
+  data-start="20"
+  data-duration="6"
+  data-track-index="1"
+></div>
+
+<!-- media is a DIRECT root child; sits over the sub-comp's frame -->
+<video
+  id="final-video"
+  class="clip"
+  src="assets/final.mp4"
+  data-start="20"
+  data-duration="6"
+  data-track-index="2"
+  muted
+  playsinline
+  style="position:absolute; left:360px; top:100px; width:1200px; height:680px; object-fit:cover; border-radius:24px;"
+></video>
+
+<script>
+  // MAIN timeline drives the host video. Global time: scene starts at 20.
+  const main = window.__timelines["main"];
+  main.fromTo(
+    "#final-video",
+    { scale: 1.4, filter: "blur(14px)" },
+    { scale: 1.0, filter: "blur(0px)", duration: 0.9, ease: "power3.out" },
+    20,
+  ); // = slot data-start (+ any scene-local offset)
+</script>
+
+<!-- compositions/final-anim.html — frame/shell only, no <video>, no host-element animation -->
+<template>
+  <div
+    data-composition-id="final-anim"
+    data-width="1920"
+    data-height="1080"
+    data-duration="6"
+    style="position:absolute; inset:0; pointer-events:none;"
+  >
+    <script>
+      const tl = gsap.timeline({ paused: true });
+      // animate ONLY this sub-comp's own elements here (labels, frame, overlays)
+      window.__timelines["final-anim"] = tl;
+    </script>
+  </div>
+</template>
+```
+
+Caveats:
+
+- In this pattern the media is a host-root child, static in `index.html`, so the main timeline's selector resolves it. (Media nested in a sub-comp is also driven fine; it just can't be reached by the main timeline's selectors — drive it from the sub-comp's own timeline.)
+- Clip lifecycle owns the media element's visibility across its `[data-start, data-start+data-duration]` window. The main-timeline opacity/scale tweens compose with it fine; for an opacity reveal/crossfade prefer a host **wrapper** so you are not fighting the lifecycle on the media element itself.
+- Two media elements sharing the same `src` + `data-start` trigger `duplicate_media_discovery_risk` (benign — both still render).
+
+### C. Multi-scene merge
+
+When several beat-level scenes share continuous state — a chat thread that grows, a persistent headline word that carries across the cut, a single canvas with internal phase changes — collapse them into one sub-comp and use **internal phase divs** rather than multiple sub-comp slots.
+
+```html
+<!-- compositions/act2-merged.html -->
+<template>
+  <div data-composition-id="act2-merged" data-width="1920" data-height="1080" data-duration="9">
+    <style>
+      [data-composition-id="act2-merged"] .phase {
+        position: absolute;
+        inset: 0;
+        opacity: 0;
+      }
+    </style>
+    <div class="phase" id="phase-a">…</div>
+    <div class="phase" id="phase-b">…</div>
+    <div class="phase" id="phase-c">…</div>
+    <script>
+      const tl = gsap.timeline({ paused: true });
+      tl.set("#phase-a", { opacity: 1 }, 0);
+      tl.to("#phase-a", { opacity: 0, duration: 0.4 }, 3.0);
+      tl.set("#phase-b", { opacity: 1 }, 3.0);
+      // …
+      window.__timelines["act2-merged"] = tl;
+    </script>
+  </div>
+</template>
+```
+
+Reach for this over multiple sequential slots when scenes share DOM, share a canvas, or need to cross-fade with persistent elements (a headline that survives the cut between phases). Each phase is just a div inside the same sub-comp — the parent timeline never has to know about the internal phase boundaries.
+
+### D. Audio at root, reactive visual inside
+
+Audio always lives at the host (`index.html`) as a root-level `<audio>` so playback survives scene cuts. A sub-comp that visualizes audio should read a **pre-baked** frequency curve at init, then sample the baked curve from its timeline — the visual must still be a deterministic function of `tl.time()`, not of `audio.currentTime`. See `determinism-rules.md` and `hyperframes-creative` for the authoring pattern.
+
+## Naming Conventions
+
+| Thing                               | Convention                                  | Example                                    |
+| ----------------------------------- | ------------------------------------------- | ------------------------------------------ |
+| Sub-comp file                       | `compositions/<scene-id>.html`              | `compositions/act0-intro-bell.html`        |
+| Sub-comp `<template>` id (optional) | `<scene-id>-template`                       | `<template id="act0-intro-bell-template">` |
+| Sub-comp root `data-composition-id` | `<scene-id>` (must match host slot)         | `data-composition-id="act0-intro-bell"`    |
+| Timeline registry key               | matches `data-composition-id`               | `window.__timelines["act0-intro-bell"]`    |
+| Host slot `id`                      | `el-<short>` or `<scene-id>`                | `id="el-intro"`, `id="act0"`               |
+| Element ids inside a sub-comp       | prefix with the scene id                    | `#act0-bell`, `#b1-tape`                   |
+| 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.