@mefistofelix/cdp.js 0.3.0 → 0.5.0

package/README.md

@@ -25,8 +25,8 @@ 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
-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
+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`.
 In Bun, use `bun add @mefistofelix/cdp.js` and the ordinary package import above.
 
@@ -37,6 +37,7 @@ In Bun, use `bun add @mefistofelix/cdp.js` and the ordinary package import above
 - 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/Bun server,
   without browser remote-debugging arguments.
@@ -188,7 +189,7 @@ belong in `params.target` and do not inherit from the constructor.
 
 For a new browser record, configuration is assembled in this order:
 
-1. Default `user_data_dir` derived from `base_path` and the browser name.
+1. Default `user_data_dir`: unset in extension/passive reverse mode, otherwise derived from `base_path` and the browser name.
 2. Constructor browser options.
 3. The `params.browser` configuration object.
 
@@ -224,7 +225,7 @@ local configuration.
 | `base_path` | string, `'.cdp'` | Constructor-only profile root, resolved against the working directory. |
 | `reverse_server` | object, `{}` | Constructor-only settings for the shared lazy listener: `hostname` defaults to `'127.0.0.1'`, `port` to `9223`. Independent of browser attachment `host`/`port`. |
 | `name` | string, `'main'` when routing is omitted | Required in a browser configuration object; dictionary key and default profile directory label. |
-| `user_data_dir` | absolute path string or `null`, `<base_path>/<name>` | Chromium user-data directory containing profiles such as `Default`. Explicit paths should be absolute. `null` omits the switch and skips manager preference-file writes; Chromium selects its system directory. |
+| `user_data_dir` | absolute path string or `null`, `null` in extension/passive reverse mode, otherwise `<base_path>/<name>` | Chromium user-data directory containing profiles such as `Default`. Explicit paths should be absolute. `null` omits the switch and skips manager preference-file writes; Chromium selects its system directory. |
 | `executable_path` | string, automatic discovery | Executable to spawn; takes precedence over `CDP_BROWSER`. |
 | `headless` | boolean, `false` | When true, add `headless: 'new'` and default `window-size: '1440,900'`. |
 | `windowsHide` | boolean, effective headless mode | Hide the spawned process's console on Windows. Defaults to true when the final arguments include `--headless`, false otherwise; an explicit value wins. Does not hide the parent terminal. |
@@ -241,9 +242,10 @@ 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 or Bun. Start one shared server automatically if needed, prepare a profile-specific extension copy and wait for its connection. |
+| `cdp_ext` | boolean, `false` | Use the extension transport under Deno/Bun: start the shared reverse listener and open a local bootstrap URL containing the logical browser name and WebSocket endpoint. No extension ID is required. |
+| `cdp_ext_install` | boolean, presence of an effective user-data directory | Prepare an extension copy and startup loading arguments. Defaults on for an explicit custom directory, off for the system profile. `false` uses an already installed extension. Only applies with `cdp_ext: true`. |
 | `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. |
+| `extension_id` | string, browser name for passive `reverse: true` attachment | Optional legacy incoming extension identity. Not needed with `cdp_ext: true`; observed automatically from the connection. |
 | `http_url` | string, unset | Discover the endpoint from an HTTP(S) base URL or exact `/json/version` URL. |
 | `port` | number, unset | Discover an existing browser at `http://<host>:<port>/json/version`. |
 | `host` | string, `'127.0.0.1'` | Host used with `port`. |
