mcp-accessibility-scanner 3.4.0 → 3.5.0

package/README.md

@@ -140,7 +140,9 @@ npx mcp-accessibility-scanner --extension
 Set `PLAYWRIGHT_MCP_EXTENSION_TOKEN` to the token shown by the extension to bypass the connection approval dialog. The relay's CDP WebSocket endpoint always requires a separate random token, generated per relay and appended automatically for the server's own connection. This CDP token is never passed in Chrome's launch arguments or extension URL; the extension approval token cannot authenticate a CDP client.
 Token-bypass connections are not background-safe: Chrome focuses the connection tab and window, and client-created tabs remain open after disconnect ([upstream limitation](https://github.com/microsoft/playwright/issues/42343)).
 With a token, the extension must connect and finish setup within 30 seconds after the connection page opens. Failed attempts release the relay so the next tool call can retry. Without a token, manual approval waits until you approve or cancel the call.
-When `--user-data-dir` contains multiple Chrome profiles, the profile with the extension installed is selected automatically, preferring Chrome's last-used profile.
+When `--user-data-dir` contains multiple Chrome profiles, the profile with the extension installed is selected automatically, preferring Chrome's last-used profile. Pass `--profile-dir-name` (or set `PLAYWRIGHT_MCP_PROFILE_DIR_NAME`) to select a profile explicitly; it requires `--user-data-dir` and accepts a Chrome profile directory name such as `Default` or `Profile 1` (see "Profile Path" at `chrome://version`). The `PLAYWRIGHT_MCP_EXTENSION_TOKEN` approval token is specific to the profile, so when selecting a profile explicitly, use the token shown in that profile.
+
+Packed extensions require an enabled record in the profile's preferences; a leftover extension directory alone does not count as installed. Profiles whose preferences mark the extension disabled or uninstalled are excluded from automatic selection and rejected for explicit selection. Explicit selection with a custom executable skips local installation checks. A whitespace-only `PLAYWRIGHT_MCP_PROFILE_DIR_NAME` is treated as unset; other string environment variables retain their existing blank-value handling.
 
 ### Discovering available tools (`list-tools` subcommand)
 
@@ -203,7 +205,8 @@ Create a `config.json` file with the following options:
   "timeouts": {
     "navigationTimeout": 60000,
     "defaultTimeout": 5000,
-    "settle": 500
+    "settle": 500,
+    "idle": 0
   },
   "network": {
     "allowedOrigins": ["example.com", "trusted-site.com"],
@@ -229,18 +232,23 @@ Create a `config.json` file with the following options:
 - `browser.cdpTimeout`: Maximum time in milliseconds to wait when connecting to the CDP endpoint (default: `30000`)
 - `browser.cdpLaunch`: Launch a Chromium-family desktop app with CDP enabled, wait for the endpoint, and manage the child process lifecycle
 - CDP attach modes preserve the target browser's existing default-context settings instead of applying Playwright's defaults.
-- `browser.contextOptions.storageState`: Start each session from a recorded Playwright storage state; applied in every mode except `--extension` (fresh contexts receive it at creation, reused contexts via `setStorageState()`). Sessions that share one reused context (non-isolated CDP modes) get the state applied once per context — a session joining a live context inherits its current state, not a fresh copy of the file; see [Auditing pages behind a login](#auditing-pages-behind-a-login)
+- `browser.contextOptions.storageState`: Start a fresh context from a recorded Playwright storage state. Imports into existing CDP or VS Code contexts are rejected; use `--isolated` for CDP or sign in interactively. The default persistent mode uses a fresh disposable profile. See [Auditing pages behind a login](#auditing-pages-behind-a-login).
+- `browser.profileDirName`: Chrome profile directory name used in extension mode, for example `Default` or `Profile 1` (CLI: `--profile-dir-name`, env: `PLAYWRIGHT_MCP_PROFILE_DIR_NAME`). Requires `--user-data-dir` and extension mode (`--extension` or `--connect-tool`); defaults to the last-used profile that has the extension installed.
 - `timeouts.navigationTimeout`: Maximum time for page navigation in milliseconds (default: `60000`)
 - `timeouts.defaultTimeout`: Default timeout for Playwright operations in milliseconds (default: `5000`)
 - `timeouts.settle`: How long to wait after every action before responding (default: `500`). An action that finishes quietly is first watched for up to 100ms (or the settle delay, whichever is shorter) so scheduled network work can still be awaited before the settle delay.
+- `timeouts.idle`: Release the default browser context after this many idle milliseconds (default: `0`, disabled). Accepts integers from `0` to `2147483647`.
 - `network.allowedOrigins`: List of origins to allow (blocks all others if specified)
 - `network.blockedOrigins`: List of origins to block
 - `snapshot.boxes`: Include each element's viewport-relative bounding box as `[box=x,y,width,height]` in snapshots (default: `false`; CLI: `--snapshot-boxes`, env: `PLAYWRIGHT_MCP_SNAPSHOT_BOXES=1`)
+- `imageResponses`: `allow` (default) returns text and images; `omit` excludes images; `only` omits text from successful responses containing images. Errors, browser lifecycle notices, and responses without images (including full-page screenshots) keep their text. Structured results and resource links are always preserved. In `only` mode, screenshot save-path text, generated code and any accompanying text-only findings are omitted; use `allow` if you need them. Interactive mode rejects `only` because its REPL prints text only; use `allow` or `omit` there. `auto` remains a legacy alias for `allow`. CLI: `--image-responses only`; env: `PLAYWRIGHT_MCP_IMAGE_RESPONSES=only`. Precedence: CLI, then environment, then config file.
 - `server.authToken`: When set, Streamable HTTP requests (`--port`) require `Authorization: Bearer <token>` or return `401` (env: `PLAYWRIGHT_MCP_AUTH_TOKEN`). Blank or malformed tokens fail at startup. The scheme is case-insensitive; the token is exact. Bearer auth does not encrypt traffic: authenticated listeners must bind to loopback, such as `--host 127.0.0.1`; use a TLS reverse proxy for remote access. The printed client config includes a header placeholder to replace locally, without logging the secret. Unset keeps unauthenticated access.
 - `outputDir`: Directory for output files — reports, screenshots, traces, and session logs (CLI: `--output-dir`, env: `PLAYWRIGHT_MCP_OUTPUT_DIR`). Defaults to a fresh directory under the system temp folder, resolved once per server run so all of a run's artifacts land together. The output location is always server configuration; the deprecated MCP roots capability (client workspace folders) is no longer consulted.
 
 CLI equivalents are also available: `--cdp-launch-command`, `--cdp-launch-args`, `--cdp-launch-cwd`, `--cdp-launch-port`, `--cdp-launch-startup-timeout`, `--cdp-endpoint`, `--cdp-header` (repeat for multiple headers, e.g. `--cdp-header "Authorization: Bearer <token>"`), and `--cdp-timeout`. The CDP headers and timeout can also be set via the `PLAYWRIGHT_MCP_CDP_HEADERS` (one `Name: Value` entry per line) and `PLAYWRIGHT_MCP_CDP_TIMEOUT` environment variables.
 
+If CDP attachment times out after the WebSocket connects, an existing sleeping or unresponsive tab may be blocking Playwright's browser initialization ([upstream report](https://github.com/microsoft/playwright/issues/42730)). Use an explicit positive `--cdp-timeout` to bound the attempt. Inspect or wake the affected tabs yourself, or attach to a separate disposable browser. `noDefaults` and `--isolated` do not skip initialization of existing tabs; the server does not close your tabs or bypass Playwright's initialization to work around this.
+
 For remote HTTP access, configure the TLS reverse proxy explicitly. For example, with the MCP server bound using `--host 127.0.0.1 --port 8931` and `PLAYWRIGHT_MCP_AUTH_TOKEN` set:
 
 - Accept only your configured public hostname over HTTPS and forward `/mcp` to `http://127.0.0.1:8931/mcp`.
@@ -254,6 +262,8 @@ Caller-supplied screenshot, PDF, scan-page-matrix, and audit report filenames us
 
 Use `--timeout-settle` or `PLAYWRIGHT_MCP_TIMEOUT_SETTLE` to override the post-action settle delay. It applies after every action so delayed DOM-only updates are included in the response; a short observation window also catches scheduled requests and waits for them before that delay.
 
+Use `--timeout-idle 300000`, `timeouts.idle`, or `PLAYWRIGHT_MCP_TIMEOUT_IDLE` to release the default browser after five idle minutes. Shared contexts stay open while any client is working; the idle window starts after the last tool call or download finishes. Explicit recordings prevent idle release until `browser_stop_recording` finishes; passive `--save-session` capture does not. Cleanup finalizes traces. The next browser tool call reopens the connection and includes a note to navigate again and refresh element references. Attached CDP, extension, and VS Code browsers are disconnected; their external pages remain open. Close and session-management tools do not relaunch an idle browser. Explicit `browser_session_open` handles keep their separate `PLAYWRIGHT_MCP_BROWSER_SESSION_TTL_MS` behavior. Zero disables this feature; blank environment values leave the existing configuration unchanged.
+
 The VS Code `browser_connect` tool accepts only `playwright` or `playwright-core` libraries and loopback WebSocket URLs. Set `PLAYWRIGHT_MCP_VSCODE_ALLOW_REMOTE=1` to allow remote endpoints, which must use `wss:`. URL userinfo credentials are rejected.
 
 #### HTTP Heartbeat
@@ -314,10 +324,14 @@ PLAYWRIGHT_MCP_ISOLATED=true PLAYWRIGHT_MCP_STORAGE_STATE=./auth.json npx mcp-ac
 
 > **Every supported mode handles the state — by applying it or refusing it.**
 >
+> **Playwright 1.63.0 safety restriction:** importing into an existing context is rejected before taking a rollback snapshot or resetting any storage. On this pin, snapshot capture can execute service-worker-served scripts for a previously visited origin whose tab is no longer open ([upstream fix](https://github.com/microsoft/playwright/pull/42664)). Use a fresh context, or omit `--storage-state` and sign in interactively. Service workers are not disabled. A future dependency upgrade must also pass the recorder/shared-client checks in [#218](https://github.com/JustasMonkev/mcp-accessibility-scanner/issues/218) and IndexedDB checks in [#224](https://github.com/JustasMonkev/mcp-accessibility-scanner/issues/224) before this restriction is reconsidered.
+>
+> **IndexedDB snapshot limitation:** on pinned Playwright 1.63.0 with Chromium 153.0.8010.12 and Firefox 155.0, `storageState({ indexedDB: true })` loses `Map` and `Set` contents. Both `newContext({ storageState })` and `setStorageState()` restore them as empty plain objects; ordinary JSON records survive. Fresh contexts protect existing browser data, but cannot recover values already lost during capture. The [upstream fix](https://github.com/microsoft/playwright/pull/42707) is merged but is not in this pin. Before allowing imports into existing contexts again, verify both restore paths preserve Map/Set types and entries on each supported engine, including after a failed import. The real-browser regression in `tests/browser-failures.integration.test.ts` checks that rejecting an import leaves the original Map/Set records intact and that isolated JSON IndexedDB imports still work.
+>
 > - **Fresh-context modes** (`--isolated`, the remote-endpoint mode, or either CDP mode combined with `--isolated`): the context is created with the storage state directly.
 > - **Default persistent-profile mode with `--storage-state`**: the session runs in a fresh, disposable profile — unique to that session and removed when it closes — built from the state, so the recorded state is provably the only session data (without `--storage-state` the regular persistent profile is used and survives restarts, as before). Any page the launch opened (for example from a URL in `browser.launchOptions.args`) is parked on a blank replacement before the state lands, then the replacement is navigated to the same URL, so a still-running anonymous page cannot overwrite the recorded identity and a scan never reads its DOM. This also means `--storage-state` cannot be combined with `--user-data-dir` (a user-supplied profile carries its own session and will not be wiped; the server refuses the combination).
-> - **CDP modes without `--isolated`**: the state is installed into the browser's existing context with Playwright's `setStorageState()`. Cookies are fully reset; origin storage (localStorage/IndexedDB) is reset for the origins recorded in the state *plus* any origins the Playwright connection has already seen — including pages open in the attached browser at connect time, whose storage can therefore be cleared even when the state omits them. Only origins from the profile's earlier history that this connection never saw survive untouched — cut in both directions, so treat an attached browser's storage as neither fully preserved nor fully reset, and add `--isolated` when you need a clean, fully-defined session. Pages already open in the attached browser are replaced with fresh tabs navigated to the same URLs so a scan never sees the previous identity's UI — and the old pages close *before* the state is installed, because a still-running page could otherwise persist the previous identity back into the freshly applied cookies or localStorage, which no later tab replacement could undo. A fresh tab also starts with empty per-tab `sessionStorage` (which sits outside Playwright storage states and would survive an in-place reload, where the old page's own scripts could even write the previous identity back between a clear and the reload), a replacement that fails to load is left blank or closed rather than left on a stale document, and these navigations run under a configured `--allowed-origins`/`--blocked-origins` policy just like every later navigation. The state is applied once per shared context: concurrent MCP sessions attached without `--isolated` share the browser's context, so a session joining while another is active inherits that context's live state (including anything the first session changed or cleared) rather than a fresh copy of the recorded file — add `--isolated` when every session must start from the recorded baseline.
-> - **`--extension`** (with or without `--isolated`) is the one exception: it works through the browser you are already running, where wiping cookies to install a recorded state is not an acceptable side effect, so the server refuses to start rather than doing that silently. There, sign in interactively instead — the persistent profile also keeps the session across restarts.
+> - **CDP modes without `--isolated` and the VS Code provider**: `--storage-state` is rejected when the browser already has a context. Add `--isolated` in CDP mode to create a fresh context; otherwise omit the state and sign in interactively. If the browser exposes no context, the server creates one with the state. CDP sessions joining that same server-created context inherit its live state without resetting it.
+> - **`--extension`** (with or without `--isolated`) refuses storage imports entirely: it works through the browser you are already running, where wiping cookies to install a recorded state is not an acceptable side effect, so the server refuses to start rather than doing that silently. There, sign in interactively instead — the persistent profile also keeps the session across restarts.
 
 ### Keep the crawl from destroying its own session
 
@@ -337,6 +351,8 @@ The check compares which cookies the crawled URLs carry, not their values, so a
 
 ## Available Tools
 
+Page-registered WebMCP tools are not currently exposed. See the [WebMCP adoption decision](https://github.com/JustasMonkev/mcp-accessibility-scanner/blob/main/docs/decisions/001-webmcp-adoption.md) for the deferral and conditions for revisiting an opt-in capability.
+
 The MCP server provides comprehensive browser automation and accessibility scanning tools:
 
 ### Core Accessibility Tool
@@ -355,7 +371,7 @@ Performs a comprehensive accessibility scan on the current page using Axe-core.
 **Annotated screenshots:**
 When `annotateScreenshot` is `true`, each violating element is outlined and labelled with the rule ids it failed, a full-page PNG is written to the MCP output directory (`scan-page-annotated-{timestamp}-{token}.png`) and returned as a resource link, and the markers are then removed so the page is left exactly as it was. The markers are drawn in an out-of-flow overlay clipped to each element's own box, so they never reflow the page. The overlay uses a fresh id per scan, is placed in the browser's top layer so it stays visible over an open dialog, popover or fullscreen element, and compensates for a CSS `zoom` or a scaled ancestor so markers line up with what is rendered.
 An element that fails several rules gets one box listing every rule id, and elements inside open shadow roots are marked by walking the shadow path Axe reports.
-Running animations are paused before the elements are measured and resumed after the capture, so a moving target keeps its marker. The markers themselves live in a shadow root under an overlay whose own styles are `!important`, so page CSS cannot restyle or hide what the report counts, and each rule label sits outside the clipped box so it stays readable on an element smaller than its own label.
+Running animations are frozen at their current time before the elements are measured and resumed after the capture, so a moving target keeps its marker. The markers themselves live in a shadow root under an overlay whose own styles are `!important`, so page CSS cannot restyle or hide what the report counts, and each rule label sits outside the clipped box so it stays readable on an element smaller than its own label.
 At most 50 elements are annotated per scan. The result text always reports how many nodes were marked out of the total, plus how many were left out because they exceeded the limit, were hidden, zero-size or off-canvas (a full-page screenshot is clipped to the document box), or were inside an iframe (cross-frame selectors cannot be resolved from the top document).
 
 **Supported Violation Tags:**
@@ -588,6 +604,7 @@ Evaluate a JavaScript expression on the page, or on a specific element when a `r
 Take a screenshot of the current page.
 - Parameters: `filename` (optional), `type` (`png`, `jpeg`, or `webp`), `scale` (`css` or `device`, default `css`), `fullPage` (optional), `element`/`ref` pair (for element screenshots)
 - `scale: device` captures a high-resolution screenshot using device pixels (accounts for the device pixel ratio); `scale: css` keeps the image sized in CSS pixels.
+- An empty capture is an error, and its output file is removed, including automatically named files. The requested format is never silently changed. If a WebP capture is empty, reduce its dimensions or explicitly request PNG/JPEG.
 
 #### `browser_pdf_save`
 Save page as PDF.
@@ -599,6 +616,12 @@ This tool requires `--caps pdf` in the CLI.
 Install the configured browser engine (use when browser executable is missing).
 - Parameters: none
 
+Disabled by default. Enable it at server startup with `--caps install`, `PLAYWRIGHT_MCP_CAPS=install`, or `"capabilities": ["install"]` in the config file. Explicit `core-install` settings remain supported as a deprecated alias; use `install` in new configurations. Without this opt-in, the tool is neither listed nor callable; existing browser installations can still be used.
+
+This tool invokes Playwright's installer, which downloads executable code. In [Playwright 1.63.0](https://github.com/microsoft/playwright/blob/v1.63.0/packages/playwright-core/src/server/registry/oopDownloadBrowserMain.ts), browser archives have no checksum or signature verification before extraction; the default download hosts use HTTPS. Only enable installation when you trust the download source and TLS configuration, including any custom `PLAYWRIGHT_DOWNLOAD_HOST`, browser-specific host overrides, or TLS-inspecting proxy. Do not disable TLS certificate validation.
+
+For deployments that require independently verified binaries, provision the browser through your trusted deployment process and use `--executable-path` or an existing browser connection. The capability opt-in limits MCP-triggered installation; it does not add archive verification or change manual, CI, or Docker build downloads.
+
 ### Browser Management
 
 #### `browser_close`
@@ -675,6 +698,7 @@ Handle browser dialogs (alerts, confirms, prompts).
 #### `browser_file_upload`
 Upload files to the page.
 - Parameters: `paths` (array of absolute file paths)
+- If `setFiles` fails, the chooser stays available for another upload attempt; `paths: []` clears the selection and completes the chooser. A successful upload clears only that chooser and waits for page activity and the configured settle delay.
 
 #### `browser_verify_element_visible`
 Verify an element by ARIA role/name.
@@ -771,6 +795,48 @@ cd mcp-accessibility-scanner
 npm install
 ```
 
+### Playwright upgrade gate
+
+The September 16, 2026 review keeps `playwright` and `playwright-core` paired at
+**1.63.0**, the [latest stable release](https://github.com/microsoft/playwright/releases/tag/v1.63.0)
+on that date. Keep the local `InputRecorder` hub and the existing factory reference
+counts: multiple MCP clients share one client-side browser context, while the hub
+multiplexes session logs and explicit recordings and excludes sibling tool actions.
+A dependency bump alone must not change that ownership model.
+
+Before adopting a stable release containing [upstream #42627](https://github.com/microsoft/playwright/pull/42627),
+adapt the hub from `_enableRecorder` / `_disableRecorder` to
+`_startRecording({ language: 'javascript' }, sink)` / `_stopRecording()` and verify
+the per-client event contract against the installed runtime. Do not ship a
+prerelease bump or an untested method-name fallback. Migrating to the separate
+connections in [#42622](https://github.com/microsoft/playwright/pull/42622) is a
+separate ownership change requiring the same lifecycle checks.
+
+Install the pinned Chromium browser, then run the real recorder gate alongside
+its failure and concurrency tests:
+
+```bash
+npx playwright install chromium
+npx vitest run tests/recorder.integration.test.ts tests/context.test.ts tests/browserSessions.test.ts tests/browserContextFactory.test.ts tests/tools-recorder.test.ts tests/sessionLog.test.ts
+```
+
+The real-browser tests cover concurrent starts, duplicate-start rejection,
+shared CDP clients, sibling-action attribution, stop/disconnect/restart,
+`--save-session`, and recording across stateless explicit sessions. Existing unit
+tests also cover failed-start recovery and overlapping start/stop. The recorder
+must receive the final input event before stop; unbuffered input delivered after
+stop begins is excluded, while buffered clicks/navigation get a 500 ms drain.
+
+Also recheck the dependency fixes motivating the upgrade. On 1.63.0 Chromium,
+both full-page and oversized element screenshots changed `navigator.maxTouchPoints`
+from 1 to 0 and `(pointer: coarse)` from true to false; navigation restored the
+properties ([#42617](https://github.com/microsoft/playwright/pull/42617)).
+The fixed-header/smooth-scroll retry fixture clicked successfully but emitted 19
+scroll events rather than instant jumps ([#42626](https://github.com/microsoft/playwright/pull/42626)).
+A candidate upgrade must preserve touch properties after full-page and element
+screenshots and navigation, and complete retry scrolling without smooth animation.
+These are dependency limitations; the recorder gate alone does not verify them.
+
 ### MCP harnesses
 
 The npm wrappers build first, then the direct harness calls every exposed MCP

package/config.d.ts

@@ -25,7 +25,7 @@ export type ToolCapability =
   | 'files'
   | 'install'
   | 'testing'
-  | 'core-install'
+  | 'core-install' // Deprecated alias for 'install'; requires explicit opt-in.
   | 'core-tabs'
   | 'devtools'
   | 'vision'
@@ -57,6 +57,13 @@ export type Config = {
      */
     userDataDir?: string;
 
+    /**
+     * Chrome profile directory name used in extension mode (for example
+     * "Default" or "Profile 1"); defaults to the last-used profile that
+     * has the extension installed.
+     */
+    profileDirName?: string;
+
     /**
      * Launch options passed to
      * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
@@ -185,9 +192,11 @@ export type Config = {
   };
 
   /**
-   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   * Image response policy. Defaults to "allow"; "auto" is a legacy alias for "allow".
+   * "omit" excludes images. "only" omits text from successful responses containing images,
+   * but preserves errors, browser lifecycle notices, structured content and resource links. Responses without images keep text.
    */
-  imageResponses?: 'allow' | 'omit' | 'auto';
+  imageResponses?: 'allow' | 'omit' | 'auto' | 'only';
 
   snapshot?: {
     /**
@@ -215,5 +224,11 @@ export type Config = {
      * How long to wait after each action for triggered work to settle before responding. Defaults to 500ms.
      */
     settle?: number;
+
+    /**
+     * Release the default browser context after this many idle milliseconds. Zero (the default) disables it.
+     * Explicit browser sessions retain their separate idle TTL.
+     */
+    idle?: number;
   };
 };

package/lib/browserContextFactory.js

@@ -25,17 +25,7 @@ import { logUnhandledError, testDebug } from './utils/log.js';
 import { createGuid, createHash, createShortGuid } from './utils/guid.js';
 import { outputFile } from './config.js';
 import { ensureNetworkPolicyRoutes } from './networkPolicy.js';
-/**
- * Throws when a storage state is configured but `factory` will not apply it. A
- * factory that neither creates a fresh context with the state nor applies it to
- * the context it reuses would drop it without a word and audit the site as an
- * anonymous user, which looks exactly like a successful run. Every factory in
- * this file applies it one way or the other; the extension factory cannot — it
- * works through the user's own running browser, where clearing every origin's
- * cookies to install the recorded state is not an acceptable side effect.
- * Callers pass the remedy that fits the mode they selected — the factory that
- * creates the context is not always the one `contextFactory()` built.
- */
+/** Rejects factories that would silently ignore a configured storage state. */
 export function assertStorageStateSupported(config, factory, remedy) {
     if (config.browser.contextOptions?.storageState && !factory.appliesStorageState)
         throw new Error(`Storage state cannot be applied in this mode. ${remedy}`);
@@ -54,142 +44,10 @@ export function assertStorageStateDoesNotResetUserProfile(config, remedy) {
 }
 export function contextFactory(config) {
     const factory = createContextFactory(config);
-    // Every built-in factory now applies a storage state; the guard stays so a
-    // future factory that forgets to declare support rejects the option instead
-    // of silently dropping it.
+    // Factories must apply the state to a fresh context or reject unsafe reuse.
     assertStorageStateSupported(config, factory, 'Drop the storage state and sign in interactively before auditing.');
     return factory;
 }
-// The rules addCookies enforces client-side (verified against Playwright
-// 1.61.1: empty or missing domain/path without a url, a url combined with a
-// domain or a path, about:blank/data:/unparseable urls, an expires other
-// than -1 or a positive number up to Playwright's ceiling, and sameSite
-// outside Strict/Lax/None are all rejected there — non-http(s) url schemes
-// and malformed origin strings fail browser-side during the apply). Failing
-// them here keeps the failure ahead of the cache clear; anything these
-// checks miss still fails inside setStorageState.
-const cookieUrlProblem = (url) => {
-    if (typeof url !== 'string')
-        return 'is not a string';
-    if (url === 'about:blank')
-        return 'cannot be about:blank';
-    if (url.startsWith('data:'))
-        return 'cannot be a data: URL';
-    try {
-        const parsed = new URL(url);
-        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
-            return `must be an http(s) URL, not ${parsed.protocol}`;
-    }
-    catch {
-        return 'is not a valid absolute URL';
-    }
-    return null;
-};
-const isValidIndexedDBKey = (value) => typeof value === 'string'
-    || (typeof value === 'number' && Number.isFinite(value))
-    || (value instanceof Date && Number.isFinite(value.getTime()))
-    || value instanceof ArrayBuffer
-    || ArrayBuffer.isView(value)
-    || (Array.isArray(value) && value.every(isValidIndexedDBKey));
-const indexedDBIdentifier = /^[$_\p{ID_Start}][$\u200C\u200D\p{ID_Continue}]*$/u;
-const isValidIndexedDBKeyPath = (value) => typeof value === 'string' && (value === '' || value.split('.').every(part => indexedDBIdentifier.test(part)));
-const isValidIndexedDBKeyPathArray = (value) => Array.isArray(value) && !!value.length && value.every(isValidIndexedDBKeyPath);
-function assertValidStorageState(state) {
-    for (const value of state.cookies ?? []) {
-        const cookie = value;
-        const problem = !cookie || typeof cookie !== 'object'
-            ? 'a cookie entry is not an object'
-            : !cookie.url && (!cookie.domain || !cookie.path)
-                ? `cookie "${String(cookie.name ?? '')}" should have a url or a domain/path pair`
-                : cookie.url && cookie.domain
-                    ? `cookie "${String(cookie.name ?? '')}" should have either a url or a domain, not both`
-                    : cookie.url && cookie.path
-                        ? `cookie "${String(cookie.name ?? '')}" should have either a url or a path, not both`
-                        : cookie.url !== undefined && cookieUrlProblem(cookie.url)
-                            ? `cookie "${String(cookie.name ?? '')}" has a url that ${cookieUrlProblem(cookie.url)}`
-                            : cookie.expires !== undefined && (typeof cookie.expires !== 'number' || Number.isNaN(cookie.expires) || (cookie.expires !== -1 && (cookie.expires <= 0 || cookie.expires > 253402300799)))
-                                ? `cookie "${String(cookie.name ?? '')}" should have a valid expires — only -1 or a positive unix timestamp in seconds up to 253402300799 (9999-12-31T23:59:59Z, Playwright's own ceiling) is allowed`
-                                : cookie.sameSite !== undefined && !['Strict', 'Lax', 'None'].includes(cookie.sameSite)
-                                    ? `cookie "${String(cookie.name ?? '')}" has sameSite "${String(cookie.sameSite)}", expected one of Strict|Lax|None`
-                                    : null;
-        if (problem)
-            throw new Error(`Invalid storage state: ${problem}. Nothing was changed — the state is validated before the apply, because setStorageState() clears the attached context's HTTP cache and cookie jar before it validates, and the cache cannot be restored.`);
-    }
-    for (const value of state.origins ?? []) {
-        const entry = value;
-        // Restoring an origin's storage navigates Playwright's temporary page to
-        // it — a malformed or non-http(s) origin fails that navigation after the
-        // clear.
-        const problem = !entry || typeof entry !== 'object'
-            ? 'an origins entry is not an object'
-            : typeof entry.origin !== 'string' || cookieUrlProblem(entry.origin)
-                ? `origins entry "${String(entry?.origin ?? '')}" is not an absolute http(s) URL`
-                : null;
-        if (problem)
-            throw new Error(`Invalid storage state: ${problem}. Nothing was changed — the state is validated before the apply, because setStorageState() clears the attached context's HTTP cache and cookie jar before it validates, and the cache cannot be restored.`);
-        const databaseNames = new Set();
-        for (const value of Array.isArray(entry?.indexedDB) ? entry.indexedDB : []) {
-            const database = value;
-            const stores = Array.isArray(database.stores) ? database.stores : [];
-            let indexedDBProblem = !Number.isSafeInteger(database.version) || database.version <= 0
-                ? `IndexedDB database "${String(database.name ?? '')}" should have a positive integer version`
-                : databaseNames.has(String(database.name))
-                    ? `IndexedDB database name "${String(database.name)}" is duplicated`
-                    : null;
-            databaseNames.add(String(database.name));
-            const storeNames = new Set();
-            for (const store of stores) {
-                const storeName = String(store.name);
-                indexedDBProblem ??= storeNames.has(storeName)
-                    ? `IndexedDB object store name "${storeName}" is duplicated in database "${String(database.name)}"`
-                    : store.keyPath !== undefined && !isValidIndexedDBKeyPath(store.keyPath)
-                        ? `IndexedDB object store "${storeName}" has an invalid key path`
-                        : store.keyPathArray !== undefined && !isValidIndexedDBKeyPathArray(store.keyPathArray)
-                            ? `IndexedDB object store "${storeName}" has an invalid array key path`
-                            : store.autoIncrement && (store.keyPath === '' || Array.isArray(store.keyPathArray))
-                                ? `IndexedDB object store "${storeName}" cannot combine autoIncrement with an empty or array key path`
-                                : null;
-                storeNames.add(storeName);
-                const recordKeys = new Set();
-                const hasInlineKey = store.keyPath !== undefined || store.keyPathArray !== undefined;
-                for (const value of Array.isArray(store.records) ? store.records : []) {
-                    const record = value;
-                    const hasExternalKey = (record.key !== undefined && record.key !== null)
-                        || (record.keyEncoded !== undefined && record.keyEncoded !== null);
-                    const key = record.key ?? record.keyEncoded;
-                    const serializedKey = hasExternalKey ? JSON.stringify(key) ?? String(key) : '';
-                    indexedDBProblem ??= record.key !== undefined && record.key !== null && !isValidIndexedDBKey(record.key)
-                        ? `IndexedDB object store "${storeName}" has an invalid external record key`
-                        : hasInlineKey && hasExternalKey
-                            ? `IndexedDB object store "${storeName}" has an inline key path but record also supplies an external key`
-                            : !hasInlineKey && !store.autoIncrement && !hasExternalKey
-                                ? `IndexedDB object store "${storeName}" requires an external key for every record`
-                                : hasExternalKey && recordKeys.has(serializedKey)
-                                    ? `IndexedDB object store "${storeName}" has duplicate record key ${serializedKey}`
-                                    : null;
-                    if (hasExternalKey)
-                        recordKeys.add(serializedKey);
-                }
-                const indexNames = new Set();
-                for (const index of Array.isArray(store.indexes) ? store.indexes : []) {
-                    const indexName = String(index.name);
-                    indexedDBProblem ??= indexNames.has(indexName)
-                        ? `IndexedDB index name "${indexName}" is duplicated in object store "${storeName}"`
-                        : index.keyPath !== undefined && !isValidIndexedDBKeyPath(index.keyPath)
-                            ? `IndexedDB index "${indexName}" has an invalid key path`
-                            : index.keyPathArray !== undefined && !isValidIndexedDBKeyPathArray(index.keyPathArray)
-                                ? `IndexedDB index "${indexName}" has an invalid array key path`
-                                : index.multiEntry && Array.isArray(index.keyPathArray)
-                                    ? `IndexedDB index "${indexName}" cannot combine multiEntry with an array key path`
-                                    : null;
-                    indexNames.add(indexName);
-                }
-            }
-            if (indexedDBProblem)
-                throw new Error(`Invalid storage state: ${indexedDBProblem}. Nothing was changed — the state is validated before the apply, because setStorageState() clears the attached context's HTTP cache and cookie jar before it validates, and the cache cannot be restored.`);
-        }
-    }
-}
 /**
  * Replaces every open page of `browserContext` with a blank fresh tab and
  * returns the fresh tabs paired with the URL each replaced page showed.
@@ -283,150 +141,10 @@ async function navigateReplacementPages(replaced) {
         }
     }));
 }
-/**
- * Lands the configured storage state in a context the browser already had.
- * `setStorageState()` clears the context's cookies, local storage and IndexedDB
- * and installs the recorded state — the documented semantics of the option the
- * caller asked for, applied to a context `newContext()` never sees: the CDP
- * modes without --isolated reuse the browser's existing context, and
- * launchPersistentContext() silently ignores a storageState option (verified
- * against Playwright 1.61.1).
- */
-export async function applyStorageStateToReusedContext(config, browserContext) {
-    const storageState = config.browser.contextOptions?.storageState;
-    if (!storageState)
-        return;
-    const parsedState = await (async () => {
-        try {
-            return typeof storageState === 'string'
-                ? JSON.parse(await fs.promises.readFile(storageState, 'utf-8'))
-                : storageState;
-        }
-        catch (error) {
-            // Letting setStorageState() discover the bad file would fail inside
-            // the apply block, whose catch answers every failure with a rollback —
-            // and the rollback's own setStorageState() clears the attached
-            // context's HTTP cache. A config error that changed nothing must not
-            // cost the running application its cache.
-            throw new Error(`The storage state file could not be read or parsed: ${error instanceof Error ? error.message : String(error)}. Nothing was changed.`);
-        }
-    })();
-    // Playwright validates cookies only while installing them — after the
-    // attached context's HTTP cache and cookie jar are already cleared — so a
-    // semantically invalid cookie (bad expires, missing domain/path) would
-    // fail the apply with the cache unrestorably gone. Checked up front, with
-    // the same rules addCookies enforces (verified against 1.61.1).
-    assertValidStorageState(parsedState);
-    // setStorageState needs a temporary page whenever the state carries origins
-    // or the context has visited any — and by the time that page creation fails
-    // on a target without Target.createTarget, the HTTP cache is already cleared
-    // and cannot be put back. Probe the page creation first, so such targets are
-    // rejected before anything is mutated. When neither signal indicates a page
-    // will be needed (cookie-only state, no pages open), the probe is skipped so
-    // that case keeps working on those targets.
-    const stateHasOrigins = (parsedState.origins?.length ?? 0) > 0;
-    const hasLoadedPages = browserContext.pages().some(page => page.url() && page.url() !== 'about:blank');
-    if (stateHasOrigins || hasLoadedPages) {
-        try {
-            const probe = await browserContext.newPage();
-            await probe.close();
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (message.includes('Target.createTarget'))
-                throw new Error(`The attached browser cannot open the temporary page Playwright needs to apply the storage state's origin data (Electron targets do not support Target.createTarget). Nothing was changed. Drop the storage state and sign in inside the app instead. Original error: ${message}`);
-            throw error;
-        }
-    }
-    // setStorageState replaces the cookie jar and then rewrites origin storage
-    // one origin at a time, so a failure partway would otherwise leave the
-    // attached browser holding a mixture of old and recorded state while the
-    // operation reports failure. Both layers are snapshotted first: the cookie
-    // jar through pure protocol calls that work everywhere (kept as the
-    // fallback for a restore whose own origin phase fails), and origin storage
-    // through storageState() below.
-    const originalCookies = await browserContext.cookies();
-    // The snapshot doubles as a probe for origins this connection has already
-    // visited while its pages have since closed or gone blank: for those,
-    // storageState() opens the same temporary page the forward apply will need
-    // — the newPage probe above cannot see them — but unlike setStorageState()
-    // it mutates nothing, so a target that cannot create pages (Electron) is
-    // rejected here with everything intact, not after the forward apply has
-    // cleared the HTTP cache. Any other snapshot failure also aborts: without
-    // the full snapshot, a partial forward apply could only be rolled back to
-    // cookies, leaving the attached browser's origin storage part old, part
-    // recorded.
-    const originalState = await browserContext.storageState({ indexedDB: true }).catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes('Target.createTarget'))
-            throw new Error(`The attached browser cannot open the temporary page Playwright needs to reset origin storage for origins this connection has already visited (Electron targets do not support Target.createTarget). Nothing was changed. Drop the storage state and sign in inside the app instead. Original error: ${message}`);
-        throw new Error(`Snapshotting the context's current storage for rollback failed, so the storage state was not applied — a partial apply could not have been undone. Nothing was changed. Retry, or use --isolated for a fresh context. Original error: ${message}`);
-    });
-    // Pages that were already open still render the previous identity — and
-    // their scripts keep running: a page that periodically persists
-    // authentication into cookies or localStorage would overwrite the state
-    // being installed if it were still alive during setStorageState(), and
-    // replacing its tab afterwards cannot undo writes already made into
-    // context-wide storage. Every open page is therefore replaced with a blank
-    // fresh tab FIRST — the old document closes before the state lands, and
-    // only blank replacements (which run no scripts) survive the apply — and
-    // the replacements are navigated to the pages they replaced only once the
-    // recorded state is in place.
-    const replaced = await replaceOpenPagesWithBlankTabs(browserContext);
-    const policyRequired = !!(config.network?.allowedOrigins?.length || config.network?.blockedOrigins?.length);
-    let replacementNavigationSafe = !policyRequired;
-    try {
-        // The state validated above is the state applied: handing the path back
-        // to Playwright would re-read the file here, and a file replaced since
-        // that read would skip the cookie/origin validation and the page-creation
-        // probe only to fail after the cache clear those exist to prevent.
-        await browserContext.setStorageState(parsedState);
-        // The replacement navigations run inside the factory, before Context
-        // ensures the configured origin allowlist/blocklist — and the recorded
-        // credentials are already in place by now. The policy is installed here
-        // (permanently — page scripts can queue requests that fire after the
-        // navigation settles, so removing the handlers before Context re-ensures
-        // the same policy would open a window to a blocked origin;
-        // ensureNetworkPolicyRoutes installs once per context, so Context's later
-        // call is a no-op). Installed after setStorageState() so an abort-all
-        // route cannot interfere with the temporary page Playwright drives to
-        // restore origin storage.
-        await ensureNetworkPolicyRoutes(config, browserContext);
-        replacementNavigationSafe = true;
-        await navigateReplacementPages(replaced);
-    }
-    catch (error) {
-        // Prefer the full-state rollback; fall back to cookies-only when its
-        // reapplication is itself impossible on this target.
-        const restoredFully = await browserContext.setStorageState(originalState).then(() => true, () => false);
-        const restoredCookies = restoredFully || await browserContext.clearCookies()
-            .then(() => originalCookies.length ? browserContext.addCookies(originalCookies) : undefined)
-            .then(() => true, () => false);
-        // The old pages were closed before the apply and cannot be handed back.
-        // Navigate their replacements only when no policy was required or its
-        // installation succeeded; otherwise restored credentials stay offline.
-        if (replacementNavigationSafe)
-            await navigateReplacementPages(replaced);
-        else
-            await Promise.all(replaced.map(({ page }) => page.close().catch(() => { })));
-        // Restoring origin storage (localStorage/IndexedDB) makes Playwright open a
-        // temporary page; a CDP target that cannot create one — Electron has no
-        // Target.createTarget — fails here. Cookie-only states need no page and
-        // still work on such targets, so name that remedy instead of surfacing the
-        // raw protocol error.
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes('Target.createTarget')) {
-            const rollbackNote = restoredFully
-                ? 'The context\'s original storage state was restored.'
-                : restoredCookies
-                    ? 'The context\'s original cookies were restored.'
-                    : 'Restoring the context\'s original cookies also failed; its cookie jar may now hold the recorded state.';
-            throw new Error(`The attached browser cannot open the temporary page Playwright needs to reset origin storage (Electron targets do not support Target.createTarget). Drop the storage state and sign in inside the app instead — a cookies-only state helps only while the attached target has no pages open and the connection has visited no origin, because clearing storage for an already-visited origin needs the same temporary page. ${rollbackNote} Original error: ${message}`);
-        }
-        if (!restoredFully && restoredCookies)
-            throw new Error(`${message} The context's original cookies were restored, but origin storage may retain partially applied state.`);
-        throw error;
-    }
+/** Existing contexts can contain service workers and storage we cannot safely snapshot. */
+export function assertReusedContextStorageStateSupported(config) {
+    if (config.browser.contextOptions?.storageState)
+        throw new Error('Cannot apply --storage-state to an existing browser context on Playwright 1.63.0: its rollback snapshot can run service-worker-served scripts and alter storage. Use a fresh context (for CDP, add --isolated), or omit --storage-state and sign in interactively. No storage snapshot or reset was attempted.');
 }
 function createContextFactory(config) {
     if (config.browser.remoteEndpoint)
@@ -615,17 +333,10 @@ class IsolatedContextFactory extends BaseContextFactory {
     }
 }
 class CdpContextFactory extends BaseContextFactory {
-    // The isolated path creates a fresh context with the state; the attach path
-    // applies it to the browser's existing context via setStorageState().
+    // Fresh contexts accept storage state; existing external contexts reject it.
     appliesStorageState = true;
-    // One attached browser — and its default context — serves every session
-    // this factory creates. Re-running the global setStorageState() for a
-    // second session would wipe the first session's live cookies and origin
-    // storage mid-audit and reload its pages, so the state is applied once per
-    // context object: later sessions join the live shared state. Keyed weakly —
-    // a reconnect yields a fresh context object, so the slate resets with the
-    // connection — and a failed apply is forgotten so the next session retries.
-    _storageStateApplied = new WeakMap();
+    // Contexts created by this factory already received the configured state.
+    _createdContexts = new WeakSet();
     // Serializes the no-context fallback the same way: two sessions arriving at
     // a contextless target must share one created context, not race two.
     _fallbackContext = new WeakMap();
@@ -725,15 +436,13 @@ class CdpContextFactory extends BaseContextFactory {
         const existing = browser.contexts()[0];
         // An attached browser can expose no context at all; a fresh one created
         // with the configured options (storage state included) beats handing an
-        // undefined context to the caller. The created context immediately seeds
-        // the applied-state memo — a later session will find it as the browser's
-        // existing context, and must join it rather than reset it — and the
-        // creation itself is memoized so concurrent arrivals share one context.
+        // undefined context to the caller. Track ownership so later sessions may
+        // join that context; memoize creation so concurrent arrivals share it.
         if (!existing) {
             let creating = this._fallbackContext.get(browser);
             if (!creating) {
                 creating = browser.newContext(this.config.browser.contextOptions).then(created => {
-                    this._storageStateApplied.set(created, Promise.resolve());
+                    this._createdContexts.add(created);
                     // Evict on close, or a context closed externally (while the
                     // connection lives on) would keep being handed out of this memo to
                     // every later session — contexts() no longer lists it, so only the
@@ -746,15 +455,8 @@ class CdpContextFactory extends BaseContextFactory {
             }
             return await creating;
         }
-        // The shared promise also serializes two sessions arriving at once: both
-        // await the same application instead of racing two global resets.
-        let applied = this._storageStateApplied.get(existing);
-        if (!applied) {
-            applied = applyStorageStateToReusedContext(this.config, existing);
-            this._storageStateApplied.set(existing, applied);
-            applied.catch(() => this._storageStateApplied.delete(existing));
-        }
-        await applied;
+        if (!this._createdContexts.has(existing))
+            assertReusedContextStorageStateSupported(this.config);
         return existing;
     }
 }
@@ -877,7 +579,7 @@ class CdpLaunchContextFactory {
             else {
                 const existing = browser.contexts()[0];
                 if (existing) {
-                    await applyStorageStateToReusedContext(this.config, existing);
+                    assertReusedContextStorageStateSupported(this.config);
                     browserContext = existing;
                 }
                 else {