@crouton-kit/capture 1.3.21 → 1.4.1

package/src/cdp/measure/collectors/states.ts

@@ -85,6 +85,11 @@
  * === after) — a baseline row for the matrix, not a forced capture.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+
 import type { CDPClient } from '../../client.js';
 import type { Rect } from '../../coordinates.js';
 import { forcePseudoStateForNode, type ForcedPseudoClass } from '../../domains.js';
@@ -101,6 +106,12 @@ const MAX_SELECTOR_MATCHES = 10;
 const MAX_AUTO_ELEMENTS = 8;
 /** Per-field length cap applied NODE-SIDE to page-controlled strings (text, aria-label). Passed to {@link sanitizeString} as `{ max }` — a tighter bound than the shared default. */
 const MAX_STRING_LEN = 200;
+/** Bounds forced-state evidence to the target subtree plus following sibling subtrees; omitted candidates are reported in `affected.truncated`. */
+const MAX_AFFECTED_ELEMENTS = 100;
+/** Default CSS-pixel inset/outset around the forced target's border rect included in its raster diff. */
+const DEFAULT_STATE_DIFF_PADDING_CSS_PX = 8;
+/** Two animation frames let style invalidation reach paint before the forced-state screenshot; this costs roughly 33ms at 60Hz per supported force. */
+const STATE_CAPTURE_SETTLE_FRAMES = 2;
 
 const CONCRETE_STATES = ['hover', 'focus', 'active', 'checked', 'open', 'disabled', 'invalid'] as const;
 type ConcreteState = (typeof CONCRETE_STATES)[number];
@@ -207,6 +218,26 @@ interface HittestDelta {
   readonly changed: boolean;
 }
 
