@crouton-kit/capture 1.3.21 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.21",
+  "version": "1.4.0",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/capture.ts

@@ -60,8 +60,9 @@ A CDP-enabled browser must be running; \`capture tab list\` is the probe, and
 \`capture tab launch\` starts one capture owns and reaps when nothing is (never
 hand-roll a detached browser — nothing reaps that). Capture never signals a
 browser it did not start, so attaching to your own with --port is unchanged.
-CDP_PORT / CDP_TARGET pin the browser + tab for orchestrators — precedence:
-explicit flag > active session > env.`;
+CDP_PORT / CDP_TARGET pin the browser + tab for target-selecting commands —
+precedence: explicit flag > active session > env. \`session start\` adopts only an
+explicit --target.`;
 }
 
 function printVersion(): void {

package/src/cdp/args.ts

@@ -19,6 +19,7 @@ const VALUE_FLAGS = new Set([
   '--filter', '--name', '--filter-url', '--filter-status', '--filter-method', '--limit', '--params', '--wait-event',
   '--timeout', '--socket', '--settle-timeout', '--state', '--for', '--before', '--after', '--snap', '--set-file',
   '--axis', '--from', '--to', '--viewport-height', '--rec-id', '--selector', '--do', '--element', '--prop', '--action', '--occurrence',
+  '--state-padding', '--crop', '--crop-selector', '--pad', '--zoom',
 ]);
 
 function valueFor(flag: string, next: string | undefined): string {
@@ -69,7 +70,7 @@ function validateKnownLeaf(command: string, positional: readonly string[]): void
   if (known && !known.includes(leaf)) throw invalidInput(`Unknown ${command} leaf: ${leaf}.`, 'unknown_command');
   if (command === 'measure' && leaf === 'map' && positional[1] !== undefined) {
     const mapLeaf = positional[1];
-    if (!['focus', 'scroll', 'layers', 'ax'].includes(mapLeaf)) throw invalidInput(`Unknown measure map leaf: ${mapLeaf}.`, 'unknown_command');
+    if (!['focus', 'scroll', 'layers', 'ax', 'paint'].includes(mapLeaf)) throw invalidInput(`Unknown measure map leaf: ${mapLeaf}.`, 'unknown_command');
   }
 }
 
@@ -107,6 +108,9 @@ export function validateCliInvocation(parsed: ParsedArgs): void {
     };
     const [min, max] = ranges[leaf];
     requireCount(values, min, max, `session ${leaf}`);
+    if (leaf === 'start' && parsed.url !== undefined && parsed.target !== undefined) {
+      throw invalidInput('session start cannot combine --url and --target.');
+    }
     return;
   }
 
@@ -169,7 +173,8 @@ export function validateCliInvocation(parsed: ParsedArgs): void {
       const mapLeaf = values[0];
       if (mapLeaf === undefined) return;
       const targets = values.slice(1);
-      requireCount(targets, mapLeaf === 'focus' || mapLeaf === 'ax' ? 1 : 0, 1, `measure map ${mapLeaf}`);
+      requireCount(targets, ['focus', 'ax', 'paint'].includes(mapLeaf) ? 1 : 0, 1, `measure map ${mapLeaf}`);
+      if (mapLeaf === 'paint' && !parsed.selector?.trim()) throw invalidInput('measure map paint requires --selector.');
     }
     return;
   }
