@crouton-kit/capture 1.4.24 → 1.4.26

package/bin/capture

@@ -10174,7 +10174,8 @@ function resolveCliContext(parsed) {
       parsed.target = session.targetId;
       parsed.targetSource = "session";
     }
-    if (parsed.port === void 0 && session.port !== void 0 && session.port !== null) {
+    const discoveringEndpoints = parsed.command === "tab" && parsed.positional[0] === "list";
+    if (parsed.port === void 0 && !discoveringEndpoints && session.port !== void 0 && session.port !== null) {
       parsed.port = session.port;
       parsed.portSource = "session";
     }
@@ -10944,7 +10945,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.24";
+  const version = "1.4.26";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -13046,7 +13047,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.24";
+  const version = "1.4.26";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -17321,7 +17322,8 @@ 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;
+  if (css.ok && !(CSS_TYPE_SELECTOR.test(selector) && !await hasLayoutBox(client, css.backendNodeId))) return css;
+  if (!css.ok && css.code === "ambiguous") return css;
   const normalized2 = normalizeAccessibleName(input);
   if (!normalized2) return css;
   const matches2 = (await readFullAXTree(client)).filter(
@@ -17330,6 +17332,52 @@ async function resolveBareTarget(client, input, selector) {
   const ax = settleAxMatches("ax", input, matches2);
   return ax.ok || ax.code === "ambiguous" ? ax : css;
 }
+async function hasLayoutBox(client, backendNodeId2) {
+  try {
+    const response = await client.send("DOM.getBoxModel", { backendNodeId: backendNodeId2 });
+    return isContentQuad(response?.model?.content);
+  } catch (error4) {
+    if (isNoLayoutError(error4)) return false;
+    throw error4;
+  }
+}
+function isNoLayoutError(error4) {
+  return error4 instanceof Error && /Node does not have a layout object|Could not compute box model/.test(error4.message);
+}
+function notClickable(backendNodeId2, detail, cause) {
+  throw captureError("world", "target_not_clickable", `Resolved target backend:${backendNodeId2} ${detail}`, cause);
+}
+function viewportClickPoint(quad, width, height) {
+  const points = [[quad[0], quad[1]], [quad[2], quad[3]], [quad[4], quad[5]], [quad[6], quad[7]]];
+  const cx = points.reduce((sum, p) => sum + p[0], 0) / 4;
+  const cy = points.reduce((sum, p) => sum + p[1], 0) / 4;
+  if (cx >= 0 && cx < width && cy >= 0 && cy < height) return { x: cx, y: cy };
+  const edges = [
+    { inside: (p) => p[0] >= 0, cut: (a, b) => [0, a[1] + (b[1] - a[1]) * (0 - a[0]) / (b[0] - a[0])] },
+    { inside: (p) => p[0] <= width, cut: (a, b) => [width, a[1] + (b[1] - a[1]) * (width - a[0]) / (b[0] - a[0])] },
+    { inside: (p) => p[1] >= 0, cut: (a, b) => [a[0] + (b[0] - a[0]) * (0 - a[1]) / (b[1] - a[1]), 0] },
+    { inside: (p) => p[1] <= height, cut: (a, b) => [a[0] + (b[0] - a[0]) * (height - a[1]) / (b[1] - a[1]), height] }
+  ];
+  let polygon = points;
+  for (const edge of edges) {
+    const input = polygon;
+    polygon = [];
+    input.forEach((current, i) => {
+      const previous = input[(i + input.length - 1) % input.length];
+      if (edge.inside(current)) {
+        if (!edge.inside(previous)) polygon.push(edge.cut(previous, current));
+        polygon.push(current);
+      } else if (edge.inside(previous)) {
+        polygon.push(edge.cut(previous, current));
+      }
+    });
+    if (polygon.length === 0) return null;
+  }
+  if (polygon.length < 3) return null;
+  const x = polygon.reduce((sum, p) => sum + p[0], 0) / polygon.length;
+  const y = polygon.reduce((sum, p) => sum + p[1], 0) / polygon.length;
+  return x >= 0 && x < width && y >= 0 && y < height ? { x, y } : null;
+}
 async function resolveLiveCss(client, input, selector) {
   await client.send("DOM.enable");
   const { root } = await client.send("DOM.getDocument", { depth: 0 });
@@ -17404,18 +17452,32 @@ async function axIdentityFor(client, backendNodeId2) {
 async function clickLiveTarget(client, input, opts = {}) {
   const initial = await resolveLiveTarget(client, input);
   if (!initial.ok) return initial;
-  await client.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: initial.backendNodeId });
+  await scrollIntoView(client, initial.backendNodeId);
   const current = await resolveLiveTarget(client, input);
   if (!current.ok) return current;
   return dispatchResolvedClick(client, current, opts);
 }
 async function clickResolved(client, resolved, opts = {}) {
-  await client.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: resolved.backendNodeId });
+  await scrollIntoView(client, resolved.backendNodeId);
   return dispatchResolvedClick(client, resolved, opts);
 }
