@crouton-kit/capture 1.4.20 → 1.4.22

package/bin/capture

@@ -3781,6 +3781,7 @@ var init_loopback = __esm({
 var detect_exports = {};
 __export(detect_exports, {
   BROWSER_PATTERNS: () => BROWSER_PATTERNS,
+  describeCdpPort: () => describeCdpPort,
   detectCdpEndpoint: () => detectCdpEndpoint,
   detectCdpPort: () => detectCdpPort,
   detectCdpPortsAsync: () => detectCdpPortsAsync,
@@ -3911,24 +3912,29 @@ function identifyBrowserBundleId(browser, processName) {
   }
   return "unknown";
 }
+async function describeEndpoint(port, processNames2) {
+  const probe = await probeCdpPort(port);
+  if (!probe) return null;
+  const processName = processNames2.get(port);
+  return {
+    port,
+    app: processName ?? probe.app,
+    bundleId: identifyBrowserBundleId(probe.browser, processName),
+    isElectron: probe.isElectron,
+    hasPageTarget: probe.hasPageTarget
+  };
+}
+async function describeCdpPort(port) {
+  return describeEndpoint(port, getListeningProcessNames());
+}
 async function detectCdpPortsAsync() {
   const ports = getLocalhostListeningPorts();
   const processNames2 = getListeningProcessNames();
   const results = [];
-  const probes = ports.map(async (port) => {
-    const probe = await probeCdpPort(port);
-    if (probe) {
-      const processName = processNames2.get(port);
-      results.push({
-        port,
-        app: processName ?? probe.app,
-        bundleId: identifyBrowserBundleId(probe.browser, processName),
-        isElectron: probe.isElectron,
-        hasPageTarget: probe.hasPageTarget
-      });
-    }
-  });
-  await Promise.all(probes);
+  await Promise.all(ports.map(async (port) => {
+    const endpoint = await describeEndpoint(port, processNames2);
+    if (endpoint) results.push(endpoint);
+  }));
   return results;
 }
 function pickPreferredEndpointWithReason(endpoints, defaultBrowser) {
@@ -8730,6 +8736,7 @@ async function viewportScopedCapture(client, viewport2, options, includeCssViewp
     } catch (error4) {
       if (options?.crop) throw error4;
     }
+    await options?.beforeCapture?.();
     const result = await client.send(
       "Page.captureScreenshot",
       screenshotOpts,
@@ -9406,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>");
     }
@@ -10559,7 +10571,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.20";
+  const version = "1.4.22";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12661,7 +12673,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.20";
+  const version = "1.4.22";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -15128,6 +15140,15 @@ function rejectSurplusPositionals(parsed, leaf, max, usage) {
   process.exitCode = 1;
   return true;
 }
+async function tabStillListed(port, targetId) {
+  await new Promise((resolve12) => setTimeout(resolve12, 250));
+  try {
+    const found = await startWorld.findTabById(port, targetId);
+    return found !== null && found.type === "page";
+  } catch {
+    return false;
+  }
+}
 async function start(parsed) {
   if (parsed.help) {
     console.log(START_USAGE);
@@ -15206,6 +15227,21 @@ async function start(parsed) {
           const openedTargetId = target.id;
           acquired.push({ label: "opened target", release: () => startWorld.closeTarget(openedPort, openedTargetId) });
           pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+          if (!await tabStillListed(cdpPort, target.id)) {
+            const lostId = target.id;
+            await startWorld.closeTarget(cdpPort, lostId).catch(() => void 0);
+            acquired.pop();
+            target = await startWorld.openTab(cdpPort, url);
+            const retryPort = cdpPort;
+            const retryId = target.id;
+            acquired.push({ label: "opened target", release: () => startWorld.closeTarget(retryPort, retryId) });
+            pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+            if (!await tabStillListed(cdpPort, target.id)) {
+              throw worldFailure(
+                `Port ${cdpPort} drops tabs created over CDP (${retryId} vanished twice). Use \`capture tab open ${url} --port ${cdpPort}\`, then \`capture session start --port ${cdpPort} --target <id>\`.`
+              );
+            }
+          }
         }
       }
       if (hold) {
@@ -16422,6 +16458,14 @@ async function connectForCommand(parsed) {
   const tab = resolved?.tab ?? null;
   if (!tab) {
     const query = parsed.target ?? parsed.url;
+    if (parsed.targetSource === "session" && activeSession2) {
+      const where = activeSession2.port ? ` on port ${activeSession2.port}` : "";
+      throw captureError(
+        "precondition",
+        "target_unavailable",
+        `Session ${activeSession2.sessionId}'s tab ${query}${where} is no longer listed \u2014 the browser closed or dropped it. Open a replacement with \`capture tab reset <url>${activeSession2.port ? ` --port ${activeSession2.port}` : ""}\` (repoints this session at it), or pick a live tab with \`capture tab list\` and pass \`--target <id>\`.`
+      );
+    }
     throw captureError(
       "precondition",
       "target_unavailable",
@@ -16984,9 +17028,20 @@ async function axIdentityFor(client, backendNodeId2) {
     return { role: null, name: null };
   }
 }
+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 });
+  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 });
+  return dispatchResolvedClick(client, resolved, opts);
+}
+async function dispatchResolvedClick(client, resolved, opts) {
   const { backendNodeId: backendNodeId2 } = resolved;
-  await client.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: backendNodeId2 });
   const boxResponse = await client.send("DOM.getBoxModel", { backendNodeId: backendNodeId2 });
   const quad = boxResponse?.model?.content;
   if (!isContentQuad(quad)) {
@@ -17003,7 +17058,18 @@ async function clickResolved(client, resolved, opts = {}) {
   const dispatchY = Math.round(y);
   let hitTestReceiverBackendNodeId;
   if (opts.inspectHitTest) {
-    const hitTest = await client.send("DOM.getNodeForLocation", { x: dispatchX, y: dispatchY });
+    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
+      });
+    }
+    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",
@@ -17014,6 +17080,7 @@ async function clickResolved(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);
@@ -17030,6 +17097,12 @@ async function clickResolved(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 });
 }
