@mefistofelix/cdp.js 0.5.1 → 0.6.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`.
@@ -491,7 +491,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.
@@ -541,7 +541,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
@@ -685,6 +685,28 @@ 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.
+It shows the current connection status, logical browser name, WebSocket endpoint,
+native extension ID and number of attached root/child sessions. 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
+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.
+**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 }`
@@ -1787,11 +1809,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 +1858,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

@@ -658,8 +658,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'), {

package/cdp_ext/cdp_ext.js

@@ -12,11 +12,44 @@ let auto_attach = {}
 let bootstrapping
 let checking = false
 let connection_message
+const debug_commands = []
+const debug_ports = []
+
+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,
+    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) {
@@ -47,6 +80,8 @@ async function bootstrap(tab) {
     }
     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 => {
@@ -91,6 +126,7 @@ function detached(source) {
       targetId: String(source.tabId),
     },
   })
+  debug_update()
 }
 
 async function attach_tab(tabId) {
@@ -206,6 +242,7 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
       sessionId: params.sessionId,
     }
     else delete sessions[params.sessionId]
+    debug_update()
   }
   send({
     method,
@@ -296,6 +333,16 @@ async function connect() {
     if (!event.data) return
     const request = JSON.parse(event.data)
     const { method, params = {}, sessionId, id } = request
+    const command = {
+      time: Date.now(),
+      id,
+      method,
+      sessionId,
+      status: 'running',
+    }
+    debug_commands.unshift(command)
+    debug_commands.length = Math.min(debug_commands.length, 50)
+    debug_update()
     let response
     try {
       let result
@@ -335,6 +382,10 @@ 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 = () => {

package/cdp_ext/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "CDP reverse connection",
-  "version": "0.5.1",
+  "version": "0.6.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,35 @@
+<!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 command history">Clear</button></header>
+<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>
+</dl>
+<h2>Recent commands <small>Latest 50 · memory only</small></h2>
+<p id="empty">No commands received.</p>
+<ol id="commands"></ol>
+<script src="sidebar.js"></script>
+</html>

package/cdp_ext/sidebar.js

@@ -0,0 +1,43 @@
+const port = chrome.runtime.connect({ name: 'cdp_debug' })
+const status = document.querySelector('#status')
+const heartbeat = setInterval(() => port.postMessage('ping'), 20000)
+
+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,
+  })) 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 ?? 'notification'),
+      command.sessionId ? 'session ' + command.sessionId : 'browser',
+      command.status,
+      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.6.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"