dsh-hyperframes 0.2.0 → 0.3.1

package/skills/hyperframes-core/SKILL.md

@@ -0,0 +1,94 @@
+---
+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. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. 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`, `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"`                                                                                            |
+| `references/tracks-and-clips.md`        | understand what `data-track-index` does (and does not) control, z-index, time a clip relative to another                                                                           |
+| `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/storyboard-format.md`       | author a `STORYBOARD.md` plan (+ the parsed manifest)                                                                                                                              |
+| `references/review-loop.md`             | run the plan → sketch → build review passes on a live board — shared by every storyboard-planning workflow                                                                         |
+| `references/production-loop.md`         | take an approved plan to a delivered video — the stage dependencies (audio, frames, assembly, transitions, captions, verify, deliver) a freeform build follows directly            |
+| `references/brief-contract.md`          | the brief's ground rules — mode derivation (collaborative / autonomous), shared field registry, question invariants (the asking itself lives in `/hyperframes` → the intent layer) |
+| `references/brief-format.md`            | author `BRIEF.md` — the confirmed intent document a workflow's Setup writes and every later step reads                                                                             |
+| `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/frame-worker-core.md`       | the shared frame-worker role contract — each narrative workflow's packet builder prepends it to that workflow's `sub-agents/frame-worker.md` delta                                 |
+| `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.
+
+> ⚠ 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.
+> ⚠ 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 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. Do not rely on automated gates alone to catch this; inspect a snapshot. 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**.
+
+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` or raw `visibility` on a clip element. The framework owns clip visibility, and `lint` rejects it. Use GSAP `autoAlpha` or a zero-duration boundary `set`. (Tweening ordinary visual properties on a clip element is fine; what lint forbids is taking over its visibility.) → `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.
+- 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
+
+- [ ] `npx hyperframes check` passes (0 findings across lint, runtime, layout, motion, and contrast)
+- [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
+- [ ] `npx hyperframes preview --background` for review (the user can edit anything in Studio's timeline, and the server survives the invoking command)
+- [ ] `npx hyperframes render` only after the user approves

package/skills/hyperframes-core/references/brief-contract.md

@@ -0,0 +1,108 @@
+# Brief contract
+
+The intent layer (`/hyperframes` → `references/intent-interview.md`) asks creation questions once. The executing workflow writes the confirmed result to `BRIEF.md` and does not ask those questions again. This contract defines the canonical run-shape fields, shared brief fields, and question rules. Route-specific options live in `/hyperframes` → `references/routes/<workflow>.md`.
+
+## Contents
+
+- [Run shape](#1-run-shape)
+- [Shared fields](#2-shared-fields)
+- [Question protocol](#3-question-protocol)
+
+## 1. Run shape
+
+Three terms describe different concerns. Do not substitute one for another.
+
+| Term         | Values                          | Owns                                                                                          |
+| ------------ | ------------------------------- | --------------------------------------------------------------------------------------------- |
+| `flow`       | `automation` or `companion`     | Who drives execution. `companion` always executes in `/general-video`.                        |
+| `storyboard` | `yes` or `no`                   | Whether the live board is used for plan and layout review.                                    |
+| `mode`       | `collaborative` or `autonomous` | How later preference and checkpoint gates behave. The user never chooses this label directly. |
+
+Derive `mode` once from the confirmed run shape:
+
+| `flow`       | `storyboard` | Derived `mode`  |
+| ------------ | ------------ | --------------- |
+| `companion`  | either value | `collaborative` |
+| `automation` | `yes`        | `collaborative` |
+| `automation` | `no`         | `autonomous`    |
+
+Default to `collaborative` only when a legacy project lacks enough state to derive a mode. `/motion-graphics` is autonomous by design and does not need the two run-shape questions.
+
+### Signals and persistence
+
+- An ongoing signal such as “surprise me”, “decide for me”, “just build it”, or “stop asking” sets `flow: automation`, `storyboard: no`, and therefore `mode: autonomous` when it appears during intent capture.
+- A bare “go” or “looks good” at a checkpoint accepts that checkpoint only. It does not change mode.
+- After `STORYBOARD.md` exists, persist the derived mode in its frontmatter. On resume, an explicit `mode` in `STORYBOARD.md` overrides the derivation because it may represent a later user change.
+- Mid-run “stop asking; finish it” changes only checkpoint behavior. Set `STORYBOARD.md` `mode` to `autonomous` when the file exists. Do not rewrite the already-confirmed `flow` or `storyboard` fields.
+- Resume collaborative checkpoints only after an explicit signal such as “let's review together”; ordinary feedback does not change mode.
+
+### Gate behavior
+
+| Gate                                                                            | Collaborative                                                   | Autonomous                                                      |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- |
+| Preference: preset, voice, caption identity                                     | Ask when the workflow marks it as required.                     | Decide and state the choice with a one-line reason.             |
+| Checkpoint: plan, sketches, pre-render review                                   | Ask and wait.                                                   | Post the same summary, then continue.                           |
+| Quality: fetch completeness, `lint`, `hyperframes check`, workflow verification | Run and stop on errors.                                         | Run and stop on errors.                                         |
+| Routing ambiguity                                                               | Resolve explicitly; a wrong route changes the deliverable.      | Same requirement.                                               |
+| Sign-in or credential unavailable                                               | Show status and wait for sign-in or explicit offline selection. | Show status and continue through an available offline provider. |
+
+Autonomous mode never silently drops a required capability. If the selected workflow has no local, cached, or offline provider for it, surface the blocker instead of omitting the capability. A credential problem does not relax the quality gates.
+
+Rendering remains user-gated in both modes. After checks pass, collaborative runs ask “render now, or what changes?” Autonomous runs ask “preview first, or render?” Render only after the answer.
+
+### Studio comments
+
+Checkpoint feedback may arrive in chat or in `.hyperframes/frame-comments.json` (format: `storyboard-format.md`). When the user replies to a checkpoint, read that file before interpreting the chat reply. Apply only the named frame changes, delete the comments file after handling it, and re-present the affected frames. A board submission does not notify the agent, so tell the user to reply in chat after submitting comments.
+
+Autonomous is not silent: replace absorbed questions with visible decisions and short reasons. Every autonomous visual or video delivery names the final preview or rendered artifact as applicable, reports the actual duration for a time-based deliverable, and includes a contact sheet or snapshot sheet plus relevant frame identifiers when available. For multi-scene work, use scene midpoints; for a single-scene piece, use one or more proof times. This gives the user a review surface even though intermediate checkpoints did not pause.
+
+## 2. Shared fields
+
+Ask only fields used by the selected route. Route entries identify their must-have questions and deferred questions. Values inferred or derived by policy are stated in the brief, not asked.
+
+| Field         | Meaning                                              | Policy                                                                                                                                              |
+| ------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flow`        | Who drives execution                                 | Ask at the end of intent capture when the route supports both flows. An autonomous signal answers it.                                               |
+| `storyboard`  | Whether to review on the live board                  | Ask before `flow` when the route supports a board. A storyboard request answers it.                                                                 |
+| `destination` | Where the video will play                            | Infer from the request. Ask only when unknown and the answer changes aspect, type scale, or composition.                                            |
+| `aspect`      | Canvas size                                          | Derive from destination: social feed → `1080x1080`; TikTok/Reels/Shorts → `1080x1920`; YouTube/website/desktop → `1920x1080`. State the derivation. |
+| `length`      | Target duration                                      | Let the workflow recommend a range supported by the material; include the reason.                                                                   |
+| `language`    | Narration and caption language                       | Use the user's language and state it.                                                                                                               |
+| `audience`    | Who will watch                                       | Infer when clear. Ask only when a different answer changes the story or terminology.                                                                |
+| `message`     | The one thing the video must communicate             | Derive and echo one sentence. Do not storyboard until this is clear.                                                                                |
+| `angle`       | Route-specific story shape                           | Recommend one route-defined option with a reason.                                                                                                   |
+| `narration`   | `yes`, `minimal`, or `no`, plus route-specific modes | Follow the selected route.                                                                                                                          |
+
+### Remembered defaults
+
+Let `<MEDIA_DIR>` be the installed `/media-use` skill directory. Let `<MEMORY_ROOT>` be the existing project root. Before scaffolding, use a deliberately nonexistent probe path with no `.media` ancestor, such as `/tmp/hyperframes-intent-memory-<run-id>`; never use the current workspace as the probe. Read merged preferences with:
+
+```bash
+node <MEDIA_DIR>/scripts/prefs.mjs get --hyperframes <MEMORY_ROOT> --json
+```
+
+For the pre-project probe, `<MEMORY_ROOT>` is the nonexistent probe path, so only the personal tier can contribute. If that path already exists or contains `.media`, choose another. Do not claim project provenance before the real project exists.
+
+A remembered value becomes the recommended answer and names its source. It never overrides the current request and never skips a required question. A confirmed recipe is different: adopting the bundle may fill the fields it contains because adoption itself is the confirmation.
+
+Record only values the user confirmed, never values merely inferred or defaulted. Recording happens after the workflow writes `BRIEF.md`; supported keys are listed in `brief-format.md`. A user who sees the recommendation and accepts it has confirmed it. Personal defaults promote only according to `/media-use` memory rules.
+
+The first time a project records a preference, say one short line that it will be remembered for future runs. Do not re-record a remembered value merely because an autonomous build reused it; only a confirmation in the current run creates a new memory event.
+
+## 3. Question protocol
+
+Follow these invariants:
+
+1. Ask only unanswered fields that materially affect the output.
+2. Ask one field per message and wait for its answer before asking the next field.
+3. Put the recommended option first and attach a short reason. A numbered choice list is allowed, but every option in that list must answer the same field. Option lists fit factual fields (destination, length, language), where they scaffold recall; a creative field (message, angle, tone) the request has not already shaped takes an anchored open question — a list there steers the answer instead of collecting it.
+4. Skip a question when the current request already answers it. Inference alone is not an answer.
+5. Ask `storyboard` and then `flow` last, only for routes that support them.
+6. Announce deferred questions before hand-off; do not surprise the user later.
+7. When an autonomous signal appears, ask no remaining preference or checkpoint questions. State the completed brief and the reasons for decisions, then build.
+8. Use native question UI when available. Otherwise send one plain-text question with one numbered option list; never place several fields in the same list.
+9. Before the hand-off summary, run one integration check: look for a consequence the combined answers create that no single answer showed, and surface it with a proposed adjustment.
+10. The hand-off summary separates fields the user stated from fields that were inferred or defaulted, with receipts on both.
+11. Revision is not confirmation: after any correction to the summary, present the updated summary and confirm before executing.
+
+At a checkpoint, “go” accepts that checkpoint's displayed recommendation. If a message explicitly presents a complete brief and says that “go” will accept every displayed default, then “go” may confirm that whole displayed brief; do not assume broader acceptance without that sentence.

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

