@tandryukha/aidemo 0.8.0 → 0.15.0

package/src/cli.ts

@@ -1,12 +1,28 @@
 import { Command } from "commander";
 import { resolve, dirname } from "node:path";
 import { readFile } from "node:fs/promises";
-import { loadEnv, engineVersion, ENGINE_ROOT, captionsAutoOffline } from "./config.js";
-import { Project } from "./project.js";
+import {
+  loadEnv,
+  engineVersion,
+  ENGINE_ROOT,
+  captionsAutoOffline,
+  chromeProfileDir,
+} from "./config.js";
+import { resetProfile } from "./profile.js";
+import { Project, parseStoryboard } from "./project.js";
 import { record } from "./recorder.js";
+import { collectSeeds, parseCookieFlag, runPreflight } from "./setup.js";
+import { extractFrames } from "./frames.js";
+import { runQa, logQa } from "./qa.js";
+import { inspectPage } from "./inspect.js";
+import { importTrace, scaffoldImported } from "./import-trace.js";
+import { GUIDE_TOPIC_NAMES, guideHeadings, readGuide, sliceGuide } from "./guide.js";
+import { lintStoryboard, logLint } from "./lint.js";
+import { readJson, writeJson } from "./util.js";
 import {
   buildProbeGolden,
   diffGolden,
+  driftFilesForDiff,
   readProbeGolden,
   writeProbeGolden,
 } from "./golden.js";
@@ -17,6 +33,7 @@ import { compose } from "./compose.js";
 import { exportGif } from "./gif.js";
 import { buildEmbed, formatEmbed } from "./embed.js";
 import { extractStills, storyboardHasStills } from "./stills.js";
+import { exportWalkthrough } from "./walkthrough.js";
 import { localizeStoryboard, missingNarrations } from "./i18n.js";
 import { synthesizeMusicBed } from "./music.js";
 import { loadVariants, renderVariants } from "./variants.js";
