@crouton-kit/capture 1.3.7 → 1.3.9

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

@@ -0,0 +1,188 @@
+import {
+  annotateUnstableFacts,
+  readFocus,
+  readGeometry,
+  readMeta,
+  unstableRegionsFor,
+  type Rect,
+  type SnapRef,
+} from '../../output/artifact.js';
+import {
+  data,
+  fact,
+  formatCoordinate,
+  line,
+  lineList,
+  text,
+  type FactLine,
+  type RenderableResult,
+} from '../../output/render.js';
+
+interface FocusRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly w?: number;
+  readonly h?: number;
+}
+
+interface FocusStop {
+  readonly step?: number;
+  readonly id?: string | null;
+  readonly backendNodeId?: number | null;
+  readonly selector?: string | null;
+  readonly role?: string | null;
+  readonly name?: string | null;
+  readonly rect?: FocusRect | null;
+  readonly scrollBefore?: { readonly x?: number; readonly y?: number };
+  readonly scrollAfter?: { readonly x?: number; readonly y?: number };
+  readonly scrollJump?: boolean;
+  readonly focusVisibleStyle?: { readonly outline?: string | null; readonly boxShadow?: string | null } | null;
+}
+
+interface UnreachedFocusable {
+  readonly id?: string;
+  readonly backendNodeId?: number | null;
+  readonly selector?: string | null;
+  readonly rect?: FocusRect | null;
+  readonly visible?: boolean;
+}
+
+interface FocusArtifact {
+  readonly available?: boolean;
+  readonly unavailableReason?: string;
+  readonly forward?: readonly FocusStop[];
+  readonly forwardTruncated?: boolean;
+  readonly reverse?: readonly FocusStop[];
+  readonly reverseTruncated?: boolean;
+  readonly unreachedFocusable?: readonly UnreachedFocusable[];
+  readonly clickableUnfocusable?: readonly UnreachedFocusable[];
+  readonly candidateCount?: number;
+  readonly scope?: { readonly root?: string; readonly shadowDom?: string; readonly iframesPresent?: number; readonly shadowHostsPresent?: number };
+}
+
+interface SnapshotMeta {
+  readonly settled?: boolean;
+  readonly settleMs?: number;
+}
+
+interface FocusFact {
+  readonly elementId?: string;
+  readonly rect?: Rect;
+}
+
+function rectOf(rect: FocusRect | null | undefined): Rect | undefined {
+  if (!rect || !Number.isFinite(rect.x) || !Number.isFinite(rect.y)) return undefined;
+  const w = rect.w ?? rect.width;
+  const h = rect.h ?? rect.height;
+  if (!Number.isFinite(w) || !Number.isFinite(h)) return undefined;
+  return { x: rect.x, y: rect.y, w, h };
+}
+
+function identity(stop: FocusStop | UnreachedFocusable, geometryIdsByBackendNode: ReadonlyMap<number, string>): string | undefined {
+  if (typeof stop.backendNodeId === 'number') return geometryIdsByBackendNode.get(stop.backendNodeId) ?? String(stop.backendNodeId);
+  return typeof stop.id === 'string' ? stop.id : undefined;
+}
+
+function caveatSuffix(caveats: ReturnType<typeof annotateUnstableFacts<FocusFact>>[number]['caveats']): FactLine | undefined {
+  if (caveats.length === 0) return undefined;
+  return line(
+    text` · nondeterminism caveat: `,
+    data(caveats.map((c) => c.selector ?? c.regionId).join(', ')),
+    text` is an unstable captured region`,
+  );
+}
+
+function stopLine(direction: 'forward' | 'reverse', stop: FocusStop, caveats: ReturnType<typeof annotateUnstableFacts<FocusFact>>[number]['caveats']): FactLine {
+  const parts: FactLine[] = [
+    fact`${direction} step ${stop.step ?? 0}: `,
+    text`selector=`, data(stop.selector ?? '(unresolved)'),
+  ];
+  if (stop.role !== null && stop.role !== undefined) parts.push(line(text` role=`, data(stop.role)));
+  if (stop.name !== null && stop.name !== undefined) parts.push(line(text` name=`, data(stop.name)));
+  const rect = rectOf(stop.rect);
+  if (rect) parts.push(line(text` rect `, formatCoordinate(rect)));
+  if (stop.scrollBefore && stop.scrollAfter) {
+    parts.push(fact` scroll x=${stop.scrollBefore.x ?? 0},y=${stop.scrollBefore.y ?? 0} → x=${stop.scrollAfter.x ?? 0},y=${stop.scrollAfter.y ?? 0}`);
+  }
+  if (stop.scrollJump) parts.push(text` scroll-jump=true`);
+  if (stop.focusVisibleStyle) {
+    parts.push(line(text` focus-visible outline=`, data(stop.focusVisibleStyle.outline ?? '(unavailable)')));
+    if (stop.focusVisibleStyle.boxShadow) parts.push(line(text` box-shadow=`, data(stop.focusVisibleStyle.boxShadow)));
+  }
+  const caveat = caveatSuffix(caveats);
+  if (caveat) parts.push(caveat);
+  return line(...parts);
+}
+
+function unreachedLine(item: UnreachedFocusable, caveats: ReturnType<typeof annotateUnstableFacts<FocusFact>>[number]['caveats']): FactLine {
+  const parts: FactLine[] = [text`unreached focusable: selector=`, data(item.selector ?? '(unresolved)')];
+  const rect = rectOf(item.rect);
+  if (rect) parts.push(line(text` rect `, formatCoordinate(rect)));
+  if (item.visible !== undefined) parts.push(fact` visible=${String(item.visible)}`);
+  const caveat = caveatSuffix(caveats);
+  if (caveat) parts.push(caveat);
+  return line(...parts);
+}
+
+/** Builds the read-only `measure map focus` report from an existing snapshot. */
+export function mapFocus(ref: SnapRef): RenderableResult {
+  const focus = readFocus<FocusArtifact>(ref);
+  const meta = readMeta<SnapshotMeta>(ref);
+  const regions = unstableRegionsFor(ref);
+  const geometry = readGeometry<{ elements?: Array<{ id?: string; backendNodeId?: number }> }>(ref);
+  const geometryIdsByBackendNode = new Map<number, string>();
+  for (const element of geometry.elements ?? []) {
+    if (typeof element.backendNodeId === 'number' && typeof element.id === 'string') {
+      geometryIdsByBackendNode.set(element.backendNodeId, element.id);
+    }
+  }
+  const forward = focus.forward ?? [];
+  const reverse = focus.reverse ?? [];
+  const unreached = focus.unreachedFocusable ?? [];
+
+  const annotate = <T extends FocusStop | UnreachedFocusable>(items: readonly T[]) => annotateUnstableFacts<FocusFact>(
+    items.map((item) => ({ elementId: identity(item, geometryIdsByBackendNode), rect: rectOf(item.rect) })),
+    regions,
+  );
+  const annotatedForward = annotate(forward);
+  const annotatedReverse = annotate(reverse);
+  const annotatedUnreached = annotate(unreached);
+
+  const sections: FactLine[] = [];
+  if (focus.available === false) {
+    sections.push(fact`Focus traversal was unavailable during snapshot capture: ${focus.unavailableReason ?? 'capture did not return a completed traversal'}.`);
+  } else {
+    sections.push(lineList(annotatedForward.map((entry, index) => stopLine('forward', forward[index]!, entry.caveats))));
+    sections.push(lineList(annotatedReverse.map((entry, index) => stopLine('reverse', reverse[index]!, entry.caveats))));
+    if (focus.forwardTruncated || focus.reverseTruncated) {
+      sections.push(fact`Traversal recording cap reached: forward=${String(Boolean(focus.forwardTruncated))}, reverse=${String(Boolean(focus.reverseTruncated))}.`);
+    }
+  }
+  if (annotatedUnreached.length) sections.push(lineList(annotatedUnreached.map((entry, index) => unreachedLine(unreached[index]!, entry.caveats))));
+  if (focus.scope) {
+    sections.push(fact`Traversal scope: root=${focus.scope.root ?? 'unavailable'}, shadow-dom=${focus.scope.shadowDom ?? 'unavailable'}, iframes-present=${focus.scope.iframesPresent ?? 0}, shadow-hosts-present=${focus.scope.shadowHostsPresent ?? 0}.`);
+  }
+
+  return {
+    tag: 'focus-map',
+    attestation: {
+      kind: 'snapshot',
+      id: ref.id,
+      path: ref.dir,
+      note: meta.settled === false
+        ? text`Snapshot was captured with unsettled regions; only facts intersecting those regions carry nondeterminism caveats.`
+        : fact`Snapshot settled${meta.settleMs === undefined ? '' : ` after ${meta.settleMs}ms`}.`,
+    },
+    attrs: {
+      forward: forward.length,
+      reverse: reverse.length,
+      'unreached-focusable': unreached.length,
+      settled: meta.settled ?? false,
+    },
+    summary: fact`Keyboard traversal facts: ${forward.length} forward stop(s), ${reverse.length} reverse stop(s), and ${unreached.length} unreached focusable element(s) from ${focus.candidateCount ?? 0} captured candidate(s).`,
+    sections,
+    followUp: fact`Read another snapshot map with \`capture measure map scroll ${ref.id}\` or \`capture measure map layers ${ref.id}\`.`,
+  };
+}

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

