npm - takomi - Versions diffs - 2.1.41 → 2.1.42 - Mend

takomi 2.1.41 → 2.1.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (597) hide show

package/assets/.agent/skills/hyperframes-core/references/sub-compositions.md ADDED Viewed

@@ -0,0 +1,237 @@
+# Sub-Compositions
+A sub-composition is a separate HTML file embedded in a host composition. HyperFrames loads it, seeks it independently, and composites the result into the host at `data-start`.
+## Host Wiring
+In the host composition, the sub-composition appears as a clip with `data-composition-src`:
+```html
+<div
+  id="chart"
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-start="2"
+  data-duration="8"
+  data-track-index="2"
+  data-width="1920"
+  data-height="1080"
+></div>
+```
+- `data-composition-id` on the host must match the internal `data-composition-id` of the file at `data-composition-src`.
+- The host clip needs its own `data-start`, `data-duration`, `data-track-index`, `data-width`, `data-height`.
+## Sub-Composition File Structure
+### Mental model — what the runtime actually does
+When a host loads a sub-composition via `data-composition-src`, the runtime:
+1. `fetch`es the HTML file.
+2. Parses it with `DOMParser`.
+3. **Finds the `<template>` element and clones ONLY its contents into the host slot.**
+4. Everything **outside** the `<template>` (including the entire `<head>`) is **discarded**.
+So `<template>` is not just a wrapper — it is the **transport container**. If a node needs to exist in the live render, it must be inside `<template>`. Full stop.
+### File shape
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <!-- head is metadata for the source file only; the runtime ignores it -->
+  </head>
+  <body>
+    <template>
+      <!-- EVERYTHING the runtime needs goes here: styles, markup, scripts -->
+      <style>
+        /* Root: style by #root, never a class. (At render the CSS is scoped to
+           data-composition-id, so a class on the root stops matching — see Pitfall 3.) */
+        #root {
+          position: absolute;
+          inset: 0;
+          color: #fff;
+        }
+        /* .label, #bar, … — descendants, plain selectors */
+      </style>
+      <div id="root" data-composition-id="data-chart" data-width="1920" data-height="1080">
+        <!-- sub-composition markup -->
+      </div>
+      <script>
+        window.__timelines = window.__timelines || {};
+        const tl = gsap.timeline({ paused: true });
+        // ... build timeline ...
+        window.__timelines["data-chart"] = tl;
+      </script>
+    </template>
+  </body>
+</html>
+```
+Contrast with **standalone** compositions, which put the root directly in `<body>` with no `<template>` wrapper.
+## Common pitfalls that pass static checks but break at render
+`lint`, `validate`, and `inspect` evaluate each file in isolation. These two failures live in the **cross-file mount contract** and cannot be caught until the runtime actually tries to mount the sub-composition. Watch for them at author time and verify with the pre-render checklist below.
+### Pitfall 1 — `<style>` in `<head>` instead of inside `<template>`
+```html
+<!-- ❌ WRONG — looks normal, ships catastrophically broken -->
+<head>
+  <style>
+    #root { font-size: 88px; ... }
+  </style>
+</head>
+<body>
+  <template>
+    <div id="root" data-composition-id="data-chart" ...>...</div>
+  </template>
+</body>
+<!-- ✅ RIGHT — styles are inside the template, root styled by #root (see Pitfall 3) -->
+<head></head>
+<body>
+  <template>
+    <style>
+      #root { font-size: 88px; ... }
+    </style>
+    <div id="root" data-composition-id="data-chart" ...>...</div>
+  </template>
+</body>
+```
+**Why this happens:** standard HTML conventions tell you to put `<style>` in `<head>`. In a standalone HTML file that's correct. In a HyperFrames sub-composition it is **not** — the runtime only clones `<template>` contents, so `<head><style>` is dropped on the floor.
+**Symptom:** the composition lints / validates / inspects clean, the render completes, but every text element shows up as tiny unstyled default text in the top-left and SVGs blow up to canvas-size because none of the CSS reached the live DOM. The same trap applies to `<script>` blocks, `<link rel="stylesheet">`, custom-element registrations — anything that needs to execute or apply in the render must be inside `<template>`.
+### Pitfall 2 — Host `data-composition-id` ≠ inner template `data-composition-id`
+```html
+<!-- ❌ WRONG — host renames the slot; runtime can't find the timeline -->
+<!-- host file (e.g. index.html) -->
+<div data-composition-id="chart-mount" data-composition-src="compositions/chart.html" ...></div>
+<!-- chart.html -->
+<template>
+  <div data-composition-id="data-chart" ...>...</div>
+  <script>
+    window.__timelines["data-chart"] = tl;
+  </script>
+</template>
+<!-- ✅ RIGHT — both ids match, and the timeline key matches them too -->
+<div data-composition-id="data-chart" data-composition-src="compositions/chart.html" ...></div>
+<!-- chart.html template root: data-composition-id="data-chart" -->
+<!-- timeline: window.__timelines["data-chart"] = tl; -->
+```
+**Why this happens:** it feels natural to give the host slot a different name like `chart-mount` ("the mount point") vs `data-chart` ("the actual chart"). HyperFrames does not work that way — **the host's `data-composition-id` is the lookup key the framework uses to find the registered timeline**. Lint passes because each file's ids are individually valid; the cross-file mismatch only blows up at render.
+**Symptom:** the render logs `Sub-composition timelines not registered after 45000ms: <host-id>` for every mismatched slot, waits 45s per scene, then captures static initial-state frames (so the video is full-length but no animation plays).
+### Pitfall 3 — Styling the root by a class instead of `#root`
+```html
+<!-- ❌ WRONG — class on the root, stylesheet keyed off it -->
+<template>
+  <style>
+    .frame {
+      position: absolute;
+      inset: 0;
+      background: #faf9f5;
+    }
+    .frame .title {
+      font-size: 120px;
+    }
+  </style>
+  <div id="root" class="frame" data-composition-id="03-scene" ...>
+    <div class="title">…</div>
+  </div>
+</template>
+<!-- ✅ RIGHT — root styled by #root, descendants by plain selectors -->
+<template>
+  <style>
+    #root {
+      position: absolute;
+      inset: 0;
+      background: #faf9f5;
+    }
+    .title {
+      font-size: 120px;
+    }
+  </style>
+  <div id="root" data-composition-id="03-scene" ...>
+    <div class="title">…</div>
+  </div>
+</template>
+```
+**Why this happens:** when sub-compositions are inlined into one composited render, the compiler **scopes each file's CSS to its own `data-composition-id`** so scenes can't leak styles into each other — every rule `S` becomes `[data-composition-id="<id>"] S` (a _descendant_ selector). A rule whose leftmost selector is the **root's own class** (`.frame`) therefore becomes `[data-composition-id="<id>"] .frame`, which cannot match the root (the root _is_ the scoped element, not a descendant of it), so **every `.frame…` rule silently drops**. `#root` is special-cased by the scoper and keeps matching the root; plain descendant selectors (`.title`) match normally. The per-scene class namespace is also just redundant — the `data-composition-id` scope already isolates each scene's styles.
+**Symptom:** _identical_ to Pitfall 1 — tiny unstyled text in the top-left, images at natural size, inline styles (e.g. a card background) the only thing surviving. The trap: this passes `lint`/`validate`/`inspect` (they evaluate the file in isolation, unscoped) **and looks perfect in `preview`** (Studio mounts each scene in its own iframe, also unscoped) — it only breaks in the composited MP4 render. Lint rule `subcomposition_root_styled_by_class` flags it; the registry blocks (e.g. `apple-money-count`) model the `#root` pattern.
+### Verification checklist before render
+```bash
+# For every sub-composition file in compositions/:
+#   1) <style> + <script> + main markup all live INSIDE <template>
+grep -n "<style\|<script\|<template" compositions/<scene>.html
+#      → first <style>/<script>/<div data-composition-id> should be AFTER <template>, before </template>
+#   2) host data-composition-id == internal data-composition-id == window.__timelines key
+grep "data-composition-id" index.html
+grep "data-composition-id\|__timelines\[" compositions/<scene>.html
+#      → all three strings must match exactly per scene
+#   3) the root is styled by #root, not by a class on the data-composition-id element
+grep -n 'data-composition-id=' compositions/<scene>.html
+#      → that element should NOT also carry a class="…" that the <style> keys off
+#        (e.g. `.frame { … }`); scoping drops it. Style the root via #root. See Pitfall 3.
+```
+For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeball), see the **Visual smoke test** step in `hyperframes-cli`'s Minimum Completion Gate — that is the only gate that catches these three pitfalls.
+## What HyperFrames Does With the Sub-Composition
+- Loads the file and registers its timeline under its internal `data-composition-id`.
+- Seeks the sub-composition's timeline independently from the host's playhead.
+- Plays the sub-composition's content from `data-start` of the host clip, for `data-duration` seconds.
+**Do not** manually `master.add(child)` a sub-composition timeline into the host timeline. HyperFrames already drives them independently — nesting them in GSAP causes double-seeks.
+### The host clip's `data-duration` is the slot's visible window
+`data-duration` on the host clip defines **how long the slot is visible**, and it takes precedence over the sub-composition's internal GSAP timeline length. Two consequences follow:
+- **Internal timeline shorter than the slot → the slot holds.** If the sub-composition's GSAP timeline finishes before `data-duration` elapses, the slot keeps showing its final frame for the rest of the window. You do **not** need to pad the timeline with empty tweens.
+- **`data-duration` shorter than the host composition → the slot ends (and goes blank) when its own `data-duration` elapses.** This is intended: the clip is a fixed-length window on the timeline, not "fill until the composition ends." To keep a sub-composition visible for the whole composition, set its `data-duration` to span the host window (or add another clip to cover the remaining time). Leaving a single full-bleed sub-composition shorter than the composition is almost always a mistake — the linter flags it as `subcomposition_blanks_before_host`.
+## Animations Inside Sub-Compositions
+Prefer `gsap.fromTo()` over `gsap.from()` for entrance tweens. The host re-seeks the sub-composition every time its clip becomes visible; `gsap.from()` records the starting state at registration and can desync on seek-back, while `gsap.fromTo()` declares both endpoints explicitly and replays cleanly.
+## Per-Instance Variables
+If the sub-composition declares variables on its `<html>` element (`data-composition-variables`), the host can override values per instance:
+```html
+<div
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-variable-values='{"title":"Q4 Revenue","accent":"#66d9ef"}'
+  data-start="2"
+  data-duration="8"
+  data-track-index="2"
+  data-width="1920"
+  data-height="1080"
+></div>
+```
+The host can render the same sub-composition multiple times with different `data-variable-values` to produce per-instance variations. See `variables-and-media.md` for variable declaration syntax.

