@crouton-kit/capture 1.3.7 → 1.3.9

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

@@ -0,0 +1,87 @@
+import * as fs from 'fs';
+
+import { type ParsedArgs } from '../../types.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 = `capture measure census --axis <axis> — value distributions and token-audit facts across one or more settled snapshots
+
+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`;
+
+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('#'));
+}
+
+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);
+    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;
+  }
+}

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

@@ -0,0 +1,109 @@
+import { type ParsedArgs } from '../../types.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 = `capture measure check [url|snap] — read threshold/fact measurements from a settled snapshot
+
+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`;
+
+const DEFAULT_FINDING_LIMIT = 20;
+
+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); 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;
+  }
+}

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

@@ -0,0 +1,120 @@
+import { type ParsedArgs } from '../../types.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 = `capture measure diff — structured before/after diff over two settled snapshots
+
+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`;
+
+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('; ')}`;
+}
+
+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);
+    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;
+  }
+}

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

@@ -0,0 +1,133 @@
+import { type ParsedArgs } from '../../types.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 = `capture measure explain <snap> --selector <sel> — per-element cascade/stacking/clipping explanation 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>
+  --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`;
+
+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);
+}
+
+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.`,
+  ];
+}
+
+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);
+    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;
+  }
+}

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

@@ -0,0 +1,106 @@
+/**
+ * `capture measure` branch router.
+ *
+ * Shifts the consumed leaf token(s) out of `parsed.positional` before
+ * handing off, so every leaf command still finds its own primary target
+ * (a URL, a snap id, ...) at `positional[0]` exactly as every other capture
+ * command does — leaf commands never need to know they're nested under a
+ * branch.
+ */
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { cmdMeasureSnap } from './snap.js';
+import { cmdMeasureCheck } from './check.js';
+import { cmdMeasureDiff } from './diff.js';
+import { cmdMeasureCensus } from './census.js';
+import { cmdMeasureExplain } from './explain.js';
+import { cmdMeasureSweep } from './sweep.js';
+import { cmdMeasureMapFocus } from './map-focus.js';
+import { cmdMeasureMapScroll } from './map-scroll.js';
+import { cmdMeasureMapLayers } from './map-layers.js';
+import { cmdMeasureMapAx } from './map-ax.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\`
+</command>`;
+
+export const MEASURE_USAGE = `capture measure — enriched snapshot substrate + read-only queries over it.
+
+\`snap\` drives the page (or a base snapshot) and writes one settled artifact
+directory; every other leaf below is a cheap read over that artifact and
+never re-drives the browser unless its target is a URL (which snaps first).
+Every leaf defaults to rendered prose; --json mirrors the same result.
+Findings exit 0 — a report, not a failure.
+\`--gate\` (exit 2 on findings/changes) is accepted only by check and diff.
+
+<subcommand name="snap" args="[url|snap] [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled] [--pixels] [--state <state[:selector]>]... [--viewport <WxH>]..." whenToUse="drive + write the settled snapshot substrate every other leaf reads"/>
+<subcommand name="check" args="[url|snap] [--for <checks>] [--gate]" whenToUse="read threshold/fact measurements from one snapshot"/>
+<subcommand name="diff" args="--before <snap> --after <snap> [--pixels] [--full] [--gate]" whenToUse="structured before/after delta between two snapshots"/>
+<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"/>
+
+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.
+
+<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)"/>
+
+capture measure map <leaf> -h    Per-leaf usage`;
+
+export async function measureMain(parsed: ParsedArgs, args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+
+  switch (leaf) {
+    case 'snap':
+      return cmdMeasureSnap(rest, args);
+    case 'check':
+      return cmdMeasureCheck(rest, args);
+    case 'diff':
+      return cmdMeasureDiff(rest, args);
+    case 'census':
+      return cmdMeasureCensus(rest, args);
+    case 'explain':
+      return cmdMeasureExplain(rest, args);
+    case 'sweep':
+      return cmdMeasureSweep(rest, args);
+    case 'map':
+      return measureMapMain(rest, args);
+    case undefined:
+      console.log(MEASURE_USAGE);
+      return;
+    default:
+      throw invalidInput(`Unknown measure leaf: ${leaf}.`, 'unknown_command');
+  }
+}
+
+async function measureMapMain(parsed: ParsedArgs, args: string[]): Promise<void> {
+  const sub = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+
+  switch (sub) {
+    case 'focus':
+      return cmdMeasureMapFocus(rest, args);
+    case 'scroll':
+      return cmdMeasureMapScroll(rest, args);
+    case 'layers':
+      return cmdMeasureMapLayers(rest, args);
+    case 'ax':
+      return cmdMeasureMapAx(rest, args);
+    case undefined:
+      console.log(MEASURE_MAP_USAGE);
+      return;
+    default:
+      throw invalidInput(`Unknown measure map leaf: ${sub}.`, 'unknown_command');
+  }
+}

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

