@crouton-kit/capture 1.3.12 → 1.3.14

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.14";
   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.14";
   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 {
@@ -241019,6 +241033,9 @@ init_motion();
 init_cdp();
 init_lib();
 var ROOTS = ["session", "page", "tab", "measure", "motion", "cdp", "lib"];
+var GUESSABLE_HINTS = {
+  screenshot: "page shot"
+};
 var ROOT_BLOCKS = [
   COMMAND_BLOCK,
   COMMAND_BLOCK2,
@@ -241042,7 +241059,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.14";
   if (declared) {
     console.log(declared);
     return;
@@ -241072,10 +241089,11 @@ async function main() {
   if (ROOTS.includes(command) || command === "__bridge-serve") {
     return cdpMain();
   }
+  const hint = GUESSABLE_HINTS[command];
   throw captureError(
     "invocation",
     "unknown_command",
-    `Unknown command ${command}; expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`
+    hint ? `Unknown command ${command}; did you mean \`capture ${hint}\`? Expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.` : `Unknown command ${command}; expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`
   );
 }
 main().catch((error) => {

package/package.json

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

package/src/capture.ts

@@ -25,6 +25,18 @@ import { COMMAND_BLOCK as LIB_BLOCK } from './cdp/commands/lib.js';
 /** The seven visible root children, in help order. */
 const ROOTS = ['session', 'page', 'tab', 'measure', 'motion', 'cdp', 'lib'] as const;
 
+/**
+ * Guessable former/legacy tokens with one unambiguous current destination —
+ * an orientation hint on the `unknown_command` error, never a second
+ * dispatchable path (the guessed token still fails; only the message
+ * changes). Deliberately small: an entry only earns a place here when its
+ * correct destination is unambiguous, so this stays a short discriminator
+ * rather than a growing synonym taxonomy.
+ */
+const GUESSABLE_HINTS: Readonly<Record<string, string>> = {
+  screenshot: 'page shot',
+};
+
 const ROOT_BLOCKS = [
   SESSION_BLOCK,
   PAGE_BLOCK,
@@ -90,10 +102,13 @@ async function main(): Promise<void> {
     return cdpMain();
   }
 
+  const hint = GUESSABLE_HINTS[command];
   throw captureError(
     'invocation',
     'unknown_command',
-    `Unknown command ${command}; expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`,
+    hint
+      ? `Unknown command ${command}; did you mean \`capture ${hint}\`? Expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`
+      : `Unknown command ${command}; expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`,
   );
 }
 

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();
     }