@crouton-kit/capture 1.3.12 → 1.3.13

package/bin/capture

@@ -9822,7 +9822,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.3.12";
+  const version = "1.3.13";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -11581,7 +11581,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.3.12";
+  const version = "1.3.13";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -13842,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) => {
@@ -14581,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"));
@@ -14612,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
@@ -14751,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();
         }
@@ -15098,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 {
@@ -241042,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.12";
+  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.12",
+  "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/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();
     }