@crouton-kit/capture 1.3.7 → 1.3.9

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/detect.ts

@@ -118,6 +118,37 @@ function getLocalhostListeningPorts(): number[] {
   }
 }
 
+function getListeningProcessNames(): Map<number, string> {
+  const names = new Map<number, string>();
+  try {
+    const output = execSync('lsof -nP -iTCP -sTCP:LISTEN -Fpcn 2>/dev/null', {
+      encoding: 'utf-8',
+    });
+    let command: string | null = null;
+    for (const line of output.split('\n')) {
+      if (line.startsWith('c')) {
+        command = line.slice(1);
+      } else if (command && line.startsWith('n')) {
+        const match = line.match(/:(\d+)(?:\s|$)/);
+        if (match) names.set(Number(match[1]), command);
+      }
+    }
+  } catch {
+    // Process identity is an optional refinement; CDP probing still works.
+  }
+  return names;
+}
+
+export function identifyBrowserBundleId(browser: string, processName?: string): string {
+  // A listening process is stronger identity than Chromium's generic
+  // Browser/User-Agent strings: Arc and Spotify both report as "Chrome".
+  const identity = (processName ?? browser).toLowerCase();
+  for (const [bundleId, patterns] of Object.entries(BROWSER_PATTERNS)) {
+    if (patterns.some((pattern) => identity.includes(pattern))) return bundleId;
+  }
+  return 'unknown';
+}
+
 export interface CdpEndpoint {
   port: number;
   app: string;
@@ -128,25 +159,18 @@ export interface CdpEndpoint {
 
 export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
   const ports = getLocalhostListeningPorts();
+  const processNames = getListeningProcessNames();
   const results: CdpEndpoint[] = [];
 
   // Probe ports in parallel for speed
   const probes = ports.map(async (port) => {
     const probe = await probeCdpPort(port);
     if (probe) {
-      // Map browser string to bundle ID for default browser matching
-      const lower = probe.browser.toLowerCase();
-      let bundleId = 'unknown';
-      for (const [bid, patterns] of Object.entries(BROWSER_PATTERNS)) {
-        if (patterns.some((p) => lower.includes(p))) {
-          bundleId = bid;
-          break;
-        }
-      }
+      const processName = processNames.get(port);
       results.push({
         port,
-        app: probe.app,
-        bundleId,
+        app: processName ?? probe.app,
+        bundleId: identifyBrowserBundleId(probe.browser, processName),
         isElectron: probe.isElectron,
         hasPageTarget: probe.hasPageTarget,
       });
@@ -179,8 +203,13 @@ export function pickPreferredEndpoint(
     if (match) return match;
   }
 
-  // Fall back to first non-Electron, then first found
-  const nonElectron = candidates.find((p) => !p.isElectron);
+  // Prefer a recognized browser over other Chromium hosts (Spotify, app
+  // shells), then fall back to the original non-Electron ordering.
+  const knownBrowser = candidates.find(
+    (endpoint) => endpoint.bundleId !== 'unknown' && !endpoint.isElectron,
+  );
+  if (knownBrowser) return knownBrowser;
+  const nonElectron = candidates.find((endpoint) => !endpoint.isElectron);
   return nonElectron ?? candidates[0];
 }
 

package/src/cdp/dispatch.ts

@@ -1,36 +1,86 @@
-import { parseCliArgs } from './args.js';
-import { CDP_USAGE } from './usage.js';
-import { cmdDetect, cmdList, cmdOpen, cmdResetTab } from './commands/tabs.js';
-import { cmdExec } from './commands/exec.js';
-import { cmdScreenshot, cmdClick, cmdType, cmdA11y } from './commands/ui.js';
-import { cmdRecord, cmdNavigate, cmdNetwork } from './commands/traffic.js';
-import { cmdHar } from './commands/har.js';
+/**
+ * Shared dispatch for every routed command. Two jobs live here:
+ *
+ *  1. Route each root (`session`, `page`, `tab`, `measure`, `motion`,
+ *     `cdp`, `lib`, hidden `__bridge-serve`) to its branch main.
+ *  2. Invoke the `--gate` guard ONCE for the whole surface: every command
+ *     that is not `measure check|diff` rejects the flag structurally here,
+ *     before any branch main runs.
+ */
+import { parseCliSyntax, resolveCliContext, validateCliInvocation } from './args.js';
+import { type ParsedArgs } from './types.js';
+import { isGateLeaf, rejectUnsupportedGate } from './commands/gate-guard.js';
+import { getActiveSession } from '../session-context.js';
+import { admitSessionOperation } from '../session/coordinator.js';
+import { sessionMain } from '../session/commands.js';
+import { pageMain } from './commands/page/index.js';
+import { tabMain } from './commands/tab/index.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';
+
+/** The dotted leaf name the gate rejection reports, derived from the parsed
+ * command plus its first positional (the branch-leaf token). */
+function gateLeafName(parsed: ParsedArgs): string {
+  const branch =
+    parsed.command === 'session' ||
+    parsed.command === 'page' ||
+    parsed.command === 'tab' ||
+    parsed.command === 'measure' ||
+    parsed.command === 'motion' ||
+    parsed.command === 'lib';
+  const leaf = parsed.positional[0];
+  return branch && leaf ? `${parsed.command} ${leaf}` : parsed.command;
+}
+
+/**
+ * Registers a session-bound operation (`page`/`measure`/`motion`) with the
+ * lifecycle coordinator BEFORE its first side effect and releases in `finally`,
+ * so a concurrent `session stop` (via `beginSessionStop`) waits for in-flight
+ * artifact writers to drain and excludes any operation that starts after stop
+ * marking (admission throws `session_stopping`). When there is no active
+ * session the operation is a one-shot with nothing to coordinate against, so it
+ * runs unwrapped. The active-session read here is never the first for these
+ * leaves — `resolveCliContext` already hydrated the same session — so it adds
+ * no new active-index side effect on the validation-rejected path.
+ */
+async function withActiveSessionAdmission(parsed: ParsedArgs, run: () => Promise<void>): Promise<void> {
+  const active = getActiveSession();
+  if (!active) return run();
+  const operation = await admitSessionOperation(active.dir);
+  try {
+    return await run();
+  } finally {
+    await operation.release();
+  }
+}
 
 export async function cdpMain(): Promise<void> {
   const args = process.argv.slice(2);
-  const parsed = parseCliArgs(args);
+  const parsed = parseCliSyntax(args);
+
+  if (parsed.gate && !isGateLeaf(parsed)) {
+    rejectUnsupportedGate(parsed, gateLeafName(parsed));
+    return;
+  }
+
+  validateCliInvocation(parsed);
+  const resolved = resolveCliContext(parsed);
 
-  switch (parsed.command) {
-    case 'detect': return cmdDetect(parsed, args);
-    case 'list': return cmdList(parsed, args);
-    case 'open': return cmdOpen(parsed, args);
-    case 'reset-tab': return cmdResetTab(parsed, args);
-    case 'exec': return cmdExec(parsed, args);
-    case 'screenshot': return cmdScreenshot(parsed, args);
-    case 'click': return cmdClick(parsed, args);
-    case 'type': return cmdType(parsed, args);
-    case 'a11y': return cmdA11y(parsed, args);
-    case 'record': return cmdRecord(parsed, args);
-    case 'navigate': return cmdNavigate(parsed, args);
-    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 '__bridge-serve': return cmdBridgeServe(parsed, args);
+  switch (resolved.command) {
+    case 'session': return sessionMain(resolved, args);
+    case 'page': return withActiveSessionAdmission(resolved, () => pageMain(resolved, args));
+    case 'tab': return tabMain(resolved, args);
+    case 'lib': return cmdLib(resolved, args);
+    case 'cdp': return cmdCdp(resolved, args);
+    case 'measure': return withActiveSessionAdmission(resolved, () => measureMain(resolved, args));
+    case 'motion': return withActiveSessionAdmission(resolved, () => motionMain(resolved, args));
+    case '__bridge-serve': return cmdBridgeServe(resolved, args);
     default:
-      console.log(CDP_USAGE);
+      // capture.ts routes only the known roots into cdpMain(); an unknown
+      // token gets its structured error there and never reaches this switch.
+      throw new Error(`dispatch: unroutable command ${JSON.stringify(resolved.command)}`);
   }
 }

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