scenescout 1.1.0 → 1.2.0

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  *   scenescout scan <projectPath>   Print project discovery results
  *   scenescout serve                Run the MCP server on stdio
- *   scenescout install              Install the skill, download Chromium, register the MCP server
+ *   scenescout install              Install the skill, download the browser, register the MCP server
  *   scenescout doctor               Check every piece of the setup and say how to fix what is missing
  */
 import { spawnSync } from "node:child_process";
@@ -13,6 +13,8 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection, playwrightInstallArgs, } from "./browsers.js";
+import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
 import { diagnose, installSkill, launchCommand, manualRegisterCommand, registerMcp, resolveClaudeDir, spawnRunner } from "./installer.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
 import { formatScan, scanProject } from "./scan.js";
@@ -26,7 +28,12 @@ Usage:
   scenescout serve                  Run the MCP server (stdio)
   scenescout install                One-step setup: skill + Chromium + MCP registration
                                     (--skip-browser, --no-register to opt out of a step;
-                                     --browser-only when the skill and server came from a plugin)
+                                     --browser-only when the skill and server came from a plugin;
+                                     --browsers <list> to choose what to download: chromium (default),
+                                     chromium-headless-shell, firefox, webkit, all — comma-separated)
+                                    (--client <list> to set up another MCP client instead of, or as well as,
+                                     Claude Code: claude-code (default), cursor, vscode, codex, gemini,
+                                     copilot, windsurf — comma-separated)
   scenescout doctor                 Check the setup and print the fix for anything missing
                                     (--engine: only node, the build and the browser — for plugin
                                      installs and other MCP clients)
@@ -109,23 +116,83 @@ function status(projectPath) {
         }
     }
 }
