browser-ctl 0.2.12__tar.gz → 0.2.13__tar.gz

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browser-ctl
-Version: 0.2.12
+Version: 0.2.13
 Summary: Control your browser from the command line via a Chrome extension + WebSocket bridge
 Author-email: geb <853934146@qq.com>
 License-Expression: MIT

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/browser_ctl/SKILL.md

@@ -59,9 +59,10 @@ bctl click <sel> [-i N] [-t text]    Click element; -t filters by visible text
 bctl dblclick <sel> [-i N] [-t text] Double-click
 bctl hover <sel> [-i N] [-t text]    Hover (triggers mouseover)
 bctl focus <sel> [-i N] [-t text]    Focus element
-bctl type <sel> <text>               Type text (replaces existing; React-compatible)
+bctl type <sel> <text>               Type text (replaces existing; React/Vue compatible)
 bctl input-text <sel> <text> [--clear] [--delay ms]  Char-by-char (rich editors)
 bctl press <key>                     Press key: Enter, Escape, Tab, ArrowDown, etc.
+                                     (includes keyCode/which for Vue 2 & jQuery compat)
 bctl check <sel> [-i N] [-t text]    Check checkbox/radio
 bctl uncheck <sel> [-i N] [-t text]  Uncheck checkbox
 bctl scroll <dir|sel> [n]            Scroll: up/down/top/bottom/<selector> [pixels]
@@ -186,6 +187,15 @@ bctl assert-url "/releases/tag/vX.Y.Z" --mode includes
 Then confirm automation side effects separately (e.g. Actions run appears/completes,
 and PyPI shows the new version).
 
+### Chat / AI UIs
+For chat interfaces (ChatGPT, Gemini, internal AI tools, etc.), use `type` + `press Enter`
+as the simplest send pattern — no need to find the send button:
+```bash
+bctl type "#input" "your prompt here"
+bctl press Enter
+```
+Then poll for completion: `bctl wait 5 && bctl count ".response"` in a loop.
+
 ### Waiting Strategy
 - After navigation: `bctl wait 2-3` or `bctl wait "<selector>" 10`
 - After hover for overlay: `bctl wait 1`
@@ -289,6 +299,13 @@ Use this sequence on any site:
 - `screenshot` captures visible viewport only — scroll for full-page capture
 - Without `-i`, `click` always hits the FIRST match — use `count` to check first
 
+## Resilience Notes
+
+- **`click` auto force-clicks** when the element is visible and enabled but obscured by
+  an overlay or fails hit-test. No need for `eval` workarounds on tricky UIs.
+- **`press` includes `keyCode`/`which`** for all common keys, so `@keydown.enter` handlers
+  in Vue 2, jQuery `.on("keydown")`, and legacy `e.keyCode` checks all work correctly.
+
 ## Error Handling
 
 - `bctl ping` shows `"extension": false` → user must check Chrome and the extension

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/browser_ctl/extension/actions.js

@@ -11,6 +11,22 @@ import { contentScriptHandler } from "./content-script.js";
 // Shared helpers
 // =========================================================================
 
