@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-cli/references/preview-render.md

@@ -0,0 +1,149 @@
+# preview, play, render, publish
+
+Serve, render, and share commands.
+
+## preview
+
+```bash
+npx hyperframes preview                   # serve current directory
+npx hyperframes preview --port 4567       # custom port (default 3002)
+npx hyperframes preview --selection --json # print the current Studio selection and exit
+npx hyperframes preview --context --json  # print compact agent context from Studio
+```
+
+Hot-reloads on file changes. Opens Studio in the browser automatically — the full timeline editor, where the user can play the video and edit anything by hand before rendering. This is the review surface, not just a viewer.
+
+When handing a project back to the user, use the Studio project URL, not the source `index.html` path:
+
+```text
+http://localhost:<port>/#project/<project-name>
+```
+
+Use the actual port and project directory name; treat `index.html` as source-code context, not the preview surface. For example, after `npx hyperframes preview --port 3017` in `codex-openai-video`, report `http://localhost:3017/#project/codex-openai-video`.
+
+### Agent context from Studio selection
+
+`preview --context` and `preview --selection` are the agent bridge into a running Studio session. They do **not** start a new server; they find the active preview server for the current project, read agent-useful state from Studio, print it, and exit.
+
+Use it when the user gives deictic edit instructions like "change this", "move the selected element", "make the card I clicked bigger", or "fix the current selection":
+
+```bash
+npx hyperframes preview --context --json --context-fields selection
+```
+
+The compact context payload includes the selected element's source file, composition path, current timeline time, `data-hf-id` / selector target, bounding box, text content, and a thumbnail URL for the selected element. Prefer `selection.target.hfId` when present; fall back to `selection.target.selector` only when no stable `data-hf-id` exists. If `selection` is `null`, inspect `errors.selection.code` (for example, `no-selection`).
+
+Keep agent context small by asking only for the slices you need:
+
+```bash
+npx hyperframes preview --context --json --context-fields selection
+npx hyperframes preview --context --json --context-fields lint
+npx hyperframes preview --context --json --context-fields selection,lint
+```
+
+Use `--context-detail full` only when the edit genuinely needs heavy selection fields such as `computedStyles`, `inlineStyles`, `dataAttributes`, or editable text-field metadata:
+
+```bash
+npx hyperframes preview --context --json --context-fields selection --context-detail full
+```
+
+`preview --selection --json` remains available when you explicitly want the full selected-element payload and do not need lint/server context.
+
+Failure modes:
+
+| Code                       | Meaning                                                                    |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `preview-not-running`      | Start Studio first with `npx hyperframes preview`.                         |
+| `ambiguous-preview-server` | Multiple matching Studio servers are open; rerun with one listed `--port`. |
+| `preview-port-mismatch`    | The requested `--port` is not one of the matching Studio servers.          |
+| `no-selection`             | Studio is open, but the user has not selected an element yet.              |
+| `selection-unavailable`    | The running preview server does not expose selection context cleanly.      |
+
+If there is no selection, ask the user to click the target element in Studio and rerun the command. If the server error lists candidate ports, rerun the same command with `--port <candidate>`. Do not infer the target from a screenshot when the CLI can give a stable element target.
+
+## play (lightweight player)
+
+```bash
+npx hyperframes play                  # current project, port 3003
+npx hyperframes play ./my-video       # specific project
+npx hyperframes play --port 8080      # custom port
+```
+
+`play` serves the composition through the embeddable `<hyperframes-player>` web component instead of the full Studio UI. Use it when sharing a preview link or when Studio is heavier than needed (no editor, no panels). `play` reports the plain `http://localhost:<port>` URL — no `#project/<name>` fragment (that's a Studio routing convention only `preview` uses).
+
+The player's `playback-rate` attribute (preview speed control, drives the timeline's `timeScale`) is clamped to `[0.1, 5]`; values `≤ 0` or non-finite fall back to `1`. This is a preview/playback knob, not a composition `data-*` attribute — authored motion still renders at `1×`.
+
+### Launching with an external browser (preview + play)
+
+Both `preview` and `play` can open inside an explicit Chromium-compatible browser instead of the OS default. Two use cases: isolated Chromium profile, or external CDP attach (DevTools / Playwright / Puppeteer / browser-MCP). **HyperFrames itself does not own CDP automation** — this only exposes the endpoint; whatever connects to it is your problem. Not to be confused with `--browser-gpu` (a `render` flag controlling Chrome GPU access during capture).
+
+| Flag                      | Type            | Notes                                                                                                                                                                                           |
+| ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--browser-path`          | path            | Absolute path to a Chromium-compatible executable (`/usr/bin/chromium`, `/Applications/Brave Browser.app/...`).                                                                                 |
+| `--user-data-dir`         | path            | Chromium-compatible profile directory. Requires `--browser-path`. Use a throwaway directory to keep state out of your main profile.                                                             |
+| `--remote-debugging-port` | integer 1-65535 | Open a Chromium CDP endpoint on the given port. **Requires both** `--browser-path` and `--user-data-dir` — refused otherwise, so a CDP endpoint cannot leak into your main profile by accident. |
+
+```bash
+# Open preview in an isolated Chromium profile
+npx hyperframes preview --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile
+
+# Same plus a CDP endpoint on :9222 (attach DevTools / Playwright / etc.)
+npx hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222
+```
+
+Validation runs before any server boots, so an invalid value exits cleanly without leaving a listening socket behind.
+
+## render
+
+> Render only after the user has reviewed in `preview` and approved. Don't auto-render when the checks pass.
+
+```bash
+npx hyperframes render                                # standard MP4 from cwd
+npx hyperframes render ./my-video --output ./out.mp4  # render from outside the project dir
+npx hyperframes render --output final.mp4             # named output (no timestamp)
+npx hyperframes render -c compositions/intro.html -o intro.mp4  # render a specific sub-composition file
+npx hyperframes render --quality draft                # fast iteration
+npx hyperframes render --fps 60 --quality high        # final delivery
+npx hyperframes render --format webm                  # transparent WebM
+npx hyperframes render --docker                       # byte-identical
+```
+
+> Default `--output` is `renders/<project-name>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>` — timestamped per render so successive runs don't clobber each other. Pass `--output` to get a stable name.
+
+| Flag                                 | Options                                                                                            | Default                        | Notes                                                                                                                                                                                                                                                                                    |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dir` (positional)                   | path                                                                                               | cwd                            | Project directory. Omit to use current working directory.                                                                                                                                                                                                                                |
+| `--composition`, `-c`                | path to composition file                                                                           | `index.html`                   | Render a specific composition file (e.g. `compositions/intro.html`) instead of the project's `index.html`.                                                                                                                                                                               |
+| `--output`, `-o`                     | path                                                                                               | `renders/<project>_<ts>.<ext>` | Output path. Default is timestamped (`<project-name>_YYYY-MM-DD_HH-MM-SS.<ext>`).                                                                                                                                                                                                        |
+| `--fps`                              | 24, 30, 60                                                                                         | 30                             | 60fps doubles render time                                                                                                                                                                                                                                                                |
+| `--quality`                          | draft, standard, high                                                                              | standard                       | draft for iterating                                                                                                                                                                                                                                                                      |
+| `--format`                           | mp4, webm, mov, gif, png-sequence                                                                  | mp4                            | WebM/MOV render with transparency; gif for inline autoplay in GitHub PRs/READMEs/docs (two-pass palette encode, fps capped at 30 — prefer `--fps 15` — no audio, 1-bit transparency only, HDR falls back to SDR); png-sequence writes RGBA frames to a directory (AE/Nuke/Fusion ingest) |
+| `--gif-loop`                         | 0-65535                                                                                            | 0                              | GIF loop count; `0` loops forever. Only with `--format gif`.                                                                                                                                                                                                                             |
+| `--resolution`                       | landscape, portrait, landscape-4k, portrait-4k, square, square-4k (+ aliases `1080p`, `4k`, `uhd`) | —                              | Supersample via Chrome `deviceScaleFactor`. Aspect ratio must match composition; scale must be an integer. Not with `--hdr`.                                                                                                                                                             |
+| `--crf`                              | 0-51                                                                                               | —                              | Encoder CRF (lower = higher quality). Mutually exclusive with `--video-bitrate`.                                                                                                                                                                                                         |
+| `--video-bitrate`                    | e.g. `10M`, `5000k`                                                                                | —                              | Target bitrate. Mutually exclusive with `--crf`.                                                                                                                                                                                                                                         |
+| `--hdr`                              | flag                                                                                               | off                            | Force HDR output even with SDR sources. MP4 only.                                                                                                                                                                                                                                        |
+| `--sdr`                              | flag                                                                                               | off                            | Force SDR even with HDR sources.                                                                                                                                                                                                                                                         |
+| `--workers`                          | number or `auto`                                                                                   | auto                           | Each worker spawns Chrome (~256 MB)                                                                                                                                                                                                                                                      |
+| `--docker`                           | flag                                                                                               | off                            | Reproducible output across hosts                                                                                                                                                                                                                                                         |
+| `--gpu`                              | flag                                                                                               | off                            | GPU-accelerated FFmpeg encoding (NVENC / VideoToolbox / VAAPI / QSV)                                                                                                                                                                                                                     |
+| `--browser-gpu` / `--no-browser-gpu` | flag                                                                                               | auto (local), off (docker)     | Host GPU for Chrome/WebGL capture                                                                                                                                                                                                                                                        |
+| `--browser-timeout`                  | seconds (0.001–86400)                                                                              | 60                             | Puppeteer page-navigation timeout for the entry HTML. Raise when heavy compositions (many videos / fonts / remote assets) can't reach `domcontentloaded` within the 60s default.                                                                                                         |
+| `--quiet`                            | flag                                                                                               | off                            | Suppress verbose output                                                                                                                                                                                                                                                                  |
+| `--strict`                           | flag                                                                                               | off                            | Fail on lint errors                                                                                                                                                                                                                                                                      |
+| `--strict-all`                       | flag                                                                                               | off                            | Fail on lint errors AND warnings                                                                                                                                                                                                                                                         |
+| `--variables`                        | JSON object                                                                                        | —                              | Override values declared in `data-composition-variables`                                                                                                                                                                                                                                 |
+| `--variables-file`                   | path                                                                                               | —                              | JSON file with variable values (alternative to `--variables`)                                                                                                                                                                                                                            |
+| `--strict-variables`                 | flag                                                                                               | off                            | Fail render on undeclared keys or type mismatches in `--variables`                                                                                                                                                                                                                       |
+
+**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
+
+**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with `data-variable-values`. See the `hyperframes-core` skill for the full pattern.
+
+### feedback (do not use)
+
+Do not run `npx hyperframes feedback` in vidfarm environments — it phones home to the upstream maintainers (and `--file-issue` publishes the project publicly). Vidfarm environments set `HYPERFRAMES_NO_TELEMETRY=1`, which disables it. Report bugs, workarounds, or friction through vidfarm channels instead.
+
+## publish (do not use)
+
+`npx hyperframes publish` uploads the project's source (HTML + assets) to third-party hosting and returns a public URL. **Do not use it in vidfarm flows.** Share through vidfarm instead: `vidfarm render` produces the MP4, and `vidfarm approve` returns a `share_url` for review and sharing.