@@ -0,0 +1,72 @@
+# Brief format — `BRIEF.md`
+
+Defines the **intent document** — the file a confirmed brief becomes. The questions that fill it live in the intent layer (`/hyperframes` → `references/intent-interview.md` + its `references/routes/<workflow>.md`); the field semantics live in `brief-contract.md` § 2. This file defines only the artifact: its shape, its home, and its lifecycle.
+
+`BRIEF.md` sits at the project root, and the project's files read as four layers: **`BRIEF.md`** (why, for whom, and everything the user asked for) → **`STORYBOARD.md`** (what, frame by frame) → **`frame.md`** (how it looks) → **`compositions/`** (the thing itself).
+
+## Frontmatter — the confirmed fields
+
+YAML block at the top: one key per deterministic field — the run's shape first, then the registry fields (`brief-contract.md` § 2) used by the route. Store canonical normalized values. Some values come directly from the user; others, such as `workflow`, `aspect`, and `language`, are routed, derived, or normalized and must use the vocabulary defined by the contract. Preserve the user's own wording in the body when it matters.
+
+| Key                                                                       | Meaning                                                                                                                    | Example                     |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| `workflow`                                                                | the executing workflow (companion runs record `general-video`)                                                             | `faceless-explainer`        |
+| `flow`                                                                    | `automation` — the matched workflow's pipeline · `companion` — co-creation in `/general-video`                             | `automation`                |
+| `storyboard`                                                              | `yes` — plan, sketches, and build reviewed on the live board (`review-loop.md`) · `no` — one shot from the confirmed brief | `yes`                       |
+| `message`                                                                 | the ONE thing the video must communicate                                                                                   | `"Ship it in an afternoon"` |
+| `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed                                                                                   | —                           |
+
+**Which keys are memory.** Only the preference-backed subset — `destination`, `aspect`, `language`, `flow`, `storyboard`, `voice`, `style_preset` — is recorded with `media-use` → `scripts/prefs.mjs record` (the store rejects any other key). `style_preset` is stored per workflow: record it with `--workflow <w>` (the store refuses it bare — a look confirmed for one genre is not a default for the others). `message`, `audience`, `length`, `angle` live in the frontmatter only: they describe this video, not the user.
+
+## Body — the intent in prose
+
+Four sections, each optional — write what the intent layer actually learned, omit what it didn't:
+
+- `## Intent` — a short paragraph: what the video is, for whom, why now; tone and feel in the user's own words.
+- `## Assets` — the user's own material, one line each: `path — what it is, where it belongs`. Files named here are staged by the workflow, never re-discovered.
+- `## Customizations` — capabilities the user opted into from the menu (`/hyperframes` → `references/capability-menu.md`) and any bespoke asks ("count-up on the revenue stat", "capture the pricing page too"), each with enough detail to act on.
+- `## Notes` — everything true that fits no field: constraints, references, things to avoid.
+
+Body prose is **project-local** — nothing in it enters cross-project memory. (Frozen recipes carry a blanked skeleton of it; a future prose-memory layer would extract from here, under its own approval rules.)
+
+## Lifecycle
+
+- **Created once, by the workflow's Setup, as its first action after `hyperframes init`** — never before (`init` refuses a non-empty directory). The intent layer confirms the answers pre-project; Setup makes them durable, then records the preference-backed fields. Later confirmed changes update this same file.
+- **It is the no-repeat token.** A workflow that finds `BRIEF.md` reads it and asks no brief question. Its `workflow:` names the executor — a workflow that finds another's name there is in the wrong room: load that skill and hand over, don't re-route through the intent layer. No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → a pre-BRIEF project: resume from the storyboard's frontmatter and the recorded preferences, optionally backfilling `BRIEF.md` from what they already say — never re-interrogate a half-built project.
+- **It stays the run's truth.** A mid-run decision updates it as it happens: an explicit change to a frontmatter field ("make it 9:16 after all") rewrites the field and re-records the preference — a changed mind is a confirmed answer; an accepted capability, adopted material, or bespoke ask lands as one line in the matching body section. Resume reads this file, so write-back is what makes a dead session resumable — a decision that lives only in chat is a decision resume never sees.
+- **Execution mode derives; the storyboard's copy wins on resume.** `flow` × `storyboard` derive collaborative/autonomous checkpoint behavior (`brief-contract.md` § 1). Persist the derived mode in `STORYBOARD.md` frontmatter when that file exists. A mid-run mode-only switch updates `STORYBOARD.md`, not the already-confirmed `flow` or `storyboard`; an explicit change to either run-shape field still updates `BRIEF.md`.
+- **`message` / `audience` live here first.** `STORYBOARD.md` frontmatter keeps its copies — the board and the parser read them — but when the two disagree, `BRIEF.md` holds what the user confirmed.
+- **Recipes carry its skeleton.** Freezing a recipe (`review-loop.md` § 4) captures `brief-skeleton.md` — frontmatter structure kept, run-shape and content values blanked — so the next run starts pre-filled yet still confirms its own two run-shape answers.
+
+## Example
+
+```markdown
+---
+workflow: faceless-explainer
+flow: automation
+storyboard: yes
+message: "Compound interest is a snowball, not a ladder"
+destination: x-feed
+aspect: 1080x1080
+language: en
+length: 60s
+angle: concept
+---
+
+## Intent
+
+Teach retail investors why starting early beats contributing more. Confident,
+a little playful — closer to a bar-napkin sketch than a lecture.
+
+## Assets
+
+- public/growth-curve.png — the real 30-year S&P chart; the proof beat builds on it.
+
+## Customizations
+
+- Count-up on the final dollar figure.
+
+## Notes
+
+- No stock-photo aesthetics; keep it typographic.
+```

package/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`), 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.
+  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:
+
+- 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>
+      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 deliberate `data-start` and a sensible `data-track-index`, and extend the existing single timeline.
+- In a **modular** project, match the pattern: add a new file under `compositions/`, add a slot in `index.html`, keep the root timeline thin. Do **not** start inlining new scenes into `index.html` when sibling scenes are sub-comps — the inconsistency is the worst of both worlds.
+- If a monolithic project needs a third or fourth scene cut, lift each scene into a sub-comp before adding more. The conversion is mechanical (see "Refactor between them" above).
+
+When picking the slot's `data-start`/`data-duration`, prefer continuing the existing sequencing convention (adjoining starts, deliberate overlaps for cross-fades). Don't introduce a new track index unless you actually need parallel visual layers — most sequential-scene projects use exactly one visual track.