@crouton-kit/capture 1.3.7 → 1.3.8

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

@@ -8,6 +8,8 @@ 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);
@@ -29,6 +31,8 @@ export async function cdpMain(): Promise<void> {
     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 });
+}