package/.agents/skills/hyperframes-cli/references/upgrade-info-misc.md

@@ -0,0 +1,75 @@
+# info, upgrade, compositions, docs, benchmark, telemetry, asset preprocessing
+
+Catch-all reference for commands that don't fit the main dev loop.
+
+## info
+
+```bash
+npx hyperframes info                   # project metadata
+npx hyperframes info ./my-video        # specific project
+npx hyperframes info --json
+```
+
+Prints **project** metadata: name, resolution, duration, element counts by type, track count, and total project size. Project-level — not environment. For environment health use `doctor`.
+
+## upgrade
+
+```bash
+npx hyperframes upgrade                # check + interactive prompt
+npx hyperframes upgrade --check        # check and exit, no prompt (agent-friendly)
+npx hyperframes upgrade --check --json # machine-readable: current / latest / updateAvailable
+npx hyperframes upgrade --yes          # print upgrade commands without prompting
+```
+
+Compares the installed CLI version against npm latest.
+
+## compositions, docs
+
+```bash
+npx hyperframes compositions           # list compositions in project
+npx hyperframes compositions --json
+npx hyperframes docs                   # list available topics
+npx hyperframes docs rendering         # print one topic inline in the terminal
+```
+
+`compositions` lists every `data-composition-id` in the project (including sub-comps) with duration, resolution, and element count.
+
+`docs` prints inline documentation **in the terminal** — it does not open a browser. Topics: `data-attributes`, `examples`, `rendering`, `gsap`, `troubleshooting`, `compositions`. Run without a topic to see the list.
+
+## benchmark
+
+```bash
+npx hyperframes benchmark              # run the preset matrix in current project
+npx hyperframes benchmark ./my-video   # specific project
+npx hyperframes benchmark --runs 5     # repeat each config N times (default 3)
+npx hyperframes benchmark --json
+```
+
+Renders the project with 5 preset configurations — `30fps draft 2w`, `30fps standard 2w`, `30fps high 2w`, `30fps standard 4w`, `60fps standard 4w` — and prints a comparison of render speed and output file size. Use it to find the fastest acceptable preset for your machine. Not a single-render-with-stage-breakdown.
+
+## telemetry
+
+```bash
+npx hyperframes telemetry status      # show telemetry state
+npx hyperframes telemetry disable     # disable anonymous usage telemetry
+npx hyperframes telemetry enable      # re-enable telemetry
+```
+
+Telemetry is anonymous usage counters only. **Vidfarm environments disable it by default** by setting `HYPERFRAMES_NO_TELEMETRY=1`; users can additionally run `npx hyperframes telemetry disable` if they want the persistent config flag set too. Do not re-enable telemetry in vidfarm flows.
+
+Events include two fingerprint properties used to distinguish managed-sandbox runs from real laptops — no PII, no env-var **values**, only existence checks:
+
+- **`sandbox_runtime`**: `gvisor` / `firecracker` / `docker` / `kvm` / `wsl` / `null`. gVisor via kernel string + `/proc/version`. Firecracker via `/dev/vsock` + DMI sys_vendor. Docker via `/.dockerenv` + cgroup.
+- **`agent_runtime`**: `claude_code` / `codex` / `cursor` / `copilot_agent` / `jules` / `replit` / `devin` / `aider` / `gemini_cli` / `hermes` / `openclaw` / `null`. Detected by the existence of well-known vendor env vars; the values themselves are never read.
+
+## Asset Preprocessing
+
+```bash
+npx hyperframes tts
+npx hyperframes transcribe
+npx hyperframes remove-background
+```
+
+These produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each may download its own model on first run.
+
+For voice selection, Whisper model rules, output format choice, and the TTS → transcript → captions chain, invoke the `vidfarm-media` skill. This skill stays focused on the dev loop.

