@crouton-kit/capture 1.3.7 → 1.3.8

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

@@ -0,0 +1,31 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure census [--snap <id>]... [--url <url>]... [--set-file <path>] --axis <axis>
+
+Value distributions and token audits across one or more snapshots. Each
+--snap/--url is repeatable to build a cross-page distribution; a --url
+target creates a one-shot snap first.
+
+Options:
+  --snap <id>          Existing snapshot id/path (repeatable)
+  --url <url>          URL to snap first (repeatable)
+  --set-file <path>    File listing additional snap/url targets, one per line
+  --viewport <WxH>     Viewport to snap at (repeatable)
+  --axis <axis>        color|font|spacing|radius|shadow|animation|geometry|media|queries
+
+Not yet implemented.`;
+
+export async function cmdMeasureCensus(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'measure census', status: 'not_implemented' },
+    summary: fact`\`measure census\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

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

@@ -0,0 +1,35 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure check [url|snap] [--for <checks>] [--viewport <WxH>]... [--gate]
+
+Threshold/fact checks over a settled snapshot's substrate: overlap,
+offscreen, overflow, tap-target size, contrast, hit-test receiver,
+truncation, form visibility, media/replaced anomalies, and animation
+facts. A URL target creates a one-shot snap first.
+
+Options:
+  --for <checks>    Comma-separated check names (e.g.
+                    overlap,offscreen,overflow,tap-targets,contrast,
+                    hit-test,truncation) or a category
+                    (geometry|content|targetability|forms|animation|all).
+                    Omit for every check.
+  --viewport <WxH>  Viewport to check at (repeatable, for a discrete
+                    multi-viewport sweep)
+  --gate            Exit 2 if any check finds something (default: exit 0)
+
+Not yet implemented.`;
+
+export async function cmdMeasureCheck(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'measure check', status: 'not_implemented' },
+    summary: fact`\`measure check\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

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

@@ -0,0 +1,32 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure diff --before <snap> --after <snap> [--pixels] [--full] [--gate]
+
+Structured before/after diff over two snapshots: style/geometry/text/form/
+media deltas, cascade provenance, and reflow attribution. No positional
+target — both snapshots must already exist.
+
+Options:
+  --before <snap>   Earlier snapshot id/path (required)
+  --after <snap>    Later snapshot id/path (required)
+  --pixels          Also report raster regions not explained by geometry
+  --full            Expand to state-matrix deltas and complete per-element
+                     change records
+  --gate            Exit 2 if any element changed (default: exit 0)
+
+Not yet implemented.`;
+
+export async function cmdMeasureDiff(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'measure diff', status: 'not_implemented' },
+    summary: fact`\`measure diff\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

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

@@ -0,0 +1,31 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure explain <snap> --selector <sel> [--size] [--text] [--form]
+
+Per-element cascade/stacking/clipping explanation over one snapshot, plus
+optional detail sections.
+
+Options:
+  --selector <sel>   Element selector (required)
+  --size             Include size/layout provenance (flex/grid/intrinsic)
+  --text             Include text/line-box/wrap detail
+  --form             Include form/caret/selection/autofill detail (redacted)
+
+With no detail flag, returns the standard compact element explanation.
+
+Not yet implemented.`;
+
+export async function cmdMeasureExplain(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'measure explain', status: 'not_implemented' },
+    summary: fact`\`measure explain\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

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

@@ -0,0 +1,114 @@
+/**
+ * `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 { 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';
+
+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)
+
+  explain <snap> --selector <sel> [--size] [--text] [--form]
+                                            Per-element cascade/stacking/clipping/size/text/form explanation
+
+  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`;
+
+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`;
+
+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:
+      console.error(`Unknown measure leaf: ${leaf}\n\n${MEASURE_USAGE}`);
+      process.exit(1);
+  }
+}
+
+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 undefined:
+      console.log(MEASURE_MAP_USAGE);
+      return;
+    default:
+      console.error(`Unknown measure map leaf: ${sub}\n\n${MEASURE_MAP_USAGE}`);
+      process.exit(1);
+  }
+}

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

