@crouton-kit/capture 1.3.11 → 1.3.13

package/bin/capture

@@ -8391,19 +8391,42 @@ async function navigateAndWait(port, url, options = {}) {
     throw new Error("New tab has no WebSocket debugger URL");
   }
   const client = new CDPClient(tab.webSocketDebuggerUrl);
-  await client.waitReady();
-  await client.send("Page.enable");
-  await new Promise((resolve11, reject) => {
-    const timer = setTimeout(
-      () => reject(new Error(`Page load timeout: ${url}`)),
-      timeout
-    );
-    client.on("Page.loadEventFired", () => {
-      clearTimeout(timer);
-      resolve11();
+  try {
+    await client.waitReady();
+    await client.send("Page.enable");
+    let timer;
+    let loadHandler;
+    let loadTimeoutError;
+    let resolveLoad;
+    const loadPromise = new Promise((resolve11) => {
+      resolveLoad = resolve11;
+      loadHandler = () => {
+        if (timer) clearTimeout(timer);
+        resolveLoad();
+      };
+      client.on("Page.loadEventFired", loadHandler);
+      timer = setTimeout(() => {
+        loadTimeoutError = new Error(`Page load timeout: ${url}`);
+        resolveLoad();
+      }, timeout);
     });
-  });
-  client.close();
+    try {
+      const result = await client.send("Runtime.evaluate", {
+        expression: "document.readyState",
+        returnByValue: true
+      });
+      const readyState = result?.result?.value;
+      if (readyState !== "complete") {
+        await loadPromise;
+        if (loadTimeoutError) throw loadTimeoutError;
+      }
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (loadHandler) client.off("Page.loadEventFired", loadHandler);
+    }
+  } finally {
+    client.close();
+  }
   const targets = await listTargets(port);
   const refreshed = targets.find((t) => t.id === tab.id);
   return refreshed ?? tab;
@@ -9799,7 +9822,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.3.11";
+  const version = "1.3.13";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -11558,7 +11581,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.3.11";
+  const version = "1.3.13";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -13819,9 +13842,9 @@ function readSession(id) {
 function generateId() {
   return `cap-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
 }
-async function waitForPageLoad(client, timeoutMs) {
+async function waitForPageLoad(client, timeoutMs, attachTimeoutMs = SESSION_TAB_ATTACH_TIMEOUT_MS) {
   await client.waitReady();
-  await client.send("Page.enable");
+  await client.send("Page.enable", {}, attachTimeoutMs);
   return await new Promise((resolve11) => {
     const timer = setTimeout(() => resolve11(true), timeoutMs);
     const done = (timedOut) => {
@@ -14558,7 +14581,7 @@ async function sessionMain(parsed, _args) {
       return;
   }
 }
-var fs9, path12, VIEW_FILTERS, SECTION_LABELS, COMMAND_BLOCK, START_USAGE, STOP_USAGE, LIST_USAGE, VIEW_USAGE, HAR_USAGE, LOG_USAGE, productionStartWorld, startWorld;
+var fs9, path12, VIEW_FILTERS, SECTION_LABELS, SESSION_TAB_ATTACH_TIMEOUT_MS, COMMAND_BLOCK, START_USAGE, STOP_USAGE, LIST_USAGE, VIEW_USAGE, HAR_USAGE, LOG_USAGE, productionStartWorld, startWorld;
 var init_commands = __esm({
   "src/session/commands.ts"() {
     fs9 = __toESM(require("fs"));
@@ -14589,6 +14612,7 @@ var init_commands = __esm({
       recs: "motion",
       other: "other"
     };
+    SESSION_TAB_ATTACH_TIMEOUT_MS = 5e3;
     COMMAND_BLOCK = `<command name="session">
 the artifact container \u2014 a session opens a tab, records HAR, and bundles every artifact; while active, every command auto-targets its tab
 use when starting scoped work against a page: start first, then every other capture command needs no --target/--port threading
@@ -14728,7 +14752,14 @@ effects:
           } catch (err) {
             throw worldFailure(`capture session start could not attach to ${url}: ${err instanceof Error ? err.message : err}. Reuse an existing tab with --target.`, err);
           }
-          return await waitForPageLoad(client, 1e4);
+          try {
+            return await waitForPageLoad(client, 1e4);
+          } catch (err) {
+            throw worldFailure(
+              `capture session start could not attach to ${url}: Page.enable failed during its ${SESSION_TAB_ATTACH_TIMEOUT_MS}ms attachment window (${err instanceof Error ? err.message : err}). The CDP endpoint created the tab but cannot drive it; choose another endpoint from \`capture tab list\` and retry with \`--port\`.`,
+              err
+            );
+          }
         } finally {
           client.close();
         }
@@ -15075,7 +15106,13 @@ async function resolveLiveTarget(client, input) {
       return resolveLiveCss(client, input, parsed.value);
   }
 }
-function settleAxMatches(kind, input, matches) {
+function preferActionable(matches) {
+  if (matches.length <= 1) return matches;
+  const interactive = matches.filter((m) => m.role?.value !== void 0 && INTERACTIVE_ROLES.has(m.role.value));
+  return interactive.length === 1 ? interactive : matches;
+}
+function settleAxMatches(kind, input, rawMatches) {
+  const matches = preferActionable(rawMatches);
   if (matches.length === 1) {
     const m = matches[0];
     return {
@@ -241019,7 +241056,7 @@ CDP_PORT / CDP_TARGET pin the browser + tab for orchestrators \u2014 precedence:
 explicit flag > active session > env.`;
 }
 function printVersion() {
-  const declared = "1.3.11";
+  const declared = "1.3.13";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.11",
+  "version": "1.3.13",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/cdp/record.ts

@@ -3,8 +3,8 @@ import {
   findTab,
   listTargets,
   openTab,
-  type CDPTarget,
 } from './targets.js';
+import { type CDPTarget } from './types.js';
 
 /**
  * Opens (or reuses) a tab for `url` and waits for its load event — `tab open`'s
@@ -32,23 +32,49 @@ export async function navigateAndWait(
     throw new Error('New tab has no WebSocket debugger URL');
   }
 
-  // Wait for page load
+  // Wait for page load. The client owns a page WebSocket, so close it even
+  // when connection, readiness, timeout, or target-refresh work fails.
   const client = new CDPClient(tab.webSocketDebuggerUrl);
-  await client.waitReady();
-  await client.send('Page.enable');
+  try {
+    await client.waitReady();
+    await client.send('Page.enable');
 
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(
-      () => reject(new Error(`Page load timeout: ${url}`)),
-      timeout,
-    );
-    client.on('Page.loadEventFired', () => {
-      clearTimeout(timer);
-      resolve();
+    let timer: NodeJS.Timeout | undefined;
+    let loadHandler: ((params: unknown) => void) | undefined;
+    let loadTimeoutError: Error | undefined;
+    let resolveLoad!: () => void;
+    const loadPromise = new Promise<void>((resolve) => {
+      resolveLoad = resolve;
+      loadHandler = () => {
+        if (timer) clearTimeout(timer);
+        resolveLoad();
+      };
+      // Arm the event before checking readyState: the load event may fire
+      // while the readiness query is in flight.
+      client.on('Page.loadEventFired', loadHandler);
+      timer = setTimeout(() => {
+        loadTimeoutError = new Error(`Page load timeout: ${url}`);
+        resolveLoad();
+      }, timeout);
     });
-  });
 
-  client.close();
+    try {
+      const result = await client.send('Runtime.evaluate', {
+        expression: 'document.readyState',
+        returnByValue: true,
+      });
+      const readyState = (result as { result?: { value?: unknown } } | undefined)?.result?.value;
+      if (readyState !== 'complete') {
+        await loadPromise;
+        if (loadTimeoutError) throw loadTimeoutError;
+      }
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (loadHandler) client.off('Page.loadEventFired', loadHandler);
+    }
+  } finally {
+    client.close();
+  }
 
   // Refresh target info — find by ID to avoid returning a different tab with same URL
   const targets = await listTargets(port);

package/src/interact.ts

@@ -18,11 +18,19 @@
  * nothing — command leaves own all output; returned facts carry the resolved
  * identity (`backendNodeId`, role, name) and the dispatched coordinates.
  *
+ * `ax:`/`axid:` tie-break: a same-name match set that mixes an
+ * {@link INTERACTIVE_ROLES} role (e.g. `button`) with non-interactive ones
+ * (e.g. `StaticText` — the common shape of a label rendering inside its own
+ * button) narrows to the interactive match when that leaves exactly one
+ * candidate, because that is the only element the caller can actually drive.
+ * A tie among multiple interactive roles (or zero) stays genuinely
+ * ambiguous — see {@link preferActionable}.
+ *
  * Uses getFullAXTree instead of queryAXTree because queryAXTree hangs on
  * complex pages (7000+ AX nodes) when given the DOM root nodeId.
  */
 
-import { readFullAXTree, type FullAXNode } from './cdp/a11y.js';
+import { INTERACTIVE_ROLES, readFullAXTree, type FullAXNode } from './cdp/a11y.js';
 import { isScrollDestination } from './cdp/leaf-grammar.js';
 import { captureError } from './errors.js';
 import { parseSelectorInput, type SelectorInputKind } from './output/selector.js';
@@ -163,11 +171,26 @@ export async function resolveLiveTarget(
   }
 }
 
+/**
+ * Narrows a same-name match set to its lone {@link INTERACTIVE_ROLES} member
+ * when the set mixes interactive and non-interactive roles — e.g. a `button`
+ * plus the `StaticText` label rendered inside it, both carrying the same
+ * accessible name. Leaves `matches` untouched when zero or more than one
+ * interactive role is present, so a genuine tie (two buttons, or no
+ * interactive role at all) still surfaces every candidate.
+ */
+function preferActionable(matches: FullAXNode[]): FullAXNode[] {
+  if (matches.length <= 1) return matches;
+  const interactive = matches.filter((m) => m.role?.value !== undefined && INTERACTIVE_ROLES.has(m.role.value));
+  return interactive.length === 1 ? interactive : matches;
+}
+
 function settleAxMatches(
   kind: LiveTargetKind,
   input: string,
-  matches: FullAXNode[],
+  rawMatches: FullAXNode[],
 ): ResolvedTarget | ResolutionFailure {
+  const matches = preferActionable(rawMatches);
   if (matches.length === 1) {
     const m = matches[0];
     return {

package/src/session/commands.ts

@@ -286,12 +286,18 @@ function generateId(): string {
   return `cap-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
 }
 
+/** A fresh target must acknowledge Page.enable promptly. Target.createTarget
+ * already succeeded; waiting a full CDP request timeout here only postpones a
+ * failed session start before it can publish or roll back its target. */
+export const SESSION_TAB_ATTACH_TIMEOUT_MS = 5_000;
+
 export async function waitForPageLoad(
-  client: { waitReady(): Promise<void>; send(method: string, params?: Record<string, unknown>): Promise<unknown>; on(event: string, handler: (params: unknown) => void): void; },
+  client: { waitReady(): Promise<void>; send(method: string, params?: Record<string, unknown>, timeout?: number): Promise<unknown>; on(event: string, handler: (params: unknown) => void): void; },
   timeoutMs: number,
+  attachTimeoutMs = SESSION_TAB_ATTACH_TIMEOUT_MS,
 ): Promise<boolean> {
   await client.waitReady();
-  await client.send('Page.enable');
+  await client.send('Page.enable', {}, attachTimeoutMs);
 
   return await new Promise<boolean>((resolve) => {
     const timer = setTimeout(() => resolve(true), timeoutMs);
@@ -502,7 +508,14 @@ const productionStartWorld: SessionStartWorld = {
       } catch (err) {
         throw worldFailure(`capture session start could not attach to ${url}: ${err instanceof Error ? err.message : err}. Reuse an existing tab with --target.`, err);
       }
-      return await waitForPageLoad(client, 10_000);
+      try {
+        return await waitForPageLoad(client, 10_000);
+      } catch (err) {
+        throw worldFailure(
+          `capture session start could not attach to ${url}: Page.enable failed during its ${SESSION_TAB_ATTACH_TIMEOUT_MS}ms attachment window (${err instanceof Error ? err.message : err}). The CDP endpoint created the tab but cannot drive it; choose another endpoint from \`capture tab list\` and retry with \`--port\`.`,
+          err,
+        );
+      }
     } finally {
       client.close();
     }