@crouton-kit/capture 1.4.0 → 1.4.2

package/bin/capture

@@ -2232,7 +2232,7 @@ var require_websocket = __commonJS({
     "use strict";
     var EventEmitter = require("events");
     var https = require("https");
-    var http = require("http");
+    var http2 = require("http");
     var net5 = require("net");
     var tls = require("tls");
     var { randomBytes: randomBytes10, createHash: createHash5 } = require("crypto");
@@ -2766,7 +2766,7 @@ var require_websocket = __commonJS({
       }
       const defaultPort = isSecure ? 443 : 80;
       const key = randomBytes10(16).toString("base64");
-      const request = isSecure ? https.request : http.request;
+      const request = isSecure ? https.request : http2.request;
       const protocolSet = /* @__PURE__ */ new Set();
       let perMessageDeflate;
       opts.createConnection = opts.createConnection || (isSecure ? tlsConnect : netConnect);
@@ -3260,7 +3260,7 @@ var require_websocket_server = __commonJS({
   "node_modules/.pnpm/ws@8.20.0/node_modules/ws/lib/websocket-server.js"(exports2, module2) {
     "use strict";
     var EventEmitter = require("events");
-    var http = require("http");
+    var http2 = require("http");
     var { Duplex } = require("stream");
     var { createHash: createHash5 } = require("crypto");
     var extension2 = require_extension();
@@ -3335,8 +3335,8 @@ var require_websocket_server = __commonJS({
           );
         }
         if (options.port != null) {
-          this._server = http.createServer((req, res) => {
-            const body = http.STATUS_CODES[426];
+          this._server = http2.createServer((req, res) => {
+            const body = http2.STATUS_CODES[426];
             res.writeHead(426, {
               "Content-Length": body.length,
               "Content-Type": "text/plain"
@@ -3623,7 +3623,7 @@ var require_websocket_server = __commonJS({
       this.destroy();
     }
     function abortHandshake(socket, code, message, headers2) {
-      message = message || http.STATUS_CODES[code];
+      message = message || http2.STATUS_CODES[code];
       headers2 = {
         Connection: "close",
         "Content-Type": "text/html",
@@ -3632,7 +3632,7 @@ var require_websocket_server = __commonJS({
       };
       socket.once("finish", socket.destroy);
       socket.end(
-        `HTTP/1.1 ${code} ${http.STATUS_CODES[code]}\r
+        `HTTP/1.1 ${code} ${http2.STATUS_CODES[code]}\r
 ` + Object.keys(headers2).map((h) => `${h}: ${headers2[h]}`).join("\r\n") + "\r\n\r\n" + message
       );
     }
@@ -3779,6 +3779,39 @@ __export(detect_exports, {
   identifyBrowserBundleId: () => identifyBrowserBundleId,
   pickPreferredEndpoint: () => pickPreferredEndpoint
 });
+function httpGetJson(port, path33, timeoutMs) {
+  return new Promise((resolve12) => {
+    const req = http.get(
+      { host: "localhost", port, path: path33, timeout: timeoutMs },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        if (status < 200 || status >= 300) {
+          res.resume();
+          resolve12(null);
+          return;
+        }
+        let body = "";
+        res.setEncoding("utf-8");
+        res.on("data", (chunk) => {
+          body += chunk;
+        });
+        res.on("end", () => {
+          try {
+            resolve12(JSON.parse(body));
+          } catch {
+            resolve12(null);
+          }
+        });
+        res.on("error", () => resolve12(null));
+      }
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      resolve12(null);
+    });
+    req.on("error", () => resolve12(null));
+  });
+}
 function getDefaultBrowserId() {
   try {
     const output = (0, import_child_process.execSync)(
@@ -3795,14 +3828,8 @@ function getDefaultBrowserId() {
 }
 async function probeCdpPort(port) {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 500);
-    const resp = await fetch(`http://localhost:${port}/json/version`, {
-      signal: controller.signal
-    });
-    clearTimeout(timeout);
-    if (resp.ok) {
-      const version = await resp.json();
+    const version = await httpGetJson(port, "/json/version", 500);
+    if (version) {
       const browser = version.Browser;
       const userAgent = version["User-Agent"] ?? "";
       if (!browser) return null;
@@ -3824,14 +3851,7 @@ async function probeCdpPort(port) {
 }
 async function probeHasPageTarget(port) {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 500);
-    const resp = await fetch(`http://localhost:${port}/json/list`, {
-      signal: controller.signal
-    });
-    clearTimeout(timeout);
-    if (!resp.ok) return false;
-    const list2 = await resp.json();
+    const list2 = await httpGetJson(port, "/json/list", 500);
     return Array.isArray(list2) && list2.some((t) => t.type === "page");
   } catch {
     return false;
@@ -3926,10 +3946,11 @@ async function detectCdpPort() {
   }
   return pickPreferredEndpoint(endpoints, getDefaultBrowserId()).port;
 }
-var import_child_process, BROWSER_PATTERNS;
+var import_child_process, http, BROWSER_PATTERNS;
 var init_detect = __esm({
   "src/cdp/detect.ts"() {
     import_child_process = require("child_process");
+    http = __toESM(require("http"));
     BROWSER_PATTERNS = {
       "company.thebrowser.browser": ["arc"],
       "com.google.chrome": ["chrome", "google chrome"],
@@ -9059,7 +9080,7 @@ function assertScrollDestination(value) {
 function parseDoAction(action) {
   if (action.startsWith("click:")) {
     const target = action.slice("click:".length);
-    if (!target) throw invalidInput("Invalid --do action: click requires a target \u2014 a css selector, ax:<name>, axid:<id>, or backend:<id>.");
+    if (!target) throw invalidInput("Invalid --do action: click requires a target \u2014 a css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, or backend:<id>.");
     return { verb: "click", target };
   }
   if (action.startsWith("scroll:")) {
@@ -9070,7 +9091,7 @@ function parseDoAction(action) {
     if (!isScrollDestination(to)) throw invalidInput("Invalid --do action: scroll requires `scroll:<target>,to=<top|bottom|px>`.");
     return { verb: "scroll", target: spec.slice(0, comma), to };
   }
-  throw invalidInput("Unsupported --do action. Supported actions: click:<target>; scroll:<target>,to=<top|bottom|px> \u2014 target is a css selector, ax:<name>, axid:<id>, or backend:<id>.");
+  throw invalidInput("Unsupported --do action. Supported actions: click:<target>; scroll:<target>,to=<top|bottom|px> \u2014 target is a css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, or backend:<id>.");
 }
 var SWEEP_NUMERIC_AXES, SWEEP_ENUM_VALUES;
 var init_leaf_grammar = __esm({
@@ -10295,7 +10316,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.0";
+  const version = "1.4.2";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12086,7 +12107,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.0";
+  const version = "1.4.2";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -16027,7 +16048,7 @@ async function resolveLiveTarget(client, input) {
       return settleAxMatches("axid", input, matches);
     }
     case "css":
-      return resolveLiveCss(client, input, parsed.value);
+      return resolveBareTarget(client, input, parsed.value);
   }
 }
 function preferActionable(matches) {
@@ -16060,6 +16081,17 @@ function settleAxMatches(kind, input, rawMatches) {
     }))
   };
 }
+async function resolveBareTarget(client, input, selector) {
+  const css = await resolveLiveCss(client, input, selector);
+  if (css.ok || css.code === "ambiguous") return css;
+  const normalized2 = normalizeAccessibleName(input);
+  if (!normalized2) return css;
+  const matches = (await readFullAXTree(client)).filter(
+    (node) => node.backendDOMNodeId !== void 0 && node.name?.value !== void 0 && normalizeAccessibleName(node.name.value) === normalized2
+  );
+  const ax = settleAxMatches("ax", input, matches);
+  return ax.ok || ax.code === "ambiguous" ? ax : css;
+}
 async function resolveLiveCss(client, input, selector) {
   await client.send("DOM.enable");
   const { root } = await client.send("DOM.getDocument", { depth: 0 });
@@ -16287,7 +16319,7 @@ function emitResolutionError(parsed, command, failure) {
       {
         tag: "error",
         attrs: { command, code: "unsupported_prefix" },
-        summary: fact`received: target \`${failure.input}\` — the \`text:\` prefix is not accepted by live driving verbs; expected one of: bare CSS selector, ax:<name>, axid:<id>, backend:<id>.`,
+        summary: fact`received: target \`${failure.input}\` — the \`text:\` prefix is not accepted by live driving verbs; expected one of: bare CSS selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, backend:<id>.`,
         followUp: fact`Retry \`${command}\` with \`ax:<name>\` (accessible-name substring) or a CSS selector; \`text:\` matching exists only on the query leaves.`
       },
       { json: parsed.json }
@@ -16339,7 +16371,7 @@ async function cmdPageClick(parsed, _args) {
     return emitInvalidInput(
       parsed,
       "page click",
-      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector, ax:<name>, axid:<id>, or backend:<id>).`
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>).`
     );
   }
   const settle = effectiveSettle(parsed, { standalone: 1e3, session: 2500 });
@@ -16390,7 +16422,7 @@ var init_click = __esm({
     USAGE = `capture page click <target> \u2014 dispatch one real click on exactly one resolved element
 
 input:
-  <target>          resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring over accessible names), axid:<id>, backend:<id>. text: is not accepted. Exactly one match required \u2014 zero or many matches is a structured error listing candidates with backend:<id> retry keys.
+  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring over accessible names), axid:<id>, backend:<id>. text: is not accepted. Exactly one match required \u2014 zero or many matches is a structured error listing candidates with backend:<id> retry keys.
   --settle <ms>     network-settle window applied after the click (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
@@ -16466,7 +16498,7 @@ var init_type = __esm({
 
 input:
   <text>            the text to insert (agent-supplied; echoed back in the result block)
-  --into <target>   focus this field first \u2014 resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required
+  --into <target>   focus this field first \u2014 resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required
   --settle <ms>     network-settle window applied after typing (default: 500; 1500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
@@ -16487,7 +16519,7 @@ async function cmdPageScroll(parsed, _args) {
     return emitInvalidInput(
       parsed,
       "page scroll",
-      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector, ax:<name>, axid:<id>, or backend:<id>) plus --to <top|bottom|px>.`
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>) plus --to <top|bottom|px>.`
     );
   }
   if (parsed.to === void 0) {
@@ -16554,7 +16586,7 @@ var init_scroll = __esm({
     USAGE3 = `capture page scroll <target> --to <top|bottom|px> \u2014 scroll one resolved container to a position
 
 input:
-  <target>          resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required \u2014 zero or many matches is a structured error listing candidates
+  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required \u2014 zero or many matches is a structured error listing candidates
   --to <dest>       required destination: top, bottom, or a pixel offset (scrollTop value)
   --settle <ms>     network-settle window applied after the scroll (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
@@ -64688,8 +64720,8 @@ ${lanes.join("\n")}
         }
         function createPerModuleNameCache() {
           const directoryPathMap = /* @__PURE__ */ new Map();
-          return { get, set };
-          function get(directory) {
+          return { get: get2, set };
+          function get2(directory) {
             return directoryPathMap.get(toPath(directory, currentDirectory, getCanonicalFileName));
           }
           function set(directory, result) {
@@ -168021,12 +168053,12 @@ ${lanes.join("\n")}
           ...info,
           parseable: !!content,
           fileName,
-          get,
+          get: get2,
           has(dependencyName, inGroups) {
-            return !!get(dependencyName, inGroups);
+            return !!get2(dependencyName, inGroups);
           }
         };
-        function get(dependencyName, inGroups = 15) {
+        function get2(dependencyName, inGroups = 15) {
           for (const [group2, deps7] of dependencyGroups) {
             if (deps7 && inGroups & group2) {
               const dep = deps7.get(dependencyName);
@@ -228091,7 +228123,7 @@ async function cmdPageShot(parsed, _args) {
     return;
   }
   if (parsed.cropSelector !== void 0 && !parsed.cropSelector.trim()) {
-    emitResult({ tag: "error", attrs: { command: "page shot", code: "invalid_crop_selector" }, summary: text`received an empty --crop-selector; expected a bare CSS selector, ax:<name>, axid:<id>, or backend:<id>.` }, { json: parsed.json });
+    emitResult({ tag: "error", attrs: { command: "page shot", code: "invalid_crop_selector" }, summary: text`received an empty --crop-selector; expected a bare CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>.` }, { json: parsed.json });
     process.exitCode = 1;
     return;
   }
@@ -228202,7 +228234,7 @@ input:
   --full-page       transient override to the full scrollable content height for this capture
   --color-scheme <dark|light>  transient prefers-color-scheme override for this capture; cleared afterward
   --crop <x,y,w,h>  capture this page-coordinate CSS-pixel rect, intersected with the live visual viewport; x/y may be fractional, w/h must be positive
-  --crop-selector <sel>  resolve exactly one live target (bare CSS, ax:<name>, axid:<id>, or backend:<id>), scroll it into view, then crop its border box and surroundings
+  --crop-selector <sel>  resolve exactly one live target (bare CSS takes precedence; exact accessible name applies when CSS finds none; ax:<name>, axid:<id>, or backend:<id>), scroll it into view, then crop its border box and surroundings
   --pad <px>        nonnegative integer CSS pixels added on every side of --crop-selector (default: 0; not accepted with --crop)
   --zoom <factor>   positive decimal CSS-to-image scale requested for a CSS crop; the 1600px image cap may produce a smaller reported scale
   --out <path>      destination file; default: the active session's shots/ sequence, or a fresh oneshot-*/page/ dir under the capture root when no session is active
@@ -228343,7 +228375,7 @@ use when driving or inspecting the tab a session opened or adopted; all verbs au
 
 All verbs auto-target the active session tab; --target/--url override. The
 driving verbs (click, type, scroll) resolve exactly one element via the
-unified target grammar \u2014 bare CSS selector, ax:<name>, axid:<id>,
+unified target grammar \u2014 bare CSS selector (which takes precedence) or exact accessible name when CSS finds none, ax:<name>, axid:<id>,
 backend:<id> \u2014 and reject an ambiguous target with the candidate list.
 During a live composed recording every verb routes through the recorder.
 
@@ -241487,7 +241519,7 @@ function recorderLiveClient(recorder) {
 function resolutionError(failure) {
   if (failure.code === "unsupported-prefix") {
     return new DoActionError(
-      `Unsupported --do target prefix in "${failure.input}": text: is query-leaf-only. Accepted prefixes: bare css selector, ax:<name>, axid:<id>, backend:<id>.`,
+      `Unsupported --do target prefix in "${failure.input}": text: is query-leaf-only. Accepted prefixes: bare css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, backend:<id>.`,
       "unsupported_target_prefix"
     );
   }
@@ -241793,7 +241825,7 @@ var init_rec = __esm({
 input:
   [url] --do <action>       one-shot: open <url> (or record the active session tab when <url> is omitted), record one action, finalize
     action                  click:<target> | scroll:<target>,to=<top|bottom|px>
-    target                  css selector (bare string) | ax:<name> (case-insensitive substring) | axid:<id> | backend:<id>
+    target                  css selector (takes precedence) or exact accessible name when CSS finds none (bare string) | ax:<name> (case-insensitive substring) | axid:<id> | backend:<id>
                             must resolve to exactly one live element; text: is not accepted by driving actions
     --duration <seconds>    keep recording after the action (default: 0)
     --viewport <WxH>        emulate a viewport for the recording window (restored after); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
@@ -243312,7 +243344,7 @@ precedence: explicit flag > active session > env. \`session start\` adopts only
 explicit --target.`;
 }
 function printVersion() {
-  const declared = "1.4.0";
+  const declared = "1.4.2";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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/commands/motion/rec.ts

@@ -72,7 +72,7 @@ const USAGE = `capture motion rec — record the page over time: composed (whate
 input:
   [url] --do <action>       one-shot: open <url> (or record the active session tab when <url> is omitted), record one action, finalize
     action                  click:<target> | scroll:<target>,to=<top|bottom|px>
-    target                  css selector (bare string) | ax:<name> (case-insensitive substring) | axid:<id> | backend:<id>
+    target                  css selector (takes precedence) or exact accessible name when CSS finds none (bare string) | ax:<name> (case-insensitive substring) | axid:<id> | backend:<id>
                             must resolve to exactly one live element; text: is not accepted by driving actions
     --duration <seconds>    keep recording after the action (default: 0)
     --viewport <WxH>        emulate a viewport for the recording window (restored after); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
@@ -212,7 +212,7 @@ function recorderLiveClient(recorder: Pick<RecorderSession, 'handleCdp'>): LiveC
 function resolutionError(failure: ResolutionFailure): DoActionError {
   if (failure.code === 'unsupported-prefix') {
     return new DoActionError(
-      `Unsupported --do target prefix in "${failure.input}": text: is query-leaf-only. Accepted prefixes: bare css selector, ax:<name>, axid:<id>, backend:<id>.`,
+      `Unsupported --do target prefix in "${failure.input}": text: is query-leaf-only. Accepted prefixes: bare css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, backend:<id>.`,
       'unsupported_target_prefix',
     );
   }

package/src/cdp/commands/page/click.ts

@@ -112,7 +112,7 @@ export function emitResolutionError(parsed: ParsedArgs, command: string, failure
       {
         tag: 'error',
         attrs: { command, code: 'unsupported_prefix' },
-        summary: fact`received: target \`${failure.input}\` — the \`text:\` prefix is not accepted by live driving verbs; expected one of: bare CSS selector, ax:<name>, axid:<id>, backend:<id>.`,
+        summary: fact`received: target \`${failure.input}\` — the \`text:\` prefix is not accepted by live driving verbs; expected one of: bare CSS selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, backend:<id>.`,
         followUp: fact`Retry \`${command}\` with \`ax:<name>\` (accessible-name substring) or a CSS selector; \`text:\` matching exists only on the query leaves.`,
       },
       { json: parsed.json },
@@ -170,7 +170,7 @@ export function emitResolutionError(parsed: ParsedArgs, command: string, failure
 const USAGE = `capture page click <target> — dispatch one real click on exactly one resolved element
 
 input:
-  <target>          resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring over accessible names), axid:<id>, backend:<id>. text: is not accepted. Exactly one match required — zero or many matches is a structured error listing candidates with backend:<id> retry keys.
+  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring over accessible names), axid:<id>, backend:<id>. text: is not accepted. Exactly one match required — zero or many matches is a structured error listing candidates with backend:<id> retry keys.
   --settle <ms>     network-settle window applied after the click (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
@@ -188,7 +188,7 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
     return emitInvalidInput(
       parsed,
       'page click',
-      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector, ax:<name>, axid:<id>, or backend:<id>).`,
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>).`,
     );
   }
 

package/src/cdp/commands/page/index.ts

@@ -30,7 +30,7 @@ export const PAGE_USAGE = `capture page — verbs against the live session tab:
 
 All verbs auto-target the active session tab; --target/--url override. The
 driving verbs (click, type, scroll) resolve exactly one element via the
-unified target grammar — bare CSS selector, ax:<name>, axid:<id>,
+unified target grammar — bare CSS selector (which takes precedence) or exact accessible name when CSS finds none, ax:<name>, axid:<id>,
 backend:<id> — and reject an ambiguous target with the candidate list.
 During a live composed recording every verb routes through the recorder.
 

package/src/cdp/commands/page/scroll.ts

@@ -22,7 +22,7 @@ import {
 const USAGE = `capture page scroll <target> --to <top|bottom|px> — scroll one resolved container to a position
 
 input:
-  <target>          resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required — zero or many matches is a structured error listing candidates
+  <target>          resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required — zero or many matches is a structured error listing candidates
   --to <dest>       required destination: top, bottom, or a pixel offset (scrollTop value)
   --settle <ms>     network-settle window applied after the scroll (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
@@ -41,7 +41,7 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
     return emitInvalidInput(
       parsed,
       'page scroll',
-      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector, ax:<name>, axid:<id>, or backend:<id>) plus --to <top|bottom|px>.`,
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>) plus --to <top|bottom|px>.`,
     );
   }
   if (parsed.to === undefined) {

package/src/cdp/commands/page/shot.ts

@@ -42,7 +42,7 @@ input:
   --full-page       transient override to the full scrollable content height for this capture
   --color-scheme <dark|light>  transient prefers-color-scheme override for this capture; cleared afterward
   --crop <x,y,w,h>  capture this page-coordinate CSS-pixel rect, intersected with the live visual viewport; x/y may be fractional, w/h must be positive
-  --crop-selector <sel>  resolve exactly one live target (bare CSS, ax:<name>, axid:<id>, or backend:<id>), scroll it into view, then crop its border box and surroundings
+  --crop-selector <sel>  resolve exactly one live target (bare CSS takes precedence; exact accessible name applies when CSS finds none; ax:<name>, axid:<id>, or backend:<id>), scroll it into view, then crop its border box and surroundings
   --pad <px>        nonnegative integer CSS pixels added on every side of --crop-selector (default: 0; not accepted with --crop)
   --zoom <factor>   positive decimal CSS-to-image scale requested for a CSS crop; the 1600px image cap may produce a smaller reported scale
   --out <path>      destination file; default: the active session's shots/ sequence, or a fresh oneshot-*/page/ dir under the capture root when no session is active
@@ -266,7 +266,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
     return;
   }
   if (parsed.cropSelector !== undefined && !parsed.cropSelector.trim()) {
-    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'invalid_crop_selector' }, summary: text`received an empty --crop-selector; expected a bare CSS selector, ax:<name>, axid:<id>, or backend:<id>.` }, { json: parsed.json });
+    emitResult({ tag: 'error', attrs: { command: 'page shot', code: 'invalid_crop_selector' }, summary: text`received an empty --crop-selector; expected a bare CSS selector or exact accessible name, ax:<name>, axid:<id>, or backend:<id>.` }, { json: parsed.json });
     process.exitCode = 1;
     return;
   }

package/src/cdp/commands/page/type.ts

@@ -28,7 +28,7 @@ const USAGE = `capture page type <text> [--into <target>] — type text into the
 
 input:
   <text>            the text to insert (agent-supplied; echoed back in the result block)
-  --into <target>   focus this field first — resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required
+  --into <target>   focus this field first — resolved against the LIVE page: bare CSS selector (takes precedence) or exact accessible name when CSS finds none, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required
   --settle <ms>     network-settle window applied after typing (default: 500; 1500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:

package/src/cdp/detect.ts

@@ -1,4 +1,56 @@
 import { execSync } from 'child_process';
+import * as http from 'http';
+
+/**
+ * A CDP-endpoint JSON probe that CANNOT leak a socket handle. Node's built-in
+ * `fetch` (undici) leaves a dangling socket + request handle when a
+ * connect-phase abort fires against a port that accepts TCP but never sends an
+ * HTTP response (e.g. a docker-proxied or half-open listener). That handle
+ * keeps this short-lived CLI process alive for undici's ~7s internal socket
+ * timeout AFTER all real work is done, so a single dead port on the machine
+ * adds ~7s to every command that runs port detection. A raw `http.get` whose
+ * request we explicitly `destroy()` on timeout releases the handle immediately.
+ *
+ * Resolves to the parsed JSON body on a 2xx response, or `null` on any
+ * timeout, connection error, non-2xx status, or unparseable body.
+ */
+function httpGetJson(
+  port: number,
+  path: string,
+  timeoutMs: number,
+): Promise<unknown | null> {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: 'localhost', port, path, timeout: timeoutMs },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        if (status < 200 || status >= 300) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf-8');
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch {
+            resolve(null);
+          }
+        });
+        res.on('error', () => resolve(null));
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.on('error', () => resolve(null));
+  });
+}
 
 export const BROWSER_PATTERNS: Record<string, string[]> = {
   'company.thebrowser.browser': ['arc'],
@@ -40,18 +92,12 @@ interface CdpProbeResult {
 // being confused for the intended browser.
 async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 500);
-    const resp = await fetch(`http://localhost:${port}/json/version`, {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (resp.ok) {
-      const version = (await resp.json()) as {
-        Browser?: string;
-        'User-Agent'?: string;
-        webSocketDebuggerUrl?: string;
-      };
+    const version = (await httpGetJson(port, '/json/version', 500)) as {
+      Browser?: string;
+      'User-Agent'?: string;
+      webSocketDebuggerUrl?: string;
+    } | null;
+    if (version) {
       const browser = version.Browser;
       const userAgent = version['User-Agent'] ?? '';
       if (!browser) return null;
@@ -83,14 +129,9 @@ async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
 
 async function probeHasPageTarget(port: number): Promise<boolean> {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 500);
-    const resp = await fetch(`http://localhost:${port}/json/list`, {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (!resp.ok) return false;
-    const list = (await resp.json()) as Array<{ type?: string }>;
+    const list = (await httpGetJson(port, '/json/list', 500)) as Array<{
+      type?: string;
+    }> | null;
     return Array.isArray(list) && list.some((t) => t.type === 'page');
   } catch {
     return false;

package/src/cdp/leaf-grammar.ts

@@ -84,7 +84,7 @@ export type DoAction =
 export function parseDoAction(action: string): DoAction {
   if (action.startsWith('click:')) {
     const target = action.slice('click:'.length);
-    if (!target) throw invalidInput('Invalid --do action: click requires a target — a css selector, ax:<name>, axid:<id>, or backend:<id>.');
+    if (!target) throw invalidInput('Invalid --do action: click requires a target — a css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, or backend:<id>.');
     return { verb: 'click', target };
   }
   if (action.startsWith('scroll:')) {
@@ -95,5 +95,5 @@ export function parseDoAction(action: string): DoAction {
     if (!isScrollDestination(to)) throw invalidInput('Invalid --do action: scroll requires `scroll:<target>,to=<top|bottom|px>`.');
     return { verb: 'scroll', target: spec.slice(0, comma), to };
   }
-  throw invalidInput('Unsupported --do action. Supported actions: click:<target>; scroll:<target>,to=<top|bottom|px> — target is a css selector, ax:<name>, axid:<id>, or backend:<id>.');
+  throw invalidInput('Unsupported --do action. Supported actions: click:<target>; scroll:<target>,to=<top|bottom|px> — target is a css selector (or exact accessible name when CSS finds none), ax:<name>, axid:<id>, or backend:<id>.');
 }

package/src/interact.ts

@@ -6,7 +6,7 @@
  * (`src/output/selector.ts`'s `parseSelectorInput`) and resolves it against
  * the LIVE page (not collector-stored records), per prefix:
  *
- *   bare string    live CSS query — `DOM.getDocument` + `DOM.querySelectorAll`
+ *   bare string    live CSS query, or an exact accessible-name match when CSS finds none
  *   backend:<id>   identity — the canonical retry key in every resolution failure
  *   ax:<name>      case-insensitive SUBSTRING over live `Accessibility.getFullAXTree` names
  *   axid:<id>      AX node id from the same live fetch
@@ -172,7 +172,7 @@ export async function resolveLiveTarget(
       return settleAxMatches('axid', input, matches);
     }
     case 'css':
-      return resolveLiveCss(client, input, parsed.value);
+      return resolveBareTarget(client, input, parsed.value);
   }
 }
 
@@ -220,6 +220,32 @@ function settleAxMatches(
   };
 }
 
+/**
+ * Bare targets preserve CSS behavior when they select one or many elements;
+ * when CSS selects none (or rejects the string), an exact accessible-name
+ * lookup lets an element name emitted by `page elements` drive directly.
+ * `ax:` remains the explicit case-insensitive substring query.
+ */
+async function resolveBareTarget(
+  client: LiveClient,
+  input: string,
+  selector: string,
+): Promise<ResolvedTarget | ResolutionFailure> {
+  const css = await resolveLiveCss(client, input, selector);
+  if (css.ok || css.code === 'ambiguous') return css;
+
+  const normalized = normalizeAccessibleName(input);
+  if (!normalized) return css;
+  const matches = (await readFullAXTree(client)).filter(
+    (node) =>
+      node.backendDOMNodeId !== undefined &&
+      node.name?.value !== undefined &&
+      normalizeAccessibleName(node.name.value) === normalized,
+  );
+  const ax = settleAxMatches('ax', input, matches);
+  return ax.ok || ax.code === 'ambiguous' ? ax : css;
+}
+
 async function resolveLiveCss(
   client: LiveClient,
   input: string,