opensteer 0.6.5 → 0.6.6

package/dist/{chunk-G6V2DJRN.js → chunk-H27BERRF.js}

@@ -7529,6 +7529,8 @@ import WebSocket2, { WebSocketServer } from "ws";
 var CDP_DISCOVERY_TIMEOUT_MS = 3e3;
 var LOCAL_PROXY_HOST = "127.0.0.1";
 var INTERNAL_COMMAND_ID_START = 1e9;
+var CREATE_BLANK_TARGET_COMMAND_ID = 1;
+var CREATE_BLANK_TARGET_TIMEOUT_MS = 5e3;
 async function discoverTargets(cdpUrl) {
   const baseUrl = resolveHttpDiscoveryBase(cdpUrl);
   const [targetsPayload, versionPayload] = await Promise.all([
@@ -7540,6 +7542,81 @@ async function discoverTargets(cdpUrl) {
     targets: readPageTargets(targetsPayload)
   };
 }
+function createBlankTarget(browserWsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket2(browserWsUrl);
+    let settled = false;
+    function settle(handler) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      ws.close();
+      handler();
+    }
+    const timeout = setTimeout(() => {
+      settle(
+        () => reject(new Error("Timed out creating a blank tab via CDP."))
+      );
+    }, CREATE_BLANK_TARGET_TIMEOUT_MS);
+    ws.once("open", () => {
+      ws.send(
+        JSON.stringify({
+          id: CREATE_BLANK_TARGET_COMMAND_ID,
+          method: "Target.createTarget",
+          params: { url: "about:blank" }
+        })
+      );
+    });
+    ws.on("message", (data, isBinary) => {
+      if (isBinary) {
+        return;
+      }
+      const message = parseMessage(data);
+      if (!message || asNumber(message.id) !== CREATE_BLANK_TARGET_COMMAND_ID) {
+        return;
+      }
+      const cdpError = asObject(message.error);
+      if (cdpError) {
+        settle(
+          () => reject(
+            new Error(
+              `Target.createTarget failed: ${asString(cdpError.message) ?? JSON.stringify(cdpError)}`
+            )
+          )
+        );
+        return;
+      }
+      const targetId = asString(asObject(message.result)?.targetId);
+      if (targetId) {
+        settle(() => resolve(targetId));
+        return;
+      }
+      settle(
+        () => reject(
+          new Error(
+            "Target.createTarget succeeded but no targetId was returned."
+          )
+        )
+      );
+    });
+    ws.once("error", (err) => {
+      settle(
+        () => reject(new Error(`Failed to create blank tab: ${errorMessage(err)}`))
+      );
+    });
+    ws.once("close", () => {
+      settle(
+        () => reject(
+          new Error(
+            "CDP browser websocket closed before blank tab creation completed."
+          )
+        )
+      );
+    });
+  });
+}
 var CDPProxy = class {
   constructor(browserWsUrl, targetId) {
     this.browserWsUrl = browserWsUrl;
@@ -7947,12 +8024,13 @@ var BrowserPool = class {
     let cdpProxy = null;
     try {
       const { browserWsUrl, targets } = await discoverTargets(cdpUrl);
-      if (targets.length === 0) {
-        throw new Error(
-          "No page targets found. Is the browser running with an open window?"
-        );
+      let targetId;
+      if (targets.length > 0) {
+        targetId = targets[0].id;
+      } else {
+        targetId = await createBlankTarget(browserWsUrl);
       }
-      cdpProxy = new CDPProxy(browserWsUrl, targets[0].id);
+      cdpProxy = new CDPProxy(browserWsUrl, targetId);
       const proxyWsUrl = await cdpProxy.start();
       browser = await chromium.connectOverCDP(proxyWsUrl, {
         timeout: timeout ?? 3e4

package/dist/cli/profile.cjs

@@ -1336,6 +1336,8 @@ var import_ws = __toESM(require("ws"), 1);
 var CDP_DISCOVERY_TIMEOUT_MS = 3e3;
 var LOCAL_PROXY_HOST = "127.0.0.1";
 var INTERNAL_COMMAND_ID_START = 1e9;
+var CREATE_BLANK_TARGET_COMMAND_ID = 1;
+var CREATE_BLANK_TARGET_TIMEOUT_MS = 5e3;
 async function discoverTargets(cdpUrl) {
   const baseUrl = resolveHttpDiscoveryBase(cdpUrl);
   const [targetsPayload, versionPayload] = await Promise.all([
@@ -1347,6 +1349,81 @@ async function discoverTargets(cdpUrl) {
     targets: readPageTargets(targetsPayload)
   };
 }
+function createBlankTarget(browserWsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new import_ws.default(browserWsUrl);
+    let settled = false;
+    function settle(handler) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      ws.close();
+      handler();
+    }
+    const timeout = setTimeout(() => {
+      settle(
+        () => reject(new Error("Timed out creating a blank tab via CDP."))
+      );
+    }, CREATE_BLANK_TARGET_TIMEOUT_MS);
+    ws.once("open", () => {
+      ws.send(
+        JSON.stringify({
+          id: CREATE_BLANK_TARGET_COMMAND_ID,
+          method: "Target.createTarget",
+          params: { url: "about:blank" }
+        })
+      );
+    });
+    ws.on("message", (data, isBinary) => {
+      if (isBinary) {
+        return;
+      }
+      const message = parseMessage(data);
+      if (!message || asNumber(message.id) !== CREATE_BLANK_TARGET_COMMAND_ID) {
+        return;
+      }
+      const cdpError = asObject(message.error);
+      if (cdpError) {
+        settle(
+          () => reject(
+            new Error(
+              `Target.createTarget failed: ${asString(cdpError.message) ?? JSON.stringify(cdpError)}`
+            )
+          )
+        );
+        return;
+      }
+      const targetId = asString(asObject(message.result)?.targetId);
+      if (targetId) {
+        settle(() => resolve(targetId));
+        return;
+      }
+      settle(
+        () => reject(
+          new Error(
+            "Target.createTarget succeeded but no targetId was returned."
+          )
+        )
+      );
+    });
+    ws.once("error", (err) => {
+      settle(
+        () => reject(new Error(`Failed to create blank tab: ${errorMessage(err)}`))
+      );
+    });
+    ws.once("close", () => {
+      settle(
+        () => reject(
+          new Error(
+            "CDP browser websocket closed before blank tab creation completed."
+          )
+        )
+      );
+    });
+  });
+}
 var CDPProxy = class {
   constructor(browserWsUrl, targetId) {
     this.browserWsUrl = browserWsUrl;
@@ -1830,12 +1907,13 @@ var BrowserPool = class {
     let cdpProxy = null;
     try {
       const { browserWsUrl, targets } = await discoverTargets(cdpUrl);
-      if (targets.length === 0) {
-        throw new Error(
-          "No page targets found. Is the browser running with an open window?"
-        );
+      let targetId;
+      if (targets.length > 0) {
+        targetId = targets[0].id;
+      } else {
+        targetId = await createBlankTarget(browserWsUrl);
       }
-      cdpProxy = new CDPProxy(browserWsUrl, targets[0].id);
+      cdpProxy = new CDPProxy(browserWsUrl, targetId);
       const proxyWsUrl = await cdpProxy.start();
       browser = await import_playwright.chromium.connectOverCDP(proxyWsUrl, {
         timeout: timeout ?? 3e4

package/dist/cli/profile.js

@@ -7,7 +7,7 @@ import {
 } from "../chunk-54KNQTOL.js";
 import {
   Opensteer
-} from "../chunk-G6V2DJRN.js";
+} from "../chunk-H27BERRF.js";
 import {
   resolveConfigWithEnv
 } from "../chunk-KPPOTU3D.js";

package/dist/cli/server.cjs

@@ -437,6 +437,8 @@ var import_ws = __toESM(require("ws"), 1);
 var CDP_DISCOVERY_TIMEOUT_MS = 3e3;
 var LOCAL_PROXY_HOST = "127.0.0.1";
 var INTERNAL_COMMAND_ID_START = 1e9;
+var CREATE_BLANK_TARGET_COMMAND_ID = 1;
+var CREATE_BLANK_TARGET_TIMEOUT_MS = 5e3;
 async function discoverTargets(cdpUrl) {
   const baseUrl = resolveHttpDiscoveryBase(cdpUrl);
   const [targetsPayload, versionPayload] = await Promise.all([
@@ -448,6 +450,81 @@ async function discoverTargets(cdpUrl) {
     targets: readPageTargets(targetsPayload)
   };
 }
+function createBlankTarget(browserWsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new import_ws.default(browserWsUrl);
+    let settled = false;
+    function settle(handler) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      ws.close();
+      handler();
+    }
+    const timeout = setTimeout(() => {
+      settle(
+        () => reject(new Error("Timed out creating a blank tab via CDP."))
+      );
+    }, CREATE_BLANK_TARGET_TIMEOUT_MS);
+    ws.once("open", () => {
+      ws.send(
+        JSON.stringify({
+          id: CREATE_BLANK_TARGET_COMMAND_ID,
+          method: "Target.createTarget",
+          params: { url: "about:blank" }
+        })
+      );
+    });
+    ws.on("message", (data, isBinary) => {
+      if (isBinary) {
+        return;
+      }
+      const message = parseMessage(data);
+      if (!message || asNumber(message.id) !== CREATE_BLANK_TARGET_COMMAND_ID) {
+        return;
+      }
+      const cdpError = asObject(message.error);
+      if (cdpError) {
+        settle(
+          () => reject(
+            new Error(
+              `Target.createTarget failed: ${asString(cdpError.message) ?? JSON.stringify(cdpError)}`
+            )
+          )
+        );
+        return;
+      }
+      const targetId = asString(asObject(message.result)?.targetId);
+      if (targetId) {
+        settle(() => resolve(targetId));
+        return;
+      }
+      settle(
+        () => reject(
+          new Error(
+            "Target.createTarget succeeded but no targetId was returned."
+          )
+        )
+      );
+    });
+    ws.once("error", (err) => {
+      settle(
+        () => reject(new Error(`Failed to create blank tab: ${errorMessage(err)}`))
+      );
+    });
+    ws.once("close", () => {
+      settle(
+        () => reject(
+          new Error(
+            "CDP browser websocket closed before blank tab creation completed."
+          )
+        )
+      );
+    });
+  });
+}
 var CDPProxy = class {
   constructor(browserWsUrl, targetId) {
     this.browserWsUrl = browserWsUrl;
@@ -931,12 +1008,13 @@ var BrowserPool = class {
     let cdpProxy = null;
     try {
       const { browserWsUrl, targets } = await discoverTargets(cdpUrl);
-      if (targets.length === 0) {
-        throw new Error(
-          "No page targets found. Is the browser running with an open window?"
-        );
+      let targetId;
+      if (targets.length > 0) {
+        targetId = targets[0].id;
+      } else {
+        targetId = await createBlankTarget(browserWsUrl);
       }
-      cdpProxy = new CDPProxy(browserWsUrl, targets[0].id);
+      cdpProxy = new CDPProxy(browserWsUrl, targetId);
       const proxyWsUrl = await cdpProxy.start();
       browser = await import_playwright.chromium.connectOverCDP(proxyWsUrl, {
         timeout: timeout ?? 3e4

package/dist/cli/server.js

@@ -1,6 +1,6 @@
 import {
   Opensteer
-} from "../chunk-G6V2DJRN.js";
+} from "../chunk-H27BERRF.js";
 import {
   normalizeError,
   resolveCloudSelection,

package/dist/index.cjs

@@ -528,6 +528,8 @@ var import_ws = __toESM(require("ws"), 1);
 var CDP_DISCOVERY_TIMEOUT_MS = 3e3;
 var LOCAL_PROXY_HOST = "127.0.0.1";
 var INTERNAL_COMMAND_ID_START = 1e9;
+var CREATE_BLANK_TARGET_COMMAND_ID = 1;
+var CREATE_BLANK_TARGET_TIMEOUT_MS = 5e3;
 async function discoverTargets(cdpUrl) {
   const baseUrl = resolveHttpDiscoveryBase(cdpUrl);
   const [targetsPayload, versionPayload] = await Promise.all([
@@ -539,6 +541,81 @@ async function discoverTargets(cdpUrl) {
     targets: readPageTargets(targetsPayload)
   };
 }
+function createBlankTarget(browserWsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new import_ws.default(browserWsUrl);
+    let settled = false;
+    function settle(handler) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      ws.close();
+      handler();
+    }
+    const timeout = setTimeout(() => {
+      settle(
+        () => reject(new Error("Timed out creating a blank tab via CDP."))
+      );
+    }, CREATE_BLANK_TARGET_TIMEOUT_MS);
+    ws.once("open", () => {
+      ws.send(
+        JSON.stringify({
+          id: CREATE_BLANK_TARGET_COMMAND_ID,
+          method: "Target.createTarget",
+          params: { url: "about:blank" }
+        })
+      );
+    });
+    ws.on("message", (data, isBinary) => {
+      if (isBinary) {
+        return;
+      }
+      const message = parseMessage(data);
+      if (!message || asNumber(message.id) !== CREATE_BLANK_TARGET_COMMAND_ID) {
+        return;
+      }
+      const cdpError = asObject(message.error);
+      if (cdpError) {
+        settle(
+          () => reject(
+            new Error(
+              `Target.createTarget failed: ${asString(cdpError.message) ?? JSON.stringify(cdpError)}`
+            )
+          )
+        );
+        return;
+      }
+      const targetId = asString(asObject(message.result)?.targetId);
+      if (targetId) {
+        settle(() => resolve(targetId));
+        return;
+      }
+      settle(
+        () => reject(
+          new Error(
+            "Target.createTarget succeeded but no targetId was returned."
+          )
+        )
+      );
+    });
+    ws.once("error", (err) => {
+      settle(
+        () => reject(new Error(`Failed to create blank tab: ${errorMessage(err)}`))
+      );
+    });
+    ws.once("close", () => {
+      settle(
+        () => reject(
+          new Error(
+            "CDP browser websocket closed before blank tab creation completed."
+          )
+        )
+      );
+    });
+  });
+}
 var CDPProxy = class {
   constructor(browserWsUrl, targetId) {
     this.browserWsUrl = browserWsUrl;
@@ -1022,12 +1099,13 @@ var BrowserPool = class {
     let cdpProxy = null;
     try {
       const { browserWsUrl, targets } = await discoverTargets(cdpUrl);
-      if (targets.length === 0) {
-        throw new Error(
-          "No page targets found. Is the browser running with an open window?"
-        );
+      let targetId;
+      if (targets.length > 0) {
+        targetId = targets[0].id;
+      } else {
+        targetId = await createBlankTarget(browserWsUrl);
       }
-      cdpProxy = new CDPProxy(browserWsUrl, targets[0].id);
+      cdpProxy = new CDPProxy(browserWsUrl, targetId);
       const proxyWsUrl = await cdpProxy.start();
       browser = await import_playwright.chromium.connectOverCDP(proxyWsUrl, {
         timeout: timeout ?? 3e4

package/dist/index.js

@@ -78,7 +78,7 @@ import {
   switchTab,
   typeText,
   waitForVisualStability
-} from "./chunk-G6V2DJRN.js";
+} from "./chunk-H27BERRF.js";
 import {
   CloudCdpClient,
   CloudSessionClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensteer",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Open-source browser automation SDK and CLI that lets AI agents build complex scrapers directly in your codebase.",
   "license": "MIT",
   "type": "module",

package/skills/electron/SKILL.md

@@ -12,14 +12,14 @@ Read [opensteer-electron-workflow.md](references/opensteer-electron-workflow.md)
 ## Core Workflow
 
 1. Launch the Electron app with `--remote-debugging-port=<port>`.
-2. Connect Opensteer with `open --connect-url http://127.0.0.1:<port>`.
+2. Connect Opensteer with `open --cdp-url http://127.0.0.1:<port>`.
 3. List windows/webviews with `tabs`, then switch with `tab-switch`.
 4. Run `snapshot action`, interact (`click`, `input`, `press`), then re-snapshot.
 5. Use `snapshot extraction` and `extract` for structured data.
 
 ```bash
 # Connect Opensteer to a running Electron app on port 9222
-opensteer open --connect-url http://127.0.0.1:9222 --session slack-desktop --name slack-desktop
+opensteer open --cdp-url http://127.0.0.1:9222 --session slack-desktop --name slack-desktop
 
 # Discover available windows/webviews
 opensteer tabs --session slack-desktop
@@ -65,8 +65,8 @@ Use `--description` when possible so selector paths persist for replay.
 Use one Opensteer session per app:
 
 ```bash
-opensteer open --connect-url http://127.0.0.1:9222 --session slack --name slack-electron
-opensteer open --connect-url http://127.0.0.1:9223 --session vscode --name vscode-electron
+opensteer open --cdp-url http://127.0.0.1:9222 --session slack --name slack-electron
+opensteer open --cdp-url http://127.0.0.1:9223 --session vscode --name vscode-electron
 
 opensteer snapshot action --session slack
 opensteer snapshot action --session vscode
@@ -78,6 +78,8 @@ opensteer snapshot action --session vscode
 - Re-snapshot after each navigation or large UI change before reusing counters.
 - Keep `--name` stable inside a session for deterministic selector replay.
 - Close sessions when done: `opensteer close --session <id>`.
+- If the app has no visible page targets, Opensteer creates one automatically.
+- If `--cdp-url` connection fails, verify with `curl -s http://127.0.0.1:<port>/json/version`.
 
 ## References
 

package/skills/electron/references/opensteer-electron-recipes.md

@@ -29,7 +29,7 @@ curl -s http://127.0.0.1:9222/json/version
 ## Connect and Select Target
 
 ```bash
-opensteer open --connect-url http://127.0.0.1:9222 --session electron --name electron
+opensteer open --cdp-url http://127.0.0.1:9222 --session electron --name electron
 opensteer tabs --session electron
 opensteer tab-switch 0 --session electron
 opensteer snapshot action --session electron
@@ -63,10 +63,10 @@ opensteer extract '{"items":[{"title":{"element":15},"meta":{"element":16}}]}' \
 
 ```bash
 # Slack
-opensteer open --connect-url http://127.0.0.1:9222 --session slack --name slack-electron
+opensteer open --cdp-url http://127.0.0.1:9222 --session slack --name slack-electron
 
 # VS Code
-opensteer open --connect-url http://127.0.0.1:9223 --session vscode --name vscode-electron
+opensteer open --cdp-url http://127.0.0.1:9223 --session vscode --name vscode-electron
 
 opensteer snapshot action --session slack
 opensteer snapshot action --session vscode
@@ -84,3 +84,5 @@ opensteer snapshot action --session vscode
   - UI changed and counters are stale; take a fresh `snapshot action`.
 - Wrong selectors on replay:
   - `--description` string differs from the original text; use exact wording.
+- Connection works but extraction returns empty:
+  - The Electron app may render in a webview. Use `opensteer tabs` + `opensteer tab-switch` to find the correct target.

package/skills/electron/references/opensteer-electron-workflow.md

@@ -7,12 +7,12 @@ This document describes the Opensteer-native flow for automating Electron apps.
 Electron apps embed Chromium. Opensteer connects through Chrome DevTools Protocol (CDP):
 
 - Launch app with `--remote-debugging-port=<port>`
-- Attach with `opensteer open --connect-url http://127.0.0.1:<port>`
+- Attach with `opensteer open --cdp-url http://127.0.0.1:<port>`
 
 Example:
 
 ```bash
-opensteer open --connect-url http://127.0.0.1:9222 --session electron --name electron
+opensteer open --cdp-url http://127.0.0.1:9222 --session electron --name electron
 ```
 
 `--session` controls runtime routing (which daemon/browser instance handles commands).

package/skills/opensteer/SKILL.md

@@ -166,11 +166,22 @@ Run with: `npx tsx scraper.ts`
 
 ## Edge Cases
 
-**Connect to an existing browser (CDP):**
+**Connect to a running browser (CDP):**
 ```bash
-opensteer open --connect-url http://localhost:9222 --name "my-scraper"
-# Verify CDP is running: curl -s http://127.0.0.1:9222/json/version
+# Verify CDP is reachable first:
+curl -s http://127.0.0.1:9222/json/version
+
+# Connect (works even if Chrome has zero open tabs):
+opensteer open --cdp-url http://localhost:9222 --name "my-scraper"
+```
+
+**Real browser mode (your actual Chrome profile):**
+```bash
+opensteer open https://example.com --browser real --name "my-scraper"            # headless
+opensteer open https://example.com --browser real --headed --name "my-scraper"   # visible window
+opensteer open https://example.com --browser real --profile "Profile 1" --headed # specific profile
 ```
+`--browser real` clones your local Chrome profile. Defaults to headless — add `--headed` to see the window. Profile cloning takes several seconds; do not assume the command hung.
 
 **Tab management:**
 ```bash
@@ -184,6 +195,9 @@ opensteer tab-close 1
 1. SPA content not loaded — add `opensteer.waitForText()` before extraction.
 2. Missing cache — re-run Phase 1 caching step for the page type that failed.
 3. Obstacle blocking target — cookie banner, modal, or login wall. Dismiss it first.
+4. Timeout on navigation — increase timeout: `opensteer navigate <url> --timeout 60000`.
+5. CDP connection refused — verify `curl -s http://127.0.0.1:<port>/json/version` returns JSON.
+6. Stale counters — take a fresh `snapshot action` and re-identify elements.
 
 ### Advanced: Direct Page Access (rare)
 

package/skills/opensteer/references/cli-reference.md

@@ -16,7 +16,10 @@ Global flags: `--session <id>`, `--name <namespace>`, `--headless`, `--descripti
 opensteer open <url>                                # Open browser, navigate to URL
 opensteer open <url> --name "my-scraper"            # Set selector cache namespace
 opensteer open <url> --headless                     # Headless mode
-opensteer open --connect-url http://localhost:9222   # Connect to running browser
+opensteer open --cdp-url http://localhost:9222        # Connect to running browser via CDP
+opensteer open <url> --browser real                   # Use real Chrome profile (headless)
+opensteer open <url> --browser real --headed           # Real Chrome, visible window
+opensteer open <url> --browser real --profile "Work"   # Specific Chrome profile
 opensteer navigate <url>                            # Navigate with visual stability wait
 opensteer navigate <url> --timeout 60000            # Custom timeout (default 30s)
 opensteer back                                      # Go back in history