playwright-write-guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Venkata Sandeep Takasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,366 @@
-# Temporary Holding Version
+# playwright-write-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A read-only safety net for Playwright tests and AI browser agents. It blocks every request whose method is not GET, HEAD or OPTIONS (unless you allow-list it) at the network layer, refuses destructive clicks inside the page before the app sees them, and writes a JSON audit log of every write it blocked or observed. Use it with Playwright Test through one import, or with Playwright MCP and the Playwright CLI either through a one-line `initPage` config entry or through a launcher that owns the browser the agent attaches to. It has no runtime dependencies and no build step. It is a safety net, not a security boundary: a restricted test account is the boundary.
+
+## What it is and why
+
+Pointing an automated browser at a real app is risky when the run should only look. A test that clicks through a settings page, or an agent asked to "find out what this dashboard shows", can press Save, Delete or Send, or fire a POST, and change real data.
+
+This package puts a read-only guard in front of the browser:
+
+- **Requests.** Any request whose method is not GET, HEAD or OPTIONS is blocked, unless a signature in your `allow` list says it is really a read (a read-only GraphQL endpoint, for example). Requests that are really writes but look like reads can be named in `writes`.
+- **Clicks.** A click, form submit, or Enter or Space keypress on a control whose label is a destructive verb (Save, Delete, Publish, Send and so on) is stopped inside the page before the app's own handlers run. Native confirmation dialogs are declined.
+- **Log.** Every write it blocked, or only observed under the `observe` policy, is recorded as one JSON line.
+
+See it work end to end, with a local page and a local server, in the walkthrough at [demo/README.md](demo/README.md) (`node demo/run.mjs`).
+
+## Install
+
+```
+npm i -D playwright-write-guard
+npx playwright install chromium
+```
+
+It needs Node 20 or newer and Playwright 1.59 or newer: `@playwright/test` for the fixture, and `playwright-core` for the launcher and its command. Using the `initPage` entry with an agent needs a Node that can `require` an ES module (see below).
+
+## Use with Playwright Test
+
+Swap one import. Everything else in your tests stays the same:
+
+```js
+// before
+// import { test, expect } from '@playwright/test';
+import { test, expect } from 'playwright-write-guard/test';
+
+test('lists items without changing them', async ({ page }) => {
+  await page.goto('https://app.example.test/items');
+  await expect(page.getByRole('list')).toBeVisible();
+});
+```
+
+The fixture guards each test's context, created with `serviceWorkers: 'block'`. By default it reads `write-guard.config.json` from the directory you run Playwright in. Every key is optional; a small example that lets a read-only GraphQL endpoint through and blocks everything else:
+
+```json
+{
+  "policy": "read-only",
+  "allow": [
+    { "method": "POST", "url": "^https://app[.]example[.]test/graphql$" }
+  ],
+  "controls": { "icons": ["icon-trash"] }
+}
+```
+
+To set the config in the test file instead, use `test.use`:
+
+```js
+test.use({ writeGuardConfig: { policy: 'read-only', allow: [] } });
+```
+
+Each test attaches what the guard saw as `write-guard.json` (open it from the HTML report or the test's attachments). The fixture never writes a JSONL log file; use that attachment instead.
+
+If you run Playwright with `-c` from another directory, the fixture will not find `write-guard.config.json` and silently falls back to the defaults. Set `WRITE_GUARD_CONFIG` to the config file's path:
+
+```
+WRITE_GUARD_CONFIG=/path/to/write-guard.config.json npx playwright test -c config/playwright.config.mjs
+```
+
+## Use with AI agents
+
+Pick one mode for a given browser. Using both at once is refused: the second guard throws `write-guard: this context is already guarded by another process; use one mode, not both`.
+
+### Config mode: the `initPage` entry
+
+Playwright MCP and the Playwright CLI can run a script on every new tab before any tool acts. Point them at this package's entry. For Playwright MCP, put this in a file and pass it with `--config`; for the Playwright CLI, put it in `.playwright/cli.config.json`:
+
+```json
+{
+  "browser": {
+    "initPage": ["/absolute/path/to/node_modules/playwright-write-guard/src/init-page.mjs"],
+    "contextOptions": { "serviceWorkers": "block" }
+  }
+}
+```
+
+The entry is loaded with `require`, so the agent server's Node must be able to `require` an ES module: Node 20.19 or newer, or 22.12 or newer. The guard reads its config with `loadConfig()` from the agent server's working directory; set `WRITE_GUARD_CONFIG` to an absolute path when in doubt. The audit log is written there too.
+
+In this mode the guard lives in the same process as the agent's tools, so the agent can remove it with its own code-running and routing tools. Deny those tools. In Claude Code, add these to `permissions.deny`:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "mcp__playwright__browser_run_code_unsafe",
+      "mcp__playwright__browser_route",
+      "mcp__playwright__browser_unroute",
+      "Bash(playwright-cli run-code:*)",
+      "Bash(playwright-cli route:*)",
+      "Bash(playwright-cli unroute:*)"
+    ]
+  }
+}
+```
+
+Without those entries the agent can remove the guard.
+
+### Launcher mode: a guarded browser the agent attaches to
+
+The launcher starts Chromium, guards its one context, and prints a WebSocket endpoint:
+
+```
+npx playwright-write-guard-browser [--config <path>] [--headed] [--host <h>] [--port <n>]
+```
+
+It prints `endpoint: <ws endpoint>`. Attach the agent to it:
+
+- Playwright MCP: start it with `--endpoint <ws endpoint>` and without `--isolated`. `--isolated` makes a new, unguarded context.
+- Playwright CLI: `playwright-cli attach --endpoint=<ws endpoint>`.
+
+The guard runs in the launcher's process, not the agent's. The agent's own `unroute` and `unrouteAll` cannot remove it, and a `page.route` handler that calls `continue()` without overrides is still judged, because page handlers run before the owner's context route. Playwright MCP's own route tool only sets the headers and status of mocked responses, so this mode survives the MCP route tools the config mode has to deny. It does not survive arbitrary client code: see "What it cannot see" below. Tabs the agent opens in that context are guarded too. Stop it with Ctrl+C.
+
+## The audit log
+
+When `log` is a path (default `write-guard.jsonl`, relative to the process's working directory), each blocked or observed write is appended as one JSON object per line, as it happens. The file is created when missing and never truncated. Allowed requests and controls are not logged. Set `"log": null` to turn it off.
+
+A blocked request and a refused control look like this (one line each in the file):
+
+```json
+{"kind":"request","action":"block","reason":"POST is not a read method; policy read-only","method":"POST","url":"https://app.example.test/items","at":"2026-01-15T09:30:00.000Z"}
+{"kind":"control","action":"block","reason":"\"Delete item\" matches a destructive label; policy read-only","label":"Delete item","at":"2026-01-15T09:30:02.000Z"}
+```
+
+A request event carries `method` and `url`; a control event carries `label` and neither. `reason` is a human-readable note whose wording may change. Under the `observe` policy the same events are recorded with `"action":"observe"` and the write goes through, which is a way to find out what a run would have blocked. The full event shape is in the API below.
+
+## What it cannot see
+
+The guard judges requests the browser sends through its context and clicks the page makes. These are outside it:
+
+- Request clients it does not own: an attached client's own `page.request` and `context.request` in launcher mode, and `playwright.request.newContext()` called from an agent's run-code tool.
+- An agent's run-code tool, and any browser the agent launches itself. In config mode, deny those tools as shown above.
+- A Playwright Test run with `-c` from another directory without `WRITE_GUARD_CONFIG`, which falls back to the defaults.
+- WebSockets, unless `websockets` is `"block"`. A caller's own `routeWebSocket` registered after the guard can take precedence over `websockets: "block"`.
+- WebRTC and WebTransport.
+- Redirects after the first URL: only the request the page made is judged, not where the server redirects it.
+- Drag-and-drop, and pointer or mouse handlers that act before `click`.
+- Client-side-only destructive actions that no click or submit reaches.
+- Mistakes in the config: requests are classified only as well as the config, so a write sent as GET, or a read sent as POST, needs a `writes` or `allow` signature.
+- In launcher mode, any context other than `contexts()[0]`: `--isolated`, or `browser.newContext()` from an agent's run-code tool, makes a new, unguarded context.
+- In launcher mode, a client's `context.route` overrides are not judged again: that handler runs after the guard, in the client's process, so a `continue()` or `fallback()` that rewrites the method, URL or body (a GET rewritten to DELETE) reaches the server.
+- In launcher mode, a client's `route.fetch()` from any route handler (`page.route` or `context.route`) is not seen: it is sent through the client's own `APIRequestContext`, which the guard cannot reach.
+- Code in the same process that calls Playwright's prototype methods directly (for example `Object.getPrototypeOf(context).route` or `.unrouteAll`, `Object.getPrototypeOf(route).continue`, or `Object.getPrototypeOf(context.request).fetch`, which goes around the read-only lock on `APIRequestContext`) or removes the guard's own `page` or `dialog` listeners (`context.removeAllListeners('page')` leaves new pages' routes unwrapped; `context.removeAllListeners('dialog')` lets a caller accept a dialog) goes around the guard's wrappers: the route it registers is not wrapped (its `continue()` can send a POST), `unrouteAll` removes the guard, and a `continue` with overrides skips the override judging.
+- Routes and dialog listeners registered before `install`: a `page.route` whose `continue()` sends a write, a `context.route` whose overrides are not judged, and a page `dialog` listener that accepts all run outside the guard's wrappers.
+- Under `observe`, sends through `context.request`, `page.request` and the `request` fixture are neither blocked nor recorded (only read-only locks them), so an observe run does not list them.
+- Controls whose label is rendered inside a shadow root: the page sees the shadow host, whose text does not include the shadow content, so the click is not refused in the page. The network layer still judges any request it sends.
+- A document loaded with `page.setContent()`: the guard's in-page listeners do not carry over into it, so a destructive click there is not refused in the page. The network layer still judges any request it sends.
+- Node's own `http`, `https` and `net` modules in the test process.
+
+It also refuses too much in two places, which is the safe direction. Under read-only, pressing Enter or Space in a text field whose value contains a built-in verb is refused (the label rule uses the focused element's value), and a click on plain text containing a verb, outside any control, can be refused.
+
+It is a safety net, not a security boundary. A restricted test account is the boundary: give the run credentials that cannot write, and use the guard to catch the mistakes that slip past.
+
+## API
+
+The package has five entry points, each with its own type declarations:
+
+| Import | Exports |
+|---|---|
+| `playwright-write-guard` | `compileConfig`, `decideRequest`, `decideControl` |
+| `playwright-write-guard/install` | `install`, `loadConfig` |
+| `playwright-write-guard/test` | `test`, `expect` |
+| `playwright-write-guard/init-page` | the default export, an `initPage` function |
+| `playwright-write-guard/browser` | `startGuardedBrowser` |
+
+It also installs one command, `playwright-write-guard-browser`. It needs Node 20 or newer and Playwright 1.59 or newer (`@playwright/test` for the fixture; `playwright-core` is needed at runtime only by `playwright-write-guard/browser` and the command, and the other entry points use the context Playwright gives them).
+
+### Config
+
+Every key is optional, and unknown keys are ignored:
+
+```json
+{
+  "policy": "read-only",
+  "allow": [],
+  "writes": [],
+  "controls": { "text": [], "icons": [] },
+  "defaultControls": true,
+  "websockets": "allow",
+  "log": "write-guard.jsonl"
+}
+```
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `policy` | `"read-only"` or `"observe"` | `"read-only"` | `read-only` blocks writes and destructive controls; `observe` records them and lets them through |
+| `allow` | list of Sig | `[]` | requests that are never writes |
+| `writes` | list of Sig | `[]` | requests that are writes even when their method is GET, HEAD or OPTIONS |
+| `controls.text` | list of regex sources | `[]` | extra label patterns that make a control destructive |
+| `controls.icons` | list of class name prefixes | `[]` | a control with a class starting with one of these is destructive |
+| `defaultControls` | boolean | `true` | include the built-in verbs in the label pattern |
+| `websockets` | `"allow"` or `"block"` | `"allow"` | `block` refuses every WebSocket |
+| `log` | path or `null` | `"write-guard.jsonl"` | the JSONL audit log, relative to the process's working directory; `null` turns it off |
+
+A **Sig** (request signature) is `{ "method": M, "url": U, "body": B }`:
+
+- `method` is one of `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS` or `*`. `*` matches any method; any other value matches that method exactly, compared with the request's method in upper case.
+- `url` is a regex source, compiled with no flags (case-sensitive) and tested, unanchored, against the full request URL. Use `^` and `$` to anchor it, and escape dots: `"^https://api[.]example[.]com/graphql$"`.
+- `body` is optional (absent or `null` means the Sig names no body): a regex source, compiled the same way and tested against the request body. A signature with a `body` never matches a request that has no body (a body that is `null` or absent).
+- A request matches a Sig when its method, its URL and (when the Sig has one) its body all match.
+
+### Writes and controls
+
+**A request is a write** when its method, upper-cased, is not GET, HEAD or OPTIONS, or it matches a `writes` signature, **and** it matches no `allow` signature. The method is upper-cased before the GET, HEAD or OPTIONS check. `allow` always wins: `{ "method": "POST", "url": "^https://app[.]example[.]com/graphql" }` in `allow` lets a read-only GraphQL endpoint through.
+
+**A control is destructive** when its label matches the label pattern, or it has a class starting with one of the `controls.icons` prefixes. The label pattern is the built-in verbs (unless `defaultControls` is `false`) plus every `controls.text` source, joined into one case-insensitive regex. The built-in verbs match as whole words, case-insensitive (`Save` and `Delete item` match, `Saved` does not):
+
+`save`, `delete`, `remove`, `publish`, `share`, `submit`, `send`, `archive`, `upload`, `import`, `rename`, `duplicate`, `update`, `confirm`, `pay`, `purchase`, `invite`, `reset`, `restore`, `approve`, `reject`, `log out`, `sign out`
+
+There are no built-in icons: icon libraries differ per app, so name yours in `controls.icons` (for example `"icon-trash"`). An empty label never matches the label pattern; with `defaultControls: false` and no `controls.text`, only icons can make a control destructive.
+
+In the page, the **control** for a click is the nearest ancestor of the click target (or the target itself) matching `button, a, [role=button], [role=menuitem], [role=link], [role=tab], input[type=submit], input[type=button], input[type=image], summary, [onclick], [tabindex]`, or the target when none does. For a form submit it is the submitter, or the form when there is none; for an Enter or Space keydown it is the focused element. Its **label** is the first non-empty, trimmed value of its `aria-label` attribute, its `innerText`, its `title` attribute and its `value`. Its **icons** are every class name on the control and on each of its descendants.
+
+### The decision core: `playwright-write-guard`
+
+```js
+import { compileConfig, decideRequest, decideControl } from 'playwright-write-guard';
+
+const config = compileConfig({ allow: [{ method: 'POST', url: '^https://app[.]example[.]com/graphql' }] });
+decideRequest({ method: 'POST', url: 'https://app.example.com/items', body: '{}' }, config);
+// { action: 'block', reason: '...' }
+decideControl({ label: 'Delete item', icons: [] }, config);
+// { action: 'block', reason: '...' }
+```
+
+- `compileConfig(raw)` validates a raw config (`null` and `undefined` mean `{}`), applies every default and compiles every pattern. On anything malformed it throws an `Error` whose message is `write-guard: <path>: <message>`, where `<path>` names the offending key the way the config spells it (`policy`, `allow[0].method`, `controls.text[2]`), or `config` for the whole value. Malformed means: a config that is not an object; a `policy`, `websockets` or Sig `method` outside its allowed values; `allow`, `writes`, `controls.text` or `controls.icons` that is not a list; a Sig that is not an object; a `url`, a `body` other than `null`, or a `controls.text` entry that is not a non-empty string or does not compile; a `controls.icons` entry that is not a non-empty string; `controls` that is not an object; `defaultControls` that is not a boolean; `log` that is neither a non-empty string nor `null`. The result is `{ policy, allow, writes, text, icons, websockets, log }`: `allow` and `writes` hold `{ method, url: RegExp, body: RegExp | null }`, `text` is the label pattern (`null` when there is none), and `icons` is `controls.icons`.
+- `decideRequest({ method, url, body }, compiled)` returns `{ action, reason }`. For a write, `action` is `"block"` under `read-only` and `"observe"` under `observe`; for anything else it is `"allow"`.
+- `decideControl({ label, icons }, compiled)` returns `{ action, reason }`. For a destructive control, `action` is `"block"` under `read-only` and `"observe"` under `observe`; for anything else it is `"allow"`.
+- `reason` is a short human-readable explanation; its wording is not part of the API.
+
+These three functions reference nothing outside their own arguments, because the installer injects their source text into every page.
+
+### The installer: `playwright-write-guard/install`
+
+`install(context, config?)` guards one Playwright `BrowserContext` and returns `Promise<GuardHandle>`. It compiles `config` (default `{}`) with `compileConfig`, so a malformed config throws before anything is installed. A second call on the same context returns the first call's handle and ignores its own `config`. It:
+
+1. Registers one catch-all `context.route` before anything else, and judges each request exactly once with `decideRequest`, however many route handlers see it. An allowed or observed request falls back to the next handler and then to the network.
+2. Wraps `context.route` and the `route` of every page in the context, present and future, so the guard judges each request before any handler registered later, and a later handler that calls `continue()` cannot let a blocked request past. The wrapped `unroute` and `unrouteAll` remove only the caller's own handlers, never the guard's. The route a later handler receives also judges its overrides again: its `continue(options)`, `fallback(options)` and `fetch(options)` are judged as the request they would make when `options` changes the method, URL or body (calls with no options, or headers only, are not judged again, because the original was already judged). Under read-only, a write override makes `continue` and `fallback` abort the request with `'blockedbyclient'` (not the 403 page, even for a document) and makes `fetch` reject with `write-guard: route.fetch of <METHOD> <URL> is refused under read-only`. Under observe the override proceeds. Either way it is recorded once as a `request` event with the effective method and URL, and not counted in `routed_requests`. This applies in the fixture, the `initPage` entry and a direct `install`; in launcher mode it covers only the launcher's own process (see below).
+3. On `block`: a request whose resource type is `document` is fulfilled with status 403, content type `text/html; charset=utf-8`, and a short HTML page reading `write-guard blocked <METHOD> <URL>` (HTML-escaped), so a blocked navigation shows why instead of a browser error page; any other request is aborted with `'blockedbyclient'`, which the page sees as a network error.
+4. Under `websockets: "block"`, refuses every WebSocket under either policy with `context.routeWebSocket`: the socket is closed without connecting to the server and recorded as a `request` event with `action: "block"` and the socket's `url` (no `method`). It is not counted in `routed_requests`.
+5. Adds an init script that runs before any page script, with capture-phase `click`, `submit` and `keydown` (Enter or Space) listeners on `window` that judge the control with `decideControl`. Under `read-only` a destructive control's event is stopped (`preventDefault` and `stopImmediatePropagation`), so the app never sees it; under `observe` it goes through. Either way the page reports the event through the binding `__writeGuardReport`, which the script captures before any page script can replace it.
+6. Under `read-only`, dismisses every dialog (`alert`, `confirm`, `prompt`, `beforeunload`) on every page, so a native confirmation before a delete is declined.
+7. Under `read-only`, replaces `context.request` and the `request` of every page, present and future, with a proxy whose send methods (`fetch`, `get`, `post`, `put`, `patch`, `delete`, `head`) throw `write-guard: <method> through APIRequestContext is refused under read-only` (for example `write-guard: post through APIRequestContext is refused under read-only`). The other properties stay readable. This lock exists only in the process that called `install`.
+
+If the binding `__writeGuardReport` is already registered on the context, another process guards it (as when an agent attached to the launcher also loads the `initPage` entry), and `install` throws `write-guard: this context is already guarded by another process; use one mode, not both`. That check happens before anything is installed, so a refused `install` leaves nothing behind.
+
+`install` cannot change how the context was created: create it with `serviceWorkers: 'block'`, or a service worker can send requests the guard never sees. The fixture, the launcher and the `initPage` config below all do.
+
+**Events.** Every blocked or observed write is one event:
+
+```ts
+{ kind: 'request' | 'control', action: 'block' | 'observe', reason: string,
+  method?: string, url?: string, label?: string, at: string }
+```
+
+A request event carries `method` and `url`; a control event carries `label` (trimmed, at most 120 characters) and neither `method` nor `url`. `at` is an ISO 8601 timestamp. Allowed requests and controls produce no event.
+
+**The handle.**
+
+- `record()` returns `{ installed: true, policy, routed_requests, blocked, observed, events }`: `routed_requests` counts the requests the guard judged, each once; `blocked` and `observed` count request and control events alike.
+- `close()` resolves after the last pending log append and returns the final `record()`. The guard stays active until the context closes.
+
+**The audit log.** When `config.log` is a path, each event is appended to that file as one JSON line, as it happens. The path is relative to the process's working directory; the file is created when missing and never truncated.
+
+**`loadConfig(path?)`** returns a raw config to pass to `install`. It reads, synchronously with `fs.readFileSync`, the first of: `path`; else the file named by the environment variable `WRITE_GUARD_CONFIG`; else `write-guard.config.json` when that file exists; else it uses `{}`. Relative paths resolve against the process's working directory. A file named by `path` or `WRITE_GUARD_CONFIG` must exist, or `loadConfig` throws. When the environment variable `WRITE_GUARD_POLICY` is set to a non-empty value, it overrides `policy`. The result is validated with `compileConfig`, so a file that does not parse as JSON, an invalid config or an invalid `WRITE_GUARD_POLICY` throws. A file that cannot be read throws `write-guard: <file>: cannot be read: <system message>`, and a file that does not parse throws `write-guard: <file>: is not valid JSON: <parser message>`, where `<file>` is the path as resolved. Every entry point below that defaults to `loadConfig()` therefore honours `WRITE_GUARD_CONFIG` and `WRITE_GUARD_POLICY`; a config you pass explicitly to `install`, `test.use` or `startGuardedBrowser` is used as given.
+
+### The Playwright Test fixture: `playwright-write-guard/test`
+
+```js
+import { test, expect } from 'playwright-write-guard/test';
+
+test.use({ writeGuardConfig: { policy: 'read-only', allow: [] } });
+
+test('lists items without changing them', async ({ page }) => {
+  await page.goto('https://app.example.com/items');
+  await expect(page.getByRole('list')).toBeVisible();
+});
+```
+
+- `test` and `expect` are Playwright Test's, extended with one option fixture, `writeGuardConfig`, settable with `test.use`. It defaults to `loadConfig()`, which resolves relative to the working directory: running Playwright with `-c` from another directory needs `WRITE_GUARD_CONFIG` to find the config.
+- The `context` fixture is created with `serviceWorkers: 'block'` and guarded with `install`, with `log` forced to `null` (the fixture never writes a log file). Under `read-only` that also locks `context.request` and `page.request`. A test whose effective `serviceWorkers` option is not `'block'` fails at fixture setup with an error starting `write-guard: serviceWorkers is`, because a service worker could send requests the guard never sees.
+- The `request` fixture throws `write-guard: the request fixture is refused under read-only` under `read-only`, and works under `observe`. A test that uses `request` under read-only therefore fails at fixture setup with that message.
+- Under both policies, while a guarded test or hook runs, these throw an error starting `write-guard:` because they would make a browser context, request context or connection the guard cannot see: `browser.newContext`, `browser.newPage`, `playwright.request.newContext`, the global `fetch`, and the browser types' `launch`, `launchPersistentContext`, `launchServer`, `connect` and `connectOverCDP`. Playwright's own creation of the test's context is the one exception.
+- Each test attaches its guard's `record()` as `write-guard.json` (`application/json`).
+
+### The `initPage` entry: `playwright-write-guard/init-page`
+
+The default export is `async ({ page }) => install(page.context(), loadConfig())`, and is idempotent per context: every new tab calls it, and the context is guarded once. Playwright MCP and the Playwright CLI run each `browser.initPage` entry with `require(path).default({ page })` in their own process for every new tab, before any tool acts. Load it with this config (MCP's `--config` file, or the CLI's `.playwright/cli.config.json`):
+
+```json
+{
+  "browser": {
+    "initPage": ["/absolute/path/to/node_modules/playwright-write-guard/src/init-page.mjs"],
+    "contextOptions": { "serviceWorkers": "block" }
+  }
+}
+```
+
+Because it is loaded with `require`, nothing in its import graph uses top-level await, and Node must support `require` of ES modules: Node 20.19 or newer, or 22.12 or newer. `loadConfig()` resolves against the agent server's working directory, so set `WRITE_GUARD_CONFIG` to an absolute path when in doubt. The log, when on, is written there too.
+
+In this mode the guard lives in the same process as the agent's tools, so the agent can remove it. Deny the tools that can, for example in Claude Code's `permissions.deny`:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "mcp__playwright__browser_run_code_unsafe",
+      "mcp__playwright__browser_route",
+      "mcp__playwright__browser_unroute",
+      "Bash(playwright-cli run-code:*)",
+      "Bash(playwright-cli route:*)",
+      "Bash(playwright-cli unroute:*)"
+    ]
+  }
+}
+```
+
+Without those entries the agent can remove the guard.
+
+### The launcher: `playwright-write-guard/browser`
+
+`startGuardedBrowser({ config, headless = true, host = '127.0.0.1', port = 0, title = 'write-guard' })` returns `Promise<{ wsEndpoint, browser, context, guard, close() }>`. It launches Chromium with `playwright-core`, creates one context with `serviceWorkers: 'block'`, guards it with `install(context, config)` (`config` defaults to `loadConfig()`), and calls `browser.bind(title, { host, port })`; `wsEndpoint` is the `endpoint` that returns, `ws://<host>:<port>/<id>` (`port: 0` lets the OS pick a free port). `guard` is the install handle. `close()` waits for `guard.close()`, then closes the context and the browser.
+
+A client attaches with `chromium.connect(wsEndpoint)` and sees the guarded context as `contexts()[0]`. The guard runs in the launcher's process, so the client's own `unroute` and `unrouteAll()` cannot remove it, and a `page.route` handler that calls `continue()` without overrides is still judged (page handlers run before the owner's context route). New tabs the client opens in that context are guarded. A client's `context.route` handler runs after the guard, in the client's process, so its `continue()` or `fallback()` overrides are not judged again, and its `route.fetch()` is not seen; see "What it cannot see" below.
+
+The command does the same from a shell:
+
+```
+npx playwright-write-guard-browser [--config <path>] [--headed] [--host <h>] [--port <n>]
+```
+
+`--config` is passed to `loadConfig` (so without it, `WRITE_GUARD_CONFIG` and `write-guard.config.json` apply), `--headed` sets `headless` to false, and `--host` and `--port` default to `127.0.0.1` and `0`. It prints `endpoint: <ws endpoint>` on a line of its own, then how to attach: Playwright MCP with `--endpoint <ws endpoint>` and without `--isolated` (which uses `contexts()[0]`), or the Playwright CLI with `playwright-cli attach --endpoint=<ws endpoint>`. It stays up until SIGINT or SIGTERM, then closes the browser and exits 0. An unknown flag or a flag missing its value prints the usage line and exits 1.
+
+### What it cannot see
+
+- `APIRequestContext` objects the guard cannot reach: an attached client's own `page.request` and `context.request` in launcher mode, and `playwright.request.newContext()` called from an agent's run-code tool.
+- An agent's run-code tool, and any browser the agent launches itself.
+- A Playwright Test run with `-c` from another directory without `WRITE_GUARD_CONFIG`: the fixture finds no config file and falls back to the defaults.
+- WebSockets, unless `websockets` is `"block"`. A caller's own `routeWebSocket` registered after the guard can take precedence over `websockets: "block"`.
+- WebRTC and WebTransport.
+- Redirects after the first URL: only the request the page made is judged, not where the server redirects it.
+- Drag-and-drop, and pointer or mouse handlers that act before `click`.
+- Client-side-only destructive actions that no click or submit reaches.
+- Requests are classified only as well as the config: a write sent as GET, or a read sent as POST, needs a `writes` or `allow` signature.
+- Any context other than `contexts()[0]` in launcher mode: `--isolated`, or `browser.newContext()` from an agent's run-code tool, makes a new, unguarded context.
+- A client's `context.route` overrides in launcher mode are not judged again: that handler runs after the guard, in the client's process, so a `continue()` or `fallback()` that rewrites the method, URL or body (a GET rewritten to DELETE) reaches the server.
+- A client's `route.fetch()` from any route handler (`page.route` or `context.route`) in launcher mode is not seen: it is sent through the client's own `APIRequestContext`, which the guard cannot reach.
+- Code in the same process that calls Playwright's prototype methods directly (for example `Object.getPrototypeOf(context).route` or `.unrouteAll`, `Object.getPrototypeOf(route).continue`, or `Object.getPrototypeOf(context.request).fetch`, which goes around the read-only lock on `APIRequestContext`) or removes the guard's own `page` or `dialog` listeners (`context.removeAllListeners('page')` leaves new pages' routes unwrapped; `context.removeAllListeners('dialog')` lets a caller accept a dialog) goes around the guard's wrappers: the route it registers is not wrapped (its `continue()` can send a POST), `unrouteAll` removes the guard, and a `continue` with overrides skips the override judging.
+- Routes and dialog listeners registered before `install`: a `page.route` whose `continue()` sends a write, a `context.route` whose overrides are not judged, and a page `dialog` listener that accepts all run outside the guard's wrappers.
+- Under `observe`, sends through `context.request`, `page.request` and the `request` fixture are neither blocked nor recorded (only read-only locks them), so an observe run does not list them.
+- Under read-only, pressing Enter or Space in a text field whose value contains a built-in verb is refused (the label rule uses the focused element's value), and a click on plain text containing a verb, outside any control, can be refused.
+- Controls whose label is rendered inside a shadow root: the page sees the shadow host, whose text does not include the shadow content, so the click is not refused in the page. The network layer still judges any request it sends.
+- A document loaded with `page.setContent()`: the guard's in-page listeners do not carry over into it, so a destructive click there is not refused in the page. The network layer still judges any request it sends.
+- Node's own `http`, `https` and `net` modules in the test process.
+
+It is a safety net, not a security boundary. A restricted test account is the boundary.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Written by Venkata Sandeep Takasi.

package/bin/browser.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// playwright-write-guard-browser: start a guarded Chromium and print how an agent attaches.
+
+import { parseArgs } from 'node:util';
+import { startGuardedBrowser } from '../src/browser.mjs';
+import { loadConfig } from '../src/install.mjs';
+
+const USAGE = 'usage: playwright-write-guard-browser [--config <path>] [--headed] [--host <h>] [--port <n>]';
+
+let args;
+try {
+  ({ values: args } = parseArgs({
+    options: { config: { type: 'string' }, headed: { type: 'boolean' }, host: { type: 'string' }, port: { type: 'string' } },
+  }));
+} catch {
+  args = null;
+}
+const port = args?.port === undefined ? 0 : Number(args.port);
+if (!args || !Number.isInteger(port) || port < 0 || port > 65535) {
+  console.error(USAGE);
+  process.exit(1);
+}
+
+let guarded;
+try {
+  guarded = await startGuardedBrowser({
+    config: loadConfig(args.config),
+    headless: !args.headed,
+    host: args.host ?? '127.0.0.1',
+    port,
+  });
+} catch (err) {
+  console.error(err?.message ?? String(err));
+  process.exit(1);
+}
+
+const ws = guarded.wsEndpoint;
+console.log(`endpoint: ${ws}`);
+console.log('Attach one of:');
+console.log(`  Playwright MCP: --endpoint ${ws} (without --isolated, which would make a new, unguarded context)`);
+console.log(`  Playwright CLI: playwright-cli attach --endpoint=${ws}`);
+console.log('Stop with Ctrl+C.');
+
+// Playwright's own signal handlers close the browser and exit 130; this process closes it
+// itself and exits 0, so they go.
+process.removeAllListeners('SIGINT');
+process.removeAllListeners('SIGTERM');
+let stopping = false;
+const stop = async () => {
+  if (stopping) return;
+  stopping = true;
+  await guarded.close().catch((err) => console.error(err?.message ?? String(err)));
+  process.exit(0);
+};
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "playwright-write-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A read-only safety net for Playwright tests and AI browser agents: blocks writes at the network layer and refuses destructive clicks in the page.",
+  "keywords": [
+    "playwright",
+    "testing",
+    "read-only",
+    "safety",
+    "ai-agents",
+    "mcp"
+  ],
+  "license": "MIT",
+  "author": "Venkata Sandeep Takasi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SandeepTakasi/playwright-write-guard.git"
+  },
+  "homepage": "https://github.com/SandeepTakasi/playwright-write-guard#readme",
+  "bugs": {
+    "url": "https://github.com/SandeepTakasi/playwright-write-guard/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/core.d.ts",
+      "default": "./src/core.mjs"
+    },
+    "./install": {
+      "types": "./types/install.d.ts",
+      "default": "./src/install.mjs"
+    },
+    "./test": {
+      "types": "./types/test.d.ts",
+      "default": "./src/fixture.mjs"
+    },
+    "./init-page": {
+      "types": "./types/init-page.d.ts",
+      "default": "./src/init-page.mjs"
+    },
+    "./browser": {
+      "types": "./types/browser.d.ts",
+      "default": "./src/browser.mjs"
+    }
+  },
+  "bin": {
+    "playwright-write-guard-browser": "./bin/browser.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs && playwright test --pass-with-no-tests"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.59",
+    "playwright-core": ">=1.59"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "1.64.0",
+    "playwright-core": "1.64.0"
+  }
+}

