takomi 2.5.1 → 2.5.4

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

@@ -1,125 +1,125 @@
-# HyperFrames Tailwind
-
-HyperFrames `init --tailwind` uses the Tailwind browser runtime pinned by the scaffold. Treat it as Tailwind v4, not Studio's Tailwind v3 setup.
-
-## When To Use
-
-- The project was scaffolded with `npx hyperframes init --tailwind`.
-- `index.html` contains `window.__tailwindReady`.
-- The task asks for Tailwind utility classes, `@theme`, custom utilities, or v3-to-v4 fixes in a composition.
-- Rendered frames have missing Tailwind styles or frame-0 flashes.
-
-## Version Contract
-
-- **Pinned: `@tailwindcss/browser@4.2.4`** (source of truth: `packages/cli/src/commands/init.ts` `TAILWIND_BROWSER_VERSION`).
-- Do not replace the scaffolded runtime with `cdn.tailwindcss.com` (unpinned, defeats reproducibility).
-- Keep the readiness shim deterministic; HyperFrames waits for `window.__tailwindReady` before frame 0 capture.
-- For offline / locked-down / production-stable renders, compile Tailwind to CSS and ship the stylesheet instead of the browser runtime.
-
-## v4 Browser Runtime Rules
-
-Tailwind v4 is CSS-first:
-
-```html
-<style type="text/tailwindcss">
-  @theme {
-    --color-brand: oklch(0.68 0.2 252);
-    --font-display: "Inter", sans-serif;
-  }
-
-  @utility headline-balance {
-    text-wrap: balance;
-    letter-spacing: 0;
-  }
-</style>
-```
-
-Avoid v3-only patterns in browser-runtime compositions:
-
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
-
-Do not add `tailwind.config.js` only for composition colors, fonts, spacing, or utilities. Use `@theme` and `@utility`.
-
-**Migrating from v3?** Load an existing JS config explicitly: put `@config "./tailwind.config.js";` inside a `text/tailwindcss` block. v4 does **not** auto-detect v3 config files.
-
-## Composition Pattern
-
-Use Tailwind for static layout and style. Keep render-critical timing in GSAP or another seekable HyperFrames adapter.
-
-```html
-<section
-  id="hero"
-  class="clip absolute inset-0 grid place-items-center bg-zinc-950 text-white"
-  data-start="0"
-  data-duration="5"
-  data-track-index="1"
->
-  <div class="w-[1280px] max-w-[82vw] text-center">
-    <h1 class="text-7xl font-black leading-none text-balance">Render-ready Tailwind</h1>
-  </div>
-</section>
-```
-
-For repeated items, **parameterize via CSS variables** — keep the class list static so the runtime sees every utility:
-
-```html
-<span class="translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 0"></span>
-<span class="translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 1"></span>
-<span class="translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 2"></span>
-```
-
-## Dynamic Class Safety
-
-The browser runtime scans classes it can see. Do not build render-critical class names only at seek time:
-
-```js
-// Risky: the runtime may never see every generated class.
-element.className = `bg-${color}-500`;
-```
-
-Prefer complete class tokens in HTML, data variants, or explicit CSS:
-
-```html
-<div data-tone="blue" class="bg-blue-500 data-[tone=rose]:bg-rose-500"></div>
-```
-
-If a generated class is unavoidable, make sure the full class token appears in a `text/tailwindcss` block before validation.
-
-## Video-Specific Guardrails
-
-v4 + render-mode footguns. Every bullet is a hard rule:
-
-- **Stable dimensions only** — use `w-[…]` / `h-[…]` / `aspect-video` / grid / flex. **No `md:` / `lg:` breakpoints** (renderer is fixed-viewport).
-- **Animate via transforms / opacity** — `translate-*`, `scale-*`, `opacity-*` are seek-safe; animating Tailwind sizing utilities is not.
-- **No `transition-*` for render-critical motion** — a seekable runtime (GSAP) must own the state.
-- **No interaction variants** — `hover:` / `focus:` / `active:` / `group-*:` / `peer-*:` / scroll / pointer variants never fire during render.
-- **Bare `border` is broken in v4** — v4 default is `currentColor` (v3 was `gray-200`). Always write the color: `border border-white/20`.
-- **v4 utility renames** — `shadow-sm` → `shadow-xs`, `rounded-sm` → `rounded-xs`, `outline-none` → `outline-hidden`, `flex-shrink-*` → `shrink-*`, `flex-grow-*` → `grow-*`.
-- **Modern CSS is fine** — `color-mix()`, container queries, logical properties work; the renderer is current Chrome.
-
-## Validation
-
-```bash
-npx hyperframes lint
-npx hyperframes validate
-npx hyperframes inspect
-
-# Render proof — frame 0 must NOT flash unstyled content. Preview alone can hide this.
-npx hyperframes render . --workers 1 --quality draft --output tailwind-proof.mp4
-```
-
-## Quick Debug Checklist
-
-When Tailwind styles don't apply in a render, check in order:
-
-1. Project scaffolded with `npx hyperframes init --tailwind`?
-2. `index.html` `<head>` has `<script src="…@tailwindcss/browser@4.2.4…">` (not `cdn.tailwindcss.com`)?
-3. `window.__tailwindReady` Promise present in `<head>`?
-4. No v3 directives (`@tailwind base/components/utilities`) in the file?
-5. Tokens moved from `tailwind.config.js` to `@theme` (or `@config` reference for v3 migration)?
-6. Every render-critical class appears as a complete static token (no `bg-${color}-500` style assembly)?
-7. Re-run `npx hyperframes validate`, then the render proof above.
+# HyperFrames Tailwind
+
+HyperFrames `init --tailwind` uses the Tailwind browser runtime pinned by the scaffold. Treat it as Tailwind v4, not Studio's Tailwind v3 setup.
+
+## When To Use
+
+- The project was scaffolded with `npx hyperframes init --tailwind`.
+- `index.html` contains `window.__tailwindReady`.
+- The task asks for Tailwind utility classes, `@theme`, custom utilities, or v3-to-v4 fixes in a composition.
+- Rendered frames have missing Tailwind styles or frame-0 flashes.
+
+## Version Contract
+
+- **Pinned: `@tailwindcss/browser@4.2.4`** (source of truth: `packages/cli/src/commands/init.ts` `TAILWIND_BROWSER_VERSION`).
+- Do not replace the scaffolded runtime with `cdn.tailwindcss.com` (unpinned, defeats reproducibility).
+- Keep the readiness shim deterministic; HyperFrames waits for `window.__tailwindReady` before frame 0 capture.
+- For offline / locked-down / production-stable renders, compile Tailwind to CSS and ship the stylesheet instead of the browser runtime.
+
+## v4 Browser Runtime Rules
+
+Tailwind v4 is CSS-first:
+
+```html
+<style type="text/tailwindcss">
+  @theme {
+    --color-brand: oklch(0.68 0.2 252);
+    --font-display: "Inter", sans-serif;
+  }
+
+  @utility headline-balance {
+    text-wrap: balance;
+    letter-spacing: 0;
+  }
+</style>
+```
+
+Avoid v3-only patterns in browser-runtime compositions:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Do not add `tailwind.config.js` only for composition colors, fonts, spacing, or utilities. Use `@theme` and `@utility`.
+
+**Migrating from v3?** Load an existing JS config explicitly: put `@config "./tailwind.config.js";` inside a `text/tailwindcss` block. v4 does **not** auto-detect v3 config files.
+
+## Composition Pattern
+
+Use Tailwind for static layout and style. Keep render-critical timing in GSAP or another seekable HyperFrames adapter.
+
+```html
+<section
+  id="hero"
+  class="clip absolute inset-0 grid place-items-center bg-zinc-950 text-white"
+  data-start="0"
+  data-duration="5"
+  data-track-index="1"
+>
+  <div class="w-[1280px] max-w-[82vw] text-center">
+    <h1 class="text-7xl font-black leading-none text-balance">Render-ready Tailwind</h1>
+  </div>
+</section>
+```
+
+For repeated items, **parameterize via CSS variables** — keep the class list static so the runtime sees every utility:
+
+```html
+<span class="translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 0"></span>
+<span class="translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 1"></span>
+<span class="translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 2"></span>
+```
+
+## Dynamic Class Safety
+
+The browser runtime scans classes it can see. Do not build render-critical class names only at seek time:
+
+```js
+// Risky: the runtime may never see every generated class.
+element.className = `bg-${color}-500`;
+```
+
+Prefer complete class tokens in HTML, data variants, or explicit CSS:
+
+```html
+<div data-tone="blue" class="bg-blue-500 data-[tone=rose]:bg-rose-500"></div>
+```
+
+If a generated class is unavoidable, make sure the full class token appears in a `text/tailwindcss` block before validation.
+
+## Video-Specific Guardrails
+
+v4 + render-mode footguns. Every bullet is a hard rule:
+
+- **Stable dimensions only** — use `w-[…]` / `h-[…]` / `aspect-video` / grid / flex. **No `md:` / `lg:` breakpoints** (renderer is fixed-viewport).
+- **Animate via transforms / opacity** — `translate-*`, `scale-*`, `opacity-*` are seek-safe; animating Tailwind sizing utilities is not.
+- **No `transition-*` for render-critical motion** — a seekable runtime (GSAP) must own the state.
+- **No interaction variants** — `hover:` / `focus:` / `active:` / `group-*:` / `peer-*:` / scroll / pointer variants never fire during render.
+- **Bare `border` is broken in v4** — v4 default is `currentColor` (v3 was `gray-200`). Always write the color: `border border-white/20`.
+- **v4 utility renames** — `shadow-sm` → `shadow-xs`, `rounded-sm` → `rounded-xs`, `outline-none` → `outline-hidden`, `flex-shrink-*` → `shrink-*`, `flex-grow-*` → `grow-*`.
+- **Modern CSS is fine** — `color-mix()`, container queries, logical properties work; the renderer is current Chrome.
+
+## Validation
+
+```bash
+npx hyperframes lint
+npx hyperframes validate
+npx hyperframes inspect
+
+# Render proof — frame 0 must NOT flash unstyled content. Preview alone can hide this.
+npx hyperframes render . --workers 1 --quality draft --output tailwind-proof.mp4
+```
+
+## Quick Debug Checklist
+
+When Tailwind styles don't apply in a render, check in order:
+
+1. Project scaffolded with `npx hyperframes init --tailwind`?
+2. `index.html` `<head>` has `<script src="…@tailwindcss/browser@4.2.4…">` (not `cdn.tailwindcss.com`)?
+3. `window.__tailwindReady` Promise present in `<head>`?
+4. No v3 directives (`@tailwind base/components/utilities`) in the file?
+5. Tokens moved from `tailwind.config.js` to `@theme` (or `@config` reference for v3 migration)?
+6. Every render-critical class appears as a complete static token (no `bg-${color}-500` style assembly)?
+7. Re-run `npx hyperframes validate`, then the render proof above.

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

