@mefistofelix/cdp.js 0.1.2 → 0.3.0

package/README.md

@@ -1,12 +1,16 @@
 # cdp.js
 
-A low-level Chromium DevTools Protocol library for Node.js. One ES module,
+A low-level Chromium DevTools Protocol library for Node.js, Deno and Bun, with an
+optional native Deno/Bun server for Chrome extension reverse connections. One ES module,
 standard-library imports, no runtime dependencies or root `package.json`.
 
 Use Node.js 22.19+ and an installed Chrome, Chromium or Edge. Import `cdp.js`
 directly from an ES module, for example `example.mjs`, and run `node example.mjs`.
 Browser discovery covers common Windows, macOS and Linux installation paths;
 use `executable_path` or the `CDP_BROWSER` environment variable for other paths.
+The same module also runs with `bun example.mjs` or `deno run -A example.mjs`.
+Direct and reverse modes are tested with Bun 1.4.3; no Bun-specific package,
+configuration file or installation step is required by the library.
 
 For a published npm release:
 
@@ -20,24 +24,39 @@ import api, { util, jsrpc, browser, cdp } from '@mefistofelix/cdp.js'
 
 The npm package exports the same file and API. Direct file imports in the examples
 below remain supported. Publication metadata is isolated in `npm/`.
+The package includes both `cdp_ext/` files. With `cdp_ext: true`, the manager
+writes a configured extension copy into the browser's profile directory and loads
+it automatically; no manual extraction or build is needed. Reverse mode still
+requires Deno or Bun. In Deno, import from `npm:@mefistofelix/cdp.js`.
+In Bun, use `bun add @mefistofelix/cdp.js` and the ordinary package import above.
 
 ## Features and scope
 
 - Native CDP requests through `call({ method, params })`, with native results.
 - Named browsers and targets, created and connected on demand.
+- Browser proxies and named direct-mode contexts with independent proxies/storage
+  and automatic cleanup after their last target closes.
+- Incognito targets in direct and reverse modes.
 - Attachment through WebSocket, HTTP discovery or a debugging port.
+- Optional Chrome extension reverse connections through one native Deno/Bun server,
+  without browser remote-debugging arguments.
+- Generic `chrome.x.y` extension API calls on that connection, including scripting,
+  tabs/windows, cookies, storage, downloads and browser settings.
 - Shared initialization for concurrent calls; reconnection and target recreation
   on subsequent use, without replaying failed commands.
 - Public object mappings and directly replaceable custom method handlers.
 - Configurable target initialization, JavaScript bindings and direct events.
+- Reverse network notifications through CDP Network or extension webRequest,
+  including observation without debugger attachment.
 - XPath `_.click` and `_.find`, including two XPath expression rewrites.
 - Configurable browser launch arguments and profile preferences.
 - Raw WebSocket JSON-RPC transport and reusable static helpers.
 
 There is no Page class, batch API, image-processing helper, event buffer/filter
-API or database. Browser, target and session mappings live in memory. Chromium
+API or database. Browser, context, target and session mappings live in memory. Chromium
 profiles and their preferences are ordinary files on disk. Any native CDP method
-supported by the connected browser remains available through `call`.
+supported by the connected browser remains available through direct `call`.
+The optional extension transport has the command/domain limits documented below.
 
 ## Quick start
 
@@ -100,13 +119,16 @@ import api, { util, jsrpc, browser, cdp } from './cdp.js'
 | `new cdp(options = {})` | Create a manager; does not launch a browser yet. |
 | `client.call({ method, params = {} })` | Resolve routing and return a promise for the native CDP result, or a custom handler's result. |
 | `client.evaluate_xpath(params, fn, options)` | Execute a serialized function with a normalized XPath in a target; return the native `Runtime.evaluate` result. |
-| `client.close()` | Close owned browser processes, disconnect attached browsers, then clear `client.browsers`. Profile directories remain. |
-| `new jsrpc(url, options = {})` | Open a raw WebSocket JSON-RPC connection. |
+| `client.close()` | Close owned processes, disconnect attached/reverse browsers, stop the reverse server and clear browser/socket mappings. Profiles and external browsers remain. |
+| `new jsrpc(urlOrSocket, options = {})` | Open a raw WebSocket JSON-RPC connection or equip an accepted socket with the same RPC methods. |
+| `client.listen_reverse(options = {})` | Start the native Deno or Bun WebSocket server; returns that server with common lifecycle fields documented below. |
 | `socket.req(request, timeout_ms)` | Assign a request ID and await its native result. |
 | `socket.notify(request)` | Serialize and send a raw message; no ID allocation or response wait. |
 | `socket.close()` | Native WebSocket close; does not terminate the browser. |
 | `browser.find_executable_path()` | Synchronously return an executable path from the environment or common locations. |
 | `browser.build_args(options = {})` | Return a fresh, editable object of launch switches. |
+| `browser.extension_id(directory)` | Compute Chromium's path-derived unpacked extension ID. Use the canonical absolute directory without a manifest `key`. |
+| `browser.profile_extension_paths(args)` | Read the effective profile and return a promise for an object keyed by extension ID, with `{ path, enabled }` values for enabled and disabled extensions. |
 | `browser.update_profile_preferences(filename, preferences)` | Update dotted keys in a JSON preferences file; return a promise. |
 | `browser.launch(options)` | Start a local browser and return a promise for `{ proc, url }`. The caller owns the process. |
 | `util.normalize_xpath(xpath)` | Return an XPath string with the supported rewrites. |
@@ -122,7 +144,7 @@ connections or target/session routing.
 
 | Field | Meaning |
 | --- | --- |
-| `method` | Native name such as `Page.navigate`, or a custom name beginning with `_.`. |
+| `method` | Native name such as `Page.navigate`, a custom name beginning with `_.`, or an extension API name such as `chrome.tabs.query` in reverse mode. |
 | `params` | Native parameters plus the two routing fields below. Defaults to `{}`. |
 | `params.browser` | Browser label or configuration object with `name`. Defaults to `'main'`. |
 | `params.target` | Target label or configuration object with `name`. Omitted or `null` means a browser-level request. |
@@ -170,7 +192,8 @@ For a new browser record, configuration is assembled in this order:
 2. Constructor browser options.
 3. The `params.browser` configuration object.
 
-`args` and `preferences` are shallow-merged separately between steps 2 and 3.
+`args`, `preferences` and `local_state` are shallow-merged separately between
+steps 2 and 3.
 For duplicate keys, the per-browser value wins. Arrays replace previous arrays;
 they are not concatenated during this merge.
 
@@ -179,6 +202,10 @@ At local launch, another two independent merges happen:
 - Generated CLI defaults, adjusted by high-level browser options, then raw `args`.
 - Generated profile preference defaults, then raw `preferences`.
 
+After the CLI merge, a non-null/non-false `disable-extensions-except` adds
+`DisableDisableExtensionsExceptCommandLineSwitch` to the final `disable-features`
+list. This requested argument convention also applies to raw feature overrides.
+
 There is no conflict resolver across CLI flags and preferences. Each is passed
 to Chromium through its own mechanism. Raw settings can therefore contradict a
 high-level option; the library does not silently reconcile them.
@@ -195,21 +222,28 @@ local configuration.
 | Option | Type / default | Meaning |
 | --- | --- | --- |
 | `base_path` | string, `'.cdp'` | Constructor-only profile root, resolved against the working directory. |
+| `reverse_server` | object, `{}` | Constructor-only settings for the shared lazy listener: `hostname` defaults to `'127.0.0.1'`, `port` to `9223`. Independent of browser attachment `host`/`port`. |
 | `name` | string, `'main'` when routing is omitted | Required in a browser configuration object; dictionary key and default profile directory label. |
