@kadj-amoah/showrunner 1.1.0 → 1.1.2

package/dist/cli.js

@@ -687,7 +687,7 @@ var HEADER = `// scripts/playwright_demo.ts
 function renderPlaywrightSpec(inputs) {
   const { manifest, recording, targetUrl, videoDir, traceDir } = inputs;
   const launchLines = [
-    `import { chromium, firefox, webkit, expect, type BrowserContext } from 'playwright';`,
+    `import { chromium, firefox, webkit, type BrowserContext } from 'playwright-core';`,
     `import { mkdirSync } from 'node:fs';`,
     ``,
     `const VIDEO_DIR = ${JSON.stringify(videoDir)};`,
@@ -774,7 +774,7 @@ function renderAction(action) {
     case "wait":
       return `await page.waitForTimeout(${action.ms});`;
     case "assert_visible":
-      return `await expect(page.locator(${JSON.stringify(flattenSelector(action.selector))}).first()).toBeVisible();`;
+      return `await page.locator(${JSON.stringify(flattenSelector(action.selector))}).first().waitFor({ state: 'visible' });`;
     case "press":
       return action.selector ? `await page.locator(${JSON.stringify(flattenSelector(action.selector))}).first().press(${JSON.stringify(action.key)});` : `await page.keyboard.press(${JSON.stringify(action.key)});`;
     case "custom":
@@ -1229,7 +1229,7 @@ async function generateManifest(opts) {
 }
 
 // src/scriptGen/domPreflight.ts
-import { chromium, firefox, webkit } from "playwright";
+import { chromium, firefox, webkit } from "playwright-core";
 
 // src/recording/selectorHeuristic.ts
 var SELECTOR_FOR_FN_SOURCE = `
@@ -1318,7 +1318,7 @@ async function scrapeSelectorInventory(opts) {
     try {
       await page.waitForLoadState("networkidle", { timeout: networkIdleMs });
     } catch {
-      logger.debug("domPreflight: networkidle did not fire within budget \u2014 proceeding");
+      logger.debug("domPreflight: networkidle did not fire within budget \xE2\u20AC\u201D proceeding");
     }
     const items = await page.evaluate(
       buildScrapeScript(SELECTOR_FOR_FN_SOURCE, maxItems)
@@ -2219,7 +2219,7 @@ import {
   chromium as chromium2,
   firefox as firefox2,
   webkit as webkit2
-} from "playwright";
+} from "playwright-core";
 
 // src/manifest/alignment.ts
 import { readFile as readFile6 } from "fs/promises";
@@ -2330,7 +2330,7 @@ async function buildStorageState(cookiesFile, localStorageFile, configDir) {
         cookiesJson.origins = [...cookiesJson.origins ?? [], ...lsJson];
       } else {
         logger.warn(
-          `local_storage_file at ${lsAbs} is not a Playwright origins list \u2014 skipping. Use storageState() output format.`
+          `local_storage_file at ${lsAbs} is not a Playwright origins list \xE2\u20AC\u201D skipping. Use storageState() output format.`
         );
       }
     } catch (err) {
@@ -2371,7 +2371,7 @@ function buildFormFill(auth) {
     } catch (err) {
       const cause = err instanceof Error ? err.message : String(err);
       throw new AuthError(
-        `Form auth: did not reach ${auth.success_url_pattern} within ${auth.timeout_ms}ms \u2014 ${cause}`
+        `Form auth: did not reach ${auth.success_url_pattern} within ${auth.timeout_ms}ms \xE2\u20AC\u201D ${cause}`
       );
     }
   };
