@crouton-kit/capture 1.3.20 → 1.3.21

package/bin/capture

@@ -10231,7 +10231,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.3.20";
+  const version = "1.3.21";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -11990,7 +11990,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.3.20";
+  const version = "1.3.21";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -15943,6 +15943,21 @@ var init_interact = __esm({
 function pageInputDeps() {
   return deps2;
 }
+async function capturePageInputScreenshot(client, action, label2, noScreenshot) {
+  try {
+    return {
+      screenshot: await deps2.autoScreenshot(client, action, label2, 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})`
+    };
+  }
+}
 function effectiveSettle(parsed, defaults) {
   if (parsed.settle !== void 0) return parsed.settle;
   return deps2.getActiveSession() !== null ? defaults.session : defaults.standalone;
@@ -16024,19 +16039,20 @@ async function cmdPageClick(parsed, _args) {
       const resolved = await resolveLiveTarget(live, target);
       if (!resolved.ok) return { failure: resolved };
       const dispatch2 = await clickResolved(live, resolved);
-      const screenshot2 = await deps2.autoScreenshot(client, "click", target, parsed.noScreenshot);
-      return { dispatch: dispatch2, screenshot: screenshot2 };
+      const screenshotResult = await capturePageInputScreenshot(client, "click", target, parsed.noScreenshot);
+      return { dispatch: dispatch2, ...screenshotResult };
     }
   );
   if ("failure" in outcome) {
     return emitResolutionError(parsed, "page click", outcome.failure);
   }
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows = [
     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(
     {
       tag: "clicked",
@@ -16066,7 +16082,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=\u2026 role=\u2026 name=\u2026> \u2014 resolved identity, dispatched coordinates, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+  <clicked backend-node-id=\u2026 role=\u2026 name=\u2026> \u2014 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`;
   }
@@ -16101,19 +16117,20 @@ async function cmdPageType(parsed, _args) {
       } else {
         await typeText(live, textArg);
       }
-      const screenshot2 = await deps7.autoScreenshot(client, "type", parsed.into ?? "focused element", parsed.noScreenshot);
-      return { dispatch: dispatch2, screenshot: screenshot2 };
+      const screenshotResult = await capturePageInputScreenshot(client, "type", parsed.into ?? "focused element", parsed.noScreenshot);
+      return { dispatch: dispatch2, ...screenshotResult };
     }
   );
   if ("failure" in outcome) {
     return emitResolutionError(parsed, "page type", outcome.failure);
   }
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows = [
     dispatch ? fact`typed "${textArg}" into ${dispatch.role ?? "unknown"} "${dispatch.name ?? ""}" (backend:${dispatch.backendNodeId}), focus click at x=${dispatch.x} y=${dispatch.y}` : fact`typed "${textArg}" into the focused element`,
     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(
     {
       tag: "typed",
@@ -16141,7 +16158,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> \u2014 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> \u2014 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`;
   }
@@ -16186,19 +16203,20 @@ async function cmdPageScroll(parsed, _args) {
       const resolved = await resolveLiveTarget(live, target);
       if (!resolved.ok) return { failure: resolved };
       const dispatch2 = await scrollResolved(live, resolved, to, { mark: `scroll:${target},to=${to}` });
-      const screenshot2 = await deps7.autoScreenshot(client, "scroll", target, parsed.noScreenshot);
-      return { dispatch: dispatch2, screenshot: screenshot2 };
+      const screenshotResult = await capturePageInputScreenshot(client, "scroll", target, parsed.noScreenshot);
+      return { dispatch: dispatch2, ...screenshotResult };
     }
   );
   if ("failure" in outcome) {
     return emitResolutionError(parsed, "page scroll", outcome.failure);
   }
-  const { dispatch, screenshot } = outcome;
+  const { dispatch, screenshot, screenshotWarning } = outcome;
   const rows = [
     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(
     {
       tag: "scrolled",
@@ -16229,7 +16247,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=\u2026 role=\u2026 name=\u2026> \u2014 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=\u2026 role=\u2026 name=\u2026> \u2014 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`;
   }
@@ -230926,17 +230944,23 @@ function normalizeComputed(raw) {
 function resolvedIdentity3(backendNodeId2) {
   return backendNodeId2 === void 0 ? { backendNodeId: null, identityUnresolved: true } : { backendNodeId: backendNodeId2 };
 }
-async function mapWithConcurrency(values, limit, fn) {
-  const result = new Array(values.length);
+async function mapWithConcurrency(values, limit, budgetMs, fn) {
+  const result = Array(values.length).fill(void 0);
+  const deadline = Date.now() + budgetMs;
   let next = 0;
+  let truncated = false;
   const worker = async () => {
     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 };
 }
 async function collectStylesInner(ctx, styleSheetUrls, styleSheetHeaders) {
   const { client } = ctx;
@@ -230986,7 +231010,7 @@ async function collectStylesInner(ctx, styleSheetUrls, styleSheetHeaders) {
     resolved = facts.map(() => void 0);
   }
   const sourceCache = /* @__PURE__ */ new Map();
-  const elements = await mapWithConcurrency(facts, PROVENANCE_CONCURRENCY, async (fact4, index) => {
+  const provenance = await mapWithConcurrency(facts, PROVENANCE_CONCURRENCY, PROVENANCE_BUDGET_MS, async (fact4, index) => {
     const ref = resolved[index];
     const computed2 = normalizeComputed(fact4.computed);
     let winningDeclarations;
@@ -231021,6 +231045,7 @@ async function collectStylesInner(ctx, styleSheetUrls, styleSheetHeaders) {
       provenanceUnavailable
     };
   });
+  const elements = provenance.values.filter((element) => element !== void 0);
   ctx.write.json("styles.json", {
     elements,
     coverage: {
@@ -231029,7 +231054,9 @@ async function collectStylesInner(ctx, styleSheetUrls, styleSheetHeaders) {
       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" } : {}
     },
     styleSheetHeaders,
     identity: identity3,
@@ -231037,13 +231064,14 @@ async function collectStylesInner(ctx, styleSheetUrls, styleSheetHeaders) {
     ...unavailableReason ? { unavailableReason } : {}
   });
 }
-var STYLES_MAX_ELEMENTS, PROVENANCE_CONCURRENCY, COMPUTED_PROPERTIES, PROVENANCE_PROPERTIES, EXCLUDED_TAGS, STYLES_SCRIPT, collectStyles;
+var STYLES_MAX_ELEMENTS, PROVENANCE_CONCURRENCY, PROVENANCE_BUDGET_MS, COMPUTED_PROPERTIES, PROVENANCE_PROPERTIES, EXCLUDED_TAGS, STYLES_SCRIPT, collectStyles;
 var init_styles = __esm({
   "src/cdp/measure/collectors/styles.ts"() {
     init_redaction();
     init_style_provenance();
     STYLES_MAX_ELEMENTS = 150;
     PROVENANCE_CONCURRENCY = 8;
+    PROVENANCE_BUDGET_MS = 5e3;
     COMPUTED_PROPERTIES = [
       "display",
       "position",
@@ -235936,22 +235964,24 @@ function boundedClient(client, phase, partialPath, onTimeout) {
     const timeoutMs = Math.min(timeout, SNAPSHOT_REQUEST_TIMEOUT_MS);
     let timer;
     let timedOut = false;
-    const markTimedOut = () => {
+    const markTimedOut = (error) => {
       if (timedOut) return;
       timedOut = true;
-      onTimeout?.();
+      onTimeout?.(error);
     };
     const deadline = new Promise((_, reject) => {
       timer = setTimeout(() => {
-        markTimedOut();
-        reject(new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath));
+        const error = new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        markTimedOut(error);
+        reject(error);
       }, timeoutMs);
     });
     const request = Promise.resolve().then(() => client.send(method, params, timeoutMs, sessionId)).catch((error) => {
       if (error instanceof SnapshotCaptureTimeout) throw error;
       if (error instanceof Error && error.message.startsWith("CDP request timeout")) {
-        markTimedOut();
-        throw new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        const timeoutError = new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        markTimedOut(timeoutError);
+        throw timeoutError;
       }
       throw error;
     });
@@ -236055,21 +236085,25 @@ async function captureSnapshotSubstrate(options) {
         if (skipCollectors.has(collector.name)) return { name: collector.name, status: "skipped" };
         const startedAt = Date.now();
         let requestTimeouts = 0;
+        let timeoutError;
         const collectorWriter = makeCollectorWriter(ctx.write);
         try {
           await collector.fn({
             ...ctx,
-            client: boundedClient(client, `collector:${collector.name}`, dir, () => {
+            client: boundedClient(client, `collector:${collector.name}`, dir, (error) => {
               requestTimeouts += 1;
+              timeoutError ??= error;
             }),
             write: collectorWriter.writer
           });
+          if (collector.name === "styles" && timeoutError) throw timeoutError;
           const ms = Date.now() - startedAt;
           collectorWriter.commit();
           return requestTimeouts > 0 ? { name: collector.name, status: "degraded", ms, requestTimeouts } : { name: collector.name, status: "ok", ms };
-        } catch {
+        } catch (error) {
           const ms = Date.now() - startedAt;
           collectorWriter.discard();
+          if (collector.name === "styles" && error instanceof SnapshotCaptureTimeout) throw error;
           return { name: collector.name, status: "error", ms, ...requestTimeouts > 0 ? { requestTimeouts } : {} };
         }
       };
@@ -242178,7 +242212,7 @@ CDP_PORT / CDP_TARGET pin the browser + tab for orchestrators \u2014 precedence:
 explicit flag > active session > env.`;
 }
 function printVersion() {
-  const declared = "1.3.20";
+  const declared = "1.3.21";
   if (declared) {
     console.log(declared);
     return;

package/package.json

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

@@ -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/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/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,

package/src/cdp/measure/snapshot.ts

@@ -199,28 +199,30 @@ export class SnapshotCaptureTimeout extends Error {
 }
 
 /** Bounds one snapshot CDP request and labels the phase that owns it. */
-function boundedClient(client: CDPClient, phase: string, partialPath: string, onTimeout?: () => void): CDPClient {
+function boundedClient(client: CDPClient, phase: string, partialPath: string, onTimeout?: (error: SnapshotCaptureTimeout) => void): CDPClient {
   const bounded = Object.create(client) as CDPClient;
   bounded.send = (method: string, params: Record<string, unknown> = {}, timeout = 60_000, sessionId?: string): Promise<unknown> => {
     const timeoutMs = Math.min(timeout, SNAPSHOT_REQUEST_TIMEOUT_MS);
     let timer: NodeJS.Timeout | undefined;
     let timedOut = false;
-    const markTimedOut = (): void => {
+    const markTimedOut = (error: SnapshotCaptureTimeout): void => {
       if (timedOut) return;
       timedOut = true;
-      onTimeout?.();
+      onTimeout?.(error);
     };
     const deadline = new Promise<never>((_, reject) => {
       timer = setTimeout(() => {
-        markTimedOut();
-        reject(new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath));
+        const error = new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        markTimedOut(error);
+        reject(error);
       }, timeoutMs);
     });
     const request = Promise.resolve().then(() => client.send(method, params, timeoutMs, sessionId)).catch((error: unknown) => {
       if (error instanceof SnapshotCaptureTimeout) throw error;
       if (error instanceof Error && error.message.startsWith('CDP request timeout')) {
-        markTimedOut();
-        throw new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        const timeoutError = new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        markTimedOut(timeoutError);
+        throw timeoutError;
       }
       throw error;
     });
@@ -387,25 +389,34 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
 
         const startedAt = Date.now();
         let requestTimeouts = 0;
+        let timeoutError: SnapshotCaptureTimeout | undefined;
         const collectorWriter = makeCollectorWriter(ctx.write);
         try {
-          // Await the collector itself, not a wall-clock race around it. Each CDP
-          // request is still bounded at five seconds; awaiting the collector keeps
-          // any cleanup and pending browser work quiescent before the next shared-
-          // connection collector starts.
+          // Await the collector itself, not a wall-clock race around it. The
+          // collector owns its cleanup, and timeout handling below decides whether
+          // this capture can safely move on to another shared-connection collector.
           await collector.fn({
             ...ctx,
-            client: boundedClient(client, `collector:${collector.name}`, dir, () => { requestTimeouts += 1; }),
+            client: boundedClient(client, `collector:${collector.name}`, dir, (error) => {
+              requestTimeouts += 1;
+              timeoutError ??= error;
+            }),
             write: collectorWriter.writer,
           });
+          // A styles timeout may be caught per-record by the provenance collector,
+          // but its browser operation can still belong to this shared connection.
+          // End this capture instead of letting another collector issue commands
+          // under that outstanding operation.
+          if (collector.name === 'styles' && timeoutError) throw timeoutError;
           const ms = Date.now() - startedAt;
           collectorWriter.commit();
           return requestTimeouts > 0
             ? { name: collector.name, status: 'degraded', ms, requestTimeouts }
             : { name: collector.name, status: 'ok', ms };
-        } catch {
+        } catch (error) {
           const ms = Date.now() - startedAt;
           collectorWriter.discard();
+          if (collector.name === 'styles' && error instanceof SnapshotCaptureTimeout) throw error;
           return { name: collector.name, status: 'error', ms, ...(requestTimeouts > 0 ? { requestTimeouts } : {}) };
         }
       };