@@ -0,0 +1,24 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure map focus [url|snap]
+
+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.
+
+Not yet implemented.`;
+
+export async function cmdMeasureMapFocus(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  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

@@ -0,0 +1,25 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure map layers [url|snap]
+
+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.
+
+Not yet implemented.`;
+
+export async function cmdMeasureMapLayers(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  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

@@ -0,0 +1,24 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure map scroll [url|snap]
+
+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.
+
+Not yet implemented.`;
+
+export async function cmdMeasureMapScroll(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  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);
+}

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

@@ -0,0 +1,36 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure snap [url|snap] [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled] [--pixels] [--state <state[:selector]>]... [--viewport <WxH>]...
+
+Drive the page (or re-capture states over a base snapshot) and write one
+settled snapshot substrate directory: geometry, styles, hit-test, text,
+forms, animation, ax, queries, focus, scroll, layers, and (with --pixels)
+per-element crops. Every other measure/motion query leaf reads this
+artifact instead of re-driving the browser.
+
+Options:
+  --freeze-animations         Pause CSS/WAAPI animation before capture
+  --settle-timeout <ms>       Override the default 5000ms settle wait
+  --capture-unsettled         Write full substrate despite non-settlement,
+                               marking unstable regions
+  --pixels                    Also write per-element raster crops
+  --state <state[:selector]>  Force a pseudo-state or real control state
+                               (repeatable)
+  --viewport <WxH>            Viewport to snap at (repeatable)
+
+Not yet implemented.`;
+
+export async function cmdMeasureSnap(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'measure snap', status: 'not_implemented' },
+    summary: fact`\`measure snap\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

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

@@ -0,0 +1,30 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture measure sweep [url] --axis <axis> [--from <val>] [--to <val>] [--viewport-height <val>]
+
+Responsive/environment sampling: repeated snap captures across an axis
+(width, dpr, zoom, color-scheme, reduced-motion, ...), binary-searched to
+find transition points and piecewise-stable ranges.
+
+Options:
+  --axis <axis>             The sampled axis (default: width)
+  --from <val>              Range start (axis-dependent: width px, dpr, zoom, ...)
+  --to <val>                Range end (axis-dependent)
+  --viewport-height <val>   Fixed viewport height while sweeping width/dpr/zoom
+
+Not yet implemented.`;
+
+export async function cmdMeasureSweep(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'measure sweep', status: 'not_implemented' },
+    summary: fact`\`measure sweep\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

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

@@ -0,0 +1,60 @@
+/**
+ * `capture motion` branch router.
+ *
+ * Shifts the consumed leaf token out of `parsed.positional` before handing
+ * off, so every leaf command still finds its own primary target (a URL, a
+ * recording id, ...) at `positional[0]` exactly as every other capture
+ * command does.
+ */
+import { type ParsedArgs } from '../../types.js';
+import { cmdMotionRec } from './rec.js';
+import { cmdMotionMask } from './mask.js';
+import { cmdMotionTimeline } from './timeline.js';
+import { cmdMotionJank } from './jank.js';
+import { cmdMotionResponse } from './response.js';
+
+export const MOTION_USAGE = `capture motion — recorder lifecycle + read-only queries over a finalized recording.
+
+\`rec\` drives (and records) the browser, one-shot or composed across
+intervening commands; every other leaf below is a cheap read over the
+finalized recording artifact.
+
+Leaves:
+  rec [url] --do <action> [--duration <ms>]   One-shot: drive one action, record it
+  rec --start                                 Composed: arm the recorder (needs an active session)
+  rec --stop                                  Composed: finalize the recorder
+
+  mask <rec>                                  Motion-diff composite image + per-region facts
+  timeline <rec> --element <sel> [--prop <prop>]
+                                               Per-frame geometry/scroll/property timeline
+  jank <rec>                                  Dropped-frame/long-task/layout-shift facts
+  response <rec> [--action <action>]          Input-to-settled response timeline
+
+Every leaf defaults to rendered prose; --json mirrors the same result as JSON.
+Exit codes: 0 always — findings are a report, not a failure. No leaf accepts --gate.
+
+capture motion <leaf> --help    Per-leaf usage`;
+
+export async function motionMain(parsed: ParsedArgs, args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+
+  switch (leaf) {
+    case 'rec':
+      return cmdMotionRec(rest, args);
+    case 'mask':
+      return cmdMotionMask(rest, args);
+    case 'timeline':
+      return cmdMotionTimeline(rest, args);
+    case 'jank':
+      return cmdMotionJank(rest, args);
+    case 'response':
+      return cmdMotionResponse(rest, args);
+    case undefined:
+      console.log(MOTION_USAGE);
+      return;
+    default:
+      console.error(`Unknown motion leaf: ${leaf}\n\n${MOTION_USAGE}`);
+      process.exit(1);
+  }
+}

package/src/cdp/commands/motion/jank.ts

@@ -0,0 +1,22 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture motion jank <rec>
+
+Dropped-frame/long-task/layout-shift facts over a finalized recording.
+
+Not yet implemented.`;
+
+export async function cmdMotionJank(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'motion jank', status: 'not_implemented' },
+    summary: fact`\`motion jank\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

package/src/cdp/commands/motion/mask.ts

@@ -0,0 +1,23 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture motion mask <rec>
+
+Motion-diff composite image over a finalized recording, plus per-region
+area/distance/velocity facts and element attribution where resolvable.
+
+Not yet implemented.`;
+
+export async function cmdMotionMask(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'motion mask', status: 'not_implemented' },
+    summary: fact`\`motion mask\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

package/src/cdp/commands/motion/rec.ts

@@ -0,0 +1,33 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture motion rec [url] --do <action> [--duration <ms>]
+       capture motion rec --start
+       capture motion rec --stop [--rec-id <id>]
+
+One-shot (\`--do\`): drives one scripted action and records it end to end.
+Composed (\`--start\` ... intervening commands ... \`--stop\`): records
+whatever the active session does across multiple independent commands.
+
+Options:
+  --do <action>      One-shot action to drive and record (e.g. click:SEL)
+  --duration <ms>    Recording duration override
+  --start            Arm the composed recorder (requires an active session)
+  --stop             Finalize the composed recorder
+  --rec-id <id>      Explicit recording id (default: the session's active recording)
+
+Not yet implemented.`;
+
+export async function cmdMotionRec(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'motion rec', status: 'not_implemented' },
+    summary: fact`\`motion rec\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

package/src/cdp/commands/motion/response.ts

@@ -0,0 +1,26 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture motion response <rec> [--action <action>]
+
+Input-to-settled response timeline over a finalized recording:
+input -> mutation -> layout -> paint -> network -> settle.
+
+Options:
+  --action <action>   Narrow to one recorded action
+
+Not yet implemented.`;
+
+export async function cmdMotionResponse(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'motion response', status: 'not_implemented' },
+    summary: fact`\`motion response\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}

package/src/cdp/commands/motion/timeline.ts

@@ -0,0 +1,27 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `Usage: capture motion timeline <rec> --element <sel> [--prop <prop>]
+
+Per-frame geometry/scroll/property values for one element across a
+finalized recording.
+
+Options:
+  --element <sel>   Element selector to track (required)
+  --prop <prop>     Additional CSS/computed property to sample per frame
+
+Not yet implemented.`;
+
+export async function cmdMotionTimeline(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'motion timeline', status: 'not_implemented' },
+    summary: fact`\`motion timeline\` is not implemented yet.`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exit(1);
+}