@@ -2380,7 +2380,7 @@ function buildFormFill(auth) {
 // src/recording/actions.ts
 import { mkdir as mkdir5 } from "fs/promises";
 import { dirname as dirname5, join as join2 } from "path";
-import { errors as playwrightErrors } from "playwright";
+import { errors as playwrightErrors } from "playwright-core";
 
 // src/recording/cursorOverlay.ts
 var CURSOR_INIT_SCRIPT = `
@@ -2454,7 +2454,7 @@ var CURSOR_INIT_SCRIPT = `
 
   if (tryInstall()) return;
 
-  console.log('[showrunner-cursor] deferring \u2014 body not ready');
+  console.log('[showrunner-cursor] deferring \xE2\u20AC\u201D body not ready');
 
   const tick = () => { if (tryInstall()) cleanup(); };
   const observer = new MutationObserver(tick);
@@ -2738,7 +2738,7 @@ async function recordDemo(opts) {
     const tFirstSegmentStart = performance.now();
     const preSegmentOffsetSec = (tFirstSegmentStart - tRecordingStart) / 1e3;
     logger.info(
-      `pre-segment recording offset: ${preSegmentOffsetSec.toFixed(2)}s (page.goto + setup) \u2014 slice_plan will be offset by this amount`
+      `pre-segment recording offset: ${preSegmentOffsetSec.toFixed(2)}s (page.goto + setup) \xE2\u20AC\u201D slice_plan will be offset by this amount`
     );
     const t0 = tFirstSegmentStart;
     let cursorPos = {
@@ -2817,7 +2817,7 @@ async function recordDemo(opts) {
               );
               if (adjusted < motionMs) {
                 warnings.push(
-                  `cursor motion for action at ${arrivalAt}s clamped from ${Math.round(motionMs)}ms to ${adjusted}ms \u2014 manifest timing tight`
+                  `cursor motion for action at ${arrivalAt}s clamped from ${Math.round(motionMs)}ms to ${adjusted}ms \xE2\u20AC\u201D manifest timing tight`
                 );
               }
               motionMs = adjusted;
@@ -2865,14 +2865,14 @@ async function recordDemo(opts) {
         if (outcome.status === "skipped") {
           warnings.push(`${action.type}: ${outcome.reason}`);
           if (outcome.screenshot) failureScreenshots.push(outcome.screenshot);
-          logger.warn(`segment ${seg.id} \u2014 ${action.type} skipped`, {
+          logger.warn(`segment ${seg.id} \xE2\u20AC\u201D ${action.type} skipped`, {
             reason: outcome.reason,
             screenshot: outcome.screenshot
           });
         } else if (outcome.status === "segment_failed") {
           failure = outcome.reason;
           if (outcome.screenshot) failureScreenshots.push(outcome.screenshot);
-          logger.error(`segment ${seg.id} \u2014 failed`, {
+          logger.error(`segment ${seg.id} \xE2\u20AC\u201D failed`, {
             reason: outcome.reason,
             screenshot: outcome.screenshot
           });
@@ -2889,7 +2889,7 @@ async function recordDemo(opts) {
         await page.waitForTimeout(Math.round(remaining * 1e3));
       } else if (remaining < -0.5) {
         warnings.push(
-          `segment took ${elapsedInSegment.toFixed(2)}s but only ${allocated.toFixed(2)}s allocated \u2014 manifest timing tight for this segment`
+          `segment took ${elapsedInSegment.toFixed(2)}s but only ${allocated.toFixed(2)}s allocated \xE2\u20AC\u201D manifest timing tight for this segment`
         );
       }
       const segEnd = (performance.now() - t0) / 1e3;
@@ -2924,7 +2924,7 @@ async function recordDemo(opts) {
       }
       recordingPath = dest;
     } else {
-      logger.warn("Recording context did not produce a video file \u2014 recordVideo may have been ignored");
+      logger.warn("Recording context did not produce a video file \xE2\u20AC\u201D recordVideo may have been ignored");
     }
     return {
       recording_path: recordingPath,
@@ -2958,10 +2958,10 @@ async function resolveStorageState(browser, recording, authPlan) {
 var PreflightError = class extends Error {
   constructor(failures) {
     const lines = failures.map(
-      (f) => `  - ${f.segment}#${f.actionIndex} \u2192 [${f.selectors.join(" | ")}]`
+      (f) => `  - ${f.segment}#${f.actionIndex} \xE2\u2020\u2019 [${f.selectors.join(" | ")}]`
     );
     super(
-      `Pre-flight check failed \u2014 ${failures.length} selector(s) did not resolve on ${failures[0]?.segment ? `the live target page` : "the page"}:
+      `Pre-flight check failed \xE2\u20AC\u201D ${failures.length} selector(s) did not resolve on ${failures[0]?.segment ? `the live target page` : "the page"}:
 ${lines.join("\n")}
 
 Fix the manifest selectors, or set recording.preflight: false to skip this check.`
@@ -5013,6 +5013,16 @@ function resolveMaybe(p, configDir) {
 var STAGE_NAMES = ["comprehension", "script", "voiceover", "record", "mux"];
 
 // src/pipeline/run.ts
+var PipelineStageError = class extends Error {
+  constructor(stage, message, cause) {
+    super(message);
+    this.stage = stage;
+    this.cause = cause;
+  }
+  stage;
+  cause;
+  name = "PipelineStageError";
+};
 var STAGES_BY_NAME = {
   comprehension: comprehensionStage,
   script: scriptStage,
@@ -5052,7 +5062,14 @@ async function run(loaded, options = {}) {
       continue;
     }
     const stage = STAGES_BY_NAME[name];
-    const result = await stage.run(ctx);
+    let result;
+    try {
+      result = await stage.run(ctx);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.event({ stage: name, status: "failed", error: message });
+      throw new PipelineStageError(name, message, err);
+    }
     results.push(result);
     logger.event({
       stage: name,
@@ -5117,10 +5134,11 @@ async function writeBuildManifest(path, payload) {
 
 // src/commands/doctor.ts
 import { spawn as spawn3 } from "child_process";
-import { stat as stat9, access, constants } from "fs/promises";
-import { isAbsolute as isAbsolute7, resolve as resolve13, dirname as dirname9 } from "path";
+import { stat as stat9, access, constants, readdir } from "fs/promises";
+import { isAbsolute as isAbsolute7, resolve as resolve13, dirname as dirname9, join as join9 } from "path";
+import { homedir, platform as osPlatform } from "os";
 import { request as undiciRequest } from "undici";
-import { chromium as chromium3, firefox as firefox3, webkit as webkit3 } from "playwright";
+import { chromium as chromium3, firefox as firefox3, webkit as webkit3 } from "playwright-core";
 
 // src/config/providerEnv.ts
 function inspectProviderEnv(config) {
@@ -5188,6 +5206,7 @@ async function doctorCommand(opts) {
     for (const r of results) printRow(r);
     const summary = summarize(results);
     if (summary.fail > 0) {
+      printFixOrder(results);
       logger.error(`doctor: ${summary.fail} FAIL, ${summary.warn} WARN, ${summary.pass} PASS`);
     } else if (summary.warn > 0) {
       logger.warn(`doctor: ${summary.warn} WARN, ${summary.pass} PASS`);
@@ -5213,10 +5232,18 @@ async function runDoctorChecks(configPath) {
   const { config, configDir } = loaded;
   for (const row of inspectProviderEnv(config)) {
     const suffix = row.stage ? ` (${row.stage} override)` : "";
-    results.push({
-      status: row.set ? "PASS" : "FAIL",
-      label: `${row.slot} provider=${row.provider}${suffix}, ${row.envVar} ${row.set ? "set" : "NOT set"}`
-    });
+    if (row.set) {
+      results.push({
+        status: "PASS",
+        label: `${row.slot} provider=${row.provider}${suffix}, ${row.envVar} set`
+      });
+    } else {
+      results.push({
+        status: "FAIL",
+        label: `${row.slot} provider=${row.provider}${suffix}, ${row.envVar} NOT set`,
+        detail: providerEnvHint(row.slot, row.provider, row.envVar)
+      });
+    }
   }
   results.push(await checkBinary("ffmpeg", ["-version"]));
   results.push(await checkBinary("ffprobe", ["-version"]));
@@ -5271,9 +5298,20 @@ function summarize(results) {
     fail: results.filter((r) => r.status === "FAIL").length
   };
 }
+function printFixOrder(results) {
+  const fails = results.filter((r) => r.status === "FAIL");
+  if (fails.length === 0) return;
+  process.stdout.write("\n");
+  logger.info("To fix:");
+  fails.forEach((r, i) => {
+    const hint = r.detail ? ` \u2014 ${r.detail}` : "";
+    logger.info(`  ${i + 1}. ${r.label}${hint}`);
+  });
+  process.stdout.write("\n");
+}
 function printRow(r) {
   const tag = `[${r.status}]`;
-  const line = `${tag} ${r.label}${r.detail ? ` \u2014 ${r.detail}` : ""}`;
+  const line = `${tag} ${r.label}${r.detail ? ` \xE2\u20AC\u201D ${r.detail}` : ""}`;
   if (r.status === "FAIL") logger.error(line);
   else if (r.status === "WARN") logger.warn(line);
   else logger.info(line);
@@ -5286,18 +5324,44 @@ async function checkBinary(name, args) {
       stdout += chunk.toString("utf8");
     });
     child.on("error", () => {
-      resolve27({ status: "FAIL", label: `${name} not on PATH` });
+      resolve27({
+        status: "FAIL",
+        label: `${name} not on PATH`,
+        detail: installHintFor(name)
+      });
     });
     child.on("exit", (code) => {
       if (code === 0) {
         const firstLine = stdout.split("\n")[0]?.trim() ?? "";
         resolve27({ status: "PASS", label: `${name} present`, detail: firstLine });
       } else {
-        resolve27({ status: "FAIL", label: `${name} exited with code ${code}` });
+        resolve27({
+          status: "FAIL",
+          label: `${name} exited with code ${code}`,
+          detail: installHintFor(name)
+        });
       }
     });
   });
 }
+function providerEnvHint(slot, provider, envVar) {
+  const dashboards = {
+    anthropic: "https://console.anthropic.com/settings/keys",
+    openai: "https://platform.openai.com/api-keys",
+    elevenlabs: "https://elevenlabs.io/app/settings/api-keys"
+  };
+  const dash = dashboards[provider];
+  const dashHint = dash ? ` (get a key from ${dash})` : "";
+  const altHint = slot === "llm" ? ` \u2014 or switch llm.default.provider to "agent_bridge" in demo.yaml to use a local CLI agent (no API key needed)` : "";
+  return `add ${envVar}=... to your project's .env file${dashHint}${altHint}`;
+}
+function installHintFor(binary) {
+  const p = osPlatform();
+  if (binary !== "ffmpeg" && binary !== "ffprobe") return "";
+  if (p === "darwin") return "install via `brew install ffmpeg`";
+  if (p === "win32") return "install via `winget install Gyan.FFmpeg` or `choco install ffmpeg`";
+  return "install via `apt install ffmpeg` (Debian/Ubuntu), `pacman -S ffmpeg` (Arch), or `dnf install ffmpeg` (Fedora)";
+}
 async function checkPlaywrightBrowser(config) {
   const browserName = config.recording.browser;
   try {
@@ -5309,13 +5373,48 @@ async function checkPlaywrightBrowser(config) {
       detail: exec
     };
   } catch (err) {
+    const sudoHit = await probeRootCache(browserName);
+    const fallback = `run \`npx playwright install ${browserName}\``;
+    if (sudoHit) {
+      return {
+        status: "FAIL",
+        label: `playwright ${browserName} binary missing for current user, but found in root/admin cache`,
+        detail: `${sudoHit} \u2014 re-run install WITHOUT sudo so the browser lands in your user cache: ${fallback}`
+      };
+    }
     return {
       status: "FAIL",
       label: `playwright ${browserName} binary missing`,
-      detail: `run \`npx playwright install ${browserName}\` (${err instanceof Error ? err.message : String(err)})`
+      detail: `${fallback} (${err instanceof Error ? err.message : String(err)})`
     };
   }
 }
+async function probeRootCache(browserName) {
+  const candidates = [];
+  const home = homedir();
+  const p = osPlatform();
+  if (p === "linux") {
+    candidates.push("/root/.cache/ms-playwright");
+  } else if (p === "darwin") {
+    candidates.push("/var/root/Library/Caches/ms-playwright");
+  } else if (p === "win32") {
+    const systemRoot = process.env["SystemRoot"] ?? "C:\\Windows";
+    candidates.push(join9(systemRoot, "System32", "config", "systemprofile", "AppData", "Local", "ms-playwright"));
+  }
+  if (candidates.length === 0) return null;
+  if (home === "/root" || home === "/var/root") return null;
+  for (const dir of candidates) {
+    try {
+      const entries = await readdir(dir);
+      const match = entries.find((e) => e.toLowerCase().startsWith(browserName.toLowerCase()));
+      if (match) {
+        return `found at ${join9(dir, match)}`;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
 async function checkTargetReachable(url) {
   try {
     const start = Date.now();
@@ -5336,10 +5435,12 @@ async function checkTargetReachable(url) {
       label: `target ${url} returned HTTP ${res.statusCode}`
     };
   } catch (err) {
+    const reason = err instanceof Error ? err.message.trim() : String(err).trim();
+    const prefix = reason ? `${reason} \u2014 ` : "";
     return {
       status: "FAIL",
       label: `target ${url} not reachable`,
-      detail: err instanceof Error ? err.message : String(err)
+      detail: `${prefix}start your dev server on this URL, or change \`recording.target_url\` in demo.yaml`
     };
   }
 }
@@ -5347,7 +5448,11 @@ async function checkScript(label, abs) {
   try {
     await stat9(abs);
   } catch {
-    return { status: "FAIL", label: `${label} not found`, detail: abs };
+    return {
+      status: "FAIL",
+      label: `${label} not found`,
+      detail: `expected at ${abs} \u2014 re-scaffold (\`showrunner init\` writes these) or remove the entry from demo.yaml's recording.state block`
+    };
   }
   if (process.platform !== "win32") {
     try {
@@ -5402,6 +5507,13 @@ function formatResolution(r) {
 }
 
 // src/commands/run.ts
+var STAGE_REMEDIATION = {
+  comprehension: "Check the LLM provider env (or switch llm.default.provider to agent_bridge in demo.yaml). If you already have a product_model.json, skip this stage: --stages script,record,voiceover,mux",
+  script: "Manifest generation failed. Inspect scripts/manifest.json if it was partially written. If the LLM is misbehaving, hand-author scripts/manifest.json and resume: --stages record,voiceover,mux",
+  record: "Playwright recording failed. Inspect with `showrunner trace -c <config> --all` or `--segment <id>`. Demo a problem segment manually with `showrunner record-actions -c <config> --segment <id>`.",
+  voiceover: "TTS synthesis or alignment failed. Check your TTS provider env. If alignment is the issue, set voiceover.alignment_strategy: best_effort in demo.yaml.",
+  mux: "ffmpeg mux failed. Check the `doctor` row about free disk + RAM. Cap libx264 threads with `SHOWRUNNER_FFMPEG_THREADS=1` if RAM is tight."
+};
 async function runCommand2(opts) {
   let loaded;
   try {
@@ -5470,6 +5582,12 @@ async function runCommand2(opts) {
       buildManifest: result.buildManifestPath
     });
   } catch (err) {
+    if (err instanceof PipelineStageError) {
+      logger.error(`Pipeline failed in stage \`${err.stage}\`: ${err.message}`);
+      const remediation = STAGE_REMEDIATION[err.stage];
+      if (remediation) logger.error(`To fix: ${remediation}`);
+      process.exit(1);
+    }
     const message = err instanceof Error ? err.message : String(err);
     logger.error(`Pipeline failed: ${message}`);
     process.exit(1);
@@ -5478,7 +5596,7 @@ async function runCommand2(opts) {
 
 // src/commands/init.ts
 import { mkdir as mkdir11, writeFile as writeFile12, access as access2 } from "fs/promises";
-import { dirname as dirname10, isAbsolute as isAbsolute8, join as join9, resolve as resolve15 } from "path";
+import { dirname as dirname10, isAbsolute as isAbsolute8, join as join10, resolve as resolve15 } from "path";
 var LLM_CHOICES = ["anthropic", "openai", "agent_bridge"];
 var TTS_CHOICES = ["elevenlabs", "openai", "custom"];
 var PLACEHOLDER_FILES = [
@@ -5504,7 +5622,7 @@ async function initCommand(opts) {
     resolution: resolvePreset(resolutionPreset)
   };
   const parent = isAbsolute8(opts.dir) ? opts.dir : resolve15(process.cwd(), opts.dir);
-  const projectRoot = join9(parent, opts.name);
+  const projectRoot = join10(parent, opts.name);
   if (!opts.force && await pathExists(projectRoot)) {
     logger.error(
       `Directory already exists: ${projectRoot}. Pass --force to overwrite, or choose a different --name/--dir.`
@@ -5513,34 +5631,59 @@ async function initCommand(opts) {
   }
   await mkdir11(projectRoot, { recursive: true });
   for (const rel of PLACEHOLDER_FILES) {
-    const dest = join9(projectRoot, rel);
+    const dest = join10(projectRoot, rel);
     await mkdir11(dirname10(dest), { recursive: true });
     await writeFile12(dest, "", "utf8");
   }
-  await writeFile12(join9(projectRoot, "demo.yaml"), demoYamlTemplate(resolved), "utf8");
-  await writeFile12(join9(projectRoot, ".env.example"), envExampleTemplate(resolved), "utf8");
-  await writeFile12(join9(projectRoot, ".gitignore"), gitignoreTemplate(), "utf8");
-  await mkdir11(join9(projectRoot, "docs"), { recursive: true });
-  await writeFile12(join9(projectRoot, "docs/PRD.md"), prdStubTemplate(resolved), "utf8");
-  await writeFile12(join9(projectRoot, "scripts/manifest.json"), starterManifest(resolved), "utf8");
-  await writeFile12(join9(projectRoot, "scripts/seed_demo_data.sh"), seedScript(), {
+  await writeFile12(join10(projectRoot, "demo.yaml"), demoYamlTemplate(resolved), "utf8");
+  await writeFile12(join10(projectRoot, ".env.example"), envExampleTemplate(resolved), "utf8");
+  await writeFile12(join10(projectRoot, ".gitignore"), gitignoreTemplate(), "utf8");
+  await mkdir11(join10(projectRoot, "docs"), { recursive: true });
+  await writeFile12(join10(projectRoot, "docs/PRD.md"), prdStubTemplate(resolved), "utf8");
+  await writeFile12(join10(projectRoot, "scripts/manifest.json"), starterManifest(resolved), "utf8");
+  await writeFile12(join10(projectRoot, "scripts/seed_demo_data.sh"), seedScript(), {
     mode: 493
   });
-  await writeFile12(join9(projectRoot, "scripts/reset_demo_data.sh"), resetScript(), {
+  await writeFile12(join10(projectRoot, "scripts/reset_demo_data.sh"), resetScript(), {
     mode: 493
   });
-  await writeFile12(join9(projectRoot, "scripts/teardown.sh"), teardownScript(), {
+  await writeFile12(join10(projectRoot, "scripts/teardown.sh"), teardownScript(), {
     mode: 493
   });
-  await writeFile12(join9(projectRoot, "README.md"), readmeTemplate(resolved), "utf8");
+  await writeFile12(join10(projectRoot, "README.md"), readmeTemplate(resolved), "utf8");
   logger.info(`Showrunner project scaffolded at ${projectRoot} (llm=${resolved.llm}, tts=${resolved.tts})`);
-  logger.info(`Next steps:
-  cd ${opts.name}
-  cp .env.example .env                    # fill in API keys
-  $EDITOR docs/PRD.md                     # replace the stub with your product brief
-  showrunner doctor --config demo.yaml    # preflight checks
-  showrunner understand --config demo.yaml   # build product_model.json
-  showrunner run --config demo.yaml       # the full pipeline`);
+  printNextSteps(opts.name, resolved);
+}
+function printNextSteps(projectName, resolved) {
+  const envVars = requiredEnvVars(resolved);
+  const lines = ["", `Next:`, ""];
+  let step = 1;
+  lines.push(`  ${step++}. cd ${projectName}`);
+  if (envVars.length > 0) {
+    const keysList = envVars.join(", ");
+    lines.push(`  ${step++}. cp .env.example .env       # then paste in: ${keysList}`);
+  } else {
+    lines.push(
+      `  ${step++}. (no .env needed \u2014 agent_bridge LLM + ${resolved.tts} TTS don't require API keys)`
+    );
+  }
+  lines.push(`  ${step++}. $EDITOR docs/PRD.md          # replace the stub with your product brief`);
+  lines.push(`  ${step++}. showrunner doctor -c demo.yaml`);
+  lines.push(`  ${step++}. showrunner run -c demo.yaml  # \u2192 output/demo_final.mp4`);
+  lines.push("");
+  lines.push(
+    `Optional: \`showrunner understand -c demo.yaml --interactive\` if you'd rather answer five questions than write the PRD upfront.`
+  );
+  lines.push("");
+  process.stdout.write(lines.join("\n"));
+}
+function requiredEnvVars(resolved) {
+  const vars = /* @__PURE__ */ new Set();
+  if (resolved.llm === "anthropic") vars.add("ANTHROPIC_API_KEY");
+  if (resolved.llm === "openai") vars.add("OPENAI_API_KEY");
+  if (resolved.tts === "elevenlabs") vars.add("ELEVENLABS_API_KEY");
+  if (resolved.tts === "openai") vars.add("OPENAI_API_KEY");
+  return [...vars];
 }
 function validateChoice(value, allowed, defaultValue, flagName) {
   if (!value) return defaultValue;
@@ -5971,6 +6114,50 @@ and \`at_word\` actions degrade to \`at\`).
 `;
 }
 
+// src/commands/installBrowser.ts
+import { spawn as spawn4 } from "child_process";
+import { access as access3 } from "fs/promises";
+import { fileURLToPath } from "url";
+import { dirname as dirname11, join as join11 } from "path";
+var DEFAULT_BROWSER = "chromium";
+async function installBrowserCommand(opts) {
+  const browser = opts.browser ?? DEFAULT_BROWSER;
+  const cli = await resolvePlaywrightCoreCli();
+  logger.info(`installing Playwright ${browser} (via bundled playwright-core, no project required)`);
+  const child = spawn4(process.execPath, [cli, "install", browser], {
+    stdio: "inherit",
+    env: process.env
+  });
+  const code = await new Promise((resolve27, reject) => {
+    child.on("error", reject);
+    child.on("close", (c) => resolve27(c ?? 0));
+  });
+  if (code !== 0) {
+    logger.error(`playwright install exited with code ${code}`);
+    process.exit(code);
+  }
+  logger.info(`${browser} installed. Try \`showrunner doctor -c demo.yaml\` next.`);
+}
+async function resolvePlaywrightCoreCli() {
+  const here = fileURLToPath(import.meta.url);
+  let dir = dirname11(here);
+  const root = dir.split(/[\\/]/)[0] + "/";
+  while (dir && dir !== root) {
+    const candidate = join11(dir, "node_modules", "playwright-core", "cli.js");
+    try {
+      await access3(candidate);
+      return candidate;
+    } catch {
+    }
+    const parent = dirname11(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "Could not locate playwright-core CLI inside Showrunner's node_modules. This is a packaging bug \u2014 please file an issue."
+  );
+}
+
 // src/commands/validate.ts
 import { stat as stat10 } from "fs/promises";
 import { isAbsolute as isAbsolute9, resolve as resolve16 } from "path";
@@ -6123,8 +6310,8 @@ async function pathExists2(p) {
 
 // src/commands/rerunSegment.ts
 import { mkdir as mkdir12, rename as rename3, writeFile as writeFile13 } from "fs/promises";
-import { join as join10, resolve as resolve19 } from "path";
-import { chromium as chromium4, firefox as firefox4, webkit as webkit4 } from "playwright";
+import { join as join12, resolve as resolve19 } from "path";
+import { chromium as chromium4, firefox as firefox4, webkit as webkit4 } from "playwright-core";
 var RERUN_BUFFER_MS = 500;
 var browserMap4 = { chromium: chromium4, firefox: firefox4, webkit: webkit4 };
 async function rerunSegmentCommand(opts) {
@@ -6242,17 +6429,17 @@ async function rerunSegmentCommand(opts) {
     await page.waitForTimeout(config.recording.segment_buffer_ms);
     const traceDir = resolve19(configDir, config.recording.trace_dir);
     await mkdir12(traceDir, { recursive: true });
-    await ctx.tracing.stopChunk({ path: join10(traceDir, `${segment.id}.zip`) });
+    await ctx.tracing.stopChunk({ path: join12(traceDir, `${segment.id}.zip`) });
     const videoHandle = page.video();
     await ctx.close();
     if (!videoHandle) {
-      logger.error("No video captured \u2014 recordVideo may have been ignored");
+      logger.error("No video captured \xE2\u20AC\u201D recordVideo may have been ignored");
       process.exit(1);
     }
     const original = await videoHandle.path();
-    const dest = join10(videoDir, `${segment.id}.webm`);
+    const dest = join12(videoDir, `${segment.id}.webm`);
     await rename3(original, dest);
-    const metadataPath = join10(videoDir, `${segment.id}.rerun.json`);
+    const metadataPath = join12(videoDir, `${segment.id}.rerun.json`);
     await writeFile13(
       metadataPath,
       JSON.stringify(
@@ -6270,7 +6457,7 @@ async function rerunSegmentCommand(opts) {
       ) + "\n",
       "utf8"
     );
-    logger.info(`Segment ${segment.id} re-recorded \u2192 ${dest}`, { metadata: metadataPath });
+    logger.info(`Segment ${segment.id} re-recorded \xE2\u2020\u2019 ${dest}`, { metadata: metadataPath });
     if (failure) {
       process.exit(1);
     }
@@ -6281,7 +6468,7 @@ async function rerunSegmentCommand(opts) {
 
 // src/commands/captureAuth.ts
 import { mkdir as mkdir14 } from "fs/promises";
-import { dirname as dirname11, isAbsolute as isAbsolute10, resolve as resolve21 } from "path";
+import { dirname as dirname12, isAbsolute as isAbsolute10, resolve as resolve21 } from "path";
 import { createInterface } from "readline/promises";
 
 // src/recording/headed.ts
@@ -6291,7 +6478,7 @@ import {
   chromium as chromium5,
   firefox as firefox5,
   webkit as webkit5
-} from "playwright";
+} from "playwright-core";
 var browserMap5 = { chromium: chromium5, firefox: firefox5, webkit: webkit5 };
 async function launchHeadedSession(opts) {
   const { recording, configDir } = opts;
@@ -6368,7 +6555,7 @@ async function captureAuthCommand(opts) {
   }
   const cookiesRel = opts.outputCookies ?? "./auth/session.json";
   const cookiesPath = isAbsolute10(cookiesRel) ? cookiesRel : resolve21(loaded.configDir, cookiesRel);
-  await mkdir14(dirname11(cookiesPath), { recursive: true });
+  await mkdir14(dirname12(cookiesPath), { recursive: true });
   logger.info("Launching headed browser for auth capture", {
     target: loaded.config.recording.target_url,
     output: cookiesPath
@@ -6408,8 +6595,8 @@ Then re-run \`showrunner run --config <demo.yaml>\`.
 }
 
 // src/commands/trace.ts
-import { readdir, stat as stat12 } from "fs/promises";
-import { isAbsolute as isAbsolute11, join as join11, resolve as resolve22 } from "path";
+import { readdir as readdir2, stat as stat12 } from "fs/promises";
+import { isAbsolute as isAbsolute11, join as join13, resolve as resolve22 } from "path";
 async function traceCommand(opts) {
   let loaded;
   try {
@@ -6423,7 +6610,7 @@ async function traceCommand(opts) {
   }
   const traceDir = resolve22(loaded.configDir, loaded.config.recording.trace_dir);
   const videoDir = resolve22(loaded.configDir, loaded.config.recording.output_dir);
-  const slicePlanPath = join11(videoDir, "slice_plan.json");
+  const slicePlanPath = join13(videoDir, "slice_plan.json");
   if (opts.all) {
     let plan;
     try {
@@ -6434,14 +6621,14 @@ async function traceCommand(opts) {
       process.exit(1);
     }
     for (const seg of plan.segments) {
-      const tracePath = seg.trace_path && isAbsolute11(seg.trace_path) ? seg.trace_path : seg.trace_path ? resolve22(loaded.configDir, seg.trace_path) : join11(traceDir, `${seg.id}.zip`);
+      const tracePath = seg.trace_path && isAbsolute11(seg.trace_path) ? seg.trace_path : seg.trace_path ? resolve22(loaded.configDir, seg.trace_path) : join13(traceDir, `${seg.id}.zip`);
       logger.info(`Opening trace for ${seg.id}`, { path: tracePath });
       await openTrace(tracePath);
     }
     return;
   }
   if (opts.segment) {
-    const tracePath = join11(traceDir, `${opts.segment}.zip`);
+    const tracePath = join13(traceDir, `${opts.segment}.zip`);
     if (!await fileExists8(tracePath)) {
       logger.error(`No trace found at ${tracePath}`);
       process.exit(1);
@@ -6482,7 +6669,7 @@ async function openTrace(tracePath) {
 }
 async function listTraces(dir) {
   try {
-    const entries = await readdir(dir);
+    const entries = await readdir2(dir);
     return entries.filter((e) => e.endsWith(".zip")).sort();
   } catch {
     return [];
@@ -6546,7 +6733,7 @@ async function fileExists9(path) {
 
 // src/commands/understand.ts
 import { mkdir as mkdir15, readFile as readFile10, writeFile as writeFile14 } from "fs/promises";
-import { dirname as dirname12, isAbsolute as isAbsolute12, resolve as resolve24 } from "path";
+import { dirname as dirname13, isAbsolute as isAbsolute12, resolve as resolve24 } from "path";
 
 // src/productModel/prompts.ts
 var PRODUCT_MODEL_SYSTEM_PROMPT = `You build product_model.json for Showrunner, an automated product demo recorder.
@@ -6751,7 +6938,7 @@ async function understandCommand(opts) {
     }
   }
   const outputPath = isAbsolute12(outputRel) ? outputRel : resolve24(configDir, outputRel);
-  await mkdir15(dirname12(outputPath), { recursive: true });
+  await mkdir15(dirname13(outputPath), { recursive: true });
   let productModel;
   const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
   try {
@@ -6798,8 +6985,8 @@ async function understandCommand(opts) {
 }
 
 // src/commands/instrument.ts
-import { mkdir as mkdir16, readdir as readdir2, writeFile as writeFile15 } from "fs/promises";
-import { dirname as dirname13, isAbsolute as isAbsolute13, join as join12, resolve as resolve25, relative as relative2 } from "path";
+import { mkdir as mkdir16, readdir as readdir3, writeFile as writeFile15 } from "fs/promises";
+import { dirname as dirname14, isAbsolute as isAbsolute13, join as join14, resolve as resolve25, relative as relative2 } from "path";
 
 // src/instrument/scan.ts
 import { readFile as readFile11 } from "fs/promises";
@@ -7022,9 +7209,9 @@ async function instrumentCommand(opts) {
   const filesToScan = /* @__PURE__ */ new Set();
   const IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "out"]);
   async function walk(root, accept) {
-    const entries = await readdir2(root, { withFileTypes: true });
+    const entries = await readdir3(root, { withFileTypes: true });
     for (const entry of entries) {
-      const abs = join12(root, entry.name);
+      const abs = join14(root, entry.name);
       if (entry.isDirectory()) {
         if (IGNORED_DIRS.has(entry.name)) continue;
         await walk(abs, accept);
@@ -7081,7 +7268,7 @@ async function instrumentCommand(opts) {
     logger.warn(`Skipped suggestion at ${s.file}:${s.line} \u2014 ${s.reason}`);
   }
   const outputPath = isAbsolute13(opts.output) ? opts.output : resolve25(loaded.configDir, opts.output);
-  await mkdir16(dirname13(outputPath), { recursive: true });
+  await mkdir16(dirname14(outputPath), { recursive: true });
   await writeFile15(outputPath, patch, "utf8");
   logger.info("Wrote instrumentation patch", { path: outputPath, suggestions: suggestions.length });
   process.stdout.write(`
@@ -7163,7 +7350,7 @@ var IN_PAGE_SCRIPT = `
     send('submit', el, null);
   }, true);
 
-  // Scroll capture \u2014 debounce 250ms, coalesce within window, emit direction + accumulated deltaY.
+  // Scroll capture \xE2\u20AC\u201D debounce 250ms, coalesce within window, emit direction + accumulated deltaY.
   let scrollLastY = window.scrollY;
   let scrollAccum = 0;
   let scrollTimer = null;
@@ -7186,7 +7373,7 @@ var IN_PAGE_SCRIPT = `
     const delta = currentY - scrollLastY;
     scrollLastY = currentY;
     if (delta === 0) return;
-    // Direction change \u2192 flush the previous burst immediately.
+    // Direction change \xE2\u2020\u2019 flush the previous burst immediately.
     if (scrollAccum !== 0 && Math.sign(delta) !== Math.sign(scrollAccum)) {
       if (scrollTimer !== null) { clearTimeout(scrollTimer); scrollTimer = null; }
       flushScroll();
@@ -7416,10 +7603,12 @@ async function fileExists10(path) {
 
 // src/cli.ts
 var program = new Command();
-program.name("showrunner").description("Automated product demo recording & production tool").version("1.1.0").option("--json", "emit structured JSON logs to stdout").option("--log-level <level>", "log level (debug|info|warn|error)").hook("preAction", (thisCmd) => {
+program.name("showrunner").description("Automated product demo recording & production tool").version("1.1.2").option("--json", "emit structured JSON logs to stdout").option("--log-level <level>", "log level (debug|info|warn|error)").hook("preAction", (thisCmd) => {
   const opts = thisCmd.opts();
   if (opts.json) logger.setJson(true);
   if (opts.logLevel) logger.setLevel(opts.logLevel);
+}).action(async () => {
+  await printWelcome();
 });
 var stageChoices = [...STAGE_NAMES];
 program.command("run").description("Run the full Showrunner pipeline").requiredOption("-c, --config <path>", "path to demo.yaml").addOption(
@@ -7447,6 +7636,7 @@ program.command("init").description("Scaffold a new Showrunner project").option(
   "scaffold resolution: low (854x480) | standard (720p) | high (1080p) | extreme (4K)",
   "standard"
 ).action(initCommand);
+program.command("install-browser").description("Install the Playwright browser binary (chromium by default) \u2014 wraps playwright-core install").option("--browser <name>", "browser to install: chromium | firefox | webkit", "chromium").action(installBrowserCommand);
 program.command("doctor").description("Run preflight checks on the current config + environment").requiredOption("-c, --config <path>", "path to demo.yaml").option("--json", "emit results as JSON instead of human-readable rows").action(doctorCommand);
 program.command("validate").description("Validate a demo.yaml config file").requiredOption("-c, --config <path>", "path to demo.yaml").option("--strict", "exit nonzero on any warning (e.g. missing provider env var)").action(validateCommand);
 program.command("understand").description("Build product_model.json from documents or interactive Q&A").option("-c, --config <path>", "path to demo.yaml").option("--interactive", "use interactive Q&A mode").option("--output <path>", "output path for product_model.json").action(understandCommand);
@@ -7463,6 +7653,60 @@ program.parseAsync(process.argv).catch((err) => {
   logger.error(message);
   process.exit(1);
 });
+async function printWelcome() {
+  const { access: access4 } = await import("fs/promises");
+  const { resolve: resolve27 } = await import("path");
+  const demoYaml = resolve27(process.cwd(), "demo.yaml");
+  let inProject = false;
+  try {
+    await access4(demoYaml);
+    inProject = true;
+  } catch {
+  }
+  const browserMissing = await isChromiumMissing();
+  const lines = ["", `Showrunner v1.1.2 \u2014 automated product-demo recording & production`, ""];
+  if (browserMissing) {
+    lines.push(`First-time setup: install the recording browser (one-off, ~150 MB):`);
+    lines.push(``);
+    lines.push(`  showrunner install-browser            # wraps Playwright; no "install dependencies first" warning`);
+    lines.push(``);
+  }
+  if (inProject) {
+    lines.push(`Detected demo.yaml in this directory. Likely next:`);
+    lines.push(``);
+    lines.push(`  showrunner doctor -c demo.yaml      # preflight checks`);
+    lines.push(`  showrunner run -c demo.yaml         # run the full pipeline`);
+    lines.push(``);
+    lines.push(`Other commands: \`showrunner --help\``);
+  } else {
+    lines.push(`No demo.yaml here. To scaffold a new project:`);
+    lines.push(``);
+    lines.push(`  showrunner init --name my-demo --url http://localhost:3000`);
+    lines.push(``);
+    lines.push(`Then inside the new directory:`);
+    lines.push(``);
+    lines.push(`  cd my-demo`);
+    lines.push(`  cp .env.example .env                 # paste provider keys, or use agent_bridge (no keys)`);
+    lines.push(`  $EDITOR docs/PRD.md                  # write your product brief`);
+    lines.push(`  showrunner doctor -c demo.yaml       # preflight`);
+    lines.push(`  showrunner run -c demo.yaml          # full pipeline \u2192 output/demo_final.mp4`);
+    lines.push(``);
+    lines.push(`See all commands: \`showrunner --help\``);
+  }
+  lines.push("");
+  process.stdout.write(lines.join("\n"));
+}
+async function isChromiumMissing() {
+  try {
+    const { chromium: chromium6 } = await import("playwright-core");
+    const exec = chromium6.executablePath();
+    const { stat: stat15 } = await import("fs/promises");
+    await stat15(exec);
+    return false;
+  } catch {
+    return true;
+  }
+}
 function parseStages(value) {
   const requested = value.split(",").map((s) => s.trim());
   const invalid = requested.filter((s) => !stageChoices.includes(s));