@@ -261,6 +266,12 @@ export function parseCliSyntax(argv: string[]): ParsedArgs {
     else if (arg === '--skip-collector') { (parsed.skipCollector ??= []).push(valueFor(arg, next)); i++; }
     else if (arg === '--pixels') parsed.pixels = true;
     else if (arg === '--state') { (parsed.state ??= []).push(valueFor(arg, next)); i++; }
+    else if (arg === '--state-padding') { parsed.statePadding = integer(valueFor(arg, next), '--state-padding', 0, 16_384); i++; }
+    else if (arg === '--list-crops') parsed.listCrops = true;
+    else if (arg === '--crop') { parsed.crop = valueFor(arg, next); i++; }
+    else if (arg === '--crop-selector') { parsed.cropSelector = valueFor(arg, next); i++; }
+    else if (arg === '--pad') { parsed.pad = integer(valueFor(arg, next), '--pad', 0, 16_384); i++; }
+    else if (arg === '--zoom') { parsed.zoom = valueFor(arg, next); i++; }
     else if (arg === '--for') { parsed.for = valueFor(arg, next); i++; }
     else if (arg === '--before') { parsed.before = valueFor(arg, next); i++; }
     else if (arg === '--after') { parsed.after = valueFor(arg, next); i++; }
@@ -326,6 +337,10 @@ function needsEndpointResolution(parsed: ParsedArgs): boolean {
  */
 export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
   if (!needsEndpointResolution(parsed)) return parsed;
+  // Session start adopts only a target named in its invocation. CDP_TARGET is
+  // an ambient page-command default, not permission to publish a new session
+  // against an implicit tab.
+  const sessionStart = parsed.command === 'session' && parsed.positional[0] === 'start';
   const session = getActiveSession({ cleanStale: false });
   if (session) {
     if (!parsed.har && session.harId) parsed.har = session.harId;
@@ -344,7 +359,7 @@ export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
   // Preserve historical stale-index cleanup once endpoint validation has
   // succeeded; only the malformed-env throw path deliberately leaves it alone.
   if (!session) getActiveSession();
-  if (!parsed.target && !parsed.url && process.env.CDP_TARGET) { parsed.target = process.env.CDP_TARGET; parsed.targetSource = 'env'; }
+  if (!sessionStart && !parsed.target && !parsed.url && process.env.CDP_TARGET) { parsed.target = process.env.CDP_TARGET; parsed.targetSource = 'env'; }
   return parsed;
 }
 

package/src/cdp/commands/measure/explain.ts

@@ -3,15 +3,16 @@ import { explainSnapshot, type ExplainMissingSelector } from '../../measure/expl
 import { ArtifactResolutionError, resolveSnapRef } from '../../../output/artifact.js';
 import { data, emitResult, fact, line, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
 
-const USAGE = `capture measure explain <snap> --selector <sel> — per-element cascade/stacking/clipping explanation over one snapshot
+const USAGE = `capture measure explain <snap> --selector <sel> — per-element cascade, ink-box, stacking, and clipping measurements over one snapshot
 
 input:
   <snap>             snapshot id in the active session or absolute artifact path (required)
-  --selector <sel>   element selector (required): CSS, backend:<id>, axid:<id>, ax:<name>, or text:<text>
+  --selector <sel>   element selector (required): CSS tag/#id/.class/[attr]/[attr="value"] compounds with descendant or child relations (or a verbatim recorded path), backend:<id>, axid:<id>, ax:<name>, or text:<text>
+  --state <name>     one recorded forced state; derives border/ink and clipping comparisons from its post-force target values
   --size             include size/layout provenance (box/flex/grid/constraints)
   --text             include text line/baseline/font/wrap metrics
   --form             include form value/geometry/caret/selection/autofill facts
-output: <explain selector=… matches=…> — the compact element explanation, plus one section per requested detail flag; --json mirrors
+output: <explain selector=… matches=…> — border/ink boxes with named paint contributors and rectangular overflow padding-box comparisons, each naming its base or forced-state provenance; unavailable forced-state or captured box evidence is stated explicitly; --json mirrors
 effects: read-only — reads existing snapshot artifacts, never drives the browser`;
 
 function attestation(ref: { id: string; dir: string }, meta: { settled?: boolean; settleMs?: number }) {
@@ -44,13 +45,16 @@ function caveatSuffix(caveats: readonly { regionId: string; selector?: string; r
 }
 
 function recoverySections(missing: ExplainMissingSelector): FactLine[] {
-  const { candidates, recordCount, kind } = missing.available;
+  const { candidates, recordCount, kind, interpretedValue } = missing.available;
   const label = kind === 'css' ? 'CSS selectors' : `${kind}: selector inputs`;
   const rows = candidates.length
     ? candidates.map((candidate, index) => fact`${index + 1}. ${candidate}`)
     : [fact`No recorded ${label} were available from geometry records.`];
+  const ranking = interpretedValue
+    ? fact`Recovery candidates: ${candidates.length} shown from ${recordCount} geometry record(s); AX-name/text inputs for attribute or quoted value ${interpretedValue} rank before generated CSS paths, then identifier similarity and string distance rank each group.`
+    : fact`Nearest recorded ${label}: ${candidates.length} shown from ${recordCount} geometry record(s), ranked by identifier similarity then string distance from the requested selector.`;
   return [
-    fact`Nearest recorded ${label}: ${candidates.length} shown from ${recordCount} geometry record(s), ranked by identifier similarity then string distance from the requested selector.`,
+    ranking,
     lineList(rows),
     text`All recorded selector and identity facts remain in this snapshot's geometry.json, ax.json, and text.json artifacts.`,
   ];
@@ -80,10 +84,20 @@ export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Pr
     process.exitCode = 1;
     return;
   }
+  if ((parsed.state?.length ?? 0) > 1) {
+    emitResult(invalidInput(fact`Expected at most one --state value; received ${parsed.state!.length}.`), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.state?.[0] === '') {
+    emitResult(invalidInput(text`The --state value must be a nonempty recorded state name.`), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
 
   try {
     const ref = await resolveSnapRef(parsed.positional[0]!);
-    const report = explainSnapshot(ref, parsed.selector, { size: parsed.size, text: parsed.text, form: parsed.form });
+    const report = explainSnapshot(ref, parsed.selector, { size: parsed.size, text: parsed.text, form: parsed.form, state: parsed.state?.[0] });
     if (report.kind === 'missing-selector') {
       emitResult({
         tag: 'error',
@@ -112,8 +126,9 @@ export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Pr
         size: Boolean(parsed.size),
         text: Boolean(parsed.text),
         form: Boolean(parsed.form),
+        state: parsed.state?.[0] ?? 'base',
       },
-      summary: fact`Recorded cascade, stacking, clipping, focus, scroll, query, and state context for ${targetSelector}.`,
+      summary: fact`Recorded cascade, border/ink geometry, stacking, clipping, focus, scroll, query, and state context for ${targetSelector}${parsed.state?.[0] ? ` under requested state ${parsed.state[0]}` : ' from base-state artifacts'}.`,
       sections,
       followUp: parsed.size || parsed.text || parsed.form
         ? text`Re-run against a new snapshot to compare the same recorded measurements after a page change.`

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

@@ -19,12 +19,13 @@ import { cmdMeasureMapFocus } from './map-focus.js';
 import { cmdMeasureMapScroll } from './map-scroll.js';
 import { cmdMeasureMapLayers } from './map-layers.js';
 import { cmdMeasureMapAx } from './map-ax.js';
+import { cmdMeasureMapPaint } from './map-paint.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="measure">
 static facts over a settled snapshot — \`snap\` writes the substrate, every other leaf is a read-only query over it
-use when measuring layout/content/targetability facts, diffing snapshots, or reading one facet (focus, scroll, layers, ax) of the substrate
-  snap · check · diff · census · explain · sweep · map — \`capture measure -h\`
+use when measuring layout/content/targetability facts, diffing snapshots, or reading one facet (focus, scroll, layers, ax, paint) of the substrate
+  snap · check · diff · census · explain · sweep · map (focus|scroll|layers|ax|paint) — \`capture measure -h\`
 </command>`;
 
 export const MEASURE_USAGE = `capture measure — enriched snapshot substrate + read-only queries over it.
@@ -42,18 +43,19 @@ Findings exit 0 — a report, not a failure.
 <subcommand name="census" args="[--snap <id>]... [--url <url>]... [--set-file <path>] --axis <axis>" whenToUse="value distributions across one or more snapshots"/>
 <subcommand name="explain" args="<snap> --selector <sel> [--size] [--text] [--form]" whenToUse="per-element cascade/stacking/clipping/size/text/form explanation"/>
 <subcommand name="sweep" args="[url] --axis <axis> [--from <val>] [--to <val>] [--viewport-height <val>]" whenToUse="responsive/environment sampling across an axis"/>
-<subcommand name="map" args="focus|scroll|layers|ax [url|snap]" whenToUse="read one facet of a snapshot's substrate — capture measure map -h"/>
+<subcommand name="map" args="focus|scroll|layers|ax [url|snap] | paint <snap> --selector <target> [--state <name>]" whenToUse="read one facet of a snapshot's substrate — capture measure map -h"/>
 
 capture measure <leaf> -h    Per-leaf usage`;
 
 export const MEASURE_MAP_USAGE = `capture measure map — read one facet of a snapshot's substrate (no browser re-drive).
 
-A URL target first creates a snap; a snap target reads its existing artifact.
+Focus, scroll, layers, and ax accept a URL target and create a snap first; paint requires an existing snapshot and reads it without browser driving.
 
 <subcommand name="focus" args="[url|snap]" whenToUse="keyboard traversal order (focus.json)"/>
 <subcommand name="scroll" args="[url|snap]" whenToUse="scroll-container topology (scroll.json)"/>
 <subcommand name="layers" args="[url|snap]" whenToUse="paint/compositor layer map (layers.json)"/>
 <subcommand name="ax" args="[url|snap]" whenToUse="AX-tree ↔ layout map (ax.json + geometry.json)"/>
+<subcommand name="paint" args="<snap> --selector <target> [--state <name>]" whenToUse="elements painted above one target and their recorded AABB coverage (geometry.json + layers.json)"/>
 
 capture measure map <leaf> -h    Per-leaf usage`;
 
@@ -97,6 +99,8 @@ async function measureMapMain(parsed: ParsedArgs, args: string[]): Promise<void>
       return cmdMeasureMapLayers(rest, args);
     case 'ax':
       return cmdMeasureMapAx(rest, args);
+    case 'paint':
+      return cmdMeasureMapPaint(rest, args);
     case undefined:
       console.log(MEASURE_MAP_USAGE);
       return;

package/src/cdp/commands/measure/map-paint.ts

@@ -0,0 +1,273 @@
+import { type ParsedArgs } from '../../types.js';
+import { ArtifactResolutionError, readGeometry, readLayers, readMeta, readStates, resolveSnapRef, type SnapRef } from '../../../output/artifact.js';
+import { resolveSelectorInput, type ElementRecord } from '../../../output/selector.js';
+import { deriveInkBox, type InkRect } from '../../measure/ink.js';
+import { baseInkSource, forcedStateInkSource, isInkSource } from '../../measure/ink-source.js';
+import { emitResult, fact, line, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture measure map paint <snap> --selector <target> [--state <name>] — recorded AABB coverage by elements painted above one target
+
+input:
+  <snap>              snapshot id in the active session or absolute artifact path (required)
+  --selector <target> recorded element selector or backend:<id> (required)
+  --state <name>      one forced state recorded in states.json; uses that target's post-force border box and computed paint styles
+output: <paint-map …> — target border and ink boxes; visible non-subtree elements after the target in DOMSnapshot back-to-front paint order; each AABB intersection area and fraction of each target box; --json mirrors
+limits: DOMSnapshot order ranks painted layout nodes, not pixel fragments. Coverage is axis-aligned border/ink-box intersection over recorded geometry, not a pixel-exact paint test.
+effects: read-only — reads geometry.json, layers.json, and (with --state) states.json from an existing snapshot; never drives a browser or writes an artifact`;
+
+interface GeometryElement extends ElementRecord {
+  readonly tag?: string;
+  readonly domPath?: string;
+  readonly frame?: { readonly frameId?: string };
+  readonly boxModel?: Record<string, unknown> | null;
+  readonly paint?: Record<string, string | null>;
+  readonly zIndex?: string;
+  readonly visibility?: { readonly visible?: boolean; readonly opacity?: number };
+}
+
+interface PaintOrderReport {
+  readonly paintOrder?: { readonly available?: boolean; readonly reason?: string; readonly backendNodeIds?: readonly number[]; readonly truncated?: number };
+}
+
+interface SourceBox {
+  readonly border: InkRect;
+  readonly ink: InkRect | null;
+  readonly provenance: string;
+  readonly inkUnavailable?: string;
+}
+
+interface Intersection {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly area: number;
+}
+
+interface Occluder {
+  readonly element: GeometryElement;
+  readonly rank: number;
+  readonly border: Intersection;
+  readonly ink: Intersection | null;
+}
+
+interface CoverageUnavailable {
+  readonly element: GeometryElement;
+  readonly rank: number;
+  readonly reason: string;
+}
+
+function area(rect: InkRect): number {
+  return rect.width * rect.height;
+}
+
+function intersection(a: InkRect, b: InkRect): Intersection | null {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  const width = right - x;
+  const height = bottom - y;
+  if (width <= 0 || height <= 0) return null;
+  return { x, y, width, height, area: width * height };
+}
+
+function relatedInTree(a: GeometryElement, b: GeometryElement): boolean {
+  if (!a.domPath || !b.domPath) return false;
+  if (a.frame?.frameId !== b.frame?.frameId) return false;
+  return a.domPath.startsWith(`${b.domPath}/`) || b.domPath.startsWith(`${a.domPath}/`);
+}
+
+function paints(element: GeometryElement): boolean {
+  return element.visibility?.visible === true && typeof element.visibility.opacity === 'number' && element.visibility.opacity > 0;
+}
+
+function formatBox(box: InkRect): string {
+  return `x=${box.x}…${box.x + box.width} y=${box.y}…${box.y + box.height} (w=${box.width} h=${box.height} area=${area(box)}px²)`;
+}
+
+function formatIntersection(value: Intersection): string {
+  return `x=${value.x}…${value.x + value.width} y=${value.y}…${value.y + value.height}; area=${value.area}px²`;
+}
+
+function percentage(covered: number, total: number): string {
+  return total > 0 ? `${(covered / total * 100).toFixed(2)}%` : 'unavailable';
+}
+
+function targetBox(target: GeometryElement, state?: string, states?: unknown): SourceBox | { readonly unavailable: string } {
+  const source = state === undefined
+    ? baseInkSource(target)
+    : forcedStateInkSource(states, target, state);
+  if (!isInkSource(source)) return source;
+  const ink = deriveInkBox(source.rect, source.styles);
+  if (ink.inkBox) return { border: source.rect, ink: ink.inkBox, provenance: source.provenance };
+  const inkUnavailable = ink.missingStyles.length
+    ? `computed styles were not captured: ${ink.missingStyles.join(', ')}`
+    : `paint extents could not be resolved: ${ink.unresolved.join(', ')}`;
+  return { border: source.rect, ink: null, provenance: source.provenance, inkUnavailable };
+}
+
+function missingSelectorResult(ref: SnapRef, selector: string): RenderableResult {
+  return {
+    tag: 'error',
+    attestation: { kind: 'snapshot', id: ref.id, path: ref.dir },
+    attrs: { command: 'measure map paint', status: 'missing_selector', selector },
+    summary: fact`No geometry record matched selector input ${selector}.`,
+    followUp: text`Use a recorded selector or backend:<id> from geometry.json.`,
+  };
+}
+
+export function buildMeasureMapPaintResult(ref: SnapRef, selector: string, state?: string): RenderableResult {
+  const geometry = readGeometry<{ elements?: GeometryElement[] }>(ref).elements ?? [];
+  const matches = resolveSelectorInput(geometry, selector) as GeometryElement[];
+  if (!matches.length) return missingSelectorResult(ref, selector);
+
+  const target = matches[0]!;
+  const source = targetBox(target, state, state === undefined ? undefined : readStates(ref));
+  const meta = readMeta<{ settled?: boolean }>(ref);
+  const targetName = target.selector ?? target.id;
+  if ('unavailable' in source) {
+    return {
+      tag: 'paint-map',
+      attestation: { kind: 'snapshot', id: ref.id, path: ref.dir, note: meta.settled === false ? text`Snapshot was captured unsettled.` : text`Snapshot was settled before its geometry was captured.` },
+      attrs: { selector: targetName, matches: matches.length, state: state ?? 'base', status: 'ink_source_unavailable' },
+      summary: fact`Paint coverage could not use the target's ${state === undefined ? 'base-state' : `forced ${state} state`} border and ink source: ${source.unavailable}.`,
+      followUp: text`Reacquire the snapshot with the target's border box and required paint styles recorded.`,
+    };
+  }
+
+  const report = readLayers<PaintOrderReport>(ref);
+  const paintOrder = report.paintOrder;
+  const ids = paintOrder?.backendNodeIds ?? [];
+  const rankByBackend = new Map<number, number>();
+  ids.forEach((id, index) => rankByBackend.set(id, index));
+  const targetRank = typeof target.backendNodeId === 'number' ? rankByBackend.get(target.backendNodeId) : undefined;
+  const orderUnavailable = !paintOrder?.available
+    ? `DOMSnapshot paint order was unavailable${paintOrder?.reason ? `: ${paintOrder.reason}` : ''}`
+    : paintOrder.truncated && paintOrder.truncated > 0
+      ? `DOMSnapshot paint order omitted ${paintOrder.truncated} backend node id(s) at the collector cap`
+      : targetRank === undefined
+        ? `the target's backend node id was not present in recorded DOMSnapshot paint order`
+        : undefined;
+  if (orderUnavailable) {
+    return {
+      tag: 'paint-map',
+      attestation: { kind: 'snapshot', id: ref.id, path: ref.dir, note: meta.settled === false ? text`Snapshot was captured unsettled.` : text`Snapshot was settled before its geometry was captured.` },
+      attrs: { selector: targetName, matches: matches.length, state: state ?? 'base', status: 'paint_order_unavailable' },
+      summary: fact`Paint coverage is unavailable because ${orderUnavailable}.`,
+      sections: [
+        fact`Target border box from ${source.provenance}: ${formatBox(source.border)}.`,
+        source.ink ? fact`Target ink box: ${formatBox(source.ink)}.` : fact`Target ink box was unavailable because ${source.inkUnavailable}.`,
+        text`Criterion: DOMSnapshot backend-node paint order is required as the back-to-front stacking-order source; no z-index fallback is inferred.`,
+      ],
+      followUp: text`Reacquire a snapshot whose layers collector records DOMSnapshot paint order.`,
+    };
+  }
+
+  const occluders: Occluder[] = [];
+  const coverageUnavailable: CoverageUnavailable[] = [];
+  for (const candidate of geometry) {
+    if (candidate.id === target.id || typeof candidate.backendNodeId !== 'number' || !paints(candidate) || relatedInTree(candidate, target)) continue;
+    const rank = rankByBackend.get(candidate.backendNodeId);
+    if (rank === undefined || rank <= targetRank) continue;
+    const candidateBox = baseInkSource(candidate);
+    if (!isInkSource(candidateBox)) {
+      coverageUnavailable.push({ element: candidate, rank, reason: candidateBox.unavailable });
+      continue;
+    }
+    const border = intersection(source.border, candidateBox.rect);
+    if (!border) continue;
+    const ink = source.ink ? intersection(source.ink, candidateBox.rect) : null;
+    occluders.push({ element: candidate, rank, border, ink });
+  }
+  occluders.sort((a, b) => a.rank - b.rank || a.element.id.localeCompare(b.element.id));
+  coverageUnavailable.sort((a, b) => a.rank - b.rank || a.element.id.localeCompare(b.element.id));
+
+  const sections: FactLine[] = [
+    fact`Target ${targetName}${matches.length > 1 ? ` matched ${matches.length} geometry records; this report uses the first in snapshot order` : ''}.`,
+    fact`Target border box from ${source.provenance}: ${formatBox(source.border)}.`,
+    source.ink
+      ? fact`Target ink box from ${source.provenance}: ${formatBox(source.ink)}.`
+      : fact`Target ink box was unavailable because ${source.inkUnavailable}.`,
+    text`Paint-order criterion: DOMSnapshot backend-node paint order is ascending back-to-front. Eligible occluders have a recorded rank after the target, visible=true, opacity>0, and are outside the target's DOM subtree and ancestor chain. Coverage is AABB intersection over recorded border/ink geometry, not a pixel-exact paint test.`,
+  ];
+  if (coverageUnavailable.length) {
+    sections.push(lineList(coverageUnavailable.map((candidate, index) => {
+      const name = candidate.element.selector ?? candidate.element.id;
+      return fact`Coverage unavailable ${index + 1}. ${name}: DOMSnapshot paint rank ${candidate.rank}; ${candidate.reason}.`;
+    })));
+  }
+  if (!occluders.length) {
+    sections.push(coverageUnavailable.length
+      ? text`No measured AABB intersection was available among candidates with captured border boxes; the occluder set is not exhaustive because coverage is unavailable for the recorded candidate(s) above.`
+      : text`No eligible recorded elements painted above the target intersect either target box; the occluder set is empty.`);
+  } else {
+    const borderArea = area(source.border);
+    const inkArea = source.ink ? area(source.ink) : 0;
+    sections.push(lineList(occluders.map((occluder, index) => {
+      const name = occluder.element.selector ?? occluder.element.id;
+      const inkCoverage = source.ink
+        ? occluder.ink
+          ? `; ink-box intersection ${formatIntersection(occluder.ink)} (${percentage(occluder.ink.area, inkArea)} of target ink box)`
+          : `; ink-box intersection none (0.00% of target ink box)`
+        : `; ink-box coverage unavailable because the target ink box was unavailable`;
+      return fact`${index + 1}. ${name}: DOMSnapshot paint rank ${occluder.rank} (target rank ${targetRank}); z-index=${occluder.element.zIndex ?? 'not recorded'}; border-box intersection ${formatIntersection(occluder.border)} (${percentage(occluder.border.area, borderArea)} of target border box)${inkCoverage}.`;
+    })));
+  }
+
+  return {
+    tag: 'paint-map',
+    attestation: { kind: 'snapshot', id: ref.id, path: ref.dir, note: meta.settled === false ? text`Snapshot was captured unsettled.` : text`Snapshot was settled before its geometry was captured.` },
+    attrs: { selector: targetName, matches: matches.length, state: state ?? 'base', occluders: occluders.length, 'coverage-unavailable': coverageUnavailable.length, 'paint-order': 'domsnapshot-back-to-front', settled: meta.settled ?? 'unknown' },
+    summary: fact`Recorded elements painting above ${targetName} are measured against both its border box and its derived ink box.`,
+    sections,
+    followUp: text`Use capture measure explain <snap> --selector <selector> for the target's captured stacking and clipping provenance.`,
+  };
+}
+
+function invalidInput(message: FactLine): RenderableResult {
+  return {
+    tag: 'error',
+    attrs: { command: 'measure map paint', status: 'invalid_input' },
+    summary: message,
+    followUp: text`Run capture measure map paint <snap> --selector <target> [--state <name>].`,
+  };
+}
+
+export async function cmdMeasureMapPaint(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (parsed.positional.length !== 1) {
+    emitResult(invalidInput(fact`Expected exactly one snapshot target; received ${parsed.positional.length}.`), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (!parsed.selector?.trim()) {
+    emitResult(invalidInput(text`The --selector flag is required.`), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if ((parsed.state?.length ?? 0) > 1) {
+    emitResult(invalidInput(fact`Expected at most one --state value; received ${parsed.state!.length}.`), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const ref = await resolveSnapRef(parsed.positional[0]!);
+    const result = buildMeasureMapPaintResult(ref, parsed.selector, parsed.state?.[0]);
+    emitResult(result, { json: parsed.json });
+    if (result.tag === 'error' || result.attrs?.status === 'ink_source_unavailable' || result.attrs?.status === 'paint_order_unavailable') process.exitCode = 1;
+  } catch (error) {
+    const detail = error instanceof ArtifactResolutionError || error instanceof Error ? error.message : String(error);
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure map paint', status: 'artifact_unavailable' },
+      summary: fact`Paint-map facts could not be read: ${detail}`,
+      followUp: text`Pass a snapshot id or absolute artifact path created by capture measure snap.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
+  }
+}

package/src/cdp/commands/measure/snap.ts

@@ -35,7 +35,9 @@ input:
   --capture-unsettled         write the full substrate despite non-settlement, marking unstable regions
   --skip-collector <name>     leave one collector out entirely (repeatable): ax, styles, queries, animation, layers, media, geometry, hittest, text, forms, focus, scroll, states, pixels. A collector that fails is recorded and skipped; every other collector's substrate is still written
   --pixels                    also write per-element raster crops
-  --state <state[:selector]>  force a pseudo-state or real control state (repeatable)
+  --list-crops                print every crop artifact path (default prints crop count and crops/ directory only)
+  --state <state[:selector]>  force a pseudo-state or real control state (repeatable); each supported forced element records target/descendant/following-peer style rows and state image/diff artifacts
+  --state-padding <px>        CSS-pixel padding around the target border box in each forced-state diff crop (default 8)
   --viewport <WxH>            temporarily capture at a CSS-pixel viewport (repeatable); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
   --color-scheme <dark|light> temporarily capture under this prefers-color-scheme value; cleared afterward
 output: <snapshot id=… path=…> — the settled artifact directory (geometry, styles, hit-test, text, forms, animation, ax, queries, focus, scroll, layers; per-element crops with --pixels) every other measure/motion query leaf reads instead of re-driving the browser; --json mirrors
@@ -48,8 +50,11 @@ interface SnapshotMetaForBase {
 export interface MeasureSnapCapture {
   readonly id: string;
   readonly dir: string;
+  /** A bare ID only resolves while its owning session remains active. */
+  readonly queryRef: string;
   readonly base?: SnapRef;
   readonly artifacts: readonly string[];
+  readonly listCrops?: boolean;
 }
 
 interface ViewportSpec extends Viewport {
@@ -69,18 +74,38 @@ function readArrayCount(filePath: string, field: string): number | undefined {
   }
 }
 
-function artifactEntries(dir: string, artifacts: readonly string[]): ArtifactEntry[] {
+function artifactEntries(dir: string, artifacts: readonly string[], listCrops: boolean): ArtifactEntry[] {
   const entries: ArtifactEntry[] = [];
   const geometryCount = readArrayCount(path.join(dir, 'geometry.json'), 'elements');
+  const crops = artifacts.filter((name) => name.startsWith('crops/'));
   for (const name of artifacts) {
+    if (!listCrops && name.startsWith('crops/')) continue;
     entries.push({
       name,
       ...(name === 'geometry.json' && geometryCount !== undefined ? { note: `${geometryCount} elements` } : {}),
     });
   }
+  if (!listCrops && crops.length) entries.push({ name: 'crops/', note: `${crops.length} crops; pass --list-crops for paths` });
   return entries;
 }
 
+interface StateSummaryAffected { readonly relation?: string; readonly selector?: string; readonly style?: { readonly changed?: readonly string[] }; }
+interface StateSummaryElement { readonly state?: string; readonly supported?: boolean; readonly style?: { readonly changed?: readonly string[] }; readonly affected?: { readonly elements?: readonly StateSummaryAffected[] }; }
+
+function stateSummary(dir: string): ReturnType<typeof fact> | undefined {
+  try {
+    const value = JSON.parse(fs.readFileSync(path.join(dir, 'states.json'), 'utf8')) as { readonly elements?: readonly StateSummaryElement[] };
+    const lines = (value.elements ?? []).filter((element) => element.supported).map((element) => {
+      const target = element.style?.changed ?? [];
+      const descendants = (element.affected?.elements ?? []).filter((affected) => affected.relation !== 'target' && (affected.style?.changed?.length ?? 0) > 0).map((affected) => `${affected.relation} ${affected.selector ?? '<identity unavailable>'}: ${(affected.style?.changed ?? []).join(', ')}`);
+      return `${element.state ?? 'state'} target style changes=${target.length ? target.join(', ') : 'none'}${descendants.length ? `; descendant/peer changes=${descendants.join('; ')}` : ''}`;
+    });
+    return lines.length ? fact`Forced state measurements: ${lines.join(' | ')}.` : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 type ViewportClient = { send: (method: string, params?: Record<string, unknown>) => Promise<unknown> };
 
 type ViewportOwnership =
@@ -277,13 +302,14 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
           viewport: viewport?.label ?? null,
           colorScheme,
           skipCollectors: parsed.skipCollector ?? [],
+          ...({ stateDiffPaddingCssPx: parsed.statePadding ?? 8 } as {}),
         });
         artifacts = result.artifacts;
       }));
     }, { settle: 0 });
 
     if (!snapDir) throw new Error('measure snap did not allocate an artifact directory');
-    return { id: snapId, dir: snapDir, artifacts, ...(base ? { base } : {}) };
+    return { id: snapId, dir: snapDir, queryRef: active ? snapId : snapDir, artifacts, ...(base ? { base } : {}) };
   } catch (err) {
     if (allocatedRoot && !(err instanceof SnapshotCaptureTimeout)) removeArtifactTree(allocatedRoot);
     throw err;
@@ -304,8 +330,9 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
   }>({ kind: 'snap', id: captured.id, dir: captured.dir });
   const incomplete = (meta.collectors ?? []).filter((c) => c.status !== 'ok');
   const elements = readArrayCount(path.join(captured.dir, 'geometry.json'), 'elements');
-  const artifacts = artifactEntries(captured.dir, captured.artifacts);
+  const artifacts = artifactEntries(captured.dir, captured.artifacts, Boolean(captured.listCrops));
   const capturedFullSubstrate = fs.existsSync(path.join(captured.dir, 'geometry.json'));
+  const stateMeasurement = stateSummary(captured.dir);
 
   return {
     tag: 'snapshot',
@@ -332,10 +359,10 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
     // not only in meta.json — its artifact is absent (timeout/error/skipped)
     // or partly built from timed-out reads (degraded), and a caller who reads
     // the remaining substrate as a whole page would be reading a hole.
-    ...(incomplete.length ? { sections: [collectorNote(incomplete)] } : {}),
+    ...((incomplete.length || stateMeasurement) ? { sections: [...(incomplete.length ? [collectorNote(incomplete)] : []), ...(stateMeasurement ? [stateMeasurement] : [])] } : {}),
     artifacts: formatArtifactList(artifacts),
     followUp: meta.settled || capturedFullSubstrate
-      ? fact`Query snapshot ${captured.id} with \`capture measure check ${captured.id}\`, \`capture measure census --snap ${captured.id} --axis color\`, or \`capture measure map focus ${captured.id}\`.`
+      ? fact`Query snapshot ${captured.id} with \`capture measure check ${captured.queryRef}\`, \`capture measure census --snap ${captured.queryRef} --axis color\`, or \`capture measure map focus ${captured.queryRef}\`.`
       : fact`Re-run with \`--freeze-animations\`, a longer \`--settle-timeout\`, or \`--capture-unsettled\` to choose a queryable capture.`,
   };
 }
@@ -417,7 +444,7 @@ export async function cmdMeasureSnap(parsed: ParsedArgs, _args: string[]): Promi
     const colorScheme = parseColorScheme(parsed.colorScheme);
     const results = [] as RenderableResult[];
     for (const viewport of viewports) {
-      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport?.label, colorScheme);
+      const capture = { ...(await captureMeasureSnap(parsed, parsed.positional[0], viewport?.label, colorScheme)), ...(parsed.listCrops ? { listCrops: true } : {}) };
       captures.push(capture);
       results.push(buildSnapshotResult(capture));
     }

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

@@ -50,7 +50,7 @@ input:
   <code>           JS source as one argument (exactly one of <code> / --file)
   --file <path>    read the JS source from a file instead of inline
   --settle <ms>    network-settle window after execution so an active session's HAR captures the requests the code triggers (default: ${DEFAULT_SETTLE_MS}; 0 disables); the block reports the measured requested/waited settle
-  --target <id>    target a tab explicitly (default: the active session tab; with no active session, --target or --url is required)
+  --target <id>    target a tab explicitly (default: the active session tab, else exactly one available page tab; multiple page tabs require --target or --url)
   --url <pattern>  target the first tab whose URL matches <pattern>
 output:
   <exec-result result-chars=…> — the JSON-serialized return value inline, escaped and capped at ${GENEROUS_RESULT_CAP} chars; a larger result is also written whole to a private artifact file (the active session's page/ dir, else a one-shot artifact dir) whose absolute path appears in the block. --json mirrors the same block with the value at full fidelity.

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

@@ -22,7 +22,7 @@ import { cmdPageElements } from './elements.js';
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="page">
 verbs against the live session tab — act (click, type, scroll, navigate, exec) and look (shot, elements)
-use when driving or inspecting the page a session opened; all verbs auto-target the active session tab, --target/--url override
+use when driving or inspecting the tab a session opened or adopted; all verbs auto-target the active session tab, --target/--url override
   click · type · scroll · navigate · exec · shot · elements — \`capture page -h\`
 </command>`;
 
@@ -39,7 +39,7 @@ During a live composed recording every verb routes through the recorder.
 <subcommand name="scroll" args="<target> --to <top|bottom|px> [--no-screenshot]" whenToUse="scroll one resolved container to a position"/>
 <subcommand name="navigate" args="<url> [--settle <ms>]" whenToUse="navigate the tab and wait for load + settle"/>
 <subcommand name="exec" args="<code> | --file <path>" whenToUse="run arbitrary JS in the tab (expressions, return, await)"/>
-<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]" whenToUse="look at the page right now without acting"/>
+<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--crop <x,y,w,h> | --crop-selector <sel> [--pad <px>]] [--zoom <factor>] [--out <path>]" whenToUse="look at the page right now without acting"/>
 <subcommand name="elements" args="[--all] [--limit <n>]" whenToUse="list what can be acted on — role, name, backend:<id> per element"/>
 
 capture page <leaf> -h    Per-leaf usage`;