@tandryukha/aidemo 0.15.2 → 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

@@ -619,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
@@ -1217,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tandryukha/aidemo",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "license": "MIT",
   "description": "AI Demo Engine — turn a storyboard into a narrated, captioned product demo video",
   "type": "module",
@@ -28,12 +28,14 @@
     "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",

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/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/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 };
+}

package/src/cursor.ts

@@ -1,4 +1,4 @@
-import { chromium } from "playwright";
+import { launchChrome } from "./browser.js";
 
 /**
  * The classic arrow pointer, shared by both cursor render paths so they look
@@ -30,7 +30,7 @@ export async function renderCursorPng(
   // Logical canvas is 32 units (24 arrow + shadow headroom); scale to sizePx.
   const LOGICAL = 32;
   const dsf = Math.max(1, sizePx / LOGICAL);
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   const context = await browser.newContext({
     viewport: { width: LOGICAL, height: LOGICAL },
     deviceScaleFactor: dsf,

package/src/distribute.ts

@@ -17,7 +17,15 @@ import { resolve, dirname, basename } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { platform, release } from "node:os";
-import { ENGINE_ROOT, engineVersion, openAiBaseUrl, ttsProvider } from "./config.js";
+import {
+  ENGINE_ROOT,
+  engineVersion,
+  openAiBaseUrl,
+  ttsProvider,
+  chromeLaunchOptions,
+  type ChromeLaunchTarget,
+} from "./config.js";
+import { describeChromeTarget, probeConfiguredBrowser } from "./browser.js";
 import { localTtsStatus } from "./voice-local.js";
 import { Project } from "./project.js";
 import { STARTER_BRIEF, STARTER_STORYBOARD, briefFromInspect, storyboardFromInspect } from "./starter.js";
@@ -371,6 +379,43 @@ async function probeChrome(): Promise<string | null> {
   return null;
 }
 
+/** Resolve + probe the browser every launch uses (see chromeLaunchOptions). */
+async function probeBrowserTarget(chrome: string | null): Promise<DoctorReport["browser"]> {
+  let target: ChromeLaunchTarget;
+  try {
+    target = chromeLaunchOptions();
+  } catch (err) {
+    return {
+      source: "channel",
+      channel: process.env.AIDEMO_CHROME_CHANNEL,
+      description: `channel ${process.env.AIDEMO_CHROME_CHANNEL} (AIDEMO_CHROME_CHANNEL)`,
+      found: false,
+      error: (err as Error).message,
+    };
+  }
+  const description = describeChromeTarget(target);
+  const isDefault = "channel" in target && !process.env.AIDEMO_CHROME_CHANNEL?.trim();
+  if (isDefault) {
+    // Unchanged default: system Chrome, detected without launching it.
+    return {
+      source: "default",
+      channel: "chrome",
+      description,
+      found: Boolean(chrome),
+      ...(chrome ? { version: chrome } : { error: "Google Chrome not found" }),
+    };
+  }
+  const probe = await probeConfiguredBrowser();
+  return {
+    ...("executablePath" in target
+      ? { source: "executable" as const, executablePath: target.executablePath }
+      : { source: "channel" as const, channel: target.channel }),
+    description,
+    found: "version" in probe,
+    ...("version" in probe ? { version: probe.version } : { error: probe.error }),
+  };
+}
+
 /** Tail the most recent logs/*.log under a demo dir (best-effort). */
 async function recentLogTail(demoDir: string, lines = 40): Promise<string | null> {
   const logsDir = resolve(demoDir, "logs");
@@ -579,7 +624,24 @@ export interface DoctorReport {
   engineVersion: string;
   node: string;
   ffmpeg: string | null;
+  /** System Google Chrome (version or path) — what the default channel launches. */
   chrome: string | null;
+  /**
+   * The browser every launch will actually use (issue #80):
+   * AIDEMO_CHROME_EXECUTABLE > AIDEMO_CHROME_CHANNEL > default channel chrome.
+   */
+  browser: {
+    source: "default" | "channel" | "executable";
+    channel?: string;
+    executablePath?: string;
+    /** e.g. "channel chromium (AIDEMO_CHROME_CHANNEL)". */
+    description: string;
+    found: boolean;
+    /** Version / path when found. */
+    version?: string;
+    /** Actionable reason when not found (or the env var is invalid). */
+    error?: string;
+  };
   gh: string | null;
   endpoint: { url: string; custom: boolean; warning?: string };
   apiKey: "set" | "not-required" | "missing";
@@ -630,11 +692,14 @@ export async function doctorReport(dir: string | undefined): Promise<DoctorRepor
   const manifest = await readManifest(target);
   const latest = engineVersion();
   const localTts = ttsProvider() === "local" ? await localTtsStatus() : null;
+  const chrome = await probeChrome();
+  const browser = await probeBrowserTarget(chrome);
   const report: DoctorReport = {
     engineVersion: latest,
     node: process.version,
     ffmpeg: await probeCmd("ffmpeg", ["-version"]),
-    chrome: await probeChrome(),
+    chrome,
+    browser,
     gh: await probeCmd("gh", ["--version"]),
     endpoint: {
       url: base ?? "https://api.openai.com/v1",
@@ -674,7 +739,7 @@ export async function doctorReport(dir: string | undefined): Promise<DoctorRepor
   };
   report.ok = Boolean(
     report.ffmpeg &&
-      report.chrome &&
+      report.browser.found &&
       report.playwright &&
       // Local TTS needs no key: voice is in-process, captions auto-fall-back
       // to the offline derivation in `render`.
@@ -695,7 +760,14 @@ export async function doctor(dir: string | undefined): Promise<void> {
 
   line("node", r.node);
   line("ffmpeg", r.ffmpeg);
-  line("chrome", r.chrome);
+  if (r.browser.source === "default") {
+    line("chrome", r.chrome);
+    ok(`browser: ${r.browser.description}`);
+  } else {
+    if (r.browser.found) ok(`browser: ${r.browser.description} — ${r.browser.version}`);
+    else fail(`browser: ${r.browser.description} — ${r.browser.error ?? "NOT FOUND"}`);
+    log(`system chrome (unused): ${r.chrome ?? "not found"}`);
+  }
   line("gh (feedback)", r.gh);
   ok(
     `voice/captions endpoint: ${r.endpoint.custom ? `${r.endpoint.url} (custom)` : "api.openai.com (default)"}`

package/src/ffmpeg.ts

@@ -83,43 +83,56 @@ export function probeDurationMs(file: string): Promise<number> {
 }
 
 /**
- * Length (ms) of the *flat* tail of a video — the trailing run of frames that
- * are a single solid color.
+ * Thresholds for "this frame shows nothing" — a blank pre-paint, a solid
+ * splash — as opposed to a page whose content is merely sparse (issue #78: a
+ * dark terminal with one prompt line). A frame is blank only when BOTH hold:
  *
- * Compose freeze-holds a scene's last frame when the narration outruns the
- * recorded action. When the scene ends right before a `goto`, that last frame
- * is the browser's white pre-paint, and the hold clones *white* for as long as
- * the narration runs (issue #36: 37 near-blank seconds out of 209). Trimming
- * the flat tail first makes the hold clone the last frame that actually shows
- * the app.
+ * 1. `FLAT_SPREAD` — `YHIGH - YLOW` from `signalstats` (luma 90th minus 10th
+ *    percentile) is at most 4: one colour covers ≥ 80% of the frame.
+ *    Percentiles, not min/max, so a cursor arrow or a stray antialiased pixel
+ *    doesn't read as content; `YDEV` would be the natural measure but many
+ *    ffmpeg builds don't emit it. On its own this is NOT a blank test: sparse
+ *    text never reaches the 10%/90% tails, so a terminal prompt (or a login
+ *    box on a big solid background) measured exactly like a white page.
+ * 2. `BLANK_EDGE_PX` — `edgedetect` (Canny, binary 0/255 output) +
+ *    `signalstats` YAVG gives the fraction of edge pixels; times the frame
+ *    area and divided by the device-pixel scale, that is the length of
+ *    visible outlines in CSS px. Glyphs are all outline, so this counts text
+ *    the percentiles miss. Measured (Chrome screenshots → x264 crf 20, at
+ *    1280x720@1x, 1920x1080@1x, 1280x720@2x): the engine's 24 px cursor over
+ *    white/grey/black ≈ 54–142; a blank page 0; `user@box:~$ ▌` 14 px on
+ *    black ≈ 288–522; `root@ttyd:~# ▌` 16 px ≈ 447–630; a heading + one
+ *    sentence ≈ 1210–1560. 200 sits between the cursor and a one-line prompt
+ *    with ~1.4x margin each side. Below it — a lone `$ ▌` (≈ 75–150), a bare
+ *    32 px spinner (≈ 115–135) — still counts as blank, which for an opening
+ *    frame is what a viewer sees too.
  *
- * Flatness is `YHIGH - YLOW` from `signalstats` — the spread between the luma
- * 90th and 10th percentiles. Percentiles rather than min/max so a cursor arrow
- * or a stray antialiased pixel doesn't make a blank page look like content;
- * `YDEV` would be the natural measure but many ffmpeg builds don't emit it.
- *
- * Scans at most `windowMs` from the end; returns 0 when the tail has real
- * content, or when the probe fails for any reason (best-effort polish, never a
- * reason to fail a compose).
+ * Both filters are core libavfilter (no external libs), like the
+ * `freezedetect`/`signalstats` probes already used here.
  */
-export function probeFlatTailMs(
+const FLAT_SPREAD = 4;
+const BLANK_EDGE_PX = 200;
+const EDGE_FILTER = "edgedetect=low=0.1:high=0.3";
+
+/** Per-frame stats from one `signalstats,metadata=print` pass, in frame order. */
+function signalstatsFrames(
   file: string,
-  durMs: number,
-  windowMs = 4000
-): Promise<number> {
-  const start = Math.max(0, durMs - windowMs) / 1000;
+  vf: string,
+  ss: number,
+  durSec: number | null
+): Promise<Array<Record<string, number>> | null> {
   return new Promise((resolvePromise) => {
     const proc = spawn(
       "ffmpeg",
       [
         "-hide_banner",
         "-nostats",
-        "-ss",
-        start.toFixed(3),
+        ...(ss > 0 ? ["-ss", ss.toFixed(3)] : []),
         "-i",
         file,
+        ...(durSec != null ? ["-t", durSec.toFixed(3)] : []),
         "-vf",
-        "signalstats,metadata=print:file=-",
+        `${vf}signalstats,metadata=print:file=-`,
         "-f",
         "null",
         "-",
@@ -128,115 +141,155 @@ export function probeFlatTailMs(
     );
     let out = "";
     proc.stdout.on("data", (d) => (out += d.toString()));
-    proc.on("error", () => resolvePromise(0));
-    proc.on("close", () => {
+    proc.on("error", () => resolvePromise(null));
+    proc.on("close", (code) => {
+      if (code !== 0) return resolvePromise(null);
       // The metadata muxer emits a header line per frame followed by one line
       // per key:
       //   frame:12  pts:...  pts_time:0.4
       //   lavfi.signalstats.YLOW=16
       //   ...
-      const frames: Array<{ t: number; spread: number }> = [];
-      let t = NaN;
-      let low = NaN;
-      let high = NaN;
-      const flush = (): void => {
-        if (!Number.isNaN(t) && !Number.isNaN(low) && !Number.isNaN(high)) {
-          frames.push({ t, spread: high - low });
-        }
-        low = NaN;
-        high = NaN;
-      };
+      const frames: Array<Record<string, number>> = [];
+      let cur: Record<string, number> | null = null;
       for (const line of out.split("\n")) {
-        const ts = /pts_time:\s*([\d.]+)/.exec(line);
+        const ts = /pts_time:\s*(-?[\d.]+)/.exec(line);
         if (ts) {
-          flush();
-          t = parseFloat(ts[1]);
+          cur = { t: parseFloat(ts[1]) };
+          frames.push(cur);
           continue;
         }
-        const lo = /YLOW=\s*([\d.]+)/.exec(line);
-        if (lo) low = parseFloat(lo[1]);
-        const hi = /YHIGH=\s*([\d.]+)/.exec(line);
-        if (hi) high = parseFloat(hi[1]);
+        const kv = /lavfi\.signalstats\.(\w+)=\s*(-?[\d.e+-]+)/.exec(line);
+        if (kv && cur) cur[kv[1]] = parseFloat(kv[2]);
       }
-      flush();
-      if (frames.length === 0) return resolvePromise(0);
-      // Walk back while frames stay flat. A real page — even a mostly-empty
-      // one — has chrome, text and edges, so its spread is far above this.
-      const FLAT_SPREAD = 4;
-      let i = frames.length - 1;
-      if (frames[i].spread > FLAT_SPREAD) return resolvePromise(0);
-      while (i > 0 && frames[i - 1].spread <= FLAT_SPREAD) i--;
-      resolvePromise(Math.max(0, Math.round(durMs - (start + frames[i].t) * 1000)));
+      resolvePromise(frames);
     });
   });
 }
 
+/** Luma flatness per frame of a window; `t` is absolute seconds in `file`. */
+async function flatFrames(
+  file: string,
+  ss: number,
+  durSec: number | null
+): Promise<Array<{ t: number; flat: boolean }> | null> {
+  const frames = await signalstatsFrames(file, "", ss, durSec);
+  if (!frames) return null;
+  const out: Array<{ t: number; flat: boolean }> = [];
+  for (const f of frames) {
+    if (f.YLOW == null || f.YHIGH == null) return null;
+    out.push({ t: ss + f.t, flat: f.YHIGH - f.YLOW <= FLAT_SPREAD });
+  }
+  return out;
+}
+
 /**
- * Mirror of `probeFlatTailMs` for the HEAD of a file: how many ms at the start
- * are a flat, contentless frame (the browser's white pre-paint after a `goto`).
- * Used to open the video on the product instead of on a blank page, and to pick
- * a poster frame that isn't a white rectangle (issue #47). Best-effort: any
- * probe failure resolves to 0.
+ * Which frames of a contiguous run of flat frames (absolute times, in order)
+ * are also free of outlines — i.e. truly blank. The edge pass is the costly
+ * one (Canny on every full-size frame), so it runs only over this run, never
+ * over a window whose frames already differ. A frame the second pass can't be
+ * matched to counts as content: a probe hiccup must never cause a trim.
  */
-export function probeFlatLeadMs(
+async function blankInRun(
   file: string,
+  run: Array<{ t: number }>,
+  pxScale: number
+): Promise<boolean[] | null> {
+  const step =
+    run.length > 1 ? (run[run.length - 1].t - run[0].t) / (run.length - 1) : 1 / 30;
+  const half = Math.max(step / 2, 0.001);
+  // Seek half a frame early: `-ss` is rounded to ms, and an accurate seek
+  // drops a frame whose pts lands a hair before it.
+  const ss = Math.max(0, run[0].t - half);
+  const [dims, edges] = await Promise.all([
+    probeVideoDims(file).catch(() => null),
+    signalstatsFrames(file, `${EDGE_FILTER},`, ss, run[run.length - 1].t - ss + step),
+  ]);
+  if (!dims || !edges) return null;
+  const area = dims.width * dims.height;
+  const scale = pxScale > 0 ? pxScale : 1;
+  const samples = edges
+    .filter((e) => e.YAVG != null)
+    .map((e) => ({ t: ss + e.t, px: ((e.YAVG / 255) * area) / scale }));
+  let j = 0;
+  return run.map((f) => {
+    while (
+      j + 1 < samples.length &&
+      Math.abs(samples[j + 1].t - f.t) <= Math.abs(samples[j].t - f.t)
+    ) {
+      j++;
+    }
+    const s = samples[j];
+    return !!s && Math.abs(s.t - f.t) <= half && s.px < BLANK_EDGE_PX;
+  });
+}
+
+/**
+ * Length (ms) of the *blank* tail of a video — the trailing run of frames
+ * that show nothing (one solid colour and no text or outlines; see
+ * `FLAT_SPREAD` / `BLANK_EDGE_PX`).
+ *
+ * Compose freeze-holds a scene's last frame when the narration outruns the
+ * recorded action. When the scene ends right before a `goto`, that last frame
+ * is the browser's white pre-paint, and the hold clones *white* for as long as
+ * the narration runs (issue #36: 37 near-blank seconds out of 209). Trimming
+ * the blank tail first makes the hold clone the last frame that actually shows
+ * the app. A sparse-but-real page (a terminal prompt on a dark background) is
+ * not blank, so its tail is never dropped (issue #78).
+ *
+ * `pxScale` is device px per CSS px (output width / `video.width`), so the
+ * edge threshold means the same on a 1x and a 2x take. Scans at most
+ * `windowMs` from the end; returns 0 when the tail has real content, or when
+ * the probe fails for any reason (best-effort polish, never a reason to fail a
+ * compose).
+ */
+export async function probeFlatTailMs(
+  file: string,
+  durMs: number,
   windowMs = 4000,
-  startMs = 0
+  pxScale = 1
 ): Promise<number> {
-  return new Promise((resolvePromise) => {
-    const proc = spawn(
-      "ffmpeg",
-      [
-        "-hide_banner",
-        "-nostats",
-        ...(startMs > 0 ? ["-ss", (startMs / 1000).toFixed(3)] : []),
-        "-i",
-        file,
-        "-t",
-        (windowMs / 1000).toFixed(3),
-        "-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(0));
-    proc.on("close", () => {
-      const frames: Array<{ t: number; spread: number }> = [];
-      let t = NaN;
-      let low = NaN;
-      let high = NaN;
-      const flush = (): void => {
-        if (!Number.isNaN(t) && !Number.isNaN(low) && !Number.isNaN(high)) {
-          frames.push({ t, spread: high - low });
-        }
-        low = NaN;
-        high = NaN;
-      };
-      for (const line of out.split("\n")) {
-        const ts = /pts_time:\s*([\d.]+)/.exec(line);
-        if (ts) {
-          flush();
-          t = parseFloat(ts[1]);
-          continue;
-        }
-        const lo = /YLOW=\s*([\d.]+)/.exec(line);
-        if (lo) low = parseFloat(lo[1]);
-        const hi = /YHIGH=\s*([\d.]+)/.exec(line);
-        if (hi) high = parseFloat(hi[1]);
-      }
-      flush();
-      const FLAT_SPREAD = 4;
-      if (!frames.length || frames[0].spread > FLAT_SPREAD) return resolvePromise(0);
-      let i = 0;
-      while (i + 1 < frames.length && frames[i + 1].spread <= FLAT_SPREAD) i++;
-      resolvePromise(Math.max(0, Math.round(frames[i].t * 1000)));
-    });
-  });
+  const start = Math.max(0, durMs - windowMs) / 1000;
+  const frames = await flatFrames(file, start, null);
+  if (!frames || !frames.length || !frames[frames.length - 1].flat) return 0;
+  let i = frames.length - 1;
+  while (i > 0 && frames[i - 1].flat) i--;
+  const run = frames.slice(i);
+  // A static page (a terminal) is one long flat run: settle it on the last
+  // frame alone before paying for the whole run.
+  if (!(await blankInRun(file, run.slice(-1), pxScale))?.[0]) return 0;
+  const blank = await blankInRun(file, run, pxScale);
+  if (!blank || !blank[blank.length - 1]) return 0;
+  let k = blank.length - 1;
+  while (k > 0 && blank[k - 1]) k--;
+  return Math.max(0, Math.round(durMs - run[k].t * 1000));
+}
+
+/**
+ * Mirror of `probeFlatTailMs` for the HEAD of a file: how many ms after
+ * `startMs` are blank frames (the browser's white pre-paint after a `goto`, a
+ * solid splash). Used to open the video on the product instead of on a blank
+ * page, and to pick a poster frame that isn't a white rectangle (issue #47). A
+ * static but populated opening — a dark terminal with a prompt — is content,
+ * not blank (issue #78). Best-effort: any probe failure resolves to 0.
+ */
+export async function probeFlatLeadMs(
+  file: string,
+  windowMs = 4000,
+  startMs = 0,
+  pxScale = 1
+): Promise<number> {
+  const start = startMs / 1000;
+  const frames = await flatFrames(file, start, windowMs / 1000);
+  if (!frames || !frames.length || !frames[0].flat) return 0;
+  let i = 0;
+  while (i + 1 < frames.length && frames[i + 1].flat) i++;
+  const run = frames.slice(0, i + 1);
+  if (!(await blankInRun(file, run.slice(0, 1), pxScale))?.[0]) return 0;
+  const blank = await blankInRun(file, run, pxScale);
+  if (!blank || !blank[0]) return 0;
+  let k = 0;
+  while (k + 1 < blank.length && blank[k + 1]) k++;
+  return Math.max(0, Math.round((run[k].t - start) * 1000));
 }
 
 /** A motionless span found by `freezedetect`, in ms from the file's start. */

package/src/frame.ts

@@ -7,7 +7,7 @@
  * overlays that PNG. Two baseline filters (`pad`, `overlay`), no drawbox.
  */
 
-import { chromium } from "playwright";
+import { launchChrome } from "./browser.js";
 import type { Brand, Frame } from "./types.js";
 
 export interface FrameLayout {
@@ -189,7 +189,7 @@ export async function renderFramePng(
     <div class="canvas">${device ? '<div class="bezel"></div>' : ""}<div class="win"></div>${chromeHtml}</div>${deviceHtml}
   </body></html>`;
 
-  const browser = await chromium.launch({ channel: "chrome", headless: true });
+  const browser = await launchChrome({ headless: true });
   const context = await browser.newContext({
     viewport: { width: W, height: H },
     deviceScaleFactor: pxScale,

package/src/inspect.ts

@@ -10,7 +10,8 @@
  * fix a selector from the failure artifact instead of guessing.
  */
 
-import { chromium, type Frame, type Page } from "playwright";
+import type { Frame, Page } from "playwright";
+import { launchChromePersistent } from "./browser.js";
 import { chromeProfileDir } from "./config.js";
 import { ensureProfileUnlocked } from "./login.js";
 import { applySeeds, type Seeds } from "./setup.js";
@@ -219,8 +220,7 @@ export async function inspectPage(opts: InspectOptions): Promise<InspectResult>
   const profileDir = opts.profileDir ?? chromeProfileDir();
   await ensureProfileUnlocked(profileDir);
   const viewport = opts.viewport ?? { width: 1280, height: 720 };
-  const context = await chromium.launchPersistentContext(profileDir, {
-    channel: "chrome",
+  const context = await launchChromePersistent(profileDir, {
     headless: opts.headless !== false,
     args: ["--disable-blink-features=AutomationControlled"],
     viewport,

package/src/login.ts

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import { join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { chromeProfileDir } from "./config.js";
+import { manualLaunchBinary } from "./browser.js";
 import { ensureDir, log, ok, step, sleep } from "./util.js";
 
 /**
@@ -98,13 +99,16 @@ export async function login(profileDir?: string, opts: LoginOptions = {}): Promi
       "--no-default-browser-check",
       url,
     ];
-    if (process.platform === "darwin") {
+    // AIDEMO_CHROME_EXECUTABLE / AIDEMO_CHROME_CHANNEL=chromium: log in with
+    // the SAME browser the recorder will launch (issue #80).
+    const configured = manualLaunchBinary();
+    if (process.platform === "darwin" && !configured) {
       spawn("open", ["-na", "Google Chrome", "--args", ...args], {
         stdio: "ignore",
         detached: true,
       }).unref();
     } else {
-      const bin = process.env.CHROME_BIN || "google-chrome";
+      const bin = configured || process.env.CHROME_BIN || "google-chrome";
       const child = spawn(bin, args, { stdio: "ignore", detached: true });
       child.on("error", () => {
         log(`could not launch "${bin}" (set CHROME_BIN) — open Chrome yourself with:`);

package/src/mcp/server.ts

@@ -4,7 +4,13 @@ import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { ENGINE_ROOT, engineVersion, captionsAutoOffline, chromeProfileDir } from "../config.js";
+import {
+  ENGINE_ROOT,
+  engineVersion,
+  captionsAutoOffline,
+  chromeProfileDir,
+  applyProjectEnv,
+} from "../config.js";
 import { Project, parseStoryboard } from "../project.js";
 import { StoryboardSchema, SeedCookieSchema, type SeedCookie, type Storyboard } from "../types.js";
 import { generateVoice } from "../voice.js";
@@ -498,6 +504,8 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
       },
     },
     async (args) => {
+      // fromUrl launches Chrome: honour the target repo's .env (#77).
+      if (args.dir && !jobs.running()) await applyProjectEnv(args.dir);
       const demoDir = await scaffoldDemo(
         args.dir ? resolve(args.dir) : process.cwd(),
         args.name,
@@ -523,7 +531,8 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
     {
       title: "Environment preflight",
       description:
-        "Check prereqs: node, ffmpeg, Chrome, TTS/STT endpoint (flags " +
+        "Check prereqs: node, ffmpeg, Chrome (or the AIDEMO_CHROME_CHANNEL / " +
+        "AIDEMO_CHROME_EXECUTABLE browser in use), TTS/STT endpoint (flags " +
         "LLM-only servers like Ollama), API key, playwright, installed skill.",
       inputSchema: {
         dir: z.string().optional().describe("repo to check for an installed skill"),
@@ -533,6 +542,15 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         node: z.string(),
         ffmpeg: z.string().nullable(),
         chrome: z.string().nullable(),
+        browser: z.object({
+          source: z.enum(["default", "channel", "executable"]),
+          channel: z.string().optional(),
+          executablePath: z.string().optional(),
+          description: z.string(),
+          found: z.boolean(),
+          version: z.string().optional(),
+          error: z.string().optional(),
+        }),
         gh: z.string().nullable(),
         endpoint: z.object({
           url: z.string(),
@@ -558,10 +576,13 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
       },
       annotations: { readOnlyHint: true },
     },
-    async (args) =>
-      jsonResult(
+    async (args) => {
+      // Report the env the pipeline would actually run with for this repo (#77).
+      if (args.dir && !jobs.running()) await applyProjectEnv(args.dir);
+      return jsonResult(
         (await doctorReport(args.dir)) as unknown as Record<string, unknown>
-      )
+      );
+    }
   );
 
   server.registerTool(
@@ -788,6 +809,9 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
       (async (args: z.infer<z.ZodObject<Shape>>) => {
         const project = new Project((args as { dir: string }).dir);
         await project.ensureDirs();
+        // The demo's own .env, as the CLI run from its repo would see it
+        // (#77). Never swapped under a running job — startJob rejects anyway.
+        if (!jobs.running()) await applyProjectEnv(project.dir);
         try {
           const job = jobs.startJob(kind, project, makeRunner(project, args));
           return jsonResult({

package/src/qa.ts

@@ -14,10 +14,12 @@
 
 import { spawn } from "node:child_process";
 import { relative } from "node:path";
+import { stat } from "node:fs/promises";
 import type { Project } from "./project.js";
 import {
   probeDurationMs,
   probeFlatLeadMs,
+  probeVideoDims,
 } from "./ffmpeg.js";
 import { ComposeReportSchema, type Storyboard } from "./types.js";
 import { exists, log, ok, readJson } from "./util.js";
@@ -105,6 +107,24 @@ function imageYavg(file: string): Promise<number | null> {
   });
 }
 
+/**
+ * `blankOpenMs` from the compose report that belongs to `video` (written at or
+ * after it), or null when there is no such report.
+ */
+async function reportedBlankOpenMs(project: Project, video: string): Promise<number | null> {
+  if (!(await exists(project.reportPath))) return null;
+  try {
+    const [rs, vs] = await Promise.all([stat(project.reportPath), stat(video)]);
+    if (rs.mtimeMs < vs.mtimeMs) return null;
+    const report = ComposeReportSchema.safeParse(await readJson(project.reportPath));
+    return report.success && typeof report.data.blankOpenMs === "number"
+      ? report.data.blankOpenMs
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Host of a URL-ish string, or null. */
 function hostOf(url: string): string | null {
   try {
@@ -137,8 +157,17 @@ export async function runQa(project: Project, storyboard: Storyboard): Promise<Q
   }
 
   // 2. The opening frames: a demo that starts on the browser's white pre-paint.
+  // Prefer compose's own measurement (report.json `blankOpenMs`): it is taken
+  // on the page footage before captions are burned in, and the finished MP4
+  // can't tell a caption pill over a blank page from sparse real content
+  // (issue #78). Fall back to probing the MP4 when there's no report for it.
   const introMs = storyboard.intro?.durationMs ?? 0;
-  const blankMs = await probeFlatLeadMs(video, 4000, introMs).catch(() => 0);
+  let blankMs = await reportedBlankOpenMs(project, video);
+  if (blankMs == null) {
+    const dims = await probeVideoDims(video).catch(() => null);
+    const pxScale = dims ? dims.width / storyboard.video.width : 1;
+    blankMs = await probeFlatLeadMs(video, 4000, introMs, pxScale).catch(() => 0);
+  }
   if (blankMs > 250) {
     add(
       "blank-open",

package/src/recorder.ts

@@ -1,4 +1,4 @@
-import { chromium } from "playwright";
+import { describeChromeTarget, launchChromePersistent } from "./browser.js";
 import { promises as fs } from "node:fs";
 import {
   TimelineSchema,
@@ -18,6 +18,8 @@ import {
   captureDevice,
   obsUrl,
   obsPassword,
+  BrowserSetupError,
+  chromeLaunchOptions,
 } from "./config.js";
 import {
   type CaptureMode,
@@ -169,6 +171,11 @@ export async function record(
   // error); clean up a stale lock from a crashed Chrome.
   await ensureProfileUnlocked(profileDir);
   log(`profile: ${profileDir}${options.fresh ? " (fresh)" : ""}`);
+  // Non-default browser (issue #80): resolve it now — a bad
+  // AIDEMO_CHROME_CHANNEL fails here, before any preflight hook runs.
+  if (process.env.AIDEMO_CHROME_EXECUTABLE?.trim() || process.env.AIDEMO_CHROME_CHANNEL?.trim()) {
+    log(`browser: ${describeChromeTarget(chromeLaunchOptions())}`);
+  }
 
   // Preflight hook (issue #44): runs before Chrome launches, with the resolved
   // profile in its env. It may rewrite the storyboard (a rotating fixture), so
@@ -311,8 +318,7 @@ export async function record(
 
   let context;
   try {
-    context = await chromium.launchPersistentContext(profileDir, {
-      channel: "chrome",
+    context = await launchChromePersistent(profileDir, {
       headless: options.headed === false,
       // Hide the automation fingerprint (navigator.webdriver=false) so
       // Cloudflare on chatgpt.com doesn't throw a "Verify you are human"
@@ -345,6 +351,8 @@ export async function record(
           }),
     });
   } catch (err) {
+    // Wrong/missing browser (issue #80) is already actionable on its own.
+    if (err instanceof BrowserSetupError) throw err;
     throw new Error(
       `Failed to launch Chrome with profile ${profileDir}.\n` +
         `If Chrome is already open on this profile, quit it first (Playwright ` +

package/src/types.ts

@@ -842,8 +842,10 @@ export const OutputSchema = z
     /**
      * Drop the browser's blank pre-paint at the very start of the video, so
      * the demo opens on the product instead of on ~0.5 s of white under the
-     * first caption (issue #47). At most `blankOpenCapMs` of the leading flat
-     * span is kept. Default false (unchanged opening).
+     * first caption (issue #47). At most `blankOpenCapMs` of the leading blank
+     * span is kept. Blank = empty (one colour, no text/outlines), not merely
+     * static: a motionless terminal or page is never trimmed (issue #78).
+     * Default false (unchanged opening).
      */
     trimLeadingBlank: z.boolean().optional(),
     /** With `trimLeadingBlank`: leading blank kept, ms. Default 100. */