@mefistofelix/cdp.js 0.6.0 → 0.8.0

package/README.md

@@ -43,6 +43,8 @@ In Bun, use `bun add @mefistofelix/cdp.js` and the ordinary package import above
   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.
+- Reverse target management and XPath helpers default to browser APIs, with
+  optional debugger execution; explicit native CDP commands still execute.
 - 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.
@@ -119,7 +121,7 @@ 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.evaluate_xpath(params, fn, options)` | Execute a serialized function with a normalized XPath. Direct/debugger mode returns native `Runtime.evaluate` data; reverse API mode returns `{ result: { type, value } }`. |
 | `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. |
@@ -244,6 +246,7 @@ local configuration.
 | `websocket_url` | string, unset | Attach directly to a browser WebSocket endpoint. |
 | `cdp_ext` | boolean, `false` | Use the extension transport under Deno/Bun: start the shared reverse listener and open a local bootstrap URL containing the logical browser name and WebSocket endpoint. No extension ID is required. |
 | `cdp_ext_install` | boolean, presence of an effective user-data directory | Prepare an extension copy and startup loading arguments. Defaults on for an explicit custom directory, off for the system profile. `false` uses an already installed extension. Only applies with `cdp_ext: true`. |
+| `cdp_ext_user_scripts` | boolean, `cdp_ext_install` plus an effective custom directory | Automatically enable Allow User Scripts for the managed bridge. False preserves the current grant. True requires installation and a custom directory; system/passive browsers use manual consent. See activation below. |
 | `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 passive `reverse: true` attachment | Optional legacy incoming extension identity. Not needed with `cdp_ext: true`; observed automatically from the connection. |
 | `http_url` | string, unset | Discover the endpoint from an HTTP(S) base URL or exact `/json/version` URL. |
@@ -529,6 +532,19 @@ the local URL and connects to the waiting manager. The user enters no extension
 ID or WebSocket address. Load the package's `cdp_ext/` once through
 `chrome://extensions` (developer mode, Load unpacked); reload it after upgrading.
 
+After accepting a trigger, the extension records `cdp_ext.trigger` in its debug
+sidebar and closes that trigger tab automatically, including when the server is
+currently offline. If it is Chrome's only tab, it becomes the extension's
+**CDP.js connection** page instead, keeping Chrome available for subsequent calls.
+This reuses the debug view and displays the logical browser and live connected/
+waiting status; it never claims a connection before one exists. No extra
+tab is created. Other loopback pages are preserved: only the exact `/cdp_ext`
+route with non-empty `browser`, `websocket_url` and `token` parameters and a
+same-host/port `ws:` endpoint is accepted. The tab URL is checked again before
+cleanup, so a tab already navigated elsewhere is left alone. Duplicate tab updates
+reuse the trigger's diagnostic entry. A conflicting live browser binding is
+reported and its trigger page is cleaned up without replacing the connection.
+
 ```js
 const client = new cdp({
   cdp_ext: true,
@@ -648,8 +664,9 @@ 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
+Reverse calls share target selection, custom handlers, mappings, routed events,
+request correlation, timeout and error behavior. Implicit CDP setup is opt-in
+through `target.execution_mode: 'debugger'`. `reverse: true` alone
 attaches externally: the manager neither launches nor updates that browser.
 `cdp_ext_install: true` owns the launched process and applies normal launch preferences.
 With installation off, Chrome is external and remains open on manager close.
@@ -688,15 +705,27 @@ network diagnostic if the server disappears between the HTTP check and upgrade.
 ### Debug sidebar
 
 Click the extension's toolbar icon to open its native Chrome side panel.
+If the icon is hidden, open Chrome's Extensions menu (the puzzle piece), find
+**CDP reverse connection**, and pin it or click its entry. The panel opens on a
+user action; loading the extension or connecting a browser does not open it.
+After updating the package, an already running Chrome still has its previously
+loaded extension: reload it in `chrome://extensions` after updating its directory,
+or restart that custom-profile browser through a fresh manager. For a manually
+installed extension, update its installed files too. Reopening an old side panel
+alone does not upgrade the worker.
+
 It shows the current connection status, logical browser name, WebSocket endpoint,
-native extension ID and number of attached root/child sessions. It works before
+native extension ID, number of routing sessions and number of debugger-attached
+root tabs. A routing session does not imply debugger attachment. It works before
 the first trigger too, displaying **Waiting for trigger** without starting a
 server connection.
 
-The most recent 50 incoming commands appear newest first, with request ID,
-method, optional session ID, running/done/error status, elapsed milliseconds and
+The most recent 50 commands and trigger entries appear newest first, with request ID,
+method, optional session ID/execution mode, running/done/error status, elapsed milliseconds and
 error text. This is command metadata only: parameters, results and the trigger
-token are not included. Empty heartbeat messages and CDP events are not logged.
+token are not included. Trigger entries show the tab ID, browser label, endpoint
+and cleanup action; the full trigger URL is never recorded. Empty heartbeat
+messages and CDP events are not logged.
 **Clear** empties this history without cancelling commands or changing the
 connection. Reopening the panel retrieves the current snapshot; a worker restart
 or extension reload clears the history. No debug history is written to storage.
