@crouton-kit/capture 1.3.19 → 1.3.21

package/src/cdp/color-scheme.ts

@@ -0,0 +1,47 @@
+import type { CDPClient } from './client.js';
+
+export type ColorScheme = 'dark' | 'light';
+
+type MediaClient = Pick<CDPClient, 'send'>;
+
+export function parseColorScheme(value: string | undefined): ColorScheme | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'dark' || value === 'light') return value;
+  throw new Error('--color-scheme must be dark or light');
+}
+
+/** Applies one media-feature override only for the supplied capture operation. */
+export async function withAppliedColorScheme<T>(client: MediaClient, colorScheme: ColorScheme | undefined, fn: () => Promise<T>): Promise<T> {
+  if (!colorScheme) return fn();
+  let ownsMediaOverride = false;
+  let primaryFailed = false;
+  let primaryError: unknown;
+  try {
+    // A rejected response does not prove Chrome rejected the request. Claim
+    // cleanup responsibility before awaiting it, just as viewport capture does.
+    ownsMediaOverride = true;
+    await client.send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-color-scheme', value: colorScheme }],
+    });
+    return await fn();
+  } catch (error) {
+    primaryFailed = true;
+    primaryError = error;
+    throw error;
+  } finally {
+    if (ownsMediaOverride) {
+      try {
+        await client.send('Emulation.setEmulatedMedia', { features: [] });
+      } catch (cleanupError) {
+        if (primaryFailed) {
+          throw new AggregateError(
+            [primaryError, cleanupError],
+            'Color-scheme capture failed and media-emulation cleanup also failed.',
+            { cause: primaryError },
+          );
+        }
+        throw cleanupError;
+      }
+    }
+  }
+}

package/src/cdp/commands/measure/index.ts

