@tandryukha/aidemo 0.14.1 → 0.15.0

package/src/qa.ts

@@ -0,0 +1,295 @@
+/**
+ * `aidemo qa <dir>` — post-render checks on the FINISHED MP4 (issue #52).
+ *
+ * `lint` predicts problems before the take and `output/report.json` records
+ * what compose did, but neither sees the file a viewer opens: a white opening
+ * frame, a blank poster, a master that is too quiet, captions that flash by,
+ * an address pill naming the wrong host. Those were caught locally with a
+ * ~150-line ffmpeg + python script; this is that script, in the engine, so
+ * every agent-driven render is self-checking.
+ *
+ * Pure measurement over existing artifacts: ffmpeg/ffprobe only, no browser,
+ * no network, nothing written.
+ */
+
+import { spawn } from "node:child_process";
+import { relative } from "node:path";
+import type { Project } from "./project.js";
+import {
+  probeDurationMs,
+  probeFlatLeadMs,
+} from "./ffmpeg.js";
+import { ComposeReportSchema, type Storyboard } from "./types.js";
+import { exists, log, ok, readJson } from "./util.js";
+
+export type QaStatus = "pass" | "warn" | "note";
+
+export interface QaCheck {
+  /** Stable id: length | blank-open | poster | loudness | bed | hold | captions | hygiene. */
+  id: string;
+  status: QaStatus;
+  message: string;
+}
+
+export interface QaResult {
+  video: string;
+  durationMs: number;
+  checks: QaCheck[];
+  warnings: number;
+  notes: number;
+}
+
+/** Integrated loudness / true peak / the momentary p10 (the bed under speech). */
+interface LoudnessStats {
+  integrated: number;
+  truePeak: number;
+  /** 10th percentile of the momentary loudness — what plays in the gaps. */
+  momentaryP10: number;
+}
+
+function ebur128(file: string): Promise<LoudnessStats | null> {
+  return new Promise((resolvePromise) => {
+    const proc = spawn(
+      "ffmpeg",
+      ["-hide_banner", "-nostats", "-i", file, "-af", "ebur128=peak=true", "-f", "null", "-"],
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    let err = "";
+    proc.stderr.on("data", (d) => (err += d.toString()));
+    proc.on("error", () => resolvePromise(null));
+    proc.on("close", () => {
+      const moments: number[] = [];
+      for (const m of err.matchAll(/M:\s*(-?[\d.]+|-inf)/g)) {
+        const v = m[1] === "-inf" ? -70 : parseFloat(m[1]);
+        if (Number.isFinite(v) && v > -70) moments.push(v);
+      }
+      const summary = err.slice(err.lastIndexOf("Integrated loudness"));
+      const I = /I:\s*(-?[\d.]+)\s*LUFS/.exec(summary);
+      const TP = /Peak:\s*(-?[\d.]+)\s*dBFS/.exec(summary);
+      if (!I) return resolvePromise(null);
+      moments.sort((a, b) => a - b);
+      resolvePromise({
+        integrated: parseFloat(I[1]),
+        truePeak: TP ? parseFloat(TP[1]) : 0,
+        momentaryP10: moments.length ? moments[Math.floor(moments.length * 0.1)] : -70,
+      });
+    });
+  });
+}
+
+/** Mean luma of a still image (a blank poster is ~white or ~black). */
+function imageYavg(file: string): Promise<number | null> {
+  return new Promise((resolvePromise) => {
+    const proc = spawn(
+      "ffmpeg",
+      [
+        "-hide_banner",
+        "-nostats",
+        "-i",
+        file,
+        "-vf",
+        "signalstats,metadata=print:file=-",
+        "-f",
+        "null",
+        "-",
+      ],
+      { stdio: ["ignore", "pipe", "ignore"] }
+    );
+    let out = "";
+    proc.stdout.on("data", (d) => (out += d.toString()));
+    proc.on("error", () => resolvePromise(null));
+    proc.on("close", () => {
+      const m = /YAVG=\s*([\d.]+)/.exec(out);
+      resolvePromise(m ? parseFloat(m[1]) : null);
+    });
+  });
+}
+
+/** Host of a URL-ish string, or null. */
+function hostOf(url: string): string | null {
+  try {
+    return new URL(url.includes("://") ? url : `https://${url}`).host;
+  } catch {
+    return null;
+  }
+}
+
+export async function runQa(project: Project, storyboard: Storyboard): Promise<QaResult> {
+  const video = project.outputPath;
+  if (!(await exists(video))) {
+    throw new Error(`no video at ${video} — run 'aidemo render <dir>' (or compose) first`);
+  }
+  const checks: QaCheck[] = [];
+  const add = (id: string, status: QaStatus, message: string): void => {
+    checks.push({ id, status, message });
+  };
+  const durationMs = await probeDurationMs(video);
+
+  // 1. Length against the storyboard's own target.
+  const target = storyboard.targetLengthSeconds;
+  const secs = Math.round(durationMs / 1000);
+  if (target == null) {
+    add("length", "note", `${secs}s (no targetLengthSeconds declared)`);
+  } else if (Math.abs(secs - target) > Math.max(10, target * 0.2)) {
+    add("length", "warn", `${secs}s vs targetLengthSeconds ${target}`);
+  } else {
+    add("length", "pass", `${secs}s (target ${target}s)`);
+  }
+
+  // 2. The opening frames: a demo that starts on the browser's white pre-paint.
+  const introMs = storyboard.intro?.durationMs ?? 0;
+  const blankMs = await probeFlatLeadMs(video, 4000, introMs).catch(() => 0);
+  if (blankMs > 250) {
+    add(
+      "blank-open",
+      "warn",
+      `opens on ${(blankMs / 1000).toFixed(2)}s of blank page — set output.trimLeadingBlank`
+    );
+  } else {
+    add("blank-open", "pass", `content from ${(blankMs / 1000).toFixed(2)}s`);
+  }
+
+  // 3. Poster: a white rectangle is worse than no poster at all.
+  if (await exists(project.posterPath)) {
+    const yavg = await imageYavg(project.posterPath);
+    if (yavg != null && (yavg > 180 || yavg < 25)) {
+      add(
+        "poster",
+        "warn",
+        `${relative(project.dir, project.posterPath)} looks blank (YAVG=${yavg.toFixed(1)}) — ` +
+          `set output.poster to an explicit ms`
+      );
+    } else {
+      add("poster", "pass", `${relative(project.dir, project.posterPath)} has content`);
+    }
+  }
+
+  // 4. Master loudness, and the music bed's level in the gaps.
+  const loud = await ebur128(video);
+  if (loud) {
+    // The loudness pass only runs with music, or when `output.loudness` is an
+    // explicit object — a narration-only render is deliberately untouched, so
+    // measuring it against -16 LUFS would warn on every such demo.
+    const normalized =
+      storyboard.output?.loudness !== false &&
+      (storyboard.music != null || typeof storyboard.output?.loudness === "object");
+    const wantI = normalized ? -16 : null;
+    if (wantI != null && Math.abs(loud.integrated - wantI) > 2) {
+      add(
+        "loudness",
+        "warn",
+        `I=${loud.integrated.toFixed(1)} LUFS (target ${wantI}), TP=${loud.truePeak.toFixed(1)} dBTP`
+      );
+    } else {
+      add(
+        "loudness",
+        wantI == null ? "note" : "pass",
+        `I=${loud.integrated.toFixed(1)} LUFS, TP=${loud.truePeak.toFixed(1)} dBTP` +
+          (wantI == null ? " (no loudness pass — narration only)" : "")
+      );
+    }
+    if (storyboard.music) {
+      const bed = loud.momentaryP10;
+      if (bed > -18) {
+        add("bed", "warn", `music bed ≈ ${bed.toFixed(1)} LUFS in the gaps — it will fight the voice`);
+      } else if (bed < -40) {
+        add("bed", "note", `music bed ≈ ${bed.toFixed(1)} LUFS — effectively inaudible`);
+      } else {
+        add("bed", "pass", `music bed ≈ ${bed.toFixed(1)} LUFS (p10 of the master)`);
+      }
+    }
+  }
+
+  // 5. Hold shares + whatever compose already warned about.
+  if (await exists(project.reportPath)) {
+    const report = ComposeReportSchema.safeParse(await readJson(project.reportPath));
+    if (report.success) {
+      for (const s of report.data.scenes) {
+        if (s.holdPct > 0.25) {
+          add("hold", "warn", `${s.id} held ${Math.round(s.holdPct * 100)}%`);
+        }
+      }
+      for (const w of report.data.warnings) {
+        add("hold", "warn", `engine: ${w.code} — ${w.message}`);
+      }
+      if (!report.data.warnings.length) add("hold", "pass", "no compose warnings");
+    }
+  }
+
+  // 6. Caption readability (the cue stats the captions step logs).
+  if (await exists(project.captionsCuesPath)) {
+    const cues = (await readJson(project.captionsCuesPath)) as Array<{
+      startMs: number;
+      endMs: number;
+      text: string;
+    }>;
+    const short = cues.filter((c) => c.endMs - c.startMs < 1000).length;
+    let midClause = 0;
+    cues.forEach((c, i) => {
+      const next = cues[i + 1];
+      if (!next) return;
+      if (!/[.!?,;:—–]["'”’)]?$/.test(c.text.trim()) && /^\p{Ll}/u.test(next.text.trim())) {
+        midClause++;
+      }
+    });
+    const pct = Math.round((midClause / Math.max(1, cues.length - 1)) * 100);
+    if (short > 2 || pct > 25) {
+      add("captions", "warn", `${cues.length} cues: ${short} under 1s, ${pct}% mid-clause breaks`);
+    } else {
+      add("captions", "pass", `${cues.length} cues, ${pct}% mid-clause breaks`);
+    }
+  }
+
+  // 7. Hygiene the eye catches and the schema can't: an address pill that
+  //    names one host while the demo visits several, ASCII-only chapter
+  //    titles in a non-English demo.
+  const frameUrl = storyboard.frame?.url;
+  if (frameUrl && frameUrl !== "auto") {
+    const hosts = new Set<string>();
+    for (const scene of storyboard.scenes) {
+      for (const a of scene.actions) {
+        if (a.op === "goto") {
+          const h = hostOf(a.url);
+          if (h) hosts.add(h);
+        }
+      }
+    }
+    const pill = hostOf(frameUrl);
+    if (hosts.size > 1 || (pill && hosts.size === 1 && !hosts.has(pill))) {
+      add(
+        "hygiene",
+        "warn",
+        `frame.url is the fixed "${frameUrl}" but the demo visits ${[...hosts].join(", ")} — ` +
+          `set frame.url: "auto" to track the page`
+      );
+    }
+  }
+  const lang = (storyboard.language ?? project.lang ?? "en").toLowerCase().split(/[-_]/)[0];
+  if (lang !== "en" && storyboard.output?.chapters) {
+    const ascii = storyboard.scenes.filter(
+      (s) => (s.title ?? s.id) && !/[^\x20-\x7e]/.test(s.title ?? s.id)
+    ).length;
+    if (ascii === storyboard.scenes.length) {
+      add(
+        "hygiene",
+        "note",
+        `every chapter title is ASCII in a "${lang}" demo — they are probably scene ids, not titles`
+      );
+    }
+  }
+
+  const warnings = checks.filter((c) => c.status === "warn").length;
+  const notes = checks.filter((c) => c.status === "note").length;
+  return { video, durationMs, checks, warnings, notes };
+}
+
+/** Print a QA result the way the rest of the CLI prints stages. */
+export function logQa(res: QaResult): void {
+  for (const c of res.checks) {
+    const glyph = c.status === "pass" ? "✓" : c.status === "warn" ? "W" : "·";
+    log(`  ${glyph} ${c.id.padEnd(11)}${c.message}`);
+  }
+  const line = `${res.warnings} warning(s), ${res.notes} note(s)`;
+  if (res.warnings) log(`── ${line}`);
+  else ok(line);
+}

package/src/recorder.ts

@@ -132,6 +132,8 @@ export interface RecordOptions {
    * to rebuild app state; recording starts at this scene.
    */
   fromScene?: string;
+  /** With `fromScene`: skip the reused scenes' actions instead of replaying them (state-earning flows). */
+  noReplay?: boolean;
 }
 
 /**
@@ -190,6 +192,23 @@ export async function record(
   if (profileWarning && !seededOnPurpose) log(`  ! ${profileWarning}`);
 
   const { width, height } = storyboard.video;
+  // Raw-video density (issue #51). The page always lays out at width x height
+  // CSS px; `deviceScaleFactor` only decides how many real pixels each of them
+  // gets in the recording. Chrome itself has always rendered at 2x for
+  // crispness, so 1 (the default) keeps the old, unchanged output size.
+  const videoScale = storyboard.video.deviceScaleFactor ?? 1;
+  const dsf = Math.max(2, videoScale);
+  if (videoScale > 1) {
+    log(
+      `video: ${width}x${height} CSS px recorded at ${width * videoScale}x${height * videoScale} ` +
+        `(deviceScaleFactor ${videoScale})`
+    );
+    if (external) {
+      log(
+        `  ! --capture ${mode} records real screen pixels — video.deviceScaleFactor is ignored`
+      );
+    }
+  }
   const videoDir = dirname(project.rawVideoPath);
   log(`viewport: ${width}x${height}`);
   if (external) log(`capture mode: ${mode}`);
@@ -238,7 +257,8 @@ export async function record(
             );
           } else {
             throw new Error(
-              `--from-scene: scene "${sc.id}" changed since the previous take (actions, hide, redact, viewport, cursor mode, setup or params) — resume from "${sc.id}" or earlier`
+              `--from-scene: scene "${sc.id}" changed since the previous take (actions, hide, redact, viewport, cursor mode, setup or params) — resume from "${sc.id}" or earlier. ` +
+                `A rewritten \`goto\` URL counts: a single-use magic link or a rotated token in an earlier scene changes its hash even though nothing else moved.`
             );
           }
         }
@@ -314,10 +334,13 @@ export async function record(
         ? { viewport: null }
         : {
             viewport: { width, height },
-            deviceScaleFactor: 2,
+            deviceScaleFactor: dsf,
             recordVideo: {
               dir: dirname(project.rawVideoPath),
-              size: { width, height },
+              // `deviceScaleFactor: n` records n x the CSS viewport, so the
+              // product reads at output size (issue #51); the default 1x path
+              // still writes exactly width x height.
+              size: { width: width * videoScale, height: height * videoScale },
             },
           }),
     });
@@ -389,6 +412,23 @@ export async function record(
   }
 
   const t0 = Date.now();
+  let salvageTailMs = 0;
+  let builtinTailMs = 0;
+  // Ctrl-C / SIGTERM on a stuck take used to lose everything — the process
+  // died before the timeline was written, so there was nothing to resume from
+  // (issue #55). Fold the signals into the abort signal the player polls, so
+  // an interrupted take takes the salvage path and writes what it has.
+  const interrupt = new AbortController();
+  const onSignal = (sig: NodeJS.Signals): void => {
+    if (interrupt.signal.aborted) return;
+    log(`\n${sig} — stopping the take and salvaging the scenes recorded so far`);
+    interrupt.abort();
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, interrupt.signal])
+    : interrupt.signal;
   const logsDir = project.p("logs");
   const doneScenes: TimelineScene[] = [];
   let timeline: Timeline;
@@ -401,11 +441,12 @@ export async function record(
       t0,
       video: { width, height },
       logsDir,
-      signal: options.signal,
+      signal,
       probe: options.probe,
       captureCursorPath: composeCursor,
       baseDir: project.dir,
       replayUntil: fromIndex || undefined,
+      skipReplay: !!options.noReplay,
       onSceneStart: options.onSceneStart,
       onSceneReplayed: (id, i, total) => {
         // Progress-wise a replayed scene is "done": its footage already exists.
@@ -443,6 +484,12 @@ export async function record(
     recordErr = err;
     const lastEnd = doneScenes.length ? doneScenes[doneScenes.length - 1].endMs : 0;
     timeline = { totalMs: lastEnd, leadInMs: 0, scenes: [...reused, ...doneScenes] };
+    // The take kept recording through the FAILED scene (its goto, waits and
+    // the assert/timeout that broke it). That footage sits AFTER the last
+    // completed scene, so it must not be mistaken for front lead-in at
+    // finalize: otherwise every reused scene of a later `--from-scene` resume
+    // is read that many ms too late and plays ahead of its narration.
+    salvageTailMs = Math.max(0, Date.now() - t0 - lastEnd);
     if (capture && !capFile) {
       const stopAt = Date.now();
       capFile = await capture.stop().catch(() => null);
@@ -450,7 +497,12 @@ export async function record(
     }
   } finally {
     if (capture && !capFile) await capture.stop().catch(() => {});
-    // For built-in capture, closing the context finalizes the video file.
+    // For built-in capture, closing the context finalizes the video file —
+    // and the recorder keeps taking frames until then. Everything after the
+    // last scene's end is TAIL, not front lead-in: attributing it to the
+    // lead-in shifts every scene's window later by that much, so a reused
+    // scene's window ran on into the next scene's navigation (issue #55).
+    builtinTailMs = Math.max(0, Date.now() - (t0 + timeline!.totalMs));
     await context.close();
   }
 
@@ -518,10 +570,14 @@ export async function record(
     // The front lead-in (about:blank + launch) = actual video length minus the
     // measured content span. This is more reliable than timing the launch.
     const videoMs = await probeDurationMs(project.rawVideoPath);
-    timeline.leadInMs = Math.max(0, videoMs - timeline.totalMs);
+    // salvageTailMs (the failed scene's footage) is part of builtinTailMs —
+    // both are measured from the last COMPLETED scene's end — so take the
+    // larger of the two rather than subtracting twice.
+    const tail = Math.max(builtinTailMs, salvageTailMs);
+    timeline.leadInMs = Math.max(0, videoMs - timeline.totalMs - tail);
     await writeJson(project.timelinePath, timeline);
     log(
-      `video ${videoMs}ms, content ${timeline.totalMs}ms → lead-in ${timeline.leadInMs}ms`
+      `video ${videoMs}ms, content ${timeline.totalMs}ms, tail ${tail}ms${salvageTailMs ? ` (failed-scene footage ${salvageTailMs}ms)` : ""} → lead-in ${timeline.leadInMs}ms`
     );
     ok(`recording → ${project.rawVideoPath}`);
     finalized = true;
@@ -546,6 +602,8 @@ export async function record(
       if (KEEP_RE.test(f) && !referenced.has(p)) await fs.rm(p, { force: true });
     }
   }
+  process.off("SIGINT", onSignal);
+  process.off("SIGTERM", onSignal);
   if (recordErr) {
     log(
       `salvaged ${doneScenes.length}/${storyboard.scenes.length} scene(s) before failure; ` +

package/src/safe-regex.ts

@@ -0,0 +1,36 @@
+/**
+ * Storyboard-supplied regex patterns (`assert.textMatches`, `assert.url`, and
+ * the `textMatches` option the player threads through) are compiled at replay
+ * time. A storyboard is data — it can arrive from an import, a template, or a
+ * generated variant — so a pattern must not be able to hang the take. Compile
+ * every one of them through here: the length cap and the nested-quantifier
+ * check turn a catastrophic-backtracking pattern into an authoring error
+ * raised before the browser ever touches it.
+ */
+
+/** Longest pattern we accept; real storyboard matchers are a few dozen chars. */
+const MAX_PATTERN_LEN = 1000;
+
+/**
+ * A quantified group whose body is itself quantified — `(a+)+`, `(a*)*`,
+ * `(\w+\s?)+` — is the shape that backtracks exponentially.
+ */
+const NESTED_QUANTIFIER = /\((?:\?[:=!<][a-zA-Z]*)?[^()]*[+*}][^()]*\)\s*[+*]|\((?:\?[:=!<][a-zA-Z]*)?[^()]*[+*][^()]*\)\s*\{\d+,\d*\}/;
+
+export function isUnsafeRegexSource(pattern: string): string | null {
+  if (pattern.length > MAX_PATTERN_LEN)
+    return `pattern is ${pattern.length} characters (limit ${MAX_PATTERN_LEN})`;
+  if (NESTED_QUANTIFIER.test(pattern))
+    return "pattern nests a quantifier inside a quantified group, which can backtrack exponentially";
+  return null;
+}
+
+/**
+ * Compile a storyboard-supplied pattern, or throw with `where` naming the
+ * field so the author can see which matcher to fix.
+ */
+export function compileUserRegex(pattern: string, flags: string, where: string): RegExp {
+  const unsafe = isUnsafeRegexSource(pattern);
+  if (unsafe) throw new Error(`${where}: unsafe regex — ${unsafe}`);
+  return new RegExp(pattern, flags);
+}