@@ -736,8 +765,10 @@ 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.
+looks up that object. API-mode root selection only registers the routing reference;
+an explicit session CDP command attaches its root lazily, sharing concurrent
+attachment, then calls `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.
@@ -752,12 +783,13 @@ 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
+Explicit native target/session CDP 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
+Their setup attempts in debugger target mode therefore appear in
+`target.setup_errors`; disable those setup flags if desired. API targets skip
+that setup. Chrome restrictions, policies and debugger detach
 events remain visible. Opening DevTools on an attached tab can detach this debugger.
 Firefox/Camoufox support remains planned.
 
@@ -893,7 +925,8 @@ 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.
+from the page's CSP. `MAIN` shares the page's globals; source injection and later
+calls to eval/new Function have different CSP behavior, explained below.
 
 ```js
 const frames = await client.call({
@@ -913,18 +946,102 @@ const frames = await client.call({
 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).
+### Arbitrary client code in MAIN, without debugger
+
+`chrome.userScripts.execute` also accepts `world: 'MAIN'`. With user-script access
+enabled, Chrome compiles the supplied `js[].code` directly in the page's JavaScript
+world. The source can arrive from the JSON-RPC client at runtime. It can read/write
+page globals and the DOM, including on a page with `script-src 'none'`, without
+debugger attachment or changing the page's CSP:
+
+```js
+const frames = await client.call({
+  method: 'chrome.userScripts.execute',
+  params: {
+    browser: 'work',
+    args: [{
+      target: { tabId },
+      world: 'MAIN',
+      js: [{
+        code: 'window.clientValue = 42; document.querySelector("h1").dataset.source = "client"; Promise.resolve(window.clientValue)',
+      }],
+    }],
+  },
+})
+console.log(frames[0].result) // 42
+```
+
+This is native source injection, not a call to `eval`. If the injected source
+itself calls `eval` or `new Function` in MAIN, those operations still obey the
+page's CSP and can remain blocked. The Allow User Scripts toggle enables this
+API; it does not globally enable string evaluation in MAIN, the worker, or normal
+`chrome.scripting.executeScript` calls. No additional RPC method is needed.
+
+In `USER_SCRIPT`, the DOM is shared but page JavaScript globals are separate.
+That world's own CSP can permit eval/new Function through
+`chrome.userScripts.configureWorld`, with a CSP such as
+`script-src 'self' 'unsafe-eval'; object-src 'self'`. Configure the world before its
+first injection into a document, or configure a fresh `worldId` and use that ID
+when injecting. Changing the configuration after a world already exists did not
+relax that existing world's CSP in our Chrome test. `configureWorld` does not
+configure MAIN's CSP. Plain `js[].code` injection needs neither eval nor this
+additional world configuration.
+
+These behaviors were verified on real Chrome with a restrictive page CSP:
+MAIN source execution returned a Promise result, shared page globals and changed
+the DOM while the tab remained debugger-detached; eval and new Function inside
+that MAIN source remained blocked. The native API and result arrays already pass
+through the bridge unchanged. See [Chrome userScripts](https://developer.chrome.com/docs/extensions/reference/api/userScripts).
+The migration discussion in [Tampermonkey #644](https://github.com/Tampermonkey/tampermonkey/issues/644#issuecomment-2094925643)
+and its [Content Script API documentation](https://www.tampermonkey.net/documentation.php?locale=en&q=content_script_api)
+describe the corresponding native user-script injection mechanism.
+
+### User-script consent: system and managed profiles
+
+The shipped manifest already declares `userScripts`, but a manifest permission
+alone cannot turn on Chrome's user consent. Before Chrome 138 the gate is Developer
+mode; from Chrome 138 it is **Allow User Scripts** for the individual extension.
+
+For a **system profile**, passive `reverse: true`, or `cdp_ext_install: false`,
+enable it manually in `chrome://extensions/?id=<extension_id>` using the observed
+`client.browsers.work.extension_id`. This is a per-extension/profile choice, not
+something to repeat at every connection. Reload the extension if the API is still
+unavailable after enabling it. Use the shipped `cdp_ext/` folder for manual installs.
+
+For **managed custom profiles**, `cdp_ext_user_scripts` defaults to true when
+`cdp_ext: true`, `cdp_ext_install: true` and an effective custom user-data directory
+are all present. Effective raw directory overrides count, including null/false
+overrides that remove the directory. Before announcing a new bootstrap binding,
+the bridge checks access and, if needed, uses Chrome's own extensions-settings UI
+API to enable it for its own extension. It briefly opens an inactive internal
+settings tab, runs a fixed native scripting function, and closes that tab. This
+uses no debugger and no remote-debugging flags.
+
+This developer setup needs generated `extensions-on-chrome-urls: true` and
+`DisableExtensionsOnChromeUrlsSwitch` in `disable-features`. The manager adds
+`chrome://extensions/*` only to the **managed copy** of the manifest. The shipped
+manifest remains suitable for a normal manual installation. The worker and sidebar
+files are copied unchanged. Chrome writes its own protected permission settings;
+the library does not edit `Secure Preferences` or compute preference signatures.
+Legacy Chrome uses the internal Developer mode setting instead of the newer
+per-extension setting; the automatic path is tested on Chrome 154.
+
+Set `cdp_ext_user_scripts: false` to skip the permission step, extra host access
+and development flags. Existing grants are preserved. Explicit true without both
+installation and a custom directory rejects before launching; it never infers or
+modifies the system profile. `update_preferences: false` controls JSON file writes
+independently and does not turn off this native permission setup. Raw CLI overrides
+still win; disabling a required switch can make setup fail. Such failures reach
+the caller through the initial reverse announcement and appear in the local
+trigger history, rather than being reported as a successful connection.
+An already running Chrome cannot adopt new command-line capabilities or a changed
+loaded manifest; restart that custom-profile browser after enabling this option.
+
+The internal settings API and developer switches are Chrome implementation
+details; unsupported browsers/policies produce errors. Simply writing
+`extensions.settings.<extension_id>.user_scripts_enabled` into `Preferences` did
+not enable access in our Windows test because Chrome protects these settings.
+See the native [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
@@ -1276,6 +1393,10 @@ See [Chrome's debugging-port restrictions](https://developer.chrome.com/blog/rem
 | `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 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. |
+| Managed extension plus effective custom directory | Default `cdp_ext_user_scripts` to true; grant through Chrome's own UI API before accepting the reverse binding. |
+| `cdp_ext_user_scripts: false` plus an existing grant | Preserve the grant, skip the permission step and omit its extra generated flags/manifest host. |
+| `cdp_ext_user_scripts: true` without custom directory or installation | Reject before launch; the system profile remains a manual choice. |
+| `update_preferences: false` plus automatic user-script consent | Skip JSON preference-file writes; still let Chrome apply its native per-extension grant. |
 | `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. |
 | `initialize: false` plus `runtime: true` or a binding name | Skip optional target setup, including domain enabling and binding installation. |
@@ -1335,7 +1456,8 @@ await client.call({
 | `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. |
 | `group` | unset | Reverse-only tab group name or first-use `{ name, color }` configuration. False skips grouping. |
 | `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. |
+| `execution_mode` | `'api'` in reverse | Reverse-only choice for implicit target setup and built-in XPath helpers: `'api'` uses extension APIs; `'debugger'` attaches and runs CDP setup. Direct CDP ignores it. |
+| `initialize` | `true` | Run the convenience CDP setup sequence in direct/debugger mode; false skips it. API mode skips that sequence regardless. |
 | `runtime` | `'bootstrap'` | Enable Runtime for setup, then disable reporting. `true` leaves it enabled; `false` skips both operations. |
 | `page` | `true` | Enable Page domain reporting for navigation/page operations and events. |
 | `network` | `true` | Enable Network reporting so native network events are available. |
@@ -1344,6 +1466,102 @@ await client.call({
 | `binding` | `'_send_to_cdp'` | Default page-to-host JavaScript binding. String changes its name; false skips installation; true selects the default name. |
 | `background_service` | `true` | Clear, observe and record `pushMessaging` background-service events in Chromium. |
 
+### Reverse execution mode
+
+In extension mode (`cdp_ext: true` or passive `reverse: true`), a target defaults
+to `execution_mode: 'api'`. Creating/selecting it, grouping it and running
+`_.find`/`_.click` do not attach the debugger. Root tabs are created through
+`chrome.tabs`/`chrome.windows`; choosing debugger mode then attaches the selected
+tab before setup. Chrome's debugger API needs an existing debuggee.
+
+| Operation | Reverse API target (default) | Reverse debugger target |
+| --- | --- | --- |
+| Target selection and root routing | Register the stable tab ID without debugger attachment. | Attach the selected tab and register the same routing ID. |
+| Implicit initialization | No Runtime/Page/Network enabling, binding, focus emulation, background-service setup or resume command. | Apply the documented initialization options and resume after setup. |
+| `_.find`, `_.click` | Fixed native `chrome.scripting.executeScript` functions in the isolated world; shared DOM, no string evaluation. | `Runtime.evaluate` in the page world. |
+| Explicit session CDP, such as `Runtime.evaluate` or `Page.navigate` | Attach lazily and execute the exact CDP request. | Execute the CDP request. |
+| Explicit `chrome.*` method | Invoke the named native extension API with the supplied positional arguments. | Same native extension API dispatch. |
+
+The target option is recorded on first use of its logical name, like the other
+target options. It belongs in `params.target`, not constructor/browser defaults.
+`runtime: true`, `network: true` or a binding name alone do not opt an API target
+into debugger setup. To retain the previous reverse convenience initialization,
+set `target.execution_mode: 'debugger'` explicitly. Direct CDP defaults are unchanged.
+As with the existing XPath helper, `_.find` does not wait for navigation or retry;
+wait for your page's readiness before querying it.
+
+```js
+const found = await client.call({
+  method: '_.find',
+  params: {
+    browser: {
+      name: 'work',
+      cdp_ext: true,
+    },
+    target: {
+      name: 'search',
+      create_params: {
+        url: 'https://example.com/',
+      },
+    },
+    xpath: '//h1',
+  },
+})
+console.log(found.result.value)
+
+// Select debugger execution for this helper call only.
+await client.call({
+  method: '_.click',
+  params: {
+    browser: 'work',
+    target: 'search',
+    execution_mode: 'debugger',
+    xpath: '//button',
+  },
+})
+
+// Native CDP executes even though the target's default remains API mode.
+await client.call({
+  method: 'Runtime.evaluate',
+  params: {
+    browser: 'work',
+    target: 'search',
+    expression: 'document.title',
+  },
+})
+
+// A separate target with the full convenience debugger setup.
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: 'work',
+    target: {
+      name: 'instrumented',
+      execution_mode: 'debugger',
+      runtime: true,
+    },
+    url: 'https://example.com/',
+  },
+})
+```
+
+For the built-in helpers and `evaluate_xpath`, `params.execution_mode` overrides
+the target's choice for that call only; it does not enable optional target setup
+or change the recorded configuration. Valid reverse values are `'api'` and
+`'debugger'`. Native CDP and `chrome.*` methods keep their explicit dispatch and
+ignore this helper override; the router removes it from native parameters.
+Custom handlers still receive the original parameters and choose their own behavior.
+
+API selection does not detach a debugger previously attached by an explicit
+command. Use `Target.detachFromTarget` explicitly if needed. After detachment,
+an API target can be selected and used through API helpers again without
+reattachment. Native CDP attachment by itself does not enable domains or install
+bindings; send the desired commands explicitly or choose debugger target setup.
+Only debugger-attached targets expose flattened worker/iframe sessions. Browser
+API helpers operate on the registered root tab's main frame; extension permissions
+and Chrome's restricted-page rules still apply. There is no automatic fallback
+from API execution to debugger execution.
+
 ### Named tab groups
 
 With `cdp_ext: true` or external `reverse: true`, set `target.group` when first
@@ -1416,6 +1634,10 @@ and [grouping tabs](https://developer.chrome.com/docs/extensions/reference/api/t
 
 ### Target initialization
 
+The following CDP setup applies to direct mode and reverse targets configured
+with `execution_mode: 'debugger'`. Reverse API targets skip it entirely, including
+`Runtime.runIfWaitingForDebugger`; `initialize: false` does not opt into debugging.
+
 Domain options set to false skip setup commands; they do not actively disable a
 domain already enabled by another caller. Likewise, `binding: false` does not
 remove a previously installed binding. Use native CDP commands for immediate
@@ -1488,10 +1710,16 @@ await loaded
 ## XPath custom methods
 
 Both built-ins require `params.target`; `params.browser` defaults to `main`
-through the normal router. They use `Runtime.evaluate` with `returnByValue`,
+through the normal router. In direct/debugger execution they use `Runtime.evaluate` with `returnByValue`,
 `awaitPromise`, `silent` and `userGesture` set to true: serialize the result,
 await async page code, suppress evaluation exception reporting, and evaluate
-with a user gesture respectively.
+with a user gesture respectively. In reverse API execution, fixed native scripting
+functions perform the same DOM operations in the isolated world, without eval,
+user-script permission or CSP changes. They keep `response.result.value` and the
+same click/find value shapes. API results contain `result.type` and `result.value`;
+they do not manufacture CDP remote-object metadata or `exceptionDetails`.
+Native injection errors reject; failed script execution also rejects. Debugger
+evaluation retains native `exceptionDetails` for page-side exceptions.
 
 | Method | Parameters | Remote result in `response.result.value` |
 | --- | --- | --- |
@@ -1520,7 +1748,13 @@ XPath snapshot length, even when `items` is limited or empty.
 not a complete parser; arbitrary nested or comma-containing arguments are outside
 that rewriting logic. Ordinary XPath expressions pass through unchanged.
 
-`client.evaluate_xpath(params, fn, options)` is available for other helpers:
+`_.find` and `_.click` already contain fixed browser-side functions. In API mode
+only the XPath string and data options are sent to them; neither needs user-script
+consent, eval or new Function. This is the appropriate path for those two built-ins.
+
+`client.evaluate_xpath(params, fn, options)` is a separate, general-purpose callback
+helper: its `fn` parameter is executable code supplied by its caller, not just an
+XPath string. It is available for other helpers:
 
 ```js
 const text = await client.evaluate_xpath({
@@ -1536,10 +1770,22 @@ const text = await client.evaluate_xpath({
 console.log(text.result.value)
 ```
 
-`params` supplies `browser`, `target` and `xpath`. `fn` is serialized and called in
+`params` supplies `browser`, `target`, `xpath` and optional per-call
+`execution_mode`. `fn` is serialized and called in
 the target as `fn(normalizedXPath, options)`; it cannot capture Node.js variables
 or imported helpers. `options` must be JSON-serializable; omission becomes null
-in the argument array. Results retain native `exceptionDetails` if page code throws.
+in the argument array. Direct/debugger results retain native `exceptionDetails`
+if page code throws. In reverse API mode this arbitrary-function helper compiles
+the serialized invocation directly through `chrome.userScripts.execute` in the
+**MAIN** world and returns `{ result: { type, value } }`. It requires user-script
+access, automatically prepared for managed profiles as described above. The
+wrapper awaits the callback and preserves undefined values; callback exceptions
+reject with their message. It does not use eval/new Function, change CSP, or fall
+back to the debugger. A callback that itself invokes eval still obeys page CSP.
+Choose `execution_mode: 'debugger'` explicitly when native CDP evaluation is
+required. Native `chrome.scripting.executeScript` calls keep their existing string
+adapter, native world default and native result array; the fixed XPath built-ins
+do not use that string adapter either.
 
 ### Register, replace or remove handlers
 
@@ -1645,6 +1891,7 @@ await client.call({
   params: {
     target: {
       name: 'bridge',
+      execution_mode: 'debugger',
       binding: 'send_to_host',
       runtime: true,
     },
@@ -1839,10 +2086,13 @@ 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.
+access in external/opt-out profiles, automatic consent in managed custom profiles,
+MAIN globals, DOM changes and Promise results under restrictive page CSP, and
+continued CSP restrictions on eval/new Function. Generic XPath callbacks run through
+native userScripts while fixed XPath commands work even with userScripts denied.
+Only disposable incognito-grant preparation uses direct CDP to operate Chrome's
+Allow in incognito toggle; reverse execution and automatic user-script consent
+use no remote-debugging flags or debugger attachment.
 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

package/cdp.js

@@ -188,6 +188,10 @@ export class browser {
     }
     if (options.cdp_ext) {
       args['remote-debugging-port'] = false
+      if (options.cdp_ext_user_scripts) {
+        args['extensions-on-chrome-urls'] = true
+        args['disable-features'].push('DisableExtensionsOnChromeUrlsSwitch')
+      }
       delete args['disable-extensions']
       delete args['disable-component-extensions-with-background-pages']
       if (options.extension_path) args['disable-extensions-except'] = [
@@ -320,7 +324,7 @@ const custom_methods = {
         if (i + 1 < options.attempts) await new Promise(resolve => setTimeout(resolve, options.interval_ms))
       }
       return false
-    }, options)
+    }, options, '_.click')
   },
   '_.find'(params) {
     const limit = params.limit ?? 20
@@ -346,7 +350,7 @@ const custom_methods = {
         count: nodes.snapshotLength,
         items,
       }
-    }, limit)
+    }, limit, '_.find')
   },
 }
 
@@ -383,7 +387,7 @@ export class cdp extends EventTarget {
           const error = new Error(message.error)
           if (record) record.reverse_error = error
           util.emit(this, 'reverse_' + encodeURIComponent(id), error)
-          return socket.close(1008, 'Chrome profile already connected')
+          return socket.close(1008, 'Reverse browser initialization failed')
         }
         if (record) record.extension_id = extension_id
         this.reverse_sockets[id] = socket
@@ -472,20 +476,59 @@ export class cdp extends EventTarget {
     })
   }
 
-  evaluate_xpath(params, fn, options) {
+  async evaluate_xpath(params, fn, options, method) {
     if (params.target == null) throw new Error('Custom method requires target')
     const xpath = util.normalize_xpath(params.xpath)
-    return this.call({
+    const { record, entry } = await this._resolve(params)
+    const reverse = record.reverse || record.cdp_ext
+    const execution_mode = params.execution_mode ?? entry.execution_mode ?? 'api'
+    if (reverse && !['api', 'debugger'].includes(execution_mode)) throw new Error('execution_mode must be api or debugger')
+    if (reverse && execution_mode === 'api') {
+      if (method) return record.socket.req({
+        method,
+        params: {
+          xpath,
+          options,
+        },
+        sessionId: entry.sessionId,
+      })
+      const results = await record.socket.req({
+        method: 'chrome.userScripts.execute',
+        params: {
+          args: [{
+            target: { tabId: Number(entry.targetId) },
+            world: 'MAIN',
+            js: [{
+              code: `(async () => {
+                try {
+                  return { value: await (${fn})(...${JSON.stringify([xpath, options])}) }
+                } catch (error) {
+                  return { error: String(error) }
+                }
+              })()`,
+            }],
+          }],
+        },
+      })
+      const result = results[0].result
+      if (!result || Object.hasOwn(result, 'error')) throw new Error(result?.error ?? results[0].error ?? 'XPath callback did not execute')
+      return {
+        result: {
+          type: typeof result.value,
+          value: result.value,
+        },
+      }
+    }
+    return record.socket.req({
       method: 'Runtime.evaluate',
       params: {
-        browser: params.browser,
-        target: params.target,
         expression: '(' + fn + ')(...' + JSON.stringify([xpath, options]) + ')',
         returnByValue: true,
         awaitPromise: true,
         silent: true,
         userGesture: true,
       },
+      sessionId: entry.sessionId,
     })
   }
 
@@ -513,7 +556,7 @@ export class cdp extends EventTarget {
     }
     const info = browser.target_info[targetId]
     if (message.method === 'Target.attachedToTarget') {
-      this._detach(browser, info?.sessionId)
+      if (info?.sessionId !== sessionId) this._detach(browser, info?.sessionId)
       info.sessionId = sessionId
       browser.session_targets[sessionId] = targetId
     }
@@ -616,6 +659,14 @@ export class cdp extends EventTarget {
   }
 
   async _connect(record) {
+    const args = browser.build_args(record)
+    if (record.cdp_ext) {
+      record.cdp_ext_install ??= !!args['user-data-dir']
+      record.cdp_ext_user_scripts ??= record.cdp_ext_install && !!args['user-data-dir']
+      if (record.cdp_ext_user_scripts && (!record.cdp_ext_install || !args['user-data-dir'])) {
+        throw new Error('Automatic user-script access requires cdp_ext_install and a custom user-data-dir')
+      }
+    }
     if (record.reverse || record.cdp_ext) {
       await this.server_closing
       if (!this.server) this.listen_reverse()
@@ -631,6 +682,7 @@ export class cdp extends EventTarget {
         bootstrap.searchParams.set('browser', record.name)
         bootstrap.searchParams.set('websocket_url', record.reverse_url)
         bootstrap.searchParams.set('token', record.reverse_token)
+        if (record.cdp_ext_user_scripts) bootstrap.searchParams.set('user_scripts', '1')
         record.bootstrap_url = bootstrap.href
       }
       delete record.reverse_error
@@ -644,8 +696,6 @@ export class cdp extends EventTarget {
       url = (await response.json()).webSocketDebuggerUrl
     }
     if (record.cdp_ext || (!record.reverse && !url)) {
-      const args = browser.build_args(record)
-      if (record.cdp_ext) record.cdp_ext_install ??= !!args['user-data-dir']
       if ((record.proc?.exitCode === null && record.proc.signalCode === null) ||
           (record.opener?.exitCode === null && record.opener.signalCode === null)) url = record.socket?.url
       else {
@@ -661,6 +711,12 @@ export class cdp extends EventTarget {
           for (const filename of ['manifest.json', 'cdp_ext.js', 'sidebar.html', 'sidebar.js']) {
             await fs.copyFile(new URL('./cdp_ext/' + filename, import.meta.url), path.join(record.extension_path, filename))
           }
+          if (record.cdp_ext_user_scripts) {
+            const filename = path.join(record.extension_path, 'manifest.json')
+            const manifest = JSON.parse(await fs.readFile(filename, 'utf8'))
+            manifest.host_permissions.push('chrome://extensions/*')
+            await fs.writeFile(filename, JSON.stringify(manifest, null, 2) + '\n')
+          }
         }
         if (args['user-data-dir'] && record.update_preferences !== false) {
           await browser.update_profile_preferences(path.join(args['user-data-dir'], args['profile-directory'] || 'Default', 'Preferences'), {
@@ -777,6 +833,8 @@ export class cdp extends EventTarget {
   async _target(browser, target) {
     const socket = browser.socket
     const reverse = browser.reverse || browser.cdp_ext
+    const execution_mode = target.execution_mode ?? 'api'
+    if (reverse && !['api', 'debugger'].includes(execution_mode)) throw new Error('execution_mode must be api or debugger')
     if (target.group != null && target.group !== false) {
       const spec = typeof target.group === 'string' ? { name: target.group } : target.group
       browser.groups[spec.name] ??= {
@@ -819,17 +877,23 @@ export class cdp extends EventTarget {
       if (!info.incognito) throw new Error('Existing target is not incognito')
     }
     if (target.group != null && target.group !== false) info.groupId = await this._group(browser, target)
-    if (!info.sessionId) {
+    if (!info.sessionId || (reverse && execution_mode === 'debugger')) {
       info.sessionId = (await socket.req({
         method: 'Target.attachToTarget',
         params: {
           targetId: target.targetId,
           flatten: true,
+          ...(reverse ? { execution_mode } : {}),
         },
       })).sessionId
       browser.session_targets[info.sessionId] = target.targetId
     }
     const sessionId = info.sessionId
+    target.setup_errors = []
+    if (reverse && execution_mode === 'api') {
+      target.sessionId = sessionId
+      return
+    }
     const steps = []
     if (target.initialize !== false) {
       for (const [option, domain] of Object.entries({
@@ -853,7 +917,6 @@ export class cdp extends EventTarget {
       if ((target.runtime ?? 'bootstrap') === 'bootstrap') steps.push(['Runtime.disable'])
     }
     steps.push(['Runtime.runIfWaitingForDebugger'])
-    target.setup_errors = []
     for (const [method, params] of steps) {
       try {
         await socket.req({
@@ -869,13 +932,7 @@ export class cdp extends EventTarget {
     target.sessionId = sessionId
   }
 
-  async call({ method, params = {} }) {
-    if (method.startsWith('_.')) {
-      const handler = this.custom_methods[method]
-      if (!handler) throw new Error('Unknown CDP extension: ' + method)
-      return handler.call(this, params)
-    }
-    const { browser = 'main', target, ...native } = params
+  async _resolve({ browser = 'main', target }) {
     const spec = typeof browser === 'string' ? { name: browser } : browser
     const record = this.browsers[spec.name] ??= {
       user_data_dir: ((spec.reverse ?? this.options.reverse) || (spec.cdp_ext ?? this.options.cdp_ext)) ? null : path.join(this.base_path, spec.name),
@@ -933,6 +990,20 @@ export class cdp extends EventTarget {
         await entry.connecting
       }
     }
+    return {
+      record,
+      entry,
+    }
+  }
+
+  async call({ method, params = {} }) {
+    if (method.startsWith('_.')) {
+      const handler = this.custom_methods[method]
+      if (!handler) throw new Error('Unknown CDP extension: ' + method)
+      return handler.call(this, params)
+    }
+    const { browser, target, execution_mode, ...native } = params
+    const { record, entry } = await this._resolve(params)
     if (method === 'Target.disposeBrowserContext' && target == null) {
       const context = Object.values(record.contexts).find(value => value.browserContextId === native.browserContextId)
       if (context) return this._dispose_context(record, context, native)

package/cdp_ext/cdp_ext.js

@@ -12,9 +12,22 @@ let auto_attach = {}
 let bootstrapping
 let checking = false
 let connection_message
+let setup_error
 const debug_commands = []
 const debug_ports = []
 
+function debug_record(fields) {
+  const record = {
+    time: Date.now(),
+    ...fields,
+    status: 'running',
+  }
+  debug_commands.unshift(record)
+  debug_commands.length = Math.min(debug_commands.length, 50)
+  debug_update()
+  return record
+}
+
 function debug_update() {
   const state = {
     status: connection_message ?? (config.browser ? 'Connecting to server' : 'Waiting for trigger'),
@@ -23,6 +36,7 @@ function debug_update() {
     endpoint: config.websocket_url ?? '',
     extension_id: chrome.runtime.id,
     sessions: Object.keys(sessions).length,
+    debugger_tabs: Object.keys(attached).length,
     commands: debug_commands,
   }
   for (const port of debug_ports) {
@@ -52,6 +66,36 @@ function report_connection(message) {
   debug_update()
 }
 
+async function enable_user_scripts() {
+  try {
+    await chrome.userScripts.getScripts()
+    return
+  } catch {}
+  const tab = await chrome.tabs.create({
+    url: 'chrome://extensions/?id=' + chrome.runtime.id,
+    active: false,
+  })
+  try {
+    const results = await chrome.scripting.executeScript({
+      target: { tabId: tab.id },
+      world: 'MAIN',
+      args: [chrome.runtime.id],
+      func: async id => {
+        const version = Number(navigator.userAgent.match(/(?:Chrome|Chromium)\/(\d+)/)?.[1])
+        if (version < 138) await chrome.developerPrivate.updateProfileConfiguration({ inDeveloperMode: true })
+        else await chrome.developerPrivate.updateExtensionConfiguration({
+          extensionId: id,
+          userScriptsAccess: true,
+        })
+        return true
+      },
+    })
+    if (results[0]?.result !== true) throw new Error('Chrome did not enable user-script access')
+  } finally {
+    await chrome.tabs.remove(tab.id)
+  }
+}
+
 async function bootstrap(tab) {
   const text = tab.pendingUrl ?? tab.url ?? ''
   if (!/^http:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?\/cdp_ext\?/.test(text)) return
@@ -67,33 +111,66 @@ async function bootstrap(tab) {
   await configured
   while (bootstrapping) await bootstrapping
   return bootstrapping = (async () => {
-    const changed = ['browser', 'websocket_url', 'token'].some(key => settings[key] !== config[key])
-    if (changed && config.browser && socket?.readyState < WebSocket.CLOSING) {
-      const probe = new WebSocket(settings.websocket_url)
-      probe.onopen = () => probe.send(JSON.stringify({
-        browser: settings.browser,
-        extension_id: chrome.runtime.id,
-        token: settings.token,
-        error: 'This Chrome profile is already connected as ' + config.browser,
-      }))
-      return
-    }
-    if (changed) {
-      Object.assign(config, settings)
-      connection_message = undefined
-      debug_update()
-      await chrome.storage.session.set({ cdp_bootstrap: settings })
-      if (socket && socket.readyState !== WebSocket.CLOSED) {
-        await new Promise(resolve => {
-          socket.addEventListener('close', resolve, { once: true })
-          socket.close()
-        })
+    const tabs = await chrome.tabs.query({})
+    if (!tabs.some(current => current.id === tab.id && (current.pendingUrl ?? current.url) === text)) return
+    const trigger = debug_commands.find(record => record.method === 'cdp_ext.trigger' &&
+      record.tabId === tab.id && record.browser === settings.browser && record.endpoint === settings.websocket_url) ?? debug_record({
+      method: 'cdp_ext.trigger',
+      tabId: tab.id,
+      browser: settings.browser,
+      endpoint: settings.websocket_url,
+    })
+    try {
+      const changed = ['browser', 'websocket_url', 'token'].some(key => settings[key] !== config[key])
+      if (changed && config.browser && socket?.readyState < WebSocket.CLOSING) {
+        const probe = new WebSocket(settings.websocket_url)
+        trigger.error = 'This Chrome profile is already connected as ' + config.browser
+        probe.onopen = () => probe.send(JSON.stringify({
+          browser: settings.browser,
+          extension_id: chrome.runtime.id,
+          token: settings.token,
+          error: trigger.error,
+        }))
+      } else {
+        setup_error = undefined
+        if (changed) {
+          Object.assign(config, settings)
+          connection_message = undefined
+          debug_update()
+          await chrome.storage.session.set({ cdp_bootstrap: settings })
+          if (socket && socket.readyState !== WebSocket.CLOSED) {
+            await new Promise(resolve => {
+              socket.addEventListener('close', resolve, { once: true })
+              socket.close()
+            })
+          }
+          await disconnecting
+        }
+        if (url.searchParams.get('user_scripts') === '1') await enable_user_scripts()
       }
-      await disconnecting
+      const current_tabs = await chrome.tabs.query({})
+      const current = current_tabs.find(current => current.id === tab.id)
+      if ((current?.pendingUrl ?? current?.url) === text) {
+        if (current_tabs.length === 1) {
+          await chrome.tabs.update(tab.id, { url: chrome.runtime.getURL('sidebar.html?connection') })
+          trigger.action = 'opened connection page'
+        } else {
+          await chrome.tabs.remove(tab.id)
+          trigger.action = 'closed tab'
+        }
+      }
+      trigger.status = trigger.error ? 'error' : 'done'
+    } catch (error) {
+      trigger.status = 'error'
+      trigger.error = error.message
+      setup_error = 'Extension setup failed: ' + error.message
+    } finally {
+      trigger.duration_ms = Date.now() - trigger.time
+      debug_update()
     }
-    await connect()
   })().finally(() => {
     bootstrapping = null
+    return connect()
   })
 }
 
@@ -114,7 +191,7 @@ function target_info(tab) {
 }
 
 function detached(source) {
-  if (!attached[source.tabId]) return
+  if (!sessions[String(source.tabId)]) return
   delete attached[source.tabId]
   for (const [id, session] of Object.entries(sessions)) {
     if (session.tabId === source.tabId) delete sessions[id]
@@ -210,6 +287,12 @@ const methods = {
   },
   async 'Target.attachToTarget'(params) {
     const tabId = Number(params.targetId)
+    if (params.execution_mode === 'api') {
+      await chrome.tabs.get(tabId)
+      sessions[String(tabId)] = { tabId }
+      debug_update()
+      return { sessionId: String(tabId) }
+    }
     if (attaching[tabId]) return attaching[tabId]
     if (attached[tabId]) return { sessionId: String(tabId) }
     return attaching[tabId] = attach_tab(tabId).finally(() => delete attaching[tabId])
@@ -220,7 +303,7 @@ const methods = {
     if (source.sessionId) {
       await chrome.debugger.sendCommand({ tabId: source.tabId }, 'Target.detachFromTarget', { sessionId: source.sessionId })
     } else {
-      await chrome.debugger.detach(source)
+      if (attached[source.tabId]) await chrome.debugger.detach(source)
       detached(source)
     }
   },
@@ -266,6 +349,7 @@ chrome.tabs.onUpdated.addListener((id, changes, tab) => {
   })
 })
 chrome.tabs.onRemoved.addListener(id => {
+  detached({ tabId: id })
   if (discovering) send({
     method: 'Target.targetDestroyed',
     params: { targetId: String(id) },
@@ -293,7 +377,7 @@ for (const [name, options] of Object.entries({
 async function connect() {
   await configured
   if (!config.browser || !config.websocket_url || !config.token) return
-  if (disconnecting || checking) return
+  if (bootstrapping || disconnecting || checking) return
   if (socket?.readyState === WebSocket.CONNECTING) return
   if (socket?.readyState === WebSocket.OPEN) return socket.send('')
   const endpoint = config.websocket_url
@@ -327,22 +411,19 @@ async function connect() {
       browser: config.browser,
       extension_id: chrome.runtime.id,
       token: config.token,
+      error: setup_error,
     }))
   }
   connection.onmessage = async event => {
     if (!event.data) return
     const request = JSON.parse(event.data)
     const { method, params = {}, sessionId, id } = request
-    const command = {
-      time: Date.now(),
+    const command = debug_record({
       id,
       method,
       sessionId,
-      status: 'running',
-    }
-    debug_commands.unshift(command)
-    debug_commands.length = Math.min(debug_commands.length, 50)
-    debug_update()
+      execution_mode: params.execution_mode,
+    })
     let response
     try {
       let result
@@ -363,11 +444,62 @@ async function connect() {
             else resolve(value)
           }))
           : await object[name](...args)
+      } else if (method === '_.click' || method === '_.find') {
+        const source = sessions[sessionId]
+        if (!source || source.sessionId) throw new Error('XPath browser API commands require a registered root tab')
+        const results = await chrome.scripting.executeScript({
+          target: { tabId: source.tabId },
+          args: [method, params.xpath, params.options],
+          func: async (method, xpath, options) => {
+            if (method === '_.click') {
+              for (let i = 0; i < options.attempts; i++) {
+                const node = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue
+                if (node) {
+                  if (typeof node.click !== 'function') return false
+                  node.click()
+                  return true
+                }
+                if (i + 1 < options.attempts) await new Promise(resolve => setTimeout(resolve, options.interval_ms))
+              }
+              return false
+            }
+            const nodes = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
+            const items = []
+            for (let i = 0; i < Math.min(nodes.snapshotLength, options); i++) {
+              const node = nodes.snapshotItem(i)
+              items.push({
+                node_type: node.nodeType,
+                node_name: node.nodeName,
+                text: String(node.innerText ?? node.textContent ?? '').trim().slice(0, 2000),
+                tag: node.tagName?.toLowerCase(),
+                id: node.id,
+                class: node.className == null ? undefined : String(node.className),
+                href: node.href,
+                value: node.value,
+                rect: node.getBoundingClientRect?.().toJSON(),
+              })
+            }
+            return {
+              count: nodes.snapshotLength,
+              items,
+            }
+          },
+        })
+        if (!Object.hasOwn(results[0] ?? {}, 'result')) throw new Error('XPath browser API execution failed')
+        result = {
+          result: {
+            type: typeof results[0].result,
+            value: results[0].result,
+          },
+        }
       } else {
         if (sessionId == null && !methods[method]) throw new Error('Unsupported reverse browser command: ' + method)
-        result = sessionId != null
-          ? await chrome.debugger.sendCommand(sessions[sessionId], method, params)
-          : await methods[method](params)
+        if (sessionId != null) {
+          const source = sessions[sessionId]
+          if (!source) throw new Error('Unknown debugger session: ' + sessionId)
+          await methods['Target.attachToTarget']({ targetId: String(source.tabId) })
+          result = await chrome.debugger.sendCommand(source, method, params)
+        } else result = await methods[method](params)
       }
       response = {
         id,
@@ -391,10 +523,11 @@ async function connect() {
   connection.onclose = () => {
     report_connection('Waiting for CDP.js server at ' + endpoint + '; retrying automatically.')
     discovering = false
-    disconnecting = Promise.all(Object.keys(attached).map(id => {
+    disconnecting = Promise.all(Object.keys(sessions).filter(id => !sessions[id].sessionId).map(id => {
       const source = { tabId: Number(id) }
+      const was_attached = attached[id]
       detached(source)
-      return chrome.debugger.detach(source).catch(() => {})
+      if (was_attached) return chrome.debugger.detach(source).catch(() => {})
     })).finally(() => disconnecting = null)
   }
 }

package/cdp_ext/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "CDP reverse connection",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "minimum_chrome_version": "125",
   "permissions": [
     "accessibilityFeatures.read",

package/cdp_ext/sidebar.html

@@ -20,16 +20,18 @@
   small { display: block; opacity: .7; margin-top: 5px; font-size: 12px; }
   .error { color: light-dark(#b42318, #ff938a); white-space: pre-wrap; overflow-wrap: anywhere; }
 </style>
-<header><h1>CDP.js debug</h1><button id="clear" type="button" title="Clear command history">Clear</button></header>
+<header><h1>CDP.js debug</h1><button id="clear" type="button" title="Clear diagnostic history">Clear</button></header>
+<p id="connection-message" hidden>Browser bridge configured. Live connection status is shown below.</p>
 <p id="status" role="status">Connecting to extension…</p>
 <dl>
   <dt>Browser</dt><dd id="browser">—</dd>
   <dt>Server</dt><dd id="endpoint">—</dd>
   <dt>Extension</dt><dd id="extension">—</dd>
-  <dt>Attached sessions</dt><dd id="sessions">0</dd>
+  <dt>Routing sessions</dt><dd id="sessions">0</dd>
+  <dt>Debugger tabs</dt><dd id="debugger_tabs">0</dd>
 </dl>
-<h2>Recent commands <small>Latest 50 · memory only</small></h2>
-<p id="empty">No commands received.</p>
+<h2>Recent activity <small>Latest 50 · memory only</small></h2>
+<p id="empty">No activity received.</p>
 <ol id="commands"></ol>
 <script src="sidebar.js"></script>
 </html>

package/cdp_ext/sidebar.js

@@ -1,6 +1,11 @@
 const port = chrome.runtime.connect({ name: 'cdp_debug' })
 const status = document.querySelector('#status')
 const heartbeat = setInterval(() => port.postMessage('ping'), 20000)
+if (location.search === '?connection') {
+  document.title = 'CDP.js connection'
+  document.querySelector('h1').textContent = document.title
+  document.querySelector('#connection-message').hidden = false
+}
 
 port.onMessage.addListener(state => {
   status.textContent = state.status
@@ -10,6 +15,7 @@ port.onMessage.addListener(state => {
     endpoint: state.endpoint,
     extension: state.extension_id,
     sessions: state.sessions,
+    debugger_tabs: state.debugger_tabs ?? 0,
   })) document.getElementById(id).textContent = value === '' ? '—' : value
   document.querySelector('#empty').hidden = state.commands.length > 0
   document.querySelector('#commands').replaceChildren(...state.commands.map(command => {
@@ -19,9 +25,14 @@ port.onMessage.addListener(state => {
     const details = document.createElement('small')
     details.textContent = [
       new Date(command.time).toLocaleTimeString(),
-      '#' + (command.id ?? 'notification'),
+      command.id == null ? (command.method === 'cdp_ext.trigger' ? 'trigger' : 'notification') : '#' + command.id,
       command.sessionId ? 'session ' + command.sessionId : 'browser',
       command.status,
+      command.execution_mode,
+      command.tabId == null ? '' : 'tab ' + command.tabId,
+      command.browser,
+      command.endpoint,
+      command.action,
       command.duration_ms == null ? '' : command.duration_ms + ' ms',
     ].filter(Boolean).join(' · ')
     row.append(method, details)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mefistofelix/cdp.js",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Low-level Chromium DevTools Protocol client for Node.js, Deno and Bun, with no runtime dependencies.",
   "type": "module",
   "exports": "./cdp.js",