+/**
+ * Get the ID of the last-focused normal Chrome window.
+ * Returns null when Chrome has no normal windows (e.g. background-only on macOS).
+ */
+async function getLastFocusedNormalWindowId() {
+  try {
+    const win = await chrome.windows.getLastFocused({ windowTypes: ["normal"] });
+    if (win && win.id !== chrome.windows.WINDOW_ID_NONE) return win.id;
+  } catch (_) {}
+  try {
+    const all = await chrome.windows.getAll({ windowTypes: ["normal"] });
+    if (all.length > 0) return all[0].id;
+  } catch (_) {}
+  return null;
+}
+
 /** Get the currently active tab. */
 export async function activeTab(context = {}) {
   if (context.tabId !== undefined && context.tabId !== null) {
@@ -21,10 +37,9 @@ export async function activeTab(context = {}) {
   if (context.windowId !== undefined && context.windowId !== null) {
     query.windowId = context.windowId;
   } else {
-    // In service workers, currentWindow is unreliable — use lastFocusedWindow
-    const focusedWindow = await chrome.windows.getLastFocused({ windowTypes: ["normal"] });
-    if (focusedWindow) {
-      query.windowId = focusedWindow.id;
+    const windowId = await getLastFocusedNormalWindowId();
+    if (windowId !== null) {
+      query.windowId = windowId;
     } else {
       query.currentWindow = true;
     }
@@ -196,9 +211,26 @@ export async function doBatch(params, context = extractExecutionContext(params))
 export async function doNavigate(params, context = extractExecutionContext(params)) {
   const url = params.url;
   if (!url) throw new Error("Missing 'url' parameter");
-  const tab = await activeTab(context);
+
+  let tab;
+  try {
+    tab = await activeTab(context);
+  } catch (_) {
+    // No active tab / no window — create a new window with the URL
+    const newWindow = await chrome.windows.create({ url });
+    const tabs = await chrome.tabs.query({ active: true, windowId: newWindow.id });
+    tab = tabs[0];
+    if (tab) {
+      const loadResult = await waitForTabLoad(tab.id, 5000);
+      if (loadResult.loaded) {
+        const updated = await getTabOrThrow(tab.id);
+        return { url: updated.url, title: updated.title };
+      }
+    }
+    return { url, title: "" };
+  }
+
   await chrome.tabs.update(tab.id, { url });
-  // Short wait — avoid long blocking that causes SW termination
   const loadResult = await waitForTabLoad(tab.id, 5000);
   if (!loadResult.loaded) {
     return { url, title: "" };
@@ -246,7 +278,11 @@ export async function doReload(params = {}, context = extractExecutionContext(pa
 
 export async function doTabs() {
   const tabs = await chrome.tabs.query({});
-  const focusedWindow = await chrome.windows.getLastFocused();
+  let focusedWindowId = null;
+  try {
+    const focusedWindow = await chrome.windows.getLastFocused();
+    focusedWindowId = focusedWindow?.id ?? null;
+  } catch (_) {}
   return {
     tabs: tabs.map((t) => ({
       id: t.id,
@@ -255,7 +291,7 @@ export async function doTabs() {
       active: t.active,
       windowId: t.windowId,
     })),
-    focusedWindowId: focusedWindow.id,
+    focusedWindowId,
   };
 }
 
@@ -275,11 +311,38 @@ export async function doSwitchTab(params) {
 }
 
 export async function doNewTab(params) {
-  const createOpts = { url: params.url || "about:blank" };
-  if (params.windowId) createOpts.windowId = params.windowId;
-  const tab = await chrome.tabs.create(createOpts);
+  const url = params.url || "about:blank";
+  const createOpts = { url };
+  if (params.windowId) {
+    createOpts.windowId = params.windowId;
+  } else {
+    const windowId = await getLastFocusedNormalWindowId();
+    if (windowId !== null) {
+      createOpts.windowId = windowId;
+    }
+  }
+
+  let tab;
+  try {
+    tab = await chrome.tabs.create(createOpts);
+  } catch (_) {
+    // No window available — create a new window with the tab
+    const newWindow = await chrome.windows.create({ url });
+    const tabs = await chrome.tabs.query({ active: true, windowId: newWindow.id });
+    tab = tabs[0];
+    if (!tab) throw new Error("Failed to create new window");
+    if (params.url) {
+      const loadResult = await waitForTabLoad(tab.id, 5000);
+      if (!loadResult.loaded) {
+        return { id: tab.id, url: params.url, title: tab.title || "" };
+      }
+      const updated = await getTabOrThrow(tab.id);
+      return { id: updated.id, url: updated.url, title: updated.title };
+    }
+    return { id: tab.id, url: tab.url, title: tab.title || "" };
+  }
+
   if (params.url) {
-    // Short wait only — avoid long blocking that causes SW termination
     const loadResult = await waitForTabLoad(tab.id, 5000);
     if (!loadResult.loaded) {
       return { id: tab.id, url: params.url, title: tab.title || "" };
@@ -300,7 +363,12 @@ export async function doCloseTab(params, context = extractExecutionContext(param
 // =========================================================================
 
 export async function doStatus(params = {}, context = extractExecutionContext(params)) {
-  const tab = await activeTab(context);
+  let tab;
+  try {
+    tab = await activeTab(context);
+  } catch (_) {
+    return { url: null, title: null, id: null, noWindow: true };
+  }
   return { url: tab.url, title: tab.title, id: tab.id };
 }
 

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/browser_ctl/extension/click.js

@@ -26,8 +26,12 @@ async function doClick(params, context = {}) {
 
   const result = results[0]?.result;
   if (!result || !result.success) {
-    // If actionability failed, try CDP fallback for fully trusted events
-    if (result?.cx !== undefined && result?.cy !== undefined && result?.error?.includes("obscured")) {
+    // If actionability failed due to hit-test (obscured / no element at coords),
+    // try CDP fallback for fully trusted events
+    const isHitTestFailure = result?.error?.includes("pointer events") ||
+      result?.error?.includes("obscured") ||
+      result?.error?.includes("no element at coordinates");
+    if (isHitTestFailure && result?.cx !== undefined && result?.cy !== undefined) {
       try {
         return await clickViaCDP(tab.id, result.cx, result.cy, params);
       } catch (_) {
@@ -365,7 +369,51 @@ async function clickHandler(selector, index, textFilter) {
       return { success: true, total, capturedUrl };
     }
 
-    // All retries exhausted
+    // All retries exhausted — if failure is purely hit-test related,
+    // force-click anyway (the element is visible, stable, enabled, just obscured)
+    const isHitTestOnly = lastReason.includes("pointer events") ||
+      lastReason.includes("obscured") ||
+      lastReason.includes("no element at coordinates");
+
+    if (isHitTestOnly) {
+      const origOpen = window.open;
+      let capturedUrl = null;
+      window.open = function (url) {
+        if (url && typeof url === "string" && url.startsWith("http")) {
+          capturedUrl = url;
+        }
+        return null;
+      };
+
+      try {
+        const rect = el.getBoundingClientRect();
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
+        const mOpts = {
+          bubbles: true,
+          cancelable: true,
+          clientX: cx,
+          clientY: cy,
+          button: 0,
+          view: window,
+        };
+        el.dispatchEvent(
+          new PointerEvent("pointerdown", { ...mOpts, pointerId: 1 })
+        );
+        el.dispatchEvent(new MouseEvent("mousedown", mOpts));
+        el.dispatchEvent(
+          new PointerEvent("pointerup", { ...mOpts, pointerId: 1 })
+        );
+        el.dispatchEvent(new MouseEvent("mouseup", mOpts));
+        el.click();
+        await new Promise((r) => setTimeout(r, 50));
+      } finally {
+        window.open = origOpen;
+      }
+
+      return { success: true, total, capturedUrl, forced: true };
+    }
+
     return {
       success: false,
       error: `click: actionability check failed for "${selector}": ${lastReason}`,

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/browser_ctl/extension/content-script.js

@@ -408,7 +408,16 @@ async function contentScriptHandler(commands) {
         while (target.shadowRoot && target.shadowRoot.activeElement) {
           target = target.shadowRoot.activeElement;
         }
-        const opts = { key, bubbles: true, cancelable: true };
+        // Map key names to legacy keyCode values for framework compatibility
+        // (Vue 2 @keydown.enter checks e.keyCode === 13, not e.key)
+        const KEY_CODES = {
+          Enter: 13, Tab: 9, Escape: 27, Backspace: 8, Delete: 46,
+          ArrowUp: 38, ArrowDown: 40, ArrowLeft: 37, ArrowRight: 39,
+          Home: 36, End: 35, PageUp: 33, PageDown: 34,
+          " ": 32, Space: 32,
+        };
+        const keyCode = KEY_CODES[key] ?? (key.length === 1 ? key.charCodeAt(0) : 0);
+        const opts = { key, keyCode, which: keyCode, bubbles: true, cancelable: true };
         const cancelled = !target.dispatchEvent(
           new KeyboardEvent("keydown", opts)
         );
@@ -1139,11 +1148,17 @@ async function contentScriptHandler(commands) {
           enabled: true,
         });
         if (!check.pass) {
-          results.push({
-            success: false,
-            error: `${op}: ${check.reason} for "${params.selector}"`,
-          });
-          break;
+          // If failure is only hit-test related, force-click anyway
+          const isHitTestOnly = check.reason.includes("pointer events") ||
+            check.reason.includes("obscured") ||
+            check.reason.includes("no element at coordinates");
+          if (!isHitTestOnly) {
+            results.push({
+              success: false,
+              error: `${op}: ${check.reason} for "${params.selector}"`,
+            });
+            break;
+          }
         }
         const data = executeOp(op, params);
         results.push({ success: true, data });
@@ -1183,11 +1198,16 @@ async function contentScriptHandler(commands) {
           receivesEvents: true,
         });
         if (!check.pass) {
-          results.push({
-            success: false,
-            error: `${op}: ${check.reason} for "${params.selector || params.source}"`,
-          });
-          break;
+          const isHitTestOnly = check.reason.includes("pointer events") ||
+            check.reason.includes("obscured") ||
+            check.reason.includes("no element at coordinates");
+          if (!isHitTestOnly) {
+            results.push({
+              success: false,
+              error: `${op}: ${check.reason} for "${params.selector || params.source}"`,
+            });
+            break;
+          }
         }
         const data = executeOp(op, params);
         results.push({ success: true, data });

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/browser_ctl/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Browser-Ctl",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Developer tool for CLI-driven browser automation. Control Chrome via command-line — navigate, click, type, query DOM, capture screenshots, and download files, all through a local WebSocket bridge.",
   "permissions": [
     "tabs",

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/browser_ctl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browser-ctl
-Version: 0.2.12
+Version: 0.2.13
 Summary: Control your browser from the command line via a Chrome extension + WebSocket bridge
 Author-email: geb <853934146@qq.com>
 License-Expression: MIT

{browser_ctl-0.2.12 → browser_ctl-0.2.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "browser-ctl"
-version = "0.2.12"
+version = "0.2.13"
 description = "Control your browser from the command line via a Chrome extension + WebSocket bridge"
 readme = "README.md"
 license = "MIT"