@@ -36,7 +36,7 @@ Every leaf defaults to rendered prose; --json mirrors the same result.
 Findings exit 0 — a report, not a failure.
 \`--gate\` (exit 2 on findings/changes) is accepted only by check and diff.
 
-<subcommand name="snap" args="[url|snap] [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled] [--pixels] [--state <state[:selector]>]... [--viewport <WxH>]..." whenToUse="drive + write the settled snapshot substrate every other leaf reads"/>
+<subcommand name="snap" args="[url|snap] [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled] [--pixels] [--state <state[:selector]>]... [--viewport <WxH>]... [--color-scheme <dark|light>]" whenToUse="drive + write the settled snapshot substrate every other leaf reads"/>
 <subcommand name="check" args="[url|snap] [--for <checks>] [--gate]" whenToUse="read threshold/fact measurements from one snapshot"/>
 <subcommand name="diff" args="--before <snap> --after <snap> [--pixels] [--full] [--gate]" whenToUse="structured before/after delta between two snapshots"/>
 <subcommand name="census" args="[--snap <id>]... [--url <url>]... [--set-file <path>] --axis <axis>" whenToUse="value distributions across one or more snapshots"/>

package/src/cdp/commands/measure/snap.ts

@@ -6,6 +6,7 @@ import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
 import { isRecorderHeldClient } from '../../recorder-client.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
+import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
 import { captureSnapshotSubstrate, COLLECTOR_NAMES, SnapshotCaptureTimeout } from '../../measure/snapshot.js';
 import type { CollectorOutcome } from '../../measure/types.js';
 import { sanitizeString } from '../../measure/redaction.js';
@@ -36,8 +37,9 @@ input:
   --pixels                    also write per-element raster crops
   --state <state[:selector]>  force a pseudo-state or real control state (repeatable)
   --viewport <WxH>            temporarily capture at a CSS-pixel viewport (repeatable); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
+  --color-scheme <dark|light> temporarily capture under this prefers-color-scheme value; cleared afterward
 output: <snapshot id=… path=…> — the settled artifact directory (geometry, styles, hit-test, text, forms, animation, ax, queries, focus, scroll, layers; per-element crops with --pixels) every other measure/motion query leaf reads instead of re-driving the browser; --json mirrors
-effects: drives the target page to capture; writes one snapshot artifact directory under the active (or a private one-shot) session`;
+effects: drives the target page to capture; writes one snapshot artifact directory under the active (or a private one-shot) session. --color-scheme transiently applies Emulation.setEmulatedMedia and clears it after capture.`;
 
 interface SnapshotMetaForBase {
   readonly url?: string | null;
@@ -216,7 +218,7 @@ function settledNote(settled: boolean, captured: boolean, settleMs: number, sett
  * seam rather than importing the substrate directly, preserving snap as the
  * sole live-driving primitive.
  */
-export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.positional[0], viewportValue = parsed.viewport): Promise<MeasureSnapCapture> {
+export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.positional[0], viewportValue = parsed.viewport, colorSchemeValue = parsed.colorScheme): Promise<MeasureSnapCapture> {
   if (parsed.positional.length > 1) {
     throw invalidInput('measure snap accepts at most one positional URL or snapshot reference');
   }
@@ -231,6 +233,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
   const viewport: ViewportSpec | undefined = viewportValue === undefined
     ? undefined
     : { label: viewportValue, ...parseViewport(viewportValue) };
+  const colorScheme = parseColorScheme(colorSchemeValue);
 
   let base: SnapRef | undefined;
   let baseUrl: string | null = null;
@@ -256,7 +259,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
   try {
     let artifacts: readonly string[] = [];
     await withConnection(connectionArgs, async (client, tab) => {
-      await withAppliedViewport(client, viewport, async () => {
+      await withAppliedColorScheme(client, colorScheme, async () => withAppliedViewport(client, viewport, async () => {
         const oneshot = active ? undefined : createOneshotSession('measure');
         const destination = active ? path.join(active.dir, 'measure', 'snaps') : oneshot!.artifactsDir;
         snapDir = path.join(destination, snapId);
@@ -272,10 +275,11 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
           pixels: parsed.pixels,
           state: parsed.state ?? [],
           viewport: viewport?.label ?? null,
+          colorScheme,
           skipCollectors: parsed.skipCollector ?? [],
         });
         artifacts = result.artifacts;
-      });
+      }));
     }, { settle: 0 });
 
     if (!snapDir) throw new Error('measure snap did not allocate an artifact directory');
@@ -290,6 +294,7 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
   const meta = readMeta<{
     url: string | null;
     viewport: string | null;
+    colorScheme?: ColorScheme;
     settled: boolean;
     settleMs: number;
     settleTimeoutMs: number;
@@ -313,6 +318,7 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
     attrs: {
       url: meta.url ?? undefined,
       viewport: meta.viewport ?? undefined,
+      'color-scheme': meta.colorScheme,
       elements,
       settled: meta.settled,
       'settle-ms': meta.settleMs,
@@ -358,7 +364,7 @@ export function classifySnapError(err: unknown): SnapErrorDetails {
   if (message.startsWith('--viewport cannot ')) {
     return { status: 'viewport_unavailable', message };
   }
-  if (message.startsWith('measure snap accepts') || message.startsWith('--settle-timeout') || message.startsWith('--viewport')) {
+  if (message.startsWith('measure snap accepts') || message.startsWith('--settle-timeout') || message.startsWith('--viewport') || message.startsWith('--color-scheme')) {
     return { status: 'invalid_input', message };
   }
   if (message.includes('No tab found') || message.includes('Use --target') || message.includes('Tab has no WebSocket debugger URL')) {
@@ -408,9 +414,10 @@ export async function cmdMeasureSnap(parsed: ParsedArgs, _args: string[]): Promi
       if (value === undefined) return undefined;
       return { label: value, ...parseViewport(value) };
     });
+    const colorScheme = parseColorScheme(parsed.colorScheme);
     const results = [] as RenderableResult[];
     for (const viewport of viewports) {
-      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport?.label);
+      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport?.label, colorScheme);
       captures.push(capture);
       results.push(buildSnapshotResult(capture));
     }

package/src/cdp/commands/page/click.ts

@@ -52,6 +52,33 @@ export function pageInputDeps(): PageInputDeps {
   return deps;
 }
 
+export interface PageInputScreenshot {
+  readonly screenshot: string | null;
+  readonly screenshotWarning: string | null;
+}
+
+/** A dispatched page action stays successful when only its follow-up screenshot times out. */
+export async function capturePageInputScreenshot(
+  client: Parameters<typeof autoScreenshot>[0],
+  action: string,
+  label: string,
+  noScreenshot?: boolean,
+): Promise<PageInputScreenshot> {
+  try {
+    return {
+      screenshot: await deps.autoScreenshot(client, action, label, noScreenshot),
+      screenshotWarning: null,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/^CDP request timeout \(\d+ms\): Page\.captureScreenshot$/.test(message)) throw error;
+    return {
+      screenshot: null,
+      screenshotWarning: `automatic screenshot timed out after the page action completed; no screenshot was saved (${message})`,
+    };
+  }
+}
+
 /**
  * The verb's settle window: `--settle <ms>` (including 0) wins outright;
  * otherwise the default is keyed off active-session presence (the in-session
@@ -147,7 +174,7 @@ input:
   --settle <ms>     network-settle window applied after the click (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <clicked backend-node-id=… role=… name=…> — resolved identity, dispatched coordinates, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <clicked backend-node-id=… role=… name=…> — resolved identity, dispatched coordinates, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   scrolls the target into view, then dispatches a real mouse press/release at its center; writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -177,8 +204,8 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
       const resolved = await resolveLiveTarget(live, target);
       if (!resolved.ok) return { failure: resolved } as const;
       const dispatch = await clickResolved(live, resolved);
-      const screenshot = await deps.autoScreenshot(client, 'click', target, parsed.noScreenshot);
-      return { dispatch, screenshot } as const;
+      const screenshotResult = await capturePageInputScreenshot(client, 'click', target, parsed.noScreenshot);
+      return { dispatch, ...screenshotResult } as const;
     },
   );
 
@@ -186,12 +213,13 @@ export async function cmdPageClick(parsed: ParsedArgs, _args: string[]): Promise
     return emitResolutionError(parsed, 'page click', outcome.failure);
   }
 
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
     fact`clicked ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) at x=${dispatch.x} y=${dispatch.y}`,
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+  if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
 
   emitResult(
     {

package/src/cdp/commands/page/index.ts

@@ -39,7 +39,7 @@ During a live composed recording every verb routes through the recorder.
 <subcommand name="scroll" args="<target> --to <top|bottom|px> [--no-screenshot]" whenToUse="scroll one resolved container to a position"/>
 <subcommand name="navigate" args="<url> [--settle <ms>]" whenToUse="navigate the tab and wait for load + settle"/>
 <subcommand name="exec" args="<code> | --file <path>" whenToUse="run arbitrary JS in the tab (expressions, return, await)"/>
-<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--out <path>]" whenToUse="look at the page right now without acting"/>
+<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]" whenToUse="look at the page right now without acting"/>
 <subcommand name="elements" args="[--all] [--limit <n>]" whenToUse="list what can be acted on — role, name, backend:<id> per element"/>
 
 capture page <leaf> -h    Per-leaf usage`;

