@tandryukha/aidemo 0.15.1 → 0.16.0

package/README.md

@@ -161,7 +161,8 @@ open examples/local-demo/output/final-demo.mp4   # xdg-open on Linux, start on W
 Voice/captions need `OPENAI_API_KEY` in `.env` — **or** `AIDEMO_TTS_PROVIDER=local`
 (no key, offline), **or** `OPENAI_BASE_URL` at a local server. See
 [docs/LOCAL_MODELS.md](docs/LOCAL_MODELS.md). No Playwright browser download is
-needed — the engine uses your system Chrome (`channel: "chrome"`).
+needed — the engine uses your system Chrome (`channel: "chrome"`; see
+[Setup](#setup) to use a different browser).
 
 [![Quickstart output — the bundled fixture rendered end-to-end](docs/quickstart.gif)](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/quickstart-demo.mp4)
 
@@ -214,6 +215,10 @@ Codex).
 - **Pipeline tools run as jobs** — `probe`/`record`/`render`/`voice`/`captions`/
   `compose`/`gif` return a `jobId` immediately; `job_status` reports stage,
   per-scene progress, and (on failure) the screenshot/frame-dump paths.
+- **`.env` works like the CLI** — the server loads its cwd's and the engine's
+  `.env` at startup, and since MCP clients often start it outside your repo, each
+  tool given a demo dir also applies that repo's `.env` (nearest one walking up
+  from the demo dir to the repo root). `doctor {dir}` shows the result.
 
 ## Why it's built this way
 
@@ -253,6 +258,22 @@ npm install
 cp .env.example .env      # add OPENAI_API_KEY, or use AIDEMO_TTS_PROVIDER=local (no key)
 ```
 
+**Choosing the browser.** Every launch (recording, `inspect`, caption/card
+rasterizing) uses system Google Chrome by default. Two env vars (shell or
+`.env`) override that, highest precedence first:
+
+- `AIDEMO_CHROME_EXECUTABLE=/path/to/chrome` — an explicit Chromium-based binary.
+- `AIDEMO_CHROME_CHANNEL=<channel>` — a Playwright channel: `chrome` (default),
+  `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`,
+  `msedge-dev`, `msedge-canary`, or `chromium`. `chromium` (Chrome for Testing)
+  is the fix when an enterprise-managed Chrome closes automated sessions after
+  a few seconds ("Target page, context or browser has been closed"); it needs a
+  one-time `npx playwright install chromium`.
+
+`aidemo doctor` reports which browser will be used and whether it was found.
+`aidemo login` opens the same browser, so the profile you log into matches the
+one you record with.
+
 ## Project layout (per demo)
 
 ```

package/docs/AUTHORING.md

@@ -70,6 +70,12 @@ scan inside them). Use it instead of reading source or guessing: copy the
 first selector of the element you mean. It writes `logs/inspect-<ts>.json`
 and a screenshot next to it. Elements below the fold are listed too (marked
 `↓` on the CLI); a `scrollTo` on them works as usual.
+The result includes `target.status` (`available` or `blocked`). Common
+security-verification and login pages return `blocked` with a reason: their
+selectors describe the interstitial, not the requested product. Inspection
+still writes its JSON and screenshot for diagnosis; `init --from-url` stops
+instead of drafting scenes from a blocked page. Open the page with an
+authenticated profile or use supported setup seeding, then inspect again.
 
 `inspect` runs the storyboard's **`setup`** block by default — preflight hook,
 `storageState`, cookies — so a gated app scans as the logged-in user instead of
@@ -613,12 +619,21 @@ millisecond instead, when you want a specific moment.
 
 **Blank opening** (`output.trimLeadingBlank: true`): a take that starts on a
 page still painting opens on white/blank frames. With this on, compose trims
-the flat lead of the first scene (capped by `output.blankOpenCapMs`, default
-1200) and re-aligns the scene's cursor, zoom and anchors to the trim. Compose
-always *measures* the opening either way and reports it as `blankOpenMs` plus
-a `blank-open` warning past ~400 ms; `aidemo lint` forecasts the same pitfall
+the blank lead of the first scene down to `output.blankOpenCapMs` (default
+100 ms kept) and re-aligns the scene's cursor, zoom and anchors to the trim.
+Compose always *measures* the opening either way — on the page footage,
+before captions and overlays — and reports it as `blankOpenMs` plus a
+`blank-open` warning past ~250 ms; `aidemo lint` forecasts the same pitfall
 from a first scene that opens with a `goto` and no wait.
 
