scenescout 1.1.0 → 1.3.0

package/dist/clients.js

@@ -0,0 +1,213 @@
+/**
+ * Registering the MCP server with clients other than Claude Code.
+ *
+ * Each client keeps its server list somewhere different. Where a client has a
+ * command for adding a server, that command is used: it knows its own config
+ * format and location. Where it has none, the JSON file it reads is edited in
+ * place, keeping every other entry.
+ *
+ * Nothing here launches a process or touches the home directory on its own:
+ * the runner, the home directory and the platform are passed in, so every rule
+ * can be table-tested.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { MCP_NAME } from "./installer.js";
+export const OTHER_CLIENTS = ["cursor", "vscode", "codex", "gemini", "copilot", "windsurf"];
+export const CLIENTS = ["claude-code", ...OTHER_CLIENTS];
+export const CLIENT_LABELS = {
+    "claude-code": "Claude Code",
+    cursor: "Cursor",
+    vscode: "VS Code (GitHub Copilot agent mode)",
+    codex: "Codex CLI",
+    gemini: "Gemini CLI",
+    copilot: "GitHub Copilot CLI",
+    windsurf: "Windsurf",
+};
+/** Read the value of `--client`. Absent means Claude Code, which is what install has always set up. */
+export function parseClients(value) {
+    if (value === undefined)
+        return { clients: ["claude-code"] };
+    const names = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const choices = CLIENTS.join(", ");
+    if (names.length === 0)
+        return { error: `--client needs a value. Choose from: ${choices}.` };
+    const picked = new Set();
+    for (const name of names) {
+        if (!CLIENTS.includes(name))
+            return { error: `"${name}" is not a client install knows how to set up. Choose from: ${choices}.` };
+        picked.add(name);
+    }
+    return { clients: CLIENTS.filter((c) => picked.has(c)) };
+}
+const STRATEGIES = {
+    cursor: { kind: "file", file: (home) => path.join(home, ".cursor", "mcp.json"), key: "mcpServers" },
+    windsurf: { kind: "file", file: (home) => path.join(home, ".codeium", "windsurf", "mcp_config.json"), key: "mcpServers" },
+    // `add` replaces an entry of the same name.
+    codex: { kind: "command", binary: "codex", add: (launch) => ["mcp", "add", MCP_NAME, "--", ...launch] },
+    // `add` updates an entry of the same name. The default scope is the project; a tool like this belongs to the user.
+    gemini: { kind: "command", binary: "gemini", add: (launch) => ["mcp", "add", "--scope", "user", MCP_NAME, ...launch] },
+    // `add` refuses a name that already exists, so the old entry is removed first.
+    copilot: { kind: "command", binary: "copilot", add: (launch) => ["mcp", "add", MCP_NAME, "--", ...launch], removeFirst: ["mcp", "remove", MCP_NAME] },
+};
+const quote = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+/** The entry every `mcpServers`-style file takes. */
+export function serverEntry(launch) {
+    return { command: launch[0], args: launch.slice(1) };
+}
+/**
+ * Put the server into a client's JSON server list, keeping everything else in
+ * the file. A file that is not valid JSON is left exactly as it is: rewriting
+ * it would discard whatever the person had in it.
+ */
+export function registerInFile(file, key, launch) {
+    const entry = serverEntry(launch);
+    const manual = `add this under "${key}" in ${file}:\n  ${JSON.stringify({ [MCP_NAME]: entry })}`;
+    let config = {};
+    // A config kept in a dotfiles repository is a link. Renaming over the link
+    // would replace it with a plain file and leave the real one unchanged, so
+    // the write goes to whatever the link points at.
+    let target = file;
+    let mode = 0o600;
+    try {
+        if (fs.existsSync(file)) {
+            target = fs.realpathSync(file);
+            mode = fs.statSync(target).mode & 0o777;
+            // Some editors save with a byte-order mark, which JSON.parse rejects.
+            const raw = fs.readFileSync(target, "utf8").replace(/^\uFEFF/, "");
+            if (raw.trim().length > 0) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch (err) {
+                    return {
+                        status: "failed",
+                        detail: `${file} is not valid JSON (${err instanceof Error ? err.message : String(err)}), so it was left untouched`,
+                        manual,
+                    };
+                }
+                if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    return { status: "failed", detail: `${file} does not hold a JSON object, so it was left untouched`, manual };
+                }
+                config = parsed;
+            }
+        }
+    }
+    catch (err) {
+        return { status: "failed", detail: `${file} could not be read (${err instanceof Error ? err.message : String(err)})`, manual };
+    }
+    const existing = config[key];
+    if (existing !== undefined && (existing === null || typeof existing !== "object" || Array.isArray(existing))) {
+        return { status: "failed", detail: `"${key}" in ${file} is not an object, so the file was left untouched`, manual };
+    }
+    const servers = (existing ?? {});
+    const before = servers[MCP_NAME];
+    const notes = [];
+    if (before !== undefined && JSON.stringify(before) !== JSON.stringify(entry)) {
+        notes.push(`the previous "${MCP_NAME}" entry was replaced; it ran: ${JSON.stringify(before)}`);
+    }
+    config[key] = { ...servers, [MCP_NAME]: entry };
+    // Written beside the target and renamed over it, so a crash cannot leave half a file.
+    const tmp = `${target}.scenescout-${process.pid}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode });
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        // The temporary file is a full copy of the config, which can hold secrets in `env`; it must not stay behind.
+        fs.rmSync(tmp, { force: true });
+        return { status: "failed", detail: `${file} could not be written (${err instanceof Error ? err.message : String(err)}), so it was left untouched`, manual };
+    }
+    return { status: "registered", where: file, replaced: before !== undefined, notes };
+}
+function registerWithCommand(client, launch, run) {
+    const manual = [client.binary, ...client.add(launch)].map(quote).join(" ");
+    let removed = false;
+    if (client.removeFirst) {
+        const removal = run(client.binary, client.removeFirst);
+        if (removal.missing)
+            return { status: "client-missing", manual };
+        // A non-zero exit here only means there was nothing of that name to remove.
+        removed = removal.status === 0;
+    }
+    const added = run(client.binary, client.add(launch));
+    if (added.missing)
+        return { status: "client-missing", manual };
+    if (added.status !== 0) {
+        const reason = (added.stdout + added.stderr).trim().split("\n")[0] || `exit code ${added.status}`;
+        // Having removed the old entry to make room, say so: the person now has no registration at all.
+        const lost = removed ? ` The previous "${MCP_NAME}" entry had already been removed to make room, so ${client.binary} now has none.` : "";
+        return { status: "failed", detail: reason + lost, manual };
+    }
+    return { status: "registered", where: `${client.binary} mcp`, replaced: removed, notes: [] };
+}
+/**
+ * The VS Code command line, or null when only a fork is installed. Cursor and
+ * Windsurf both install a `code` command of their own, and running that one
+ * registers the server in the wrong editor: it reports success and VS Code
+ * never sees the entry. A `code` that resolves into another editor's files is
+ * therefore not VS Code.
+ *
+ * The real path is only inspected. What gets run is the command as found on
+ * PATH: some installs (snap) link `code` to a launcher that decides what to
+ * start from the name it was called by, and running the link's target directly
+ * starts the wrong thing.
+ */
+export function vscodeBinary(opts) {
+    if (opts.platform === "darwin") {
+        for (const root of ["/Applications", path.posix.join(opts.home, "Applications")]) {
+            const bundled = path.posix.join(root, "Visual Studio Code.app", "Contents", "Resources", "app", "bin", "code");
+            if (opts.exists(bundled))
+                return bundled;
+        }
+    }
+    if (!opts.codeOnPath)
+        return null;
+    // Looked for below the home directory's own name, so an account called "cursor" does not disqualify every install under it.
+    const real = opts.codeOnPath.realPath;
+    const belowHome = real.toLowerCase().startsWith(opts.home.toLowerCase()) ? real.slice(opts.home.length) : real;
+    return /cursor|windsurf|codeium|vscodium/i.test(belowHome) ? null : opts.codeOnPath.command;
+}
+/** What `code --add-mcp` takes: the entry plus its name. */
+export function vscodeAddArgs(launch) {
+    return ["--add-mcp", JSON.stringify({ name: MCP_NAME, ...serverEntry(launch) })];
+}
+export function registerWithClient(client, opts) {
+    if (client === "vscode") {
+        const manual = `in VS Code run "MCP: Add Server…" and choose a command (stdio) server, or run:\n  code ${vscodeAddArgs(opts.launch).map(quote).join(" ")}`;
+        if (!opts.vscode)
+            return { status: "client-missing", manual };
+        const added = opts.run(opts.vscode, vscodeAddArgs(opts.launch));
+        if (added.missing)
+            return { status: "client-missing", manual };
+        const output = (added.stdout + added.stderr).trim();
+        if (added.status !== 0)
+            return { status: "failed", detail: output.split("\n")[0] || `exit code ${added.status}`, manual };
+        // This command replaces an entry of the same name and does not say whether there was one.
+        return { status: "registered", where: "VS Code's user profile", replaced: false, notes: [] };
+    }
+    const strategy = STRATEGIES[client];
+    return strategy.kind === "file" ? registerInFile(strategy.file(opts.home), strategy.key, opts.launch) : registerWithCommand(strategy, opts.launch, opts.run);
+}
+/** How to register with a client by hand, without running anything. */
+export function manualFor(client, launch, home) {
+    if (client === "vscode")
+        return `code ${vscodeAddArgs(launch).map(quote).join(" ")}`;
+    const strategy = STRATEGIES[client];
+    if (strategy.kind === "command")
+        return [strategy.binary, ...strategy.add(launch)].map(quote).join(" ");
+    return `add under "${strategy.key}" in ${strategy.file(home)}:  ${JSON.stringify({ [MCP_NAME]: serverEntry(launch) })}`;
+}
+/** What to tell the person once their clients are set up: how the method reaches an agent that has no skill. */
+export function firstMessageHint(clients) {
+    const names = clients.map((c) => CLIENT_LABELS[c]);
+    const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}` : names[0];
+    return (`Restart ${list} (or reload the MCP servers there), then ask the agent:\n` +
+        `  Use SceneScout to test http://localhost:3000\n` +
+        `The server hands the agent the testing method through its scout_playbook tool.`);
+}

