@crouton-kit/capture 1.3.8 → 1.3.9

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

@@ -7,6 +7,7 @@
  * 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';
@@ -17,53 +18,44 @@ 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 it explicitly accepts a URL target.
-
-Leaves:
-  snap [url|snap]                          Drive + write a settled snapshot substrate
-    [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled]
-    [--pixels] [--state <state[:selector]>]...
-
-  check [url|snap] [--for <checks>] [--viewport <WxH>]... [--gate]
-                                            Threshold/fact checks over a snapshot
-
-  diff --before <snap> --after <snap> [--pixels] [--full] [--gate]
-                                            Structured before/after snapshot diff
-
-  census [--snap <id>]... [--url <url>]... [--set-file <path>] --axis <axis>
-                                            Value distributions across one or more snapshots
-                                            (--snap/--url repeatable)
+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.
 
-  explain <snap> --selector <sel> [--size] [--text] [--form]
-                                            Per-element cascade/stacking/clipping/size/text/form explanation
+<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"/>
 
-  sweep [url] --axis <axis> [--from <val>] [--to <val>] [--viewport-height <val>]
-                                            Responsive/environment sampling
-
-  map focus|scroll|layers [url|snap]       Read one facet of a snapshot's substrate
-                                            (see \`capture measure map --help\`)
-
-Every leaf defaults to rendered prose; --json mirrors the same result as JSON.
-Exit codes: 0 by default — findings are a report, not a failure.
---gate exits 2 on findings/changes; only \`check\` and \`diff\` accept it.
-
-capture measure <leaf> --help    Per-leaf usage`;
+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).
 
-Leaves:
-  focus  [url|snap]      Keyboard traversal order (focus.json)
-  scroll [url|snap]      Scroll-container topology (scroll.json)
-  layers [url|snap]      Paint/compositor layer map (layers.json)
-
 A URL target first creates a snap; a snap target reads its existing artifact.
 
-capture measure map <leaf> --help    Per-leaf usage`;
+<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];
@@ -88,8 +80,7 @@ export async function measureMain(parsed: ParsedArgs, args: string[]): Promise<v
       console.log(MEASURE_USAGE);
       return;
     default:
-      console.error(`Unknown measure leaf: ${leaf}\n\n${MEASURE_USAGE}`);
-      process.exit(1);
+      throw invalidInput(`Unknown measure leaf: ${leaf}.`, 'unknown_command');
   }
 }
 
@@ -104,11 +95,12 @@ async function measureMapMain(parsed: ParsedArgs, args: string[]): Promise<void>
       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:
-      console.error(`Unknown measure map leaf: ${sub}\n\n${MEASURE_MAP_USAGE}`);
-      process.exit(1);
+      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

@@ -1,24 +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 = `Usage: capture measure map focus [url|snap]
+const USAGE = `capture measure map focus [url|snap] — keyboard traversal facts recorded in a snapshot's focus.json
 
-Keyboard traversal order recorded in a snapshot's focus.json: forward and
-reverse Tab sequence, rects, scroll jumps, focus-visible facts, and
-unreached focusable elements. A URL target creates a snap first.
+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`;
 
-Not yet implemented.`;
+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);
-    process.exit(0);
+    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;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure map focus', status: 'not_implemented' },
-    summary: fact`\`measure map focus\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
 }

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

@@ -1,25 +1,59 @@
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import { captureMeasureSnap } from './snap.js';
+import { buildMeasureMapLayersResult } from '../../measure/map-layers.js';
+import { resolveSnapRef } from '../../../output/artifact.js';
+import { emitResult, fact, text, type RenderableResult } from '../../../output/render.js';
 
-const USAGE = `Usage: capture measure map layers [url|snap]
+const USAGE = `capture measure map layers [url|snap] — paint/compositor facts recorded in a snapshot's layers.json
 
-Paint/compositor layer map recorded in a snapshot's layers.json: layers,
-bounds, compositing reasons, paint order, per-node membership, and source
-provenance for layer-affecting declarations. A URL target creates a snap
-first.
+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: <layer-map …> — layer bounds, compositing reasons, DOMSnapshot paint order, per-node membership, and available source provenance for layer-affecting declarations; --json mirrors
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot first`;
 
