@mefistofelix/cdp.js 0.4.0 → 0.5.1

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.
 
@@ -189,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.
 
@@ -225,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. |
@@ -242,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`. |
@@ -492,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
@@ -513,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',
@@ -521,65 +523,98 @@ 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) 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.
+
+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.
+
+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
+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). 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 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 |
+| --- | --- | --- |
+| `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
@@ -616,7 +651,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.
@@ -628,20 +664,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
@@ -649,10 +676,20 @@ 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.
+
 ### Reverse protocol and supported commands
 
-The first extension-to-server message is `{ "browser": "<extension ID>" }`. Subsequent
-messages use existing 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 } }`.
@@ -1618,8 +1655,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. |
@@ -1677,7 +1714,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
@@ -1784,5 +1824,16 @@ 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.
+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 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',
@@ -150,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',
@@ -174,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'
@@ -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',
@@ -616,12 +658,7 @@ 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'))
-          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
-          await fs.writeFile(path.join(record.extension_path, 'manifest.json'), JSON.stringify(manifest))
+          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'))
         }
         if (args['user-data-dir'] && record.update_preferences !== false) {
@@ -635,17 +672,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)
@@ -829,7 +877,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: {

package/cdp_ext/cdp_ext.js

@@ -1,4 +1,7 @@
-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 = {}
 const attaching = {}
@@ -6,6 +9,58 @@ let socket
 let disconnecting
 let discovering = false
 let auto_attach = {}
+let bootstrapping
+let checking = false
+let connection_message
+
+function report_connection(message) {
+  if (connection_message === message) return
+  connection_message = message
+  console.info('[cdp_ext] ' + message)
+}
+
+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))
@@ -160,12 +215,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) },
@@ -196,12 +253,45 @@ for (const [name, options] of Object.entries({
   }), { urls: ['<all_urls>'] }, options)
 }
 
-function connect() {
-  if (disconnecting) return
+async function connect() {
+  await configured
+  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: chrome.runtime.id }))
+  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)
@@ -248,6 +338,7 @@ function connect() {
     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) }
@@ -257,8 +348,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()
+setInterval(connect, config.reconnect_ms)
+start()

package/cdp_ext/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "CDP reverse connection",
-  "version": "0.2.0",
+  "version": "0.5.1",
   "minimum_chrome_version": "125",
   "permissions": [
     "accessibilityFeatures.read",
@@ -68,9 +68,5 @@
   "incognito": "spanning",
   "background": {
     "service_worker": "cdp_ext.js"
-  },
-  "cdp": {
-    "websocket_url": "ws://127.0.0.1:9223",
-    "reconnect_ms": 5000
   }
 }

package/package.json

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