npm - takomi - Versions diffs - 2.1.40 → 2.1.42 - Mend

takomi 2.1.40 → 2.1.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (662) hide show

package/assets/.agent/skills/music-to-video/scripts/assemble-index.mjs ADDED Viewed

@@ -0,0 +1,218 @@
+#!/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; duck slightly when VO present
+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/assets/.agent/skills/music-to-video/scripts/lib/storyboard.mjs ADDED Viewed

@@ -0,0 +1,249 @@
+// 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-core/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/assets/.agent/skills/music-to-video/scripts/stage-assets.mjs ADDED Viewed

@@ -0,0 +1,58 @@
+#!/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/assets/.agent/skills/music-to-video/scripts/validate-plan.mjs ADDED Viewed

@@ -0,0 +1,161 @@
+#!/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)`,
+);