dsh-hyperframes 0.9.1 → 0.9.2

package/skills/music-to-video/scripts/assemble-index.mjs

@@ -1,220 +0,0 @@
-#!/usr/bin/env node
-// assemble-index.mjs — deterministic top-level index.html assembly for a
-// music-to-video project. No subagent, no judgment: turns STORYBOARD.md + the
-// built per-frame composition files (+ assets/bgm.mp3) into the standalone
-// index.html the renderer consumes.
-//
-// index.html is a *standalone* composition (root <div id="root"> directly in
-// <body>, no <template> wrapper — template is for the frame sub-comps). Each
-// frame is referenced (not inlined) as a <div class="frame"> with
-// data-composition-src pointing at its file; the renderer seeks each at its
-// absolute data-start. Frames tile the track gap-free, so frame→frame is a
-// plain back-to-back HARD CUT — there is NO transition injector (unlike
-// product-launch, whose transitions.mjs exists only for soft transitions).
-//
-// Track lanes:
-//   1   frame clips (sequential, gap-free, hard cut between)
-//   10  optional per-frame VO <audio>  (deferred; mounted only if audio_meta has it)
-//   11  BGM <audio> (full duration)
-//
-// Reads:  --storyboard STORYBOARD.md, --hyperframes <root>, [--audiomap audiomap.json],
-//         [--bgm assets/bgm.mp3], [--audio-meta audio_meta.json]. On disk: each frame's src html.
-// Writes: <project>/index.html
-//
-// Exit 0 = index.html written + summary. Exit 1 = fatal contract break (no
-// frames, a frame missing/empty/with-no-duration, an inner id mismatch).
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { parseStoryboard } from "./lib/storyboard.mjs";
-
-const argv = process.argv.slice(2);
-const flag = (name, def) => {
-  const i = argv.indexOf(`--${name}`);
-  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
-};
-function die(msg) {
-  console.error(`✗ assemble-index.mjs: ${msg}`);
-  process.exit(1);
-}
-const r3 = (x) => Math.round(x * 1000) / 1000;
-const anomalies = [];
-
-const hyperframesDir = resolve(flag("hyperframes", "."));
-const storyboardPath = resolve(flag("storyboard", join(hyperframesDir, "STORYBOARD.md")));
-const audiomapPath = resolve(flag("audiomap", join(hyperframesDir, "audiomap.json")));
-const audioMetaPath = resolve(flag("audio-meta", join(hyperframesDir, "audio_meta.json")));
-const bgmRel = flag("bgm", "assets/bgm.mp3");
-const outPath = resolve(flag("out", join(hyperframesDir, "index.html")));
-
-// ---------- parse storyboard ----------
-if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
-const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
-const G = manifest.globals.extra ?? {};
-
-// canvas from frontmatter `canvas: {"w":1920,"h":1080,"fps":30}` (key lowercased by parser)
-let WIDTH = 1920,
-  HEIGHT = 1080;
-if (G.canvas) {
-  try {
-    const c = JSON.parse(G.canvas);
-    if (Number.isFinite(c.w)) WIDTH = c.w;
-    if (Number.isFinite(c.h)) HEIGHT = c.h;
-  } catch {
-    anomalies.push(
-      `could not JSON.parse canvas frontmatter: ${G.canvas} — using ${WIDTH}×${HEIGHT}`,
-    );
-  }
-}
-
-// audio duration is the spine truth
-let audioDur = null;
-if (existsSync(audiomapPath)) {
-  try {
-    audioDur = JSON.parse(readFileSync(audiomapPath, "utf8"))?.audio?.duration_sec ?? null;
-  } catch (e) {
-    anomalies.push(`audiomap.json parse failed (${e.message}) — using frame sum for duration`);
-  }
-}
-
-// ---------- resolve mountable frames in document order ----------
-const mounted = [];
-for (const f of manifest.frames) {
-  const label = `frame ${f.number ?? f.index}${f.title ? ` (${f.title})` : ""}`;
-  if (!f.src) die(`${label} has no \`src\` — the planner must write it in STORYBOARD.md`);
-  const compAbs = join(hyperframesDir, f.src);
-  if (!existsSync(compAbs))
-    die(`${label}: src ${f.src} is not on disk — re-dispatch its frame-worker before assembling`);
-  if (!Number.isFinite(f.durationSeconds) || f.durationSeconds <= 0)
-    die(`${label}: no positive \`duration\` (got ${JSON.stringify(f.duration)})`);
-  const compId = basename(f.src).replace(/\.html?$/i, "");
-  const inner = readFileSync(compAbs, "utf8");
-  if (!inner.trim() || !/<\w/.test(inner))
-    die(
-      `${label}: ${f.src} is empty/blank — the frame-worker wrote a partial file. Re-dispatch it.`,
-    );
-  if (
-    !inner.includes(`data-composition-id="${compId}"`) &&
-    !inner.includes(`data-composition-id='${compId}'`)
-  )
-    die(`${label}: ${f.src} has no data-composition-id="${compId}" (host/inner id must match)`);
-  mounted.push({ frame: f, compId, durationSeconds: r3(f.durationSeconds) });
-}
-if (mounted.length === 0) die("no mountable frames (none with an on-disk src)");
-
-// cumulative starts — start[i] + duration[i] == start[i+1] exactly (gap-free hard cuts)
-let acc = 0;
-for (const m of mounted) {
-  m.start = r3(acc);
-  acc += m.durationSeconds;
-}
-const FRAME_SUM = r3(acc);
-const TOTAL = r3(audioDur ?? FRAME_SUM);
-if (audioDur != null && Math.abs(FRAME_SUM - audioDur) > 0.1)
-  anomalies.push(
-    `frames sum to ${FRAME_SUM}s but audio is ${audioDur}s (Δ${r3(FRAME_SUM - audioDur)}s) — frames should tile the track; check the plan`,
-  );
-
-// ---------- optional VO (deferred hook) ----------
-let audio = { voices: [] };
-if (existsSync(audioMetaPath)) {
-  try {
-    audio = JSON.parse(readFileSync(audioMetaPath, "utf8"));
-  } catch (e) {
-    anomalies.push(`audio_meta.json parse: ${e.message}`);
-  }
-}
-const voiceByNum = new Map();
-for (const v of audio.voices ?? []) if (v.frame != null) voiceByNum.set(v.frame, v);
-
-// ---------- build <body> ----------
-const body = [];
-let voiceCount = 0;
-for (const m of mounted) {
-  body.push(
-    `      <div`,
-    `        id="el-${m.compId}"`,
-    `        class="frame"`,
-    `        data-composition-id="${m.compId}"`,
-    `        data-composition-src="${m.frame.src}"`,
-    `        data-start="${m.start}"`,
-    `        data-duration="${m.durationSeconds}"`,
-    `        data-track-index="1"`,
-    `      ></div>`,
-  );
-  const v = m.frame.number != null ? voiceByNum.get(m.frame.number) : undefined;
-  if (v?.path && existsSync(join(hyperframesDir, v.path))) {
-    body.push(
-      `      <audio id="el-${m.compId}-voice" src="${v.path}" data-start="${m.start}"`,
-      `        data-duration="${m.durationSeconds}" data-track-index="10" data-volume="1"></audio>`,
-    );
-    voiceCount++;
-  }
-  body.push("");
-}
-
-// BGM (track 11) — full duration. Here the music IS the content (music-first
-// skill), so it never drops to the explainer pipelines' narration-bed default
-// (bgmDefaultVolume() 0.12 ≈ -18 dB): an incidental VO ducks it only slightly.
-let bgmEmitted = false;
-if (existsSync(join(hyperframesDir, bgmRel))) {
-  const vol = voiceCount > 0 ? 0.8 : 0.9;
-  body.push(
-    `      <!-- BGM -->`,
-    `      <audio id="el-bgm" src="${bgmRel}" data-start="0" data-duration="${TOTAL}"`,
-    `        data-track-index="11" data-volume="${vol}"></audio>`,
-  );
-  bgmEmitted = true;
-} else {
-  anomalies.push(`BGM not found at ${bgmRel} — index has no music track`);
-}
-
-// ---------- head + emit ----------
-const headStyle = [
-  "      * { margin: 0; padding: 0; box-sizing: border-box; }",
-  `      html, body { width: ${WIDTH}px; height: ${HEIGHT}px; overflow: hidden; background: #000; }`,
-  `      #root { position: relative; width: ${WIDTH}px; height: ${HEIGHT}px; overflow: hidden; }`,
-  "      .frame { position: absolute; inset: 0; width: 100%; height: 100%; }",
-].join("\n");
-
-const html = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=${WIDTH}, height=${HEIGHT}" />
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
-    <style>
-${headStyle}
-    </style>
-  </head>
-  <body>
-    <div
-      id="root"
-      data-composition-id="main"
-      data-start="0"
-      data-duration="${TOTAL}"
-      data-width="${WIDTH}"
-      data-height="${HEIGHT}"
-    >
-${body.join("\n")}
-    </div>
-
-    <script>
-      window.__timelines = window.__timelines || {};
-      window.__timelines["main"] = gsap.timeline({ paused: true });
-    </script>
-  </body>
-</html>
-`;
-writeFileSync(outPath, html);
-
-console.log(`✓ wrote ${outPath}`);
-console.log(`  canvas:           ${WIDTH}×${HEIGHT}`);
-console.log(`  frames (track 1): ${mounted.length}`);
-console.log(`  bgm (track 11):   ${bgmEmitted ? bgmRel : "MISSING"}`);
-console.log(`  vo (track 10):    ${voiceCount}`);
-console.log(`  total duration:   ${TOTAL}s` + (audioDur != null ? ` (audio ${audioDur}s)` : ""));
-if (anomalies.length) {
-  console.log(`\nanomalies (non-fatal):`);
-  for (const a of anomalies) console.log(`  - ${a}`);
-}

package/skills/music-to-video/scripts/lib/storyboard.mjs

@@ -1,249 +0,0 @@
-// storyboard.mjs — vendored lenient parser for STORYBOARD.md.
-//
-// Faithful plain-JS port of @hyperframes/core/storyboard
-// (packages/core/src/storyboard/parseStoryboard.ts). Vendored because skills
-// ship standalone: installed via `npx skills add`, a skill's scripts can't reach
-// the monorepo's core package, and the core export points at .ts source that
-// `node` (which runs these scripts) can't load. CANONICAL contract = the core
-// parser + skills/hyperframes/references/storyboard-format.md; keep this in
-// lockstep. Behavior: never throws, accepts freeform narrative, recognizes
-// Frame/Beat/Scene headings at H2/H3, preserves unknown keys verbatim under
-// `extra` (keys lowercased). Pure node — no deps.
-
-export const FRAME_STATUSES = ["outline", "built", "animated"];
-export const DEFAULT_FRAME_STATUS = "outline";
-
-// Detection-only frame heading (ends at the keyword); ReDoS-hardened — keep as-is.
-const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
-const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
-const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
-const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
-const LEADING_INT_RE = /^(\d+)/;
-const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
-const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
-const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
-export const VOICEOVER_ALIASES = ["voiceover", "vo", "voice_over", "narration"];
-const VOICEOVER_KEYS = new Set(VOICEOVER_ALIASES);
-
-export function parseStoryboard(source) {
-  const warnings = [];
-  const { globals, bodyStartLine, body } = parseFrontmatter(source, warnings);
-  const frames = parseFrames(body, bodyStartLine, warnings);
-  return { globals, frames, warnings };
-}
-
-function emptyGlobals() {
-  return { extra: {} };
-}
-
-function isFrameStatus(value) {
-  return FRAME_STATUSES.includes(value);
-}
-
-// ── Frontmatter ─────────────────────────────────────────────────────────────
-function findFrontmatterRange(lines, warnings) {
-  let start = 0;
-  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
-  if ((lines[start] ?? "").trim() !== "---") return null;
-  for (let i = start + 1; i < lines.length; i++) {
-    if ((lines[i] ?? "").trim() === "---") return { start, end: i };
-  }
-  warnings.push({
-    message: "Frontmatter opening '---' has no closing '---'; treating whole file as body.",
-    line: start + 1,
-  });
-  return null;
-}
-
-function parseFrontmatterEntries(lines, start, end, warnings) {
-  const globals = emptyGlobals();
-  for (let i = start + 1; i < end; i++) {
-    const raw = lines[i] ?? "";
-    if (raw.trim() === "") continue;
-    const colon = raw.indexOf(":");
-    if (colon === -1) {
-      warnings.push({
-        message: `Ignored non key:value frontmatter line: "${raw.trim()}"`,
-        line: i + 1,
-      });
-      continue;
-    }
-    const key = raw.slice(0, colon).trim().toLowerCase();
-    assignGlobal(globals, key, stripQuotes(raw.slice(colon + 1).trim()));
-  }
-  return globals;
-}
-
-function parseFrontmatter(source, warnings) {
-  const lines = source.split(/\r?\n/);
-  const range = findFrontmatterRange(lines, warnings);
-  if (!range) return { globals: emptyGlobals(), bodyStartLine: 1, body: source };
-  const globals = parseFrontmatterEntries(lines, range.start, range.end, warnings);
-  const body = lines.slice(range.end + 1).join("\n");
-  return { globals, bodyStartLine: range.end + 2, body };
-}
-
-function assignGlobal(globals, key, value) {
-  switch (key) {
-    case "format":
-      globals.format = value;
-      break;
-    case "message":
-      globals.message = value;
-      break;
-    case "arc":
-      globals.arc = value;
-      break;
-    case "audience":
-      globals.audience = value;
-      break;
-    default:
-      globals.extra[key] = value;
-  }
-}
-
-// ── Frames ──────────────────────────────────────────────────────────────────
-function openFrameSection(line, headingLine) {
-  const match = FRAME_HEADING_RE.exec(line);
-  if (!match) return null;
-  const headingText = line.slice(match[0].length).replace(FRAME_TITLE_SEP_RE, "").trim();
-  return { headingText, headingLine, level: (match[1] ?? "##").length, lines: [] };
-}
-
-function endsFrameSection(line, current) {
-  if (!current) return false;
-  const heading = HEADING_LEVEL_RE.exec(line);
-  return heading !== null && (heading[1] ?? "").length <= current.level;
-}
-
-function parseFrames(body, bodyStartLine, warnings) {
-  const lines = body.split(/\r?\n/);
-  const sections = [];
-  let current = null;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    const opened = openFrameSection(line, bodyStartLine + i);
-    if (opened) {
-      sections.push(opened);
-      current = opened;
-    } else if (endsFrameSection(line, current)) {
-      current = null;
-    } else if (current) {
-      current.lines.push(line);
-    }
-  }
-  return sections.map((section, idx) => buildFrame(section, idx + 1, warnings));
-}
-
-function buildFrame(section, index, warnings) {
-  const frame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };
-  const { number, title } = parseHeading(section.headingText);
-  if (number !== undefined) frame.number = number;
-  if (title) frame.title = title;
-
-  const narrativeLines = [];
-  for (const line of section.lines) {
-    const meta = META_RE.exec(line);
-    if (meta) {
-      applyMeta(
-        frame,
-        (meta[1] ?? "").toLowerCase(),
-        (meta[2] ?? "").trim(),
-        section.headingLine,
-        warnings,
-      );
-    } else {
-      narrativeLines.push(line);
-    }
-  }
-  frame.narrative = narrativeLines.join("\n").trim();
-  return frame;
-}
-
-function parseHeading(text) {
-  if (!text) return {};
-  const intMatch = LEADING_INT_RE.exec(text);
-  if (!intMatch) return { title: text };
-  const number = Number.parseInt(intMatch[1] ?? "", 10);
-  const rest = text
-    .slice((intMatch[0] ?? "").length)
-    .replace(/^[\s.:—-]+/, "")
-    .trim();
-  return { number, title: rest || undefined };
-}
-
-// Dispatch a recognized metadata key to its field, else stash under `extra`.
-// Mirrors core's META_SETTERS map exactly (direct keys + alias sets).
-function applyMeta(frame, key, value, headingLine, warnings) {
-  switch (key) {
-    case "duration":
-      applyDuration(frame, value, headingLine, warnings);
-      return;
-    case "status":
-      applyStatus(frame, value, headingLine, warnings);
-      return;
-    case "poster":
-      applyPoster(frame, value);
-      return;
-    case "src":
-      frame.src = value;
-      return;
-  }
-  if (TRANSITION_KEYS.has(key)) {
-    frame.transitionIn = value;
-    return;
-  }
-  if (SCENE_KEYS.has(key)) {
-    frame.scene = value;
-    return;
-  }
-  if (VOICEOVER_KEYS.has(key)) {
-    frame.voiceover = stripQuotes(value);
-    return;
-  }
-  frame.extra[key] = value;
-}
-
-function applyPoster(frame, value) {
-  const num = DURATION_NUM_RE.exec(value);
-  if (num) frame.poster = Number.parseFloat(num[1] ?? "");
-}
-
-function applyDuration(frame, value, headingLine, warnings) {
-  frame.duration = value;
-  const num = DURATION_NUM_RE.exec(value);
-  if (num) {
-    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
-    return;
-  }
-  warnings.push({
-    message: `Frame ${frame.index}: could not parse duration "${value}".`,
-    line: headingLine,
-    frameIndex: frame.index,
-  });
-}
-
-function applyStatus(frame, value, headingLine, warnings) {
-  const normalized = value.toLowerCase();
-  if (isFrameStatus(normalized)) {
-    frame.status = normalized;
-    return;
-  }
-  frame.extra.status = value;
-  warnings.push({
-    message: `Frame ${frame.index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`,
-    line: headingLine,
-    frameIndex: frame.index,
-  });
-}
-
-function stripQuotes(value) {
-  if (value.length >= 2) {
-    const first = value[0];
-    const last = value[value.length - 1];
-    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-      return value.slice(1, -1);
-    }
-  }
-  return value;
-}

package/skills/music-to-video/scripts/stage-assets.mjs

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-// stage-assets.mjs — copy user-supplied media into the project's assets/ so scene
-// files (and lint/validate/render) can reference them locally. Only needed when
-// the user provides images/videos for asset treatments (montage.md). First-wins,
-// idempotent, safe to run twice. Never fetches remote URLs.
-//
-// Usage: node stage-assets.mjs --from <srcDir> --hyperframes <projectRoot>
-//        [--into public]   (subdir under assets/; default copies flat into assets/)
-//
-// Copies common media extensions only; reports what landed.
-
-import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from "node:fs";
-import { extname, join, resolve, basename } from "node:path";
-
-const argv = process.argv.slice(2);
-const flag = (n, d) => {
-  const i = argv.indexOf(`--${n}`);
-  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : d;
-};
-function die(m) {
-  console.error(`✗ stage-assets.mjs: ${m}`);
-  process.exit(1);
-}
-
-const fromDir = flag("from", null);
-if (!fromDir) die("missing --from <srcDir>");
-const fromAbs = resolve(fromDir);
-if (!existsSync(fromAbs) || !statSync(fromAbs).isDirectory())
-  die(`--from is not a directory: ${fromAbs}`);
-const hyperframesDir = resolve(flag("hyperframes", "."));
-const into = flag("into", "");
-const destDir = join(hyperframesDir, "assets", into);
-
-const MEDIA = new Set([".jpg", ".jpeg", ".png", ".webp", ".gif", ".mp4", ".mov", ".webm", ".m4v"]);
-
-mkdirSync(destDir, { recursive: true });
-let staged = 0,
-  skipped = 0;
-const landed = [];
-for (const name of readdirSync(fromAbs)) {
-  const src = join(fromAbs, name);
-  if (!statSync(src).isFile()) continue;
-  if (!MEDIA.has(extname(name).toLowerCase())) continue;
-  const dest = join(destDir, basename(name));
-  if (existsSync(dest)) {
-    skipped++;
-    continue;
-  } // first-wins
-  copyFileSync(src, dest);
-  staged++;
-  landed.push(join("assets", into, basename(name)));
-}
-
-console.log(
-  `✓ stage-assets: ${staged} copied, ${skipped} already present → ${join("assets", into)}/`,
-);
-for (const l of landed) console.log(`  ${l}`);
-if (staged === 0 && skipped === 0) console.log(`  (no media files found in ${fromAbs})`);

package/skills/music-to-video/scripts/validate-plan.mjs

@@ -1,161 +0,0 @@
-#!/usr/bin/env node
-// validate-plan.mjs — machine-check STORYBOARD.md against the audiomap + template
-// catalog at Step 3, before any frame is built. Runs on the PLAN (frame files do
-// not exist yet), so it checks fields, not on-disk html.
-//
-// HARD (exit 1): frontmatter duration_s == audiomap duration; >=1 frame; each frame
-//   has src + positive duration; frames tile the track gap-free (sum == duration_s);
-//   every frame has >=1 filled group (a frame whose `### Groups` is still
-//   `TBD (Step 3)`/empty is a Step-2 skeleton, not an approved plan — fail it so a
-//   skipped Step 3 can never reach the build step).
-// WARN (exit 0): best-effort group checks — each group exactly one of
-//   template/free_design/asset; a template id exists under the --templates dir;
-//   phrase_flow frame has no beat_cut asset treatment.
-//
-// Frame-level checks use the vendored storyboard parser. Group-level checks re-scan
-// the RAW source (the parser's META_RE consumes indented `- params:`/`- asset:` lines).
-//
-// Reads: --storyboard, --audiomap, --hyperframes <root> (for templates/).
-
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { parseStoryboard } from "./lib/storyboard.mjs";
-
-const argv = process.argv.slice(2);
-const flag = (n, d) => {
-  const i = argv.indexOf(`--${n}`);
-  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : d;
-};
-const hyperframesDir = resolve(flag("hyperframes", "."));
-const storyboardPath = resolve(flag("storyboard", join(hyperframesDir, "STORYBOARD.md")));
-const audiomapPath = resolve(flag("audiomap", join(hyperframesDir, "audiomap.json")));
-const templatesDir = resolve(flag("templates", join(hyperframesDir, "templates")));
-
-const errors = [];
-const warns = [];
-const r3 = (x) => Math.round(x * 1000) / 1000;
-
-if (!existsSync(storyboardPath)) {
-  console.error(`✗ STORYBOARD.md not found at ${storyboardPath}`);
-  process.exit(1);
-}
-const raw = readFileSync(storyboardPath, "utf8");
-const manifest = parseStoryboard(raw);
-const G = manifest.globals.extra ?? {};
-
-// ---------- audio duration ----------
-let audioDur = null;
-if (existsSync(audiomapPath)) {
-  try {
-    audioDur = JSON.parse(readFileSync(audiomapPath, "utf8"))?.audio?.duration_sec ?? null;
-  } catch (e) {
-    warns.push(`audiomap parse failed: ${e.message}`);
-  }
-} else {
-  warns.push(`audiomap not found at ${audiomapPath} — skipping duration cross-check`);
-}
-
-// ---------- frontmatter duration_s ----------
-const declaredDur = G.duration_s != null ? Number.parseFloat(G.duration_s) : NaN;
-if (!Number.isFinite(declaredDur)) errors.push(`frontmatter \`duration_s\` missing or unparseable`);
-else if (audioDur != null && Math.abs(declaredDur - audioDur) > 0.05)
-  errors.push(`frontmatter duration_s (${declaredDur}) != audiomap duration (${audioDur})`);
-
-// ---------- frames (hard) ----------
-const frames = manifest.frames;
-if (frames.length === 0) errors.push(`no frames (no \`## Frame N — <id>\` headings found)`);
-
-let sum = 0;
-for (const f of frames) {
-  const label = `frame ${f.number ?? f.index}${f.title ? ` (${f.title})` : ""}`;
-  if (!f.src) errors.push(`${label}: missing \`- src:\``);
-  if (!Number.isFinite(f.durationSeconds) || f.durationSeconds <= 0)
-    errors.push(`${label}: missing/!positive \`- duration:\` (got ${JSON.stringify(f.duration)})`);
-  else sum += f.durationSeconds;
-}
-sum = r3(sum);
-const tileTarget = Number.isFinite(declaredDur) ? declaredDur : audioDur;
-if (tileTarget != null && Math.abs(sum - tileTarget) > 0.1)
-  errors.push(
-    `frame durations sum to ${sum}s but the track is ${tileTarget}s — frames must tile it gap-free`,
-  );
-
-// ---------- group checks (warns) — parse RAW text ----------
-const FRAME_HEAD = /^##\s+(?:frame|scene|section)\b/i;
-const GROUP_HEAD = /^\s*[-*]\s*\*\*\s*(\w+)\s*\*\*\s*[—:-]\s*(template|free_design|asset)\b(.*)$/i;
-const templateExistsCache = new Map();
-function templateExists(id) {
-  if (templateExistsCache.has(id)) return templateExistsCache.get(id);
-  const ok = existsSync(join(templatesDir, id, "index.html"));
-  templateExistsCache.set(id, ok);
-  return ok;
-}
-
-// walk raw lines → group blocks tagged with their frame label + pacing
-const blocks = [];
-let frameLabel = "?";
-let pacing = "";
-let cur = null;
-for (const ln of raw.split(/\r?\n/)) {
-  if (FRAME_HEAD.test(ln)) {
-    frameLabel = ln.replace(/^#+\s+/, "").trim();
-    pacing = "";
-    cur = null;
-    continue;
-  }
-  const pm = ln.match(/^\s*[-*]\s*pacing\s*:\s*([A-Za-z_]+)/i);
-  if (pm && !cur) {
-    pacing = pm[1].toLowerCase();
-    continue;
-  }
-  const h = GROUP_HEAD.exec(ln);
-  if (h) {
-    cur = { frameLabel, pacing, name: h[1], kind: h[2].toLowerCase(), rest: h[3] ?? "", lines: [] };
-    blocks.push(cur);
-    continue;
-  }
-  if (cur) cur.lines.push(ln);
-}
-
-// HARD: every frame needs >=1 filled group. A frame with no parseable group head
-// is still a Step-2 skeleton (`### Groups` = `TBD (Step 3)`/empty) — erroring here
-// is what stops a skipped Step 3 from reaching the build step.
-const framesWithGroups = new Set(blocks.map((b) => b.frameLabel));
-for (const f of frames) {
-  const title = String(f.title ?? "").trim();
-  const lbl = `Frame ${f.number ?? ""} — ${f.title ?? f.index}`.replace(/\s+—\s+$/, "");
-  const hasGroup = title !== "" && [...framesWithGroups].some((s) => s.includes(title));
-  if (!hasGroup) {
-    errors.push(
-      `${lbl}: no filled groups — still a Step-2 skeleton (\`### Groups\` is TBD/empty). ` +
-        `Run Step 3: fill its groups (\`- **gN** — template|free_design|asset …\`) before building.`,
-    );
-  }
-}
-
-for (const b of blocks) {
-  const gid = `${b.frameLabel} / ${b.name}`;
-  const blockText = b.rest + " " + b.lines.join(" ");
-  if (b.kind === "template") {
-    const m = b.rest.match(/`([^`]+)`/) || b.rest.match(/:\s*([\w-]+)/);
-    const id = m ? m[1].trim() : null;
-    if (!id) warns.push(`${gid}: template kind but no template id on the head line`);
-    else if (!templateExists(id))
-      warns.push(`${gid}: template \`${id}\` not found at templates/${id}/index.html`);
-  }
-  if (b.kind === "asset" && b.pacing === "phrase_flow" && /beat_cut/.test(blockText))
-    warns.push(
-      `${gid}: beat_cut asset treatment on a phrase_flow frame — use ken_burns/crossfade instead`,
-    );
-}
-
-// ---------- report ----------
-for (const w of warns) console.log(`⚠ ${w}`);
-if (errors.length) {
-  for (const e of errors) console.error(`✗ ${e}`);
-  console.error(`\nvalidate-plan: ${errors.length} error(s), ${warns.length} warning(s)`);
-  process.exit(1);
-}
-console.log(
-  `✓ validate-plan: ${frames.length} frames tile ${sum}s; ${blocks.length} groups; ${warns.length} warning(s)`,
-);