cdp-mcp 0.1.2 → 0.2.0

package/docs/known-chromium-gaps.md

@@ -0,0 +1,138 @@
+# Known Chromium gaps
+
+Specs in the L3 e2e suite that fail (or fail intermittently) on Chromium but
+pass on Chrome stable. Every entry below is a real coverage gap on Linux
+ARM64 + Chromium (the day-1 primary target) — not a CI-only concession.
+
+If the gap is mitigatable in production code, link the fix PR. If it's a CDP
+protocol-version difference, link the Chromium release that includes the fix.
+
+| Spec | Skip tag | CDP method missing/changed | Chromium version that fixes it | Tracking |
+|---|---|---|---|---|
+| _none yet — populate as L3 lands_ | | | | |
+
+## Pre-flagged risks (not yet observed; documented for triage)
+
+These are known protocol-version-sensitive areas the test+eval plan flagged
+as risky during planning. Add a row above when one of them actually fires
+on the e2e suite.
+
+- **`Network.loadNetworkResource`** — Used by `src/sourcemap/loader.ts:113`
+  to fetch source maps through the browser's network stack (so cookies/
+  origin/auth flow naturally). Older Chromium revisions ship a more limited
+  param set (no `options.includeCredentials`, no `options.disableCache`);
+  the production code already has a Node-fetch fallback, but verify the
+  fallback path is exercised under the older Chromium.
+
+- **`Page.captureScreenshot`** flag set — `captureBeyondViewport` and
+  `quality` (when `format=jpeg`) gained options across versions. The
+  screenshot e2e spec asserts byte-shape, not flag-respect, so this is
+  most likely to surface as a "bytes don't match" assertion under older
+  Chromium.
+
+## Conventions
+
+- Add a `// @chromium-skip — <gap-id>` comment on the spec's `it()` line.
+- Set the spec to `it.skipIf(process.env.CDP_TEST_BROWSER === "chromium")` or
+  use vitest's `.skip` with a runtime check.
+- Every skip MUST have a corresponding row in the table above. **Enforced** by
+  `scripts/check-chromium-skips.mjs` — runs as `pretest:e2e` on every PR and
+  also as `npm run lint:chromium-skips`. Greps `test/e2e/**/*.test.ts` for
+  `@chromium-skip` tags and `it.skipIf`/`describe.skipIf` Chromium guards,
+  parses the table above, exits 1 if any skip lacks a row OR any row points
+  at a spec that no longer exists. Zero-skip state (the current state) is
+  fine — the script is a no-op.
+
+_(no entries below this line yet means no L3 specs needed a Chromium skip)_
+
+## Known host gaps (not Chromium-version issues)
+
+These are host/library combinations where the e2e suite cannot run end-to-
+end, separate from the per-Chromium-version skip mechanism above. Listed
+here so future contributors don't waste a debug cycle.
+
+- **Windows 11 + chrome-launcher 1.2.1.** `chrome-launcher.launch()`'s
+  internal startup-port poll always fails with `ECONNREFUSED` on this Win11
+  configuration, regardless of headless mode (`--headless=new`, classic
+  `--headless`, or non-headless), browser (Chrome stable from Program
+  Files, Playwright-bundled Chromium under `~/AppData/Local/ms-playwright/
+  chromium-XXXX/chrome-win64/chrome.exe`), or how the port is selected
+  (chrome-launcher-managed vs explicit). Spawning `chrome.exe` directly via
+  `Start-Process` and probing `/json/version` over HTTP works fine — only
+  chrome-launcher's launch path fails. The same code works on Linux (CI)
+  and is widely used elsewhere, so this is a Windows-host quirk rather
+  than a cdp-mcp issue. **Workaround**: run L3 changes under WSL2
+  (Ubuntu) or push and let CI validate (but see WSL2 caveat below). Unit
+  + L2 tests work fine on native Windows.
+
+  *Originally hit on agents/l3-impl during PR #11 implementation.
+  Cross-confirmed by Codex reviewer who diagnosed the on-CI failure
+  separately — turned out to be a different root cause (Codex blocker on
+  --remote-debugging-port=0 in chromeFlags overriding chrome-launcher's
+  own port). After that fix, CI on Linux is the live validation; Win11
+  local-host status remains as documented here.*
+
+- **macOS arm64 + system unbranded Chromium (brew cask).** The `chromium`
+  Homebrew cask is **deprecated** ("does not pass the macOS Gatekeeper
+  check; will be disabled 2026-09-01"). Install completes and the wrapper
+  script lands at `/opt/homebrew/bin/chromium`, but on first launch
+  Gatekeeper rejects the `.app` as "damaged" and the binary is unusable
+  for unattended e2e/eval runs. Workaround for darwin-arm64: use Playwright
+  Chrome-for-Testing (`npx playwright install chromium`) — `resolveBrowser`
+  picks it up automatically from `~/Library/Caches/ms-playwright/chromium-
+  <rev>/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/
+  Google Chrome for Testing` (CfT layout added to `pickPlaywrightExe` in
+  the same PR that landed this entry). The resolver also explicitly skips
+  the brew-cask wrapper on darwin (`isBrewCaskChromium`) so users who
+  tried the deprecated cask first — and then turn to Playwright per this
+  entry — fall through to the Playwright cache instead of getting the
+  Gatekeeper-rejected wrapper back from Step 2. Functionally Chromium-
+  channel at a fixed protocol revision, but Google-branded — call it out
+  if your eval needs *unbranded* Chromium. Building Chromium from source
+  on macOS is multi-hour + multi-GB ongoing maintenance; not a viable
+  automation path.
+
+  *Originally hit while validating set_breakpoint idempotency on a
+  macOS arm64 host.*
+
+- **WSL2 (Ubuntu) + snap-installed chromium.** Default-template Ubuntu on
+  WSL2 ships chromium as a snap (`/snap/bin/chromium`), which runs in a
+  confined namespace. chrome-launcher launches the binary successfully
+  (visible window appears under WSLg) but its startup-port poll
+  `ECONNREFUSEs` on iter 1 and often iter 2 — the debug port either
+  binds to a different port than chrome-launcher polled (race) or is
+  invisible across the snap sandbox boundary. After 2-4 retries the
+  agent's tool-use loop eventually picks an instance that responds, so
+  the eval does run, but every trial pays an inflated cost in retry
+  iterations and the trace is contaminated with WARN entries that look
+  like real failures. Same chrome-launcher code path is clean on macOS,
+  Linux native, and Linux CI.
+
+  **Workaround options**: (a) **prefer macOS or Linux native** for
+  interactive eval iteration — a macOS arm64 host confirmed clean;
+  (b) install non-snap chromium in WSL2 via apt or
+  symlink Playwright's bundled chromium to `/usr/local/bin/chromium-browser`
+  before the snap path; (c) accept the noise and rely on CI for the
+  authoritative signal. Don't rely on WSL2 for eval validation runs.
+
+  *A re-run on the same commit (`f0ce92a`) on a native host showed 0
+  chrome-launcher errors, isolating the cause to the WSL2 + snap-chromium
+  combination rather than the harness.*
+
+- **Ubuntu 23.10+ (incl. 24.04) + Playwright-bundled Chromium.** Recent
+  Ubuntu kernels restrict unprivileged user namespaces via AppArmor, and
+  Playwright-bundled Chromium ships without a SUID `chrome_sandbox`
+  helper. Without `--no-sandbox`, Chromium FATALs at startup
+  (`zygote_host_impl_linux.cc: No usable sandbox!`) before opening its
+  debug port — chrome-launcher's port-poll loop then times out with
+  ECONNREFUSED, looking exactly like the WSL2/snap gap above but with a
+  different root cause. **Mitigation:** `launchChrome` defaults
+  `sandbox: false` so `--no-sandbox` is added automatically; eval
+  pipelines on this host work out-of-the-box. For the full security model,
+  including `sandbox: true`, AppArmor, snap confinement, and Bubblewrap, see
+  [docs/chromium-sandboxing.md](./chromium-sandboxing.md).
+
+  *First observed on an Ubuntu 24.04 arm64 host (Parallels VM) while
+  validating the L4 eval suite. Quick eval went from FAIL/$0.34/445s
+  (chrome-launcher retry storm) to PASS/$0.31/107s once `--no-sandbox`
+  was the default.*

package/docs/launchd-service.md

@@ -0,0 +1,217 @@
+# macOS: Run as a Persistent Service (launchd)
+
+Register `cdp-mcp` as a launchd user agent so it starts automatically on login
+and exposes the MCP SSE endpoint on `127.0.0.1:9719`.
+
+Persistent service mode is useful for MCP clients that support SSE because the
+`cdp-mcp` process and its browser/CDP session can survive MCP client restarts or
+reconnects. It does **not** persist state across service-process restarts.
+
+> Security note: the local SSE endpoint has no authentication. MCP tools include
+> in-page JavaScript evaluation and filesystem writes via screenshot paths. Only
+> run a persistent service on trusted single-user machines, and do not bind it to
+> non-loopback interfaces unless you understand the `--allow-remote` exposure.
+
+## Contents
+
+- [1. Install the server](#1-install-the-server)
+- [2. Create the plist](#2-create-the-plist)
+- [3. Load and start](#3-load-and-start)
+- [4. Verify](#4-verify)
+- [5. Configure an MCP client](#5-configure-an-mcp-client)
+- [6. Logs](#6-logs)
+- [7. Stop / uninstall](#7-stop--uninstall)
+- [8. Upgrade](#8-upgrade)
+- [Troubleshooting](#troubleshooting)
+
+## 1. Install the server
+
+Requires Node.js 20+ and a local Chrome/Chromium browser.
+
+```bash
+npm install -g cdp-mcp
+```
+
+Verify with `cdp-mcp --help`. The package ships prebuilt `dist/`, so there is no
+build step and no repo checkout needed.
+
+If `launch_chrome` cannot find Chrome/Chromium automatically, set `CHROME_PATH`
+in the plist generated below.
+
+## 2. Create the plist
+
+Run this from any directory:
+
+```bash
+# If you use fnm, nvm, or another Node version manager, set these variables to
+# stable paths before running this snippet. Example:
+# NODE_BIN="$HOME/.local/share/fnm/aliases/default/bin/node"
+# CDP_SCRIPT="$HOME/.local/share/fnm/aliases/default/bin/cdp-mcp"
+NODE_BIN="${NODE_BIN:-$(command -v node)}"
+CDP_SCRIPT="${CDP_SCRIPT:-$(command -v cdp-mcp)}"
+CHROME_PATH="${CHROME_PATH:-}"
+
+if [ -z "$NODE_BIN" ]; then
+  echo "Error: node not found in PATH. Install Node 20+ first." >&2
+  exit 1
+fi
+if [ -z "$CDP_SCRIPT" ]; then
+  echo "Error: cdp-mcp not found. Run 'npm install -g cdp-mcp' first." >&2
+  exit 1
+fi
+
+xml_escape() {
+  printf '%s' "$1" \
+    | sed \
+      -e 's/&/\&/g' \
+      -e 's/</\&lt;/g' \
+      -e 's/>/\&gt;/g' \
+      -e 's/"/\&quot;/g' \
+      -e "s/'/\&apos;/g"
+}
+
+NODE_DIR="$(dirname "$NODE_BIN")"
+mkdir -p ~/Library/LaunchAgents ~/Library/Logs/cdp-mcp
+ESC_NODE=$(xml_escape "$NODE_BIN")
+ESC_NODE_DIR=$(xml_escape "$NODE_DIR")
+ESC_CDP=$(xml_escape "$CDP_SCRIPT")
+ESC_HOME=$(xml_escape "$HOME")
+ESC_CHROME=$(xml_escape "$CHROME_PATH")
+cat > ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>io.github.lcjanke2020.cdp-mcp</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$ESC_NODE</string>
+    <string>$ESC_CDP</string>
+    <string>--port</string>
+    <string>9719</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>$ESC_HOME/Library/Logs/cdp-mcp/server.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>$ESC_HOME/Library/Logs/cdp-mcp/server.stderr.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>$ESC_NODE_DIR:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+$(if [ -n "$CHROME_PATH" ]; then printf '    <key>CHROME_PATH</key>\n    <string>%s</string>\n' "$ESC_CHROME"; fi)
+  </dict>
+</dict>
+</plist>
+PLIST
+```
+
+The plist invokes `node` directly with the `cdp-mcp` script path. That makes the
+`NODE_BIN` override authoritative even when your shell uses a Node version
+manager.
+
+## 3. Load and start
+
+On macOS 10.15+, use:
+
+```bash
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
+launchctl kickstart -k gui/$UID/io.github.lcjanke2020.cdp-mcp
+```
+
+Older macOS releases also support:
+
+```bash
+launchctl load ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
+```
+
+## 4. Verify
+
+```bash
+launchctl print gui/$UID/io.github.lcjanke2020.cdp-mcp
+lsof -i :9719
+curl -v --max-time 2 http://127.0.0.1:9719/sse 2>&1 | head -20
+```
+
+The `curl` command should show a `200 OK` response and SSE event output. A
+timeout after the first event is expected because `/sse` keeps the connection
+open. The server also sends periodic SSE keepalive comments by default; tune
+with `CDP_MCP_SSE_KEEPALIVE_MS` only if your MCP client needs a different idle
+interval.
+
+## 5. Configure an MCP client
+
+Point an SSE-capable MCP client at:
+
+```text
+http://127.0.0.1:9719/sse
+```
+
+For example, clients that use JSON MCP server config commonly use:
+
+```json
+{
+  "mcpServers": {
+    "cdp-mcp": {
+      "type": "sse",
+      "url": "http://127.0.0.1:9719/sse"
+    }
+  }
+}
+```
+
+SSE mode is single-client today. Multiple MCP clients connected to the same
+service share one process-global browser/CDP session and can interfere with each
+other. Use one active debugging client per service, or run separate services on
+separate ports.
+
+A reconnecting client resumes the prior session. If you want a clean browser
+session after reconnecting, call `close_session` before launching or attaching
+again.
+
+## 6. Logs
+
+```bash
+tail -f ~/Library/Logs/cdp-mcp/server.stderr.log
+```
+
+## 7. Stop / uninstall
+
+```bash
+launchctl bootout gui/$UID/io.github.lcjanke2020.cdp-mcp
+rm ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
+```
+
+Older macOS releases also support:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
+```
+
+## 8. Upgrade
+
+```bash
+npm install -g cdp-mcp@latest
+launchctl kickstart -k gui/$UID/io.github.lcjanke2020.cdp-mcp
+```
+
+Restart or reconnect your MCP client after a server upgrade so it reloads tool
+schemas.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `bootstrap` says service already loaded | Run `launchctl bootout gui/$UID/io.github.lcjanke2020.cdp-mcp`, then bootstrap again |
+| Service exits immediately | Check `~/Library/Logs/cdp-mcp/server.stderr.log`; usually `cdp-mcp` is not installed, Node is too old, or a version-manager path moved |
+| Port 9719 is already in use | Check `lsof -i :9719`, then stop the other process or change the port in the plist |
+| MCP client rejects the config | Confirm the client supports SSE MCP servers and include both `"type": "sse"` and the `/sse` URL if your client uses JSON config |
+| `launch_chrome` cannot find Chrome | Set `CHROME_PATH` before generating the plist, or edit the plist environment and reload the service |
+| Service not starting after reboot | Verify the plist is in `~/Library/LaunchAgents/`, not `LaunchDaemons` |
+| Service not starting after reboot with fnm/nvm | Version-manager shell paths can be ephemeral. Recreate the plist with stable `NODE_BIN` and `CDP_SCRIPT` paths, or install with a system Node |
+| `already_session` after reconnecting | The prior browser/CDP session is still alive. Resume it, or call `close_session` before starting fresh |

package/docs/local-l3-e2e-setup.md

@@ -0,0 +1,199 @@
+# Local L3 e2e setup (Playwright Chromium + AppArmor)
+
+**Last updated: 2026-06-09**
+
+A step-by-step runbook for getting `npm run test:e2e` (the L3 real-browser
+suite) passing on a local Linux machine **with Chromium's sandbox on**. This is
+the practical companion to [`chromium-sandboxing.md`](./chromium-sandboxing.md);
+read that for the full `--no-sandbox` / `sandbox: true` threat model and the
+validated-hosts table.
+
+Assumes Ubuntu (23.10+/24.04). Other distributions may need no host-side work at
+all — see "Other distributions" below.
+
+## Why this is needed on Ubuntu
+
+The L3 e2e harness launches Chromium with the sandbox **on** when running
+locally; it only adds `--no-sandbox` when the `CI` env var is set
+(`test/e2e/setup/global.ts`). That is deliberate — locally we want the sandbox
+when the host can provide it.
+
+But recent Ubuntu releases ship:
+
+```sh
+kernel.apparmor_restrict_unprivileged_userns = 1
+```
+
+which blocks the unprivileged **user namespace** that Chromium's sandbox needs.
+Playwright-bundled Chromium does not ship a SUID `chrome_sandbox` helper, so on a
+stock Ubuntu host a sandbox-on launch fails before the DevTools port opens:
+
+```text
+zygote_host_impl_linux.cc: No usable sandbox!
+```
+
+From `chrome-launcher` this usually surfaces as a startup port-poll timeout or
+`ECONNREFUSED`.
+
+The fix is an AppArmor profile that grants `userns,` to the Playwright Chromium
+binary, giving it a stable named label that is allowed to create the user
+namespace. The steps below install Chromium, confirm the resolver finds it,
+attach the profile, and run the suite.
+
+## 1. Install Playwright Chromium
+
+From the repo:
+
+```sh
+npx --yes playwright install chromium
+```
+
+This drops a managed Chromium into the per-user cache:
+
+```text
+~/.cache/ms-playwright/chromium-<rev>/chrome-linux*/chrome
+```
+
+The leaf directory varies by Playwright version and arch — `chrome-linux` on
+ARM64 and older builds, `chrome-linux64` on x86_64 with the newer
+Chrome-for-Testing layout (the resolver and the AppArmor glob below cover both).
+Install it for **each OS user** that will run the suite — the cache is
+per-`$HOME`.
+
+## 2. Verify the resolver finds it
+
+The launcher resolver (`src/util/browser-resolve.ts`) finds Chromium in this
+order: an explicit `CDP_TEST_BROWSER_PATH`, then a system `chromium` on `PATH`,
+then the Playwright cache. After a build, confirm what it picks:
+
+```sh
+npm run build
+node --input-type=module \
+  -e "import('./dist/util/browser-resolve.js').then(m => console.log(JSON.stringify(m.resolveBrowser(), null, 2)))"
+```
+
+This runbook targets the **Playwright-cache** binary, so expect
+`source: "playwright-cache"` and a `binaryPath` under `~/.cache/ms-playwright/`:
+
+```json
+{
+  "binaryPath": "/home/<user>/.cache/ms-playwright/chromium-<rev>/chrome-linux/chrome",
+  "choice": "chromium",
+  "snapConfined": false,
+  "source": "playwright-cache"
+}
+```
+
+If you have a system Chromium on `PATH` (apt `/usr/bin/chromium`, snap
+`/snap/bin/chromium`), the resolver returns that first with
+`source: "which-chromium"` — that binary is *not* covered by the AppArmor
+profile below (snap brings its own confinement; apt Chromium is a separate
+sandbox story). To exercise the Playwright binary under this profile, point the
+suite at it explicitly:
+
+```sh
+export CDP_TEST_BROWSER_PATH="$(ls -d ~/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | head -1)"
+```
+
+## 3. Attach the AppArmor profile
+
+First confirm the kernel knob is the restrictive default:
+
+```sh
+sysctl kernel.apparmor_restrict_unprivileged_userns   # = 1 on stock Ubuntu 24.04
+```
+
+If it is `0` (some hosts turn it off system-wide), Chromium's sandbox already
+works and you can skip to step 5.
+
+Create a profile that grants `userns,` to the Playwright Chromium binary path.
+This mirrors the shape of Ubuntu's stock `chrome` / `msedge` / `brave` profiles
+(a named-unconfined profile that opts into user namespaces):
+
+```apparmor
+# /etc/apparmor.d/cdp-mcp-chromium
+abi <abi/4.0>,
+include <tunables/global>
+
+profile cdp-mcp-chromium /home/*/.cache/ms-playwright/chromium-*/chrome-linux*/chrome flags=(unconfined) {
+  userns,
+
+  include if exists <local/cdp-mcp-chromium>
+}
+```
+
+The `chrome-linux*` component matches both the `chrome-linux` (ARM64/older) and
+`chrome-linux64` (x86_64 Chrome-for-Testing) layouts — in AppArmor `*` matches
+within a single path segment, so a too-specific `chrome-linux` would silently
+fail to attach on x86_64. The `/home/*/` glob matches any user's Playwright
+cache; if you prefer to scope it to specific accounts, replace `*` with a brace
+list of usernames, e.g. `/home/{alice,bob}/.cache/...`.
+
+Load it (profiles in `/etc/apparmor.d/` also auto-load at boot):
+
+```sh
+sudo apparmor_parser -r /etc/apparmor.d/cdp-mcp-chromium
+```
+
+## 4. Verify the label attaches
+
+Launch the bundled Chromium sandbox-on and read its AppArmor label — it must be
+the named profile, not bare `unconfined`:
+
+```sh
+BIN=$(ls -d ~/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | head -1)
+"$BIN" --headless=new --no-startup-window --remote-debugging-port=0 \
+       --user-data-dir=$(mktemp -d) about:blank & pid=$!
+sleep 3; cat /proc/$pid/attr/current   # -> cdp-mcp-chromium (unconfined)
+kill $pid
+```
+
+If this prints `cdp-mcp-chromium (unconfined)`, the profile is attached. A bare
+`unconfined` means the binary path didn't match the profile's glob — re-check
+the cache path against the profile.
+
+## 5. Run L3
+
+```sh
+npm run test:e2e
+```
+
+With the sandbox on and the profile attached, the suite should pass, e.g.:
+
+```text
+Test Files  10 passed (10)
+Tests       29 passed (29)
+```
+
+## Fallback (before AppArmor is configured)
+
+The L3 harness adds `--no-sandbox` when `CI` is set, so you can run the suite
+without the profile as a lower-security stopgap:
+
+```sh
+env CI=1 npm run test:e2e
+```
+
+This keeps work moving, but the AppArmor profile is the desired long-term
+posture so that plain `npm run test:e2e` exercises sandbox-on Chromium. See
+[`chromium-sandboxing.md`](./chromium-sandboxing.md) for why `--no-sandbox`
+widens the blast radius of a compromised renderer.
+
+## Other distributions
+
+This profile work is Ubuntu-specific. Distributions that don't restrict
+unprivileged user namespaces by default (or use SELinux instead of AppArmor,
+e.g. Fedora) generally run sandbox-on Chromium without a host-side profile.
+Validate the actual host before assuming the Ubuntu steps are required — check
+`sysctl kernel.apparmor_restrict_unprivileged_userns` (absent or `0` means no
+AppArmor userns restriction to work around).
+
+## Related
+
+- [`docs/chromium-sandboxing.md`](./chromium-sandboxing.md) — the canonical
+  `--no-sandbox` / `sandbox: true` threat model, the AppArmor / userns / snap /
+  Bubblewrap mechanism map, and the validated-hosts table.
+- [`docs/known-chromium-gaps.md`](./known-chromium-gaps.md) — per-spec
+  Chromium-vs-Chrome gaps and host-OS workarounds.
+- [README §L3](../README.md) — browser selection, `CDP_TEST_BROWSER_PATH`, and
+  the per-platform support matrix.