@crouton-kit/capture 1.4.21 → 1.4.22

package/bin/capture

@@ -9413,7 +9413,12 @@ function validateCliInvocation(parsed) {
     }
     if (leaf === "launch" || leaf === "list") requireCount(values, 0, 0, `tab ${leaf}`);
     else if (leaf === "quit") requireCount(values, 0, 1, "tab quit");
-    else requireCount(values, 1, 1, `tab ${leaf}`);
+    else if (leaf === "close" && parsed.target !== void 0) {
+      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>");
     }
@@ -10566,7 +10571,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.21";
+  const version = "1.4.22";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12668,7 +12673,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.21";
+  const version = "1.4.22";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -17075,6 +17080,7 @@ async function dispatchResolvedClick(client, resolved, opts) {
     }
     if (hitTest.backendNodeId !== backendNodeId2 || opts.includeHitTestReceiver) hitTestReceiverBackendNodeId = hitTest.backendNodeId;
   }
+  await presentFrameBeforeInput(client);
   const pressParams = { type: "mousePressed", x: dispatchX, y: dispatchY, button: "left", clickCount: 1 };
   if (opts.mark !== void 0 && client.sendMarked) {
     await client.sendMarked("Input.dispatchMouseEvent", pressParams, opts.mark);
@@ -17091,6 +17097,12 @@ async function dispatchResolvedClick(client, resolved, opts) {
     ...hitTestReceiverBackendNodeId === void 0 ? {} : { hitTestReceiverBackendNodeId }
   };
 }
+async function presentFrameBeforeInput(client) {
+  await client.send("Page.captureScreenshot", {
+    format: "png",
+    clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 }
+  });
+}
 async function typeText(client, text2) {
   await client.send("Input.insertText", { text: text2 });
 }
@@ -228715,6 +228727,19 @@ function spillWholeResult(payload, artifactDir) {
   writePrivateFile(filePath, payload);
   return filePath;
 }
+function describePageException(details) {
+  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 ? ", \u2026" : ""}}`;
+  }
+  return exception.description ?? details.text ?? "Unknown error";
+}
 function isRequestTimeout(error4) {
   return error4 instanceof Error && /CDP request timeout \(\d+ms\): Runtime\.evaluate|collector-host CDP call "Runtime\.evaluate" failed: CDP request timeout/.test(error4.message);
 }
@@ -228860,7 +228885,7 @@ async function cmdPageExec(parsed, _args) {
     );
   }
   if (evalResult.exceptionDetails) {
-    const description = evalResult.exceptionDetails.exception?.description ?? "Unknown error";
+    const description = describePageException(evalResult.exceptionDetails);
     return emitExecError(
       parsed,
       "exec_exception",
@@ -230199,9 +230224,9 @@ async function cmdTabClose(parsed, _args) {
     console.log(USAGE13);
     return;
   }
-  const target = parsed.positional[0];
+  const target = parsed.positional[0] ?? (parsed.targetSource === "flag" ? parsed.target : void 0);
   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");
@@ -230267,6 +230292,7 @@ var init_close = __esm({
 
 input:
   <target>        required \u2014 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=\u2026 target=\u2026> \u2014 the closed tab's full target id and last observed URL.
@@ -267458,7 +267484,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.`;
 }
 function printVersion() {
-  const declared = "1.4.21";
+  const declared = "1.4.22";
   if (declared) {
     console.log(declared);
     return;

package/package.json

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

@@ -272,6 +272,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>');

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