@mefistofelix/cdp.js 0.5.0 → 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,9 +541,9 @@ 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
-`<user-data-dir>/<profile-directory>/cdp_ext/` (`Default` when unset), sets the
-shared server URL in that manifest and adds startup loading flags. Normal launch
+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
 an extension already installed in that profile, or true to force preparation and
 loading. A null/false raw directory override makes automatic installation default off.
@@ -568,6 +568,13 @@ and enable the bridge. An `extensions` array adds its directories;
 `extensions: true` retains enabled profile extensions through `'*'`. Raw `args`
 still win and can prevent loading or connection.
 
+Both launch paths keep `--no-first-run` and
+`--disable-search-engine-choice-screen`, including when opening a new custom
+profile with installation disabled. This suppresses onboarding and the search
+engine selection prompt without changing the chosen search provider or writing
+search preferences. Raw `args` can override either flag. An existing Chrome only
+receives the URL; new startup flags require restarting that instance.
+
 The manager opens an actual local HTTP URL on the shared listener, for example
 `http://127.0.0.1:9223/cdp_ext?browser=work&websocket_url=...&token=...`.
 The port is the effective listening port, including an automatically allocated
@@ -590,15 +597,22 @@ manager while connected returns an explicit error, preserving the existing
 connection. After disconnection, a new bootstrap can rebind it.
 
 Passive external attachment remains available through `reverse: true`: it opens
-no URL and waits for `extension_id` (or the browser label). Without bootstrap,
-the extension announces its native ID and uses its manifest endpoint. This
-compatibility mode is optional; `cdp_ext: true` needs neither `reverse` nor an ID.
+no URL and waits for `extension_id` (or the browser label). This compatibility
+mode is optional; `cdp_ext: true` needs neither `reverse` nor an ID.
+The current extension still requires a trigger URL in passive mode; it never
+connects automatically to a manifest endpoint or a default port.
+
+The extension stays idle until a valid trigger URL supplies the logical name,
+WebSocket endpoint and token. Before that it makes no server requests and logs
+no connection messages. A worker restart may resume the same browser session's
+previous trigger from `chrome.storage.session`.
 
-The manifest's `cdp` configuration supplies initial connection defaults:
+The shipped manifest needs no custom configuration keys. An optional custom
+`cdp.reconnect_ms` override remains supported (Chrome displays a harmless
+unrecognized-key warning if it is added):
 
 | Manifest `cdp` key | Default | Meaning |
 | --- | --- | --- |
-| `websocket_url` | `ws://127.0.0.1:9223` | Initial shared endpoint; URL bootstrap overrides it. |
 | `reconnect_ms` | `5000` | Awake retry and connected heartbeat interval; use a positive value below 30000. |
 
 Construction and direct CDP calls do not start a listener. The first browser call
@@ -662,10 +676,42 @@ another connection attempt; the configured interval applies while it is awake.
 Connected empty-text heartbeats keep an otherwise idle WebSocket worker active.
 These are transport messages, not event buffering or polling of browser state.
 
+After a trigger, the server may be offline normally. Before each disconnected
+WebSocket attempt the extension checks the same server's HTTP `/cdp_ext` endpoint
+with a two-second timeout and no cache. It opens the socket only when that
+endpoint identifies CDP.js. Concurrent retries share the check; an unavailable or
+incompatible server causes one informational waiting message, not a failing
+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 first announcement contains `{ browser, extension_id, token }` for bootstrap,
-or the native extension ID for passive attachment. Subsequent messages use CDP envelopes:
+The current extension's first announcement contains `{ browser, extension_id, token }`
+after a trigger. The server also accepts legacy native-ID announcements.
+Subsequent messages use CDP envelopes:
 
 - Request: `{ id, method, params, sessionId? }`.
 - Response: `{ id, result }` or `{ id, error: { code, message } }`.
@@ -1763,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
@@ -1805,5 +1852,13 @@ already running instance, startup when absent, one shared extension directory,
 logical names, binding tokens, conflicting names and preservation on manager close.
 Installation defaults, raw directory overrides, profile writes independent of
 installation and shared wildcard expansion are covered without opening personal profiles.
-The npm tarball contains `package.json`, `cdp.js`, `README.md` and the two extension
-files required by managed reverse launches.
+Argument coverage crosses direct/extension launch modes with headless, proxy,
+image/login/translation options, extension selectors and raw overrides. Profile
+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 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