package/assets/.agent/skills/hyperframes-core/references/subagent-dispatch.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Subagent dispatch — harness adapter
+The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video` / `motion-graphics` / `general-video`) describe subagent dispatch in harness-neutral verbs. This file maps those verbs to the primitives of whatever agent harness you are running on. Read it once per run, before the first dispatch; everything else in the workflows (dispatch packets, file artifacts, exit-code gates, Resume tables) is harness-independent and needs no translation.
+## The contract (identical on every harness)
+- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named `agents/<role>.md` file** followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
+- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
+- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
+## Concurrency cap → batching rule (cap never changes scope)
+A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
+- Harness queues excess children internally (Claude Code; Hermes `delegate_task` beyond `max_concurrent_children`) → submit **all N at once** and let the queue drain.
+- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
+## Primitive map
+| Verb in the workflows            | Claude Code                                                         | Codex CLI                                                                                   | OpenClaw                                                                               | Hermes Agent                                                                                                   |
+| -------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| DISPATCH                         | `Agent` tool, `subagent_type: "general-purpose"`                    | `spawn_agent` (built-in `worker` role; prompt carries the role file)                        | `sessions_spawn` (role file rides in `task`; child only auto-loads AGENTS.md/TOOLS.md) | `delegate_task` — put role file + context into each task's `context` (child system prompt is not customizable) |
+| parallel fan-out                 | multiple Agent calls in one message, each `run_in_background: true` | multiple `spawn_agent` calls (async by design) or `spawn_agents_on_csv` for uniform batches | repeated `sessions_spawn` (always non-blocking)                                        | one `delegate_task(tasks=[...])` batch call                                                                    |
+| WAIT                             | background-task completion notifications arrive automatically       | `wait_agent` with all child IDs                                                             | `sessions_yield` (never poll session lists)                                            | `delegate_task` returns when all tasks finish (blocking the turn is normal)                                    |
+| default concurrency              | min(16, cores − 2), excess queues                                   | 6 (`agents.max_threads`)                                                                    | 5 active per session, 8 global                                                         | 3 (`delegation.max_concurrent_children`)                                                                       |
+| re-dispatch after a gate failure | new Agent call, same prompt + the error/`## Repair context`         | new `spawn_agent`, same prompt + the error                                                  | new `sessions_spawn`, same `task` + the error                                          | new `delegate_task`, same `context` + the error                                                                |
+Harness-specific notes:
+- **Codex**: children inherit the parent cwd and cannot change it — exactly what these pipelines need (shared `PROJECT_DIR`). Prefer prompt-carried roles over `.codex/agents/*.toml` registration; the workflows already deliver roles in the prompt. **Codex policy-gates spawning on the user explicitly requesting delegation — a skill instruction alone does not satisfy it, and you will be tempted to skip the tool without even trying.** Do not silently degrade: on Codex, if the user has not granted delegation this session, **ask one line** — "OK to run this workflow's workers as parallel subagents?" — **folded into the workflow's first existing user pause** (e.g. the API-key question) so the run pauses only once; at the latest, before the first dispatch step. An affirmative — or a standing grant in the workspace `AGENTS.md` or the kickoff prompt — unlocks native dispatch for the whole session. Only without a grant: prefer ladder rung 1 below (headless `codex exec` children) for the scene fan-out; inline serial is the last resort.
+- **OpenClaw**: result announcement is best-effort (lost on gateway restart) — the artifact-on-disk WAIT rule above is the source of truth, not the announce message.
+- **Hermes**: children get a fresh conversation and only see what you put in `context`, and only the final summary returns — both already match the workflows' design (dispatch packets carry everything; results land on disk). Requires a **local execution backend** (the pipelines exchange data through `PROJECT_DIR` and packet files on the shared filesystem; Docker/remote backends break that).
+- **Any other harness**, or subagents unavailable/disabled — degrade down this ladder:
+  1. Headless CLI children: write each child prompt to a file, start the CLI per worker as a background shell process (redirect stdin from /dev/null, output to a log), then collect artifacts from disk.
+  2. Inline serial execution: do each role yourself, one at a time — read the role file, follow it with the dispatch context as if you were the child, finish, then return to the runbook. Load only one role's resources at a time (a scene's role file + its packet), and still run every per-role self-check before moving on.
+## Vocabulary mapping (older phrasing you may meet in agent prompts)
+- "in the same message" / `run_in_background: true` — Claude Code idioms for "concurrently / as a background child"; apply your harness's equivalent from the table.
+- "Skill `X`" / "loaded with the Skill tool" — load skill X; on harnesses without a skill-loading tool, read `<skills-root>/X/SKILL.md` directly (the skills root is the directory containing this skill family; derive it from `SKILL_DIR` in your dispatch context).
+- `Read` / `Write` / `Edit` / `Bash` — capability names (read file / write file / edit in place / run shell); map to your harness's tools.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

