@crouton-kit/capture 1.4.2 → 1.4.11

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

@@ -1,6 +1,8 @@
 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 { selectRecords } from '../../../output/selection.js';
+import { resolveSnapRef, readGeometry, readMeta, type ArtifactResolutionError } from '../../../output/artifact.js';
+import { resolveSelectorInput } from '../../../output/selector.js';
+import { capped, data, emitResult, fact, line, text, formatCoordinate, formatFindings, type FactLine, type FindingInput, type RenderableResult } from '../../../output/render.js';
 import { captureMeasureSnap } from './snap.js';
 import { checkSnapshot, parseChecks, writeFindingCrop } from '../../measure/check.js';
 
@@ -9,10 +11,13 @@ const USAGE = `capture measure check [url|snap] — read threshold/fact measurem
 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)
+  --limit <n>     return at most n representative findings in prose and JSON (default: 20)
+  --selector <s>  limit measurements to recorded CSS/text/AX selector input or backend:<id>
+  --artifact-dir <path>  root for the one-shot snapshot bundle when the target is a URL
   --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`;
+boundary: measurements are local to the selected snapshot. \`capture lighthouse\` runs the independent audited sweep.
+effects: read-only over an existing snapshot artifact; a URL target writes one one-shot snapshot bundle under --artifact-dir when supplied`;
 
 const DEFAULT_FINDING_LIMIT = 20;
 