+async function scrollIntoView(client, backendNodeId2) {
+  try {
+    await client.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: backendNodeId2 });
+  } catch (error4) {
+    if (isNoLayoutError(error4)) notClickable(backendNodeId2, "has no layout box to scroll to (hidden, detached, or not rendered).", error4);
+    throw error4;
+  }
+}
 async function dispatchResolvedClick(client, resolved, opts) {
   const { backendNodeId: backendNodeId2 } = resolved;
-  const boxResponse = await client.send("DOM.getBoxModel", { backendNodeId: backendNodeId2 });
+  let boxResponse;
+  try {
+    boxResponse = await client.send("DOM.getBoxModel", { backendNodeId: backendNodeId2 });
+  } catch (error4) {
+    if (isNoLayoutError(error4)) notClickable(backendNodeId2, "has no layout box to click (hidden, detached, or not rendered).", error4);
+    throw error4;
+  }
   const quad = boxResponse?.model?.content;
   if (!isContentQuad(quad)) {
     throw captureError(
@@ -17425,24 +17487,39 @@ async function dispatchResolvedClick(client, resolved, opts) {
       { method: "DOM.getBoxModel", response: boxResponse }
     );
   }
-  const x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
-  const y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+  const metrics = await client.send("Page.getLayoutMetrics");
+  const viewport2 = metrics.cssVisualViewport;
+  if (!viewport2 || ![viewport2.pageX, viewport2.pageY, viewport2.clientWidth, viewport2.clientHeight].every(Number.isFinite)) {
+    throw captureError("world", "malformed_protocol", "Page.getLayoutMetrics returned no valid CSS visual viewport.", {
+      method: "Page.getLayoutMetrics",
+      response: metrics
+    });
+  }
+  const point = viewportClickPoint(quad, viewport2.clientWidth, viewport2.clientHeight);
+  if (point === null) {
+    notClickable(
+      backendNodeId2,
+      `is outside the ${viewport2.clientWidth}x${viewport2.clientHeight} viewport after scrolling it into view (a fixed or clipped element the page cannot scroll to).`,
+      { method: "DOM.getBoxModel", response: boxResponse }
+    );
+  }
+  const { x, y } = point;
   const dispatchX = Math.round(x);
   const dispatchY = Math.round(y);
   let hitTestReceiverBackendNodeId;
   if (opts.inspectHitTest) {
-    const metrics = await client.send("Page.getLayoutMetrics");
-    const viewport2 = metrics.cssVisualViewport;
-    if (!viewport2 || !Number.isFinite(viewport2.pageX) || !Number.isFinite(viewport2.pageY)) {
-      throw captureError("world", "malformed_protocol", "Page.getLayoutMetrics returned no valid CSS visual viewport.", {
-        method: "Page.getLayoutMetrics",
-        response: metrics
+    let hitTest;
+    try {
+      hitTest = await client.send("DOM.getNodeForLocation", {
+        x: Math.round(x + viewport2.pageX),
+        y: Math.round(y + viewport2.pageY)
       });
+    } catch (error4) {
+      if (error4 instanceof Error && error4.message.includes("No node found at given location")) {
+        notClickable(backendNodeId2, `has no element at its click point x=${dispatchX} y=${dispatchY}; nothing there can receive the click.`, error4);
+      }
+      throw error4;
     }
-    const hitTest = await client.send("DOM.getNodeForLocation", {
-      x: Math.round(x + viewport2.pageX),
-      y: Math.round(y + viewport2.pageY)
-    });
     if (typeof hitTest.backendNodeId !== "number" || !Number.isSafeInteger(hitTest.backendNodeId) || hitTest.backendNodeId <= 0) {
       throw captureError(
         "world",
@@ -17555,7 +17632,7 @@ async function scrollResolved(client, resolved, to, opts = {}) {
     }
   }
 }
-var ACCEPTED_LIVE_PREFIXES, CANDIDATE_LIMIT;
+var ACCEPTED_LIVE_PREFIXES, CANDIDATE_LIMIT, CSS_TYPE_SELECTOR;
 var init_interact = __esm({
   "src/interact.ts"() {
     init_a11y();
@@ -17564,6 +17641,7 @@ var init_interact = __esm({
     init_selector();
     ACCEPTED_LIVE_PREFIXES = ["css", "ax:", "axid:", "backend:"];
     CANDIDATE_LIMIT = 10;
+    CSS_TYPE_SELECTOR = /^[A-Za-z][A-Za-z0-9-]*$/;
   }
 });
 
@@ -230506,7 +230584,7 @@ var init_list = __esm({
     USAGE11 = `capture tab list \u2014 discover CDP endpoints and list the page tabs on each.
 
 input:
-  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
+  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint; an active session's endpoint does not narrow it (CDP_PORT still pins one endpoint)
 
 output: <tabs endpoints=\u2026 tabs=\u2026> \u2014 one section per reachable endpoint (port, app, page-tab count, preferred marker, and a capture-owned pid marker on any browser \`tab launch\` started) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
 effects: probes local CDP endpoints over HTTP/WebSocket; no page-observable writes. Also sweeps capture-launched browsers, stopping any that have exited, stopped answering CDP, or gone idle \u2014 browsers capture did not start are never signalled.`;
@@ -267518,7 +267596,7 @@ I/O contract: flags and positionals on input; one rendered prose block on stdout
 A CDP-enabled browser must be running; \`capture tab list\` is the probe, and \`capture tab launch\` starts one capture owns and reaps when nothing is (never hand-roll a detached browser \u2014 nothing reaps that). Capture never signals a browser it did not start, so attaching to your own with --port is unchanged. CDP_PORT / CDP_TARGET pin the browser + tab for target-selecting commands \u2014 precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target. When CRTR_NODE_ID is set (a crtr agent node), a browser command with no --port, no --target and no active session of that node is refused instead of falling back to CDP_PORT, CDP_TARGET or localhost discovery, because the browser found could belong to another node: run \`capture session start --url <url>\`, or pass --port or --target. \`capture tab list\` and commands that only read a recorded artifact are not refused.`;
 }
 function printVersion() {
-  const declared = "1.4.24";
+  const declared = "1.4.26";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.24",
+  "version": "1.4.26",
   "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/args.ts

@@ -625,7 +625,10 @@ export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
     // A session target is inseparable from the endpoint that created it.
     // Prefer that endpoint over ambient CDP_PORT, but retain an explicit
     // --port override for deliberate multi-browser work.
-    if (parsed.port === undefined && session.port !== undefined && session.port !== null) { parsed.port = session.port; parsed.portSource = 'session'; }
+    // `tab list` is the discovery probe: without --port it lists every
+    // localhost endpoint, so the session's endpoint must not narrow it.
+    const discoveringEndpoints = parsed.command === 'tab' && parsed.positional[0] === 'list';
+    if (parsed.port === undefined && !discoveringEndpoints && session.port !== undefined && session.port !== null) { parsed.port = session.port; parsed.portSource = 'session'; }
   }
   refuseUnownedEndpoint(parsed, sessionStart);
   if (parsed.port === undefined && process.env.CDP_PORT !== undefined) {

package/src/cdp/commands/tab/list.ts

@@ -30,7 +30,7 @@ import {
 const USAGE = `capture tab list — discover CDP endpoints and list the page tabs on each.
 
 input:
-  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
+  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint; an active session's endpoint does not narrow it (CDP_PORT still pins one endpoint)
 
 output: <tabs endpoints=… tabs=…> — one section per reachable endpoint (port, app, page-tab count, preferred marker, and a capture-owned pid marker on any browser \`tab launch\` started) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
 effects: probes local CDP endpoints over HTTP/WebSocket; no page-observable writes. Also sweeps capture-launched browsers, stopping any that have exited, stopped answering CDP, or gone idle — browsers capture did not start are never signalled.`;

package/src/interact.ts

@@ -238,7 +238,11 @@ async function resolveBareTarget(
   selector: string,
 ): Promise<ResolvedTarget | ResolutionFailure> {
   const css = await resolveLiveCss(client, input, selector);
-  if (css.ok || css.code === 'ambiguous') return css;
+  // A one-word accessible name is also a valid CSS type selector: `Title` is
+  // the <title> element in <head>, which has no layout box. That match cannot
+  // be driven, so it must not shadow the accessible name.
+  if (css.ok && !(CSS_TYPE_SELECTOR.test(selector) && !(await hasLayoutBox(client, css.backendNodeId)))) return css;
+  if (!css.ok && css.code === 'ambiguous') return css;
 
   const normalized = normalizeAccessibleName(input);
   if (!normalized) return css;
@@ -252,6 +256,67 @@ async function resolveBareTarget(
   return ax.ok || ax.code === 'ambiguous' ? ax : css;
 }
 
+/** A selector that is a single tag name — the only CSS shape an accessible name can collide with. */
+const CSS_TYPE_SELECTOR = /^[A-Za-z][A-Za-z0-9-]*$/;
+
+async function hasLayoutBox(client: LiveClient, backendNodeId: number): Promise<boolean> {
+  try {
+    const response = (await client.send('DOM.getBoxModel', { backendNodeId })) as { model?: { content?: unknown } } | undefined;
+    return isContentQuad(response?.model?.content);
+  } catch (error) {
+    if (isNoLayoutError(error)) return false;
+    throw error;
+  }
+}
+
+/** The renderer's messages for a node with no layout box (`<title>`, `display:none`, detached). */
+function isNoLayoutError(error: unknown): boolean {
+  return error instanceof Error && /Node does not have a layout object|Could not compute box model/.test(error.message);
+}
+
+function notClickable(backendNodeId: number, detail: string, cause?: unknown): never {
+  throw captureError('world', 'target_not_clickable', `Resolved target backend:${backendNodeId} ${detail}`, cause);
+}
+
+/**
+ * Where to click a content quad: its center when that is inside the viewport,
+ * otherwise the center of the part of the quad that is. A tall or wide element
+ * (or a fixed one larger than the window) can have its center outside the
+ * viewport after scrolling; a mouse event there reaches no element.
+ */
+function viewportClickPoint(quad: number[], width: number, height: number): { x: number; y: number } | null {
+  const points: Array<[number, number]> = [[quad[0], quad[1]], [quad[2], quad[3]], [quad[4], quad[5]], [quad[6], quad[7]]];
+  const cx = points.reduce((sum, p) => sum + p[0], 0) / 4;
+  const cy = points.reduce((sum, p) => sum + p[1], 0) / 4;
+  if (cx >= 0 && cx < width && cy >= 0 && cy < height) return { x: cx, y: cy };
+  // Sutherland–Hodgman clip of the (convex) quad against the viewport rectangle.
+  const edges: Array<{ inside: (p: [number, number]) => boolean; cut: (a: [number, number], b: [number, number]) => [number, number] }> = [
+    { inside: (p) => p[0] >= 0, cut: (a, b) => [0, a[1] + ((b[1] - a[1]) * (0 - a[0])) / (b[0] - a[0])] },
+    { inside: (p) => p[0] <= width, cut: (a, b) => [width, a[1] + ((b[1] - a[1]) * (width - a[0])) / (b[0] - a[0])] },
+    { inside: (p) => p[1] >= 0, cut: (a, b) => [a[0] + ((b[0] - a[0]) * (0 - a[1])) / (b[1] - a[1]), 0] },
+    { inside: (p) => p[1] <= height, cut: (a, b) => [a[0] + ((b[0] - a[0]) * (height - a[1])) / (b[1] - a[1]), height] },
+  ];
+  let polygon = points;
+  for (const edge of edges) {
+    const input = polygon;
+    polygon = [];
+    input.forEach((current, i) => {
+      const previous = input[(i + input.length - 1) % input.length];
+      if (edge.inside(current)) {
+        if (!edge.inside(previous)) polygon.push(edge.cut(previous, current));
+        polygon.push(current);
+      } else if (edge.inside(previous)) {
+        polygon.push(edge.cut(previous, current));
+      }
+    });
+    if (polygon.length === 0) return null;
+  }
+  if (polygon.length < 3) return null;
+  const x = polygon.reduce((sum, p) => sum + p[0], 0) / polygon.length;
+  const y = polygon.reduce((sum, p) => sum + p[1], 0) / polygon.length;
+  return x >= 0 && x < width && y >= 0 && y < height ? { x, y } : null;
+}
+
 async function resolveLiveCss(
   client: LiveClient,
   input: string,
@@ -368,7 +433,7 @@ export async function clickLiveTarget(
   const initial = await resolveLiveTarget(client, input);
   if (!initial.ok) return initial;
 
-  await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId: initial.backendNodeId });
+  await scrollIntoView(client, initial.backendNodeId);
 
   const current = await resolveLiveTarget(client, input);
   if (!current.ok) return current;
@@ -380,19 +445,32 @@ export async function clickResolved(
   resolved: ResolvedTarget,
   opts: { mark?: string; inspectHitTest?: boolean; includeHitTestReceiver?: boolean } = {},
 ): Promise<ClickDispatch> {
-  await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId: resolved.backendNodeId });
+  await scrollIntoView(client, resolved.backendNodeId);
   return dispatchResolvedClick(client, resolved, opts);
 }
 
+async function scrollIntoView(client: LiveClient, backendNodeId: number): Promise<void> {
+  try {
+    await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+  } catch (error) {
+    if (isNoLayoutError(error)) notClickable(backendNodeId, 'has no layout box to scroll to (hidden, detached, or not rendered).', error);
+    throw error;
+  }
+}
+
 async function dispatchResolvedClick(
   client: LiveClient,
   resolved: ResolvedTarget,
   opts: { mark?: string; inspectHitTest?: boolean; includeHitTestReceiver?: boolean },
 ): Promise<ClickDispatch> {
   const { backendNodeId } = resolved;
-  const boxResponse = (await client.send('DOM.getBoxModel', { backendNodeId })) as
-    | { model?: { content?: unknown } }
-    | undefined;
+  let boxResponse: { model?: { content?: unknown } } | undefined;
+  try {
+    boxResponse = (await client.send('DOM.getBoxModel', { backendNodeId })) as { model?: { content?: unknown } } | undefined;
+  } catch (error) {
+    if (isNoLayoutError(error)) notClickable(backendNodeId, 'has no layout box to click (hidden, detached, or not rendered).', error);
+    throw error;
+  }
 
   // Content quad is [x1,y1, x2,y2, x3,y3, x4,y4] — validated here, once, for
   // every click consumer (page click and motion rec's one-shot alike).
@@ -405,24 +483,39 @@ async function dispatchResolvedClick(
       { method: 'DOM.getBoxModel', response: boxResponse },
     );
   }
-  const x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
-  const y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+  const metrics = (await client.send('Page.getLayoutMetrics')) as { cssVisualViewport?: { pageX: number; pageY: number; clientWidth: number; clientHeight: number } };
+  const viewport = metrics.cssVisualViewport;
+  if (!viewport || ![viewport.pageX, viewport.pageY, viewport.clientWidth, viewport.clientHeight].every(Number.isFinite)) {
+    throw captureError('world', 'malformed_protocol', 'Page.getLayoutMetrics returned no valid CSS visual viewport.', {
+      method: 'Page.getLayoutMetrics', response: metrics,
+    });
+  }
+  const point = viewportClickPoint(quad, viewport.clientWidth, viewport.clientHeight);
+  if (point === null) {
+    notClickable(
+      backendNodeId,
+      `is outside the ${viewport.clientWidth}x${viewport.clientHeight} viewport after scrolling it into view (a fixed or clipped element the page cannot scroll to).`,
+      { method: 'DOM.getBoxModel', response: boxResponse },
+    );
+  }
+  const { x, y } = point;
 
   const dispatchX = Math.round(x);
   const dispatchY = Math.round(y);
   let hitTestReceiverBackendNodeId: number | undefined;
   if (opts.inspectHitTest) {
     // The box quad and mouse dispatch use viewport coordinates; DOM.getNodeForLocation uses page coordinates.
-    const metrics = (await client.send('Page.getLayoutMetrics')) as { cssVisualViewport?: { pageX: number; pageY: number } };
-    const viewport = metrics.cssVisualViewport;
-    if (!viewport || !Number.isFinite(viewport.pageX) || !Number.isFinite(viewport.pageY)) {
-      throw captureError('world', 'malformed_protocol', 'Page.getLayoutMetrics returned no valid CSS visual viewport.', {
-        method: 'Page.getLayoutMetrics', response: metrics,
-      });
+    let hitTest: { backendNodeId?: unknown };
+    try {
+      hitTest = (await client.send('DOM.getNodeForLocation', {
+        x: Math.round(x + viewport.pageX), y: Math.round(y + viewport.pageY),
+      })) as { backendNodeId?: unknown };
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('No node found at given location')) {
+        notClickable(backendNodeId, `has no element at its click point x=${dispatchX} y=${dispatchY}; nothing there can receive the click.`, error);
+      }
+      throw error;
     }
-    const hitTest = (await client.send('DOM.getNodeForLocation', {
-      x: Math.round(x + viewport.pageX), y: Math.round(y + viewport.pageY),
-    })) as { backendNodeId?: unknown };
     if (typeof hitTest.backendNodeId !== 'number' || !Number.isSafeInteger(hitTest.backendNodeId) || hitTest.backendNodeId <= 0) {
       throw captureError(
         'world',