-| `user_data_dir` | absolute path string, `<base_path>/<name>` | Chromium user-data directory containing profiles such as `Default`. The generated default is absolute; explicit overrides should be absolute too. |
+| `user_data_dir` | absolute path string or `null`, `<base_path>/<name>` | Chromium user-data directory containing profiles such as `Default`. Explicit paths should be absolute. `null` omits the switch and skips manager preference-file writes; Chromium selects its system directory. |
 | `executable_path` | string, automatic discovery | Executable to spawn; takes precedence over `CDP_BROWSER`. |
 | `headless` | boolean, `false` | When true, add `headless: 'new'` and default `window-size: '1440,900'`. |
 | `windowsHide` | boolean, effective headless mode | Hide the spawned process's console on Windows. Defaults to true when the final arguments include `--headless`, false otherwise; an explicit value wins. Does not hide the parent terminal. |
-| `extensions` | boolean, `false` | When true, omit the two extension-disabling switches; does not install extensions. |
+| `extensions` | boolean or array of directory strings, `false` | True enables normal profile extensions. An array also generates `disable-extensions-except` to load the listed local directories at startup; include `'*'` to retain enabled profile extensions. False adds the two extension-disabling switches. |
 | `images` | boolean, `true` | When false, request `blink-settings: 'imagesEnabled=false'`; controls loading, not image processing. |
+| `proxy` | string or `false`, unset | A string generates `proxy-server` using native Chromium syntax; false generates `no-proxy-server`. Unset/null adds neither flag. Applies at launch, including managed extension launches. |
 | `translations` | boolean, `false` | Set translation preferences and, unless true, disable translation feature IDs. |
 | `login` | boolean, `false` | Set browser sign-in preferences and, unless true, disable sync and sign-in promotions. Does not prevent website login. |
 | `args` | object, `{}` | Raw CLI overrides applied after generated defaults; keys omit `--`. |
+| `update_preferences` | boolean, presence of an effective user-data directory | Manager-only switch for writing `Preferences` and `Local State` before launch. `false` skips both files. No files are written without a directory, including when explicitly true. |
 | `preferences` | object, `{}` | Dotted JSON preference overrides applied after generated preference defaults. |
+| `local_state` | object, `{}` | Dotted JSON overrides for `<user-data-dir>/Local State`, shared by profiles in that directory. No generated defaults. |
 | `connect_timeout_ms` | number, `15000` | Timeout for each discovery, launch-readiness or socket-opening wait; not one combined deadline. |
 | `request_timeout_ms` | number, `30000` | Default timeout for each protocol request on this browser's socket. |
 | `waitForDebuggerOnStart` | boolean, `false` | Ask Chromium to pause newly auto-attached targets. Applied to `Target.setAutoAttach` when connecting; not a CLI argument or target option. |
 | `websocket_url` | string, unset | Attach directly to a browser WebSocket endpoint. |
+| `cdp_ext` | boolean, `false` | Launch with the reverse extension under Deno or Bun. Start one shared server automatically if needed, prepare a profile-specific extension copy and wait for its connection. |
+| `reverse` | boolean, `false` | Attach to an externally launched extension instead of launching or discovering a browser. Starts the shared listener on first use under Deno or Bun. |
+| `extension_id` | string, browser name for external reverse attachment | Incoming extension ID to associate with this logical browser. Set automatically for managed `cdp_ext` launches. |
 | `http_url` | string, unset | Discover the endpoint from an HTTP(S) base URL or exact `/json/version` URL. |
 | `port` | number, unset | Discover an existing browser at `http://<host>:<port>/json/version`. |
 | `host` | string, `'127.0.0.1'` | Host used with `port`. |
@@ -240,8 +274,10 @@ arbitrary locations in `PATH`.
 
 ### Attach to an existing browser
 
-`websocket_url` takes precedence over HTTP discovery; `http_url` takes precedence
-over `host`/`port`. Use one endpoint form:
+With `reverse: true`, the manager waits for the extension and ignores attachment
+endpoints and launch options. With `cdp_ext: true`, it launches through the extension
+and ignores attachment endpoints. Otherwise, `websocket_url` takes precedence over
+HTTP discovery; `http_url` takes precedence over `host`/`port`. Use one endpoint form:
 
 ```js
 await client.call({
@@ -255,13 +291,607 @@ await client.call({
 })
 ```
 
-The existing browser must already expose CDP. Launch flags and profile
-preferences are not applied to it. `client.close()` disconnects its socket and
-leaves that browser running.
+The existing browser must already expose CDP. Launch flags, profile preferences
+and Local State overrides are not applied to it. `client.close()` disconnects its
+socket and leaves that browser running.
 
 `port: 9222` means **attach**. To **launch** on that port, use
 `args: { 'remote-debugging-port': 9222 }` without an attachment endpoint.
 
