fix(capture,audio): three defects found running product-launch-video end to end

Found while running the full product-launch-video workflow twice against a real
site (linear.app) to verify PRs #2880/#2881/#2882. All three are independent of
those PRs.

**Scraped SVGs were unusable as files.** `assetDownloader` wrote an inline
`<svg>`'s `outerHTML` straight to `assets/svgs/*.svg`. An inline SVG inherits its
namespace from the HTML parser, so `outerHTML` omits `xmlns` — valid pasted back
into HTML, but not a standalone document, and `<img src="logo-abc.svg">` renders a
broken-image icon. That is exactly how these assets get consumed. `toStandaloneSvg`
now declares the namespace on the way to disk (plus `xmlns:xlink`, but only when an
`xlink:` attribute is actually used). The filename hash moved to the bytes that
land on disk so it still cannot drift from content.

**`sfx: none` became a cue named "none".** `fetch-sfx` split the storyboard's
`sfx:` list and dropped only empty strings, so the absence marker reached the
engine as a real cue that could not resolve. The absence spellings are part of the
storyboard vocabulary; drop them.

**`bgm_pending` was lost translating neutral meta to product-launch meta.** A
detached Lyria/MusicGen generate leaves `bgm: null, bgm_pending: true` until the
track lands. `toProductLaunchMeta` returned only `{bgm, voices, sfx}`, so "not
ready yet" became indistinguishable from "silent by design" — and because
`fetch-sfx` rewrites `audio_meta.json` from the sidecar, a still-generating bed was
snapshotted away with nothing to signal it. The flag now survives, and `fetch-sfx`
warns when it snapshots a pending bed instead of leaving a silent film that the
storyboard claims has music.

Not included, deliberately: `assemble-index.mjs` rewrites `index.html` wholesale
and so discards the block `transitions.mjs inject` wrote, meaning any Step 6 rework
silently loses transitions. Fixing that means deciding whether assemble preserves an
injected block or inject becomes re-appliable — it touches both scripts and the
Step 5/6 ordering in SKILL.md, so it deserves its own change.

Validation: `node --test skills/product-launch-video/scripts/audio.test.mjs`
(13 pass, 5 new) · `vitest run src/capture` (85 pass, 5 new) · `bun run lint:skills`
· oxlint/oxfmt clean · `tsc --noEmit` clean

Author: WaterrrForever

