scenescout 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # scenescout
 
+## 1.2.0
+
+### Minor Changes
+
+- 2932164: `scenescout install --browsers <list>` chooses what to download: `chromium` (the default, unchanged), `chromium-headless-shell` for the smallest working setup, `firefox`, `webkit`, or `all`. `scout_attach` takes a `browser` option, and `SCENESCOUT_BROWSER` sets the default. In Firefox and WebKit the engine keeps service workers from registering, because a request issued by one cannot be intercepted there and would pass the write policy. The missing-browser message and `doctor` now name the build that is actually missing, and the sizes quoted are the sizes on disk.
+  
+  Pages are no longer given shared workers unless the mode is `destructive`. A request a shared worker sends cannot be intercepted in any browser, and a `DELETE` sent from one reached the server in read-only mode.
+  
+  Hover no longer reports text that was already on the page and only moved to a new line, and the keyboard focus audit uses Option+Tab in WebKit on macOS, where plain Tab skips buttons and links.
+- ad0f31d: `scenescout install --client <list>` registers the server with clients other than Claude Code: `cursor`, `vscode`, `codex`, `gemini`, `copilot` and `windsurf`. Clients that have a command for adding a server are registered through it; Cursor and Windsurf get an entry added to their JSON server list, with every other entry kept and an unreadable file left untouched. For VS Code, a `code` command that belongs to another editor is not used. The skill is installed only when `claude-code` is among the clients.
+- 5504c63: The testing method now reaches every MCP client, not only Claude Code. A new `scout_playbook` tool returns it, the server's instructions tell an agent to call that tool before its first attach, and an `explore` prompt loads the method together with the target URL for clients that list server prompts as commands. It is the same text Claude Code loads as a skill, read from the same file.
+
+### Patch Changes
+
+- d0aa6aa: The package description, keywords and README now present SceneScout as a tool for any MCP client, with Claude Code as one of them. `doctor --engine` ends with what to ask an agent instead of a Claude Code command.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,9 @@
 
 # 🔭 SceneScout
 
