@crouton-kit/capture 1.4.2 → 1.4.10

package/src/cdp/measure/map-layers.ts

@@ -1,4 +1,5 @@
 import type { LayerRecord, LayersReport } from './collectors/layers.js';
+import { selectRecords } from '../../output/selection.js';
 import type { SnapMeta } from '../../session/artifacts.js';
 import {
   annotateUnstableFacts,
@@ -27,6 +28,22 @@ interface LayerFact {
   readonly rect: Rect;
 }
 
+const INLINE_IDENTIFIER_LIMIT = 50;
+
+function boundedIdentifiers(ids: readonly number[], total: number): { listed: readonly number[]; omitted: number } {
+  const listed = ids.slice(0, INLINE_IDENTIFIER_LIMIT);
+  return { listed, omitted: Math.max(0, total - listed.length) };
+}
+
+function layerJson(layer: LayerRecord): Record<string, unknown> {
+  const members = boundedIdentifiers(layer.memberBackendNodeIds, layer.memberCount);
+  return {
+    ...layer,
+    memberBackendNodeIds: members.listed,
+    memberBackendNodeIdsOmitted: members.omitted,
+  };
+}
+
 function sourceFor(layer: LayerRecord): string | undefined {
   const provenance = layer.styleProvenance;
   if (!provenance) return undefined;
@@ -75,8 +92,12 @@ function formatLayer(layer: LayerRecord, membershipAvailable: boolean, caveats:
   else if (layer.compositingReasons.length) details.push(fact`Compositing reasons: ${layer.compositingReasons.join(', ')}`);
   else details.push(text`Compositing reasons: none reported.`);
   if (!membershipAvailable) details.push(text`Node membership was unavailable for this layer.`);
-  else if (layer.membersTruncated) details.push(fact`Node membership: ${layer.memberCount} painted node(s); first ${layer.memberBackendNodeIds.length} backend id(s): ${layer.memberBackendNodeIds.join(', ')}; ${layer.membersTruncated} additional id(s) not listed.`);
-  else details.push(fact`Node membership: ${layer.memberCount} painted node(s); backend id(s): ${layer.memberBackendNodeIds.join(', ') || '(none)'}.`);
+  else {
+    const members = boundedIdentifiers(layer.memberBackendNodeIds, layer.memberCount);
+    details.push(members.omitted
+      ? line(fact`Node membership: ${layer.memberCount} painted node(s); first ${members.listed.length} backend id(s): `, data(members.listed.join(', ') || '(none)', 1000), fact`; ${members.omitted} id(s) omitted.`)
+      : line(fact`Node membership: ${layer.memberCount} painted node(s); backend id(s): `, data(members.listed.join(', ') || '(none)', 1000), text`.`));
+  }
   if (layer.styleProvenance) {
     const provenance = layer.styleProvenance;
     details.push(line(
@@ -104,14 +125,16 @@ function formatLayer(layer: LayerRecord, membershipAvailable: boolean, caveats:
 
 function paintOrderLine(report: LayersReport, caveats: readonly UnstableCaveat[]): FactLine {
   if (!report.paintOrder.available) return fact`DOMSnapshot paint order unavailable${report.paintOrder.reason ? `: ${report.paintOrder.reason}` : ''}.`;
-  const ids = report.paintOrder.backendNodeIds;
-  const suffix = report.paintOrder.truncated ? `; ${report.paintOrder.truncated} additional backend node id(s) not listed` : '';
-  const base = fact`DOMSnapshot paint order (back-to-front): ${ids.join(', ') || '(no painted backend nodes recorded)'}${suffix}.`;
+  const total = report.paintOrder.backendNodeIds.length + report.paintOrder.truncated;
+  const ids = boundedIdentifiers(report.paintOrder.backendNodeIds, total);
+  const base = ids.omitted
+    ? line(fact`DOMSnapshot paint order (back-to-front): ${total} painted node(s); first ${ids.listed.length} backend id(s): `, data(ids.listed.join(', ') || '(none)', 1000), fact`; ${ids.omitted} id(s) omitted.`)
+    : line(fact`DOMSnapshot paint order (back-to-front): ${total} painted node(s); backend id(s): `, data(ids.listed.join(', ') || '(none)', 1000), text`.`);
   const caveat = caveatLine(caveats);
   return caveat ? lineList([base, caveat]) : base;
 }
 
-export function buildMeasureMapLayersResult(ref: SnapRef): RenderableResult {
+export function buildMeasureMapLayersResult(ref: SnapRef, limit?: number): RenderableResult {
   const report = readLayers<LayersReport>(ref);
   const meta = readMeta<SnapMeta>(ref);
   const regions = unstableRegionsFor(ref);
@@ -138,9 +161,15 @@ export function buildMeasureMapLayersResult(ref: SnapRef): RenderableResult {
   const layerTreeStatus = report.layerTree.available ? 'available' : 'unavailable';
   const paintOrderStatus = report.paintOrder.available ? 'available' : 'unavailable';
   const membershipStatus = report.membership.available ? 'available' : 'unavailable';
+  const paintedNodeCount = report.paintOrder.backendNodeIds.length + report.paintOrder.truncated;
+  const paintOrderJson = report.paintOrder.available
+    ? { ...report.paintOrder, paintedNodeCount, ...(() => { const ids = boundedIdentifiers(report.paintOrder.backendNodeIds, paintedNodeCount); return { backendNodeIds: ids.listed, backendNodeIdsOmitted: ids.omitted }; })() }
+    : report.paintOrder;
   const availability = report.layerTree.available
     ? fact`LayerTree facts available for ${report.layers.length} layer(s). DOMSnapshot paint order is ${paintOrderStatus}.`
     : fact`LayerTree facts unavailable${report.layerTree.reason ? `: ${report.layerTree.reason}` : ''}. DOMSnapshot paint order is ${paintOrderStatus}.`;
+  const displayed = selectRecords(annotated, { limit }, 25);
+  const layerPaintOrder = selectRecords(report.layerPaintOrder, { limit }, 25);
   const sections: FactLine[] = [availability, paintOrderLine(report, paintOrderCaveats)];
   if (report.layersTruncated) sections.push(fact`${report.layersTruncated} compositor layer(s) were not listed because the snapshot collector capped the layer inventory.`);
   if (report.membership.available) {
@@ -151,7 +180,8 @@ export function buildMeasureMapLayersResult(ref: SnapRef): RenderableResult {
   if (!report.styleSheetHeaders.available) {
     sections.push(fact`Stylesheet-header provenance availability: unavailable${report.styleSheetHeaders.reason ? `: ${report.styleSheetHeaders.reason}` : ''}.`);
   }
-  sections.push(...annotated.map(({ layerFact, caveats }) => formatLayer(layerFact.layer, report.membership.available, caveats)));
+  if (annotated.length > displayed.length) sections.push(fact`Layer records: listing capped at ${displayed.length} of ${annotated.length} layers (--limit).`);
+  sections.push(...displayed.map(({ layerFact, caveats }) => formatLayer(layerFact.layer, report.membership.available, caveats)));
 
   return {
     tag: 'layer-map',
@@ -165,13 +195,27 @@ export function buildMeasureMapLayersResult(ref: SnapRef): RenderableResult {
     },
     attrs: {
       layers: report.layers.length,
+      displayed: displayed.length,
       'layer-tree': layerTreeStatus,
       'paint-order': paintOrderStatus,
       membership: membershipStatus,
+      'painted-nodes': report.paintOrder.available ? paintedNodeCount : undefined,
       settled: meta.settled,
     },
-    summary: text`Paint/compositor layer facts, DOMSnapshot paint order, node membership, and available layer-style provenance are reported from layers.json.`,
+    summary: report.paintOrder.available
+      ? fact`Paint/compositor layer facts and ${paintedNodeCount} DOMSnapshot painted node(s) are reported from layers.json; identifier lists are limited to ${INLINE_IDENTIFIER_LIMIT} per corpus with omitted counts.`
+      : text`Paint/compositor layer facts, DOMSnapshot paint order, node membership, and available layer-style provenance are reported from layers.json.`,
     sections,
+    jsonSections: [{
+      layerTree: report.layerTree,
+      layers: displayed.map(({ layerFact }) => layerJson(layerFact.layer)),
+      layersTruncated: report.layersTruncated,
+      paintOrder: paintOrderJson,
+      layerPaintOrder,
+      layerPaintOrderOmitted: report.layerPaintOrder.length - layerPaintOrder.length,
+      membership: report.membership,
+      styleSheetHeaders: report.styleSheetHeaders,
+    }],
     followUp: fact`Inspect an element's cascade and stacking facts with \`capture measure explain ${ref.id} --selector <selector>\`.`,
   };
 }

package/src/cdp/measure/snapshot.ts

@@ -182,6 +182,8 @@ function makeCollectorWriter(writer: RollbackWriter): { writer: SnapshotWriter;
 
 /** 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;
+/** Scroll-topology sampling can trigger a page's own scroll handler before its next CDP read. Keep that one collector bounded, but long enough to observe the resulting renderer work. */
+export const SCROLL_COLLECTOR_REQUEST_TIMEOUT_MS = 30_000;
 
 /** A snapshot operation timed out after writing zero or more partial artifacts. */
 export class SnapshotCaptureTimeout extends Error {
@@ -199,10 +201,10 @@ export class SnapshotCaptureTimeout extends Error {
 }
 
 /** Bounds one snapshot CDP request and labels the phase that owns it. */
-function boundedClient(client: CDPClient, phase: string, partialPath: string, onTimeout?: (error: SnapshotCaptureTimeout) => void): CDPClient {
+function boundedClient(client: CDPClient, phase: string, partialPath: string, onTimeout?: (error: SnapshotCaptureTimeout) => void, requestTimeoutCapMs = SNAPSHOT_REQUEST_TIMEOUT_MS): 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);
+    const timeoutMs = Math.min(timeout, requestTimeoutCapMs);
     let timer: NodeJS.Timeout | undefined;
     let timedOut = false;
     const markTimedOut = (error: SnapshotCaptureTimeout): void => {
@@ -403,7 +405,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
             client: boundedClient(client, `collector:${collector.name}`, dir, (error) => {
               requestTimeouts += 1;
               timeoutError ??= error;
-            }),
+            }, collector.name === 'scroll' ? SCROLL_COLLECTOR_REQUEST_TIMEOUT_MS : SNAPSHOT_REQUEST_TIMEOUT_MS),
             write: collectorWriter.writer,
           });
           // A styles timeout may be caught per-record by the provenance collector,

package/src/cdp/measure/sweep.ts

@@ -23,6 +23,8 @@ export interface SweepTransition {
   readonly before: string;
   readonly after: string;
   readonly changes: readonly SweepChange[];
+  /** The observed endpoint difference could not be narrowed before the sample budget ran out. */
+  readonly uncertainty?: 'sampling_limit';
 }
 
 export interface SweepChange {
@@ -42,6 +44,7 @@ export interface SweepRange {
   readonly from: number | string;
   readonly to: number | string;
   readonly snapId: string;
+  readonly snapDir: string;
   readonly fingerprint: string;
 }
 
@@ -91,6 +94,7 @@ export interface SweepRecovery {
 interface StylesElement {
   readonly id?: string;
   readonly selector?: string;
+  readonly backendNodeId?: number | null;
   readonly computed?: Record<string, string | null>;
   readonly winningDeclarations?: readonly {
     readonly property?: string;
@@ -194,15 +198,26 @@ function sourceFor(declaration: SweepDeclaration): SweepChange['provenance'] | u
   return { selector: declaration.selector ?? undefined, specificity: declaration.specificity ?? undefined, source };
 }
 
+/** A cross-snapshot element key must survive an inserted/removed sibling; collector-local s-<index> ids do not. */
+function snapshotElementKey(element: StylesElement): string | null {
+  if (typeof element.backendNodeId === 'number') return `backend:${element.backendNodeId}`;
+  if (element.selector) return `selector:${element.selector}`;
+  return element.id && !/^s-\d+$/.test(element.id) ? `id:${element.id}` : null;
+}
+
 /** Extracts changed computed values and the winning declaration for the new value, when captured. */
 export function changesBetweenSnapshots(beforeDir: string, afterDir: string): SweepChange[] {
   const before = readJson<StylesReport>(path.join(beforeDir, 'styles.json'));
   const after = readJson<StylesReport>(path.join(afterDir, 'styles.json'));
   if (!before?.elements || !after?.elements) return [];
-  const prior = new Map(before.elements.map((element) => [element.id ?? element.selector ?? '', element]));
+  const prior = new Map(before.elements.flatMap((element) => {
+    const key = snapshotElementKey(element);
+    return key === null ? [] : [[key, element] as const];
+  }));
   const changes: SweepChange[] = [];
   for (const next of after.elements) {
-    const key = next.id ?? next.selector ?? '';
+    const key = snapshotElementKey(next);
+    if (key === null) continue;
     const old = prior.get(key);
     if (!old) continue;
     const properties = new Set([...Object.keys(old.computed ?? {}), ...Object.keys(next.computed ?? {})]);
@@ -218,17 +233,19 @@ export function changesBetweenSnapshots(beforeDir: string, afterDir: string): Sw
 }
 
 /** Builds adjacent observed changes and matching-fingerprint spans; neither denotes unobserved values as stable. */
-export function analyzeSweepSamples(axis: SweepAxis, _from: number | string, _to: number | string, samples: readonly SweepSample[]): Pick<SweepArtifact, 'transitions' | 'ranges'> {
+export function analyzeSweepSamples(axis: SweepAxis, _from: number | string, _to: number | string, samples: readonly SweepSample[], uncertainties: readonly SweepUncertainty[] = []): Pick<SweepArtifact, 'transitions' | 'ranges'> {
   const transitions: SweepTransition[] = [];
   const ranges: SweepRange[] = [];
   for (let i = 1; i < samples.length; i += 1) {
     const previous = samples[i - 1];
     const current = samples[i];
     if (previous.fingerprint === current.fingerprint) {
-      ranges.push({ from: previous.value, to: current.value, snapId: previous.snapId, fingerprint: previous.fingerprint });
+      ranges.push({ from: previous.value, to: current.value, snapId: previous.snapId, snapDir: previous.snapDir, fingerprint: previous.fingerprint });
       continue;
     }
-    transitions.push({ bracket: { from: previous.value, to: current.value }, before: previous.snapId, after: current.snapId, changes: changesBetweenSnapshots(previous.snapDir, current.snapDir) });
+    const samplingLimited = typeof previous.value === 'number' && typeof current.value === 'number'
+      && uncertainties.some((interval) => interval.reason === 'sampling_limit' && interval.from === previous.value && interval.to === current.value);
+    transitions.push({ bracket: { from: previous.value, to: current.value }, before: previous.snapId, after: current.snapId, changes: changesBetweenSnapshots(previous.snapDir, current.snapDir), ...(samplingLimited ? { uncertainty: 'sampling_limit' as const } : {}) });
   }
   return { transitions, ranges };
 }
@@ -256,7 +273,13 @@ export async function refineNumericSweep(samples: readonly SweepSample[], tolera
       continue;
     }
     if (!byValue.has(middle)) byValue.set(middle, await capture(middle));
-    pending.push({ from, to: middle }, { from: middle, to });
+    const midpoint = byValue.get(middle)!;
+    const left = byValue.get(from)!;
+    const right = byValue.get(to)!;
+    // One midpoint observes an otherwise-unsampled interval; only a changed
+    // fingerprint can justify spending more samples narrowing that half.
+    if (left.fingerprint !== midpoint.fingerprint) pending.push({ from, to: middle });
+    if (midpoint.fingerprint !== right.fingerprint) pending.push({ from: middle, to });
   }
   return { samples: [...byValue.values()].sort((a, b) => Number(a.value) - Number(b.value)), uncertainties };
 }

package/src/cdp/measure/text.ts

@@ -0,0 +1,227 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PNG } from 'pngjs';
+
+import { getActiveSession } from '../../session-context.js';
+import { createOneshotSession } from '../../session/commands.js';
+import { writeBinaryPrivate } from '../../session/artifacts.js';
+import { artifactPath, readGeometry, readMeta, readQueries, readStyles, readText, type SnapRef } from '../../output/artifact.js';
+import { explainSnapshot, type ExplainAmbiguousSelector, type ExplainMissingSelector } from './explain.js';
+import { measureElementContrast } from './check.js';
+
+interface TextRecord {
+  readonly id?: string;
+  readonly geometryId?: string;
+  readonly backendNodeId?: number | null;
+  readonly selector?: string;
+  readonly text?: string;
+  readonly textLength?: number;
+  readonly lineCount?: number;
+  readonly truncated?: boolean;
+  readonly truncationStyle?: string;
+  readonly scrollWidth?: number;
+  readonly clientWidth?: number;
+  readonly writingMode?: string;
+  readonly direction?: string;
+  readonly fallbackUsed?: boolean;
+  readonly font?: { readonly family?: string; readonly size?: string; readonly weight?: string; readonly lineHeight?: string };
+  readonly platformFontsAvailable?: boolean;
+  readonly platformFonts?: readonly { readonly familyName?: string }[];
+  readonly lines?: readonly { readonly index?: number; readonly rect?: { readonly x?: number; readonly y?: number; readonly width?: number; readonly height?: number; readonly w?: number; readonly h?: number }; readonly baseline?: number; readonly baselineApproximate?: boolean; readonly wrapAfterChar?: number; readonly wrapAfterCharUnavailable?: boolean }[];
+}
+
+interface StyleRecord {
+  readonly id?: string;
+  readonly geometryId?: string;
+  readonly backendNodeId?: number | null;
+  readonly selector?: string;
+  readonly provenanceUnavailable?: boolean;
+  readonly winningDeclarations?: readonly { readonly property?: string; readonly value?: string | null; readonly selector?: string | null; readonly specificity?: string | null; readonly important?: boolean; readonly authored?: { readonly file?: string; readonly line?: number; readonly column?: number }; readonly generated?: { readonly sourceURL?: string; readonly line?: number; readonly column?: number }; readonly sourceStyleSheetUrl?: string; readonly winnerApproximate?: boolean; readonly winnerApproximateReason?: string }[];
+}
+
+interface GeometryRecord {
+  readonly id: string;
+  readonly selector?: string;
+  readonly backendNodeId?: number | null;
+  readonly domPath?: string;
+}
+
+interface TextArtifact {
+  readonly elements?: TextRecord[];
+  readonly available?: boolean;
+  readonly unavailableReason?: string;
+}
+
+interface QueriesArtifact {
+  readonly available?: boolean;
+  readonly unavailableReason?: string;
+  readonly environment?: { readonly width?: number; readonly height?: number };
+}
+
+export interface TextStyleProvenance {
+  readonly element: string;
+  readonly property: string;
+  readonly value: string;
+  readonly selector: string;
+  readonly specificity: string;
+  readonly source: string;
+  readonly uncertainty?: string;
+}
+
+interface TextStyleProvenanceReport {
+  readonly styles: readonly TextStyleProvenance[];
+  readonly unavailableFor: readonly string[];
+}
+
+export interface TextCrop {
+  readonly path: string;
+  readonly requested: { readonly x: number; readonly y: number; readonly w: number; readonly h: number };
+  readonly delivered: { readonly x: number; readonly y: number; readonly w: number; readonly h: number };
+  readonly scale: { readonly x: number; readonly y: number };
+}
+
+export interface TextMeasurement {
+  readonly kind: 'measurement';
+  readonly ref: SnapRef;
+  readonly selector: string;
+  readonly matchCount: number;
+  readonly element: { readonly id: string; readonly selector?: string; readonly backendNodeId?: number | null; readonly rect?: { readonly x: number; readonly y: number; readonly width?: number; readonly height?: number } | null };
+  readonly text?: TextRecord;
+  readonly textAvailable: boolean;
+  readonly textUnavailableReason?: string;
+  readonly contrast: ReturnType<typeof measureElementContrast>;
+  readonly styles: readonly TextStyleProvenance[];
+  readonly styleProvenanceUnavailableFor: readonly string[];
+  readonly meta: { readonly settled?: boolean; readonly settleMs?: number; readonly viewport?: string | null };
+}
+
+export type TextSnapshotResult = TextMeasurement | ExplainMissingSelector | ExplainAmbiguousSelector;
+
+function sameTarget(record: { backendNodeId?: number | null; id?: string; geometryId?: string }, element: { backendNodeId?: number | null; id: string }): boolean {
+  return (typeof element.backendNodeId === 'number' && record.backendNodeId === element.backendNodeId) || record.id === element.id || record.geometryId === element.id;
+}
+
+function sourceOf(declaration: NonNullable<StyleRecord['winningDeclarations']>[number]): string {
+  if (declaration.authored?.file) return `${declaration.authored.file}:${declaration.authored.line ?? 0}:${declaration.authored.column ?? 0} (authored)`;
+  if (declaration.generated?.sourceURL) return `${declaration.generated.sourceURL}:${declaration.generated.line ?? 0}:${declaration.generated.column ?? 0} (generated)`;
+  if (declaration.sourceStyleSheetUrl) return `${declaration.sourceStyleSheetUrl} (generated source)`;
+  return 'selector-only provenance';
+}
+
+function parentPath(domPath: string | undefined): string | undefined {
+  if (domPath === undefined) return undefined;
+  const index = domPath.lastIndexOf('/');
+  return index < 0 ? '' : domPath.slice(0, index);
+}
+
+function elementLabel(element: { id: string; selector?: string }): string {
+  return element.selector ?? element.id;
+}
+
+function styleProvenance(ref: SnapRef, element: GeometryRecord, contrast: ReturnType<typeof measureElementContrast>): TextStyleProvenanceReport {
+  const records = readStyles<{ elements?: StyleRecord[] }>(ref).elements ?? [];
+  const geometry = readGeometry<{ elements?: GeometryRecord[] }>(ref).elements ?? [];
+  const byPath = new Map(geometry.filter((candidate) => candidate.domPath !== undefined).map((candidate) => [candidate.domPath!, candidate]));
+  const backgroundElements: GeometryRecord[] = [];
+  let candidate: GeometryRecord | undefined = element;
+  while (candidate) {
+    backgroundElements.push(candidate);
+    if (contrast.available && candidate.id === contrast.backgroundSourceElementId) break;
+    candidate = byPath.get(parentPath(candidate.domPath) ?? '');
+  }
+  const targets = new Map<string, { element: GeometryRecord; properties: ReadonlySet<string> }>();
+  targets.set(element.id, { element, properties: new Set(['color', 'background-color', 'backgroundColor']) });
+  for (const ancestor of backgroundElements) {
+    const existing = targets.get(ancestor.id);
+    targets.set(ancestor.id, { element: ancestor, properties: existing ? new Set([...existing.properties, 'background-color', 'backgroundColor']) : new Set(['background-color', 'backgroundColor']) });
+  }
+  const styles: TextStyleProvenance[] = [];
+  const unavailableFor: string[] = [];
+  for (const { element: target, properties } of targets.values()) {
+    const record = records.find((candidate) => sameTarget(candidate, target));
+    if (!record || record.provenanceUnavailable) {
+      unavailableFor.push(elementLabel(target));
+      continue;
+    }
+    for (const declaration of record.winningDeclarations ?? []) {
+      if (!declaration.property || !properties.has(declaration.property)) continue;
+      styles.push({
+        element: elementLabel(target),
+        property: declaration.property,
+        value: declaration.value ?? '(no computed value)',
+        selector: declaration.selector ?? '(no author declaration)',
+        specificity: declaration.specificity ?? (declaration.selector === 'inline' ? 'inline' : 'none'),
+        source: sourceOf(declaration),
+        ...(declaration.winnerApproximate ? { uncertainty: declaration.winnerApproximateReason ?? 'simplified cascade model' } : {}),
+      });
+    }
+  }
+  return { styles, unavailableFor };
+}
+
+/** Reads one target's recorded text, font, color, and cascade facts without driving a browser. */
+export function measureTextSnapshot(ref: SnapRef, selector: string): TextSnapshotResult {
+  const textArtifact = readText<TextArtifact>(ref);
+  if (textArtifact.available === false && selector.startsWith('text:')) throw new Error(`text collection is unavailable${textArtifact.unavailableReason ? `: ${textArtifact.unavailableReason}` : ''}; cannot resolve a text: selector`);
+  const selection = explainSnapshot(ref, selector, { text: true });
+  if (selection.kind !== 'explanation') return selection;
+  const element = selection.element;
+  const textAvailable = textArtifact.available !== false;
+  const text = textAvailable ? (textArtifact.elements ?? []).find((record) => sameTarget(record, element)) : undefined;
+  const contrast = measureElementContrast(ref, element.id);
+  const provenance = styleProvenance(ref, element, contrast);
+  return {
+    kind: 'measurement',
+    ref,
+    selector,
+    matchCount: selection.matchCount,
+    element,
+    text,
+    textAvailable,
+    ...(textArtifact.available === false ? { textUnavailableReason: textArtifact.unavailableReason ?? 'no reason was recorded' } : {}),
+    contrast,
+    styles: provenance.styles,
+    styleProvenanceUnavailableFor: provenance.unavailableFor,
+    meta: { ...selection.meta, viewport: readMeta<{ viewport?: string | null }>(ref).viewport },
+  };
+}
+
+function capturedCssViewport(ref: SnapRef): { width: number; height: number } {
+  const queries = readQueries<QueriesArtifact>(ref);
+  if (queries.available === false) throw new Error(`the snapshot query environment is unavailable${queries.unavailableReason ? `: ${queries.unavailableReason}` : ''}; cannot map CSS geometry to screenshot pixels`);
+  const width = queries.environment?.width;
+  const height = queries.environment?.height;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width! <= 0 || height! <= 0) throw new Error('the snapshot has no positive recorded CSS viewport in queries.json; cannot map CSS geometry to screenshot pixels');
+  return { width: width!, height: height! };
+}
+
+/** Writes a crop into the active session or a fresh measure one-shot bundle, never into the source snapshot. */
+export function writeTextCrop(measurement: TextMeasurement, artifactDir?: string): TextCrop {
+  const rect = measurement.element.rect;
+  const width = rect?.width;
+  const height = rect?.height;
+  if (!rect || !Number.isFinite(rect.x) || !Number.isFinite(rect.y) || !Number.isFinite(width) || !Number.isFinite(height) || width! <= 0 || height! <= 0) throw new Error('the selected element has no positive recorded geometry for a crop');
+  const source = PNG.sync.read(fs.readFileSync(artifactPath(measurement.ref, 'screenshot.png')));
+  const capturedViewport = capturedCssViewport(measurement.ref);
+  const scaleX = source.width / capturedViewport.width;
+  const scaleY = source.height / capturedViewport.height;
+  const requested = { x: rect.x, y: rect.y, w: width!, h: height! };
+  const x = Math.max(0, Math.floor(requested.x * scaleX));
+  const y = Math.max(0, Math.floor(requested.y * scaleY));
+  const right = Math.min(source.width, Math.ceil((requested.x + requested.w) * scaleX));
+  const bottom = Math.min(source.height, Math.ceil((requested.y + requested.h) * scaleY));
+  if (right <= x || bottom <= y) throw new Error('the selected element has no recorded intersection with screenshot.png');
+  const crop = new PNG({ width: right - x, height: bottom - y });
+  PNG.bitblt(source, crop, x, y, crop.width, crop.height, 0, 0);
+  const active = getActiveSession();
+  const root = active?.dir ?? createOneshotSession('measure', artifactDir).dir;
+  const filename = `text-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.png`;
+  const output = path.join(root, 'measure', 'text', filename);
+  writeBinaryPrivate(output, PNG.sync.write(crop));
+  return {
+    path: output,
+    requested,
+    delivered: { x, y, w: crop.width, h: crop.height },
+    scale: { x: scaleX, y: scaleY },
+  };
+}