@mefistofelix/cdp.js 0.2.0 → 0.4.0

package/README.md

@@ -1,13 +1,16 @@
 # cdp.js
 
-A low-level Chromium DevTools Protocol library for Node.js, with an optional
-native Deno server for Chrome extension reverse connections. One ES module,
+A low-level Chromium DevTools Protocol library for Node.js, Deno and Bun, with an
+optional native Deno/Bun server for Chrome extension reverse connections. One ES module,
 standard-library imports, no runtime dependencies or root `package.json`.
 
 Use Node.js 22.19+ and an installed Chrome, Chromium or Edge. Import `cdp.js`
 directly from an ES module, for example `example.mjs`, and run `node example.mjs`.
 Browser discovery covers common Windows, macOS and Linux installation paths;
 use `executable_path` or the `CDP_BROWSER` environment variable for other paths.
+The same module also runs with `bun example.mjs` or `deno run -A example.mjs`.
+Direct and reverse modes are tested with Bun 1.4.3; no Bun-specific package,
+configuration file or installation step is required by the library.
 
 For a published npm release:
 
@@ -24,7 +27,8 @@ below remain supported. Publication metadata is isolated in `npm/`.
 The package includes both `cdp_ext/` files. With `cdp_ext: true`, the manager
 writes a configured extension copy into the browser's profile directory and loads
 it automatically; no manual extraction or build is needed. Reverse mode still
-requires Deno. In Deno, import from `npm:@mefistofelix/cdp.js`.
+requires Deno or Bun. In Deno, import from `npm:@mefistofelix/cdp.js`.
+In Bun, use `bun add @mefistofelix/cdp.js` and the ordinary package import above.
 
 ## Features and scope
 
@@ -33,8 +37,9 @@ requires Deno. In Deno, import from `npm:@mefistofelix/cdp.js`.
 - Browser proxies and named direct-mode contexts with independent proxies/storage
   and automatic cleanup after their last target closes.
 - Incognito targets in direct and reverse modes.
+- Named, colored tab groups through the reverse Chrome extension.
 - Attachment through WebSocket, HTTP discovery or a debugging port.
-- Optional Chrome extension reverse connections through one native Deno server,
+- Optional Chrome extension reverse connections through one native Deno/Bun server,
   without browser remote-debugging arguments.
 - Generic `chrome.x.y` extension API calls on that connection, including scripting,
   tabs/windows, cookies, storage, downloads and browser settings.
@@ -116,8 +121,8 @@ import api, { util, jsrpc, browser, cdp } from './cdp.js'
 | `client.call({ method, params = {} })` | Resolve routing and return a promise for the native CDP result, or a custom handler's result. |
 | `client.evaluate_xpath(params, fn, options)` | Execute a serialized function with a normalized XPath in a target; return the native `Runtime.evaluate` result. |
 | `client.close()` | Close owned 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 native WebSocket with the same RPC methods. |
-| `client.listen_reverse(options = {})` | Start the native Deno WebSocket server; returns its `HttpServer`. |
+| `new jsrpc(urlOrSocket, options = {})` | Open a raw WebSocket JSON-RPC connection or equip an accepted socket with the same RPC methods. |
+| `client.listen_reverse(options = {})` | Start the native Deno or Bun WebSocket server; returns that server with common lifecycle fields documented below. |
 | `socket.req(request, timeout_ms)` | Assign a request ID and await its native result. |
 | `socket.notify(request)` | Serialize and send a raw message; no ID allocation or response wait. |
 | `socket.close()` | Native WebSocket close; does not terminate the browser. |
@@ -237,8 +242,8 @@ local configuration.
 | `request_timeout_ms` | number, `30000` | Default timeout for each protocol request on this browser's socket. |
 | `waitForDebuggerOnStart` | boolean, `false` | Ask Chromium to pause newly auto-attached targets. Applied to `Target.setAutoAttach` when connecting; not a CLI argument or target option. |
 | `websocket_url` | string, unset | Attach directly to a browser WebSocket endpoint. |
-| `cdp_ext` | boolean, `false` | Launch with the reverse extension under Deno. Start one shared server automatically if needed, prepare a profile-specific extension copy and wait for its connection. |
-| `reverse` | boolean, `false` | Attach to an externally launched extension instead of launching or discovering a browser. Starts the shared listener on first use under Deno. |
+| `cdp_ext` | boolean, `false` | Launch with the reverse extension under Deno or Bun. Start one shared server automatically if needed, prepare a profile-specific extension copy and wait for its connection. |
+| `reverse` | boolean, `false` | Attach to an externally launched extension instead of launching or discovering a browser. Starts the shared listener on first use under Deno or Bun. |
 | `extension_id` | string, browser name for external reverse attachment | Incoming extension ID to associate with this logical browser. Set automatically for managed `cdp_ext` launches. |
 | `http_url` | string, unset | Discover the endpoint from an HTTP(S) base URL or exact `/json/version` URL. |
 | `port` | number, unset | Discover an existing browser at `http://<host>:<port>/json/version`. |
