@mefistofelix/cdp.js 0.5.1 → 0.7.0

package/README.md

@@ -24,7 +24,7 @@ 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
+The package includes the worker, manifest and debug sidebar files. With `cdp_ext: true`, the manager
 prepares and loads the extension automatically with a custom user-data directory.
 The system profile uses an already installed extension by default. Reverse mode still
 requires Deno or Bun. In Deno, import from `npm:@mefistofelix/cdp.js`.
@@ -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. |
@@ -491,7 +493,7 @@ can configure its native incognito scope. See
 ## 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
+[cdp_ext/cdp_ext.js](cdp_ext/cdp_ext.js), with the local debug sidebar, 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; bootstrapped extensions announce the logical
 browser name and native extension ID. No remote-debugging argument is needed.
@@ -529,6 +531,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,
@@ -541,7 +556,7 @@ await client.call({
 
 Provide `user_data_dir` or raw `args['user-data-dir']` to choose a custom
 directory. An effective custom directory makes `cdp_ext_install` default to true:
-the manager copies the two extension files into
+the manager copies the four extension files into
 `<user-data-dir>/<profile-directory>/cdp_ext/` (`Default` when unset) and adds
 startup loading flags. The server address comes only from the trigger URL. Normal launch
 options and profile preferences then apply. Set `cdp_ext_install: false` to use
@@ -648,8 +663,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.
@@ -685,6 +701,40 @@ WebSocket attempt on every timer tick. Successful connections and later
 disconnects log their status once per transition. Chrome can still emit a native
 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, 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 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. 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.
+
+The panel receives updates through a local extension port. While open, a
+20-second port heartbeat keeps the worker available, including before a trigger.
+Closing the panel does not disconnect CDP. After reloading the extension, reopen
+the panel if its old document reports that it has disconnected. The HTML and
+external script follow the normal extension CSP and require no build or dependency.
+
 ### Reverse protocol and supported commands
 
 The current extension's first announcement contains `{ browser, extension_id, token }`
@@ -714,8 +764,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.
@@ -730,12 +782,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.
 
@@ -1313,7 +1366,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. |
@@ -1322,6 +1376,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
@@ -1394,6 +1544,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
@@ -1466,10 +1620,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` |
 | --- | --- | --- |
@@ -1514,10 +1674,19 @@ 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 uses the
+existing string-function scripting adapter in the **MAIN** world and returns
+`{ result: { type, value } }`. Unlike the two fixed built-ins, arbitrary source
+evaluation requires the page CSP to allow eval. Injection errors or missing
+execution results reject; no debugger, CSP bypass or user-script toggle is enabled
+automatically. Choose `execution_mode: 'debugger'` explicitly when native CDP
+evaluation is required. Native `chrome.scripting.executeScript` calls retain their
+existing native world default and native result array.
 
 ### Register, replace or remove handlers
 
@@ -1623,6 +1792,7 @@ await client.call({
   params: {
     target: {
       name: 'bridge',
+      execution_mode: 'debugger',
       binding: 'send_to_host',
       runtime: true,
     },
@@ -1787,11 +1957,12 @@ 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 copies `cdp.js`, this README and the
-two `cdp_ext/` files into `npm/` alongside its manifest; no build script is needed.
+four `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 --check cdp_ext/sidebar.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
@@ -1835,5 +2006,7 @@ combinations include default/custom directories, null/false raw directory
 overrides, forced installation and independent preference-write controls.
 Offline worker checks verify silence before a trigger, deduplicated waiting logs,
 no WebSocket attempts against absent/incompatible servers and concurrent retry checks.
-The npm tarball contains `package.json`, `cdp.js`, `README.md` and the two extension
-files required by managed reverse launches.
+The npm tarball contains `package.json`, `cdp.js`, `README.md` and the four extension
+files required by managed reverse launches and their debug sidebar. Tests cover
+live command metadata, its 50-entry limit, error/session details, sidebar rendering,
+safe text display, reopening and clearing through native extension messaging.

package/cdp.js

@@ -320,7 +320,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 +346,7 @@ const custom_methods = {
         count: nodes.snapshotLength,
         items,
       }
-    }, limit)
+    }, limit, '_.find')
   },
 }
 
@@ -472,20 +472,52 @@ 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.scripting.executeScript',
+        params: {
+          args: [{
+            target: { tabId: Number(entry.targetId) },
+            world: 'MAIN',
+            func: 'async (...args) => ({ value: await (' + fn + ')(...args) })',
+            args: [xpath, options ?? null],
+          }],
+        },
+      })
+      const result = results[0]?.result
+      if (!result) throw new Error('Browser API evaluation failed; check page CSP and extension access. No debugger fallback was used.')
+      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 +545,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
     }
