@crouton-kit/capture 1.3.8 → 1.3.9

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

@@ -1,31 +1,87 @@
+import * as fs from 'fs';
+
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import { captureMeasureSnap } from './snap.js';
+import { ArtifactResolutionError, resolveSnapRef, type SnapRef } from '../../../output/artifact.js';
+import { emitResult, fact, formatArtifactList, text, type RenderableResult } from '../../../output/render.js';
+import { buildCensus, CENSUS_AXES, censusResultLines, type CensusAxis } from '../../measure/census.js';
 
-const USAGE = `Usage: capture measure census [--snap <id>]... [--url <url>]... [--set-file <path>] --axis <axis>
+const USAGE = `capture measure census --axis <axis> — value distributions and token-audit facts across one or more settled snapshots
 
-Value distributions and token audits across one or more snapshots. Each
---snap/--url is repeatable to build a cross-page distribution; a --url
-target creates a one-shot snap first.
+input:
+  --axis <axis>       color|font|spacing|radius|shadow|animation|geometry|media|queries (required)
+  --snap <id|path>    existing snapshot id or absolute artifact path (repeatable)
+  --url <url>         URL to snap first (repeatable)
+  --set-file <path>   file listing one snapshot id/path or URL per line
+output: <census axis=… snapshots=… distinct=…> — distributions with provenance where recorded, and per-region nondeterminism caveats for facts touching an unsettled capture; --json mirrors
+effects: read-only over existing snapshot artifacts; each --url writes one one-shot snapshot first`;
 
-Options:
-  --snap <id>          Existing snapshot id/path (repeatable)
-  --url <url>          URL to snap first (repeatable)
-  --set-file <path>    File listing additional snap/url targets, one per line
-  --viewport <WxH>     Viewport to snap at (repeatable)
-  --axis <axis>        color|font|spacing|radius|shadow|animation|geometry|media|queries
+function targetsFromFile(filePath: string): string[] {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+}
 
-Not yet implemented.`;
+function isAxis(value: string | undefined): value is CensusAxis {
+  return value !== undefined && (CENSUS_AXES as readonly string[]).includes(value);
+}
+
+async function resolveTargets(parsed: ParsedArgs): Promise<SnapRef[]> {
+  const targetRefs = [...(parsed.snap ?? []), ...(parsed.urls ?? [])];
+  if (parsed.setFile) targetRefs.push(...targetsFromFile(parsed.setFile));
+  if (!targetRefs.length) throw new Error('census needs at least one --snap, --url, or --set-file target');
+
+  const snaps: SnapRef[] = [];
+  for (const target of targetRefs) {
+    snaps.push(await resolveSnapRef(target, {
+      onUrl: async (url) => {
+        const captured = await captureMeasureSnap({ ...parsed, positional: [], url, target: undefined }, url);
+        return captured;
+      },
+    }));
+  }
+  return snaps;
+}
+
+function errorResult(message: string, status: string): RenderableResult {
+  return {
+    tag: 'error',
+    attrs: { command: 'measure census', status },
+    summary: fact`Census could not read the requested measurement artifacts: ${message}`,
+    followUp: text`Create a settled snapshot with capture measure snap, then pass its id or absolute artifact path.`,
+  };
+}
 
 export async function cmdMeasureCensus(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
-    process.exit(0);
+    return;
+  }
+  if (parsed.positional.length) {
+    emitResult(errorResult('this leaf takes targets only through repeatable --snap and --url flags.', 'invalid_input'), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (!isAxis(parsed.axis)) {
+    emitResult(errorResult(`--axis must be one of ${CENSUS_AXES.join('|')}; received ${parsed.axis ?? '(missing)'}.`, 'invalid_axis'), { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const snapshots = await resolveTargets(parsed);
+    const report = buildCensus(parsed.axis, snapshots);
+    const result: RenderableResult = {
+      tag: 'census',
+      attrs: { axis: report.axis, snapshots: snapshots.length, distinct: report.distinct },
+      summary: fact`Distribution facts were measured from ${snapshots.length} snapshot artifact(s).`,
+      artifacts: formatArtifactList(snapshots.map((snap) => ({ name: snap.dir, note: snap.id }))),
+      sections: [censusResultLines(report)],
+      followUp: fact`Use capture measure explain ${snapshots[0].id} --selector <selector> for one element's recorded provenance.`,
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (err) {
+    const detail = err instanceof ArtifactResolutionError || err instanceof Error ? err.message : String(err);
+    emitResult(errorResult(detail, 'artifact_unavailable'), { json: parsed.json });
+    process.exitCode = 1;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure census', status: 'not_implemented' },
-    summary: fact`\`measure census\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
 }

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

@@ -1,35 +1,109 @@
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import { resolveSnapRef, readMeta, type ArtifactResolutionError } from '../../../output/artifact.js';
+import { emitResult, fact, line, text, formatFindings, type FindingInput, type RenderableResult } from '../../../output/render.js';
+import { captureMeasureSnap } from './snap.js';
+import { checkSnapshot, parseChecks, writeFindingCrop } from '../../measure/check.js';
 
-const USAGE = `Usage: capture measure check [url|snap] [--for <checks>] [--viewport <WxH>]... [--gate]
+const USAGE = `capture measure check [url|snap] — read threshold/fact measurements from a settled snapshot
 
-Threshold/fact checks over a settled snapshot's substrate: overlap,
-offscreen, overflow, tap-target size, contrast, hit-test receiver,
-truncation, form visibility, media/replaced anomalies, and animation
-facts. A URL target creates a one-shot snap first.
+input:
+  [url|snap]      a URL creates one one-shot snapshot first; a snap id or absolute path is read without re-driving the browser
+  --for <checks>  geometry|content|targetability|forms|animation|all, or comma-separated overlap,offscreen,overflow,tap-targets,contrast,hit-test,truncation,forms,media,animation
+  --limit <n>     render at most n representative findings in prose (default: 20; --json retains all findings)
+  --gate          exit 2 when the report contains findings (default: exit 0)
+output: <checks result=… findings=…> — findings with coordinates and collection provenance; measurements, not a pass/fail judgment; --json mirrors
+effects: read-only over an existing snapshot artifact; a URL target writes one one-shot snapshot first`;
 
-Options:
-  --for <checks>    Comma-separated check names (e.g.
-                    overlap,offscreen,overflow,tap-targets,contrast,
-                    hit-test,truncation) or a category
-                    (geometry|content|targetability|forms|animation|all).
-                    Omit for every check.
-  --viewport <WxH>  Viewport to check at (repeatable, for a discrete
-                    multi-viewport sweep)
-  --gate            Exit 2 if any check finds something (default: exit 0)
+const DEFAULT_FINDING_LIMIT = 20;
 
-Not yet implemented.`;
+function representativeFindings<T extends { kind: string }>(findings: readonly T[], limit: number): T[] {
+  const byKind = new Map<string, T[]>();
+  for (const finding of findings) {
+    const group = byKind.get(finding.kind) ?? [];
+    group.push(finding);
+    byKind.set(finding.kind, group);
+  }
+  const displayed: T[] = [];
+  for (let index = 0; displayed.length < limit; index++) {
+    let added = false;
+    for (const group of byKind.values()) {
+      const finding = group[index];
+      if (!finding) continue;
+      displayed.push(finding);
+      added = true;
+      if (displayed.length === limit) break;
+    }
+    if (!added) break;
+  }
+  return displayed;
+}
+
+function rollup(findings: readonly { kind: string }[]) {
+  const counts = new Map<string, number>();
+  for (const finding of findings) counts.set(finding.kind, (counts.get(finding.kind) ?? 0) + 1);
+  return [...counts.entries()].map(([kind, count]) => fact`${kind}=${count}`).reduce<ReturnType<typeof fact> | undefined>((line, entry) => line ? [...line, ...text`, `, ...entry] : entry, undefined);
+}
+
+function caveatLine(caveats: readonly { regionId: string; selector?: string; reason?: string }[]) {
+  if (!caveats.length) return undefined;
+  return fact`Nondeterminism caveat: unstable region ${caveats.map((c) => `${c.regionId}${c.selector ? ` (${c.selector})` : ''}${c.reason ? `: ${c.reason}` : ''}`).join('; ')}.`;
+}
 
 export async function cmdMeasureCheck(parsed: ParsedArgs, _args: string[]): Promise<void> {
-  if (parsed.help) {
-    console.log(USAGE);
-    process.exit(0);
+  if (parsed.help) { console.log(USAGE); return; }
+  if (parsed.positional.length > 1) {
+    emitResult({ tag: 'error', attrs: { command: 'measure check', status: 'invalid_input' }, summary: text`measure check accepts at most one URL or snapshot reference.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const target = parsed.positional[0];
+    if (!target) throw new Error('missing snapshot target; pass a snapshot id/path or URL');
+    const checks = parseChecks(parsed.for);
+    const ref = await resolveSnapRef(target, { onUrl: async (url) => captureMeasureSnap({ ...parsed, positional: [url] }, url) });
+    const report = checkSnapshot(ref, checks);
+    const proseFindings = representativeFindings(report.findings, parsed.limit ?? DEFAULT_FINDING_LIMIT);
+    const findingsForOutput = parsed.json ? report.findings : proseFindings;
+    const withCrops = findingsForOutput.map((finding, index) => ({ ...finding, crop: writeFindingCrop(ref, finding, index) }));
+    const meta = readMeta<{ settled: boolean; capturedAt?: string }> (ref);
+    const findingSections: FindingInput[] = withCrops.map((finding) => ({
+      kind: finding.kind,
+      headline: fact`${finding.detail}`,
+      detail: [
+        ...(finding.provenance ? [fact`Provenance: ${finding.provenance}`] : []),
+        ...(caveatLine(finding.caveats) ? [caveatLine(finding.caveats)!] : []),
+      ],
+      artifactPath: finding.crop,
+    }));
+    const result: RenderableResult = {
+      tag: 'checks',
+      attestation: {
+        kind: 'snapshot', id: ref.id, path: ref.dir,
+        note: meta.settled ? text`Measurements read from a settled snapshot.` : text`Measurements read from a queryable unsettled snapshot; affected facts carry per-region nondeterminism caveats.`,
+      },
+      attrs: { result: report.findings.length ? 'findings' : 'clean', checks: checks.join(','), elements: report.elementCount, findings: report.findings.length, displayed: withCrops.length, settled: report.settled },
+      summary: report.findings.length
+        ? fact`${report.findings.length} measured fact(s) matched the selected thresholds in viewport ${report.viewport.width}×${report.viewport.height}; ${withCrops.length} representative record(s) rendered.`
+        : fact`No selected measurement threshold was crossed among ${report.elementCount} recorded elements in viewport ${report.viewport.width}×${report.viewport.height}.`,
+      sections: [
+        ...(report.findings.length ? [line(text`Finding counts: `, rollup(report.findings)!)] : []),
+        ...formatFindings(findingSections),
+      ],
+      followUp: parsed.json
+        ? fact`All ${report.findings.length} measured finding record(s) are included in this JSON result.`
+        : fact`Use --json to read all ${report.findings.length} measured finding record(s) from this snapshot.`,
+    };
+    emitResult(result, { json: parsed.json });
+    if (parsed.gate && report.findings.length) process.exitCode = 2;
+  } catch (err) {
+    const resolution = err as Partial<ArtifactResolutionError>;
+    const detail = err instanceof Error ? err.message : 'unknown artifact read failure';
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure check', status: resolution.name === 'ArtifactResolutionError' ? 'artifact_unavailable' : 'check_failed' },
+      summary: fact`Measure check could not read the requested artifact: ${detail}`,
+      followUp: text`Create a settled snapshot with capture measure snap <url>, then pass its id or absolute path.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure check', status: 'not_implemented' },
-    summary: fact`\`measure check\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
 }

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

@@ -1,32 +1,120 @@
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import { resolveSnapRef, ArtifactResolutionError } from '../../../output/artifact.js';
+import { diffSnapshots, type ElementDiff } from '../../measure/diff.js';
+import { emitResult, fact, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
 
-const USAGE = `Usage: capture measure diff --before <snap> --after <snap> [--pixels] [--full] [--gate]
+const USAGE = `capture measure diff — structured before/after diff over two settled snapshots
 
-Structured before/after diff over two snapshots: style/geometry/text/form/
-media deltas, cascade provenance, and reflow attribution. No positional
-target — both snapshots must already exist.
+input:
+  --before <snap>   earlier snapshot id or absolute path (required; no positional target — both snapshots must already exist)
+  --after <snap>    later snapshot id or absolute path (required)
+  --pixels          write and report a full-raster PNG diff
+  --full            include state-matrix and unchanged per-element records
+  --gate            exit 2 if a measured delta exists (default: exit 0)
+output: <diff …> — style, geometry, text, form, and media deltas, cascade provenance, and geometry movement/size facts; --json mirrors
+effects: read-only over the two snapshot artifacts; --pixels additionally writes the reported raster-diff PNG`;
 
-Options:
-  --before <snap>   Earlier snapshot id/path (required)
-  --after <snap>    Later snapshot id/path (required)
-  --pixels          Also report raster regions not explained by geometry
-  --full            Expand to state-matrix deltas and complete per-element
-                     change records
-  --gate            Exit 2 if any element changed (default: exit 0)
+function caveatLine(caveats: readonly { regionId: string; selector?: string; reason?: string; snapshot: 'before' | 'after' }[]): FactLine | undefined {
+  if (!caveats.length) return undefined;
+  return fact`nondeterminism caveat: ${caveats.map((caveat) => `${caveat.snapshot} snapshot ${caveat.regionId}${caveat.selector ? ` (${caveat.selector})` : ''}${caveat.reason ? `: ${caveat.reason}` : ''}`).join('; ')}`;
+}
+
+function recordLine(record: ElementDiff, full: boolean): FactLine {
+  const selector = record.selector ?? record.key;
+  const facts: string[] = [];
+  if (record.styleDeltas.length) facts.push(`style properties ${record.styleDeltas.map((delta) => `${delta.property} ${String(delta.before)}→${String(delta.after)}`).join(', ')}`);
+  if (record.geometryChanged) facts.push(`geometry changed${record.reflow ? ' (position/size delta)' : ''}`);
+  if (record.textChanged) facts.push('text facts changed');
+  if (record.formChanged) facts.push('form facts changed');
+  if (record.mediaChanged) facts.push('media facts changed');
+  if (!facts.length && full) facts.push('no compared delta');
+  return fact`${selector} — ${facts.join('; ')}`;
+}
 
-Not yet implemented.`;
+function provenanceLines(records: readonly ElementDiff[]): FactLine[] {
+  const lines: FactLine[] = [];
+  for (const record of records) {
+    for (const provenance of record.provenance) {
+      lines.push(fact`${record.selector ?? record.key} ${provenance.property}: cascade provenance before=${JSON.stringify(provenance.beforeProvenance ?? null)} after=${JSON.stringify(provenance.afterProvenance ?? null)}${provenance.changed ? '' : provenance.declarationChanged ? ' (unchanged computed value; winning declaration changed)' : ' (unchanged value)'}`);
+    }
+  }
+  return lines;
+}
 
 export async function cmdMeasureDiff(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
-    process.exit(0);
+    return;
+  }
+  if (parsed.positional.length > 0 || !parsed.before || !parsed.after) {
+    const result: RenderableResult = {
+      tag: 'error',
+      attrs: { command: 'measure diff', status: 'invalid_input' },
+      summary: text`This command requires --before SNAP and --after SNAP and accepts no positional target.`,
+      followUp: text`Use capture measure diff --before SNAP --after SNAP.`,
+    };
+    emitResult(result, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const before = await resolveSnapRef(parsed.before);
+    const after = await resolveSnapRef(parsed.after);
+    const report = diffSnapshots(before, after, { pixels: parsed.pixels, full: parsed.full });
+    const changedRecords = report.changes.filter((record) => record.geometryChanged || record.textChanged || record.formChanged || record.mediaChanged || record.styleDeltas.length > 0);
+    const recordLines = report.changes
+      .filter((record) => Boolean(parsed.full) || record.geometryChanged || record.textChanged || record.formChanged || record.mediaChanged || record.styleDeltas.length > 0)
+      .map((record) => recordLine(record, Boolean(parsed.full)));
+    const caveats = report.changes.flatMap((record) => record.caveats);
+    const sections: FactLine[] = [];
+    if (recordLines.length) sections.push(lineList(recordLines));
+    const provenance = provenanceLines(report.changes);
+    if (provenance.length) sections.push(lineList(provenance));
+    if (parsed.full) {
+      sections.push(fact`state-matrix records: ${report.stateDeltas.length}; changed state records: ${report.stateDeltas.filter((state) => state.changed).length}.`);
+      if (report.stateDeltas.length) sections.push(lineList(report.stateDeltas.map((state) => fact`${state.key} — ${state.changed ? 'state delta' : 'no state delta'}`)));
+    }
+    if (report.raster) {
+      const raster = report.raster.outcome;
+      sections.push(raster.ok
+        ? fact`Raster diff: ${raster.diffPixelCount} changed pixels across ${raster.width}×${raster.height}; diff artifact ${report.raster.path}. Raster regions without a geometry delta: ${report.raster.unexplainedRegions}.`
+        : fact`Raster diff was not computed: ${raster.message}.`);
+      if (raster.ok && report.raster.regions.length) {
+        sections.push(lineList(report.raster.regions.map((region) => fact`raster region x=${region.x} y=${region.y} w=${region.w} h=${region.h} changed-pixels=${region.changedPixels} explained-by-geometry=${String(region.explainedByGeometry)}`)));
+      }
+    }
+    const caveat = caveatLine(caveats);
+    if (caveat) sections.push(caveat);
+
+    const result: RenderableResult = {
+      tag: 'diff',
+      attestation: {
+        kind: 'snapshot',
+        id: after.id,
+        path: after.dir,
+        note: fact`Compared before snapshot ${before.id} (settled=${String(report.beforeMeta.settled ?? 'unknown')}) with after snapshot ${after.id} (settled=${String(report.afterMeta.settled ?? 'unknown')}).`,
+      },
+      attrs: { before: before.id, after: after.id, 'changed-elements': changedRecords.length, ...(report.raster?.outcome.ok ? { 'raster-regions': report.raster.unexplainedRegions } : {}) },
+      summary: report.changed
+        ? fact`${changedRecords.length} element record(s) contain measured style, geometry, text, form, or media deltas.`
+        : text`No measured style, geometry, text, form, media, state, or requested raster delta was recorded.`,
+      sections,
+      followUp: parsed.full
+        ? fact`Inspect a changed element with capture measure explain ${after.id} --selector SELECTOR.`
+        : fact`Use --full for state-matrix and unchanged per-element provenance records.`,
+    };
+    emitResult(result, { json: parsed.json });
+    if (parsed.gate && report.changed) process.exitCode = 2;
+  } catch (error) {
+    const detail = error instanceof ArtifactResolutionError ? error.message : error instanceof Error ? error.message : String(error);
+    const result: RenderableResult = {
+      tag: 'error',
+      attrs: { command: 'measure diff', status: 'artifact_unavailable' },
+      summary: fact`The requested snapshot comparison could not be read: ${detail}`,
+      followUp: text`Create settled snapshots with capture measure snap, then pass their ids or absolute artifact paths.`,
+    };
+    emitResult(result, { json: parsed.json });
+    process.exitCode = 1;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure diff', status: 'not_implemented' },
-    summary: fact`\`measure diff\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
 }

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

@@ -1,31 +1,133 @@
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import { explainSnapshot, type ExplainMissingSelector } from '../../measure/explain.js';
+import { ArtifactResolutionError, resolveSnapRef } from '../../../output/artifact.js';
+import { data, emitResult, fact, line, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
 
-const USAGE = `Usage: capture measure explain <snap> --selector <sel> [--size] [--text] [--form]
+const USAGE = `capture measure explain <snap> --selector <sel> — per-element cascade/stacking/clipping explanation over one snapshot
 
-Per-element cascade/stacking/clipping explanation over one snapshot, plus
-optional detail sections.
+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>
+  --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
+effects: read-only — reads existing snapshot artifacts, never drives the browser`;
 
-Options:
-  --selector <sel>   Element selector (required)
-  --size             Include size/layout provenance (flex/grid/intrinsic)
-  --text             Include text/line-box/wrap detail
-  --form             Include form/caret/selection/autofill detail (redacted)
+function attestation(ref: { id: string; dir: string }, meta: { settled?: boolean; settleMs?: number }) {
+  return {
+    kind: 'snapshot' as const,
+    id: ref.id,
+    path: ref.dir,
+    note: meta.settled === false
+      ? text`Snapshot was captured unsettled; each explanation fact intersecting an unstable region carries its own nondeterminism caveat.`
+      : meta.settled === true
+        ? fact`Snapshot settled${meta.settleMs === undefined ? '' : ` after ${meta.settleMs}ms`}.`
+        : text`Snapshot settledness was not recorded.`,
+  };
+}
+
+function caveatSuffix(caveats: readonly { regionId: string; selector?: string; reason?: string }[]): FactLine | undefined {
+  if (!caveats.length) return undefined;
+  const entries = caveats.map((caveat) => {
+    const parts: FactLine[] = [data(caveat.regionId)];
+    if (caveat.selector) parts.push(line(text` (`, data(caveat.selector), text`)`));
+    if (caveat.reason) parts.push(line(text`: `, data(caveat.reason)));
+    return line(...parts);
+  });
+  const joined: FactLine[] = [];
+  entries.forEach((entry, index) => {
+    if (index) joined.push(text`; `);
+    joined.push(entry);
+  });
+  return line(text` — nondeterminism caveat: `, ...joined);
+}
 
-With no detail flag, returns the standard compact element explanation.
+function recoverySections(missing: ExplainMissingSelector): FactLine[] {
+  const { candidates, recordCount, kind } = 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.`];
+  return [
+    fact`Nearest recorded ${label}: ${candidates.length} shown from ${recordCount} geometry record(s), ranked by identifier similarity then string distance from the requested selector.`,
+    lineList(rows),
+    text`All recorded selector and identity facts remain in this snapshot's geometry.json, ax.json, and text.json artifacts.`,
+  ];
+}
 
-Not yet implemented.`;
+function invalidInput(message: FactLine): RenderableResult {
+  return {
+    tag: 'error',
+    attrs: { command: 'measure explain', status: 'invalid_input' },
+    summary: message,
+    followUp: text`Run capture measure explain <snap> --selector <CSS|backend:id|axid:id|ax:name|text:value>.`,
+  };
+}
 
 export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
-    process.exit(0);
+    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) {
+    emitResult(invalidInput(text`The --selector flag is required.`), { 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 });
+    if (report.kind === 'missing-selector') {
+      emitResult({
+        tag: 'error',
+        attestation: attestation(report.ref, report.meta),
+        attrs: { command: 'measure explain', status: 'missing_selector', selector: report.selector },
+        summary: fact`No geometry element matched selector input ${report.selector}. Bounded recovery candidates from this snapshot follow.`,
+        sections: recoverySections(report),
+        followUp: text`The selector input also accepts CSS, backend:, axid:, ax:, and text: forms.`,
+      }, { json: parsed.json });
+      process.exitCode = 1;
+      return;
+    }
+
+    const sections = report.sections.map((section) => lineList(section.facts.map(({ fact: item, caveats }) => {
+      const suffix = caveatSuffix(caveats);
+      return suffix ? line(item.line, suffix) : item.line;
+    })));
+    const targetSelector = report.element.selector ?? report.element.id;
+    const result: RenderableResult = {
+      tag: 'explain',
+      attestation: attestation(report.ref, report.meta),
+      attrs: {
+        selector: targetSelector,
+        matches: report.matchCount,
+        settled: report.meta.settled ?? 'unknown',
+        size: Boolean(parsed.size),
+        text: Boolean(parsed.text),
+        form: Boolean(parsed.form),
+      },
+      summary: fact`Recorded cascade, stacking, clipping, focus, scroll, query, and state context for ${targetSelector}.`,
+      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.`
+        : text`Add --size, --text, or --form to include only those optional detail sections.`,
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (error) {
+    const detail = error instanceof ArtifactResolutionError || error instanceof Error ? error.message : String(error);
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure explain', status: 'artifact_unavailable' },
+      summary: fact`The requested snapshot explanation could not be read: ${detail}`,
+      followUp: text`Create a settled snapshot with capture measure snap, then pass its id or absolute artifact path.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure explain', status: 'not_implemented' },
-    summary: fact`\`measure explain\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
 }