@crouton-kit/capture 1.4.21 → 1.4.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.21",
+  "version": "1.4.23",
   "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';
 
@@ -272,6 +273,16 @@ export function validateCliInvocation(parsed: ParsedArgs): void {
     // `quit` takes an optional port; every other tab leaf names exactly one.
     if (leaf === 'launch' || leaf === 'list') requireCount(values, 0, 0, `tab ${leaf}`);
     else if (leaf === 'quit') requireCount(values, 0, 1, 'tab quit');
+    // `tab close` names its tab either positionally or with an explicit
+    // --target flag (the form every follow_up line teaches). Only the flag
+    // counts here: session/CDP_TARGET defaults are hydrated later and must
+    // never choose which tab a destructive close removes.
+    else if (leaf === 'close' && parsed.target !== undefined) {
+      requireCount(values, 0, 1, 'tab close');
+      if (values.length === 1 && values[0] !== parsed.target) {
+        throw schemaInput('tab close', `<target>=${values[0]}, --target=${parsed.target}`, 'one tab: the positional <target> or --target, not two different ids', '<target> or --target');
+      }
+    }
     else requireCount(values, 1, 1, `tab ${leaf}`);
     if (leaf === 'network' && values[0] !== 'offline' && values[0] !== 'online') {
       throw schemaInput('tab network', values[0] ?? '(missing)', 'offline or online', '<mode>');
@@ -547,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`:
@@ -572,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/page/exec.ts

@@ -107,7 +107,39 @@ function spillWholeResult(payload: string, artifactDir?: string): string {
 
 interface EvalResult {
   result?: { value?: unknown };
-  exceptionDetails?: { exception?: { description?: string } };
+  exceptionDetails?: ExceptionDetails;
+}
+
+interface ExceptionDetails {
+  text?: string;
+  exception?: {
+    type?: string;
+    subtype?: string;
+    className?: string;
+    value?: unknown;
+    description?: string;
+    preview?: { properties?: Array<{ name: string; value?: string }>; overflow?: boolean };
+  };
+}
+
+/**
+ * Describes what the page threw. An Error carries its message and stack in
+ * `description`; a thrown string, number, or plain object does not, so its
+ * value (or its preview's properties) is named instead of falling back to a
+ * bare "Object" or "Unknown error".
+ */
+function describePageException(details: ExceptionDetails): string {
+  const exception = details.exception;
+  if (!exception) return details.text ?? 'Unknown error';
+  if (exception.subtype === 'error' && exception.description) return exception.description;
+  if (exception.type === 'undefined') return 'undefined';
+  if ('value' in exception) return JSON.stringify(exception.value);
+  const properties = exception.preview?.properties;
+  if (exception.type === 'object' && properties) {
+    const fields = properties.map((p) => `${p.name}: ${p.value ?? '?'}`).join(', ');
+    return `${exception.className ?? 'Object'} {${fields}${exception.preview?.overflow ? ', …' : ''}}`;
+  }
+  return exception.description ?? details.text ?? 'Unknown error';
 }
 
 /** The structural client surface the focus/evaluation scope drives — the
@@ -316,7 +348,7 @@ export async function cmdPageExec(parsed: ParsedArgs, _args: string[]): Promise<
   }
 
   if (evalResult.exceptionDetails) {
-    const description = evalResult.exceptionDetails.exception?.description ?? 'Unknown error';
+    const description = describePageException(evalResult.exceptionDetails);
     return emitExecError(
       parsed,
       'exec_exception',

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

@@ -17,6 +17,7 @@ const USAGE = `capture tab close — close one explicitly identified background
 
 input:
   <target>        required — full tab target id or an unambiguous 8-character prefix
+  --target <id>   same as <target>; only an explicit flag counts, never the session's tab or CDP_TARGET
   --port <port>   CDP endpoint (default: the auto-discovered preferred endpoint)
 
 output: <tab-closed port=… target=…> — the closed tab's full target id and last observed URL.
@@ -36,9 +37,9 @@ export async function cmdTabClose(parsed: ParsedArgs, _args: string[]): Promise<
     return;
   }
 
-  const target = parsed.positional[0];
+  const target = parsed.positional[0] ?? (parsed.targetSource === 'flag' ? parsed.target : undefined);
   if (!target) {
-    throw invalidInput('received: no target; expected: capture tab close <target> [--port <port>].', 'missing_argument');
+    throw invalidInput('received: no target; expected: capture tab close <target> (or --target <id>) [--port <port>].', 'missing_argument');
   }
   if (target.length < 8) {
     throw invalidInput(`received: target ${target}; expected: a full target id or an unambiguous prefix of at least 8 characters.`, 'target_prefix_too_short');

package/src/interact.ts

@@ -434,6 +434,8 @@ async function dispatchResolvedClick(
     if (hitTest.backendNodeId !== backendNodeId || opts.includeHitTestReceiver) hitTestReceiverBackendNodeId = hitTest.backendNodeId;
   }
 
+  await presentFrameBeforeInput(client);
+
   const pressParams = { type: 'mousePressed', x: dispatchX, y: dispatchY, button: 'left', clickCount: 1 };
   if (opts.mark !== undefined && client.sendMarked) {
     await client.sendMarked('Input.dispatchMouseEvent', pressParams, opts.mark);
@@ -452,6 +454,21 @@ async function dispatchResolvedClick(
   };
 }
 
+/**
+ * Makes the renderer produce a frame before mouse input is dispatched. Arc does
+ * not paint a tab opened with `Target.createTarget({ background: true })` until
+ * something asks for a frame, and until it paints, `Input.dispatchMouseEvent`
+ * returns success while delivering no events to the page. A 1x1 clipped capture
+ * is the cheapest request that forces that frame. Chrome, which already paints
+ * background targets, only pays the capture.
+ */
+async function presentFrameBeforeInput(client: LiveClient): Promise<void> {
+  await client.send('Page.captureScreenshot', {
+    format: 'png',
+    clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 },
+  });
+}
+
 /** Types text into the currently focused element via CDP `Input.insertText`. */
 export async function typeText(client: LiveClient, text: string): Promise<void> {
   await client.send('Input.insertText', { text });