pro-visu 0.3.1 → 0.5.0

package/dist/cli/index.js

@@ -4,7 +4,7 @@
 import { cac } from "cac";
 
 // src/version.ts
-var TOOL_VERSION = true ? "0.3.1" : "0.0.0-dev";
+var TOOL_VERSION = true ? "0.5.0" : "0.0.0-dev";
 
 // src/cli/update-check.ts
 import updateNotifier from "update-notifier";
@@ -31,6 +31,7 @@ function checkForUpdates(version = TOOL_VERSION) {
 import path17 from "path";
 import { existsSync as existsSync4, readFileSync } from "fs";
 import { readFile as readFile5, writeFile as writeFile6 } from "fs/promises";
+import { createRequire as createRequire2 } from "module";
 
 // src/utils/paths.ts
 import path from "path";
@@ -155,7 +156,11 @@ async function ensureChromium(opts) {
     child.on("error", reject);
     child.on(
       "close",
-      (code) => code === 0 ? resolve() : reject(new Error(`Chromium install failed (exit code ${code}).`))
+      (code) => code === 0 ? resolve() : reject(
+        new Error(
+          `Chromium install failed (exit code ${code}). If you're offline or behind a proxy, set HTTPS_PROXY, or point PLAYWRIGHT_DOWNLOAD_HOST at a mirror.`
+        )
+      )
     );
   });
   opts.logger.success("Chromium installed.");
@@ -163,17 +168,111 @@ async function ensureChromium(opts) {
 }
 
 // src/media/ensure-ffmpeg.ts
-import path5 from "path";
 import { existsSync as existsSync2 } from "fs";
-import { rm as rm3 } from "fs/promises";
 import { spawn as spawn3 } from "child_process";
-import { createRequire as createRequire2 } from "module";
 
 // src/media/ffmpeg.ts
-import path4 from "path";
+import path5 from "path";
 import { spawn as spawn2 } from "child_process";