package/assets/.agent/skills/hyperframes-creative/SKILL.md ADDED Viewed

@@ -0,0 +1,70 @@
+---
+name: hyperframes-creative
+description: Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.
+---
+# HyperFrames Creative
+Brand, pacing, style, narration, and composition direction. Use after the technical contract from `hyperframes-core` is in place.
+For motion patterns, scene blueprints, transitions, and CSS marker effects, use `hyperframes-animation` — this skill is intentionally non-animation.
+> **Read these two FIRST for any non-trivial composition — they override web instincts:**
+>
+> - `references/house-style.md` — "interpret the prompt, generate real content," the lazy-default list, and the background/foreground layer recipe. This is what turns a literal restyle into a _concept_.
+> - `references/video-composition.md` — video-medium density, scale, foreground metadata (the "produced, not generated" detailing: data bars, registration marks, monospace readouts, 8-10 elements/scene).
+>
+> Skipping these is the single biggest cause of generic, web-page-looking output. They are not optional rows in the routing table below — for anything beyond a one-line edit, open both before you choose colors or write HTML.
+## Workflow
+1. If a project has a design spec, **read it first** and treat its frontmatter tokens as brand truth (colors, fonts, spacing, tone, constraints). Which file to read (precedence `frame.md` → `design.md` → `DESIGN.md`) and how to parse it (frontmatter = normative, prose = context) are defined once in [`references/design-spec.md`](references/design-spec.md) — resolve and load per that doc.
+2. If no design spec exists and the user asks for visual direction, choose a route:
+   - Ready-made frame-preset (optional) → `frame-presets/` (adopt a `FRAME.md` as `frame.md`; see `references/design-spec.md`)
+   - Named style or mood → `references/visual-styles.md`
+   - Fast defaults → `references/house-style.md`
+   - Interactive selection → `references/design-picker.md`
+3. For multi-scene work, plan beats and rhythm before writing HTML → `references/beat-direction.md`. For scene transitions, jump to `hyperframes-animation/transitions/`.
+4. For motion-heavy work, read `references/motion-principles.md` (high-level guardrails), then go to `hyperframes-animation` for atomic rules.
+## Routing
+| Topic                                                                    | Read                                           |
+| ------------------------------------------------------------------------ | ---------------------------------------------- |
+| Adopt a ready-made frame-preset as `frame.md` (optional)                 | `frame-presets/` · `references/design-spec.md` |
+| Default palettes, motion, typography, lazy defaults to question          | `references/house-style.md`                    |
+| Named style presets, mood-to-style routing                               | `references/visual-styles.md`                  |
+| Palette-specific color tokens                                            | `palettes/*.md`                                |
+| Composition patterns — PiP, text-behind-subject, title card, slide show  | `references/composition-patterns.md`           |
+| Stats / infographic presentation                                         | `references/data-in-motion.md`                 |
+| Structured expansion for open-ended prompts                              | `references/prompt-expansion.md`               |
+| Video-medium density, scale, color, frame composition                    | `references/video-composition.md`              |
+| Per-beat direction, rhythm planning, transition timing                   | `references/beat-direction.md`                 |
+| Post-authoring spec verification (colors, type, corners, spacing, depth) | `references/design-adherence.md`               |
+| High-level motion guardrails and GSAP-quality rules                      | `references/motion-principles.md`              |
+| Font selection, pairings, rendered-video type guardrails                 | `references/typography.md`                     |
+| Script pacing, tone, openings, number pronunciation                      | `references/narration.md`                      |
+| Precomputed audio bands mapped to motion                                 | `references/audio-reactive.md`                 |
+## Scripts
+- `scripts/contrast-report.mjs` — inspect contrast warnings from rendered frames.
+- `scripts/extract-audio-data.py` — pre-extract audio bands for audio-reactive compositions.
+- `scripts/package-loader.mjs` — support script for bundled creative tooling.
+`contrast-report.mjs` resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set `HYPERFRAMES_SKILL_PKG_VERSION=<version>` only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.
+Run from the repo root with explicit paths, for example:
+```bash
+python skills/hyperframes-creative/scripts/extract-audio-data.py <audio-file>
+```
+Animation analysis (`animation-map.mjs`) lives in `hyperframes-animation/scripts/`.
+## Boundaries
+- Do not override `hyperframes-core` technical rules.
+- Do not require a design system for a minimal technical composition.
+- Do not add extra scenes, narration, music, captions, or transitions unless the request calls for them or you first propose the expansion.
+- Keep recipe references task-specific; do not read every reference for simple edits.