package/src/browser.mjs

@@ -0,0 +1,29 @@
+// playwright-write-guard/browser: a guarded Chromium that an agent attaches to. The guard runs
+// in this process, so an attached client cannot remove it. Its context.route overrides, its
+// route.fetch() and any context other than this one are not seen (see the README's limits).
+
+import { chromium } from 'playwright-core';
+import { install, loadConfig } from './install.mjs';
+
+export async function startGuardedBrowser({ config = loadConfig(), headless = true, host = '127.0.0.1', port = 0, title = 'write-guard' } = {}) {
+  const browser = await chromium.launch({ headless });
+  try {
+    const context = await browser.newContext({ serviceWorkers: 'block' });
+    const guard = await install(context, config);
+    const { endpoint } = await browser.bind(title, { host, port });
+    return {
+      wsEndpoint: endpoint,
+      browser,
+      context,
+      guard,
+      async close() {
+        await guard.close();
+        await context.close();
+        await browser.close();
+      },
+    };
+  } catch (err) {
+    await browser.close().catch(() => {});
+    throw err;
+  }
+}

package/src/core.mjs

@@ -0,0 +1,109 @@
+// playwright-write-guard: the decision core. Pure functions, no I/O, no imports.
+//
+// Every exported function is self-contained: it references nothing outside its own
+// arguments and body, because the installer injects `fn.toString()` into pages, where a
+// capture-phase click listener must decide synchronously. Keep it that way: no module-level
+// helpers or constants, and inline whatever a function needs.
+
+/**
+ * Validate a raw config and apply its defaults. `null` and `undefined` mean `{}`.
+ * Throws `write-guard: <path>: <message>` on anything malformed.
+ */
+export function compileConfig(raw) {
+  const METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', '*'];
+  const VERBS = ['save', 'delete', 'remove', 'publish', 'share', 'submit', 'send', 'archive', 'upload',
+    'import', 'rename', 'duplicate', 'update', 'confirm', 'pay', 'purchase', 'invite', 'reset',
+    'restore', 'approve', 'reject', 'log out', 'sign out'];
+  const fail = (path, message) => { throw new Error(`write-guard: ${path}: ${message}`); };
+  const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const list = (v, path) => {
+    if (v === undefined) return [];
+    if (!Array.isArray(v)) fail(path, 'must be a list');
+    return v;
+  };
+  const oneOf = (v, allowed, dflt, path) => {
+    if (v === undefined) return dflt;
+    if (!allowed.includes(v)) fail(path, `must be one of ${allowed.join(' | ')}`);
+    return v;
+  };
+  const regex = (src, path, flags) => {
+    if (typeof src !== 'string' || src === '') fail(path, 'must be a non-empty regex string');
+    try { return new RegExp(src, flags); } catch (e) { return fail(path, `does not compile: ${e.message}`); }
+  };
+  const sigs = (v, key) => list(v, key).map((s, i) => {
+    const at = `${key}[${i}]`;
+    if (!isObj(s)) fail(at, 'must be an object');
+    if (!METHODS.includes(s.method)) fail(`${at}.method`, `must be one of ${METHODS.join(' | ')}`);
+    return {
+      method: s.method,
+      url: regex(s.url, `${at}.url`, ''),
+      body: s.body === undefined || s.body === null ? null : regex(s.body, `${at}.body`, ''),
+    };
+  });
+
+  const cfg = raw ?? {};
+  if (!isObj(cfg)) fail('config', 'must be an object');
+  const controls = cfg.controls === undefined ? {} : cfg.controls;
+  if (!isObj(controls)) fail('controls', 'must be an object');
+  if (cfg.defaultControls !== undefined && typeof cfg.defaultControls !== 'boolean') {
+    fail('defaultControls', 'must be a boolean');
+  }
+  if (cfg.log !== undefined && cfg.log !== null && (typeof cfg.log !== 'string' || cfg.log === '')) {
+    fail('log', 'must be a non-empty string or null');
+  }
+
+  const policy = oneOf(cfg.policy, ['read-only', 'observe'], 'read-only', 'policy');
+  const websockets = oneOf(cfg.websockets, ['allow', 'block'], 'allow', 'websockets');
+  const allow = sigs(cfg.allow, 'allow');
+  const writes = sigs(cfg.writes, 'writes');
+  const extra = list(controls.text, 'controls.text');
+  extra.forEach((s, i) => regex(s, `controls.text[${i}]`, 'i'));
+  const icons = list(controls.icons, 'controls.icons');
+  icons.forEach((s, i) => { if (typeof s !== 'string' || s === '') fail(`controls.icons[${i}]`, 'must be a non-empty string'); });
+
+  // The built-in verbs match as whole words ("save", not "saved"); user sources are regexes.
+  const parts = [...(cfg.defaultControls === false ? [] : [`\\b(?:${VERBS.join('|')})\\b`]),
+    ...extra.map((s) => `(?:${s})`)];
+
+  return {
+    policy,
+    allow,
+    writes,
+    text: parts.length ? new RegExp(parts.join('|'), 'i') : null,
+    icons: [...icons],
+    websockets,
+    log: cfg.log === undefined ? 'write-guard.jsonl' : cfg.log,
+  };
+}
+
+/** `block` (read-only) or `observe` (observe) for a write, else `allow`. */
+export function decideRequest(request, config) {
+  const method = String(request.method ?? '').toUpperCase();
+  const url = String(request.url ?? '');
+  const body = request.body;
+  const matches = (s) => (s.method === '*' || s.method === method) && s.url.test(url)
+    && (s.body === null || (typeof body === 'string' && s.body.test(body)));
+
+  const allowed = config.allow.findIndex(matches);
+  if (allowed !== -1) return { action: 'allow', reason: `allow[${allowed}] marks it a read` };
+  const hit = config.writes.findIndex(matches);
+  let what;
+  if (hit !== -1) what = `${method} matches writes[${hit}]`;
+  else if (!['GET', 'HEAD', 'OPTIONS'].includes(method)) what = `${method} is not a read method`;
+  else return { action: 'allow', reason: `${method} is a read method and matches no writes signature` };
+  return config.policy === 'observe'
+    ? { action: 'observe', reason: `${what}; policy observe` }
+    : { action: 'block', reason: `${what}; policy read-only` };
+}
+
+/** `block` (read-only) or `observe` (observe) for a destructive control, else `allow`. */
+export function decideControl(control, config) {
+  const label = String(control.label ?? '').trim();
+  const icon = (control.icons ?? []).find((c) => config.icons.some((p) => String(c).startsWith(p)));
+  const textHit = label !== '' && config.text !== null && config.text.test(label);
+  if (!textHit && icon === undefined) return { action: 'allow', reason: 'not a destructive control' };
+  const what = textHit ? `"${label.slice(0, 80)}" matches a destructive label` : `icon ${icon} matches a destructive icon`;
+  return config.policy === 'observe'
+    ? { action: 'observe', reason: `${what}; policy observe` }
+    : { action: 'block', reason: `${what}; policy read-only` };
+}