-/** Where Playwright expects its Chromium build; null when playwright cannot say. */
-async function chromiumPath() {
+/** Which browser builds are on disk, going by the paths Playwright reports for the version we depend on. */
+async function presentBrowsers() {
+    const executables = { chromium: null, firefox: null, webkit: null };
     try {
-        const { chromium } = await import("playwright");
-        return chromium.executablePath() || null;
+        const playwright = await import("playwright");
+        for (const name of BROWSER_ENGINES)
+            executables[name] = playwright[name].executablePath() || null;
     }
     catch {
-        return null;
+        // Playwright cannot be loaded: every build reads as absent, which is what doctor should say.
     }
+    return browserPresence(executables);
 }
-/** Download Chromium through the playwright CLI that ships with our own dependency. */
-function downloadChromium() {
+/** Download browser builds through the playwright CLI that ships with our own dependency. */
+function downloadBrowsers(targets) {
     const require = createRequire(import.meta.url);
     const cli = path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
-    const r = spawnSync(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" });
+    const r = spawnSync(process.execPath, [cli, ...playwrightInstallArgs(targets)], { stdio: "inherit" });
     return r.status === 0;
 }
+/**
+ * The value of a flag written as `--name x` or `--name=x`. Undefined when the
+ * flag is absent; empty when it was given no value, which includes being
+ * followed by another flag.
+ */
+function flagValue(flags, name) {
+    const inline = flags.find((f) => f.startsWith(`${name}=`));
+    if (inline)
+        return inline.slice(name.length + 1);
+    const at = flags.indexOf(name);
+    if (at < 0)
+        return undefined;
+    const next = flags[at + 1];
+    return next === undefined || next.startsWith("--") ? "" : next;
+}
+function browsersFlag(flags) {
+    // `--browser-only` is a different flag; a bare `--browser` is a slip that would otherwise be ignored and download Chromium.
+    const slip = flags.find((f) => f === "--browser" || f.startsWith("--browser="));
+    if (slip)
+        throw new Error(`unknown flag ${slip.split("=")[0]} — did you mean --browsers?`);
+    return flagValue(flags, "--browsers");
+}
+/** The `code` command on PATH, with its real path: the real path is what tells VS Code from a fork. */
+function codeOnPath() {
+    const names = process.platform === "win32" ? ["code.cmd", "code.exe"] : ["code"];
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            try {
+                if (fs.existsSync(candidate))
+                    return { command: candidate, realPath: fs.realpathSync(candidate) };
+            }
+            catch {
+                // An unreadable PATH entry is not a VS Code install.
+            }
+        }
+    }
+    return null;
+}
+/** Every value given for a flag, across repeats and both spellings, joined the way one comma-separated value would be. */
+function flagValues(flags, names) {
+    const values = [];
+    flags.forEach((f, i) => {
+        for (const name of names) {
+            if (f.startsWith(`${name}=`))
+                values.push(f.slice(name.length + 1));
+            else if (f === name) {
+                const next = flags[i + 1];
+                values.push(next === undefined || next.startsWith("--") ? "" : next);
+            }
+        }
+    });
+    if (values.length === 0)
+        return undefined;
+    // One occurrence without a value is a mistake even when another has one.
+    return values.some((v) => v.trim() === "") ? "" : values.join(",");
+}
 async function install(flags) {
     const serverPath = path.join(packageRoot, "dist", "mcp-server.js");
     if (!fs.existsSync(serverPath)) {
@@ -137,7 +204,17 @@ async function install(flags) {
     // A plugin install already brings the skill and the server registration; the
     // only thing it cannot bring is the browser download.
     const browserOnly = flags.includes("--browser-only");
-    if (!browserOnly) {
+    // Read the choice before doing anything, so a typo costs nothing.
+    const selection = parseBrowserSelection(browsersFlag(flags));
+    if ("error" in selection)
+        throw new Error(selection.error);
+    const chosen = parseClients(flagValues(flags, ["--client", "--clients"]));
+    if ("error" in chosen)
+        throw new Error(chosen.error);
+    const forClaude = chosen.clients.includes("claude-code");
+    const others = chosen.clients.filter((c) => c !== "claude-code");
+    // The skill is Claude Code's way of receiving the method; every other client gets it from the server.
+    if (!browserOnly && forClaude) {
         const skill = installSkill({ packageRoot, claudeDir: resolveClaudeDir(process.env, os.homedir()) });
         for (const note of skill.notes)
             console.log(`· ${note}`);
@@ -149,45 +226,85 @@ async function install(flags) {
         console.log("· Browser download skipped (--skip-browser).");
     }
     else {
-        const existing = await chromiumPath();
-        if (existing && fs.existsSync(existing)) {
-            console.log(`✓ Chromium already present: ${existing}`);
-        }
-        else {
-            console.log("· Downloading Chromium (one-time, ~150 MB)…");
-            if (downloadChromium())
-                console.log("✓ Chromium downloaded.");
+        const present = await presentBrowsers();
+        const missing = selection.targets.filter((t) => !present[t].installed);
+        for (const t of selection.targets)
+            if (present[t].installed)
+                console.log(`✓ ${t} already present: ${present[t].path}`);
+        if (missing.length > 0) {
+            const size = missing.reduce((sum, t) => sum + APPROX_DISK_MB[t], 0);
+            console.log(`· Downloading ${missing.join(", ")} (one-time, about ${size} MB on disk)…`);
+            if (downloadBrowsers(missing))
+                console.log(`✓ Downloaded: ${missing.join(", ")}.`);
             else {
                 failed = true;
-                console.log("✗ Chromium download failed — run `npx playwright install chromium` and check your network/proxy.");
+                console.log(`✗ Browser download failed — run \`npx playwright install ${missing.join(" ")}\` and check your network/proxy.`);
             }
         }
     }
+    // Downloading a browser the server will not launch leaves the first attach failing with no hint why.
+    const engine = defaultEngine(process.env);
+    const note = defaultAttachNote({
+        selected: flags.includes("--skip-browser") ? [] : selection.targets,
+        defaultEngine: engine,
+        defaultInstalled: (await presentBrowsers())[launchTarget(engine, false)].installed,
+    });
+    if (note)
+        console.log(`· Note: ${note}`);
+    const launch = launchCommand({ packageRoot, nodePath: process.execPath, serverPath });
     if (browserOnly) {
         // nothing to register
     }
     else if (flags.includes("--no-register")) {
-        console.log(`· MCP registration skipped (--no-register). To do it by hand:\n\n  ${manualRegisterCommand(launchCommand({ packageRoot, nodePath: process.execPath, serverPath }))}\n`);
+        console.log("· MCP registration skipped (--no-register). To do it by hand:\n");
+        if (forClaude)
+            console.log(`  ${manualRegisterCommand(launch)}`);
+        for (const client of others)
+            console.log(`  ${CLIENT_LABELS[client]}: ${manualFor(client, launch, os.homedir())}`);
+        console.log("");
     }
     else {
-        const reg = registerMcp({ launch: launchCommand({ packageRoot, nodePath: process.execPath, serverPath }), serverPath, run: spawnRunner });
-        if (reg.status === "registered") {
-            console.log(`✓ MCP server ${reg.replaced ? "re-registered (paths refreshed)" : "registered"} with Claude Code at user scope.`);
-            for (const name of reg.removedLegacy)
-                console.log(`· removed the pre-rename MCP registration "${name}" (it pointed at this same server).`);
-            for (const note of reg.notes)
-                console.log(`· ${note}`);
+        if (forClaude) {
+            const reg = registerMcp({ launch, serverPath, run: spawnRunner });
+            if (reg.status === "registered") {
+                console.log(`✓ MCP server ${reg.replaced ? "re-registered (paths refreshed)" : "registered"} with Claude Code at user scope.`);
+                for (const name of reg.removedLegacy)
+                    console.log(`· removed the pre-rename MCP registration "${name}" (it pointed at this same server).`);
+                for (const note of reg.notes)
+                    console.log(`· ${note}`);
+            }
+            else {
+                failed = true;
+                console.log(reg.status === "claude-missing"
+                    ? "· `claude` is not on this shell's PATH, so the MCP server was not registered."
+                    : `✗ \`claude mcp add\` failed: ${reg.detail}`);
+                console.log(`  Run this once from a terminal where \`claude\` works:\n\n  ${reg.manual}\n`);
+            }
         }
-        else {
-            failed = true;
-            console.log(reg.status === "claude-missing"
-                ? "· `claude` is not on this shell's PATH, so the MCP server was not registered."
-                : `✗ \`claude mcp add\` failed: ${reg.detail}`);
-            console.log(`  Run this once from a terminal where \`claude\` works:\n\n  ${reg.manual}\n`);
+        const vscode = others.includes("vscode")
+            ? vscodeBinary({ platform: process.platform, home: os.homedir(), exists: fs.existsSync, codeOnPath: codeOnPath() })
+            : null;
+        for (const client of others) {
+            const reg = registerWithClient(client, { launch, home: os.homedir(), run: spawnRunner, vscode });
+            const label = CLIENT_LABELS[client];
+            if (reg.status === "registered") {
+                console.log(`✓ MCP server ${reg.replaced ? "re-registered" : "registered"} with ${label} (${reg.where}).`);
+                for (const note of reg.notes)
+                    console.log(`· ${note}`);
+            }
+            else {
+                failed = true;
+                // On Windows a client installed through npm is a .cmd shim, which node cannot start directly.
+                const windowsNote = process.platform === "win32" ? " (or it is installed as a .cmd shim, which cannot be started from here)" : "";
+                console.log(reg.status === "client-missing"
+                    ? `· ${label} was not found on this machine${windowsNote}, so nothing was registered with it.`
+                    : `✗ Registering with ${label} failed: ${reg.detail}`);
+                console.log(`  To do it by hand, ${reg.manual}\n`);
+            }
         }
     }
     if (failed) {
-        console.log("\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor");
+        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor${forClaude ? "" : " --engine"}`);
         process.exitCode = 1;
         return;
     }
@@ -195,8 +312,12 @@ async function install(flags) {
         console.log("\nThe browser is ready — attach again.");
         return;
     }
-    console.log("\nStart a FRESH Claude Code session, then in any project run:  /scenescout");
-    console.log("Something off? Run:  scenescout doctor");
+    if (forClaude)
+        console.log("\nStart a FRESH Claude Code session, then in any project run:  /scenescout");
+    // Telling someone to restart a client nothing was registered with sends them looking for a server that is not there.
+    if (others.length > 0 && !flags.includes("--no-register"))
+        console.log(`\n${firstMessageHint(others)}`);
+    console.log(`Something off? Run:  scenescout doctor${forClaude ? "" : " --engine"}`);
 }
 async function doctor(flags) {
     const checks = diagnose({
@@ -204,7 +325,12 @@ async function doctor(flags) {
         packageRoot,
         claudeDir: resolveClaudeDir(process.env, os.homedir()),
         nodeVersion: process.version,
-        chromiumPath: await chromiumPath(),
+        // What a default attach launches: the headless build of the default browser.
+        defaultBrowser: await (async () => {
+            const target = launchTarget(defaultEngine(process.env), false);
+            const found = (await presentBrowsers())[target];
+            return { target, path: found.installed ? found.path : null, expected: found.path };
+        })(),
         run: spawnRunner,
     });
     for (const c of checks) {
@@ -214,7 +340,9 @@ async function doctor(flags) {
     }
     if (checks.some((c) => !c.ok))
         process.exit(1);
-    console.log("\nAll good. In any project, run:  /scenescout");
+    console.log(flags.includes("--engine")
+        ? "\nAll good. Ask your agent:  Use SceneScout to test http://localhost:3000"
+        : "\nAll good. In any project, run:  /scenescout   (or ask: Use SceneScout to test http://localhost:3000)");
 }
 const [, , command, ...args] = process.argv;
 // A CLI's failure mode should be a sentence, not a stack trace. `scan` on a

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,4 +1,4 @@
-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";
@@ -8,6 +8,8 @@ import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGE
 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, 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";
@@ -228,6 +230,8 @@ export class BrowserEngine {
     }
     /** 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 = [];
     /**
@@ -293,11 +297,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 +469,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 +1288,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. */
@@ -1924,15 +1925,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 +1963,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));
+}