@crouton-kit/capture 1.4.2 → 1.4.10

package/src/cdp/scope-lock.ts

@@ -5,12 +5,12 @@
  * reads). Each scope is an enable→work→restore sequence whose intermediate
  * state lives on the connection. A DIRECT connection needs no serialization —
  * its emulation/domain state is scoped to its own websocket session, which
- * closes with the command. The recorder, however, holds ONE persistent tab
- * connection whose state outlives any single command, so two concurrent
+ * closes with the command. The motion collector, however, holds ONE persistent
+ * tab connection whose state outlives any single command, so two concurrent
  * routed callers could otherwise clear/disable one another's live state
- * (the recorder bridge's `handleCdp` is strictly per-request — it provides
- * no serialization of its own). When the client is the recorder-held
- * adapter, the whole scope therefore runs under the owning session's private
+ * (its dispatch is strictly per-request and provides no serialization).
+ * When the client is the motion-held adapter, the whole scope therefore runs
+ * under the owning session's private
  * cross-process lock (`.<scope>-scope.lock`, the shared `acquirePrivateLock`
  * authority every session lock uses).
  */
@@ -18,14 +18,14 @@ import * as path from 'path';
 import { acquirePrivateLock } from '../session/artifacts.js';
 import { getActiveSession } from '../session-context.js';
 import { captureError } from '../errors.js';
-import { isRecorderHeldClient } from './recorder-client.js';
+import { isMotionHeldClient } from './host/held-client.js';
 
 export interface ScopeSerializationDeps {
-  isRecorderHeldClient: (client: unknown) => boolean;
+  isMotionHeldClient: (client: unknown) => boolean;
   getActiveSession: typeof getActiveSession;
 }
 
