@crouton-kit/capture 1.4.2 → 1.4.10

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

@@ -15,18 +15,17 @@
  * sequence; sessionless with no `--out` → a fresh `oneshot-{id}/page` dir
  * under the capture root (never a loose /tmp file).
  */
-import * as fs from 'fs';
 import * as path from 'path';
 import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
-import { captureScreenshotWithCssViewport, type CapturedRegion, type ScreenshotCrop } from '../../screenshot.js';
+import { type CDPClient } from '../../client.js';
+import { captureScreenshotWithCssViewport, writeScreenshot, type CapturedRegion, type ScreenshotCrop, type ScrollOffset } from '../../screenshot.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
 import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
 import { nextStepPath } from '../../../session-context.js';
 import { createOneshotSession } from '../../../session/commands.js';
 import { resolveLiveTarget, type LiveClient, type ResolutionFailure } from '../../../interact.js';
 import { emitResolutionError } from './click.js';
-import { assertUnderCaptureRoot, writeBinaryPrivate } from '../../../session/artifacts.js';
 import {
   emitResult,
   fact,
@@ -45,13 +44,14 @@ input:
   --crop-selector <sel>  resolve exactly one live target (bare CSS takes precedence; exact accessible name applies when CSS finds none; ax:<name>, axid:<id>, or backend:<id>), scroll it into view, then crop its border box and surroundings
   --pad <px>        nonnegative integer CSS pixels added on every side of --crop-selector (default: 0; not accepted with --crop)
   --zoom <factor>   positive decimal CSS-to-image scale requested for a CSS crop; the 1600px image cap may produce a smaller reported scale
-  --out <path>      destination file; default: the active session's shots/ sequence, or a fresh oneshot-*/page/ dir under the capture root when no session is active
+  --out <path>      caller-owned destination PNG; default: the active session's shots/ sequence, or a fresh one-shot bundle when no session is active
+  --artifact-dir <path>  root for that sessionless one-shot bundle (ignored with --out or an active session)
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
   --json            mirror the result as JSON
 output:
-  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page color-scheme=dark|light> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, byte size, crop provenance, and any requested transient emulation
+  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… effective-downscale-x=… effective-downscale-y=… scroll-x=… scroll-y=… emulation=none|viewport|full-page color-scheme=dark|light> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, visual-viewport scroll offset at capture, any effective downscale below 1 image px/CSS px, byte size, crop provenance, and any requested transient emulation
 effects:
-  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; an empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
+  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. Sessionless captures write one bundle under --artifact-dir when supplied; --out writes only its caller-owned PNG. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture. --crop-selector scrolls its resolved target into view. CSS crops are intersected with the source visual viewport; a selector crop reports its requested and delivered regions when its padded box cannot fit. An empty intersection fails without writing an image. --crop/--crop-selector cannot be combined with --full-page.`;
 
 // ---------------------------------------------------------------------------
 // Test-injectable dependency seam (the CDP-stub test pattern; the capture
@@ -94,29 +94,13 @@ export function pngDimensions(png: Buffer): { width: number; height: number } |
 
 /**
  * Resolves the output path: explicit `--out` > active session's `shots/`
- * sequence > a fresh `oneshot-{id}/page` dir under the capture root.
+ * sequence > a fresh `oneshot-{id}/page` dir under the selected artifact root.
  */
 async function resolveOutPath(parsed: ParsedArgs): Promise<string> {
   if (parsed.out) return parsed.out;
   const sessionPath = await deps.nextStepPath('shot', 'manual');
   if (sessionPath) return sessionPath;
-  return path.join(deps.createOneshotSession('page').artifactsDir, 'shot.png');
-}
-
-/**
- * Writes the PNG privately (0600 under a 0700 dir) when it lands under
- * CAPTURE_ROOT (auto-generated session/oneshot paths), and with a plain
- * write when the user gave an explicit `--out` outside the capture tree —
- * a user-chosen destination whose permissions are the user's to decide.
- */
-function writeScreenshot(outPath: string, png: Buffer): void {
-  try {
-    assertUnderCaptureRoot(outPath);
-  } catch {
-    fs.writeFileSync(outPath, png);
-    return;
-  }
-  writeBinaryPrivate(outPath, png);
+  return path.join(deps.createOneshotSession('page', parsed.artifactDir).artifactsDir, 'shot.png');
 }
 
 // ---------------------------------------------------------------------------
@@ -125,6 +109,8 @@ function writeScreenshot(outPath: string, png: Buffer): void {
 
 export type EmulationMode = 'none' | 'viewport' | 'full-page';
 
+const LEGIBILITY_SCALE_THRESHOLD = 0.5;
+
 interface CropProvenance {
   readonly source: 'coordinates' | 'selector';
   readonly requested: ScreenshotCrop;
@@ -139,11 +125,16 @@ function round6(value: number): number {
   return Math.round(value * 1e6) / 1e6;
 }
 
+function sameRect(a: ScreenshotCrop, b: CapturedRegion): boolean {
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+
 export function buildScreenshotResult(f: {
   path: string;
   bytes: number;
   dimensions: { width: number; height: number } | null;
   cssViewport?: CapturedRegion;
+  scrollOffset?: ScrollOffset;
   emulation: EmulationMode;
   viewport?: { width: number; height: number };
   colorScheme?: ColorScheme;
@@ -155,6 +146,17 @@ export function buildScreenshotResult(f: {
   const scale = f.dimensions && f.cssViewport
     ? { x: f.dimensions.width / f.cssViewport.width, y: f.dimensions.height / f.cssViewport.height }
     : undefined;
+  const downscale = scale && (scale.x < 1 || scale.y < 1)
+    ? { x: scale.x < 1 ? scale.x : undefined, y: scale.y < 1 ? scale.y : undefined }
+    : undefined;
+  const downscaleDescription = downscale
+    ? [
+      downscale.x === undefined ? undefined : `horizontal ${downscale.x.toFixed(6)}×`,
+      downscale.y === undefined ? undefined : `vertical ${downscale.y.toFixed(6)}×`,
+    ].filter((axis): axis is string => axis !== undefined).join(' and ')
+    : undefined;
+  const cropConstrained = f.crop?.source === 'selector' && f.cssViewport !== undefined && !sameRect(f.crop.requested, f.cssViewport);
+  const legibilityConstrained = scale !== undefined && Math.min(scale.x, scale.y) < LEGIBILITY_SCALE_THRESHOLD && Math.min(scale.x, scale.y) < (f.crop?.zoom ?? 1);
   const sections: FactLine[] = [
     scale && f.cssViewport
       ? fact`CSS-to-image scale: ${scale.x.toFixed(6)} image px/CSS px horizontally and ${scale.y.toFixed(6)} image px/CSS px vertically (captured CSS region ${round6(f.cssViewport.width)}×${round6(f.cssViewport.height)} at page origin ${round6(f.cssViewport.x)},${round6(f.cssViewport.y)}).`
@@ -162,6 +164,12 @@ export function buildScreenshotResult(f: {
     f.crop
       ? fact`CSS crop: ${f.crop.source === 'selector' ? `selector ${f.crop.selector} (backend:${f.crop.backendNodeId}), border box plus ${f.crop.pad}px padding` : 'coordinates'} requested ${formatRect(f.crop.requested)} at zoom ${f.crop.zoom}; the captured CSS region above is its intersection with the source visual viewport.`
       : text`CSS crop: none — the captured CSS region above is the source visual viewport.`,
+    ...(cropConstrained && f.crop && f.cssViewport
+      ? [fact`Crop constraint: requested ${formatRect(f.crop.requested)}; delivered ${formatRect(f.cssViewport)} because the requested selector crop extended outside the ${f.emulation === 'viewport' ? 'effective live visual viewport after its transient device-metrics override' : 'live visual viewport'}, so the artifact contains its visual-viewport intersection.`]
+      : []),
+    f.scrollOffset
+      ? fact`scroll offset at capture: x=${round6(f.scrollOffset.x)} y=${round6(f.scrollOffset.y)} CSS px.`
+      : text`scroll offset at capture unavailable: the browser did not return the visual viewport origin.`,
     f.emulation === 'none'
       ? text`viewport emulation: none — the browser's actual current viewport was captured.`
       : f.emulation === 'viewport'
@@ -172,6 +180,7 @@ export function buildScreenshotResult(f: {
     f.colorScheme
       ? fact`color scheme: transient prefers-color-scheme=${f.colorScheme} override applied for the capture and cleared after.`
       : text`color scheme: browser default — no Emulation.setEmulatedMedia call was made.`,
+    ...(legibilityConstrained ? [fact`Image constraint: the 1600px image-side cap reduced this artifact below ${LEGIBILITY_SCALE_THRESHOLD} image px per CSS px.`] : []),
   ];
   return {
     tag: 'screenshot',
@@ -185,17 +194,27 @@ export function buildScreenshotResult(f: {
       'css-y': f.cssViewport === undefined ? undefined : round6(f.cssViewport.y),
       'css-to-image-x': scale?.x.toFixed(6),
       'css-to-image-y': scale?.y.toFixed(6),
+      'effective-downscale-x': downscale?.x?.toFixed(6),
+      'effective-downscale-y': downscale?.y?.toFixed(6),
       emulation: f.emulation,
       'color-scheme': f.colorScheme,
       'crop-source': f.crop?.source,
       'crop-selector': f.crop?.selector,
       'crop-backend-node-id': f.crop?.backendNodeId,
       'requested-zoom': f.crop?.zoom,
+      'crop-constrained': cropConstrained ? 'visual-viewport' : undefined,
+      'scroll-x': f.scrollOffset === undefined ? undefined : round6(f.scrollOffset.x),
+      'scroll-y': f.scrollOffset === undefined ? undefined : round6(f.scrollOffset.y),
     },
     summary: f.dimensions
-      ? fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes.`
+      ? downscaleDescription
+        ? fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes; effective downscale: ${downscaleDescription} (image px/CSS px).`
+        : fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes.`
       : fact`saved ${f.path} — ${f.bytes} bytes.`,
     sections,
+    followUp: legibilityConstrained
+      ? text`A selector crop with --zoom 1 captures a bounded region at 1 image px/CSS px when each captured CSS side is at most 1600px.`
+      : undefined,
   };
 }
 
@@ -231,6 +250,25 @@ function padded(rect: ScreenshotCrop, pad: number): ScreenshotCrop {
   return { x: rect.x - pad, y: rect.y - pad, width: rect.width + 2 * pad, height: rect.height + 2 * pad };
 }
 
+async function pageBorderRect(client: CDPClient, backendNodeId: number): Promise<ScreenshotCrop | undefined> {
+  const box = (await client.send('DOM.getBoxModel', { backendNodeId })) as { model?: unknown };
+  const rect = borderRect(box.model);
+  if (!rect) return undefined;
+
+  // DOM box-model quads are relative to the live viewport. Screenshot clips
+  // use page coordinates, so account for the scroll DOM.scrollIntoViewIfNeeded
+  // just performed for a selector crop.
+  const metrics = (await client.send('Page.getLayoutMetrics')) as {
+    cssVisualViewport?: { pageX?: unknown; pageY?: unknown; clientWidth?: unknown; clientHeight?: unknown };
+  };
+  const pageX = metrics.cssVisualViewport?.pageX;
+  const pageY = metrics.cssVisualViewport?.pageY;
+  if (typeof pageX !== 'number' || !Number.isFinite(pageX) || typeof pageY !== 'number' || !Number.isFinite(pageY)) {
+    throw new Error('Page.getLayoutMetrics returned no valid visual-viewport page origin for --crop-selector.');
+  }
+  return { ...rect, x: rect.x + pageX, y: rect.y + pageY };
+}
+
 // ---------------------------------------------------------------------------
 // page shot
 // ---------------------------------------------------------------------------
@@ -326,8 +364,6 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
     return;
   }
 
-  const emulation: EmulationMode = parsed.fullPage ? 'full-page' : viewport ? 'viewport' : 'none';
-
   // connection.ts derives the recorder-routed action label from
   // parsed.command, which the router leaves as the branch token 'page' —
   // restore the verb so stderr diagnostics identify this leaf.
@@ -340,8 +376,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
         const resolved = await resolveLiveTarget(client as unknown as LiveClient, parsed.cropSelector);
         if (!resolved.ok) return { failure: resolved } as const;
         await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId: resolved.backendNodeId });
-        const box = (await client.send('DOM.getBoxModel', { backendNodeId: resolved.backendNodeId })) as { model?: unknown };
-        const rect = borderRect(box.model);
+        const rect = await pageBorderRect(client, resolved.backendNodeId);
         if (!rect) throw new Error(`Resolved target backend:${resolved.backendNodeId} has no measurable border box for --crop-selector.`);
         const pad = parsed.pad ?? 0;
         requestedCrop = padded(rect, pad);
@@ -352,7 +387,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
       const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage, crop: requestedCrop, zoom });
       const outPath = await resolveOutPath(parsed);
       writeScreenshot(outPath, screenshot.png);
-      return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport, crop: cropProvenance } as const;
+      return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport, scrollOffset: screenshot.scrollOffset, crop: cropProvenance } as const;
     }),
     { settle: 0 },
   );
@@ -361,5 +396,5 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
     emitResolutionError(parsed, 'page shot', result.failure as ResolutionFailure);
     return;
   }
-  emitResult(buildScreenshotResult({ ...result, emulation, viewport, colorScheme }), { json: parsed.json });
+  emitResult(buildScreenshotResult({ ...result, emulation: parsed.fullPage ? 'full-page' : viewport ? 'viewport' : 'none', viewport, colorScheme }), { json: parsed.json });
 }

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

@@ -32,7 +32,7 @@ input:
   --settle <ms>     network-settle window applied after typing (default: 500; 1500 with an active session; 0 disables)
   --no-screenshot   skip the auto-screenshot
 output:
-  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
+  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, a hit-test receiver fact when another node covers that focus-click point, the measured settle (requested/waited), and either the screenshot artifact path or a warning when only that follow-up capture timed out; --json mirrors the same fields
 effects:
   dispatches a real focus click (when --into) followed by real text insertion; writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
 
@@ -65,7 +65,7 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
       if (parsed.into) {
         const resolved = await resolveLiveTarget(live, parsed.into);
         if (!resolved.ok) return { failure: resolved } as const;
-        dispatch = await focusAndType(live, resolved, textArg);
+        dispatch = await focusAndType(live, resolved, textArg, { inspectHitTest: true });
       } else {
         await typeText(live, textArg);
       }
@@ -84,6 +84,9 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
     dispatch
       ? fact`typed "${textArg}" into ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}), focus click at x=${dispatch.x} y=${dispatch.y}`
       : fact`typed "${textArg}" into the focused element`,
+    ...(dispatch?.hitTestReceiverBackendNodeId === undefined
+      ? []
+      : [fact`focus-click hit test at x=${dispatch.x} y=${dispatch.y} resolved to backend:${dispatch.hitTestReceiverBackendNodeId}, not target backend:${dispatch.backendNodeId}`]),
     fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
   ];
   if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
@@ -97,6 +100,7 @@ export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<
             'backend-node-id': dispatch.backendNodeId,
             role: dispatch.role ?? undefined,
             name: dispatch.name ?? undefined,
+            'hit-test-receiver-backend-node-id': dispatch.hitTestReceiverBackendNodeId,
           }
         : {},
       summary: lineList(rows),

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

@@ -0,0 +1,32 @@
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { cmdPerfTrace } from './trace.js';
+import { cmdPerfVitals } from './vitals.js';
+import { cmdPerfInsights } from './insights.js';
+
+export const COMMAND_BLOCK = `<command name="perf">
+the Chrome performance-trace substrate — \`trace\` records one, \`vitals\` and \`insights\` are read-only queries over it
+use for Core Web Vitals and DevTools insights over a page load or one interaction, timed from trace events
+</command>`;
+
+const HELP = `<command name="perf" description="the Chrome performance-trace substrate">
+<model>\`trace\` drives (and records) the browser, one-shot or composed across intervening commands; the other leaves are cheap reads over the finalized trace artifact. Findings exit 0 — a report, not a failure; input/precondition errors exit 1. No leaf accepts --gate.</model>
+<subcommand name="trace" description="record a Chrome performance trace" whenToUse="Use to record the substrate that vitals and insights read — a page load, one interaction, or a window you open and close."/>
+<subcommand name="vitals" description="Core Web Vitals from a recorded trace" whenToUse="Use for LCP, INP, and CLS with their subparts and attribution."/>
+<subcommand name="insights" description="the DevTools insight set from a recorded trace" whenToUse="Use for the engine's computed insights — render-blocking requests, forced reflow, layout-shift culprits, and the rest of the set."/>
+</command>`;
+
+export async function perfMain(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+  switch (leaf) {
+    case 'trace': return cmdPerfTrace(rest);
+    case 'vitals': return cmdPerfVitals(rest);
+    case 'insights': return cmdPerfInsights(rest);
+    case undefined:
+      console.log(HELP);
+      return;
+    default:
+      throw invalidInput(`Unknown perf leaf: ${leaf}.`, 'unknown_command');
+  }
+}

package/src/cdp/commands/perf/insights.ts

@@ -0,0 +1,214 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { type ParsedArgs } from '../../types.js';
+import { analyzeChromeTrace, type TraceInsight, type TraceInsightField, type TraceInsightSet } from '../../trace-analysis.js';
+import { resolveTraceRef } from '../../../output/artifact.js';
+import { data, emitResult, fact, line, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+import { selectRecords } from '../../../output/selection.js';
+
+const HELP = `capture perf insights <trace> [--name <insight> --full] [--limit <N>] — the DevTools insight set computed from a recorded trace
+
+input:
+  <trace>          trace id in the active session or an absolute trace path (required; the trace must be finalized)
+  --name <insight> select one engine insight by name from the default aggregation
+  --limit <N>      return at most N selected insight records in prose and JSON; default 25
+  --full            with --name, include a bounded related-event drill-down only when every selected event fits within 50 events and 48,000 serialized bytes; otherwise returns the bounded --name view and states the factual bound
+output: <insights …> — default output is a bounded aggregation of engine insight names, scalar metrics, and related-event counts; --name adds top stack and duration-distribution facts for that insight; --name with --full preserves those facts before adding a complete bounded event drill-down, or refuses partial event detail when the selected corpus exceeds its stated bound; capture reports engine facts without converting an insight's presence into an assessment of the page; --json mirrors
+effects: read-only — reads the finalized trace artifact, never drives the browser`;
+
+function error(parsed: ParsedArgs, status: string, message: string): void {
+  emitResult({ tag: 'error', attrs: { command: 'perf insights', status }, summary: fact`${message}` }, { json: parsed.json });
+  process.exitCode = 1;
+}
+
+function relatedEventCount(fields: Readonly<Record<string, TraceInsightField>>): number {
+  const related = fields.relatedEvents;
+  if (Array.isArray(related)) return related.length;
+  if (related !== null && typeof related === 'object' && !Array.isArray(related)) {
+    const entries = related.entries;
+    if (Array.isArray(entries)) return entries.length;
+  }
+  return 0;
+}
+
+function scalarMetrics(fields: Readonly<Record<string, TraceInsightField>>): Record<string, number | boolean> {
+  return Object.fromEntries(Object.entries(fields).flatMap(([name, value]) => typeof value === 'number' || typeof value === 'boolean' ? [[name, value]] : []));
+}
+
+function aggregate(insight: TraceInsight): { name: string; relatedEventCount: number; scalarMetrics: Record<string, number | boolean> } {
+  return { name: insight.name, relatedEventCount: relatedEventCount(insight.fields), scalarMetrics: scalarMetrics(insight.fields) };
+}
+
+function aggregateLine(insight: TraceInsight): FactLine {
+  const summary = aggregate(insight);
+  const metrics = Object.entries(summary.scalarMetrics).map(([name, value]) => `${name}=${value}`);
+  return fact`${summary.name}: ${summary.relatedEventCount} related event(s); scalar metrics: ${metrics.length ? metrics.join(', ') : 'none'}.`;
+}
+
+const FULL_EVENT_LIMIT = 50;
+const FULL_BYTE_LIMIT = 48_000;
+
+type RelatedEvent = Record<string, unknown>;
+
+interface FullFields {
+  scalarMetrics: Record<string, number | boolean>;
+  relatedEvents: { events: RelatedEvent[]; omitted: number };
+}
+
+interface FullBudget {
+  remainingEvents: number;
+  remainingBytes: number;
+}
+
+interface NamedFields {
+  relatedEventCount: number;
+  durationDistribution: string;
+  topStack: { label: string; count: number } | null;
+}
+
+function relatedEvents(fields: Readonly<Record<string, TraceInsightField>>): RelatedEvent[] {
+  const related = fields.relatedEvents;
+  if (Array.isArray(related)) return related.filter((event): event is RelatedEvent => event !== null && typeof event === 'object' && !Array.isArray(event));
+  if (related !== null && typeof related === 'object' && !Array.isArray(related) && Array.isArray(related.entries)) {
+    return related.entries.filter((event): event is RelatedEvent => event !== null && typeof event === 'object' && !Array.isArray(event));
+  }
+  return [];
+}
+
+function durationDistribution(events: readonly RelatedEvent[]): string {
+  const durations = events.map(event => event.dur).filter((duration): duration is number => typeof duration === 'number' && Number.isFinite(duration)).sort((a, b) => a - b);
+  if (durations.length === 0) return 'unavailable (no related event carried a finite dur)';
+  const at = (percentile: number) => durations[Math.min(durations.length - 1, Math.floor((durations.length - 1) * percentile))]! / 1000;
+  return `n=${durations.length}, min=${at(0)}ms, p50=${at(0.5)}ms, p95=${at(0.95)}ms, max=${at(1)}ms`;
+}
+
+function stackLabel(event: RelatedEvent): string | null {
+  const args = event.args && typeof event.args === 'object' ? event.args as { data?: unknown; beginData?: unknown } : undefined;
+  const data = args?.data ?? args?.beginData;
+  const stack = data && typeof data === 'object' ? (data as { stackTrace?: unknown; stack?: unknown }).stackTrace ?? (data as { stack?: unknown }).stack : undefined;
+  const frame = Array.isArray(stack) ? stack[0] : stack && typeof stack === 'object' ? stack : undefined;
+  if (!frame || typeof frame !== 'object') return null;
+  const value = frame as { functionName?: unknown; url?: unknown; lineNumber?: unknown; columnNumber?: unknown };
+  const name = typeof value.functionName === 'string' && value.functionName ? value.functionName : '(anonymous)';
+  const location = typeof value.url === 'string' ? `${value.url}:${typeof value.lineNumber === 'number' ? value.lineNumber + 1 : '?'}` : null;
+  return location ? `${name} at ${location}` : name;
+}
+
+function namedFields(insight: TraceInsight): NamedFields {
+  const events = relatedEvents(insight.fields);
+  const stacks = new Map<string, number>();
+  for (const event of events) {
+    const label = stackLabel(event);
+    if (label) stacks.set(label, (stacks.get(label) ?? 0) + 1);
+  }
+  const topStack = [...stacks.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+  return {
+    relatedEventCount: relatedEventCount(insight.fields),
+    durationDistribution: durationDistribution(events),
+    topStack: topStack ? { label: topStack[0], count: topStack[1] } : null,
+  };
+}
+
+function namedRecordLine(insight: TraceInsight): FactLine {
+  const details = namedFields(insight);
+  return fact`${insight.name}: ${details.relatedEventCount} related event(s); duration distribution ${details.durationDistribution}; top stack ${details.topStack ? `${details.topStack.label} (${details.topStack.count} event(s))` : 'unavailable'}.`;
+}
+
+function fullFields(insight: TraceInsight, budget: FullBudget): FullFields {
+  const events = relatedEvents(insight.fields);
+  const retained: RelatedEvent[] = [];
+  for (const event of events) {
+    const bytes = Buffer.byteLength(JSON.stringify(event));
+    if (budget.remainingEvents === 0 || bytes > budget.remainingBytes) break;
+    retained.push(event);
+    budget.remainingEvents--;
+    budget.remainingBytes -= bytes;
+  }
+  return {
+    scalarMetrics: scalarMetrics(insight.fields),
+    relatedEvents: { events: retained, omitted: events.length - retained.length },
+  };
+}
+
+function fullRecordLine(insight: TraceInsight, fields: FullFields): FactLine {
+  return lineList([
+    namedRecordLine(insight),
+    line(fact`${insight.name}: complete related-event detail (${fields.relatedEvents.events.length} event(s)); fields: `, data(JSON.stringify(fields), FULL_BYTE_LIMIT)),
+  ]);
+}
+
+function completeFullFields(insight: TraceInsight): FullFields {
+  return {
+    scalarMetrics: scalarMetrics(insight.fields),
+    relatedEvents: { events: relatedEvents(insight.fields), omitted: 0 },
+  };
+}
+
+function fullDetailSize(insights: readonly TraceInsight[]): { bytes: number; largestChars: number } {
+  return insights.reduce(({ bytes, largestChars }, insight) => {
+    const serialized = JSON.stringify(completeFullFields(insight));
+    return { bytes: bytes + Buffer.byteLength(serialized), largestChars: Math.max(largestChars, serialized.length) };
+  }, { bytes: 0, largestChars: 0 });
+}
+
+function section(set: TraceInsightSet, insights: readonly TraceInsight[], full: boolean, named: boolean, fullByInsight: ReadonlyMap<TraceInsight, FullFields>): FactLine {
+  const records = insights.length ? insights.map(insight => full ? fullRecordLine(insight, fullByInsight.get(insight)!) : named ? namedRecordLine(insight) : aggregateLine(insight)) : [text`No engine records matched the requested insight name.`];
+  return lineList([fact`Insight set ${set.id} for ${set.url}`, ...records]);
+}
+
+function noInsightSet(events: readonly object[], completion: string): { section: FactLine; json: Record<string, string | number> } {
+  const navigations = events.filter((event) => (event as { name?: unknown }).name === 'navigationStart').length;
+  const recording = completion === 'complete'
+    ? `The trace was recorded successfully and finalized (completion=${completion}).`
+    : `The trace artifact was finalized with completion=${completion}.`;
+  return navigations === 0
+    ? { section: fact`${recording} This trace-engine analysis emitted 0 navigation-scoped insight set(s) because the trace contains no navigation. That engine scope does not describe the other performance evidence recorded in trace.json.`, json: { status: 'no-insight-set', navigations, 'trace-recording': `finalized:${completion}`, 'engine-analysis-scope': 'navigation-scoped-insight-sets', 'navigation-insight-sets': 0, reason: 'no-navigation' } }
+    : { section: text`No DevTools insight set was produced for the ${navigations} recorded navigation(s), so this recording cannot yield DevTools insights.`, json: { status: 'no-insight-set', navigations, reason: 'engine-produced-no-insight-set' } };
+}
+
+export async function cmdPerfInsights(parsed: ParsedArgs): Promise<void> {
+  if (parsed.help) { console.log(HELP); return; }
+  const input = parsed.positional[0];
+  if (!input) return error(parsed, 'invalid_target', 'perf insights requires one finalized trace id or absolute trace path.');
+  try {
+    const trace = resolveTraceRef(input);
+    const raw = JSON.parse(fs.readFileSync(path.join(trace.dir, 'trace.json'), 'utf8')) as { traceEvents?: object[] };
+    if (!Array.isArray(raw.traceEvents)) throw new Error('trace.json is not a Chrome trace with a traceEvents array');
+    const analysis = await analyzeChromeTrace({ traceEvents: raw.traceEvents });
+    let remaining = parsed.limit ?? 25;
+    const selected = analysis.insightSets.map((set) => {
+      const filtered = parsed.name === undefined ? set.insights : set.insights.filter(insight => insight.name === parsed.name);
+      const insights = selectRecords(filtered, { limit: remaining }, remaining);
+      remaining -= insights.length;
+      return { ...set, insights };
+    });
+    const selectedInsights = selected.flatMap((set) => set.insights);
+    const relatedEventsTotal = selectedInsights.reduce((count, insight) => count + relatedEvents(insight.fields).length, 0);
+    const detailSize = fullDetailSize(selectedInsights);
+    const fullRefused = parsed.full && (relatedEventsTotal > FULL_EVENT_LIMIT || detailSize.bytes > FULL_BYTE_LIMIT || detailSize.largestChars > FULL_BYTE_LIMIT);
+    const fullBudget: FullBudget = { remainingEvents: FULL_EVENT_LIMIT, remainingBytes: FULL_BYTE_LIMIT };
+    const fullByInsight = new Map<TraceInsight, FullFields>();
+    if (parsed.full && !fullRefused) {
+      for (const set of selected) {
+        for (const insight of set.insights) fullByInsight.set(insight, fullFields(insight, fullBudget));
+      }
+    }
+    const relatedEventsRetained = [...fullByInsight.values()].reduce((total, fields) => total + fields.relatedEvents.events.length, 0);
+    const noSet = selected.length === 0 ? noInsightSet(raw.traceEvents, trace.completion) : undefined;
+    const result: RenderableResult = {
+      tag: 'insights',
+      attestation: { kind: 'trace', id: trace.id, path: trace.dir },
+      attrs: { completion: trace.completion, ...(trace.reason ? { reason: trace.reason } : {}), engine: analysis.source.engine, 'insight-sets': selected.length, insights: selected.reduce((count, set) => count + set.insights.length, 0), limit: parsed.limit ?? 25, ...(parsed.name ? { name: parsed.name } : {}), ...(parsed.full && !fullRefused ? { detail: 'full', 'events-retained': relatedEventsRetained, 'events-omitted': relatedEventsTotal - relatedEventsRetained, 'event-bytes-retained': FULL_BYTE_LIMIT - fullBudget.remainingBytes } : parsed.full ? { detail: 'aggregation', full: 'refused', 'full-reason': 'selected-event-corpus-exceeds-bound', 'related-events': relatedEventsTotal, 'related-event-bytes': detailSize.bytes } : { detail: 'aggregation' }) },
+      summary: parsed.full && !fullRefused
+        ? fact`The selected related-event drill-down contains every selected event within the ${FULL_EVENT_LIMIT}-event/${FULL_BYTE_LIMIT}-byte bound; each record begins with its duration-distribution and top-stack facts.`
+        : parsed.full
+          ? fact`The selected related-event corpus has ${relatedEventsTotal} event(s) and ${detailSize.bytes} serialized detail bytes, exceeding the ${FULL_EVENT_LIMIT}-event/${FULL_BYTE_LIMIT}-byte full-detail bound; this result preserves the bounded --name aggregation rather than emitting a partial event corpus.`
+          : parsed.name
+            ? fact`The selected insight reports its related-event count, duration distribution, and most frequent reported stack without emitting the event corpus.`
+            : fact`Insight names, scalar metrics, and related-event counts are computed by the DevTools trace engine (${analysis.source.engine}, an unstable upstream API pinned by capture). Use \`--name <insight>\` for stack and duration facts, or add \`--full\` for a bounded related-event drill-down.`,
+      sections: selected.length ? selected.map(set => section(set, set.insights, parsed.full === true && !fullRefused, parsed.name !== undefined, fullByInsight)) : [noSet!.section],
+      jsonSections: selected.length ? selected.map(set => ({ set: set.id, url: set.url, insights: parsed.full && !fullRefused ? set.insights.map(insight => ({ ...aggregate(insight), ...namedFields(insight), fields: fullByInsight.get(insight)! })) : parsed.name ? set.insights.map(insight => ({ ...aggregate(insight), ...namedFields(insight) })) : set.insights.map(aggregate) })) : [noSet!.json],
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (cause) { error(parsed, 'artifact_unavailable', cause instanceof Error ? cause.message : String(cause)); }
+}