@crouton-kit/capture 1.3.17 → 1.3.19

package/src/cdp/record.ts

@@ -11,6 +11,42 @@ import { type CDPTarget } from './types.js';
  * load-wait helper. Navigation of an existing tab lives in
  * `./commands/page/navigate.ts` via ordinary page targeting.
  */
+function isMissingDefaultExecutionContext(err: unknown): boolean {
+  return err instanceof Error && err.message === 'Cannot find default execution context';
+}
+
+/**
+ * Arc can report the page load before it has installed the default execution
+ * context (notably for hash-routed Gmail URLs). Retry only that known transient
+ * CDP error; every other Runtime.evaluate failure remains fatal.
+ */
+export async function readReadyStateWithRetry(
+  client: Pick<CDPClient, 'send'>,
+  timeout: number,
+): Promise<unknown> {
+  const deadline = Date.now() + timeout;
+  let lastRetryableError: unknown;
+  while (true) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      if (lastRetryableError) throw lastRetryableError;
+      throw new Error('Runtime.evaluate deadline exceeded');
+    }
+    try {
+      const result = await client.send('Runtime.evaluate', {
+        expression: 'document.readyState',
+        returnByValue: true,
+      }, remaining);
+      return (result as { result?: { value?: unknown } } | undefined)?.result?.value;
+    } catch (err) {
+      const remainingAfterAttempt = deadline - Date.now();
+      if (!isMissingDefaultExecutionContext(err) || remainingAfterAttempt <= 0) throw err;
+      lastRetryableError = err;
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, remainingAfterAttempt)));
+    }
+  }
+}
+
 export async function navigateAndWait(
   port: number,
   url: string,
@@ -59,11 +95,7 @@ export async function navigateAndWait(
     });
 
     try {
-      const result = await client.send('Runtime.evaluate', {
-        expression: 'document.readyState',
-        returnByValue: true,
-      });
-      const readyState = (result as { result?: { value?: unknown } } | undefined)?.result?.value;
+      const readyState = await readReadyStateWithRetry(client, timeout);
       if (readyState !== 'complete') {
         await loadPromise;
         if (loadTimeoutError) throw loadTimeoutError;

package/src/cdp/screenshot.ts

@@ -4,6 +4,25 @@ import { nextStepPath } from '../session-context.js';
 import { writeBinaryPrivate } from '../session/artifacts.js';
 import { withScopeSerialization } from './scope-lock.js';
 
+/**
+ * The CSS-pixel rectangle a captured PNG covers: its page-coordinate origin and
+ * its size. `image px / width` (and `/ height`) is the capture's true CSS-to-
+ * image scale, and `x`/`y` turn a page coordinate into an image coordinate.
+ */
+export interface CapturedRegion {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** 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 {
+  const finite = [region.x, region.y, region.width, region.height].every((n) => typeof n === 'number' && Number.isFinite(n));
+  if (!finite || region.width <= 0 || region.height <= 0) return undefined;
+  return region;
+}
+
 /**
  * Downscales a PNG so its longest side fits within maxDim, using a box
  * filter. Used when a clipped/scaled CDP capture is unavailable and the raw
@@ -65,9 +84,27 @@ export async function captureScreenshot(
   viewport?: { width: number; height: number },
   options?: { fullPage?: boolean },
 ): Promise<Buffer> {
-  return withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
+  const result = await withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
     viewportScopedCapture(client, viewport, options),
   );
+  return result.png;
+}
+
+/**
+ * Captures a PNG and the CSS-pixel region the image actually covers — the clip
+ * sent to `Page.captureScreenshot` (or, for an unclipped capture, the visual
+ * viewport). Dividing the PNG's pixel dimensions by that region's size is the
+ * true CSS-to-image scale; the layout viewport (`window.innerWidth`) is a
+ * different coordinate space under page zoom and must not stand in for it.
+ */
+export async function captureScreenshotWithCssViewport(
+  client: CDPClient,
+  viewport?: { width: number; height: number },
+  options?: { fullPage?: boolean },
+): Promise<{ png: Buffer; cssViewport?: CapturedRegion }> {
+  return withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
+    viewportScopedCapture(client, viewport, options, true),
+  );
 }
 
 /**
@@ -81,7 +118,8 @@ async function viewportScopedCapture(
   client: CDPClient,
   viewport?: { width: number; height: number },
   options?: { fullPage?: boolean },
-): Promise<Buffer> {
+  includeCssViewport = false,
+): Promise<{ png: Buffer; cssViewport?: CapturedRegion }> {
   const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
   let ownsDeviceMetricsOverride = false;
   let primaryFailed = false;
@@ -102,7 +140,7 @@ async function viewportScopedCapture(
     }
 
     if (options?.fullPage) {
-      const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
+      const layoutMetrics = (await client.send('Page.getLayoutMetrics', {}, 5000)) as {
         contentSize?: { width: number; height: number };
         cssVisualViewport?: { clientWidth: number };
       };
@@ -123,8 +161,13 @@ async function viewportScopedCapture(
       captureBeyondViewport: false,
     };
 
+    // The CSS-pixel region the returned image covers, set from the clip that is
+    // actually sent. An unclipped capture clears it again and it is read from the
+    // live visual viewport below instead.
+    let capturedRegion: CapturedRegion | undefined;
+
     try {
-      const metrics = (await client.send('Page.getLayoutMetrics')) as {
+      const metrics = (await client.send('Page.getLayoutMetrics', {}, 5000)) as {
         cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
       };
       // Snap the clip to integer CSS pixels: browser zoom (e.g. 110%) makes the
@@ -139,7 +182,7 @@ async function viewportScopedCapture(
       const dprResult = (await client.send('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
-      })) as { result: { value: number } };
+      }, 5000)) as { result: { value: number } };
       const dpr = dprResult.result.value ?? 1;
 
       const actualMaxSide = Math.max(vw, vh) * dpr;
@@ -148,6 +191,9 @@ async function viewportScopedCapture(
         ...screenshotOpts,
         clip: { x: sx, y: sy, width: vw, height: vh, scale },
       };
+      // The clip is what the image is cut from, rounding included — not the
+      // fractional viewport it was derived from.
+      capturedRegion = validRegion({ x: sx, y: sy, width: vw, height: vh });
     } catch {
       // Capture without downscaling when the optional metrics probe is unavailable.
     }
@@ -155,6 +201,7 @@ async function viewportScopedCapture(
     const result = (await client.send(
       'Page.captureScreenshot',
       screenshotOpts,
+      15000,
     )) as { data?: string };
     let png = Buffer.from(result.data ?? '', 'base64');
 
@@ -167,7 +214,7 @@ async function viewportScopedCapture(
       const retry = (await client.send('Page.captureScreenshot', {
         ...screenshotOpts,
         clip: { ...clip, scale: 1 },
-      })) as { data?: string };
+      }, 15000)) as { data?: string };
       png = Buffer.from(retry.data ?? '', 'base64');
       if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
     }
@@ -178,9 +225,37 @@ async function viewportScopedCapture(
       const retry = (await client.send('Page.captureScreenshot', {
         format: 'png',
         captureBeyondViewport: false,
-      })) as { data?: string };
+      }, 15000)) as { data?: string };
       png = Buffer.from(retry.data ?? '', 'base64');
       if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
+      // An unclipped capture covers the visual viewport itself, not the integer
+      // clip that was refused — and the two failed attempts above can have taken
+      // 30 seconds, so the viewport sampled before them is no longer evidence.
+      if (png.length > 0) capturedRegion = undefined;
+    }
+
+    // The image was captured unclipped (no clip was ever sent, or the clipped
+    // attempts were refused), so it covers the visual viewport. Read it as it
+    // stands now rather than reporting the layout viewport, which is a different
+    // space under page zoom, or a sample taken before a failed attempt.
+    if (includeCssViewport && !capturedRegion) {
+      try {
+        const response = (await client.send('Runtime.evaluate', {
+          expression: '(() => { const v = window.visualViewport; return v ? { x: v.pageLeft, y: v.pageTop, width: v.width, height: v.height } : null; })()',
+          returnByValue: true,
+        }, 5000)) as { result?: { value?: Record<string, unknown> | null } };
+        const value = response.result?.value;
+        if (value) {
+          capturedRegion = validRegion({
+            x: Number(value.x),
+            y: Number(value.y),
+            width: Number(value.width),
+            height: Number(value.height),
+          });
+        }
+      } catch {
+        // The image remains usable; only its CSS-coordinate mapping is unavailable.
+      }
     }
 
     if (png.length === 0) {
@@ -189,7 +264,7 @@ async function viewportScopedCapture(
       );
     }
 
-    return png;
+    return { png, ...(includeCssViewport && capturedRegion ? { cssViewport: capturedRegion } : {}) };
   } catch (error) {
     primaryFailed = true;
     primaryError = error;

package/src/cdp/targets.ts

@@ -1,5 +1,6 @@
 import { CDPClient } from './client.js';
 import { detectCdpPortsAsync } from './detect.js';
+import { touchOwnedBrowser } from './browser-process.js';
 import { type CDPTarget } from './types.js';
 
 /**
@@ -30,6 +31,10 @@ export async function getBrowserClient(
   }
   const client = new CDPClient(version.webSocketDebuggerUrl);
   await client.waitReady();
+  // Every browser-level connection funnels through here, which makes this the
+  // one place that can tell capture's idle sweep the browser is still in use.
+  // A port capture did not launch has no registry record and this is a no-op.
+  touchOwnedBrowser(port);
   return { client, browserWsUrl: version.webSocketDebuggerUrl };
 }
 

package/src/cdp/types.ts

@@ -25,6 +25,8 @@ export interface ParsedArgs {
    * can auto-append recorded traffic to the session HAR. */
   har?: string;
   new?: boolean;
+  /** `tab launch --headed` — a visible window instead of headless. */
+  headed?: boolean;
   target?: string;
   /** Where `target` was assigned from: an actual `--target` flag, active-session
    * autofill, or the ambient `CDP_TARGET` env var. Recorded at the assignment
@@ -68,6 +70,8 @@ export interface ParsedArgs {
   settleTimeout?: number;
   /** `snap --capture-unsettled` — write full substrate despite non-settlement. */
   captureUnsettled?: boolean;
+  /** `snap --skip-collector <name>` — repeatable; one entry per occurrence. */
+  skipCollector?: string[];
   /** `snap|diff|mask --pixels` — include raster crop/diff facts. */
   pixels?: boolean;
   /** `snap --state <state[:selector]>` — repeatable; one entry per occurrence. */

package/src/har-manager.ts

@@ -552,8 +552,8 @@ function vEntry(v: unknown, source: string, path: string): HAREntry {
 
   // Response-state ⇄ status coupling.
   if (capResponse.state === 'received') {
-    if (status < 100 || status > 599) {
-      fail(source, `${path}.response.status`, 'a received response requires status 100..599');
+    if ((status < 100 || status > 599) && !(terminal.kind === 'redirect' && status === 0)) {
+      fail(source, `${path}.response.status`, 'a received response requires status 100..599 (or 0 for a redirect with no HTTP response)');
     }
   } else {
     // unavailable
@@ -566,8 +566,8 @@ function vEntry(v: unknown, source: string, path: string): HAREntry {
       fail(source, `${path}._capture.clocks.responseMonotonic`, 'must be null when no response was received');
     }
   }
-  if (status === 0 && capResponse.state !== 'unavailable') {
-    fail(source, `${path}.response.status`, 'status 0 is permitted only when _capture.response.state is "unavailable"');
+  if (status === 0 && capResponse.state !== 'unavailable' && terminal.kind !== 'redirect') {
+    fail(source, `${path}.response.status`, 'status 0 is permitted only for an unavailable response or a redirect with no HTTP response');
   }
 
   // Terminal ⇄ response/status/body coupling.
@@ -582,8 +582,8 @@ function vEntry(v: unknown, source: string, path: string): HAREntry {
     if (capResponse.state !== 'received') {
       fail(source, `${path}._capture.response.state`, 'a redirect requires a received response');
     }
-    if (status < 300 || status > 399) {
-      fail(source, `${path}.response.status`, 'a redirect requires status 300..399');
+    if (status !== 0 && (status < 300 || status > 399)) {
+      fail(source, `${path}.response.status`, 'a redirect requires status 0 (no HTTP response) or 300..399');
     }
     if (body.state !== 'not_applicable' || body.reason !== 'redirect') {
       fail(source, `${path}._capture.body`, 'a redirect requires body not_applicable/redirect');
@@ -666,17 +666,18 @@ function vIncompleteResponse(
   path: string,
   minResponseMonotonic: number,
   allowUnknownClock = false,
+  allowNoHttpStatus = false,
 ): IncompleteResponse {
   const o = vObject(v, source, path);
   exactKeys(o, ['status', 'headers', 'responseMonotonic'], source, path);
   const responseMonotonic = o.responseMonotonic === null
     ? allowUnknownClock ? null : fail(source, `${path}.responseMonotonic`, 'must be a finite number')
     : vFiniteMin(o.responseMonotonic, minResponseMonotonic, source, `${path}.responseMonotonic`);
-  return {
-    status: vIntInRange(o.status, 100, 599, source, `${path}.status`),
-    headers: vHeaders(o.headers, source, `${path}.headers`),
-    responseMonotonic,
-  };
+  const status = vIntInRange(o.status, 0, 599, source, `${path}.status`);
+  if ((status < 100 && status !== 0) || (status === 0 && (!allowNoHttpStatus || responseMonotonic !== null))) {
+    fail(source, `${path}.status`, 'must be 100..599 (or 0 for a redirect with no HTTP response)');
+  }
+  return { status, headers: vHeaders(o.headers, source, `${path}.headers`), responseMonotonic };
 }
 
 function vStoppedBeforeTerminal(
@@ -754,9 +755,9 @@ function vInvalidClockOrder(
   const generation = vSafeIntMin(o.generation, 1, source, `${path}.generation`);
   const startedDateTime = vString(o.startedDateTime, source, `${path}.startedDateTime`);
   const request = vRequest(o.request, source, `${path}.request`);
-  const response =
-    o.response === null ? null : vIncompleteResponse(o.response, source, `${path}.response`, 0, true);
   const terminal = vInvalidClockTerminal(o.terminal, source, `${path}.terminal`);
+  const response =
+    o.response === null ? null : vIncompleteResponse(o.response, source, `${path}.response`, 0, true, terminal.kind === 'redirect');
 
   const cap = vObject(o._capture, source, `${path}._capture`);
   exactKeys(cap, ['schemaVersion', 'requestWallTime', 'requestMonotonic'], source, `${path}._capture`);
@@ -775,8 +776,8 @@ function vInvalidClockOrder(
   // CDP redirectResponse preserves redirect facts but has no independently observed response clock.
   if (terminal.kind === 'redirect') {
     if (response === null) fail(source, `${path}.response`, 'a redirect terminal requires an observed response');
-    if (response.status < 300 || response.status > 399) {
-      fail(source, `${path}.response.status`, 'a redirect terminal requires status 300..399');
+    if (response.status !== 0 && (response.status < 300 || response.status > 399)) {
+      fail(source, `${path}.response.status`, 'a redirect terminal requires status 0 (no HTTP response) or 300..399');
     }
     if (response.responseMonotonic !== null) {
       fail(source, `${path}.response.responseMonotonic`, 'must be null for a redirect terminal');

package/src/interact.ts

@@ -89,6 +89,11 @@ export type ResolutionFailure =
       readonly input: string;
       readonly acceptedPrefixes: typeof ACCEPTED_LIVE_PREFIXES;
     }
+  | {
+      readonly ok: false;
+      readonly code: 'invalid-css-selector';
+      readonly input: string;
+    }
   | {
       readonly ok: false;
       readonly code: 'no-match' | 'ambiguous';
@@ -222,10 +227,21 @@ async function resolveLiveCss(
 ): Promise<ResolvedTarget | ResolutionFailure> {
   await client.send('DOM.enable');
   const { root } = (await client.send('DOM.getDocument', { depth: 0 })) as { root: { nodeId: number } };
-  const { nodeIds } = (await client.send('DOM.querySelectorAll', {
-    nodeId: root.nodeId,
-    selector,
-  })) as { nodeIds: number[] };
+  let nodeIds: number[];
+  try {
+    ({ nodeIds } = (await client.send('DOM.querySelectorAll', {
+      nodeId: root.nodeId,
+      selector,
+    })) as { nodeIds: number[] });
+  } catch (error) {
+    // Chrome reports a malformed CSS selector from this CDP method as the
+    // otherwise opaque "DOM Error while querying". The bare grammar is CSS;
+    // make the accessible-name retry explicit instead of leaking that error.
+    if (error instanceof Error && error.message.includes('DOM Error while querying')) {
+      return { ok: false, code: 'invalid-css-selector', input };
+    }
+    throw error;
+  }
 
   if (nodeIds.length === 1) {
     const backendNodeId = await backendNodeIdFor(client, nodeIds[0]);

package/src/output/render.ts

@@ -56,6 +56,8 @@ export const RESULT_TAGS = [
   'tab-opened',
   'tab-closed',
   'tab-reset',
+  'browser-launched',
+  'browser-quit',
   'network',
   'cdp-result',
   'libs',

package/src/registry.ts

@@ -87,7 +87,7 @@ const ref = 'css:<selector> | backend:<id> | axid:<id> | ax:<name> | text:<text>
 
 export const CAPTURE_REGISTRY: RegistryBranch = branch('', 'Capture — browser evidence and automation over CDP.', [
   branch('session', 'persistent browser-work lifecycle and artifact bundles.', [
-    leaf('session start', 'start a fresh persistent capture session.', { flags: [requiredValue('--url', 'absolute-http(s)-url'), port()], effects: effects(true, true, true), constraints: 'Required singleton --url <absolute-http(s)-url>; optional singleton --port <1..65535>. No target, prefix, positional URL, or ambient CDP selection.', orderedOutput: 'Exact session ID; open lifecycle; full target ID; endpoint; observed URL; target_live=true; scope key; active generation.', artifactOwnership: 'Exclusively allocates the session directory and atomically publishes the canonical session record before its scoped pointer.' }),
+    leaf('session start', 'open or prepare a tab for a persistent capture session.', { flags: [value('--url', 'absolute-http(s)-url'), bool('--hold'), port()], effects: effects(true, true, true), constraints: 'Optional singleton --url <absolute-http(s)-url> opens a fresh tab through Target.createTarget; endpoints such as Electron that reject Target.createTarget cannot use --url. Optional singleton --hold retains a browser connection; optional singleton --port <1..65535> selects its endpoint. To work against an existing tab, omit --url, run `capture session start --hold --port <port>`, list it with `capture tab list --port <port>`, then run `capture page navigate <url> --target <target-id> --port <port>`; that navigate command adopts the target and later page commands auto-target it. No target, prefix, positional URL, or ambient CDP selection on session start.', orderedOutput: 'Exact session ID; open lifecycle; full target ID or null; endpoint or null; observed URL or null; target_live=true when a tab was opened; scope key; active generation.', artifactOwnership: 'Exclusively allocates the session directory and atomically publishes the canonical session record before its scoped pointer.' }),
     leaf('session stop', 'stop and bundle one exact capture session.', { positionals: [positional('session-id', 'exact-session-id')], effects: effects(true, true, true), constraints: 'One exact case-sensitive session ID; no prefixes. Only matching open/stopping/completed lifecycle records are accepted before bundle effects.', orderedOutput: 'Exact ID; stop-operation ID; stopped lifecycle; final bundle access; pointer outcome deleted|absent|superseded.', artifactOwnership: 'Resumes the recorded operation and owns bundle staging/publication; never rolls lifecycle back to open.', recovery: 'session_stop_state_invalid: inspect capture session view <exact-session-id> and preserve the session directory; never delete or allocate a new stop. session_stop_staging_cleanup_failed: correct access at the reported staging path and retry the identical capture session stop <exact-session-id>. session_stop_bundle_failed: correct the reported bundle/filesystem cause and retry that identical command. Both retries resume the recorded operation.' }),
     leaf('session list', 'list same-user host capture sessions.', { effects: effects(false, true), constraints: 'No target/session filters or ambient defaults.', orderedOutput: 'Rows sorted by exact session ID: ID, lifecycle, active_in_current_scope, full target ID or null, endpoint or null, target_live.' }),
     leaf('session view', 'view one exact capture session.', { positionals: [positional('session-id', 'exact-session-id')], effects: effects(false, true), constraints: 'One exact case-sensitive session ID; no prefix.' }),