@@ -658,8 +690,9 @@ export class cdp extends EventTarget {
           await fs.mkdir(record.extension_path, { recursive: true })
           record.extension_path = await fs.realpath(record.extension_path)
           record.extension_id = browser.extension_id(record.extension_path)
-          await fs.copyFile(new URL('./cdp_ext/manifest.json', import.meta.url), path.join(record.extension_path, 'manifest.json'))
-          await fs.copyFile(new URL('./cdp_ext/cdp_ext.js', import.meta.url), path.join(record.extension_path, 'cdp_ext.js'))
+          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 (args['user-data-dir'] && record.update_preferences !== false) {
           await browser.update_profile_preferences(path.join(args['user-data-dir'], args['profile-directory'] || 'Default', 'Preferences'), {
@@ -776,6 +809,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] ??= {
@@ -818,17 +853,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({
@@ -852,7 +893,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({
@@ -868,13 +908,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),
@@ -932,6 +966,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,11 +12,57 @@ let auto_attach = {}
 let bootstrapping
 let checking = false
 let connection_message
+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'),
+    connected: socket?.readyState === WebSocket.OPEN,
+    browser: config.browser ?? '',
+    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) {
+    try {
+      port.postMessage(state)
+    } catch {}
+  }
+}
+
+chrome.runtime.onConnect.addListener(port => {
+  if (port.name !== 'cdp_debug') return
+  debug_ports.push(port)
+  port.onDisconnect.addListener(() => debug_ports.splice(debug_ports.indexOf(port), 1))
+  port.onMessage.addListener(message => {
+    if (message !== 'clear') return
+    debug_commands.length = 0
+    debug_update()
+  })
+  configured.then(debug_update)
+})
+chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true })
 
 function report_connection(message) {
   if (connection_message === message) return
   connection_message = message
   console.info('[cdp_ext] ' + message)
+  debug_update()
 }
 
 async function bootstrap(tab) {
@@ -34,29 +80,62 @@ 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)
-      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 {
+        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
+        }
+        await connect()
       }
-      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
+      throw error
+    } finally {
+      trigger.duration_ms = Date.now() - trigger.time
+      debug_update()
     }
-    await connect()
   })().finally(() => {
     bootstrapping = null
   })
@@ -79,7 +158,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]
@@ -91,6 +170,7 @@ function detached(source) {
       targetId: String(source.tabId),
     },
   })
+  debug_update()
 }
 
 async function attach_tab(tabId) {
@@ -174,6 +254,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])
@@ -184,7 +270,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)
     }
   },
@@ -206,6 +292,7 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
       sessionId: params.sessionId,
     }
     else delete sessions[params.sessionId]
+    debug_update()
   }
   send({
     method,
@@ -229,6 +316,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) },
@@ -296,6 +384,12 @@ async function connect() {
     if (!event.data) return
     const request = JSON.parse(event.data)
     const { method, params = {}, sessionId, id } = request
+    const command = debug_record({
+      id,
+      method,
+      sessionId,
+      execution_mode: params.execution_mode,
+    })
     let response
     try {
       let result
@@ -316,11 +410,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,
@@ -335,15 +480,20 @@ async function connect() {
         },
       }
     }
+    command.status = response.error ? 'error' : 'done'
+    command.error = response.error?.message
+    command.duration_ms = Date.now() - command.time
+    debug_update()
     if (id != null && connection.readyState === WebSocket.OPEN) connection.send(JSON.stringify(response))
   }
   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.5.1",
+  "version": "0.7.0",
   "minimum_chrome_version": "125",
   "permissions": [
     "accessibilityFeatures.read",
@@ -64,7 +64,12 @@
   "host_permissions": [
     "<all_urls>"
   ],
-  "action": {},
+  "action": {
+    "default_title": "CDP.js debug"
+  },
+  "side_panel": {
+    "default_path": "sidebar.html"
+  },
   "incognito": "spanning",
   "background": {
     "service_worker": "cdp_ext.js"

package/cdp_ext/sidebar.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CDP.js debug</title>
+<style>
+  :root { color-scheme: light dark; font: 14px system-ui, sans-serif; }
+  body { margin: 16px; }
+  header { display: flex; align-items: center; justify-content: space-between; }
+  h1 { font-size: 18px; margin: 0; }
+  h2 { font-size: 14px; margin: 24px 0 12px; }
+  button { font: inherit; cursor: pointer; padding: 5px 10px; }
+  #status { border-left: 3px solid #d99b24; padding-left: 10px; overflow-wrap: anywhere; }
+  #status.connected { border-color: #35a76a; }
+  dt { opacity: .65; margin-top: 12px; }
+  dd { margin: 3px 0; overflow-wrap: anywhere; font-family: monospace; }
+  #commands { padding: 0; list-style: none; }
+  li { border-top: 1px solid #8885; padding: 10px 0; }
+  strong { display: block; overflow-wrap: anywhere; font: 13px monospace; }
+  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 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>Routing sessions</dt><dd id="sessions">0</dd>
+  <dt>Debugger tabs</dt><dd id="debugger_tabs">0</dd>
+</dl>
+<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

@@ -0,0 +1,54 @@
+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
+  status.classList.toggle('connected', state.connected)
+  for (const [id, value] of Object.entries({
+    browser: state.browser,
+    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 => {
+    const row = document.createElement('li')
+    const method = document.createElement('strong')
+    method.textContent = command.method
+    const details = document.createElement('small')
+    details.textContent = [
+      new Date(command.time).toLocaleTimeString(),
+      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)
+    if (command.error) {
+      const error = document.createElement('p')
+      error.className = 'error'
+      error.textContent = command.error
+      row.append(error)
+    }
+    return row
+  }))
+})
+port.onDisconnect.addListener(() => {
+  clearInterval(heartbeat)
+  status.textContent = 'Extension disconnected. Reopen this panel after reloading the extension.'
+  status.classList.remove('connected')
+  document.querySelector('#clear').disabled = true
+})
+document.querySelector('#clear').addEventListener('click', () => port.postMessage('clear'))

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@mefistofelix/cdp.js",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Low-level Chromium DevTools Protocol client for Node.js, Deno and Bun, with no runtime dependencies.",
   "type": "module",
   "exports": "./cdp.js",
   "files": [
     "cdp.js",
     "cdp_ext/manifest.json",
-    "cdp_ext/cdp_ext.js"
+    "cdp_ext/cdp_ext.js",
+    "cdp_ext/sidebar.html",
+    "cdp_ext/sidebar.js"
   ],
   "engines": {
     "node": ">=22.19.0"