@@ -17219,9 +17292,9 @@ async function cmdPageClick(parsed, _args) {
     { settleMs: settle },
     async (client) => {
       const live = client;
-      const resolved = await resolveLiveTarget(live, target);
-      if (!resolved.ok) return { failure: resolved };
-      const dispatch2 = await clickResolved(live, resolved, { inspectHitTest: true });
+      const clicked = await clickLiveTarget(live, target, { inspectHitTest: true });
+      if ("ok" in clicked) return { failure: clicked };
+      const dispatch2 = clicked;
       const screenshotResult = await capturePageInputScreenshot(client, "click", target, parsed.noScreenshot, parsed.out);
       return { dispatch: dispatch2, ...screenshotResult };
     }
@@ -228654,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);
 }
@@ -228799,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",
@@ -229039,6 +229125,29 @@ async function pageBorderRect(client, backendNodeId2) {
   }
   return { ...rect3, x: rect3.x + pageX, y: rect3.y + pageY };
 }
+async function finishColorTransitions(client) {
+  const tree = await client.send("Page.getFrameTree");
+  if (!tree.frameTree) throw new Error("Page.getFrameTree returned no frames for color-scheme capture.");
+  const frames2 = [tree.frameTree];
+  for (const frame of frames2) {
+    frames2.push(...frame.childFrames ?? []);
+    const world2 = await client.send("Page.createIsolatedWorld", {
+      frameId: frame.frame.id,
+      worldName: "capture-color-scheme"
+    });
+    if (world2.executionContextId === void 0) throw new Error(`No execution context for frame ${frame.frame.id}.`);
+    const result = await client.send("Runtime.evaluate", {
+      contextId: world2.executionContextId,
+      expression: `(() => {
+        document.getAnimations({ subtree: true })
+          .filter(animation => animation instanceof CSSTransition)
+          .forEach(transition => transition.finish());
+      })()`,
+      returnByValue: true
+    });
+    if (!result.result || result.exceptionDetails) throw new Error(`Could not finish CSS transitions in frame ${frame.frame.id}: ${result.exceptionDetails?.text ?? "page evaluation failed"}`);
+  }
+}
 async function cmdPageShot(parsed, _args) {
   if (parsed.help) {
     console.log(USAGE6);
@@ -229142,7 +229251,12 @@ async function cmdPageShot(parsed, _args) {
       } else if (requestedCrop) {
         cropProvenance = { source: "coordinates", requested: requestedCrop, zoom };
       }
-      const screenshot = await captureScreenshotWithCssViewport(client, viewport2, { fullPage: parsed.fullPage, crop: requestedCrop, zoom });
+      const screenshot = await captureScreenshotWithCssViewport(client, viewport2, {
+        fullPage: parsed.fullPage,
+        crop: requestedCrop,
+        zoom,
+        ...colorScheme ? { beforeCapture: () => finishColorTransitions(client) } : {}
+      });
       const outPath = await resolveOutPath(parsed);
       writeScreenshot(outPath, screenshot.png);
       return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport, scrollOffset: screenshot.scrollOffset, crop: cropProvenance };
@@ -229173,7 +229287,7 @@ var init_shot = __esm({
 input:
   --viewport <WxH>  transient device-metrics override for this capture; grammar: <positive-safe-int>x<positive-safe-int>, exact lowercase x with no whitespace \u2014 preset names are not accepted. Absent \u2192 no emulation, the browser's actual current viewport is captured
   --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
+  --color-scheme <dark|light>  transient prefers-color-scheme override for this capture; CSS transitions finish before the shot; 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 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)
@@ -229185,7 +229299,7 @@ input:
 output:
   <screenshot path=\u2026 width=\u2026 height=\u2026 css-width=\u2026 css-height=\u2026 css-x=\u2026 css-y=\u2026 css-to-image-x=\u2026 css-to-image-y=\u2026 effective-downscale-x=\u2026 effective-downscale-y=\u2026 scroll-x=\u2026 scroll-y=\u2026 emulation=none|viewport|full-page color-scheme=dark|light> \u2014 saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, visual-viewport scroll offset at capture, any effective downscale below 1 image px/CSS px, byte size, crop provenance, and any requested transient emulation
 effects:
-  no flags: none \u2014 the capture reads the viewport as-is, with zero Emulation.* calls. Sessionless captures write one bundle under --artifact-dir when supplied; --out writes only its caller-owned PNG. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture \u2014 two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; a selector crop reports its requested and delivered regions when its padded box cannot fit. An empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
+  no flags: none \u2014 the capture reads the viewport as-is, with zero Emulation.* calls. Sessionless captures write one bundle under --artifact-dir when supplied; --out writes only its caller-owned PNG. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture \u2014 two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override, finishes CSS transitions before capture, and clears the override afterward. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; a selector crop reports its requested and delivered regions when its padded box cannot fit. An empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
     deps4 = { withConnection, nextStepPath, createOneshotSession };
     PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
     LEGIBILITY_SCALE_THRESHOLD = 0.5;
@@ -229909,6 +230023,9 @@ effects: SIGTERM (then SIGKILL if needed) to capture-launched browsers only, ver
 });
 
 // src/cdp/commands/tab/list.ts