@@ -343,7 +348,7 @@ Native proxy rules can use semicolon-separated strings; the generic CLI converte
 still comma-joins every array. Bypass lists accept both separators. Chrome gives
 `no-proxy-server` precedence, so overriding `proxy-server` alone does not cancel
 that flag; override `args['no-proxy-server']: false` too if needed.
-Browser proxy options affect Chrome traffic, not Node/Deno's endpoint discovery
+Browser proxy options affect Chrome traffic, not the runtime's endpoint discovery
 or CDP transport. Chrome normally bypasses loopback addresses. To proxy them,
 use `args['proxy-bypass-list']: '<-loopback>'`; in reverse mode keep the extension's
 local WebSocket listener reachable. The library inserts no extra bypass rule.
@@ -491,12 +496,13 @@ browser instances on the same port; each extension announces its native ID
 in its first message. No remote-debugging argument is needed.
 
 Run the server under Deno using its native
-[WebSocket upgrade](https://docs.deno.com/api/deno/websockets/).
+[WebSocket upgrade](https://docs.deno.com/api/deno/websockets/) or under Bun using
+[Bun.serve](https://bun.sh/docs/runtime/http/websockets).
 Node's direct CDP mode remains supported; `listen_reverse()` under Node rejects
-with an explicit Deno requirement. There is no WebSocket framing implementation,
+with an explicit Deno/Bun requirement. There is no WebSocket framing implementation,
 third-party server dependency or additional build step.
 
-Run `deno run -A examples/reverse.mjs` to launch Chrome with the extension, create
+Run `deno run -A examples/reverse.mjs` or `bun examples/reverse.mjs` to launch Chrome with the extension, create
 a target and evaluate `21 * 2`. Ctrl+C closes the owned browser and server.
 The same mode is available per browser:
 
@@ -589,15 +595,24 @@ retry. Direct browsers do not keep this listener alive.
 `client.reverse_server` is the public shared configuration object. After startup
 it contains the effective listening port, including when `port: 0` originally
 requested an available port. Restarts reuse that port so existing extensions can
-still reconnect. `client.server` contains the current native Deno `HttpServer`,
+still reconnect. `client.server` contains the current native Deno `HttpServer` or Bun `Server`,
 or is unset/null while stopped. A call arriving during shutdown waits for it to
 finish before starting a replacement server.
 
 `listen_reverse(options = client.reverse_server)` remains available to start the
-listener explicitly ahead of a browser call. It returns the native `HttpServer`;
+listener explicitly ahead of a browser call. It returns the native runtime server;
 calling it while a server is running rejects. Explicit options replace the stored
 settings, with omitted fields taking the hostname/port defaults above.
 
+Both runtimes expose `server.addr.hostname`, `server.addr.port`,
+`server.shutdown()` and `server.finished`. On Bun, the library adds these fields:
+`shutdown()` calls native `stop()` and resolves `finished` after shutdown.
+Use `client.close()` to also close owned browsers and incoming sockets.
+Bun's callback-based server sockets receive a small EventTarget adapter with
+native send/close and live ready state. The same `jsrpc` handles both runtimes;
+registration, request IDs, pending waits, events and session routing are shared.
+Native Bun WebSocket limits still apply.
+
 Reverse calls reuse the normal target setup, custom handlers, mappings, routed
 events, request correlation, timeout and error behavior. `reverse: true` alone
 attaches externally: the manager neither launches nor updates that browser.
@@ -1259,6 +1274,7 @@ await client.call({
 | `targetId` | `null` | Optional existing physical target ID. Reused if discovered; otherwise create a new target. |
 | `context` | unset | Direct-mode context name or first-use configuration object; see named contexts above. Reverse mode rejects this option. |
 | `incognito` | `false` | Create/select a private target; direct mode uses the shared `'incognito'` context by default, reverse uses a native incognito window with the user's extension grant. |
+| `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. |
 | `runtime` | `'bootstrap'` | Enable Runtime for setup, then disable reporting. `true` leaves it enabled; `false` skips both operations. |
@@ -1269,6 +1285,78 @@ 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. |
 
+### Named tab groups
+
+With `cdp_ext: true` or external `reverse: true`, set `target.group` when first
+configuring a target:
+
+```js
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: {
+      name: 'work',
+      cdp_ext: true,
+    },
+    target: {
+      name: 'search',
+      group: {
+        name: 'Research',
+        color: 'blue',
+      },
+    },
+    url: 'https://example.com/',
+  },
+})
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: 'work',
+    target: {
+      name: 'notes',
+      group: 'Research',
+    },
+    url: 'https://example.com/notes',
+  },
+})
+```
+
+| Group option | Default | Meaning |
+| --- | --- | --- |
+| `name` | required in an object | Logical name in `record.groups`; also the visible group title. A string reference creates a default group if this name is new. |
+| `color` | unset | Chrome's native color selection for new groups; otherwise retain the current color. Explicit values: `grey`, `blue`, `red`, `yellow`, `green`, `pink`, `purple`, `cyan`, `orange`. |
+
+The first use of a group name records its configuration. Concurrent target
+creation shares that definition and serializes group operations. Names are scoped
+to the logical browser. Each window has its own native group for that name:
+tabs stay in their current window, including separate regular/incognito windows.
+Groups are created by the library, not adopted from unrelated groups that happen
+to have the same visible title. Incognito still requires the bridge's user grant.
+
+Grouping happens before optional CDP setup, including with `initialize: false`.
+It also works with `targetId` selecting an existing tab. As with other target
+options, passing a new group on a target label that was already configured does
+not reconfigure that label. Use another label with its physical `targetId`, or
+edit the public record and reinitialize the target.
+
+Reconnection reapplies the name/color and rejoins a surviving group. If its last
+tab was closed or ungrouped, Chrome removes the native group; later target setup
+creates a new one. `record.groups[name].window_groups[windowId]` stores the last
+known native group ID. These IDs are checked against Chrome during setup and can
+remain stale between operations; no extra event subscriptions or persistence are
+added. In reverse target info, `groupId` is the current native ID, or `-1` when
+ungrouped. Generic `chrome.tabs` / `chrome.tabGroups` calls remain available for
+immediate native updates. Native errors, including invalid colors, reject setup
+with the usual RPC error context and can be retried after correcting the record.
+
+Direct CDP does not expose browser tab-group commands. A non-false `group` option
+therefore rejects before connecting or launching in direct mode. The bridge's
+existing `tabGroups` permission is sufficient; no extra permission is added.
+See [Chrome tab groups](https://developer.chrome.com/docs/extensions/reference/api/tabGroups)
+and [grouping tabs](https://developer.chrome.com/docs/extensions/reference/api/tabs#method-group).
+
+### Target initialization
+
 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
@@ -1530,9 +1618,9 @@ dictionary containers have a null prototype.
 | `client.reverse_server` | Shared listener configuration; the effective hostname/port are stored after startup. |
 | `client.custom_methods[name]` | Handler function. |
 | `client.browsers[name]` | Browser configuration fields plus live state. |
-| `client.reverse_sockets[extension_id]` | Announced incoming native WebSocket, available even before the first call. |
+| `client.reverse_sockets[extension_id]` | Announced incoming socket, available even before the first call; native on Deno, an EventTarget adapter on Bun. |
 | `record.extension_id`, `record.extension_path` | Expected extension identity and the managed copy's canonical directory. |
-| `client.server` | Current native Deno reverse `HttpServer`, or unset/null when not listening. |
+| `client.server` | Current native Deno/Bun reverse server with shared lifecycle fields, or unset/null when not listening. |
 | `client.server_closing` | Shutdown promise while the reverse listener is stopping, otherwise unset/null. |
 | `record.socket` | Current `jsrpc` connection once created. |
 | `record.proc` | Owned child process; absent for external attachment. |
@@ -1540,6 +1628,7 @@ dictionary containers have a null prototype.
 | `record.targets[label]` | Target options, physical `targetId`, `sessionId`, `connecting` and `setup_errors` after setup. |
 | `record.contexts[name]` | Recorded context options, native `browserContextId` or null, and pending `connecting`/`closing` promises. Direct mode only. |
 | `record.context_checking` | Pending automatic empty-context cleanup, otherwise unset/null. |
+| `record.groups[name]` | Recorded tab-group options, per-window native IDs in `window_groups`, and a pending `connecting` operation. Reverse only. |
 | `record.target_info[targetId]` | Discovered native target info plus cached `sessionId` when attached. |
 | `record.session_targets[sessionId]` | Physical `targetId` for a session. |
 | `socket.pending[id]` | Response-wait promise, removed on completion. |
@@ -1599,11 +1688,13 @@ subject to the debugging-port restrictions described above.
 Readiness timeout or launch failure rejects and attempts to
 terminate the spawned process.
 
-`jsrpc` takes a WebSocket URL or an accepted native WebSocket and an options
+`jsrpc` takes a WebSocket URL or an accepted EventTarget socket and an options
 object whose recognized option is
 `request_timeout_ms` (default `30000`). Wait for the socket to open before `req`.
-For an accepted socket, it returns that same WebSocket with RPC fields/methods;
-it remains a native WebSocket, but need not be an instance of the `jsrpc` subclass.
+For an accepted socket, it returns that same object with RPC fields/methods.
+The object supplies `send`, `close`, live `readyState` and normal message/close/error
+events. Deno sockets remain native WebSockets; Bun uses the adapter described
+above. Accepted sockets need not be instances of the `jsrpc` subclass.
 The reverse server consumes the initial browser announcement before equipping
 the socket with RPC behavior. Empty-text heartbeats are ignored.
 The request is a raw envelope: `method`, optional `params`, and optional top-level
@@ -1625,6 +1716,7 @@ labels, target labels, custom methods or reconnection policy in this layer.
 | Failed discovery or local launch | Reject the call establishing the connection. |
 | Named context in reverse mode | Reject explicitly; no separate process emulation. |
 | Reverse incognito without the extension's user grant | Reject with an instruction to enable Allow in incognito. |
+| Tab group in direct mode | Reject before connecting; tab groups require the reverse extension APIs. |
 | Automatic context cleanup fails | Emit the manager's `error` event with browser label and original error. |
 
 ```js