-let deps: ScopeSerializationDeps = { isRecorderHeldClient, getActiveSession };
+let deps: ScopeSerializationDeps = { isMotionHeldClient, getActiveSession };
 
 /** Swap the held-client/session seams for the CDP-stub tests. */
 export function __setScopeSerializationDepsForTest(overrides: Partial<ScopeSerializationDeps>): () => void {
@@ -50,7 +50,7 @@ export async function withScopeSerialization<T>(
   overrides?: ScopeSerializationDeps,
 ): Promise<T> {
   const d = overrides ?? deps;
-  if (!d.isRecorderHeldClient(client)) {
+  if (!d.isMotionHeldClient(client)) {
     return fn();
   }
   const session = d.getActiveSession();

package/src/cdp/screenshot.ts

@@ -1,7 +1,8 @@
+import * as fs from 'fs';
 import { PNG } from 'pngjs';
 import { CDPClient } from './client.js';
 import { nextStepPath } from '../session-context.js';
-import { writeBinaryPrivate } from '../session/artifacts.js';
+import { assertUnderCaptureRoot, writeBinaryPrivate } from '../session/artifacts.js';
 import { withScopeSerialization } from './scope-lock.js';
 
 /**
@@ -16,6 +17,12 @@ export interface CapturedRegion {
   readonly height: number;
 }
 
+/** The visual viewport's page-coordinate origin at capture time. */
+export interface ScrollOffset {
+  readonly x: number;
+  readonly y: number;
+}
+
 /** A CSS-pixel crop request. The capture is intersected with the live visual viewport before it reaches CDP. */
 export interface ScreenshotCrop {
   readonly x: number;
@@ -33,6 +40,10 @@ function validRegion(region: CapturedRegion): CapturedRegion | undefined {
   return region;
 }
 
+function validScrollOffset(offset: ScrollOffset): ScrollOffset | undefined {
+  return [offset.x, offset.y].every(Number.isFinite) ? offset : undefined;
+}
+
 /** Intersects page-coordinate CSS regions without rounding their geometry. */
 function intersectRegions(a: CapturedRegion, b: CapturedRegion): CapturedRegion | undefined {
   const x = Math.max(a.x, b.x);
@@ -120,7 +131,7 @@ export async function captureScreenshotWithCssViewport(
   client: CDPClient,
   viewport?: { width: number; height: number },
   options?: ScreenshotOptions,
-): Promise<{ png: Buffer; cssViewport?: CapturedRegion }> {
+): Promise<{ png: Buffer; cssViewport?: CapturedRegion; scrollOffset?: ScrollOffset }> {
   return withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
     viewportScopedCapture(client, viewport, options, true),
   );
@@ -138,8 +149,9 @@ async function viewportScopedCapture(
   viewport?: { width: number; height: number },
   options?: ScreenshotOptions,
   includeCssViewport = false,
-): Promise<{ png: Buffer; cssViewport?: CapturedRegion }> {
+): Promise<{ png: Buffer; cssViewport?: CapturedRegion; scrollOffset?: ScrollOffset }> {
   const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
+  const SCREENSHOT_REQUEST_TIMEOUT_MS = 30_000;
   let ownsDeviceMetricsOverride = false;
   let primaryFailed = false;
   let primaryError: unknown;
@@ -184,6 +196,7 @@ async function viewportScopedCapture(
     // actually sent. An unclipped capture clears it again and it is read from the
     // live visual viewport below instead.
     let capturedRegion: CapturedRegion | undefined;
+    let scrollOffset: ScrollOffset | undefined;
 
     try {
       const metrics = (await client.send('Page.getLayoutMetrics', {}, 5000)) as {
@@ -195,8 +208,11 @@ async function viewportScopedCapture(
       // are fractional with a SUCCESSFUL response carrying empty `data`.
       const vw = Math.round(metrics.cssVisualViewport?.clientWidth ?? 0);
       const vh = Math.round(metrics.cssVisualViewport?.clientHeight ?? 0);
-      const sx = Math.floor(metrics.cssVisualViewport?.pageX ?? 0);
-      const sy = Math.floor(metrics.cssVisualViewport?.pageY ?? 0);
+      const pageX = metrics.cssVisualViewport?.pageX ?? 0;
+      const pageY = metrics.cssVisualViewport?.pageY ?? 0;
+      const sx = Math.floor(pageX);
+      const sy = Math.floor(pageY);
+      scrollOffset = validScrollOffset({ x: pageX, y: pageY });
 
       const dprResult = (await client.send('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
@@ -233,7 +249,7 @@ async function viewportScopedCapture(
     const result = (await client.send(
       'Page.captureScreenshot',
       screenshotOpts,
-      15000,
+      SCREENSHOT_REQUEST_TIMEOUT_MS,
     )) as { data?: string };
     let png = Buffer.from(result.data ?? '', 'base64');
 
@@ -246,7 +262,7 @@ async function viewportScopedCapture(
       const retry = (await client.send('Page.captureScreenshot', {
         ...screenshotOpts,
         clip: { ...clip, scale: 1 },
-      }, 15000)) as { data?: string };
+      }, SCREENSHOT_REQUEST_TIMEOUT_MS)) as { data?: string };
       png = Buffer.from(retry.data ?? '', 'base64');
       if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
     }
@@ -257,13 +273,16 @@ async function viewportScopedCapture(
       const retry = (await client.send('Page.captureScreenshot', {
         format: 'png',
         captureBeyondViewport: false,
-      }, 15000)) as { data?: string };
+      }, SCREENSHOT_REQUEST_TIMEOUT_MS)) 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;
+      // 30 seconds, so the viewport facts sampled before them are no longer evidence.
+      if (png.length > 0) {
+        capturedRegion = undefined;
+        scrollOffset = undefined;
+      }
     }
 
     // The image was captured unclipped (no clip was ever sent, or the clipped
@@ -278,12 +297,10 @@ async function viewportScopedCapture(
         }, 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),
-          });
+          const x = Number(value.x);
+          const y = Number(value.y);
+          capturedRegion = validRegion({ x, y, width: Number(value.width), height: Number(value.height) });
+          scrollOffset = validScrollOffset({ x, y });
         }
       } catch {
         // The image remains usable; only its CSS-coordinate mapping is unavailable.
@@ -296,7 +313,11 @@ async function viewportScopedCapture(
       );
     }
 
-    return { png, ...(includeCssViewport && capturedRegion ? { cssViewport: capturedRegion } : {}) };
+    return {
+      png,
+      ...(includeCssViewport && capturedRegion ? { cssViewport: capturedRegion } : {}),
+      ...(includeCssViewport && scrollOffset ? { scrollOffset } : {}),
+    };
   } catch (error) {
     primaryFailed = true;
     primaryError = error;
@@ -319,22 +340,31 @@ async function viewportScopedCapture(
   }
 }
 
+export function writeScreenshot(outPath: string, png: Buffer): void {
+  try {
+    assertUnderCaptureRoot(outPath);
+  } catch {
+    fs.writeFileSync(outPath, png);
+    return;
+  }
+  writeBinaryPrivate(outPath, png);
+}
+
 export async function autoScreenshot(
   client: CDPClient,
   action: string,
   label: string,
   noScreenshot?: boolean,
+  out?: string,
 ): Promise<string | null> {
   if (noScreenshot) return null;
-  const shotPath = await nextStepPath(action, label);
+  const shotPath = out || await nextStepPath(action, label);
   if (!shotPath) return null;
 
   // Brief settle for UI to update
   await new Promise((r) => setTimeout(r, 300));
   const png = await captureScreenshot(client);
-  // Shot path always resolves under the session dir (CAPTURE_ROOT); the
-  // private writer creates the file 0600 and re-ensures shots/ is 0700.
-  writeBinaryPrivate(shotPath, png);
+  writeScreenshot(shotPath, png);
   console.error(`  [screenshot] ${shotPath}`);
   return shotPath;
 }

package/src/cdp/timing.ts

@@ -2,7 +2,7 @@
  * Shared timing helpers for `measure`/`motion`. See the design's "Recorder timing model":
  * the authoritative clock for every reported timestamp is `performance.now()`, relative to
  * the recorder-armed marker (`t=0`). Screencast frames carry a wall-clock `metadata.timestamp`
- * and Tracing events carry a monotonic `ts` in their own domains; the recorder bridge (U13/U14)
+ * and Tracing events carry a monotonic `ts` in their own domains; the motion collector (U13/U14)
  * converts both into the `performance.now()` domain by baseline-offset subtraction using the
  * baseline this module reads.
  */
@@ -22,7 +22,7 @@ export interface BracketedTiming<T> {
  * context. Used to attribute a discrete action (e.g. an `Input.dispatch*` call) to a window in
  * the recorder's authoritative `performance.now()` clock domain. The action's landmark label
  * (`mark`, when the caller supplied one) is recorded host-side only — appended straight to
- * `events.jsonl` alongside these two bracket numbers (see `../recorder-bridge.ts`'s `handleCdp`)
+ * `events.jsonl` alongside these two bracket numbers (see `host/collectors/motion.ts`'s `handleCdp`)
  * — never written into the page's own PerformanceTimeline via `performance.mark()`: that page-
  * visible side channel was removed (a predictable, page-observable channel the injected
  * PerformanceObserver would otherwise re-observe as its own event, in violation of the
@@ -59,10 +59,10 @@ export interface TraceClockBaseline {
 
 /**
  * Reads one synchronized (`performance.now()`, wall-clock) pair from the page in a single
- * round trip. The recorder bridge reads this once when it arms (`rec-start`) as the anchor half
- * of the three-way `markers.json` baseline; the other two members — the first screencast frame's
+ * round trip. The motion collector reads this once when it arms as the anchor half of the
+ * three-way `markers.json` baseline; the other two members — the first screencast frame's
  * `metadata.timestamp` (wall-clock seconds) and the first Tracing batch's earliest event `ts`
- * (trace-clock microseconds) — are captured separately by the recorder bridge itself as those
+ * (trace-clock microseconds) — are captured separately by the motion collector as those
  * events arrive (not by this function, since neither exists yet at arm time). Post-processing
  * converts frame-time and trace-time into the `performance.now()` domain by subtracting this
  * baseline's wall-clock offset.

package/src/cdp/trace-analysis.ts

@@ -0,0 +1,320 @@
+import * as TraceEngine from '@paulirish/trace_engine';
+
+export type RawChromeTrace = readonly object[] | { readonly traceEvents: readonly object[] };
+
+export interface MetricProvenance {
+  /** Trace-derived measurements are lab data, never field percentiles. */
+  readonly origin: 'lab';
+  readonly producer: 'Chrome performance trace analyzed by DevTools Trace Engine';
+  readonly scope: 'recording-window';
+  readonly limitations: readonly string[];
+}
+
+export interface ObservedMetric<Value, Attribution = never> {
+  readonly status: 'observed';
+  readonly value: Value;
+  readonly provenance: MetricProvenance;
+  readonly attribution?: Attribution;
+}
+
+export interface UnobservedMetric {
+  readonly status: 'not-observed';
+  readonly reason: 'not-present-in-recording';
+  readonly provenance: MetricProvenance;
+}
+
+export interface LargestContentfulPaint {
+  readonly durationMs: number;
+  readonly subpartsMs: Readonly<Partial<Record<'ttfb' | 'loadDelay' | 'loadDuration' | 'renderDelay', number>>>;
+}
+
+export interface LargestContentfulPaintAttribution {
+  /** The node description emitted by Chrome, such as `IMG id='hero'`; it is not a selector. */
+  readonly element?: string;
+  readonly nodeId?: number;
+  readonly resourceUrl?: string;
+}
+
+export interface InteractionToNextPaint {
+  readonly durationMs: number;
+  readonly interactionType: string;
+  readonly interactionId: number;
+  readonly inputDelayMs: number;
+  /** Time the trace engine attributed to main-thread handling for this interaction. */
+  readonly mainThreadHandlingMs: number;
+  readonly presentationDelayMs: number;
+}
+
+export interface InteractionAttribution {
+  readonly targetNodeId?: number;
+}
+
+export type LayoutShiftCulpritKind = 'web-font' | 'iframe' | 'non-composited-animation' | 'unsized-image' | 'engine-reported';
+
+export interface LayoutShiftCulprit {
+  readonly kind: LayoutShiftCulpritKind;
+  readonly url?: string;
+  readonly nodeId?: number;
+  /** Engine-provided culprit description. */
+  readonly description?: string;
+}
+
+export interface LayoutShiftCluster {
+  readonly value: number;
+  readonly shiftCount: number;
+  readonly culprits: readonly LayoutShiftCulprit[];
+}
+
+export interface CumulativeLayoutShift {
+  readonly value: number;
+  readonly clusters: readonly LayoutShiftCluster[];
+}
+
+export type TraceInsightField = string | number | boolean | null | readonly TraceInsightField[] | Readonly<Record<string, TraceInsightField>>;
+
+export interface TraceInsight {
+  /** The engine's insight key. */
+  readonly name: string;
+  /** Factual engine fields, made JSON-safe without adding capture judgments. */
+  readonly fields: Readonly<Record<string, TraceInsightField>>;
+}
+
+export interface TraceInsightSet {
+  /** DevTools' navigation or no-navigation insight-set identifier. */
+  readonly id: string;
+  readonly url: string;
+  /** Engine-computed records. The adapter deliberately does not turn insight states into judgments. */
+  readonly insights: readonly TraceInsight[];
+  readonly metrics: {
+    readonly lcp: ObservedMetric<LargestContentfulPaint, LargestContentfulPaintAttribution> | UnobservedMetric;
+    readonly inp: ObservedMetric<InteractionToNextPaint, InteractionAttribution> | UnobservedMetric;
+    readonly cls: ObservedMetric<CumulativeLayoutShift> | UnobservedMetric;
+  };
+}
+
+export interface TraceAnalysis {
+  readonly source: {
+    readonly format: 'chrome-performance-trace';
+    readonly engine: '@paulirish/trace_engine@0.0.65';
+  };
+  readonly insightSets: readonly TraceInsightSet[];
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as UnknownRecord : null;
+}
+
+function finite(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function string(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function traceEvents(trace: RawChromeTrace): readonly object[] {
+  if (!('traceEvents' in trace)) return trace;
+  if (!Array.isArray(trace.traceEvents)) throw new Error('Chrome trace must be an event array or an object with a traceEvents array.');
+  return trace.traceEvents;
+}
+
+function lcpProvenance(): MetricProvenance {
+  return {
+    origin: 'lab',
+    producer: 'Chrome performance trace analyzed by DevTools Trace Engine',
+    scope: 'recording-window',
+    limitations: ['Records the largest contentful paint observed during this trace, not a real-user field percentile.'],
+  };
+}
+
+function inpProvenance(): MetricProvenance {
+  return {
+    origin: 'lab',
+    producer: 'Chrome performance trace analyzed by DevTools Trace Engine',
+    scope: 'recording-window',
+    limitations: ['Only interactions that occurred during this trace can be measured.', 'No recorded interaction is not a zero-millisecond interaction.', 'This is not a real-user field percentile.'],
+  };
+}
+
+function clsProvenance(): MetricProvenance {
+  return {
+    origin: 'lab',
+    producer: 'Chrome performance trace analyzed by DevTools Trace Engine',
+    scope: 'recording-window',
+    limitations: ['Only layout shifts observed during this trace contribute to this value.', 'This is not a real-user field percentile.'],
+  };
+}
+
+function unobserved(provenance: MetricProvenance): UnobservedMetric {
+  return { status: 'not-observed', reason: 'not-present-in-recording', provenance };
+}
+
+function lcpFrom(model: UnknownRecord): TraceInsightSet['metrics']['lcp'] {
+  const insight = record(model.LCPBreakdown);
+  const durationMs = finite(insight?.lcpMs);
+  if (durationMs === undefined) return unobserved(lcpProvenance());
+
+  const event = record(insight?.lcpEvent);
+  const eventData = record(record(event?.args)?.data);
+  const requestData = record(record(record(insight?.lcpRequest)?.args)?.data);
+  const subparts = record(insight?.subparts);
+  const subpartsMs: Partial<Record<'ttfb' | 'loadDelay' | 'loadDuration' | 'renderDelay', number>> = {};
+  for (const name of ['ttfb', 'loadDelay', 'loadDuration', 'renderDelay'] as const) {
+    const rangeUs = finite(record(subparts?.[name])?.range);
+    if (rangeUs !== undefined) subpartsMs[name] = rangeUs / 1000;
+  }
+  const attribution: LargestContentfulPaintAttribution = {
+    ...(string(eventData?.nodeName) === undefined ? {} : { element: string(eventData?.nodeName) }),
+    ...(finite(eventData?.nodeId) === undefined ? {} : { nodeId: finite(eventData?.nodeId) }),
+    ...(string(requestData?.url) === undefined ? {} : { resourceUrl: string(requestData?.url) }),
+  };
+  return {
+    status: 'observed',
+    value: { durationMs, subpartsMs },
+    provenance: lcpProvenance(),
+    ...(Object.keys(attribution).length === 0 ? {} : { attribution }),
+  };
+}
+
+function inpFrom(model: UnknownRecord): TraceInsightSet['metrics']['inp'] {
+  const interaction = record(record(model.INPBreakdown)?.highPercentileInteractionEvent);
+  const durationUs = finite(interaction?.dur);
+  const interactionId = finite(interaction?.interactionId);
+  const interactionType = string(interaction?.type);
+  if (durationUs === undefined || interactionId === undefined || interactionType === undefined) return unobserved(inpProvenance());
+  const sourceData = record(record(record(interaction.rawSourceEvent)?.args)?.data);
+  const targetNodeId = finite(sourceData?.nodeId);
+  return {
+    status: 'observed',
+    value: {
+      durationMs: durationUs / 1000,
+      interactionType,
+      interactionId,
+      inputDelayMs: (finite(interaction.inputDelay) ?? 0) / 1000,
+      mainThreadHandlingMs: (finite(interaction.mainThreadHandling) ?? 0) / 1000,
+      presentationDelayMs: (finite(interaction.presentationDelay) ?? 0) / 1000,
+    },
+    provenance: inpProvenance(),
+    ...(targetNodeId === undefined ? {} : { attribution: { targetNodeId } }),
+  };
+}
+
+function culpritFrom(value: unknown): LayoutShiftCulprit {
+  const culprit = record(value);
+  const type = finite(culprit?.type);
+  const kind: LayoutShiftCulpritKind = type === 0 ? 'web-font'
+    : type === 1 ? 'iframe'
+      : type === 2 ? 'non-composited-animation'
+        : type === 3 ? 'unsized-image'
+          : 'engine-reported';
+  const url = string(culprit?.url);
+  const nodeId = finite(culprit?.backendNodeId);
+  const description = string(record(culprit?.description)?.formattedDefault);
+  return { kind, ...(url === undefined ? {} : { url }), ...(nodeId === undefined ? {} : { nodeId }), ...(description === undefined ? {} : { description }) };
+}
+
+function clsFrom(model: UnknownRecord): TraceInsightSet['metrics']['cls'] {
+  const insight = record(model.CLSCulprits);
+  const clusters = Array.isArray(insight?.clusters) ? insight.clusters : [];
+  if (clusters.length === 0) return unobserved(clsProvenance());
+  const culpritsByCluster = insight?.topCulpritsByCluster instanceof Map ? insight.topCulpritsByCluster : new Map();
+  const values: LayoutShiftCluster[] = clusters.map((cluster) => {
+    const item = record(cluster);
+    const rawCulprits = culpritsByCluster.get(cluster);
+    return {
+      value: finite(item?.clusterCumulativeScore) ?? 0,
+      shiftCount: Array.isArray(item?.events) ? item.events.length : 0,
+      culprits: Array.isArray(rawCulprits) ? rawCulprits.map(culpritFrom) : [],
+    };
+  });
+  return {
+    status: 'observed',
+    value: { value: Math.max(...values.map((cluster) => cluster.value)), clusters: values },
+    provenance: clsProvenance(),
+  };
+}
+
+const PRESENTATION_FIELDS = new Set([
+  'insightKey', 'strings', 'title', 'description', 'docs', 'category', 'state', 'fail', 'warnings', 'createOverlays', 'label', 'preconnectCandidates', 'checklist',
+]);
+
+function presentationField(name: string): boolean {
+  return PRESENTATION_FIELDS.has(name) || /saving|wasted|score/i.test(name);
+}
+
+function reportableField(value: unknown, ancestors = new Set<object>()): TraceInsightField | undefined {
+  const text = string(value);
+  if (text !== undefined) return text;
+  const number = finite(value);
+  if (number !== undefined) return number;
+  if (typeof value === 'boolean' || value === null) return value;
+  if (Array.isArray(value)) return value.flatMap((item) => {
+    const field = reportableField(item, ancestors);
+    return field === undefined ? [] : [field];
+  });
+  if (value instanceof Map) {
+    if (ancestors.has(value)) return undefined;
+    ancestors.add(value);
+    const entries = [...value].flatMap(([key, item]) => {
+      const reportableKey = reportableField(key, ancestors);
+      const reportableValue = reportableField(item, ancestors);
+      return reportableKey === undefined || reportableValue === undefined ? [] : [{ key: reportableKey, value: reportableValue }];
+    });
+    ancestors.delete(value);
+    return { entries };
+  }
+  if (value instanceof Set) {
+    if (ancestors.has(value)) return undefined;
+    ancestors.add(value);
+    const values = [...value].flatMap((item) => {
+      const field = reportableField(item, ancestors);
+      return field === undefined ? [] : [field];
+    });
+    ancestors.delete(value);
+    return { values };
+  }
+  const fields = record(value);
+  if (fields === null || ancestors.has(fields)) return undefined;
+  ancestors.add(fields);
+  const result: Record<string, TraceInsightField> = {};
+  for (const [key, item] of Object.entries(fields)) {
+    if (presentationField(key)) continue;
+    const field = reportableField(item, ancestors);
+    if (field !== undefined) result[key] = field;
+  }
+  ancestors.delete(fields);
+  return result;
+}
+
+function insightsFrom(model: UnknownRecord): readonly TraceInsight[] {
+  return Object.values(model).flatMap((value) => {
+    const fields = record(value);
+    const name = string(fields?.insightKey);
+    if (name === undefined) return [];
+    const details = reportableField(fields);
+    return details === undefined || Array.isArray(details) ? [] : [{ name, fields: details }];
+  });
+}
+
+/** Parses an in-memory Chrome performance trace without reading files, controlling Chrome, or assigning quality verdicts. */
+export async function analyzeChromeTrace(trace: RawChromeTrace): Promise<TraceAnalysis> {
+  const processor = TraceEngine.Processor.TraceProcessor.createWithAllHandlers();
+  await processor.parse(traceEvents(trace) as readonly TraceEngine.Types.Events.Event[], { isFreshRecording: true });
+  const insightSets = processor.insights;
+  if (!insightSets) throw new Error('DevTools Trace Engine produced no insight sets for this trace.');
+
+  return {
+    source: { format: 'chrome-performance-trace', engine: '@paulirish/trace_engine@0.0.65' },
+    insightSets: [...insightSets.values()].map((set) => {
+      const model = set.model as unknown as UnknownRecord;
+      return {
+        id: String(set.id),
+        url: set.url.toString(),
+        insights: insightsFrom(model),
+        metrics: { lcp: lcpFrom(model), inp: inpFrom(model), cls: clsFrom(model) },
+      };
+    }),
+  };
+}

package/src/cdp/types.ts

@@ -16,6 +16,8 @@ export interface ParsedArgs {
    * different browser endpoint. */
   portSource?: 'flag' | 'session' | 'env';
   out?: string;
+  /** Root directory for a session bundle or one-shot artifact bundle. */
+  artifactDir?: string;
   json?: boolean;
   duration?: number;
   settle?: number;
@@ -40,6 +42,8 @@ export interface ParsedArgs {
   viewport?: string;
   /** `page shot|measure snap --color-scheme dark|light` — transient media override. */
   colorScheme?: string;
+  /** `page scroll --behavior instant|smooth` — dispatch behavior. */
+  behavior?: 'instant' | 'smooth';
   fullPage?: boolean;
   help?: boolean;
   /** `--all` — boolean scope-widener (per-leaf semantics). */
@@ -53,6 +57,8 @@ export interface ParsedArgs {
   /** `session log --name <label>` */
   name?: string;
   filterUrl?: string;
+  /** `session har --body <url>` — exact captured response URL to export. */
+  body?: string;
   filterStatus?: string;
   filterMethod?: string;
   limit?: number;
@@ -86,6 +92,8 @@ export interface ParsedArgs {
   /** `shot --crop <x,y,w,h>` — crop region in CSS px; composite grammar is
    * validated by the owning leaf, which documents it. */
   crop?: string;
+  /** `measure text --crop` — write the selected target's measured PNG crop. */
+  textCrop?: boolean;
   /** `shot --crop-selector <selector>` — crop to this element's live box. */
   cropSelector?: string;
   /** `shot --pad <px>` — CSS-px padding added around a resolved crop rect. */
@@ -99,7 +107,7 @@ export interface ParsedArgs {
   before?: string;
   /** `diff --after <snap>` */
   after?: string;
-  /** `diff --full` — expand to the complete state-matrix/per-element diff. */
+  /** `diff --full` expands the complete state-matrix/per-element diff; `perf insights --name <insight> --full` renders that insight's related events. */
   full?: boolean;
   /** `check|diff --gate` — exit 2 on findings/changes instead of 0. */
   gate?: boolean;
@@ -146,4 +154,26 @@ export interface ParsedArgs {
   action?: string;
   /** `motion response --occurrence <n>` — 1-based occurrence of a repeated action label. */
   occurrence?: number;
+  /** `heap objects --constructor <name>` */
+  constructor?: string;
+  /** `heap retainers --node <object-id>` */
+  node?: string;
+  /** `heap retainers --paths <N>` */
+  paths?: number;
+  /** `heap objects --sort retained|self` */
+  sort?: string;
+  /** `tab mock start --rules <path>` */
+  rules?: string;
+  /** `lighthouse --categories <list>` */
+  categories?: string;
+  /** `lighthouse --preset mobile|desktop` */
+  preset?: string;
+  /** `page inspect listeners --scope window|document|target` */
+  scope?: 'window' | 'document' | 'target';
+  /** `page inspect listeners --event <type>` */
+  event?: string;
+  /** `page repeat --steps <json>` */
+  steps?: string;
+  /** `page repeat --iterations <n>` */
+  iterations?: number;
 }

package/src/cdp.ts

@@ -2,11 +2,10 @@
  * CDP (Chrome DevTools Protocol) — the library barrel over the CDP substrate.
  *
  * Re-exports the client, target discovery, screenshot, a11y, console-recording,
- * and tab-lock building blocks, plus `cdpMain` (the routed command dispatch).
- * HAR ownership is NOT exported here: the session HAR manager
- * (`src/har-manager.ts`) fed by the internal streaming recorder
- * (`src/cdp/har-recorder.ts`, a direct import of the recorder bridge) is the
- * sole HAR lane.
+ * and `cdpMain` (the routed command dispatch). HAR ownership is NOT exported
+ * here: the session HAR manager (`src/har-manager.ts`) fed by the internal
+ * streaming motion collector (`src/cdp/host/collectors/motion.ts`, which
+ * directly imports `src/cdp/har-recorder.ts`) is the sole HAR lane.
  * The command surface itself lives under `src/cdp/commands/` and is routed by
  * `src/capture.ts` → `src/cdp/dispatch.ts`. This module is a pure barrel:
  * `src/capture.ts` is the ONLY entrypoint and the ONLY error/termination
@@ -23,5 +22,4 @@ export { getAccessibilityTree } from './cdp/a11y.js';
 export { navigateAndWait } from './cdp/record.js';
 export { ConsoleRecorder } from './cdp/console-recorder.js';
 export type { ConsoleEntry } from './cdp/console-recorder.js';
-export { acquireTabLock, isTabLocked, releaseTabLock, withTabLock } from './cdp/tab-lock.js';
 export { cdpMain } from './cdp/dispatch.js';