@@ -0,0 +1,52 @@
+import { type ParsedArgs } from '../../types.js';
+import { captureMeasureSnap } from './snap.js';
+import { buildMeasureMapAxResult } from '../../measure/map-ax.js';
+import { ArtifactResolutionError, resolveSnapRef } from '../../../output/artifact.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture measure map ax [url|snap] — accessibility-tree facts recorded in a snapshot's ax.json joined against geometry.json
+
+input:
+  [url|snap]   required target: a URL creates a settled snapshot first; a snapshot id or absolute path is read without re-driving the browser
+output: <ax-map …> — non-ignored AX nodes with role, name, states, backendNodeId, and top-viewport rect; ignored AX nodes with their ignored-reasons; DOM elements with rendered boxes but no non-ignored AX node; and AX nodes whose rect is offscreen, clipped, or zero-size; --json mirrors
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot first`;
+
+function recoveryResult(err: unknown): RenderableResult {
+  const detail = err instanceof ArtifactResolutionError || err instanceof Error
+    ? err.message
+    : 'The snapshot artifacts could not be resolved.';
+  return {
+    tag: 'error',
+    attrs: { command: 'measure map ax', status: 'artifact_unavailable' },
+    summary: fact`AX-map facts could not be read: ${detail}`,
+    followUp: fact`Create a settled snapshot with \`capture measure snap <url>\`, then run \`capture measure map ax <snap>\`.`,
+  };
+}
+
+export async function cmdMeasureMapAx(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (parsed.positional.length !== 1) {
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure map ax', status: 'invalid_target' },
+      summary: fact`Expected exactly one URL or snapshot target; received ${parsed.positional.length} positional target(s).`,
+      followUp: fact`Run \`capture measure map ax <snap>\` or \`capture measure map ax <url>\`.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const target = parsed.positional[0]!;
+    const ref = await resolveSnapRef(target, {
+      onUrl: async (url) => captureMeasureSnap({ ...parsed, positional: [url] }, url),
+    });
+    emitResult(buildMeasureMapAxResult(ref), { json: parsed.json });
+  } catch (err) {
+    emitResult(recoveryResult(err), { json: parsed.json });
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,52 @@
+import { type ParsedArgs } from '../../types.js';
+import { captureMeasureSnap } from './snap.js';
+import { mapFocus } from '../../measure/map-focus.js';
+import { ArtifactResolutionError, resolveSnapRef } from '../../../output/artifact.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture measure map focus [url|snap] — keyboard traversal facts recorded in a snapshot's focus.json
+
+input:
+  [url|snap]   required target: a URL creates a settled snapshot first; a snapshot id or absolute path is read without re-driving the browser
+output: <focus-map …> — forward and reverse Tab sequences, top-viewport rects, scroll jumps, focus-visible style facts, and unreached focusable elements; --json mirrors
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot first`;
+
+function recoveryResult(err: unknown): RenderableResult {
+  const detail = err instanceof ArtifactResolutionError || err instanceof Error
+    ? err.message
+    : 'The focus artifact could not be resolved.';
+  return {
+    tag: 'error',
+    attrs: { command: 'measure map focus', status: 'artifact_unavailable' },
+    summary: fact`Focus-map facts could not be read: ${detail}`,
+    followUp: fact`Create a settled snapshot with \`capture measure snap <url>\`, then run \`capture measure map focus <snap>\`.`,
+  };
+}
+
+export async function cmdMeasureMapFocus(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (parsed.positional.length !== 1) {
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure map focus', status: 'invalid_target' },
+      summary: fact`Expected exactly one URL or snapshot target; received ${parsed.positional.length} positional target(s).`,
+      followUp: fact`Run \`capture measure map focus <snap>\` or \`capture measure map focus <url>\`.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const target = parsed.positional[0]!;
+    const ref = await resolveSnapRef(target, {
+      onUrl: async (url) => captureMeasureSnap({ ...parsed, positional: [url] }, url),
+    });
+    emitResult(mapFocus(ref), { json: parsed.json });
+  } catch (err) {
+    emitResult(recoveryResult(err), { json: parsed.json });
+    process.exitCode = 1;
+  }
+}