@mefistofelix/cdp.js 0.1.0 → 0.1.2

package/README.md

@@ -199,6 +199,7 @@ local configuration.
 | `user_data_dir` | absolute path string, `<base_path>/<name>` | Chromium user-data directory containing profiles such as `Default`. The generated default is absolute; explicit overrides should be absolute too. |
 | `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. |
 | `extensions` | boolean, `false` | When true, omit the two extension-disabling switches; does not install extensions. |
 | `images` | boolean, `true` | When false, request `blink-settings: 'imagesEnabled=false'`; controls loading, not image processing. |
 | `translations` | boolean, `false` | Set translation preferences and, unless true, disable translation feature IDs. |
@@ -207,6 +208,7 @@ local configuration.
 | `preferences` | object, `{}` | Dotted JSON preference overrides applied after generated preference defaults. |
 | `connect_timeout_ms` | number, `15000` | Timeout for each discovery, launch-readiness or socket-opening wait; not one combined deadline. |
 | `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. |
 | `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`. |
@@ -458,6 +460,8 @@ writes with a running browser, which may overwrite the file itself.
 | --- | --- |
 | `headless: true` plus `args.headless: false` | Omit `--headless`; the generated window-size argument remains unless also overridden. |
 | `headless: false` plus `args.headless: 'new'` | Send `--headless=new`; no automatic headless window-size default was generated. |
+| `windowsHide` omitted plus a raw `args.headless` override | Follow the effective `--headless` switch after the override. |
+| Explicit `windowsHide: true` or `false` | Pass that value to Node's `spawn`, regardless of headless mode. |
 | `extensions: true` plus `args['disable-extensions']: true` | The raw extension-disabling switch still wins. |
 | `extensions: false` plus only `args['disable-extensions']: false` | Remove that flag, but retain `disable-component-extensions-with-background-pages`. Use `extensions: true` to omit both generated flags. |
 | `images: false` plus an overridden `blink-settings` | Replace the whole string; image disabling is not appended to the caller's value. |
@@ -534,8 +538,35 @@ 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
 changes. `initialize: false` skips binding installation too;
-`Runtime.runIfWaitingForDebugger` is still sent at the end. Auto-attachment uses
-`waitForDebuggerOnStart: false`.
+`Runtime.runIfWaitingForDebugger` is still sent at the end. The browser option
+`waitForDebuggerOnStart` defaults to `false`. With `true`, auto-attachment requests
+a pause. Bootstrap setup sends `Runtime.disable` before the resume command.
+To ensure setup completes before navigating, keep the initial `about:blank` and
+use `Page.navigate` afterward, as below. The pause flag alone does not guarantee
+that a URL supplied through `create_params.url` waits for setup; Chromium can
+execute that navigation's scripts during initialization.
+
+Set this option in constructor browser defaults or in `params.browser`:
+
+```js
+await client.call({
+  method: 'Page.navigate',
+  params: {
+    browser: {
+      name: 'paused',
+      waitForDebuggerOnStart: true,
+    },
+    target: 'page',
+    url: 'https://example.com/',
+  },
+})
+```
+
+The setting affects auto-attachment across that browser connection. Only targets
+selected through `params.target` receive setup and automatic resume. Other newly
+auto-attached tabs can remain paused: select their physical ID using
+`params.target.targetId`, or send `Runtime.runIfWaitingForDebugger` through the
+browser socket with their `sessionId`.
 
 Setup CDP errors are collected as strings in `target.setup_errors`, allowing the
 sequence to continue when a browser/target does not support a setup command.
@@ -822,8 +853,8 @@ workflow for detecting new conversations and extracting connector session handle
 from tool-call history. It is a caller-side recipe, not additional library API.
 
 For npm packaging, account setup, and GitHub publishing, see
-[Publishing](npm/PUBLISHING.md). `build.bat` prepares the package on Windows;
-`node npm/prepare.mjs` prepares its files on any supported Node platform.
+[Publishing](npm/PUBLISHING.md). Publishing only copies `cdp.js` and this README
+into `npm/` alongside its manifest; no build script is needed.
 
 ```sh
 node --check cdp.js

package/cdp.js

@@ -209,7 +209,7 @@ export class browser {
       ...options.preferences,
     })
     const proc = child_process.spawn(options.executable_path || browser.find_executable_path(), [...util.args_to_strings(args), 'about:blank'], {
-      windowsHide: true,
+      windowsHide: options.windowsHide ?? (args.headless != null && args.headless !== false),
       stdio: ['ignore', 'ignore', 'pipe'],
     })
     let diagnostic = ''
@@ -386,7 +386,7 @@ export class cdp extends EventTarget {
       params: {
         autoAttach: true,
         flatten: true,
-        waitForDebuggerOnStart: false,
+        waitForDebuggerOnStart: record.waitForDebuggerOnStart ?? false,
       },
     })
     await socket.req({

package/package.json

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