@crouton-kit/capture 1.3.18 → 1.3.19

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

@@ -41,9 +41,8 @@
  * turns into a `backendNodeId`. A page can predefine a setter for any
  * global name it can guess; it can observe nothing here, because nothing
  * is ever set on it. No DOM mutation and no page-observable global either,
- * so nothing in the emitted `screenshot.png`/`dom.html`/any other baseline
- * collector running concurrently in the same `Promise.all` can ever
- * observe this collector having run.
+ * so nothing in the emitted `screenshot.png`/`dom.html` can observe this
+ * collector having run.
  */
 
 import type { CDPClient } from '../../client.js';
@@ -628,9 +627,8 @@ async function resolveIndexedObjectIds(
 export const collectForms: Collector = async (ctx) => {
   // The walk's return value is a plain in-memory `{ facts, elements }`
   // object — never a `window` global, never a live-DOM attribute — so
-  // nothing another baseline collector or the `screenshot.png`/`dom.html`
-  // capture running concurrently in the same `Promise.all` (see
-  // `snapshot.ts`) could ever observe. `Runtime.evaluate({returnByValue:
+  // nothing another baseline artifact capture could ever observe.
+  // `Runtime.evaluate({returnByValue:
   // false})` hands that object back as a CDP `RemoteObject` (an `objectId`
   // with zero page visibility into it); every held `objectId` (the
   // container, `facts`, `elements`) is released via `Runtime.releaseObject`

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

@@ -4,8 +4,7 @@
  * state, and (for `object-fit`-bearing elements) computed crop/letterbox
  * facts. One `Runtime.evaluate` gathers raw per-element facts in-page;
  * `backendNodeId` correlation reuses `resolveNodeIds` from `./styles.js`
- * (this file issues its own `DOM.getDocument` call — collectors run
- * concurrently, so no CDP call is shared across files).
+ * while issuing its own `DOM.getDocument` call.
  *
  * This is a `phase: 'baseline'` collector, so it must not create or pin
  * any page-observable state: `canvas.getContext(...)` is deliberately NOT

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

@@ -5,12 +5,7 @@
  * Written ONLY when at least one `--state` was requested (`ctx.state.length
  * > 0`); otherwise this is a no-op (no file written). Owned by U12.
  *
- * Independent of the other 13 collectors (they all fan out via
- * `Promise.all` in `snapshot.ts` — there is no cross-collector read
- * ordering, and `geometry.json`/`styles.json`/`hittest.json` may not exist
- * yet when this runs), so this collector drives its own minimal
- * geometry/style/hittest re-capture per forced element rather than reading
- * those files. Scope: top-frame light DOM only — elements inside an
+ * This collector drives its own minimal geometry/style/hittest re-capture per forced element rather than reading those files. Scope: top-frame light DOM only — elements inside an
  * iframe or a shadow root are out of reach of `DOM.querySelectorAll`'s
  * plain (non-piercing) subtree walk and are not visited here; frame/shadow
  * stitching is `geometry.json`'s concern, not this collector's.

package/src/cdp/measure/collectors/style-provenance.ts

@@ -29,22 +29,10 @@
  * re-invoking `CSS.enable` while the domain is ALREADY enabled is a
  * no-op that redelivers nothing — only a `CSS.disable` + `CSS.enable`
  * pair forces Chrome to resend every currently-known stylesheet's
- * header). Both `styles.ts` and `layers.ts` run in the same `baseline`
- * `Promise.all` (see `snapshot.ts`), and `enableDomainsForSnap` already
- * enabled CSS once before either collector starts — so a caller-owned
- * listener registered only after that point would otherwise never see
- * the headers for stylesheets already parsed at that time. Each caller
- * runs `captureStyleSheetHeaders` independently, as the very first thing
- * it does (before any other CSS-domain call), and awaits it before
- * issuing any of its own `CSS.*` calls. Because listener registration is
- * synchronous (before any `await`), and JS never yields to socket I/O
- * mid-way through `Promise.all`'s synchronous dispatch of every baseline
- * collector, both this file's and the other collector's listeners are
- * always attached before either's disable/enable pair reaches Chrome —
- * so neither can miss the other's redelivery burst, and once both
- * callers' own `captureStyleSheetHeaders` calls resolve, the CSS domain
- * is stably enabled for the rest of the snapshot (neither file disables
- * it again).
+ * header). `enableDomainsForSnap` already enabled CSS before either
+ * collector starts, so each collector captures its own headers as its
+ * first CSS-domain action and awaits that capture before its provenance
+ * reads. This keeps either artifact self-contained.
  */
 
 import { resolveAuthoredSourceLocation, type ResolvedSourceLocation } from '../../source-map.js';

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