package/.agents/skills/hyperframes-core/SKILL.md

@@ -0,0 +1,78 @@
+---
+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
+
+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. Other concerns live in the sibling domain skills — `hyperframes-animation`, `hyperframes-creative`, `hyperframes-media`, `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"`           |
+| `references/tracks-and-clips.md`     | pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another     |
+| `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; the animatable-property allowlist; layout / text fit |
+| `references/full-screen-motion.md`   | author full-frame motion with shared backgrounds                                                  |
+| `references/storyboard-format.md`    | author a `STORYBOARD.md` plan (+ the parsed manifest)                                             |
+| `references/script-format.md`        | author the optional `SCRIPT.md` locked narration                                                  |
+| `references/subagent-dispatch.md`    | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness                |
+| `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 it hides all content and breaks rendering).
+- **Sub-composition** (loaded via `data-composition-src`) — root **must** be wrapped in `<template>`.
+
+> ⚠ Transport rule: the runtime **only clones `<template>` contents**; everything outside (incl. `<head>` styles/scripts) is discarded — put `<style>`/`<script>` **inside** the template.
+> ⚠ Host-id rule: the host slot's `data-composition-id` must **exactly equal** the inner template's `data-composition-id` **and** the `window.__timelines["<id>"]` key — no `-mount`/`-slot`/`-host` suffix.
+
+File shape, host wiring, and the pre-render checklist → `references/sub-compositions.md`.
+
+### Root must be sized (silent layout bug)
+
+The standalone root needs an explicit **sized box** (`width`/`height` in px), and every ancestor down to a `height:100%` element must have a resolved height — otherwise a flex/`100%` child collapses to ~0 and content piles into the top-left corner. `lint`/`validate`/`inspect` do **not** catch this. 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`), built **synchronously** at page load. Render duration = root `data-duration`, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`.
+
+### Non-negotiable rules (silent bugs `lint`/`validate`/`inspect` won't catch)
+
+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`
+- Animate only the visual-property allowlist; never `display`/`visibility`; no `gsap.set` on later-scene clips. → `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>` must be a **direct child of the host root** (never inside a sub-comp `<template>`/wrapper); the framework owns playback. → `variables-and-media.md`
+- Every `id` must be unique across the **assembled** page; inside a sub-comp, prefix ids with the composition id (`#<id>-hero`). Duplicate `<video>`/`<img>` ids render **blank** — the producer injects frames by `getElementById`, and cross-file dupes slip past `lint`. → `composition-patterns.md`
+- A full-screen scene fill goes on a full-bleed **child** (`position:absolute; inset:0`), never on the composition root itself — the producer's frame compositing can drop the root element's own `background` (the frame renders **black**) even though preview/`snapshot` show it correctly. → `composition-patterns.md`
+
+## Editing existing compositions
+
+- Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
+- Match existing composition IDs and timeline keys.
+- Adding a clip: pick a non-overlapping `data-track-index` or adjust surrounding timing intentionally.
+- Adding a sub-composition: verify its internal `data-composition-id` before wiring the host.
+
+## Validation
+
+Use `hyperframes-cli` for command details
+
+- [ ] `npx hyperframes lint` passes (0 errors)
+- [ ] `npx hyperframes validate` passes (0 console errors)
+- [ ] `npx hyperframes inspect` passes (0 errors)
+- [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
+- [ ] `npx hyperframes preview` for review (the user can edit anything in Studio's timeline)
+- [ ] `npx hyperframes render` only after the user approves

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

@@ -0,0 +1,263 @@
+# 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).
+
+## 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.
+
+### 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.
+
+```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: 1920px;
+        height: 1080px;
+        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 = window.__timelines || {};
+      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`). Sequential — they cannot overlap on the same track. For a cross-fade between two scenes, put one on a higher track and overlap their times by the fade duration.
+- **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 (REQUIRED for any `<video>`/`<audio>`)
+
+Media playback only works when the `<video>`/`<audio>` is a **direct child of the host root** — never inside a sub-comp `<template>` (it would render blank/black). This is not optional or "for media that spans scenes"; it applies to every clip, including a scene-specific one. The scene's sub-comp keeps the frame/shell; the media is a host sibling positioned over it.
+
+A sub-comp timeline **cannot** drive host elements (a global selector or `document.querySelector` does not resolve across the boundary). So author the media's 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.
+  window.__timelines = window.__timelines || {};
+  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>
+      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;
+    </script>
+  </div>
+</template>
+```
+
+Caveats:
+
+- The host media must be a direct root child and exist in the DOM (static in `index.html`) — it always is.
+- 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>
+      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);
+      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.
+
+## 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 non-overlapping `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.