+## Proxy configuration
+
+Set `proxy` in constructor browser defaults, a per-browser `params.browser`
+object, or standalone `browser.launch` options:
+
+```js
+const client = new cdp({
+  proxy: 'http://127.0.0.1:8080',
+})
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: {
+      name: 'socks',
+      proxy: 'socks5://127.0.0.1:1080',
+    },
+    target: 'page',
+    url: 'https://example.com/',
+  },
+})
+await client.close()
+```
+
+`proxy: false` requests direct connections through `--no-proxy-server`.
+Unset/null adds no proxy flags, preserving Chrome's system/profile selection.
+Configuration is recorded on first use of a browser label and applies at launch;
+it does not change an already running or externally attached browser.
+HTTP, HTTPS and SOCKS proxy syntax passes through unchanged. Credentials embedded
+in proxy URLs are not supported by Chrome; use native authentication instead.
+The library does not add an authentication responder.
+
+Raw `args` override generated keys independently. Use them for other proxy
+controls, including bypass rules and PAC:
+
+```js
+const client = new cdp({
+  args: {
+    'proxy-server': 'http://127.0.0.1:8080',
+    'proxy-bypass-list': '*.internal.example;localhost',
+  },
+})
+// Alternatively: args: { 'proxy-pac-url': 'https://example.com/proxy.pac' }
+await client.close()
+```
+
+Native proxy rules can use semicolon-separated strings; the generic CLI converter
+still comma-joins every array. Bypass lists accept both separators. Chrome gives
+`no-proxy-server` precedence, so overriding `proxy-server` alone does not cancel
+that flag; override `args['no-proxy-server']: false` too if needed.
+Browser proxy options affect Chrome traffic, not the runtime's endpoint discovery
+or CDP transport. Chrome normally bypasses loopback addresses. To proxy them,
+use `args['proxy-bypass-list']: '<-loopback>'`; in reverse mode keep the extension's
+local WebSocket listener reachable. The library inserts no extra bypass rule.
+See [Chromium proxy configuration](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md)
+and [proxy switches](https://www.chromium.org/developers/design-documents/network-settings/).
+
+### Named contexts and different tab proxies
+
+Direct CDP supports separate proxies and storage through browser contexts.
+Configure a named context on its first target, then reference that name on other
+targets in the same browser:
+
+```js
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: 'main',
+    target: {
+      name: 'proxied-tab',
+      context: {
+        name: 'tenant-a',
+        proxy: 'http://127.0.0.1:8081',
+        create_params: {
+          proxyBypassList: '*.internal.example',
+        },
+      },
+    },
+    url: 'https://example.com/',
+  },
+})
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: 'main',
+    target: {
+      name: 'another-tab',
+      context: 'tenant-a',
+    },
+    url: 'https://example.com/another',
+  },
+})
+```
+
+| Context option | Default | Meaning |
+| --- | --- | --- |
+| `name` | required in an object | Label in this browser's public `contexts` object. A previously unused string label creates a context with native defaults. |
+| `proxy` | unset | Native context proxy override. String sets `proxyServer`; false sets `'direct://'`; unset/null uses Chrome's native selection. |
+| `create_params` | `{}` | Native `Target.createBrowserContext` parameters, overriding the generated `proxyServer`. |
+
+Configuration is recorded on first use of the context label. Context names are
+scoped to a browser; constructor options remain browser defaults. Concurrent
+targets sharing a name create one native context. There is no `target.proxy`
+option: put proxy settings on `target.context`.
+
+Contexts have private cookies/storage and do not inherit ordinary-profile website
+logins. Tabs sharing a context share its storage and proxy. Existing physical tabs
+cannot move between contexts; specifying a context for an existing target in
+another context rejects. Native proxy fields are experimental and unsupported
+browsers return normal CDP errors.
+
+The manager disposes a named context after its last application target disappears.
+It checks native targets, including unselected popups/workers, and waits for pending
+target initialization. Internal Chrome `browser_ui` targets do not retain it.
+Cleanup follows destruction events and can finish after `Target.closeTarget`
+returns. The `context_closed` event signals completion. Cleanup failures emit
+`error` with `{ browser, error }`; the context remains available for a later attempt.
+The logical record remains in `record.contexts`; its `browserContextId` becomes
+null. Reusing the name creates a fresh private context with the recorded options.
+Socket reconnection preserves a surviving native context; browser restart creates
+a new one. Context maps are in memory, not written to profile files.
+
+`client.close()` disposes managed contexts, including their tabs in externally
+attached browsers, while preserving other external tabs and unmanaged contexts.
+You can also call `Target.disposeBrowserContext` with the ID from
+`client.browsers.main.contexts['tenant-a'].browserContextId`; managed state is
+invalidated when that call succeeds. Raw native context creation remains available:
+pass its ID through `target.create_params.browserContextId` and dispose it yourself.
+Do not combine that raw ID with `target.context`. No automatic `disposeOnDetach`
+option is added. See the native
+[Target context API](https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-createBrowserContext).
+
+Named contexts reject explicitly in both reverse attachment and managed extension
+mode. Chrome's extension/debugger APIs cannot create independent browser contexts.
+Launch-time `proxy`/raw CLI flags work with `cdp_ext: true`. For changes through
+an already connected extension, the existing generic `chrome.proxy.settings`
+methods accept native `params.args`:
+
+```js
+await client.call({
+  method: 'chrome.proxy.settings.set',
+  params: {
+    browser: 'work',
+    args: [{
+      value: {
+        mode: 'fixed_servers',
+        rules: {
+          singleProxy: {
+            scheme: 'http',
+            host: '127.0.0.1',
+            port: 8080,
+          },
+        },
+      },
+      scope: 'regular',
+    }],
+  },
+})
+```
+
+The extension already declares `proxy` permission. ChromeSetting scopes apply to
+profiles/incognito, not individual tabs. `scope: 'regular'` can persist the setting
+in the profile. Use the appropriate native scope or explicitly call
+`chrome.proxy.settings.clear` with the same scope. Policy/extension conflicts are
+reported by `chrome.proxy.settings.get`. See the
+[Chrome proxy API](https://developer.chrome.com/docs/extensions/reference/api/proxy).
+
+### Incognito targets
+
+Set `target: { name: 'private', incognito: true }` to create a private target.
+The default is false. In direct mode, this selects the shared named context
+`'incognito'` unless an explicit `context` or raw `create_params.browserContextId`
+was supplied. All named CDP contexts are already private. Use different context
+names for independent private sessions or proxies.
+
+In reverse mode, this creates a native incognito tab, reusing an existing incognito
+window or opening one. Enable **Allow in incognito** for the bridge in
+`chrome://extensions` first; otherwise creation returns an explicit error.
+The manifest's `incognito: 'spanning'` setting does not grant this user permission,
+and the library never enables it automatically. Existing regular targets cannot
+be changed into incognito targets. `create_params.incognito` is the native reverse
+creation override; the high-level `incognito` flag also checks existing targets.
+
+All native Chrome incognito windows share one private session. Storage clears
+when the last incognito window closes; these are not independent named contexts.
+Reverse incognito does not add per-tab proxies. The generic `chrome.proxy` API
+can configure its native incognito scope. See
+[Chrome incognito behavior](https://support.google.com/chrome/answer/95464).
+
+## Reverse Chrome extension transport
+
+[cdp_ext/manifest.json](cdp_ext/manifest.json) and
+[cdp_ext/cdp_ext.js](cdp_ext/cdp_ext.js) form a Manifest V3 extension for Chrome
+125+. The extension connects out to one WebSocket server. The server serves all
+browser instances on the same port; each extension announces its native ID
+in its first message. No remote-debugging argument is needed.
+
+Run the server under Deno using its native
+[WebSocket upgrade](https://docs.deno.com/api/deno/websockets/) or under Bun using
+[Bun.serve](https://bun.sh/docs/runtime/http/websockets).
+Node's direct CDP mode remains supported; `listen_reverse()` under Node rejects
+with an explicit Deno/Bun requirement. There is no WebSocket framing implementation,
+third-party server dependency or additional build step.
+
+Run `deno run -A examples/reverse.mjs` or `bun examples/reverse.mjs` to launch Chrome with the extension, create
+a target and evaluate `21 * 2`. Ctrl+C closes the owned browser and server.
+The same mode is available per browser:
+
+```js
+const result = await client.call({
+  method: 'Runtime.evaluate',
+  params: {
+    browser: {
+      name: 'work',
+      cdp_ext: true,
+      headless: true,
+    },
+    target: 'demo',
+    expression: '21 * 2',
+  },
+})
+```
+
+The manager copies the two extension files into `cdp_ext/` inside the effective
+profile directory, sets the shared server URL in that copy's manifest and loads
+it before browser startup. Without an effective user-data directory, the copy
+lives under `base_path/<name>/<profile-directory>/` instead (`Default` when unset);
+Chromium still uses its system profile. Profile preferences follow the existing
+`update_preferences` rules.
+The generated launch arguments omit remote debugging and enable this extension.
+An `extensions` array also selects those directories; `extensions: true` keeps
+normally enabled profile extensions through `'*'`. Raw `args` still win and can
+prevent the bridge from loading or connecting, causing a connection timeout.
+
+For external attachment, load unpacked `cdp_ext/` through `chrome://extensions`
+or the [local-extension argument options](#local-extensions-at-startup).
+Use its ID shown in Chrome, or `browser.extension_id(directory)`, as the
+browser option `extension_id`. The logical `name` stays in the manager.
+
+The extension configuration is read from `chrome.runtime.getManifest()`:
+
+| Manifest `cdp` key | Default | Meaning |
+| --- | --- | --- |
+| `websocket_url` | `ws://127.0.0.1:9223` | The shared server endpoint. Port 9223 avoids the usual direct CDP port 9222. |
+| `reconnect_ms` | `5000` | Connection retry interval while the extension worker is awake; also the empty-message heartbeat interval while connected. Use a positive value below 30000. |
+
+The first message uses `chrome.runtime.id`, not a configured logical browser name.
+For an unpacked extension without a manifest `key`, Chromium derives this ID from
+its directory. Managed launches use a separate directory for each profile, so
+the ID is stable across reconnects and restarts, and the manager knows which
+browser it belongs to. External instances must likewise use distinct extension
+directories. Moving the directory changes the ID. The server rejects duplicate
+live IDs and announcements that differ from the WebSocket's `chrome-extension://`
+origin. This is routing information, not an authentication credential.
+
+```js
+import { browser, cdp } from './cdp.js'
+
+const client = new cdp({
+  reverse: true,
+  connect_timeout_ms: 60000,
+  reverse_server: {
+    hostname: '127.0.0.1',
+    port: 9223,
+  },
+})
+const result = await client.call({
+  method: 'Runtime.evaluate',
+  params: {
+    browser: {
+      name: 'other',
+      reverse: true,
+      extension_id: browser.extension_id('/absolute/path/to/cdp_ext'),
+    },
+    target: 'demo',
+    expression: 'document.title',
+  },
+})
+console.log(result.result.value)
+await client.close()
+```
+
+Construction and direct CDP calls do not start a listener. The first browser call
+using `reverse: true` or `cdp_ext: true` starts the shared server lazily, with the
+constructor's `reverse_server` settings. To mix direct and reverse browsers, leave the
+constructor's `reverse` default false and specify `reverse: true` in that browser's
+`params.browser` object. Constructor `port` remains a direct attachment option.
+
+The listener closes when no reverse connection, pending reverse initialization
+or live owned reverse process needs it. A live owned browser keeps it available
+through temporary disconnects. External disconnects can release it when nothing
+else needs it; the next reverse call restarts it and waits for the extension's
+retry. Direct browsers do not keep this listener alive.
+
+`client.reverse_server` is the public shared configuration object. After startup
+it contains the effective listening port, including when `port: 0` originally
+requested an available port. Restarts reuse that port so existing extensions can
+still reconnect. `client.server` contains the current native Deno `HttpServer` or Bun `Server`,
+or is unset/null while stopped. A call arriving during shutdown waits for it to
+finish before starting a replacement server.
+
+`listen_reverse(options = client.reverse_server)` remains available to start the
+listener explicitly ahead of a browser call. It returns the native runtime server;
+calling it while a server is running rejects. Explicit options replace the stored
+settings, with omitted fields taking the hostname/port defaults above.
+
+Both runtimes expose `server.addr.hostname`, `server.addr.port`,
+`server.shutdown()` and `server.finished`. On Bun, the library adds these fields:
+`shutdown()` calls native `stop()` and resolves `finished` after shutdown.
+Use `client.close()` to also close owned browsers and incoming sockets.
+Bun's callback-based server sockets receive a small EventTarget adapter with
+native send/close and live ready state. The same `jsrpc` handles both runtimes;
+registration, request IDs, pending waits, events and session routing are shared.
+Native Bun WebSocket limits still apply.
+
+Reverse calls reuse the normal target setup, custom handlers, mappings, routed
+events, request correlation, timeout and error behavior. `reverse: true` alone
+attaches externally: the manager neither launches nor updates that browser.
+`cdp_ext: true` owns the launched process and applies normal launch preferences.
+Closing the manager closes owned processes and the server, while external
+browsers and tabs remain open. The extension retries when the server returns;
+the next call rebuilds discovery and sessions, preserving surviving target IDs.
+Commands interrupted by disconnect are never replayed.
+
+A WebSocket close is not proof that Chrome exited. A managed reverse connection
+loss or connection timeout leaves its owned process alive. Subsequent calls wait
+for that extension to reconnect; they do not spawn another process. Only the
+child process's confirmed exit permits a new launch. Explicit manager `close()`
+still terminates owned browsers.
+
+The current reverse registration uses a profile-specific extension copy. It does
+not assign a new logical name to an already running Chrome using a shared extension
+directory. Unpacked `chrome.runtime.id` identifies the extension path, not the
+user-data directory or browser executable. Shared-path registration and URL-based
+bootstrap are tracked in [TODO.md](TODO.md), not implemented behavior.
+
+Chrome's [process singleton](https://github.com/chromium/chromium/blob/main/chrome/browser/process_singleton.h)
+uses the user-data directory to decide whether to forward a new launch to an
+existing instance. `no-default-browser-check` only suppresses the default-browser
+prompt. The current Chromium [notification callback](https://github.com/chromium/chromium/blob/main/chrome/browser/chrome_browser_main.cc)
+rejects forwarding when either command line enables automation or uses headless
+mode. This library generates `enable-automation` by default; a normal browser
+started with `args['enable-automation']: false` can behave differently. Do not
+infer ownership of the real browser from a short-lived forwarding process.
+
+The [service-worker lifecycle](https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle)
+allows termination while offline. A 30-second Chrome alarm wakes the worker for
+another connection attempt; the configured interval applies while it is awake.
+Connected empty-text heartbeats keep an otherwise idle WebSocket worker active.
+These are transport messages, not event buffering or polling of browser state.
+
+### Reverse protocol and supported commands
+
+The first extension-to-server message is `{ "browser": "<extension ID>" }`. Subsequent
+messages use existing CDP envelopes:
+
+- Request: `{ id, method, params, sessionId? }`.
+- Response: `{ id, result }` or `{ id, error: { code, message } }`.
+- Notification: `{ method, params, sessionId? }`.
+- Empty text: heartbeat, ignored by `jsrpc`.
+
+`jsrpc` assigns increasing request IDs per socket, shared by all its targets and
+sessions. The extension echoes each request's ID in its response; IDs internal
+to `chrome.debugger` are not exposed. Replies can arrive out of order. A timed-out
+request's late reply cannot resolve a newer request. A new socket starts a new
+ID sequence; the extension sends replies only on the connection that received
+the request, so old completions cannot enter the replacement connection.
+
+Top-level target IDs are stringified Chrome tab IDs, stable while a tab survives.
+For root commands, the envelope's `sessionId` is that tab ID: the extension sends
+to its registered `{ tabId }` debuggee without a generated UUID.
+`Target.attachToTarget` returns the same tab ID in `sessionId`, and root
+notifications use it too. This keeps the shared manager and RPC flow unchanged;
+it is a reverse routing reference, not a native root CDP session.
+
+Worker and out-of-process iframe commands still use real flattened CDP sessions.
+Their native session IDs pass through unchanged, without prefixes. The extension
+uses one `sessions` object for both roots and children: a tab ID maps to `{ tabId }`,
+and a native child session ID maps to `{ tabId, sessionId }`. Every target command
+looks up that object and passes the debuggee directly to `chrome.debugger.sendCommand`;
+there is no fallback that interprets unknown session IDs as tab IDs.
+Explicit detach takes `params.sessionId` for either a tab or child
+session. Logical target labels remain inside the manager. Reconnecting invalidates
+attachment/setup state even though a surviving root tab's routing ID stays the same.
+
+The extension adapts browser-level `Target.getTargets`, `getTargetInfo`,
+`setDiscoverTargets`, `setAutoAttach`, `createTarget`, `attachToTarget`,
+`detachFromTarget`, `closeTarget` and `activateTarget` to Chrome tab/debugger APIs.
+Discovery lists tabs; attaching a selected tab exposes its native child target
+events and flattened sessions. It does not attach every unselected tab.
+`createTarget` accepts only `url`, `background` and `incognito`; `activateTarget` selects the
+tab and focuses its window. `Browser.getVersion` returns product/user-agent data;
+its protocol version is `1.3`, with empty `revision` and `jsVersion` fields.
+Other browser-level commands return explicit unsupported-command errors.
+
+Target/session commands go through
+[chrome.debugger](https://developer.chrome.com/docs/extensions/reference/api/debugger),
+which supports a restricted set of CDP domains. Runtime, Page, Network, DOM,
+Input and Emulation are available; ServiceWorker and BackgroundService are not.
+Their default setup attempts therefore appear in `target.setup_errors`; disable
+those setup flags if desired. Chrome restrictions, policies and debugger detach
+events remain visible. Opening DevTools on an attached tab can detach this debugger.
+Firefox/Camoufox support remains planned.
+
+Browser-level `waitForDebuggerOnStart: true` returns an explicit error in reverse
+mode: the extension cannot pause newly created root tabs before attachment.
+Keep its default false and create `about:blank`, finish setup, then navigate.
+Normal target-side `Target.setAutoAttach` is still native pass-through for children.
+
+### Chrome extension API commands
+
+In reverse mode, `chrome.<namespace>.<method>` calls the corresponding Chrome
+extension method directly, including nested objects such as
+`chrome.storage.session.get` and `chrome.privacy.websites.referrersEnabled.get`.
+There is no method registry or CDP-name translation. A name such as
+`Runtime.evaluate` still uses `chrome.debugger`; a name such as
+`chrome.debugger.getTargets` calls the extension API with its native signature.
+The same connection, request IDs, timeouts and RPC error envelopes handle both.
+These names are extension-only; direct CDP connections do not implement them.
+
+| Parameter | Meaning |
+| --- | --- |
+| `browser` | Usual manager browser label/configuration. |
+| `args` | Positional native arguments as a JSON array; defaults to `[]`. One object argument is `[object]`; two arguments are `[first, second]`. |
+| `callback` | Default `false`: await a native Promise or return a synchronous result. Set `true` for callback APIs: append a callback, await its first result and reject on `chrome.runtime.lastError`. |
+| `target` | Optional manager target selection/setup. It does not supply a native tab ID to the extension API. Put native `target` objects inside `args`. |
+
+```js
+const tabs = await client.call({
+  method: 'chrome.tabs.query',
+  params: {
+    browser: 'work',
+    args: [{}],
+  },
+})
+await client.call({
+  method: 'chrome.scripting.insertCSS',
+  params: {
+    browser: 'work',
+    args: [{
+      target: {
+        tabId: tabs[0].id,
+      },
+      css: 'body { background: white; }',
+    }],
+  },
+})
+await client.call({
+  method: 'chrome.storage.session.set',
+  params: {
+    browser: 'work',
+    args: [{
+      example: true,
+    }],
+  },
+})
+```
+
+Native arrays, objects, strings, booleans, numbers and `null` are returned directly;
+only `undefined` becomes `{}`. The method is called on its owning object, so nested
+API objects retain their native receiver. Arguments and results must be JSON data.
+Callbacks can only be supplied through `callback: true`; functions, event listeners,
+Ports, Blobs and other live/non-JSON objects have no remote representation.
+The bridge forwards the network notifications documented below. It does not
+provide generic remote registration of other extension event listeners.
+
+`chrome.scripting.executeScript` supports `files` relative to the loaded extension
+directory and returns the native array of frame results. The bridge also accepts
+`func` as a function-expression string, including arrow and async functions:
+
+```js
+const frames = await client.call({
+  method: 'chrome.scripting.executeScript',
+  params: {
+    browser: 'work',
+    args: [{
+      target: {
+        tabId,
+      },
+      world: 'MAIN',
+      func: '(first, second) => first + second',
+      args: [19, 23],
+    }],
+  },
+})
+console.log(frames[0].result) // 42
+```
+
+Only string-valued `func` is adapted: a fixed native function evaluates that source
+inside the destination world, then calls it with the supplied injection `args`.
+The worker does not evaluate incoming source. Other injection fields remain native;
+Chrome awaits returned Promises and returns its frame-result array. A bare body
+such as `return 42` is not a function expression. To execute arbitrary script text,
+use `func: 'code => (0, eval)(code)'` and `args: [code]`; the last expression or
+resolved Promise supplies the result. Both paths have access to the destination DOM.
+
+The native world default remains `ISOLATED`, whose content-script CSP blocks `eval`
+and `new Function`. Select `MAIN` explicitly for string functions; the page's CSP
+must allow string evaluation there. Both evaluators require the same `unsafe-eval`
+permission, so switching between them does not bypass CSP. Native execution errors
+may leave a frame result without `result`; consult the tab console as well. See
+[content-script CSP](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#content_security_policy).
+
+CSP changes are explicit calls, never automatic. Two existing API paths are:
+
+- With a debugger attachment, call `Page.setBypassCSP` with `enabled: true` on the
+  selected target **before navigation or reload**, then inject into `MAIN`.
+  Set `enabled: false` and reload to restore normal enforcement. This native CDP
+  method works through the reverse extension too; `Runtime.evaluate` already
+  accepts script text through the same debugger connection.
+- Without a debugger, call `chrome.declarativeNetRequest.updateSessionRules` with a
+  `modifyHeaders` rule removing the `content-security-policy` response header.
+  Scope its `condition.tabIds` to the intended tab and its `resourceTypes` to
+  `main_frame` (include `sub_frame` for iframe navigations), then reload the tab.
+  Remove the rule through `removeRuleIds` when finished and reload again. Session
+  rules expire on browser shutdown. Header removal does not remove a CSP supplied
+  by HTML `<meta>`; the policy already applied to a loaded document also remains
+  until navigation. CSP affects the page's scripts as well as the injection.
+
+See [Page.setBypassCSP](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-setBypassCSP)
+and [declarative request rules](https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest).
+Tested on Chrome 154: both explicit paths allow `MAIN` string evaluation and DOM
+access on a page served with `script-src 'none'`.
+
+These operations are observable. Page JavaScript can probe `eval` or `new Function`
+and compare the outcome with its intended CSP. Code in `MAIN` shares the page's
+globals, including any replacements of those functions. There is no standard page
+API reporting which extension attached a debugger, but inspector operations can
+have observable effects; attachment is not guaranteed to be invisible. V8 explicitly
+treats prevention of [inspector detection](https://chromium.googlesource.com/v8/v8/+/c195efb1d03b5171c376a02bca885c68792ae0f7/src/inspector/SECURITY.md)
+as a non-goal. A current behavioral probe does not provide a reliable history of
+every past attachment or identify the caller by itself.
+
+For native script-text injection without changing the page's CSP,
+`chrome.userScripts.execute` (Chrome 135+) accepts `js[].code`. Its default
+`USER_SCRIPT` world shares the DOM but has separate JavaScript globals and is exempt
+from the page's CSP. `MAIN` instead shares the page's globals and CSP.
+
+```js
+const frames = await client.call({
+  method: 'chrome.userScripts.execute',
+  params: {
+    browser: 'work',
+    args: [{
+      target: {
+        tabId,
+      },
+      js: [{
+        code: 'document.querySelector("h1").dataset.injected = "yes"; Promise.resolve(42)',
+      }],
+    }],
+  },
+})
+console.log(frames[0].result) // 42
+```
+
+The manifest includes the permission, but Chrome also requires explicit user
+activation: Developer mode before Chrome 138, or **Allow User Scripts** on the
+extension's details page from Chrome 138 onward. Open
+`chrome://extensions/?id=<extension_id>` using `client.browsers.work.extension_id`.
+If necessary, reload the extension after enabling the toggle. Neither `cdp_ext: true`
+nor `extensions` enables it or adds a default profile setting. A previously enabled
+profile retains its choice. Chrome stores the extension-specific
+`extensions.settings.<extension_id>.user_scripts_enabled` setting; on Windows it
+is in protected `Secure Preferences`, and simply writing the key into a fresh
+profile did not enable access in our test. Use Chrome's toggle rather than assuming
+a normal `preferences` entry can update protected extension settings.
+See the native [userScripts API and activation steps](https://developer.chrome.com/docs/extensions/reference/api/userScripts).
+
+Chrome's native `scripting.executeScript` still rejects strings supplied directly
+as `func`; the bridge's fixed function makes this adaptation possible. Overriding
+an actual function's `toString`, `Symbol.toPrimitive` or `Function.prototype.toString`
+does not replace the source Chrome serializes. Tests on Chrome 154 confirmed that
+these overrides were never called and the original function executed.
+
+The manifest grants `<all_urls>` host access and broad desktop extension API
+permissions for scripting/debugging, tabs/groups/sessions, bookmarks/history/reading
+list/search, cookies/content settings, storage, downloads, management, privacy/proxy,
+accessibility/font settings, alarms/idle/power, system information, notifications,
+context menus, capture, clipboard/geolocation access, identity, native messaging,
+messaging through GCM, offscreen documents, side panels, speech/engines,
+navigation/network requests and declarative rules.
+Its `action` declaration also enables `chrome.action` methods. The exact permission
+list is in [cdp_ext/manifest.json](cdp_ext/manifest.json); managed launches copy it.
+There are no per-method permission prompts added by the bridge.
+
+Permissions do not bypass Chrome's native restrictions: platform-specific,
+enterprise-only and channel-specific APIs are not enabled by this manifest, and
+Manifest V3's policy-only `webRequestBlocking` is not requested. User gestures,
+incognito/file-access grants, capture dialogs, native messaging host installations
+and required extension resources still apply. Unavailable methods and native errors
+reject normally. See the official [extension API reference](https://developer.chrome.com/docs/extensions/reference/api),
+[permission list](https://developer.chrome.com/docs/extensions/reference/permissions-list)
+and [scripting API](https://developer.chrome.com/docs/extensions/reference/api/scripting).
+
 ## Command-line arguments
 
 The library exposes a JavaScript API, not a command-line program. `args` refers
@@ -351,9 +981,12 @@ and [content switches](https://raw.githubusercontent.com/chromium/chromium/main/
 | `disable-features` | array below | Disable named Chromium features. |
 | `headless` | `'new'` when `headless` is true | Run without a visible browser window. |
 | `window-size` | `'1440,900'` when headless | Set initial window dimensions. |
-| `disable-extensions` | `true` unless `extensions` is true | Disable browser extensions. |
+| `disable-extensions` | `true` unless `extensions` is true or an array | Disable browser extensions. |
 | `disable-component-extensions-with-background-pages` | same condition | Disable those component extensions. |
+| `disable-extensions-except` | the `extensions` array, otherwise unset | Load local directories and exclude other normal extensions. Raw overrides win. |
 | `blink-settings` | `'imagesEnabled=false'` when `images` is false | Disable image loading through Blink settings. |
+| `proxy-server` | `proxy` when it is a string | Configure the launched browser's proxy using native Chromium syntax. |
+| `no-proxy-server` | `true` when `proxy` is false | Request direct connections; Chrome gives this flag precedence over other proxy flags. |
 | `disable-signin-promo-on-avatar-pill-for-testing` | `true` unless `login` is true | Suppress the avatar sign-in promotion. |
 | `disable-sync` | same condition | Disable browser sync. |
 
@@ -395,12 +1028,74 @@ These are native Chromium feature identifiers, not additional library options.
 Unless `translations` is true, the library appends `Translate`, `TranslateToast`
 and `EnableTranslatePdf`. Unless `login` is true, it appends
 `DiceWebSigninInterception` and `SigninPromoOnAvatarPill`. A raw
-`args['disable-features']` replaces that entire generated array.
+`args['disable-features']` replaces that generated array; an active
+`disable-extensions-except` then appends its required feature ID as described below.
+
+## Local extensions at startup
+
+These conventions operate before Chromium starts, without CDP installation calls
+or manual extension registration in preference files:
+
+1. An `extensions` array generates `disable-extensions-except` and omits the two
+   normal extension-disabling defaults. `extensions: true` alone keeps normal
+   profile loading without generating an exception list.
+2. Raw `args` override generated switches. A final non-null/non-false
+   `disable-extensions-except` automatically appends
+   `DisableDisableExtensionsExceptCommandLineSwitch` to `disable-features`, once.
+   Raw feature arrays or comma-separated strings retain their entries.
+3. At launch, an exact `'*'` entry expands to enabled extension paths from the
+   effective profile; duplicate paths are removed. Explicit paths remain selected.
+
+```js
+const client = new cdp({
+  extensions: [
+    '*',
+    '/absolute/path/to/local-extension',
+  ],
+})
+```
+
+The equivalent raw selection is `args['disable-extensions-except']` containing
+that array or a comma-separated string. It works independently of `extensions`;
+other raw switches remain effective. A null/false selector suppresses the generated
+exception list and its automatic feature addition. An empty array selects no
+normal extensions. Arrays passed by the caller are not mutated.
+
+`browser.build_args` leaves `'*'` unexpanded. `browser.launch` reads
+`<user-data-dir>/<profile-directory or Default>/Preferences` and `Secure Preferences`
+before spawning, using the final raw directory arguments. Secure records take
+precedence for duplicate IDs. `browser.profile_extension_paths(args)` returns a
+plain object keyed by extension ID, containing both enabled and disabled records
+as `{ path, enabled }`. Paths refer to the current recorded version, including
+absolute unpacked paths. Disable reasons and legacy disabled state set
+`enabled: false`; internal component extensions and records without a path are
+omitted. Wildcard expansion takes only the entries with `enabled: true`, without
+scanning obsolete versions or activating disabled extensions. Missing files contribute no
+entries; malformed JSON and other read errors reject launch. `'*'` requires an
+explicit effective user-data directory; the system directory is not inferred.
+`update_preferences: false` does not disable this read-only expansion.
+
+```js
+const extensions = await browser.profile_extension_paths({
+  'user-data-dir': '/absolute/path/to/profile-root',
+  'profile-directory': 'Default',
+})
+// extensions[extensionId] contains { path, enabled }.
+const disabled = Object.entries(extensions).filter(([, extension]) => !extension.enabled)
+```
+
+Explicit directories must contain unpacked extensions with `manifest.json`.
+The native argument excludes other normal extensions, so include `'*'` when
+preserving enabled profile extensions. Chromium still decides whether an extension
+can load. The feature override was verified on Chrome 154; it depends on Chrome
+retaining that internal switch, rather than a stable extension-installation API.
+See [Chromium's startup loader](https://github.com/chromium/chromium/blob/main/chrome/browser/extensions/extension_service.cc).
 
 ## Profile preferences
 
-Local launch edits the profile's JSON `Preferences` file before spawning
-Chromium. The effective path is:
+The `cdp` manager edits the profile's JSON `Preferences` file before spawning
+Chromium when the effective `user-data-dir` argument specifies a directory and
+`update_preferences` is not false. The path is:
 
 ```text
 <args['user-data-dir']>/<args['profile-directory'] or Default>/Preferences
@@ -417,6 +1112,10 @@ preference defaults are:
 
 `options.preferences` overwrites these defaults by key. Preferences and switches
 are separate layers; overriding one does not remove the other.
+`update_preferences: false` skips generated and raw preference writes, including
+`local_state`. It does not change generated CLI arguments. The default follows
+the effective directory, including raw overrides; the manager's generated named
+directory counts as a configured directory.
 
 ```js
 await client.call({
@@ -454,6 +1153,49 @@ supplied object. `null` is stored as JSON null. Malformed JSON, incompatible
 existing path values and filesystem errors propagate. It does not coordinate
 writes with a running browser, which may overwrite the file itself.
 
+### Local State and the remote-debugging checkbox
+
+Chrome stores settings shared by profiles in the same user-data directory in
+`<user-data-dir>/Local State`, outside `Default` or `Profile 1`. `local_state`
+instructs the `cdp` manager to update this file before launch using the same
+`browser.update_profile_preferences` helper and preservation rules.
+The effective raw `args['user-data-dir']` override
+selects its location; `profile-directory` does not affect it.
+
+For Chrome's `chrome://inspect/#remote-debugging` checkbox:
+
+```js
+const client = new cdp({
+  local_state: {
+    'devtools.remote_debugging.user-enabled': true,
+  },
+})
+```
+
+Set the key to `false` to disable it. The helper can also edit this file directly,
+before starting Chrome:
+
+```js
+await browser.update_profile_preferences('/absolute/user-data-dir/Local State', {
+  'devtools.remote_debugging.user-enabled': true,
+})
+```
+
+This is the user-enabled setting, distinct from the administrator policy
+`devtools.remote_debugging.allowed`. Chrome's native mode requires approval for
+incoming connections; setting the preference does not remove that prompt.
+The library's normal launch still uses `--remote-debugging-port`, which takes
+precedence over this mode. See the [Chromium implementation](https://github.com/chromium/chromium/blob/main/chrome/browser/devtools/remote_debugging_server.cc).
+
+`user_data_dir: null`, or a raw `args['user-data-dir']: null`/`false`, omits the
+directory switch. Direct `browser.launch` also omits it when no directory is
+provided. The manager skips both `preferences` and `local_state` writes in that
+case; it does not discover or edit the system directory. Chrome 136+ ignores
+the debugging-port switch for its system directory, so omitting the directory
+does not provide a working CDP connection through the normal launcher.
+Attach using an existing endpoint when using Chrome's native approval mode.
+See [Chrome's debugging-port restrictions](https://developer.chrome.com/blog/remote-debugging-port).
+
 ## Overlaps and override examples
 
 | Settings | Effective library behavior |
@@ -464,10 +1206,15 @@ writes with a running browser, which may overwrite the file itself.
 | Explicit `windowsHide: true` or `false` | Pass that value to Node's `spawn`, regardless of headless mode. |
 | `extensions: true` plus `args['disable-extensions']: true` | The raw extension-disabling switch still wins. |
 | `extensions: false` plus only `args['disable-extensions']: false` | Remove that flag, but retain `disable-component-extensions-with-background-pages`. Use `extensions: true` to omit both generated flags. |
+| `extensions: ['*', directory]` | Select enabled profile extensions plus the explicit local directory before startup. |
+| An `extensions` array plus a raw `disable-extensions-except` | The raw selection replaces the generated array; null/false suppresses that selection. |
 | `images: false` plus an overridden `blink-settings` | Replace the whole string; image disabling is not appended to the caller's value. |
+| A string `proxy` plus `args['proxy-server']` | The raw proxy-server value replaces the generated one. |
+| `proxy: false` plus only `args['proxy-server']` | Retain `no-proxy-server`; Chrome still selects direct connections. Override `args['no-proxy-server']: false` to remove it. |
+| `proxy` plus an attachment endpoint | The launch option is unused; no running browser proxy is changed. |
 | `translations: false` plus `preferences['translate.enabled']: true` | Store true in the profile, while generated translation-disabling feature IDs remain on the CLI. |
 | `login: true` plus `args['disable-sync']: true` | Allow profile sign-in through generated preferences while still requesting sync to be disabled. |
-| Any high-level settings plus a raw `disable-features` array | Replace the whole generated list, including translation/sign-in additions. |
+| Any high-level settings plus a raw `disable-features` array | Replace the generated list, including translation/sign-in additions; an active `disable-extensions-except` still appends its required feature ID. |
 | `user_data_dir` plus `args['user-data-dir']` | The raw argument determines both the profile write location and the launched browser directory. |
 | `port` plus `args['remote-debugging-port']` | Attach using `port`; no launch occurs, so the raw launch argument is unused. |
 | Constructor options plus an existing browser label | Reuse the stored record; configuration is not merged again on every call. |
@@ -524,6 +1271,8 @@ await client.call({
 | --- | --- | --- |
 | `name` | required in an object | Logical label in this browser's `targets` mapping. |
 | `targetId` | `null` | Optional existing physical target ID. Reused if discovered; otherwise create a new target. |
+| `context` | unset | Direct-mode context name or first-use configuration object; see named contexts above. Reverse mode rejects this option. |
+| `incognito` | `false` | Create/select a private target; direct mode uses the shared `'incognito'` context by default, reverse uses a native incognito window with the user's extension grant. |
 | `create_params` | `{}` | Native creation overrides, merged over `url: 'about:blank'` and `background: true`; start from a blank target without requesting foreground activation. |
 | `initialize` | `true` | Run the convenience setup sequence; false skips it. |
 | `runtime` | `'bootstrap'` | Enable Runtime for setup, then disable reporting. `true` leaves it enabled; `false` skips both operations. |
@@ -696,6 +1445,46 @@ browser/target resolution, may be synchronous or asynchronous, and define their
 own return value. Their exceptions propagate. An unregistered `_.` name rejects
 without launching a browser.
 
+## Reverse network notifications
+
+Reverse mode exposes two independent streams through the same JSON-RPC connection:
+
+| Stream | Debugger required | Data |
+| --- | --- | --- |
+| `Network.*` | Yes | Native CDP events after `Network.enable`, normally enabled by target setup. Native commands can retrieve response bodies where supported. |
+| `chrome.webRequest.*` | No | Native extension request lifecycle details for accessible tabs, including request/response headers. No response bodies or WebSocket frames. |
+
+The extension always forwards `onBeforeRequest`, `onBeforeSendHeaders`,
+`onSendHeaders`, `onHeadersReceived`, `onAuthRequired`, `onResponseStarted`,
+`onBeforeRedirect`, `onCompleted` and `onErrorOccurred` under the
+`chrome.webRequest.` prefix while connected. `network: false` skips debugger
+Network setup but does not disable this extension stream. No debugger attachment
+is required to observe a tab created/navigated through `chrome.tabs` calls.
+
+```js
+client.addEventListener('chrome.webRequest.onCompleted', event => {
+  const { browser, target, tabId, requestId, url, statusCode } = event.detail
+  console.log(browser, target, tabId, requestId, url, statusCode)
+})
+```
+
+Raw notifications have `{ method, params, sessionId }` and no request `id`.
+`params` contains native Chrome details. When `tabId >= 0`, `sessionId` is its
+string form, allowing normal manager routing even without a debugger session.
+Requests with `tabId: -1` have no target routing reference. Browser labels are
+added by the manager; target labels are added only for known logical targets.
+`requestId` belongs to the extension API and is not a CDP Network request ID.
+Raw socket notifications remain unchanged.
+
+The manifest includes `webRequest`, `webRequestAuthProvider` and `<all_urls>`.
+`onAuthRequired` is observation only: no authentication response is supplied.
+Incognito traffic requires the bridge's **Allow in incognito** grant. Chrome
+restrictions, cached requests and protected URLs can limit visibility. Sensitive
+headers and some preflights require native `extraHeaders`, which this stream does
+not request. There is no library filtering, buffering, replay, interception or
+generic remote event registration; disconnected notifications are dropped.
+See the [Chrome webRequest API](https://developer.chrome.com/docs/extensions/reference/api/webRequest).
+
 ## Events and bindings
 
 | Emitter / event | `event.detail` |
@@ -703,6 +1492,9 @@ without launching a browser.
 | `client`, `notify` | CDP message with browser and, when known, target labels added to `params`. |
 | `client`, native method such as `Runtime.bindingCalled` | That message's routed parameters. |
 | `client`, `close` | `{ browser, code }` for closure of the current browser socket. |
+| `client`, `context_closed` | `{ browser, context, browserContextId }` after successful managed context disposal. |
+| `client`, `error` | `{ browser, error }` when asynchronous managed context cleanup fails. |
+| `client`, `chrome.webRequest.*` | Native extension request details with browser and, when known, target labels. Reverse only; does not require debugger attachment. |
 | `socket`, `notify` | The unmodified CDP notification from the raw transport. |
 
 Labels are strings, not record objects. Native `sessionId` remains available on
@@ -748,13 +1540,20 @@ dictionary containers have a null prototype.
 | Path | Contents |
 | --- | --- |
 | `client.base_path` | Resolved profile root. |
-| `client.options` | Constructor browser defaults, excluding `base_path`. |
+| `client.options` | Constructor browser defaults, excluding `base_path` and `reverse_server`. |
+| `client.reverse_server` | Shared listener configuration; the effective hostname/port are stored after startup. |
 | `client.custom_methods[name]` | Handler function. |
 | `client.browsers[name]` | Browser configuration fields plus live state. |
+| `client.reverse_sockets[extension_id]` | Announced incoming socket, available even before the first call; native on Deno, an EventTarget adapter on Bun. |
+| `record.extension_id`, `record.extension_path` | Expected extension identity and the managed copy's canonical directory. |
+| `client.server` | Current native Deno/Bun reverse server with shared lifecycle fields, or unset/null when not listening. |
+| `client.server_closing` | Shutdown promise while the reverse listener is stopping, otherwise unset/null. |
 | `record.socket` | Current `jsrpc` connection once created. |
 | `record.proc` | Owned child process; absent for external attachment. |
 | `record.connecting` | In-progress connection promise, cleared after settlement. |
 | `record.targets[label]` | Target options, physical `targetId`, `sessionId`, `connecting` and `setup_errors` after setup. |
+| `record.contexts[name]` | Recorded context options, native `browserContextId` or null, and pending `connecting`/`closing` promises. Direct mode only. |
+| `record.context_checking` | Pending automatic empty-context cleanup, otherwise unset/null. |
 | `record.target_info[targetId]` | Discovered native target info plus cached `sessionId` when attached. |
 | `record.session_targets[sessionId]` | Physical `targetId` for a session. |
 | `socket.pending[id]` | Response-wait promise, removed on completion. |
@@ -800,15 +1599,29 @@ try {
 }
 ```
 
-`browser.launch` requires a usable absolute directory through `user_data_dir` or
-`args['user-data-dir']`; this helper does not resolve that path for you. It writes
-preferences, starts the process, reads the
-DevTools WebSocket URL from stderr and returns `{ proc, url }`. It does not open
-a CDP connection. Readiness timeout or launch failure rejects and attempts to
+`browser.launch` builds arguments, starts the process, reads the
+DevTools WebSocket URL from stderr and returns `{ proc, url }`. With `cdp_ext: true`,
+it waits for process spawn instead and returns `url: undefined`; the caller must
+prepare the extension and supply its directory as `extension_path`.
+It does not open a CDP connection or write preference files; `update_preferences`, `preferences`
+and `local_state` are manager options, ignored by this helper.
+To prepare files independently, call
+`browser.update_profile_preferences` explicitly before launch. The helper does
+not resolve `user_data_dir` or `args['user-data-dir']`; explicit paths should be
+absolute. Omitting the directory lets Chromium select its system directory,
+subject to the debugging-port restrictions described above.
+Readiness timeout or launch failure rejects and attempts to
 terminate the spawned process.
 
-`jsrpc` takes a WebSocket URL and an options object whose recognized option is
+`jsrpc` takes a WebSocket URL or an accepted EventTarget socket and an options
+object whose recognized option is
 `request_timeout_ms` (default `30000`). Wait for the socket to open before `req`.
+For an accepted socket, it returns that same object with RPC fields/methods.
+The object supplies `send`, `close`, live `readyState` and normal message/close/error
+events. Deno sockets remain native WebSockets; Bun uses the adapter described
+above. Accepted sockets need not be instances of the `jsrpc` subclass.
+The reverse server consumes the initial browser announcement before equipping
+the socket with RPC behavior. Empty-text heartbeats are ignored.
 The request is a raw envelope: `method`, optional `params`, and optional top-level
 `sessionId`. `req` assigns its own incrementing ID even if the input contains one.
 Its second argument overrides the timeout for that request. There are no browser
@@ -826,6 +1639,9 @@ labels, target labels, custom methods or reconnection policy in this layer.
 | Unknown `_.` handler | Reject before browser creation. |
 | Invalid profile JSON or filesystem failure | Propagate the parsing/filesystem error. |
 | Failed discovery or local launch | Reject the call establishing the connection. |
+| Named context in reverse mode | Reject explicitly; no separate process emulation. |
+| Reverse incognito without the extension's user grant | Reject with an instruction to enable Allow in incognito. |
+| Automatic context cleanup fails | Emit the manager's `error` event with browser label and original error. |
 
 ```js
 try {
@@ -845,6 +1661,7 @@ try {
 
 Contributors and coding agents should read [AGENTS.md](AGENTS.md) and
 [DEV_PREF.md](DEV_PREF.md). The maintained implementation is [cdp.js](cdp.js).
+Planned work is tracked in [TODO.md](TODO.md).
 `extra/`, when present locally, holds ignored reference files and is not part of
 the tracked source or runtime dependencies.
 
@@ -853,14 +1670,41 @@ workflow for detecting new conversations and extracting connector session handle
 from tool-call history. It is a caller-side recipe, not additional library API.
 
 For npm packaging, account setup, and GitHub publishing, see
-[Publishing](npm/PUBLISHING.md). Publishing only copies `cdp.js` and this README
-into `npm/` alongside its manifest; no build script is needed.
+[Publishing](npm/PUBLISHING.md). Publishing copies `cdp.js`, this README and the
+two `cdp_ext/` files into `npm/` alongside its manifest; no build script is needed.
 
 ```sh
 node --check cdp.js
+node --check cdp_ext/cdp_ext.js
 node --test tests/cdp.test.js
+deno test -A tests/reverse.test.js
+bun test tests/cdp.test.js tests/reverse.test.js --timeout 60000
 ```
 
 Integration tests launch local headless Chromium with disposable profiles under
 `build/tests/`. Set `CDP_BROWSER` if discovery does not match the machine. Direct
 library use needs no build or package installation; npm packaging is optional.
+The shared Deno/Bun reverse suite loads the real extension into two headless Chrome instances on one
+server port without remote-debugging arguments. It checks native/custom calls,
+Network events, webRequest notifications without debugger attachment, bindings,
+child sessions, reconnect, detach/recreate, incognito and isolation.
+Node coverage also checks actual browser/context proxy routing, shared private
+storage, concurrent context creation, automatic disposal, unselected targets and
+context ownership in externally attached browsers.
+Extension API coverage checks granted permissions, positional arguments, nested
+API receivers, synchronous/Promise/callback results, CSS/script injection, storage,
+native validation errors and false/null/undefined results. Function-injection checks
+cover native string rejection, ignored custom string conversions, the bridge's
+string-function adapter and async arguments/results. Real page CSP checks cover
+both evaluators in both worlds, explicit debugger bypass after reload, and explicit
+header removal through session rules. User-script checks cover default denied
+access and explicit activation, DOM changes and Promise results under restrictive
+page CSP. Only disposable-profile preparation uses direct CDP to operate Chrome's
+Allow User Scripts and Allow in incognito toggles; subsequent reverse execution
+uses no remote-debugging flags and never enables these grants automatically.
+Managed-launch coverage checks concurrent first use, profile-specific identity,
+connection timeout without process replacement, lazy listener startup/shutdown
+independent of direct browsers, and relaunch after confirmed exit. External reverse
+timeouts release the listening port; other live reverse connections retain it.
+The npm tarball contains `package.json`, `cdp.js`, `README.md` and the two extension
+files required by managed reverse launches.