@prestyj/cli 5.27.0 → 5.28.1

package/assets/motion/references/runtime/preview-render.md

@@ -0,0 +1,156 @@
+# preview, play, render, publish
+
+Serve, render, and share commands.
+
+## preview
+
+```bash
+hf preview                   # foreground on a TTY; persistent in agent shells
+hf preview --background      # explicit persistent session
+hf preview --foreground --json # ready JSON, then remain attached
+hf preview --background --port 4567 # agent-safe custom port (default 3002)
+hf preview --selection --json # print the current Studio selection and exit
+hf preview --context --json  # print compact agent context from Studio
+```
+
+Hot-reloads on file changes. Opens Studio in the browser automatically — the full timeline editor, where the user can play the video and edit anything by hand before rendering. This is the review surface, not just a viewer.
+
+When handing a project back to the user, use the Studio project URL, not the source `index.html` path:
+
+```text
+http://localhost:<port>/#project/<project-name>
+```
+
+Use the actual port and project directory name; treat `index.html` as source-code context, not the preview surface. For example, after `hf preview --background --port 3017` in `codex-openai-video`, report `http://localhost:3017/#project/codex-openai-video`.
+
+Two ways a handed URL turns out dead — check both before handing it back: the URL is missing its `#project/<project-name>` hash (Studio loads but has no project to open), or the server is not actually running. Bare `preview` automatically creates a managed persistent session in a non-TTY agent shell; `--background` remains the clearest explicit form. Verify the printed URL returns HTTP 200, keep it alive for the whole review, and stop it explicitly with `hf preview --stop` afterward. Use the printed URL as-is: HyperFrames URL-encodes project names that contain route metacharacters.
+
+### Agent context from Studio selection
+
+`preview --context` and `preview --selection` are the agent bridge into a running Studio session. They do **not** start a new server; they find the active preview server for the current project, read agent-useful state from Studio, print it, and exit.
+
+Use it when the user gives deictic edit instructions like "change this", "move the selected element", "make the card I clicked bigger", or "fix the current selection":
+
+```bash
+hf preview --context --json --context-fields selection
+```
+
+The compact context payload includes the selected element's source file, composition path, current timeline time, `data-hf-id` / selector target, bounding box, text content, and a thumbnail URL for the selected element. Prefer `selection.target.hfId` when present; fall back to `selection.target.selector` only when no stable `data-hf-id` exists. If `selection` is `null`, inspect `errors.selection.code` (for example, `no-selection`).
+
+Keep agent context small by asking only for the slices you need:
+
+```bash
+hf preview --context --json --context-fields selection
+hf preview --context --json --context-fields lint
+hf preview --context --json --context-fields selection,lint
+```
+
+Use `--context-detail full` only when the edit genuinely needs heavy selection fields such as `computedStyles`, `inlineStyles`, `dataAttributes`, or editable text-field metadata:
+
+```bash
+hf preview --context --json --context-fields selection --context-detail full
+```
+
+`preview --selection --json` remains available when you explicitly want the full selected-element payload and do not need lint/server context.
+
+Failure modes:
+
+| Code                       | Meaning                                                                    |
+| -------------------------- | -------------------------------------------------------------------------- |
+| `preview-not-running`      | Start Studio first with `hf preview --background`.            |
+| `ambiguous-preview-server` | Multiple matching Studio servers are open; rerun with one listed `--port`. |
+| `preview-port-mismatch`    | The requested `--port` is not one of the matching Studio servers.          |
+| `no-selection`             | Studio is open, but the user has not selected an element yet.              |
+| `selection-unavailable`    | The running preview server does not expose selection context cleanly.      |
+
+If there is no selection, ask the user to click the target element in Studio and rerun the command. If the server error lists candidate ports, rerun the same command with `--port <candidate>`. Do not infer the target from a screenshot when the CLI can give a stable element target.
+
+## play (lightweight player)
+
+```bash
+hf play                  # current project, port 3003
+hf play ./my-video       # specific project
+hf play --port 8080      # custom port
+```
+
+`play` serves the composition through the embeddable `<hyperframes-player>` web component instead of the full Studio UI. Use it when sharing a preview link or when Studio is heavier than needed (no editor, no panels). `play` reports the plain `http://localhost:<port>` URL — no `#project/<name>` fragment (that's a Studio routing convention only `preview` uses).
+
+The player's `playback-rate` attribute (preview speed control, drives the timeline's `timeScale`) is clamped to `[0.1, 5]`; values `≤ 0` or non-finite fall back to `1`. This is a preview/playback knob, not a composition `data-*` attribute — authored motion still renders at `1×`.
+
+### Launching with an external browser (preview + play)
+
+Both `preview` and `play` can open inside an explicit Chromium-compatible browser instead of the OS default. Two use cases: isolated Chromium profile, or external CDP attach (DevTools / Playwright / Puppeteer / browser-MCP). **HyperFrames itself does not own CDP automation** — this only exposes the endpoint; whatever connects to it is your problem. Not to be confused with `--browser-gpu` (a `render` flag controlling Chrome GPU access during capture).
+
+| Flag                      | Type            | Notes                                                                                                                                                                                           |
+| ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--browser-path`          | path            | Absolute path to a Chromium-compatible executable (`/usr/bin/chromium`, `/Applications/Brave Browser.app/...`).                                                                                 |
+| `--user-data-dir`         | path            | Chromium-compatible profile directory. Requires `--browser-path`. Use a throwaway directory to keep state out of your main profile.                                                             |
+| `--remote-debugging-port` | integer 1-65535 | Open a Chromium CDP endpoint on the given port. **Requires both** `--browser-path` and `--user-data-dir` — refused otherwise, so a CDP endpoint cannot leak into your main profile by accident. |
+
+```bash
+# Open preview in an isolated Chromium profile
+hf preview --background --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile
+
+# Same plus a CDP endpoint on :9222 (attach DevTools / Playwright / etc.)
+hf play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222
+```
+
+Validation runs before any server boots, so an invalid value exits cleanly without leaving a listening socket behind.
+
+## render
+
+> A clear video request authorizes a new, versioned local render. Preview is available when useful, not a mandatory approval checkpoint. Ask only for unresolved inputs, material choices or permission to overwrite an existing export; check the result once through `motion_check`.
+
+```bash
+hf render                                # standard MP4 from cwd
+hf render ./my-video --output ./out.mp4  # render from outside the project dir
+hf render --output final.mp4             # named output (no timestamp)
+hf render -c compositions/intro.html -o intro.mp4  # render a specific sub-composition file
+hf render --quality draft                # fast iteration
+hf render --quality looks                # first real encode (default)
+hf render --fps 60 --quality delivery    # final delivery
+hf render --format webm                  # transparent WebM
+hf render --docker                       # byte-identical
+```
+
+> Default `--output` is `renders/<project-name>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>` — timestamped per render so successive runs don't clobber each other. Pass `--output` to get a stable name.
+
+| Flag                                 | Options                                                                                            | Default                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dir` (positional)                   | path                                                                                               | cwd                            | Project directory. Omit to use current working directory.                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--composition`, `-c`                | path to composition file                                                                           | `index.html`                   | Render a specific composition file (e.g. `compositions/intro.html`) instead of the project's `index.html`.                                                                                                                                                                                                                                                                                                                                    |
+| `--output`, `-o`                     | path                                                                                               | `renders/<project>_<ts>.<ext>` | Output path. Default is timestamped (`<project-name>_YYYY-MM-DD_HH-MM-SS.<ext>`).                                                                                                                                                                                                                                                                                                                                                             |
+| `--fps`                              | 24, 30, 60                                                                                         | 30                             | 60fps doubles render time                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--quality`                          | draft, looks, delivery, standard, high                                                             | looks                          | `looks` is CRF 16 on the standard preset. `delivery` is `high`. draft for iterating                                                                                                                                                                                                                                                                                                                                                           |
+| `--format`                           | mp4, webm, mov, gif, png-sequence, hls                                                             | mp4                            | WebM/MOV render with transparency; gif for inline autoplay in GitHub PRs/READMEs/docs (two-pass palette encode, fps capped at 30 — prefer `--fps 15` — no audio, 1-bit transparency only, HDR falls back to SDR); png-sequence writes RGBA frames to a directory (AE/Nuke/Fusion ingest); hls writes an HLS VOD directory (master.m3u8 + video/audio playlists + MPEG-TS segments), SDR only, rejects `--gpu`, unavailable on lambda/cloudrun |
+| `--gif-loop`                         | 0-65535                                                                                            | 0                              | GIF loop count; `0` loops forever. Only with `--format gif`.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--hls-segment-seconds`              | 1-60                                                                                               | 4                              | HLS target segment length in whole seconds; also locks the encoder GOP so every segment starts on a keyframe. Only with `--format hls`.                                                                                                                                                                                                                                                                                                       |
+| `--resolution`                       | landscape, portrait, landscape-4k, portrait-4k, square, square-4k (+ aliases `1080p`, `4k`, `uhd`) | —                              | Supersample via Chrome `deviceScaleFactor`. Aspect ratio must match composition; scale must be an integer. Not with `--hdr`.                                                                                                                                                                                                                                                                                                                  |
+| `--crf`                              | 0-51                                                                                               | —                              | Encoder CRF (lower = higher quality). Mutually exclusive with `--video-bitrate`.                                                                                                                                                                                                                                                                                                                                                              |
+| `--video-bitrate`                    | e.g. `10M`, `5000k`                                                                                | —                              | Target bitrate. Mutually exclusive with `--crf`.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--hdr`                              | flag                                                                                               | off                            | Force HDR output even with SDR sources. MP4 only.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `--sdr`                              | flag                                                                                               | off                            | Force SDR even with HDR sources.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--workers`                          | number or `auto`                                                                                   | auto                           | Each worker spawns Chrome (~256 MB)                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `--docker`                           | flag                                                                                               | off                            | Reproducible output across hosts                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--gpu`                              | flag                                                                                               | off                            | GPU-accelerated FFmpeg encoding (NVENC / VideoToolbox / VAAPI / QSV)                                                                                                                                                                                                                                                                                                                                                                          |
+| `--browser-gpu` / `--no-browser-gpu` | flag                                                                                               | auto (local), off (docker)     | Host GPU for Chrome/WebGL capture                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `--browser-timeout`                  | seconds (0.001–86400)                                                                              | 60                             | Puppeteer page-navigation timeout for the entry HTML. Raise when heavy compositions (many videos / fonts / remote assets) can't reach `domcontentloaded` within the 60s default.                                                                                                                                                                                                                                                              |
+| `--quiet`                            | flag                                                                                               | off                            | Suppress verbose output                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--strict`                           | flag                                                                                               | off                            | Fail on lint errors                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `--strict-all`                       | flag                                                                                               | off                            | Fail on lint errors AND warnings                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--variables`                        | JSON object                                                                                        | —                              | Override values declared in `data-composition-variables`                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--variables-file`                   | path                                                                                               | —                              | JSON file with variable values (alternative to `--variables`)                                                                                                                                                                                                                                                                                                                                                                                 |
+| `--strict-variables`                 | flag                                                                                               | off                            | Fail render on undeclared keys or type mismatches in `--variables`                                                                                                                                                                                                                                                                                                                                                                            |
+
+**Quality guidance:** `draft` while iterating, `looks` (the default) for the first real encode, `delivery` for final delivery. `standard` and `high` still work.
+
+**Read the summary's second line.** After the output path and size, `render` prints the capture path, GPU mode, and per-stage timings, e.g. `beginframe capture · software gpu · compile 0.7s · setup 1.1s · capture 8.1s · encode 5.8s`. `capture` is the frame loop and `setup` is calibration plus session init; the capture path reads `a|b` when parallel workers diverged, and `encode (during capture)` means the streaming encoder overlapped the loop, so do not add it to the wall time. Local GPU `auto` (the default) requests BeginFrame. If the line still says `screenshot capture` with `software gpu` on Linux, a hint under it says BeginFrame did not run (needs chrome-headless-shell, no `--resolution` upscale). It only appears when the GPU was auto-probed, never under `--docker` or `--no-browser-gpu`, where software GL is the point. Heavy compositions can stall on software GL. Do not reach for `--debug` just to learn which path ran.
+
+**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with `data-variable-values`. See the `hyperframes-core` skill for the full pattern.
+
+## GG delivery boundary
+
+Keep renders and diagnostics local. Feedback submission, issue filing, publishing
+and cloud rendering are not automatic completion steps. They require explicit
+user authorization; do not send source files, private assets or logs upstream.
+Use GG's `reveal.mjs` to select the delivered local file.

package/assets/motion/references/runtime/sub-compositions.md

@@ -0,0 +1,176 @@
+# 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. lint: subcomposition_root_styled_by_class. 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>
+        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.
+
+### 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`
+
+`lint` still errors (`subcomposition_root_styled_by_class`) if a sub-composition styles the host root's own class. Style the root with `#root`.
+
+## 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.