@@ -49,6 +54,34 @@ function caveatLine(caveats: readonly { regionId: string; selector?: string; rea
   return fact`Nondeterminism caveat: unstable region ${caveats.map((c) => `${c.regionId}${c.selector ? ` (${c.selector})` : ''}${c.reason ? `: ${c.reason}` : ''}`).join('; ')}.`;
 }
 
+/** Contrast colors are the measurement's subject, not incidental selector text. Keep each color as its own uncapped, escaped field so a long selector cannot elide either one. */
+function contrastHeadline(detail: string): FactLine {
+  const ratioPrefix = 'contrast ratio ';
+  const divider = ' — ';
+  const foregroundMarker = ' foreground ';
+  const backgroundMarker = ' against composited background ';
+  const dividerAt = detail.indexOf(divider);
+  if (!detail.startsWith(ratioPrefix) || dividerAt < 0) return fact`${detail}`;
+  const ratio = detail.slice(ratioPrefix.length, dividerAt);
+  const subject = detail.slice(dividerAt + divider.length);
+  const foregroundAt = subject.lastIndexOf(foregroundMarker);
+  const backgroundAt = subject.indexOf(backgroundMarker, foregroundAt + foregroundMarker.length);
+  if (foregroundAt < 0 || backgroundAt < 0) return fact`${detail}`;
+  const selector = subject.slice(0, foregroundAt);
+  const foreground = subject.slice(foregroundAt + foregroundMarker.length, backgroundAt);
+  const background = subject.slice(backgroundAt + backgroundMarker.length);
+  return line(
+    text`contrast ratio `,
+    data(ratio),
+    text` — `,
+    data(selector),
+    text` foreground `,
+    data(capped(foreground, Number.MAX_SAFE_INTEGER)),
+    text` against composited background `,
+    data(capped(background, Number.MAX_SAFE_INTEGER)),
+  );
+}
+
 export async function cmdMeasureCheck(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) { console.log(USAGE); return; }
   if (parsed.positional.length > 1) {
@@ -62,14 +95,34 @@ export async function cmdMeasureCheck(parsed: ParsedArgs, _args: string[]): Prom
     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 scopedElements = parsed.selector
+      ? resolveSelectorInput(readGeometry<{ elements?: Array<{ id: string; selector?: string; backendNodeId?: number | null }> }>(ref).elements ?? [], parsed.selector)
+      : undefined;
+    if (scopedElements && !scopedElements.length) {
+      emitResult({
+        tag: 'error',
+        attrs: { command: 'measure check', status: 'missing_selector', selector: parsed.selector! },
+        summary: fact`No geometry record matched selector input ${parsed.selector}.`,
+        followUp: text`Use a recorded selector or backend:<id> from geometry.json.`,
+      }, { json: parsed.json });
+      process.exitCode = 1;
+      return;
+    }
+    const scopedIds = scopedElements ? new Set(scopedElements.map((element) => element.id)) : undefined;
+    const scopedBackendNodeIds = scopedElements ? new Set(scopedElements.map((element) => element.backendNodeId).filter((backendNodeId): backendNodeId is number => backendNodeId !== null && backendNodeId !== undefined)) : undefined;
+    const selectorCounts = new Map<string, number>();
+    for (const element of readGeometry<{ elements?: Array<{ selector?: string }> }>(ref).elements ?? []) if (element.selector !== undefined) selectorCounts.set(element.selector, (selectorCounts.get(element.selector) ?? 0) + 1);
+    const scopedSelectors = scopedElements ? new Set(scopedElements.map((element) => element.selector).filter((selector): selector is string => selector !== undefined && selectorCounts.get(selector) === 1)) : undefined;
+    const findings = scopedIds ? report.findings.filter((finding) => (finding.elementId !== undefined && scopedIds.has(finding.elementId)) || (finding.backendNodeId !== undefined && scopedBackendNodeIds!.has(finding.backendNodeId)) || (finding.selector !== undefined && scopedSelectors!.has(finding.selector))) : report.findings;
+    const findingsForOutput = selectRecords(representativeFindings(findings, parsed.limit ?? DEFAULT_FINDING_LIMIT), parsed, parsed.limit ?? DEFAULT_FINDING_LIMIT);
     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}`,
+      headline: finding.kind === 'contrast' ? contrastHeadline(finding.detail) : fact`${finding.detail}`,
       detail: [
+        ...(finding.rect ? [line(text`Rect: `, formatCoordinate(finding.rect))] : []),
+        ...(finding.backendNodeId !== undefined ? [fact`Selector input: backend:${finding.backendNodeId}`] : []),
         ...(finding.provenance ? [fact`Provenance: ${finding.provenance}`] : []),
         ...(caveatLine(finding.caveats) ? [caveatLine(finding.caveats)!] : []),
       ],
@@ -81,20 +134,21 @@ export async function cmdMeasureCheck(parsed: ParsedArgs, _args: string[]): Prom
         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}.`,
+      attrs: { result: findings.length ? 'findings' : 'clean', checks: checks.join(','), elements: scopedElements?.length ?? report.elementCount, findings: findings.length, displayed: withCrops.length, settled: report.settled, ...(parsed.selector ? { selector: parsed.selector } : {}) },
+      summary: findings.length
+        ? fact`${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 ${scopedElements?.length ?? report.elementCount} recorded elements in viewport ${report.viewport.width}×${report.viewport.height}.`,
       sections: [
-        ...(report.findings.length ? [line(text`Finding counts: `, rollup(report.findings)!)] : []),
+        ...(findings.length ? [line(text`Finding counts: `, rollup(findings)!)] : []),
         ...formatFindings(findingSections),
+        fact`Measurements are local to snapshot ${ref.id}; \`capture lighthouse\` runs the independent audited sweep.`,
       ],
-      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.`,
+      followUp: findings.length > withCrops.length
+        ? fact`The full snapshot artifact at ${ref.dir} retains every measured finding input; this result is bounded by --limit.`
+        : undefined,
     };
     emitResult(result, { json: parsed.json });
-    if (parsed.gate && report.findings.length) process.exitCode = 2;
+    if (parsed.gate && findings.length) process.exitCode = 2;
   } catch (err) {
     const resolution = err as Partial<ArtifactResolutionError>;
     const detail = err instanceof Error ? err.message : 'unknown artifact read failure';

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

@@ -50,8 +50,7 @@ export async function cmdMeasureDiff(parsed: ParsedArgs, _args: string[]): Promi
     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.`,
+      summary: fact`received: ${parsed.positional.length} positional argument(s), --before=${parsed.before ?? '(missing)'}, --after=${parsed.after ?? '(missing)'}\nexpected: no positional target and both settled snapshot references\nfield: <positional>, --before, --after\nNext: Run \`capture measure diff -h\` and read the schema before re-issuing.`,
     };
     emitResult(result, { json: parsed.json });
     process.exitCode = 1;

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

@@ -1,5 +1,5 @@
 import { type ParsedArgs } from '../../types.js';