@@ -14,9 +14,8 @@
  * file's `CSS.getMatchedStylesForNode` calls (which need a CDP `nodeId`,
  * not just a `backendNodeId`) and reused by `media.ts` for its own
  * per-element `backendNodeId` correlation. Both `styles.ts` and `media.ts`
- * independently issue their own `Runtime.evaluate`/`DOM.getDocument`
- * calls — they run concurrently in `snapshot.ts`'s `Promise.all`, so there
- * is no cross-collector call sharing beyond this shared, stateless logic.
+ * independently issue their own `Runtime.evaluate`/`DOM.getDocument` calls,
+ * so there is no cross-collector call sharing beyond this shared, stateless logic.
  */
 
 import type { ResolvedSourceLocation } from '../../source-map.js';
@@ -35,6 +34,7 @@ export { computeSpecificity, resolveNodeIds };
 export type { Specificity, CSSRange, WinningDeclaration } from './style-provenance.js';
 
 const STYLES_MAX_ELEMENTS = 150;
+const PROVENANCE_CONCURRENCY = 8;
 
 /** Full computed-style snapshot tracked per element — broad, cheap (no CDP round trip; read via `getComputedStyle` in one `Runtime.evaluate`). */
 const COMPUTED_PROPERTIES = [
@@ -205,6 +205,20 @@ 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);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < values.length) {
+      const index = next++;
+      result[index] = await fn(values[index]!, index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, values.length) }, worker));
+  return result;
+}
+
 // ============================================================================
 // Collector
 // ============================================================================
