@crouton-kit/capture 1.4.22 → 1.4.24

package/package.json

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

@@ -65,7 +65,7 @@ Selecting a noun: session, page, and tab address the live browser; measure, moti
 
 I/O contract: flags and positionals on input; one rendered prose block on stdout. --json mirrors the same result as JSON, but the rendered block is the contract. stderr carries in-flight diagnostics only. --artifact-dir <path> selects the root for a session bundle (\`session start\`) or a sessionless artifact-producing leaf's one-shot bundle; leaf help states when it writes one. --out always names one caller-owned file, never a bundle directory.
 
-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 — 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 — precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target.`;
+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 — 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 — 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(): void {

package/src/cdp/args.ts

@@ -1,5 +1,6 @@
-import { invalidInput } from '../errors.js';
+import { captureError, invalidInput } from '../errors.js';
 import { getActiveSession } from '../session-context.js';
+import { isUrlRef } from '../output/artifact.js';
 import { type ParsedArgs } from './types.js';
 import { assertParseableUrl, assertScrollDestination, assertSweepBounds, parsePositiveNumber, parseDoAction, type SweepAxisName } from './leaf-grammar.js';
 
@@ -557,6 +558,50 @@ function needsEndpointResolution(parsed: ParsedArgs): boolean {
   return true;
 }
 
+/**
+ * False only for leaves that never open a CDP connection: `tab list` (the probe
+ * that finds a port to pass), and the leaves that read a recorded artifact by
+ * id or path. A leaf that also takes a URL (`measure check`, `measure census`,
+ * `measure map ax|focus|layers|scroll`) reaches a browser only when it is given
+ * one. Everything not named here counts as reaching a browser, so a new leaf is
+ * guarded until it is listed.
+ */
+function mayReachBrowser(parsed: ParsedArgs): boolean {
+  const [leaf, sub] = parsed.positional;
+  switch (parsed.command) {
+    case 'tab': return leaf !== 'list';
+    case 'motion': return leaf === 'rec';
+    case 'perf': return leaf === 'trace';
+    case 'heap': return leaf === 'snapshot';
+    case 'measure': {
+      if (leaf === 'diff' || leaf === 'explain' || leaf === 'text' || (leaf === 'map' && sub === 'paint')) return false;
+      if (leaf === 'check' || leaf === 'census' || leaf === 'map') return parsed.url !== undefined || parsed.positional.some(isUrlRef);
+      return true;
+    }
+    default: return true;
+  }
+}
+
+/**
+ * A node (`CRTR_NODE_ID` set) may only drive a browser it chose: an explicit
+ * `--port` or `--target`, or the port/tab recorded by its own active session.
+ * Otherwise `CDP_PORT`, `CDP_TARGET` and localhost auto-discovery would accept
+ * whatever browser is there, which can be another node's signed-in browser.
+ * `session start` is the way to choose one, and `tab list` only lists, so
+ * neither is refused. With no `CRTR_NODE_ID` (a person at a shell) nothing here
+ * applies.
+ */
+function refuseUnownedEndpoint(parsed: ParsedArgs, sessionStart: boolean): void {
+  if (!process.env.CRTR_NODE_ID?.trim() || sessionStart || !mayReachBrowser(parsed)) return;
+  if (parsed.port !== undefined || parsed.targetSource === 'flag' || parsed.targetSource === 'session') return;
+  const command = leafCommand(parsed.command, parsed.positional);
+  throw captureError(
+    'precondition',
+    'no_owned_browser',
+    `\`capture ${command}\` was not run: this node (CRTR_NODE_ID) has no browser of its own. With no --port, no --target and no active session holding a browser, capture will not use CDP_PORT, CDP_TARGET or auto-discovery, because the browser it found could belong to another node. Do one of: (1) \`capture session start --url <url>\` to open and hold your own browser tab, or \`capture tab launch\` then \`capture session start --port <port>\`; (2) pass \`--port <port>\` (see \`capture tab list\`); (3) pass \`--target <tabId>\`.`,
+  );
+}
+
 /**
  * Hydrates endpoint/session defaults only after pure invocation validation
  * succeeds. Endpoint precedence is `explicit flag > session endpoint > env`:
@@ -582,6 +627,7 @@ export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
     // --port override for deliberate multi-browser work.
     if (parsed.port === undefined && 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) {
     parsed.port = schemaInteger(leafCommand(parsed.command, parsed.positional), process.env.CDP_PORT, 'CDP_PORT', 1, 65535);
     parsed.portSource = 'env';

package/src/cdp/commands/measure/check.ts

@@ -152,11 +152,16 @@ export async function cmdMeasureCheck(parsed: ParsedArgs, _args: string[]): Prom
   } catch (err) {
     const resolution = err as Partial<ArtifactResolutionError>;
     const detail = err instanceof Error ? err.message : 'unknown artifact read failure';
+    const unresolved = resolution.name === 'ArtifactResolutionError';
     emitResult({
       tag: 'error',
-      attrs: { command: 'measure check', status: resolution.name === 'ArtifactResolutionError' ? 'artifact_unavailable' : 'check_failed' },
-      summary: fact`Measure check could not read the requested artifact: ${detail}`,
-      followUp: text`Create a settled snapshot with capture measure snap <url>, then pass its id or absolute path.`,
+      attrs: { command: 'measure check', status: unresolved ? 'artifact_unavailable' : 'check_failed' },
+      summary: unresolved
+        ? fact`Measure check could not read the requested artifact: ${detail}`
+        : fact`Measure check failed while measuring the snapshot: ${detail}`,
+      followUp: unresolved
+        ? text`Create a settled snapshot with capture measure snap <url>, then pass its id or absolute path.`
+        : text`The snapshot resolved; this is an internal capture check error, not a missing snapshot. Narrow --for to the checks you need, and report the error with the snapshot path.`,
     }, { json: parsed.json });
     process.exitCode = 1;
   }

package/src/cdp/measure/check.ts

@@ -448,7 +448,9 @@ export function checkSnapshot(ref: SnapRef, requested: readonly CheckName[]): {
       if (!e) continue;
       const point = sample.points?.find((p) => {
         const receiver = p.result?.topReceiver;
-        const receiverElement = receiver && elements.find((x) => receiver.backendNodeId != null && x.backendNodeId === receiver.backendNodeId);
+        // The collector records `topReceiver: null` for a point with an empty hit stack (e.g. a sample outside the viewport); no receiver means nothing occludes it.
+        if (!receiver) return false;
+        const receiverElement = elements.find((x) => receiver.backendNodeId != null && x.backendNodeId === receiver.backendNodeId);
         return receiverElement !== undefined && !isSelfOrDescendant(e, receiverElement);
       })?.result;
       if (!point?.topReceiver) continue;