package/src/cdp/commands/page/scroll.ts

@@ -13,6 +13,7 @@ import { resolveLiveTarget, scrollResolved, type LiveClient } from '../../../int
 import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
 import {
   pageInputDeps,
+  capturePageInputScreenshot,
   effectiveSettle,
   emitInvalidInput,
   emitResolutionError,
@@ -26,7 +27,7 @@ input:
   --settle <ms>     network-settle window applied after the scroll (default: 1000; 2500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, the container's resulting scrollTop, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, the container's resulting scrollTop, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   assigns the container's scrollTop in-page (may trigger lazy-load network); writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -74,8 +75,8 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
       // Same landmark shape `motion rec --do scroll:` records; carried by
       // the one mutating call when the transport records landmarks.
       const dispatch = await scrollResolved(live, resolved, to, { mark: `scroll:${target},to=${to}` });
-      const screenshot = await deps.autoScreenshot(client, 'scroll', target, parsed.noScreenshot);
-      return { dispatch, screenshot } as const;
+      const screenshotResult = await capturePageInputScreenshot(client, 'scroll', target, parsed.noScreenshot);
+      return { dispatch, ...screenshotResult } as const;
     },
   );
 
@@ -83,12 +84,13 @@ export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promis
     return emitResolutionError(parsed, 'page scroll', outcome.failure);
   }
 
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
     fact`scrolled ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) to ${dispatch.to} — scrollTop now ${dispatch.scrollTop}`,
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+  if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
 
   emitResult(
     {

package/src/cdp/commands/page/shot.ts

@@ -4,8 +4,9 @@
  * The navigational look: vision as navigator, never inspector — cheap, no
  * settling, no collectors. With no flags it captures the browser's ACTUAL
  * current viewport and performs zero `Emulation.*` calls; emulation exists
- * only when explicitly asked (`--viewport <WxH>` / `--full-page`), applied
- * as a transient `Emulation.setDeviceMetricsOverride` (+ ~150ms re-layout)
+ * only when explicitly asked (`--viewport <WxH>` / `--full-page` /
+ * `--color-scheme dark|light`), applied transiently; viewport emulation uses
+ * `Emulation.setDeviceMetricsOverride` (+ ~150ms re-layout)
  * and cleared after — two page-observable resizes, declared as the leaf's
  * effect in `-h` (I-1/I-2 posture). Explicit viewport emulation uses the
  * single `WxH` grammar (D10).
@@ -20,6 +21,7 @@ import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
 import { captureScreenshotWithCssViewport, type CapturedRegion } from '../../screenshot.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
+import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
 import { nextStepPath } from '../../../session-context.js';
 import { createOneshotSession } from '../../../session/commands.js';
 import { assertUnderCaptureRoot, writeBinaryPrivate } from '../../../session/artifacts.js';
@@ -36,13 +38,14 @@ 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
   --out <path>      destination file; default: the active session's shots/ sequence, or a fresh oneshot-*/page/ dir under the capture root when no session is active
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
   --json            mirror the result as JSON
 output:
-  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page> — 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, byte size, and the emulation fact (whether a transient override was applied, or its absence)
+  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-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, byte size, and any requested transient emulation
 effects:
-  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. With --viewport/--full-page: applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes (resize events fire; media queries flip and flip back)`;
+  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. --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.`;
 
 // ---------------------------------------------------------------------------
 // Test-injectable dependency seam (the CDP-stub test pattern; the capture
@@ -128,6 +131,7 @@ export function buildScreenshotResult(f: {
   cssViewport?: CapturedRegion;
   emulation: EmulationMode;
   viewport?: { width: number; height: number };
+  colorScheme?: ColorScheme;
 }): RenderableResult {
   // The denominator is the CSS region the image was actually cut from, so the
   // ratio stays true under page zoom, device pixel ratio, and the local
@@ -140,12 +144,15 @@ export function buildScreenshotResult(f: {
       ? fact`CSS-to-image scale: ${scale.x.toFixed(6)} image px/CSS px horizontally and ${scale.y.toFixed(6)} image px/CSS px vertically (captured CSS region ${round6(f.cssViewport.width)}×${round6(f.cssViewport.height)} at page origin ${round6(f.cssViewport.x)},${round6(f.cssViewport.y)}).`
       : text`CSS-to-image scale unavailable: the browser did not return the CSS region this capture covers.`,
     f.emulation === 'none'
-      ? text`emulation: none — the browser's actual current viewport was captured; no Emulation call was made.`
+      ? text`viewport emulation: none — the browser's actual current viewport was captured.`
       : f.emulation === 'viewport'
         ? fact`emulation: transient ${f.viewport!.width}x${f.viewport!.height} device-metrics override applied for the capture and cleared after — two page-observable resizes.`
         : f.viewport
           ? fact`emulation: transient full-page device-metrics override (from ${f.viewport.width}x${f.viewport.height}) applied for the capture and cleared after — two page-observable resizes.`
           : text`emulation: transient full-page device-metrics override applied for the capture and cleared after — two page-observable resizes.`,
+    f.colorScheme
+      ? fact`color scheme: transient prefers-color-scheme=${f.colorScheme} override applied for the capture and cleared after.`
+      : text`color scheme: browser default — no Emulation.setEmulatedMedia call was made.`,
   ];
   return {
     tag: 'screenshot',
@@ -160,6 +167,7 @@ export function buildScreenshotResult(f: {
       'css-to-image-x': scale?.x.toFixed(6),
       'css-to-image-y': scale?.y.toFixed(6),
       emulation: f.emulation,
+      'color-scheme': f.colorScheme,
     },
     summary: f.dimensions
       ? fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes.`
@@ -183,7 +191,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
       {
         tag: 'error',
         attrs: { command: 'page shot', code: 'invalid_input' },
-        summary: fact`received: ${parsed.positional.length} positional arguments; expected none — \`capture page shot [--viewport <WxH>] [--full-page] [--out <path>]\`.`,
+        summary: fact`received: ${parsed.positional.length} positional arguments; expected none — \`capture page shot [--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]\`.`,
       },
       { json: parsed.json },
     );
@@ -209,6 +217,22 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
     }
   }
 
+  let colorScheme: ColorScheme | undefined;
+  try {
+    colorScheme = parseColorScheme(parsed.colorScheme);
+  } catch {
+    emitResult(
+      {
+        tag: 'error',
+        attrs: { command: 'page shot', code: 'invalid_color_scheme' },
+        summary: fact`received: --color-scheme ${parsed.colorScheme}; expected dark or light.`,
+      },
+      { json: parsed.json },
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   const emulation: EmulationMode = parsed.fullPage ? 'full-page' : viewport ? 'viewport' : 'none';
 
   // connection.ts derives the recorder-routed action label from
@@ -216,14 +240,14 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
   // restore the verb so stderr diagnostics identify this leaf.
   const result = await deps.withConnection(
     { ...parsed, command: 'shot' },
-    async (client) => {
+    async (client) => withAppliedColorScheme(client, colorScheme, async () => {
       const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage });
       const outPath = await resolveOutPath(parsed);
       writeScreenshot(outPath, screenshot.png);
       return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport };
-    },
+    }),
     { settle: 0 },
   );
 
-  emitResult(buildScreenshotResult({ ...result, emulation, viewport }), { json: parsed.json });
+  emitResult(buildScreenshotResult({ ...result, emulation, viewport, colorScheme }), { json: parsed.json });
 }