@@ -491,8 +493,8 @@ can configure its native incognito scope. See
 [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
 125+. The extension connects out to one WebSocket server. The server serves all
-browser instances on the same port; each extension announces its native ID
-in its first message. No remote-debugging argument is needed.
+browser instances on the same port; bootstrapped extensions announce the logical
+browser name and native extension ID. No remote-debugging argument is needed.
 
 Run the server under Deno using its native
 [WebSocket upgrade](https://docs.deno.com/api/deno/websockets/) or under Bun using
@@ -512,6 +514,7 @@ const result = await client.call({
     browser: {
       name: 'work',
       cdp_ext: true,
+      user_data_dir: '/absolute/path/to/work-profile',
       headless: true,
     },
     target: 'demo',
@@ -520,65 +523,84 @@ const result = await client.call({
 })
 ```
 
-The manager copies the two extension files into `cdp_ext/` inside the effective
-profile directory, sets the shared server URL in that copy's manifest and loads
-it before browser startup. Without an effective user-data directory, the copy
-lives under `base_path/<name>/<profile-directory>/` instead (`Default` when unset);
-Chromium still uses its system profile. Profile preferences follow the existing
-`update_preferences` rules.
-The generated launch arguments omit remote debugging and enable this extension.
-An `extensions` array also selects those directories; `extensions: true` keeps
-normally enabled profile extensions through `'*'`. Raw `args` still win and can
-prevent the bridge from loading or connecting, causing a connection timeout.
-
-For external attachment, load unpacked `cdp_ext/` through `chrome://extensions`
-or the [local-extension argument options](#local-extensions-at-startup).
-Use its ID shown in Chrome, or `browser.extension_id(directory)`, as the
-browser option `extension_id`. The logical `name` stays in the manager.
-
-The extension configuration is read from `chrome.runtime.getManifest()`:
-
-| Manifest `cdp` key | Default | Meaning |
-| --- | --- | --- |
-| `websocket_url` | `ws://127.0.0.1:9223` | The shared server endpoint. Port 9223 avoids the usual direct CDP port 9222. |
-| `reconnect_ms` | `5000` | Connection retry interval while the extension worker is awake; also the empty-message heartbeat interval while connected. Use a positive value below 30000. |
-
-The first message uses `chrome.runtime.id`, not a configured logical browser name.
-For an unpacked extension without a manifest `key`, Chromium derives this ID from
-its directory. Managed launches use a separate directory for each profile, so
-the ID is stable across reconnects and restarts, and the manager knows which
-browser it belongs to. External instances must likewise use distinct extension
-directories. Moving the directory changes the ID. The server rejects duplicate
-live IDs and announcements that differ from the WebSocket's `chrome-extension://`
-origin. This is routing information, not an authentication credential.
+With just `cdp_ext: true`, Chrome uses its system user-data directory. No
+`user-data-dir` switch is added. An already installed and enabled bridge reads
+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.
 
 ```js
-import { browser, cdp } from './cdp.js'
-
 const client = new cdp({
-  reverse: true,
-  connect_timeout_ms: 60000,
-  reverse_server: {
-    hostname: '127.0.0.1',
-    port: 9223,
-  },
+  cdp_ext: true,
 })
-const result = await client.call({
-  method: 'Runtime.evaluate',
-  params: {
-    browser: {
-      name: 'other',
-      reverse: true,
-      extension_id: browser.extension_id('/absolute/path/to/cdp_ext'),
-    },
-    target: 'demo',
-    expression: 'document.title',
-  },
+await client.call({
+  method: 'Browser.getVersion',
+  params: { browser: 'work' },
 })
-console.log(result.result.value)
-await client.close()
 ```
 
+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
+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.
+
+Forced installation without a directory places only the extension copy under
+`<base_path>/<name>/<profile-directory>/cdp_ext/`; Chrome still selects its system
+profile. The manager never infers system profile paths for preference writes.
+Loading switches apply only at Chrome startup. An already running Chrome cannot
+load a new extension from a forwarded command line: install it once or restart
+that Chrome before forcing installation.
+
+With installation disabled, opening the link skips the automation launch preset
+so normal Chrome can forward the URL into its existing instance. High-level
+headless, proxy, image, translation, login and extension options still generate
+their flags, followed by raw overrides and the same enabled-only wildcard
+expansion. The manager does not claim ownership of Chrome. Preference writes are
+independent of extension installation: `update_preferences` controls them and
+they require an explicit directory. A running instance does not apply new flags.
+With installation
+enabled, the normal launch preset applies, generated flags omit remote debugging
+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.
+
+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
+port for `reverse_server.port: 0`. Name, WebSocket URL and generated binding token
+are internal bootstrap parameters, not additional user options. The extension
+observes startup tabs, tab creation and URL changes. Bootstrap accepts only
+loopback HTTP URLs with a WebSocket endpoint on the same host/port. The bootstrap
+tab remains open.
+
+The first announcement contains `{ browser, extension_id, token }`. The browser
+field is the logical label; `extension_id` is `chrome.runtime.id` and must match
+the upgrade origin. The token must match the pending manager record. One extension
+directory and native ID can therefore serve multiple profiles with distinct
+logical labels. No logical name is written into a manifest. Bootstrap settings
+use `chrome.storage.session` to survive worker restarts; they disappear on browser
+restart or extension reload. Manager browser/target/session mappings remain in memory.
+
+A profile has one active logical connection. A link requesting another name or
+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.
+
+The manifest's `cdp` configuration supplies initial connection defaults:
+
+| 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
 using `reverse: true` or `cdp_ext: true` starts the shared server lazily, with the
 constructor's `reverse_server` settings. To mix direct and reverse browsers, leave the
@@ -615,7 +637,8 @@ 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.
-`cdp_ext: true` owns the launched process and applies normal launch preferences.
+`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.
 Closing the manager closes owned processes and the server, while external
 browsers and tabs remain open. The extension retries when the server returns;
 the next call rebuilds discovery and sessions, preserving surviving target IDs.
@@ -627,20 +650,11 @@ for that extension to reconnect; they do not spawn another process. Only the
 child process's confirmed exit permits a new launch. Explicit manager `close()`
 still terminates owned browsers.
 
-The current reverse registration uses a profile-specific extension copy. It does
-not assign a new logical name to an already running Chrome using a shared extension
-directory. Unpacked `chrome.runtime.id` identifies the extension path, not the
-user-data directory or browser executable. Shared-path registration and URL-based
-bootstrap are tracked in [TODO.md](TODO.md), not implemented behavior.
-
-Chrome's [process singleton](https://github.com/chromium/chromium/blob/main/chrome/browser/process_singleton.h)
-uses the user-data directory to decide whether to forward a new launch to an
-existing instance. `no-default-browser-check` only suppresses the default-browser
-prompt. The current Chromium [notification callback](https://github.com/chromium/chromium/blob/main/chrome/browser/chrome_browser_main.cc)
-rejects forwarding when either command line enables automation or uses headless
-mode. This library generates `enable-automation` by default; a normal browser
-started with `args['enable-automation']: false` can behave differently. Do not
-infer ownership of the real browser from a short-lived forwarding process.
+Chrome selects an existing instance by user-data directory. The minimal link
+opener preserves this normal behavior. Automation/headless flags can prevent
+forwarding; `no-default-browser-check` only suppresses a prompt. The short-lived
+launcher is `record.opener`; its exit is not proof of browser exit. Installed
+launches use `record.proc` instead.
 
 The [service-worker lifecycle](https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle)
 allows termination while offline. A 30-second Chrome alarm wakes the worker for
@@ -650,8 +664,8 @@ These are transport messages, not event buffering or polling of browser state.
 
 ### Reverse protocol and supported commands
 
-The first extension-to-server message is `{ "browser": "<extension ID>" }`. Subsequent
-messages use existing CDP envelopes:
+The first announcement contains `{ browser, extension_id, token }` for bootstrap,
+or the native extension ID for passive attachment. Subsequent messages use CDP envelopes:
 
 - Request: `{ id, method, params, sessionId? }`.
 - Response: `{ id, result }` or `{ id, error: { code, message } }`.
@@ -1273,6 +1287,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. |
@@ -1283,6 +1298,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
@@ -1544,8 +1631,8 @@ 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 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.reverse_sockets[browser_name]` | Announced socket (native extension ID for passive attachment); native on Deno, an EventTarget adapter on Bun. |
+| `record.extension_id`, `record.extension_path` | Observed native extension identity and, when installed by the manager, the copy's canonical directory. |
 | `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. |
@@ -1554,6 +1641,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. |
@@ -1602,7 +1690,10 @@ try {
 `browser.launch` builds arguments, starts the process, reads the
 DevTools WebSocket URL from stderr and returns `{ proc, url }`. With `cdp_ext: true`,
 it waits for process spawn instead and returns `url: undefined`; the caller must
-prepare the extension and supply its directory as `extension_path`.
+prepare the extension and supply its directory as `extension_path` when loading
+it. With `cdp_ext_install: false`, the helper skips the automation preset, uses
+the same option/argument/wildcard handling, and returns an unreferenced launcher.
+`bootstrap_url` is the optional startup URL, defaulting to `about:blank`.
 It does not open a CDP connection or write preference files; `update_preferences`, `preferences`
 and `local_state` are manager options, ignored by this helper.
 To prepare files independently, call
@@ -1641,6 +1732,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
@@ -1688,6 +1780,8 @@ The shared Deno/Bun reverse suite loads the real extension into two headless Chr
 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.
@@ -1706,5 +1800,10 @@ Managed-launch coverage checks concurrent first use, profile-specific identity,
 connection timeout without process replacement, lazy listener startup/shutdown
 independent of direct browsers, and relaunch after confirmed exit. External reverse
 timeouts release the listening port; other live reverse connections retain it.
+URL bootstrap also uses disposable normal Chrome profiles to check reuse of an
+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.

package/cdp.js

@@ -125,7 +125,10 @@ export class browser {
   }
 
   static build_args(options = {}) {
-    const args = {
+    const args = options.cdp_ext && options.cdp_ext_install === false ? {
+      'user-data-dir': options.user_data_dir,
+      'disable-features': [],
+    } : {
       'enable-automation': true,
       'mute-audio': true,
       'disable-blink-features': 'AutomationControlled',
@@ -264,10 +267,17 @@ export class browser {
         directory === '*' ? installed : directory,
       ))]
     }
-    const proc = child_process.spawn(options.executable_path || browser.find_executable_path(), [...util.args_to_strings(args), 'about:blank'], {
+    const external = options.cdp_ext && options.cdp_ext_install === false
+    const proc = child_process.spawn(options.executable_path || browser.find_executable_path(), [...util.args_to_strings(args), options.bootstrap_url ?? 'about:blank'], {
       windowsHide: options.windowsHide ?? (args.headless != null && args.headless !== false),
-      stdio: ['ignore', 'ignore', 'pipe'],
+      detached: external,
+      stdio: external ? 'ignore' : ['ignore', 'ignore', 'pipe'],
     })
+    if (external) {
+      await once(proc, 'spawn')
+      proc.unref()
+      return { proc }
+    }
     let diagnostic = ''
     const ready = util.on_first(proc, options.cdp_ext ? 'spawn exit' : 'ready exit', options.connect_timeout_ms ?? 15000)
     const data = chunk => {
@@ -359,11 +369,23 @@ export class cdp extends EventTarget {
     if (this.server) throw new Error('Reverse server is already listening')
     const accept = (socket, origin) => {
       socket.addEventListener('message', event => {
-        const id = JSON.parse(event.data).browser
-        if (id !== origin.slice('chrome-extension://'.length) ||
+        const message = JSON.parse(event.data)
+        const id = message.browser
+        const extension_id = message.extension_id ?? id
+        const record = this.browsers[id]
+        if (typeof id !== 'string' || extension_id !== origin.slice('chrome-extension://'.length) ||
+            (record?.reverse_token && message.token !== record.reverse_token) ||
+            (id !== extension_id && !record?.reverse_token) ||
             this.reverse_sockets[id]?.readyState < WebSocket.CLOSING) {
-          return socket.close(1008, 'Invalid or already connected extension ID')
+          return socket.close(1008, 'Invalid or already connected reverse browser')
+        }
+        if (message.error) {
+          const error = new Error(message.error)
+          if (record) record.reverse_error = error
+          util.emit(this, 'reverse_' + encodeURIComponent(id), error)
+          return socket.close(1008, 'Chrome profile already connected')
         }
+        if (record) record.extension_id = extension_id
         this.reverse_sockets[id] = socket
         socket.addEventListener('close', () => {
           if (this.reverse_sockets[id] === socket) delete this.reverse_sockets[id]
@@ -373,6 +395,9 @@ export class cdp extends EventTarget {
       }, { once: true })
     }
     const fetch = (request, server) => {
+      if (request.method === 'GET' && new URL(request.url).pathname === '/cdp_ext') {
+        return new Response('CDP.js browser connection')
+      }
       const origin = request.headers.get('origin')
       if (request.headers.get('upgrade') !== 'websocket' ||
           !origin?.startsWith('chrome-extension://')) {
@@ -594,6 +619,21 @@ export class cdp extends EventTarget {
     if (record.reverse || record.cdp_ext) {
       await this.server_closing
       if (!this.server) this.listen_reverse()
+      let host = this.server.addr.hostname
+      if (host === '0.0.0.0') host = '127.0.0.1'
+      if (host === '::') host = '::1'
+      const address = (host.includes(':') ? '[' + host + ']' : host) + ':' + this.server.addr.port
+      record.reverse_url = 'ws://' + address
+      if (record.cdp_ext) {
+        if (!['127.0.0.1', 'localhost', '::1'].includes(host)) throw new Error('URL bootstrap requires a loopback reverse listener')
+        record.reverse_token ??= crypto.randomUUID()
+        const bootstrap = new URL('http://' + address + '/cdp_ext')
+        bootstrap.searchParams.set('browser', record.name)
+        bootstrap.searchParams.set('websocket_url', record.reverse_url)
+        bootstrap.searchParams.set('token', record.reverse_token)
+        record.bootstrap_url = bootstrap.href
+      }
+      delete record.reverse_error
     }
     let url = record.websocket_url
     if (!record.reverse && !record.cdp_ext && !url && (record.http_url || record.port)) {
@@ -604,10 +644,12 @@ export class cdp extends EventTarget {
       url = (await response.json()).webSocketDebuggerUrl
     }
     if (record.cdp_ext || (!record.reverse && !url)) {
-      if (record.proc?.exitCode === null && record.proc.signalCode === null) url = record.socket?.url
+      const args = browser.build_args(record)
+      if (record.cdp_ext) record.cdp_ext_install ??= !!args['user-data-dir']
+      if ((record.proc?.exitCode === null && record.proc.signalCode === null) ||
+          (record.opener?.exitCode === null && record.opener.signalCode === null)) url = record.socket?.url
       else {
-        const args = browser.build_args(record)
-        if (record.cdp_ext) {
+        if (record.cdp_ext && record.cdp_ext_install) {
           record.extension_path = path.resolve(
             args['user-data-dir'] || path.join(this.base_path, record.name),
             args['profile-directory'] || 'Default',
@@ -617,10 +659,7 @@ export class cdp extends EventTarget {
           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'))
-          let host = this.server.addr.hostname
-          if (host === '0.0.0.0') host = '127.0.0.1'
-          if (host === '::') host = '::1'
-          manifest.cdp.websocket_url = 'ws://' + (host.includes(':') ? '[' + host + ']' : host) + ':' + this.server.addr.port
+          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'))
         }
@@ -635,17 +674,28 @@ export class cdp extends EventTarget {
             await browser.update_profile_preferences(path.join(args['user-data-dir'], 'Local State'), record.local_state)
           }
         }
-        const launched = await browser.launch(record)
-        record.proc = launched.proc
-        if (record.cdp_ext) record.proc.once('exit', () => this._close_reverse_if_idle())
-        url = launched.url
+        if (!record.cdp_ext || record.cdp_ext_install) {
+          const launched = await browser.launch(record)
+          record.proc = launched.proc
+          if (record.cdp_ext) record.proc.once('exit', () => this._close_reverse_if_idle())
+          url = launched.url
+        }
       }
     }
     if (record.reverse || record.cdp_ext) {
-      const id = record.extension_id ?? record.name
+      const id = record.cdp_ext ? record.name : record.extension_id ?? record.name
       url = this.reverse_sockets[id]
       if (url?.readyState !== WebSocket.OPEN) {
-        url = (await util.on_first(this, 'reverse_' + encodeURIComponent(id), record.connect_timeout_ms ?? 15000)).args[0].detail
+        if (record.cdp_ext && !record.cdp_ext_install &&
+            !(record.opener?.exitCode === null && record.opener.signalCode === null)) {
+          record.opener = (await browser.launch(record)).proc
+        }
+        if (record.reverse_error) throw record.reverse_error
+        url = this.reverse_sockets[id]
+        if (url?.readyState !== WebSocket.OPEN) {
+          url = (await util.on_first(this, 'reverse_' + encodeURIComponent(id), record.connect_timeout_ms ?? 15000)).args[0].detail
+        }
+        if (url instanceof Error) throw url
       }
     }
     const socket = record.socket = new jsrpc(url, record)
@@ -684,9 +734,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'
     }
@@ -720,6 +819,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',
@@ -779,7 +879,7 @@ export class cdp extends EventTarget {
     const { browser = 'main', target, ...native } = params
     const spec = typeof browser === 'string' ? { name: browser } : browser
     const record = this.browsers[spec.name] ??= {
-      user_data_dir: path.join(this.base_path, 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),
       ...this.options,
       ...spec,
       args: {
@@ -796,10 +896,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

@@ -1,4 +1,5 @@
 const config = chrome.runtime.getManifest().cdp ?? {}
+const configured = chrome.storage.session.get('cdp_bootstrap').then(value => Object.assign(config, value.cdp_bootstrap))
 const sessions = {}
 const attached = {}
 const attaching = {}
@@ -6,6 +7,50 @@ let socket
 let disconnecting
 let discovering = false
 let auto_attach = {}
+let bootstrapping
+
+async function bootstrap(tab) {
+  const text = tab.pendingUrl ?? tab.url ?? ''
+  if (!/^http:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?\/cdp_ext\?/.test(text)) return
+  const url = new URL(text)
+  const settings = {
+    browser: url.searchParams.get('browser'),
+    websocket_url: url.searchParams.get('websocket_url'),
+    token: url.searchParams.get('token'),
+  }
+  if (!settings.browser || !settings.websocket_url || !settings.token) return
+  const endpoint = new URL(settings.websocket_url)
+  if (endpoint.protocol !== 'ws:' || endpoint.host !== url.host) return
+  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()
+        })
+      }
+      await disconnecting
+    }
+    await connect()
+  })().finally(() => {
+    bootstrapping = null
+  })
+}
 
 function send(message) {
   if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message))
@@ -19,6 +64,7 @@ function target_info(tab) {
     url: tab.url ?? tab.pendingUrl ?? '',
     attached: !!attached[tab.id],
     incognito: tab.incognito,
+    groupId: tab.groupId,
   }
 }
 
@@ -159,12 +205,14 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
 })
 chrome.debugger.onDetach.addListener(detached)
 chrome.tabs.onCreated.addListener(tab => {
+  bootstrap(tab)
   if (discovering) send({
     method: 'Target.targetCreated',
     params: { targetInfo: target_info(tab) },
   })
 })
 chrome.tabs.onUpdated.addListener((id, changes, tab) => {
+  bootstrap(tab)
   if (discovering) send({
     method: 'Target.targetInfoChanged',
     params: { targetInfo: target_info(tab) },
@@ -195,12 +243,17 @@ for (const [name, options] of Object.entries({
   }), { urls: ['<all_urls>'] }, options)
 }
 
-function connect() {
+async function connect() {
+  await configured
   if (disconnecting) 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: chrome.runtime.id }))
+  connection.onopen = () => connection.send(JSON.stringify({
+    browser: config.browser ?? chrome.runtime.id,
+    extension_id: chrome.runtime.id,
+    token: config.token,
+  }))
   connection.onmessage = async event => {
     if (!event.data) return
     const request = JSON.parse(event.data)
@@ -256,8 +309,19 @@ function connect() {
   }
 }
 
-chrome.runtime.onStartup.addListener(connect)
+async function start() {
+  await configured
+  if (!config.browser) {
+    for (const tab of (await chrome.tabs.query({})).reverse()) {
+      if (config.browser) break
+      await bootstrap(tab)
+    }
+  }
+  await connect()
+}
+
+chrome.runtime.onStartup.addListener(start)
 chrome.alarms.onAlarm.addListener(connect)
 chrome.alarms.create('cdp-reconnect', { periodInMinutes: 0.5 })
 setInterval(connect, config.reconnect_ms ?? 5000)
-connect()
+start()

package/cdp_ext/manifest.json

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

package/package.json

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