-**Exploratory UI testing, driven by an AI agent.**
+**Exploratory UI testing, driven by the AI agent you already use.**
+
+Works with Claude Code · Cursor · VS Code (Copilot) · Codex CLI · Gemini CLI · Copilot CLI · Windsurf · any [MCP](https://modelcontextprotocol.io) client
 
 [![test](https://github.com/brunoboto96/SceneScout/actions/workflows/test.yml/badge.svg)](https://github.com/brunoboto96/SceneScout/actions/workflows/test.yml)
 [![npm](https://img.shields.io/npm/v/scenescout.svg)](https://www.npmjs.com/package/scenescout)
@@ -14,11 +16,11 @@
 
 </div>
 
-SceneScout is an [MCP](https://modelcontextprotocol.io) server that hands an agent a *structured view* of a running web app — every element, its geometry, and a set of always-on correctness oracles — and lets the agent explore it like a curious user. Claude Code is the brain; SceneScout is the hands, eyes, and memory.
+SceneScout is an [MCP](https://modelcontextprotocol.io) server that hands an agent a *structured view* of a running web app — every element, its geometry, and a set of always-on correctness oracles — and lets the agent explore it like a curious user. Your coding agent is the brain; SceneScout is the hands, eyes, and memory. Any MCP client can drive it, and the testing method comes with the server, so the agent knows how to use the tools wherever it runs.
 
 ```
 ┌─────────────────────┐   MCP (stdio)   ┌───────────────────────────────┐
-│ Claude Code + skill │ ──────────────▶ │ SceneScout engine             │
+│ Your coding agent   │ ──────────────▶ │ SceneScout engine             │
 │ (intent, judgment,  │ ◀────────────── │ Playwright · oracles · memory │
 │  your subscription) │  tool results   │ findings · report — no LLM    │
 └─────────────────────┘                 └───────────────────────────────┘
@@ -58,7 +60,7 @@ Every finding comes with a repro trace and a Playwright regression-test skeleton
 
 ## ✨ Why it's different
 
-- 🧠 **Claude is the brain — no API key.** The engine contains no LLM. Exploration runs on your Claude Code subscription; SceneScout just gives it deterministic tools.
+- 🧠 **Your agent is the brain — no API key.** The engine contains no LLM. Exploration runs on the agent and subscription you already have (Claude Code, Cursor, Copilot, Codex, Gemini CLI and others); SceneScout just gives it deterministic tools and the method for using them.
 - 📐 **Structured scene, not pixels.** The agent reads element lists *with layout geometry*, not screenshots. Overlap and off-screen bugs are computed from boxes — deterministic, no vision guessing. Images that failed to load are read from the DOM too. (Screenshots exist only for pixel-native residue like a canvas or a rendering glitch.)
 - 🛡️ **Read-only by default, enforced on the wire.** Destructive actions are blocked at the network layer, not by asking the model nicely. Opt into writes only against disposable data.
 - ✅ **Completion is a contract, not a vibe.** The engine knows the app's routes and *refuses* to file an "extensive" report while any known route is unvisited, unexercised, or un-audited. "Explored a bit and stopped" is structurally impossible.
@@ -80,7 +82,7 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 | **What a finding looks like** | the symptom, **plus** the file behind it and a suggested fix | the symptom, a repro trace, and a regression-test skeleton |
 | **Typical target** | `localhost` while you build | staging, a preview deploy, a client's site |
 
-**Why the codebase helps.** The agent driving SceneScout is Claude Code, which can already read your repository. With the source at hand it knows the app's static routes before opening the browser, so coverage is measured against the real app instead of whatever happened to be linked. It can also check a suspicion against the code before reporting it: "there is no way to export this table" is a much stronger finding once the agent has confirmed no export handler exists. And when something breaks it can open the component or handler responsible and tell you *where* and *how* to fix it — "the save button does nothing" becomes "`OrderForm` swallows the rejected promise in `onSubmit`; surface the error and re-enable the button".
+**Why the codebase helps.** The agent driving SceneScout is a coding agent, which can already read your repository. With the source at hand it knows the app's static routes before opening the browser, so coverage is measured against the real app instead of whatever happened to be linked. It can also check a suspicion against the code before reporting it: "there is no way to export this table" is a much stronger finding once the agent has confirmed no export handler exists. And when something breaks it can open the component or handler responsible and tell you *where* and *how* to fix it — "the save button does nothing" becomes "`OrderForm` swallows the rejected promise in `onSubmit`; surface the error and re-enable the button".
 
 **Why it still works without it.** Everything SceneScout *observes* comes from the running page — elements, layout geometry, console and network errors, design-audit scores, task-ease measurements — and none of that needs source code. Point it at a URL you are allowed to test and it behaves like a thorough QA tester: it explores, reproduces, and files findings with evidence.
 
@@ -104,7 +106,7 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 | | |
 |---|---|
 | **Node** | ≥ 20 |
-| **An MCP client** | [Claude Code](https://claude.ai/code) is the first-class one (it loads the skill); [others work too](#-other-mcp-clients) |
+| **An MCP client** | Claude Code, Cursor, VS Code with Copilot, Codex CLI, Gemini CLI, GitHub Copilot CLI, Windsurf, or [any other](#-other-mcp-clients) |
 | **A web app to test** | SceneScout tests a *live* app: start yours locally first (e.g. `npm run dev`, `make dev-up`), or have the URL of a deployed one you're allowed to test |
 
 ### 1️⃣ Install
@@ -112,9 +114,12 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 It is on npm. Nothing to clone:
 
 ```bash
-npx -y scenescout install      # skill + Chromium (~150 MB, one-time) + registers the server with Claude Code
+npx -y scenescout install                      # Claude Code: skill + server + Chromium (one-time download)
+npx -y scenescout install --client cursor      # or: vscode, codex, gemini, copilot, windsurf (comma-separated for several)
 ```
 
+Either way it downloads the browser and registers the server with the client you named. Claude Code also gets the method as a skill; every other client receives the same method from the server. [What each client gets](#-other-mcp-clients).
+
 **Prefer a Claude Code plugin?** The skill and the server arrive together:
 
 ```
@@ -124,13 +129,13 @@ npx -y scenescout install      # skill + Chromium (~150 MB, one-time) + register
 
 Then download the browser once with `npx -y scenescout install --browser-only`. The command becomes `/scenescout:scenescout`. A plugin's skill comes from this repository and its server from the latest npm release, so right after a release lands here the two can differ for a short while; `/plugin marketplace update scenescout-marketplace` brings the skill up to date.
 
-**Another MCP client?** Run `npx -y scenescout install --browser-only` and [add the server to its config](#-other-mcp-clients).
+**A client that is not in that list?** Run `npx -y scenescout install --browser-only` and [add the server to its config by hand](#-other-mcp-clients).
 
 <details>
 <summary>What <code>install</code> actually does</summary>
 
 1. puts the `/scenescout` skill into `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`) — a `scenescout` folder it didn't create is moved aside to a `.backup-…` copy, never deleted,
-2. downloads the Chromium build SceneScout drives (skipped if you already have it),
+2. downloads the browser SceneScout drives (skipped if you already have it). By default that is Chromium, as two builds: the full browser for headed runs and the headless shell every other run uses. [Choose something else](#-choosing-browsers) with `--browsers`,
 3. registers the MCP server with Claude Code at user scope. Run through `npx`, the launcher is `npx -y scenescout serve`, with the absolute path of `npx` where one sits beside node, so it works under nvm/fnm. From a clone or a global install it is the absolute node path plus that install's `dist/mcp-server.js`.
 
 Re-run it any time: after moving the folder or switching node versions it refreshes the stored paths. It exits non-zero if any step failed, so it is safe to chain. Opt out of a step with `--no-register` or `--skip-browser`.
@@ -146,8 +151,8 @@ claude mcp add --scope user scenescout -- npx -y scenescout serve
 ### 2️⃣ Check it
 
 ```bash
-npx -y scenescout doctor            # everything, for the default install
-npx -y scenescout doctor --engine   # plugin install or another MCP client: node + build + browser only
+npx -y scenescout doctor --engine   # any client: node + build + browser
+npx -y scenescout doctor            # Claude Code: the above, plus the skill and the registration
 ```
 
 Every line should be a ✓. Anything that isn't prints the exact command that fixes it. Then **start a fresh session** in your client so it picks up the new tools.
@@ -156,13 +161,19 @@ Every line should be a ✓. Anything that isn't prints the exact command that fi
 
 No app handy? Clone this repository and run `npm run demo:serve`: the [demo app](demo-app/) starts on `http://127.0.0.1:4173`.
 
-From Claude Code, inside the project you want to test (or, for a [remote URL](#-two-ways-to-use-it), any folder):
+Open your agent inside the project you want to test (or, for a [remote URL](#-two-ways-to-use-it), any folder) and ask:
+
+```
+Use SceneScout to test http://localhost:3000 at medium level
+```
+
+In Claude Code the skill gives you a command with flags for the same thing:
 
 ```
 /scenescout --level medium --url http://localhost:3000 --role qa
 ```
 
-The skill scans the project (if there is one), attaches read-only, explores, and writes findings to `.scenescout/report.md`. That's it.
+The agent scans the project (if there is one), attaches read-only, explores, and writes findings to `.scenescout/report.md`. That's it.
 
 **Common flags** — `--level minimal|medium|extensive` · `--url <app>` · `--role <name\|path>` (a Playwright storage-state to explore as: a name found by the scan, or a path to the JSON file) · `--observe` / `--safe-write` / `--allow-destructive`.
 
@@ -192,11 +203,11 @@ Snapshots are cheap: re-snapshotting a route returns only *what changed*, with s
 
 ## 🧰 The toolbox
 
-24 deterministic tools. The agent picks; you rarely call these by hand.
+25 deterministic tools. The agent picks; you rarely call these by hand.
 
 | Phase | Tools | What they do |
 |---|---|---|
-| **Set up** | `scout_scan` `scout_attach` `scout_session` | Discover routes; launch a browser in a write-mode; keep several authenticated roles alive at once |
+| **Set up** | `scout_playbook` `scout_scan` `scout_attach` `scout_session` | Hand the testing method to an agent that has no skill loaded; discover routes; launch a browser in a write-mode; keep several authenticated roles alive at once |
 | **Explore** | `scout_crawl` `scout_coverage` | Sweep every route in one call; ask what's still untested |
 | **Look** | `scout_snapshot` `scout_hover` `scout_screenshot` | Read the structured scene (diffed); reveal tooltips/hover cards; capture pixels only when needed |
 | **Act** | `scout_click` `scout_type` `scout_select` `scout_upload` `scout_press` `scout_scroll` `scout_navigate` `scout_back` `scout_run_plan` | Drive the UI like a user; `scout_run_plan` batches a whole mechanical sequence into one call |
@@ -263,7 +274,7 @@ Run `npx -y scenescout doctor` first — it checks every setup item below (every
 | The `scout_*` tools don't appear | The MCP server isn't registered, or points at an old path. `npx -y scenescout install` re-registers it; `claude mcp list` should show `scenescout` as connected. |
 | *"Executable not found in $PATH"* | The server was registered with a bare `node`. `npx -y scenescout install` registers an absolute path. |
 | Installed as a plugin, and the tools fail with *"Executable not found in $PATH: npx"* | A plugin starts the server with a bare `npx`, which Claude Code can only find if it was launched from an environment that has Node on its `PATH`. Under nvm or fnm that means starting Claude Code from a terminal, not from a dock or launcher. Or use `npx -y scenescout install` instead, which registers the absolute path of `npx`. |
-| *"Executable doesn't exist … chromium"* | The browser download was skipped or failed. `npx playwright install chromium` (on Linux add `--with-deps`). |
+| *"… build has not been downloaded yet"* on attach | The browser download was skipped or failed, or the run asked for a browser you did not install. Run the command the message names, for example `npx -y scenescout install --browser-only --browsers firefox`. On Linux, system libraries may be missing too: `npx playwright install --with-deps chromium`. |
 | Tools broke after moving the folder or changing node version | The registration stores absolute paths. `npx -y scenescout install` refreshes them. |
 | Attach fails or every route lands on the login page | Your app isn't running at `--url`, or the `--role` storage state has expired — regenerate it the way your project's Playwright setup does. |
 
@@ -275,17 +286,69 @@ Run `npx -y scenescout doctor` first — it checks every setup item below (every
 ### 🧹 Uninstall
 
 ```bash
+# Claude Code
 claude mcp remove --scope user scenescout
 rm -rf ~/.claude/skills/scenescout
+# Codex / Gemini / Copilot CLI
+codex mcp remove scenescout        # likewise: gemini mcp remove …, copilot mcp remove …
 ```
 
+For Cursor, Windsurf and VS Code, delete the `scenescout` entry from the client's MCP server list.
+
 Nothing else is installed: `npx` runs the package from npm's cache. Per-project memory lives in each tested project's `.scenescout/` folder; delete it there if you want it gone.
 
 ---
 
+## 🌐 Choosing browsers
+
+`install` downloads Chromium and nothing else unless you ask. `--browsers` takes one name, a comma-separated list, or `all`:
+
+| `--browsers` | What is downloaded | About, on disk |
+|---|---|---|
+| `chromium` *(default)* | the full browser and the headless shell | 550 MB |
+| `chromium-headless-shell` | the headless shell only: every run works except `headed` | 200 MB |
+| `firefox` | Firefox | 270 MB |
+| `webkit` | WebKit, the engine behind Safari | 290 MB |
+| `all` | Chromium, Firefox and WebKit | 1.1 GB |
+
+```bash
+npx -y scenescout install --browsers chromium-headless-shell   # the smallest working setup
+npx -y scenescout install --browser-only --browsers firefox,webkit   # add two more later
+```
+
+Sizes vary by platform. The builds go to Playwright's shared cache, so a build another tool already fetched is not downloaded again.
+
+To drive another browser, pass `browser` when attaching (`scout_attach { browser: "firefox" }`), or set `SCENESCOUT_BROWSER=webkit` in the server's environment to change the default. `scenescout doctor` checks the browser named by that variable in the shell it runs from, so check another one with `SCENESCOUT_BROWSER=webkit scenescout doctor`. Two things differ outside Chromium:
+
+- **Service workers are not allowed to register** in Firefox and WebKit. The write policy works by intercepting requests, and only Chromium lets a request issued by a service worker be intercepted. An app that depends on its worker may behave differently there.
+- **A Firefox or WebKit left behind by a crash is not cleaned up** on the next start the way a leftover Chromium is.
+
+In every browser, pages are not given shared workers unless the mode is `destructive`: a request a shared worker sends cannot be intercepted anywhere, so the app is made to do that work on the page, where the policy sees it.
+
 ## 🔌 Other MCP clients
 
-The engine is a plain MCP server over stdio, so any client can drive it. The Claude Code route is the one this project tests. The entries below follow each client's own documentation for a local stdio server and have not been run by the maintainer; if one is out of date, a correction is welcome (say which client version you checked). The server entry is always the same command — `npx -y scenescout serve` — only the config file differs. Download the browser once with `npx -y scenescout install --browser-only`.
+The engine is a plain MCP server over stdio, so any client can drive it, and the testing method reaches the agent through the server itself (see the end of this section). `install` can register it for you:
+
+```bash
+npx -y scenescout install --client cursor            # one client
+npx -y scenescout install --client vscode,codex      # several; add claude-code to keep that one too
+```
+
+| `--client` | How it is registered |
+|---|---|
+| `claude-code` *(default)* | `claude mcp add`, plus the skill |
+| `cursor` | adds an entry to `~/.cursor/mcp.json`, keeping the others |
+| `vscode` | VS Code's own `code --add-mcp`. A `code` command that belongs to another editor is not used |
+| `codex` | `codex mcp add` |
+| `gemini` | `gemini mcp add --scope user` |
+| `copilot` | `copilot mcp add` (GitHub Copilot CLI) |
+| `windsurf` | adds an entry to `~/.codeium/windsurf/mcp_config.json`, keeping the others |
+
+A config file that is not valid JSON is left untouched, and the entry to add by hand is printed instead; a config that is a link into a dotfiles repository is written through the link. When a client that is registered through its own command is not installed, `install` says so and prints the command to run later. Cursor and Windsurf are files, so their entry is written whether or not the editor is installed yet. On Windows, a client installed through npm is a `.cmd` shim that `install` cannot start; it prints the command for you to run instead. Then restart the client and ask its agent: *"Use SceneScout to test http://localhost:3000"*.
+
+What has been checked: registering through each command above was run against Codex CLI, Gemini CLI, GitHub Copilot CLI and VS Code, and Cursor's command line agent read the entry `install` wrote, connected and listed the tools. The Windsurf path follows its documentation. A full test session has been run in Claude Code, with and without the skill. If a client behaves differently for you, a correction is welcome (say which client version you checked).
+
+To register by hand instead, the server entry is always the same command, `npx -y scenescout serve`:
 
 <details>
 <summary><strong>Cursor</strong> — <code>~/.cursor/mcp.json</code> (or <code>.cursor/mcp.json</code> in a project)</summary>
@@ -383,7 +446,12 @@ Most clients accept the same `mcpServers` JSON shape shown for Cursor.
 
 </details>
 
-**The skill is what makes it good.** The tools are only hands and eyes; [`skills/scenescout/SKILL.md`](skills/scenescout/SKILL.md) is the method — what to look at first, when to stop, what counts as a finding. Claude Code loads it as a skill. In another client, give the agent that file as its instructions (a rule, a custom mode, or pasted into the first message).
+**The method travels with the server.** The tools are only hands and eyes; [`skills/scenescout/SKILL.md`](skills/scenescout/SKILL.md) is the method: what to look at first, when to stop, what counts as a finding. Claude Code loads it as a skill. Every other client gets the same text from the server, with nothing to copy:
+
+- the server's instructions tell the agent to call `scout_playbook` before its first attach, and that tool returns the method,
+- clients that list server prompts as commands also get an `explore` prompt, which loads the method and takes an optional URL, level and focus.
+
+So in any client, a first message like *"Use SceneScout to test http://localhost:3000"* is enough. If an agent starts clicking without having called `scout_playbook`, tell it to call that first; how closely a model follows server instructions varies by client.
 
 The CLI is also useful on its own:
 
@@ -398,7 +466,7 @@ npx -y scenescout status <path>     # what a running engine is doing right now
 
 ```
 src/
-  mcp-server.ts     the 24 tools + per-session dispatch
+  mcp-server.ts     the 25 tools + per-session dispatch
   scan.ts           project discovery (framework, routes, auth)
   cli.ts            scan · serve · install · doctor · status
   installer.ts      setup logic (skill link, MCP registration, diagnostics)
@@ -417,7 +485,7 @@ src/
     …               collector · dispatch · fixtures · authloss · reaper
 scripts/            the 12 test suites (smoke/ holds the real-browser ones)
 test-app/           fixtures for the real-browser smoke tests
-skills/scenescout/   the Claude Code skill (SKILL.md)
+skills/scenescout/   the testing method (SKILL.md): a skill in Claude Code, served by the server everywhere else
 docs/adr/           why it's built this way
 ```
 

package/dist/browsers.js

@@ -0,0 +1,185 @@
+/**
+ * Which browsers SceneScout can drive, which builds `scenescout install`
+ * downloads for them, and which build a given launch needs.
+ *
+ * Kept free of Playwright so the rules can be table-tested: the CLI and the
+ * engine pass in the paths Playwright reports and get decisions back.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** A browser the engine can launch. */
+export const BROWSER_ENGINES = ["chromium", "firefox", "webkit"];
+/**
+ * A build Playwright downloads. Chromium comes as two: the full browser, which
+ * a headed run opens, and the headless shell, which every headless run uses.
+ * Installing "chromium" brings both, which is what install has always done.
+ */
+export const INSTALL_TARGETS = ["chromium", "chromium-headless-shell", "firefox", "webkit"];
+export const DEFAULT_ENGINE = "chromium";
+/** Environment variable naming the browser an attach uses when it does not name one. */
+export const DEFAULT_ENGINE_ENV = "SCENESCOUT_BROWSER";
+/** Approximate size on disk, so the install output can say what it is about to fetch. */
+export const APPROX_DISK_MB = {
+    chromium: 550,
+    "chromium-headless-shell": 200,
+    firefox: 270,
+    webkit: 290,
+};
+export function isBrowserEngine(value) {
+    return BROWSER_ENGINES.includes(value);
+}
+/** The engine an attach uses when the caller names none: the environment's choice, else Chromium. */
+export function defaultEngine(env) {
+    const raw = env[DEFAULT_ENGINE_ENV]?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_ENGINE;
+    if (!isBrowserEngine(raw)) {
+        throw new Error(`${DEFAULT_ENGINE_ENV}="${env[DEFAULT_ENGINE_ENV]}" is not a browser SceneScout can drive. Use one of: ${BROWSER_ENGINES.join(", ")}.`);
+    }
+    return raw;
+}
+/**
+ * Read the value of `--browsers`. Absent means what install has always done.
+ * `all` is every engine; a comma-separated list picks several. "chromium"
+ * already includes the headless shell, so naming both is the same as naming it.
+ */
+export function parseBrowserSelection(value) {
+    if (value === undefined)
+        return { targets: ["chromium"] };
+    const names = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const choices = `${INSTALL_TARGETS.join(", ")}, all`;
+    if (names.length === 0)
+        return { error: `--browsers needs a value. Choose from: ${choices}.` };
+    const picked = new Set();
+    for (const name of names) {
+        if (name === "all") {
+            for (const t of ["chromium", "firefox", "webkit"])
+                picked.add(t);
+        }
+        else if (INSTALL_TARGETS.includes(name)) {
+            picked.add(name);
+        }
+        else {
+            return { error: `"${name}" is not a browser SceneScout can install. Choose from: ${choices}.` };
+        }
+    }
+    if (picked.has("chromium"))
+        picked.delete("chromium-headless-shell");
+    return { targets: INSTALL_TARGETS.filter((t) => picked.has(t)) };
+}
+/** The arguments for Playwright's own installer. Target names are Playwright's names. */
+export function playwrightInstallArgs(targets) {
+    return ["install", ...targets];
+}
+/** The build a launch needs on disk. */
+export function launchTarget(engine, headed) {
+    if (engine !== "chromium")
+        return engine;
+    return headed ? "chromium" : "chromium-headless-shell";
+}
+/** The engine each build belongs to. */
+export function engineOf(target) {
+    return target === "chromium-headless-shell" ? "chromium" : target;
+}
+/**
+ * Where the headless shell lives, worked out from the full browser's path.
+ * Playwright exposes no path for the shell, but it keeps the two side by side
+ * under one revision: `chromium-1234/…` next to `chromium_headless_shell-1234/`.
+ * Null when the path does not have that shape.
+ */
+export function headlessShellDir(chromiumExecutable) {
+    if (!chromiumExecutable)
+        return null;
+    const parts = chromiumExecutable.split(/[\\/]/);
+    // The LAST such segment: a cache kept under a directory that happens to be
+    // named the same way must not be mistaken for the build directory.
+    let at = -1;
+    for (let i = parts.length - 1; i >= 0 && at < 0; i--)
+        if (/^chromium-\d+$/.test(parts[i]))
+            at = i;
+    if (at < 0)
+        return null;
+    const sep = chromiumExecutable.includes("\\") && !chromiumExecutable.includes("/") ? "\\" : "/";
+    return [...parts.slice(0, at), parts[at].replace(/^chromium-/, "chromium_headless_shell-")].join(sep);
+}
+/**
+ * Which builds are on disk. `executables` is what Playwright reports for each
+ * engine; a path Playwright names is not proof the file is there. The shell is
+ * counted only once Playwright has marked its download complete.
+ */
+export function browserPresence(executables, exists = fs.existsSync) {
+    const at = (p) => ({ installed: !!p && exists(p), path: p });
+    const shellDir = headlessShellDir(executables.chromium);
+    const shellMarker = shellDir ? path.join(shellDir, "INSTALLATION_COMPLETE") : null;
+    const chromium = at(executables.chromium);
+    return {
+        chromium: { installed: chromium.installed && !!shellMarker && exists(shellMarker), path: chromium.path },
+        "chromium-headless-shell": { installed: !!shellMarker && exists(shellMarker), path: shellDir },
+        firefox: at(executables.firefox),
+        webkit: at(executables.webkit),
+    };
+}
+/** The command that downloads one build, for the way this copy of SceneScout was installed. */
+export function installCommandFor(target, fromCheckout) {
+    const flags = `--browser-only --browsers ${target}`;
+    return fromCheckout ? `node dist/cli.js install ${flags}` : `npx -y scenescout install ${flags}`;
+}
+/**
+ * Whether pages may register service workers in this browser.
+ *
+ * The write policy works by intercepting requests. Only Chromium lets the
+ * driver intercept a request a service worker issues; in Firefox and WebKit
+ * such a request goes straight to the network, so an app that syncs its writes
+ * from a worker would send a DELETE through read-only mode with nothing
+ * logged. Blocking registration there makes the page send those requests
+ * itself, where the policy sees them.
+ */
+export function serviceWorkerPolicy(engine) {
+    return engine === "chromium" ? "allow" : "block";
+}
+/**
+ * The key that moves keyboard focus to the next control, links and buttons
+ * included. WebKit on macOS follows Safari: plain Tab stops only at text
+ * fields, and Option+Tab stops everywhere. A focus audit that pressed Tab
+ * there would walk past every button and report nothing.
+ */
+export function focusAdvanceKey(engine, platform) {
+    return engine === "webkit" && platform === "darwin" ? "Alt+Tab" : "Tab";
+}
+/**
+ * Run in every page before its own scripts: takes shared workers away.
+ *
+ * A request issued by a shared worker cannot be intercepted in any browser, so
+ * a write sent from one passes the policy unseen and unlogged. Removing the
+ * constructor makes feature detection fail, and an app then does that work on
+ * the page, where the policy sees it. Not applied in `destructive` mode, where
+ * the policy blocks nothing and the person has opted in to everything.
+ */
+export const REMOVE_SHARED_WORKER_SCRIPT = `(() => {
+  try { delete globalThis.SharedWorker; } catch {}
+  if ("SharedWorker" in globalThis) {
+    try { Object.defineProperty(globalThis, "SharedWorker", { value: undefined, configurable: true, writable: true }); } catch {}
+  }
+})()`;
+/** Whether pages may use shared workers in this write mode. */
+export function sharedWorkersAllowed(mode) {
+    return mode === "destructive";
+}
+/**
+ * What install says when the browsers it was asked for do not include the one
+ * a default attach launches, and that one is not on disk either. Without it,
+ * `install --browsers firefox` on a fresh machine ends in "ready" and the first
+ * attach fails. Null when there is nothing to say.
+ */
+export function defaultAttachNote(opts) {
+    if (opts.defaultInstalled || opts.selected.length === 0)
+        return null;
+    if (opts.selected.some((t) => engineOf(t) === opts.defaultEngine))
+        return null;
+    const engine = engineOf(opts.selected[0]);
+    return (`an attach drives ${opts.defaultEngine} unless told otherwise, and that build is not installed. ` +
+        `Pass browser: "${engine}" when attaching, or set ${DEFAULT_ENGINE_ENV}=${engine} in the MCP server's environment.`);
+}