-Not yet implemented.`;
+function errorResult(err: unknown): RenderableResult {
+  const detail = err instanceof Error ? err.message : String(err);
+  return {
+    tag: 'error',
+    attrs: { command: 'measure map layers', status: 'artifact_unavailable' },
+    summary: fact`Layer-map facts could not be read: ${detail}`,
+    followUp: text`Pass a settled snapshot id or its absolute artifact path, or pass a URL to create a snapshot first with capture measure snap.`,
+  };
+}
 
 export async function cmdMeasureMapLayers(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
-    process.exit(0);
+    return;
+  }
+  if (parsed.positional.length > 1) {
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure map layers', status: 'invalid_target' },
+      summary: text`measure map layers accepts at most one URL, snapshot id, or absolute snapshot artifact path.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  const target = parsed.positional[0];
+  if (!target) {
+    emitResult({
+      tag: 'error',
+      attrs: { command: 'measure map layers', status: 'missing_target' },
+      summary: text`A URL, snapshot id, or absolute snapshot artifact path is required to read layer-map facts.`,
+      followUp: text`Capture one with capture measure snap <url>, then pass its snapshot id or artifact path.`,
+    }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const ref = await resolveSnapRef(target, {
+      onUrl: async (url) => captureMeasureSnap(parsed, url),
+    });
+    emitResult(buildMeasureMapLayersResult(ref), { json: parsed.json });
+  } catch (err) {
+    emitResult(errorResult(err), { json: parsed.json });
+    process.exitCode = 1;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure map layers', status: 'not_implemented' },
-    summary: fact`\`measure map layers\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
 }

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

@@ -1,24 +1,94 @@
 import { type ParsedArgs } from '../../types.js';
-import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+import { captureMeasureSnap } from './snap.js';
+import { ArtifactResolutionError, resolveSnapRef, type SnapUrlResult } from '../../../output/artifact.js';
+import { emitResult, fact, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+import { measureMapScroll } from '../../measure/map-scroll.js';
 
-const USAGE = `Usage: capture measure map scroll [url|snap]
+const USAGE = `capture measure map scroll [url|snap] — scroll-container topology recorded in a snapshot's scroll.json
 
-Scroll-container topology recorded in a snapshot's scroll.json: containers,
-ranges, current/max offsets, sticky/fixed occupancy, snap points, and
-visual/layout viewport facts. A URL target creates a snap first.
+input:
+  [url|snap]   required target: a URL creates a settled snapshot first; a snapshot id from the active session or an absolute snapshot artifact path is read without re-driving the browser
+output: <scroll-map …> — containers, ranges, current/max offsets, sticky/fixed occupancy, snap points, visual/layout viewport facts, and reachable-content samples; --json mirrors
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot first`;
 
-Not yet implemented.`;
+type CaptureSnap = (parsed: ParsedArgs, target: string) => Promise<SnapUrlResult>;
+type Emit = typeof emitResult;
+
+interface MapScrollDeps {
+  readonly captureSnap?: CaptureSnap;
+  readonly emit?: Emit;
+}
+
+function artifactRecovery(err: ArtifactResolutionError): FactLine[] {
+  return [
+    fact`artifact resolution error: ${err.message}`,
+    fact`received ref: ${err.ref}`,
+    fact`searched path count: ${err.searched.length}`,
+    ...err.searched.map((candidate) => fact`searched path: ${candidate}`),
+    fact`creating command: ${err.creatingCommand ?? 'capture measure snap'}`,
+  ];
+}
+
+export async function runMeasureMapScroll(parsed: ParsedArgs, deps: MapScrollDeps = {}): Promise<void> {
+  const captureSnap = deps.captureSnap ?? captureMeasureSnap;
+  const emit = deps.emit ?? emitResult;
 
-export async function cmdMeasureMapScroll(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
-    process.exit(0);
+    return;
+  }
+
+  if (parsed.positional.length > 1) {
+    const result: RenderableResult = {
+      tag: 'error',
+      attrs: { command: 'measure map scroll', status: 'invalid_target' },
+      summary: text`Measure map scroll accepts one URL, snapshot id, or absolute snapshot path.`,
+      followUp: text`Pass one target, for example: \`capture measure map scroll snap-a3f2\`.`,
+    };
+    emit(result, { json: parsed.json });
+    process.exitCode = 1;
+    return;
   }
-  const result: RenderableResult = {
-    tag: 'error',
-    attrs: { command: 'measure map scroll', status: 'not_implemented' },
-    summary: fact`\`measure map scroll\` is not implemented yet.`,
-  };
-  emitResult(result, { json: parsed.json });
-  process.exit(1);
+
+  const target = parsed.positional[0] ?? parsed.url;
+  if (!target) {
+    const result: RenderableResult = {
+      tag: 'error',
+      attrs: { command: 'measure map scroll', status: 'missing_target' },
+      summary: text`No snapshot or URL target was received.`,
+      followUp: text`Create a snapshot with \`capture measure snap <url>\`, then pass its id or absolute path to \`capture measure map scroll\`.`,
+    };
+    emit(result, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const ref = await resolveSnapRef(target, {
+      onUrl: async (url) => captureSnap({ ...parsed, positional: [url] }, url),
+    });
+    emit(measureMapScroll(ref), { json: parsed.json });
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const recovery = err instanceof ArtifactResolutionError ? artifactRecovery(err) : [];
+    const result: RenderableResult = {
+      tag: 'error',
+      attrs: {
+        command: 'measure map scroll',
+        status: 'artifact_unavailable',
+        recovery: err instanceof ArtifactResolutionError ? 'artifact-resolution-error' : undefined,
+        'searched-paths': err instanceof ArtifactResolutionError ? err.searched.length : undefined,
+        'creating-command': err instanceof ArtifactResolutionError ? (err.creatingCommand ?? 'capture measure snap') : undefined,
+      },
+      summary: fact`Scroll topology could not be read: ${detail}`,
+      sections: recovery.length ? [lineList(recovery)] : undefined,
+      followUp: text`Create a settled snapshot with \`capture measure snap <url>\`; it writes scroll.json for this query.`,
+    };
+    emit(result, { json: parsed.json });
+    process.exitCode = 1;
+  }
+}
+
+export async function cmdMeasureMapScroll(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  await runMeasureMapScroll(parsed);
 }