package/dist/engine/browser.js

@@ -1,13 +1,15 @@
-import { chromium } from "playwright";
+import { chromium, firefox, webkit } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
-import { AUTH_LOSS_PREFIX, MemoryStore } from "./memory.js";
+import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore } from "./memory.js";
 import { AuthLossTracker } from "./authloss.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
+import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
+import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
 import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
 import { BROWSER_MARKER, reapOrphanBrowsers } from "./reaper.js";
@@ -96,6 +98,8 @@ function actionabilityDiagnostic(message) {
  * actions by ref, runs oracles after every action, and records everything in
  * the persistent memory store. Contains no LLM calls — the MCP client is the brain.
  */
+/** A screencast whose page has been gone for this many 500 ms ticks ends and says so; a re-attach takes fewer. */
+const SCREENCAST_PAGELESS_TICKS = 20;
 export class BrowserEngine {
     browser = null;
     context = null;
@@ -184,6 +188,8 @@ export class BrowserEngine {
     designAuditCount = 0;
     /** Active task-efficiency measurement (scout_journey), if any. */
     journey = null;
+    /** The session's task, from scout_attach. Empty when the agent gave none. */
+    task = "";
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
      * real task ("create an order", "approve a document"). E2E suites assert
@@ -198,7 +204,7 @@ export class BrowserEngine {
             fromLog: this.memory?.actionLog.length ?? 0,
             startUrl: page.url(),
         };
-        this.logAction({ action: "journey:start", target: goal, url: page.url() });
+        this.logAction({ action: JOURNEY_START, target: goal, url: page.url() });
         return `JOURNEY STARTED — "${goal}"\nFrom: ${page.url()}\nNow perform the task the way a first-time user would (click through the UI; don't jump straight to a known deep URL, or the measurement is meaningless). Call scout_journey {action:"end"} when the task is complete or you conclude it can't be.`;
     }
     /** Close the journey and report its interaction cost + friction signals. */
@@ -223,11 +229,13 @@ export class BrowserEngine {
         catch {
             /* fact recording is best-effort */
         }
-        this.logAction({ action: "journey:end", target: j.goal, url: page.url(), result: completed ? "completed" : "abandoned" });
+        this.logAction({ action: JOURNEY_END, target: j.goal, url: page.url(), result: completed ? "completed" : "abandoned" });
         return formatJourney({ goal: j.goal, completed, seconds, note }, measured);
     }
     /** Whether the browser window is visible — headed hover results carry a physical-cursor caveat. */
     headed = false;
+    /** The browser this engine launched; reported by attach so a finding can say where it was seen. */
+    engineName = "chromium";
     /** Non-GET requests fired since the last action — surfaces silent state mutation in read-only runs (timestamped for attribution). */
     mutationRequests = [];
     /**
@@ -254,6 +262,7 @@ export class BrowserEngine {
             throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
         }
         this.mode = opts.mode ?? "read-only";
+        this.task = (opts.task ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
         this.pendingCreations = new Set();
@@ -293,11 +302,15 @@ export class BrowserEngine {
             this.knownRoutes = [];
         }
         try {
-            this.browser = await this.launchWithRecovery(opts.headed ?? false);
+            this.engineName = opts.browser ?? defaultEngine(process.env);
+            this.browser = await this.launchWithRecovery(this.engineName, opts.headed ?? false);
             this.context = await this.browser.newContext({
                 storageState: opts.storageStatePath,
                 viewport: opts.viewport ?? { width: 1280, height: 900 },
+                serviceWorkers: serviceWorkerPolicy(this.engineName),
             });
+            if (!sharedWorkersAllowed(this.mode))
+                await this.context.addInitScript(REMOVE_SHARED_WORKER_SCRIPT);
             this.page = await this.context.newPage();
         }
         catch (err) {
@@ -461,6 +474,8 @@ export class BrowserEngine {
                 `Continuing now tests a logged-out app.`
             : "";
         return (`Attached to ${this.page.url()} (mode=${this.mode}` +
+            `${this.engineName === "chromium" ? "" : `, browser=${this.engineName}, service workers blocked because their requests cannot be intercepted here`}` +
+            `${focusAdvanceKey(this.engineName, process.platform) === "Tab" ? "" : `, keyboard: Tab stops only at text fields in this browser — press Alt+Tab to reach buttons and links`}` +
             `${opts.storageStatePath ? `, auth=${opts.storageStatePath}` : ""}). ` +
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
@@ -1278,16 +1293,7 @@ export class BrowserEngine {
         const bodyAfter = (await page.evaluate(`document.body ? document.body.innerText : ""`).catch(() => null));
         if (bodyAfter === null)
             return { revealed: [], fallbackUsed: false };
-        const beforeLines = new Set(bodyBefore
-            .split("\n")
-            .map((l) => l.trim())
-            .filter(Boolean));
-        revealed = bodyAfter
-            .split("\n")
-            .map((l) => l.trim())
-            .filter((l) => l && !beforeLines.has(l))
-            .slice(0, 5)
-            .map((l) => l.slice(0, 300));
+        revealed = revealedLines(bodyBefore, bodyAfter);
         return { revealed, fallbackUsed: revealed.length > 0 };
     }
     /** Pre-hover baselines: overlay texts, body text, and whether the page is already churning on its own. */
@@ -1908,6 +1914,125 @@ export class BrowserEngine {
         this.logAction({ action: "screenshot", url: page.url() });
         return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
     }
+    /**
+     * What the live view shows next to a session's name. The task is what the
+     * agent said the session is for; the objective is the goal of the journey it
+     * is on right now (scout_journey). Both are the agent's own words — the
+     * engine sees tool calls, never the reasoning behind them. Neither is
+     * redacted here: the caller that writes them anywhere does that.
+     */
+    get liveDescription() {
+        return {
+            mode: this.mode,
+            browser: this.engineName,
+            headed: this.headed,
+            ...(this.task ? { task: this.task } : {}),
+            ...(this.journey ? { objective: this.journey.goal, objectiveSince: new Date(this.journey.startedAt).toISOString() } : {}),
+        };
+    }
+    /**
+     * A frame for somebody WATCHING the run, as opposed to scout_screenshot,
+     * which is the agent looking. It is not logged: the action log is the repro
+     * trace attached to findings, and a person glancing at the dashboard is not
+     * a step anyone should replay. It is also bounded, because the moment a
+     * viewer most wants a picture is when the renderer has wedged.
+     */
+    async liveShot(timeoutMs = 3000) {
+        const page = this.page;
+        if (!page || page.isClosed())
+            return null;
+        let timer;
+        // The driver's own timeout covers a slow capture; the race covers a
+        // renderer that never answers the protocol at all.
+        return Promise.race([
+            page.screenshot({ type: "jpeg", quality: 55, fullPage: false, timeout: timeoutMs }).catch(() => null),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), timeoutMs + 500);
+            }),
+        ]).finally(() => clearTimeout(timer));
+    }
+    /**
+     * Push frames of this session's page until the returned function is called.
+     * The stream follows the session rather than one tab: adopting a popup
+     * replaces `this.page`, and a stream left on the old tab would show a page
+     * the session is no longer driving.
+     */
+    async startScreencast(onFrame, onEnd = () => { }) {
+        if (!this.page || this.page.isClosed())
+            return null;
+        let stopped = false;
+        let bound = null;
+        let release = null;
+        // Ticks in a row with no page to take frames from: a re-attach passes
+        // through a few, a closed session never comes back.
+        let pageless = 0;
+        const bind = async (page) => {
+            if (screencastSupport(this.engineName) === "cdp") {
+                const cdp = await page.context().newCDPSession(page);
+                try {
+                    cdp.on("Page.screencastFrame", (frame) => {
+                        if (!stopped)
+                            onFrame(Buffer.from(frame.data, "base64"));
+                        void cdp.send("Page.screencastFrameAck", { sessionId: frame.sessionId }).catch(() => { });
+                    });
+                    await cdp.send("Page.startScreencast", { format: "jpeg", quality: 55, maxWidth: 1280, maxHeight: 900, everyNthFrame: 2 });
+                }
+                catch (err) {
+                    // Not bound: the timer tries this page again on its next tick.
+                    await cdp.detach().catch(() => { });
+                    throw err;
+                }
+                release = async () => {
+                    await cdp.send("Page.stopScreencast").catch(() => { });
+                    await cdp.detach().catch(() => { });
+                };
+            }
+            else {
+                release = null;
+            }
+            bound = page;
+        };
+        const stop = async () => {
+            stopped = true;
+            clearInterval(timer);
+            const current = release;
+            release = null;
+            await current?.();
+        };
+        await bind(this.page).catch(() => { });
+        // One timer does both jobs: it notices a replaced tab, and where the
+        // browser cannot push frames it is also what takes them.
+        const timer = setInterval(() => {
+            if (stopped)
+                return;
+            const page = this.page;
+            if (!page || page.isClosed()) {
+                pageless += 1;
+                if (pageless >= SCREENCAST_PAGELESS_TICKS)
+                    void stop().finally(onEnd);
+                return;
+            }
+            pageless = 0;
+            if (page !== bound) {
+                const previous = release;
+                release = null;
+                void (async () => {
+                    await previous?.();
+                    if (!stopped)
+                        await bind(page).catch(() => { });
+                })();
+                return;
+            }
+            if (screencastSupport(this.engineName) === "poll") {
+                void this.liveShot(1500).then((jpeg) => {
+                    if (jpeg && !stopped)
+                        onFrame(jpeg);
+                });
+            }
+        }, 500);
+        timer.unref();
+        return stop;
+    }
     get currentState() {
         return this.currentFingerprint;
     }
