@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/product-launch-video/scripts/captions.mjs

@@ -0,0 +1,508 @@
+#!/usr/bin/env node
+// captions.mjs — build the captions sub-composition from STORYBOARD + audio_meta.
+//
+// One mode: `build`. Reads STORYBOARD.md (frame order + durations → cumulative
+// frame starts) + audio_meta.json (voices[].words, frame-relative) → absolute-
+// timed caption groups → writes:
+//   compositions/captions.html  — a self-contained sub-composition the index
+//        assembler mounts on its captions track (data-composition-id="captions").
+//   caption_groups.json         — the computed groups (debug / inspection / --out).
+//   caption-overrides.json      — an empty `[]` shim (silences the captions runtime's
+//        validate-time fetch; only written when captions.html is).
+// No narration / no words → legal skip: nothing written, assemble-index then omits
+// the captions track (it keys off compositions/captions.html existence).
+//
+//   node captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json
+//
+// CAPTION LOOK — two sources, picked automatically:
+//   1. PRESET SKIN (preferred). If a project-local `.hyperframes/caption-skin.html`
+//      exists (Step 2 copies the chosen frame-preset's skin into the project), it is
+//      the caption look.
+//      It is a brand-token-strict skin with three reserved holes; this script fills them
+//      and wraps the result in a <template> for the engine:
+//        - `var GROUPS = [];`            → the computed caption groups
+//        - `var DURATION = 0;` + data-duration="0" (and data-width/height="0") → real values
+//        - `<style data-brand-tokens></style>` → :root tokens derived from the project's
+//          frame.md (colors + fonts), mapped to a fixed semantic vocab every skin shares:
+//          --cap-ink / --cap-canvas / --cap-accent / --cap-accent-2 / --font-display /
+//          --font-body, plus --cap-band-top / --cap-band-height (the keep-out band).
+//      So the brand-token overlay from Step 2 flows into the captions automatically.
+//   2. DEFAULT (fallback). No skin file → the built-in Roboto/black pill (buildCaptionsHtml).
+//
+// Grouping mirrors the proven heuristics (frame boundary · sentence-end punct ·
+// silence gap · density-aware word cap); word timings come inline from audio_meta.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseStoryboard } from "./lib/storyboard.mjs";
+import { captionBand, parseFormat } from "./lib/dimensions.mjs";
+import { parseColors, parseFonts, semanticColors, lum } from "./lib/tokens.mjs";
+
+const flag = (argv, name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+const r3 = (x) => Number(x.toFixed(3));
+
+// ── grouping params ───────────────────────────────────────────────────────────
+const SILENCE_GAP = 0.18; // s of silence between words → split
+const TAIL_PAD = 0.12; // s the group lingers after its last word
+const SENT_END = /[.?!,;:—]$/;
+const DENSITY_WINDOW = 1.0; // s window for words/sec density
+function wordCap(density) {
+  return density > 3.5 ? 2 : density > 2.5 ? 3 : 4;
+}
+
+function runBuild(argv) {
+  const skip = (reason) => {
+    console.log(`captions: skipped (${reason})`);
+    process.exit(0);
+  };
+  const die = (m) => {
+    console.error(`✗ captions build: ${m}`);
+    process.exit(1);
+  };
+
+  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
+  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
+  const audioMetaPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
+  const outPath = resolve(flag(argv, "out", join(hyperframesDir, "caption_groups.json")));
+  const htmlPath = join(hyperframesDir, "compositions/captions.html");
+  const overridesPath = join(hyperframesDir, "caption-overrides.json");
+  const skinArg = flag(argv, "skin", null);
+  const hiddenSkinPath = join(hyperframesDir, ".hyperframes", "caption-skin.html");
+  const legacySkinPath = join(hyperframesDir, "caption-skin.html");
+  const skinPath = resolve(
+    skinArg ?? (existsSync(hiddenSkinPath) ? hiddenSkinPath : legacySkinPath),
+  );
+  const framePath = resolve(flag(argv, "frame", join(hyperframesDir, "frame.md")));
+
+  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
+  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
+  const { width: W, height: H } = parseFormat(manifest.globals.format);
+
+  if (!existsSync(audioMetaPath)) skip("no audio_meta.json (silent film)");
+  const meta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
+  if (!Array.isArray(meta.voices) || meta.voices.length === 0) skip("no narration");
+
+  // cumulative frame starts (by frame number) + total duration, from STORYBOARD.
+  const startByFrame = new Map();
+  let acc = 0;
+  for (const f of manifest.frames) {
+    if (f.number != null) startByFrame.set(f.number, acc);
+    acc += Number.isFinite(f.durationSeconds) ? f.durationSeconds : 0;
+  }
+  const total = r3(acc);
+
+  // absolute word stream: frame start + frame-relative word timing.
+  const words = [];
+  for (const v of meta.voices) {
+    const base = startByFrame.get(v.frame);
+    if (base == null || !Array.isArray(v.words)) continue;
+    for (const w of v.words) {
+      const text = String(w.text ?? "").trim();
+      if (!text || /^[.?!,;:—–-]+$/.test(text)) continue; // drop empties + bare punctuation
+      if (!isFinite(w.start) || !isFinite(w.end)) continue;
+      words.push({ text, start: r3(base + w.start), end: r3(base + w.end), frame: v.frame });
+    }
+  }
+  words.sort((a, b) => a.start - b.start);
+  if (words.length === 0) skip("no usable words");
+
+  // density at i = words whose start falls within [w.start, w.start + WINDOW).
+  const densityAt = (i) => {
+    const t0 = words[i].start;
+    let n = 0;
+    for (let j = i; j < words.length && words[j].start < t0 + DENSITY_WINDOW; j++) n++;
+    return n / DENSITY_WINDOW;
+  };
+
+  // group: split on frame change / silence gap / word cap; always flush after a
+  // sentence-ending word.
+  const groups = [];
+  let cur = null;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    const prev = cur && cur.words[cur.words.length - 1];
+    const crossFrame = cur && w.frame !== cur.frame;
+    const gap = prev && w.start - prev.end > SILENCE_GAP;
+    const full = cur && cur.words.length >= cur.cap;
+    if (!cur || crossFrame || gap || full) {
+      if (cur) groups.push(cur);
+      cur = { frame: w.frame, cap: wordCap(densityAt(i)), words: [] };
+    }
+    cur.words.push(w);
+    if (SENT_END.test(w.text)) {
+      groups.push(cur);
+      cur = null;
+    }
+  }
+  if (cur) groups.push(cur);
+
+  // finalize: ids, start/end (tail-padded, clamped < next group's start), text.
+  const finalized = groups.map((g, gi) => {
+    const first = g.words[0];
+    const last = g.words[g.words.length - 1];
+    const next = groups[gi + 1];
+    let end = r3(last.end + TAIL_PAD);
+    if (next && next.words[0].start < end) end = r3(next.words[0].start);
+    return {
+      id: `caption-group-${gi}`,
+      frame: g.frame,
+      start: r3(first.start),
+      end,
+      text: g.words.map((w) => w.text).join(" "),
+      words: g.words.map((w, wi) => ({
+        id: `caption-word-${gi}-${wi}`,
+        text: w.text,
+        start: r3(w.start),
+        end: r3(w.end),
+      })),
+    };
+  });
+
+  // ── write caption_groups.json ──
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(
+    outPath,
+    JSON.stringify({ total_duration_s: total, width: W, height: H, groups: finalized }, null, 2),
+  );
+
+  // ── write compositions/captions.html (preset skin if present, else default) ──
+  mkdirSync(dirname(htmlPath), { recursive: true });
+  let source;
+  if (existsSync(skinPath)) {
+    const tokens = frameTokensCss(framePath, H);
+    const faces = brandFontFaces(framePath, hyperframesDir);
+    const fonts = existsSync(framePath) ? parseFonts(readFileSync(framePath, "utf8")) : {};
+    writeFileSync(
+      htmlPath,
+      buildFromSkin(
+        readFileSync(skinPath, "utf8"),
+        finalized,
+        total,
+        W,
+        H,
+        tokens,
+        die,
+        faces,
+        fonts,
+      ),
+    );
+    source = `preset skin (${skinPath.replace(hyperframesDir + "/", "")})`;
+  } else {
+    writeFileSync(htmlPath, buildCaptionsHtml(finalized, total, W, H));
+    source = "default (built-in pill)";
+  }
+
+  // ── write caption-overrides.json shim ──
+  // Atomic create-if-absent: `wx` throws if the file already exists (which we
+  // ignore) — no existsSync→writeFileSync TOCTOU gap.
+  try {
+    writeFileSync(overridesPath, "[]\n", { flag: "wx" });
+  } catch {
+    /* overrides shim already present */
+  }
+
+  console.log(
+    `✓ captions build: ${finalized.length} group(s) from ${words.length} words → compositions/captions.html (total ${total}s) · skin: ${source}`,
+  );
+}
+
+// ── preset-skin path ────────────────────────────────────────────────────────
+// Fill the skin's three reserved holes + the root's 0-placeholders, then wrap the
+// fragment in a <template> (the engine clones template contents only). One generic
+// fill works for every preset's skin — no per-skin transform.
+//
+// Every preset's skin is authored against ITS OWN fonts/metrics (broadside→Barlow @
+// line-height 1.02, capsule→Bodoni, …). When the project's brand font differs (it
+// almost always does), three things must be reconciled so ANY skin renders correctly
+// for ANY brand — done here generically, not per-project:
+//   · @font-face for the brand fonts (else the renderer can't supply them → fallback)
+//   · the skin's preset-font FALLBACK literals (var(--font-x, "Barlow")) repointed to
+//     the brand family, so no undeclared font name trips font_family_without_font_face
+//   · a metric safety net: a heavier brand font overflows a tight preset line-height,
+//     so the active-word highlight clips — a line-height floor + word padding fixes it
+//   · data-composition-id + dimensions on the <template> root (skins lead with
+//     <script>/<style>, so the root element must carry the id, not the first child)
+function buildFromSkin(skin, groups, total, W, H, tokens, die, faces = "", fonts = {}) {
+  const fillOnce = (src, re, repl, label) => {
+    const n = (src.match(re) || []).length;
+    if (n !== 1) die(`caption-skin.html: expected exactly one ${label}, found ${n}`);
+    return src.replace(re, () => repl);
+  };
+  let out = skin;
+  // Strip HTML doc-comments first. A skin's authoring comment can contain tag-like text
+  // (broadside's literally says "<template>"), which the linter's tag scanner then picks
+  // up as the root element → false root_missing_composition_id / root_missing_dimensions.
+  // The comments are preview/authoring docs, not needed in the generated composition.
+  // Strip in a fixpoint loop, not a single global pass: removing one comment can
+  // re-form a marker from a nested/partial pair (e.g. <!--<!---->-->), which one
+  // pass misses — CodeQL flags the single replace as incomplete sanitization.
+  for (let prev = ""; prev !== out; ) {
+    prev = out;
+    out = out.replace(/<!--[\s\S]*?-->/g, "");
+  }
+  // brand :root tokens + @font-face for the brand fonts, both into the reserved hole
+  out = fillOnce(
+    out,
+    /<style data-brand-tokens>\s*<\/style>/,
+    `<style data-brand-tokens>\n${faces ? faces + "\n" : ""}${tokens}\n    </style>`,
+    "<style data-brand-tokens></style> hole",
+  );
+  // Resolve the skin's font-family var()s to the brand family LITERAL. Two reasons:
+  //  (1) the linter's used-font scanner naively comma-splits, so var(--x, "Brand") yields
+  //      junk tokens ('var(--x', 'brand")') that never match the @font-face → a false
+  //      font_family_without_font_face; a plain "Brand" literal matches the @font-face.
+  //  (2) it drops the preset's own fallback name (Barlow / IBM Plex Mono / …), which has
+  //      no @font-face in this project. The :root token stays for any other consumer.
+  if (fonts.display)
+    out = out.replace(/var\(\s*--font-display\s*(?:,\s*"[^"]*"\s*)?\)/g, fonts.display);
+  if (fonts.body) out = out.replace(/var\(\s*--font-body\s*(?:,\s*"[^"]*"\s*)?\)/g, fonts.body);
+  out = fillOnce(
+    out,
+    /var GROUPS = \[\];/,
+    `var GROUPS = ${JSON.stringify(groups)};`,
+    "`var GROUPS = [];` hole",
+  );
+  out = fillOnce(out, /var DURATION = 0;/, `var DURATION = ${total};`, "`var DURATION = 0;` hole");
+  out = fillOnce(out, /data-duration="0"/, `data-duration="${total}"`, '`data-duration="0"` hole');
+  out = fillOnce(out, /data-width="0"/, `data-width="${W}"`, '`data-width="0"` hole');
+  out = fillOnce(out, /data-height="0"/, `data-height="${H}"`, '`data-height="0"` hole');
+  // font-robust safety net — appended last so it wins the cascade over the skin's own
+  // (preset-font-tuned) line-height. Kept SNUG (1.1) so the plate hugs the text. NO extra
+  // word/pill padding: inspect's `text_box_overflow` on the highlight words is a cosmetic
+  // false-positive here (heavy-glyph ink slightly exceeds the line box, but there's no
+  // overflow:hidden — nothing is clipped); zeroing it would need an airy line-height that
+  // balloons the pill, which is worse. Override only if a brand font genuinely clips.
+  out += "\n<style>\n  .caption-line { line-height: 1.1 !important; }\n</style>";
+  // dark-ground caption contrast (auto). The preset caption skins are tuned for a LIGHT
+  // pill (cream); on a dark brand ground the pill goes near-black, so the skin's faint
+  // upcoming-word mix and light highlight block turn unreadable. When the resolved caption
+  // canvas is dark, override the three word states: a brighter muted upcoming color + an
+  // on-brand ACCENT highlight block with light text. Light grounds are left untouched.
+  const capCanvas = (tokens.match(/--cap-canvas:\s*(#[0-9a-fA-F]{6})/) || [])[1];
+  if (capCanvas && (lum(capCanvas) ?? 255) < 90) {
+    out +=
+      "\n<style>\n" +
+      "  .caption-word { color: color-mix(in srgb, var(--cap-ink) 64%, var(--cap-canvas)); }\n" +
+      "  .caption-word.is-active { color: var(--cap-ink); background: var(--cap-accent); box-shadow: 0 0 0 0.06em var(--cap-accent); }\n" +
+      "  .caption-word.is-spoken { color: var(--cap-ink); background: transparent; box-shadow: none; }\n" +
+      "</style>";
+  }
+  return `<template id="captions-template" data-composition-id="captions" data-width="${W}" data-height="${H}">\n${out.trim()}\n</template>\n`;
+}
+
+// @font-face for the brand display/body fonts, matched from the project's font dirs
+// (staged assets/fonts first, else capture/assets/fonts) by family-name prefix, with
+// weight parsed from the filename. Paths are relative to compositions/captions.html.
+// Returns "" when frame.md or font files are absent (then the skin's fallback applies).
+function brandFontFaces(framePath, hyperframesDir) {
+  if (!existsSync(framePath)) return "";
+  const { display, body } = parseFonts(readFileSync(framePath, "utf8"));
+  const families = [
+    ...new Set([display, body].filter(Boolean).map((f) => f.replace(/^"|"$/g, ""))),
+  ];
+  if (!families.length) return "";
+  const dirs = [
+    // ROOT-RELATIVE — compositions are served with the project root as their base URL, so a
+    // "../" prefix escapes the root (lint: invalid_parent_traversal_in_asset_path) and 404s in
+    // Studio/preview. Mirror what the frame workers use for images.
+    { abs: join(hyperframesDir, "assets/fonts"), rel: "assets/fonts" },
+    { abs: join(hyperframesDir, "capture/assets/fonts"), rel: "capture/assets/fonts" },
+  ].filter((d) => existsSync(d.abs));
+  const weightOf = (n) => {
+    const s = n.toLowerCase();
+    if (/black|heavy|ultra|extrabold/.test(s)) return 800;
+    if (/semibold|demibold/.test(s)) return 600; // before /bold/ — "demibold" contains "bold"
+    if (/bold/.test(s)) return 700;
+    if (/medium/.test(s)) return 500;
+    if (/light|thin/.test(s)) return 300;
+    return 400; // book / regular / roman
+  };
+  const fmtOf = (f) =>
+    /\.woff2$/i.test(f)
+      ? "woff2"
+      : /\.woff$/i.test(f)
+        ? "woff"
+        : /\.ttf$/i.test(f)
+          ? "truetype"
+          : "opentype";
+  // Normalize away ALL non-alphanumerics (spaces, underscores, hyphens) on BOTH the
+  // family name and the filename. Real font files use "_" / "-" as word separators
+  // ("TT_Norms_Pro_Bold.woff2"), so stripping only whitespace never matched them — the
+  // family key "ttnormspro" failed `startsWith` against "tt_norms_pro_bold", and the
+  // function silently returned "" → captions shipped with NO @font-face for any
+  // 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 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
+  // belong to "TT Norms Pro Mono" (its key is a prefix of the longer one's).
+  const ranked = [...families].sort((a, b) => norm(b).length - norm(a).length);
+  for (const fam of ranked) {
+    const key = norm(fam);
+    for (const d of dirs) {
+      let files = [];
+      try {
+        files = readdirSync(d.abs);
+      } catch {
+        continue;
+      }
+      for (const f of files.sort()) {
+        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;
+        const w = weightOf(f);
+        const dedup = `${fam}-${w}`;
+        if (seen.has(dedup)) continue; // one src per weight; 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-display: block; }`,
+        );
+      }
+    }
+  }
+  // Loud signal instead of a silent "". If frame.md named a brand font but no file
+  // matched, the caption text WILL fall back to a generic font in the render — surface
+  // the cause here (at build time) rather than letting it surface 2 steps later as a
+  // font_family_without_font_face lint error disconnected from its root cause.
+  if (!faces.length) {
+    const where = dirs.length
+      ? dirs.map((d) => d.rel).join(" / ")
+      : "assets/fonts or capture/assets/fonts (neither exists)";
+    console.warn(
+      `  ⚠ captions: frame.md names font ${families.map((f) => `"${f}"`).join(", ")} ` +
+        `but no matching .woff2/.woff/.ttf/.otf was found in ${where} — captions will fall back ` +
+        `(text may render in the wrong font). Stage a font file whose name starts with the family ` +
+        `(e.g. "TT Norms Pro" → TT_Norms_Pro_Bold.woff2) so it ships with the project.`,
+    );
+  }
+  return faces.join("\n");
+}
+
+// frame.md colors:/typography: → a :root token block, mapped to the fixed semantic
+// vocab every preset skin references. Robust to per-preset key names: colors are
+// matched by name, then by luminance. Brand-token overlay (Step 2) flows through
+// because the values come from the project's frame.md. No frame.md → band vars only.
+function frameTokensCss(framePath, H) {
+  const band = captionBand(H);
+  const out = [];
+  if (existsSync(framePath)) {
+    const md = readFileSync(framePath, "utf8");
+    const colors = parseColors(md);
+    for (const [k, v] of colors) out.push(`      --${k}: ${v};`); // raw, for completeness
+    const sem = semanticColors(colors);
+    if (sem.ink) out.push(`      --cap-ink: ${sem.ink};`);
+    if (sem.canvas) out.push(`      --cap-canvas: ${sem.canvas};`);
+    if (sem.accent) out.push(`      --cap-accent: ${sem.accent};`);
+    if (sem.accent2) out.push(`      --cap-accent-2: ${sem.accent2};`);
+    const { display, body } = parseFonts(md);
+    if (display) out.push(`      --font-display: ${display}, system-ui, serif;`);
+    if (body) out.push(`      --font-body: ${body}, system-ui, sans-serif;`);
+  }
+  out.push(`      --cap-band-top: ${band.bandTopY}px;`);
+  out.push(`      --cap-band-height: ${band.bandHeight}px;`);
+  return `      :root {\n${out.join("\n")}\n      }`;
+}
+
+// ── default path (no preset skin) ─────────────────────────────────────────────
+// Self-contained captions sub-composition. The <template> holds the band container
+// + style AND the <script> (the HyperFrames loader only executes scripts INSIDE the
+// cloned template — a sibling <script> after </template> never runs, so the timeline
+// never registers and captions render blank). The script builds per-word spans and a
+// paused, seek-safe GSAP timeline (opacity for group show/hide, a quick color tween
+// per word for the karaoke highlight — no className flips, no JS state) and ends each
+// group with a hard tl.set kill so an exit can't get stuck. gsap is loaded via CDN
+// inside the template (matching the frame compositions). Band = captionBand(H).
+function buildCaptionsHtml(groups, total, W, H) {
+  const band = captionBand(H);
+  const fs = Math.round(H * 0.038);
+  const pad = Math.round(fs * 0.4);
+  return `<template id="captions-template">
+  <div
+    data-composition-id="captions"
+    data-width="${W}"
+    data-height="${H}"
+    data-duration="${total}"
+    id="captions-root"
+  >
+    <div id="cap"></div>
+  </div>
+  <style>
+    #captions-root {
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+    }
+#cap {
+      position: absolute;
+      left: 0;
+      right: 0;
+      top: ${band.bandTopY}px;
+      height: ${band.bandHeight}px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+.caption-group {
+      position: absolute;
+      max-width: 80%;
+      padding: ${pad}px ${Math.round(pad * 1.8)}px;
+      background: rgba(0, 0, 0, 0.72);
+      border-radius: ${Math.round(fs * 0.3)}px;
+      font-family: Roboto, sans-serif;
+      font-weight: 700;
+      font-size: ${fs}px;
+      line-height: 1.25;
+      text-align: center;
+      color: #fff;
+      opacity: 0;
+    }
+.caption-word {
+      color: rgba(255, 255, 255, 0.55);
+    }
+  </style>
+  <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 cap = document.getElementById("cap");
+      var tl = gsap.timeline({ paused: true });
+      GROUPS.forEach(function (g) {
+        var el = document.createElement("div");
+        el.className = "caption-group";
+        g.words.forEach(function (w) {
+          var s = document.createElement("span");
+          s.className = "caption-word";
+          s.textContent = w.text + " ";
+          el.appendChild(s);
+        });
+        cap.appendChild(el);
+        tl.fromTo(el, { opacity: 0 }, { opacity: 1, duration: 0.18, overwrite: "auto" }, g.start);
+        tl.to(el, { opacity: 0, duration: 0.12, overwrite: "auto" }, g.end);
+        tl.set(el, { opacity: 0, visibility: "hidden" }, g.end + 0.12); // deterministic hard kill
+        g.words.forEach(function (w, i) {
+          tl.to(el.children[i], { color: "#ffffff", duration: 0.06 }, w.start);
+        });
+      });
+      tl.to({}, { duration: ${total} }, 0); // full-span anchor
+      window.__timelines = window.__timelines || {};
+      window.__timelines["captions"] = tl;
+    })();
+  </script>
+</template>
+`;
+}
+
+const sub = process.argv[2];
+if (sub === "build" || sub === undefined) runBuild(process.argv.slice(sub === "build" ? 3 : 2));
+else {
+  console.error(
+    "usage: node captions.mjs build [--storyboard …] [--audio-meta …] [--hyperframes .]",
+  );
+  process.exit(2);
+}

package/.agents/skills/product-launch-video/scripts/lib/assets.mjs

@@ -0,0 +1,55 @@
+// assets.mjs — stage frame-named capture assets into assets/.
+// Shared by stage-assets.mjs (Step 4 close, BEFORE the frame workers run) and
+// assemble-index.mjs (Step 5, idempotent backstop). Only assets a frame names
+// in `asset_candidates` are staged; unnamed assets never reach the project.
+// asset_candidates value form: "assets/<basename> — desc; assets/… — …".
+
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export function basenamesFromCandidates(value) {
+  if (typeof value !== "string") return [];
+  return value
+    .split(";")
+    .map((seg) => seg.split(/\s+[—–-]\s+/)[0].trim()) // strip the " — description"
+    .filter(Boolean)
+    .map((p) => basename(p.replace(/^assets\//, "")));
+}
+
+// Copy each frame's asset_candidates from capture/{assets,assets/videos,
+// screenshots} into assets/. Already-staged files are left as is (first-wins),
+// so calling this twice is safe. Returns { staged, wanted, anomalies }.
+export function stageAssets({ hyperframesDir, frames }) {
+  const wanted = new Set();
+  for (const f of frames) {
+    for (const b of basenamesFromCandidates(f.extra?.asset_candidates)) wanted.add(b);
+  }
+  const captureDirs = [
+    join(hyperframesDir, "capture/assets"),
+    join(hyperframesDir, "capture/assets/videos"), // videos download into a subdir
+    join(hyperframesDir, "capture/screenshots"),
+  ];
+  const assetsDir = join(hyperframesDir, "assets");
+  const anomalies = [];
+  let staged = 0;
+  if (wanted.size > 0) {
+    mkdirSync(assetsDir, { recursive: true });
+    for (const b of wanted) {
+      const dest = join(assetsDir, b);
+      if (existsSync(dest)) {
+        staged++;
+        continue;
+      } // first-wins / already staged
+      const src = captureDirs.map((d) => join(d, b)).find((p) => existsSync(p));
+      if (src) {
+        copyFileSync(src, dest);
+        staged++;
+      } else {
+        anomalies.push(
+          `asset "${b}" named by a frame but not found under capture/ — frame will 404 it`,
+        );
+      }
+    }
+  }
+  return { staged, wanted, anomalies };
+}

package/.agents/skills/product-launch-video/scripts/lib/dimensions.mjs

@@ -0,0 +1,45 @@
+// dimensions.mjs — canvas size + caption-band geometry for the product-launch
+// pipeline. Single source of truth = the STORYBOARD frontmatter `format` global
+// ("1920x1080" / "1080x1920" / "1080x1080", or a named orientation). Every
+// script and the index assembler reads the size from here; none hardcodes it.
+
+// Named orientation presets. Square/portrait are 1080-based so they share the
+// long-edge pixel budget with landscape (same render-cost ballpark).
+export const ORIENTATION_PRESETS = {
+  landscape: { width: 1920, height: 1080 }, // 16:9 — default
+  portrait: { width: 1080, height: 1920 }, // 9:16 — reels / shorts / TikTok
+  square: { width: 1080, height: 1080 }, // 1:1 — feed
+};
+
+export const DEFAULT_DIMENSIONS = ORIENTATION_PRESETS.landscape;
+
+function sane(w, h) {
+  return Number.isFinite(w) && Number.isFinite(h) && w >= 240 && h >= 240 && w <= 8192 && h <= 8192;
+}
+
+// Parse a STORYBOARD `format` global into { width, height, source }. Accepts
+// "WxH" (e.g. "1920x1080"; `x` or `×`, any inner spacing) or a named orientation;
+// falls back to landscape so a storyboard with a missing/garbled format still
+// renders (no behavior change vs the old landscape lock).
+export function parseFormat(format) {
+  const s = typeof format === "string" ? format.trim().toLowerCase() : "";
+  if (ORIENTATION_PRESETS[s]) return { ...ORIENTATION_PRESETS[s], source: `orientation=${s}` };
+  const m = s.match(/^(\d+)\s*[x×]\s*(\d+)$/);
+  if (m) {
+    const w = parseInt(m[1] ?? "", 10);
+    const h = parseInt(m[2] ?? "", 10);
+    if (sane(w, h)) return { width: w, height: h, source: "format" };
+  }
+  return { ...DEFAULT_DIMENSIONS, source: "default(landscape)" };
+}
+
+// Caption band geometry, derived from canvas height: the bottom ~16.67% (180px
+// at h=1080). Frame content must end `safetyPx` above the band top. Holds even
+// when captions are disabled (bottom-edge consistency).
+export const CAPTION_BAND_FRACTION = 0.1667;
+export function captionBand(height, safetyPx = 20) {
+  const h = Number.isFinite(height) ? height : DEFAULT_DIMENSIONS.height;
+  const bandHeight = Math.round(h * CAPTION_BAND_FRACTION);
+  const bandTopY = h - bandHeight; // foreground must end at/above this y
+  return { bandHeight, bandTopY, foregroundMaxY: bandTopY - safetyPx };
+}

package/.agents/skills/product-launch-video/scripts/lib/pad-frame-duration.mjs

@@ -0,0 +1,36 @@
+// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
+// sync with the padded index.html wrapper duration transitions.mjs computes.
+//
+// The frame's OWN internal file declares its #root/clip data-duration to the
+// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
+// upstream"). When an outgoing transition pads the index.html WRAPPER's
+// data-duration to cover the transition tail, the frame's own internal
+// duration is left short — the render engine clip-gates the sub-composition's
+// visible content at that shorter value, so content vanishes abruptly at
+// content-end instead of fading gracefully through the wrapper's extended
+// fade-out tween. Pad the frame's own file to match so both durations agree.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
+  const framePath = resolve(hyperframesDir, frameSrc);
+  let html;
+  try {
+    html = readFileSync(framePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return;
+    throw err;
+  }
+  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
+  let m;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
+    if (!/data-duration="[\d.]+"/.test(tag)) continue;
+    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
+    if (newTag === tag) return;
+    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
+    return;
+  }
+}