+"Blank" means *empty*, not *static*: one colour covering the frame **and** no
+text or outlines beyond a cursor-sized mark. A white pre-paint or a solid
+splash (any colour, black included) is blank; a motionless page that shows
+something — a dark terminal with a prompt line, a login box on a big solid
+background — is content, so it is never trimmed or warned about. The same
+test guards the freeze-hold tail trim (`blank-tail`). A frame showing only a
+cursor, a lone `$` or a small spinner still reads as blank.
+
 ## Capture resolution (`video.deviceScaleFactor`)
 
 `video: {width, height}` is the **logical** viewport — the CSS px the page
@@ -763,7 +778,7 @@ for UI that re-renders under the cursor) and `anchor?` (land this action on a
   out of the way before a reveal, or point at what the narration names.
 - `{op:"assert", target?, textMatches?, url?, timeoutMs?=5000}` — **prove the
   payoff happened**: polls until `target` is visible (and its text matches
-  `textMatches`, JS regex, no inline flags — use `[Cc]onfirmed`) and/or the
+  `textMatches`, RE2-compatible regex, no inline flags — use `[Cc]onfirmed`) and/or the
   page URL matches `url`; otherwise **fails the take with a named error**
   (`assert failed after 5000ms: text "…" does not match /…/`). Put one after
   the moment the demo exists to show (order confirmed, item added) so a
@@ -1211,8 +1226,14 @@ CLI. If nothing came up, skip this.
   composed video) to see the whole thing.
 - `AIDEMO_KEEP_TMP=1` preserves `.compose-tmp/` intermediates when debugging
   compose.
-- `doctor` checks Node, ffmpeg, Chrome, the TTS/STT endpoint (and flags
-  LLM-only servers like Ollama, which have no audio endpoints — point
+- Browser: every launch uses system Chrome unless `AIDEMO_CHROME_EXECUTABLE`
+  (explicit binary) or `AIDEMO_CHROME_CHANNEL` (`chromium` — Chrome for
+  Testing, after `npx playwright install chromium` — `chrome-beta`, `msedge`,
+  …) is set; the executable wins. Use `chromium` when a managed Chrome closes
+  the automated session after a few seconds ("Target page, context or browser
+  has been closed").
+- `doctor` checks Node, ffmpeg, the browser in use, the TTS/STT endpoint
+  (and flags LLM-only servers like Ollama, which have no audio endpoints — point
   `OPENAI_BASE_URL` at a speech server such as speaches instead).
 
 ## Import from Playwright (trace or test file)
@@ -1319,6 +1340,15 @@ all) using each scene's measured duration from `voice.json`; only the timing
 measured speech rhythm). `captions` logs a one-line reminder of this whenever
 the resolved language isn't English.
 
+The STT caption step compares each scene's recognized words with its known
+script and warns when at least 20% differ. Review those captions before
+publishing. `aidemo captions <dir> --align-script` uses the script's spelling
+and punctuation while retaining the measured STT word times; words missing
+from the transcript are placed between their nearest timed neighbours. This
+is useful for misheard names and inflected words. If the spoken narration
+actually differs from the script, correct the script or use the original STT
+captions instead.
+
 **Cue segmentation.** Cues are broken at sentence ends first, then at clause
 punctuation, then before a conjunction, and only then on length — so a cue
 stops reading like it was cut mid-thought ("we open the" / "settings panel").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tandryukha/aidemo",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "license": "MIT",
   "description": "AI Demo Engine — turn a storyboard into a narrated, captioned product demo video",
   "type": "module",
@@ -28,15 +28,18 @@
     "build": "tsc --noEmit",
     "serve-example": "node examples/local-demo/serve.mjs",
     "mcp-smoke": "node test/mcp-smoke.mjs",
