@crouton-kit/capture 1.3.6 → 1.3.8

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);
+}

package/src/cdp/coordinates.ts

@@ -0,0 +1,158 @@
+/**
+ * Shared quad math and frame/shadow coordinate stitching helpers for `measure snap`.
+ *
+ * These helpers are pure (`axisAlignedRectFromQuad`, `composeFrameTransform`,
+ * `toTopViewportQuad`) except `getContentQuadBox`, which calls the existing `CDPClient.send`
+ * directly (no new client abstraction). Quad helpers always preserve the original four
+ * points from CDP; an axis-aligned rect is only ever a derived convenience alongside them,
+ * never a replacement — several instruments (raster crops, hit-test, motion masks) need the
+ * real quad for transformed/rotated/wrapped elements.
+ */
+
+import type { CDPClient } from './client.js';
+
+/** Four corner points clockwise from top-left, in a single local frame's coordinate space: [x1,y1,x2,y2,x3,y3,x4,y4]. */
+export type Quad = [number, number, number, number, number, number, number, number];
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface BoxModelQuads {
+  content: Quad;
+  padding: Quad;
+  border: Quad;
+  margin: Quad;
+  width: number;
+  height: number;
+}
+
+export interface ContentQuadBox {
+  /**
+   * One quad per DOM fragment. Most elements produce exactly one; an inline element wrapped
+   * across lines (or an element split by column/fragmentation) produces more than one, and
+   * every fragment is preserved rather than collapsed into a single bounding rect.
+   */
+  quads: Quad[];
+  /** `DOM.getBoxModel`'s content/padding/border/margin quads plus width/height, in the same local coordinate space as `quads`. */
+  boxModel: BoxModelQuads;
+}
+
+/** Identifies a DOM node the way CDP's `DOM.getContentQuads`/`DOM.getBoxModel` accept it. */
+export type NodeRef = { backendNodeId: number } | { nodeId: number } | { objectId: string };
+
+/**
+ * Reads both the content quad(s) and the full box model (content/padding/border/margin) for
+ * one node via `DOM.getContentQuads` and `DOM.getBoxModel`. Coordinates are in the node's own
+ * frame's local viewport space — use `composeFrameTransform`/`toTopViewportQuad` to stitch
+ * iframe-nested coordinates into top-viewport space.
+ */
+export async function getContentQuadBox(client: CDPClient, ref: NodeRef): Promise<ContentQuadBox> {
+  const [quadsResult, boxResult] = await Promise.all([
+    client.send('DOM.getContentQuads', ref as unknown as Record<string, unknown>) as Promise<{
+      quads: number[][];
+    }>,
+    client.send('DOM.getBoxModel', ref as unknown as Record<string, unknown>) as Promise<{
+      model: {
+        content: number[];
+        padding: number[];
+        border: number[];
+        margin: number[];
+        width: number;
+        height: number;
+      };
+    }>,
+  ]);
+
+  const model = boxResult.model;
+
+  return {
+    quads: quadsResult.quads.map(asQuad),
+    boxModel: {
+      content: asQuad(model.content),
+      padding: asQuad(model.padding),
+      border: asQuad(model.border),
+      margin: asQuad(model.margin),
+      width: model.width,
+      height: model.height,
+    },
+  };
+}
+
+function asQuad(points: number[]): Quad {
+  if (points.length !== 8) {
+    throw new Error(`Expected an 8-number quad (x1,y1,x2,y2,x3,y3,x4,y4), got ${points.length} numbers`);
+  }
+  return points as Quad;
+}
+
+/** Derives the axis-aligned bounding rect of a quad. Purely a convenience — `quad` itself stays the source of truth. */
+export function axisAlignedRectFromQuad(quad: Quad): Rect {
+  const xs = [quad[0], quad[2], quad[4], quad[6]];
+  const ys = [quad[1], quad[3], quad[5], quad[7]];
+  const minX = Math.min(...xs);
+  const maxX = Math.max(...xs);
+  const minY = Math.min(...ys);
+  const maxY = Math.max(...ys);
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+/**
+ * One nested frame's offset: the translation (and optional scale, e.g. CSS zoom) of a child
+ * frame's content-box origin within its parent frame's local coordinate space.
+ */
+export interface FrameOffset {
+  dx: number;
+  dy: number;
+  /** Defaults to 1 (no scale) when omitted. */
+  scaleX?: number;
+  scaleY?: number;
+}
+
+export interface FrameTransform {
+  dx: number;
+  dy: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+/**
+ * Composes a chain of nested iframe offsets into one affine transform from the innermost
+ * (target) frame's local coordinates to top-viewport coordinates. `chain` is ordered from the
+ * outermost transition first (the top frame's offset into its direct child) to the innermost
+ * transition last (the target's immediate parent frame's offset into the target frame).
+ *
+ * Shadow DOM does not need this — shadow-root content shares its host element's coordinate
+ * space, so shadow-root traversal only affects which node a query resolves to, not its quad.
+ */
+export function composeFrameTransform(chain: FrameOffset[]): FrameTransform {
+  let transform: FrameTransform = { dx: 0, dy: 0, scaleX: 1, scaleY: 1 };
+  for (const offset of chain) {
+    const scaleX = offset.scaleX ?? 1;
+    const scaleY = offset.scaleY ?? 1;
+    transform = {
+      dx: transform.dx + offset.dx * transform.scaleX,
+      dy: transform.dy + offset.dy * transform.scaleY,
+      scaleX: transform.scaleX * scaleX,
+      scaleY: transform.scaleY * scaleY,
+    };
+  }
+  return transform;
+}
+
+/** Applies a composed `FrameTransform` to every point of a quad, mapping it into top-viewport space. */
+export function toTopViewportQuad(quad: Quad, transform: FrameTransform): Quad {
+  return [
+    quad[0] * transform.scaleX + transform.dx,
+    quad[1] * transform.scaleY + transform.dy,
+    quad[2] * transform.scaleX + transform.dx,
+    quad[3] * transform.scaleY + transform.dy,
+    quad[4] * transform.scaleX + transform.dx,
+    quad[5] * transform.scaleY + transform.dy,
+    quad[6] * transform.scaleX + transform.dx,
+    quad[7] * transform.scaleY + transform.dy,
+  ];
+}

package/src/cdp/dispatch.ts

@@ -6,6 +6,10 @@ import { cmdScreenshot, cmdClick, cmdType, cmdA11y } from './commands/ui.js';
 import { cmdRecord, cmdNavigate, cmdNetwork } from './commands/traffic.js';
 import { cmdHar } from './commands/har.js';
 import { cmdLib } from './commands/lib.js';
+import { cmdCdp } from './commands/cdp.js';
+import { cmdBridgeServe } from './commands/bridge-serve.js';
+import { measureMain } from './commands/measure/index.js';
+import { motionMain } from './commands/motion/index.js';
 
 export async function cdpMain(): Promise<void> {
   const args = process.argv.slice(2);
@@ -26,6 +30,10 @@ export async function cdpMain(): Promise<void> {
     case 'network': return cmdNetwork(parsed, args);
     case 'har': return cmdHar(parsed, args);
     case 'lib': return cmdLib(parsed, args);
+    case 'cdp': return cmdCdp(parsed, args);
+    case 'measure': return measureMain(parsed, args);
+    case 'motion': return motionMain(parsed, args);
+    case '__bridge-serve': return cmdBridgeServe(parsed, args);
     default:
       console.log(CDP_USAGE);
   }

package/src/cdp/domains.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared CDP domain enablement and reversible state-forcing helpers for `measure`/`motion`.
+ *
+ * Every helper here takes an already-connected `CDPClient` (see ./client.ts) and calls
+ * `client.send(...)` directly — there is no separate client abstraction. Domain `.enable`
+ * calls are idempotent in CDP, so callers may call these more than once per connection
+ * (e.g. once per collector) without ill effect.
+ */
+
+import type { CDPClient } from './client.js';
+
+/**
+ * Enables the CDP domains the `measure snap` substrate collectors need: frame/navigation
+ * metadata (Page), element geometry and tree access (DOM), computed style + winning-rule
+ * provenance (CSS — requires DOM.enable first), the accessibility tree (Accessibility),
+ * compositor layer facts (LayerTree), the animation inventory (Animation), and script
+ * execution for hit-test/text/form introspection (Runtime).
+ */
+export async function enableDomainsForSnap(client: CDPClient): Promise<void> {
+  await client.send('Page.enable');
+  await client.send('DOM.enable');
+  await client.send('CSS.enable');
+  await Promise.all([
+    client.send('Accessibility.enable'),
+    client.send('LayerTree.enable'),
+    client.send('Animation.enable'),
+    client.send('Runtime.enable'),
+  ]);
+}
+
+/**
+ * Enables the CDP domains the motion recorder bridge needs: frame/navigation metadata and
+ * `Page.startScreencast` (Page), element geometry for rect/selector resolution (DOM), script
+ * execution for the injected Mutation/Resize/Performance observers (Runtime), request/response
+ * timing for `motion response` (Network), and playback-rate control for the animation inventory
+ * (Animation). `Tracing.start` is configured with its own category set by the recorder bridge
+ * (U13) and is not a plain `.enable` call, so it is not included here.
+ */
+export async function enableDomainsForMotionRec(client: CDPClient): Promise<void> {
+  await client.send('Page.enable');
+  await client.send('DOM.enable');
+  await Promise.all([
+    client.send('Runtime.enable'),
+    client.send('Network.enable'),
+    client.send('Animation.enable'),
+  ]);
+}
+
+/**
+ * CSS pseudo-classes CDP can force directly via `CSS.forcePseudoState`. Real control states
+ * (checked/open/disabled/invalid) are not pseudo-classes in this sense — collectors toggle
+ * those with reversible DOM property writes and restore them after capture instead of using
+ * this helper.
+ */
+export type ForcedPseudoClass =
+  | 'active'
+  | 'focus'
+  | 'focus-visible'
+  | 'focus-within'
+  | 'hover'
+  | 'target'
+  | 'visited';
+
+/**
+ * Forces (or, called with an empty array, clears) a set of CSS pseudo-classes on a node.
+ * Requires `CSS.enable` (see `enableDomainsForSnap`). The caller is responsible for restoring
+ * state after capture by calling this again with `[]`.
+ */
+export async function forcePseudoStateForNode(
+  client: CDPClient,
+  nodeId: number,
+  forcedPseudoClasses: ForcedPseudoClass[],
+): Promise<void> {
+  await client.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses });
+}