+function endpointNote(app) {
+  return app !== void 0 && /^arc$/i.test(app.trim()) ? ARC_ENDPOINT_NOTE : void 0;
+}
 function buildTabsResult(endpoints, unreachable) {
   const totalTabs = endpoints.reduce((n, ep) => n + ep.pages.length, 0);
   let summary = endpoints.length === 0 && unreachable.length === 0 ? text`0 CDP endpoints found listening on localhost.` : fact`${totalTabs} page tab(s) on ${endpoints.length} reachable CDP endpoint(s).`;
@@ -229927,7 +230044,8 @@ function buildTabsResult(endpoints, unreachable) {
     const rows = ep.pages.map(
       (t) => line(text`  `, data(t.id.slice(0, 8)), text`  "`, data(t.title, 120), text`"  `, data(t.url, 300))
     );
-    return lineList([header, ...rows]);
+    const note = endpointNote(ep.app);
+    return lineList([header, ...rows, ...note ? [note] : []]);
   });
   if (unreachable.length > 0) {
     sections.push(
@@ -229970,8 +230088,10 @@ async function cmdTabList(parsed, _args) {
   if (parsed.port) {
     try {
       const targets = await listTargets(parsed.port);
+      const described = await describeCdpPort(parsed.port).catch(() => null);
       reachable.push({
         port: parsed.port,
+        ...described ? { app: described.app } : {},
         preferred: false,
         ...owned.has(parsed.port) ? { ownedPid: owned.get(parsed.port).pid } : {},
         pages: targets.filter((t) => t.type === "page").map((t) => ({ id: t.id, title: t.title, url: t.url }))
@@ -230003,7 +230123,7 @@ async function cmdTabList(parsed, _args) {
   }
   emitResult(buildTabsResult(reachable, unreachable), { json: parsed.json });
 }
-var USAGE11;
+var USAGE11, ARC_ENDPOINT_NOTE;
 var init_list = __esm({
   "src/cdp/commands/tab/list.ts"() {
     init_detect();
@@ -230017,6 +230137,7 @@ input:
 
 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.`;
+    ARC_ENDPOINT_NOTE = text`  note: Arc exposes only tabs opened over CDP as page targets; the tabs in its windows are not listed. Open one with "capture tab open <url> --port <port>", then "capture session start --port <port> --target <id>".`;
   }
 });
 
@@ -230103,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");
@@ -230171,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.
@@ -267362,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.20";
+  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.20",
+  "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/click.ts

@@ -14,8 +14,7 @@ import { withPageAction } from '../../connection.js';
 import { autoScreenshot } from '../../screenshot.js';
 import { getActiveSession } from '../../../session-context.js';
 import {
-  resolveLiveTarget,
-  clickResolved,
+  clickLiveTarget,
   type LiveClient,
   type ResolutionFailure,
 } from '../../../interact.js';
@@ -206,9 +205,9 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
     { settleMs: settle },
     async (client) => {
       const live = client as unknown as LiveClient;
-      const resolved = await resolveLiveTarget(live, target);
-      if (!resolved.ok) return { failure: resolved } as const;
-      const dispatch = await clickResolved(live, resolved, { inspectHitTest: true });
+      const clicked = await clickLiveTarget(live, target, { inspectHitTest: true });
+      if ('ok' in clicked) return { failure: clicked } as const;
+      const dispatch = clicked;
       const screenshotResult = await capturePageInputScreenshot(client, 'click', target, parsed.noScreenshot, parsed.out);
       return { dispatch, ...screenshotResult } as const;
     },

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/page/shot.ts

@@ -39,7 +39,7 @@ const USAGE = `capture page shot — capture a PNG of the tab as it is right now
 input:
   --viewport <WxH>  transient device-metrics override for this capture; grammar: <positive-safe-int>x<positive-safe-int>, exact lowercase x with no whitespace — preset names are not accepted. Absent → no emulation, the browser's actual current viewport is captured
   --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
+  --color-scheme <dark|light>  transient prefers-color-scheme override for this capture; CSS transitions finish before the shot; 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 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)
@@ -51,7 +51,7 @@ input:
 output:
   <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… effective-downscale-x=… effective-downscale-y=… scroll-x=… scroll-y=… emulation=none|viewport|full-page color-scheme=dark|light> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, visual-viewport scroll offset at capture, any effective downscale below 1 image px/CSS px, byte size, crop provenance, and any requested transient emulation
 effects:
-  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. Sessionless captures write one bundle under --artifact-dir when supplied; --out writes only its caller-owned PNG. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; a selector crop reports its requested and delivered regions when its padded box cannot fit. An empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
+  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. Sessionless captures write one bundle under --artifact-dir when supplied; --out writes only its caller-owned PNG. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override, finishes CSS transitions before capture, and clears the override afterward. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; a selector crop reports its requested and delivered regions when its padded box cannot fit. An empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
 
 // ---------------------------------------------------------------------------
 // Test-injectable dependency seam (the CDP-stub test pattern; the capture
@@ -273,6 +273,31 @@ async function pageBorderRect(client: CDPClient, backendNodeId: number): Promise
 // page shot
 // ---------------------------------------------------------------------------
 
+async function finishColorTransitions(client: CDPClient): Promise<void> {
+  type FrameTree = { frame: { id: string }; childFrames?: FrameTree[] };
+  const tree = (await client.send('Page.getFrameTree')) as { frameTree?: FrameTree };
+  if (!tree.frameTree) throw new Error('Page.getFrameTree returned no frames for color-scheme capture.');
+  const frames = [tree.frameTree];
+  for (const frame of frames) {
+    frames.push(...(frame.childFrames ?? []));
+    const world = (await client.send('Page.createIsolatedWorld', {
+      frameId: frame.frame.id,
+      worldName: 'capture-color-scheme',
+    })) as { executionContextId?: number };
+    if (world.executionContextId === undefined) throw new Error(`No execution context for frame ${frame.frame.id}.`);
+    const result = (await client.send('Runtime.evaluate', {
+      contextId: world.executionContextId,
+      expression: `(() => {
+        document.getAnimations({ subtree: true })
+          .filter(animation => animation instanceof CSSTransition)
+          .forEach(transition => transition.finish());
+      })()`,
+      returnByValue: true,
+    })) as { result?: object; exceptionDetails?: { text?: string } };
+    if (!result.result || result.exceptionDetails) throw new Error(`Could not finish CSS transitions in frame ${frame.frame.id}: ${result.exceptionDetails?.text ?? 'page evaluation failed'}`);
+  }
+}
+
 export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
@@ -384,7 +409,10 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
       } else if (requestedCrop) {
         cropProvenance = { source: 'coordinates', requested: requestedCrop, zoom };
       }
-      const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage, crop: requestedCrop, zoom });
+      const screenshot = await captureScreenshotWithCssViewport(client, viewport, {
+        fullPage: parsed.fullPage, crop: requestedCrop, zoom,
+        ...(colorScheme ? { beforeCapture: () => finishColorTransitions(client) } : {}),
+      });
       const outPath = await resolveOutPath(parsed);
       writeScreenshot(outPath, screenshot.png);
       return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport, scrollOffset: screenshot.scrollOffset, crop: cropProvenance } as const;

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/cdp/commands/tab/list.ts

@@ -8,6 +8,7 @@
  * (titles, URLs, app names, target ids) flows through `data()`/`fact` (I-9).
  */
 import {
+  describeCdpPort,
   detectCdpPortsAsync,
   getDefaultBrowserId,
   pickPreferredEndpoint,
@@ -58,6 +59,13 @@ export interface UnreachableEndpoint {
   reason: string;
 }
 
+/** Arc lists only the tabs created over CDP: its ordinary tabs are not page targets. */
+const ARC_ENDPOINT_NOTE: FactLine = text`  note: Arc exposes only tabs opened over CDP as page targets; the tabs in its windows are not listed. Open one with "capture tab open <url> --port <port>", then "capture session start --port <port> --target <id>".`;
+
+function endpointNote(app: string | undefined): FactLine | undefined {
+  return app !== undefined && /^arc$/i.test(app.trim()) ? ARC_ENDPOINT_NOTE : undefined;
+}
+
 /** Pure `<tabs>` result builder — exported for tests. */
 export function buildTabsResult(
   endpoints: readonly EndpointTabs[],
@@ -85,7 +93,8 @@ export function buildTabsResult(
     const rows = ep.pages.map((t) =>
       line(text`  `, data(t.id.slice(0, 8)), text`  "`, data(t.title, 120), text`"  `, data(t.url, 300)),
     );
-    return lineList([header, ...rows]);
+    const note = endpointNote(ep.app);
+    return lineList([header, ...rows, ...(note ? [note] : [])]);
   });
 
   if (unreachable.length > 0) {
@@ -137,8 +146,10 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
   if (parsed.port) {
     try {
       const targets = await listTargets(parsed.port);
+      const described = await describeCdpPort(parsed.port).catch(() => null);
       reachable.push({
         port: parsed.port,
+        ...(described ? { app: described.app } : {}),
         preferred: false,
         ...(owned.has(parsed.port) ? { ownedPid: owned.get(parsed.port)!.pid } : {}),
         pages: targets

package/src/cdp/connection.ts

@@ -204,6 +204,14 @@ export async function connectForCommand(
 
   if (!tab) {
     const query = parsed.target ?? parsed.url;
+    if (parsed.targetSource === 'session' && activeSession) {
+      const where = activeSession.port ? ` on port ${activeSession.port}` : '';
+      throw captureError(
+        'precondition',
+        'target_unavailable',
+        `Session ${activeSession.sessionId}'s tab ${query}${where} is no longer listed — the browser closed or dropped it. Open a replacement with \`capture tab reset <url>${activeSession.port ? ` --port ${activeSession.port}` : ''}\` (repoints this session at it), or pick a live tab with \`capture tab list\` and pass \`--target <id>\`.`,
+      );
+    }
     throw captureError(
       'precondition',
       'target_unavailable',

package/src/cdp/detect.ts

@@ -199,27 +199,34 @@ export interface CdpEndpoint {
   hasPageTarget: boolean;
 }
 
+async function describeEndpoint(port: number, processNames: Map<number, string>): Promise<CdpEndpoint | null> {
+  const probe = await probeCdpPort(port);
+  if (!probe) return null;
+  const processName = processNames.get(port);
+  return {
+    port,
+    app: processName ?? probe.app,
+    bundleId: identifyBrowserBundleId(probe.browser, processName),
+    isElectron: probe.isElectron,
+    hasPageTarget: probe.hasPageTarget,
+  };
+}
+
+/** Identifies the app serving one known CDP port (null when it is not a CDP browser). */
+export async function describeCdpPort(port: number): Promise<CdpEndpoint | null> {
+  return describeEndpoint(port, getListeningProcessNames());
+}
+
 export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
   const ports = getLocalhostListeningPorts();
   const processNames = getListeningProcessNames();
   const results: CdpEndpoint[] = [];
 
   // Probe ports in parallel for speed
-  const probes = ports.map(async (port) => {
-    const probe = await probeCdpPort(port);
-    if (probe) {
-      const processName = processNames.get(port);
-      results.push({
-        port,
-        app: processName ?? probe.app,
-        bundleId: identifyBrowserBundleId(probe.browser, processName),
-        isElectron: probe.isElectron,
-        hasPageTarget: probe.hasPageTarget,
-      });
-    }
-  });
-
-  await Promise.all(probes);
+  await Promise.all(ports.map(async (port) => {
+    const endpoint = await describeEndpoint(port, processNames);
+    if (endpoint) results.push(endpoint);
+  }));
   return results;
 }
 

package/src/cdp/screenshot.ts

@@ -31,7 +31,7 @@ export interface ScreenshotCrop {
   readonly height: number;
 }
 
-type ScreenshotOptions = { fullPage?: boolean; crop?: ScreenshotCrop; zoom?: number };
+type ScreenshotOptions = { fullPage?: boolean; crop?: ScreenshotCrop; zoom?: number; beforeCapture?: () => Promise<void> };
 
 /** A region is reportable only if every number is finite and its size is positive; anything else would produce a fabricated scale. */
 function validRegion(region: CapturedRegion): CapturedRegion | undefined {
@@ -246,6 +246,7 @@ async function viewportScopedCapture(
       // Capture without downscaling when the optional metrics probe is unavailable.
     }
 
+    await options?.beforeCapture?.();
     const result = (await client.send(
       'Page.captureScreenshot',
       screenshotOpts,

package/src/interact.ts

@@ -352,23 +352,44 @@ async function axIdentityFor(
 // ---------------------------------------------------------------------------
 
 /**
- * Clicks a resolved target: scroll into view → box model → center-point
- * `Input.dispatchMouseEvent` press/release pair. When the caller supplies
+ * Resolves a live target, scrolls it into view, then resolves it again before
+ * dispatching a center-point `Input.dispatchMouseEvent` press/release pair. When the caller supplies
  * `opts.mark` and the transport records landmarks
  * ({@link LiveClient.sendMarked}), the INITIATING PRESS alone carries the
  * label — one logical click is one landmark, never two (the release and every
  * incidental call stay unmarked). Without a marked lane the press degrades to
  * a plain `send` (nothing is recording landmarks).
  */
+export async function clickLiveTarget(
+  client: LiveClient,
+  input: string,
+  opts: { mark?: string; inspectHitTest?: boolean; includeHitTestReceiver?: boolean } = {},
+): Promise<ClickDispatch | ResolutionFailure> {
+  const initial = await resolveLiveTarget(client, input);
+  if (!initial.ok) return initial;
+
+  await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId: initial.backendNodeId });
+
+  const current = await resolveLiveTarget(client, input);
+  if (!current.ok) return current;
+  return dispatchResolvedClick(client, current, opts);
+}
+
 export async function clickResolved(
   client: LiveClient,
   resolved: ResolvedTarget,
   opts: { mark?: string; inspectHitTest?: boolean; includeHitTestReceiver?: boolean } = {},
 ): Promise<ClickDispatch> {
-  const { backendNodeId } = resolved;
-
-  await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+  await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId: resolved.backendNodeId });
+  return dispatchResolvedClick(client, resolved, opts);
+}
 
+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;
@@ -391,7 +412,17 @@ export async function clickResolved(
   const dispatchY = Math.round(y);
   let hitTestReceiverBackendNodeId: number | undefined;
   if (opts.inspectHitTest) {
-    const hitTest = (await client.send('DOM.getNodeForLocation', { x: dispatchX, y: dispatchY })) as { backendNodeId?: unknown };
+    // 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,
+      });
+    }
+    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',
@@ -403,6 +434,8 @@ export async function clickResolved(
     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);
@@ -421,6 +454,21 @@ export async function clickResolved(
   };
 }
 
+/**
+ * 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 });

package/src/session/commands.ts

@@ -660,6 +660,17 @@ interface Acquisition {
   release(): Promise<void> | void;
 }
 
+/** True when the port's target list still contains this page target. */
+async function tabStillListed(port: number, targetId: string): Promise<boolean> {
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  try {
+    const found = await startWorld.findTabById(port, targetId);
+    return found !== null && found.type === 'page';
+  } catch {
+    return false;
+  }
+}
+
 async function start(parsed: ParsedArgs): Promise<void> {
   if (parsed.help) {
     console.log(START_USAGE);
@@ -750,6 +761,24 @@ async function start(parsed: ParsedArgs): Promise<void> {
           const openedTargetId = target.id;
           acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(openedPort, openedTargetId) });
           pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+          // Some browsers (Arc) acknowledge Target.createTarget and then drop the
+          // page. Reporting that tab as the session's target would leave every
+          // later command pointing at nothing, so confirm it is still listed.
+          if (!await tabStillListed(cdpPort!, target.id)) {
+            const lostId = target.id;
+            await startWorld.closeTarget(cdpPort!, lostId).catch(() => undefined);
+            acquired.pop();
+            target = await startWorld.openTab(cdpPort!, url);
+            const retryPort = cdpPort!;
+            const retryId = target.id;
+            acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(retryPort, retryId) });
+            pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+            if (!await tabStillListed(cdpPort!, target.id)) {
+              throw worldFailure(
+                `Port ${cdpPort} drops tabs created over CDP (${retryId} vanished twice). Use \`capture tab open ${url} --port ${cdpPort}\`, then \`capture session start --port ${cdpPort} --target <id>\`.`,
+              );
+            }
+          }
         }
       }