@@ -29,6 +46,7 @@ import {
   setLogFile,
   closeLogFile,
   teeStageLog,
+  exists,
 } from "./util.js";
 import {
   scaffoldDemo,
@@ -70,12 +88,54 @@ program
   .command("init")
   .argument("<name>", "demo name (creates ./demos/<name>/)")
   .option("--force", "overwrite an existing demos/<name>/", false)
+  .option(
+    "--from-url <url>",
+    "draft from a live page: inspect it, headings → scenes, unique selectors → beats (no LLM)"
+  )
+  .option("--headed", "show the browser while inspecting (--from-url)", false)
+  .option("--profile <dir>", "Chrome user-data dir for --from-url (logged-in pages)")
+  .option("--viewport <WxH>", "viewport for --from-url (default 1280x720)")
   .description("scaffold a new demo project (in the current repo) with a starter storyboard")
-  .action(async (name: string, opts: { force?: boolean }) => {
-    // Scaffold into the *current* working directory, so `init` works both in the
-    // engine's own repo and in a consumer repo that invoked it via npx.
-    const dir = await scaffoldDemo(process.cwd(), name, { force: opts.force });
-    ok(`edit generated/storyboard.json, then: aidemo render ${dir}`);
+  .action(
+    async (
+      name: string,
+      opts: { force?: boolean; fromUrl?: string; headed?: boolean; profile?: string; viewport?: string }
+    ) => {
+      // Scaffold into the *current* working directory, so `init` works both in the
+      // engine's own repo and in a consumer repo that invoked it via npx.
+      const vp = opts.viewport ? /^(\d+)x(\d+)$/.exec(opts.viewport) : null;
+      if (opts.viewport && !vp) throw new Error(`--viewport expects WxH, got ${opts.viewport}`);
+      const dir = await scaffoldDemo(process.cwd(), name, {
+        force: opts.force,
+        fromUrl: opts.fromUrl,
+        headed: opts.headed,
+        profileDir: opts.profile,
+        ...(vp ? { viewport: { width: Number(vp[1]), height: Number(vp[2]) } } : {}),
+      });
+      ok(
+        opts.fromUrl
+          ? `write the narration in generated/storyboard.json (input/brief.md lists what inspect saw), then: aidemo probe ${dir}`
+          : `edit generated/storyboard.json, then: aidemo render ${dir}`
+      );
+    }
+  );
+
+program
+  .command("import-trace")
+  .argument("<file>", "Playwright trace.zip (context.tracing / --trace on) or a *.spec.ts test file")
+  .requiredOption("--name <name>", "demo name (creates ./demos/<name>/)")
+  .option("--force", "overwrite an existing demos/<name>/storyboard", false)
+  .option("--json", "print the draft storyboard to stdout instead of writing a demo", false)
+  .description("draft a storyboard from a Playwright trace or test: its actions + selectors become scenes (no LLM)")
+  .action(async (file: string, opts: { name: string; force?: boolean; json?: boolean }) => {
+    const result = await importTrace(resolve(file), opts.name);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(result.storyboard, null, 2) + "\n");
+      return;
+    }
+    const dir = await scaffoldImported(process.cwd(), opts.name, result, { force: opts.force });
+    for (const n of result.notes) log(`  · ${n}`);
+    ok(`write the narration in ${dir}/generated/storyboard.json, then: aidemo probe ${dir}`);
   });
 
 program
@@ -125,22 +185,82 @@ program
 program
   .command("guide")
   .description("print the agent-neutral authoring guide (docs/AUTHORING.md)")
-  .action(async () => {
+  .option(
+    "--topic <name>",
+    `print one slice: ${GUIDE_TOPIC_NAMES.join(", ")} — or an H2 heading prefix`
+  )
+  .option("--list", "list topics and section headings")
+  .action(async (opts: { topic?: string; list?: boolean }) => {
     // Deliberate stdout (not the stderr logger): the guide is the output.
-    process.stdout.write(
-      await readFile(resolve(ENGINE_ROOT, "docs/AUTHORING.md"), "utf8")
-    );
+    const md = await readGuide();
+    if (opts.list) {
+      process.stdout.write(
+        `topics: ${GUIDE_TOPIC_NAMES.join(", ")}\n\nsections:\n` +
+          guideHeadings(md)
+            .map((h) => `  ${h}`)
+            .join("\n") +
+          "\n"
+      );
+      return;
+    }
+    if (!opts.topic) {
+      process.stdout.write(md);
+      return;
+    }
+    const slice = sliceGuide(md, opts.topic);
+    if (slice == null) {
+      fail(
+        `unknown guide topic "${opts.topic}" — topics: ${GUIDE_TOPIC_NAMES.join(", ")}; ` +
+          `sections: ${guideHeadings(md).join(" · ")}`
+      );
+      process.exit(1);
+    }
+    process.stdout.write(slice);
   });
 
+/** Read all of stdin as UTF-8 (for `--body-file -`). */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
 program
   .command("feedback")
   .argument("[dir]", "demo project directory (adds storyboard + log context)")
+  .option("--title <text>", "issue title (default: \"Demo feedback: <dir>\")")
+  .option("--body <text>", "issue body; environment + log context is appended")
+  .option("--body-file <file>", "read the body from a file, or \"-\" for stdin")
   .option("--web", "open a prefilled New Issue page instead of filing directly", false)
   .option("--dry-run", "print the issue title/body without filing", false)
   .description("file demo-recording feedback as a GitHub issue on the engine repo")
-  .action(async (dir: string | undefined, opts: { web?: boolean; dryRun?: boolean }) => {
-    await feedback(dir, { web: opts.web, dryRun: opts.dryRun });
-  });
+  .action(
+    async (
+      dir: string | undefined,
+      opts: {
+        title?: string;
+        body?: string;
+        bodyFile?: string;
+        web?: boolean;
+        dryRun?: boolean;
+      }
+    ) => {
+      // Non-interactive body so an agent (or a script) can file without the
+      // placeholder template — the reason issue #38 was filed with `gh` by hand.
+      let body = opts.body;
+      if (opts.bodyFile) {
+        body = await (opts.bodyFile === "-"
+          ? readStdin()
+          : readFile(opts.bodyFile, "utf8"));
+      }
+      await feedback(dir, {
+        web: opts.web,
+        dryRun: opts.dryRun,
+        title: opts.title,
+        description: body,
+      });
+    }
+  );
 
 program
   .command("doctor")
@@ -150,6 +270,21 @@ program
     await doctor(opts.dir);
   });
 
+/**
+ * `--tts <provider>` — a discoverable spelling of AIDEMO_TTS_PROVIDER (the env
+ * var is canonical; the flag just sets it before the pipeline reads it).
+ */
+function applyTtsFlag(value?: string): void {
+  if (value == null) return;
+  if (value !== "openai" && value !== "elevenlabs" && value !== "local") {
+    throw new Error(`--tts must be openai, elevenlabs or local (got "${value}")`);
+  }
+  process.env.AIDEMO_TTS_PROVIDER = value;
+}
+
+const TTS_OPT_DESC =
+  "TTS provider: openai (default) | elevenlabs | local (in-process Kokoro; needs `npm install kokoro-js`) — same as AIDEMO_TTS_PROVIDER";
+
 function parsePositiveInt(name: string, value: string): number {
   const n = Number(value);
   if (!Number.isInteger(n) || n <= 0)
@@ -180,6 +315,10 @@ function parseParams(pairs?: string[]): Record<string, string> | undefined {
   return out;
 }
 
+const NO_REPLAY_OPT_DESC =
+  "with --from-scene: do not replay the reused scenes' actions — the profile already holds the state (balances earned, a day rolled forward); the resumed scene must open with its own goto";
+const FROM_SCENE_OPT_DESC =
+  "resume: keep the previous take's scenes before this id (verified unchanged) and record from it";
 const PARAM_OPT_DESC =
   "set a storyboard template param (key=value; repeatable; must be declared in the storyboard's params block)";
 
@@ -194,6 +333,32 @@ const LANGS_OPT_DESC =
  * `[undefined]` when neither is given — the default single-language render,
  * byte-for-byte unchanged (undefined = the base storyboard, unsuffixed paths).
  */
+const STRICT_OPT_DESC =
+  "exit 1 when compose reports any warning (anchor-unreachable, overrun-trim, scene-freeze, blank-open …) — each one maps to a defect a viewer will see";
+const STORAGE_STATE_OPT_DESC =
+  "seed a Playwright storageState JSON (cookies + localStorage) into the profile before the take";
+const COOKIE_OPT_DESC =
+  'seed a cookie before the take: "name=value;domain=host[;path=/;secure;httpOnly;sameSite=Lax]" (repeatable)';
+const PROFILE_SEEDED_OPT_DESC =
+  "the profile is seeded on purpose (login / cookie gate): silence the carried-over-state warning";
+
+/** Profile-seeding flags shared by record/probe/render → RecordOptions fields. */
+function seedOpts(opts: {
+  storageState?: string;
+  cookie?: string[];
+  profileSeeded?: boolean;
+}): {
+  storageState?: string;
+  cookies?: ReturnType<typeof parseCookieFlag>[];
+  profileSeeded?: boolean;
+} {
+  return {
+    storageState: opts.storageState,
+    cookies: opts.cookie?.length ? opts.cookie.map(parseCookieFlag) : undefined,
+    profileSeeded: opts.profileSeeded,
+  };
+}
+
 function langsFrom(opts: { lang?: string; langs?: string }): Array<string | undefined> {
   const list = [
     ...(opts.langs ? opts.langs.split(",") : []),
@@ -214,29 +379,415 @@ function warnPartialCoverage(storyboard: Parameters<typeof missingNarrations>[0]
     );
 }
 
+program
+  .command("login")
+  .argument("[profile]", "Chrome user-data dir (default: the engine's recording profile)")
+  .option("--url <url>", "page to open for the login", "https://chatgpt.com/")
+  .option("--no-wait", "launch Chrome and return without waiting for it to quit")
+  .description(
+    "open a manual-login Chrome on the recording profile (mock-keychain cookie " +
+      "store, same as record) and wait until you quit it"
+  )
+  .action(async (profile: string | undefined, opts: { url: string; wait: boolean }) => {
+    const { login } = await import("./login.js");
+    await login(profile, { url: opts.url, noWait: !opts.wait });
+  });
+
+program
+  .command("profile")
+  .argument("[action]", "path (default) | reset", "path")
+  .option("--profile <dir>", "operate on this Chrome user-data dir instead of the default")
+  .description(
+    "show or wipe the recording Chrome profile (a profile carrying state for " +
+      "the app can silently record the wrong story)"
+  )
+  .action(async (action: string, opts: { profile?: string }) => {
+    const dir = opts.profile ?? chromeProfileDir();
+    if (action === "reset") {
+      await resetProfile(dir);
+      step("Profile reset");
+      ok(`wiped → ${dir}`);
+      ok("the next take starts from a clean browser identity (you'll need to log in again)");
+      return;
+    }
+    if (action !== "path") {
+      throw new Error(`unknown profile action "${action}" — use: path | reset`);
+    }
+    step("Recording profile");
+    ok(dir);
+    ok(`exists: ${(await exists(dir)) ? "yes" : "no"}`);
+    ok("wipe it with: aidemo profile reset  (or record/probe with --fresh)");
+  });
+
+program
+  .command("validate")
+  .argument("[dir]", "demo project directory (validates generated/storyboard.json)")
+  .option("--file <path>", "validate this storyboard file instead of <dir>/generated/storyboard.json")
+  .option("--relaxed", "narration optional (probe semantics)", false)
+  .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
+  .option("--json", "print the structured result as JSON", false)
+  .description(
+    "validate a storyboard against the engine schema without running anything " +
+      "(the CLI twin of the MCP validate_storyboard tool; non-zero exit on issues)"
+  )
+  .action(
+    async (
+      dir: string | undefined,
+      opts: { file?: string; relaxed?: boolean; param?: string[]; json?: boolean }
+    ) => {
+      if (!dir && !opts.file) {
+        throw new Error("pass a demo dir or --file <storyboard.json>");
+      }
+      const path = opts.file ? resolve(opts.file) : new Project(dir!).storyboardPath;
+      let raw: unknown;
+      try {
+        raw = await readJson<unknown>(path);
+      } catch (err) {
+        const result = {
+          valid: false,
+          storyboardPath: path,
+          issues: [{ path: "", message: (err as Error).message, code: "unreadable" }],
+          warnings: [] as string[],
+        };
+        if (opts.json) console.log(JSON.stringify(result, null, 2));
+        else fail(`${path}: ${(err as Error).message}`);
+        process.exitCode = 1;
+        return;
+      }
+      const params = parseParams(opts.param);
+      const parsed = parseStoryboard(raw, {
+        relaxed: opts.relaxed,
+        params,
+        strict: params != null,
+      });
+      const result = parsed.ok
+        ? {
+            valid: true,
+            storyboardPath: path,
+            title: parsed.storyboard.title,
+            sceneCount: parsed.storyboard.scenes.length,
+            issues: [] as Array<{ path: string; message: string; code: string }>,
+            warnings: parsed.warnings,
+          }
+        : { valid: false, storyboardPath: path, issues: parsed.issues, warnings: [] as string[] };
+      const lint = parsed.ok ? lintStoryboard(parsed.storyboard) : null;
+      if (opts.json) {
+        console.log(JSON.stringify({ ...result, lint: lint?.issues ?? [] }, null, 2));
+      } else if (result.valid) {
+        step("Storyboard valid");
+        ok(`${path} — "${result.title}", ${result.sceneCount} scene(s)`);
+        for (const w of result.warnings) log(w);
+        if (lint) logLint(lint, log);
+      } else {
+        fail(`${path}: ${result.issues.length} issue(s)`);
+        for (const i of result.issues) log(`  - ${i.path || "<root>"}: ${i.message}`);
+      }
+      if (!result.valid) process.exitCode = 1;
+    }
+  );
+
+program
+  .command("lint")
+  .argument("[dir]", "demo project directory (lints generated/storyboard.json)")
+  .option("--file <path>", "lint this storyboard file instead of <dir>/generated/storyboard.json")
+  .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
+  .option("--lang <code>", "lint the narrations[code] translation + that language's pace")
+  .option("--json", "print the structured result as JSON", false)
+  .option("--strict", "non-zero exit on warnings too (default: errors only)", false)
+  .description(
+    "preflight a storyboard without a browser: pacing forecast (which scenes " +
+      "compose will freeze or cut), selector/wait pitfalls, no-op keys"
+  )
+  .action(
+    async (
+      dir: string | undefined,
+      opts: { file?: string; param?: string[]; lang?: string; json?: boolean; strict?: boolean }
+    ) => {
+      if (!dir && !opts.file) {
+        throw new Error("pass a demo dir or --file <storyboard.json>");
+      }
+      const path = opts.file ? resolve(opts.file) : new Project(dir!).storyboardPath;
+      const params = parseParams(opts.param);
+      const parsed = parseStoryboard(await readJson<unknown>(path), {
+        relaxed: true,
+        params,
+        strict: params != null,
+      });
+      if (!parsed.ok) {
+        fail(`${path}: ${parsed.issues.length} schema issue(s) — run validate first`);
+        for (const i of parsed.issues) log(`  - ${i.path || "<root>"}: ${i.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      const result = lintStoryboard(parsed.storyboard, { lang: opts.lang });
+      if (opts.json) {
+        console.log(JSON.stringify({ storyboardPath: path, ...result }, null, 2));
+      } else {
+        step(`Lint "${parsed.storyboard.title}"`);
+        log(
+          `  ${"scene".padEnd(12)}${"words".padStart(6)}${"narr".padStart(7)}${"action".padStart(8)}${"hold%".padStart(7)}`
+        );
+        for (const e of result.estimate) {
+          log(
+            `  ${e.id.padEnd(12)}${String(e.words).padStart(6)}` +
+              `${(e.narrationMs / 1000).toFixed(1).padStart(6)}s` +
+              `${(e.actionMs / 1000).toFixed(1).padStart(7)}s` +
+              `${e.holdPct > 0 ? `${Math.round(e.holdPct * 100)}%`.padStart(7) : "".padStart(7)}` +
+              (e.overrunMs > 0 ? `  cut ≈${(e.overrunMs / 1000).toFixed(1)}s` : "")
+          );
+        }
+        if (result.issues.length === 0) {
+          ok(`no issues — predicted narration ≈${(result.narrationTotalMs / 1000).toFixed(0)}s`);
+        } else {
+          logLint(result, log);
+        }
+      }
+      const errors = result.issues.filter((i) => i.severity === "error").length;
+      const warns = result.issues.filter((i) => i.severity === "warn").length;
+      if (errors > 0 || (opts.strict && warns > 0)) process.exitCode = 1;
+    }
+  );
+
+program
+  .command("walkthrough")
+  .argument("<dir>", "demo project directory")
+  .option("--lang <code>", "language variant (final-demo.<lang>.mp4)")
+  .option("--width <px>", "frame width in px (default 960)", "960")
+  .option("--out <dir>", "output directory (default <dir>/output/walkthrough)")
+  .description(
+    "export output/walkthrough/: index.html + guide.md + per-scene frames + captions from the final video"
+  )
+  .action(async (dir: string, opts: { lang?: string; width: string; out?: string }) => {
+    const base = new Project(dir);
+    const project = opts.lang ? new Project(dir, opts.lang) : base;
+    await beginCommand(project, "walkthrough");
+    const storyboard = await base.loadStoryboard({ relaxed: true });
+    const sb = opts.lang ? localizeStoryboard(storyboard, opts.lang) : storyboard;
+    const res = await exportWalkthrough(project, sb, {
+      width: Number(opts.width) || 960,
+      outDir: opts.out,
+    });
+    ok(`walkthrough → ${res.index} (${res.scenes.length} scene(s); guide.md alongside)`);
+  });
+
+program
+  .command("inspect")
+  .argument("<url>", "page to inspect (absolute URL)")
+  .option("--dir <dir>", "demo directory to write logs/inspect-*.json + screenshot into")
+  .option("--profile <dir>", "Chrome user-data dir (default: the recording profile)")
+  .option("--headed", "show the browser (default headless)", false)
+  .option("--limit <n>", "max elements (default 80)", "80")
+  .option("--viewport <WxH>", "viewport (default 1280x720)")
+  .option("--frame <name=selector>", "also scan this iframe (repeatable)", collectKv, [])
+  .option("--storage-state <file>", STORAGE_STATE_OPT_DESC)
+  .option("--cookie <spec>", COOKIE_OPT_DESC, collectKv, [])
+  .option(
+    "--no-setup",
+    "with --dir: ignore the storyboard's setup block (cookies/storageState/preflight)"
+  )
+  .option("--json", "print the full JSON result", false)
+  .description(
+    "list the page's visible interactive elements with unique selectors (no selector guessing)"
+  )
+  .action(
+    async (
+      url: string,
+      opts: {
+        dir?: string;
+        profile?: string;
+        headed?: boolean;
+        limit: string;
+        viewport?: string;
+        frame: string[];
+        storageState?: string;
+        cookie: string[];
+        setup?: boolean;
+        json?: boolean;
+      }
+    ) => {
+      const vp = opts.viewport?.match(/^(\d+)x(\d+)$/);
+      const frames: Record<string, string> = {};
+      for (const kv of opts.frame) {
+        const i = kv.indexOf("=");
+        if (i > 0) frames[kv.slice(0, i)] = kv.slice(i + 1);
+      }
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+      const project = opts.dir ? new Project(opts.dir) : null;
+      if (project) await ensureDir(project.p("logs"));
+      // #53: authenticate the scan the same way a take does — the storyboard
+      // already declares how (setup.storageState / cookies / preflight), and
+      // --storage-state / --cookie layer on top for a project-less inspect.
+      const useSetup = opts.setup !== false;
+      let storyboard: Awaited<ReturnType<Project["loadStoryboard"]>> | null = null;
+      if (project && useSetup) {
+        storyboard = await project.loadStoryboard({ relaxed: true }).catch(() => null);
+      }
+      if (storyboard?.setup?.preflight) {
+        await runPreflight(storyboard.setup.preflight, {
+          demoDir: project!.dir,
+          storyboardPath: project!.storyboardPath,
+          profileDir: opts.profile ?? chromeProfileDir(),
+        });
+        storyboard = await project!.loadStoryboard({ relaxed: true }).catch(() => storyboard);
+      }
+      const seeds = await collectSeeds(
+        project?.dir ?? process.cwd(),
+        storyboard ?? ({ setup: undefined } as never),
+        {
+          storageState: opts.storageState,
+          cookies: opts.cookie?.length ? opts.cookie.map(parseCookieFlag) : undefined,
+        }
+      );
+      for (const [name, selector] of Object.entries(storyboard?.frames ?? {})) {
+        if (!(name in frames)) frames[name] = selector;
+      }
+      const res = await inspectPage({
+        url,
+        headless: !opts.headed,
+        profileDir: opts.profile,
+        limit: Number(opts.limit) || 80,
+        ...(vp
+          ? { viewport: { width: Number(vp[1]), height: Number(vp[2]) } }
+          : storyboard?.video
+            ? { viewport: storyboard.video }
+            : {}),
+        seeds,
+        frames,
+        ...(project ? { screenshotPath: project.p("logs", `inspect-${stamp}.png`) } : {}),
+      });
+      if (project) {
+        const file = project.p("logs", `inspect-${stamp}.json`);
+        await writeJson(file, res);
+        log(`inspect → ${file}`);
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+        return;
+      }
+      process.stdout.write(`${res.title || "(untitled)"} — ${res.finalUrl}\n`);
+      if (res.headings.length) {
+        process.stdout.write(
+          res.headings.map((h) => `  ${"#".repeat(h.level)} ${h.text}`).join("\n") + "\n"
+        );
+      }
+      if (res.iframes.length) {
+        process.stdout.write(
+          `iframes: ${res.iframes.map((f) => `${f.name} (${f.selector})`).join(", ")}\n`
+        );
+      }
+      process.stdout.write(`${res.elements.length} interactive element(s)${res.truncated ? " (truncated — raise --limit)" : ""}:\n`);
+      const pad = (t: string, n: number) => (t.length > n ? t.slice(0, n - 1) + "…" : t.padEnd(n));
+      for (const el of res.elements) {
+        process.stdout.write(
+          `  ${pad(el.role, 9)} ${pad(el.name || "(no name)", 34)} ${el.inViewport ? " " : "↓"} ${el.frame ? `[${el.frame}] ` : ""}${el.selector || "(no unique selector)"}\n`
+        );
+      }
+    }
+  );
+
+program
+  .command("frames")
+  .argument("<dir>", "demo project directory")
+  .option("--every <sec>", "seconds between frames (default 3)", "3")
+  .option(
+    "--source <which>",
+    "final (output/final-demo.mp4, default) | raw (latest raw file) | take (the whole take, across a resume's raw files)",
+    "final"
+  )
+  .option("--width <px>", "frame width in px, aspect kept (default 640)", "640")
+  .option("--out <dir>", "output directory (default <dir>/output/frames)")
+  .option("--sheet", "also tile the frames into one contact-sheet PNG", false)
+  .option("--columns <n>", "contact-sheet columns (default 5)", "5")
+  .description(
+    "dump evenly spaced PNG frames from the final video (or the raw take) for review"
+  )
+  .action(
+    async (
+      dir: string,
+      opts: {
+        every: string;
+        source: string;
+        width: string;
+        out?: string;
+        sheet?: boolean;
+        columns: string;
+      }
+    ) => {
+      const everySec = Number(opts.every);
+      if (!(everySec > 0)) throw new Error(`--every must be a positive number of seconds`);
+      if (!["final", "raw", "take"].includes(opts.source)) {
+        throw new Error(`--source must be "final", "raw" or "take"`);
+      }
+      const project = new Project(dir);
+      const res = await extractFrames(project, {
+        everySec,
+        source: opts.source as "final" | "raw" | "take",
+        width: parsePositiveInt("--width", opts.width),
+        outDir: opts.out ? resolve(opts.out) : undefined,
+        sheet: opts.sheet,
+        sheetColumns: parsePositiveInt("--columns", opts.columns),
+      });
+      step("Frames");
+      ok(
+        `${res.files.length} frame(s) every ${res.everySec}s from ${res.source} ` +
+          `(${(res.durationMs / 1000).toFixed(1)}s)`
+      );
+      for (const f of res.files) log(`  ${f}`);
+      if (res.sheet) ok(`contact sheet → ${res.sheet}`);
+    }
+  );
+
 program
   .command("record")
   .argument("<dir>", "demo project directory")
   .option("--profile <dir>", "Chrome user-data dir (logged-in profile)")
+  .option(
+    "--fresh",
+    "wipe and use a throwaway profile for this take (no carried-over cookies/localStorage)",
+    false
+  )
+  .option("--storage-state <file>", STORAGE_STATE_OPT_DESC)
+  .option("--cookie <spec>", COOKIE_OPT_DESC, collectKv, [])
+  .option("--profile-seeded", PROFILE_SEEDED_OPT_DESC, false)
   .option("--headless", "run headless (not recommended for real Chrome)", false)
   .option(
     "--capture <mode>",
     "capture path: playwright (default) | native (ffmpeg screen grab) | obs"
   )
   .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
+  .option("--from-scene <id>", FROM_SCENE_OPT_DESC)
+  .option("--no-replay", NO_REPLAY_OPT_DESC)
   .description("drive the storyboard in Chrome and record raw video + timeline.json")
   .action(
     async (
       dir: string,
-      opts: { profile?: string; headless?: boolean; capture?: string; param?: string[] }
+      opts: {
+        profile?: string;
+        fresh?: boolean;
+        storageState?: string;
+        cookie?: string[];
+        profileSeeded?: boolean;
+        headless?: boolean;
+        capture?: string;
+        param?: string[];
+        fromScene?: string;
+        replay?: boolean;
+      }
     ) => {
       const project = new Project(dir);
       await beginCommand(project, "record");
-      const storyboard = await project.loadStoryboard({ params: parseParams(opts.param) });
+      const load = () => project.loadStoryboard({ params: parseParams(opts.param) });
+      const storyboard = await load();
+      logLint(lintStoryboard(storyboard), log);
       await record(project, storyboard, {
         profileDir: opts.profile,
+        fresh: opts.fresh,
+        ...seedOpts(opts),
+        reloadStoryboard: load,
         headed: !opts.headless,
         capture: parseCapture(opts.capture),
+        fromScene: opts.fromScene,
+        noReplay: opts.replay === false,
       });
     }
   );
@@ -245,6 +796,14 @@ program
   .command("probe")
   .argument("<dir>", "demo project directory")
   .option("--profile <dir>", "Chrome user-data dir (logged-in profile)")
+  .option(
+    "--fresh",
+    "wipe and use a throwaway profile for this take (no carried-over cookies/localStorage)",
+    false
+  )
+  .option("--storage-state <file>", STORAGE_STATE_OPT_DESC)
+  .option("--cookie <spec>", COOKIE_OPT_DESC, collectKv, [])
+  .option("--profile-seeded", PROFILE_SEEDED_OPT_DESC, false)
   .option("--headless", "run headless (not recommended for real Chrome)", false)
   .option(
     "--capture <mode>",
@@ -269,6 +828,10 @@ program
       dir: string,
       opts: {
         profile?: string;
+        fresh?: boolean;
+        storageState?: string;
+        cookie?: string[];
+        profileSeeded?: boolean;
         headless?: boolean;
         capture?: string;
         param?: string[];
@@ -279,14 +842,20 @@ program
       const project = new Project(dir);
       await beginCommand(project, "probe");
       // Relaxed: narration is optional — a probe just exercises the flow.
-      const storyboard = await project.loadStoryboard({
-        relaxed: true,
-        params: parseParams(opts.param),
-      });
+      const load = () =>
+        project.loadStoryboard({
+          relaxed: true,
+          params: parseParams(opts.param),
+        });
+      const storyboard = await load();
+      logLint(lintStoryboard(storyboard), log);
       const goldenMode = !!(opts.golden || opts.updateGolden);
       const probeScenes: ProbeGoldenScene[] = [];
       await record(project, storyboard, {
         profileDir: opts.profile,
+        fresh: opts.fresh,
+        ...seedOpts(opts),
+        reloadStoryboard: load,
         headed: !opts.headless,
         capture: parseCapture(opts.capture),
         ...(goldenMode ? { probe: probeScenes } : {}),
@@ -317,6 +886,10 @@ program
         if (diffs.length > 0) {
           fail(`golden probe mismatch — ${diffs.length} field difference(s):`);
           for (const d of diffs) log(d);
+          const drift = await driftFilesForDiff(project, actual, diffs);
+          for (const f of drift) {
+            log(`  selector drift → ${f.file} (scene ${f.scene}, action #${f.action}: nearest candidates)`);
+          }
           throw new Error(
             `probe --golden failed: the recorded flow drifted from ` +
               `${project.goldenProbePath} (${diffs.length} difference(s)). ` +
@@ -339,6 +912,7 @@ program
   .argument("<dir>", "demo project directory")
   .option("--scene <id>", "regenerate only this scene's narration")
   .option("--force", "re-synthesize every scene even if unchanged", false)
+  .option("--tts <provider>", TTS_OPT_DESC)
   .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
   .option("--lang <code>", LANG_OPT_DESC)
   .option("--langs <codes>", LANGS_OPT_DESC)
@@ -346,8 +920,16 @@ program
   .action(
     async (
       dir: string,
-      opts: { scene?: string; force?: boolean; param?: string[]; lang?: string; langs?: string }
+      opts: {
+        scene?: string;
+        force?: boolean;
+        tts?: string;
+        param?: string[];
+        lang?: string;
+        langs?: string;
+      }
     ) => {
+      applyTtsFlag(opts.tts);
       const storyboard = await new Project(dir).loadStoryboard({
         params: parseParams(opts.param),
       });
@@ -429,25 +1011,69 @@ program
   .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
   .option("--lang <code>", LANG_OPT_DESC)
   .option("--langs <codes>", LANGS_OPT_DESC)
+  .option("--strict", STRICT_OPT_DESC, false)
   .description("trim, sync, mux and caption into output/final-demo.mp4")
   .action(
     async (
       dir: string,
-      opts: { gif?: boolean; param?: string[]; lang?: string; langs?: string }
+      opts: { gif?: boolean; param?: string[]; lang?: string; langs?: string; strict?: boolean }
     ) => {
       const storyboard = await new Project(dir).loadStoryboard({
         params: parseParams(opts.param),
       });
+      let warningTotal = 0;
       for (const lang of langsFrom(opts)) {
         const project = new Project(dir, lang);
         await beginCommand(project, "compose");
         const sb = lang ? localizeStoryboard(storyboard, lang) : storyboard;
-        await compose(project, sb);
+        const report = await compose(project, sb);
+        warningTotal += report.warnings.length;
         if (opts.gif) await exportGif(project);
+        // `output.walkthrough` is a pure post-process on the final video, so
+        // honour it here too (issue #45): a pipeline that drives the stages
+        // itself got chapters + poster and a silently ignored flag.
+        if (sb.output?.walkthrough) await exportWalkthrough(project, sb);
+      }
+      if (opts.strict && warningTotal > 0) {
+        process.exitCode = 1;
+        fail(
+          `--strict: ${warningTotal} compose warning(s) — see the grouped list above, ` +
+            `output/report.json and the frames in output/warnings/`
+        );
       }
     }
   );
 
+program
+  .command("qa")
+  .argument("<dir>", "demo project directory")
+  .option("--lang <code>", "check the <code> language variant's video")
+  .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
+  .option("--json", "print the full JSON result", false)
+  .option("--strict", "exit 1 when any check warns", false)
+  .description(
+    "post-render checks on the finished MP4: blank open, blank poster, loudness, music bed, hold shares, cue readability, frame/chapter hygiene"
+  )
+  .action(
+    async (
+      dir: string,
+      opts: { lang?: string; param?: string[]; json?: boolean; strict?: boolean }
+    ) => {
+      const base = new Project(dir);
+      const storyboard = await base.loadStoryboard({ params: parseParams(opts.param) });
+      const project = new Project(dir, opts.lang);
+      const sb = opts.lang ? localizeStoryboard(storyboard, opts.lang) : storyboard;
+      const res = await runQa(project, sb);
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+      } else {
+        step(`demo QA: ${res.video}`);
+        logQa(res);
+      }
+      if (opts.strict && res.warnings > 0) process.exitCode = 1;
+    }
+  );
+
 program
   .command("gif")
   .argument("<dir>", "demo project directory")
@@ -514,12 +1140,21 @@ program
   .command("render")
   .argument("<dir>", "demo project directory")
   .option("--profile <dir>", "Chrome user-data dir (logged-in profile)")
+  .option(
+    "--fresh",
+    "wipe and use a throwaway profile for this take (no carried-over cookies/localStorage)",
+    false
+  )
+  .option("--storage-state <file>", STORAGE_STATE_OPT_DESC)
+  .option("--cookie <spec>", COOKIE_OPT_DESC, collectKv, [])
+  .option("--profile-seeded", PROFILE_SEEDED_OPT_DESC, false)
   .option("--headless", "run headless", false)
   .option(
     "--capture <mode>",
     "capture path: playwright (default) | native (ffmpeg screen grab) | obs"
   )
   .option("--force-voice", "re-synthesize narration even if unchanged", false)
+  .option("--tts <provider>", TTS_OPT_DESC)
   .option("--gif", "also export output/final-demo.gif after the mux", false)
   .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
   .option(
@@ -528,22 +1163,44 @@ program
   )
   .option("--lang <code>", LANG_OPT_DESC)
   .option("--langs <codes>", `${LANGS_OPT_DESC} — records ONCE, then renders each`)
+  .option("--from-scene <id>", FROM_SCENE_OPT_DESC)
+  .option("--no-replay", NO_REPLAY_OPT_DESC)
+  .option("--strict", STRICT_OPT_DESC, false)
   .description("run the full pipeline: voice → record → captions → compose")
   .action(
     async (
       dir: string,
       opts: {
         profile?: string;
+        fresh?: boolean;
+        storageState?: string;
+        cookie?: string[];
+        profileSeeded?: boolean;
         headless?: boolean;
         capture?: string;
         forceVoice?: boolean;
+        tts?: string;
         gif?: boolean;
         param?: string[];
         variants?: string;
         lang?: string;
         langs?: string;
+        fromScene?: string;
+        replay?: boolean;
+        strict?: boolean;
       }
     ) => {
+      applyTtsFlag(opts.tts);
+      let warningTotal = 0;
+      const strictGate = (): void => {
+        if (opts.strict && warningTotal > 0) {
+          process.exitCode = 1;
+          fail(
+            `--strict: ${warningTotal} compose warning(s) — see the grouped list above, ` +
+              `output/report.json and the frames in output/warnings/`
+          );
+        }
+      };
       const base = new Project(dir);
       await beginCommand(base, "render");
 
@@ -553,6 +1210,8 @@ program
         const results = await renderVariants(dir, variants, {
           record: {
             profileDir: opts.profile,
+            fresh: opts.fresh,
+            ...seedOpts(opts),
             headed: !opts.headless,
             capture: parseCapture(opts.capture),
           },
@@ -575,9 +1234,12 @@ program
         }
       };
 
-      const storyboard = await base.loadStoryboard({ params: parseParams(opts.param) });
+      const load = () => base.loadStoryboard({ params: parseParams(opts.param) });
+      const storyboard = await load();
       const langs = langsFrom(opts);
       const multi = !(langs.length === 1 && langs[0] === undefined);
+      // Browser-free preflight: pacing forecast + pitfalls, before TTS is paid for.
+      for (const lang of langs) logLint(lintStoryboard(storyboard, { lang }), log);
 
       if (!multi) {
         // Default single-language pipeline — voice → record → captions → compose.
@@ -589,20 +1251,33 @@ program
         await stageLog(base, "record", () =>
           record(base, storyboard, {
             profileDir: opts.profile,
+            fresh: opts.fresh,
+            ...seedOpts(opts),
+            reloadStoryboard: load,
             headed: !opts.headless,
             capture: parseCapture(opts.capture),
+            fromScene: opts.fromScene,
+            noReplay: opts.replay === false,
           })
         );
         await stageLog(base, "captions", () => captionsFor(base, storyboard));
-        await stageLog(base, "compose", () => compose(base, storyboard));
+        await stageLog(base, "compose", async () => {
+          const report = await compose(base, storyboard);
+          warningTotal += report.warnings.length;
+          return report;
+        });
         if (opts.gif) await stageLog(base, "gif", () => exportGif(base));
         // Screenshot mode: emit any `still` PNGs from the clean take (a
         // re-extract, not a re-record).
         if (storyboardHasStills(storyboard)) {
           await stageLog(base, "stills", () => extractStills(base));
         }
+        if (storyboard.output?.walkthrough) {
+          await stageLog(base, "walkthrough", () => exportWalkthrough(base, storyboard));
+        }
         step("Done");
         ok(`▶ open ${base.outputPath}`);
+        strictGate();
         return;
       }
 
@@ -612,8 +1287,13 @@ program
       await stageLog(base, "record", () =>
         record(base, storyboard, {
           profileDir: opts.profile,
+          fresh: opts.fresh,
+          ...seedOpts(opts),
+          reloadStoryboard: load,
           headed: !opts.headless,
           capture: parseCapture(opts.capture),
+          fromScene: opts.fromScene,
+          noReplay: opts.replay === false,
         })
       );
       if (storyboardHasStills(storyboard)) {
@@ -628,11 +1308,16 @@ program
           generateVoice(project, sb, { force: opts.forceVoice })
         );
         await stageLog(project, "captions", () => captionsFor(project, sb));
-        await stageLog(project, "compose", () => compose(project, sb));
+        await stageLog(project, "compose", async () => {
+          const report = await compose(project, sb);
+          warningTotal += report.warnings.length;
+          return report;
+        });
         if (opts.gif) await stageLog(project, "gif", () => exportGif(project));
         ok(`▶ open ${project.outputPath}`);
       }
       step("Done");
+      strictGate();
     }
   );