@@ -1662,15 +1754,18 @@ node --check cdp.js
 node --check cdp_ext/cdp_ext.js
 node --test tests/cdp.test.js
 deno test -A tests/reverse.test.js
+bun test tests/cdp.test.js tests/reverse.test.js --timeout 60000
 ```
 
 Integration tests launch local headless Chromium with disposable profiles under
 `build/tests/`. Set `CDP_BROWSER` if discovery does not match the machine. Direct
 library use needs no build or package installation; npm packaging is optional.
-The Deno test loads the real extension into two headless Chrome instances on one
+The shared Deno/Bun reverse suite loads the real extension into two headless Chrome instances on one
 server port without remote-debugging arguments. It checks native/custom calls,
 Network events, webRequest notifications without debugger attachment, bindings,
 child sessions, reconnect, detach/recreate, incognito and isolation.
+Tab-group checks cover concurrent creation, existing tabs, title/color, per-window
+incognito separation, reconnection, recreation and native validation/retry.
 Node coverage also checks actual browser/context proxy routing, shared private
 storage, concurrent context creation, automatic disposal, unselected targets and
 context ownership in externally attached browsers.

package/cdp.js

@@ -46,7 +46,7 @@ export class util {
 
 export class jsrpc extends WebSocket {
   constructor(url, options = {}) {
-    const socket = url instanceof WebSocket ? url : super(url)
+    const socket = typeof url === 'string' || url instanceof URL ? super(url) : url
     setMaxListeners(0, socket)
     socket.id = 0
     socket.pending = {}
@@ -355,18 +355,9 @@ export class cdp extends EventTarget {
     hostname = '127.0.0.1',
     port = 9223,
   } = this.reverse_server) {
-    if (!globalThis.Deno) throw new Error('The reverse WebSocket server requires Deno')
+    if (!globalThis.Deno && !globalThis.Bun) throw new Error('The reverse WebSocket server requires Deno or Bun')
     if (this.server) throw new Error('Reverse server is already listening')
-    this.server = Deno.serve({
-      hostname,
-      port,
-    }, request => {
-      const origin = request.headers.get('origin')
-      if (request.headers.get('upgrade') !== 'websocket' ||
-          !origin?.startsWith('chrome-extension://')) {
-        return new Response(null, { status: 403 })
-      }
-      const { socket, response } = Deno.upgradeWebSocket(request)
+    const accept = (socket, origin) => {
       socket.addEventListener('message', event => {
         const id = JSON.parse(event.data).browser
         if (id !== origin.slice('chrome-extension://'.length) ||
@@ -380,8 +371,61 @@ export class cdp extends EventTarget {
         })
         util.emit(this, 'reverse_' + encodeURIComponent(id), socket)
       }, { once: true })
+    }
+    const fetch = (request, server) => {
+      const origin = request.headers.get('origin')
+      if (request.headers.get('upgrade') !== 'websocket' ||
+          !origin?.startsWith('chrome-extension://')) {
+        return new Response(null, { status: 403 })
+      }
+      if (globalThis.Bun) {
+        if (server.upgrade(request, {
+          data: {
+            origin,
+            socket: new EventTarget(),
+          },
+        })) return
+        return new Response(null, { status: 400 })
+      }
+      const { socket, response } = Deno.upgradeWebSocket(request)
+      accept(socket, origin)
       return response
-    })
+    }
+    if (globalThis.Bun) {
+      const server = this.server = Bun.serve({
+        hostname,
+        port,
+        fetch,
+        websocket: {
+          open(socket) {
+            const events = socket.data.socket
+            events.send = socket.send.bind(socket)
+            events.close = socket.close.bind(socket)
+            Object.defineProperty(events, 'readyState', { get: () => socket.readyState })
+            accept(events, socket.data.origin)
+          },
+          message(socket, data) {
+            socket.data.socket.dispatchEvent(new MessageEvent('message', { data }))
+          },
+          close(socket, code, reason) {
+            socket.data.socket.dispatchEvent(Object.assign(new Event('close'), {
+              code,
+              reason,
+            }))
+          },
+        },
+      })
+      server.addr = {
+        hostname,
+        port: server.port,
+      }
+      const finished = Promise.withResolvers()
+      server.finished = finished.promise
+      server.shutdown = () => server.stop().then(finished.resolve)
+    } else this.server = Deno.serve({
+      hostname,
+      port,
+    }, fetch)
     this.reverse_server = {
       hostname,
       port: this.server.addr.port,
@@ -640,9 +684,58 @@ export class cdp extends EventTarget {
     }
   }
 
+  async _group(browser, target) {
+    const socket = browser.socket
+    const group = browser.groups[target.group]
+    while (group.connecting) await group.connecting
+    return group.connecting = (async () => {
+      const tab = await socket.req({
+        method: 'chrome.tabs.get',
+        params: { args: [Number(target.targetId)] },
+      })
+      const groups = await socket.req({
+        method: 'chrome.tabGroups.query',
+        params: { args: [{ windowId: tab.windowId }] },
+      })
+      const groupId = group.window_groups[tab.windowId]
+      const existing = groups.some(value => value.id === groupId)
+      const id = await socket.req({
+        method: 'chrome.tabs.group',
+        params: {
+          args: [{
+            tabIds: tab.id,
+            groupId: existing ? groupId : undefined,
+            createProperties: existing ? undefined : { windowId: tab.windowId },
+          }],
+        },
+      })
+      group.window_groups[tab.windowId] = id
+      await socket.req({
+        method: 'chrome.tabGroups.update',
+        params: {
+          args: [id, {
+            title: group.name,
+            color: group.color,
+          }],
+        },
+      })
+      return id
+    })().finally(() => {
+      group.connecting = null
+    })
+  }
+
   async _target(browser, target) {
     const socket = browser.socket
     const reverse = browser.reverse || browser.cdp_ext
+    if (target.group != null && target.group !== false) {
+      const spec = typeof target.group === 'string' ? { name: target.group } : target.group
+      browser.groups[spec.name] ??= {
+        ...spec,
+        window_groups: Object.create(null),
+      }
+      target.group = spec.name
+    }
     if (target.incognito && !reverse && target.context == null && target.create_params?.browserContextId == null) {
       target.context = 'incognito'
     }
@@ -676,6 +769,7 @@ export class cdp extends EventTarget {
       Object.assign(info, targetInfo)
       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) {
       info.sessionId = (await socket.req({
         method: 'Target.attachToTarget',
@@ -752,10 +846,14 @@ export class cdp extends EventTarget {
       },
       targets: Object.create(null),
       contexts: Object.create(null),
+      groups: Object.create(null),
     }
     if (target?.context != null && (record.reverse || record.cdp_ext)) {
       throw new Error('Named browser contexts are unavailable through the reverse Chrome extension')
     }
+    if (target?.group != null && target.group !== false && !record.reverse && !record.cdp_ext) {
+      throw new Error('Tab groups require the reverse Chrome extension (cdp_ext or reverse)')
+    }
     if (!record.connecting && record.socket?.readyState !== WebSocket.OPEN) {
       record.connecting = this._connect(record).catch(error => {
         record.socket?.close()

package/cdp_ext/cdp_ext.js

@@ -19,6 +19,7 @@ function target_info(tab) {
     url: tab.url ?? tab.pendingUrl ?? '',
     attached: !!attached[tab.id],
     incognito: tab.incognito,
+    groupId: tab.groupId,
   }
 }
 

package/package.json

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