@@ -213,9 +227,8 @@ export const collectStyles: Collector = async (ctx) => {
   const { client } = ctx;
 
   // Registers the CSS.styleSheetAdded listener and forces header redelivery
-  // BEFORE anything else touches the CSS domain — see style-provenance.ts's
-  // module doc for why this must run first and why it's safe alongside the
-  // concurrently-running `layers` collector's own copy of the same step.
+  // BEFORE this collector uses the CSS domain — see style-provenance.ts's
+  // module doc for why header capture must begin before provenance reads.
   const {
     urls: styleSheetUrls,
     stop: stopTrackingStyleSheets,
@@ -292,8 +305,7 @@ async function collectStylesInner(
 
   const sourceCache = new Map<string, Promise<ResolvedSourceLocation>>();
 
-  const elements: StylesElementRecord[] = await Promise.all(
-    facts.map(async (fact, index) => {
+  const elements = await mapWithConcurrency(facts, PROVENANCE_CONCURRENCY, async (fact, index): Promise<StylesElementRecord> => {
       const ref = resolved[index];
       const computed = normalizeComputed(fact.computed);
 
@@ -334,8 +346,7 @@ async function collectStylesInner(
         winningDeclarations,
         provenanceUnavailable,
       };
-    }),
-  );
+    });
 
   ctx.write.json('styles.json', {
     elements,

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

@@ -27,8 +27,7 @@
  * identifier `CSS.getPlatformFontsForNode` accepts — and `backendNodeId`.
  * No `setAttribute`/`removeAttribute` pair and no page-observable global
  * either, so nothing in the emitted `screenshot.png`/`dom.html`/any other
- * baseline collector running concurrently in the same `Promise.all` (see
- * `snapshot.ts`) can ever observe this collector having run.
+ * baseline artifact capture can ever observe this collector having run.
  */
 
 import type { CDPClient } from '../../client.js';
@@ -421,9 +420,8 @@ async function resolveIndexedObjectIds(
 export const collectText: Collector = async (ctx) => {
   // The walk's return value is a plain in-memory `{ facts, elements }`
   // object — never a `window` global, never a live-DOM attribute — so
-  // nothing another baseline collector or the `screenshot.png`/`dom.html`
-  // capture running concurrently in the same `Promise.all` (see
-  // `snapshot.ts`) could ever observe. `Runtime.evaluate({returnByValue:
+  // nothing another baseline artifact capture could ever observe.
+  // `Runtime.evaluate({returnByValue:
   // false})` hands that object back as a CDP `RemoteObject` (an `objectId`
   // with zero page visibility into it); every held `objectId` (the
   // container, `facts`, `elements`) is released via `Runtime.releaseObject`

package/src/cdp/measure/snapshot.ts

@@ -1,8 +1,8 @@
 /**
  * The `measure snap` orchestrator — drives the settledness gate, then (when
- * captured) runs the collectors in two phases: `baseline` collectors in
- * parallel, then `screenshot.png`/`dom.html` at the baseline boundary,
- * then `mutating` collectors serialized (so their DOM/focus/scroll/
+ * captured) runs the collectors in two phases: serialized `baseline`
+ * collectors, then `screenshot.png`/`dom.html` at the baseline boundary,
+ * then serialized `mutating` collectors (so their DOM/focus/scroll/
  * background changes can't contaminate the baseline artifacts). `meta.json`
  * is ALWAYS written last. This is the one function
  * `src/cdp/commands/measure/snap.ts` (U15) calls; nothing else drives a
@@ -11,7 +11,8 @@
 
 import * as path from 'path';
 
-import { ensurePrivateDir, writeJsonPrivate, writeBinaryPrivate, writePrivateFile } from '../../session/artifacts.js';
+import { ensurePrivateDir, writeJsonPrivate, writeBinaryPrivate, writePrivateFile, unlinkPrivateFile } from '../../session/artifacts.js';
+import type { CDPClient } from '../client.js';
 import { enableDomainsForSnap } from '../domains.js';
 import {
   DEFAULT_SETTLE_TIMEOUT_MS,
@@ -37,6 +38,7 @@ import type {
   SnapshotWriter,
   UnstableRegion,
   CollectorDescriptor,
+  CollectorOutcome,
 } from './types.js';
 
 import { collectGeometry } from './collectors/geometry.js';
@@ -55,9 +57,9 @@ import { collectStates } from './collectors/states.js';
 import { collectMedia } from './collectors/media.js';
 
 /**
- * The collector set, split by phase. `baseline` collectors run in parallel
- * and are all finished before `screenshot.png`/`dom.html` are captured;
- * `mutating` collectors run afterward, serialized, so their
+ * The collector set, split by phase. Every collector shares one browser CDP
+ * connection, so both phases run in descriptor order. Baseline collectors
+ * finish before `screenshot.png`/`dom.html`; `mutating` collectors run afterward, so their
  * DOM/focus/scroll/background mutations cannot contaminate the baseline
  * artifacts. Geometry/hittest/text/forms are safely `baseline`: none of
  * them ever mutates the DOM — each resolves its elements' `backendNodeId`
@@ -68,13 +70,13 @@ import { collectMedia } from './collectors/media.js';
  * `screenshot.png`/`dom.html` capture could observe ever changes.
  */
 const COLLECTORS: readonly CollectorDescriptor[] = [
+  { name: 'geometry', phase: 'baseline', fn: collectGeometry },
   { name: 'ax', phase: 'baseline', fn: collectAx },
   { name: 'styles', phase: 'baseline', fn: collectStyles },
   { name: 'queries', phase: 'baseline', fn: collectQueries },
   { name: 'animation', phase: 'baseline', fn: collectAnimation },
   { name: 'layers', phase: 'baseline', fn: collectLayers },
   { name: 'media', phase: 'baseline', fn: collectMedia },
-  { name: 'geometry', phase: 'baseline', fn: collectGeometry },
   { name: 'hittest', phase: 'baseline', fn: collectHittest },
   { name: 'text', phase: 'baseline', fn: collectText },
   { name: 'forms', phase: 'baseline', fn: collectForms },
@@ -84,6 +86,8 @@ const COLLECTORS: readonly CollectorDescriptor[] = [
   { name: 'pixels', phase: 'mutating', fn: collectPixels },
 ];
 
+export const COLLECTOR_NAMES = COLLECTORS.map((collector) => collector.name);
+
 /**
  * Resolves `filename` against the snap `dir` and rejects (throws) anything
  * that would escape it — an absolute path, or a `path.relative(dir, target)`
@@ -101,7 +105,12 @@ function resolveScopedArtifactPath(dir: string, filename: string): string {
   return target;
 }
 
-function makeWriter(dir: string, artifacts: string[]): SnapshotWriter {
+/** The snap-directory writer, plus the un-write a failed collector commit needs to leave nothing behind. */
+interface RollbackWriter extends SnapshotWriter {
+  remove(filename: string): void;
+}
+
+function makeWriter(dir: string, artifacts: string[]): RollbackWriter {
   return {
     json(filename: string, value: unknown): void {
       writeJsonPrivate(resolveScopedArtifactPath(dir, filename), value);
@@ -111,6 +120,59 @@ function makeWriter(dir: string, artifacts: string[]): SnapshotWriter {
       writeBinaryPrivate(resolveScopedArtifactPath(dir, filename), data);
       artifacts.push(filename);
     },
+    remove(filename: string): void {
+      const index = artifacts.lastIndexOf(filename);
+      if (index !== -1) artifacts.splice(index, 1);
+      try {
+        unlinkPrivateFile(resolveScopedArtifactPath(dir, filename));
+      } catch {
+        // The file is already gone, or the snap dir itself is unwritable; the
+        // artifact list no longer advertises it either way.
+      }
+    },
+  };
+}
+
+/**
+ * A collector publishes its artifacts only after it returns cleanly, and only
+ * as a set: a write that throws part-way through `commit` un-writes the ones
+ * that already landed and rethrows, so the collector is recorded as `error`
+ * with nothing of its own left in the snapshot. A partial artifact never
+ * reaches a completed snapshot by either route.
+ */
+function makeCollectorWriter(writer: RollbackWriter): { writer: SnapshotWriter; commit: () => void; discard: () => void } {
+  const staged: Array<{ filename: string; value: unknown } | { filename: string; data: Buffer }> = [];
+  let open = true;
+  return {
+    writer: {
+      json(filename: string, value: unknown): void {
+        if (open) staged.push({ filename, value });
+      },
+      binary(filename: string, data: Buffer): void {
+        if (open) staged.push({ filename, data });
+      },
+    },
+    commit(): void {
+      if (!open) return;
+      open = false;
+      const written: string[] = [];
+      try {
+        for (const artifact of staged) {
+          if ('data' in artifact) writer.binary(artifact.filename, artifact.data);
+          else writer.json(artifact.filename, artifact.value);
+          written.push(artifact.filename);
+        }
+      } catch (error) {
+        for (const filename of written.reverse()) writer.remove(filename);
+        throw error;
+      } finally {
+        staged.length = 0;
+      }
+    },
+    discard(): void {
+      open = false;
+      staged.length = 0;
+    },
   };
 }
 
@@ -118,6 +180,57 @@ function makeWriter(dir: string, artifacts: string[]): SnapshotWriter {
 // Orchestrator
 // ============================================================================
 
+/** One CDP operation is bounded so a page-side script or browser command that never returns cannot strand the CLI behind CDPClient's 60-second default. */
+export const SNAPSHOT_REQUEST_TIMEOUT_MS = 5_000;
+
+/** A snapshot operation timed out after writing zero or more partial artifacts. */
+export class SnapshotCaptureTimeout extends Error {
+  readonly code = 'snapshot_capture_timeout';
+
+  constructor(
+    readonly phase: string,
+    readonly method: string,
+    readonly timeoutMs: number,
+    readonly partialPath: string,
+  ) {
+    super(`snapshot capture timed out in ${phase} while waiting for ${method} after ${timeoutMs}ms; partial artifacts: ${partialPath}`);
+    this.name = 'SnapshotCaptureTimeout';
+  }
+}
+
+/** Bounds one snapshot CDP request and labels the phase that owns it. */
+function boundedClient(client: CDPClient, phase: string, partialPath: string, onTimeout?: () => 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 => {
+      if (timedOut) return;
+      timedOut = true;
+      onTimeout?.();
+    };
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        markTimedOut();
+        reject(new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath));
+      }, 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);
+      }
+      throw error;
+    });
+    return Promise.race([request, deadline]).finally(() => {
+      if (timer) clearTimeout(timer);
+    });
+  };
+  return bounded;
+}
+
 /**
  * Captures one snapshot substrate directory: enables the CDP domains,
  * runs the settledness gate, and — when the page settled or the caller
@@ -140,8 +253,10 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
   // Apply the shared artifact-string cap once at the source. URL contents
   // otherwise survive unchanged in meta.json, the result, and collector context.
   const url = options.url ? sanitizeString(options.url) : null;
+  const artifacts: string[] = [];
+  const phaseClient = (phase: string): CDPClient => boundedClient(client, phase, dir);
 
-  await enableDomainsForSnap(client);
+  await enableDomainsForSnap(phaseClient('domains'));
 
   // I-6: capture each animation's pre-freeze origin BEFORE this, the first
   // mutation, and restore it exception-safely — `animationFreezeHandle`/
@@ -173,7 +288,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
   let freezeIncomplete: boolean | undefined;
   let unfrozenCount: number | undefined;
   if (freezeAnimations) {
-    animationFreezeHandle = await freezeAnimationsBeforeCapture(client);
+    animationFreezeHandle = await freezeAnimationsBeforeCapture(phaseClient('freeze-animations'));
     freezeOverrideApplied = animationFreezeHandle?.rateOverrideApplied;
     freezeIncomplete = animationFreezeHandle?.freezeIncomplete;
     unfrozenCount = animationFreezeHandle?.unfrozenCount;
@@ -185,12 +300,12 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
     if (!animationFreezeHandle) return;
     const handle = animationFreezeHandle;
     animationFreezeHandle = undefined;
-    const result = await restoreAnimationsAfterCapture(client, handle);
+    const result = await restoreAnimationsAfterCapture(phaseClient('restore-animations'), handle);
     animationsRestored = result.restored;
   };
 
   try {
-    const churnHandle = await injectChurnObservers(client);
+    const churnHandle = await injectChurnObservers(phaseClient('settle-observers'));
 
     // The churn observers (MutationObserver/ResizeObserver) MUST be torn down
     // even if sampling throws (a CDP failure mid-poll) — otherwise they leak
@@ -204,7 +319,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
     let settleResult: Awaited<ReturnType<typeof pollForSettle<string>>>;
     try {
       settleResult = await pollForSettle({
-        captureSample: buildDomSettleSampler(client, churnHandle),
+        captureSample: buildDomSettleSampler(phaseClient('settle'), churnHandle),
         isEqual: domSignaturesEqual,
         settleTimeoutMs,
         quietThresholdMs,
@@ -212,7 +327,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       });
     } catch (pollError) {
       try {
-        await collectChurnEvidence(client, churnHandle);
+        await collectChurnEvidence(phaseClient('settle-cleanup'), churnHandle);
       } catch {
         // Secondary teardown failure — the original poll error is what matters.
       }
@@ -220,22 +335,22 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
     }
 
     // Always call — cleanup, and potential evidence, regardless of settledness.
-    const churnEvidenceRaw = await collectChurnEvidence(client, churnHandle);
+    const churnEvidenceRaw = await collectChurnEvidence(phaseClient('settle-cleanup'), churnHandle);
 
     const settled = settleResult.settled;
     const captured = settled || captureUnsettled;
     const unstable = !settled;
 
-    const artifacts: string[] = [];
     let unstableRegions: readonly UnstableRegion[] = [];
     // I-5: set only inside the `captured` branch below (the only place
     // `dom.html` is ever attempted) — stays `undefined` on the evidence-only
     // branch, where `meta.json`'s spread omits the field entirely rather than
     // implying a read that never happened.
     let domHtmlFact: SnapshotMeta['domHtml'];
+    const collectorOutcomes: CollectorOutcome[] = [];
 
     if (unstable) {
-      const animationEvidence = await collectAnimationEvidence(client);
+      const animationEvidence = await collectAnimationEvidence(phaseClient('settle-evidence'));
       const grouped = groupChurnEvidence(churnEvidenceRaw, animationEvidence, settleResult.elapsedMs, settleTimeoutMs);
       unstableRegions = grouped.unstableRegions;
       writeJsonPrivate(path.join(dir, 'churn.json'), grouped.report);
@@ -263,19 +378,50 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       };
 
       const collectors = options.collectors ?? COLLECTORS;
+      const skipCollectors = new Set(options.skipCollectors ?? []);
       const baseline = collectors.filter((c) => c.phase === 'baseline');
       const mutating = collectors.filter((c) => c.phase === 'mutating');
+      const runCollector = async (collector: CollectorDescriptor): Promise<CollectorOutcome> => {
+        if (skipCollectors.has(collector.name)) return { name: collector.name, status: 'skipped' };
 
-      // Phase 1 — baseline collectors observe the page exactly as it settled;
-      // they run in parallel and must ALL finish before the baseline
-      // artifacts are captured.
-      await Promise.all(baseline.map((c) => c.fn(ctx)));
+        const startedAt = Date.now();
+        let requestTimeouts = 0;
+        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 collector.fn({
+            ...ctx,
+            client: boundedClient(client, `collector:${collector.name}`, dir, () => { requestTimeouts += 1; }),
+            write: collectorWriter.writer,
+          });
+          const ms = Date.now() - startedAt;
+          collectorWriter.commit();
+          return requestTimeouts > 0
+            ? { name: collector.name, status: 'degraded', ms, requestTimeouts }
+            : { name: collector.name, status: 'ok', ms };
+        } catch {
+          const ms = Date.now() - startedAt;
+          collectorWriter.discard();
+          return { name: collector.name, status: 'error', ms, ...(requestTimeouts > 0 ? { requestTimeouts } : {}) };
+        }
+      };
+
+      // Phase 1 — baseline collectors observe the page exactly as it settled.
+      // They are serialized to COMPLETION because CDP commands share one browser
+      // connection: the next collector starts only once the previous one has
+      // returned or thrown, so no abandoned collector can still be issuing CDP
+      // commands (or restoring page state) underneath its successor. Every
+      // completed result is published before the baseline boundary.
+      for (const collector of baseline) collectorOutcomes.push(await runCollector(collector));
 
       // Baseline boundary — capture screenshot.png + dom.html BEFORE any
       // mutating collector runs, so a mutating collector's DOM/focus/scroll/
       // background change (or a failed restoration) can never contaminate
       // these artifacts.
-      const screenshotResponse = (await client.send('Page.captureScreenshot', { format: 'png' })) as { data: string };
+      const screenshotResponse = (await phaseClient('baseline-screenshot').send('Page.captureScreenshot', { format: 'png' })) as { data: string };
       writeBinaryPrivate(path.join(dir, 'screenshot.png'), Buffer.from(screenshotResponse.data, 'base64'));
       artifacts.push('screenshot.png');
 
@@ -288,7 +434,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       let domHtmlValue: string | undefined;
       let domHtmlUnavailableReason: string | undefined;
       try {
-        const domResponse = (await client.send('Runtime.evaluate', {
+        const domResponse = (await phaseClient('baseline-dom').send('Runtime.evaluate', {
           expression: 'document.documentElement.outerHTML',
           returnByValue: true,
         })) as { result?: { value?: string } };
@@ -316,11 +462,9 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       await restoreAnimationsOnce();
 
       // Phase 2 — mutating collectors run AFTER the baseline artifacts are
-      // captured, and SERIALIZED (one at a time) so their mutations and
-      // restorations cannot contaminate each other.
-      for (const c of mutating) {
-        await c.fn(ctx);
-      }
+      // captured, one at a time, so their mutations and restorations cannot
+      // contaminate each other.
+      for (const collector of mutating) collectorOutcomes.push(await runCollector(collector));
     } else {
       // Evidence-only branch (unstable, not captured) — nothing depends on
       // animations staying frozen any longer, so restore now.
@@ -362,6 +506,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       // `freezeIncomplete`, matching the handle's own documented contract.
       ...(freezeIncomplete === true ? { freezeIncomplete: true as const, unfrozenCount: unfrozenCount ?? 0 } : {}),
       ...(domHtmlFact ? { domHtml: domHtmlFact } : {}),
+      ...(captured ? { collectors: collectorOutcomes } : {}),
     };
     writeJsonPrivate(path.join(dir, 'meta.json'), meta);
     artifacts.push('meta.json');
@@ -377,8 +522,29 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       settleTimeoutMs,
       unstableRegions,
       artifacts,
+      collectors: collectorOutcomes,
       meta,
     };
+  } catch (error) {
+    if (error instanceof SnapshotCaptureTimeout) {
+      try {
+        writeJsonPrivate(path.join(dir, 'capture-timeout.json'), {
+          schemaVersion: 1,
+          id: snapId,
+          status: 'timeout',
+          phase: error.phase,
+          method: error.method,
+          timeoutMs: error.timeoutMs,
+          partialPath: dir,
+          artifacts,
+          capturedAt: new Date().toISOString(),
+        });
+        artifacts.push('capture-timeout.json');
+      } catch {
+        // Preserve the timeout and its directory even if recovery metadata cannot be written.
+      }
+    }
+    throw error;
   } finally {
     // I-6 exception safety net: if anything above threw before either
     // natural restore point ran, still restore the page against the

package/src/cdp/measure/types.ts

@@ -73,6 +73,32 @@ export interface CaptureSnapshotOptions {
    * the real collector set `snapshot.ts` defines.
    */
   readonly collectors?: readonly CollectorDescriptor[];
+  /** `--skip-collector <name>` (repeatable); collectors to leave out of this capture entirely. Each one is recorded in {@link SnapshotMeta.collectors} as `skipped`, so an absent artifact is never mistaken for a failed read. */
+  readonly skipCollectors?: readonly string[];
+}
+
+/**
+ * What one collector did in this capture — the honest ledger written to
+ * `meta.json`'s `collectors` field, so an absent artifact always names its
+ * reason.
+ *
+ * - `ok`: ran to completion; its artifact is present and trustworthy.
+ * - `degraded`: ran to completion, but at least one of its CDP requests was
+ *   killed by the per-request bound. The artifact exists and its own
+ *   per-record failure markers are honest, but some of what it reports is a
+ *   timed-out read rather than a measurement — `requestTimeouts` counts them.
+ * - `error`: threw before completing (including a CDP request killed by the
+ *   per-request bound that the collector did not itself absorb). Its artifact is
+ *   absent because writes publish only after collector completion.
+ * - `skipped`: excluded by `--skip-collector`; never ran.
+ */
+export interface CollectorOutcome {
+  readonly name: string;
+  readonly status: 'ok' | 'degraded' | 'error' | 'skipped';
+  /** Wall-clock ms the collector ran. Absent for `skipped` — it never ran. */
+  readonly ms?: number;
+  /** Present only when at least one of this collector's CDP requests was killed by the per-request bound. */
+  readonly requestTimeouts?: number;
 }
 
 /** `meta.json`'s on-disk shape — a {@link SnapMeta} (the U03 contract) plus snapshot-specific detail. */
@@ -94,6 +120,8 @@ export interface SnapshotMeta extends SnapMeta {
   readonly unfrozenCount?: number;
   /** Present only when the snapshot reached the baseline boundary (`captured`) — whether `document.documentElement.outerHTML` was actually read (I-5). `false` means the CDP read threw or returned no value: `dom.html` is NOT written in that case (an absent file, never a benign empty one), and `unavailableReason` names why. */
   readonly domHtml?: { readonly available: boolean; readonly unavailableReason?: string };
+  /** Per-collector outcome ledger — present only on a capture that reached the collector phase (`captured`), never on an evidence-only unsettled capture where no collector ran. See {@link CollectorOutcome}. */
+  readonly collectors?: readonly CollectorOutcome[];
 }
 
 /** Return value of {@link captureSnapshotSubstrate}. */
@@ -110,6 +138,8 @@ export interface CaptureSnapshotResult {
   readonly unstableRegions: readonly UnstableRegion[];
   /** Filenames written under `dir`, relative to it. */
   readonly artifacts: readonly string[];
+  /** Per-collector outcome ledger; empty on an evidence-only capture where no collector ran. */
+  readonly collectors: readonly CollectorOutcome[];
   readonly meta: SnapshotMeta;
 }
 
@@ -159,8 +189,8 @@ export type Collector = (ctx: SnapshotContext) => Promise<void>;
  * Which snapshot phase a collector belongs to — the ordering guarantee the
  * orchestrator enforces:
  *  - `baseline`: pure/measuring collectors that must observe the page as it
- *    settled. They run in PARALLEL, and ALL finish before `screenshot.png`
- *    + `dom.html` are captured at the baseline boundary.
+ *    settled. They run in descriptor order, and all finish before
+ *    `screenshot.png` + `dom.html` are captured at the baseline boundary.
  *  - `mutating`: collectors that mutate DOM/focus/scroll/background
  *    (focus, scroll, states, pixels). They run AFTER the baseline artifacts
  *    are captured, and SERIALIZED (one at a time) so their mutations and

package/src/cdp/motion/jank.ts

@@ -426,7 +426,14 @@ function longTask(source: 'observer' | 'trace', timingDomain: LongTaskTimingDoma
 export function readMotionJank(ref: RecRef): { analysis: MotionJankAnalysis; meta: Record<string, unknown> } {
   const meta = readMeta<Record<string, unknown>>(ref);
   const state = typeof meta.state === 'string' ? meta.state : undefined;
-  if (state !== 'finalized' && state !== 'orphaned-finalized') {
+  // A one-shot recording that captured zero screencast frames is still a
+  // completed recording, not one awaiting `--stop` (which only applies to an
+  // active composed lifecycle recording) — its retained event/trace records
+  // remain readable, so long-task and layout-shift facts stay available;
+  // only frame-derived counts fall back to "incomplete" via cadenceMs===null.
+  // Mirrors the same exception already made in response.ts's loadResponseTimeline.
+  const readablePartial = state === 'partial' && meta.reason === 'no_frames';
+  if (state !== 'finalized' && state !== 'orphaned-finalized' && !readablePartial) {
     throw new Error(`recording ${JSON.stringify(ref.id)} is state ${JSON.stringify(state ?? 'unknown')}, not finalized; finalize it with: capture motion rec --stop`);
   }
   return { analysis: analyzeMotionJank({ rects: readRects(ref), events: readEvents(ref), markers: readMarkers<Markers>(ref), state }), meta };