@qwertybit/pr-preview 0.1.2 → 0.1.4

package/dist/cli/index.js

@@ -6,12 +6,13 @@ import { Command } from "commander";
 
 // src/cli/commands/init.ts
 import { existsSync } from "fs";
-import { readFile, writeFile, appendFile } from "fs/promises";
+import { readFile, writeFile, appendFile, mkdir } from "fs/promises";
 import path from "path";
 
 // src/cli/ui/logger.ts
 import pc from "picocolors";
 import ora from "ora";
+import { createInterface } from "readline/promises";
 var log = {
   info(msg) {
     console.log(`${pc.cyan("\u25CF")} ${msg}`);
@@ -30,6 +31,20 @@ var log = {
   },
   spinner(text) {
     return ora({ text, color: "cyan" }).start();
+  },
+  /**
+   * Ask a yes/no question. Defaults to "no". In a non-interactive shell
+   * (no TTY, e.g. CI) it resolves to `false` without blocking.
+   */
+  async confirm(question) {
+    if (!process.stdin.isTTY) return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const answer = await rl.question(`${pc.yellow("?")} ${question} ${pc.dim("(y/N)")} `);
+      return /^y(es)?$/i.test(answer.trim());
+    } finally {
+      rl.close();
+    }
   }
 };
 
@@ -77,10 +92,105 @@ var GITIGNORE_BLOCK = `
 # pr-preview (worktrees, recordings, output)
 .pr-preview/
 `;
