dsh-hyperframes 0.3.1 → 0.4.0

package/skills/embedded-captions/scripts/preview-frames.cjs

@@ -23,8 +23,24 @@
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
+const crypto = require("crypto");
+const { pathToFileURL } = require("url");
+
+function sriSha384(source) {
+  return `sha384-${crypto.createHash("sha384").update(source).digest("base64")}`;
+}
+
+function withPreviewGsapSri(html, gsapSource) {
+  const integrity = sriSha384(gsapSource);
+  return html.replace(/<script\b(?=[^>]*\bsrc=["'][^"']*gsap[^"']*["'])[^>]*>/gi, (tag) =>
+    tag
+      .replace(/\s+integrity\s*=\s*(?:"[^"]*"|'[^']*')/gi, "")
+      .replace(/>$/, ` integrity="${integrity}">`),
+  );
+}
 
 const HF_ROOTS = [
+  process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
   process.env.HYPERFRAMES_ROOT,
   path.resolve(__dirname, "../../.."),
   path.join(os.homedir(), "Downloads", "hyperframes"),
@@ -63,11 +79,13 @@ for (const r of HF_ROOTS) {
   }
   if (!gsapSource) {
     const g = findInBun(r, "gsap", path.join("dist", "gsap.min.js"));
-    if (g) gsapSource = fs.readFileSync(g, "utf8");
+    if (g) gsapSource = fs.readFileSync(g);
   }
 }
-if (!puppeteer || !sharp) {
-  console.error("[preview] need puppeteer+sharp — set HYPERFRAMES_ROOT");
+if (require.main === module && (!puppeteer || !sharp)) {
+  console.error(
+    "[preview] need puppeteer+sharp — install project dependencies per embedded-captions SKILL.md Runtime prerequisites",
+  );
   process.exit(0);
 }
 
@@ -80,9 +98,15 @@ async function shotAt(browser, file, W, H, t) {
     // evaluation runs while document.head is still null, and gsap's init then
     // throws "appendChild of null" — which killed previews for theme projects.
     await page.setRequestInterception(true);
+    const documentUrl = pathToFileURL(file).href;
+    const documentHtml = gsapSource
+      ? withPreviewGsapSri(fs.readFileSync(file, "utf8"), gsapSource)
+      : fs.readFileSync(file, "utf8");
     page.on("request", (req) => {
       const u = req.url();
-      if (req.resourceType() === "script" && /gsap/i.test(u) && /^https?:/i.test(u)) {
+      if (req.isNavigationRequest() && u === documentUrl) {
+        req.respond({ status: 200, contentType: "text/html", body: documentHtml });
+      } else if (req.resourceType() === "script" && /gsap/i.test(u) && /^https?:/i.test(u)) {
         if (gsapSource)
           req.respond({ status: 200, contentType: "application/javascript", body: gsapSource });
         else req.continue(); // no local bundle — let the CDN load (online machines)
@@ -90,7 +114,7 @@ async function shotAt(browser, file, W, H, t) {
         req.abort(); // a-roll pixels come from frames_bg
       else req.continue();
     });
-    await page.goto(`file://${file}`, { waitUntil: "load", timeout: 15000 });
+    await page.goto(documentUrl, { waitUntil: "load", timeout: 15000 });
     const t0 = Date.now();
     let tlReady = false;
     while (Date.now() - t0 < 15000) {
@@ -260,9 +284,13 @@ async function main() {
     await Promise.race([browser.close().catch(() => {}), new Promise((r) => setTimeout(r, 8000))]);
   }
 }
-main()
-  .then(() => process.exit(0))
-  .catch((e) => {
-    console.error("[preview]", e.message);
-    process.exit(1);
-  });
+if (require.main === module) {
+  main()
+    .then(() => process.exit(0))
+    .catch((e) => {
+      console.error("[preview]", e.message);
+      process.exit(1);
+    });
+}
+
+module.exports = { sriSha384, withPreviewGsapSri };

package/skills/embedded-captions/scripts/preview-frames.test.mjs

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+import test from "node:test";
+
+const require = createRequire(import.meta.url);
+const { sriSha384, withPreviewGsapSri } = require("./preview-frames.cjs");
+
+test("preview GSAP integrity matches the intercepted asset bytes", () => {
+  const servedAsset = Buffer.from("the exact local GSAP response body");
+  const html = `
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js" integrity="sha384-stale" crossorigin="anonymous"></script>
+    <script src="https://cdn.example.test/app.js" integrity="sha384-app" crossorigin="anonymous"></script>
+  `;
+
+  const emitted = withPreviewGsapSri(html, servedAsset);
+  const expected = `sha384-${crypto.createHash("sha384").update(servedAsset).digest("base64")}`;
+  const gsapTag = emitted.match(/<script[^>]*gsap[^>]*>/i)[0];
+
+  assert.equal(sriSha384(servedAsset), expected);
+  assert.match(gsapTag, new RegExp(`integrity="${expected}"`));
+  assert.match(gsapTag, /crossorigin="anonymous"/);
+  assert.match(emitted, /app\.js" integrity="sha384-app" crossorigin="anonymous"/);
+});

package/skills/embedded-captions/scripts/render-and-composite.sh

@@ -12,21 +12,10 @@ set -euo pipefail
 PROJECT="${1:?usage: render-and-composite.sh <project-dir> [hyperframes-repo]}"
 PROJECT="$(cd "$PROJECT" && pwd)"
 
-# Resolve the hyperframes checkout. Candidate order:
-#   1. arg 2   2. $HYPERFRAMES_ROOT   3. repo root if this skill ships INSIDE the
-#   hyperframes repo (skills/embedded-captions/scripts → ../../..)   4. ~/Downloads/hyperframes
 SKILL_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-HF=""
-for cand in "${2:-}" "${HYPERFRAMES_ROOT:-}" "$(cd "$SKILL_SCRIPT_DIR/../../.." 2>/dev/null && pwd)" "$HOME/Downloads/hyperframes"; do
-  if [[ -n "$cand" && -f "$cand/packages/cli/dist/cli.js" ]]; then HF="$cand"; break; fi
-done
-if [[ -z "$HF" ]]; then
-  echo "[render] hyperframes CLI not found. Set HYPERFRAMES_ROOT to your hyperframes" >&2
-  echo "         checkout (needs packages/cli/dist/cli.js — 'bun install && bun run build')." >&2
-  exit 1
-fi
-export HYPERFRAMES_ROOT="$HF"   # so the occlusion gate's measure-layout.cjs finds puppeteer too
-HF_CLI="$HF/packages/cli/dist/cli.js"
+HF_CLI="$(node "$SKILL_SCRIPT_DIR/hf-cli.cjs" "${2:-}")"
+# Retain the explicit dependency-root override for source-checkout users.
+if [[ -n "${2:-}" ]]; then export HYPERFRAMES_ROOT="$2"; fi
 if [[ ! -d "$PROJECT/frames_fg" ]]; then
   echo "[render] missing matte frames at $PROJECT/frames_fg — run matte.cjs first" >&2
   exit 1
@@ -237,49 +226,16 @@ echo "[render] snapshot → history/index-${STAMP}.html"
 
 echo "[render] hyperframes render @ ${FPS}fps"
 
-# Hyperframes occasionally hangs on Chromium shutdown *after* the output file
-# is successfully written (seen multiple times on 15–30s clips). Without a
-# guard the shell waits forever. This helper enforces a max wall-clock budget,
-# and if the output is already on disk when we hit it, treats the run as
-# successful and kills the zombie. Tune HF_TIMEOUT_S via env if needed.
-# Default SCALES with clip size: two parallel Chromium passes on a long clip
-# legitimately exceed a fixed 240s (a 38s/1151-frame render was killed at 244s
-# while healthy). ~1.5s per source frame, floor 240s.
-N_FRAMES="$(ls "$PROJECT/frames_fg" 2>/dev/null | wc -l | tr -d ' ')"
-HF_TIMEOUT_S="${HF_TIMEOUT_S:-$(( N_FRAMES * 3 / 2 > 240 ? N_FRAMES * 3 / 2 : 240 ))}"
-# hf_render_dir: render one hyperframes composition.
-# args: <output.mp4> <label> <project_dir>
-# watches for the Chromium-shutdown-hang; if output file exists and is >1MB
-# past timeout, treats as success and kills the zombie.
+# Wait for the renderer's real exit status. File size cannot prove completion,
+# and a portable process snapshot cannot safely recover a timed-out render tree.
+# Cancellation/browser cleanup belongs to the CLI that owns those processes.
 hf_render_dir() {
   local out="$1" label="$2" proj="$3" fmt="${4:-}"
-  # bash 3.2 (macOS) throws on empty-array expansion under `set -u`, so branch
-  # explicitly instead of splatting an optional --format array.
   if [[ -n "$fmt" ]]; then
-    node "$HF_CLI" render --skill=embedded-captions --dir "$proj" --fps "$FPS" --format "$fmt" --crf 11 -o "$out" &
+    node "$HF_CLI" render --skill=embedded-captions --dir "$proj" --fps "$FPS" --format "$fmt" --crf 11 -o "$out" || return $?
   else
-    node "$HF_CLI" render --skill=embedded-captions --dir "$proj" --fps "$FPS" --crf 11 -o "$out" &
+    node "$HF_CLI" render --skill=embedded-captions --dir "$proj" --fps "$FPS" --crf 11 -o "$out" || return $?
   fi
-  local pid=$! start=$SECONDS elapsed
-  while kill -0 "$pid" 2>/dev/null; do
-    elapsed=$((SECONDS - start))
-    if (( elapsed > HF_TIMEOUT_S )); then
-      local sz=0
-      [[ -f "$out" ]] && sz=$(stat -f%z "$out" 2>/dev/null || echo 0)
-      if (( sz > 1000000 )); then
-        echo "[render] ${label}: node hung ${elapsed}s after shutdown (output ${sz}B exists, treating as success)"
-        kill -9 "$pid" 2>/dev/null
-        pkill -9 -f "puppeteer_dev_chrome_profile" 2>/dev/null
-        return 0
-      fi
-      echo "[render] ${label}: hung ${elapsed}s with no output — killing and failing" >&2
-      kill -9 "$pid" 2>/dev/null
-      pkill -9 -f "puppeteer_dev_chrome_profile" 2>/dev/null
-      return 2
-    fi
-    sleep 5
-  done
-  wait "$pid" 2>/dev/null
   [[ -f "$out" ]]
 }
 

package/skills/embedded-captions/scripts/safe-zones.cjs

@@ -22,6 +22,7 @@ const THRESH = 30 / 255; // a cell is "subject" if ≥12% covered at any sampled
 const SAMPLES = 48; // frames cached across the clip (windows aggregate the cached grids)
 
 const HF_ROOTS = [
+  process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
   process.env.HYPERFRAMES_ROOT,
   path.resolve(__dirname, "../../.."),
   path.join(os.homedir(), "Downloads", "hyperframes"),
@@ -558,7 +559,9 @@ async function main() {
     process.exit(2);
   }
   if (!sharp) {
-    console.error("[safe-zones] sharp unavailable — set HYPERFRAMES_ROOT");
+    console.error(
+      "[safe-zones] sharp unavailable — install project dependencies per embedded-captions SKILL.md Runtime prerequisites",
+    );
     process.exit(0);
   }
 

package/skills/embedded-captions/scripts/transcribe.cjs

@@ -9,20 +9,10 @@
  */
 const path = require("path");
 const fs = require("fs");
-const os = require("os");
 const cp = require("child_process");
 
-function hfRoot() {
-  const roots = [
-    process.env.HYPERFRAMES_ROOT,
-    path.resolve(__dirname, "..", "..", ".."),
-    path.join(os.homedir(), "Downloads", "hyperframes"),
-  ].filter(Boolean);
-  for (const r of roots)
-    if (fs.existsSync(path.join(r, "packages", "cli", "dist", "cli.js"))) return r;
-  console.error("[transcribe] hyperframes CLI not found — set HYPERFRAMES_ROOT");
-  process.exit(3);
-}
+const { hfCli } = require("./hf-cli.cjs");
+
 function ensureSource(project) {
   const src = path.join(project, "source.mp4");
   if (fs.existsSync(src)) return src;
@@ -247,7 +237,7 @@ function main() {
 
   if (!words) {
     // run hyperframes Whisper → writes a flat word array to <dir>/transcript.json
-    const cli = path.join(hfRoot(), "packages", "cli", "dist", "cli.js");
+    const cli = hfCli();
     const args = ["transcribe", audio, "-d", project, "--json", "--model", model];
     if (language) args.push("--language", language);
     let info = {};
@@ -270,7 +260,8 @@ function main() {
         end: w.end ?? w.t1,
         type: "word",
       }));
-    engine = `whisper.cpp(${model})`;
+    // Under the default --engine auto the CLI may have run Parakeet; it reports which.
+    engine = info.engine === "parakeet" ? `parakeet(${info.model})` : `whisper.cpp(${model})`;
   }
 
   // Tail-hallucination guard: drop words whisper placed entirely inside a terminal

package/skills/embedded-captions/scripts/transcribe.test.mjs

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+// A stub CLI answers as `transcribe --json` does when --engine auto ran Parakeet.
+const STUB_CLI = `
+const fs = require("fs"), path = require("path");
+const project = process.argv[process.argv.indexOf("-d") + 1];
+const transcriptPath = path.join(project, "cli-words.json");
+fs.writeFileSync(transcriptPath, JSON.stringify([{ text: "hello", start: 0.1, end: 0.5 }]));
+console.log(JSON.stringify({ ok: true, engine: "parakeet", model: "parakeet-tdt-0.6b-v3", transcriptPath }));
+`;
+
+test("the CLI fallback labels the transcript with the engine the CLI ran", () => {
+  const root = mkdtempSync(join(tmpdir(), "embedded-captions-transcribe-"));
+  try {
+    const cliDir = join(root, "hf", "packages", "cli", "dist");
+    mkdirSync(cliDir, { recursive: true });
+    writeFileSync(join(cliDir, "cli.js"), STUB_CLI);
+    const project = join(root, "project");
+    mkdirSync(project);
+    writeFileSync(join(project, "source.mp4"), "");
+    writeFileSync(join(project, "audio.mp3"), "");
+    execFileSync(
+      process.execPath,
+      [fileURLToPath(new URL("./transcribe.cjs", import.meta.url)), project],
+      {
+        stdio: "ignore",
+        env: { ...process.env, HYPERFRAMES_ROOT: join(root, "hf"), TRANSCRIBE_ENGINE: "whisper" },
+      },
+    );
+    const transcript = JSON.parse(readFileSync(join(project, "transcript.json"), "utf8"));
+    assert.equal(transcript.engine, "parakeet(parakeet-tdt-0.6b-v3)");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/skills/faceless-explainer/SKILL.md

@@ -3,6 +3,8 @@ name: faceless-explainer
 description: "Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes."
 ---
 
+**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 faceless-explainer`. 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.
 
 > **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.
@@ -13,7 +15,7 @@ Use this skill to turn a body of text into an explainer video: pick a design sys
 
 > **The front door is `/hyperframes`.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for **explaining a topic from text, with no product and no website to capture**. Any other intent, a bare "make a video", or any uncertainty → read `/hyperframes` first — the intent layer owns every route decision, and a fresh creation arriving here without `BRIEF.md` goes through it anyway (Setup's opening rule).
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the gate types and how `BRIEF.md`'s `flow`/`storyboard` derive the mode that governs the Step 3/4/6 gates. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes/references/brief-contract.md` before Step 0 — it defines the gate types and how `BRIEF.md`'s `flow`/`storyboard` derive the mode that governs the Step 3/4/6 gates. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup → `hyperframes.json`; Step 1 brief → `capture/extracted/`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.
 
@@ -31,7 +33,7 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the topi
 
 After init, let `<PROJECT_ROOT>` be `videos/<project>` and run every subsequent relative-path command with that directory as its working directory. In the commands below, `.` means `<PROJECT_ROOT>`; never write `.media`, `capture`, or output files in the caller directory.
 
-**Write `BRIEF.md` immediately after init** (never before — `init` refuses a non-empty directory): the intent layer's locked brief, shape per `../hyperframes-core/references/brief-format.md`. Resolve `<MEDIA_DIR>` as the installed `/media-use` skill directory. Then record each preference-backed answer with `node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes .` (`brief-format.md` names the subset). If the intent layer adopted a recipe, run `node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>`; it copies its `frame.md` into the project (Step 2 is then skipped) and returns the skeletons Step 3 drafts from. A recipe fills answers, not approvals; the review gates still run.
+**Write `BRIEF.md` immediately after init** (never before — `init` refuses a non-empty directory): the intent layer's locked brief, shape per `../hyperframes/references/brief-format.md`. Resolve `<MEDIA_DIR>` as the installed `/media-use` skill directory. Then record each preference-backed answer with `node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes .` (`brief-format.md` names the subset). If the intent layer adopted a recipe, run `node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>`; it copies its `frame.md` into the project (Step 2 is then skipped) and returns the skeletons Step 3 drafts from. A recipe fills answers, not approvals; the review gates still run.
 
 **Show sign-in status before proceeding past Setup** — run `npx hyperframes auth status` and relay its output verbatim. It reports whether voice/BGM will use HeyGen or local engines and, when signed out, how to sign in. Apply one branch:
 
@@ -83,11 +85,11 @@ A faceless explainer usually has **no brand colors/fonts** (`tokens.json` colors
 
 Goal: Turn the text into an approved frame-by-frame teaching plan.
 
-Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal, source-traceable visuals), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`. Set the frontmatter `duration:` from the brief's `length` — a rough expectation; assembly reports where the cut lands against it.
+Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal, source-traceable visuals), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes/references/storyboard-format.md`, and `../hyperframes/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`. Set the frontmatter `duration:` from the brief's `length` — a rough expectation; assembly reports where the cut lands against it.
 
 Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. Use the exact required fields from the storyboard and script references.
 
-After drafting, run the review loop's plan pass — `../hyperframes-core/references/review-loop.md` § 1: open the board (don't ask whether to), present the plan as a proposal, and ask the two questions — approve or change, and **sketches first** (recommended) or skip. Feedback loops through chat or the board's comments file until approved. This is a **checkpoint gate** (brief contract § 1): in autonomous mode there is no board and nothing to ask — post the same summary as a heads-up and proceed; sketches collapse into the build, and the one preview question comes at Step 6.
+After drafting, run the review loop's plan pass — `../hyperframes/references/review-loop.md` § 1: present the plan as a proposal, and ask the two questions — approve or change, and **sketches first** (recommended) or skip. Feedback arrives as a chat reply; loop until approved. This is a **checkpoint gate** (brief contract § 1): in autonomous mode there is nothing to ask — post the same summary as a heads-up and proceed; sketches collapse into the build, and the one preview question comes at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
@@ -117,17 +119,19 @@ If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may stil
 
 Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.
 
-**Sketch the board first (collaborative only).** The moment the plan is approved, run the sketch pass — `../hyperframes-core/references/review-loop.md` § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself, mark each `built`, pause for the one layout question when the board is full, and revise only the sketches named until the board is confirmed. Only then write the visual design below onto the confirmed layouts. In autonomous mode, or when the user chose to skip sketches at Step 3, skip this pass — frames go straight from `outline` to `animated` at Step 5.
+**Sketch the storyboard sheet first (collaborative only).** The moment the plan is approved, run the sketch pass — `../hyperframes/references/review-loop.md` § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself as a cell of `storyboard.html` (`../hyperframes-creative/references/storyboard-recipe.md` § 3), mark each `built`, pause for the one layout question when every frame is `built`, and revise only the sketches named until the sheet is confirmed. Only then write the visual design below onto the confirmed layouts. In autonomous mode, or when the user chose to skip sketches at Step 3, skip this pass — frames go straight from `outline` to `animated` at Step 5.
 
 Edit `STORYBOARD.md` in place. Do not create another storyboard. Use `frame.md` as source of truth for color, type, layout feel, and style.
 
 Read `references/visual-design.md`, `../hyperframes-animation/blueprints-index.md`, `references/motion-language.md`, and `../hyperframes-animation/rules-index.md`. Use `visual-design.md` for the method (the time-coded shot sequence, the inline Layout vocabulary, and the invented-visual treatment), plus the required `## Video direction` block. Use `../hyperframes-animation/blueprints-index.md` to pick each frame's shot shape. Use `motion-language.md` (the motion vocabulary + the motion doctrine) and `../hyperframes-animation/rules-index.md` (valid rule names) for motion — do not invent motion names.
 
+**Search the live catalog before you invent any named look.** A faceless explainer invents every visual, which is exactly when a hand-authored rebuild of an existing block is most likely. 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 you write that look into `STORYBOARD.md`. 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. A block that already does the job becomes the frame's `focal` — name it here so Step 5's workers install and customize it. Invent a visual only after a search for it came back with nothing that fits.
+
 For every frame, write a **time-coded shot sequence** into `STORYBOARD.md` per `visual-design.md`'s method: pick the frame's blueprint (or compose), instantiate it with THIS frame's **invented** content, and pace each Scene's reveal to the voiceover so the frame develops across its full duration instead of front-loading then freezing. Because the explainer is faceless, `focal`/`roles` name the **invented visual elements** (a hero word, a diagram node, a data-viz series) — you are designing them, not selecting captured assets. State layout and motion **inline** per Scene (vocabularies in `visual-design.md` and `motion-language.md`). Add one video-wide `## Video direction` block.
 
 Do not change story, script, `transition_in`, or the source text. Do not write HTML in this step. There is **no asset-staging step** — faceless visuals are built by the workers in Step 5. If the user supplied a real `public/<basename>` image, reference it by path in the relevant frame's `focal`/`roles`; otherwise nothing to stage.
 
-**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); each frame names its invented `focal` and/or `roles`; `## Video direction` exists. Collaborative: the sketch board was confirmed.
+**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); each frame names its invented `focal` and/or `roles`; `## Video direction` exists. Collaborative: the sketch sheet was confirmed.
 
 ---
 
@@ -143,15 +147,15 @@ Wait for Step 3.1 audio to finish if audio was started. Then sync durations and
 
 Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.
 
-Before dispatch, read `../hyperframes-core/references/subagent-dispatch.md`. Build the per-frame packets and the worker role payload:
+Before dispatch, read `../hyperframes/references/subagent-dispatch.md`. Build the per-frame packets and the worker role payload:
 
 `node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"`
 
-The builder writes one bounded packet per frame under `.hyperframes/frame-packets/` (the frame'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 one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame: its prompt carries `_role.md` and that frame's packet — paste both in full, or hand the two file paths for the worker to read first (equivalent; the worker starts from exactly those two documents either way) — plus a dispatch context with `PROJECT_DIR`, `frame_id`, whether the frame has a **confirmed sketch** on disk (the worker dresses that layout rather than redrawing it — frame-worker core § When a confirmed sketch exists), canvas size, and caption status + keep-out band if captions are enabled.
+The builder writes one bounded packet per frame under `.hyperframes/frame-packets/` (the frame'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 one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame: its prompt carries `_role.md` and that frame's packet — paste both in full, or hand the two file paths for the worker to read first (equivalent; the worker starts from exactly those two documents either way) — plus a dispatch context with `PROJECT_DIR`, `frame_id`, whether the frame has a **confirmed sketch** on disk (the worker dresses that layout rather than redrawing it — frame-worker core § When a confirmed sketch exists), canvas size, and caption status + keep-out band if captions are enabled.
 
 Workers read only their packet and `frame.md`; they never open `STORYBOARD.md` or the skill documents (the packet inlines what was selected upstream). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
 
-**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `../hyperframes-core/references/frame-worker-core.md`.)
+**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `../hyperframes/references/frame-worker-core.md`.)
 
 As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
 
@@ -163,7 +167,7 @@ After audio timings exist, build captions in the background and assemble the ind
 
 `captions.mjs` uses the project's `.hyperframes/caption-skin.html` (copied in Step 2) as the caption look, injecting brand tokens from `frame.md`; with no skin present it renders the built-in default pill. `captions: skipped (<reason>)` is valid. Continue without captions when explicitly skipped.
 
-**Gate:** every frame is marked `animated` (collaborative: the sketch board was confirmed at Step 4), `index.html` exists, and captions are built or explicitly skipped.
+**Gate:** every frame is marked `animated` (collaborative: the sketch sheet was confirmed at Step 4), `index.html` exists, and captions are built or explicitly skipped.
 
 ---
 
@@ -189,7 +193,7 @@ If a command fails, surface stderr and stop — don't pile on recovery commands.
 
 **Known false-positive — do not chase it.** `check` may report a handful of `text_box_overflow` findings of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
 
-After checks pass, pause for user review — the review loop's final look (`../hyperframes-core/references/review-loop.md` § 4): one question, on the Studio that has been open since Step 3 — render now, or what changes? (Autonomous: the one kept question, preview first or render.) Then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
+After checks pass, pause for user review — the review loop's final look (`../hyperframes/references/review-loop.md` § 4): one question, on the final Studio preview — render now, or what changes? (Autonomous: the one kept question, preview first or render.) Then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview --background`
 
@@ -215,19 +219,19 @@ The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blue
 
 | Read                                                                                                                                                        | When                                                                                                     |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Gate types, mode derivation from `BRIEF.md`, field semantics.                                            |
+| `[../hyperframes/references/brief-contract.md](../hyperframes/references/brief-contract.md)`                                                                | Gate types, mode derivation from `BRIEF.md`, field semantics.                                            |
 | `[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)`                                                    | Step 3: story doctrine — hook language, value-before-evidence, proposal shape, source-traceable visuals. |
 | `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                                                                 |
 | `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                                                                    |
 | `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the explainer story.                                                                        |
 | `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.                                                |
-| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                                                           |
-| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                                                               |
+| `[../hyperframes/references/storyboard-format.md](../hyperframes/references/storyboard-format.md)`                                                          | Step 3: write `STORYBOARD.md`.                                                                           |
+| `[../hyperframes/references/script-format.md](../hyperframes/references/script-format.md)`                                                                  | Step 3: write `SCRIPT.md`.                                                                               |
 | `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers and voices.                                                 |
 | `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary).                                           |
 | `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.                                                     |
 | `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).                                            |
 | `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.                                                  |
-| `[../hyperframes-core/references/frame-worker-core.md](../hyperframes-core/references/frame-worker-core.md)`                                                | Step 5: the shared worker contract (packet builder prepends it to the delta).                            |
+| `[../hyperframes/references/frame-worker-core.md](../hyperframes/references/frame-worker-core.md)`                                                          | Step 5: the shared worker contract (packet builder prepends it to the delta).                            |
 | `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: the workflow's frame-worker delta.                                                               |
-| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                                                                      |
+| `[../hyperframes/references/subagent-dispatch.md](../hyperframes/references/subagent-dispatch.md)`                                                          | Step 5: dispatch sub-agents safely.                                                                      |

package/skills/faceless-explainer/references/story-design.md

@@ -2,7 +2,7 @@
 
 Use this reference in Step 3 to write `STORYBOARD.md` and `SCRIPT.md` for a faceless explainer — a topic, concept, how-to, listicle, or narrative explainer built from text, with **no product, no website, and no captured assets**.
 
-This file defines the story: what the video teaches, in what order, and why each frame exists. It does not define layout, visual effects, animation, or final markdown schemas. For exact file syntax, follow `../hyperframes-core/references/storyboard-format.md` and `../hyperframes-core/references/script-format.md`.
+This file defines the story: what the video teaches, in what order, and why each frame exists. It does not define layout, visual effects, animation, or final markdown schemas. For exact file syntax, follow `../hyperframes/references/storyboard-format.md` and `../hyperframes/references/script-format.md`.
 
 ## Read first
 

package/skills/faceless-explainer/scripts/assemble-index.mjs

@@ -6,8 +6,7 @@
 //
 // index.html is a *standalone* composition (root <div id="root"> directly in
 // <body>, no <template> wrapper — template is for sub-comps). Structure is
-// modeled on the canonical fixture packages/studio/fixtures/storyboard-sample/
-// index.html and the authoritative head/audio template in
+// modeled on the canonical fixture project index.html and the authoritative head/audio template in
 // packages/core/docs/quickstart-template.html. Frame mount order = STORYBOARD
 // document order. Transitions are NOT written here — the transitions injector
 // mutates this file afterward (data-start/duration/track-index + GSAP).
@@ -58,7 +57,7 @@ import { parseStoryboard } from "./lib/storyboard.mjs";
 import { parseFormat } from "./lib/dimensions.mjs";
 import { stageAssets } from "./lib/assets.mjs";
 import { parseColors, semanticColors } from "./lib/tokens.mjs";
-import { bgmDefaultVolume } from "../../media-use/audio/scripts/lib/bgm.mjs";
+import { bgmDefaultVolume } from "./lib/bgm-volume.mjs";
 
 // ---------- argv ----------
 const argv = process.argv.slice(2);
@@ -92,7 +91,10 @@ function ensureBgmCovers(relPath, hyperframesDir, total) {
   if (!Number.isFinite(dur) || dur <= 0)
     return { looped: false, short: false, reason: "unreadable duration" };
   if (dur >= total - 0.1) return { looped: false, short: false, dur }; // already covers
-  const relOut = relPath.replace(/\.([^./]+)$/, ".loop.$1");
+  // Always emit .mp3: the encode below is libmp3lame regardless of the source
+  // extension, so preserving relPath's own extension (e.g. "bgm.wav") would
+  // smuggle an MP3 stream into a .wav-named file (PRINFRA-309).
+  const relOut = relPath.replace(/\.([^./]+)$/, ".loop.mp3");
   const absOut = join(hyperframesDir, relOut);
   const fadeOut = Math.max(0, total - 1.5);
   const ff = spawnSync(

package/skills/faceless-explainer/scripts/assemble-index.test.mjs

@@ -1,18 +1,21 @@
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import test from "node:test";
 
 const assembleScript = new URL("./assemble-index.mjs", import.meta.url).pathname;
+const HAS_FFMPEG =
+  spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0 &&
+  spawnSync("ffprobe", ["-version"], { stdio: "ignore" }).status === 0;
 
 // ── bgm_pending at the assembly boundary ─────────────────────────────────────
 // Regression: the flag survived into audio_meta.json but assemble rebuilt its audio object
 // from three named keys and dropped it, so the step that actually builds the film could not
 // tell "not ready yet" from "silent by design" and would ship the silent one.
 
-function assembleWith({ audioMeta, extraArgs = [] }) {
+function assembleWith({ audioMeta, extraArgs = [], beforeAssemble }) {
   const dir = mkdtempSync(join(tmpdir(), "product-launch-assemble-"));
   writeFileSync(
     join(dir, "STORYBOARD.md"),
@@ -25,6 +28,7 @@ function assembleWith({ audioMeta, extraArgs = [] }) {
       '<section class="clip" data-start="0" data-duration="3"></section></div>',
   );
   if (audioMeta) writeFileSync(join(dir, "audio_meta.json"), JSON.stringify(audioMeta));
+  if (beforeAssemble) beforeAssemble(dir);
   const r = spawnSync(
     process.execPath,
     [
@@ -70,3 +74,54 @@ test("a film that is silent BY DESIGN still assembles untouched", () => {
   assert.equal(existsSync(join(dir, "index.html")), true);
   assert.doesNotMatch(r.stderr, /bgm_pending/);
 });
+
+// ── PRINFRA-309: loop-extended BGM must be a real .mp3, not MP3-in-a-.wav ────
+// ensureBgmCovers() always encodes the loop-extended track with libmp3lame — so a source
+// asset named "*.wav" that's short of TOTAL used to come out as MP3 audio inside a
+// .loop.wav-named file: decodes fine via ffprobe/ffmpeg/Chromium (which sniff the real
+// WAVE_FORMAT_MPEGLAYER3 tag), but hard-fails in any naive/strict WAV parser (e.g. Python's
+// stdlib `wave` module) that doesn't do full format-tag dispatch.
+test(
+  "loop-extended bgm is written as .mp3, not .loop.wav, even when the source is a .wav",
+  { skip: !HAS_FFMPEG },
+  () => {
+    const { dir, r } = assembleWith({
+      audioMeta: { bgm: { path: "assets/bgm/bed.wav" }, voices: [], sfx: [] },
+      beforeAssemble: (projectDir) => {
+        mkdirSync(join(projectDir, "assets", "bgm"), { recursive: true });
+        // 1s tone, well short of the 3s TOTAL from the single storyboard frame above —
+        // guarantees ensureBgmCovers() takes the loop-extend branch.
+        const gen = spawnSync(
+          "ffmpeg",
+          [
+            "-y",
+            "-f",
+            "lavfi",
+            "-i",
+            "sine=frequency=440:duration=1",
+            join(projectDir, "assets", "bgm", "bed.wav"),
+          ],
+          { encoding: "utf8" },
+        );
+        assert.equal(gen.status, 0, gen.stderr);
+      },
+    });
+
+    assert.equal(r.status, 0, r.stderr);
+    const html = readFileSync(join(dir, "index.html"), "utf8");
+    const bgmEl = html.match(/id="el-bgm"[\s\S]*?src="([^"]+)"/);
+    assert.ok(bgmEl, "expected a bgm <audio> element in index.html");
+    const bgmSrc = bgmEl[1];
+    assert.match(bgmSrc, /\.mp3$/, `bgm src should end in .mp3, got "${bgmSrc}"`);
+    assert.doesNotMatch(bgmSrc, /\.wav$/);
+
+    const outPath = join(dir, bgmSrc);
+    assert.equal(existsSync(outPath), true);
+    const probe = spawnSync(
+      "ffprobe",
+      ["-v", "error", "-show_entries", "stream=codec_name", "-of", "csv=p=0", "--", outPath],
+      { encoding: "utf8" },
+    );
+    assert.equal(probe.stdout.trim(), "mp3");
+  },
+);

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

@@ -173,6 +173,8 @@ function runGenerate(argv) {
       : { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
   };
   if (userVoice) request.voice = userVoice;
+  if (flag(argv, "tts-model", null)) request.tts_model = flag(argv, "tts-model", null);
+  if (flag(argv, "style", null)) request.style = flag(argv, "style", null);
 
   const neutral = neutralPath(outPath);
   runEngine({ request, hyperframesDir, neutral, only: "tts,bgm" }, die);

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

@@ -41,6 +41,8 @@ import {
   UA_DEFAULT_COLORS,
 } from "./lib/tokens.mjs";
 
+import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
 const flag = (name, def) => {
@@ -481,11 +483,12 @@ if (brandFonts.length) {
   const famOf = (f) =>
     fams.length === 1 ? fams[0] : ranked.find((x) => norm(f).includes(norm(x)));
   const outDir = join(hyperframesDir, "assets/fonts");
-  const faces = [];
-  const stagedNames = new Set();
+  const captured = stageCapturedFonts(hyperframesDir, fams);
+  const faces = [...captured.faces];
+  const stagedNames = new Set(captured.files);
   for (const { d, f } of files) {
     const fam = famOf(f);
-    if (!fam) continue;
+    if (!fam || captured.families.has(fam.toLowerCase())) continue;
     const { n, w } = weightInfo(f);
     const style = styleOf(f);
     const clean = `${fam.replace(/[^A-Za-z0-9]/g, "")}-${w}${style === "italic" ? "-Italic" : ""}.${extOf(f)}`;