dsh-hyperframes 0.9.1 → 0.9.2

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

@@ -1,127 +0,0 @@
-import assert from "node:assert/strict";
-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 = [], beforeAssemble }) {
-  const dir = mkdtempSync(join(tmpdir(), "product-launch-assemble-"));
-  writeFileSync(
-    join(dir, "STORYBOARD.md"),
-    "---\nformat: 1920x1080\nmessage: T\n---\n\n## Frame 1 — A\n- duration: 3s\n- src: compositions/frames/01-a.html\n",
-  );
-  mkdirSync(join(dir, "compositions", "frames"), { recursive: true });
-  writeFileSync(
-    join(dir, "compositions", "frames", "01-a.html"),
-    '<div data-composition-id="01-a" data-width="1920" data-height="1080">' +
-      '<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,
-    [
-      assembleScript,
-      "--storyboard",
-      join(dir, "STORYBOARD.md"),
-      "--hyperframes",
-      dir,
-      ...extraArgs,
-    ],
-    { encoding: "utf8" },
-  );
-  return { dir, r };
-}
-
-test("assemble REFUSES while bgm_pending and no bed on disk", () => {
-  const { dir, r } = assembleWith({
-    audioMeta: { bgm: null, bgm_pending: true, voices: [], sfx: [] },
-  });
-
-  assert.notEqual(r.status, 0, "should not assemble a silent film over a pending bed");
-  assert.match(r.stderr, /bgm_pending/);
-  // Refusing means producing nothing, not a half-built index.
-  assert.equal(existsSync(join(dir, "index.html")), false);
-});
-
-test("--allow-pending-bgm assembles anyway, and says so", () => {
-  const { dir, r } = assembleWith({
-    audioMeta: { bgm: null, bgm_pending: true, voices: [], sfx: [] },
-    extraArgs: ["--allow-pending-bgm"],
-  });
-
-  assert.equal(r.status, 0, r.stderr);
-  assert.equal(existsSync(join(dir, "index.html")), true);
-  assert.match(r.stdout + r.stderr, /pending/i);
-});
-
-test("a film that is silent BY DESIGN still assembles untouched", () => {
-  // The whole point of carrying the flag: this case must stay distinguishable from the above.
-  const { dir, r } = assembleWith({ audioMeta: { bgm: null, voices: [], sfx: [] } });
-
-  assert.equal(r.status, 0, r.stderr);
-  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

@@ -1,293 +0,0 @@
-#!/usr/bin/env node
-// audio.mjs — audio ADAPTER (reuses the product-launch SCRIPT.md / STORYBOARD.md
-// model; this file is intentionally identical across the reusing skills). The
-// TTS / BGM / SFX implementation
-// no longer lives here: it is the shared engine at
-// ../../media-use/audio/scripts/audio.mjs. This file only (a) maps the
-// product-launch model (SCRIPT.md frames + STORYBOARD.md music/sfx) into the
-// engine's neutral audio_request.json, (b) converts the engine's id-keyed
-// audio_meta back into the frame-keyed shape captions.mjs / assemble-index.mjs
-// already consume, and (c) keeps the local `sync-durations` pass (it rewrites
-// STORYBOARD.md, which is product-launch-specific).
-//
-// Three modes (unchanged CLI surface):
-//   (default) generate — engine --only tts,bgm. BGM mode is "retrieve" (strict:
-//        no HeyGen credential ⇒ skip, never a detached generate, since this
-//        workflow has no wait-bgm step). Runs in the background during Step 4.
-//   sync-durations — write real voice durations into STORYBOARD.md (local).
-//   fetch-sfx      — engine --only sfx, merged into the existing meta (Step 5,
-//        after the frames' `sfx:` cues exist).
-//
-//   node audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json
-//   node audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
-//   node audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
-
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseStoryboard } from "./lib/storyboard.mjs";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_ENGINE = join(HERE, "..", "..", "media-use", "audio", "scripts", "audio.mjs");
-
-const flag = (argv, name, def) => {
-  const i = argv.indexOf(`--${name}`);
-  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
-};
-const pad2 = (n) => String(n).padStart(2, "0");
-
-// SCRIPT.md → [{ frame, text }]. `## … (Frame N)` opens a line; `**key:**` rows
-// are metadata; the indented block is the spoken text (the only TTS input).
-function parseScript(md) {
-  const out = [];
-  let cur = null;
-  const flush = () => {
-    if (cur && cur.text.trim()) out.push({ frame: cur.frame, text: cur.text.trim() });
-    cur = null;
-  };
-  for (const line of md.split(/\r?\n/)) {
-    const h = line.match(/^#{2,3}\s+.*?\(frame\s+(\d+)\)/i);
-    if (h) {
-      flush();
-      cur = { frame: Number(h[1]), text: "" };
-      continue;
-    }
-    if (!cur) continue;
-    if (/^\s*\*\*/.test(line)) continue;
-    const m = line.match(/^(?: {4,}|\t)(.+)$/);
-    if (m) cur.text += (cur.text ? " " : "") + m[1].trim();
-  }
-  flush();
-  return out;
-}
-
-// Path of the engine's neutral meta — a stable sidecar so `--only` merges
-// (generate then fetch-sfx) accumulate, while audio_meta.json holds the PL shape.
-const neutralPath = (plOutPath) => join(dirname(plOutPath), "audio_engine_meta.json");
-
-// Run the shared engine. Returns nothing; dies on a non-zero exit.
-function runEngine({ request, hyperframesDir, neutral, only, extra = [] }, die) {
-  const reqPath = join(hyperframesDir, "audio_request.json");
-  writeFileSync(reqPath, JSON.stringify(request, null, 2));
-  const engine = process.env.HF_MEDIA_ENGINE || DEFAULT_ENGINE;
-  if (!existsSync(engine)) die(`media audio engine not found at ${engine} (set $HF_MEDIA_ENGINE)`);
-  const args = [
-    engine,
-    "--request",
-    reqPath,
-    "--hyperframes",
-    hyperframesDir,
-    "--out",
-    neutral,
-    "--only",
-    only,
-    ...extra,
-  ];
-  const r = spawnSync("node", args, { stdio: "inherit" });
-  if (r.status !== 0) die(`media audio engine exited ${r.status}`);
-}
-
-// Engine neutral meta (id-keyed) → product-launch meta (frame-keyed) consumed by
-// captions.mjs / assemble-index.mjs. id is the zero-padded frame number.
-function toProductLaunchMeta(neutral) {
-  const voices = (neutral.voices ?? []).map((v) => ({
-    frame: Number(v.id),
-    path: v.path,
-    duration_s: v.duration_s,
-    words: (v.words ?? []).map((w) => ({ id: w.id, text: w.text, start: w.start, end: w.end })),
-  }));
-  const bgm = neutral.bgm
-    ? {
-        path: neutral.bgm.path,
-        volume: neutral.bgm.volume,
-        query: neutral.bgm.query ?? null,
-        duration_s: neutral.bgm.duration_s ?? null,
-      }
-    : null;
-  // bgm_pending must survive the neutral → skill translation. A detached generate
-  // (Lyria/MusicGen) leaves `bgm: null, bgm_pending: true` until the track lands; dropping the
-  // flag makes "not ready yet" indistinguishable from "silent by design", so a later
-  // `fetch-sfx` snapshot turns a still-generating bed into no music at all with no signal.
-  const bgmPending = !!neutral.bgm_pending;
-  const sfx = (neutral.sfx ?? []).map((s) => ({
-    frame: Number(s.id),
-    file: s.file,
-    offset_s: s.offset_s ?? 0,
-    duration_s: s.duration_s ?? 1,
-    volume: s.volume ?? 0.35,
-  }));
-  return { bgm, bgm_pending: bgmPending, voices, sfx };
-}
-
-// ── generate (TTS + BGM) ────────────────────────────────────────────────────
-function runGenerate(argv) {
-  const die = (m) => {
-    console.error(`✗ audio generate: ${m}`);
-    process.exit(1);
-  };
-  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
-  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
-  const scriptPath = resolve(flag(argv, "script", join(hyperframesDir, "SCRIPT.md")));
-  const outPath = resolve(flag(argv, "out", join(hyperframesDir, "audio_meta.json")));
-  const userVoice = flag(argv, "voice", null);
-  const speed = Number(flag(argv, "speed", "1.0")) || 1.0;
-
-  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
-  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
-  const g = manifest.globals;
-
-  const lines = existsSync(scriptPath)
-    ? parseScript(readFileSync(scriptPath, "utf8")).map((l) => ({
-        id: pad2(l.frame),
-        text: l.text,
-      }))
-    : [];
-  // The canonical fully-silent marker (SKILL.md Step 3.1): `music: none` in
-  // the storyboard's top YAML block turns BGM off; combined with no SCRIPT.md
-  // the project is fully silent — generate nothing and remove any stale meta
-  // from a previous run (assemble treats an absent audio_meta.json as silent).
-  const bgmOff =
-    String(g.extra?.music ?? "")
-      .trim()
-      .toLowerCase() === "none";
-  if (bgmOff && !lines.length) {
-    rmSync(outPath, { force: true });
-    rmSync(neutralPath(outPath), { force: true });
-    console.log(
-      "✓ audio generate: project marked silent (music: none, no SCRIPT.md) — nothing to generate",
-    );
-    return;
-  }
-  if (!lines.length) console.error("· no SCRIPT.md — silent film (BGM only)");
-
-  // BGM mood: storyboard `music:` → message → arc → default. `mode: retrieve` is
-  // strict here (no wait-bgm step downstream).
-  const query = (g.extra && g.extra.music) || g.message || g.arc || "calm cinematic underscore";
-  const request = {
-    provider: "auto",
-    speed,
-    lines,
-    bgm: bgmOff
-      ? { mode: "none" }
-      : { 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);
-
-  const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8")));
-  writeFileSync(outPath, JSON.stringify(meta, null, 2));
-  console.log(
-    `✓ audio generate: ${meta.voices.length} voice + ${meta.bgm ? "1 bgm" : "no bgm"} → ${outPath}`,
-  );
-}
-
-// ── fetch-sfx ────────────────────────────────────────────────────────────────
-function runFetchSfx(argv) {
-  const die = (m) => {
-    console.error(`✗ audio fetch-sfx: ${m}`);
-    process.exit(1);
-  };
-  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
-  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
-  const outPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
-
-  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
-  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
-
-  // Per-frame `sfx:` cues (comma-separated) → engine lines carrying only sfx.
-  // `filter(Boolean)` alone is not enough: a storyboard that spells "no SFX here" as
-  // `sfx: none` reaches the engine as a cue literally NAMED "none", which then fails to
-  // resolve. The absence sentinels are part of the storyboard vocabulary, so drop them.
-  const SFX_NONE = new Set(["none", "no", "n/a", "na", "skip", "-", "—", "–"]);
-  const lines = [];
-  for (const f of manifest.frames) {
-    const names = (f.extra?.sfx ?? "")
-      .split(",")
-      .map((s) => s.trim())
-      .filter((s) => s && !SFX_NONE.has(s.toLowerCase()));
-    if (names.length && f.number != null) lines.push({ id: pad2(f.number), sfx: names });
-  }
-
-  const neutral = neutralPath(outPath);
-  const request = { lines, bgm: { mode: "none" } };
-  // --only sfx is a MERGE, not an overwrite: the engine reads the existing neutral
-  // sidecar (audio_engine_meta.json) and recomputes only the sfx section, so the
-  // voices/bgm written by the earlier generate (--only tts,bgm) pass are preserved.
-  runEngine({ request, hyperframesDir, neutral, only: "sfx" }, die);
-
-  const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8")));
-  writeFileSync(outPath, JSON.stringify(meta, null, 2));
-  console.log(`✓ audio fetch-sfx: ${meta.sfx.length} SFX cue(s) → ${outPath}`);
-  // This pass rewrites audio_meta.json from the neutral sidecar. If a detached BGM generate is
-  // still running, the bed it eventually writes is NOT folded back in — the snapshot we just
-  // took has no music. Say so instead of leaving a silent film behind.
-  if (meta.bgm_pending && !meta.bgm) {
-    console.warn(
-      "⚠ audio fetch-sfx: a detached BGM generate is still pending, so this snapshot has no bed. " +
-        "Re-run `fetch-sfx` (or re-point audio_meta.json at the track) once it lands, before assembling.",
-    );
-  }
-}
-
-// ── sync-durations (local; rewrites STORYBOARD.md) ────────────────────────────
-function runSyncDurations(argv) {
-  const die = (m) => {
-    console.error(`✗ audio sync-durations: ${m}`);
-    process.exit(1);
-  };
-  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
-  const audioMetaPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
-  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
-  if (!existsSync(audioMetaPath)) die(`audio_meta.json not found at ${audioMetaPath}`);
-
-  const meta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
-  const durByFrame = new Map();
-  for (const v of meta.voices ?? []) {
-    if (v.frame != null && v.duration_s) durByFrame.set(v.frame, v.duration_s);
-  }
-
-  // Read directly and handle ENOENT here, rather than an existsSync precheck —
-  // the check→write pair (write-back below) is a TOCTOU race CodeQL flags.
-  let storyboardRaw = "";
-  try {
-    storyboardRaw = readFileSync(storyboardPath, "utf8");
-  } catch {
-    die(`STORYBOARD.md not found at ${storyboardPath}`);
-  }
-  const lines = storyboardRaw.split(/\r?\n/);
-  const FRAME_RE = /^#{2,3}\s+(?:frame|beat|scene)\b.*?(\d+)/i;
-  let curFrame = null;
-  let updated = 0;
-  for (let i = 0; i < lines.length; i++) {
-    const h = lines[i].match(FRAME_RE);
-    if (h) {
-      curFrame = Number(h[1]);
-      continue;
-    }
-    if (curFrame != null && durByFrame.has(curFrame)) {
-      const m = lines[i].match(/^(\s*[-*]\s+duration\s*:\s*).*/i);
-      if (m) {
-        lines[i] = `${m[1]}${durByFrame.get(curFrame)}s`;
-        durByFrame.delete(curFrame);
-        updated++;
-      }
-    }
-  }
-  writeFileSync(storyboardPath, lines.join("\n"));
-  const missing = [...durByFrame.keys()];
-  console.log(
-    `✓ audio sync-durations: ${updated} frame duration(s) updated` +
-      (missing.length ? ` · no \`- duration:\` line for frame(s) ${missing.join(", ")}` : ""),
-  );
-}
-
-// ── dispatch ──────────────────────────────────────────────────────────────────
-const sub = process.argv[2];
-if (sub === "sync-durations") runSyncDurations(process.argv.slice(3));
-else if (sub === "fetch-sfx") runFetchSfx(process.argv.slice(3));
-else runGenerate(process.argv.slice(2)); // default: generate

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

@@ -1,176 +0,0 @@
-import assert from "node:assert/strict";
-import { existsSync, 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 script = new URL("./audio.mjs", import.meta.url).pathname;
-
-// The header of this adapter declares it "intentionally identical across the
-// reusing skills" — pin that contract so a fix landing in one copy can't
-// silently miss the other (the fully-silent marker bug did exactly that).
-test("audio.mjs is byte-identical to pr-to-video's copy (the stated contract)", () => {
-  const here = readFileSync(script, "utf8");
-  const sibling = readFileSync(
-    new URL("../../pr-to-video/scripts/audio.mjs", import.meta.url),
-    "utf8",
-  );
-  assert.equal(here, sibling);
-});
-
-// ── the canonical fully-silent marker (SKILL.md Step 3.1) ────────────────────
-// Same contract as product-launch (see its audio.test.mjs): `music: none` in
-// the storyboard's top YAML block + no SCRIPT.md ⇒ generate nothing; with
-// narration ⇒ TTS runs, BGM off.
-
-function runAudioRaw({ storyboard, scriptMd = null, preexistingMeta = null }) {
-  const dir = mkdtempSync(join(tmpdir(), "faceless-audio-"));
-  const engine = join(dir, "engine.mjs");
-  writeFileSync(join(dir, "STORYBOARD.md"), storyboard);
-  if (scriptMd != null) writeFileSync(join(dir, "SCRIPT.md"), scriptMd);
-  if (preexistingMeta != null) writeFileSync(join(dir, "audio_meta.json"), preexistingMeta);
-  writeFileSync(
-    engine,
-    `import { readFileSync, writeFileSync } from "node:fs";
-const argv = process.argv.slice(2);
-const flag = (name) => argv[argv.indexOf(name) + 1];
-const request = JSON.parse(readFileSync(flag("--request"), "utf8"));
-writeFileSync(new URL("request.json", import.meta.url), JSON.stringify(request));
-writeFileSync(flag("--out"), JSON.stringify({ voices: [], bgm: null, sfx: [] }));
-`,
-  );
-  const result = spawnSync(
-    process.execPath,
-    [script, "--hyperframes", dir, "--storyboard", join(dir, "STORYBOARD.md")],
-    { encoding: "utf8", env: { ...process.env, HF_MEDIA_ENGINE: engine } },
-  );
-  return { dir, result };
-}
-
-test("music: none + no SCRIPT.md = fully silent: no engine run, no audio_meta.json", () => {
-  const { dir, result } = runAudioRaw({ storyboard: "---\nmessage: Test\nmusic: none\n---\n" });
-
-  assert.equal(result.status, 0, result.stderr);
-  assert.match(result.stdout, /marked silent/);
-  assert.equal(existsSync(join(dir, "request.json")), false);
-  assert.equal(existsSync(join(dir, "audio_meta.json")), false);
-});
-
-test("fully-silent run removes stale audio_meta.json from a previous non-silent run", () => {
-  const { dir, result } = runAudioRaw({
-    storyboard: "---\nmessage: Test\nmusic: none\n---\n",
-    preexistingMeta: JSON.stringify({ bgm: { path: "old.mp3" }, voices: [], sfx: [] }),
-  });
-
-  assert.equal(result.status, 0, result.stderr);
-  assert.equal(existsSync(join(dir, "audio_meta.json")), false);
-});
-
-test("music: none with narration keeps TTS but turns BGM off (not fully silent)", () => {
-  const { dir, result } = runAudioRaw({
-    storyboard: "---\nmessage: Test\nmusic: none\n---\n",
-    scriptMd: "## Hook (Frame 1)\n\n    Spoken line for frame one.\n",
-  });
-
-  assert.equal(result.status, 0, result.stderr);
-  const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
-  assert.equal(request.bgm.mode, "none");
-  assert.equal(request.lines.length, 1);
-});
-
-test("a storyboard music mood still retrieves BGM (marker is exact, not fuzzy)", () => {
-  const { dir, result } = runAudioRaw({
-    storyboard: "---\nmessage: Test\nmusic: upbeat synthwave with heavy drums\n---\n",
-  });
-
-  assert.equal(result.status, 0, result.stderr);
-  const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
-  assert.equal(request.bgm.mode, "retrieve");
-  assert.equal(request.bgm.query, "upbeat synthwave with heavy drums");
-});
-
-// ── fetch-sfx ────────────────────────────────────────────────────────────────
-// Regressions found while running the full product-launch workflow end to end
-// (linear.app site showcase, 2026-07-30).
-
-/** Runs the fetch-sfx subcommand. `neutralOut` is what the stub engine writes to --out. */
-function runFetchSfx({ storyboard, neutralOut = { voices: [], bgm: null, sfx: [] } }) {
-  const dir = mkdtempSync(join(tmpdir(), "product-launch-sfx-"));
-  const engine = join(dir, "engine.mjs");
-  writeFileSync(join(dir, "STORYBOARD.md"), storyboard);
-  writeFileSync(
-    engine,
-    `import { readFileSync, writeFileSync } from "node:fs";
-const argv = process.argv.slice(2);
-const flag = (name) => argv[argv.indexOf(name) + 1];
-const request = JSON.parse(readFileSync(flag("--request"), "utf8"));
-writeFileSync(new URL("request.json", import.meta.url), JSON.stringify(request));
-writeFileSync(flag("--out"), ${JSON.stringify(JSON.stringify(neutralOut))});
-`,
-  );
-  const result = spawnSync(
-    process.execPath,
-    [script, "fetch-sfx", "--hyperframes", dir, "--storyboard", join(dir, "STORYBOARD.md")],
-    { encoding: "utf8", env: { ...process.env, HF_MEDIA_ENGINE: engine } },
-  );
-  return { dir, result };
-}
-
-const FRAME_WITH_SFX = (sfx) =>
-  `---\nmessage: Test\n---\n\n## Frame 1 — Hook\n- duration: 3s\n- sfx: ${sfx}\n`;
-
-test("fetch-sfx: `sfx: none` is an absence marker, not a cue named none", () => {
-  const { dir, result } = runFetchSfx({ storyboard: FRAME_WITH_SFX("none") });
-
-  assert.equal(result.status, 0, result.stderr);
-  const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
-  // Used to reach the engine as { sfx: ["none"] } — a cue that cannot resolve.
-  assert.deepEqual(request.lines, []);
-});
-
-test("fetch-sfx: the other absence spellings are markers too", () => {
-  for (const spelling of ["None", "n/a", "NA", "skip", "-", "—"]) {
-    const { dir, result } = runFetchSfx({ storyboard: FRAME_WITH_SFX(spelling) });
-    assert.equal(result.status, 0, result.stderr);
-    const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
-    assert.deepEqual(request.lines, [], `spelling: ${spelling}`);
-  }
-});
-
-test("fetch-sfx: a real cue still reaches the engine, and mixed lists drop only the marker", () => {
-  const { dir, result } = runFetchSfx({ storyboard: FRAME_WITH_SFX("whoosh, none, click") });
-
-  assert.equal(result.status, 0, result.stderr);
-  const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
-  assert.deepEqual(request.lines, [{ id: "01", sfx: ["whoosh", "click"] }]);
-});
-
-test("fetch-sfx: carries bgm_pending through and warns that the snapshot has no bed", () => {
-  const { dir, result } = runFetchSfx({
-    storyboard: FRAME_WITH_SFX("whoosh"),
-    // A detached Lyria/MusicGen generate that has not landed yet.
-    neutralOut: { voices: [], bgm: null, bgm_pending: true, sfx: [] },
-  });
-
-  assert.equal(result.status, 0, result.stderr);
-  const meta = JSON.parse(readFileSync(join(dir, "audio_meta.json"), "utf8"));
-  // The flag used to be dropped in the neutral → PL translation, making "not ready yet"
-  // indistinguishable from "silent by design".
-  assert.equal(meta.bgm_pending, true);
-  assert.equal(meta.bgm, null);
-  assert.match(result.stderr + result.stdout, /pending/i);
-});
-
-test("fetch-sfx: a resolved bed reports bgm_pending false and no warning", () => {
-  const { dir, result } = runFetchSfx({
-    storyboard: FRAME_WITH_SFX("whoosh"),
-    neutralOut: { voices: [], bgm: { path: "assets/bgm/track.mp3", volume: 0.12 }, sfx: [] },
-  });
-
-  assert.equal(result.status, 0, result.stderr);
-  const meta = JSON.parse(readFileSync(join(dir, "audio_meta.json"), "utf8"));
-  assert.equal(meta.bgm_pending, false);
-  assert.equal(meta.bgm.path, "assets/bgm/track.mp3");
-  assert.doesNotMatch(result.stderr, /pending/i);
-});