package/assets/motion/references/runtime/tracks-and-clips.md

@@ -0,0 +1,87 @@
+# Tracks and Clips
+
+Clips are timed elements inside a composition. Tracks are a Studio display concept: the render never reads them.
+
+## What is a Clip
+
+A clip is any DOM element with `data-start` and, where required, `data-duration`. `data-track-index` is optional. 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>`. `data-duration` is optional and defaults to 3 seconds; write it only for another length.
+
+Add `class="clip"` to authored visual clips. The runtime does not read it, but the scaffold's shared `.clip { position: absolute; inset: 0 }` rule is what gives a scene its full-frame box, Studio treats it as an edit hint, and `lint` warns without it.
+
+## Tracks Are a Display Lane
+
+`data-track-index` is the row a clip occupies in Studio's timeline. It is **not** read by the render, and it constrains nothing:
+
+- **Two clips on the same track may overlap in time.** Nothing rejects it and the render is well defined: both are visible, painted in CSS order.
+- **Visual layering (front/back)** is controlled by CSS `z-index`, not by track index.
+- **Omitting it is fine.** The parser defaults it, and Studio then lays out one lane per clip.
+
+A clip on track `5` is not "above" a clip on track `1`. Use CSS for layering, `data-start`/`data-duration` for sequencing.
+
+The one place the value carries meaning: two `<audio>` elements that share a track index **and** overlap in time raise a `lint` warning (`duplicate_audio_track`), which is a useful nudge that you are about to double up a bed.
+
+## Picking a Track Index
+
+Purely a readability choice for whoever opens the file in Studio. Common patterns, owned by `/hyperframes-studio` (one caption track, one element kind per track).
+
+When adding a clip to an existing composition, set its `data-start`/`data-duration` against the clips around it. You do not need to hunt for a free lane, and you never need to renumber tracks after a retime.
+
+## 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.
+
+## Cut one source into multiple ranges
+
+For a hard cut, trim, splice, or reorder, duplicate the same video source into
+multiple clip elements. Each copy selects its source range with
+`data-media-start` plus `data-duration`, and places that range on the authored
+timeline with `data-start`. Change the source offsets and placement order; do
+not try to keyframe source cutting.
+
+Separately authored audio gives each audio copy the identical source range and
+timing as its matching video clip (`data-media-start`, `data-duration`, and
+`data-start`). Video stays muted; the separate audio elements carry sound.
+
+## 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, and three ways this fails **silently**. Nothing in `lint` checks any of them, so read them before you use a reference:
+
+- **Spaces around the operator are required.** `data-start="intro - 0.5"` means "0.5s before `intro` ends". `data-start="intro-0.5"` (no spaces) is parsed as a reference to an element whose id is literally `intro-0.5`; that element does not exist, so the clip silently starts at 0.
+- **An unresolved reference resolves to 0**, it does not error. A typo'd id, or a target that is not in the document, puts the clip at the start of the composition.
+- **If the target has no resolvable duration, the reference lands on the target's START, not its end.** So `data-start="hero"` where `hero` has no `data-duration` and no known media length silently means "same time as `hero`" rather than "after `hero`".
+- **A cycle resolves to 0** rather than erroring. `A → B → A` puts one of them at 0.
+- Lookup is **document-wide** (`getElementById`, then `[data-composition-id]`). A reference can therefore reach a target in another composition on the assembled page. Keep referenced ids unique and keep the reference and its target in the same file, or the result depends on assembly order.
+- A value that parses as a number is always absolute seconds. Otherwise the resolver expects `<id>`, `<id> + <number>`, or `<id> - <number>`.
+- References can chain (`A → B → C`). Keep chains under 3-4 levels for readability.
+- Negative offsets create overlap, which is allowed. Overlapping clips do **not** need different tracks.
+
+Because every failure mode above is a silent 0, snapshot a reference-timed composition and check the clip actually starts where you meant.

package/assets/motion/references/runtime/variables-and-media.md

@@ -0,0 +1,107 @@
+# 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>
+```
+
+**Prefer declarative bindings — no script needed** for direct substitution:
+
+```html
+<img class="clip" data-start="0" data-duration="5" data-var-src="heroImage" src="fallback.jpg" />
+<h1 class="clip" data-start="0" data-duration="5" data-var-text="title">Fallback</h1>
+<style>
+  .card {
+    color: var(--accent);
+  }
+</style>
+```
+
+- `data-var-src="id"` substitutes the element's `src` (URL string or image `{url}`); the authored `src` is the fallback.
+- `data-var-text="id"` substitutes the element's own text; element children (nested clips, animated spans) are preserved.
+- Every scalar variable is applied automatically as a `--{id}` CSS custom property on the composition root, so `var(--id)` CSS responds to overrides — no `setProperty` boilerplate.
+- Bindings resolve identically in preview and render, and per-instance for sub-compositions.
+- Caveat: media with audio should keep a real fallback `src` — render audio extraction reads the authored attribute (lint: `media_variable_src_no_fallback`).
+
+For logic beyond direct substitution (loops, conditionals, derived values), read values once during initialization:
+
+```js
+const { title, accent } = window.__hyperframes.getVariables();
+document.getElementById("title").textContent = title;
+```
+
+### 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 shader adjustments, finishing details, blur/pixelate effects, and custom LUTs.
+
+### 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
+
+**`<video>`/`<audio>` work at any nesting depth, including inside a sub-composition `<template>` or a wrapper `<div>`.** The runtime discovers media with a flat `document.querySelectorAll("video, audio")`, resolves each element's host composition via `element.closest("[data-composition-id]")`, and rebases its local `data-start` by the accumulated absolute start of every ancestor composition. A host at `2` with child media at `2` therefore starts that media at root time `4`, consistently in preview, snapshot, extraction, and render. Legacy projects that deliberately authored a media start in root time must mark that element with `data-hf-media-start-basis="global"`; never infer the basis from overlapping numbers. New compositions should always use scene-local `data-start`. If a panel renders blank after a render, capture a per-frame `snapshot` and treat it as render-blocking.
+
+The one real constraint is about **timelines, not media placement**: a sub-composition timeline **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 if a media element lives at the host root, **its per-scene motion (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`). Keeping the media inside the scene sub-comp instead lets that sub-comp's own timeline animate it with scene-local time. 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** drive host-root media from a sub-comp timeline: a sub-comp timeline cannot reach elements outside its subtree, so it has no effect. Drive host-root media from the main timeline at global time (or keep the media inside the sub-comp whose timeline animates it).
+- **Do not** animate timed media element dimensions; animate a non-timed wrapper instead.
+- **Do not** nest video inside a timed wrapper. `lint` rejects a `<video data-start>` whose ancestor also carries `data-start` (`video_nested_in_timed_element`, error), and the failure is real: the frame extractor resolves the video's start from its own `data-start` without the wrapper's offset, while visibility uses the wrapper's window. The clip then shows the wrong source frames and disappears partway through its slot. Put the timing on the wrapper **or** on the media element, never both.
+- **Sub-compositions are exempt and work.** A `<video>`/`<audio>` inside a sub-composition renders identically to one at the host root, because a composition host propagates its offset. Only plain timed wrappers (a `<section data-start>` around a `<video data-start>`) break.
+- **Never** add `crossorigin` to `<video>`/`<audio>`. `lint` rejects it unconditionally (`media_crossorigin_breaks_preview`, error) because a media host without `Access-Control-Allow-Origin` then fails silently in preview while renders still work, hiding the bug. There is no suppression, so this holds even for the canvas/WebGL/WebAudio readback case.
+- **Every `<audio>` needs an `id`.** The mixer selects `audio[id][src]`, so an id-less `<audio>` is never mixed and the render is **silent**. `lint` catches it as `media_missing_id`.
+- 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 and ducking, use the `data-automation` volume lane; the exact form is in `creator-editing-recipes.md`. `data-volume` is the static baseline. A timeline `volume` tween is ignored when a lane is present.
+
+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.
+
+Input codecs: render decodes video via FFmpeg (frames are pre-extracted and injected), so HEVC/H.265 assets (8/10-bit) render correctly everywhere; live preview auto-proxies any browser-hostile asset (transcodes and caches an H.264 copy on first use, opt out with `--no-proxy` or `media.autoProxy: false`), and `lint` emits an info-level `hevc_preview_codec` note naming affected assets.

package/assets/motion/references/signal-study.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>GG study — attention follows a changing path</title>
+<style>
+  html, body { margin: 0; background: #142033; overflow: hidden; }
+  svg { display: block; width: 960px; height: 540px; }
+</style>
+<svg viewBox="0 0 960 540" role="img" aria-label="A signal traces a path; the framing follows it before revealing the complete route">
+  <g id="world">
+    <path id="route" d="M100 330 C260 330 230 150 430 160 S630 410 840 280 S1050 70 1250 200 S1450 450 1650 270" fill="none" stroke="#95e0c0" stroke-width="12" stroke-linecap="round"/>
+    <circle id="head" r="22" fill="#f7e7ae"/>
+    <circle id="halo" r="38" fill="none" stroke="#f7e7ae" stroke-width="2"/>
+  </g>
+</svg>
+<script>
+// GG-authored reduction of the local Follow the Signal study (1.5–6.3s).
+// Transfer the coupled path-progress/framing mechanism, not palette or camera rules.
+const route = document.getElementById('route');
+const length = route.getTotalLength();
+route.style.strokeDasharray = length;
+const smooth = (p) => p * p * (3 - 2 * p);
+window.seekStudy = (seconds) => {
+  const progress = Math.max(0, Math.min(1, seconds / 4));
+  const point = route.getPointAtLength(progress * length);
+  route.style.strokeDashoffset = (1 - progress) * length;
+  for (const id of ['head', 'halo']) {
+    document.getElementById(id).setAttribute('cx', point.x);
+    document.getElementById(id).setAttribute('cy', point.y);
+  }
+  const resolve = smooth(Math.max(0, (progress - .65) / .35));
+  const zoom = 1.15 - .64 * resolve;
+  const x = (480 - point.x * zoom) * (1 - resolve) + 40 * resolve;
+  const y = (270 - point.y * zoom) * (1 - resolve) + 125 * resolve;
+  document.getElementById('world').setAttribute('transform', `translate(${x} ${y}) scale(${zoom})`);
+};
+window.seekStudy(0);
+</script>
+</html>