@@ -1,76 +1,76 @@
-# Tracks and Clips
-
-Clips are timed children of the composition root. Tracks are a temporal-overlap concept, not a visual-stacking concept.
-
-## What is a Clip
-
-A clip is any DOM element with `data-start`, `data-duration` (where required), and `data-track-index`. Common kinds:
-
-- **Visual `<div>` clips** — scenes, cards, overlays. Always require `data-duration`.
-- **Sub-composition hosts** — `<div>` with `data-composition-src`. Always require `data-duration`.
-- **Video clips** — `<video>` with `muted` and `playsinline`. Duration can default to media length.
-- **Audio clips** — `<audio>`. Duration can default to media length.
-- **Image clips** — `<img>`. Always require `data-duration`.
-
-Add `class="clip"` to authored visual clips so tooling and examples can find them.
-
-## Tracks Are Temporal, Not Visual
-
-`data-track-index` controls **temporal overlap**, not paint order:
-
-- **Two clips on the same `data-track-index`** must NOT overlap in time. `hyperframes lint` flags this.
-- **Visual layering (front/back)** is controlled by CSS `z-index`, not by track index.
-
-A clip on track `5` is not "above" a clip on track `1` — it's just on a different audio/visual lane in time. Use CSS for layering, tracks for sequencing.
-
-## Picking a Track Index
-
-There's no fixed convention, but common patterns:
-
-- **Track 0** — base video (e.g. an A-roll).
-- **Track 1+** — visual scenes, overlays, captions.
-- **Higher tracks (e.g. 10+)** — audio clips, separated from visual tracks to keep linting clear.
-
-When adding a new clip to an existing composition:
-
-1. Find an existing track that has no overlap with your new clip's `[data-start, data-start + data-duration)` range.
-2. Or pick a fresh track index.
-3. Never overlap two clips on the same track — the linter will fail and the render is undefined.
-
-## Clip Time Inside the Composition
-
-`data-start` is in seconds, measured from the start of the _composition_. For sub-compositions, the sub-composition's internal timeline (its own `data-duration` and child clips) runs from `data-start` to `data-start + data-duration` of the host.
-
-`data-media-start` (on `<video>`/`<audio>`) is an offset _into the source media_. Use it to skip the first few seconds of a media file without trimming the file itself.
-
-## Relative Timing
-
-`data-start` accepts a clip ID instead of a number, meaning "start when that clip ends". Add `+ N` / `- N` to offset; negative produces overlap (useful for crossfades).
-
-```html
-<video id="intro" data-start="0" data-duration="10" data-track-index="0" src="..."></video>
-<video id="main" data-start="intro" data-duration="20" data-track-index="0" src="..."></video>
-<video
-  id="scene-a"
-  data-start="intro + 2"
-  data-duration="20"
-  data-track-index="0"
-  src="..."
-></video>
-<video
-  id="scene-b"
-  data-start="intro - 0.5"
-  data-duration="20"
-  data-track-index="1"
-  src="..."
-></video>
-```
-
-Rules:
-
-- References resolve **inside the same composition only** — cannot reach into a parent or sibling sub-composition.
-- The referenced clip must have a **known duration** (explicit `data-duration` or inferred from media). Otherwise the reference cannot resolve.
-- **No circular references** — `A → B → A` is rejected. Cycles are detected and error out.
-- A value that parses as a number is always treated as absolute seconds. Otherwise the resolver expects `<id>`, `<id> + <number>`, or `<id> - <number>` (whitespace optional).
-- References can chain (`A → B → C`). Keep chains under 3-4 levels for readability.
-- Negative offsets create overlap; overlapping clips must be on **different tracks**, same-track overlap is rejected.
+# Tracks and Clips
+
+Clips are timed children of the composition root. Tracks are a temporal-overlap concept, not a visual-stacking concept.
+
+## What is a Clip
+
+A clip is any DOM element with `data-start`, `data-duration` (where required), and `data-track-index`. Common kinds:
+
+- **Visual `<div>` clips** — scenes, cards, overlays. Always require `data-duration`.
+- **Sub-composition hosts** — `<div>` with `data-composition-src`. Always require `data-duration`.
+- **Video clips** — `<video>` with `muted` and `playsinline`. Duration can default to media length.
+- **Audio clips** — `<audio>`. Duration can default to media length.
+- **Image clips** — `<img>`. Always require `data-duration`.
+
+Add `class="clip"` to authored visual clips so tooling and examples can find them.
+
+## Tracks Are Temporal, Not Visual
+
+`data-track-index` controls **temporal overlap**, not paint order:
+
+- **Two clips on the same `data-track-index`** must NOT overlap in time. `hyperframes lint` flags this.
+- **Visual layering (front/back)** is controlled by CSS `z-index`, not by track index.
+
+A clip on track `5` is not "above" a clip on track `1` — it's just on a different audio/visual lane in time. Use CSS for layering, tracks for sequencing.
+
+## Picking a Track Index
+
+There's no fixed convention, but common patterns:
+
+- **Track 0** — base video (e.g. an A-roll).
+- **Track 1+** — visual scenes, overlays, captions.
+- **Higher tracks (e.g. 10+)** — audio clips, separated from visual tracks to keep linting clear.
+
+When adding a new clip to an existing composition:
+
+1. Find an existing track that has no overlap with your new clip's `[data-start, data-start + data-duration)` range.
+2. Or pick a fresh track index.
+3. Never overlap two clips on the same track — the linter will fail and the render is undefined.
+
+## Clip Time Inside the Composition
+
+`data-start` is in seconds, measured from the start of the _composition_. For sub-compositions, the sub-composition's internal timeline (its own `data-duration` and child clips) runs from `data-start` to `data-start + data-duration` of the host.
+
+`data-media-start` (on `<video>`/`<audio>`) is an offset _into the source media_. Use it to skip the first few seconds of a media file without trimming the file itself.
+
+## Relative Timing
+
+`data-start` accepts a clip ID instead of a number, meaning "start when that clip ends". Add `+ N` / `- N` to offset; negative produces overlap (useful for crossfades).
+
+```html
+<video id="intro" data-start="0" data-duration="10" data-track-index="0" src="..."></video>
+<video id="main" data-start="intro" data-duration="20" data-track-index="0" src="..."></video>
+<video
+  id="scene-a"
+  data-start="intro + 2"
+  data-duration="20"
+  data-track-index="0"
+  src="..."
+></video>
+<video
+  id="scene-b"
+  data-start="intro - 0.5"
+  data-duration="20"
+  data-track-index="1"
+  src="..."
+></video>
+```
+
+Rules:
+
+- References resolve **inside the same composition only** — cannot reach into a parent or sibling sub-composition.
+- The referenced clip must have a **known duration** (explicit `data-duration` or inferred from media). Otherwise the reference cannot resolve.
+- **No circular references** — `A → B → A` is rejected. Cycles are detected and error out.
+- A value that parses as a number is always treated as absolute seconds. Otherwise the resolver expects `<id>`, `<id> + <number>`, or `<id> - <number>` (whitespace optional).
+- References can chain (`A → B → C`). Keep chains under 3-4 levels for readability.
+- Negative offsets create overlap; overlapping clips must be on **different tracks**, same-track overlap is rejected.

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

