@crouton-kit/capture 1.4.19 → 1.4.21

package/README.md

@@ -217,3 +217,5 @@ The CLI is designed to be read by a model: errors are structured, every error ca
 ## License
 
 MIT
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute.

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,
@@ -10559,7 +10566,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.19";
+  const version = "1.4.21";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12661,7 +12668,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.19";
+  const version = "1.4.21";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -15128,6 +15135,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 +15222,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 +16453,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 +17023,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 +17053,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",
@@ -17219,9 +17280,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 };
     }
@@ -229039,6 +229100,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 +229226,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 +229262,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 +229274,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 +229998,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 +230019,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 +230063,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 +230098,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 +230112,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>".`;
   }
 });
 
@@ -267362,7 +267458,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.19";
+  const declared = "1.4.21";
   if (declared) {
     console.log(declared);
     return;

package/package.json

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

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>\`.`,
+              );
+            }
+          }
         }
       }