+    "test:blank-open": "tsx --test test/blank-open.mjs",
+    "mcp-env-test": "node test/mcp-env.mjs",
     "guard-openai-key": "tsx scripts/guard-openai-key.ts",
     "sync:plugin-skill": "cp .claude/skills/record-demo/SKILL.md plugins/record-demo/skills/record-demo/SKILL.md",
     "check:plugin-skill": "diff -q .claude/skills/record-demo/SKILL.md plugins/record-demo/skills/record-demo/SKILL.md"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "commander": "^12.1.0",
     "openai": "^4.67.0",
     "playwright": "^1.55.1",
+    "re2js": "2.8.6",
     "tsx": "^4.23.1",
     "zod": "^3.23.8",
     "zod-to-json-schema": "3.25.2"

package/src/attention.ts

@@ -12,7 +12,8 @@
  * every PNG is rendered at deviceScaleFactor = pxScale so it lands 1:1.
  */
 
-import { chromium, type Page } from "playwright";
+import type { Page } from "playwright";
+import { launchChrome } from "./browser.js";
 import { resolve } from "node:path";
 import type { AttentionEvent, AttentionStyle, RedactSpan } from "./types.js";
 import { ensureDir } from "./util.js";
@@ -107,7 +108,7 @@ export async function renderAttentionPngs(
 ): Promise<OverlayItem[]> {
   if (events.length === 0) return [];
   await ensureDir(outDir);
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   const context = await browser.newContext({
     viewport: { width: videoW, height: videoH },
     deviceScaleFactor: pxScale,
@@ -231,7 +232,7 @@ export async function renderKeyChipPngs(
 ): Promise<OverlayItem[]> {
   if (keys.length === 0) return [];
   await ensureDir(outDir);
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   const context = await browser.newContext({
     viewport: { width: 600, height: 120 },
     deviceScaleFactor: pxScale,
@@ -287,7 +288,7 @@ export async function renderClickRingPngs(
 ): Promise<OverlayItem[]> {
   if (clicks.length === 0) return [];
   await ensureDir(outDir);
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   const context = await browser.newContext({
     viewport: { width: 64, height: 64 },
     deviceScaleFactor: pxScale,

package/src/browser.ts

@@ -0,0 +1,108 @@
+/**
+ * Single choke point for every Playwright browser launch (issue #80).
+ *
+ * Every launch site — recorder, inspect, caption/card/frame/attention/cursor
+ * rasterizers — goes through launchChrome()/launchChromePersistent(), which
+ * merge chromeLaunchOptions() (AIDEMO_CHROME_EXECUTABLE > AIDEMO_CHROME_CHANNEL
+ * > `channel: "chrome"`) into the caller's options. With neither env var set
+ * the options are exactly the engine's historical `{ channel: "chrome", ... }`.
+ */
+import { chromium, type Browser, type BrowserContext, type LaunchOptions } from "playwright";
+import { BrowserSetupError, chromeLaunchOptions, type ChromeLaunchTarget } from "./config.js";
+
+type PersistentOptions = NonNullable<Parameters<typeof chromium.launchPersistentContext>[1]>;
+
+/** Human-readable description of the configured browser, for logs/doctor. */
+export function describeChromeTarget(target: ChromeLaunchTarget = chromeLaunchOptions()): string {
+  if ("executablePath" in target) return `executable ${target.executablePath} (AIDEMO_CHROME_EXECUTABLE)`;
+  return target.channel === "chrome" && !process.env.AIDEMO_CHROME_CHANNEL?.trim()
+    ? `channel chrome (default — system Google Chrome)`
+    : `channel ${target.channel} (AIDEMO_CHROME_CHANNEL)`;
+}
+
+const MISSING_RE =
+  /Executable doesn't exist|is not found at|distribution '[^']*' is not found|npx playwright install|ENOENT/i;
+
+/**
+ * Turn a "browser binary not found" launch failure into an actionable error.
+ * Any other failure is returned untouched so callers' own wrapping (e.g. the
+ * recorder's profile-lock hint) still sees the original message.
+ */
+export function explainLaunchError(err: unknown, target: ChromeLaunchTarget): Error {
+  const e = err instanceof Error ? err : new Error(String(err));
+  if (!MISSING_RE.test(e.message)) return e;
+  let hint: string;
+  if ("executablePath" in target) {
+    hint =
+      `AIDEMO_CHROME_EXECUTABLE=${target.executablePath} could not be launched — ` +
+      `point it at an existing Chromium-based browser binary, or unset it.`;
+  } else if (target.channel === "chromium") {
+    hint =
+      `Playwright's Chromium (AIDEMO_CHROME_CHANNEL=chromium) is not installed — ` +
+      `run: npx playwright install chromium   (or unset AIDEMO_CHROME_CHANNEL to use system Chrome).`;
+  } else if (target.channel === "chrome") {
+    hint =
+      `Google Chrome was not found. Install Chrome, or use Playwright's Chromium: ` +
+      `npx playwright install chromium && set AIDEMO_CHROME_CHANNEL=chromium ` +
+      `(or AIDEMO_CHROME_EXECUTABLE=/path/to/chrome).`;
+  } else {
+    hint =
+      `Browser channel "${target.channel}" (AIDEMO_CHROME_CHANNEL) is not installed — ` +
+      `install it (npx playwright install ${target.channel}) or unset AIDEMO_CHROME_CHANNEL.`;
+  }
+  const out = new BrowserSetupError(`${hint}\nOriginal error: ${e.message}`);
+  (out as Error & { cause?: unknown }).cause = e;
+  return out;
+}
+
+/** chromium.launch() with the configured browser. */
+export async function launchChrome(options: Omit<LaunchOptions, "channel" | "executablePath"> = {}): Promise<Browser> {
+  const target = chromeLaunchOptions();
+  try {
+    return await chromium.launch({ ...target, ...options });
+  } catch (err) {
+    throw explainLaunchError(err, target);
+  }
+}
+
+/** chromium.launchPersistentContext() with the configured browser. */
+export async function launchChromePersistent(
+  userDataDir: string,
+  options: Omit<PersistentOptions, "channel" | "executablePath"> = {}
+): Promise<BrowserContext> {
+  const target = chromeLaunchOptions();
+  try {
+    return await chromium.launchPersistentContext(userDataDir, { ...target, ...options });
+  } catch (err) {
+    throw explainLaunchError(err, target);
+  }
+}
+
+/**
+ * Doctor probe for a NON-default browser target: launch it headless once and
+ * read its version. Returns `{ version }` or `{ error }` (actionable message).
+ */
+export async function probeConfiguredBrowser(): Promise<{ version: string } | { error: string }> {
+  let browser: Browser | undefined;
+  try {
+    browser = await launchChrome({ headless: true, timeout: 20000 });
+    return { version: browser.version() };
+  } catch (err) {
+    return { error: (err as Error).message.split("\n")[0] };
+  } finally {
+    await browser?.close().catch(() => {});
+  }
+}
+
+/**
+ * Binary for a NON-Playwright launch (`aidemo login` opens a normal window on
+ * the profile) when the configured browser isn't system Chrome: the
+ * AIDEMO_CHROME_EXECUTABLE path, or Playwright's Chromium for
+ * AIDEMO_CHROME_CHANNEL=chromium. null = keep login's system-Chrome launch.
+ */
+export function manualLaunchBinary(): string | null {
+  const target = chromeLaunchOptions();
+  if ("executablePath" in target) return target.executablePath;
+  if (target.channel === "chromium") return chromium.executablePath();
+  return null;
+}

package/src/caption-render.ts

@@ -1,4 +1,4 @@
-import { chromium } from "playwright";
+import { launchChrome } from "./browser.js";
 import { resolve } from "node:path";
 import type { Cue } from "./captions.js";
 import type { CaptionsConfig } from "./types.js";
@@ -28,7 +28,7 @@ export async function renderCaptionPngs(
   look: CaptionsConfig & { font?: string } = {}
 ): Promise<RenderedCue[]> {
   await ensureDir(outDir);
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   // Layout at the storyboard's logical width; deviceScaleFactor matches the
   // raw video's pixel density (1 for Playwright capture, 2 for native/OBS
   // retina capture) so the PNG overlays the frame 1:1.

package/src/captions.ts

@@ -96,6 +96,8 @@ const MAX_PROMPT_CHARS = 900;
 export interface CaptionsSttOptions extends SceneProgress {
   /** ISO-639-1/BCP-47 language hint for Whisper, overriding --lang / storyboard.language. */
   language?: string;
+  /** Use storyboard spelling/punctuation while retaining STT word timing. */
+  alignScript?: boolean;
 }
 
 /**
@@ -168,6 +170,7 @@ export async function generateCaptions(
     config,
     prompt,
     language,
+    ...(opts.alignScript ? { alignScript: true } : {}),
   });
   const prior = await readCaptionsManifest(project);
   if (prior && prior.mode === "stt" && prior.inputHash === inputHash) {
@@ -197,13 +200,32 @@ export async function generateCaptions(
   if (words.length === 0) {
     log("no word timestamps returned; captions may be empty");
   }
-  const cues = groupWords(words, sceneEnds, seg);
+  const sceneWords = splitWordsByScene(words, ids, sceneEnds, config.gapMs);
+  let captionWords = words;
+  if (storyboard && sceneEnds.length === storyboard.scenes.length) {
+    const aligned: Word[] = [];
+    let sceneStartMs = 0;
+    for (let i = 0; i < storyboard.scenes.length; i++) {
+      const scene = storyboard.scenes[i];
+      const timed = sceneWords[i]?.words ?? [];
+      const result = alignCaptionWords(scene.narration, timed, sceneEnds[i] - sceneStartMs);
+      if (result.driftPct >= 20) {
+        log(`⚠ caption drift in scene ${scene.id}: ${result.driftPct}% of script words differ from STT; ${opts.alignScript ? "script text aligned to STT timing — review against the audio" : "review captions or use --align-script"}`);
+      }
+      for (const w of result.words) aligned.push({ ...w, start: w.start + sceneStartMs / 1000, end: w.end + sceneStartMs / 1000 });
+      sceneStartMs = sceneEnds[i] + config.gapMs;
+    }
+    if (opts.alignScript) captionWords = aligned;
+  } else if (opts.alignScript) {
+    throw new Error("--align-script requires a storyboard and matching voice scene timings");
+  }
+  const cues = groupWords(captionWords, sceneEnds, seg);
   await writeCaptionFiles(project, cues);
   await writeCaptionsManifest(project, {
     mode: "stt",
     inputHash,
     config,
-    scenes: splitWordsByScene(words, ids, sceneEnds, config.gapMs),
+    scenes: opts.alignScript ? splitWordsByScene(captionWords, ids, sceneEnds, config.gapMs) : sceneWords,
     cues,
   });
   reportDone();
@@ -245,6 +267,62 @@ function splitWordsByScene(
   return out;
 }
 
+/** Align written words to measured STT timestamps. Inserted script words share
+ * the space between their nearest timed neighbours; STT-only words are dropped. */
+export function alignCaptionWords(
+  narration: string,
+  spoken: Word[],
+  durationMs: number
+): { words: Word[]; driftPct: number } {
+  const script = narration.split(/\s+/).filter(Boolean);
+  if (!script.length) return { words: [], driftPct: spoken.length ? 100 : 0 };
+  if (!spoken.length) return { words: deriveSceneWords(narration, durationMs), driftPct: 100 };
+  const norm = (s: string) => s.normalize("NFKC").toLocaleLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+  const n = script.length, m = spoken.length;
+  const dp = Array.from({ length: n + 1 }, () => new Uint16Array(m + 1));
+  for (let i = 0; i <= n; i++) dp[i][0] = i;
+  for (let j = 0; j <= m; j++) dp[0][j] = j;
+  for (let i = 1; i <= n; i++) for (let j = 1; j <= m; j++) {
+    dp[i][j] = Math.min(
+      dp[i - 1][j - 1] + (norm(script[i - 1]) === norm(spoken[j - 1].word) ? 0 : 1),
+      dp[i - 1][j] + 1,
+      dp[i][j - 1] + 1
+    );
+  }
+  const matched: Array<number | undefined> = Array(n).fill(undefined);
+  let i = n, j = m;
+  while (i && j) {
+    const cost = norm(script[i - 1]) === norm(spoken[j - 1].word) ? 0 : 1;
+    if (dp[i][j] === dp[i - 1][j - 1] + cost) {
+      matched[--i] = --j;
+    } else if (dp[i][j] === dp[i - 1][j] + 1) {
+      i--;
+    } else {
+      j--;
+    }
+  }
+  const duration = Math.max(0, durationMs / 1000);
+  const words: Word[] = script.map((word, k) => {
+    const at = matched[k];
+    return at === undefined ? { word, start: 0, end: 0 } : {
+      word, start: Math.max(0, spoken[at].start), end: Math.min(duration, spoken[at].end),
+    };
+  });
+  for (let k = 0; k < n;) {
+    if (matched[k] !== undefined) { k++; continue; }
+    const first = k;
+    while (k < n && matched[k] === undefined) k++;
+    const start = first ? words[first - 1].end : 0;
+    const end = k < n ? words[k].start : duration;
+    const span = Math.max(0, end - start);
+    for (let t = first; t < k; t++) {
+      words[t].start = start + span * (t - first) / (k - first);
+      words[t].end = start + span * (t - first + 1) / (k - first);
+    }
+  }
+  return { words, driftPct: Math.round(100 * dp[n][m] / Math.max(n, m)) };
+}
+
 /** Scene-relative words for a scene; script-timed fallback when the manifest has none. */
 export async function sceneWordsFor(
   project: Project,

package/src/cards.ts

@@ -1,4 +1,4 @@
-import { chromium } from "playwright";
+import { launchChrome } from "./browser.js";
 import type { Brand, Card } from "./types.js";
 
 /**
@@ -17,7 +17,7 @@ export async function renderCardPng(
   brand?: Brand,
   logoDataUri?: string
 ): Promise<void> {
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   const context = await browser.newContext({
     viewport: { width: logicalW, height: logicalH },
     deviceScaleFactor: scale,

package/src/cli.ts

@@ -664,6 +664,9 @@ program
         process.stdout.write(JSON.stringify(res, null, 2) + "\n");
         return;
       }
+      if (res.target.status === "blocked") {
+        process.stdout.write(`⚠ inspect blocked: ${res.target.reason}\n`);
+      }
       process.stdout.write(`${res.title || "(untitled)"} — ${res.finalUrl}\n`);
       if (res.headings.length) {
         process.stdout.write(
@@ -967,6 +970,7 @@ program
   .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
   .option("--lang <code>", LANG_OPT_DESC)
   .option("--langs <codes>", LANGS_OPT_DESC)
+  .option("--align-script", "restore storyboard spelling and punctuation using STT word timing", false)
   .option(
     "--stt-lang <code>",
     "override the Whisper STT language hint (ISO-639-1, e.g. et) — defaults to " +
@@ -982,6 +986,7 @@ program
         lang?: string;
         langs?: string;
         sttLang?: string;
+        alignScript?: boolean;
       }
     ) => {
       const langs = langsFrom(opts);
@@ -998,7 +1003,7 @@ program
         if (opts.offline) {
           await generateCaptionsOffline(project, sb);
         } else {
-          await generateCaptions(project, sb, { language: opts.sttLang });
+          await generateCaptions(project, sb, { language: opts.sttLang, alignScript: opts.alignScript });
         }
       }
     }

package/src/compose.ts

@@ -236,7 +236,7 @@ export async function compose(
     let leadTrimMs = 0;
     if (i === 0 && storyboard.output?.trimLeadingBlank && srcMs > 1000) {
       const cap = storyboard.output.blankOpenCapMs ?? 100;
-      const flatLead = await probeFlatLeadMs(rawSegPath);
+      const flatLead = await probeFlatLeadMs(rawSegPath, 4000, 0, pxScale);
       if (flatLead > cap + 80) {
         leadTrimMs = Math.min(flatLead - cap, srcMs - 500);
         srcMs -= leadTrimMs;
@@ -251,7 +251,7 @@ export async function compose(
     // (issue #36), so drop a flat tail before deciding how long to hold —
     // but only when we would actually hold, and never the whole segment.
     if (srcMs > 0 && targetMs > srcMs + 400) {
-      const flatMs = await probeFlatTailMs(rawSegPath, srcMs);
+      const flatMs = await probeFlatTailMs(rawSegPath, srcMs, 4000, pxScale);
       const trimTo = srcMs - flatMs;
       if (flatMs > 200 && trimTo > 500) {
         blankTrimMs = flatMs;
@@ -668,6 +668,13 @@ export async function compose(
     );
   }
 
+  // Blank-open measurement (issues #47, #78), taken HERE — on the assembled
+  // scenes, before redaction, attention, compose-time cursor, zoom, frame and
+  // captions — because the final MP4 can't tell a blank page from content: a
+  // caption pill over a white pre-paint has as much text as a terminal prompt.
+  // Same timeline as the final video minus the intro card.
+  const blankOpenMs = await probeFlatLeadMs(content, 4000, 0, pxScale).catch(() => 0);
+
   // Redaction first: blur boxes ride every later pass (cursor, zoom, blur).
   if (redactPlaced.length) {
     let src = content;
@@ -1094,10 +1101,10 @@ export async function compose(
     : null;
   await muxAudio(project, storyboard, finalVideo, introMs, chapters);
   ok(`final video → ${project.outputPath}`);
-  // Blank-open measurement + poster (issue #47). The poster used to be taken
-  // at a fixed offset, which on a demo that opens with a `goto` is exactly the
-  // white load frame; pick the first frame that actually shows content instead.
-  const blankOpenMs = await probeFlatLeadMs(project.outputPath, 4000, introMs).catch(() => 0);
+  // Blank-open warning + poster (issue #47; measured after scene assembly,
+  // above). The poster used to be taken at a fixed offset, which on a demo
+  // that opens with a `goto` is exactly the white load frame; pick the first
+  // frame that actually shows content instead.
   if (blankOpenMs > 250) {
     warn(
       "blank-open",

package/src/config.ts

@@ -66,7 +66,9 @@ async function readEnvFile(envPath: string): Promise<Record<string, string>> {
  * instead. See scripts/guard-openai-key.ts, which fails the build if this
  * skip-if-already-set shape ever comes back. Ambient only wins here when
  * NEITHER .env file defines the key at all (e.g. a deliberate one-off invocation
- * like `OPENAI_API_KEY=sk-... aidemo record ...`). Called once at CLI startup.
+ * like `OPENAI_API_KEY=sk-... aidemo record ...`). Called once at CLI startup —
+ * which includes `aidemo mcp`; MCP tools then layer the demo's project .env on
+ * top via applyProjectEnv(), since the server's cwd is rarely the project.
  */
 export async function loadEnv(): Promise<void> {
   const cwdEnv = resolve(process.cwd(), ".env");
@@ -79,6 +81,71 @@ export async function loadEnv(): Promise<void> {
   }
 }
 
+/**
+ * The `.env` a CLI user of this demo dir would have loaded: the nearest
+ * `.env` walking up from `dir`, stopping at the enclosing repo root (the
+ * first ancestor holding `.git`) — i.e. the cwd/.env of someone running
+ * `aidemo <cmd> demos/<name>` from their repo. null when there is none.
+ */
+async function findProjectEnv(dir: string): Promise<string | null> {
+  let cur = resolve(dir);
+  for (;;) {
+    const candidate = resolve(cur, ".env");
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // keep walking
+    }
+    try {
+      await fs.access(resolve(cur, ".git"));
+      return null; // repo root reached without a .env
+    } catch {
+      // not a repo root
+    }
+    const parent = resolve(cur, "..");
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+/** Keys a project .env overrode → their value before the first override (undefined = unset). */
+const projectEnvSaved = new Map<string, string | undefined>();
+let projectEnvFile: string | null = null;
+
+/**
+ * MCP counterpart of loadEnv()'s cwd/.env layer (issue #77). loadEnv() runs
+ * once at startup for `aidemo mcp` too, but an MCP client usually spawns the
+ * server with a cwd that is NOT the consumer's repo (and an npx engine root
+ * has no .env), so the project's .env was never seen. Tools that take a demo
+ * dir call this to apply that project's .env (see findProjectEnv) with the
+ * same precedence as the CLI's cwd/.env: it overrides the engine .env and the
+ * ambient environment. Switching to another project first restores every key
+ * the previous project's .env set, so values never leak between repos.
+ * Logs only to stderr (stdout is the JSON-RPC channel). Returns the file applied.
+ */
+export async function applyProjectEnv(dir: string): Promise<string | null> {
+  const envFile = await findProjectEnv(dir);
+  const values = envFile ? await readEnvFile(envFile) : {};
+  for (const [key, prev] of projectEnvSaved) {
+    if (key in values) continue;
+    if (prev === undefined) delete process.env[key];
+    else process.env[key] = prev;
+    projectEnvSaved.delete(key);
+  }
+  for (const [key, val] of Object.entries(values)) {
+    if (!projectEnvSaved.has(key)) projectEnvSaved.set(key, process.env[key]);
+    process.env[key] = val;
+  }
+  if (envFile !== projectEnvFile) {
+    process.stderr.write(
+      envFile ? `  env: loaded ${envFile}\n` : `  env: no project .env for ${resolve(dir)}\n`
+    );
+    projectEnvFile = envFile;
+  }
+  return envFile;
+}
+
 /**
  * Custom endpoint for any OpenAI-compatible server (LocalAI, speaches,
  * Kokoro-FastAPI, …). AIDEMO_OPENAI_BASE_URL wins over the SDK-standard
@@ -220,3 +287,55 @@ export const obsPassword = () => process.env.AIDEMO_OBS_PASSWORD;
  */
 export const nativeCropUnsafe = () =>
   process.env.AIDEMO_NATIVE_CROP_UNSAFE === "1";
+
+/** Playwright browser channels the engine accepts for AIDEMO_CHROME_CHANNEL. */
+export const CHROME_CHANNELS = [
+  "chrome",
+  "chrome-beta",
+  "chrome-dev",
+  "chrome-canary",
+  "msedge",
+  "msedge-beta",
+  "msedge-dev",
+  "msedge-canary",
+  "chromium",
+] as const;
+export type ChromeChannel = (typeof CHROME_CHANNELS)[number];
+
+/**
+ * A browser-selection problem (bad AIDEMO_CHROME_CHANNEL, browser not
+ * installed) — already actionable, so callers rethrow it without adding
+ * unrelated hints (e.g. the recorder's profile-lock advice).
+ */
+export class BrowserSetupError extends Error {
+  override name = "BrowserSetupError";
+}
+
+/** Which browser binary every Playwright launch uses — spread into launch options. */
+export type ChromeLaunchTarget = { channel: ChromeChannel } | { executablePath: string };
+
+/**
+ * The browser every launch site uses (issue #80). Precedence:
+ *   1. AIDEMO_CHROME_EXECUTABLE — explicit binary path (`{ executablePath }`)
+ *   2. AIDEMO_CHROME_CHANNEL    — a Playwright channel (`{ channel }`), e.g.
+ *      `chromium` (Chrome for Testing — for managed Chrome that kills automated
+ *      sessions; needs `npx playwright install chromium`)
+ *   3. default `{ channel: "chrome" }` — system Google Chrome, exactly the
+ *      engine's historical launch options.
+ * Throws on an unknown channel name. Re-read on every call (env is live).
+ */
+export function chromeLaunchOptions(): ChromeLaunchTarget {
+  const exe = process.env.AIDEMO_CHROME_EXECUTABLE?.trim();
+  if (exe) return { executablePath: exe };
+  const raw = process.env.AIDEMO_CHROME_CHANNEL?.trim();
+  if (!raw) return { channel: "chrome" };
+  const channel = raw.toLowerCase();
+  if (!(CHROME_CHANNELS as readonly string[]).includes(channel)) {
+    throw new BrowserSetupError(
+      `AIDEMO_CHROME_CHANNEL="${raw}" is not a supported browser channel. ` +
+        `Use one of: ${CHROME_CHANNELS.join(", ")} — or set AIDEMO_CHROME_EXECUTABLE ` +
+        `to a Chromium-based browser binary instead.`
+    );
+  }
+  return { channel: channel as ChromeChannel };
+}