package/src/cdp/commands/page/type.ts

@@ -18,6 +18,7 @@ import {
 import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
 import {
   pageInputDeps,
+  capturePageInputScreenshot,
   effectiveSettle,
   emitInvalidInput,
   emitResolutionError,
@@ -31,7 +32,7 @@ input:
   --settle <ms>     network-settle window applied after typing (default: 500; 1500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   dispatches a real focus click (when --into) followed by real text insertion; writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -69,8 +70,8 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
         await typeText(live, textArg);
       }
       // Screenshot label identifies the field, never the typed content.
-      const screenshot = await deps.autoScreenshot(client, 'type', parsed.into ?? 'focused element', parsed.noScreenshot);
-      return { dispatch, screenshot } as const;
+      const screenshotResult = await capturePageInputScreenshot(client, 'type', parsed.into ?? 'focused element', parsed.noScreenshot);
+      return { dispatch, ...screenshotResult } as const;
     },
   );
 
@@ -78,7 +79,7 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
     return emitResolutionError(parsed, 'page type', outcome.failure);
   }
 
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows: FactLine[] = [
     dispatch
       ? fact`typed "${textArg}" into ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}), focus click at x=${dispatch.x} y=${dispatch.y}`
@@ -86,6 +87,7 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+  if (screenshotWarning) rows.push(fact`screenshot-warning: ${screenshotWarning}`);
 
   emitResult(
     {

package/src/cdp/measure/collectors/styles.ts

@@ -35,6 +35,8 @@ export type { Specificity, CSSRange, WinningDeclaration } from './style-provenan
 
 const STYLES_MAX_ELEMENTS = 150;
 const PROVENANCE_CONCURRENCY = 8;
+/** Bounds queued provenance work without abandoning in-flight CDP requests on the shared snap connection. Matches snapshot.ts's per-request bound but remains local to avoid a collector/orchestrator import cycle. */
+const PROVENANCE_BUDGET_MS = 5_000;
 
 /** Full computed-style snapshot tracked per element — broad, cheap (no CDP round trip; read via `getComputedStyle` in one `Runtime.evaluate`). */
 const COMPUTED_PROPERTIES = [
@@ -95,6 +97,10 @@ export interface StylesCoverage {
   keptElements: number;
   /** `true` when {@link STYLES_MAX_ELEMENTS} dropped one or more candidate elements from enumeration — an explicit fact (I-5), never a silent cap. */
   elementsTruncated: boolean;
+  /** `true` when the bounded provenance pass stopped starting element reads before every enumerated element was inspected; completed in-flight reads are still included. */
+  provenanceTruncated: boolean;
+  /** Present only when {@link provenanceTruncated} is true; names the factual bound that stopped additional provenance requests. */
+  provenanceTruncationReason?: 'collector-time-budget';
 }
 
 export interface StylesReport {
@@ -205,18 +211,33 @@ function resolvedIdentity(backendNodeId: number | undefined): { backendNodeId: n
   return backendNodeId === undefined ? { backendNodeId: null, identityUnresolved: true } : { backendNodeId };
 }
 
-/** Limits expensive per-element CDP provenance reads without changing document order. */
-async function mapWithConcurrency<T, R>(values: readonly T[], limit: number, fn: (value: T, index: number) => Promise<R>): Promise<R[]> {
-  const result = new Array<R>(values.length);
+/**
+ * Limits expensive per-element CDP provenance reads without changing document
+ * order. Once its budget expires it starts no more reads, but awaits the
+ * current worker batch so no CDP work is left running under the next collector.
+ */
+async function mapWithConcurrency<T, R>(
+  values: readonly T[],
+  limit: number,
+  budgetMs: number,
+  fn: (value: T, index: number) => Promise<R>,
+): Promise<{ values: Array<R | undefined>; truncated: boolean }> {
+  const result = Array<R | undefined>(values.length).fill(undefined);
+  const deadline = Date.now() + budgetMs;
   let next = 0;
+  let truncated = false;
   const worker = async (): Promise<void> => {
     while (next < values.length) {
+      if (Date.now() >= deadline) {
+        truncated = true;
+        return;
+      }
       const index = next++;
       result[index] = await fn(values[index]!, index);
     }
   };
   await Promise.all(Array.from({ length: Math.min(limit, values.length) }, worker));
-  return result;
+  return { values: result, truncated };
 }
 
 // ============================================================================
@@ -305,48 +326,49 @@ async function collectStylesInner(
 
   const sourceCache = new Map<string, Promise<ResolvedSourceLocation>>();
 
-  const elements = await mapWithConcurrency(facts, PROVENANCE_CONCURRENCY, async (fact, index): Promise<StylesElementRecord> => {
-      const ref = resolved[index];
-      const computed = normalizeComputed(fact.computed);
-
-      // A `noDeclarationRecord` is reserved for a SUCCESSFUL matched-styles response that genuinely had
-      // no candidate for a property — an honest "nothing declares this" fact. When provenance itself
-      // couldn't be inspected (no CDP nodeId, or `CSS.getMatchedStylesForNode` failed), that's a different
-      // fact — "unknown", not "none" — so `winningDeclarations` is left empty and `provenanceUnavailable`
-      // is set, rather than conflating the two into misleading no-declaration records.
-      let winningDeclarations: WinningDeclaration[];
-      let provenanceUnavailable: boolean | undefined;
-      if (ref?.nodeId !== undefined) {
-        try {
-          const matched = (await client.send('CSS.getMatchedStylesForNode', {
-            nodeId: ref.nodeId,
-          })) as CDPMatchedStylesResponse;
-          winningDeclarations = await buildWinningDeclarations(
-            client,
-            matched,
-            computed,
-            sourceCache,
-            styleSheetUrls,
-            PROVENANCE_PROPERTIES,
-          );
-        } catch {
-          winningDeclarations = [];
-          provenanceUnavailable = true;
-        }
-      } else {
+  const provenance = await mapWithConcurrency(facts, PROVENANCE_CONCURRENCY, PROVENANCE_BUDGET_MS, async (fact, index): Promise<StylesElementRecord> => {
+    const ref = resolved[index];
+    const computed = normalizeComputed(fact.computed);
+
+    // A `noDeclarationRecord` is reserved for a SUCCESSFUL matched-styles response that genuinely had
+    // no candidate for a property — an honest "nothing declares this" fact. When provenance itself
+    // couldn't be inspected (no CDP nodeId, or `CSS.getMatchedStylesForNode` failed), that's a different
+    // fact — "unknown", not "none" — so `winningDeclarations` is left empty and `provenanceUnavailable`
+    // is set, rather than conflating the two into misleading no-declaration records.
+    let winningDeclarations: WinningDeclaration[];
+    let provenanceUnavailable: boolean | undefined;
+    if (ref?.nodeId !== undefined) {
+      try {
+        const matched = (await client.send('CSS.getMatchedStylesForNode', {
+          nodeId: ref.nodeId,
+        })) as CDPMatchedStylesResponse;
+        winningDeclarations = await buildWinningDeclarations(
+          client,
+          matched,
+          computed,
+          sourceCache,
+          styleSheetUrls,
+          PROVENANCE_PROPERTIES,
+        );
+      } catch {
         winningDeclarations = [];
         provenanceUnavailable = true;
       }
+    } else {
+      winningDeclarations = [];
+      provenanceUnavailable = true;
+    }
 
-      return {
-        id: `s-${index}`,
-        selector: sanitizeString(fact.cssPath),
-        ...resolvedIdentity(ref?.backendNodeId),
-        computed,
-        winningDeclarations,
-        provenanceUnavailable,
-      };
-    });
+    return {
+      id: `s-${index}`,
+      selector: sanitizeString(fact.cssPath),
+      ...resolvedIdentity(ref?.backendNodeId),
+      computed,
+      winningDeclarations,
+      provenanceUnavailable,
+    };
+  });
+  const elements = provenance.values.filter((element): element is StylesElementRecord => element !== undefined);
 
   ctx.write.json('styles.json', {
     elements,
@@ -356,7 +378,9 @@ async function collectStylesInner(
       shadowRootsNotWalked: inventory.shadowRootsNotWalked,
       totalCandidateElements: inventory.total,
       keptElements: elements.length,
-      elementsTruncated: inventory.total > elements.length,
+      elementsTruncated: inventory.total > facts.length,
+      provenanceTruncated: provenance.truncated,
+      ...(provenance.truncated ? { provenanceTruncationReason: 'collector-time-budget' as const } : {}),
     },
     styleSheetHeaders: styleSheetHeaders,
     identity,