@@ -0,0 +1,177 @@
+import type { LayerRecord, LayersReport } from './collectors/layers.js';
+import type { SnapMeta } from '../../session/artifacts.js';
+import {
+  annotateUnstableFacts,
+  readGeometry,
+  readLayers,
+  readMeta,
+  unstableRegionsFor,
+  type Rect,
+  type SnapRef,
+  type UnstableCaveat,
+} from '../../output/artifact.js';
+import {
+  data,
+  fact,
+  formatCoordinate,
+  formatProvenance,
+  line,
+  lineList,
+  text,
+  type FactLine,
+  type RenderableResult,
+} from '../../output/render.js';
+
+interface LayerFact {
+  readonly layer: LayerRecord;
+  readonly rect: Rect;
+}
+
+function sourceFor(layer: LayerRecord): string | undefined {
+  const provenance = layer.styleProvenance;
+  if (!provenance) return undefined;
+  if (provenance.authored) {
+    return `${provenance.authored.file}:${provenance.authored.line}:${provenance.authored.column}`;
+  }
+  if (provenance.generated) {
+    return `${provenance.generated.sourceURL}:${provenance.generated.line}:${provenance.generated.column}`;
+  }
+  return provenance.sourceStyleSheetUrl;
+}
+
+function caveatLine(caveats: readonly UnstableCaveat[]): FactLine | undefined {
+  if (!caveats.length) return undefined;
+  return lineList(caveats.map((caveat) => fact`nondeterminism caveat: unstable region ${caveat.regionId}${caveat.selector ? ` (${caveat.selector})` : ''}${caveat.reason ? ` — ${caveat.reason}` : ''}`));
+}
+
+function uniqueCaveats(caveats: readonly UnstableCaveat[]): UnstableCaveat[] {
+  const seen = new Set<string>();
+  return caveats.filter((caveat) => {
+    const key = `${caveat.regionId}\u0000${caveat.selector ?? ''}\u0000${caveat.reason ?? ''}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function formatLayer(layer: LayerRecord, membershipAvailable: boolean, caveats: readonly UnstableCaveat[]): FactLine {
+  const details: FactLine[] = [
+    line(
+      text`Layer `,
+      data(layer.id),
+      text` — `,
+      formatCoordinate({ x: layer.bounds.x, y: layer.bounds.y, w: layer.bounds.width, h: layer.bounds.height }),
+      text`; LayerTree delivery index `,
+      data(layer.layerPaintOrder),
+      text`; draws content `,
+      data(layer.drawsContentUnavailable ? 'unavailable' : String(layer.drawsContent)),
+      text`; paint count `,
+      data(layer.paintCountUnavailable ? 'unavailable' : layer.paintCount),
+    ),
+  ];
+  if (layer.backendNodeId !== null) details.push(fact`owner backend node ${layer.backendNodeId}${layer.selector ? ` (${layer.selector})` : ''}`);
+  if (layer.parentLayerId) details.push(fact`parent layer ${layer.parentLayerId}`);
+  if (layer.compositingReasonsUnavailable) details.push(text`Compositing reasons were unavailable for this layer.`);
+  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)'}.`);
+  if (layer.styleProvenance) {
+    const provenance = layer.styleProvenance;
+    details.push(line(
+      text`Layer-affecting property `,
+      data(provenance.property),
+      text`: `,
+      formatProvenance({
+        selector: provenance.selector ?? '(no selector)',
+        source: sourceFor(layer),
+        specificity: provenance.specificity ?? undefined,
+        extra: provenance.value === null ? text`computed value unavailable` : fact`computed value ${provenance.value}`,
+      }),
+    ));
+    if (provenance.winnerApproximate) details.push(fact`Winning-declaration ordering is approximate${provenance.winnerApproximateReason ? `: ${provenance.winnerApproximateReason}` : ''}.`);
+    if (provenance.sourceResolutionUnavailable) details.push(fact`Source provenance resolution was unavailable${provenance.sourceResolutionUnavailableReason ? `: ${provenance.sourceResolutionUnavailableReason}` : ''}.`);
+  } else if (layer.styleProvenanceUnavailable) {
+    details.push(text`Layer-affecting declaration provenance was unavailable for this layer.`);
+  } else {
+    details.push(text`No author-declared layer-affecting property was recorded for this layer.`);
+  }
+  const caveat = caveatLine(caveats);
+  if (caveat) details.push(caveat);
+  return lineList(details);
+}
+
+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 caveat = caveatLine(caveats);
+  return caveat ? lineList([base, caveat]) : base;
+}
+
+export function buildMeasureMapLayersResult(ref: SnapRef): RenderableResult {
+  const report = readLayers<LayersReport>(ref);
+  const meta = readMeta<SnapMeta>(ref);
+  const regions = unstableRegionsFor(ref);
+  const geometry = readGeometry<{ elements?: Array<{ id?: string; backendNodeId?: number; rect?: Rect }> }>(ref);
+  const geometryByBackendNodeId = new Map<number, { id?: string; rect?: Rect }>();
+  for (const element of geometry.elements ?? []) {
+    if (typeof element.backendNodeId === 'number') geometryByBackendNodeId.set(element.backendNodeId, element);
+  }
+  const caveatsForBackendNodeIds = (ids: readonly number[]): UnstableCaveat[] => uniqueCaveats(
+    annotateUnstableFacts(ids.map((id) => {
+      const element = geometryByBackendNodeId.get(id);
+      return { elementId: element?.id, rect: element?.rect };
+    }), regions).flatMap(({ caveats }) => caveats),
+  );
+  const layerFacts: LayerFact[] = report.layers.map((layer) => ({
+    layer,
+    rect: { x: layer.bounds.x, y: layer.bounds.y, w: layer.bounds.width, h: layer.bounds.height },
+  }));
+  const annotated = annotateUnstableFacts(layerFacts, regions).map(({ fact: layerFact, caveats }) => ({
+    layerFact,
+    caveats: uniqueCaveats([...caveats, ...caveatsForBackendNodeIds(layerFact.layer.memberBackendNodeIds)]),
+  }));
+  const paintOrderCaveats = caveatsForBackendNodeIds(report.paintOrder.backendNodeIds);
+  const layerTreeStatus = report.layerTree.available ? 'available' : 'unavailable';
+  const paintOrderStatus = report.paintOrder.available ? 'available' : 'unavailable';
+  const membershipStatus = report.membership.available ? 'available' : 'unavailable';
+  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 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) {
+    sections.push(fact`Per-node layer membership available; ${report.membership.unassignedCount} painted node(s) had no layer assignment.`);
+  } else {
+    sections.push(fact`Per-node layer membership unavailable${report.membership.reason ? `: ${report.membership.reason}` : ''}.`);
+  }
+  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)));
+
+  return {
+    tag: 'layer-map',
+    attestation: {
+      kind: 'snapshot',
+      id: ref.id,
+      path: ref.dir,
+      note: meta.settled
+        ? text`Snapshot was settled before its layer facts were captured.`
+        : fact`Snapshot was captured unsettled; layer facts carry per-region nondeterminism caveats where their bounds overlap marked unstable regions.`,
+    },
+    attrs: {
+      layers: report.layers.length,
+      'layer-tree': layerTreeStatus,
+      'paint-order': paintOrderStatus,
+      membership: membershipStatus,
+      settled: meta.settled,
+    },
+    summary: text`Paint/compositor layer facts, DOMSnapshot paint order, node membership, and available layer-style provenance are reported from layers.json.`,
+    sections,
+    followUp: fact`Inspect an element's cascade and stacking facts with \`capture measure explain ${ref.id} --selector <selector>\`.`,
+  };
+}

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