package/src/fixture.mjs

@@ -0,0 +1,105 @@
+// playwright-write-guard/test: Playwright Test's `test` and `expect`, with every context guarded.
+//
+// The test's own context is guarded with `install` (which also locks context.request and
+// page.request under read-only). Worker-level locks refuse the Playwright APIs that would make
+// a context, a request client or a connection the guard cannot see (newContext, newPage,
+// request.newContext, the global fetch, and the launch and connect family) while a guarded test
+// or hook runs. Nothing else is refused: Node's own http, https and net are not seen.
+// Playwright's own creation of the test's context (and, under observe, of the request
+// fixture) is the one exception, and the window that allows it is shut again straight after.
+
+import { test as base, expect } from '@playwright/test';
+import { compileConfig } from './core.mjs';
+import { install, loadConfig } from './install.mjs';
+
+// Open only while Playwright builds this test's context, or its request fixture.
+let contextWindow = false;
+let requestWindow = false;
+
+const refuse = (what) => new Error(
+  `write-guard: ${what} is refused: it would make a context, request client or connection the guard cannot see. `
+  + 'Drive the app through the test\'s own page and context.');
+
+export const test = base.extend({
+  // The guard's config. Evaluated when a test first needs it, so a bad config file is that
+  // test's error rather than a failure to load the file. `test.use` replaces it, used as given.
+  writeGuardConfig: [async ({}, use) => { await use(loadConfig()); }, { option: true }],
+
+  // A service worker can send requests the guard's route never sees.
+  serviceWorkers: 'block',
+
+  // Once per worker. It depends on `browser`, so Playwright has launched its own browser
+  // before the launch family is locked.
+  _writeGuardWorker: [async ({ browser, playwright }, use) => {
+    const restore = [];
+    const lock = (obj, name, label, open = () => false) => {
+      if (typeof obj?.[name] !== 'function') return;
+      const original = obj[name];
+      restore.push(() => { obj[name] = original; });
+      obj[name] = async (...args) => {
+        if (open()) return original.apply(obj, args);
+        throw refuse(label);
+      };
+    };
+    lock(browser, 'newContext', 'browser.newContext()', () => contextWindow);
+    lock(browser, 'newPage', 'browser.newPage()');
+    lock(playwright.request, 'newContext', 'request.newContext()', () => requestWindow);
+    lock(globalThis, 'fetch', 'fetch() (Node\'s own, from the test)');
+    for (const type of [playwright.chromium, playwright.firefox, playwright.webkit]) {
+      for (const method of ['launch', 'launchPersistentContext', 'launchServer', 'connect', 'connectOverCDP']) {
+        lock(type, method, `${type.name()}.${method}()`);
+      }
+    }
+    try {
+      await use();
+    } finally {
+      for (const r of restore.reverse()) r();
+    }
+  }, { scope: 'worker', auto: true }],
+
+  // Set up before the auto fixture below forces the context, so the window is open exactly
+  // while Playwright builds this test's context, and shut whatever happens.
+  _writeGuardOpen: [async ({}, use) => {
+    contextWindow = true;
+    try { await use(); } finally { contextWindow = false; }
+  }, { auto: true }],
+
+  // Every guarded test gets the built-in context, used or not, so the window always closes in
+  // the context fixture below rather than staying open through a test that never asked for a page.
+  _writeGuardContext: [async ({ context }, use) => { await use(); }, { auto: true }],
+
+  // Wraps the built-in context rather than creating one, so storageState, video and trace
+  // settings all survive.
+  context: async ({ context, writeGuardConfig, serviceWorkers }, use, testInfo) => {
+    contextWindow = false;
+    // install cannot change how the context was created; a project that asked for service
+    // workers made a context the guard cannot fully see.
+    if (serviceWorkers !== 'block') {
+      throw new Error(`write-guard: serviceWorkers is '${serviceWorkers}'; the guard needs 'block', or a service worker can send requests it never sees`);
+    }
+    const guard = await install(context, { ...writeGuardConfig, log: null });
+    try {
+      await use(context);
+    } finally {
+      await testInfo.attach('write-guard.json', { body: JSON.stringify(await guard.close(), null, 2), contentType: 'application/json' });
+    }
+  },
+
+  // Playwright builds the request fixture with request.newContext(), so under observe the
+  // window opens for that. Fixtures are set up in parameter order, so this one comes first.
+  // Under read-only this is where the fixture is refused, at setup, before anything is built.
+  _writeGuardRequestWindow: async ({ writeGuardConfig }, use) => {
+    if (compileConfig(writeGuardConfig).policy === 'read-only') {
+      throw new Error('write-guard: the request fixture is refused under read-only');
+    }
+    requestWindow = true;
+    try { await use(); } finally { requestWindow = false; }
+  },
+
+  request: async ({ _writeGuardRequestWindow, request }, use) => {
+    requestWindow = false;
+    await use(request);
+  },
+});
+
+export { expect };

