@tandryukha/aidemo 0.8.0 → 0.14.1

package/src/profile.ts

@@ -0,0 +1,128 @@
+/**
+ * Recording-profile hygiene.
+ *
+ * Takes replay against a persistent Chrome profile, which is what makes a
+ * logged-in demo possible at all — and also the single most dangerous piece of
+ * hidden state in the pipeline. A profile that already holds cookies or
+ * localStorage for the app skips first-run gates, onboarding, empty states and
+ * one-shot flows, and the take then *silently demonstrates the opposite of what
+ * the narration says* (issue #39). The reviewer cannot tell; nothing failed.
+ *
+ * Two remedies live here: `--fresh`, which runs the take against a throwaway
+ * profile, and a warning that names the trap when the shared profile already
+ * has state for the storyboard's origin.
+ */
+
+import { promises as fs } from "node:fs";
+import { join, resolve } from "node:path";
+import { chromeProfileDir } from "./config.js";
+import type { Storyboard } from "./types.js";
+import { exists } from "./util.js";
+
+/** Where a `--fresh` run's throwaway profile lives (wiped before each take). */
+export function freshProfileDir(demoDir: string): string {
+  return resolve(demoDir, ".chrome-profile-fresh");
+}
+
+/** Wipe and re-create the throwaway profile for a `--fresh` run. */
+export async function resetProfile(dir: string): Promise<void> {
+  await fs.rm(dir, { recursive: true, force: true });
+  await fs.mkdir(dir, { recursive: true });
+}
+
+/** The origin of the storyboard's first `goto`, or null if it has none. */
+export function firstGotoOrigin(storyboard: Storyboard): string | null {
+  for (const scene of storyboard.scenes) {
+    for (const action of scene.actions) {
+      if (action.op === "goto") {
+        try {
+          return new URL(action.url).origin;
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Does the profile already hold state for `origin`? Checks Chrome's cookie and
+ * Local Storage stores as opaque bytes — both record the origin as a plain
+ * string, so a substring scan answers the question without launching a browser
+ * or navigating anywhere. Best-effort: any read error means "don't warn".
+ */
+export async function profileHasStateFor(
+  profileDir: string,
+  origin: string
+): Promise<boolean> {
+  let host: string;
+  try {
+    host = new URL(origin).hostname;
+  } catch {
+    return false;
+  }
+  const needles = [host, `_${origin}`, origin];
+  const roots = [
+    join(profileDir, "Default", "Local Storage", "leveldb"),
+    join(profileDir, "Default", "Session Storage"),
+  ];
+  const files: string[] = [join(profileDir, "Default", "Cookies")];
+  for (const root of roots) {
+    for (const f of await fs.readdir(root).catch(() => [] as string[])) {
+      files.push(join(root, f));
+    }
+  }
+  for (const file of files) {
+    if (!(await exists(file))) continue;
+    let buf: Buffer;
+    try {
+      buf = await fs.readFile(file);
+    } catch {
+      continue;
+    }
+    // Chrome writes leveldb keys as UTF-16 for values and ASCII for keys;
+    // "latin1" catches the ASCII origin either way.
+    const text = buf.toString("latin1");
+    if (needles.some((n) => text.includes(n))) return true;
+  }
+  return false;
+}
+
+export interface ResolveProfileOptions {
+  /** Explicit --profile dir, if any. */
+  profileDir?: string;
+  /** --fresh: run against a wiped throwaway profile in the demo dir. */
+  fresh?: boolean;
+}
+
+/**
+ * Pick the profile a take should run against, preparing it if needed, and
+ * return any warning the caller should log. `--fresh` wins; otherwise the
+ * shared profile is used and checked for carried-over state.
+ */
+export async function resolveProfile(
+  demoDir: string,
+  storyboard: Storyboard,
+  opts: ResolveProfileOptions
+): Promise<{ dir: string; warning?: string }> {
+  if (opts.fresh) {
+    const dir = opts.profileDir ?? freshProfileDir(demoDir);
+    await resetProfile(dir);
+    return { dir };
+  }
+  const dir = opts.profileDir ?? chromeProfileDir();
+  const origin = firstGotoOrigin(storyboard);
+  if (origin && (await profileHasStateFor(dir, origin))) {
+    return {
+      dir,
+      warning:
+        `profile already holds cookies/localStorage for ${origin} — a first-run ` +
+        `gate, onboarding step or one-shot flow may be skipped, and the take ` +
+        `would look fine while showing the wrong story. Re-run with --fresh ` +
+        `for a clean identity — or, if the profile is seeded on purpose, ` +
+        `set setup.expectState: true (CLI --profile-seeded) to silence this.`,
+    };
+  }
+  return { dir };
+}

package/src/project.ts

@@ -1,6 +1,7 @@
 import { resolve, isAbsolute } from "node:path";
 import { StoryboardSchema, type Storyboard } from "./types.js";
 import { applyParams } from "./params.js";
+import { applyAnchors } from "./anchors.js";
 import { ensureDir, exists, readJson, writeJson, log } from "./util.js";
 
 /**
@@ -119,6 +120,14 @@ export class Project {
   get gifPath() {
     return this.p("output", this.lang ? `final-demo.${this.lang}.gif` : "final-demo.gif");
   }
+  /** Structured compose report (per-scene retime facts + warnings). */
+  get posterPath() {
+    return resolve(this.dir, "output", this.lang ? `poster.${this.lang}.png` : "poster.png");
+  }
+
+  get reportPath() {
+    return this.p("output", this.lang ? `report.${this.lang}.json` : "report.json");
+  }
   /** Directory for screenshot-mode stills (one PNG per named `still` marker). */
   get stillsDir() {
     return this.p("output", "stills");
@@ -265,11 +274,12 @@ export function parseStoryboard(
       issues: [{ path: "params", message: applied.message, code: "params" }],
     };
   }
+  const storyboard = applyAnchors(applied.storyboard);
   return {
     ok: true,
-    storyboard: applied.storyboard,
+    storyboard,
     resolved: applied.resolved,
-    warnings: storyboardWarnings(applied.storyboard),
+    warnings: storyboardWarnings(storyboard),
   };
 }
 

package/src/recorder.ts

@@ -1,16 +1,19 @@
 import { chromium } from "playwright";
 import { promises as fs } from "node:fs";
-import type {
-  Storyboard,
-  Timeline,
-  TimelineScene,
-  ProbeGoldenScene,
+import {
+  TimelineSchema,
+  type Scene,
+  type Storyboard,
+  type Timeline,
+  type TimelineScene,
+  type ProbeGoldenScene,
+  type SeedCookie,
 } from "./types.js";
 import { Project } from "./project.js";
 import { cursorInitScript } from "./cursor.js";
+import { hideCss } from "./player.js";
 import { runStoryboard } from "./player.js";
 import {
-  chromeProfileDir,
   defaultCaptureMode,
   captureDevice,
   obsUrl,
@@ -24,16 +27,86 @@ import {
   ObsCapture,
   measureViewportGeometry,
   cropCaptureToViewport,
+  verifyCaptureMatchesPage,
 } from "./capture.js";
-import { ensureDir, exists, writeJson, log, ok, step } from "./util.js";
+import { ensureProfileUnlocked } from "./login.js";
+import { resolveProfile } from "./profile.js";
+import { applySeeds, collectSeeds, runPreflight } from "./setup.js";
+import { ensureDir, exists, readJson, writeJson, log, ok, step } from "./util.js";
 import { probeDurationMs } from "./ffmpeg.js";
-import { dirname, join } from "node:path";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { createHash } from "node:crypto";
 
 const FPS = 30;
 
+/**
+ * Identity of a scene's take: everything that changes what the camera sees
+ * for that scene. `record --from-scene` reuses a previous take's scene only
+ * when this still matches, so a resumed demo never splices stale footage.
+ */
+export function sceneHash(storyboard: Storyboard, scene: Scene): string {
+  return hashIdent({
+    ...legacyIdent(storyboard, scene),
+    // A param change that alters typed text already shows up in `actions`
+    // (params resolve at load time), but one that only moves `setup` — a
+    // different cookie, a different storageState, another preflight — used to
+    // slip through and splice footage of a differently-prepared app.
+    setup: storyboard.setup ?? null,
+    params: storyboard.params ?? null,
+  });
+}
+
+/** The pre-`setup`/`params` identity — only to recognize takes recorded before it. */
+export function legacySceneHash(storyboard: Storyboard, scene: Scene): string {
+  return hashIdent(legacyIdent(storyboard, scene));
+}
+
+function legacyIdent(storyboard: Storyboard, scene: Scene): Record<string, unknown> {
+  return {
+    id: scene.id,
+    actions: scene.actions,
+    hide: [...(storyboard.hide ?? []), ...(scene.hide ?? [])],
+    redact: [...(storyboard.redact ?? []), ...(scene.redact ?? [])],
+    video: storyboard.video,
+    cursor: !!storyboard.cursor,
+  };
+}
+
+function hashIdent(ident: unknown): string {
+  return createHash("sha256").update(JSON.stringify(ident)).digest("hex").slice(0, 16);
+}
+
+/** `recordings/raw.keep-<stamp>.<ext>` — footage a resumed take still references. */
+const KEEP_RE = /^raw\.keep-.*\.(webm|mp4)$/;
+
 export interface RecordOptions {
   /** Chrome user-data dir (logged-in profile). Defaults to config profile. */
   profileDir?: string;
+  /**
+   * Run against a WIPED throwaway profile (`<demo>/.chrome-profile-fresh`)
+   * instead of the shared one. Use for any storyboard that shows a first-run
+   * gate, onboarding, an empty state or a one-shot flow — carried-over state
+   * silently records the wrong story (see src/profile.ts).
+   */
+  fresh?: boolean;
+  /**
+   * Playwright storageState JSON to seed (cookies + per-origin localStorage)
+   * before the first action — on top of the storyboard's `setup.storageState`.
+   */
+  storageState?: string;
+  /** Cookies to seed before the first action (on top of `setup.cookies`). */
+  cookies?: SeedCookie[];
+  /**
+   * The profile is seeded on purpose (a login, a cookie gate): silence the
+   * carried-over-state warning. Implied by seeds and by `setup.expectState`.
+   */
+  profileSeeded?: boolean;
+  /**
+   * Re-read the storyboard after a `setup.preflight` hook ran — the hook may
+   * have patched it (e.g. a selector for today's fixture). Call sites pass the
+   * same loader they used, so params/relaxed semantics are preserved.
+   */
+  reloadStoryboard?: () => Promise<Storyboard>;
   /** Show the browser window. Default true (channel chrome needs a display). */
   headed?: boolean;
   /**
@@ -53,6 +126,12 @@ export interface RecordOptions {
    * abort on an action failure — for `aidemo probe --golden/--update-golden`.
    */
   probe?: ProbeGoldenScene[];
+  /**
+   * Resume from this scene id: the previous take's scenes before it are kept
+   * (footage + timeline, verified unchanged by hash) and only replayed at speed
+   * to rebuild app state; recording starts at this scene.
+   */
+  fromScene?: string;
 }
 
 /**
@@ -62,9 +141,10 @@ export interface RecordOptions {
  */
 export async function record(
   project: Project,
-  storyboard: Storyboard,
+  storyboardIn: Storyboard,
   options: RecordOptions = {}
 ): Promise<Timeline> {
+  let storyboard = storyboardIn;
   step(`Recording "${storyboard.title}"`);
   await project.ensureDirs();
   await ensureDir(dirname(project.rawVideoPath));
@@ -77,13 +157,109 @@ export async function record(
     );
   }
 
-  const profileDir = options.profileDir ?? chromeProfileDir();
+  const { dir: profileDir, warning: profileWarning } = await resolveProfile(
+    project.dir,
+    storyboard,
+    { profileDir: options.profileDir, fresh: options.fresh }
+  );
+  // Fail fast with the actual fix when Chrome is still running on the profile
+  // (a live lock stalls Playwright and then dies with a raw ProcessSingleton
+  // error); clean up a stale lock from a crashed Chrome.
+  await ensureProfileUnlocked(profileDir);
+  log(`profile: ${profileDir}${options.fresh ? " (fresh)" : ""}`);
+
+  // Preflight hook (issue #44): runs before Chrome launches, with the resolved
+  // profile in its env. It may rewrite the storyboard (a rotating fixture), so
+  // re-read it afterwards when the caller gave us a loader.
+  if (storyboard.setup?.preflight) {
+    await runPreflight(storyboard.setup.preflight, {
+      demoDir: project.dir,
+      storyboardPath: project.storyboardPath,
+      profileDir,
+    });
+    if (options.reloadStoryboard) storyboard = await options.reloadStoryboard();
+  }
+  const seeds = await collectSeeds(project.dir, storyboard, {
+    storageState: options.storageState,
+    cookies: options.cookies,
+  });
+  // A deliberately seeded profile is the point, not the trap the warning
+  // names — acknowledge it via --profile-seeded / setup.expectState / seeds.
+  const seededOnPurpose =
+    !!options.profileSeeded || !!storyboard.setup?.expectState || !!seeds;
+  if (profileWarning && !seededOnPurpose) log(`  ! ${profileWarning}`);
+
   const { width, height } = storyboard.video;
   const videoDir = dirname(project.rawVideoPath);
-  log(`profile: ${profileDir}`);
   log(`viewport: ${width}x${height}`);
   if (external) log(`capture mode: ${mode}`);
 
+  // Resume: keep the previous take's leading scenes. Their raw file moves to a
+  // `raw.keep-*` name that the reused timeline scenes point at, the take's
+  // rotation below then only sees the new recording, and unreferenced keep
+  // files are swept once the resumed timeline is written.
+  let fromIndex = 0;
+  const reused: TimelineScene[] = [];
+  if (options.fromScene) {
+    fromIndex = storyboard.scenes.findIndex((s) => s.id === options.fromScene);
+    if (fromIndex < 0) {
+      throw new Error(`--from-scene: no scene "${options.fromScene}" in the storyboard`);
+    }
+    if (fromIndex === 0) {
+      log(`--from-scene ${options.fromScene} is the first scene — recording the full take`);
+    } else {
+      const prevRaw = await project.resolveRawVideo();
+      if (!(await exists(project.timelinePath)) || !(await exists(prevRaw))) {
+        throw new Error(
+          `--from-scene: no previous take to resume from (need ${project.timelinePath} + ${prevRaw}); record the full demo first`
+        );
+      }
+      const prev = TimelineSchema.parse(await readJson(project.timelinePath));
+      for (let i = 0; i < fromIndex; i++) {
+        const sc = storyboard.scenes[i];
+        const ps = prev.scenes[i];
+        if (!ps || ps.id !== sc.id) {
+          throw new Error(
+            `--from-scene: the previous take has ${ps ? `"${ps.id}"` : "nothing"} at position ${i + 1}, the storyboard has "${sc.id}" — scene order changed; record the full demo`
+          );
+        }
+        if (!ps.hash) {
+          throw new Error(
+            `--from-scene: the previous take predates resume support (no scene hashes); record the full demo once, then resume`
+          );
+        }
+        if (ps.hash !== sceneHash(storyboard, sc)) {
+          if (ps.hash === legacySceneHash(storyboard, sc)) {
+            // Recorded before `setup`/`params` were part of the identity: the
+            // action-spec still matches, so reuse the footage, but say plainly
+            // what can no longer be checked.
+            log(
+              `resume: scene "${sc.id}" predates setup/params hashing — its actions match, but a changed \`setup\` (cookies, storageState, preflight) would not be caught; re-record if the app is prepared differently now`
+            );
+          } 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`
+            );
+          }
+        }
+      }
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+      const keepPath = join(videoDir, `raw.keep-${stamp}${extname(prevRaw)}`);
+      await fs.rename(prevRaw, keepPath);
+      const keepRel = relative(project.dir, keepPath);
+      for (const ps of prev.scenes.slice(0, fromIndex)) {
+        reused.push({
+          ...ps,
+          source: ps.source ?? keepRel,
+          leadInMs: ps.leadInMs ?? prev.leadInMs,
+        });
+      }
+      log(
+        `resume: reusing ${reused.length} scene(s) from the previous take (${keepRel}); recording from "${options.fromScene}"`
+      );
+    }
+  }
+
   // Preserve the previous take as ONE `.prev` generation instead of deleting
   // it: a bad new take (mid-run failure, wrong native-capture crop) must not
   // destroy the last good recording. Roll back by copying raw.prev.* /
@@ -106,7 +282,7 @@ export async function record(
   }
   // Clear stray recordings so we can unambiguously pick the new one afterwards.
   for (const f of await fs.readdir(videoDir).catch(() => [])) {
-    if (f.endsWith(".webm") && !f.includes(".prev")) {
+    if (f.endsWith(".webm") && !f.includes(".prev") && !KEEP_RE.test(f)) {
       await fs.rm(join(videoDir, f), { force: true });
     }
   }
@@ -167,10 +343,28 @@ export async function record(
     log("cursor: compose-time overlay (recording cursor-free take + path)");
   }
 
+  // Top-level `hide`: a stylesheet injected before any page script, in every
+  // frame and across navigations — teasers, cookie bars, ad slots that would
+  // photobomb the take. The ONE record-time exception to compose-time polish.
+  if (storyboard.hide?.length) {
+    const css = hideCss(storyboard.hide);
+    await context.addInitScript({
+      content:
+        `(() => { const add = () => { const s = document.createElement("style");` +
+        ` s.id = "__aidemo_hide"; s.textContent = ${JSON.stringify(css)};` +
+        ` (document.head || document.documentElement).appendChild(s); };` +
+        ` if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", add); else add(); })();`,
+    });
+    log(`hide: ${storyboard.hide.length} selector(s) hidden at record time`);
+  }
+
   const page = context.pages()[0] ?? (await context.newPage());
 
   // Start from a clean blank so the recording's lead-in isn't the new-tab page.
   await page.goto("about:blank");
+  // Seed cookies / localStorage (issue #44). Any origin visits this needs land
+  // in the lead-in, which compose trims.
+  if (seeds) await applySeeds(context, page, seeds);
 
   let capture: CaptureProvider | null = null;
   let geo: ViewportGeometry | null = null;
@@ -187,6 +381,11 @@ export async function record(
         : new ObsCapture(obsUrl(), obsPassword());
     log(`starting ${capture.name}`);
     await capture.start();
+    // Re-assert front-most right before driving: the measure/start dance takes
+    // seconds, and a screen grab records whatever window is PAINTED at the
+    // crop rect — an occluded browser silently ships someone else's window
+    // into the take (issue #21).
+    await page.bringToFront();
   }
 
   const t0 = Date.now();
@@ -194,6 +393,7 @@ export async function record(
   const doneScenes: TimelineScene[] = [];
   let timeline: Timeline;
   let capFile: string | null = null;
+  let captureRefPath: string | null = null;
   let tailMs = 0;
   let recordErr: unknown = null;
   try {
@@ -204,13 +404,30 @@ export async function record(
       signal: options.signal,
       probe: options.probe,
       captureCursorPath: composeCursor,
+      baseDir: project.dir,
+      replayUntil: fromIndex || undefined,
       onSceneStart: options.onSceneStart,
+      onSceneReplayed: (id, i, total) => {
+        // Progress-wise a replayed scene is "done": its footage already exists.
+        options.onSceneComplete?.(reused[i], i, total);
+      },
       onSceneComplete: (s, i, total) => {
+        s.hash = sceneHash(storyboard, storyboard.scenes[i]);
         doneScenes.push(s);
         options.onSceneComplete?.(s, i, total);
       },
     });
+    timeline.scenes = [...reused, ...doneScenes];
     if (capture) {
+      // Reference frame for the post-crop content verification (issue #21):
+      // the CDP page buffer at stop time — immune to window occlusion, so if
+      // the cropped screen pixels don't match it, the grab recorded something
+      // other than the driven page. Taken BEFORE stopAt so its latency lands
+      // in the (trimmed) tail, not in the lead-in math.
+      captureRefPath = join(videoDir, "capture-ref.png");
+      await page
+        .screenshot({ path: captureRefPath, timeout: 5000 })
+        .catch(() => (captureRefPath = null));
       // Stop immediately so the tail past the last scene stays small. Measure
       // the tail at stop-initiation — the recorder stops taking frames at the
       // stop signal, not when it finishes flushing the file.
@@ -222,10 +439,10 @@ export async function record(
     // Salvage: a failure in scene 7 of 7 (a phantom click, a platform
     // interruption) otherwise discards minutes of good recording. Keep the
     // scenes that completed, still finalize the video below, then re-throw so
-    // the exit code stays 1. `record --from-scene <id>` resume is future work.
+    // the exit code stays 1; `record --from-scene <id>` resumes past them.
     recordErr = err;
     const lastEnd = doneScenes.length ? doneScenes[doneScenes.length - 1].endMs : 0;
-    timeline = { totalMs: lastEnd, leadInMs: 0, scenes: doneScenes };
+    timeline = { totalMs: lastEnd, leadInMs: 0, scenes: [...reused, ...doneScenes] };
     if (capture && !capFile) {
       const stopAt = Date.now();
       capFile = await capture.stop().catch(() => null);
@@ -250,6 +467,18 @@ export async function record(
       FPS
     );
     await fs.rm(capFile!, { force: true });
+    // Content guard (issue #21): geometry can be perfect while the pixels are
+    // some other window's (occlusion / wrong display). On mismatch this throws
+    // and keeps both files for review; on pass the reference is cleaned up.
+    // A salvaged (failed) take skips it — the reference may not exist.
+    if (captureRefPath && !recordErr) {
+      await verifyCaptureMatchesPage(project.rawVideoMp4Path, captureRefPath);
+      await fs.rm(captureRefPath, { force: true });
+    } else if (!recordErr) {
+      log(
+        "⚠ no page reference screenshot — capture content not verified; frame-review the take"
+      );
+    }
     const videoMs = await probeDurationMs(project.rawVideoMp4Path);
     // Capture started before t0 and stopped ~tailMs after the last scene.
     timeline.leadInMs = Math.max(0, videoMs - tailMs - timeline.totalMs);
@@ -267,7 +496,7 @@ export async function record(
     // recording), not just the first one, then drop the strays. The preserved
     // previous take (raw.prev.webm) is not a candidate.
     const produced = (await fs.readdir(videoDir)).filter(
-      (f) => f.endsWith(".webm") && !f.includes(".prev")
+      (f) => f.endsWith(".webm") && !f.includes(".prev") && !KEEP_RE.test(f)
     );
     if (produced.length === 0) {
       throw new Error(`No video produced in ${videoDir}`);
@@ -308,6 +537,14 @@ export async function record(
     ok(
       `timeline  → ${project.timelinePath} (${timeline.scenes.length} scenes, ${timeline.totalMs}ms)`
     );
+    // Sweep keep files no scene of the written timeline points at anymore.
+    const referenced = new Set(
+      timeline.scenes.filter((s) => s.source).map((s) => resolve(project.dir, s.source!))
+    );
+    for (const f of await fs.readdir(videoDir).catch(() => [])) {
+      const p = join(videoDir, f);
+      if (KEEP_RE.test(f) && !referenced.has(p)) await fs.rm(p, { force: true });
+    }
   }
   if (recordErr) {
     log(