@crouton-kit/capture 1.3.18 → 1.3.20

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
@@ -137,11 +250,14 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
   const pixels = options.pixels ?? false;
   const state = options.state ?? [];
   const viewport = options.viewport ?? null;
+  const colorScheme = options.colorScheme;
   // 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 +289,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 +301,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 +320,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 +328,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 +336,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 +379,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 +435,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 +463,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.
@@ -339,6 +484,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       captureUnsettled,
       pixels,
       states: state.map((spec) => sanitizeString(spec)),
+      ...(colorScheme ? { colorScheme } : {}),
       unstableRegionCount: unstableRegions.length,
       ...(freezeAnimations ? { animationsRestored: animationsRestored ?? false } : {}),
       // #8: the browser-wide `Animation.setPlaybackRate({playbackRate:0})`
@@ -362,6 +508,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 +524,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

@@ -53,6 +53,8 @@ export interface CaptureSnapshotOptions {
   /** `--state <state[:selector]>` (repeatable); default `[]`. */
   readonly state?: readonly string[];
   readonly viewport?: string | null;
+  /** Transient `prefers-color-scheme` media override used while capturing. */
+  readonly colorScheme?: 'dark' | 'light';
   /**
    * Poll interval for the settledness loop; default {@link DEFAULT_POLL_INTERVAL_MS}
    * (100ms). Not part of the CLI surface — a test-only override so the
@@ -73,6 +75,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. */
@@ -83,6 +111,8 @@ export interface SnapshotMeta extends SnapMeta {
   readonly captureUnsettled: boolean;
   readonly pixels: boolean;
   readonly states: readonly string[];
+  /** Present only when this snapshot applied a transient color-scheme override. */
+  readonly colorScheme?: 'dark' | 'light';
   readonly unstableRegionCount: number;
   /** Present only when `freezeAnimations` is true — whether every animation `freezeAnimationsBeforeCapture` paused was confirmed resumed to its pre-freeze `playState` (I-6). `false` means restoration could not be guaranteed (origin capture failed, or the restore call itself threw) — never omitted to imply a clean restore. */
   readonly animationsRestored?: boolean;
@@ -94,6 +124,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 +142,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 +193,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 };

package/src/cdp/screenshot.ts

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