package/src/init-page.mjs

@@ -0,0 +1,9 @@
+// playwright-write-guard/init-page: the `browser.initPage` entry for Playwright MCP and the
+// Playwright CLI. They load it with require(), so nothing it imports uses top-level await.
+
+import { install, loadConfig } from './install.mjs';
+
+/** Guards `page.context()` with `loadConfig()`; install() makes it once per context. */
+export default async function initPage({ page }) {
+  return install(page.context(), loadConfig());
+}

package/src/install.mjs

@@ -0,0 +1,265 @@
+// playwright-write-guard/install: guard one Playwright BrowserContext.
+//
+// The network side judges every request in a catch-all context route registered first, and
+// wraps every route a caller registers later so the guard judges before the caller's handler
+// can continue a request. The page side is an init script built from the decision core's own
+// source, with capture-phase listeners that refuse destructive controls before the app sees
+// them. No playwright import: everything goes through the context it is handed.
+
+import { existsSync, promises as fsp, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { compileConfig, decideControl, decideRequest } from './core.mjs';
+
+const BINDING = '__writeGuardReport';
+const ALREADY = 'write-guard: this context is already guarded by another process; use one mode, not both';
+const SENDS = new Set(['fetch', 'get', 'post', 'put', 'patch', 'delete', 'head']);
+const guarded = new WeakMap();
+
+/** Guard a browser context; a second call on the same context returns the first call's handle. */
+export async function install(context, config = {}) {
+  // Synchronous up to here, so concurrent calls (one per new tab) share one install. A
+  // malformed config throws before anything is stored or installed.
+  if (!guarded.has(context)) guarded.set(context, setup(context, config, compileConfig(config)));
+  return guarded.get(context);
+}
+
+async function setup(context, raw, cfg) {
+  const events = [];
+  const counts = { routed: 0, blocked: 0, observed: 0 };
+  const logPath = cfg.log === null ? null : resolve(cfg.log);
+  let pending = Promise.resolve();
+
+  const record = () => ({
+    installed: true,
+    policy: cfg.policy,
+    routed_requests: counts.routed,
+    blocked: counts.blocked,
+    observed: counts.observed,
+    events: events.map((e) => ({ ...e })),
+  });
+  const emit = (event) => {
+    const e = { ...event, at: new Date().toISOString() };
+    events.push(e);
+    counts[e.action === 'block' ? 'blocked' : 'observed']++;
+    if (logPath) {
+      const line = `${JSON.stringify(e)}\n`;
+      pending = pending.then(() => fsp.appendFile(logPath, line))
+        .catch((err) => process.emitWarning(`write-guard: cannot append to ${logPath}: ${err.message}`));
+    }
+  };
+
+  // First, before anything else: a refused install must leave nothing behind.
+  try {
+    await context.exposeBinding(BINDING, (_source, e) => {
+      if (!e || e.kind !== 'control' || (e.action !== 'block' && e.action !== 'observe')) return;
+      emit({ kind: 'control', action: e.action, reason: String(e.reason), label: String(e.label ?? '').trim().slice(0, 120) });
+    });
+  } catch (err) {
+    if (/already registered/.test(String(err?.message))) throw new Error(ALREADY);
+    throw err;
+  }
+
+  // Each request is judged once, however many handlers see it. True means pass it on.
+  const decided = new WeakSet();
+  const judge = async (route) => {
+    const req = route.request();
+    if (decided.has(req)) return true;
+    decided.add(req);
+    counts.routed++;
+    const method = req.method();
+    const url = req.url();
+    let body = null;
+    try { body = req.postData(); } catch { /* an undecodable body is judged as none */ }
+    const v = decideRequest({ method, url, body }, cfg);
+    if (v.action === 'allow') return true;
+    emit({ kind: 'request', action: v.action, reason: v.reason, method, url });
+    if (v.action === 'observe') return true;
+    if (req.resourceType() === 'document') {
+      await route.fulfill({ status: 403, contentType: 'text/html; charset=utf-8', body: blockedPage(method, url) });
+    } else {
+      await route.abort('blockedbyclient');
+    }
+    return false;
+  };
+
+  // A caller handler's continue, fallback or fetch overrides are judged as the request they
+  // make; one the original already matches was judged above. True means let it proceed.
+  const judgeOverride = (route, options = {}) => {
+    const req = route.request();
+    let original = null;
+    try { original = req.postData(); } catch { /* an undecodable body is judged as none */ }
+    const p = options.postData;
+    const body = p == null ? original : typeof p === 'string' ? p : Buffer.isBuffer(p) ? p.toString('utf8') : JSON.stringify(p);
+    const method = String(options.method || req.method()).toUpperCase();
+    const url = options.url || req.url();
+    if (method === req.method() && url === req.url() && body === original) return { pass: true };
+    const v = decideRequest({ method, url, body }, cfg);
+    if (v.action !== 'allow') emit({ kind: 'request', action: v.action, reason: v.reason, method, url });
+    return { pass: v.action !== 'block', method, url };
+  };
+
+  // A predicate, not a glob, so no caller's unroute(url) can name it.
+  await context.route(() => true, async (route) => { if (await judge(route)) await route.fallback(); });
+
+  if (cfg.websockets === 'block') {
+    await context.routeWebSocket(() => true, async (ws) => {
+      emit({ kind: 'request', action: 'block', reason: 'websockets is "block": every WebSocket is refused', url: ws.url() });
+      await ws.close({ code: 1008, reason: 'write-guard' }).catch(() => {});
+    });
+  }
+
+  await context.addInitScript({ content: pageScript(raw) });
+
+  patchRoutes(context, judge, judgeOverride);
+  if (cfg.policy === 'read-only') {
+    lockRequest(context);
+    // The context's dialog event is emitted before any page's, so this runs ahead of every
+    // listener a caller adds later; their accept() then finds the dialog already handled.
+    context.on('dialog', (d) => d.dismiss().catch(() => {}));
+  }
+  const onPage = (page) => {
+    patchRoutes(page, judge, judgeOverride);
+    if (cfg.policy === 'read-only') lockRequest(page);
+  };
+  for (const p of context.pages()) onPage(p);
+  context.on('page', onPage);
+
+  return {
+    record,
+    async close() {
+      // Appends chain onto `pending`; wait until no new one arrived while waiting.
+      let last;
+      do { last = pending; await last; } while (last !== pending);
+      return record();
+    },
+  };
+}
+
+const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const blockedPage = (method, url) => `<!doctype html><html><head><meta charset="utf-8"><title>write-guard</title></head>`
+  + `<body><p>write-guard blocked ${escapeHtml(method)} ${escapeHtml(url)}</p></body></html>`;
+
+// The route a caller's handler gets: continue, fallback and fetch judge their overrides first,
+// and everything else is the original Route.
+function judgedRoute(r, judgeOverride) {
+  return new Proxy(r, {
+    get(obj, prop) {
+      if (prop === 'continue' || prop === 'fallback') {
+        return async (options) => (judgeOverride(obj, options).pass ? obj[prop](options) : obj.abort('blockedbyclient'));
+      }
+      if (prop === 'fetch') {
+        return async (options) => {
+          const v = judgeOverride(obj, options);
+          if (!v.pass) throw new Error(`write-guard: route.fetch of ${v.method} ${v.url} is refused under read-only`);
+          return obj.fetch(options);
+        };
+      }
+      const v = Reflect.get(obj, prop, obj);
+      return typeof v === 'function' ? v.bind(obj) : v;
+    },
+  });
+}
+
+// Every handler a caller registers asks the guard first; unroute and unrouteAll remove only
+// the caller's own handlers.
+function patchRoutes(target, judge, judgeOverride) {
+  const route = target.route.bind(target);
+  const unroute = target.unroute.bind(target);
+  const tracked = [];
+  const sameUrl = (a, b) => a === b
+    || (a instanceof RegExp && b instanceof RegExp && a.source === b.source && a.flags === b.flags);
+  target.route = (url, handler, options) => {
+    const wrapped = async (r, request) => { if (await judge(r)) return handler(judgedRoute(r, judgeOverride), request); };
+    tracked.push({ url, handler, wrapped });
+    // The returned disposable calls target.unroute(url, wrapped), which lands below.
+    return route(url, wrapped, options);
+  };
+  target.unroute = async (url, handler) => {
+    for (const t of tracked.filter((x) => sameUrl(x.url, url) && (!handler || x.handler === handler || x.wrapped === handler))) {
+      tracked.splice(tracked.indexOf(t), 1);
+      await unroute(t.url, t.wrapped);
+    }
+  };
+  // unrouteAll's `behavior` option is ignored; the guard never waits on a caller's handlers.
+  target.unrouteAll = async () => {
+    for (const t of tracked.splice(0)) await unroute(t.url, t.wrapped);
+  };
+}
+
+// The request object stays readable (Playwright's own teardown reads it); only sends throw.
+function lockRequest(target) {
+  const original = target.request;
+  const locked = new Proxy(original, {
+    get(obj, prop) {
+      if (typeof prop === 'string' && SENDS.has(prop)) {
+        return async () => { throw new Error(`write-guard: ${prop} through APIRequestContext is refused under read-only`); };
+      }
+      const v = Reflect.get(obj, prop, obj);
+      return typeof v === 'function' ? v.bind(obj) : v;
+    },
+  });
+  Object.defineProperty(target, 'request', { get: () => locked, configurable: true });
+}
+
+// The page side. A capture-phase listener must decide synchronously, so the decision core
+// runs in the page, compiled from the same raw config.
+function pageScript(raw) {
+  return `(() => {
+  const compileConfig = ${compileConfig.toString()};
+  const decideControl = ${decideControl.toString()};
+  const cfg = compileConfig(${JSON.stringify(raw ?? {})});
+  // Captured before any page script runs, so the page cannot swap them out.
+  const bind = window.${BINDING};
+  const preventDefault = Function.prototype.call.bind(Event.prototype.preventDefault);
+  const stopImmediatePropagation = Function.prototype.call.bind(Event.prototype.stopImmediatePropagation);
+  const report = (e) => { try { Promise.resolve(bind(e)).catch(() => {}); } catch (_) {} };
+  const CONTROL = 'button, a, [role=button], [role=menuitem], [role=link], [role=tab], input[type=submit], input[type=button], input[type=image], summary, [onclick], [tabindex]';
+  const labelOf = (el) => {
+    for (const v of [el.getAttribute('aria-label'), el.innerText, el.getAttribute('title'), el.value]) {
+      if (typeof v === 'string' && v.trim()) return v.trim();
+    }
+    return '';
+  };
+  const iconsOf = (el) => {
+    const out = [];
+    for (const n of [el, ...el.querySelectorAll('[class]')]) {
+      for (const c of (n.getAttribute('class') || '').split(/\\s+/)) if (c) out.push(c);
+    }
+    return out;
+  };
+  const judge = (el, e) => {
+    if (!(el instanceof Element)) return;
+    const label = labelOf(el);
+    const v = decideControl({ label, icons: iconsOf(el) }, cfg);
+    if (v.action === 'allow') return;
+    if (v.action === 'block') { preventDefault(e); stopImmediatePropagation(e); }
+    report({ kind: 'control', action: v.action, reason: v.reason, label: label.slice(0, 120) });
+  };
+  window.addEventListener('click', (e) => {
+    if (e.target instanceof Element) judge(e.target.closest(CONTROL) || e.target, e);
+  }, true);
+  window.addEventListener('submit', (e) => judge(e.submitter || e.target, e), true);
+  window.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' || e.key === ' ') judge(document.activeElement, e);
+  }, true);
+})();`;
+}
+
+/**
+ * Read a raw config: `path`, else WRITE_GUARD_CONFIG, else write-guard.config.json when it
+ * exists, else {}. WRITE_GUARD_POLICY, when non-empty, overrides `policy`. Validated, returned raw.
+ */
+export function loadConfig(path) {
+  const named = path || process.env.WRITE_GUARD_CONFIG;
+  const file = named ? resolve(named) : existsSync(resolve('write-guard.config.json')) ? resolve('write-guard.config.json') : null;
+  let raw = {};
+  if (file) {
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch (err) { throw new Error(`write-guard: ${file}: cannot be read: ${err.message}`); }
+    try { raw = JSON.parse(text) ?? {}; } catch (err) { throw new Error(`write-guard: ${file}: is not valid JSON: ${err.message}`); }
+  }
+  const policy = process.env.WRITE_GUARD_POLICY;
+  if (policy && raw !== null && typeof raw === 'object' && !Array.isArray(raw)) raw = { ...raw, policy };
+  compileConfig(raw);
+  return raw;
+}

package/types/browser.d.ts

@@ -0,0 +1,31 @@
+// playwright-write-guard/browser: a guarded Chromium that an agent attaches to.
+
+import type { Browser, BrowserContext } from 'playwright-core';
+import type { Config } from './core.js';
+import type { GuardHandle } from './install.js';
+
+export interface GuardedBrowserOptions {
+  /** Default `loadConfig()`. */
+  config?: Config;
+  /** Default `true`. */
+  headless?: boolean;
+  /** Default `"127.0.0.1"`. */
+  host?: string;
+  /** Default `0`: the OS picks a free port. */
+  port?: number;
+  /** Default `"write-guard"`. */
+  title?: string;
+}
+
+export interface GuardedBrowser {
+  /** The endpoint `browser.bind` returned, `ws://<host>:<port>/<id>`. */
+  wsEndpoint: string;
+  browser: Browser;
+  /** The one guarded context; an attached client sees it as `contexts()[0]`. */
+  context: BrowserContext;
+  guard: GuardHandle;
+  /** Flushes the guard's log, then closes the context and the browser. */
+  close(): Promise<void>;
+}
+
+export function startGuardedBrowser(options?: GuardedBrowserOptions): Promise<GuardedBrowser>;

package/types/core.d.ts

@@ -0,0 +1,97 @@
+// playwright-write-guard: the decision core. Pure functions, no I/O, no Playwright types.
+
+/** `read-only` blocks writes; `observe` records them and lets them through. */
+export type Policy = 'read-only' | 'observe';
+
+/** A request method a signature can name. `*` matches any method. */
+export type SigMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | '*';
+
+/**
+ * A request signature. `url` and `body` are regex sources, compiled with no flags
+ * (case-sensitive) and tested unanchored against the full URL and the request body.
+ * A signature with `body` never matches a request that has no body.
+ */
+export interface Sig {
+  method: SigMethod;
+  url: string;
+  /** Absent or `null`: the signature names no body. */
+  body?: string | null;
+}
+
+/** The raw config. Every key is optional; unknown keys are ignored. */
+export interface Config {
+  /** Default `"read-only"`. */
+  policy?: Policy;
+  /** Requests matching any of these are never writes. */
+  allow?: Sig[];
+  /** Requests matching any of these are writes even when their method is GET, HEAD or OPTIONS. */
+  writes?: Sig[];
+  controls?: {
+    /** Regex sources, compiled case-insensitive, added to the built-in verbs. */
+    text?: string[];
+    /** Class name prefixes; a control with a class starting with one is destructive. */
+    icons?: string[];
+  };
+  /** Default `true`: include the 23 built-in verbs in the text pattern. */
+  defaultControls?: boolean;
+  /** Default `"allow"`. */
+  websockets?: 'allow' | 'block';
+  /** JSONL audit log path, relative to the working directory. Default `"write-guard.jsonl"`; `null` turns it off. */
+  log?: string | null;
+}
+
+export interface CompiledSig {
+  method: SigMethod;
+  url: RegExp;
+  /** `null` when the signature names no body. */
+  body: RegExp | null;
+}
+
+/** What `compileConfig` returns: every default applied, every pattern compiled. */
+export interface CompiledConfig {
+  policy: Policy;
+  allow: CompiledSig[];
+  writes: CompiledSig[];
+  /** The built-in verbs (unless `defaultControls` is false) and `controls.text`, as one case-insensitive pattern; `null` when there are none. */
+  text: RegExp | null;
+  /** `controls.icons`; there are no built-in icons. */
+  icons: string[];
+  websockets: 'allow' | 'block';
+  log: string | null;
+}
+
+export interface RequestInput {
+  method: string;
+  url: string;
+  /** The request body; `null` or absent when it has none. */
+  body?: string | null;
+}
+
+export interface RequestDecision {
+  action: 'allow' | 'block' | 'observe';
+  reason: string;
+}
+
+export interface ControlInput {
+  /** The control's label. */
+  label: string;
+  /** Every class name on the control and its descendants. */
+  icons: string[];
+}
+
+export interface ControlDecision {
+  action: 'allow' | 'block' | 'observe';
+  reason: string;
+}
+
+/**
+ * Validate a raw config and apply its defaults. `null` and `undefined` mean `{}`.
+ * Throws `write-guard: <path>: <message>` on anything malformed.
+ */
+export function compileConfig(raw?: Config | null): CompiledConfig;
+
+/** `block` (read-only) or `observe` (observe) for a write, else `allow`. */
+export function decideRequest(request: RequestInput, config: CompiledConfig): RequestDecision;
+
+/** `block` (read-only) or `observe` (observe) for a destructive control, else `allow`. */
+export function decideControl(control: ControlInput, config: CompiledConfig): ControlDecision;

package/types/init-page.d.ts

@@ -0,0 +1,9 @@
+// playwright-write-guard/init-page: the `browser.initPage` entry for Playwright MCP and the Playwright CLI.
+
+import type { Page } from 'playwright-core';
+import type { GuardHandle } from './install.js';
+
+/** Guards `page.context()` with `loadConfig()`; once per context, however many pages it is handed. */
+declare function initPage(args: { page: Page }): Promise<GuardHandle>;
+
+export default initPage;

package/types/install.d.ts

@@ -0,0 +1,49 @@
+// playwright-write-guard/install: the installer every entry point shares.
+
+import type { BrowserContext } from 'playwright-core';
+import type { Config, Policy } from './core.js';
+
+/** One write the guard blocked or observed. Request events carry `method` and `url`; control events carry `label`. */
+export interface GuardEvent {
+  kind: 'request' | 'control';
+  action: 'block' | 'observe';
+  reason: string;
+  method?: string;
+  url?: string;
+  label?: string;
+  /** ISO 8601 timestamp. */
+  at: string;
+}
+
+export interface GuardRecord {
+  installed: true;
+  policy: Policy;
+  /** Requests the guard judged, each counted once. */
+  routed_requests: number;
+  /** Request and control events with `action: "block"`. */
+  blocked: number;
+  /** Request and control events with `action: "observe"`. */
+  observed: number;
+  events: GuardEvent[];
+}
+
+export interface GuardHandle {
+  /** A snapshot of what the guard has seen so far. */
+  record(): GuardRecord;
+  /** Resolves after the last pending log append with the final record. The guard stays active until the context closes. */
+  close(): Promise<GuardRecord>;
+}
+
+/**
+ * Guard a browser context. Compiles `config` (default `{}`); a second call on the same
+ * context returns the first call's handle. Throws `write-guard: this context is already
+ * guarded by another process; use one mode, not both` when another process has guarded it.
+ */
+export function install(context: BrowserContext, config?: Config): Promise<GuardHandle>;
+
+/**
+ * Read a config: `path`, else `WRITE_GUARD_CONFIG`, else `write-guard.config.json` when it
+ * exists, else `{}`. `WRITE_GUARD_POLICY`, when set, overrides `policy`. Validated through
+ * `compileConfig`; returns the raw config.
+ */
+export function loadConfig(path?: string): Config;

package/types/test.d.ts

@@ -0,0 +1,22 @@
+// playwright-write-guard/test: Playwright Test's `test` and `expect`, with every context guarded.
+
+import type {
+  PlaywrightTestArgs,
+  PlaywrightTestOptions,
+  PlaywrightWorkerArgs,
+  PlaywrightWorkerOptions,
+  TestType,
+} from '@playwright/test';
+import type { Config } from './core.js';
+
+export interface WriteGuardOptions {
+  /** The guard's config, settable with `test.use`. Default `loadConfig()`. Its `log` is ignored: the fixture never writes a log file. */
+  writeGuardConfig: Config;
+}
+
+export declare const test: TestType<
+  PlaywrightTestArgs & PlaywrightTestOptions & WriteGuardOptions,
+  PlaywrightWorkerArgs & PlaywrightWorkerOptions
+>;
+
+export { expect } from '@playwright/test';