@@ -0,0 +1,317 @@
+import {
+  readGeometry,
+  readMeta,
+  readScroll,
+  unstableRegionsFor,
+  annotateUnstableFacts,
+  type Rect,
+  type SnapRef,
+  type UnstableCaveat,
+  type UnstableRegion,
+} from '../../output/artifact.js';
+import { data, fact, line, lineList, text, type FactLine, type RenderableResult } from '../../output/render.js';
+
+interface RectLike {
+  readonly x?: unknown;
+  readonly y?: unknown;
+  readonly width?: unknown;
+  readonly height?: unknown;
+  readonly w?: unknown;
+  readonly h?: unknown;
+}
+
+interface ScrollChild {
+  readonly id?: unknown;
+  readonly backendNodeId?: unknown;
+  readonly selector?: unknown;
+  readonly position?: unknown;
+  readonly scrollSnapAlign?: unknown;
+  readonly rect?: RectLike | null;
+  readonly nestedAncestryUnavailable?: unknown;
+}
+
+interface ScrollSample {
+  readonly offsetTop?: unknown;
+  readonly visibleChildren?: readonly ScrollChild[];
+  readonly visibleChildrenTruncated?: unknown;
+}
+
+interface ScrollContainer extends ScrollChild {
+  readonly isRoot?: unknown;
+  readonly scrollWidth?: unknown;
+  readonly scrollHeight?: unknown;
+  readonly clientWidth?: unknown;
+  readonly clientHeight?: unknown;
+  readonly scrollTop?: unknown;
+  readonly scrollLeft?: unknown;
+  readonly maxScrollTop?: unknown;
+  readonly maxScrollLeft?: unknown;
+  readonly overflowX?: unknown;
+  readonly overflowY?: unknown;
+  readonly scrollbarGutter?: unknown;
+  readonly scrollSnapType?: unknown;
+  readonly snapDescendants?: readonly ScrollChild[];
+  readonly snapDescendantsTruncated?: unknown;
+  readonly stickyFixedDescendants?: readonly ScrollChild[];
+  readonly stickyFixedDescendantsTruncated?: unknown;
+  readonly samples?: readonly ScrollSample[];
+  readonly nestedAncestry?: readonly unknown[];
+}
+
+interface ScrollArtifact {
+  readonly available?: unknown;
+  readonly reason?: unknown;
+  readonly containers?: readonly ScrollContainer[];
+  readonly scrollContainersTotal?: unknown;
+  readonly scrollContainersTruncated?: unknown;
+  readonly scrollContainersCountUnavailable?: unknown;
+  readonly documentScrollHeight?: unknown;
+  readonly documentScrollWidth?: unknown;
+  readonly visualViewport?: unknown;
+  readonly visualViewportUnavailable?: unknown;
+  readonly layoutViewport?: unknown;
+  readonly layoutViewportUnavailable?: unknown;
+  readonly scope?: { readonly root?: unknown; readonly shadowDom?: unknown; readonly iframesPresent?: unknown; readonly shadowHostsPresent?: unknown };
+  readonly scopeCountsUnavailable?: unknown;
+}
+
+interface SnapMeta {
+  readonly settled?: unknown;
+  readonly viewport?: unknown;
+}
+
+interface GeometryElement {
+  readonly id?: unknown;
+  readonly backendNodeId?: unknown;
+  readonly rect?: RectLike | null;
+}
+
+interface CaveatContext {
+  readonly regions: readonly UnstableRegion[];
+  readonly geometryByBackendNodeId: ReadonlyMap<number, { readonly id?: string; readonly rect?: Rect }>;
+}
+
+function numeric(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function numberText(value: unknown): FactLine {
+  const n = numeric(value);
+  return n === undefined ? text`unavailable` : data(n);
+}
+
+function string(value: unknown, fallback = '(unavailable)'): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function rect(value: RectLike | null | undefined): Rect | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const x = numeric(value.x);
+  const y = numeric(value.y);
+  const w = numeric(value.w ?? value.width);
+  const h = numeric(value.h ?? value.height);
+  if (x === undefined || y === undefined || w === undefined || h === undefined) return undefined;
+  return { x, y, w, h };
+}
+
+function formatRect(value: RectLike | null | undefined): FactLine {
+  const measured = rect(value);
+  return measured
+    ? fact`x=${measured.x} y=${measured.y} w=${measured.w} h=${measured.h}`
+    : text`rect unavailable`;
+}
+
+function formatDimension(width: unknown, height: unknown): FactLine {
+  return line(numberText(width), text`×`, numberText(height));
+}
+
+function viewportFacts(label: string, value: unknown, unavailable: unknown): FactLine {
+  if (unavailable === true) return fact`${label}: viewport metrics unavailable in Page.getLayoutMetrics.`;
+  if (!value || typeof value !== 'object') return fact`${label}: unavailable`;
+  const viewport = value as Record<string, unknown>;
+  return line(
+    data(label),
+    text`: client `,
+    formatDimension(viewport.clientWidth, viewport.clientHeight),
+    text` at page x=`,
+    numberText(viewport.pageX),
+    text` y=`,
+    numberText(viewport.pageY),
+    text` scale=`,
+    numberText(viewport.scale),
+  );
+}
+
+function backendNodeId(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function explicitElementId(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Keeps only producer-supplied region identities. Settle's descriptive
+ * `tag#id.classes` labels cannot safely be reconciled with geometry paths:
+ * ids may contain punctuation and geometry intentionally caps class lists.
+ * A selector-only legacy region therefore remains unjoined rather than
+ * attributing its caveat to a potentially different measured element.
+ */
+function resolveRegions(regions: readonly UnstableRegion[]): readonly UnstableRegion[] {
+  return regions;
+}
+
+function uniqueCaveats(caveats: readonly UnstableCaveat[]): UnstableCaveat[] {
+  const seen = new Set<string>();
+  return caveats.filter((caveat) => {
+    const key = `${caveat.regionId}\u0000${caveat.selector ?? ''}\u0000${caveat.reason ?? ''}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function caveatsFor(target: ScrollChild, context: CaveatContext): readonly UnstableCaveat[] {
+  const backend = backendNodeId(target.backendNodeId);
+  const geometry = backend === undefined ? undefined : context.geometryByBackendNodeId.get(backend);
+  const ownRect = rect(target.rect) ?? geometry?.rect;
+  const elementIds = [
+    explicitElementId(target.id),
+    geometry?.id,
+    backend === undefined ? undefined : String(backend),
+  ].filter((id): id is string => id !== undefined);
+
+  const facts = elementIds.length
+    ? elementIds.map((elementId) => ({ elementId, rect: ownRect }))
+    : [{ rect: ownRect }];
+  return uniqueCaveats(annotateUnstableFacts(facts, context.regions).flatMap((entry) => entry.caveats));
+}
+
+function caveatLines(caveats: readonly UnstableCaveat[]): FactLine[] {
+  return caveats.map((caveat) => fact`   nondeterminism caveat: unstable region ${caveat.regionId}${caveat.selector ? ` (${caveat.selector})` : ''}${caveat.reason ? ` — ${caveat.reason}` : ''}`);
+}
+
+function availabilityLines(label: string, children: readonly ScrollChild[] | undefined, truncated: unknown, context: CaveatContext): FactLine[] {
+  if (children === undefined) return [fact`   ${label} facts unavailable in scroll.json.`];
+  if (children.length === 0) {
+    const none = label === 'snap point' ? 'none recorded' : 'none recorded';
+    return [fact`   ${label}: ${none}.`];
+  }
+
+  const rows: FactLine[] = [];
+  for (const child of children) {
+    const detail = child.position ?? child.scrollSnapAlign ?? '(unavailable)';
+    rows.push(line(text`   `, data(label), text` `, data(string(child.selector)), text` — `, data(string(detail)), text` · `, formatRect(child.rect)));
+    rows.push(...caveatLines(caveatsFor(child, context)));
+  }
+  if (truncated === true) rows.push(fact`   ${label} enumeration reached its capture cap.`);
+  return rows;
+}
+
+function sampleLines(samples: readonly ScrollSample[] | undefined, context: CaveatContext): FactLine[] {
+  if (samples === undefined) return [text`   reachable-content samples unavailable in scroll.json.`];
+  if (samples.length === 0) return [text`   reachable-content samples: none recorded.`];
+
+  const rows: FactLine[] = [];
+  for (const sample of samples) {
+    rows.push(line(text`   sample offset y=`, numberText(sample.offsetTop), text`: `));
+    const children = sample.visibleChildren;
+    if (children === undefined) {
+      rows.push(text`      visible children unavailable in scroll.json.`);
+    } else if (children.length === 0) {
+      rows.push(text`      no visible child records at this sampled offset.`);
+    } else {
+      for (const child of children) {
+        rows.push(line(text`      visible child `, data(string(child.selector)), text` · `, formatRect(child.rect)));
+        rows.push(...caveatLines(caveatsFor(child, context)).map((caveat) => line(text`   `, caveat)));
+      }
+    }
+    if (sample.visibleChildrenTruncated === true) rows.push(text`      visible-child enumeration reached its capture cap.`);
+  }
+  return rows;
+}
+
+function scopeCount(value: unknown, unavailable: unknown, topologyAvailable: boolean): FactLine {
+  return !topologyAvailable || unavailable === true || numeric(value) === undefined ? text`unavailable` : numberText(value);
+}
+
+function buildCaveatContext(ref: SnapRef): CaveatContext {
+  const geometry = readGeometry<{ elements?: readonly GeometryElement[] }>(ref);
+  const elements = geometry.elements ?? [];
+  const regions = resolveRegions(unstableRegionsFor(ref));
+  const geometryByBackendNodeId = new Map<number, { id?: string; rect?: Rect }>();
+  for (const element of elements) {
+    const backend = backendNodeId(element.backendNodeId);
+    if (backend !== undefined) geometryByBackendNodeId.set(backend, { id: explicitElementId(element.id), rect: rect(element.rect) });
+  }
+  return { regions, geometryByBackendNodeId };
+}
+
+/** Builds the read-only scroll topology report for a resolved snapshot. */
+export function measureMapScroll(ref: SnapRef): RenderableResult {
+  const scroll = readScroll<ScrollArtifact>(ref);
+  const meta = readMeta<SnapMeta>(ref);
+  const topologyAvailable = scroll.available !== false;
+  const containersAvailable = topologyAvailable && Array.isArray(scroll.containers);
+  const containers = containersAvailable ? scroll.containers : [];
+  const caveatContext = buildCaveatContext(ref);
+
+  const sections: FactLine[] = [];
+  if (scroll.available === false) {
+    sections.push(fact`scroll.json reports that topology collection was unavailable: ${string(scroll.reason)}.`);
+  }
+
+  for (const container of containers) {
+    const selector = container.isRoot === true ? '(document)' : string(container.selector);
+    const ancestry = container.nestedAncestryUnavailable === true
+      ? 'unavailable'
+      : container.nestedAncestry === undefined
+        ? 'unavailable'
+        : container.nestedAncestry.map((item) => string(item)).join(' → ') || '(top-level)';
+    const containerCaveats = caveatsFor(container, caveatContext);
+    const rows: FactLine[] = [
+      line(fact`${selector} — `, formatRect(container.rect), text` · range `, formatDimension(container.scrollWidth, container.scrollHeight), text` · client `, formatDimension(container.clientWidth, container.clientHeight)),
+      ...caveatLines(containerCaveats),
+      line(text`   offsets current x=`, numberText(container.scrollLeft), text` y=`, numberText(container.scrollTop), text`; max x=`, numberText(container.maxScrollLeft), text` y=`, numberText(container.maxScrollTop), fact` · overflow ${string(container.overflowX)}/${string(container.overflowY)} · gutter ${string(container.scrollbarGutter)} · snap type ${string(container.scrollSnapType)}`),
+      fact`   nested ancestry: ${ancestry}`,
+      ...availabilityLines('sticky/fixed', container.stickyFixedDescendants, container.stickyFixedDescendantsTruncated, caveatContext),
+      ...availabilityLines('snap point', container.snapDescendants, container.snapDescendantsTruncated, caveatContext),
+      ...sampleLines(container.samples, caveatContext),
+      ...(container.nestedAncestryUnavailable === true ? [text`   nested-ancestry measurement unavailable for this container.`] : []),
+    ];
+    sections.push(lineList(rows));
+  }
+
+  const settled = meta.settled === true;
+  const totalAvailable = topologyAvailable && scroll.scrollContainersCountUnavailable !== true && numeric(scroll.scrollContainersTotal) !== undefined;
+  const measuredCount = totalAvailable ? numberText(scroll.scrollContainersTotal) : text`unavailable`;
+  const recordedCount = containersAvailable ? data(containers.length) : text`unavailable`;
+  const documentWidth = topologyAvailable ? scroll.documentScrollWidth : undefined;
+  const documentHeight = topologyAvailable ? scroll.documentScrollHeight : undefined;
+  return {
+    tag: 'scroll-map',
+    attestation: {
+      kind: 'snapshot',
+      id: ref.id,
+      path: ref.dir,
+      note: settled ? text`Snapshot settled before topology collection.` : text`Snapshot was captured without settledness; facts intersecting marked unstable regions carry nondeterminism caveats.`,
+    },
+    attrs: {
+      containers: containersAvailable ? containers.length : undefined,
+      'scroll-containers': totalAvailable ? numeric(scroll.scrollContainersTotal) : undefined,
+      settled,
+      viewport: typeof meta.viewport === 'string' ? meta.viewport : undefined,
+    },
+    summary: line(measuredCount, text` measured scroll container(s) (`, recordedCount, text` recorded); document extent `, formatDimension(documentWidth, documentHeight), text`.`),
+    sections: [
+      viewportFacts('visual viewport', scroll.visualViewport, scroll.visualViewportUnavailable),
+      viewportFacts('layout viewport', scroll.layoutViewport, scroll.layoutViewportUnavailable),
+      line(text`scope: root `, data(string(scroll.scope?.root)), text`; shadow DOM `, data(string(scroll.scope?.shadowDom)), text`; iframes `, scopeCount(scroll.scope?.iframesPresent, scroll.scopeCountsUnavailable, topologyAvailable), text`; shadow hosts `, scopeCount(scroll.scope?.shadowHostsPresent, scroll.scopeCountsUnavailable, topologyAvailable), text`.`),
+      ...(!containersAvailable ? [text`Scroll container records were unavailable in scroll.json; no container rows are rendered below.`] : []),
+      ...(!totalAvailable && containersAvailable ? [text`Scroll-container total/truncation counts were unavailable in scroll.json; recorded container rows are still rendered below.`] : []),
+      ...(scroll.scrollContainersTruncated === true ? [text`Scroll-container enumeration reached its capture cap; recorded containers are a prefix of the measured topology.`] : []),
+      ...sections,
+    ],
+    followUp: line(fact`Read focus or layer facts from ${ref.id} with `, text`\`capture measure map focus `, data(ref.id), text`\` or \`capture measure map layers `, data(ref.id), text`\`.`),
+  };
+}