@crouton-kit/capture 1.3.20 → 1.4.0

package/src/cdp/measure/explain.ts

@@ -18,11 +18,15 @@ import {
 } from '../../output/artifact.js';
 import { parseSelectorInput, resolveSelectorInput, type ElementRecord, type SelectorInputKind } from '../../output/selector.js';
 import { fact, line, text, type FactLine } from '../../output/render.js';
+import { deriveInkBox, type InkEdges, type InkRect } from './ink.js';
+import { baseInkSource, forcedStateInkSource, isInkSource, quadRect } from './ink-source.js';
 
 export interface ExplainDetailOptions {
   readonly size?: boolean;
   readonly text?: boolean;
   readonly form?: boolean;
+  /** One requested post-force state recorded by `measure snap --state`. */
+  readonly state?: string;
 }
 
 interface ArtifactElement extends ElementRecord {
@@ -47,6 +51,8 @@ interface GeometryElement extends ArtifactElement {
   readonly boxModel?: Record<string, unknown> | null;
   readonly stackingContext?: { readonly creates?: boolean; readonly reasons?: readonly string[] };
   readonly clipping?: { readonly clippedBy?: string; readonly clippedFraction?: number } | null;
+  /** Present on snapshots that recorded uncapped ink-relevant computed styles with geometry. */
+  readonly paint?: Record<string, string | null>;
   readonly visibility?: { readonly visible?: boolean; readonly opacity?: number };
   readonly layout?: Record<string, unknown>;
 }
@@ -97,6 +103,8 @@ export interface ExplainSuccess {
 export interface MissingSelectorRecovery {
   readonly recordCount: number;
   readonly kind: SelectorInputKind;
+  /** Present when a CSS attribute/quoted value was ranked as AX/text evidence before generated CSS paths. */
+  readonly interpretedValue?: string;
   readonly candidates: readonly string[];
 }
 
@@ -177,6 +185,21 @@ function selectorIdentifierDistance(requested: string, candidate: string): numbe
   return requestedTokens.reduce((total, token) => total + Math.min(...candidateTokens.map((other) => editDistance(token, other) / Math.max(token.length, other.length))), 0);
 }
 
+function quotedSelectorValue(value: string): string | undefined {
+  const attribute = /\[[^\]]*?=\s*(?:"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|([^\]\s]+))\]/.exec(value);
+  const quoted = attribute?.[1] ?? attribute?.[2] ?? attribute?.[3] ?? /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'/.exec(value)?.slice(1).find(Boolean);
+  return quoted?.replace(/\\(.)/g, '$1');
+}
+
+function rankCandidates(candidates: string[], requested: string, valueOf: (candidate: string) => string): string[] {
+  return candidates.sort((a, b) => {
+    const aValue = valueOf(a).toLowerCase(), bValue = valueOf(b).toLowerCase();
+    const aIdentifierDistance = selectorIdentifierDistance(requested, aValue), bIdentifierDistance = selectorIdentifierDistance(requested, bValue);
+    const aDistance = editDistance(requested.toLowerCase(), aValue), bDistance = editDistance(requested.toLowerCase(), bValue);
+    return aIdentifierDistance - bIdentifierDistance || aDistance - bDistance || a.length - b.length || a.localeCompare(b);
+  });
+}
+
 function recoveryForms(elements: readonly ElementRecord[], requested: string): MissingSelectorRecovery {
   const input = parseSelectorInput(requested);
   const formFor = (element: ElementRecord): string | undefined => {
@@ -189,14 +212,17 @@ function recoveryForms(elements: readonly ElementRecord[], requested: string): M
     }
   };
   const valueOf = (candidate: string) => input.kind === 'css' ? candidate : candidate.slice(candidate.indexOf(':') + 1);
-  const candidates = [...new Set(elements.map(formFor).filter((candidate): candidate is string => Boolean(candidate)))];
-  candidates.sort((a, b) => {
-    const aValue = valueOf(a).toLowerCase(), bValue = valueOf(b).toLowerCase();
-    const aIdentifierDistance = selectorIdentifierDistance(input.value, aValue), bIdentifierDistance = selectorIdentifierDistance(input.value, bValue);
-    const aDistance = editDistance(input.value.toLowerCase(), aValue), bDistance = editDistance(input.value.toLowerCase(), bValue);
-    return aIdentifierDistance - bIdentifierDistance || aDistance - bDistance || a.length - b.length || a.localeCompare(b);
-  });
-  return { recordCount: elements.length, kind: input.kind, candidates: candidates.slice(0, RECOVERY_CANDIDATE_LIMIT) };
+  const cssCandidates = rankCandidates([...new Set(elements.map(formFor).filter((candidate): candidate is string => Boolean(candidate)))], input.value, valueOf);
+  const interpretedValue = input.kind === 'css' ? quotedSelectorValue(input.value) : undefined;
+  if (!interpretedValue) {
+    return { recordCount: elements.length, kind: input.kind, candidates: cssCandidates.slice(0, RECOVERY_CANDIDATE_LIMIT) };
+  }
+  const identityCandidates = rankCandidates([...new Set(elements.flatMap((element) => [
+    element.axName ? `ax:${element.axName}` : undefined,
+    element.text ? `text:${element.text}` : undefined,
+  ]).filter((candidate): candidate is string => Boolean(candidate)))], interpretedValue, (candidate) => candidate.slice(candidate.indexOf(':') + 1));
+  const candidates = [...identityCandidates, ...cssCandidates.filter((candidate) => !identityCandidates.includes(candidate))];
+  return { recordCount: elements.length, kind: input.kind, interpretedValue, candidates: candidates.slice(0, RECOVERY_CANDIDATE_LIMIT) };
 }
 
 function sourceDescription(declaration: WinningDeclaration): string | undefined {
@@ -257,30 +283,85 @@ function cascadeSection(target: GeometryElement, styles: readonly StyleElement[]
   return { kind: 'cascade', facts };
 }
 
-function stackingClippingSection(target: GeometryElement, geometry: readonly GeometryElement[]): RawSection {
+function formatBox(rect: InkRect): string {
+  return `x=${rect.x}…${rect.x + rect.width} y=${rect.y}…${rect.y + rect.height} (w=${rect.width} h=${rect.height})`;
+}
+
+function overflowEdges(box: InkRect, clip: InkRect): InkEdges {
+  return {
+    top: Math.max(0, clip.y - box.y),
+    right: Math.max(0, box.x + box.width - (clip.x + clip.width)),
+    bottom: Math.max(0, box.y + box.height - (clip.y + clip.height)),
+    left: Math.max(0, clip.x - box.x),
+  };
+}
+
+function formatOverflow(edges: InkEdges): string {
+  const named = (Object.entries(edges) as Array<[keyof InkEdges, number]>).filter(([, value]) => value > 0).map(([edge, value]) => `${edge}=${value}px`);
+  return named.length ? named.join(' ') : 'none';
+}
+
+function stackingClippingSection(target: GeometryElement, geometry: readonly GeometryElement[], states: unknown, state?: string): RawSection {
   const facts: ExplainFact[] = [];
   const ancestors = ancestorElements(geometry, target);
   const stacking = ancestors.filter((element) => element.stackingContext?.creates);
   const root = ancestors[0];
-  if (root) facts.push(factFor(root, fact`Stacking climb root: ${root.selector ?? root.tag ?? root.id}; z-index=${root.zIndex ?? 'auto'}.`));
+  if (root) facts.push(factFor(root, fact`Stacking climb root: ${root.selector ?? root.tag ?? root.id}; z-index=${root.zIndex ?? 'auto'} (base-state geometry record).`));
   for (const ancestor of stacking) {
-    facts.push(factFor(ancestor, fact`Stacking ancestor ${ancestor.selector ?? ancestor.id}: z-index=${ancestor.zIndex ?? 'auto'}; creates context from ${(ancestor.stackingContext?.reasons ?? []).join(', ') || 'recorded context trigger'}.`));
+    facts.push(factFor(ancestor, fact`Stacking ancestor ${ancestor.selector ?? ancestor.id}: z-index=${ancestor.zIndex ?? 'auto'}; creates context from ${(ancestor.stackingContext?.reasons ?? []).join(', ') || 'recorded context trigger'} (base-state geometry record).`));
+  }
+  facts.push(factFor(target, fact`Target stacking record: z-index=${target.zIndex ?? 'auto'}; creates-context=${String(Boolean(target.stackingContext?.creates))}; reasons=${(target.stackingContext?.reasons ?? []).join(', ') || 'none recorded'} (base-state geometry record).`));
+
+  let source = baseInkSource(target);
+  if (state) {
+    const forced = forcedStateInkSource(states, target, state);
+    if (isInkSource(forced)) source = forced;
+    else facts.push(factFor(target, fact`Requested state "${state}" supplied no post-force ink source: ${forced.unavailable}; border/ink and clipping comparisons use the base-state geometry record.`));
+  }
+  const borderBox = isInkSource(source) ? source.rect : undefined;
+  const ink = isInkSource(source) ? deriveInkBox(source.rect, source.styles) : undefined;
+  if (ink?.inkBox && borderBox) {
+    const contributors = ink.contributors.length
+      ? ink.contributors.map((contributor) => `${contributor.source}${contributor.index === undefined ? '' : ` ${contributor.index}`} (top=${contributor.edges.top}px right=${contributor.edges.right}px bottom=${contributor.edges.bottom}px left=${contributor.edges.left}px)`).join('; ')
+      : 'none';
+    facts.push(factFor(target, ink.nominal
+      ? fact`Border box (${source.provenance}): ${formatBox(borderBox)}. Nominal ink box (blur-radius extent, ${source.provenance}): ${formatBox(ink.inkBox)}; contributors: ${contributors}.`
+      : fact`Border box (${source.provenance}): ${formatBox(borderBox)}. Ink box (${source.provenance}): ${formatBox(ink.inkBox)}; contributors: ${contributors}.`));
+  } else if (ink) {
+    const reason = ink.missingStyles.length
+      ? `computed styles were not captured: ${ink.missingStyles.join(', ')}`
+      : `paint extents could not be resolved: ${ink.unresolved.join(', ')}`;
+    facts.push(factFor(target, fact`Ink box (${source.provenance}) was not calculated because ${reason}.`));
+  } else {
+    facts.push(factFor(target, text`Ink box was not calculated because ${source.unavailable}.`));
   }
-  facts.push(factFor(target, fact`Target stacking record: z-index=${target.zIndex ?? 'auto'}; creates-context=${String(Boolean(target.stackingContext?.creates))}; reasons=${(target.stackingContext?.reasons ?? []).join(', ') || 'none recorded'}.`));
 
-  const clippingAncestors = ancestors.filter((element) => {
+  const overflowAncestors = ancestors.filter((element) => {
     const layout = element.layout ?? {};
-    return [layout.overflowX, layout.overflowY].some((value) => typeof value === 'string' && /hidden|auto|scroll|clip/.test(value));
+    return [layout.overflowX, layout.overflowY].some((value) => typeof value === 'string' && /\b(?:hidden|auto|scroll|clip)\b/.test(value));
+  });
+  const clipPathAncestors = ancestors.filter((element) => {
+    const clipPath = element.paint?.['clip-path'];
+    return typeof clipPath === 'string' && clipPath !== 'none';
   });
-  for (const ancestor of clippingAncestors) {
+  for (const ancestor of overflowAncestors) {
     const layout = ancestor.layout ?? {};
-    const active = target.clipping?.clippedBy === ancestor.selector;
-    facts.push(factFor(ancestor, fact`Clipping ancestor ${ancestor.selector ?? ancestor.id}: overflow-x=${String(layout.overflowX ?? 'unknown')}; overflow-y=${String(layout.overflowY ?? 'unknown')}; clips-target=${String(active)}${active && target.clipping?.clippedFraction !== undefined ? `; visible-fraction=${target.clipping.clippedFraction}` : ''}.`));
+    const clip = quadRect((ancestor.boxModel ?? {}).padding);
+    const radius = ancestor.paint?.['border-radius'];
+    if (!clip) {
+      facts.push(factFor(ancestor, fact`Clipping ancestor ${ancestor.selector ?? ancestor.id}: overflow-x=${String(layout.overflowX ?? 'unknown')}; overflow-y=${String(layout.overflowY ?? 'unknown')} (base-state geometry record); padding-box clip was not captured, so border-box and ink-box clipping were not calculated.`));
+      continue;
+    }
+    const borderEdges = borderBox ? overflowEdges(borderBox, clip) : undefined;
+    const inkEdges = ink?.inkBox ? overflowEdges(ink.inkBox, clip) : undefined;
+    const targetSource = isInkSource(source) ? source.provenance : source.unavailable;
+    facts.push(factFor(ancestor, fact`Clipping ancestor ${ancestor.selector ?? ancestor.id}: overflow-x=${String(layout.overflowX ?? 'unknown')}; overflow-y=${String(layout.overflowY ?? 'unknown')}; rectangular padding clip (base-state geometry record) ${formatBox(clip)}; border-radius=${radius ?? 'not captured'}${radius && radius !== '0px' ? ' (rounded clip shape not resolved)' : ''}; target border/ink source=${targetSource}; border-box-overflows-padding-clip=${String(Boolean(borderEdges && formatOverflow(borderEdges) !== 'none'))}; border-box-overflow=${borderEdges ? formatOverflow(borderEdges) : 'not calculated'}; ink-box-overflows-padding-clip=${String(Boolean(inkEdges && formatOverflow(inkEdges) !== 'none'))}; ink-box-overflow=${inkEdges ? formatOverflow(inkEdges) : 'not calculated'}.`));
+  }
+  for (const ancestor of clipPathAncestors) {
+    facts.push(factFor(ancestor, fact`Clip-path ancestor ${ancestor.selector ?? ancestor.id}: clip-path=${ancestor.paint?.['clip-path']} (base-state geometry record); shape geometry was not captured, so border-box and ink-box clipping were not calculated for this source.`));
   }
-  if (target.clipping?.clippedBy && !clippingAncestors.some((ancestor) => ancestor.selector === target.clipping?.clippedBy)) {
-    facts.push(factFor(target, fact`Recorded clipping source ${target.clipping.clippedBy}; visible-fraction=${target.clipping.clippedFraction ?? 'unknown'}.`));
-  } else if (!target.clipping) {
-    facts.push(factFor(target, text`No clipping source was recorded for the target.`));
+  if (!overflowAncestors.length && !clipPathAncestors.length) {
+    facts.push(factFor(target, text`No overflow or clip-path clipping ancestor was recorded for the target.`));
   }
   return { kind: 'stacking-clipping', facts };
 }
@@ -361,7 +442,26 @@ function queriesStatesSection(target: GeometryElement, queries: Record<string, u
     const records = (Array.isArray(states.elements) ? states.elements : [])
       .filter((entry): entry is ArtifactElement & Record<string, unknown> => Boolean(entry && typeof entry === 'object'))
       .filter((entry) => sameTarget(entry, target));
-    facts.push(factFor(target, fact`State matrix context: requested=${requested.join(', ') || 'none'}; matching records=${records.length}.`));
+    // A forced state records the element it forced plus the descendants and following peers whose
+    // style or geometry moved. Counting only the forced-target rows reports `matching records=0` for
+    // an element whose post-force values this same output just derived from an affected row.
+    const affectedRows = (Array.isArray(states.elements) ? states.elements : [])
+      .filter((entry): entry is ArtifactElement & Record<string, unknown> => Boolean(entry && typeof entry === 'object'))
+      .flatMap((entry) => {
+        const affected = entry.affected as Record<string, unknown> | undefined;
+        const rows = affected && typeof affected === 'object' && Array.isArray(affected.elements) ? affected.elements : [];
+        return rows
+          .filter((row): row is ArtifactElement & Record<string, unknown> => Boolean(row && typeof row === 'object'))
+          .filter((row) => String(row.relation ?? '') !== 'target' && sameTarget(row, target))
+          .map((row) => ({ state: String(entry.state ?? 'unknown'), forced: String(entry.selector ?? 'unknown'), row }));
+      });
+    facts.push(factFor(target, fact`State matrix context: requested=${requested.join(', ') || 'none'}; records forcing this element=${records.length}; records where it is an affected descendant or peer=${affectedRows.length}.`));
+    for (const { state, forced, row } of affectedRows) {
+      const changes = row.style && typeof row.style === 'object' && Array.isArray((row.style as Record<string, unknown>).changed)
+        ? ((row.style as Record<string, unknown>).changed as unknown[]).map(String).join(', ')
+        : 'none recorded';
+      facts.push(factFor(target, fact`State ${state}: recorded as ${String(row.relation ?? 'unknown')} of forced target ${forced}; style changes=${changes}; geometry-changed=${String((row.geometry as Record<string, unknown> | undefined)?.changed ?? false)}; hittest-changed=${String((row.hittest as Record<string, unknown> | undefined)?.changed ?? false)}.`));
+    }
     for (const record of records) {
       const changes = record.style && typeof record.style === 'object' && Array.isArray((record.style as Record<string, unknown>).changed)
         ? ((record.style as Record<string, unknown>).changed as unknown[]).map(String).join(', ')
@@ -478,7 +578,7 @@ export function explainSnapshot(ref: SnapRef, selector: string, detailOpts: Expl
   const rawSections: RawSection[] = [
     elementSection(target, matches.length),
     cascadeSection(target, styles),
-    stackingClippingSection(target, geometry),
+    stackingClippingSection(target, geometry, states, detailOpts.state),
     focusScrollSection(target, focus, scroll),
     queriesStatesSection(target, queries, states, styles),
   ];

package/src/cdp/measure/ink-source.ts

@@ -0,0 +1,116 @@
+import type { InkRect, InkStyles } from './ink.js';
+
+/**
+ * Selects which recorded rect + computed-style table an ink derivation runs over:
+ * the base-state geometry record, or one element's post-force values under a
+ * requested `--state`. Both callers of `deriveInkBox` over snapshot artifacts
+ * (`measure explain` and `measure map paint`) resolve their input here so the
+ * two leaves cannot disagree about what a forced-state ink box is derived from.
+ */
+export interface InkSource {
+  readonly rect: InkRect;
+  readonly styles: InkStyles;
+  /** Factual description of where `rect` and `styles` were read from, for the caller to report. */
+  readonly provenance: string;
+}
+
+export interface InkSourceUnavailable {
+  /** Factual reason no rect/style pair was found, phrased for direct inclusion in output. */
+  readonly unavailable: string;
+}
+
+export type InkSourceResult = InkSource | InkSourceUnavailable;
+
+export function isInkSource(result: InkSourceResult): result is InkSource {
+  return (result as InkSource).rect !== undefined;
+}
+
+export interface InkTargetIdentity {
+  readonly selector?: string;
+  readonly backendNodeId?: number | null;
+}
+
+interface GeometryLike extends InkTargetIdentity {
+  readonly boxModel?: Record<string, unknown> | null;
+  /** Ink-relevant computed styles recorded beside geometry; absent on snapshots taken before that collection existed. */
+  readonly paint?: Record<string, string | null>;
+}
+
+/** Converts a CDP box-model quad (8 numbers) to its axis-aligned bounding rect. */
+export function quadRect(value: unknown): InkRect | undefined {
+  if (!Array.isArray(value) || value.length !== 8 || !value.every((entry) => Number.isFinite(entry))) return undefined;
+  const xs = [value[0], value[2], value[4], value[6]] as number[];
+  const ys = [value[1], value[3], value[5], value[7]] as number[];
+  const left = Math.min(...xs), top = Math.min(...ys);
+  return { x: left, y: top, width: Math.max(...xs) - left, height: Math.max(...ys) - top };
+}
+
+export function baseInkSource(element: GeometryLike): InkSourceResult {
+  const rect = quadRect((element.boxModel ?? {}).border);
+  if (!rect) return { unavailable: `this target's border-box quad was not captured` };
+  return { rect, styles: element.paint ?? {}, provenance: 'base-state geometry record' };
+}
+
+function rectFrom(value: unknown): InkRect | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const raw = value as Record<string, unknown>;
+  const [x, y, width, height] = [raw.x, raw.y, raw.width ?? raw.w, raw.height ?? raw.h];
+  if (![x, y, width, height].every((entry) => typeof entry === 'number' && Number.isFinite(entry))) return undefined;
+  return { x: x as number, y: y as number, width: width as number, height: height as number };
+}
+
+function stylesFrom(value: unknown): InkStyles | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const after = (value as Record<string, unknown>).after;
+  if (!after || typeof after !== 'object') return undefined;
+  return after as InkStyles;
+}
+
+function identityMatches(row: InkTargetIdentity, target: InkTargetIdentity): boolean {
+  if (typeof target.backendNodeId === 'number' && typeof row.backendNodeId === 'number') return row.backendNodeId === target.backendNodeId;
+  return Boolean(target.selector && row.selector === target.selector);
+}
+
+interface StateRow extends InkTargetIdentity {
+  readonly relation?: string;
+  readonly geometry?: unknown;
+  readonly style?: unknown;
+}
+
+/**
+ * Resolves one element's post-force rect and computed styles from `states.json`.
+ * The rect is that element's `getBoundingClientRect` AABB after the force was
+ * applied — a border box, which is what `deriveInkBox` grows. Under a forced
+ * state the paint change frequently lands on a descendant of the forced target
+ * (a hover ring drawn on a child), so `affected.elements` rows are searched
+ * alongside the forced target's own record.
+ */
+export function forcedStateInkSource(states: unknown, target: InkTargetIdentity, state: string): InkSourceResult {
+  const elements = (states && typeof states === 'object' && Array.isArray((states as Record<string, unknown>).elements))
+    ? (states as { elements: unknown[] }).elements.filter((entry): entry is Record<string, unknown> => Boolean(entry && typeof entry === 'object'))
+    : [];
+  const forState = elements.filter((record) => String(record.state ?? '') === state);
+  if (!forState.length) {
+    const recorded = [...new Set(elements.map((record) => String(record.state ?? '')).filter(Boolean))];
+    return { unavailable: `this snapshot recorded no "${state}" state${recorded.length ? `; it recorded ${recorded.join(', ')}` : ''}` };
+  }
+  const unsupported = forState.filter((record) => record.supported === false);
+  for (const record of forState) {
+    if (record.supported === false) continue;
+    const affected = (record.affected && typeof record.affected === 'object' && Array.isArray((record.affected as Record<string, unknown>).elements))
+      ? ((record.affected as { elements: unknown[] }).elements.filter((entry): entry is StateRow => Boolean(entry && typeof entry === 'object')))
+      : [];
+    const own: StateRow = { selector: record.selector as string | undefined, backendNodeId: record.backendNodeId as number | null | undefined, relation: 'target', geometry: record.geometry, style: record.style };
+    for (const row of [own, ...affected]) {
+      if (!identityMatches(row, target)) continue;
+      const rect = rectFrom((row.geometry as Record<string, unknown> | undefined)?.after);
+      const styles = stylesFrom(row.style);
+      if (!rect) return { unavailable: `the "${state}" record for this target captured no post-force rect` };
+      if (!styles) return { unavailable: `the "${state}" record for this target captured no post-force computed styles` };
+      const id = String(record.id ?? state);
+      return { rect, styles, provenance: `forced state "${state}" (states.json record ${id}, ${row.relation ?? 'affected'} row, post-force values)` };
+    }
+  }
+  if (unsupported.length === forState.length) return { unavailable: `state "${state}" was recorded as unsupported on its forced target` };
+  return { unavailable: `no "${state}" record matched this target; forced-state rows cover the forced target, its light-DOM descendants, and its following-sibling subtrees` };
+}

package/src/cdp/measure/ink.ts

@@ -0,0 +1,180 @@
+export interface InkRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface InkStyles {
+  readonly 'box-shadow'?: string | null;
+  readonly 'outline-width'?: string | null;
+  readonly 'outline-style'?: string | null;
+  readonly 'outline-offset'?: string | null;
+  readonly filter?: string | null;
+  readonly transform?: string | null;
+}
+
+export interface InkEdges {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+
+export interface InkContributor {
+  readonly source: 'box-shadow' | 'outline' | 'filter:drop-shadow';
+  readonly index?: number;
+  readonly edges: InkEdges;
+  /** A blur has no finite specified painted edge; its radius is a nominal AABB convention. */
+  readonly nominal?: true;
+}
+
+export interface InkResult {
+  /** `null` when a needed computed-style value was not captured or a paint-growing filter could not be resolved. */
+  readonly inkBox: InkRect | null;
+  readonly contributors: readonly InkContributor[];
+  readonly missingStyles: readonly string[];
+  readonly unresolved: readonly string[];
+  /** True when an included blur uses the parser's nominal blur-radius extent. */
+  readonly nominal: boolean;
+}
+
+const REQUIRED_STYLES = ['box-shadow', 'outline-width', 'outline-style', 'outline-offset', 'filter', 'transform'] as const;
+
+function zeroEdges(): InkEdges {
+  return { top: 0, right: 0, bottom: 0, left: 0 };
+}
+
+function splitTopLevel(value: string, delimiter: ',' | ' '): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]!;
+    if (char === '(') depth += 1;
+    else if (char === ')' && depth > 0) depth -= 1;
+    else if (depth === 0 && (delimiter === ',' ? char === ',' : /\s/.test(char))) {
+      const part = value.slice(start, index).trim();
+      if (part) parts.push(part);
+      start = index + 1;
+    }
+  }
+  const tail = value.slice(start).trim();
+  if (tail) parts.push(tail);
+  return parts;
+}
+
+function px(value: string): number | undefined {
+  const match = /^(-?(?:\d+|\d*\.\d+))px$/.exec(value) ?? (/^-?(?:\d+|\d*\.\d+)$/.test(value) ? [value, value] : undefined);
+  if (!match) return undefined;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function edgesForShadow(offsetX: number, offsetY: number, blur: number, spread: number): InkEdges {
+  // CSS computes these values to px. Blur's painted boundary is not a hard CSS edge;
+  // its radius is the recorded geometric extent used for this conservative ink AABB.
+  const growth = Math.max(0, blur + spread);
+  return {
+    left: Math.max(0, growth - offsetX),
+    right: Math.max(0, growth + offsetX),
+    top: Math.max(0, growth - offsetY),
+    bottom: Math.max(0, growth + offsetY),
+  };
+}
+
+function parseShadow(value: string, source: InkContributor['source'], index: number, allowSpread: boolean): InkContributor | undefined {
+  const tokens = splitTopLevel(value, ' ').filter((token) => token.toLowerCase() !== 'inset');
+  const lengths = tokens.map(px).filter((length): length is number => length !== undefined);
+  if (lengths.length < 2 || lengths.length > (allowSpread ? 4 : 3)) return undefined;
+  const [offsetX, offsetY, blur = 0, spread = 0] = lengths;
+  return { source, index, edges: edgesForShadow(offsetX!, offsetY!, blur, allowSpread ? spread : 0), ...(blur > 0 ? { nominal: true as const } : {}) };
+}
+
+function dropShadowArguments(filter: string): string[] {
+  const out: string[] = [];
+  const lower = filter.toLowerCase();
+  let cursor = 0;
+  while (cursor < lower.length) {
+    const start = lower.indexOf('drop-shadow(', cursor);
+    if (start < 0) break;
+    let depth = 1;
+    let end = start + 'drop-shadow('.length;
+    while (end < filter.length && depth > 0) {
+      if (filter[end] === '(') depth += 1;
+      else if (filter[end] === ')') depth -= 1;
+      end += 1;
+    }
+    if (depth === 0) out.push(filter.slice(start + 'drop-shadow('.length, end - 1));
+    cursor = end;
+  }
+  return out;
+}
+
+function containsUnresolvedPaintFilter(filter: string): boolean {
+  const remainder = filter.replace(/drop-shadow\((?:[^()]|\([^()]*\))*\)/gi, '').trim();
+  return /(?:\bblur\(|\burl\()/i.test(remainder);
+}
+
+function combineEdges(contributors: readonly InkContributor[]): InkEdges {
+  return contributors.reduce<InkEdges>((extent, contributor) => ({
+    top: Math.max(extent.top, contributor.edges.top),
+    right: Math.max(extent.right, contributor.edges.right),
+    bottom: Math.max(extent.bottom, contributor.edges.bottom),
+    left: Math.max(extent.left, contributor.edges.left),
+  }), zeroEdges());
+}
+
+/** Derives an axis-aligned ink box from a recorded border box and computed-style table without a browser. */
+export function deriveInkBox(rect: InkRect, styles: InkStyles): InkResult {
+  const missingStyles = REQUIRED_STYLES.filter((property) => styles[property] === undefined || styles[property] === null);
+  if (missingStyles.length) return { inkBox: null, contributors: [], missingStyles, unresolved: [], nominal: false };
+  if (styles.transform !== 'none') return { inkBox: null, contributors: [], missingStyles: [], unresolved: ['transform'], nominal: false };
+
+  const contributors: InkContributor[] = [];
+  const unresolved: string[] = [];
+  const boxShadow = styles['box-shadow']!.trim();
+  if (boxShadow && boxShadow !== 'none') {
+    splitTopLevel(boxShadow, ',').forEach((shadow, index) => {
+      if (/\binset\b/i.test(shadow)) return;
+      const contributor = parseShadow(shadow, 'box-shadow', index + 1, true);
+      if (contributor) contributors.push(contributor);
+      else unresolved.push(`box-shadow ${index + 1}`);
+    });
+  }
+
+  if (styles['outline-style'] !== 'none') {
+    const width = px(styles['outline-width']!.trim());
+    const offset = px(styles['outline-offset']!.trim());
+    if (width === undefined || offset === undefined) unresolved.push('outline');
+    else {
+      const extent = Math.max(0, width + offset);
+      contributors.push({ source: 'outline', edges: { top: extent, right: extent, bottom: extent, left: extent } });
+    }
+  }
+
+  const filter = styles.filter!.trim();
+  if (filter && filter !== 'none') {
+    dropShadowArguments(filter).forEach((shadow, index) => {
+      const contributor = parseShadow(shadow, 'filter:drop-shadow', index + 1, false);
+      if (contributor) contributors.push(contributor);
+      else unresolved.push(`filter drop-shadow ${index + 1}`);
+    });
+    if (containsUnresolvedPaintFilter(filter)) unresolved.push('filter');
+  }
+
+  if (unresolved.length) return { inkBox: null, contributors, missingStyles: [], unresolved, nominal: contributors.some((contributor) => contributor.nominal) };
+  const extent = combineEdges(contributors);
+  return {
+    inkBox: {
+      x: rect.x - extent.left,
+      y: rect.y - extent.top,
+      width: rect.width + extent.left + extent.right,
+      height: rect.height + extent.top + extent.bottom,
+    },
+    contributors,
+    missingStyles: [],
+    unresolved: [],
+    nominal: contributors.some((contributor) => contributor.nominal),
+  };
+}

package/src/cdp/measure/snapshot.ts

@@ -199,28 +199,30 @@ 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?: () => void): CDPClient {
+function boundedClient(client: CDPClient, phase: string, partialPath: string, onTimeout?: (error: SnapshotCaptureTimeout) => void): CDPClient {
   const bounded = Object.create(client) as CDPClient;
   bounded.send = (method: string, params: Record<string, unknown> = {}, timeout = 60_000, sessionId?: string): Promise<unknown> => {
     const timeoutMs = Math.min(timeout, SNAPSHOT_REQUEST_TIMEOUT_MS);
     let timer: NodeJS.Timeout | undefined;
     let timedOut = false;
-    const markTimedOut = (): void => {
+    const markTimedOut = (error: SnapshotCaptureTimeout): void => {
       if (timedOut) return;
       timedOut = true;
-      onTimeout?.();
+      onTimeout?.(error);
     };
     const deadline = new Promise<never>((_, reject) => {
       timer = setTimeout(() => {
-        markTimedOut();
-        reject(new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath));
+        const error = new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        markTimedOut(error);
+        reject(error);
       }, timeoutMs);
     });
     const request = Promise.resolve().then(() => client.send(method, params, timeoutMs, sessionId)).catch((error: unknown) => {
       if (error instanceof SnapshotCaptureTimeout) throw error;
       if (error instanceof Error && error.message.startsWith('CDP request timeout')) {
-        markTimedOut();
-        throw new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        const timeoutError = new SnapshotCaptureTimeout(phase, method, timeoutMs, partialPath);
+        markTimedOut(timeoutError);
+        throw timeoutError;
       }
       throw error;
     });
@@ -251,6 +253,8 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
   const state = options.state ?? [];
   const viewport = options.viewport ?? null;
   const colorScheme = options.colorScheme;
+  // This narrow extension is parsed by `measure snap`; the shared SnapshotContext remains backwards-compatible for every other collector.
+  const stateDiffPaddingCssPx = (options as CaptureSnapshotOptions & { stateDiffPaddingCssPx?: number }).stateDiffPaddingCssPx ?? 8;
   // Apply the shared artifact-string cap once at the source. URL contents
   // otherwise survive unchanged in meta.json, the result, and collector context.
   const url = options.url ? sanitizeString(options.url) : null;
@@ -375,6 +379,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
         pixels,
         state,
         unstableRegions,
+        ...({ stateDiffPaddingCssPx } as {}),
         write: makeWriter(dir, artifacts),
       };
 
@@ -387,25 +392,34 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
 
         const startedAt = Date.now();
         let requestTimeouts = 0;
+        let timeoutError: SnapshotCaptureTimeout | undefined;
         const collectorWriter = makeCollectorWriter(ctx.write);
         try {
-          // Await the collector itself, not a wall-clock race around it. Each CDP
-          // request is still bounded at five seconds; awaiting the collector keeps
-          // any cleanup and pending browser work quiescent before the next shared-
-          // connection collector starts.
+          // Await the collector itself, not a wall-clock race around it. The
+          // collector owns its cleanup, and timeout handling below decides whether
+          // this capture can safely move on to another shared-connection collector.
           await collector.fn({
             ...ctx,
-            client: boundedClient(client, `collector:${collector.name}`, dir, () => { requestTimeouts += 1; }),
+            client: boundedClient(client, `collector:${collector.name}`, dir, (error) => {
+              requestTimeouts += 1;
+              timeoutError ??= error;
+            }),
             write: collectorWriter.writer,
           });
+          // A styles timeout may be caught per-record by the provenance collector,
+          // but its browser operation can still belong to this shared connection.
+          // End this capture instead of letting another collector issue commands
+          // under that outstanding operation.
+          if (collector.name === 'styles' && timeoutError) throw timeoutError;
           const ms = Date.now() - startedAt;
           collectorWriter.commit();
           return requestTimeouts > 0
             ? { name: collector.name, status: 'degraded', ms, requestTimeouts }
             : { name: collector.name, status: 'ok', ms };
-        } catch {
+        } catch (error) {
           const ms = Date.now() - startedAt;
           collectorWriter.discard();
+          if (collector.name === 'styles' && error instanceof SnapshotCaptureTimeout) throw error;
           return { name: collector.name, status: 'error', ms, ...(requestTimeouts > 0 ? { requestTimeouts } : {}) };
         }
       };