-import { explainSnapshot, type ExplainMissingSelector } from '../../measure/explain.js';
+import { explainSnapshot, type ExplainAmbiguousSelector, 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';
 
@@ -9,10 +9,11 @@ input:
   <snap>             snapshot id in the active session or absolute artifact path (required)
   --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=…> — 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
+  --size             include size/layout provenance (box/flex/grid/constraints) before general rendering context
+  --text             include text line/baseline/font/wrap metrics before general rendering context
+  --form             include form value/geometry/caret/selection/autofill facts before general rendering context
+output: <explain selector=… matches=…> — requested size/text/form measurements lead after target identity; full cascade, border/ink, stacking, clipping, focus, scroll, query, and state context remains in the result; --json mirrors
+boundary: measurements are local to the selected snapshot. \`capture lighthouse\` runs the independent audited sweep.
 effects: read-only — reads existing snapshot artifacts, never drives the browser`;
 
 function attestation(ref: { id: string; dir: string }, meta: { settled?: boolean; settleMs?: number }) {
@@ -60,6 +61,14 @@ function recoverySections(missing: ExplainMissingSelector): FactLine[] {
   ];
 }
 
+function ambiguitySections(ambiguous: ExplainAmbiguousSelector): FactLine[] {
+  const rows = ambiguous.candidates.map((candidate, index) => fact`${index + 1}. ${candidate.selector ?? candidate.id}${typeof candidate.backendNodeId === 'number' ? ` — backend:${candidate.backendNodeId}` : ''}${candidate.axId ? ` — axid:${candidate.axId}` : ''}${candidate.axName ? ` — ax:${candidate.axName}` : ''}`);
+  return [lineList([
+    ...(ambiguous.matchCount > ambiguous.candidates.length ? [fact`candidates (first ${ambiguous.candidates.length} of ${ambiguous.matchCount}):`] : [text`candidates:`]),
+    ...rows,
+  ])];
+}
+
 function invalidInput(message: FactLine): RenderableResult {
   return {
     tag: 'error',
@@ -69,6 +78,19 @@ function invalidInput(message: FactLine): RenderableResult {
   };
 }
 
+function requestedSectionsFirst<T extends { kind: string }>(sections: readonly T[], parsed: ParsedArgs): readonly T[] {
+  const requested = new Set([
+    ...(parsed.size ? ['size'] : []),
+    ...(parsed.text ? ['text'] : []),
+    ...(parsed.form ? ['form'] : []),
+  ]);
+  if (!requested.size) return sections;
+  const element = sections.filter((section) => section.kind === 'element');
+  const detail = sections.filter((section) => requested.has(section.kind));
+  const context = sections.filter((section) => section.kind !== 'element' && !requested.has(section.kind));
+  return [...element, ...detail, ...context];
+}
+
 export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(USAGE);
@@ -110,8 +132,20 @@ export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Pr
       process.exitCode = 1;
       return;
     }
+    if (report.kind === 'ambiguous-selector') {
+      emitResult({
+        tag: 'error',
+        attestation: attestation(report.ref, report.meta),
+        attrs: { command: 'measure explain', status: 'ambiguous_selector', selector: report.selector, matches: report.matchCount, displayed: report.candidates.length },
+        summary: fact`Selector input ${report.selector} matched ${report.matchCount} recorded elements; no element was selected.`,
+        sections: ambiguitySections(report),
+        followUp: text`Retry with an exact CSS selector, axid, or numeric backend id from the candidate identity facts.`,
+      }, { json: parsed.json });
+      process.exitCode = 1;
+      return;
+    }
 
-    const sections = report.sections.map((section) => lineList(section.facts.map(({ fact: item, caveats }) => {
+    const sections = requestedSectionsFirst(report.sections, parsed).map((section) => lineList(section.facts.map(({ fact: item, caveats }) => {
       const suffix = caveatSuffix(caveats);
       return suffix ? line(item.line, suffix) : item.line;
     })));
@@ -129,7 +163,10 @@ export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Pr
         state: parsed.state?.[0] ?? 'base',
       },
       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,
+      sections: [
+        ...sections,
+        fact`Measurements are local to snapshot ${report.ref.id}; \`capture lighthouse\` runs the independent audited sweep.`,
+      ],
       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.`,

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

@@ -14,6 +14,7 @@ import { cmdMeasureCheck } from './check.js';
 import { cmdMeasureDiff } from './diff.js';
 import { cmdMeasureCensus } from './census.js';
 import { cmdMeasureExplain } from './explain.js';
+import { cmdMeasureText } from './text.js';
 import { cmdMeasureSweep } from './sweep.js';
 import { cmdMeasureMapFocus } from './map-focus.js';
 import { cmdMeasureMapScroll } from './map-scroll.js';
@@ -23,41 +24,30 @@ 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, paint) of the substrate
-  snap · check · diff · census · explain · sweep · map (focus|scroll|layers|ax|paint) — \`capture measure -h\`
+the settled-snapshot substrate — static facts at one moment; \`snap\` writes the substrate, every other leaf is a read-only query over it
+use for static rendered-page facts from a settled snapshot: layout, content, cascade provenance, targetability, and snapshot diffs
 </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>]... [--color-scheme <dark|light>]" 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] | 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).
-
-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)"/>
+export const MEASURE_USAGE = `<command name="measure" description="enriched snapshot substrate and read-only queries">
+<model>\`snap\` drives the page (or a base snapshot) and writes one settled artifact directory; every other leaf below reads that artifact and never re-drives the browser unless its target is a URL, which first creates a snapshot. Findings exit 0 — a report, not a failure. \`--gate\` (exit 2 on findings or changes) is accepted only by check and diff.</model>
+<subcommand name="snap" description="settled snapshot artifact" whenToUse="Use to capture the static rendered-page substrate that measure queries read."/>
+<subcommand name="check" description="snapshot threshold measurements" whenToUse="Use to measure selected layout and content thresholds from one snapshot."/>
+<subcommand name="diff" description="snapshot delta" whenToUse="Use to compare the measured facts from two snapshots."/>
+<subcommand name="census" description="snapshot value distributions" whenToUse="Use to count values across one or more snapshots."/>
+<subcommand name="explain" description="element rendering explanation" whenToUse="Use to inspect cascade, stacking, clipping, size, text, or form facts for one element."/>
+<subcommand name="text" description="targeted DOM-content text measurement" whenToUse="Use to read one element's direct DOM content text, font, recorded color-model values, contrast ratio, and provenance from a snapshot."/>
+<subcommand name="sweep" description="responsive environment sampling" whenToUse="Use to compare snapshot facts across values on one environment axis."/>
+<subcommand name="map" description="one snapshot facet" whenToUse="Use to read focus, scroll, layer, accessibility, or paint facts from a snapshot."/>
+</command>`;
 
-capture measure map <leaf> -h    Per-leaf usage`;
+export const MEASURE_MAP_USAGE = `<command name="map" description="one facet of a snapshot's substrate">
+<model>Focus, scroll, layers, and ax accept a URL target and create a snapshot first; paint requires an existing snapshot and reads it without browser driving.</model>
+<subcommand name="focus" description="keyboard traversal order" whenToUse="Use to inspect focus order from a snapshot."/>
+<subcommand name="scroll" description="scroll-container topology" whenToUse="Use to inspect scroll containers and their relationships."/>
+<subcommand name="layers" description="paint and compositor layers" whenToUse="Use to inspect layer allocation and paint order."/>
+<subcommand name="ax" description="accessibility and layout map" whenToUse="Use to relate accessibility-tree nodes to layout geometry."/>
+<subcommand name="paint" description="coverage above one target" whenToUse="Use to inspect elements painted above a target and their recorded coverage."/>
+</command>`;
 
 export async function measureMain(parsed: ParsedArgs, args: string[]): Promise<void> {
   const leaf = parsed.positional[0];
@@ -74,6 +64,8 @@ export async function measureMain(parsed: ParsedArgs, args: string[]): Promise<v
       return cmdMeasureCensus(rest, args);
     case 'explain':
       return cmdMeasureExplain(rest, args);
+    case 'text':
+      return cmdMeasureText(rest, args);
     case 'sweep':
       return cmdMeasureSweep(rest, args);
     case 'map':

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

@@ -8,8 +8,9 @@ const USAGE = `capture measure map ax [url|snap] — accessibility-tree facts re
 
 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
+  --artifact-dir <path>  root for the one-shot snapshot bundle when the target is a URL
 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`;
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot bundle under --artifact-dir when supplied`;
 
 function recoveryResult(err: unknown): RenderableResult {
   const detail = err instanceof ArtifactResolutionError || err instanceof Error

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

@@ -8,8 +8,9 @@ const USAGE = `capture measure map focus [url|snap] — keyboard traversal facts
 
 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
+  --artifact-dir <path>  root for the one-shot snapshot bundle when the target is a URL
 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`;
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot bundle under --artifact-dir when supplied`;
 
 function recoveryResult(err: unknown): RenderableResult {
   const detail = err instanceof ArtifactResolutionError || err instanceof Error

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

@@ -8,8 +8,10 @@ const USAGE = `capture measure map layers [url|snap] — paint/compositor facts
 
 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`;
+  --artifact-dir <path>  root for the one-shot snapshot bundle when the target is a URL
+  --limit <n>  maximum final layer records in prose and JSON (default 25)
+output: <layer-map …> — layer bounds, compositing reasons, painted-node counts, per-node membership, and available source provenance for layer-affecting declarations; backend-id corpora are limited to 50 per list with omitted counts, and --json mirrors the same cap
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot bundle under --artifact-dir when supplied`;
 
 function errorResult(err: unknown): RenderableResult {
   const detail = err instanceof Error ? err.message : String(err);
@@ -51,7 +53,7 @@ export async function cmdMeasureMapLayers(parsed: ParsedArgs, _args: string[]):
     const ref = await resolveSnapRef(target, {
       onUrl: async (url) => captureMeasureSnap(parsed, url),
     });
-    emitResult(buildMeasureMapLayersResult(ref), { json: parsed.json });
+    emitResult(buildMeasureMapLayersResult(ref, parsed.limit), { json: parsed.json });
   } catch (err) {
     emitResult(errorResult(err), { json: parsed.json });
     process.exitCode = 1;

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

@@ -8,8 +8,9 @@ const USAGE = `capture measure map scroll [url|snap] — scroll-container topolo
 
 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
+  --artifact-dir <path>  root for the one-shot snapshot bundle when the target is a URL
 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`;
+effects: read-only over an existing snapshot artifact; a URL target writes one settled snapshot bundle under --artifact-dir when supplied`;
 
 type CaptureSnap = (parsed: ParsedArgs, target: string) => Promise<SnapUrlResult>;
 type Emit = typeof emitResult;

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

@@ -4,7 +4,7 @@ import { randomBytes } from 'crypto';
 
 import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
-import { isRecorderHeldClient } from '../../recorder-client.js';
+import { isMotionHeldClient } from '../../host/held-client.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
 import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
 import { captureSnapshotSubstrate, COLLECTOR_NAMES, SnapshotCaptureTimeout } from '../../measure/snapshot.js';
@@ -40,8 +40,9 @@ input:
   --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
+  --artifact-dir <path>      root for this sessionless snapshot bundle; ignored when an active session owns the snapshot
 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
-effects: drives the target page to capture; writes one snapshot artifact directory under the active (or a private one-shot) session. --color-scheme transiently applies Emulation.setEmulatedMedia and clears it after capture.`;
+effects: drives the target page to capture; writes one snapshot artifact directory under the active session or, when sessionless, a one-shot bundle under --artifact-dir. --color-scheme transiently applies Emulation.setEmulatedMedia and clears it after capture.`;
 
 interface SnapshotMetaForBase {
   readonly url?: string | null;
@@ -132,7 +133,7 @@ interface ScreenInfo {
  * never clears an override it cannot restore.
  */
 async function viewportOwnership(client: ViewportClient): Promise<ViewportOwnership> {
-  if (isRecorderHeldClient(client)) return { owner: 'recorder' };
+  if (isMotionHeldClient(client)) return { owner: 'recorder' };
   try {
     const [page, screens] = await Promise.all([
       client.send('Runtime.evaluate', {
@@ -285,7 +286,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
     let artifacts: readonly string[] = [];
     await withConnection(connectionArgs, async (client, tab) => {
       await withAppliedColorScheme(client, colorScheme, async () => withAppliedViewport(client, viewport, async () => {
-        const oneshot = active ? undefined : createOneshotSession('measure');
+        const oneshot = active ? undefined : createOneshotSession('measure', parsed.artifactDir);
         const destination = active ? path.join(active.dir, 'measure', 'snaps') : oneshot!.artifactsDir;
         snapDir = path.join(destination, snapId);
         allocatedRoot = active ? snapDir : oneshot!.dir;

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

@@ -7,7 +7,8 @@ import { withConnection } from '../../connection.js';
 import { captureSnapshotSubstrate } from '../../measure/snapshot.js';
 import { createOneshotSession } from '../../../session/commands.js';
 import { getActiveSession } from '../../../session-context.js';
-import { emitResult, fact, line, lineList, renderResult, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+import { capped, emitResult, fact, line, lineList, renderResult, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+import { normalizeFailure } from '../../../errors.js';
 import { assertSweepBounds, parsePositiveNumber } from '../../leaf-grammar.js';
 import {
   SWEEP_AXES,
@@ -30,13 +31,14 @@ import {
 const USAGE = `capture measure sweep [url] --axis <axis> — responsive/environment sampling with recursive bracketing of observed state changes
 
 input:
-  [url]                     page to sweep; outside a session, snapshots and sweep.json are written under one private one-shot measure directory
+  [url]                     match an existing page tab by URL; this does not open a URL — run inside \`capture session start --url …\` when no matching tab exists
   --axis <axis>             width|dpr|zoom|color-scheme|reduced-motion (required)
   --from <val>              numeric range start, or a color-scheme/reduced-motion value
   --to <val>                numeric range end, or a color-scheme/reduced-motion value
   --viewport-height <val>   fixed viewport height for width/dpr sweeps
+  --artifact-dir <path>     root for this sessionless sweep bundle; ignored when an active session owns the sweep
 output: <sweep axis=… samples=… transitions=…> — observed state facts per sampled point, each sampled snapshot path included; --json mirrors
-effects: drives the page repeatedly under CDP Emulation settings; writes one snapshot substrate per sampled point plus sweep.json`;
+effects: drives the page repeatedly under CDP Emulation settings; writes one snapshot substrate per sampled point plus sweep.json under the active session or, when sessionless, a one-shot bundle under --artifact-dir`;
 
 const SAMPLE_LIMIT = 96;
 
@@ -80,9 +82,11 @@ function valuesForAxis(axis: SweepAxis, parsed: ParsedArgs): Array<number | stri
 }
 
 export function transitionSections(artifact: SweepArtifact): FactLine[] {
-  const ranges = artifact.ranges.map((range) => line(fact`  observed matching fingerprint ${range.from}–${range.to} → ${range.snapId} (${range.snapDir})`));
+  const ranges = artifact.ranges.map((range) => fact`  observed matching fingerprint ${range.from}–${range.to} → ${range.snapId} (${range.snapDir})`);
   const transitions = artifact.transitions.flatMap((transition, index) => {
-    const header = line(fact`${index + 1}. bracketed between ${transition.bracket.from} and ${transition.bracket.to} — ${transition.before} → ${transition.after}`);
+    const header = transition.uncertainty === 'sampling_limit'
+      ? fact`${index + 1}. observed difference unresolved between ${transition.bracket.from} and ${transition.bracket.to}: the ${artifact.sampleLimit} sample limit stopped refinement — ${transition.before} → ${transition.after}`
+      : fact`${index + 1}. bracketed between ${transition.bracket.from} and ${transition.bracket.to} — ${transition.before} → ${transition.after}`;
     const changes = transition.changes.slice(0, 12).map((change) => {
       const provenance = change.provenance?.source ? fact` (${change.provenance.selector ?? 'winning declaration'}${change.provenance.specificity ? `, specificity ${change.provenance.specificity}` : ''}, ${change.provenance.source})` : change.provenance?.selector ? fact` (${change.provenance.selector}${change.provenance.specificity ? `, specificity ${change.provenance.specificity}` : ''})` : text``;
       return line(fact`   ${change.selector} ${change.property}: ${change.before ?? 'unset'} → ${change.after ?? 'unset'}`, provenance);
@@ -136,7 +140,7 @@ export async function runMeasureSweep(parsed: ParsedArgs, _args: string[], overr
 
   const axis = parsed.axis;
   const active = dependencies.getActiveSession();
-  const oneShot = active ? undefined : dependencies.createOneshotSession('measure');
+  const oneShot = active ? undefined : dependencies.createOneshotSession('measure', parsed.artifactDir);
   const snapsDir = active ? path.join(active.dir, 'measure', 'snaps') : oneShot!.artifactsDir;
   const artifactDir = active ? path.join(active.dir, 'measure', 'sweeps', sweepId()) : path.join(oneShot!.dir, 'measure', 'sweeps', sweepId());
   const recoverySamples: Array<SweepRecovery['samples'][number]> = [];
@@ -204,7 +208,7 @@ export async function runMeasureSweep(parsed: ParsedArgs, _args: string[], overr
     const samples = (axis === 'width' || axis === 'dpr' || axis === 'zoom') ? [...samplesByValue.values()].sort((a, b) => Number(a.value) - Number(b.value)) : values.map((value) => samplesByValue.get(String(value))!).filter(Boolean);
     const from = values[0];
     const to = values[values.length - 1];
-    const analyzed = analyzeSweepSamples(axis, from, to, samples);
+    const analyzed = analyzeSweepSamples(axis, from, to, samples, uncertainties);
     const artifact: SweepArtifact = { axis, from, to, capturedAt: new Date().toISOString(), samples, ...analyzed, uncertainties, sampleLimit: SAMPLE_LIMIT, environmentRestoration: environmentFacts };
     const artifactPath = writeSweepArtifact(artifactDir, artifact);
     const result: RenderableResult = {
@@ -214,13 +218,14 @@ export async function runMeasureSweep(parsed: ParsedArgs, _args: string[], overr
       followUp: samples.length > 1 ? fact`Compare two sampled substrates with \`capture measure diff --before ${samples[0].snapDir} --after ${samples[1].snapDir}\`.` : undefined,
     };
     dependencies.emitResult(result, { json: parsed.json });
-  } catch {
+  } catch (error) {
     const evidenceOnly = recoverySamples.some((sample) => sample.status === 'evidence_only');
+    const failure = normalizeFailure(error).descriptor;
     const recoveryPath = writeSweepRecoveryArtifact(artifactDir, { axis, capturedAt: new Date().toISOString(), reason: evidenceOnly ? 'evidence_only' : 'capture_failed', environmentRestoration, samples: recoverySamples });
     dependencies.emitResult({
-      tag: 'error', attrs: { command: 'measure sweep', status: evidenceOnly ? 'evidence_only' : 'sweep_failed', path: recoveryPath },
-      summary: fact`Sweep did not produce a queryable sample set. Recovery artifact: ${recoveryPath}.`,
-      sections: recoverySamples.length ? [text`Partial snapshot/recovery provenance:`, ...recoverySamples.map((sample) => fact`${sample.value}: ${sample.snapDir} status=${sample.status} captured=${sample.captured} settled=${sample.settled} artifacts=${sample.artifacts.join(', ') || 'none'} unstable=${sample.unstableRegions.map((region) => `${region.id}${region.reason ? `:${region.reason}` : ''}`).join(', ') || 'none'}`), fact`environment restoration: ${environmentRestoration}`] : undefined,
+      tag: 'error', attrs: { command: 'measure sweep', status: evidenceOnly ? 'evidence_only' : failure.code, path: recoveryPath },
+      summary: fact`Sweep did not produce a queryable sample set: ${capped(failure.message, 600)} Recovery artifact: ${recoveryPath}.`,
+      sections: recoverySamples.length ? [text`Partial snapshot/recovery provenance:`, ...recoverySamples.map((sample) => fact`${sample.value}: ${sample.snapDir} status=${sample.status} captured=${String(sample.captured)} settled=${String(sample.settled)} artifacts=${sample.artifacts.join(', ') || 'none'} unstable=${sample.unstableRegions.map((region) => `${region.id}${region.reason ? `:${region.reason}` : ''}`).join(', ') || 'none'}`), fact`environment restoration: ${environmentRestoration}`] : undefined,
     }, { json: parsed.json });
     process.exitCode = 1;
   }