@@ -1924,15 +2049,18 @@ export class BrowserEngine {
      * On the first failure or timeout, reap orphaned Playwright processes and
      * try once more before giving up with a diagnosable error.
      */
-    async launchWithRecovery(headed) {
+    async launchWithRecovery(engine, headed) {
+        const types = { chromium, firefox, webkit };
         const attempt = async () => {
             // The marker is what makes reapOrphanBrowsers safe to run at startup:
             // it appears in the child's command line, so the sweep can tell a browser
             // WE leaked from one belonging to somebody else's Playwright run.
             // `--enable-features` takes arbitrary names and ignores unknown ones.
-            const launch = chromium.launch({
+            // It is a Chromium switch: Firefox and WebKit are launched without it,
+            // so a leaked one of those is not reaped and has to be closed by hand.
+            const launch = types[engine].launch({
                 headless: !headed,
-                args: [`--enable-features=${BROWSER_MARKER}`],
+                args: engine === "chromium" ? [`--enable-features=${BROWSER_MARKER}`] : [],
             });
             let timer;
             try {
@@ -1959,13 +2087,13 @@ export class BrowserEngine {
             const firstMessage = firstErr instanceof Error ? firstErr.message : String(firstErr);
             // A browser that was never downloaded will not appear on a second try.
             if (isMissingBrowser(firstMessage))
-                throw new Error(explainLaunchFailure(firstMessage, 0));
+                throw new Error(explainLaunchFailure(firstMessage, 0, { engine, headed }));
             const reaped = reapOrphanBrowsers();
             try {
                 return await attempt();
             }
             catch {
-                throw new Error(explainLaunchFailure(firstMessage, reaped));
+                throw new Error(explainLaunchFailure(firstMessage, reaped, { engine, headed }));
             }
         }
     }

package/dist/engine/hover.js

@@ -0,0 +1,42 @@
+/**
+ * The page-text fallback for hover: which text is new after the pointer moved.
+ *
+ * Pure, so the rule can be table-tested. The browser side only supplies the
+ * two `innerText` readings.
+ */
+const squash = (s) => s.replace(/\s+/g, " ").trim();
+/** How many times `needle` occurs in `haystack`, overlaps not counted. */
+function occurrences(haystack, needle) {
+    let n = 0;
+    for (let at = haystack.indexOf(needle); at >= 0; at = haystack.indexOf(needle, at + needle.length))
+        n++;
+    return n;
+}
+/**
+ * Lines present after the hover whose text was not on the page before it.
+ *
+ * Comparing line by line is not enough. When something that was showing goes
+ * away — the previous hover's tooltip closing as the pointer leaves it — the
+ * text around it can re-flow onto a line of its own, and that line is "new"
+ * only as a line: every word of it was already visible. How text re-flows
+ * differs between browsers. So a line counts as revealed when its text occurs
+ * MORE often after the hover than before: text that only moved occurs as often
+ * as it did, while a tooltip reading "Delete" on a page that already says
+ * "Delete account" occurs once more and is still reported.
+ */
+export function revealedLines(bodyBefore, bodyAfter, limit = 5) {
+    const beforeText = squash(bodyBefore);
+    const afterText = squash(bodyAfter);
+    const seen = new Set();
+    return bodyAfter
+        .split("\n")
+        .map(squash)
+        .filter((l) => {
+        if (!l || seen.has(l))
+            return false;
+        seen.add(l);
+        return occurrences(afterText, l) > occurrences(beforeText, l);
+    })
+        .slice(0, limit)
+        .map((l) => l.slice(0, 300));
+}

package/dist/engine/launch.js

@@ -2,21 +2,28 @@
  * Turning a failed browser launch into something the person can act on.
  *
  * For anyone who installed from npm and never ran the setup step, the first
- * attach fails because Chromium was never downloaded — and Playwright reports
+ * attach fails because the browser was never downloaded — and Playwright reports
  * that as a multi-line box of text with a path in it. That is the single most
  * likely first-run failure, so it gets one plain instruction instead.
  */
+import { APPROX_DISK_MB, launchTarget } from "../browsers.js";
 /** Playwright's wording when the browser binary is not on disk. */
 const MISSING_BROWSER_RE = /Executable doesn't exist|playwright install|browserType\.launch:.*(not found|ENOENT)/i;
 export function isMissingBrowser(message) {
     return MISSING_BROWSER_RE.test(message);
 }
 /** The error text for a launch that failed. `reaped` is how many orphaned browsers were cleaned up between attempts. */
-export function explainLaunchFailure(message, reaped) {
+export function explainLaunchFailure(message, reaped, need = { engine: "chromium", headed: false }) {
     if (isMissingBrowser(message)) {
-        return (`Chromium has not been downloaded yet (one-time, ~150 MB). Run this once, then attach again:\n` +
-            `  npx -y scenescout install --browser-only\n` +
-            `(from a clone: npm run setup). On Linux, if system libraries are missing: npx playwright install --with-deps chromium`);
+        const target = launchTarget(need.engine, need.headed);
+        // Someone who installed only the headless shell did run install, so say what is different about a headed run.
+        const why = target === "chromium" && need.headed
+            ? "A headed run needs the full Chromium browser, which has not been downloaded (the headless shell alone cannot open a window)"
+            : `The ${target} build has not been downloaded yet`;
+        return (`${why} (one-time, about ${APPROX_DISK_MB[target]} MB on disk). Run this once, then attach again:\n` +
+            `  npx -y scenescout install --browser-only --browsers ${target}\n` +
+            `(from a clone: node dist/cli.js install --browser-only --browsers ${target}). ` +
+            `On Linux, if system libraries are missing: npx playwright install --with-deps ${target}`);
     }
     const firstLine = message.split("\n")[0];
     return (`browser launch failed twice (${firstLine})` +