@@ -153,12 +153,10 @@ export class browser {
       'disable-prompt-on-repost': true,
       'force-color-profile': 'srgb',
       'metrics-recording-only': true,
-      'no-first-run': true,
       'password-store': 'basic',
       'use-mock-keychain': true,
       'no-service-autorun': true,
       'export-tagged-pdf': true,
-      'disable-search-engine-choice-screen': true,
       'disable-features': [
         'InfiniteSessionRestore',
         'ImprovedCookieControls',
@@ -177,6 +175,8 @@ export class browser {
       'user-data-dir': options.user_data_dir,
       'remote-debugging-port': 0,
     }
+    args['no-first-run'] = true
+    args['disable-search-engine-choice-screen'] = true
     if (options.headless) {
       args.headless = 'new'
       args['window-size'] = '1440,900'
@@ -658,10 +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)
-          const manifest = JSON.parse(await fs.readFile(new URL('./cdp_ext/manifest.json', import.meta.url), 'utf8'))
-          manifest.cdp.websocket_url = record.reverse_url
-          await fs.writeFile(path.join(record.extension_path, 'manifest.json'), JSON.stringify(manifest))
-          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

@@ -1,4 +1,6 @@
-const config = chrome.runtime.getManifest().cdp ?? {}
+const config = {
+  reconnect_ms: chrome.runtime.getManifest().cdp?.reconnect_ms ?? 5000,
+}
 const configured = chrome.storage.session.get('cdp_bootstrap').then(value => Object.assign(config, value.cdp_bootstrap))
 const sessions = {}
 const attached = {}
@@ -8,6 +10,47 @@ let disconnecting
 let discovering = false
 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) {
   const text = tab.pendingUrl ?? tab.url ?? ''
@@ -37,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 => {
@@ -81,6 +126,7 @@ function detached(source) {
       targetId: String(source.tabId),
     },
   })
+  debug_update()
 }
 
 async function attach_tab(tabId) {
@@ -196,6 +242,7 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
       sessionId: params.sessionId,
     }
     else delete sessions[params.sessionId]
+    debug_update()
   }
   send({
     method,
@@ -245,19 +292,57 @@ for (const [name, options] of Object.entries({
 
 async function connect() {
   await configured
-  if (disconnecting) return
+  if (!config.browser || !config.websocket_url || !config.token) return
+  if (disconnecting || checking) return
   if (socket?.readyState === WebSocket.CONNECTING) return
   if (socket?.readyState === WebSocket.OPEN) return socket.send('')
-  const connection = socket = new WebSocket(config.websocket_url ?? 'ws://127.0.0.1:9223')
-  connection.onopen = () => connection.send(JSON.stringify({
-    browser: config.browser ?? chrome.runtime.id,
-    extension_id: chrome.runtime.id,
-    token: config.token,
-  }))
+  const endpoint = config.websocket_url
+  const url = new URL(endpoint)
+  url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:'
+  url.pathname = '/cdp_ext'
+  url.search = ''
+  url.hash = ''
+  let available = false
+  checking = true
+  try {
+    const response = await fetch(url, {
+      cache: 'no-store',
+      signal: AbortSignal.timeout(2000),
+    })
+    available = response.ok && await response.text() === 'CDP.js browser connection'
+  } catch (error) {
+    if (!(error instanceof TypeError) && error.name !== 'TimeoutError') throw error
+  } finally {
+    checking = false
+  }
+  if (endpoint !== config.websocket_url) return connect()
+  if (!available) {
+    report_connection('Waiting for CDP.js server at ' + endpoint + '; retrying automatically.')
+    return
+  }
+  const connection = socket = new WebSocket(endpoint)
+  connection.onopen = () => {
+    report_connection('Connected to CDP.js server at ' + endpoint + '.')
+    connection.send(JSON.stringify({
+      browser: config.browser,
+      extension_id: chrome.runtime.id,
+      token: config.token,
+    }))
+  }
   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(),
+      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
@@ -297,9 +382,14 @@ 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 => {
       const source = { tabId: Number(id) }
@@ -323,5 +413,5 @@ async function start() {
 chrome.runtime.onStartup.addListener(start)
 chrome.alarms.onAlarm.addListener(connect)
 chrome.alarms.create('cdp-reconnect', { periodInMinutes: 0.5 })
-setInterval(connect, config.reconnect_ms ?? 5000)
+setInterval(connect, config.reconnect_ms)
 start()

package/cdp_ext/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "CDP reverse connection",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "minimum_chrome_version": "125",
   "permissions": [
     "accessibilityFeatures.read",
@@ -64,13 +64,14 @@
   "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"
-  },
-  "cdp": {
-    "websocket_url": "ws://127.0.0.1:9223",
-    "reconnect_ms": 5000
   }
 }

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.0",
+  "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"