packages/cli/src/capture/assetDownloader.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { isPrivateUrl, safeFetch } from "./assetDownloader.js";
+import { isPrivateUrl, safeFetch, toStandaloneSvg } from "./assetDownloader.js";
 
 describe("isPrivateUrl — SSRF denylist (security: F-003)", () => {
   it("blocks loopback, private, and metadata IPv4", () => {
@@ -91,3 +91,39 @@ describe("safeFetch — re-validates the denylist on every redirect hop (securit
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
+
+describe("toStandaloneSvg — scraped inline SVGs must survive as .svg files", () => {
+  it("adds the SVG namespace that outerHTML omits for inline SVG", () => {
+    const inline = '<svg viewBox="0 0 24 24"><path d="M0 0h24v24H0z"/></svg>';
+    const out = toStandaloneSvg(inline);
+    expect(out).toContain('xmlns="http://www.w3.org/2000/svg"');
+    // Nothing else may change — the path geometry is the brand mark.
+    expect(out).toContain('<path d="M0 0h24v24H0z"/>');
+    expect(out.endsWith("</svg>")).toBe(true);
+  });
+
+  it("leaves an SVG that already declares xmlns untouched", () => {
+    const already = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><rect/></svg>';
+    expect(toStandaloneSvg(already)).toBe(already);
+  });
+
+  it("declares xmlns:xlink only when an xlink: attribute is actually used", () => {
+    const withXlink = '<svg viewBox="0 0 8 8"><use xlink:href="#a"/></svg>';
+    expect(toStandaloneSvg(withXlink)).toContain('xmlns:xlink="http://www.w3.org/1999/xlink"');
+    const without = '<svg viewBox="0 0 8 8"><use href="#a"/></svg>';
+    expect(toStandaloneSvg(without)).not.toContain("xmlns:xlink");
+  });
+
+  it("is idempotent and preserves attributes on the root", () => {
+    const inline = '<svg class="logo" width="120" height="24" fill="currentColor"><g/></svg>';
+    const once = toStandaloneSvg(inline);
+    expect(toStandaloneSvg(once)).toBe(once);
+    for (const attr of ['class="logo"', 'width="120"', 'height="24"', 'fill="currentColor"']) {
+      expect(once).toContain(attr);
+    }
+  });
+
+  it("returns non-SVG input unchanged rather than corrupting it", () => {
+    expect(toStandaloneSvg("<div>not an svg</div>")).toBe("<div>not an svg</div>");
+  });
+});

packages/cli/src/capture/assetDownloader.ts

@@ -17,6 +17,32 @@ function svgContentHashSlug(svgSource: string | Buffer, isLogo: boolean): string
   return isLogo ? `logo-${hash}` : `svg-${hash}`;
 }
 
+/**
+ * Make a scraped inline `<svg>` usable as a standalone `.svg` file.
+ *
+ * An inline SVG in an HTML document inherits the SVG namespace from the parser, so the DOM's
+ * `outerHTML` does not serialize `xmlns`. That string is fine pasted back into HTML but is NOT
+ * a valid standalone document: `<img src="logo-abc123.svg">` renders a broken-image icon, which
+ * is how these assets are actually consumed downstream. Declare the namespaces on the way to disk.
+ *
+ * `xlink:href` is deprecated but still emitted by plenty of sites; an undeclared `xlink:` prefix
+ * is a parse error in a standalone document, so declare that too — but only when it is used.
+ */
+export function toStandaloneSvg(outerHTML: string): string {
+  const open = outerHTML.match(/<svg\b[^>]*>/i);
+  if (!open) return outerHTML;
+  const original = open[0];
+  let tag = original;
+  const add: string[] = [];
+  if (!/\sxmlns\s*=/i.test(tag)) add.push('xmlns="http://www.w3.org/2000/svg"');
+  if (/\sxlink:[a-z-]+\s*=/i.test(outerHTML) && !/\sxmlns:xlink\s*=/i.test(tag)) {
+    add.push('xmlns:xlink="http://www.w3.org/1999/xlink"');
+  }
+  if (!add.length) return outerHTML;
+  tag = tag.replace(/^<svg\b/i, `<svg ${add.join(" ")}`);
+  return outerHTML.replace(original, tag);
+}
+
 export async function downloadAssets(
   tokens: DesignTokens,
   outputDir: string,
@@ -34,7 +60,9 @@ export async function downloadAssets(
   for (let i = 0; i < tokens.svgs.length && i < 30; i++) {
     const svg = tokens.svgs[i]!;
     if (!svg.outerHTML || svg.outerHTML.length < 50) continue;
-    const slug = svgContentHashSlug(svg.outerHTML, !!svg.isLogo);
+    // Hash the bytes that actually land on disk, so the filename still can't drift from content.
+    const svgFile = toStandaloneSvg(svg.outerHTML);
+    const slug = svgContentHashSlug(svgFile, !!svg.isLogo);
     let finalSlug = slug;
     let suffix = 2;
     while (usedSvgNames.has(finalSlug)) {
@@ -45,7 +73,7 @@ export async function downloadAssets(
     const name = `${finalSlug}.svg`;
     const localPath = `assets/svgs/${name}`;
     try {
-      writeFileSync(join(outputDir, localPath), svg.outerHTML, "utf-8");
+      writeFileSync(join(outputDir, localPath), svgFile, "utf-8");
       assets.push({ url: "", localPath, type: "svg" });
     } catch {
       /* skip */

skills-manifest.json

@@ -62,7 +62,7 @@
       "files": 29
     },
     "product-launch-video": {
-      "hash": "1a14737e16f6a154",
+      "hash": "6f2b690d22392425",
       "files": 26
     },
     "remotion-to-hyperframes": {

skills/product-launch-video/scripts/audio.mjs

@@ -103,14 +103,19 @@ function toProductLaunchMeta(neutral) {
         duration_s: neutral.bgm.duration_s ?? null,
       }
     : null;
+  // bgm_pending must survive the neutral → PL translation. A detached generate (Lyria/MusicGen)
+  // leaves `bgm: null, bgm_pending: true` until the track lands; dropping the flag made
+  // "not ready yet" indistinguishable from "silent by design", so a later `fetch-sfx` snapshot
+  // turned a still-generating bed into no music at all with nothing to signal it.
+  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, voices, sfx };
+  return { bgm, bgm_pending: bgmPending, voices, sfx };
 }
 
 // ── generate (TTS + BGM) ────────────────────────────────────────────────────
@@ -192,12 +197,16 @@ function runFetchSfx(argv) {
   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` used to reach the engine as a cue literally NAMED "none", which then failed
+  // 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(Boolean);
+      .filter((s) => s && !SFX_NONE.has(s.toLowerCase()));
     if (names.length && f.number != null) lines.push({ id: pad2(f.number), sfx: names });
   }
 
@@ -211,6 +220,16 @@ function runFetchSfx(argv) {
   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 that the storyboard claims has a
+  // bed (observed live: the caller had to notice on its own and rebuild the entry).
+  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) ────────────────────────────

skills/product-launch-video/scripts/audio.test.mjs

@@ -131,3 +131,88 @@ test("a storyboard music mood still retrieves BGM (marker is exact, not fuzzy)",
   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);
+});