dsh-hyperframes 0.1.1 → 0.3.0

package/skills/hyperframes-core/references/subagent-dispatch.md

@@ -0,0 +1,35 @@
+# 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 role file** (a builder-assembled payload like `.hyperframes/frame-packets/_role.md`, or a workflow's `sub-agents/<role>.md`) 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.
+
+- When the harness queues excess children internally, 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.
+
+## Harness mapping
+
+Use the current harness's native delegation and waiting tools when they are available. The workflow contract stays the same:
+
+- **DISPATCH** sends the complete role file and dispatch context to one worker.
+- **Parallel fan-out** starts independent workers concurrently up to the harness limit.
+- **WAIT** verifies the expected artifacts on disk, not only a completion notification.
+- **Re-dispatch** starts a fresh worker with the same context plus the gate failure.
+
+When native delegation is unavailable, use the existing fallback ladder: launch headless CLI workers that share the project filesystem, then fall back to inline serial execution.
+
+On Codex, native delegation requires the user's explicit permission. Fold a one-line request into the workflow's first existing user pause before dispatch; a standing grant in `AGENTS.md` or the kickoff prompt also counts. Without it, use the fallback ladder rather than silently skipping work.
+
+## Vocabulary mapping
+
+- A request to work "in the background" means dispatch concurrently when the harness supports it.
+- Load a named skill through the harness's skill mechanism, or read `<skills-root>/<skill>/SKILL.md` directly.
+- Map generic read, write, edit, and shell verbs to the current harness's equivalent tools.

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

@@ -0,0 +1,123 @@
+# 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 check
+
+# 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 check`, then the render proof above.

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

@@ -0,0 +1,91 @@
+# 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>`. Always require `data-duration`.
+
+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:
+
+- **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.
+
+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/skills/hyperframes-core/references/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 (`packages/core/src/runtime/{media,startResolver}.ts`). So a scene-specific clip can live in its scene's sub-comp with scene-local `data-start`, and it seeks/decodes correctly. If a panel renders blank after a render, that is a real bug: 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/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. A tween's values REPLACE that baseline rather than scaling it, so on a clip whose gain is not `1` you scale the tween's targets instead (`{ volume: 1.95 }`, not `{ volume: 1 }`) — `lint` warns with `audio_volume_tween_overrides_gain` when the two disagree.
+
+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/skills/hyperframes-core/scripts/lib/frame-packets-core.mjs

