dsh-hyperframes 0.2.0 → 0.3.1

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

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

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

@@ -0,0 +1,69 @@
+# Minimal Composition
+
+The smallest renderable HyperFrames composition — a standalone (top-level) root with one clip and one tween:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Minimal HyperFrames Composition</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        background: #0b0f14;
+        color: white;
+        font-family: Inter, system-ui, sans-serif;
+      }
+      #root {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+      .clip {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+      }
+      h1 {
+        margin: 0;
+        font-size: 96px;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-width="1920"
+      data-height="1080"
+      data-duration="5"
+    >
+      <section id="title-card" class="clip" data-start="0" data-duration="5">
+        <h1 id="title">Hello HyperFrames</h1>
+      </section>
+    </div>
+    <script>
+      const tl = gsap.timeline({ paused: true });
+      tl.from("#title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0.2);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+What the runtime actually requires:
+
+- Root `<div>` with `data-composition-id`, `data-width`, `data-height`. Root `data-start="0"` is written above by convention and every shipped block has it, but the runtime stamps it when absent, so it is not required.
+- A duration source: root `data-duration` (as above), or a GSAP timeline, or media, or an adapter that can infer one.
+- Timed elements carry `data-start` plus a duration. That attribute alone is what makes an element a clip: `class="clip"` is a layout and tooling convention, and `data-track-index` is a Studio display lane. Neither is required, and a composition with no clips at all renders fine.
+- A GSAP timeline created paused and registered on `window.__timelines["<composition-id>"]`.
+
+Everything else in the skeleton is ordinary HTML and CSS: the `#root` box, `.clip` positioning, and fonts are yours to choose.
+
+This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.

package/skills/hyperframes-core/references/production-loop.md

@@ -0,0 +1,26 @@
+# Production loop — from an approved plan to a delivered video
+
+The stages between a plan the user has agreed to and a video in their hands, written as **dependencies, not numbered steps**: order between independent stages is free — audio renders in the background while frames build; that is the standard trick — order inside a dependency chain is not. Nothing in this file addresses the user: every user-facing pause lives in `review-loop.md`, and this file only marks where those passes attach. Some routes bring their own spine (a beat grid, existing footage) — the stages compose around it. A stage whose need is absent simply doesn't run: no narration, no audio stage; a single scene, no transitions. An edit request enters at the artifact it touches and re-runs verify.
+
+The shipped narrative workflows implement these stages with their own scripts; a freeform build follows this file directly, borrowing tools where the capability menu says they live (`hyperframes/references/capability-menu.md`).
+
+| Stage               | Needs                                                                                                                    | Produces                                                                                                                                                | Where the capability lives                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Blocks & assets** | the approved plan                                                                                                        | registry blocks installed **once, before any parallel work** (parallel workers race the registry); user assets staged; logos / images / grades resolved | `npx hyperframes add <block>` per block the plan names; staging, adoption, and `resolve` via the menu's media rows                            |
+| **Audio**           | narration text (when narrated); the storyboard's `music:` mood                                                           | voice files + **word timings** + BGM + SFX → `audio_meta.json`                                                                                          | the one engine — `media-use/audio/scripts/audio.mjs`, run in the background; `wait-bgm.mjs` before render when BGM generates                  |
+| **Frames**          | design spec + the plan (+ a confirmed sketch when one exists — dress that layout, never redraw it: `review-loop.md` § 3) | each scene at `compositions/frames/NN-*.html`, marked `animated` in the storyboard as it lands                                                          | `frame.md` + `hyperframes-animation` blueprints / rules (+ the genre lens, menu § Genre lenses); parallel dispatch per `subagent-dispatch.md` |
+| **Duration sync**   | word timings + frames                                                                                                    | scene durations trued to real voice length — real duration wins, silent scenes keep estimates, synced values are never hand-edited                      | a mechanical rule; the narrative workflows' audio scripts apply it, a freeform build applies it by hand                                       |
+| **Assembly**        | frames                                                                                                                   | the index composition — scenes as sub-compositions on tracks                                                                                            | `sub-compositions.md` + `tracks-and-clips.md`; borrowable `assemble-index.mjs` (menu)                                                         |
+| **Transitions**     | the assembled index                                                                                                      | scene handoffs injected                                                                                                                                 | `hyperframes-animation/transitions/overview.md` → `catalog.md`; borrowable `transitions.mjs` (menu)                                           |
+| **Captions**        | word timings + the index                                                                                                 | the caption track                                                                                                                                       | borrowable `captions.mjs` (menu); no script to time against → `media-use` `scripts/transcribe.mjs` first                                      |
+| **Verify**          | the index (+ captions / transitions when present)                                                                        | `npx hyperframes lint` and `npx hyperframes check` **passing**; a contact-sheet glance (`snapshot --at <frame-midpoints>`)                              | `hyperframes-cli`                                                                                                                             |
+| **Deliver**         | verify passing                                                                                                           | the final-look pause → on approval `render` → optionally `publish` (a stable public link) → the recipe offer                                            | final approval and recipe offer: `review-loop.md` § 4; render / publish: `hyperframes-cli`                                                    |
+
+The Frames stage follows the plan's citations: a scene planned on a blueprint or on named rules is built by reading that recipe's body (`hyperframes-animation/blueprints/<id>.md`, `rules/<id>.md`) before its motion is written — names come from the indexes, never invented, and a scene the plan left uncited gets its citation at build time, not improvised motion.
+
+## Scheduling economics (facts you can't see from inside the session)
+
+- **External generations are independent work.** Image plates, TTS, BGM, video gen: fire every generation whose prompt is already known **concurrently or in the background**, and overlap the wait with reading or building. Three image plates generated one-after-another cost ~3× the wall time of firing them together.
+- **Attaching an image re-prices your whole context.** A mid-session image inspection (especially at original detail) invalidates the prompt cache — the next request re-sends your entire history at full price. Batch visual checks (one contact sheet beats N single-frame views) and schedule them at phase boundaries, not mid-build.
+
+Two attach points carry the user's voice into this loop: the plan that starts it was approved at `review-loop.md` § 1 (collaborative) or posted as a heads-up (autonomous), and nothing renders before the § 4 final look. Everything between those two is yours to schedule.

package/skills/hyperframes-core/references/review-loop.md

@@ -0,0 +1,41 @@
+# The review loop — plan, sketch, build
+
+How a `storyboard: yes` run earns fidelity one pass at a time: the plan is reviewed as text on a live board, the layouts as wireframe sketches, and the finished piece as the assembled video. Collaborative mode waits at each checkpoint. Autonomous mode posts the same checkpoint summaries and continues, keeping exactly one question before render.
+
+This is the shared process for any workflow that plans on a storyboard. The contracts it leans on live next door: interaction mode, gate types, and the comments channel in `brief-contract.md`; the `STORYBOARD.md` format, the `outline → built → animated` statuses, and the comments sidecar in `storyboard-format.md`. A workflow's SKILL.md says **when** its steps hit each pass and supplies its **sketch stand-ins** (what the plain blocks represent); how the loop runs is defined here, once. The stage mechanics between the passes — audio, frames, assembly, transitions, captions, verify — live in `production-loop.md`; this file owns only the user-facing pauses.
+
+## § 1 — The plan, on a live board
+
+Open the **storyboard board** before presenting the plan: run `npx hyperframes preview --background` from the project directory, confirm it is serving, and open `http://localhost:<port>/?view=storyboard#project/<project-name>`. This is an early planning surface, not the final composition preview; it may open before composition checks. The plan appears as frame cards and refreshes as work lands.
+
+Present the plan as a proposal (shape: `hyperframes-creative/references/story-spine.md` § 3): open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). Hand the board URL with it, noting feedback lands in both places — comment on the board or reply here, one revision loop — and that a board submit still needs one reply here (anything) to get picked up.
+
+In the same message ask two things: **(a)** approve or request changes, and **(b)** **sketches first** (recommended — a quick wireframe look check right after this approval) or skip sketches and build in one go. Iterate until approved — feedback arrives in chat or as the comments file (`brief-contract.md` § 1, the comments channel): revise exactly the frames it names, clear the file, re-present.
+
+This is a **checkpoint gate** (`brief-contract.md` § 1). A run that starts autonomous normally has `storyboard: no` and does not enter this loop. If mode switches to autonomous after a board exists, keep updating the board, post the same summary as a heads-up, and continue without waiting; the one kept question comes at § 4.
+
+## § 2 — The sketch pass (collaborative, unless skipped)
+
+The moment the plan is approved, wireframe every frame yourself — no sub-agents, no waiting on other steps (sketches don't use timings), straight from the approved frame table.
+
+A sketch is a **wireframe with the real words, not a styled frame**: the frame's layout at its key moment — the actual headline / stat / label text placed where it will live, plain blocks for panels, charts, diagrams, and media (the workflow says what its blocks stand in for), `frame.md`'s background and ink plus one accent on the focal, nothing else. No decoration, no full brand treatment, **no motion** — all of that arrives with the build pass.
+
+Keep each sketch a real composition file at `compositions/frames/NN-*.html` (template wrapper, `data-composition-id`, `#root` styling, one paused **empty** timeline registered at `window.__timelines["<frame_id>"]`) so the Studio poster renders — and the poster is the only picture this pass needs: **run no CLI here** — no `snapshot`, no `lint` / `check`, no rendering. A sketch is a few dozen lines of HTML; the whole board lands in minutes.
+
+Mark each frame `built` as its sketch lands — the user's open board fills in blue by itself. When every frame is `built`, pause and ask one thing: does the board look right, or which frames change? This is a **checkpoint gate**; the user reviews in Studio (open since § 1 — restart and re-hand the same URL if the server died), and feedback arrives in chat or as the comments file — check the file first when the reply arrives: revise **only the sketches named**, re-present, and loop until the layout is confirmed. Only then does the workflow's visual design get written onto the confirmed layouts.
+
+A confirmed board is also a valid place to **stop**. When the user asked for a storyboard rather than a finished video — a plan to pitch, review, or hand off — the sketched board is the deliverable: confirm it, hand the board URL, and go no further unless asked to build.
+
+In autonomous mode, or when the user chose to skip sketches at § 1, skip this pass — frames go straight from `outline` to `animated` in the build.
+
+## § 3 — Building on confirmed layouts
+
+However the workflow builds — sub-agent workers per frame, or inline scene by scene — a confirmed sketch's **composition is settled**: placement, hierarchy, and copy were approved on the board, so building means dressing that layout (full design treatment, real assets, motion), never redrawing it. Workflows that dispatch workers put "this frame has a **confirmed sketch** on disk" in the worker's context and carry the keep-the-layout rule in their worker prompt; a landed frame must still read as the approved wireframe, fully dressed.
+
+Mark each frame `animated` as it lands. The build gate carries the loop's condition: in collaborative mode, the sketch board was confirmed at § 2.
+
+## § 4 — The final look
+
+After the workflow's checks pass, use the **final composition preview**. In collaborative mode Studio may already be serving from § 1; hand the timeline URL and ask one thing: render now, or what changes? In autonomous mode this is the one question the mode keeps: ask “preview first, or render?” Open the final preview on yes; render on an explicit render answer. Render only on approval.
+
+**After approval, offer the recipe — once.** An approved run is a proven bundle. At delivery, offer to freeze it: `media-use` → `scripts/recipe.mjs freeze --name <name>` (the workflow comes from BRIEF.md; pass `--workflow` only in a project without one) keeps the design spec, the storyboard skeleton (structure kept, content blanked), the brief skeleton, and the confirmed brief values, and the next run of this type starts from it (the intent layer checks for a matching recipe before its first question). When the freeze lands, teach the recall in the confirmation — "Saved as **<name>** (v<N>). Next time say _make another <name>_, or just _like last time_." — the name is something the system reminds the user of, never something they must remember. In autonomous mode don't ask — name the freeze command in the delivery note instead.

package/skills/hyperframes-core/references/script-format.md

@@ -0,0 +1,52 @@
+# `SCRIPT.md` — locked narration (optional)
+
+The **locked narration** for a project: the final spoken lines + voice + delivery. It is an _optional_ plan-layer file — a video with no narration (bgm-only, silent overlay) has none. The storyboard's per-frame `voiceover` is the lighter, editable _guide_; `SCRIPT.md` is the _commit_. (Storyboard format → `references/storyboard-format.md`.)
+
+This file defines the SCRIPT.md **shape** only. Synthesizing the spoken lines into audio is a capability owned by `media-use` → `references/tts.md`.
+
+Free-form markdown — there is no strict parser; the Studio renders it read-only beside the Storyboard board, and the TTS step extracts the indented spoken lines.
+
+## Shape
+
+A header block, then one section per spoken line.
+
+| Part                            | Holds                                                                                                                                   |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Header                          | `**Voice:**` (provider + voice), `**Voice settings:**` (e.g. stability / similarity / style), `**Voice direction:**` (overall delivery) |
+| `## Line N — <label> (Frame N)` | one spoken line, tied to its storyboard frame                                                                                           |
+| `**Time:**`                     | the board's rough window — a _guide_, not authoritative (real timing comes from TTS word timestamps)                                    |
+| `**Delivery:**`                 | per-line delivery note                                                                                                                  |
+| indented block                  | the **spoken text** — the only part fed to TTS                                                                                          |
+
+## Example
+
+```markdown
+# SCRIPT — acme-launch
+
+**Voice:** Rachel (ElevenLabs)
+**Voice settings:** stability 0.35 · similarity 0.75 · style 0.20
+**Voice direction:** Confident, warm, a little playful.
+
+---
+
+## Line 1 — Hook (Frame 1)
+
+**Time:** 0.0 – 3.0s
+**Delivery:** Land the promise on the beat.
+
+    Ship a launch video in an afternoon.
+
+## Line 2 — The problem (Frame 2)
+
+**Time:** 3.0 – 7.0s
+**Delivery:** Wry, a touch tired.
+
+    The old way? Prompt, wait twenty minutes, get something that misses.
+```
+
+## To TTS
+
+Feed each line's spoken text to the provider documented in
+`media-use/audio/references/tts.md`. The `hyperframes tts` command is
+Kokoro-only; use its `--voice` flag, or use the bundled HeyGen helper when word
+timestamps are required. Real per-word timing replaces the `**Time:**` guides.

package/skills/hyperframes-core/references/storyboard-format.md

@@ -0,0 +1,130 @@
+# Storyboard format — `STORYBOARD.md` + parsed manifest
+
+Defines the storyboard's **base data format** only: the `STORYBOARD.md` file shape and the `StoryboardManifest` it parses into. How a workflow _generates_ a storyboard lives in that workflow; the optional narration/TTS file (`SCRIPT.md`) is a separate concern owned by the TTS step, not here.
+
+A storyboard is the **plan layer** for a video — an ordered set of **frames** (key moments) in one markdown file. HyperFrames Studio renders it as a contact sheet (the Storyboard view, available by default in every Studio session). Parser: `@hyperframes/core/storyboard` → `StoryboardManifest`; read API: `GET /api/projects/<id>/storyboard`.
+
+## Frontmatter (global direction)
+
+YAML block at the top. Unknown keys are kept under `globals.extra`.
+
+| Key        | Meaning                                                           | Example                                   |
+| ---------- | ----------------------------------------------------------------- | ----------------------------------------- |
+| `format`   | Canvas size                                                       | `1920x1080`                               |
+| `duration` | The brief's rough length expectation (advisory, not a hard limit) | `22s`                                     |
+| `message`  | One-line thesis                                                   | `Ship a launch video in an afternoon`     |
+| `arc`      | Narrative arc                                                     | `Hook → Problem → Solution → Proof → CTA` |
+| `audience` | Who it's for                                                      | `indie devs on X`                         |
+| `mode`     | Interaction mode (see `brief-contract.md`; default collaborative) | `autonomous`                              |
+
+Set `duration` from the brief's `length` when the storyboard is first written. It is an expectation, not a gate: assembly reports where the cut actually lands against it and flags a large gap — judge whether the drift serves the piece, and update the value when the intended length genuinely changes.
+
+## Per-frame sections
+
+One `## Frame N — Title` heading per frame (`Frame` / `Beat` / `Scene` accepted at H2/H3). Metadata as `- key: value` bullets; everything below them until the next heading is the free-form **narrative**.
+
+| Key             | Meaning                                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------- |
+| `status`        | `outline` → `built` → `animated` (defaults `outline`)                                                         |
+| `src`           | project-relative path to the frame's HTML sub-composition (the tile poster renders from it)                   |
+| `duration`      | e.g. `4s`                                                                                                     |
+| `transition_in` | `crossfade` / `cut` / `wipe` … (alias `transition`)                                                           |
+| `scene`         | one-line contact-sheet caption (aliases `description` / `summary` / `caption`)                                |
+| `voiceover`     | the frame's narration _guide_ (aliases `vo` / `voice_over` / `narration`)                                     |
+| `poster`        | seconds to seek for the tile poster (past the intro animation)                                                |
+| _any other key_ | kept verbatim under the frame's `extra` — a workflow carries its own per-frame data (effects, assets, …) here |
+
+## Parsed manifest
+
+The parser is **lenient**: it never throws and records anything surprising as a `warning`.
+
+```
+StoryboardManifest {
+  globals: { format?, message?, arc?, audience?, extra: {…} }
+  frames: Array<{
+    index, number?, title?,
+    status,                       // "outline" | "built" | "animated"
+    src?, duration? / durationSeconds?, transitionIn?,
+    scene?, voiceover?, poster?,
+    narrative,                    // markdown below the metadata
+    extra: {…}                    // unknown keys, preserved
+  }>
+  warnings: Array<{ message, line?, frameIndex? }>
+}
+```
+
+The read API also adds `srcExists` per frame and attaches the optional `SCRIPT.md` payload when present.
+
+## `SCRIPT.md` (out of scope here)
+
+Optional, free-form, **not parsed into the manifest** — the locked-narration file that drives TTS. Its format is defined in `references/script-format.md`, and it is absent for videos with no narration/TTS. The per-frame `voiceover` above is the storyboard's own narration guide.
+
+## Frame comments — `.hyperframes/frame-comments.json`
+
+The storyboard review's **structured feedback channel** — the file Studio's per-frame comment boxes write on submit (chat feedback follows the same rule — `brief-contract.md` § 1, the comments channel). Like `SCRIPT.md`, it is a sibling of the storyboard, not parsed into the manifest.
+
+```json
+{
+  "version": 1,
+  "pass": "sketch",
+  "submitted_at": "2026-07-09T12:04:00Z",
+  "comments": [
+    {
+      "frame": 3,
+      "src": "compositions/frames/03-mechanism.html",
+      "title": "Mechanism",
+      "text": "Swap the bar chart for a before/after slider."
+    }
+  ]
+}
+```
+
+| Field                    | Meaning                                                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `pass`                   | which review the batch belongs to: `storyboard` (text layer) / `sketch` (static frames) / `final` (assembled video) |
+| `comments[].frame`       | the frame's 1-based `index` in the manifest — the key                                                               |
+| `comments[].src` `title` | copied from the frame at submit time — if frames get reordered after submit, the mismatch shows                     |
+| `comments[].text`        | the feedback, verbatim                                                                                              |
+
+Lifecycle — the whole contract: a workflow finding this file at a checkpoint treats it as the revision feedback — **revise exactly the frames named, delete the file, re-present**. Writers create it only on submit; it never lingers across rounds.
+
+## Example
+
+```markdown
+---
+format: 1920x1080
+message: "Ship a launch video in an afternoon"
+arc: Hook → Problem → Solution → Proof → CTA
+audience: indie devs on X
+---
+
+## Frame 1 — Hook
+
+- scene: Big type punches in on the beat
+- duration: 3s
+- poster: 2s
+- transition_in: cut
+- status: animated
+- voiceover: "Ship a launch video in an afternoon."
+- src: compositions/frames/01-hook.html
+
+Open cold on the promise. This is the thesis — everything after pays it off.
+
+## Frame 2 — The problem
+
+- scene: A 20-minute timer spins on a stack of rejected takes
+- duration: 4s
+- transition_in: crossfade
+- status: built
+- voiceover: "The old way? Prompt, wait twenty minutes, get something that misses."
+- src: compositions/frames/02-problem.html
+
+The old way: prompt, wait, get something that misses. Establish the pain we remove.
+```
+
+## Notes
+
+- A frame with `status: outline` and no built `src` renders as an outline placeholder.
+- `built` is the middle rung: the frame's HTML exists and its **layout is confirmed** (a wireframe sketch or better) — motion not yet added. Studio chips it blue.
+- The process that walks these statuses — plan, sketch, build, each pass reviewed on the board — is `review-loop.md`.
+- Multi-line `voiceover` values collapse to one line on save.

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

@@ -0,0 +1,239 @@
+# Sub-Compositions
+
+A sub-composition is a separate HTML file embedded in a host composition. HyperFrames loads it, seeks it independently, and composites the result into the host at `data-start`.
+
+## Host Wiring
+
+In the host composition, the sub-composition appears as a clip with `data-composition-src`:
+
+```html
+<div
+  id="chart"
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-start="2"
+  data-duration="8"
+  data-track-index="2"
+  data-width="1920"
+  data-height="1080"
+></div>
+```
+
+- `data-composition-id` on the host must match the internal `data-composition-id` of the file at `data-composition-src`.
+- The host clip needs its own `data-start`, `data-duration`, `data-track-index`, `data-width`, `data-height`.
+
+## Sub-Composition File Structure
+
+### Mental model — what the runtime actually does
+
+When a host loads a sub-composition via `data-composition-src`, the runtime:
+
+1. `fetch`es the HTML file.
+2. Parses it with `DOMParser`.
+3. **Finds the `<template>` element and clones ONLY its contents into the host slot.**
+4. Everything **outside** the `<template>` (including the entire `<head>`) is **discarded**.
+
+So `<template>` is not just a wrapper — it is the **transport container**. If a node needs to exist in the live render, it must be inside `<template>`. Full stop.
+
+### File shape
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <!-- head is metadata for the source file only; the runtime ignores it -->
+  </head>
+  <body>
+    <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 {
+          position: absolute;
+          inset: 0;
+          color: #fff;
+        }
+        /* .label, #bar, … — descendants, plain selectors */
+      </style>
+
+      <div id="root" data-composition-id="data-chart" data-width="1920" data-height="1080">
+        <!-- sub-composition markup -->
+      </div>
+
+      <script>
+        window.__timelines = window.__timelines || {};
+        const tl = gsap.timeline({ paused: true });
+        // ... build timeline ...
+        window.__timelines["data-chart"] = tl;
+      </script>
+    </template>
+  </body>
+</html>
+```
+
+Contrast with **standalone** compositions, which put the root directly in `<body>` with no `<template>` wrapper.
+
+## 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.
+
+### Pitfall 1 — `<style>` in `<head>` instead of inside `<template>`
+
+```html
+<!-- ❌ WRONG — looks normal, ships catastrophically broken -->
+<head>
+  <style>
+    #root { font-size: 88px; ... }
+  </style>
+</head>
+<body>
+  <template>
+    <div id="root" data-composition-id="data-chart" ...>...</div>
+  </template>
+</body>
+
+<!-- ✅ RIGHT — styles are inside the template, root styled by #root (see Pitfall 3) -->
+<head></head>
+<body>
+  <template>
+    <style>
+      #root { font-size: 88px; ... }
+    </style>
+    <div id="root" data-composition-id="data-chart" ...>...</div>
+  </template>
+</body>
+```
+
+**Why this happens:** standard HTML conventions tell you to put `<style>` in `<head>`. In a standalone HTML file that's correct. In a HyperFrames sub-composition it is **not** — the runtime only clones `<template>` contents, so `<head><style>` is dropped on the floor.
+
+**Symptom:** isolated checks pass and the render completes, but every text element appears as tiny unstyled default text in the top-left and SVGs expand to canvas size because no CSS reached the live DOM. The same trap applies to `<script>` blocks, `<link rel="stylesheet">`, and custom-element registrations: anything that must execute or apply in the render belongs inside `<template>`.
+
+### Pitfall 2 — Host `data-composition-id` ≠ inner template `data-composition-id`
+
+```html
+<!-- ❌ WRONG — host renames the slot; runtime can't find the timeline -->
+<!-- host file (e.g. index.html) -->
+<div data-composition-id="chart-mount" data-composition-src="compositions/chart.html" ...></div>
+
+<!-- chart.html -->
+<template>
+  <div data-composition-id="data-chart" ...>...</div>
+  <script>
+    window.__timelines["data-chart"] = tl;
+  </script>
+</template>
+
+<!-- ✅ RIGHT — both ids match, and the timeline key matches them too -->
+<div data-composition-id="data-chart" data-composition-src="compositions/chart.html" ...></div>
+<!-- chart.html template root: data-composition-id="data-chart" -->
+<!-- timeline: window.__timelines["data-chart"] = tl; -->
+```
+
+**Why this happens:** it feels natural to give the host slot a different name like `chart-mount` ("the mount point") vs `data-chart` ("the actual chart"). HyperFrames does not work that way — **the host's `data-composition-id` is the lookup key the framework uses to find the registered timeline**. Lint passes because each file's ids are individually valid; the cross-file mismatch only blows up at render.
+
+**Symptom:** the render logs `Sub-composition timelines not registered after 45000ms: <host-id>` for every mismatched slot, waits 45s per scene, then captures static initial-state frames (so the video is full-length but no animation plays).
+
+### 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.
+
+## What HyperFrames Does With the Sub-Composition
+
+- Loads the file and registers its timeline under its internal `data-composition-id`.
+- Seeks the sub-composition's timeline independently from the host's playhead.
+- Plays the sub-composition's content from `data-start` of the host clip, for `data-duration` seconds.
+
+**Do not** manually `master.add(child)` a sub-composition timeline into the host timeline. HyperFrames already drives them independently — nesting them in GSAP causes double-seeks.
+
+### The host clip's `data-duration` is the slot's visible window
+
+`data-duration` on the host clip defines **how long the slot is visible**, and it takes precedence over the sub-composition's internal GSAP timeline length. Two consequences follow:
+
+- **Internal timeline shorter than the slot → the slot holds.** If the sub-composition's GSAP timeline finishes before `data-duration` elapses, the slot keeps showing its final frame for the rest of the window. You do **not** need to pad the timeline with empty tweens.
+- **`data-duration` shorter than the host composition → the slot ends (and goes blank) when its own `data-duration` elapses.** This is intended: the clip is a fixed-length window on the timeline, not "fill until the composition ends." To keep a sub-composition visible for the whole composition, set its `data-duration` to span the host window (or add another clip to cover the remaining time). Leaving a single full-bleed sub-composition shorter than the composition is almost always a mistake — the linter flags it as `subcomposition_blanks_before_host`.
+
+## Animations Inside Sub-Compositions
+
+Prefer `gsap.fromTo()` over `gsap.from()` for entrance tweens. The host re-seeks the sub-composition every time its clip becomes visible; `gsap.from()` records the starting state at registration and can desync on seek-back, while `gsap.fromTo()` declares both endpoints explicitly and replays cleanly.
+
+## Per-Instance Variables
+
+If the sub-composition declares variables on its `<html>` element (`data-composition-variables`), the host can override values per instance:
+
+```html
+<div
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-variable-values='{"title":"Q4 Revenue","accent":"#66d9ef"}'
+  data-start="2"
+  data-duration="8"
+  data-track-index="2"
+  data-width="1920"
+  data-height="1080"
+></div>
+```
+
+The host can render the same sub-composition multiple times with different `data-variable-values` to produce per-instance variations. See `variables-and-media.md` for variable declaration syntax.