-import { rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import ffmpegStatic from "ffmpeg-static";
+import { rm as rm3, writeFile as writeFile2 } from "fs/promises";
+
+// src/media/ffmpeg-binary.ts
+import os from "os";
+import path4 from "path";
+import https from "https";
+import { createWriteStream } from "fs";
+import { mkdir as mkdir2, rename, rm as rm2, chmod } from "fs/promises";
+import { createGunzip } from "zlib";
+import { pipeline } from "stream/promises";
+var FFMPEG_RELEASE = process.env.FFMPEG_BINARY_RELEASE || "b6.1.1";
+var BINARIES_URL = process.env.FFMPEG_BINARIES_URL || "https://github.com/eugeneware/ffmpeg-static/releases/download";
+var SUPPORTED = {
+  darwin: ["x64", "arm64"],
+  linux: ["x64", "ia32", "arm64", "arm"],
+  win32: ["x64", "ia32"],
+  freebsd: ["x64"]
+};
+function ffmpegIsSupported() {
+  return (SUPPORTED[process.platform] ?? []).includes(process.arch);
+}
+function ffmpegCacheDir() {
+  const base = process.env.PROVISU_FFMPEG_DIR || path4.join(os.homedir(), ".cache", "pro-visu", "ffmpeg");
+  return path4.join(base, FFMPEG_RELEASE);
+}
+function ffmpegCachedBinary() {
+  return path4.join(ffmpegCacheDir(), process.platform === "win32" ? "ffmpeg.exe" : "ffmpeg");
+}
+function ffmpegBinaryPath() {
+  return process.env.FFMPEG_BIN || ffmpegCachedBinary();
+}
+function ffmpegDownloadUrl() {
+  if (!ffmpegIsSupported()) return null;
+  return `${BINARIES_URL}/${FFMPEG_RELEASE}/ffmpeg-${process.platform}-${process.arch}.gz`;
+}
+function getFollowing(url, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { "User-Agent": "pro-visu" } }, (res) => {
+      const status = res.statusCode ?? 0;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume();
+        if (redirects <= 0) return reject(new Error("Too many redirects fetching ffmpeg."));
+        resolve(getFollowing(new URL(res.headers.location, url).toString(), redirects - 1));
+        return;
+      }
+      if (status !== 200) {
+        res.resume();
+        reject(new Error(`ffmpeg download failed: HTTP ${status} for ${url}`));
+        return;
+      }
+      resolve(res);
+    });
+    req.on("error", reject);
+  });
+}
+var NETWORK_CODES = /* @__PURE__ */ new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT"]);
+function withNetworkHint(err) {
+  const code = err.code;
+  if (code && NETWORK_CODES.has(code)) {
+    return new Error(
+      `${err.message} \u2014 you appear to be offline or behind a proxy. Set FFMPEG_BINARIES_URL to a reachable mirror, or FFMPEG_BIN to a local ffmpeg binary.`
+    );
+  }
+  return err;
+}
+async function downloadFfmpeg(onProgress) {
+  const url = ffmpegDownloadUrl();
+  if (!url) {
+    throw new Error(
+      `No prebuilt ffmpeg for ${process.platform}/${process.arch}. Set FFMPEG_BIN to a local ffmpeg binary.`
+    );
+  }
+  const dest = ffmpegCachedBinary();
+  const tmp = `${dest}.download`;
+  await mkdir2(path4.dirname(dest), { recursive: true });
+  await rm2(tmp, { force: true });
+  try {
+    const res = await getFollowing(url);
+    if (onProgress) {
+      const totalHeader = Number(res.headers["content-length"]);
+      const total = Number.isFinite(totalHeader) && totalHeader > 0 ? totalHeader : void 0;
+      let downloaded = 0;
+      res.on("data", (chunk) => {
+        downloaded += chunk.length;
+        onProgress(downloaded, total);
+      });
+    }
+    await pipeline(res, createGunzip(), createWriteStream(tmp));
+  } catch (err) {
+    throw withNetworkHint(err);
+  }
+  await chmod(tmp, 493).catch(() => {
+  });
+  await rm2(dest, { force: true });
+  await rename(tmp, dest);
+  return dest;
+}
+
+// src/media/ffmpeg.ts
 var SCALE_COLOR = "out_color_matrix=bt709:out_range=tv";
 var COLOR_TAGS = [
   "-colorspace",
@@ -186,11 +285,7 @@ var COLOR_TAGS = [
   "tv"
 ];
 function ffmpegPath() {
-  const p = ffmpegStatic;
-  if (!p) {
-    throw new Error("ffmpeg-static did not provide a binary for this platform.");
-  }
-  return p;
+  return ffmpegBinaryPath();
 }
 function buildTranscodeArgs(args) {
   const seek = args.startOffsetSeconds && args.startOffsetSeconds > 0 ? ["-ss", args.startOffsetSeconds.toFixed(3)] : [];
@@ -332,7 +427,7 @@ function buildConcatArgs(listFile, outPath) {
   ];
 }
 async function concatMp4(segments, outPath, logger, signal) {
-  await ensureDir(path4.dirname(outPath));
+  await ensureDir(path5.dirname(outPath));
   const listFile = `${outPath}.concat.txt`;
   const list = segments.map((s) => `file '${s.replace(/\\/g, "/")}'`).join("\n");
   await writeFile2(listFile, `${list}
@@ -340,7 +435,7 @@ async function concatMp4(segments, outPath, logger, signal) {
   try {
     await runFfmpeg(buildConcatArgs(listFile, outPath), logger, signal);
   } finally {
-    await rm2(listFile, { force: true });
+    await rm3(listFile, { force: true });
   }
 }
 async function runFfmpeg(argv, logger, signal) {
@@ -362,7 +457,7 @@ ${stderr.slice(-2e3)}`));
   });
 }
 async function transcodeToMp4(args) {
-  await ensureDir(path4.dirname(args.outputPath));
+  await ensureDir(path5.dirname(args.outputPath));
   await runFfmpeg(buildTranscodeArgs(args), args.logger, args.signal);
 }
 function aspectTarget(aspect) {
@@ -467,7 +562,6 @@ function buildStillSegmentArgs(a) {
 }
 
 // src/media/ensure-ffmpeg.ts
-var require3 = createRequire2(import.meta.url);
 async function ffmpegWorks() {
   let bin;
   try {
@@ -488,42 +582,35 @@ async function ffmpegWorks() {
     child.on("close", (code) => resolve(code === 0));
   });
 }
-function resolveInstallScript() {
-  try {
-    return require3.resolve("ffmpeg-static/install.js");
-  } catch {
-    try {
-      const pkg = require3.resolve("ffmpeg-static/package.json");
-      return path5.join(path5.dirname(pkg), "install.js");
-    } catch {
-      return null;
-    }
-  }
-}
 async function ensureFfmpeg(opts) {
   if (await ffmpegWorks()) return true;
   if (opts.checkOnly) return false;
-  const installScript = resolveInstallScript();
-  if (!installScript) {
-    opts.logger.error("ffmpeg-static is not installed; cannot fetch an ffmpeg binary.");
+  if (process.env.FFMPEG_BIN) {
+    opts.logger.error(`FFMPEG_BIN is set to "${process.env.FFMPEG_BIN}" but that binary won't run.`);
+    return false;
+  }
+  if (!ffmpegIsSupported()) {
+    opts.logger.error(
+      `No prebuilt ffmpeg for ${process.platform}/${process.arch}. Set FFMPEG_BIN to a local ffmpeg binary.`
+    );
     return false;
   }
   opts.logger.info("Fetching ffmpeg (one-time, ~80 MB)\u2026");
   try {
-    await rm3(ffmpegPath(), { force: true });
-  } catch {
-  }
-  await new Promise((resolve, reject) => {
-    const child = spawn3(process.execPath, [installScript], {
-      cwd: path5.dirname(installScript),
-      stdio: "inherit"
+    let lastQuartile = 0;
+    await downloadFfmpeg((downloaded, total) => {
+      if (!total) return;
+      const quartile = Math.floor(downloaded / total * 4);
+      if (quartile > lastQuartile && quartile < 4) {
+        lastQuartile = quartile;
+        const mb = (n) => (n / 1024 / 1024).toFixed(0);
+        opts.logger.info(`ffmpeg download: ${quartile * 25}% (${mb(downloaded)}/${mb(total)} MB)`);
+      }
     });
-    child.on("error", reject);
-    child.on(
-      "close",
-      (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg download failed (exit code ${code}).`))
-    );
-  });
+  } catch (err) {
+    opts.logger.error(`ffmpeg download failed: ${err.message}`);
+    return false;
+  }
   if (!await ffmpegWorks()) {
     opts.logger.error("ffmpeg was downloaded but still won't run on this platform.");
     return false;
@@ -578,6 +665,16 @@ var serverSettingsSchema = z.object({
   /** If a server is already reachable at the URL, use it as-is (don't start or stop one). */
   reuseExisting: z.boolean().default(true).describe("If a server is already reachable at the URL, use it as-is (don't start or stop one). Default true.")
 }).strict();
+var captureSettingsSchema = z.object({
+  /** Query params appended to every URL-based asset (e.g. `{ capture: "1" }` → `?capture=1`). */
+  query: z.record(z.string(), z.string()).optional().describe('Query params appended to every URL-based asset, e.g. { capture: "1" }.'),
+  /** Cookies set on every capture context before navigation, scoped to the asset's origin. */
+  cookies: z.array(z.object({ name: z.string().min(1), value: z.string() }).strict()).optional().describe("Cookies set on every capture context before navigation (scoped to the asset's origin)."),
+  /** localStorage entries seeded before the page's own scripts run. */
+  localStorage: z.record(z.string(), z.string()).optional().describe("localStorage entries seeded (per origin) before the page's own scripts run."),
+  /** JS source run in every page before its own scripts — e.g. set a global capture flag. */
+  initScript: z.string().optional().describe("JS run in every page before its own scripts (e.g. `window.__PV_CAPTURE__ = true`).")
+}).strict();
 var settingsSchema = z.object({
   /** Output directory, relative to the repo root. */
   outDir: z.string().min(1).default("pro-visu").describe('Output directory for generated assets, relative to the repo root (default "pro-visu").'),
@@ -599,17 +696,19 @@ var settingsSchema = z.object({
   defaults: z.record(z.string(), z.record(z.string(), z.unknown())).default({}).describe("Per-generator option defaults, keyed by generator id, merged underneath each asset's own options."),
   /** Optional managed dev/prod server lifecycle (build → start → wait → … → stop). */
   server: serverSettingsSchema.optional().describe("Build \u2192 start \u2192 wait \u2192 capture \u2192 stop a server automatically."),
+  /** "Capture mode" toggles (query/cookies/localStorage/init script) applied to every URL capture. */
+  capture: captureSettingsSchema.optional().describe("Capture-mode toggles applied to every URL-based asset (e.g. disable animations / hide the cookie banner)."),
   /** Render quality. "draft" lowers fps/scale and speeds the encoder for fast iteration. */
   quality: z.enum(["draft", "final"]).default("final").describe('Render quality; "draft" lowers fps/scale and speeds the encoder for fast iteration (default "final").'),
   /** Skip assets whose inputs+options+tool fingerprint is unchanged (opt-in; can be stale). */
   cache: z.boolean().default(false).describe("Skip assets whose inputs+options+tool fingerprint is unchanged (opt-in; can be stale). Default false.")
-});
+}).strict();
 var assetSpecSchema = z.object({
   name: z.string().min(1),
   /**
    * Page to capture: an absolute `https://…` URL, or a path like `/shop` resolved against the
    * managed server's URL. Optional — with a managed server, a url-based asset that omits it
-   * captures the server root; local generators (`scene`, `palette`) need no url.
+   * captures the server root; local generators (`specimen`, `palette`, `wall`, …) need no url.
    */
   url: z.string().min(1).refine((s) => /^https?:\/\//i.test(s) || s.startsWith("/"), {
     message: 'url must be an absolute http(s) URL or a path starting with "/" (resolved against the managed server)'
@@ -624,9 +723,11 @@ var assetSpecSchema = z.object({
   inputs: z.record(z.string(), z.string()).default({})
 }).strict();
 var showcaseConfigSchema = z.object({
+  /** JSON configs may carry an editor `$schema` pointer; accepted and ignored at runtime. */
+  $schema: z.string().optional(),
   settings: settingsSchema.default({}),
   assets: z.array(assetSpecSchema).min(1, "Define at least one asset in `assets`.")
-}).superRefine((cfg, ctx) => {
+}).strict().superRefine((cfg, ctx) => {
   const seen = /* @__PURE__ */ new Set();
   for (const [i, asset] of cfg.assets.entries()) {
     if (seen.has(asset.name)) {
@@ -648,12 +749,12 @@ import { stat as stat2 } from "fs/promises";
 import { z as z2 } from "zod";
 var easingSchema = z2.enum([
   "linear",
-  "easeInOutCubic",
-  "easeInOutQuad",
-  "easeOutCubic",
-  "easeInOutSine",
-  "easeInOutExpo",
-  "easeOutQuint"
+  "ease-in-out-cubic",
+  "ease-in-out-quad",
+  "ease-out-cubic",
+  "ease-in-out-sine",
+  "ease-in-out-expo",
+  "ease-out-quint"
 ]);
 var choreographyStepSchema = z2.object({
   /** Target: a 0..1 number, an "NN%" string, or a CSS selector to bring into view. */
@@ -662,7 +763,7 @@ var choreographyStepSchema = z2.object({
   durationMs: z2.number().int().nonnegative().optional().describe("Travel time to this target (ms). Default 1200."),
   /** Hold time at this target after arriving (ms). Default 800. */
   holdMs: z2.number().int().nonnegative().optional().describe("Hold time at this target after arriving (ms). Default 800."),
-  easing: easingSchema.optional().describe('Easing for the travel to this target. Default "easeInOutCubic".')
+  easing: easingSchema.optional().describe('Easing for the travel to this target. Default "ease-in-out-cubic".')
 }).strict();
 var interactionActionSchema = z2.object({
   do: z2.enum(["move", "click", "hover", "type", "scrollTo", "wait"]).describe("What this step does."),
@@ -728,8 +829,8 @@ var scrollReelOptionsSchema = z2.object({
   /** Output frames per second (re-encoded from the recording). */
   fps: z2.number().int().positive().max(120).default(30).describe("Output frames per second (re-encoded from the recording). Default 30."),
   /** Time to scroll from top to bottom (ms). */
-  duration: z2.number().int().positive().default(6e3).describe("Time to scroll from top to bottom (ms). Default 6000."),
-  easing: easingSchema.default("easeInOutCubic").describe('Easing for the default top\u2192bottom scroll. Default "easeInOutCubic".'),
+  durationMs: z2.number().int().positive().default(6e3).describe("Time to scroll from top to bottom (ms). Default 6000."),
+  easing: easingSchema.default("ease-in-out-cubic").describe('Easing for the default top\u2192bottom scroll. Default "ease-in-out-cubic".'),
   /** Dwell at the top before scrolling (ms). */
   startDelayMs: z2.number().int().nonnegative().default(500).describe("Dwell at the top before scrolling (ms). Default 500."),
   /** Dwell at the bottom after scrolling (ms). */
@@ -788,7 +889,7 @@ var scrollReelOptionsSchema = z2.object({
     scaleFrom: z2.number().positive().optional().describe("Start scale (1 = no zoom). Default 1."),
     /** End scale. Default 1.08. */
     scaleTo: z2.number().positive().optional().describe("End scale. Default 1.08."),
-    easing: easingSchema.optional().describe('Easing for the zoom ramp. Default "easeInOutCubic".'),
+    easing: easingSchema.optional().describe('Easing for the zoom ramp. Default "ease-in-out-cubic".'),
     /** Zoom origin X within the viewport (0 = left, 1 = right). Default 0.5. */
     originX: z2.number().min(0).max(1).optional().describe("Zoom origin X within the viewport (0 = left, 1 = right). Default 0.5."),
     /** Zoom origin Y within the viewport (0 = top, 1 = bottom). Default 0.5. */
@@ -943,30 +1044,67 @@ var scrollReelOptionsSchema = z2.object({
 import path6 from "path";
 import { mkdtemp } from "fs/promises";
 
+// src/pipeline/capture.ts
+function withCaptureQuery(url, capture) {
+  if (!url || !capture?.query) return url;
+  try {
+    const u = new URL(url);
+    for (const [k, v] of Object.entries(capture.query)) u.searchParams.set(k, v);
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+async function applyCapture(context, capture, url) {
+  if (!capture) return;
+  if (capture.cookies?.length && url) {
+    try {
+      const origin = new URL(url).origin;
+      await context.addCookies(
+        capture.cookies.map((c) => ({ name: c.name, value: c.value, url: origin }))
+      );
+    } catch {
+    }
+  }
+  const scripts = [];
+  if (capture.localStorage) {
+    scripts.push(
+      `try{var e=${JSON.stringify(capture.localStorage)};for(var k in e)localStorage.setItem(k,e[k]);}catch(_){}`
+    );
+  }
+  if (capture.initScript) scripts.push(capture.initScript);
+  if (scripts.length) await context.addInitScript(scripts.join("\n"));
+}
+
 // src/generators/scroll-reel/scroll.ts
 var EASINGS = {
   linear: (t) => t,
-  easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
-  easeInOutQuad: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
-  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
-  easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
-  easeInOutExpo: (t) => t === 0 ? 0 : t === 1 ? 1 : t < 0.5 ? Math.pow(2, 20 * t - 10) / 2 : (2 - Math.pow(2, -20 * t + 10)) / 2,
-  easeOutQuint: (t) => 1 - Math.pow(1 - t, 5)
+  "ease-in-out-cubic": (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+  "ease-in-out-quad": (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+  "ease-out-cubic": (t) => 1 - Math.pow(1 - t, 3),
+  "ease-in-out-sine": (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+  "ease-in-out-expo": (t) => t === 0 ? 0 : t === 1 ? 1 : t < 0.5 ? Math.pow(2, 20 * t - 10) / 2 : (2 - Math.pow(2, -20 * t + 10)) / 2,
+  "ease-out-quint": (t) => 1 - Math.pow(1 - t, 5)
 };
 async function prepareScroll(args) {
   const target = findScrollTarget(document, getComputedStyle);
   forceInstant(target);
   const sleep2 = (ms) => new Promise((resolve) => setTimeout(() => resolve(), ms));
+  const withCap = (p, ms) => Promise.race([p ?? Promise.resolve(), sleep2(ms)]);
   scrollTargetTo(target, maxScrollOf(target));
   await sleep2(Math.max(0, args.settleMs));
   try {
-    await (document.fonts?.ready ?? Promise.resolve());
+    await withCap(document.fonts?.ready ?? null, 5e3);
   } catch {
   }
   try {
     const imgs = Array.from(document.images ?? []);
-    await Promise.all(imgs.map((im) => im.decode ? im.decode().catch(() => {
-    }) : null));
+    await withCap(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      Promise.all(imgs.map((im) => im.decode ? im.decode().catch(() => {
+      }) : null)),
+      4e3
+    );
   } catch {
   }
   scrollTargetTo(target, 0);
@@ -1311,17 +1449,17 @@ async function pageScroll(args) {
   const { durationMs, easing, startDelayMs, endDwellMs } = args;
   const ease = (t) => {
     switch (easing) {
-      case "easeInOutCubic":
+      case "ease-in-out-cubic":
         return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
-      case "easeInOutQuad":
+      case "ease-in-out-quad":
         return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
-      case "easeOutCubic":
+      case "ease-out-cubic":
         return 1 - Math.pow(1 - t, 3);
-      case "easeInOutSine":
+      case "ease-in-out-sine":
         return -(Math.cos(Math.PI * t) - 1) / 2;
-      case "easeInOutExpo":
+      case "ease-in-out-expo":
         return t === 0 ? 0 : t === 1 ? 1 : t < 0.5 ? Math.pow(2, 20 * t - 10) / 2 : (2 - Math.pow(2, -20 * t + 10)) / 2;
-      case "easeOutQuint":
+      case "ease-out-quint":
         return 1 - Math.pow(1 - t, 5);
       default:
         return t;
@@ -1410,6 +1548,7 @@ async function captureScrollWebm(args) {
       size: { width: options.width, height: options.height }
     }
   });
+  await applyCapture(context, args.capture, url);
   const page = await context.newPage();
   const video = page.video();
   const recStart = Date.now();
@@ -1424,7 +1563,7 @@ async function captureScrollWebm(args) {
     await page.evaluate(prepareScroll, { settleMs: PREWARM_SETTLE_MS });
     leadSeconds = (Date.now() - recStart) / 1e3;
     const distance = await page.evaluate(pageScroll, {
-      durationMs: options.duration,
+      durationMs: options.durationMs,
       easing: options.easing,
       startDelayMs: options.startDelayMs,
       endDwellMs: options.endDwellMs
@@ -1444,10 +1583,10 @@ async function captureScrollWebm(args) {
 }
 
 // src/media/frame-capture.ts
-import os from "os";
+import os2 from "os";
 import path7 from "path";
 function autoWorkers() {
-  const cores = os.cpus()?.length ?? 2;
+  const cores = os2.cpus()?.length ?? 2;
   return Math.max(1, Math.min(6, Math.floor(cores / 2)));
 }
 function planFrames(totalFrames, workers) {
@@ -1895,7 +2034,7 @@ function scrollTimelineTotalMs(o) {
   if (o.autoSections) {
     return autoSectionsBudgetMs(o.autoSections);
   }
-  return o.startDelayMs + o.duration + o.endDwellMs;
+  return o.startDelayMs + o.durationMs + o.endDwellMs;
 }
 function boomerangSpec(spec) {
   const forward = spec.segments.map((s) => ({ ...s, durationFraction: s.durationFraction / 2 }));
@@ -1991,7 +2130,7 @@ async function buildScrollTimeline(page, options, totalSeconds, logger) {
   return finalize(
     defaultTimelineSpec({
       startDelayMs: options.startDelayMs,
-      durationMs: options.duration,
+      durationMs: options.durationMs,
       endDwellMs: options.endDwellMs,
       easing: options.easing
     })
@@ -2019,6 +2158,7 @@ async function captureScrollFrames(a) {
     signal: a.signal,
     prepare: async (page, { logger }) => {
       if (a.colorScheme) await page.emulateMedia({ colorScheme: a.colorScheme });
+      await applyCapture(page.context(), a.capture, a.url);
       await installNetworkHygiene(page, options);
       await installPreNav(page, options);
       logger.debug(`navigating to ${a.url} (waitUntil=${options.waitUntil})`);
@@ -2483,6 +2623,7 @@ async function captureInteractionWebm(args) {
     deviceScaleFactor: options.deviceScaleFactor,
     recordVideo: { dir: recordDir, size: { width: options.width, height: options.height } }
   });
+  await applyCapture(context, args.capture, url);
   const page = await context.newPage();
   const video = page.video();
   const actions = options.actions ?? [];
@@ -2545,6 +2686,7 @@ async function captureFocusWebm(args) {
     deviceScaleFactor: options.deviceScaleFactor,
     recordVideo: { dir: recordDir, size: { width: options.width, height: options.height } }
   });
+  await applyCapture(context, args.capture, url);
   const page = await context.newPage();
   const video = page.video();
   const actions = focus.actions ?? [];
@@ -2639,6 +2781,7 @@ async function run(ctx, options) {
     ctx.logger.info(`recording ${url} (focus: ${options.focus.selector})`);
     const { webmPath, leadSeconds, durationSeconds, cropBox } = await captureFocusWebm({
       browser: ctx.browser,
+      capture: ctx.capture,
       url,
       options,
       colorScheme: scheme,
@@ -2692,6 +2835,7 @@ async function run(ctx, options) {
     ctx.logger.info(`recording ${url} (interaction, ${options.actions.length} action(s))`);
     const { webmPath, leadSeconds, durationSeconds } = await captureInteractionWebm({
       browser: ctx.browser,
+      capture: ctx.capture,
       url,
       options,
       colorScheme: scheme,
@@ -2747,7 +2891,7 @@ async function run(ctx, options) {
         ...options,
         choreography: r.choreography,
         autoSections: r.autoSections,
-        duration: r.durationMs ?? options.duration
+        durationMs: r.durationMs ?? options.durationMs
       };
       const segPath = path10.join(ctx.tmpDir, `${slugify(ctx.target.name)}-route-${i}.mp4`);
       ctx.logger.info(
@@ -2755,6 +2899,7 @@ async function run(ctx, options) {
       );
       await captureScrollFrames({
         browser: ctx.browser,
+        capture: ctx.capture,
         url: routeUrl,
         options: routeOpts,
         outPath: segPath,
@@ -2806,10 +2951,11 @@ async function run(ctx, options) {
     }
     const fileName = options.fileName ?? `${slugify(ctx.target.name)}.mp4`;
     const outPath = ctx.resolveOutPath(fileName);
-    const durationSeconds = (options.startDelayMs + options.duration + options.endDwellMs) / 1e3;
+    const durationSeconds = (options.startDelayMs + options.durationMs + options.endDwellMs) / 1e3;
     ctx.logger.info(`recording ${url} (realtime)`);
     const { webmPath, leadSeconds } = await captureScrollWebm({
       browser: ctx.browser,
+      capture: ctx.capture,
       url,
       options,
       tmpDir: ctx.tmpDir,
@@ -2839,7 +2985,7 @@ async function run(ctx, options) {
       format: "mp4",
       width: options.width,
       height: options.height,
-      durationMs: options.startDelayMs + options.duration + options.endDwellMs,
+      durationMs: options.startDelayMs + options.durationMs + options.endDwellMs,
       bytes: stats.size,
       contentHash,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2873,6 +3019,7 @@ async function run(ctx, options) {
     ctx.logger.info(`recording ${url}${label} (frame-stepped, ${workers} worker(s))`);
     await captureScrollFrames({
       browser: ctx.browser,
+      capture: ctx.capture,
       url,
       options: vopts,
       outPath: captureMp4,
@@ -2922,7 +3069,7 @@ import { imageSize } from "image-size";
 
 // src/generators/screenshots/options.ts
 import { z as z3 } from "zod";
-var breakpointSchema = z3.object({
+var viewportSchema = z3.object({
   name: z3.string().min(1).describe('Label for this viewport \u2014 used in the filename + manifest id (e.g. "desktop").'),
   width: z3.number().int().positive().describe("Viewport width in CSS px."),
   /** Viewport height. Note: ignored for `fullPage` shots (Playwright resizes to the page height);
@@ -2930,8 +3077,8 @@ var breakpointSchema = z3.object({
   height: z3.number().int().positive().default(900).describe(
     "Viewport height in CSS px. Default 900. Ignored for fullPage shots; only affects viewport/element captures."
   ),
-  /** Override the generator-level deviceScaleFactor for this breakpoint. */
-  deviceScaleFactor: z3.number().positive().max(4).optional().describe("Override the generator-level deviceScaleFactor for this breakpoint. Omit to inherit it.")
+  /** Override the generator-level deviceScaleFactor for this viewport. */
+  deviceScaleFactor: z3.number().positive().max(4).optional().describe("Override the generator-level deviceScaleFactor for this viewport. Omit to inherit it.")
 }).strict();
 var elementShotSchema = z3.object({
   selector: z3.string().min(1).describe("CSS selector of the element to shoot."),
@@ -2939,7 +3086,7 @@ var elementShotSchema = z3.object({
   name: z3.string().min(1).describe("Name used in the filename + manifest id for this element shot.")
 }).strict();
 var screenshotsOptionsSchema = z3.object({
-  breakpoints: z3.array(breakpointSchema).min(1).default([
+  viewports: z3.array(viewportSchema).min(1).default([
     { name: "desktop", width: 1440, height: 900 },
     { name: "mobile", width: 390, height: 844 }
   ]).describe(
@@ -2953,8 +3100,8 @@ var screenshotsOptionsSchema = z3.object({
   deviceScaleFactor: z3.number().positive().max(4).default(2).describe("Render scale (2 = retina-crisp). Default 2."),
   waitUntil: z3.enum(["load", "domcontentloaded", "networkidle", "commit"]).default("networkidle").describe('Page-load milestone to wait for before capturing. Default "networkidle".'),
   waitForSelector: z3.string().optional().describe("Optional element to wait for before capturing (e.g. a hero image). Omit to skip."),
-  /** Element captures taken at every breakpoint. */
-  elements: z3.array(elementShotSchema).default([]).describe("Specific elements to crop (in addition to the page) at every breakpoint. Default none."),
+  /** Element captures taken at every viewport. */
+  elements: z3.array(elementShotSchema).default([]).describe("Specific elements to crop (in addition to the page) at every viewport. Default none."),
   /** png only: capture with a transparent background. */
   omitBackground: z3.boolean().default(false).describe("Capture with a transparent background (png only). Default false."),
   /** Extra settle time after load before capturing (ms). */
@@ -2984,14 +3131,14 @@ async function mapLimit(items, limit, fn) {
 var MIN_PREPARE_SETTLE_MS = 600;
 async function captureScreenshots(args) {
   const { options } = args;
-  const perBreakpoint = await mapLimit(
-    options.breakpoints,
-    Math.min(3, options.breakpoints.length),
-    (bp) => captureBreakpoint(args, bp)
+  const perViewport = await mapLimit(
+    options.viewports,
+    Math.min(3, options.viewports.length),
+    (bp) => captureViewport(args, bp)
   );
-  return perBreakpoint.flat();
+  return perViewport.flat();
 }
-async function captureBreakpoint(args, bp) {
+async function captureViewport(args, bp) {
   const { browser, url, options, logger } = args;
   const shots = [];
   {
@@ -2999,6 +3146,7 @@ async function captureBreakpoint(args, bp) {
       viewport: { width: bp.width, height: bp.height },
       deviceScaleFactor: bp.deviceScaleFactor ?? options.deviceScaleFactor
     });
+    await applyCapture(context, args.capture, url);
     const page = await context.newPage();
     try {
       logger.debug(`[${bp.name}] navigating to ${url}`);
@@ -3069,7 +3217,8 @@ async function run2(ctx, options) {
     browser: ctx.browser,
     url,
     options,
-    logger: ctx.logger
+    logger: ctx.logger,
+    capture: ctx.capture
   });
   const records = [];
   for (const shot of shots) {
@@ -3114,276 +3263,148 @@ var screenshotsGenerator = {
 };
 
 // src/generators/wall/options.ts
-import { z as z6 } from "zod";
-
-// src/generators/scene/scene-options.ts
 import { z as z5 } from "zod";
 
-// src/generators/specimen/options.ts
+// src/generators/scene/scene-options.ts
 import { z as z4 } from "zod";
-var pulseSchema = z4.object({
-  /** Human label for the beat, e.g. "color sweep" — purely to keep the config readable. */
-  name: z4.string().default("").describe('Human label for the beat, e.g. "color sweep" \u2014 purely to keep the config readable.'),
-  /** Length of this beat, in seconds. */
-  duration: z4.number().positive().describe("Length of this beat, in seconds."),
-  /** Fraction of cells whose glyph changes during this beat (0..1; 1 = every cell once). */
-  chars: z4.number().nonnegative().default(0).describe("Fraction of cells whose glyph changes during this beat (0..1; 1 = every cell once; 0 = a hold). Default 0."),
-  /** Fraction of cells whose color changes during this beat (0..1; 1 = every cell once). */
-  colors: z4.number().nonnegative().default(0).describe("Fraction of cells whose color changes during this beat (0..1; 1 = every cell once). Default 0."),
-  /**
-   * Target color for this beat's color changes. When set, every color change in the beat goes to
-   * this exact token (a deliberate sweep) instead of a weighted-random pick. Set `colors: 1` with
-   * `pacing: "even"` to wash the whole specimen to one color evenly. Omit for the default
-   * scattered, weighted-random recoloring.
-   */
-  color: z4.enum(["foreground", "muted", "accent"]).optional().describe("Target color token for this beat's color changes (a deliberate sweep); omit for the default weighted-random recoloring."),
-  /**
-   * How the changes are distributed in time across the beat — like a CSS easing curve:
-   * "linear"/"even" = uniform, "ease-in" = front-loaded, "ease-out" = back-loaded,
-   * "ease-in-out" = bunched at both ends, "random" = scattered.
-   */
-  pacing: z4.enum(["even", "linear", "ease-in", "ease-out", "ease-in-out", "random"]).default("even").describe("How changes are distributed in time across the beat (CSS-easing-like): even/linear, ease-in, ease-out, ease-in-out, random. Default even.")
+var specimenWirePulseSchema = z4.object({
+  name: z4.string().default(""),
+  /** Length of this beat, in seconds (wire unit). */
+  duration: z4.number().positive(),
+  chars: z4.number().nonnegative().default(0),
+  colors: z4.number().nonnegative().default(0),
+  color: z4.enum(["foreground", "muted", "accent"]).optional(),
+  pacing: z4.enum(["even", "linear", "ease-in", "ease-out", "ease-in-out", "random"]).default("even")
 }).strict();
-var P = (name, duration, chars = 0, colors = 0) => ({
-  name,
-  duration,
-  chars,
-  colors,
-  pacing: "even"
-});
-var DEFAULT_PULSES = [
-  P("intro hold", 0.8),
-  P("first letters", 0.8, 0.15, 0),
-  P("settle", 1.5),
-  P("ripple", 1, 0.08, 0.04),
-  P("color sweep", 1.2, 0, 0.13),
-  P("rest", 1.2),
-  P("quick burst", 0.6, 0.18, 0),
-  P("drift", 1.2, 0, 0.08),
-  P("finale", 1.2, 0.18, 0.13),
-  P("outro hold", 0.5)
-];
-var DEMO_PULSES = [
-  { name: "linear", duration: 5, chars: 0.5, pacing: "linear" },
-  { name: "hold", duration: 2 },
-  { name: "ease-in", duration: 5, chars: 0.5, pacing: "ease-in" },
-  { name: "hold", duration: 2 },
-  { name: "ease-out", duration: 5, chars: 0.5, pacing: "ease-out" },
-  { name: "hold", duration: 2 },
-  { name: "ease-in-out", duration: 5, chars: 0.5, pacing: "ease-in-out" },
-  { name: "hold", duration: 2 },
-  { name: "random", duration: 5, chars: 0.5, pacing: "random" },
-  { name: "hold", duration: 2 },
-  // Even, per-character color sweeps: each washes every glyph to one token, evenly across the beat.
-  { name: "sweep \u2192 muted", duration: 4, colors: 1, color: "muted", pacing: "even" },
-  { name: "sweep \u2192 accent", duration: 4, colors: 1, color: "accent", pacing: "even" },
-  { name: "sweep \u2192 foreground", duration: 4, colors: 1, color: "foreground", pacing: "even" },
-  { name: "hold", duration: 2 },
-  { name: "weighted recolor", duration: 5, colors: 0.6 },
-  { name: "hold", duration: 2 },
-  { name: "mingle", duration: 5, chars: 0.3, colors: 0.3 }
-];
-var SWEEP_COLORS = {
-  background: "#0b0b0f",
-  foreground: "#f4f4f5",
-  muted: "#6b7280",
-  accent: "#7c9cff"
-};
-var SWEEP_PULSES = [
-  { name: "hold", duration: 0.8 },
-  { name: "to muted", duration: 2.2, colors: 1, color: "muted", pacing: "ease-in-out" },
-  { name: "settle", duration: 0.6 },
-  { name: "to accent", duration: 2.2, colors: 1, color: "accent", pacing: "ease-in-out" },
-  { name: "settle", duration: 0.6 },
-  { name: "to foreground", duration: 2.2, colors: 1, color: "foreground", pacing: "ease-in-out" },
-  { name: "glyph drift", duration: 1.4, chars: 0.5, pacing: "even" },
-  { name: "hold", duration: 0.6 }
-];
-var SPECIMEN_TEMPLATES = {
-  demo: { demo: true, mirror: false, lines: 4, pulses: DEMO_PULSES },
-  sweep: {
-    mirror: true,
-    lines: 4,
-    colors: SWEEP_COLORS,
-    pulses: SWEEP_PULSES
-  }
-};
-function applyTemplate(raw) {
-  if (!raw || typeof raw !== "object") return raw;
-  const r = raw;
-  const tmpl = typeof r.template === "string" ? SPECIMEN_TEMPLATES[r.template] : void 0;
-  return tmpl ? { ...tmpl, ...r } : raw;
-}
-var specimenObjectSchema = z4.object({
-  font: z4.string().min(1).describe("Font file to showcase (path relative to the working dir, or absolute). Required."),
-  template: z4.enum(["demo", "sweep"]).optional().describe("Load a named option preset (demo or sweep); your explicit options still override what it sets."),
-  name: z4.string().default("").describe('Display name shown bottom-left (e.g. "ABC Oracle"). Default none.'),
-  demo: z4.boolean().default(false).describe("Demo mode: overlay the active pulse's name bottom-right, to see which beat is playing. Default false."),
-  fps: z4.number().int().positive().max(120).default(30).describe("Output frames per second. Default 30."),
-  durationSeconds: z4.number().positive().optional().describe("Clip length in seconds. Defaults to the (mirrored) sum of the pulse durations; set to override."),
-  width: z4.number().int().positive().default(1920).describe("Output frame width in px. Default 1920."),
-  height: z4.number().int().positive().default(1080).describe("Output frame height in px. Default 1080."),
-  deviceScaleFactor: z4.number().positive().max(4).default(1).describe("Render scale (1 = 1:1; higher = crisper capture, downscaled into the video). Default 1."),
-  weight: z4.number().int().min(1).max(1e3).default(820).describe("Glyph weight on the variable-font axis, 1\u20131000. Default 820."),
-  lines: z4.number().int().min(1).max(40).default(3).describe("Number of glyph rows; glyph size is derived so rows fill the top 80% of the frame. Default 3."),
-  leading: z4.number().positive().default(0.78).describe("Line-height of the glyph block. Default 0.78 (tight, cap-height-hugging)."),
-  blacklist: z4.string().default("").describe('Glyphs to exclude from the showcase, e.g. "QXZ" (case-insensitive). Default none.'),
-  characterPool: z4.string().refine((s) => (/* @__PURE__ */ new Set([...s.trim()])).size >= 2, "characterPool needs \u22652 distinct characters").optional().describe("Override the glyph pool the specimen draws from (\u22652 distinct characters). Default A\u2013Z 0\u20139 + symbols."),
-  seed: z4.number().int().default(1).describe("Schedule seed \u2014 same seed \u21D2 identical animation. Change for a different deterministic take. Default 1."),
+var specimenSceneOptionsSchema = z4.object({
+  label: z4.string().default(""),
+  demo: z4.boolean().default(false),
+  weight: z4.number().min(1).max(1e3).default(820),
+  lines: z4.number().int().min(1).max(40).default(3),
+  blacklist: z4.string().default(""),
   colors: z4.object({
-    background: z4.string().default("#eceef1").describe("Backdrop behind the glyphs."),
-    foreground: z4.string().default("#16181d").describe("Primary glyph color \u2014 the resting majority."),
-    muted: z4.string().default("#a7adb6").describe("Muted/secondary glyph color."),
-    accent: z4.string().optional().describe("Accent color for occasional pops; defaults to `background` (accent glyphs blend in) if unset."),
-    // defaults to `background` at render (accent glyphs blend in)
-    label: z4.string().optional().describe("Color of the font-name label (bottom corner); defaults to `foreground` if unset.")
-    // defaults to `foreground` at render
-  }).default({}).describe("Color tokens the glyphs cycle through (any CSS colors). Override any subset. Default: light-grey palette."),
-  colorWeights: z4.object({
-    foreground: z4.number().nonnegative().default(2).describe("Relative likelihood of the foreground token on a random color change. Default 2."),
-    muted: z4.number().nonnegative().default(2).describe("Relative likelihood of the muted token on a random color change. Default 2."),
-    accent: z4.number().nonnegative().default(1).describe("Relative likelihood of the accent token on a random color change. Default 1.")
-  }).default({}).describe("Relative likelihood of each color token on a random (non-targeted) color change. Default 2 / 2 / 1."),
-  pulses: z4.array(pulseSchema).min(1).default(DEFAULT_PULSES).describe("The animation storyboard: an ordered sequence of pulses (beats). Default: a lively built-in storyboard."),
-  characterIntensity: z4.number().nonnegative().default(1).describe("Multiply every pulse's glyph-change fraction (1 = baseline, 2 = twice as busy, 0 = none). Default 1."),
-  colorIntensity: z4.number().nonnegative().default(1).describe("Multiply every pulse's color-change fraction (1 = baseline, 2 = twice as busy, 0 = none). Default 1."),
-  maxLineDrift: z4.number().positive().max(0.5).default(0.05).describe("Max fraction a line's total width may drift as its glyphs change; swaps are width-compensated. Default 0.05."),
-  mirror: z4.boolean().default(true).describe("Mirror the pulses (play out and back) for a seamless loop; doubles the clip length. Default true."),
-  crf: z4.number().int().min(0).max(51).default(18).describe("x264 quality, 0\u201351 (lower = better quality / larger file). Default 18."),
-  fileName: z4.string().optional().describe('Output filename; defaults to "<slug(asset name)>.mp4".')
-}).strict();
-var specimenOptionsSchema = z4.preprocess(applyTemplate, specimenObjectSchema);
-
-// src/generators/scene/scene-options.ts
-var specimenSceneOptionsSchema = z5.object({
-  label: z5.string().default(""),
-  demo: z5.boolean().default(false),
-  weight: z5.number().min(1).max(1e3).default(820),
-  lines: z5.number().int().min(1).max(40).default(3),
-  blacklist: z5.string().default(""),
-  colors: z5.object({
-    background: z5.string(),
-    foreground: z5.string(),
-    muted: z5.string(),
-    accent: z5.string().optional(),
-    label: z5.string().optional()
+    background: z4.string(),
+    foreground: z4.string(),
+    muted: z4.string(),
+    accent: z4.string().optional(),
+    label: z4.string().optional()
   }).partial().default({}),
-  colorWeights: z5.object({
-    foreground: z5.number().nonnegative(),
-    muted: z5.number().nonnegative(),
-    accent: z5.number().nonnegative()
+  colorWeights: z4.object({
+    foreground: z4.number().nonnegative(),
+    muted: z4.number().nonnegative(),
+    accent: z4.number().nonnegative()
   }).partial().default({}),
-  pulses: z5.array(pulseSchema).default([]),
-  mirror: z5.boolean().default(true),
-  characterIntensity: z5.number().nonnegative().default(1),
-  colorIntensity: z5.number().nonnegative().default(1),
+  pulses: z4.array(specimenWirePulseSchema).default([]),
+  mirror: z4.boolean().default(true),
+  characterIntensity: z4.number().nonnegative().default(1),
+  colorIntensity: z4.number().nonnegative().default(1),
   /** Max fraction a line's width may drift as glyphs change (right-edge stability). */
-  maxLineDrift: z5.number().positive().max(0.5).default(0.05),
+  maxLineDrift: z4.number().positive().max(0.5).default(0.05),
   /** Schedule seed — same seed ⇒ identical animation (parallel workers must agree). */
-  seed: z5.number().int().default(1),
+  seed: z4.number().int().default(1),
   /** Line-height of the glyph block. */
-  leading: z5.number().positive().default(0.78),
+  leading: z4.number().positive().default(0.78),
   /** Glyph pool override (≥2 distinct characters after the blacklist). */
-  characterPool: z5.string().min(2).optional()
+  characterPool: z4.string().min(2).optional()
 }).strict();
-var wallEasingEnum = z5.enum([
+var wallEasingEnum = z4.enum([
   "linear",
   "ease-in",
   "ease-out",
   "ease-in-out",
   "ease-in-out-strong"
 ]);
-var wallPulseSchema = z5.object({
+var wallPulseSchema = z4.object({
   /** When the pulse starts, as a fraction of the clip (0..1). */
-  at: z5.number().min(0).max(1).describe("When the pulse starts, as a fraction of the clip (0..1)."),
+  at: z4.number().min(0).max(1).describe("When the pulse starts, as a fraction of the clip (0..1)."),
   /** How long the move takes, as a fraction of the clip (0..1). */
-  duration: z5.number().positive().max(1).describe("How long the move takes, as a fraction of the clip (0..1)."),
+  span: z4.number().positive().max(1).describe("How long the move takes, as a fraction of the clip (0..1)."),
   /** How far it travels, in periods (1 = one full tile-set / one wrap). Usually 0..1. */
-  distance: z5.number().nonnegative().describe("How far it travels, in periods (1 = one full tile-set / wrap). Usually 0..1."),
+  distance: z4.number().nonnegative().describe("How far it travels, in periods (1 = one full tile-set / wrap). Usually 0..1."),
   /** Easing of the move's ramp. */
   easing: wallEasingEnum.default("ease-in-out").describe("Easing of the move's ramp. Default 'ease-in-out'.")
 }).strict();
-var wallPanSchema = z5.object({
+var wallPanSchema = z4.object({
   /** Pan direction. */
-  direction: z5.enum(["left", "right"]).default("left").describe("Pan direction. Default 'left'."),
+  direction: z4.enum(["left", "right"]).default("left").describe("Pan direction. Default 'left'."),
   /** Continuous whole-clip horizontal loops (0 = no pan unless `pulses` move it). */
-  loops: z5.number().nonnegative().default(0).describe("Continuous whole-clip horizontal loops (0 = no pan unless pulses move it). Default 0."),
+  loops: z4.number().nonnegative().default(0).describe("Continuous whole-clip horizontal loops (0 = no pan unless pulses move it). Default 0."),
   /** Pulses added on top of the base loops. */
-  pulses: z5.array(wallPulseSchema).default([]).describe("Pulses added on top of the base loops.")
+  pulses: z4.array(wallPulseSchema).default([]).describe("Pulses added on top of the base loops.")
 }).strict();
-var wallColumnSchema = z5.object({
+var wallColumnSchema = z4.object({
   /** Assets stacked in this column, by name (cycled to fill the height). At least one. */
-  tiles: z5.array(z5.string().min(1)).min(1).describe("Assets stacked in this column, by name (cycled to fill the height). At least one."),
+  tiles: z4.array(z4.string().min(1)).min(1).describe("Assets stacked in this column, by name (cycled to fill the height). At least one."),
   /** Constant start-position shift, 0..1 of a tile-set — de-aligns columns with similar content. */
-  stagger: z5.number().min(0).max(1).default(0).describe("Start-position shift (0..1 of a tile-set) that de-aligns columns with similar content. Default 0."),
+  stagger: z4.number().min(0).max(1).default(0).describe("Start-position shift (0..1 of a tile-set) that de-aligns columns with similar content. Default 0."),
   /** Scroll direction. Defaults to "down". */
-  direction: z5.enum(["up", "down"]).optional().describe("Scroll direction. Default 'down'."),
+  direction: z4.enum(["up", "down"]).optional().describe("Scroll direction. Default 'down'."),
   /** Continuous whole-clip loops for this column. Omit to inherit the wall-level `loops`. */
-  loops: z5.number().nonnegative().optional().describe("Continuous whole-clip loops for this column. Omit to inherit the wall-level loops."),
+  loops: z4.number().nonnegative().optional().describe("Continuous whole-clip loops for this column. Omit to inherit the wall-level loops."),
   /** This column's pulses. Omit to inherit the wall-level `pulses`. */
-  pulses: z5.array(wallPulseSchema).optional().describe("This column's pulses. Omit to inherit the wall-level pulses.")
+  pulses: z4.array(wallPulseSchema).optional().describe("This column's pulses. Omit to inherit the wall-level pulses.")
 }).strict();
-var fauxTileSchema = z5.object({
+var fauxTileSchema = z4.object({
   /** Box fill (any CSS color). Omit to auto-derive a distinct color from the tile name. */
-  color: z5.string().optional().describe("Box fill (any CSS color). Omit to auto-derive a distinct color from the tile name."),
+  color: z4.string().optional().describe("Box fill (any CSS color). Omit to auto-derive a distinct color from the tile name."),
   /** Optional caption shown under the name (e.g. "16:9") — purely cosmetic. */
-  size: z5.string().optional().describe("Optional caption shown under the name (e.g. 16:9) \u2014 purely cosmetic."),
+  size: z4.string().optional().describe("Optional caption shown under the name (e.g. 16:9) \u2014 purely cosmetic."),
   /** This faux tile's aspect ratio (width / height): 1.78 = 16:9 (short), 0.56 = 9:16 (tall), 1 =
    *  square. Omit to use the wall's `tileAspect` default. Real tiles use their media's own aspect. */
-  aspect: z5.number().positive().optional().describe("Faux tile aspect (w/h): 1.78 = 16:9, 0.56 = 9:16, 1 = square. Omit to use the wall's tileAspect.")
+  aspect: z4.number().positive().optional().describe("Faux tile aspect (w/h): 1.78 = 16:9, 0.56 = 9:16, 1 = square. Omit to use the wall's tileAspect.")
 }).strict();
-var wallSceneOptionsSchema = z5.object({
+var wallSceneOptionsSchema = z4.object({
   /** The columns (≥3) — each its own tiles + motion. Count = array length (fewer = bigger tiles). */
-  columns: z5.array(wallColumnSchema).min(3),
+  columns: z4.array(wallColumnSchema).min(3),
   /** Gap between columns and between their tile contents (px). */
-  gap: z5.number().nonnegative().default(16),
+  gap: z4.number().nonnegative().default(16),
   /** Default/fallback tile aspect (width / height). Tiles fit the column width and take their OWN
    *  height from their media's aspect (16:9 → short, 9:16 → tall); this is only used for faux
    *  (`test`) tiles that don't set their own `aspect`. 1.6 = 16:10 landscape, <1 = portrait. */
-  tileAspect: z5.number().positive().default(1.6),
+  tileAspect: z4.number().positive().default(1.6),
   /** Tile corner radius (px). */
-  cornerRadius: z5.number().nonnegative().default(12),
+  cornerRadius: z4.number().nonnegative().default(12),
   /** Backdrop shown in the gap gutters and behind tiles. Defaults to the scene's `background`. */
-  background: z5.string().optional(),
+  background: z4.string().optional(),
   /** System 1 — the X pan. */
   pan: wallPanSchema.default({}),
   /** Default continuous whole-clip loops for columns that omit their own `loops` (0 = static unless
    *  a pulse moves it; one pulse then rounds the total up to a single loop). */
-  loops: z5.number().nonnegative().default(0),
+  loops: z4.number().nonnegative().default(0),
   /** Default pulses for columns that omit their own `pulses` (the uniform wall-level motion). */
-  pulses: z5.array(wallPulseSchema).default([]),
+  pulses: z4.array(wallPulseSchema).default([]),
   /** Preview mode: render every tile as a flat labeled color box (see `testTiles`) instead of the
    *  real assets, so you can dial in layout + motion instantly — no producers run. */
-  test: z5.boolean().default(false),
+  test: z4.boolean().default(false),
   /** Per-tile faux appearance for `test` mode, keyed by tile name. Tiles not listed get an
    *  auto-derived color and their name as the label. */
-  testTiles: z5.record(z5.string(), fauxTileSchema).default({})
+  testTiles: z4.record(z4.string(), fauxTileSchema).default({})
 }).strict();
-var reelItemSchema = z5.object({
+var reelItemSchema = z4.object({
   /** Color display name (already cased per `uppercase`). */
-  name: z5.string(),
+  name: z4.string(),
   /** Swatch background hex (`#RRGGBB`). */
-  hex: z5.string(),
+  hex: z4.string(),
   /** Contrast-picked text color for this band. */
-  textColor: z5.string(),
+  textColor: z4.string(),
   /** Preformatted detail lines revealed on expand (hex / oklch / rgb …). */
-  details: z5.array(z5.string())
+  details: z4.array(z4.string())
 }).strict();
-var paletteReelSceneOptionsSchema = z5.object({
-  items: z5.array(reelItemSchema).min(1),
-  orientation: z5.enum(["rows", "columns"]).default("rows"),
-  holdSeconds: z5.number().positive().default(2),
-  transitionSeconds: z5.number().positive().default(0.7),
-  bounce: z5.boolean().default(true),
-  easing: z5.enum(["linear", "ease-in", "ease-out", "ease-in-out"]).default("ease-in-out"),
-  grownFlex: z5.number().min(1).default(12),
-  minCrossPx: z5.number().nonnegative().default(0),
-  nameAlwaysVisible: z5.boolean().default(true),
-  fontWeight: z5.number().int().min(1).max(1e3).default(700),
-  fontSize: z5.number().positive().optional(),
-  detailFontScale: z5.number().positive().default(0.62),
-  gap: z5.number().nonnegative().default(0),
-  cornerRadius: z5.number().nonnegative().default(0)
+var paletteReelSceneOptionsSchema = z4.object({
+  items: z4.array(reelItemSchema).min(1),
+  orientation: z4.enum(["rows", "columns"]).default("rows"),
+  holdSeconds: z4.number().positive().default(2),
+  transitionSeconds: z4.number().positive().default(0.7),
+  bounce: z4.boolean().default(true),
+  easing: z4.enum(["linear", "ease-in", "ease-out", "ease-in-out"]).default("ease-in-out"),
+  grownFlex: z4.number().min(1).default(12),
+  minCrossPx: z4.number().nonnegative().default(0),
+  nameAlwaysVisible: z4.boolean().default(true),
+  fontWeight: z4.number().int().min(1).max(1e3).default(700),
+  fontSize: z4.number().positive().optional(),
+  detailFontScale: z4.number().positive().default(0.62),
+  gap: z4.number().nonnegative().default(0),
+  cornerRadius: z4.number().nonnegative().default(0)
 }).strict();
 var SCENE_OPTION_SCHEMAS = {
   specimen: specimenSceneOptionsSchema,
@@ -3392,64 +3413,64 @@ var SCENE_OPTION_SCHEMAS = {
 };
 
 // src/generators/wall/options.ts
-var wallOptionsSchema = z6.object({
+var wallOptionsSchema = z5.object({
   // --- output ---
   /** Output width (CSS px). */
-  width: z6.number().int().positive().default(1920).describe("Output width in CSS px. Default 1920."),
+  width: z5.number().int().positive().default(1920).describe("Output width in CSS px. Default 1920."),
   /** Output height (CSS px). */
-  height: z6.number().int().positive().default(1080).describe("Output height in CSS px. Default 1080."),
+  height: z5.number().int().positive().default(1080).describe("Output height in CSS px. Default 1080."),
   /** Render scale (2 = retina-crisp, downscaled into the video). */
-  deviceScaleFactor: z6.number().positive().max(4).default(2).describe("Render scale (2 = retina-crisp, downscaled into the video). Default 2."),
+  deviceScaleFactor: z5.number().positive().max(4).default(2).describe("Render scale (2 = retina-crisp, downscaled into the video). Default 2."),
   /** Output frames per second. */
-  fps: z6.number().int().positive().max(120).default(30).describe("Output frames per second. Default 30."),
-  /** Clip length (seconds) — the whole loop. Tile videos should loop within a length dividing this. */
-  durationSeconds: z6.number().positive().default(16).describe("Clip length in seconds \u2014 the whole loop. Default 16."),
+  fps: z5.number().int().positive().max(120).default(30).describe("Output frames per second. Default 30."),
+  /** Clip length (ms) — the whole loop. Tile videos should loop within a length dividing this. */
+  durationMs: z5.number().positive().default(16e3).describe("Clip length in ms \u2014 the whole loop. Default 16000."),
   /** x264 quality, 0–51 (lower = better/larger). */
-  crf: z6.number().int().min(0).max(51).default(18).describe("x264 quality, 0\u201351 (lower = better quality / larger file). Default 18."),
+  crf: z5.number().int().min(0).max(51).default(18).describe("x264 quality, 0\u201351 (lower = better quality / larger file). Default 18."),
   /** Capture strategy. "frames" (default) is deterministic + parallelizable. */
-  capture: z6.enum(["frames", "realtime"]).default("frames").describe('Capture strategy. "frames" (default) is deterministic + parallelizable; "realtime" records the live session.'),
+  capture: z5.enum(["frames", "realtime"]).default("frames").describe('Capture strategy. "frames" (default) is deterministic + parallelizable; "realtime" records the live session.'),
   /** Parallel frame-render workers. Video-heavy walls can cold-start black under many workers —
    *  set 1 (or omit) for those. */
-  workers: z6.number().int().positive().optional().describe("Parallel frame-render workers. Video-heavy walls can cold-start to black under many workers \u2014 set 1 (or omit). Auto-picks from cores."),
+  workers: z5.number().int().positive().optional().describe("Parallel frame-render workers. Video-heavy walls can cold-start to black under many workers \u2014 set 1 (or omit). Auto-picks from cores."),
   /** Intermediate frame format (frames capture only). "jpeg" (default) is fast; "png" is lossless. */
-  frameFormat: z6.enum(["jpeg", "png"]).default("jpeg").describe('Intermediate frame format (frames capture). "jpeg" (default) is fast; "png" is lossless.'),
+  frameFormat: z5.enum(["jpeg", "png"]).default("jpeg").describe('Intermediate frame format (frames capture). "jpeg" (default) is fast; "png" is lossless.'),
   /** Backdrop shown in the gutters between tiles. */
-  background: z6.string().default("#0b0b0f").describe('Backdrop shown in the gutters between tiles. Default "#0b0b0f".'),
+  background: z5.string().default("#0b0b0f").describe('Backdrop shown in the gutters between tiles. Default "#0b0b0f".'),
   /** Output filename; defaults to "<slug(asset name)>.mp4". */
-  fileName: z6.string().optional().describe('Output filename; defaults to "<slug(asset name)>.mp4".'),
+  fileName: z5.string().optional().describe('Output filename; defaults to "<slug(asset name)>.mp4".'),
   // --- columns (System 2 + layout): each column = its tiles + its own motion ---
   /** The columns (≥3) — each its own tiles + motion. Count = array length (fewer = larger tiles). */
-  columns: z6.array(wallColumnSchema).min(3).describe("The columns (\u22653) \u2014 each lists its stacked `tiles` (by name) and may carry its own motion. Count = columns.length."),
+  columns: z5.array(wallColumnSchema).min(3).describe("The columns (\u22653) \u2014 each lists its stacked `tiles` (by name) and may carry its own motion. Count = columns.length."),
   /** Gap between columns and between tiles (px). */
-  gap: z6.number().nonnegative().default(8).describe("Gap between columns and between tiles (px). Default 8."),
+  gap: z5.number().nonnegative().default(8).describe("Gap between columns and between tiles (px). Default 8."),
   /** Default/fallback tile aspect (width / height). Tiles fit the column width and take their OWN
    *  height from their media's aspect (16:9 → short, 9:16 → tall); this is only used for faux
    *  (`test`) tiles that don't set their own `aspect`. 0.75 = 3:4 portrait. */
-  tileAspect: z6.number().positive().default(0.75).describe("Default/fallback tile aspect (w/h) \u2014 only for faux (test) tiles without their own `aspect`. 0.75 = 3:4 portrait. Default 0.75."),
+  tileAspect: z5.number().positive().default(0.75).describe("Default/fallback tile aspect (w/h) \u2014 only for faux (test) tiles without their own `aspect`. 0.75 = 3:4 portrait. Default 0.75."),
   /** Tile corner radius (px). */
-  cornerRadius: z6.number().nonnegative().default(6).describe("Tile corner radius (px). Default 6."),
+  cornerRadius: z5.number().nonnegative().default(6).describe("Tile corner radius (px). Default 6."),
   // --- motion (uniform pulse model) ---
   /** System 1 — the whole-wall X pan. */
   pan: wallPanSchema.default({}).describe("System 1 \u2014 the whole wall's horizontal pan (`direction` / `loops` / `pulses`). Default: no pan."),
   /** Default continuous whole-clip loops for columns that omit their own `loops` (0 = static unless
    *  a pulse moves it; one pulse then rounds the total up to a single loop). */
-  loops: z6.number().nonnegative().default(0).describe("Default continuous whole-clip loops for columns that omit their own `loops`. Default 0 (static unless a pulse moves it)."),
+  loops: z5.number().nonnegative().default(0).describe("Default continuous whole-clip loops for columns that omit their own `loops`. Default 0 (static unless a pulse moves it)."),
   /** Default pulses for columns that omit their own `pulses` (the uniform wall-level motion). */
-  pulses: z6.array(wallPulseSchema).default([]).describe("Default pulses for columns that omit their own `pulses` (the uniform wall-level motion). Default none."),
+  pulses: z5.array(wallPulseSchema).default([]).describe("Default pulses for columns that omit their own `pulses` (the uniform wall-level motion). Default none."),
   // --- test / preview ---
   /** Preview mode: render every tile as a flat labeled color box (see `testTiles`) instead of the
    *  real assets. No producer assets run, so the wall renders in seconds — use it to dial in
    *  layout + motion, then turn it off for the real render. */
-  test: z6.boolean().default(false).describe("Preview mode: render every tile as a flat labeled color box instead of real assets, so the wall renders in seconds. Default false."),
+  test: z5.boolean().default(false).describe("Preview mode: render every tile as a flat labeled color box instead of real assets, so the wall renders in seconds. Default false."),
   /** Per-tile faux appearance for `test` mode, keyed by tile name. Tiles not listed get an
    *  auto-derived color and their name as the label. */
-  testTiles: z6.record(z6.string(), fauxTileSchema).default({}).describe("Per-tile faux appearance for `test` mode, keyed by tile name (color + caption). Default {} (auto colors + names).")
+  testTiles: z5.record(z5.string(), fauxTileSchema).default({}).describe("Per-tile faux appearance for `test` mode, keyed by tile name (color + caption). Default {} (auto colors + names).")
 }).strict();
 
 // src/generators/scene/index.ts
 import path13 from "path";
 import { fileURLToPath } from "url";
-import { copyFile as copyFile2, rename, stat as stat4 } from "fs/promises";
+import { copyFile as copyFile2, rename as rename2, stat as stat4 } from "fs/promises";
 
 // src/scene/serve.ts
 import http from "http";
@@ -3774,7 +3795,7 @@ async function renderScene(ctx, options, generatorId = SCENE_ID) {
       });
     }
     try {
-      await rename(composedTmp, outPath);
+      await rename2(composedTmp, outPath);
     } catch {
       await copyFile2(composedTmp, outPath);
     }
@@ -3815,7 +3836,8 @@ async function run3(ctx, o) {
     background: o.background,
     deviceScaleFactor: o.deviceScaleFactor,
     fps: o.fps,
-    durationSeconds: o.durationSeconds,
+    // The scene wire format keeps seconds internally; the authoring surface is milliseconds.
+    durationSeconds: o.durationMs / 1e3,
     capture: o.capture,
     workers: o.workers,
     frameFormat: o.frameFormat,
@@ -3850,11 +3872,147 @@ var wallGenerator = {
   run: run3
 };
 
+// src/generators/specimen/options.ts
+import { z as z6 } from "zod";
+var pulseSchema = z6.object({
+  /** Human label for the beat, e.g. "color sweep" — purely to keep the config readable. */
+  name: z6.string().default("").describe('Human label for the beat, e.g. "color sweep" \u2014 purely to keep the config readable.'),
+  /** Length of this beat (ms). */
+  durationMs: z6.number().positive().describe("Length of this beat in ms."),
+  /** Fraction of cells whose glyph changes during this beat (0..1; 1 = every cell once). */
+  chars: z6.number().nonnegative().default(0).describe("Fraction of cells whose glyph changes during this beat (0..1; 1 = every cell once; 0 = a hold). Default 0."),
+  /** Fraction of cells whose color changes during this beat (0..1; 1 = every cell once). */
+  colors: z6.number().nonnegative().default(0).describe("Fraction of cells whose color changes during this beat (0..1; 1 = every cell once). Default 0."),
+  /**
+   * Target color for this beat's color changes. When set, every color change in the beat goes to
+   * this exact token (a deliberate sweep) instead of a weighted-random pick. Set `colors: 1` with
+   * `pacing: "even"` to wash the whole specimen to one color evenly. Omit for the default
+   * scattered, weighted-random recoloring.
+   */
+  color: z6.enum(["foreground", "muted", "accent"]).optional().describe("Target color token for this beat's color changes (a deliberate sweep); omit for the default weighted-random recoloring."),
+  /**
+   * How the changes are distributed in time across the beat — like a CSS easing curve:
+   * "linear"/"even" = uniform, "ease-in" = front-loaded, "ease-out" = back-loaded,
+   * "ease-in-out" = bunched at both ends, "random" = scattered.
+   */
+  pacing: z6.enum(["even", "linear", "ease-in", "ease-out", "ease-in-out", "random"]).default("even").describe("How changes are distributed in time across the beat (CSS-easing-like): even/linear, ease-in, ease-out, ease-in-out, random. Default even.")
+}).strict();
+var P = (name, durationMs, chars = 0, colors = 0) => ({
+  name,
+  durationMs,
+  chars,
+  colors,
+  pacing: "even"
+});
+var DEFAULT_PULSES = [
+  P("intro hold", 800),
+  P("first letters", 800, 0.15, 0),
+  P("settle", 1500),
+  P("ripple", 1e3, 0.08, 0.04),
+  P("color sweep", 1200, 0, 0.13),
+  P("rest", 1200),
+  P("quick burst", 600, 0.18, 0),
+  P("drift", 1200, 0, 0.08),
+  P("finale", 1200, 0.18, 0.13),
+  P("outro hold", 500)
+];
+var DEMO_PULSES = [
+  { name: "linear", durationMs: 5e3, chars: 0.5, pacing: "linear" },
+  { name: "hold", durationMs: 2e3 },
+  { name: "ease-in", durationMs: 5e3, chars: 0.5, pacing: "ease-in" },
+  { name: "hold", durationMs: 2e3 },
+  { name: "ease-out", durationMs: 5e3, chars: 0.5, pacing: "ease-out" },
+  { name: "hold", durationMs: 2e3 },
+  { name: "ease-in-out", durationMs: 5e3, chars: 0.5, pacing: "ease-in-out" },
+  { name: "hold", durationMs: 2e3 },
+  { name: "random", durationMs: 5e3, chars: 0.5, pacing: "random" },
+  { name: "hold", durationMs: 2e3 },
+  // Even, per-character color sweeps: each washes every glyph to one token, evenly across the beat.
+  { name: "sweep \u2192 muted", durationMs: 4e3, colors: 1, color: "muted", pacing: "even" },
+  { name: "sweep \u2192 accent", durationMs: 4e3, colors: 1, color: "accent", pacing: "even" },
+  { name: "sweep \u2192 foreground", durationMs: 4e3, colors: 1, color: "foreground", pacing: "even" },
+  { name: "hold", durationMs: 2e3 },
+  { name: "weighted recolor", durationMs: 5e3, colors: 0.6 },
+  { name: "hold", durationMs: 2e3 },
+  { name: "mingle", durationMs: 5e3, chars: 0.3, colors: 0.3 }
+];
+var SWEEP_COLORS = {
+  background: "#0b0b0f",
+  foreground: "#f4f4f5",
+  muted: "#6b7280",
+  accent: "#7c9cff"
+};
+var SWEEP_PULSES = [
+  { name: "hold", durationMs: 800 },
+  { name: "to muted", durationMs: 2200, colors: 1, color: "muted", pacing: "ease-in-out" },
+  { name: "settle", durationMs: 600 },
+  { name: "to accent", durationMs: 2200, colors: 1, color: "accent", pacing: "ease-in-out" },
+  { name: "settle", durationMs: 600 },
+  { name: "to foreground", durationMs: 2200, colors: 1, color: "foreground", pacing: "ease-in-out" },
+  { name: "glyph drift", durationMs: 1400, chars: 0.5, pacing: "even" },
+  { name: "hold", durationMs: 600 }
+];
+var SPECIMEN_TEMPLATES = {
+  demo: { demo: true, mirror: false, lines: 4, pulses: DEMO_PULSES },
+  sweep: {
+    mirror: true,
+    lines: 4,
+    colors: SWEEP_COLORS,
+    pulses: SWEEP_PULSES
+  }
+};
+function applyTemplate(raw) {
+  if (!raw || typeof raw !== "object") return raw;
+  const r = raw;
+  const tmpl = typeof r.template === "string" ? SPECIMEN_TEMPLATES[r.template] : void 0;
+  return tmpl ? { ...tmpl, ...r } : raw;
+}
+var specimenObjectSchema = z6.object({
+  font: z6.string().min(1).describe("Font file to showcase (path relative to the working dir, or absolute). Required."),
+  template: z6.enum(["demo", "sweep"]).optional().describe("Load a named option preset (demo or sweep); your explicit options still override what it sets."),
+  name: z6.string().default("").describe('Display name shown bottom-left (e.g. "ABC Oracle"). Default none.'),
+  demo: z6.boolean().default(false).describe("Demo mode: overlay the active pulse's name bottom-right, to see which beat is playing. Default false."),
+  fps: z6.number().int().positive().max(120).default(30).describe("Output frames per second. Default 30."),
+  durationMs: z6.number().positive().optional().describe("Clip length in ms. Defaults to the (mirrored) sum of the pulse durations; set to override."),
+  width: z6.number().int().positive().default(1920).describe("Output frame width in px. Default 1920."),
+  height: z6.number().int().positive().default(1080).describe("Output frame height in px. Default 1080."),
+  deviceScaleFactor: z6.number().positive().max(4).default(1).describe("Render scale (1 = 1:1; higher = crisper capture, downscaled into the video). Default 1."),
+  weight: z6.number().int().min(1).max(1e3).default(820).describe("Glyph weight on the variable-font axis, 1\u20131000. Default 820."),
+  lines: z6.number().int().min(1).max(40).default(3).describe("Number of glyph rows; glyph size is derived so rows fill the top 80% of the frame. Default 3."),
+  leading: z6.number().positive().default(0.78).describe("Line-height of the glyph block. Default 0.78 (tight, cap-height-hugging)."),
+  blacklist: z6.string().default("").describe('Glyphs to exclude from the showcase, e.g. "QXZ" (case-insensitive). Default none.'),
+  characterPool: z6.string().refine((s) => (/* @__PURE__ */ new Set([...s.trim()])).size >= 2, "characterPool needs \u22652 distinct characters").optional().describe("Override the glyph pool the specimen draws from (\u22652 distinct characters). Default A\u2013Z 0\u20139 + symbols."),
+  seed: z6.number().int().default(1).describe("Schedule seed \u2014 same seed \u21D2 identical animation. Change for a different deterministic take. Default 1."),
+  colors: z6.object({
+    background: z6.string().default("#eceef1").describe("Backdrop behind the glyphs."),
+    foreground: z6.string().default("#16181d").describe("Primary glyph color \u2014 the resting majority."),
+    muted: z6.string().default("#a7adb6").describe("Muted/secondary glyph color."),
+    accent: z6.string().optional().describe("Accent color for occasional pops; defaults to `background` (accent glyphs blend in) if unset."),
+    // defaults to `background` at render (accent glyphs blend in)
+    label: z6.string().optional().describe("Color of the font-name label (bottom corner); defaults to `foreground` if unset.")
+    // defaults to `foreground` at render
+  }).default({}).describe("Color tokens the glyphs cycle through (any CSS colors). Override any subset. Default: light-grey palette."),
+  colorWeights: z6.object({
+    foreground: z6.number().nonnegative().default(2).describe("Relative likelihood of the foreground token on a random color change. Default 2."),
+    muted: z6.number().nonnegative().default(2).describe("Relative likelihood of the muted token on a random color change. Default 2."),
+    accent: z6.number().nonnegative().default(1).describe("Relative likelihood of the accent token on a random color change. Default 1.")
+  }).default({}).describe("Relative likelihood of each color token on a random (non-targeted) color change. Default 2 / 2 / 1."),
+  pulses: z6.array(pulseSchema).min(1).default(DEFAULT_PULSES).describe("The animation storyboard: an ordered sequence of pulses (beats). Default: a lively built-in storyboard."),
+  characterIntensity: z6.number().nonnegative().default(1).describe("Multiply every pulse's glyph-change fraction (1 = baseline, 2 = twice as busy, 0 = none). Default 1."),
+  colorIntensity: z6.number().nonnegative().default(1).describe("Multiply every pulse's color-change fraction (1 = baseline, 2 = twice as busy, 0 = none). Default 1."),
+  maxLineDrift: z6.number().positive().max(0.5).default(0.05).describe("Max fraction a line's total width may drift as its glyphs change; swaps are width-compensated. Default 0.05."),
+  mirror: z6.boolean().default(true).describe("Mirror the pulses (play out and back) for a seamless loop; doubles the clip length. Default true."),
+  crf: z6.number().int().min(0).max(51).default(18).describe("x264 quality, 0\u201351 (lower = better quality / larger file). Default 18."),
+  fileName: z6.string().optional().describe('Output filename; defaults to "<slug(asset name)>.mp4".')
+}).strict();
+var specimenOptionsSchema = z6.preprocess(applyTemplate, specimenObjectSchema);
+
 // src/generators/specimen/index.ts
 var SPECIMEN_ID = "specimen";
 async function run4(ctx, o) {
-  const pulsesTotal = o.pulses.reduce((sum, p) => sum + p.duration, 0);
-  const durationSeconds = o.durationSeconds ?? (o.mirror ? pulsesTotal * 2 : pulsesTotal);
+  const pulsesTotalMs = o.pulses.reduce((sum, p) => sum + p.durationMs, 0);
+  const durationSeconds = (o.durationMs ?? (o.mirror ? pulsesTotalMs * 2 : pulsesTotalMs)) / 1e3;
+  const wirePulses = o.pulses.map(({ durationMs, ...p }) => ({ ...p, duration: durationMs / 1e3 }));
   const sceneOptions = {
     scene: "specimen",
     width: o.width,
@@ -3881,7 +4039,7 @@ async function run4(ctx, o) {
       characterPool: o.characterPool,
       colors: o.colors,
       colorWeights: o.colorWeights,
-      pulses: o.pulses,
+      pulses: wirePulses,
       mirror: o.mirror,
       characterIntensity: o.characterIntensity,
       colorIntensity: o.colorIntensity,
@@ -4217,13 +4375,13 @@ var paletteReelObjectSchema = z8.object({
   details: z8.array(fieldEnum2).default(["hex", "oklch", "rgb"]).describe(
     "Fields revealed when a color expands (the name is always shown, so it's ignored here). Default hex + oklch + rgb."
   ),
-  holdSeconds: z8.number().positive().default(2).describe("How long each color stays fully open before handing off to the next (s). Default 2."),
-  transitionSeconds: z8.number().positive().default(0.7).describe("Crossfade length from one open color to the next (s). Default 0.7."),
+  holdMs: z8.number().positive().default(2e3).describe("How long each color stays fully open before handing off to the next (ms). Default 2000."),
+  transitionMs: z8.number().positive().default(700).describe("Crossfade length from one open color to the next (ms). Default 700."),
   bounce: z8.boolean().default(true).describe(
     "Ping-pong the sweep so each handoff is between neighbouring bands; off wraps directly (last to first). Default true."
   ),
   easing: z8.enum(["linear", "ease-in", "ease-out", "ease-in-out"]).default("ease-in-out").describe('Easing applied to the crossfade ramp. Default "ease-in-out".'),
-  durationSeconds: z8.number().positive().optional().describe("Clip length override (s). Omit to derive (count x (hold + transition)) for a clean loop."),
+  durationMs: z8.number().positive().optional().describe("Clip length override (ms). Omit to derive (count x (hold + transition)) for a clean loop."),
   grownFlex: z8.number().min(1).default(12).describe(
     "How many times a sliver's share a fully-open band takes (a collapsed sliver is the baseline). Default 12."
   ),
@@ -4255,10 +4413,10 @@ var paletteReelOptionsSchema = paletteReelObjectSchema;
 
 // src/generators/palette-reel/index.ts
 var PALETTE_REEL_ID = "palette-reel";
-function deriveDuration(o) {
+function deriveDurationMs(o) {
   const n = o.colors.length;
   const stops = n <= 1 ? n : o.bounce ? 2 * (n - 1) : n;
-  return stops * (o.holdSeconds + o.transitionSeconds);
+  return stops * (o.holdMs + o.transitionMs);
 }
 async function run6(ctx, o) {
   const fmt = { uppercaseName: o.uppercase, rgbStyle: o.rgbStyle, oklchStyle: o.oklchStyle };
@@ -4276,7 +4434,7 @@ async function run6(ctx, o) {
       details: fields.map((f) => formatField(color, f, fmt))
     };
   });
-  const durationSeconds = o.durationSeconds ?? deriveDuration(o);
+  const durationSeconds = (o.durationMs ?? deriveDurationMs(o)) / 1e3;
   const sceneOptions = {
     scene: PALETTE_REEL_ID,
     width: o.width,
@@ -4296,8 +4454,8 @@ async function run6(ctx, o) {
     sceneOptions: {
       items,
       orientation: o.orientation,
-      holdSeconds: o.holdSeconds,
-      transitionSeconds: o.transitionSeconds,
+      holdSeconds: o.holdMs / 1e3,
+      transitionSeconds: o.transitionMs / 1e3,
       bounce: o.bounce,
       easing: o.easing,
       grownFlex: o.grownFlex,
@@ -4402,6 +4560,9 @@ function getGenerator(id) {
 function listGenerators() {
   return [...registry.values()];
 }
+function generatorIds() {
+  return [...registry.keys()];
+}
 register(scrollReelGenerator);
 register(screenshotsGenerator);
 register(wallGenerator);
@@ -4501,10 +4662,52 @@ var CONFIG_FILES = [
   ".pro-visurc",
   ".pro-visurc.json"
 ];
-var CONFIG_TEMPLATE = `import { defineConfig } from "pro-visu";
+var FRAMEWORKS = [
+  ["next", "Next.js", 3e3],
+  ["nuxt", "Nuxt", 3e3],
+  ["astro", "Astro", 4321],
+  ["@sveltejs/kit", "SvelteKit", 5173],
+  ["gatsby", "Gatsby", 8e3],
+  ["@remix-run/dev", "Remix", 3e3],
+  ["vite", "Vite", 5173]
+];
+function detectProject(cwd) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(readFileSync(path17.join(cwd, "package.json"), "utf8"));
+  } catch {
+  }
+  const pmField = typeof pkg.packageManager === "string" ? pkg.packageManager.split("@")[0] : "";
+  const pm = pmField === "pnpm" || pmField === "yarn" || pmField === "bun" || pmField === "npm" ? pmField : existsSync4(path17.join(cwd, "pnpm-lock.yaml")) ? "pnpm" : existsSync4(path17.join(cwd, "yarn.lock")) ? "yarn" : existsSync4(path17.join(cwd, "bun.lockb")) || existsSync4(path17.join(cwd, "bun.lock")) ? "bun" : "npm";
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies
+  };
+  const match = FRAMEWORKS.find(([dep]) => deps[dep]);
+  const devScript = pkg.scripts?.dev ?? "";
+  const flag = /(?:-p|--port)[ =](\d{2,5})/.exec(devScript);
+  const devPort = flag ? Number(flag[1]) : match?.[2];
+  let localDep = false;
+  try {
+    createRequire2(path17.join(cwd, "package.json")).resolve("pro-visu/package.json");
+    localDep = true;
+  } catch {
+    localDep = false;
+  }
+  return { pm, framework: match?.[1], devPort, localDep };
+}
+function runCmd(pm, script) {
+  return pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+}
+function tsConfigTemplate(info) {
+  const port = info.devPort ?? 3101;
+  const urlComment = info.devPort ? `// Your ${info.framework} dev server's URL \u2014 start it (\`${runCmd(info.pm, "dev")}\`) before generating,
+// point this at a deployed site, or enable the managed \`server\` block below instead.` : "// URL the capture assets point at \u2014 your running site, a deployed URL, or the managed server below.";
+  const start = info.pm === "npm" ? "npm start" : `${info.pm} start`;
+  return `import { defineConfig } from "pro-visu";
 
-// URL the capture assets point at. The optional managed server (below) binds this port.
-const URL = "http://localhost:3101";
+${urlComment}
+const URL = "http://localhost:${port}";
 
 export default defineConfig({
   settings: {
@@ -4514,10 +4717,11 @@ export default defineConfig({
     // installed Chrome, or args: ["--no-sandbox"] on CI.
     browser: { headless: true },
     // Optional: let the tool build + start your site, wait for it, capture, then stop it.
-    // 'port' defaults to 3101 (off the common 3000 dev port); your command must bind it.
+    // PORT is set in the command's env (default 3101), so PORT-honoring frameworks bind it
+    // automatically. If you enable this, point URL above at the same port.
     // server: {
-    //   build: "npm run build",
-    //   command: "npm start -- -p 3101", // e.g. Next: "npx next start -p 3101"
+    //   build: "${runCmd(info.pm, "build")}",
+    //   command: "${start}",
     //   port: 3101,
     // },
     defaults: {
@@ -4530,7 +4734,7 @@ export default defineConfig({
       name: "home-reel",
       url: URL,
       generator: "scroll-reel",
-      // options: { duration: 7000, waitForSelector: "main" },
+      // options: { durationMs: 7000, waitForSelector: "main" },
     },
     // A looping type-specimen from a font file (no URL needed):
     // {
@@ -4541,7 +4745,10 @@ export default defineConfig({
   ],
 });
 `;
-var JSON_CONFIG_TEMPLATE = `{
+}
+function jsonConfigTemplate(info) {
+  const port = info.devPort ?? 3101;
+  return `{
   "$schema": "./${DEFAULT_SCHEMA_FILE}",
   "settings": {
     "outDir": "pro-visu",
@@ -4552,26 +4759,36 @@ var JSON_CONFIG_TEMPLATE = `{
     }
   },
   "assets": [
-    { "name": "home-reel", "url": "http://localhost:3101", "generator": "scroll-reel" }
+    { "name": "home-reel", "url": "http://localhost:${port}", "generator": "scroll-reel" }
   ]
 }
 `;
+}
 async function runInit(options = {}) {
   const cwd = resolveCwd(options.cwd);
   const logger = createLogger("info");
   let createdSomething = false;
-  const configFile = options.json ? "pro-visu.config.json" : "pro-visu.config.ts";
+  const info = detectProject(cwd);
+  if (info.framework) {
+    logger.info(`detected ${info.framework} (${info.pm}${info.devPort ? `, dev port ${info.devPort}` : ""})`);
+  }
+  let useJson = Boolean(options.json);
+  if (!useJson && !info.localDep) {
+    useJson = true;
+    logger.info("pro-visu isn't a local dependency \u2014 scaffolding a JSON config (works via npx/global)");
+  }
+  const configFile = useJson ? "pro-visu.config.json" : "pro-visu.config.ts";
   const existingConfig = findExistingConfig(cwd);
   if (existingConfig) {
     logger.info(`config exists (${existingConfig}) \u2014 leaving it untouched`);
-  } else if (options.json) {
-    await writeFile6(path17.join(cwd, configFile), JSON_CONFIG_TEMPLATE, "utf8");
+  } else if (useJson) {
+    await writeFile6(path17.join(cwd, configFile), jsonConfigTemplate(info), "utf8");
     logger.success(`created ${configFile}`);
     await writeFile6(path17.join(cwd, DEFAULT_SCHEMA_FILE), serializeConfigJsonSchema(), "utf8");
     logger.success(`created ${DEFAULT_SCHEMA_FILE}`);
     createdSomething = true;
   } else {
-    await writeFile6(path17.join(cwd, configFile), CONFIG_TEMPLATE, "utf8");
+    await writeFile6(path17.join(cwd, configFile), tsConfigTemplate(info), "utf8");
     logger.success(`created ${configFile}`);
     createdSomething = true;
   }
@@ -4616,8 +4833,9 @@ async function runInit(options = {}) {
     }
   }
   logger.log("");
+  const startHint = info.devPort ? `start your dev server (\`${runCmd(info.pm, "dev")}\`)` : "start your site (or point the config at a deployed URL)";
   logger.info(
-    createdSomething ? `Next: edit ${configFile}, start your site (or use a deployed URL), then run \`pro-visu generate\`.` : `Already initialized. Edit ${configFile}, then run \`pro-visu generate\`.`
+    createdSomething ? `Next: edit ${configFile}, ${startHint}, then run \`pro-visu generate\`. (\`pro-visu doctor\` checks the setup.)` : `Already initialized. Edit ${configFile}, then run \`pro-visu generate\`.`
   );
 }
 function findExistingConfig(cwd) {
@@ -4916,7 +5134,7 @@ function killTreeByPid(pid) {
 // src/server/manage-server.ts
 import path20 from "path";
 import http2 from "http";
-import https from "https";
+import https2 from "https";
 import { spawn as spawn6 } from "child_process";
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 function resolveServerUrl(server) {
@@ -4924,7 +5142,7 @@ function resolveServerUrl(server) {
 }
 function probe(url) {
   return new Promise((resolve) => {
-    const lib = url.startsWith("https:") ? https : http2;
+    const lib = url.startsWith("https:") ? https2 : http2;
     const req = lib.get(url, (res) => {
       res.resume();
       resolve((res.statusCode ?? 0) > 0);
@@ -5085,7 +5303,7 @@ async function startManagedServer(server, baseCwd, logger, tasks = {}, signal) {
 }
 
 // src/pipeline/runner.ts
-import os2 from "os";
+import os3 from "os";
 import path23 from "path";
 import { existsSync as existsSync7 } from "fs";
 import { mkdtemp as mkdtemp4 } from "fs/promises";
@@ -5109,7 +5327,10 @@ async function createContext(args) {
   await ensureDir(genDir);
   return {
     browser: args.browser,
-    target: args.target,
+    // Fold the capture query params into the target URL so every generator's `requireUrl(ctx)`
+    // captures in capture mode without each one re-applying it.
+    target: { ...args.target, url: withCaptureQuery(args.target.url, args.capture) },
+    capture: args.capture,
     resolvedInputs: args.resolvedInputs,
     outDir: args.outDir,
     resolveOutPath: (filename) => path21.join(genDir, filename),
@@ -5196,7 +5417,7 @@ function computeCacheKey(parts) {
 // src/manifest/manifest.ts
 import path22 from "path";
 import { existsSync as existsSync6 } from "fs";
-import { readFile as readFile7, rename as rename2, rm as rm5, writeFile as writeFile8 } from "fs/promises";
+import { readFile as readFile7, rename as rename3, rm as rm5, writeFile as writeFile8 } from "fs/promises";
 
 // src/manifest/schema.ts
 import { z as z10 } from "zod";
@@ -5263,7 +5484,7 @@ async function writeManifest(outDir, manifest) {
   const maxAttempts = 5;
   for (let attempt = 1; ; attempt++) {
     try {
-      await rename2(tmp, file);
+      await rename3(tmp, file);
       return;
     } catch (err) {
       const code = err.code;
@@ -5309,6 +5530,57 @@ var ManifestStore = class _ManifestStore {
 };
 
 // src/pipeline/runner.ts
+import { ZodError } from "zod";
+
+// src/generators/migration.ts
+var RENAMED_KEYS = {
+  "scroll-reel": {
+    duration: 'renamed to "durationMs" (same unit \u2014 milliseconds)'
+  },
+  screenshots: {
+    breakpoints: 'renamed to "viewports" (same shape)'
+  },
+  wall: {
+    durationSeconds: 'renamed to "durationMs" and now in milliseconds (16 \u2192 16000)',
+    duration: 'pulse "duration" was renamed to "span" (same 0..1 clip fraction)'
+  },
+  specimen: {
+    durationSeconds: 'renamed to "durationMs" and now in milliseconds (10 \u2192 10000)',
+    duration: 'pulse "duration" was renamed to "durationMs" and is now in milliseconds (0.8 \u2192 800)'
+  },
+  "palette-reel": {
+    holdSeconds: 'renamed to "holdMs" and now in milliseconds (2 \u2192 2000)',
+    transitionSeconds: 'renamed to "transitionMs" and now in milliseconds (0.7 \u2192 700)',
+    durationSeconds: 'renamed to "durationMs" and now in milliseconds (10 \u2192 10000)'
+  }
+};
+function kebab(value) {
+  return value.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+function legacyOptionHint(generatorId, issue) {
+  if (issue.code === "unrecognized_keys") {
+    const renames = RENAMED_KEYS[generatorId];
+    if (!renames) return void 0;
+    const hints = issue.keys.filter((key) => renames[key]).map((key) => `"${key}" ${renames[key]}`);
+    return hints.length ? hints.join("; ") : void 0;
+  }
+  if (issue.code === "invalid_enum_value" && typeof issue.received === "string") {
+    const kebabbed = kebab(issue.received);
+    if (kebabbed !== issue.received && issue.options.includes(kebabbed)) {
+      return `easing names are kebab-case now \u2014 use "${kebabbed}"`;
+    }
+  }
+  return void 0;
+}
+
+// src/pipeline/runner.ts
+function describeOptionIssues(generatorId, err) {
+  return err.issues.map((issue) => {
+    const where = ["options", ...issue.path].join(".");
+    const hint = legacyOptionHint(generatorId, issue);
+    return `  \u2022 ${where}: ${issue.message}${hint ? ` \u2014 ${hint}` : ""}`;
+  }).join("\n");
+}
 function applyQuality(options, quality) {
   if (quality !== "draft") return options;
   const o = { ...options };
@@ -5324,7 +5596,7 @@ async function runPipeline(opts) {
   if (specs.length === 0) return [];
   await ensureDir(opts.outDir);
   const manifest = await ManifestStore.load(opts.outDir);
-  const tmpRoot = await mkdtemp4(path23.join(os2.tmpdir(), "pro-visu-"));
+  const tmpRoot = await mkdtemp4(path23.join(os3.tmpdir(), "pro-visu-"));
   const browser = await launchBrowser(opts.config.settings.browser);
   opts.onResources?.({ tmpDir: tmpRoot });
   const concurrency = Math.max(1, opts.concurrency ?? opts.config.settings.concurrency);
@@ -5376,7 +5648,9 @@ async function runPipeline(opts) {
         inputs: inputHashes,
         files: fileHashes,
         quality,
-        toolVersion: opts.toolVersion
+        toolVersion: opts.toolVersion,
+        // Capture-mode toggles change the rendered output, so a change must bust the cache.
+        capture: opts.config.settings.capture
       });
       if (cacheEnabled) {
         const existing = manifest.find(spec.name);
@@ -5405,6 +5679,7 @@ async function runPipeline(opts) {
         toolVersion: opts.toolVersion,
         quality,
         manifest,
+        capture: opts.config.settings.capture,
         onProgress: reporter ? (v) => reporter.progress(spec.name, v) : void 0,
         signal: opts.signal
       });
@@ -5417,7 +5692,8 @@ async function runPipeline(opts) {
       reporter?.status(spec.name, "ok");
       return { name: spec.name, generator: spec.generator, status: "ok", records: result.assets };
     } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
+      const err = error instanceof ZodError ? new Error(`Invalid ${spec.generator} options:
+${describeOptionIssues(spec.generator, error)}`) : error instanceof Error ? error : new Error(String(error));
       if (opts.signal?.aborted) {
         return { name: spec.name, generator: spec.generator, status: "failed", records: [], error: err, cancelled: true };
       }
@@ -5494,7 +5770,18 @@ function applyDerivedInputs(config) {
 }
 function mergeGeneratorOptions(defaults, spec) {
   const generatorDefaults = defaults[spec.generator] ?? {};
-  return { ...generatorDefaults, ...spec.options };
+  return deepMerge(generatorDefaults, spec.options);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, override) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const existing = out[key];
+    out[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+  }
+  return out;
 }
 
 // src/cli/dashboard/index.tsx
@@ -5975,7 +6262,7 @@ var InkReporter = class {
   }
 };
 function createReporter(opts) {
-  const forced = process.env.SHOWCASE_LIVE;
+  const forced = process.env.PRO_VISU_LIVE ?? process.env.SHOWCASE_LIVE;
   if (forced === "0") return new NoopReporter();
   if (forced === "1") return new InkReporter();
   return opts.tty && !opts.verbose ? new InkReporter() : new NoopReporter();
@@ -6064,6 +6351,13 @@ function renderSummary(outcomes, outDir, columns = 80) {
 }
 
 // src/cli/ui.ts
+function zodIssueLines(zodError, pathPrefix = "") {
+  return zodError.issues.map((issue) => {
+    const joined = issue.path.join(".");
+    const where = [pathPrefix, joined].filter(Boolean).join(".") || "(root)";
+    return `  \u2022 ${where}: ${issue.message}`;
+  });
+}
 function reportConfigError(logger, err) {
   if (err instanceof ConfigNotFoundError) {
     logger.error(err.message);
@@ -6071,10 +6365,7 @@ function reportConfigError(logger, err) {
   }
   if (err instanceof ConfigValidationError) {
     logger.error(`Invalid config${err.file ? ` (${err.file})` : ""}:`);
-    for (const issue of err.zodError.issues) {
-      const where = issue.path.length ? issue.path.join(".") : "(root)";
-      logger.error(`  \u2022 ${where}: ${issue.message}`);
-    }
+    for (const line of zodIssueLines(err.zodError)) logger.error(line);
     return;
   }
   logger.error(err instanceof Error ? err.message : String(err));
@@ -6088,6 +6379,47 @@ function printSummary(logger, outcomes, outDir) {
   logger.log(renderSummary(outcomes, outDir, process.stdout.columns ?? 80));
 }
 
+// src/utils/suggest.ts
+function editDistance(a, b) {
+  const cols = b.length + 1;
+  const dist = Array.from({ length: cols }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = dist[0] ?? 0;
+    dist[0] = i;
+    for (let j = 1; j < cols; j++) {
+      const tmp = dist[j] ?? 0;
+      dist[j] = Math.min(
+        (dist[j] ?? 0) + 1,
+        // deletion
+        (dist[j - 1] ?? 0) + 1,
+        // insertion
+        prev + (a[i - 1] === b[j - 1] ? 0 : 1)
+        // substitution
+      );
+      prev = tmp;
+    }
+  }
+  return dist[cols - 1] ?? 0;
+}
+function closestMatch(input, candidates) {
+  const needle = input.toLowerCase();
+  let best;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const d = editDistance(needle, candidate.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  const threshold = Math.max(2, Math.floor(input.length / 3));
+  return bestDist <= threshold ? best : void 0;
+}
+function didYouMean(input, candidates) {
+  const match = closestMatch(input, candidates);
+  return match ? ` (did you mean "${match}"?)` : "";
+}
+
 // src/cli/commands/generate.ts
 async function runGenerate(options = {}) {
   const cwd = resolveCwd(options.cwd);
@@ -6105,35 +6437,76 @@ async function runGenerate(options = {}) {
   if (config.settings.maxMemoryMB) {
     bootstrapLog.info(`Node heap limit: ${currentHeapLimitMB()} MB (settings.maxMemoryMB=${config.settings.maxMemoryMB})`);
   }
-  const level = options.verbose ? "debug" : config.settings.logLevel;
-  const reporter = createReporter({ tty: Boolean(process.stdout.isTTY), verbose: !!options.verbose });
-  const logger = reporter.isLive ? createReportingLogger(level, reporter) : createLogger(level);
   const outDir = resolveOutDir(cwd, config.settings.outDir);
+  let concurrencyOverride;
+  if (options.concurrency != null) {
+    const raw = options.concurrency;
+    const n = typeof raw === "boolean" ? Number.NaN : Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+      bootstrapLog.error(`Invalid --concurrency "${options.concurrency}" \u2014 expected a positive integer.`);
+      process.exitCode = 1;
+      return;
+    }
+    concurrencyOverride = n;
+  }
   const requested = normalizeAssetNames(options.asset);
   if (requested) {
     const known = new Set(config.assets.map((a) => a.name));
     const unknown = requested.filter((name) => !known.has(name));
-    if (unknown.length) logger.warn(`Unknown asset(s): ${unknown.join(", ")}`);
+    for (const name of unknown) bootstrapLog.warn(`Unknown asset "${name}"${didYouMean(name, known)}`);
     if (requested.every((name) => !known.has(name))) {
-      logger.error("No matching assets to generate.");
+      bootstrapLog.error("No matching assets to generate.");
       process.exitCode = 1;
       return;
     }
   }
+  applyDerivedInputs(config);
+  const selected = expandSelection(config.assets, requested);
+  const quality = options.draft ? "draft" : config.settings.quality;
+  if (!validatePlan(bootstrapLog, config, selected, quality)) {
+    process.exitCode = 1;
+    return;
+  }
+  const anyNeedsServer = selected.some((s) => Boolean(getGenerator(s.generator)?.requiresUrl));
+  if (config.settings.server && !options.skipServer && !anyNeedsServer) {
+    bootstrapLog.info("No selected asset needs a URL \u2014 skipping the managed server.");
+  }
+  const baseServerCfg = options.skipServer || !anyNeedsServer ? void 0 : config.settings.server;
+  const serverCfg = baseServerCfg && options.skipBuild ? { ...baseServerCfg, build: void 0 } : baseServerCfg;
+  const serverBase = serverCfg ? resolveServerUrl(serverCfg) : void 0;
+  const resolvedConfig = {
+    ...config,
+    assets: resolveTargets(
+      config.assets,
+      serverBase,
+      (id) => Boolean(getGenerator(id)?.requiresUrl)
+    )
+  };
+  if (options.dryRun) {
+    printPlan(bootstrapLog, resolvedConfig, selected, serverCfg, quality, concurrencyOverride);
+    return;
+  }
+  if (!serverCfg && !await preflightUrls(bootstrapLog, resolvedConfig, selected)) {
+    process.exitCode = 1;
+    return;
+  }
   const usingManaged = !config.settings.browser.channel && !config.settings.browser.executablePath;
   if (!options.skipBrowser && usingManaged) {
-    const ready = await ensureChromium({ logger });
+    const ready = await ensureChromium({ logger: bootstrapLog });
     if (!ready) {
-      logger.error("Chromium is required. Run `pro-visu init` or install it manually.");
+      bootstrapLog.error("Chromium is required. Run `pro-visu init` or install it manually.");
       process.exitCode = 1;
       return;
     }
   }
-  if (!await ensureFfmpeg({ logger })) {
-    logger.error("A working ffmpeg is required for video generators.");
+  if (!await ensureFfmpeg({ logger: bootstrapLog })) {
+    bootstrapLog.error("A working ffmpeg is required for video generators.");
     process.exitCode = 1;
     return;
   }
+  const level = options.verbose ? "debug" : config.settings.logLevel;
+  const reporter = createReporter({ tty: Boolean(process.stdout.isTTY), verbose: !!options.verbose });
+  const logger = reporter.isLive ? createReportingLogger(level, reporter) : createLogger(level);
   await ensureDir(outDir);
   await startRunState(outDir);
   const abort = new AbortController();
@@ -6174,23 +6547,6 @@ async function runGenerate(options = {}) {
     }
   }, 1500);
   memTimer.unref?.();
-  applyDerivedInputs(config);
-  const selected = expandSelection(config.assets, requested);
-  const anyNeedsServer = selected.some((s) => Boolean(getGenerator(s.generator)?.requiresUrl));
-  if (config.settings.server && !options.skipServer && !anyNeedsServer) {
-    logger.info("No selected asset needs a URL \u2014 skipping the managed server.");
-  }
-  const baseServerCfg = options.skipServer || !anyNeedsServer ? void 0 : config.settings.server;
-  const serverCfg = baseServerCfg && options.skipBuild ? { ...baseServerCfg, build: void 0 } : baseServerCfg;
-  const serverBase = serverCfg ? resolveServerUrl(serverCfg) : void 0;
-  const resolvedConfig = {
-    ...config,
-    assets: resolveTargets(
-      config.assets,
-      serverBase,
-      (id) => Boolean(getGenerator(id)?.requiresUrl)
-    )
-  };
   const gates = [];
   const tasks = {};
   if (reporter.isLive && serverCfg) {
@@ -6222,16 +6578,14 @@ async function runGenerate(options = {}) {
       server = await startManagedServer(serverCfg, cwd, logger, tasks, abort.signal);
       await updateRunState(outDir, { serverPid: server?.pid });
     }
-    const concurrency = options.concurrency != null ? Number(options.concurrency) : void 0;
-    const count = requested ? requested.length : config.assets.length;
-    if (!reporter.isLive) logger.start(`Generating ${count} asset(s)\u2026`);
+    if (!reporter.isLive) logger.start(`Generating ${selected.length} asset(s)\u2026`);
     outcomes = await runPipeline({
       config: resolvedConfig,
       outDir,
       logger,
       toolVersion: TOOL_VERSION,
       assetNames: requested,
-      concurrency: Number.isFinite(concurrency) ? concurrency : void 0,
+      concurrency: concurrencyOverride,
       quality: options.draft ? "draft" : void 0,
       cache: options.cache,
       reporter,
@@ -6270,6 +6624,107 @@ async function runGenerate(options = {}) {
     process.exitCode = 1;
   }
 }
+function validatePlan(log, config, selected, quality) {
+  let ok = true;
+  const ids = generatorIds();
+  const known = new Set(ids);
+  for (const key of Object.keys(config.settings.defaults)) {
+    if (!known.has(key)) {
+      log.warn(`settings.defaults["${key}"] matches no generator${didYouMean(key, ids)} \u2014 it will never apply.`);
+    }
+  }
+  for (const spec of selected) {
+    const generator = getGenerator(spec.generator);
+    if (!generator) {
+      log.error(
+        `Asset "${spec.name}": unknown generator "${spec.generator}"${didYouMean(spec.generator, ids)}. Available: ${ids.join(", ")}.`
+      );
+      ok = false;
+      continue;
+    }
+    const merged = applyQuality(mergeGeneratorOptions(config.settings.defaults, spec), quality);
+    const parsed2 = generator.optionsSchema.safeParse(merged);
+    if (!parsed2.success) {
+      log.error(`Asset "${spec.name}" has invalid ${spec.generator} options:`);
+      for (const issue of parsed2.error.issues) {
+        const where = ["options", ...issue.path].join(".");
+        const hint = legacyOptionHint(spec.generator, issue);
+        log.error(`  \u2022 ${where}: ${issue.message}${hint ? ` \u2014 ${hint}` : ""}`);
+      }
+      ok = false;
+    }
+  }
+  return ok;
+}
+function printPlan(log, resolvedConfig, selected, serverCfg, quality, concurrencyOverride) {
+  const byName = new Map(resolvedConfig.assets.map((a) => [a.name, a]));
+  const concurrency = concurrencyOverride ?? resolvedConfig.settings.concurrency;
+  log.info(`Plan: ${selected.length} asset(s), quality "${quality}", concurrency ${concurrency}`);
+  for (const s of selected) {
+    const resolved = byName.get(s.name) ?? s;
+    log.log(`  \u2022 ${s.name}  [${s.generator}]${resolved.url ? `  ${resolved.url}` : ""}`);
+  }
+  if (serverCfg) log.info(`Managed server: ${serverCfg.command}`);
+  log.info("Dry run \u2014 nothing generated.");
+}
+async function preflightUrls(log, resolvedConfig, selected) {
+  const byName = new Map(resolvedConfig.assets.map((a) => [a.name, a]));
+  const missing = [];
+  const relative = [];
+  const urls = /* @__PURE__ */ new Set();
+  for (const s of selected) {
+    if (!getGenerator(s.generator)?.requiresUrl) continue;
+    const url = byName.get(s.name)?.url;
+    if (!url) missing.push(s.name);
+    else if (url.startsWith("/")) relative.push(`"${s.name}" (${url})`);
+    else urls.add(url);
+  }
+  let ok = true;
+  if (missing.length) {
+    log.error(
+      `Asset(s) missing a url: ${missing.join(", ")} \u2014 set "url", or configure settings.server so they capture the managed server's root.`
+    );
+    ok = false;
+  }
+  if (relative.length) {
+    log.error(
+      `Relative url(s) require the managed server: ${relative.join(", ")} \u2014 configure settings.server, or use absolute URLs.`
+    );
+    ok = false;
+  }
+  const origins = /* @__PURE__ */ new Map();
+  for (const url of urls) {
+    try {
+      const origin = new URL(url).origin;
+      if (!origins.has(origin)) origins.set(origin, url);
+    } catch {
+    }
+  }
+  const probes = await Promise.all(
+    [...origins.values()].map(async (url) => await urlResponds(url) ? null : url)
+  );
+  const unreachable = probes.filter((url) => url !== null);
+  if (unreachable.length) {
+    for (const url of unreachable) log.error(`Nothing is responding at ${url}.`);
+    log.error(
+      "Start your site (or point the asset urls at a deployed one), or configure settings.server so pro-visu builds and starts it for you."
+    );
+    ok = false;
+  }
+  return ok;
+}
+async function urlResponds(url) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 1e4);
+  try {
+    await fetch(url, { signal: ctrl.signal, redirect: "manual" });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function taskHandle(reporter, id) {
   return {
     start: () => reporter.status(id, "running"),
@@ -6284,6 +6739,83 @@ function normalizeAssetNames(value) {
   return arr.length ? arr : void 0;
 }
 
+// src/cli/commands/doctor.ts
+import { existsSync as existsSync8 } from "fs";
+async function runDoctor(options = {}) {
+  const cwd = resolveCwd(options.cwd);
+  const log = createLogger("info");
+  let failed = false;
+  const fail = (message) => {
+    failed = true;
+    log.error(message);
+  };
+  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+  if (major > 18 || major === 18 && minor >= 18) {
+    log.success(`Node ${process.versions.node}`);
+  } else {
+    fail(`Node ${process.versions.node} \u2014 pro-visu requires >= 18.18.`);
+  }
+  let config;
+  try {
+    const loaded = await loadShowcaseConfig({ cwd, configFile: options.config });
+    config = loaded.config;
+    const where = loaded.configFile ?? 'package.json "pro-visu" key';
+    log.success(`Config OK (${where}) \u2014 ${config.assets.length} asset(s).`);
+  } catch (err) {
+    failed = true;
+    reportConfigError(log, err);
+  }
+  if (config) {
+    if (validatePlan(log, config, config.assets, config.settings.quality)) {
+      log.success("Asset options OK.");
+    } else {
+      failed = true;
+    }
+    try {
+      applyDerivedInputs(config);
+      buildGraph(config.assets);
+    } catch (err) {
+      fail(err.message);
+    }
+  }
+  const browser = config?.settings.browser;
+  if (browser?.executablePath) {
+    if (existsSync8(browser.executablePath)) log.success(`Browser executable: ${browser.executablePath}`);
+    else fail(`browser.executablePath not found: ${browser.executablePath}`);
+  } else if (browser?.channel) {
+    log.info(`Browser channel "${browser.channel}" \u2014 verified at launch.`);
+  } else if (await ensureChromium({ logger: log, checkOnly: true })) {
+    log.success("Chromium installed.");
+  } else {
+    fail("Chromium missing \u2014 run `pro-visu init` (or it installs on first `pro-visu generate`).");
+  }
+  if (await ensureFfmpeg({ logger: log, checkOnly: true })) {
+    log.success(`ffmpeg OK${process.env.FFMPEG_BIN ? " (FFMPEG_BIN)" : ""}.`);
+  } else if (ffmpegIsSupported()) {
+    log.warn("ffmpeg not fetched yet \u2014 it downloads automatically on first `pro-visu generate`.");
+  } else {
+    fail(
+      `No prebuilt ffmpeg for ${process.platform}/${process.arch} \u2014 set FFMPEG_BIN to a local ffmpeg binary.`
+    );
+  }
+  if (config) {
+    if (config.settings.server) {
+      log.info(`Managed server configured: \`${config.settings.server.command}\` (started per run).`);
+    } else if (await preflightUrls(log, config, config.assets)) {
+      log.success("Asset URLs respond.");
+    } else {
+      failed = true;
+    }
+  }
+  log.log("");
+  if (failed) {
+    log.error("Some checks failed \u2014 see above.");
+    process.exitCode = 1;
+  } else {
+    log.success("All checks passed. Run `pro-visu generate` when ready.");
+  }
+}
+
 // src/cli/commands/list.ts
 import pc from "picocolors";
 async function runList(options = {}) {
@@ -6303,6 +6835,11 @@ async function runList(options = {}) {
     }
   }
   const manifest = await readManifest(outDir);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ outDir, assets: manifest.assets }, null, 2)}
+`);
+    return;
+  }
   if (manifest.assets.length === 0) {
     logger.info("Nothing generated yet. Run `pro-visu generate`.");
     return;
@@ -6323,7 +6860,7 @@ import path25 from "path";
 async function runReset(options = {}) {
   const cwd = resolveCwd(options.cwd);
   const log = createLogger("info");
-  let outDir = path25.join(cwd, "pro-visu");
+  let outDir = path25.join(cwd, DEFAULT_OUTDIR);
   try {
     const { config } = await loadShowcaseConfig({ cwd, configFile: options.config });
     outDir = resolveOutDir(cwd, config.settings.outDir);
@@ -6358,9 +6895,10 @@ async function runReset(options = {}) {
 
 // src/cli/index.ts
 var cli = cac("pro-visu");
-cli.command("init", "Scaffold config, gitignore the output dir, and ensure a browser").option("--cwd <dir>", "Working directory").option("--no-script", "Do not add a package.json script").option("--skip-browser", "Do not install Chromium").option("--json", "Scaffold a dependency-free JSON config + JSON Schema (for npx / global use)").action(runInit);
-cli.command("generate", "Generate showcase assets defined in your config").alias("gen").option("--config <path>", "Path to a config file").option("--cwd <dir>", "Working directory").option("--asset <name>", "Only generate these assets (repeatable)").option("--concurrency <n>", "Override parallelism").option("--skip-browser", "Skip the Chromium check/install").option("--skip-server", "Skip the managed server (use an already-running site)").option("--skip-build", "Skip the server build step (fast iteration when the site is unchanged)").option("--draft", "Draft quality: faster, lower-fidelity renders for iteration").option("--cache", "Skip assets whose inputs+options are unchanged").option("--verbose", "Verbose (debug) logging").action(runGenerate);
-cli.command("list", "List assets recorded in the manifest").alias("ls").option("--config <path>", "Path to a config file").option("--cwd <dir>", "Working directory").action(runList);
+cli.command("init", "Scaffold config, gitignore the output dir, and ensure a browser").option("--cwd <dir>", "Working directory").option("--no-script", 'Skip adding the "pro-visu" script to package.json').option("--skip-browser", "Do not install Chromium").option("--json", "Scaffold a dependency-free JSON config + JSON Schema (for npx / global use)").action(runInit);
+cli.command("generate", "Generate showcase assets defined in your config").alias("gen").option("--config <path>", "Path to a config file").option("--cwd <dir>", "Working directory").option("--asset <name>", "Only generate these assets (repeatable)").option("--concurrency <n>", "Override parallelism").option("--skip-browser", "Skip the Chromium check/install").option("--skip-server", "Skip the managed server (use an already-running site)").option("--skip-build", "Skip the server build step (fast iteration when the site is unchanged)").option("--draft", "Draft quality: faster, lower-fidelity renders for iteration").option("--cache", "Skip assets whose inputs+options are unchanged").option("--dry-run", "Validate the config and print the plan without generating").option("--verbose", "Verbose (debug) logging (plain logs instead of the live dashboard)").action(runGenerate);
+cli.command("doctor", "Check the environment + config (Node, config, Chromium, ffmpeg, URLs)").option("--config <path>", "Path to a config file").option("--cwd <dir>", "Working directory").action(runDoctor);
+cli.command("list", "List assets recorded in the manifest").alias("ls").option("--config <path>", "Path to a config file").option("--cwd <dir>", "Working directory").option("--json", "Print the manifest as JSON (for scripts/CI)").action(runList);
 cli.command("schema", "Write a JSON Schema for pro-visu.config.json (editor autocomplete)").option("--cwd <dir>", "Working directory").option("--out <path>", "Output path (default pro-visu.schema.json)").action(runSchema);
 cli.command("reset", "Clean up orphaned processes/temp from an interrupted run").option("--config <path>", "Path to a config file").option("--cwd <dir>", "Working directory").option("--force", "Clean up even if a run still looks active").action(runReset);
 cli.help();
@@ -6369,6 +6907,11 @@ var parsed = cli.parse(process.argv, { run: false });
 async function main() {
   checkForUpdates();
   if (!cli.matchedCommand) {
+    if (parsed.args.length > 0) {
+      console.error(`Unknown command "${parsed.args[0]}". Run \`pro-visu --help\` for the command list.`);
+      process.exitCode = 1;
+      return;
+    }
     if (!parsed.options.help && !parsed.options.version) cli.outputHelp();
     return;
   }
@@ -6376,6 +6919,12 @@ async function main() {
 }
 main().catch((err) => {
   process.exitCode = 1;
-  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  if (!process.argv.includes("--verbose") && err instanceof Error && err.stack) {
+    console.error("Re-run with --verbose for a stack trace.");
+  } else if (err instanceof Error && err.stack) {
+    console.error(err.stack);
+  }
 });
 //# sourceMappingURL=index.js.map