demo-this-pr 0.1.0

package/dist/playwright.js

@@ -0,0 +1,846 @@
+import { cp, mkdir, readdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join, relative } from "node:path";
+import { chromium } from "@playwright/test";
+import { runProcess } from "./shell.js";
+const require = createRequire(import.meta.url);
+const ffmpegPath = require("ffmpeg-static");
+const INTRO_HOLD_MS = 3600;
+const CAPTION_HOLD_MS = 900;
+const POINTER_HOLD_MS = 1300;
+const AFTER_ACTION_HOLD_MS = 1100;
+export async function writePlaywrightArtifacts(outputDir, plan) {
+    const assetsDir = join(outputDir, "assets");
+    await mkdir(join(assetsDir, "screenshots"), { recursive: true });
+    await mkdir(join(assetsDir, "mcp-screenshots"), { recursive: true });
+    await mkdir(join(assetsDir, "test-results"), { recursive: true });
+    const specPath = join(outputDir, "pr-demo.spec.ts");
+    const configPath = join(outputDir, "playwright.config.ts");
+    const planPath = join(outputDir, "demo-plan.json");
+    const mcpGuidePath = join(outputDir, "MCP_PLAYWRIGHT.md");
+    const mcpScriptPath = join(outputDir, "mcp-playwright-demo.js");
+    await writeFile(planPath, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+    await writeFile(specPath, renderSpec(plan, assetsDir), "utf8");
+    await writeFile(configPath, renderConfig(outputDir), "utf8");
+    await writeFile(mcpScriptPath, renderMcpScript(plan, assetsDir), "utf8");
+    await writeFile(mcpGuidePath, renderMcpGuide(plan, mcpScriptPath, outputDir), "utf8");
+    return { specPath, configPath, planPath, mcpGuidePath, mcpScriptPath };
+}
+export async function runPlaywrightDemo(outputDir, plan, options) {
+    const assetsDir = join(outputDir, "assets");
+    const videoDir = join(assetsDir, "test-results", "programmatic-video");
+    await mkdir(videoDir, { recursive: true });
+    let browser;
+    let webmPath;
+    try {
+        browser = await chromium.launch({ headless: !options.headed, slowMo: options.headed ? 260 : 120 });
+        const context = await browser.newContext({
+            viewport: { width: 1440, height: 900 },
+            recordVideo: {
+                dir: videoDir,
+                size: { width: 1440, height: 900 }
+            }
+        });
+        const page = await context.newPage();
+        await runDemoPlan(page, plan, assetsDir);
+        const video = page.video();
+        await context.close();
+        await browser.close();
+        browser = undefined;
+        const rawVideoPath = await video?.path();
+        if (rawVideoPath) {
+            webmPath = await copyVideo(rawVideoPath, outputDir);
+        }
+        const conversion = webmPath ? await convertToMp4(outputDir, webmPath) : { mp4Path: undefined, error: undefined };
+        return {
+            attempted: true,
+            passed: true,
+            command: "playwright chromium programmatic demo",
+            output: `Recorded ${plan.steps.length} step(s).`,
+            videoPath: conversion.mp4Path ?? webmPath,
+            webmPath,
+            mp4Path: conversion.mp4Path,
+            conversionError: conversion.error
+        };
+    }
+    catch (error) {
+        await browser?.close();
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            attempted: true,
+            passed: false,
+            command: "playwright chromium programmatic demo",
+            output: message,
+            webmPath,
+            videoPath: webmPath,
+            error: message
+        };
+    }
+}
+function renderConfig(outputDir) {
+    return `import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: ".",
+  outputDir: ${JSON.stringify(join(outputDir, "assets", "test-results"))},
+  timeout: 60_000,
+  reporter: [["list"], ["html", { outputFolder: ${JSON.stringify(join(outputDir, "assets", "playwright-report"))}, open: "never" }]],
+  use: {
+    ...devices["Desktop Chrome"],
+    video: "on",
+    screenshot: "only-on-failure",
+    trace: "retain-on-failure",
+    viewport: { width: 1440, height: 900 },
+    launchOptions: { slowMo: 120 }
+  },
+  projects: [{ name: "chromium" }]
+});
+`;
+}
+function renderSpec(plan, assetsDir) {
+    return `import { expect, test, type Page } from "@playwright/test";
+
+const plan = ${JSON.stringify(plan, null, 2)} as const;
+const assetsDir = ${JSON.stringify(assetsDir)};
+
+test(plan.title, async ({ page }) => {
+  await showIntro(page, plan);
+
+  for (const [index, step] of plan.steps.entries()) {
+    await showCaption(page, step.caption ?? actionLabel(step), index + 1, plan.steps.length);
+
+    if ("goto" in step && step.goto) {
+      if (!plan.baseUrl) {
+        throw new Error("Demo step uses goto but baseUrl is missing.");
+      }
+      await page.goto(resolveUrl(plan.baseUrl, step.goto));
+    }
+
+    if ("click" in step && step.click) {
+      const target = page.locator(step.click).first();
+      await pointAtLocator(page, target, \`Click \${step.click}\`);
+      await target.click();
+    }
+
+    if ("fill" in step && step.fill) {
+      const target = page.locator(step.fill.selector).first();
+      await pointAtLocator(page, target, \`Fill \${step.fill.selector}\`);
+      await target.fill(step.fill.value);
+    }
+
+    if ("press" in step && step.press) {
+      const target = page.locator(step.press.selector).first();
+      await pointAtLocator(page, target, \`Press \${step.press.key}\`);
+      await target.press(step.press.key);
+    }
+
+    if ("expectText" in step && step.expectText) {
+      const target = page.getByText(step.expectText, { exact: false }).first();
+      await expect(target).toBeVisible();
+      await pointAtLocator(page, target, \`Verify \${step.expectText}\`);
+    }
+
+    if ("waitMs" in step && step.waitMs !== undefined) {
+      await page.waitForTimeout(step.waitMs);
+    }
+
+    if ("screenshot" in step && step.screenshot) {
+      await page.screenshot({ path: \`\${assetsDir}/screenshots/\${String(index + 1).padStart(2, "0")}-\${slug(step.screenshot)}.png\`, fullPage: true });
+    }
+
+    await page.waitForTimeout(250);
+  }
+});
+
+async function showCaption(page: Page, caption: string, index: number, total: number) {
+  await page.evaluate(
+    ({ caption, index, total }) => {
+      const id = "__demo_this_pr_caption";
+      let element = document.getElementById(id);
+      if (!element) {
+        element = document.createElement("div");
+        element.id = id;
+        document.body.appendChild(element);
+      }
+      element.textContent = \`\${index}/\${total} · \${caption}\`;
+      Object.assign(element.style, {
+        position: "fixed",
+        left: "24px",
+        bottom: "24px",
+        zIndex: "2147483647",
+        maxWidth: "760px",
+        padding: "12px 14px",
+        borderRadius: "8px",
+        background: "rgba(12, 18, 28, 0.92)",
+        color: "#fff",
+        font: "500 15px/1.4 system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        boxShadow: "0 12px 32px rgba(0,0,0,.24)"
+      });
+    },
+    { caption, index, total }
+  );
+}
+
+async function showIntro(page: Page, demoPlan: typeof plan) {
+  await page.setContent(renderIntroHtml(demoPlan));
+  await page.waitForTimeout(2200);
+}
+
+async function pointAtLocator(page: Page, locator: import("@playwright/test").Locator, label: string) {
+  await locator.scrollIntoViewIfNeeded();
+  const box = await locator.boundingBox();
+  if (!box) {
+    return;
+  }
+
+  const x = box.x + box.width / 2;
+  const y = box.y + box.height / 2;
+  await page.mouse.move(x, y, { steps: 18 });
+  await page.evaluate(
+    ({ x, y, label }) => {
+      let cursor = document.getElementById("__demo_this_pr_cursor");
+      if (!cursor) {
+        cursor = document.createElement("div");
+        cursor.id = "__demo_this_pr_cursor";
+        cursor.innerHTML = \`<div class="dot"></div><div class="label"></div>\`;
+        document.body.appendChild(cursor);
+      }
+
+      Object.assign(cursor.style, {
+        position: "fixed",
+        left: \`\${x}px\`,
+        top: \`\${y}px\`,
+        transform: "translate(-8px, -8px)",
+        zIndex: "2147483647",
+        pointerEvents: "none",
+        transition: "left 260ms ease, top 260ms ease"
+      });
+
+      const dot = cursor.querySelector(".dot") as HTMLElement;
+      Object.assign(dot.style, {
+        width: "18px",
+        height: "18px",
+        borderRadius: "999px",
+        background: "#38bdf8",
+        border: "3px solid #ffffff",
+        boxShadow: "0 0 0 8px rgba(56, 189, 248, .22), 0 8px 20px rgba(0,0,0,.28)"
+      });
+
+      const labelEl = cursor.querySelector(".label") as HTMLElement;
+      labelEl.textContent = label;
+      Object.assign(labelEl.style, {
+        margin: "8px 0 0 12px",
+        padding: "7px 10px",
+        borderRadius: "8px",
+        background: "rgba(15, 23, 42, .92)",
+        color: "#fff",
+        font: "600 13px/1.3 system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        whiteSpace: "nowrap",
+        boxShadow: "0 8px 24px rgba(0,0,0,.22)"
+      });
+    },
+    { x, y, label }
+  );
+  await page.waitForTimeout(550);
+}
+
+function section(title: string, items: readonly string[]) {
+  if (!items.length) return "";
+  return \`
+    <div style="margin-top:18px">
+      <h2 style="font-size:13px;color:#93c5fd;text-transform:uppercase;letter-spacing:.08em;margin:0 0 8px">\${escapeHtml(title)}</h2>
+      <ul style="margin:0;padding-left:20px;color:#e2e8f0">\${items.map((item) => \`<li style="margin:4px 0">\${escapeHtml(item)}</li>\`).join("")}</ul>
+    </div>
+  \`;
+}
+
+function renderIntroHtml(demoPlan: typeof plan) {
+  const tests = demoPlan.context?.tests ?? [];
+  const changes = demoPlan.context?.changes ?? [];
+  const technologies = demoPlan.context?.technologies ?? [];
+  const files = demoPlan.context?.changedFiles ?? [];
+
+  return \`<!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <title>\${escapeHtml(demoPlan.title)}</title>
+      </head>
+      <body style="margin:0;background:#0f172a;color:#e5edf7;font:15px/1.45 system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif">
+        <section style="max-width:980px;margin:72px auto;padding:32px;border:1px solid rgba(148,163,184,.35);border-radius:14px;background:rgba(15,23,42,.92);box-shadow:0 24px 80px rgba(0,0,0,.35)">
+          <div style="color:#93c5fd;text-transform:uppercase;font-weight:700;font-size:12px;letter-spacing:.08em">Demo this PR</div>
+          <h1 style="font-size:34px;line-height:1.1;margin:10px 0 12px">\${escapeHtml(demoPlan.title)}</h1>
+          <p style="font-size:18px;color:#cbd5e1;margin:0 0 24px">\${escapeHtml(demoPlan.why ?? "Review the changed behavior.")}</p>
+          \${section("What changed", changes)}
+          \${section("Technology used", technologies)}
+          \${section("Tests", tests.map((test) => \`\${test.status.toUpperCase()} · \${test.command} · \${formatMs(test.durationMs)}\`))}
+          \${section("Changed files", files.slice(0, 6))}
+          <p style="color:#94a3b8;margin:24px 0 0">Video is local-only evidence for review. It is not meant to be committed or uploaded automatically.</p>
+        </section>
+      </body>
+    </html>\`;
+}
+
+function escapeHtml(value: string) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function formatMs(ms: number) {
+  return ms < 1000 ? \`\${ms}ms\` : \`\${(ms / 1000).toFixed(1)}s\`;
+}
+
+function resolveUrl(baseUrl: string, target: string) {
+  return new URL(target, baseUrl).toString();
+}
+
+function actionLabel(step: Record<string, unknown>) {
+  if (step.goto) return \`Open \${step.goto}\`;
+  if (step.click) return \`Click \${step.click}\`;
+  if (step.fill && typeof step.fill === "object") return "Fill field";
+  if (step.press && typeof step.press === "object") return "Press key";
+  if (step.expectText) return \`Verify \${step.expectText}\`;
+  if (step.screenshot) return \`Capture \${step.screenshot}\`;
+  if (step.waitMs) return \`Wait \${step.waitMs}ms\`;
+  return "Demo step";
+}
+
+function slug(value: string) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "step";
+}
+`;
+}
+async function runDemoPlan(page, plan, assetsDir) {
+    await showRuntimeIntro(page, plan);
+    for (const [index, step] of plan.steps.entries()) {
+        await showRuntimeCaption(page, step.caption ?? describeStep(step), index + 1, plan.steps.length);
+        await page.waitForTimeout(CAPTION_HOLD_MS);
+        if (step.goto) {
+            if (!plan.baseUrl) {
+                throw new Error("Demo step uses goto but baseUrl is missing.");
+            }
+            await page.goto(resolveRuntimeUrl(plan.baseUrl, step.goto));
+            await page.waitForTimeout(AFTER_ACTION_HOLD_MS);
+        }
+        if (step.click) {
+            const target = page.locator(step.click).first();
+            await pointAtRuntimeLocator(page, target, `Click ${step.click}`);
+            await target.click();
+            await page.waitForTimeout(AFTER_ACTION_HOLD_MS);
+        }
+        if (step.fill) {
+            const target = page.locator(step.fill.selector).first();
+            await pointAtRuntimeLocator(page, target, `Fill ${step.fill.selector}`);
+            await target.fill(step.fill.value);
+            await page.waitForTimeout(AFTER_ACTION_HOLD_MS);
+        }
+        if (step.press) {
+            const target = page.locator(step.press.selector).first();
+            await pointAtRuntimeLocator(page, target, `Press ${step.press.key}`);
+            await target.press(step.press.key);
+            await page.waitForTimeout(AFTER_ACTION_HOLD_MS);
+        }
+        if (step.expectText) {
+            const target = page.getByText(step.expectText, { exact: false }).first();
+            await target.waitFor({ state: "visible", timeout: 15_000 });
+            await pointAtRuntimeLocator(page, target, `Verify ${step.expectText}`);
+            await page.waitForTimeout(AFTER_ACTION_HOLD_MS);
+        }
+        if (step.waitMs !== undefined) {
+            await page.waitForTimeout(step.waitMs);
+        }
+        if (step.screenshot) {
+            await page.screenshot({ path: `${assetsDir}/screenshots/${String(index + 1).padStart(2, "0")}-${slugRuntime(step.screenshot)}.png`, fullPage: true });
+        }
+        await page.waitForTimeout(700);
+    }
+}
+async function showRuntimeIntro(page, plan) {
+    await page.setContent(renderRuntimeIntroHtml(plan));
+    await page.waitForTimeout(INTRO_HOLD_MS);
+}
+async function showRuntimeCaption(page, caption, index, total) {
+    await page.evaluate(({ caption, index, total }) => {
+        const id = "__demo_this_pr_caption";
+        let element = document.getElementById(id);
+        if (!element) {
+            element = document.createElement("div");
+            element.id = id;
+            document.body.appendChild(element);
+        }
+        element.textContent = `${index}/${total} · ${caption}`;
+        Object.assign(element.style, {
+            position: "fixed",
+            left: "24px",
+            bottom: "24px",
+            zIndex: "2147483647",
+            maxWidth: "760px",
+            padding: "12px 14px",
+            borderRadius: "8px",
+            background: "rgba(12, 18, 28, 0.92)",
+            color: "#fff",
+            font: "500 15px/1.4 system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+            boxShadow: "0 12px 32px rgba(0,0,0,.24)"
+        });
+    }, { caption, index, total });
+}
+async function pointAtRuntimeLocator(page, locator, label) {
+    await locator.scrollIntoViewIfNeeded();
+    const box = await locator.boundingBox();
+    if (!box) {
+        return;
+    }
+    const x = box.x + box.width / 2;
+    const y = box.y + box.height / 2;
+    await page.mouse.move(x, y, { steps: 42 });
+    await page.evaluate(({ x, y, label, box }) => {
+        let highlight = document.getElementById("__demo_this_pr_highlight");
+        if (!highlight) {
+            highlight = document.createElement("div");
+            highlight.id = "__demo_this_pr_highlight";
+            document.body.appendChild(highlight);
+        }
+        Object.assign(highlight.style, {
+            position: "fixed",
+            left: `${Math.max(box.x - 8, 0)}px`,
+            top: `${Math.max(box.y - 8, 0)}px`,
+            width: `${box.width + 16}px`,
+            height: `${box.height + 16}px`,
+            zIndex: "2147483646",
+            pointerEvents: "none",
+            border: "4px solid #38bdf8",
+            borderRadius: "10px",
+            boxShadow: "0 0 0 8px rgba(56,189,248,.22), 0 0 34px rgba(14,165,233,.45)",
+            transition: "left 320ms ease, top 320ms ease, width 320ms ease, height 320ms ease"
+        });
+        let cursor = document.getElementById("__demo_this_pr_cursor");
+        if (!cursor) {
+            cursor = document.createElement("div");
+            cursor.id = "__demo_this_pr_cursor";
+            cursor.innerHTML = `<div class="dot"></div><div class="label"></div>`;
+            document.body.appendChild(cursor);
+        }
+        Object.assign(cursor.style, {
+            position: "fixed",
+            left: `${x}px`,
+            top: `${y}px`,
+            transform: "translate(-8px, -8px)",
+            zIndex: "2147483647",
+            pointerEvents: "none",
+            transition: "left 260ms ease, top 260ms ease"
+        });
+        const dot = cursor.querySelector(".dot");
+        Object.assign(dot.style, {
+            width: "18px",
+            height: "18px",
+            borderRadius: "999px",
+            background: "#38bdf8",
+            border: "3px solid #ffffff",
+            boxShadow: "0 0 0 8px rgba(56, 189, 248, .22), 0 8px 20px rgba(0,0,0,.28)"
+        });
+        const labelEl = cursor.querySelector(".label");
+        labelEl.textContent = label;
+        Object.assign(labelEl.style, {
+            margin: "8px 0 0 12px",
+            padding: "7px 10px",
+            borderRadius: "8px",
+            background: "rgba(15, 23, 42, .92)",
+            color: "#fff",
+            font: "600 13px/1.3 system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+            whiteSpace: "nowrap",
+            boxShadow: "0 8px 24px rgba(0,0,0,.22)"
+        });
+    }, { x, y, label, box });
+    await page.waitForTimeout(POINTER_HOLD_MS);
+}
+function renderRuntimeIntroHtml(plan) {
+    const tests = plan.context?.tests ?? [];
+    const changes = plan.context?.changes ?? [];
+    const technologies = plan.context?.technologies ?? [];
+    const files = plan.context?.changedFiles ?? [];
+    return `<!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <title>${escapeRuntimeHtml(plan.title)}</title>
+      </head>
+      <body style="margin:0;background:#0f172a;color:#e5edf7;font:15px/1.45 system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif">
+        <section style="max-width:980px;margin:72px auto;padding:32px;border:1px solid rgba(148,163,184,.35);border-radius:14px;background:rgba(15,23,42,.92);box-shadow:0 24px 80px rgba(0,0,0,.35)">
+          <div style="color:#93c5fd;text-transform:uppercase;font-weight:700;font-size:12px;letter-spacing:.08em">Demo this PR</div>
+          <h1 style="font-size:34px;line-height:1.1;margin:10px 0 12px">${escapeRuntimeHtml(plan.title)}</h1>
+          <p style="font-size:18px;color:#cbd5e1;margin:0 0 24px">${escapeRuntimeHtml(plan.why ?? "Review the changed behavior.")}</p>
+          ${runtimeSection("What changed", changes)}
+          ${runtimeSection("Technology used", technologies)}
+          ${runtimeSection("Tests", tests.map((test) => `${test.status.toUpperCase()} · ${test.command} · ${formatRuntimeMs(test.durationMs)}`))}
+          ${runtimeSection("Changed files", files.slice(0, 6))}
+          <p style="color:#94a3b8;margin:24px 0 0">Video is local-only evidence for review. It is not meant to be committed or uploaded automatically.</p>
+        </section>
+      </body>
+    </html>`;
+}
+function runtimeSection(title, items) {
+    if (!items.length)
+        return "";
+    return `
+    <div style="margin-top:18px">
+      <h2 style="font-size:13px;color:#93c5fd;text-transform:uppercase;letter-spacing:.08em;margin:0 0 8px">${escapeRuntimeHtml(title)}</h2>
+      <ul style="margin:0;padding-left:20px;color:#e2e8f0">${items.map((item) => `<li style="margin:4px 0">${escapeRuntimeHtml(item)}</li>`).join("")}</ul>
+    </div>
+  `;
+}
+function escapeRuntimeHtml(value) {
+    return String(value).replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/"/gu, "&quot;");
+}
+function formatRuntimeMs(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+function resolveRuntimeUrl(baseUrl, target) {
+    if (/^https?:\/\//iu.test(target))
+        return target;
+    return `${String(baseUrl).replace(/\/+$/u, "")}/${String(target).replace(/^\/+/u, "")}`;
+}
+function slugRuntime(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "").slice(0, 48) || "step";
+}
+function renderMcpScript(plan, assetsDir) {
+    return `(async (page) => {
+  const plan = ${JSON.stringify(plan, null, 2)};
+  const assetsDir = ${JSON.stringify(assetsDir)};
+
+  await showIntro(page, plan);
+
+  for (const [index, step] of plan.steps.entries()) {
+    await showCaption(page, step.caption ?? actionLabel(step), index + 1, plan.steps.length);
+
+    if (step.goto) {
+      if (!plan.baseUrl) {
+        throw new Error("Demo step uses goto but baseUrl is missing.");
+      }
+      await page.goto(resolveUrl(plan.baseUrl, step.goto));
+    }
+
+    if (step.click) {
+      const target = page.locator(step.click).first();
+      await pointAtLocator(page, target, \`Click \${step.click}\`);
+      await target.click();
+    }
+
+    if (step.fill) {
+      const target = page.locator(step.fill.selector).first();
+      await pointAtLocator(page, target, \`Fill \${step.fill.selector}\`);
+      await target.fill(step.fill.value);
+    }
+
+    if (step.press) {
+      const target = page.locator(step.press.selector).first();
+      await pointAtLocator(page, target, \`Press \${step.press.key}\`);
+      await target.press(step.press.key);
+    }
+
+    if (step.expectText) {
+      const target = page.getByText(step.expectText, { exact: false }).first();
+      await target.waitFor({ state: "visible" });
+      await pointAtLocator(page, target, \`Verify \${step.expectText}\`);
+    }
+
+    if (step.waitMs !== undefined) {
+      await page.waitForTimeout(step.waitMs);
+    }
+
+    if (step.screenshot) {
+      await page.screenshot({ path: \`\${assetsDir}/mcp-screenshots/\${String(index + 1).padStart(2, "0")}-\${slug(step.screenshot)}.png\`, fullPage: true });
+    }
+
+    await page.waitForTimeout(250);
+  }
+
+  return {
+    title: plan.title,
+    steps: plan.steps.length,
+    url: page.url(),
+    screenshotsDir: \`\${assetsDir}/mcp-screenshots\`
+  };
+
+async function showCaption(page, caption, index, total) {
+  await page.evaluate(
+    ({ caption, index, total }) => {
+      const id = "__demo_this_pr_caption";
+      let element = document.getElementById(id);
+      if (!element) {
+        element = document.createElement("div");
+        element.id = id;
+        document.body.appendChild(element);
+      }
+      element.textContent = \`\${index}/\${total} · \${caption}\`;
+      Object.assign(element.style, {
+        position: "fixed",
+        left: "24px",
+        bottom: "24px",
+        zIndex: "2147483647",
+        maxWidth: "760px",
+        padding: "12px 14px",
+        borderRadius: "8px",
+        background: "rgba(12, 18, 28, 0.92)",
+        color: "#fff",
+        font: "500 15px/1.4 system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        boxShadow: "0 12px 32px rgba(0,0,0,.24)"
+      });
+    },
+    { caption, index, total }
+  );
+}
+
+async function showIntro(page, demoPlan) {
+  await page.setContent(renderIntroHtml(demoPlan));
+  await page.waitForTimeout(2200);
+}
+
+async function pointAtLocator(page, locator, label) {
+  await locator.scrollIntoViewIfNeeded();
+  const box = await locator.boundingBox();
+  if (!box) return;
+
+  const x = box.x + box.width / 2;
+  const y = box.y + box.height / 2;
+  await page.mouse.move(x, y, { steps: 18 });
+  await page.evaluate(
+    ({ x, y, label }) => {
+      let cursor = document.getElementById("__demo_this_pr_cursor");
+      if (!cursor) {
+        cursor = document.createElement("div");
+        cursor.id = "__demo_this_pr_cursor";
+        cursor.innerHTML = \`<div class="dot"></div><div class="label"></div>\`;
+        document.body.appendChild(cursor);
+      }
+
+      Object.assign(cursor.style, {
+        position: "fixed",
+        left: \`\${x}px\`,
+        top: \`\${y}px\`,
+        transform: "translate(-8px, -8px)",
+        zIndex: "2147483647",
+        pointerEvents: "none",
+        transition: "left 260ms ease, top 260ms ease"
+      });
+
+      const dot = cursor.querySelector(".dot");
+      Object.assign(dot.style, {
+        width: "18px",
+        height: "18px",
+        borderRadius: "999px",
+        background: "#38bdf8",
+        border: "3px solid #ffffff",
+        boxShadow: "0 0 0 8px rgba(56, 189, 248, .22), 0 8px 20px rgba(0,0,0,.28)"
+      });
+
+      const labelEl = cursor.querySelector(".label");
+      labelEl.textContent = label;
+      Object.assign(labelEl.style, {
+        margin: "8px 0 0 12px",
+        padding: "7px 10px",
+        borderRadius: "8px",
+        background: "rgba(15, 23, 42, .92)",
+        color: "#fff",
+        font: "600 13px/1.3 system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        whiteSpace: "nowrap",
+        boxShadow: "0 8px 24px rgba(0,0,0,.22)"
+      });
+    },
+    { x, y, label }
+  );
+  await page.waitForTimeout(550);
+}
+
+function renderIntroHtml(demoPlan) {
+  const tests = demoPlan.context?.tests ?? [];
+  const changes = demoPlan.context?.changes ?? [];
+  const technologies = demoPlan.context?.technologies ?? [];
+  const files = demoPlan.context?.changedFiles ?? [];
+
+  return \`<!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <title>\${escapeHtml(demoPlan.title)}</title>
+      </head>
+      <body style="margin:0;background:#0f172a;color:#e5edf7;font:15px/1.45 system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif">
+        <section style="max-width:980px;margin:72px auto;padding:32px;border:1px solid rgba(148,163,184,.35);border-radius:14px;background:rgba(15,23,42,.92);box-shadow:0 24px 80px rgba(0,0,0,.35)">
+          <div style="color:#93c5fd;text-transform:uppercase;font-weight:700;font-size:12px;letter-spacing:.08em">Demo this PR</div>
+          <h1 style="font-size:34px;line-height:1.1;margin:10px 0 12px">\${escapeHtml(demoPlan.title)}</h1>
+          <p style="font-size:18px;color:#cbd5e1;margin:0 0 24px">\${escapeHtml(demoPlan.why ?? "Review the changed behavior.")}</p>
+          \${section("What changed", changes)}
+          \${section("Technology used", technologies)}
+          \${section("Tests", tests.map((test) => \`\${test.status.toUpperCase()} · \${test.command} · \${formatMs(test.durationMs)}\`))}
+          \${section("Changed files", files.slice(0, 6))}
+          <p style="color:#94a3b8;margin:24px 0 0">Video is local-only evidence for review. It is not meant to be committed or uploaded automatically.</p>
+        </section>
+      </body>
+    </html>\`;
+}
+
+function section(title, items) {
+  if (!items.length) return "";
+  return \`
+    <div style="margin-top:18px">
+      <h2 style="font-size:13px;color:#93c5fd;text-transform:uppercase;letter-spacing:.08em;margin:0 0 8px">\${escapeHtml(title)}</h2>
+      <ul style="margin:0;padding-left:20px;color:#e2e8f0">\${items.map((item) => \`<li style="margin:4px 0">\${escapeHtml(item)}</li>\`).join("")}</ul>
+    </div>
+  \`;
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function formatMs(ms) {
+  return ms < 1000 ? \`\${ms}ms\` : \`\${(ms / 1000).toFixed(1)}s\`;
+}
+
+function actionLabel(step) {
+  if (step.goto) return \`Open \${step.goto}\`;
+  if (step.click) return \`Click \${step.click}\`;
+  if (step.fill) return \`Fill \${step.fill.selector}\`;
+  if (step.press) return \`Press \${step.press.key}\`;
+  if (step.expectText) return \`Verify \${step.expectText}\`;
+  if (step.screenshot) return \`Capture \${step.screenshot}\`;
+  if (step.waitMs) return \`Wait \${step.waitMs}ms\`;
+  return "Demo step";
+}
+
+function resolveUrl(baseUrl, target) {
+  if (/^https?:\\/\\//i.test(target)) return target;
+  return \`\${String(baseUrl).replace(/\\/+$/, "")}/\${String(target).replace(/^\\/+/, "")}\`;
+}
+
+function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "step";
+}
+})
+`;
+}
+function renderMcpGuide(plan, mcpScriptPath, outputDir) {
+    return `# MCP Playwright verification
+
+This repo prefers Playwright MCP for browser verification. Use an isolated MCP Chromium context, not the user's normal Chrome profile.
+
+## Feature
+
+${plan.title}
+
+## Why
+
+${plan.why ?? "No reason provided."}
+
+## Run with MCP
+
+1. Start the app under review.
+2. Open or select an isolated Playwright MCP Chromium tab.
+3. Resize the viewport to 1440x900.
+4. Navigate to \`${plan.baseUrl ?? "the local app URL"}\`.
+5. Run the generated script through \`mcp__playwright__.browser_run_code_unsafe\`:
+
+\`\`\`json
+{
+  "filename": ${JSON.stringify(mcpScriptPath)}
+}
+\`\`\`
+
+6. Capture a final full-page screenshot through MCP if useful.
+7. Close the MCP tab/window after verification.
+
+## Demo steps
+
+${plan.steps.map((step, index) => `${index + 1}. ${step.caption ?? describeStep(step)}`).join("\n")}
+
+## Artifacts
+
+- MCP script: \`${relative(outputDir, mcpScriptPath)}\`
+- Screenshots: \`assets/mcp-screenshots/\`
+- Optional video runner: \`pr-demo.spec.ts\`
+`;
+}
+function describeStep(step) {
+    if (step.caption) {
+        return step.caption;
+    }
+    if (step.goto) {
+        return `Open ${step.goto}`;
+    }
+    if (step.click) {
+        return `Click ${step.click}`;
+    }
+    if (step.fill) {
+        return `Fill ${step.fill.selector}`;
+    }
+    if (step.press) {
+        return `Press ${step.press.key}`;
+    }
+    if (step.expectText) {
+        return `Verify ${step.expectText}`;
+    }
+    if (step.screenshot) {
+        return `Capture ${step.screenshot}`;
+    }
+    if (step.waitMs !== undefined) {
+        return `Wait ${step.waitMs}ms`;
+    }
+    return "Demo step";
+}
+async function copyFirstVideo(outputDir) {
+    const testResultsDir = join(outputDir, "assets", "test-results");
+    const video = await findFile(testResultsDir, ".webm");
+    if (!video) {
+        return undefined;
+    }
+    const target = join(outputDir, "assets", "demo-this-pr.webm");
+    await cp(video, target);
+    return relative(outputDir, target);
+}
+async function copyVideo(source, outputDir) {
+    const target = join(outputDir, "assets", "demo-this-pr.webm");
+    await cp(source, target);
+    return relative(outputDir, target);
+}
+async function convertToMp4(outputDir, webmPath) {
+    if (!ffmpegPath) {
+        return { error: "ffmpeg-static did not provide a binary for this platform." };
+    }
+    const source = join(outputDir, webmPath);
+    const target = join(outputDir, "assets", "demo-this-pr.mp4");
+    const result = await runProcess(ffmpegPath, ["-y", "-i", source, "-movflags", "faststart", "-pix_fmt", "yuv420p", target], outputDir);
+    if (result.exitCode !== 0) {
+        return { error: trimOutput(`${result.stdout}\n${result.stderr}`) || "ffmpeg failed to convert WebM to MP4." };
+    }
+    return { mp4Path: relative(outputDir, target) };
+}
+async function findFile(dir, suffix) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith(suffix)) {
+            return path;
+        }
+        if (entry.isDirectory()) {
+            const nested = await findFile(path, suffix);
+            if (nested) {
+                return nested;
+            }
+        }
+    }
+    return undefined;
+}
+function summarizeFailure(result) {
+    const output = trimOutput(`${result.stderr}\n${result.stdout}`);
+    if (/Executable doesn't exist|playwright install|browser.*not found/iu.test(output)) {
+        return "Playwright browser is not installed. Run: npx playwright install chromium";
+    }
+    return output.split("\n").slice(-8).join("\n");
+}
+function trimOutput(output) {
+    return output.trim().split("\n").slice(-80).join("\n");
+}