@@ -1,90 +1,90 @@
-# Variables and Media
-
-Two separate concerns, grouped because both control "what flows in from outside the HTML": runtime parameters (variables) and external media files (video/audio).
-
-## Variables
-
-Declare variables on the `<html>` element with `data-composition-variables`. Each declaration needs `id`, `type`, `label`, and `default`:
-
-```html
-<html
-  data-composition-variables='[
-    {"id":"title","type":"string","label":"Title","default":"Hello"},
-    {"id":"accent","type":"color","label":"Accent","default":"#66d9ef"}
-  ]'
-></html>
-```
-
-Read resolved values once during initialization:
-
-```js
-const { title, accent } = window.__hyperframes.getVariables();
-document.getElementById("title").textContent = title;
-document.documentElement.style.setProperty("--accent", accent);
-```
-
-### Variable Rules
-
-- Supported types and their extra options (consumed by Studio's editing UI):
-  - `string` — optional `placeholder`, `maxLength`
-  - `number` — optional `min`, `max`, `step`, `unit`
-  - `color` — none
-  - `boolean` — none
-  - `enum` — **required** `options: [{ "value": "...", "label": "..." }, ...]`
-- Always provide useful `default` values so preview works without CLI overrides.
-- Use `data-variable-values='{"title":"Pro"}'` on sub-composition hosts for per-instance overrides.
-- Use `npx hyperframes render --variables '{"title":"Q4 Report"}'` or `--variables-file` for render-time overrides.
-- Add `--strict-variables` in CI: turns undeclared keys, type mismatches, and enum values not in `options` into errors instead of warnings.
-- Read values once during init, not on every animation tick — variables don't change mid-render.
-- Media color grading can use exact variable references inside `data-color-grading` JSON. Use `$gradingPreset` or `${gradingIntensity}` as the whole field value; the runtime resolves it from the current composition's variables before applying the shader grading.
-
-### Two JSON Shapes (Easy to Confuse)
-
-- `data-composition-variables` is an **array of declarations** (the schema): `[{id, type, label, default}, ...]`
-- `--variables` and `data-variable-values` are **objects keyed by id** (the values): `{ title: "Q4", accent: "#fff" }`
-
-## Media
-
-**NON-NEGOTIABLE: `<video>`/`<audio>` must be a DIRECT child of the host composition root (`index.html`).** The runtime only registers + drives media that is a direct root child. Media placed inside a sub-composition `<template>`, or wrapped in any intermediate `<div>`, is never seeked/decoded → renders blank (paper/white) or black. `lint`/`validate`/`inspect` do not catch this; per-frame `snapshot` shows the blank panel.
-
-Consequences:
-
-- A scene-specific clip still lives at the host root, not in the scene's sub-comp. The sub-comp keeps only the frame/shell; the media is a sibling host element positioned over it.
-- A sub-composition **cannot reach or animate host elements** — neither `document.querySelector("#host-id")` nor a gsap selector string (`tl.to("#host-id", …)`) resolves across the boundary; a sub-comp timeline only drives its own subtree. So **all per-scene motion on host media (scale/opacity/morph/tilt/breathing) must be authored on the MAIN timeline in `index.html`, at GLOBAL time** (scene-local time + the scene slot's `data-start`). For 3D tilt without a perspective parent, use gsap `transformPerspective` on the element. See `composition-patterns.md` archetype B.
-
-Video elements must be muted and inline. Audio must be a separate `<audio>` element, even when it uses the same source file.
-
-```html
-<video
-  id="a-roll"
-  class="clip"
-  src="assets/demo.mp4"
-  data-start="0"
-  data-duration="12"
-  data-track-index="0"
-  muted
-  playsinline
-></video>
-
-<audio
-  id="a-roll-audio"
-  src="assets/demo.mp4"
-  data-start="0"
-  data-duration="12"
-  data-track-index="10"
-  data-volume="1"
-></audio>
-```
-
-### Media Rules
-
-- **Do not** call `video.play()`, `audio.play()`, pause, or seek in composition code. HyperFrames owns playback.
-- **Do not** place media inside a sub-comp `<template>` or any wrapper `<div>` — direct host-root child only (see above), else it never decodes.
-- **Do not** drive host media from a sub-comp timeline — it has no effect. Drive it from the main timeline at global time.
-- **Do not** animate timed media element dimensions; animate a non-timed wrapper instead.
-- **Do not** nest video inside a timed wrapper. Put timing on the media element or keep the wrapper untimed.
-- Add `crossorigin="anonymous"` for external media that needs canvas capture or pixel inspection.
-- Audio always lives on a separate `<audio>` element — even if its source file is the same as a `<video>`. The `<video>` is muted; the `<audio>` carries sound.
-- For volume fades/ducking, animate `volume` on the timeline (`tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`) rather than swapping `data-volume`. The runtime probes the timeline's volume keyframes and applies them identically in preview and render; `data-volume` is the static baseline for elements no tween touches.
-
-For media duration: `<video>` and `<audio>` can omit `data-duration` if the media's intrinsic length is known and you want the full clip. Otherwise provide `data-duration` explicitly.
+# Variables and Media
+
+Two separate concerns, grouped because both control "what flows in from outside the HTML": runtime parameters (variables) and external media files (video/audio).
+
+## Variables
+
+Declare variables on the `<html>` element with `data-composition-variables`. Each declaration needs `id`, `type`, `label`, and `default`:
+
+```html
+<html
+  data-composition-variables='[
+    {"id":"title","type":"string","label":"Title","default":"Hello"},
+    {"id":"accent","type":"color","label":"Accent","default":"#66d9ef"}
+  ]'
+></html>
+```
+
+Read resolved values once during initialization:
+
+```js
+const { title, accent } = window.__hyperframes.getVariables();
+document.getElementById("title").textContent = title;
+document.documentElement.style.setProperty("--accent", accent);
+```
+
+### Variable Rules
+
+- Supported types and their extra options (consumed by Studio's editing UI):
+  - `string` — optional `placeholder`, `maxLength`
+  - `number` — optional `min`, `max`, `step`, `unit`
+  - `color` — none
+  - `boolean` — none
+  - `enum` — **required** `options: [{ "value": "...", "label": "..." }, ...]`
+- Always provide useful `default` values so preview works without CLI overrides.
+- Use `data-variable-values='{"title":"Pro"}'` on sub-composition hosts for per-instance overrides.
+- Use `npx hyperframes render --variables '{"title":"Q4 Report"}'` or `--variables-file` for render-time overrides.
+- Add `--strict-variables` in CI: turns undeclared keys, type mismatches, and enum values not in `options` into errors instead of warnings.
+- Read values once during init, not on every animation tick — variables don't change mid-render.
+- Media color grading can use exact variable references inside `data-color-grading` JSON. Use `$gradingPreset` or `${gradingIntensity}` as the whole field value; the runtime resolves it from the current composition's variables before applying the shader grading.
+
+### Two JSON Shapes (Easy to Confuse)
+
+- `data-composition-variables` is an **array of declarations** (the schema): `[{id, type, label, default}, ...]`
+- `--variables` and `data-variable-values` are **objects keyed by id** (the values): `{ title: "Q4", accent: "#fff" }`
+
+## Media
+
+**NON-NEGOTIABLE: `<video>`/`<audio>` must be a DIRECT child of the host composition root (`index.html`).** The runtime only registers + drives media that is a direct root child. Media placed inside a sub-composition `<template>`, or wrapped in any intermediate `<div>`, is never seeked/decoded → renders blank (paper/white) or black. `lint`/`validate`/`inspect` do not catch this; per-frame `snapshot` shows the blank panel.
+
+Consequences:
+
+- A scene-specific clip still lives at the host root, not in the scene's sub-comp. The sub-comp keeps only the frame/shell; the media is a sibling host element positioned over it.
+- A sub-composition **cannot reach or animate host elements** — neither `document.querySelector("#host-id")` nor a gsap selector string (`tl.to("#host-id", …)`) resolves across the boundary; a sub-comp timeline only drives its own subtree. So **all per-scene motion on host media (scale/opacity/morph/tilt/breathing) must be authored on the MAIN timeline in `index.html`, at GLOBAL time** (scene-local time + the scene slot's `data-start`). For 3D tilt without a perspective parent, use gsap `transformPerspective` on the element. See `composition-patterns.md` archetype B.
+
+Video elements must be muted and inline. Audio must be a separate `<audio>` element, even when it uses the same source file.
+
+```html
+<video
+  id="a-roll"
+  class="clip"
+  src="assets/demo.mp4"
+  data-start="0"
+  data-duration="12"
+  data-track-index="0"
+  muted
+  playsinline
+></video>
+
+<audio
+  id="a-roll-audio"
+  src="assets/demo.mp4"
+  data-start="0"
+  data-duration="12"
+  data-track-index="10"
+  data-volume="1"
+></audio>
+```
+
+### Media Rules
+
+- **Do not** call `video.play()`, `audio.play()`, pause, or seek in composition code. HyperFrames owns playback.
+- **Do not** place media inside a sub-comp `<template>` or any wrapper `<div>` — direct host-root child only (see above), else it never decodes.
+- **Do not** drive host media from a sub-comp timeline — it has no effect. Drive it from the main timeline at global time.
+- **Do not** animate timed media element dimensions; animate a non-timed wrapper instead.
+- **Do not** nest video inside a timed wrapper. Put timing on the media element or keep the wrapper untimed.
+- Add `crossorigin="anonymous"` for external media that needs canvas capture or pixel inspection.
+- Audio always lives on a separate `<audio>` element — even if its source file is the same as a `<video>`. The `<video>` is muted; the `<audio>` carries sound.
+- For volume fades/ducking, animate `volume` on the timeline (`tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`) rather than swapping `data-volume`. The runtime probes the timeline's volume keyframes and applies them identically in preview and render; `data-volume` is the static baseline for elements no tween touches.
+
+For media duration: `<video>` and `<audio>` can omit `data-duration` if the media's intrinsic length is known and you want the full clip. Otherwise provide `data-duration` explicitly.