+async function writeMcpConfig(root) {
+  const mcpPath = path.join(root, ".mcp.json");
+  const entry = { command: "npx", args: ["pr-preview", "mcp"] };
+  let doc = {};
+  if (existsSync(mcpPath)) {
+    try {
+      doc = JSON.parse(await readFile(mcpPath, "utf8"));
+    } catch {
+      log.warn(".mcp.json exists but isn't valid JSON \u2014 leaving it untouched.");
+      return;
+    }
+  }
+  doc.mcpServers ??= {};
+  if (doc.mcpServers["pr-preview"]) {
+    const overwrite = await log.confirm(
+      ".mcp.json already has a pr-preview server. Overwrite it?"
+    );
+    if (!overwrite) {
+      log.warn("Left the existing pr-preview MCP server untouched.");
+      return;
+    }
+  }
+  doc.mcpServers["pr-preview"] = entry;
+  await writeFile(mcpPath, JSON.stringify(doc, null, 2) + "\n");
+  log.success(`${existsSync(mcpPath) ? "Updated" : "Created"} .mcp.json (pr-preview MCP server for Claude Code)`);
+}
+var RECORD_SKILL = `---
+name: record
+description: Record a video of a user journey through a web app, automatically, using PR Preview (@qwertybit/pr-preview). Claude drives the app itself and produces an MP4 \u2014 no human clicking. Usage: /record [url] [journey in plain English]. Use when the user wants to record, film, or capture a walkthrough or before/after video of an app for a pull request or demo.
+---
+
+# /record \u2014 record an app journey automatically with PR Preview
+
+You record a real video walkthrough of a web app by **driving it yourself** through the
+PR Preview MCP server \u2014 not by asking the user to click. PR Preview opens its harness (a
+visible Chrome window with the app in an iframe and a step sidebar); you perform the
+journey through its tools and it captures a clean, PR-ready MP4.
+
+## Arguments
+\`/record [url] [journey]\`
+- **url** (optional): the app to record, e.g. \`http://localhost:3000\` or \`https://staging.example.com\`. The first URL-looking token is the URL; the rest is the journey.
+- **journey** (optional): what to do, in plain English (e.g. "add 3 books to the cart, then go to checkout").
+
+## Preconditions
+The PR Preview MCP tools must be connected: \`start_recording\`, \`snapshot\`, \`act\`,
+\`next_pass\`, \`finish_recording\`, \`open_pr\`, \`detect_localhost\`.
+- If they are NOT available, tell the user to install and connect it:
+  \`npm i -D @qwertybit/pr-preview\` \u2192 \`npx pr-preview init\` (writes \`.mcp.json\`) \u2192 reload Claude Code.
+  Stop until it's connected.
+
+## Steps
+1. **Resolve the URL.** If a URL was given, use it. Otherwise call \`detect_localhost\`; if apps
+   are running, ask the user which to record; if none are, ask for a local, staging, or
+   production URL. **Never guess.**
+2. **Start.** Call \`start_recording\` with \`{ url }\`. A Chrome window opens with the harness \u2014
+   the app runs in the iframe and the sidebar records each step. Do NOT click "Start recording";
+   \`start_recording\` already began it. (For a base-vs-branch PR comparison, use
+   \`{ mode: "before-after" }\` with a managed dev server instead.)
+3. **Drive the journey.** Read the returned accessibility snapshot. For each step in the journey,
+   call \`act\` (\`click\` / \`fill\` / \`press\` / \`hover\` / \`navigate\` / \`scroll\`), targeting elements
+   by their \`[ref=\u2026]\` handle. Take a fresh snapshot after any step that changes the page. Perform
+   the journey faithfully \u2014 **you drive it; never ask the user to click.**
+4. **Finish.** Call \`finish_recording\` and report the output MP4 path.
+5. **PR (optional).** If the user asked, call \`open_pr\` with the produced file(s).
+
+## Important
+- This is agent-driven but a REAL capture of the real app \u2014 nothing is synthesized.
+- Do NOT use the \`pr-preview run\` CLI for this \u2014 that is the manual, human-in-the-loop flow that
+  waits for a person to click. Always drive via the MCP tools above so recording is automatic.
+`;
+async function writeRecordSkill(root) {
+  const skillDir = path.join(root, ".claude", "skills", "record");
+  const skillPath = path.join(skillDir, "SKILL.md");
+  if (existsSync(skillPath)) {
+    const overwrite = await log.confirm(
+      ".claude/skills/record/SKILL.md already exists. Overwrite it?"
+    );
+    if (!overwrite) {
+      log.warn("Left the existing /record skill untouched.");
+      return;
+    }
+  }
+  await mkdir(skillDir, { recursive: true });
+  await writeFile(skillPath, RECORD_SKILL);
+  log.success("Installed the /record slash command (.claude/skills/record/SKILL.md)");
+}
 async function initCommand(root) {
   const configPath = path.join(root, "pr-preview.config.js");
-  if (existsSync(configPath) || existsSync(path.join(root, "pr-preview.config.ts")) || existsSync(path.join(root, "pr-preview.config.json"))) {
-    log.warn("A pr-preview config already exists \u2014 leaving it untouched.");
+  const existingConfig = [".js", ".ts", ".json"].map((ext) => path.join(root, `pr-preview.config${ext}`)).find(existsSync);
+  if (existingConfig) {
+    const overwrite = await log.confirm(
+      `A pr-preview config already exists (${path.basename(existingConfig)}). Overwrite it?`
+    );
+    if (overwrite) {
+      await writeFile(existingConfig, CONFIG_TEMPLATE);
+      log.success(`Overwrote ${path.basename(existingConfig)}`);
+    } else {
+      log.warn("Left the existing pr-preview config untouched.");
+    }
   } else {
     await writeFile(configPath, CONFIG_TEMPLATE);
     log.success(`Created ${path.basename(configPath)}`);
@@ -91,12 +201,22 @@ async function initCommand(root) {
     await appendFile(gitignorePath, GITIGNORE_BLOCK);
     log.success("Added .pr-preview/ to .gitignore");
   }
+  await writeMcpConfig(root);
+  await writeRecordSkill(root);
   log.info("Edit the config to match your dev command, then run `pr-preview run` on a PR branch.");
+  log.info("Or ask Claude Code to record a flow for you (e.g. \u201Crecord my add-to-cart flow\u201D),");
+  log.info("or run the /record slash command: `/record localhost:3000 add a book, then checkout`.");
 }
 
-// src/cli/commands/record.ts
-import path11 from "path";
-import pc2 from "picocolors";
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+import path14 from "path";
+
+// src/mcp/recorder.ts
+import { existsSync as existsSync8 } from "fs";
+import path12 from "path";
 
 // src/config/load.ts
 import { existsSync as existsSync2 } from "fs";
@@ -147,7 +267,22 @@ var configSchema = z.object({
     // 24fps keeps the synthetic cursor's motion fluid in the clip.
     fps: z.number().positive().max(60).default(24),
     quality: z.enum(["high", "max"]).default("high"),
-    maxColors: z.number().int().min(2).max(256).default(256)
+    maxColors: z.number().int().min(2).max(256).default(256),
+    /**
+     * Motion smoothing for the MP4. The screencast delivers a low, variable
+     * frame rate, so the raw capture can look choppy. Interpolation synthesises
+     * intermediate frames up to `smoothFps` from the real captured frames:
+     * - "blend" (default): cross-dissolves frames — natural motion-blur, never
+     *   warps text/geometry. Safe for any site.
+     * - "mci": motion-compensated — sharper moving cursor, but can warp fast-
+     *   scrolling dense text on some pages.
+     * - "off": no interpolation (raw capture rate).
+     */
+    interpolate: z.enum(["blend", "mci", "off"]).default("blend"),
+    /** Target fps for interpolation (only used when interpolate ≠ "off").
+     *  60 = display-refresh smoothness; interpolation fills every gap between
+     *  the real captured frames up to this rate. */
+    smoothFps: z.number().int().positive().max(120).default(60)
   }).default({}),
   /**
    * Start-of-pass reset choice default: true (default) offers "reset" (clear
@@ -425,8 +560,8 @@ function harnessDistDir() {
 async function startHarnessServer(opts) {
   const dist = harnessDistDir();
   let appUrl = opts.appUrl;
-  const server = http.createServer(async (req, res) => {
-    const urlPath = (req.url ?? "/").split("?")[0];
+  const server = http.createServer(async (req2, res) => {
+    const urlPath = (req2.url ?? "/").split("?")[0];
     if (urlPath === "/runtime.json") {
       res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
       res.end(JSON.stringify({ appUrl, mode: opts.mode, viewport: opts.viewport }));
@@ -544,10 +679,10 @@ async function playwrightDisabledFeatures() {
   if (cachedBaseDisabledFeatures !== null) return cachedBaseDisabledFeatures;
   cachedBaseDisabledFeatures = "";
   try {
-    const probe = await chromium.launchServer({ headless: true });
-    const arg = probe.process().spawnargs.find((a) => a.startsWith("--disable-features="));
+    const probe2 = await chromium.launchServer({ headless: true });
+    const arg = probe2.process().spawnargs.find((a) => a.startsWith("--disable-features="));
     cachedBaseDisabledFeatures = arg ? arg.slice("--disable-features=".length) : "";
-    await probe.close();
+    await probe2.close();
   } catch {
   }
   return cachedBaseDisabledFeatures;
@@ -852,7 +987,9 @@ async function startScreencast(page, opts = {}) {
   await cdp.send("Page.startScreencast", {
     format: "jpeg",
     quality: opts.quality ?? 90,
-    everyNthFrame: opts.everyNthFrame ?? 1
+    everyNthFrame: opts.everyNthFrame ?? 1,
+    ...opts.maxWidth ? { maxWidth: opts.maxWidth } : {},
+    ...opts.maxHeight ? { maxHeight: opts.maxHeight } : {}
   });
   return {
     frameCount() {
@@ -918,14 +1055,14 @@ function resampleToFps(frames, fps) {
 }
 
 // src/encode/gif.ts
-import { mkdir as mkdir2, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "fs/promises";
 import path8 from "path";
 import sharp2 from "sharp";
 import * as gifencNs from "gifenc";
 
 // src/encode/ffmpeg.ts
 import { execFile, spawn as spawn2 } from "child_process";
-import { mkdtemp, rm, writeFile as writeFile2, mkdir } from "fs/promises";
+import { mkdtemp, rm, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
 import { tmpdir } from "os";
 import path6 from "path";
 var available = null;
@@ -953,14 +1090,14 @@ async function withFrameDir(pngFrames, fn) {
 }
 async function encodeWithFfmpeg(pngFrames, fps, outFile) {
   await withFrameDir(pngFrames, async (pattern) => {
-    await mkdir(path6.dirname(outFile), { recursive: true });
+    await mkdir2(path6.dirname(outFile), { recursive: true });
     const filter = `[0:v]fps=${fps},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`;
     await run("ffmpeg", ["-y", "-framerate", String(fps), "-i", pattern, "-filter_complex", filter, outFile]);
   });
 }
 async function encodeMp4(pngFrames, fps, outFile) {
   await withFrameDir(pngFrames, async (pattern) => {
-    await mkdir(path6.dirname(outFile), { recursive: true });
+    await mkdir2(path6.dirname(outFile), { recursive: true });
     await run("ffmpeg", [
       "-y",
       "-framerate",
@@ -983,6 +1120,39 @@ async function encodeMp4(pngFrames, fps, outFile) {
     ]);
   });
 }
+async function encodeMp4Interpolated(pngFrames, durationsSec, outFps, mode, outFile) {
+  const dir = await mkdtemp(path6.join(tmpdir(), "pr-preview-frames-"));
+  try {
+    await Promise.all(
+      pngFrames.map(
+        (buf, i) => writeFile2(path6.join(dir, `frame${String(i).padStart(5, "0")}.png`), buf)
+      )
+    );
+    const lines = [];
+    pngFrames.forEach((_, i) => {
+      lines.push(`file 'frame${String(i).padStart(5, "0")}.png'`);
+      lines.push(`duration ${Math.max(1e-3, durationsSec[i] ?? 1 / outFps).toFixed(4)}`);
+    });
+    lines.push(`file 'frame${String(pngFrames.length - 1).padStart(5, "0")}.png'`);
+    await writeFile2(path6.join(dir, "list.txt"), lines.join("\n") + "\n");
+    await mkdir2(path6.dirname(outFile), { recursive: true });
+    const interp = mode === "mci" ? `minterpolate=fps=${outFps}:mi_mode=mci:me_mode=bidir:mc_mode=aobmc:vsbmc=1:scd=fdiff` : `minterpolate=fps=${outFps}:mi_mode=blend:scd=fdiff`;
+    const common = ["-c:v", "libx264", "-preset", "slow", "-crf", "19", "-pix_fmt", "yuv420p", "-movflags", "+faststart", outFile];
+    const input = ["-f", "concat", "-safe", "0", "-i", path6.join(dir, "list.txt")];
+    const scale = "scale=trunc(iw/2)*2:trunc(ih/2)*2";
+    try {
+      await run("ffmpeg", ["-y", ...input, "-vf", `${interp},${scale}`, "-r", String(outFps), ...common]);
+    } catch (err) {
+      console.warn(
+        `[pr-preview] motion smoothing (${mode}) failed; encoding without interpolation \u2014 the clip will look choppier.
+  ${err.message?.split("\n")[0] ?? err}`
+      );
+      await run("ffmpeg", ["-y", ...input, "-vf", scale, "-r", String(outFps), ...common]);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
 function run(cmd, args) {
   return new Promise((resolve, reject) => {
     const child = spawn2(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
@@ -1207,7 +1377,7 @@ async function encodeGif(rawFrames, opts) {
     opts.onProgress?.("Encoding GIF", ++done, frames.length);
   }
   gif.finish();
-  await mkdir2(path8.dirname(opts.outFile), { recursive: true });
+  await mkdir3(path8.dirname(opts.outFile), { recursive: true });
   await writeFile3(opts.outFile, gif.bytes());
   return { path: opts.outFile, frameCount: frames.length };
 }
@@ -1222,7 +1392,9 @@ async function encodeMedia(rawFrames, opts) {
   const paths = [];
   let frameCount = 0;
   if (doMp4) {
-    const frames = resampleToFps(rawFrames, opts.fps);
+    const interpolate = opts.interpolate ?? "off";
+    const smooth = interpolate !== "off";
+    const frames = smooth ? rawFrames : resampleToFps(rawFrames, opts.fps);
     frameCount = frames.length;
     const meta = await sharp3(frames[0].data).metadata();
     const crop = cssRectToFramePixels(
@@ -1248,7 +1420,16 @@ async function encodeMedia(rawFrames, opts) {
     }
     const file = `${opts.outBase}.mp4`;
     opts.onProgress?.("Encoding MP4", frames.length, frames.length);
-    await encodeMp4(pngs, opts.fps, file);
+    if (smooth) {
+      const MAX_HOLD = 0.5;
+      const durations = frames.map(
+        (f, i) => i < frames.length - 1 ? Math.min(MAX_HOLD, Math.max(1e-3, (frames[i + 1].t - f.t) / 1e3)) : 1 / opts.fps
+      );
+      const outFps = Math.max(opts.smoothFps ?? 30, opts.fps);
+      await encodeMp4Interpolated(pngs, durations, outFps, interpolate, file);
+    } else {
+      await encodeMp4(pngs, opts.fps, file);
+    }
     paths.push(file);
   }
   if (doGif) {
@@ -1513,8 +1694,12 @@ var Session = class {
     }
     const page = this.page;
     if (!page) return;
+    const { maxWidth, maxHeight } = await page.evaluate(() => ({
+      maxWidth: Math.min(window.innerWidth, 1920),
+      maxHeight: Math.min(window.innerHeight, 1200)
+    })).catch(() => ({ maxWidth: 1920, maxHeight: 1200 }));
     try {
-      this.recordingFeed = await startScreencast(page, { quality: 80 });
+      this.recordingFeed = await startScreencast(page, { quality: 80, maxWidth, maxHeight });
     } catch {
       this.recordingFeed = null;
     }
@@ -1586,6 +1771,8 @@ var Session = class {
       fps: this.config.gif.fps,
       quality: this.config.gif.quality,
       maxColors: this.config.gif.maxColors,
+      interpolate: this.config.gif.interpolate,
+      smoothFps: this.config.gif.smoothFps,
       format: this.config.format,
       outBase,
       label: label ? { pass: this.singleClip ? "single" : which, ...label } : void 0,
@@ -1732,82 +1919,59 @@ async function bootstrap(repoRoot, config, mode, opts = {}) {
   };
 }
 
-// src/recorder/journey.ts
-import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir3 } from "fs/promises";
-import path10 from "path";
-import { z as z2 } from "zod";
-var stepSchema = z2.object({
-  id: z2.string(),
-  type: z2.enum(["click", "fill", "select", "press", "scroll", "navigate", "wait"]),
-  selectors: z2.array(z2.string()).optional(),
-  coordinates: z2.object({ xNorm: z2.number(), yNorm: z2.number() }).optional(),
-  frameUrl: z2.string().optional(),
-  value: z2.string().optional(),
-  key: z2.string().optional(),
-  scrollTarget: z2.string().optional(),
-  scroll: z2.object({ xNorm: z2.number(), yNorm: z2.number() }).optional(),
-  url: z2.string().optional(),
-  causesNavigation: z2.boolean().optional(),
-  label: z2.string().optional(),
-  timestamp: z2.number(),
-  thumbnail: z2.string().optional()
-});
-var journeySchema = z2.object({
-  version: z2.literal(1),
-  createdAt: z2.string(),
-  baseRef: z2.string().optional(),
-  viewport: z2.object({
-    width: z2.number(),
-    height: z2.number(),
-    deviceScaleFactor: z2.number()
-  }),
-  startUrl: z2.string(),
-  steps: z2.array(stepSchema)
-});
-async function saveJourney(file, journey) {
-  const clean = {
-    ...journey,
-    steps: journey.steps.map((s) => {
-      const { thumbnail: _thumbnail, ...rest } = s;
-      return rest;
-    })
-  };
-  await mkdir3(path10.dirname(file), { recursive: true });
-  await writeFile4(file, JSON.stringify(clean, null, 2) + "\n");
+// src/mcp/motion.ts
+var MOTION = {
+  glideMs: 750,
+  // ceiling; the cursor scales the actual glide by distance
+  scrollMs: 600,
+  typeDelayMs: 35,
+  settleMs: 140,
+  holdMs: 80
+  // brief pause after a glide lands, before the click, so the
+  // arrival + click-pulse frames are captured
+};
+async function glideCursor(frame, x, y, ms = MOTION.glideMs) {
+  await frame.evaluate(
+    ({ x: x2, y: y2, ms: ms2 }) => window.__prPreviewCursor?.moveTo(x2, y2, ms2) ?? Promise.resolve(),
+    { x, y, ms }
+  ).catch(() => {
+  });
 }
-
-// src/cli/commands/record.ts
-async function recordCommand(repoRoot, opts) {
-  const { config } = await loadConfig(repoRoot);
-  const journeyFile = path11.resolve(repoRoot, opts.out ?? ".pr-preview/journey.json");
-  try {
-    const boot = await bootstrap(repoRoot, config, "record");
-    await boot.startApp("after", repoRoot);
-    await boot.openBrowser("after");
-    log.info(`Harness open at ${pc2.bold(boot.harness.url)}`);
-    log.step("Click Record in the sidebar, perform the journey, then Confirm.");
-    const steps = await boot.session.recordUntilConfirmed();
-    if (steps.length === 0) {
-      log.warn("No steps recorded \u2014 nothing saved.");
-      return;
-    }
-    await saveJourney(journeyFile, {
-      version: 1,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      viewport: { ...config.viewport, deviceScaleFactor: 2 },
-      startUrl: boot.session.startUrl,
-      steps
-    });
-    log.success(`Saved ${steps.length} steps to ${path11.relative(repoRoot, journeyFile)}`);
-  } finally {
-    await runCleanups();
-  }
+async function showCursor(frame, x, y) {
+  await frame.evaluate(
+    ({ x: x2, y: y2 }) => {
+      const c = window.__prPreviewCursor;
+      if (!c) return;
+      c.show(x2 ?? (window.innerWidth || 1280) / 2, y2 ?? (window.innerHeight || 800) / 2);
+    },
+    { x: x ?? null, y: y ?? null }
+  ).catch(() => {
+  });
+}
+async function pulseCursor(frame) {
+  await frame.evaluate(
+    () => window.__prPreviewCursor?.clickPulse() ?? Promise.resolve()
+  ).catch(() => {
+  });
+}
+async function smoothScrollBy(frame, deltaY, ms = MOTION.scrollMs) {
+  await frame.evaluate(
+    ({ deltaY: deltaY2, ms: ms2 }) => new Promise((resolve) => {
+      const startY = window.scrollY;
+      const t0 = performance.now();
+      const ease = (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+      const tick = (now) => {
+        const t = Math.min(1, (now - t0) / ms2);
+        window.scrollTo(0, startY + deltaY2 * ease(t));
+        if (t < 1) requestAnimationFrame(tick);
+        else resolve();
+      };
+      requestAnimationFrame(tick);
+    }),
+    { deltaY, ms }
+  ).catch(() => {
+  });
 }
-
-// src/cli/commands/run.ts
-import { existsSync as existsSync8 } from "fs";
-import path14 from "path";
-import pc3 from "picocolors";
 
 // src/git/exec.ts
 import { execFile as execFile2 } from "child_process";
@@ -1886,7 +2050,7 @@ async function detectBase(repoRoot, override) {
 // src/git/worktree.ts
 import { existsSync as existsSync6 } from "fs";
 import { rm as rm2 } from "fs/promises";
-import path12 from "path";
+import path10 from "path";
 var WORKTREE_DIR = ".pr-preview/worktrees";
 function explainGitCrash(err, repoRoot) {
   const msg = err instanceof Error ? err.message : String(err);
@@ -1903,7 +2067,7 @@ Original error: ${msg}`
   throw err;
 }
 async function createBaseWorktree(repoRoot, sha) {
-  const dir = path12.join(repoRoot, WORKTREE_DIR, `base-${sha.slice(0, 12)}`);
+  const dir = path10.join(repoRoot, WORKTREE_DIR, `base-${sha.slice(0, 12)}`);
   if (existsSync6(dir) && await tryGit(dir, ["rev-parse", "HEAD"]) === sha) {
     return { dir, remove: () => removeWorktree(repoRoot, dir) };
   }
@@ -1929,12 +2093,12 @@ async function pruneStaleWorktrees(repoRoot) {
 
 // src/server/pkgManager.ts
 import { existsSync as existsSync7 } from "fs";
-import path13 from "path";
+import path11 from "path";
 import { spawn as spawn3 } from "child_process";
 function detectPackageManager(dir) {
-  if (existsSync7(path13.join(dir, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync7(path13.join(dir, "yarn.lock"))) return "yarn";
-  if (existsSync7(path13.join(dir, "bun.lockb")) || existsSync7(path13.join(dir, "bun.lock"))) {
+  if (existsSync7(path11.join(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync7(path11.join(dir, "yarn.lock"))) return "yarn";
+  if (existsSync7(path11.join(dir, "bun.lockb")) || existsSync7(path11.join(dir, "bun.lock"))) {
     return "bun";
   }
   return "npm";
@@ -1961,6 +2125,737 @@ ${tail}`));
   });
 }
 
+// src/mcp/recorder.ts
+function stamp() {
+  const d = /* @__PURE__ */ new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+function fileStamp() {
+  const d = /* @__PURE__ */ new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`;
+}
+var shortRef = (ref) => ref.replace(/^origin\//, "");
+var slug = (s) => shortRef(s).replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "clip";
+var PreviewRecorder = class {
+  constructor(repoRoot) {
+    this.repoRoot = repoRoot;
+  }
+  repoRoot;
+  boot = null;
+  page = null;
+  config = null;
+  outDir = ".pr-preview/output";
+  mode = "single";
+  pass = "before";
+  started = false;
+  // before/after bookkeeping
+  beforeServer = null;
+  worktree = null;
+  baseLabel = "";
+  headLabel = "";
+  fstamp = "";
+  timestamp = "";
+  beforePaths = [];
+  fellBackToGif = false;
+  get isActive() {
+    return this.started;
+  }
+  /** Launch the browser + app and begin recording. Returns the first snapshot. */
+  async start(opts = {}) {
+    if (this.started) throw new Error("A recording is already in progress \u2014 call finish_recording first.");
+    this.mode = opts.mode ?? "single";
+    if (this.mode === "before-after") return this.startBeforeAfter();
+    return this.startSingle(opts.url);
+  }
+  async startSingle(url) {
+    let config;
+    try {
+      config = (await loadConfig(this.repoRoot)).config;
+    } catch (err) {
+      if (url && err instanceof ConfigError) config = configSchema.parse({ devCommand: "external", url });
+      else throw err;
+    }
+    this.config = config;
+    this.outDir = path12.resolve(this.repoRoot, config.output);
+    this.headLabel = await this.currentBranch();
+    this.timestamp = stamp();
+    this.fstamp = fileStamp();
+    const boot = url ? await bootstrap(this.repoRoot, config, "run", { fixedUrl: url }) : await bootstrap(this.repoRoot, config, "run");
+    this.boot = boot;
+    boot.session.setPasses(1);
+    if (!url) await boot.startApp("before", this.repoRoot);
+    const browser = await boot.openBrowser("before");
+    this.page = browser.page;
+    await this.beginRecording();
+    this.started = true;
+    return { snapshot: await this.snapshot(), startUrl: boot.session.startUrl, mode: this.mode };
+  }
+  async startBeforeAfter() {
+    const config = (await loadConfig(this.repoRoot)).config;
+    this.config = config;
+    this.outDir = path12.resolve(this.repoRoot, config.output);
+    const currentBranch = await tryGit(this.repoRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    if (!currentBranch) {
+      throw new GitError(
+        "before/after recording needs you to be on a branch (detached HEAD).\nCheck out your PR branch first, or use single mode."
+      );
+    }
+    const base = await detectBase(this.repoRoot, config.baseBranch);
+    this.baseLabel = shortRef(base.ref);
+    this.headLabel = shortRef(currentBranch);
+    this.timestamp = stamp();
+    this.fstamp = fileStamp();
+    const worktree = await createBaseWorktree(this.repoRoot, base.sha);
+    this.worktree = worktree;
+    if (!config.keepWorktree) registerCleanup(() => worktree.remove());
+    if (config.install !== "never") {
+      const appDir = path12.join(worktree.dir, config.cwd);
+      const hasModules = existsSync8(path12.join(appDir, "node_modules"));
+      if (config.install === "always" || !hasModules) {
+        await installDependencies(appDir, detectPackageManager(appDir));
+      }
+    }
+    const boot = await bootstrap(this.repoRoot, config, "run");
+    this.boot = boot;
+    boot.session.setPasses(2);
+    boot.session.setBranches(base.ref, currentBranch);
+    this.beforeServer = await boot.startApp("before", worktree.dir);
+    const browser = await boot.openBrowser("before");
+    this.page = browser.page;
+    this.pass = "before";
+    await this.beginRecording();
+    this.started = true;
+    return { snapshot: await this.snapshot(), startUrl: boot.session.startUrl, mode: this.mode };
+  }
+  /** before/after only: finish the BEFORE clip, switch to the branch app, start AFTER. */
+  async nextPass() {
+    if (!this.started) throw new Error("No active recording \u2014 call start_recording first.");
+    if (this.mode !== "before-after") throw new Error("next_pass is only valid in before-after mode.");
+    if (this.pass !== "before") throw new Error("Already recording the AFTER pass.");
+    const boot = this.boot;
+    boot.session.setPhase("idle");
+    const before = await boot.session.encodeClip("before", this.outPath("before", this.baseLabel), {
+      branch: this.baseLabel,
+      baseBranch: this.baseLabel,
+      timestamp: this.timestamp
+    });
+    this.beforePaths = before.paths;
+    this.fellBackToGif ||= before.fellBackToGif;
+    await this.beforeServer?.stop();
+    await boot.startApp("after", this.repoRoot);
+    boot.session.switchPass("after");
+    await boot.switchApp("after");
+    this.pass = "after";
+    await this.beginRecording();
+    return { snapshot: await this.snapshot() };
+  }
+  /** Accessibility tree of the app (with [ref=eN] handles) for Claude to target. */
+  async snapshot() {
+    const frame = await this.frame();
+    await frame.waitForLoadState("domcontentloaded").catch(() => {
+    });
+    return frame.locator("body").ariaSnapshot({ mode: "ai" });
+  }
+  /** Perform one action in the app, then return the fresh snapshot. Motions are
+   *  animated in-page (synthetic-cursor glide, rAF scroll, per-character typing)
+   *  so the live screencast captures continuous video, not a jumpy slideshow. */
+  async act(a) {
+    if (!this.started) throw new Error("No active recording \u2014 call start_recording first.");
+    const frame = await this.frame();
+    switch (a.action) {
+      case "click": {
+        const loc = frame.locator(`aria-ref=${req(a.ref, "ref")}`);
+        await this.glideToLocator(loc);
+        await pulseCursor(frame);
+        await loc.click({ timeout: 15e3 });
+        break;
+      }
+      case "fill": {
+        const loc = frame.locator(`aria-ref=${req(a.ref, "ref")}`);
+        await this.glideToLocator(loc);
+        await loc.click({ timeout: 15e3 });
+        await loc.fill("", { timeout: 15e3 });
+        await loc.pressSequentially(req(a.text, "text"), { delay: MOTION.typeDelayMs, timeout: 15e3 });
+        break;
+      }
+      case "press": {
+        const loc = frame.locator(`aria-ref=${req(a.ref, "ref")}`);
+        const key = req(a.key, "key");
+        await this.glideToLocator(loc);
+        if (key === "Enter" || key === " " || key === "Spacebar") await pulseCursor(frame);
+        await loc.press(key, { timeout: 15e3 });
+        break;
+      }
+      case "hover": {
+        const loc = frame.locator(`aria-ref=${req(a.ref, "ref")}`);
+        await this.glideToLocator(loc);
+        await loc.hover({ timeout: 15e3 });
+        break;
+      }
+      case "scroll":
+        if (a.ref) await this.smoothScrollToLocator(frame.locator(`aria-ref=${a.ref}`));
+        else {
+          const delta = await frame.evaluate(() => window.innerHeight * 0.8);
+          await smoothScrollBy(frame, delta);
+        }
+        break;
+      case "navigate": {
+        const target = new URL(req(a.url, "url"), this.boot.session.targetOrigin + "/").toString();
+        await frame.goto(target, { waitUntil: "domcontentloaded" });
+        await showCursor(await this.frame());
+        break;
+      }
+      case "wait":
+        await this.page.waitForTimeout(Math.min(a.ms ?? 1e3, 15e3));
+        break;
+      default:
+        throw new Error(`Unknown action: ${String(a.action)}`);
+    }
+    await this.page.waitForTimeout(MOTION.settleMs);
+    return { snapshot: await this.snapshot() };
+  }
+  /** Bring a target on-screen, then glide the synthetic cursor to its centre.
+   *  Coordinates are frame-local (what the in-page cursor uses). */
+  async glideToLocator(loc) {
+    await loc.scrollIntoViewIfNeeded({ timeout: 15e3 }).catch(() => {
+    });
+    const c = await loc.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+    }).catch(() => null);
+    if (c) {
+      await glideCursor(await this.frame(), c.x, c.y);
+      await this.page.waitForTimeout(MOTION.holdMs);
+    }
+  }
+  /** Smoothly scroll a target to the vertical centre of the viewport. The delta
+   *  is measured inside the frame (frame-local coords). */
+  async smoothScrollToLocator(loc) {
+    const delta = await loc.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      return r.top + r.height / 2 - window.innerHeight / 2;
+    }).catch(() => null);
+    if (delta === null) {
+      await loc.scrollIntoViewIfNeeded({ timeout: 15e3 }).catch(() => {
+      });
+      return;
+    }
+    if (Math.abs(delta) < 8) return;
+    await smoothScrollBy(await this.frame(), delta);
+  }
+  /** Stop recording, encode the final clip(s), and return the output file paths. */
+  async finish(opts = {}) {
+    if (!this.started) throw new Error("No active recording \u2014 call start_recording first.");
+    if (this.mode === "before-after" && this.pass !== "after") {
+      throw new Error("Record the AFTER pass first: call next_pass, redo the journey, then finish_recording.");
+    }
+    const boot = this.boot;
+    boot.session.setPhase("idle");
+    let files;
+    if (this.mode === "before-after") {
+      const after = await boot.session.encodeClip("after", this.outPath("after", this.headLabel), {
+        branch: this.headLabel,
+        baseBranch: this.baseLabel,
+        timestamp: this.timestamp
+      });
+      this.fellBackToGif ||= after.fellBackToGif;
+      files = [...this.beforePaths, ...after.paths];
+    } else {
+      const clip = await boot.session.encodeClip("before", this.outPath("single", opts.name ?? this.headLabel), {
+        branch: this.headLabel,
+        baseBranch: this.headLabel,
+        timestamp: this.timestamp
+      });
+      this.fellBackToGif ||= clip.fellBackToGif;
+      files = clip.paths;
+    }
+    const fellBack = this.fellBackToGif;
+    await this.dispose();
+    return { files, fellBackToGif: fellBack };
+  }
+  /** Tear everything down (browser, harness, dev servers, worktree) without encoding. */
+  async dispose() {
+    this.started = false;
+    this.boot = null;
+    this.page = null;
+    this.beforeServer = null;
+    this.worktree = null;
+    await runCleanups();
+  }
+  // ── helpers ────────────────────────────────────────────────────────────────
+  outPath(which, label) {
+    return path12.join(this.outDir, `${which === "single" ? slug(label) : `${which}-${slug(label)}`}-${this.fstamp}`);
+  }
+  /** Capture the start path, then begin the live screencast recording. */
+  async beginRecording() {
+    const boot = this.boot;
+    const frame = await getAppFrame(this.page, boot.session.targetOrigin);
+    await frame.waitForLoadState("domcontentloaded").catch(() => {
+    });
+    boot.session.startUrl = await frame.evaluate(() => location.pathname + location.search).catch(() => "/");
+    boot.session.setPhase("recording");
+    await showCursor(frame);
+  }
+  async frame() {
+    if (!this.page || !this.boot) throw new Error("No active recording.");
+    return getAppFrame(this.page, this.boot.session.targetOrigin);
+  }
+  async currentBranch() {
+    const ref = await tryGit(this.repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    return ref ? shortRef(ref) : "app";
+  }
+};
+function req(v, name) {
+  if (v === void 0 || v === null || v === "") throw new Error(`Missing required "${name}" for this action.`);
+  return v;
+}
+
+// src/mcp/publish.ts
+import { execFile as execFile3 } from "child_process";
+import { promisify } from "util";
+import { copyFile, mkdir as mkdir4 } from "fs/promises";
+import { existsSync as existsSync9 } from "fs";
+import path13 from "path";
+var pexec = promisify(execFile3);
+async function run2(cmd, args, cwd) {
+  try {
+    const { stdout } = await pexec(cmd, args, { cwd, maxBuffer: 16 * 1024 * 1024 });
+    return stdout.trim();
+  } catch (e) {
+    const err = e;
+    throw new Error(`\`${cmd} ${args.slice(0, 2).join(" ")}\` failed: ${(err.stderr || err.message || String(e)).trim()}`);
+  }
+}
+async function openPr(repoRoot, files, opts = {}) {
+  if (files.length === 0) {
+    throw new Error("No clip files provided \u2014 run finish_recording first and pass its output paths.");
+  }
+  try {
+    await run2("gh", ["--version"], repoRoot);
+  } catch {
+    throw new Error("GitHub CLI (gh) not found. Install it from https://cli.github.com, then `gh auth login`.");
+  }
+  try {
+    await run2("gh", ["auth", "status"], repoRoot);
+  } catch {
+    throw new Error("GitHub CLI isn't authenticated. Run `gh auth login`, then try again.");
+  }
+  const branch = await tryGit(repoRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (!branch) throw new Error("You're on a detached HEAD. Check out your PR branch first.");
+  if (!await tryGit(repoRoot, ["remote", "get-url", "origin"])) {
+    throw new Error("No `origin` remote found. Add one (and push the branch), then retry.");
+  }
+  const slug3 = await repoSlug(repoRoot);
+  const abs = files.map((f) => path13.isAbsolute(f) ? f : path13.resolve(repoRoot, f));
+  for (const f of abs) if (!existsSync9(f)) throw new Error(`Clip file not found: ${f}`);
+  const destDir = path13.join(repoRoot, "pr-preview");
+  await mkdir4(destDir, { recursive: true });
+  const committed = [];
+  let embedGifRel = null;
+  const mp4Rel = [];
+  for (const f of abs) {
+    const base = path13.basename(f);
+    await copyFile(f, path13.join(destDir, base));
+    committed.push(`pr-preview/${base}`);
+    if (base.endsWith(".gif") && !embedGifRel) embedGifRel = `pr-preview/${base}`;
+    if (base.endsWith(".mp4")) mp4Rel.push(`pr-preview/${base}`);
+  }
+  if (!embedGifRel && mp4Rel.length && await ffmpegAvailable()) {
+    const src = path13.join(repoRoot, mp4Rel[0]);
+    const gifName = path13.basename(mp4Rel[0]).replace(/\.mp4$/, ".gif");
+    await run2(
+      "ffmpeg",
+      ["-y", "-i", src, "-vf", "fps=15,scale=900:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse", path13.join(destDir, gifName)],
+      repoRoot
+    );
+    committed.push(`pr-preview/${gifName}`);
+    embedGifRel = `pr-preview/${gifName}`;
+  }
+  await git(repoRoot, ["add", "--", ...committed]);
+  try {
+    await git(repoRoot, ["commit", "-m", "Add PR preview clip"]);
+  } catch (e) {
+    if (!/nothing to commit/i.test(String(e))) throw e;
+  }
+  await run2("git", ["push", "-u", "origin", branch], repoRoot);
+  const rawBase = `https://github.com/${slug3}/raw/${branch}`;
+  const body = buildBody(embedGifRel, mp4Rel, rawBase);
+  const args = ["pr", "create", "--title", opts.title ?? `Preview: ${branch}`, "--body", body, "--head", branch];
+  if (opts.base) args.push("--base", opts.base);
+  const prUrl = await run2("gh", args, repoRoot);
+  return { prUrl, committed, embedded: embedGifRel ? "gif" : "mp4-link" };
+}
+function buildBody(gifRel, mp4Rel, rawBase) {
+  const lines = ["## PR Preview", ""];
+  if (gifRel) lines.push(`![PR preview](${rawBase}/${gifRel})`, "");
+  if (mp4Rel.length) {
+    lines.push("Full-quality MP4:");
+    for (const m of mp4Rel) lines.push(`- [${path13.basename(m)}](${rawBase}/${m})`);
+    lines.push("");
+  }
+  lines.push("<sub>Recorded with [PR Preview](https://pr-preview.com) via Claude Code.</sub>");
+  return lines.join("\n");
+}
+async function repoSlug(repoRoot) {
+  try {
+    return await run2("gh", ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], repoRoot);
+  } catch {
+  }
+  const url = await tryGit(repoRoot, ["remote", "get-url", "origin"]) ?? "";
+  const m = url.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (!m) throw new Error("Couldn't determine the GitHub owner/repo from the origin remote.");
+  return m[1];
+}
+
+// src/mcp/detect.ts
+var CANDIDATE_PORTS = [
+  3e3,
+  3001,
+  3002,
+  3003,
+  // Next.js / CRA / Node
+  5173,
+  5174,
+  4321,
+  // Vite / Astro
+  4200,
+  // Angular
+  8080,
+  8e3,
+  5e3,
+  4e3,
+  3333,
+  // misc dev servers
+  1420,
+  // Tauri
+  6006
+  // Storybook
+];
+async function probe(url, timeoutMs = 1200) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal, redirect: "manual" });
+    if (res.status >= 500) return null;
+    let title;
+    try {
+      const html = await res.text();
+      title = html.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1]?.trim() || void 0;
+    } catch {
+    }
+    return { url, title };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function detectLocalApps(preferred) {
+  const urls = /* @__PURE__ */ new Set();
+  if (preferred && /^https?:\/\//.test(preferred)) urls.add(preferred);
+  for (const port of CANDIDATE_PORTS) urls.add(`http://localhost:${port}`);
+  const results = await Promise.all([...urls].map((u) => probe(u)));
+  return results.filter((r) => r !== null);
+}
+
+// src/mcp/server.ts
+function urlAsk(found, hasConfig) {
+  const lines = ["No URL was specified \u2014 I won't guess which app to record."];
+  if (found.length) {
+    lines.push("", "Apps currently running on localhost:");
+    for (const f of found) lines.push(`- ${f.url}${f.title ? ` \u2014 ${f.title}` : ""}`);
+    lines.push("", "Ask the user which of these to record (confirm the exact URL), then call start_recording again with that `url`.");
+  } else {
+    lines.push(
+      "",
+      "Nothing is responding on common localhost ports \u2014 the project may not be running locally.",
+      "Ask the user for the URL to record: their local dev server URL, or a staging / production URL. Then call start_recording with that `url`."
+    );
+  }
+  if (hasConfig) {
+    lines.push(
+      "",
+      "Alternatively, if the user wants PR Preview to start the project's own dev server (from pr-preview.config.js), call start_recording with `useDevServer: true`."
+    );
+  }
+  return lines.join("\n");
+}
+async function startMcpServer(repoRoot) {
+  const recorder = new PreviewRecorder(repoRoot);
+  const server = new McpServer({
+    name: "pr-preview",
+    version: "0.1.0"
+  });
+  const text = (s) => ({ content: [{ type: "text", text: s }] });
+  const fail = (e) => ({
+    content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }],
+    isError: true
+  });
+  const SNAPSHOT_HINT = "\n\nEach line is an element with a [ref=eN] handle. To act on one, call `act` with that ref. Always take a fresh snapshot after any action that changes the page (refs are only valid for the most recent snapshot).";
+  server.tool(
+    "detect_localhost",
+    "Probe common localhost ports and list the apps currently running. Use this when the user hasn't given a URL, to offer them the running app(s) to record.",
+    {},
+    async () => {
+      try {
+        const found = await detectLocalApps();
+        if (!found.length) {
+          return text(
+            "No app is responding on common localhost ports. Ask the user for a URL to record \u2014 their local dev server, or a staging / production URL."
+          );
+        }
+        return text(
+          "Apps running on localhost:\n" + found.map((f) => `- ${f.url}${f.title ? ` \u2014 ${f.title}` : ""}`).join("\n") + "\n\nAsk the user which one to record, then call start_recording with that url."
+        );
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "start_recording",
+    "Open the user's app in the PR Preview harness \u2014 a real, VISIBLE Chrome window where the app runs inside the harness iframe and the sidebar records each step \u2014 and begin recording. Returns the app's accessibility snapshot so you can pick the first action.\n\nURL handling \u2014 do NOT guess: if the user gave a URL, pass it as `url`. If they did NOT specify one, call this with no `url`; it detects apps on localhost and returns them so you can ASK the user which URL to record. If nothing is running locally, ask the user for a staging or production URL. Only pass `useDevServer: true` when the user explicitly wants PR Preview to start the project's own dev server (from pr-preview.config.js).\n\nmode 'single' (default) records one clip. mode 'before-after' records the SAME journey twice \u2014 first on the PR's base branch, then on your branch \u2014 for a true before/after (uses a managed dev server and requires being on a git branch; `url` is ignored). In before-after mode: drive the journey with `act`, call `next_pass`, redo the SAME journey, then finish.",
+    {
+      url: z2.string().optional().describe("URL of an already-running app to record (ask the user if unsure)"),
+      mode: z2.enum(["single", "before-after"]).optional(),
+      useDevServer: z2.boolean().optional().describe("Start the project's own dev server from pr-preview.config.js instead of using a URL")
+    },
+    async ({ url, mode, useDevServer }) => {
+      try {
+        const m = mode ?? "single";
+        if (m === "single" && !url && !useDevServer) {
+          const found = await detectLocalApps();
+          let hasConfig = false;
+          try {
+            await loadConfig(repoRoot);
+            hasConfig = true;
+          } catch {
+          }
+          return text(urlAsk(found, hasConfig));
+        }
+        const r = await recorder.start({ url, mode });
+        const win = "A Chrome window has opened with the PR Preview harness \u2014 the app is running in the iframe and the sidebar records each step.";
+        const hint = r.mode === "before-after" ? "\n\nThis is the BEFORE pass (base branch). Perform the journey, then call `next_pass`." : "";
+        return text(`${win}
+Recording started at ${r.startUrl}. Current page:
+
+${r.snapshot}${SNAPSHOT_HINT}${hint}`);
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "next_pass",
+    "before-after mode only: finish the BEFORE clip, switch the app to your branch, and begin the AFTER recording. After calling this, redo the SAME journey with `act`, then call `finish_recording`.",
+    {},
+    async () => {
+      try {
+        const { snapshot } = await recorder.nextPass();
+        return text(
+          `BEFORE clip captured. Now recording the AFTER pass (your branch) \u2014 redo the same journey.
+
+${snapshot}${SNAPSHOT_HINT}`
+        );
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "snapshot",
+    "Return the current accessibility snapshot of the app (elements with [ref=eN] handles). Use this to see the page before choosing the next action.",
+    {},
+    async () => {
+      try {
+        return text(await recorder.snapshot() + SNAPSHOT_HINT);
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "act",
+    "Perform one action in the app, then return the fresh snapshot. Actions: `click` (ref), `fill` (ref + text), `press` (ref + key, e.g. Enter), `hover` (ref), `navigate` (url or path), `scroll` (optional ref to scroll into view), `wait` (ms). The action is recorded into the live clip.",
+    {
+      action: z2.enum(["click", "fill", "press", "hover", "navigate", "scroll", "wait"]),
+      ref: z2.string().optional().describe("Element ref from the latest snapshot, e.g. e14"),
+      text: z2.string().optional().describe("Text to type (for fill)"),
+      key: z2.string().optional().describe("Key to press, e.g. Enter (for press)"),
+      url: z2.string().optional().describe("URL or path (for navigate)"),
+      ms: z2.number().optional().describe("Milliseconds to pause (for wait)")
+    },
+    async (args) => {
+      try {
+        const { snapshot } = await recorder.act(args);
+        return text(`Done: ${args.action}. Current page:
+
+${snapshot}${SNAPSHOT_HINT}`);
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "finish_recording",
+    "Stop recording, encode the clip, and return the output file path(s). Call this when the journey is complete. `name` optionally sets the output filename.",
+    { name: z2.string().optional() },
+    async ({ name }) => {
+      try {
+        const { files, fellBackToGif } = await recorder.finish({ name });
+        const rel = files.map((f) => path14.relative(repoRoot, f));
+        const note = fellBackToGif ? "\n(ffmpeg was not found, so a GIF was produced instead of MP4 \u2014 `brew install ffmpeg` for MP4.)" : "";
+        return text(
+          `Recording complete. Output:
+${rel.map((r) => `  - ${r}`).join("\n")}${note}
+
+Drag the file into your PR description to embed it, or commit it and open the PR.`
+        );
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "open_pr",
+    "Commit the recorded clip into the repo, push the current branch, and open a pull request with the preview embedded in the body. Pass the file path(s) returned by finish_recording. Requires the GitHub CLI (gh) authenticated and an `origin` remote. Note: GitHub only plays inline video from its own CDN, so this embeds an animated GIF (rendered inline) and links the full MP4. Side effects: it creates a commit on your branch and pushes it.",
+    {
+      files: z2.array(z2.string()).describe("Clip file path(s) from finish_recording"),
+      title: z2.string().optional().describe("PR title (defaults to 'Preview: <branch>')"),
+      base: z2.string().optional().describe("Base branch for the PR (e.g. main)")
+    },
+    async ({ files, title, base }) => {
+      try {
+        const { prUrl, committed, embedded } = await openPr(repoRoot, files, { title, base });
+        const how = embedded === "gif" ? "an inline GIF preview" : "a link to the MP4";
+        return text(
+          `Pull request opened: ${prUrl}
+Committed ${committed.length} file(s) under pr-preview/ and embedded ${how}.`
+        );
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  server.tool(
+    "cancel_recording",
+    "Abort the current recording and close the browser without producing a clip.",
+    {},
+    async () => {
+      try {
+        await recorder.dispose();
+        return text("Recording cancelled \u2014 browser closed, no clip produced.");
+      } catch (e) {
+        return fail(e);
+      }
+    }
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  await new Promise((resolve) => {
+    transport.onclose = () => {
+      void recorder.dispose().finally(resolve);
+    };
+  });
+}
+
+// src/cli/commands/mcp.ts
+async function mcpCommand(repoRoot) {
+  const toStderr = (...args) => {
+    process.stderr.write(
+      args.map((a) => typeof a === "string" ? a : String(a)).join(" ") + "\n"
+    );
+  };
+  console.log = toStderr;
+  console.info = toStderr;
+  console.warn = toStderr;
+  console.debug = toStderr;
+  await startMcpServer(repoRoot);
+}
+
+// src/cli/commands/record.ts
+import path16 from "path";
+import pc2 from "picocolors";
+
+// src/recorder/journey.ts
+import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir5 } from "fs/promises";
+import path15 from "path";
+import { z as z3 } from "zod";
+var stepSchema = z3.object({
+  id: z3.string(),
+  type: z3.enum(["click", "fill", "select", "press", "scroll", "navigate", "wait"]),
+  selectors: z3.array(z3.string()).optional(),
+  coordinates: z3.object({ xNorm: z3.number(), yNorm: z3.number() }).optional(),
+  frameUrl: z3.string().optional(),
+  value: z3.string().optional(),
+  key: z3.string().optional(),
+  scrollTarget: z3.string().optional(),
+  scroll: z3.object({ xNorm: z3.number(), yNorm: z3.number() }).optional(),
+  url: z3.string().optional(),
+  causesNavigation: z3.boolean().optional(),
+  label: z3.string().optional(),
+  timestamp: z3.number(),
+  thumbnail: z3.string().optional()
+});
+var journeySchema = z3.object({
+  version: z3.literal(1),
+  createdAt: z3.string(),
+  baseRef: z3.string().optional(),
+  viewport: z3.object({
+    width: z3.number(),
+    height: z3.number(),
+    deviceScaleFactor: z3.number()
+  }),
+  startUrl: z3.string(),
+  steps: z3.array(stepSchema)
+});
+async function saveJourney(file, journey) {
+  const clean = {
+    ...journey,
+    steps: journey.steps.map((s) => {
+      const { thumbnail: _thumbnail, ...rest } = s;
+      return rest;
+    })
+  };
+  await mkdir5(path15.dirname(file), { recursive: true });
+  await writeFile4(file, JSON.stringify(clean, null, 2) + "\n");
+}
+
+// src/cli/commands/record.ts
+async function recordCommand(repoRoot, opts) {
+  const { config } = await loadConfig(repoRoot);
+  const journeyFile = path16.resolve(repoRoot, opts.out ?? ".pr-preview/journey.json");
+  try {
+    const boot = await bootstrap(repoRoot, config, "record");
+    await boot.startApp("after", repoRoot);
+    await boot.openBrowser("after");
+    log.info(`Harness open at ${pc2.bold(boot.harness.url)}`);
+    log.step("Click Record in the sidebar, perform the journey, then Confirm.");
+    const steps = await boot.session.recordUntilConfirmed();
+    if (steps.length === 0) {
+      log.warn("No steps recorded \u2014 nothing saved.");
+      return;
+    }
+    await saveJourney(journeyFile, {
+      version: 1,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      viewport: { ...config.viewport, deviceScaleFactor: 2 },
+      startUrl: boot.session.startUrl,
+      steps
+    });
+    log.success(`Saved ${steps.length} steps to ${path16.relative(repoRoot, journeyFile)}`);
+  } finally {
+    await runCleanups();
+  }
+}
+
+// src/cli/commands/run.ts
+import { existsSync as existsSync10 } from "fs";
+import path17 from "path";
+import pc3 from "picocolors";
+
 // src/cli/util/openPath.ts
 import { spawn as spawn4 } from "child_process";
 function openPath(target) {
@@ -1992,25 +2887,25 @@ function revealFiles(files, dir) {
 function captureClip(session, which, outBase, label) {
   return session.encodeClip(which, outBase, label);
 }
-function stamp() {
+function stamp2() {
   const d = /* @__PURE__ */ new Date();
   const p = (n) => String(n).padStart(2, "0");
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 }
-function shortRef(ref) {
+function shortRef2(ref) {
   return ref.replace(/^origin\//, "");
 }
-function slug(ref) {
-  return shortRef(ref).replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+function slug2(ref) {
+  return shortRef2(ref).replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function fileStamp() {
+function fileStamp2() {
   const d = /* @__PURE__ */ new Date();
   const p = (n) => String(n).padStart(2, "0");
   return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`;
 }
 async function branchName(repoRoot, fallback) {
   const ref = await tryGit(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
-  return ref ? shortRef(ref) : fallback;
+  return ref ? shortRef2(ref) : fallback;
 }
 async function runCommand(repoRoot, opts) {
   let config;
@@ -2030,7 +2925,7 @@ async function runCommand(repoRoot, opts) {
     keepWorktree: opts.keepWorktree ?? config.keepWorktree,
     single: opts.single
   };
-  const outDir = path14.resolve(repoRoot, config.output);
+  const outDir = path17.resolve(repoRoot, config.output);
   const passes = opts.single ? 1 : config.passes;
   if (passes === 1) return runSingleClip(repoRoot, config, outDir, opts);
   if (opts.url) return runWithExternalApp(repoRoot, config, outDir, opts);
@@ -2048,11 +2943,11 @@ async function runCommand(repoRoot, opts) {
     }
     const worktree = await createBaseWorktree(repoRoot, base.sha);
     if (!opts.keepWorktree) registerCleanup(() => worktree.remove());
-    log.success(`Base worktree at ${path14.relative(repoRoot, worktree.dir)}`);
+    log.success(`Base worktree at ${path17.relative(repoRoot, worktree.dir)}`);
     if (config.install !== "never") {
-      const appDir = path14.join(worktree.dir, config.cwd);
+      const appDir = path17.join(worktree.dir, config.cwd);
       const pm = detectPackageManager(appDir);
-      const hasModules = existsSync8(path14.join(appDir, "node_modules"));
+      const hasModules = existsSync10(path17.join(appDir, "node_modules"));
       if (config.install === "always" || !hasModules) {
         const spinner = log.spinner(`Installing dependencies in worktree (${pm}) \u2026`);
         try {
@@ -2075,21 +2970,21 @@ async function runCommand(repoRoot, opts) {
     const beforeSteps = await boot.session.recordUntilConfirmed();
     if (beforeSteps.length === 0) throw new Error("No steps recorded for BEFORE \u2014 aborting.");
     await saveJourneyFile(repoRoot, "journey-before.json", config, boot.session.startUrl, beforeSteps, base.sha);
-    const timestamp = stamp();
-    const fstamp = fileStamp();
-    const baseLabel = shortRef(base.ref);
-    const headLabel = shortRef(currentBranch);
+    const timestamp = stamp2();
+    const fstamp = fileStamp2();
+    const baseLabel = shortRef2(base.ref);
+    const headLabel = shortRef2(currentBranch);
     log.info("Capturing BEFORE \u2026");
     const before = await captureClip(
       boot.session,
       "before",
-      path14.join(outDir, `before-${slug(base.ref)}-${fstamp}`),
+      path17.join(outDir, `before-${slug2(base.ref)}-${fstamp}`),
       { branch: baseLabel, baseBranch: baseLabel, timestamp }
     );
     if (before.fellBackToGif) {
       log.warn("ffmpeg not found \u2014 produced a GIF instead of MP4 (brew install ffmpeg).");
     }
-    log.success(`${before.paths.map((p) => path14.basename(p)).join(" + ")} (${before.frameCount} frames)`);
+    log.success(`${before.paths.map((p) => path17.basename(p)).join(" + ")} (${before.frameCount} frames)`);
     await beforeServer.stop();
     await boot.startApp("after", repoRoot);
     boot.session.switchPass("after");
@@ -2106,10 +3001,10 @@ async function runCommand(repoRoot, opts) {
     const after = await captureClip(
       boot.session,
       "after",
-      path14.join(outDir, `after-${slug(currentBranch)}-${fstamp}`),
+      path17.join(outDir, `after-${slug2(currentBranch)}-${fstamp}`),
       { branch: headLabel, baseBranch: baseLabel, timestamp }
     );
-    log.success(`${after.paths.map((p) => path14.basename(p)).join(" + ")} (${after.frameCount} frames)`);
+    log.success(`${after.paths.map((p) => path17.basename(p)).join(" + ")} (${after.frameCount} frames)`);
     boot.session.setPhase("done");
     boot.harness.bus.send({
       type: "DONE",
@@ -2118,7 +3013,7 @@ async function runCommand(repoRoot, opts) {
     console.log();
     log.success(pc3.bold("Done \u2014 drag these into your PR description:"));
     for (const p of [...before.paths, ...after.paths]) {
-      log.step(path14.relative(repoRoot, p));
+      log.step(path17.relative(repoRoot, p));
     }
     revealFiles([...before.paths, ...after.paths], outDir);
   } finally {
@@ -2143,12 +3038,12 @@ async function runSingleClip(repoRoot, config, outDir, opts) {
     const steps = await boot.session.recordUntilConfirmed();
     if (steps.length === 0) throw new Error("No steps recorded \u2014 aborting.");
     await saveJourneyFile(repoRoot, "journey.json", config, boot.session.startUrl, steps);
-    const timestamp = stamp();
+    const timestamp = stamp2();
     log.info("Capturing the clip \u2026");
     const clip = await captureClip(
       boot.session,
       "before",
-      path14.join(outDir, `${slug(branch)}-${fileStamp()}`),
+      path17.join(outDir, `${slug2(branch)}-${fileStamp2()}`),
       { branch, baseBranch: branch, timestamp }
     );
     if (clip.fellBackToGif) {
@@ -2159,7 +3054,7 @@ async function runSingleClip(repoRoot, config, outDir, opts) {
     boot.harness.bus.send({ type: "DONE", outputs: { before: clip.paths[0] } });
     console.log();
     log.success(pc3.bold("Done \u2014 your clip:"));
-    for (const p of clip.paths) log.step(path14.relative(repoRoot, p));
+    for (const p of clip.paths) log.step(path17.relative(repoRoot, p));
     revealFiles(clip.paths, outDir);
   } finally {
     await runCleanups();
@@ -2178,17 +3073,17 @@ async function runWithExternalApp(repoRoot, config, outDir, opts) {
     await boot.session.promptResetChoice();
     const beforeSteps = await boot.session.recordUntilConfirmed();
     if (beforeSteps.length === 0) throw new Error("No steps recorded for BEFORE \u2014 aborting.");
-    const timestamp = stamp();
-    const fstamp = fileStamp();
+    const timestamp = stamp2();
+    const fstamp = fileStamp2();
     await saveJourneyFile(repoRoot, "journey-before.json", config, boot.session.startUrl, beforeSteps);
     log.info("Capturing BEFORE \u2026");
     const before = await captureClip(
       boot.session,
       "before",
-      path14.join(outDir, `before-${slug(beforeBranch)}-${fstamp}`),
+      path17.join(outDir, `before-${slug2(beforeBranch)}-${fstamp}`),
       { branch: beforeBranch, baseBranch: beforeBranch, timestamp }
     );
-    log.success(`${before.paths.map((p) => path14.basename(p)).join(" + ")} (${before.frameCount} frames)`);
+    log.success(`${before.paths.map((p) => path17.basename(p)).join(" + ")} (${before.frameCount} frames)`);
     log.info(pc3.bold("\u2192 Switch your app to the PR branch and restart it on the same URL, then Continue in the harness."));
     boot.harness.bus.send({
       type: "MANUAL_PAUSE",
@@ -2211,22 +3106,22 @@ async function runWithExternalApp(repoRoot, config, outDir, opts) {
     const after = await captureClip(
       boot.session,
       "after",
-      path14.join(outDir, `after-${slug(afterBranch)}-${fstamp}`),
+      path17.join(outDir, `after-${slug2(afterBranch)}-${fstamp}`),
       { branch: afterBranch, baseBranch: beforeBranch, timestamp }
     );
-    log.success(`${after.paths.map((p) => path14.basename(p)).join(" + ")} (${after.frameCount} frames)`);
+    log.success(`${after.paths.map((p) => path17.basename(p)).join(" + ")} (${after.frameCount} frames)`);
     boot.session.setPhase("done");
     boot.harness.bus.send({ type: "DONE", outputs: { before: before.paths[0], after: after.paths[0] } });
     console.log();
     log.success(pc3.bold("Done \u2014 drag these into your PR description:"));
-    for (const p of [...before.paths, ...after.paths]) log.step(path14.relative(repoRoot, p));
+    for (const p of [...before.paths, ...after.paths]) log.step(path17.relative(repoRoot, p));
     revealFiles([...before.paths, ...after.paths], outDir);
   } finally {
     await runCleanups();
   }
 }
 async function saveJourneyFile(repoRoot, name, config, startUrl, steps, baseRef) {
-  await saveJourney(path14.join(repoRoot, ".pr-preview", name), {
+  await saveJourney(path17.join(repoRoot, ".pr-preview", name), {
     version: 1,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     baseRef,
@@ -2273,6 +3168,9 @@ Notes:
   \u2022 Without --url, a before/after run needs a git repo and to be on a branch with commits
     beyond its base (it records the base in a throwaway worktree, your branch in place).`
 ).action((opts) => wrap(() => runCommand(process.cwd(), opts)));
+program.command("mcp").description(
+  "Run the Model Context Protocol server (stdio) so Claude Code can drive a recording from a prompt"
+).action(() => wrap(() => mcpCommand(process.cwd())));
 async function wrap(fn) {
   try {
     await fn();