+interface StateAffectedRecord {
+  readonly relation: 'target' | 'descendant' | 'peer-sibling';
+  readonly selector?: string;
+  readonly backendNodeId: number | null;
+  readonly identityUnresolved?: true;
+  readonly geometry: GeometryDelta;
+  readonly style: StyleDelta;
+  readonly hittest: HittestDelta;
+}
+
+interface StateRasterArtifact {
+  readonly screenshot: string;
+  readonly diff?: string;
+  readonly viewportScale: { readonly available: boolean; readonly innerWidth: number; readonly innerHeight: number; readonly scaleX: number; readonly scaleY: number; readonly unavailableReason?: 'viewport-read-unavailable' };
+  readonly diffCrop: { readonly paddingCssPx: number; readonly borderRect: Rect };
+  readonly diffPixelCount?: number;
+  readonly changedPixelBboxCss?: Rect;
+  readonly diffUnavailableReason?: 'baseline-unavailable' | 'dimension-mismatch';
+}
+
 interface StateElementRecord {
   readonly id: string;
   readonly state: string;
@@ -229,6 +260,10 @@ interface StateElementRecord {
   readonly geometry?: GeometryDelta;
   readonly style?: StyleDelta;
   readonly hittest?: HittestDelta;
+  /** Target, light-DOM descendants, and following sibling subtrees measured under this force. `truncated` names candidates omitted by the explicit cap. */
+  readonly affected?: { readonly elements: readonly StateAffectedRecord[]; readonly total: number; readonly kept: number; readonly truncated: boolean };
+  /** Rendered evidence captured while this exact force remained active. */
+  readonly raster?: StateRasterArtifact;
   /** `true` when the pre- or post-force `evalFacts` read itself failed (evaluate threw, or resolved with no `value`) — distinguishes "could not read" from a genuine `{exists:false}`/"not found" measured outcome (I-5). Present only on that failure path. */
   readonly factsUnavailable?: true;
   readonly factsUnavailableReason?: FactsUnavailableReason;
@@ -684,8 +719,178 @@ function zeroDelta(before: Rect): GeometryDelta {
   return { before, after: before, delta: { dx: 0, dy: 0, dwidth: 0, dheight: 0 }, changed: false };
 }
 
+interface DomNode {
+  readonly nodeId?: number;
+  readonly nodeType?: number;
+  readonly nodeName?: string;
+  readonly backendNodeId?: number;
+  readonly attributes?: readonly string[];
+  readonly children?: readonly DomNode[];
+}
+
+interface AffectedSubject {
+  readonly nodeId: number;
+  readonly relation: StateAffectedRecord['relation'];
+  readonly selector?: string;
+  readonly backendNodeId: number | null;
+  readonly identityUnresolved?: true;
+}
+
+function elementNodes(node: DomNode, out: DomNode[]): void {
+  if (node.nodeType === 1 && typeof node.nodeId === 'number') out.push(node);
+  for (const child of node.children ?? []) elementNodes(child, out);
+}
+
+function findNodeAndParent(node: DomNode, nodeId: number, parent?: DomNode): { node: DomNode; parent?: DomNode } | undefined {
+  if (node.nodeId === nodeId) return { node, parent };
+  for (const child of node.children ?? []) {
+    const found = findNodeAndParent(child, nodeId, node);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+/** Resolves a bounded subject population without re-requesting the document, because a new DOM root invalidates the frontend node id that CSS.forcePseudoState must restore. */
+async function affectedSubjects(client: CDPClient, targetNodeId: number, target: AffectedSubject): Promise<{ subjects: AffectedSubject[]; total: number }> {
+  let targetObjectId: string | undefined;
+  let siblingsObjectId: string | undefined;
+  try {
+    const nodes: Array<{ node: DomNode; relation: StateAffectedRecord['relation'] }> = [];
+    const targetDescription = (await client.send('DOM.describeNode', { nodeId: targetNodeId, depth: -1, pierce: false })) as { node?: DomNode };
+    if (!targetDescription.node) return { subjects: [target], total: 1 };
+    const targetSubtree: DomNode[] = [];
+    elementNodes(targetDescription.node, targetSubtree);
+    for (const node of targetSubtree) nodes.push({ node, relation: node.nodeId === targetNodeId ? 'target' : 'descendant' });
+    const resolved = (await client.send('DOM.resolveNode', { nodeId: targetNodeId })) as { object?: { objectId?: string } };
+    targetObjectId = resolved.object?.objectId;
+    if (targetObjectId) {
+      const siblings = (await client.send('Runtime.callFunctionOn', { objectId: targetObjectId, functionDeclaration: 'function __captureStateFollowingPeers(){ const all = Array.from(this.parentElement ? this.parentElement.children : []); return all.slice(all.indexOf(this) + 1); }' })) as { result?: { objectId?: string } };
+      siblingsObjectId = siblings.result?.objectId;
+      if (siblingsObjectId) {
+        const properties = (await client.send('Runtime.getProperties', { objectId: siblingsObjectId, ownProperties: true })) as { result?: Array<{ name?: string; value?: { objectId?: string } }> };
+        for (const property of properties.result ?? []) {
+          if (!/^\d+$/.test(property.name ?? '') || !property.value?.objectId) continue;
+          const requested = (await client.send('DOM.requestNode', { objectId: property.value.objectId })) as { nodeId?: number };
+          if (!requested.nodeId) continue;
+          const siblingDescription = (await client.send('DOM.describeNode', { nodeId: requested.nodeId, depth: -1, pierce: false })) as { node?: DomNode };
+          if (!siblingDescription.node) continue;
+          const subtree: DomNode[] = [];
+          elementNodes(siblingDescription.node, subtree);
+          for (const node of subtree) nodes.push({ node, relation: 'peer-sibling' });
+        }
+      }
+    }
+    const subjects = nodes.slice(0, MAX_AFFECTED_ELEMENTS).map(({ node, relation }) => ({
+      nodeId: node.nodeId!, relation, selector: buildSelector(node.nodeName, node.attributes), backendNodeId: node.backendNodeId ?? null,
+      ...(node.backendNodeId === undefined ? { identityUnresolved: true as const } : {}),
+    }));
+    return { subjects: subjects.length ? subjects : [target], total: nodes.length || 1 };
+  } catch {
+    return { subjects: [target], total: 1 };
+  } finally {
+    for (const objectId of [siblingsObjectId, targetObjectId]) if (objectId) {
+      try { await client.send('Runtime.releaseObject', { objectId }); } catch { /* best-effort object release */ }
+    }
+  }
+}
+
+function nodeFactsFunction(): string {
+  return `function __captureStateNodeFacts() {
+    const el = this;
+    const rect = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    const style = {};
+    for (const p of ${JSON.stringify(STYLE_PROPS)}) style[p] = cs.getPropertyValue(p);
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const inViewport = rect.width > 0 && rect.height > 0 && cx >= 0 && cy >= 0 && cx <= window.innerWidth && cy <= window.innerHeight;
+    const stack = inViewport ? document.elementsFromPoint(cx, cy) : [];
+    const top = stack[0] || null;
+    return { exists: true, tag: el.tagName, rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, style, hit: { isTarget: top === el, topTag: top ? top.tagName : null }, text: (el.textContent || '').trim(), axName: el.getAttribute('aria-label') };
+  }`;
+}
+
+async function evalFactsForNode(client: CDPClient, nodeId: number, backendNodeId: number | null): Promise<ElementFacts> {
+  let objectId: string | undefined;
+  try {
+    // Child node ids in a depth-recursive DOM.describeNode response are not guaranteed to be frontend-bound; backend ids are the cross-call identity Chrome promises.
+    const resolved = (await client.send('DOM.resolveNode', backendNodeId === null ? { nodeId } : { backendNodeId })) as { object?: { objectId?: string } };
+    objectId = resolved.object?.objectId;
+    if (!objectId) return { exists: false, factsUnavailable: true, factsUnavailableReason: 'facts-evaluate-returned-no-value' };
+    const response = (await client.send('Runtime.callFunctionOn', { objectId, functionDeclaration: nodeFactsFunction(), returnByValue: true })) as { result?: { value?: ElementFacts } };
+    return response.result?.value ?? { exists: false, factsUnavailable: true, factsUnavailableReason: 'facts-evaluate-returned-no-value' };
+  } catch {
+    return { exists: false, factsUnavailable: true, factsUnavailableReason: 'facts-evaluate-threw' };
+  } finally {
+    if (objectId) {
+      try { await client.send('Runtime.releaseObject', { objectId }); } catch { /* object lifetime is browser-owned if release fails */ }
+    }
+  }
+}
+
+function deltaForFacts(before: ElementFacts, after: ElementFacts): { geometry: GeometryDelta; style: StyleDelta; hittest: HittestDelta } | undefined {
+  if (!before.exists || !after.exists || before.factsUnavailable || after.factsUnavailable || !before.rect || !after.rect || !before.style || !after.style || !before.hit || !after.hit) return undefined;
+  const geometryChanged = before.rect.x !== after.rect.x || before.rect.y !== after.rect.y || before.rect.width !== after.rect.width || before.rect.height !== after.rect.height;
+  return {
+    geometry: { before: before.rect, after: after.rect, delta: { dx: after.rect.x - before.rect.x, dy: after.rect.y - before.rect.y, dwidth: after.rect.width - before.rect.width, dheight: after.rect.height - before.rect.height }, changed: geometryChanged },
+    style: { changed: STYLE_PROPS.filter((property) => before.style![property] !== after.style![property]), before: sanitizeStyleValues(before.style), after: sanitizeStyleValues(after.style) },
+    hittest: { before: before.hit, after: after.hit, changed: before.hit.isTarget !== after.hit.isTarget || before.hit.topTag !== after.hit.topTag },
+  };
+}
+
+async function settleForcedState(client: CDPClient): Promise<void> {
+  await client.send('Runtime.evaluate', { expression: `(async function __captureStatePaintSettle(){ for (let i = 0; i < ${STATE_CAPTURE_SETTLE_FRAMES}; i += 1) await new Promise(requestAnimationFrame); return true; })()`, awaitPromise: true, returnByValue: true });
+}
+
+function round3(value: number): number { return Math.round(value * 1000) / 1000; }
+
+/** Captures the active forced state and a target-border-plus-padding pixel diff against screenshot.png. */
+async function captureStateRaster(ctx: import('../types.js').SnapshotContext, client: CDPClient, state: string, id: string, borderRect: Rect): Promise<StateRasterArtifact | undefined> {
+  const baselinePath = path.join(ctx.dir, 'screenshot.png');
+  if (!fs.existsSync(baselinePath)) return undefined;
+  const response = (await client.send('Page.captureScreenshot', { format: 'png' })) as { data: string };
+  const statePng = Buffer.from(response.data, 'base64');
+  const imageName = `states/${sanitizeToken(state) || 'state'}-${id}.png`;
+  ctx.write.binary(imageName, statePng);
+  const stateImage = PNG.sync.read(statePng);
+  const viewport = await client.send('Runtime.evaluate', { expression: '({w: window.innerWidth, h: window.innerHeight})', returnByValue: true }) as { result?: { value?: { w?: number; h?: number } } };
+  const w = viewport.result?.value?.w;
+  const h = viewport.result?.value?.h;
+  const available = typeof w === 'number' && w > 0 && typeof h === 'number' && h > 0;
+  const scaleX = available ? stateImage.width / w! : 1;
+  const scaleY = available ? stateImage.height / h! : 1;
+  const paddingCssPx = (ctx as import('../types.js').SnapshotContext & { stateDiffPaddingCssPx?: number }).stateDiffPaddingCssPx ?? DEFAULT_STATE_DIFF_PADDING_CSS_PX;
+  const raster: StateRasterArtifact = { screenshot: imageName, viewportScale: { available, innerWidth: available ? w! : 0, innerHeight: available ? h! : 0, scaleX: round3(scaleX), scaleY: round3(scaleY), ...(available ? {} : { unavailableReason: 'viewport-read-unavailable' as const }) }, diffCrop: { paddingCssPx, borderRect } };
+  const baseline = PNG.sync.read(fs.readFileSync(baselinePath));
+  if (baseline.width !== stateImage.width || baseline.height !== stateImage.height) return { ...raster, diffUnavailableReason: 'dimension-mismatch' };
+  const x0 = Math.max(0, Math.floor((borderRect.x - paddingCssPx) * scaleX));
+  const y0 = Math.max(0, Math.floor((borderRect.y - paddingCssPx) * scaleY));
+  const x1 = Math.min(stateImage.width, Math.ceil((borderRect.x + borderRect.width + paddingCssPx) * scaleX));
+  const y1 = Math.min(stateImage.height, Math.ceil((borderRect.y + borderRect.height + paddingCssPx) * scaleY));
+  const width = Math.max(1, x1 - x0);
+  const height = Math.max(1, y1 - y0);
+  const before = new PNG({ width, height });
+  const after = new PNG({ width, height });
+  PNG.bitblt(baseline, before, x0, y0, width, height, 0, 0);
+  PNG.bitblt(stateImage, after, x0, y0, width, height, 0, 0);
+  const diff = new PNG({ width, height });
+  const diffPixelCount = pixelmatch(before.data, after.data, diff.data, width, height, { threshold: 0.1, diffMask: true });
+  const diffName = `states/${sanitizeToken(state) || 'state'}-${id}-diff.png`;
+  ctx.write.binary(diffName, PNG.sync.write(diff));
+  let minX = width, minY = height, maxX = -1, maxY = -1;
+  for (let y = 0; y < height; y += 1) for (let x = 0; x < width; x += 1) {
+    const offset = (y * width + x) * 4;
+    if (diff.data[offset] || diff.data[offset + 1] || diff.data[offset + 2] || diff.data[offset + 3]) { minX = Math.min(minX, x); minY = Math.min(minY, y); maxX = Math.max(maxX, x); maxY = Math.max(maxY, y); }
+  }
+  const changedPixelBboxCss = maxX >= 0
+    ? { x: round3((x0 + minX) / scaleX), y: round3((y0 + minY) / scaleY), width: round3((maxX - minX + 1) / scaleX), height: round3((maxY - minY + 1) / scaleY) }
+    : undefined;
+  return { ...raster, diff: diffName, diffPixelCount, ...(changedPixelBboxCss ? { changedPixelBboxCss } : {}) };
+}
+
 /** Captures one requested state on one already-resolved node: baseline facts, force (when not `normal`), post-force facts, delta, and — always, even on error — restoration. */
 async function captureOneElement(
+  ctx: import('../types.js').SnapshotContext,
   client: CDPClient,
   selector: string,
   index: number,
@@ -722,6 +927,8 @@ async function captureOneElement(
 
   const axName = before.axName ? sanitizeString(before.axName, { max: MAX_STRING_LEN }) : undefined;
   const text = before.text ? sanitizeString(before.text, { max: MAX_STRING_LEN }) : undefined;
+  const population = await affectedSubjects(client, nodeId, { nodeId, relation: 'target', selector: resolvedSelector, backendNodeId, ...(identityUnresolved ? { identityUnresolved } : {}) });
+  const affectedBefore = await Promise.all(population.subjects.map((subject) => subject.nodeId === nodeId ? Promise.resolve(before) : evalFactsForNode(client, subject.nodeId, subject.backendNodeId)));
 
   if (state === 'normal') {
     const rect = before.rect!;
@@ -739,6 +946,16 @@ async function captureOneElement(
       geometry: zeroDelta(rect),
       style: { changed: [], before: style, after: style },
       hittest: { before: hit, after: hit, changed: false },
+      affected: {
+        elements: population.subjects.flatMap((subject, subjectIndex) => {
+          const facts = affectedBefore[subjectIndex]!;
+          const delta = deltaForFacts(facts, facts);
+          return delta ? [{ relation: subject.relation, selector: subject.selector, backendNodeId: subject.backendNodeId, ...(subject.identityUnresolved ? { identityUnresolved: true as const } : {}), ...delta }] : [];
+        }),
+        total: population.total,
+        kept: population.subjects.length,
+        truncated: population.total > population.subjects.length,
+      },
     };
   }
 
@@ -752,6 +969,8 @@ async function captureOneElement(
   let restored = true;
   let afterFactsUnavailableReason: FactsUnavailableReason | undefined;
   let forceReadUnavailableReason: ForceReadUnavailableReason | undefined;
+  let affectedAfter: ElementFacts[] = [];
+  let raster: StateRasterArtifact | undefined;
 
   try {
     if (isPseudo) {
@@ -805,6 +1024,8 @@ async function captureOneElement(
     }
 
     if (supported) {
+      await settleForcedState(client);
+      raster = await captureStateRaster(ctx, client, state, id, before.rect!);
       after = await evalFacts(client, selector, index);
       if (after.factsUnavailable) {
         supported = false;
@@ -813,9 +1034,8 @@ async function captureOneElement(
       } else if (!after.exists) {
         supported = false;
         reason = 'element no longer present after forcing state';
-      } else if (!(await identityStillMatches(client, selector, index, identity.backendNodeId))) {
-        supported = false;
-        reason = 'post-force facts no longer resolve to the original element (identity check failed)';
+      } else {
+        affectedAfter = await Promise.all(population.subjects.map((subject) => subject.nodeId === nodeId ? Promise.resolve(after!) : evalFactsForNode(client, subject.nodeId, subject.backendNodeId)));
       }
     }
   } catch (err) {
@@ -831,6 +1051,12 @@ async function captureOneElement(
     }
   }
 
+  // Re-resolving selector[index] can invalidate CSS's frontend node id, so it happens only after the `finally` restored the forced state.
+  if (supported && !(await identityStillMatches(client, selector, index, identity.backendNodeId))) {
+    supported = false;
+    reason = 'post-force facts no longer resolve to the original element (identity check failed)';
+  }
+
   if (!supported) {
     return {
       id,
@@ -866,6 +1092,16 @@ async function captureOneElement(
   const changedStyleProps = STYLE_PROPS.filter((p) => rawBeforeStyle[p] !== rawAfterStyle[p]);
   const hitChanged = beforeHit.isTarget !== afterHit.isTarget || beforeHit.topTag !== afterHit.topTag;
 
+  const affected = {
+    elements: population.subjects.flatMap((subject, subjectIndex) => {
+      const delta = deltaForFacts(affectedBefore[subjectIndex]!, affectedAfter[subjectIndex]!);
+      return delta ? [{ relation: subject.relation, selector: subject.selector, backendNodeId: subject.backendNodeId, ...(subject.identityUnresolved ? { identityUnresolved: true as const } : {}), ...delta }] : [];
+    }),
+    total: population.total,
+    kept: population.subjects.length,
+    truncated: population.total > population.subjects.length,
+  };
+
   return {
     id,
     state,
@@ -889,6 +1125,8 @@ async function captureOneElement(
     },
     style: { changed: changedStyleProps, before: beforeStyle, after: afterStyle },
     hittest: { before: beforeHit, after: afterHit, changed: hitChanged },
+    affected,
+    ...(raster ? { raster } : {}),
   };
 }
 
@@ -965,6 +1203,7 @@ export const collectStates: Collector = async (ctx) => {
       const nodeId = nodeIds[i];
       const identity = await describeNode(client, nodeId);
       const record = await captureOneElement(
+        ctx,
         client,
         selector,
         i,
@@ -980,7 +1219,7 @@ export const collectStates: Collector = async (ctx) => {
 
   ctx.write.json('states.json', {
     requested: ctx.state.map((s) => sanitizeString(s)),
-    scope: { root: 'top-document', shadowDom: 'light-only' },
+    scope: { root: 'top-document', shadowDom: 'light-only', affected: { descendants: true, peerSiblings: 'following-sibling-subtrees', maxElements: MAX_AFFECTED_ELEMENTS } },
     elements,
     truncatedRequests,
   });

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),
   ];