dsh-hyperframes 0.3.2 → 0.4.0

package/skills/faceless-explainer/scripts/captions.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
 // captions.mjs — build the captions sub-composition from STORYBOARD + audio_meta.
 //
 // One mode: `build`. Reads STORYBOARD.md (frame order + durations → cumulative
@@ -263,7 +264,7 @@ function buildFromSkin(skin, groups, total, W, H, tokens, die, faces = "", fonts
   out = fillOnce(
     out,
     /var GROUPS = \[\];/,
-    `var GROUPS = ${JSON.stringify(groups)};`,
+    `var GROUPS = ${JSON.stringify(groups).replace(/</g, "\\u003c")};`,
     "`var GROUPS = [];` hole",
   );
   out = fillOnce(out, /var DURATION = 0;/, `var DURATION = ${total};`, "`var DURATION = 0;` hole");
@@ -344,7 +345,8 @@ function brandFontFaces(framePath, hyperframesDir) {
   // underscore/hyphen-named brand font (e.g. TT Norms Pro), which is exactly the
   // font_family_without_font_face bug.
   const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
-  const faces = [];
+  const captured = stageCapturedFonts(hyperframesDir, families);
+  const faces = [...captured.faces];
   const seen = new Set();
   const claimed = new Set(); // each file is claimed by the MOST SPECIFIC family only
   // Match the longest family key first so "TT Norms Pro" can't swallow the files that
@@ -363,12 +365,13 @@ function brandFontFaces(framePath, hyperframesDir) {
         if (!/\.(woff2|woff|ttf|otf)$/i.test(f)) continue;
         if (claimed.has(f)) continue; // a more specific family already took this file
         if (!norm(f.replace(/\.(woff2|woff|ttf|otf)$/i, "")).startsWith(key)) continue;
+        claimed.add(f);
+        if (captured.families.has(fam.toLowerCase())) continue;
         const w = weightOf(f);
         const style = styleOf(f);
         const dedup = `${fam}-${w}-${style}`;
         if (seen.has(dedup)) continue; // one src per face; assets/fonts wins over capture
         seen.add(dedup);
-        claimed.add(f);
         faces.push(
           `      @font-face { font-family: '${fam}'; src: url('${d.rel}/${f}') format('${fmtOf(f)}'); font-weight: ${w}; font-style: ${style}; font-display: block; }`,
         );
@@ -480,7 +483,7 @@ function buildCaptionsHtml(groups, total, W, H) {
   <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
   <script>
     (function () {
-      var GROUPS = ${JSON.stringify(groups)};
+      var GROUPS = ${JSON.stringify(groups).replace(/</g, "\\u003c")};
       var cap = document.getElementById("cap");
       var tl = gsap.timeline({ paused: true });
       GROUPS.forEach(function (g) {

package/skills/faceless-explainer/scripts/frame-packets.mjs

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// Thin wrapper over the shared packet builder in hyperframes-core — this file only
+// Thin wrapper over the shared packet builder in hyperframes — this file only
 // pins the paths that are specific to this workflow skill. The logic (frame
 // splitting, rule citation, packet bounds, `_role.md` assembly) has one owner:
-// ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
+// ../../hyperframes/scripts/lib/frame-packets-core.mjs
 
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
+import * as core from "./lib/frame-packets-core.mjs";
 
 const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const CONFIG = {
   animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
-  corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
+  corePath: resolve(SKILL_DIR, "../hyperframes/references/frame-worker-core.md"),
   deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
 };
 

package/skills/faceless-explainer/scripts/lib/bgm-volume.mjs

@@ -0,0 +1,4 @@
+// Music sits under narration; a silent film brings music forward.
+export const BGM_BED_VOLUME = 0.12;
+export const BGM_SILENT_VOLUME = 0.9;
+export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);

package/skills/faceless-explainer/scripts/lib/captured-fonts.mjs

@@ -0,0 +1,58 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Capture preserves subset and variable-axis descriptors in extracted/page.html.
+// Filenames alone cannot identify a face's character coverage.
+export function stageCapturedFonts(projectDir, families) {
+  const page = join(projectDir, "capture/extracted/page.html");
+  const result = { faces: [], families: new Set(), files: new Set() };
+  if (!existsSync(page)) return result;
+  const wanted = new Set(families.map((family) => family.toLowerCase()));
+  const html = readFileSync(page, "utf8");
+  const copied = new Set();
+  for (const style of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)) {
+    const css = style[1].replace(/\/\*[\s\S]*?\*\//g, "");
+    for (const match of css.matchAll(/@font-face\s*\{([^}]+)\}/gi)) {
+      const body = match[1];
+      const familyValue = /(?:^|;)\s*font-family\s*:\s*([^;]+)/i.exec(body)?.[1]?.trim();
+      if (!familyValue) continue;
+      const family = familyValue.replace(/^(['"])(.*)\1$/, "$2");
+      if (!wanted.has(family.toLowerCase())) continue;
+      result.families.add(family.toLowerCase());
+      const source = /(?:^|;)\s*src\s*:\s*([^;]+)/i.exec(body);
+      if (!source) continue;
+      const sources = localFontSources(source[1], projectDir);
+      if (!sources.length) {
+        console.warn("Captured font has no downloaded source: " + family);
+        continue;
+      }
+      for (const file of sources) {
+        if (copied.has(file.name)) continue;
+        if (!copied.size) mkdirSync(join(projectDir, "assets/fonts"), { recursive: true });
+        copyFileSync(file.source, join(projectDir, file.target));
+        copied.add(file.name);
+        result.files.add(file.target);
+      }
+      const src = sources.map((file) => file.css).join(", ");
+      const rule = "@font-face{" + body.replace(source[1], src) + "}";
+      if (!result.faces.includes(rule)) result.faces.push(rule);
+    }
+  }
+  return result;
+}
+
+function localFontSources(source, projectDir) {
+  const files = [];
+  for (const match of source.matchAll(
+    /url\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)(\s*format\([^)]*\))?/gi,
+  )) {
+    const url = match[1] ?? match[2] ?? match[3];
+    const name = /^assets\/fonts\/([a-z0-9_.-]+\.(?:woff2?|ttf|otf))$/i.exec(url)?.[1];
+    if (!name) continue;
+    const path = join(projectDir, "capture/assets/fonts", name);
+    if (!existsSync(path)) continue;
+    const target = "assets/fonts/captured-" + name;
+    files.push({ name, source: path, target, css: 'url("' + target + '")' + (match[4] ?? "") });
+  }
+  return files;
+}

package/skills/{hyperframes-core → faceless-explainer}/scripts/lib/frame-packets-core.mjs

@@ -1,20 +1,6 @@
-// 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.
+// Frame packets inline the storyboard frame, blueprint and cited recipes.
+// Workflow wrappers supply resource paths and workflow-specific sections.
+// The role combines the shared worker contract with the workflow delta.
 
 import {
   existsSync,
@@ -100,12 +86,8 @@ export function resourceSections(block, { animationDir, ruleIds, frameId }) {
   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).
+    // An installed library must contain the named blueprint.
+    // An absent on-demand library warns, like missing motion rules.
     if (!existsSync(blueprintsDir)) {
       console.warn(
         `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,

package/skills/faceless-explainer/scripts/lib/storyboard.mjs

@@ -5,7 +5,7 @@
 // ship standalone: installed via `npx skills add`, a skill's scripts can't reach
 // the monorepo's core package, and the core export points at .ts source that
 // `node` (which runs these scripts) can't load. CANONICAL contract = the core
-// parser + skills/hyperframes-core/references/storyboard-format.md; keep this in
+// parser + skills/hyperframes/references/storyboard-format.md; keep this in
 // lockstep. Behavior: never throws, accepts freeform narrative, recognizes
 // Frame/Beat/Scene headings at H2/H3, preserves unknown keys verbatim under
 // `extra` (keys lowercased). Pure node — no deps.

package/skills/faceless-explainer/scripts/lib/transitions.json

@@ -34,11 +34,11 @@
       "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
       "gsap_template_horizontal": [
         "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ],
       "gsap_template_vertical": [
         "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ]
     },
     {
@@ -61,7 +61,7 @@
       "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
       "gsap_template": [
         "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ]
     }
   ],

package/skills/faceless-explainer/scripts/transitions.mjs

@@ -248,6 +248,7 @@ function runInject(argv) {
     gsapLines.push(
       ...buildGsap(rec, outgoing.id, incoming.id, dur, T, spec.direction, CW, CH, die),
     );
+    gsapLines.push(`tl.addLabel("hf:transition:${outgoing.id}:${incoming.id}:${rec.name}", ${T});`);
     applied.push({ from: outgoing.id, to: incoming.id, type: rec.name, dur, T });
   }
 

package/skills/faceless-explainer/scripts/transitions.test.mjs

@@ -65,4 +65,6 @@ format: 1920x1080
   const outgoing = readFileSync(join(project, "compositions/frames/01-a.html"), "utf8");
   assert.match(outgoing, /data-composition-id="01-a" data-duration="2.5"/);
   assert.match(outgoing, /class="clip"[^>]*data-duration="2.5"/);
+  const index = readFileSync(join(project, "index.html"), "utf8");
+  assert.match(index, /tl\.addLabel\("hf:transition:01-a:02-b:crossfade", 2\)/);
 });

package/skills/faceless-explainer/sub-agents/frame-worker.md

@@ -1,6 +1,6 @@
 # Frame worker — faceless-explainer delta
 
-> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a faceless-explainer frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
+> The shared law is the core contract above (the packet builder prepends `../hyperframes/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a faceless-explainer frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
 
 ## Your `focal:` / `roles:` — invented elements
 

package/skills/figma/SKILL.md

@@ -3,6 +3,8 @@ name: figma
 description: Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 > **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update figma`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
 
 # Figma → HyperFrames

package/skills/general-video/SKILL.md

@@ -8,6 +8,8 @@ description: >
   Route fresh creation through hyperframes before using this skill.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 # General video
 
 Before relying on this workflow, run:
@@ -20,7 +22,7 @@ A successful no-op means the skill is current. Surface an update failure instead
 
 ## 1. Apply cross-cutting source adapters
 
-- **Media:** For any audio, image, icon, logo, voice, grade, LUT, treatment/effect, caption, or media-operation need, load `/media-use` and follow `../media-use/references/resolve.md` (resolve, adopt, reuse) and `../media-use/references/setup-providers.md` (providers, auth). Vague footage feedback and named styles use `../media-use/references/media-treatments.md` before editing; do not improvise supported media effects with CSS/SVG/opacity. Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply the gate in `../hyperframes-core/references/brief-contract.md`: collaborative waits for sign-in or an explicit offline choice; autonomous states the status and continues through an available offline provider. Surface a blocker when no offline provider can satisfy a required capability. Local adoption alone does not require an auth gate.
+- **Media:** For any audio, image, icon, logo, voice, grade, LUT, treatment/effect, caption, or media-operation need, load `/media-use` and follow `../media-use/references/resolve.md` (resolve, adopt, reuse) and `../media-use/references/setup-providers.md` (providers, auth). Vague footage feedback and named styles use `../media-use/references/media-treatments.md` before editing; do not improvise supported media effects with CSS/SVG/opacity. Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply the gate in `../hyperframes/references/brief-contract.md`: collaborative waits for sign-in or an explicit offline choice; autonomous states the status and continues through an available offline provider. Surface a blocker when no offline provider can satisfy a required capability. Local adoption alone does not require an auth gate.
 - **Figma:** If any input is a `figma.com` URL, run `/figma` first. Build from its exported assets, tokens, components, or storyboard frames. Do not use raw Figma connector calls because they skip SVG sanitization, media provenance, and brand-token binding.
 
 These adapters do not change the workflow selected by `/hyperframes`.
@@ -42,16 +44,16 @@ For a new project, choose a kebab-case directory name from the brief and scaffol
 npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=general-video
 ```
 
-Then write `BRIEF.md` at the project root using `../hyperframes-core/references/brief-format.md`. In an existing project, the root is the directory containing `hyperframes.json`. Record only the confirmed preference-backed fields named by the brief format, using `node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes <PROJECT_ROOT>`; never record inferred defaults. Here `<MEDIA_DIR>` is the installed `/media-use` skill directory and `<PROJECT_ROOT>` is the directory containing `hyperframes.json`. If the intent layer adopted a recipe, apply it now with `node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes <PROJECT_ROOT> --name <name>` and do not ask again.
+Then write `BRIEF.md` at the project root using `../hyperframes/references/brief-format.md`. In an existing project, the root is the directory containing `hyperframes.json`. Record only the confirmed preference-backed fields named by the brief format, using `node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes <PROJECT_ROOT>`; never record inferred defaults. Here `<MEDIA_DIR>` is the installed `/media-use` skill directory and `<PROJECT_ROOT>` is the directory containing `hyperframes.json`. If the intent layer adopted a recipe, apply it now with `node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes <PROJECT_ROOT> --name <name>` and do not ask again.
 
 ## 3. Interpret the run shape
 
-Use only the canonical terms from `../hyperframes-core/references/brief-contract.md`:
+Use only the canonical terms from `../hyperframes/references/brief-contract.md`:
 
 | Field          | Meaning                               | Effect                                                                              |
 | -------------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
 | `flow`         | Who drives                            | `automation`: choose and execute the route. `companion`: co-create in conversation. |
-| `storyboard`   | Whether the board is a review surface | `yes`: run plan and sketch review. `no`: build without the board.                   |
+| `storyboard`   | Plan, sketch, and review before build | `yes`: run plan and sketch review (`storyboard.html`). `no`: build without it.      |
 | derived `mode` | How checkpoint gates behave           | Follow the brief contract. Never ask the user to name a mode.                       |
 
 Do not invent synonyms for these states. An ongoing “just build it” signal is handled by the intent layer and arrives as `flow: automation`, `storyboard: no`.
@@ -88,9 +90,9 @@ These reads are mandatory when their condition matches:
 | Any composition HTML or scene layout                                                                              | `/hyperframes-core`; use `references/determinism-rules.md` for its layout contract                                                                                                                                                     |
 | Any non-trivial creation or visual treatment                                                                      | `/hyperframes-creative` → `references/house-style.md` and `references/video-composition.md`                                                                                                                                            |
 | Any motion, animation, or scene transition                                                                        | `/hyperframes-animation`; follow its routing to the matching rules, adapters, blueprints, or transition references                                                                                                                     |
-| `storyboard: yes`                                                                                                 | `../hyperframes-core/references/storyboard-format.md` and `../hyperframes-core/references/review-loop.md`                                                                                                                              |
+| `storyboard: yes`                                                                                                 | `../hyperframes/references/storyboard-format.md` and `../hyperframes/references/review-loop.md`                                                                                                                                        |
 | Any media asset or operation, including narration, BGM, SFX, captions, grading, or transforms                     | `/media-use`; for framework playback and placement also read `/hyperframes-core` → `references/variables-and-media.md`                                                                                                                 |
-| Multi-scene assembly                                                                                              | `../hyperframes-core/references/production-loop.md`                                                                                                                                                                                    |
+| Multi-scene assembly                                                                                              | `../hyperframes/references/production-loop.md`                                                                                                                                                                                         |
 | `flow: companion`, before the first plan                                                                          | `/hyperframes-creative` → `references/story-spine.md` and `references/house-style.md`; the nearest genre lens and the full `../hyperframes/references/capability-menu.md` — the ceiling treatment is designed from these, not recalled |
 | A companion capability offer, capture, beat grid, generative video, map, publishing, or cross-workflow capability | `../hyperframes/references/capability-menu.md`                                                                                                                                                                                         |
 | A design spec exists, before final approval                                                                       | `/hyperframes-creative` → `references/design-adherence.md`                                                                                                                                                                             |
@@ -101,8 +103,8 @@ Do not replace these reads with recollection. Progressive disclosure saves conte
 
 Use this dependency order. Skip a stage only when its input is absent.
 
-1. **Plan.** State the viewer arc, structure, rhythm, and duration driver. Use one file for a short single scene; use sub-compositions for three or more hard scene cuts or any reused scene. Read `/hyperframes-creative` → `references/story-spine.md` for narrated arcs, `references/beat-direction.md` for rhythm, and `/hyperframes-core` → `references/composition-patterns.md` for structure. For an open-ended multi-scene brief, expand the prompt through `/hyperframes-creative` → `references/prompt-expansion.md`. A multi-scene plan cites each scene's shape: a blueprint id from `/hyperframes-animation` → `blueprints-index.md` when one fits, or the named rules it composes from `rules-index.md` when none does — motion names come from those indexes, never invented. Story truth decides which scenes exist; the citation dresses them. A multi-scene plan is also recorded as the dispatch artifact: one `## Frame N` block per scene in `STORYBOARD.md` — `status: outline`, a declared `src:`, the blueprint/rules citation, and the beat text — **even when `storyboard: no`**. The block is the dispatch unit; the board is only the review surface.
-2. **Review the plan when requested.** For `storyboard: yes`, run the shared review loop over those blocks. For `storyboard: no`, continue without opening the board. When a plan pause happens anyway, fold the sub-agent delegation grant (needed by codex for step 4's dispatch) into that pause rather than stopping again later.
+1. **Plan.** State the viewer arc, structure, rhythm, and duration driver. Use one file for a short single scene; use sub-compositions for three or more hard scene cuts or any reused scene. Read `/hyperframes-creative` → `references/story-spine.md` for narrated arcs, `references/beat-direction.md` for rhythm, and `/hyperframes-core` → `references/composition-patterns.md` for structure. For an open-ended multi-scene brief, expand the prompt through `/hyperframes-creative` → `references/prompt-expansion.md`. A multi-scene plan cites each scene's shape: a blueprint id from `/hyperframes-animation` → `blueprints-index.md` when one fits, or the named rules it composes from `rules-index.md` when none does — motion names come from those indexes, never invented. Story truth decides which scenes exist; the citation dresses them. **Search the live catalog before you plan to build any named look yourself**: for every look, effect, treatment or transition the brief names — "CRT scanlines", "glitch", "film grain", "shimmer sweep", "confetti burst" — run `npx hyperframes catalog --query "<the look, in plain English>" --json` and read the top results before the plan names how that look gets built. The search needs **nothing installed**: no project, no prior `add`, no account. It ranks the whole hosted registry (~400 blocks and components) from any directory, so it also applies to a look the user asks for mid-build. Blocks the plan names are installed at stage 3; hand-author a look only after a search for it came back with nothing that fits. A multi-scene plan is also recorded as the dispatch artifact: one `## Frame N` block per scene in `STORYBOARD.md` — `status: outline`, a declared `src:`, the blueprint/rules citation, and the beat text — **even when `storyboard: no`**. The block is the dispatch unit; the storyboard sheet is only the review surface.
+2. **Review the plan when requested.** For `storyboard: yes`, run the shared review loop over those blocks. For `storyboard: no`, continue without a plan pause or sketch sheet. When a plan pause happens anyway, fold the sub-agent delegation grant (needed by codex for step 4's dispatch) into that pause rather than stopping again later.
 3. **Resolve dependencies.** Install registry blocks before parallel work. Stage user assets, adopt existing media, and resolve only what the brief requires. Start audio early when its timings drive duration.
 4. **Build scenes.** For a short single-scene piece, implement the scene at its most visible moment before adding motion (the confirmed wireframe, when present, is that end state and must not be redrawn), then animate from its cited blueprint or rules — read the full recipe body (`/hyperframes-animation` → `blueprints/<id>.md`, `rules/<id>.md`) before writing motion.
 
@@ -110,10 +112,10 @@ Use this dependency order. Skip a stage only when its input is absent.
 
    `node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"`
 
-   The builder writes one bounded packet per scene under `.hyperframes/frame-packets/` (the scene's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes-core/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch the workers — 2–3 scene packets each, all in one wave (`../hyperframes-core/references/subagent-dispatch.md`); each worker's prompt carries `_role.md` and its packets — paste them in full, or hand the file paths for the worker to read first (equivalent either way) — plus a dispatch context with `PROJECT_DIR`, its `frame_id`s, and canvas size. WAIT on every scene's `compositions/<frame_id>.html` + `compositions/<frame_id>.motion.json`. Workers read only their packets and the design truth file; they never open `STORYBOARD.md` or the skill documents. With no delegation channel, fall back serially: process one packet at a time in this context, still working from the packet alone.
+   The builder writes one bounded packet per scene under `.hyperframes/frame-packets/` (the scene's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch the workers — 2–3 scene packets each, all in one wave (`../hyperframes/references/subagent-dispatch.md`); each worker's prompt carries `_role.md` and its packets — paste them in full, or hand the file paths for the worker to read first (equivalent either way) — plus a dispatch context with `PROJECT_DIR`, its `frame_id`s, and canvas size. WAIT on every scene's `compositions/<frame_id>.html` + `compositions/<frame_id>.motion.json`. Workers read only their packets and the design truth file; they never open `STORYBOARD.md` or the skill documents. With no delegation channel, fall back serially: process one packet at a time in this context, still working from the packet alone.
 
 5. **Merge motion sidecars.** Collect the workers' `compositions/<frame_id>.motion.json` files and carry their durations and exit/entry vectors into assembly; where the doctrine chain (`/motion-doctrine`) is installed, translate them into the project ledger before stamping seams.
-6. **Assemble.** Mount scenes, media, transitions, captions, and audio using the production loop. Real voice duration overrides estimates.
+6. **Assemble.** Mount scenes, media, transitions, captions, and audio using the production loop. Real voice duration overrides estimates. When a music bed plays under any voice track, carve the bed before verifying: `/hyperframes-audio` → `scripts/carve.mjs --comp index.html`. A volume duck alone does not finish the mix.
 7. **Verify.** Use `npx hyperframes lint` for fast feedback after the first HTML pass and structural changes. For the final gate, run `npx hyperframes check`; it reruns lint internally, so do not run a redundant standalone lint immediately before it. For sub-compositions, inspect midpoint snapshots. For multi-scene work, review the animation map.
 8. **Final approval.** Open the final Studio preview only after checks pass. Ask whether to render or revise. Render only after approval.
 
@@ -162,4 +164,4 @@ A run is complete only when:
 - the user approves the final Studio preview before render;
 - the rendered file is verified when a render was requested.
 
-After final approval, offer once to freeze the run as a recipe, following `../hyperframes-core/references/review-loop.md` § 4.
+After final approval, offer once to freeze the run as a recipe, following `../hyperframes/references/review-loop.md` § 4.

package/skills/general-video/scripts/frame-packets.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
-// Thin wrapper over the shared packet builder in hyperframes-core — this file pins
+// Thin wrapper over the shared packet builder in hyperframes — this file pins
 // this workflow's paths plus its one behavioral difference: design truth resolves
 // frame.md → design.md → DESIGN.md (general-video § 6 order). Everything else has
-// one owner: ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
+// one owner: ../../hyperframes/scripts/lib/frame-packets-core.mjs
 
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
+import * as core from "./lib/frame-packets-core.mjs";
 
 const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -22,7 +22,7 @@ function designTruthLine(projectDir) {
 
 const CONFIG = {
   animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
-  corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
+  corePath: resolve(SKILL_DIR, "../hyperframes/references/frame-worker-core.md"),
   deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
   designTruthLine,
 };

package/skills/general-video/scripts/lib/frame-packets-core.mjs

@@ -0,0 +1,194 @@
+// Frame packets inline the storyboard frame, blueprint and cited recipes.
+// Workflow wrappers supply resource paths and workflow-specific sections.
+// The role combines the shared worker contract with the workflow delta.
+
+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`);
+    // An installed library must contain the named blueprint.
+    // An absent on-demand library warns, like missing motion rules.
+    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/general-video/sub-agents/frame-worker.md

@@ -1,6 +1,6 @@
 # Frame worker — general-video delta
 
-> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a general-video scene; you run N-up, **one scene each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
+> The shared law is the core contract above (the packet builder prepends `../../hyperframes/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a general-video scene; you run N-up, **one scene each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
 
 ## Your scene is invented, not captured