@@ -0,0 +1,212 @@
+// Shared frame-packet builder — the script half of the frame-worker core/delta split.
+//
+// Each narrative workflow ships a thin `scripts/frame-packets.mjs` wrapper that pins
+// its own paths (animation skill, role delta, design-truth resolution, extra packet
+// sections) and delegates everything else here, exactly as the markdown half already
+// does with `references/frame-worker-core.md` + each workflow's delta. One owner for
+// the packet-building logic; the wrappers own only what genuinely differs per workflow.
+//
+// Packet (<frame_id>.md) = project inputs + the frame's exact `## Frame N` block
+// + the blueprint body + every cited rule recipe, inlined — so a worker never opens
+// the shared STORYBOARD.md or any skill document. Cited motions are found
+// mechanically: the explicit `- rules:` field when present, plus every valid rule id
+// (a filename under the animation skill's rules/) mentioned in the block.
+//
+// _role.md = frame-worker-core.md + the workflow's sub-agents/frame-worker.md,
+// concatenated verbatim — the complete worker role, assembled from the two source
+// documents so nothing is hand-maintained twice.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function field(block, name) {
+  const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
+  return match?.[1]?.trim() ?? null;
+}
+
+export function splitFrames(storyboard) {
+  const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
+  return matches.map((match, index) => {
+    const start = match.index;
+    const end = matches[index + 1]?.index ?? storyboard.length;
+    return {
+      heading: match[1].trim(),
+      block: storyboard.slice(start, end).trim(),
+    };
+  });
+}
+
+export function frameId(frame) {
+  const src = field(frame.block, "src");
+  if (!src) throw new Error(`${frame.heading}: missing src`);
+  return basename(src).replace(/\.html?$/i, "");
+}
+
+export function selectedFile(path, heading) {
+  if (!path || !existsSync(path)) return "";
+  return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
+}
+
+function escapeRegExp(id) {
+  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function knownRuleIds(animationDir) {
+  const rulesDir = join(animationDir, "rules");
+  if (!existsSync(rulesDir)) {
+    console.warn(
+      `frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
+    );
+    return [];
+  }
+  return readdirSync(rulesDir)
+    .filter((name) => name.endsWith(".md"))
+    .map((name) => name.replace(/\.md$/, ""));
+}
+
+export function citedRules(block, ruleIds) {
+  const explicit = (field(block, "rules") ?? "")
+    .split(/[,\s]+/)
+    .map((rule) => rule.trim())
+    .filter(Boolean);
+  const mentioned = ruleIds.filter((id) =>
+    new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
+  );
+  return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
+}
+
+// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
+// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
+// the filename. Parse the field into the id it names (or null for `compose`), so
+// no caller ever resolves a raw field value against the blueprints directory.
+export function blueprintId(block) {
+  const raw = field(block, "blueprint");
+  if (!raw) return null;
+  const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
+  return id && id.toLowerCase() !== "compose" ? id : null;
+}
+
+export function resourceSections(block, { animationDir, ruleIds, frameId }) {
+  let sections = "";
+  const blueprint = blueprintId(block);
+  if (blueprint) {
+    const blueprintsDir = join(animationDir, "blueprints");
+    const path = join(blueprintsDir, `${blueprint}.md`);
+    // A blueprint that resolved to nothing used to inline an empty string, so the
+    // packet shipped without the one document the frame was designed against and
+    // the run still reported success. Name it instead — but only when the library
+    // is actually there to be named against. The animation skill installs on
+    // demand, so an absent blueprints/ is a missing install, not a bad id, and it
+    // degrades with a warning exactly like an absent rules/ (see knownRuleIds).
+    if (!existsSync(blueprintsDir)) {
+      console.warn(
+        `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
+      );
+    } else if (!existsSync(path)) {
+      throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
+    } else {
+      sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
+    }
+  }
+  for (const rule of citedRules(block, ruleIds)) {
+    sections += selectedFile(
+      join(animationDir, "rules", `${rule}.md`),
+      `Selected motion rule: ${rule}`,
+    );
+  }
+  return sections;
+}
+
+export function buildRolePayload({ corePath, deltaPath, outDir }) {
+  const core = readFileSync(corePath, "utf8").trim();
+  const delta = readFileSync(deltaPath, "utf8").trim();
+  const role = `${core}\n\n---\n\n${delta}\n`;
+  mkdirSync(outDir, { recursive: true });
+  const path = join(outDir, "_role.md");
+  writeFileSync(path, role);
+  return { path, bytes: Buffer.byteLength(role) };
+}
+
+export function buildFramePackets({
+  projectDir,
+  storyboardPath = join(projectDir, "STORYBOARD.md"),
+  outDir = join(projectDir, ".hyperframes", "frame-packets"),
+  maxPacketBytes = 48_000,
+  animationDir,
+  corePath,
+  deltaPath,
+  // Per-workflow hooks (all optional):
+  // designTruthLine(projectDir) -> the packet's design-truth input line
+  // validateFrame(frame, id)   -> throw to reject a frame before packing
+  // extraSections(block)       -> extra packet sections appended after the rule recipes
+  designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
+  validateFrame,
+  extraSections,
+}) {
+  const storyboard = readFileSync(storyboardPath, "utf8");
+  const frames = splitFrames(storyboard);
+  if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
+  const ruleIds = knownRuleIds(animationDir);
+
+  const packets = frames.map((frame) => {
+    const id = frameId(frame);
+    if (validateFrame) validateFrame(frame, id);
+    const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
+    const bytes = Buffer.byteLength(packet);
+    if (bytes > maxPacketBytes) {
+      throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
+    }
+    return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
+  });
+
+  mkdirSync(outDir, { recursive: true });
+  for (const { path, packet } of packets) writeFileSync(path, packet);
+  buildRolePayload({ corePath, deltaPath, outDir });
+  return packets.map(({ packet: _packet, ...result }) => result);
+}
+
+export function flag(argv, name, fallback) {
+  const index = argv.indexOf(`--${name}`);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+}
+
+// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
+// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
+// a raw compare silently skips main() when invoked through any symlinked path.
+export function isMainModule(importMetaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+  } catch {
+    return false;
+  }
+}
+
+export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
+  const argv = process.argv.slice(2);
+  const projectDir = resolve(flag(argv, "project", "."));
+  const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
+  try {
+    const packets = build({
+      projectDir,
+      storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
+      outDir,
+    });
+    const role = buildRole({ outDir });
+    console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
+    for (const packet of packets)
+      console.log(`  ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
+    console.log(`  worker role: ${role.bytes} bytes → ${role.path}`);
+  } catch (error) {
+    console.error(`✗ frame packets: ${error.message}`);
+    process.exit(1);
+  }
+}

package/skills/hyperframes-creative/SKILL.md

@@ -0,0 +1,71 @@
+---
+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 scale, depth, and foreground detail. It explains how to avoid empty web-page layouts without imposing a universal element count.
+>
+> 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`                     |
+| Story doctrine — hook language, value-before-evidence, storyboard-as-proposal, source-traceable visuals | `references/story-spine.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.