@crouton-kit/capture 1.3.6 → 1.3.8

package/src/cdp/bridge/spawn.ts

@@ -0,0 +1,127 @@
+/**
+ * Spawns/stops the detached bridge process for a held session
+ * (`capture session start --hold`). Mirrors the existing detached-child +
+ * pid-tracking pattern used for session log tailers (`session/commands.ts`).
+ */
+
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function bridgeSocketPath(sessionDir: string): string {
+  return path.join(sessionDir, 'bridge.sock');
+}
+
+/** The recorder bridge's own socket, scoped to its recording dir so it can't collide with a session's plain `--hold` bridge. */
+export function recorderSocketPath(recDir: string): string {
+  return path.join(recDir, 'recorder.sock');
+}
+
+export async function startBridge(
+  sessionDir: string,
+  port: number,
+  timeoutMs = 5000,
+): Promise<{ socketPath: string; pid: number }> {
+  const socketPath = bridgeSocketPath(sessionDir);
+  // Re-invoke the currently-running capture entrypoint in a hidden mode.
+  // Only works against the built bin (a bundled, plain-node-runnable JS
+  // file) \u2014 running `npm run dev` (tsx) can't self-spawn this way.
+  const scriptPath = process.argv[1];
+  const child = spawn(
+    process.execPath,
+    [scriptPath, '__bridge-serve', '--socket', socketPath, '--port', String(port)],
+    { detached: true, stdio: 'ignore' },
+  );
+  child.unref();
+  const pid = child.pid;
+  if (!pid) {
+    throw new Error('Failed to spawn CDP bridge process.');
+  }
+
+  const start = Date.now();
+  while (!fs.existsSync(socketPath)) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(
+        `CDP bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
+          `Check that a browser is reachable on port ${port} (capture detect).`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  return { socketPath, pid };
+}
+
+export function stopBridge(pid: number | null | undefined, socketPath: string | null | undefined): void {
+  if (pid) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // Already dead.
+    }
+  }
+  if (socketPath) {
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      // Already gone.
+    }
+  }
+}
+
+/**
+ * Spawns the same detached `__bridge-serve` entrypoint in recorder mode:
+ * it connects to one tab (`targetId`) instead of the browser level, and
+ * drives `capture motion rec`'s screencast/tracing/observers instead of
+ * proxying arbitrary `--browser` CDP calls. Mirrors `startBridge()`'s
+ * spawn + "wait for the socket file to appear" pattern; the caller
+ * (U14's lifecycle routing) tears it down with the same `stopBridge()`
+ * used for the plain held bridge.
+ *
+ * Recorder mode is selected via a positional (`recorder <recDir>`) rather
+ * than a new flag — `capture`'s CLI arg parser (`src/cdp/args.ts`) is not
+ * owned by this unit, but `positional` is already generic passthrough.
+ */
+export async function startRecorderBridge(
+  socketPath: string,
+  port: number,
+  targetId: string,
+  recDir: string,
+  timeoutMs = 5000,
+): Promise<{ socketPath: string; pid: number }> {
+  const scriptPath = process.argv[1];
+  const child = spawn(
+    process.execPath,
+    [
+      scriptPath,
+      '__bridge-serve',
+      '--socket',
+      socketPath,
+      '--port',
+      String(port),
+      '--target',
+      targetId,
+      'recorder',
+      recDir,
+    ],
+    { detached: true, stdio: 'ignore' },
+  );
+  child.unref();
+  const pid = child.pid;
+  if (!pid) {
+    throw new Error('Failed to spawn recorder bridge process.');
+  }
+
+  const start = Date.now();
+  while (!fs.existsSync(socketPath)) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(
+        `Recorder bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
+          `Check that target "${targetId}" is reachable on port ${port}.`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  return { socketPath, pid };
+}

package/src/cdp/client.ts

@@ -60,13 +60,14 @@ export class CDPClient {
     method: string,
     params: Record<string, unknown> = {},
     timeout = 60000,
+    sessionId?: string,
   ): Promise<unknown> {
     await this.ready;
     const id = ++this.messageId;
 
     return new Promise((resolve, reject) => {
       this.pendingRequests.set(id, { resolve, reject });
-      this.ws.send(JSON.stringify({ id, method, params }));
+      this.ws.send(JSON.stringify(sessionId ? { id, method, params, sessionId } : { id, method, params }));
 
       const timer = setTimeout(() => {
         if (this.pendingRequests.has(id)) {
@@ -86,6 +87,11 @@ export class CDPClient {
     this.eventHandlers.get(event)!.push(handler);
   }
 
+  /** Fires when the underlying websocket goes away (browser closed, crashed, CDP endpoint dropped). */
+  onDisconnect(handler: () => void): void {
+    this.ws.on('close', handler);
+  }
+
   close(): void {
     // Clear all pending timeouts to allow process to exit
     for (const timer of this.pendingTimeouts.values()) {

package/src/cdp/commands/bridge-serve.ts

@@ -0,0 +1,43 @@
+import { runBridgeServer } from '../bridge/server.js';
+import { runRecorderBridge } from '../recorder-bridge.js';
+import { type ParsedArgs } from '../types.js';
+
+/**
+ * Hidden entrypoint spawned detached by `capture session start --hold`
+ * (see `bridge/spawn.ts`'s `startBridge()`) or by `capture motion rec
+ * --start` in recorder mode (`startRecorderBridge()`). Not documented in
+ * `capture --help` — nothing calls this directly.
+ *
+ * Recorder mode is selected by a `recorder <recDir>` positional rather
+ * than a new flag, since `src/cdp/args.ts`'s fixed flag set isn't owned by
+ * this unit but `parsed.positional` is already generic passthrough:
+ *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir>
+ */
+export async function cmdBridgeServe(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (!parsed.socket) {
+    console.error(
+      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId> recorder <recDir>]',
+    );
+    process.exit(1);
+  }
+
+  if (parsed.positional[0] === 'recorder') {
+    const recDir = parsed.positional[1];
+    if (!parsed.target || !recDir) {
+      console.error(
+        'Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir>',
+      );
+      process.exit(1);
+    }
+    await runRecorderBridge({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, recDir });
+    // Deliberately does not exit: the open Unix socket server and the live
+    // tab websocket keep this detached process alive until the caller sends
+    // it SIGTERM (same teardown as the plain held bridge).
+    return;
+  }
+
+  await runBridgeServer(parsed.socket, parsed.port);
+  // Deliberately does not exit: the open Unix socket server and the live
+  // browser websocket keep this detached process alive until `session stop`
+  // sends it SIGTERM.
+}

package/src/cdp/commands/cdp.ts

@@ -0,0 +1,203 @@
+/**
+ * Raw CDP passthrough \u2014 the escape hatch for domains no other capture
+ * command wraps (`Browser.grantPermissions`, `ServiceWorker.*`, etc.).
+ *
+ * `--browser` routes through the HELD connection (see `session start
+ * --hold` / `src/cdp/bridge/`) instead of a fresh page/tab websocket.
+ * Browser-scoped state (permission grants) and target-scoped state that was
+ * enabled on that same connection (`ServiceWorker.enable`, ...) is
+ * per-CLIENT and reverts the instant its websocket disconnects, so a plain
+ * one-shot call here only lasts for that single command \u2014 running inside a
+ * held session is what keeps it alive across commands.
+ */
+
+import * as fs from 'fs';
+import { getActiveSession } from '../../session-context.js';
+import { connectForCommand } from '../connection.js';
+import { getBrowserClient, findTabById } from '../targets.js';
+import { detectCdpPort } from '../detect.js';
+import { sendBridgeRequest } from '../bridge/client.js';
+import { type CDPClient } from '../client.js';
+import { type ParsedArgs } from '../types.js';
+
+const DEFAULT_TIMEOUT_MS = 10000;
+
+function printHelp(): void {
+  console.log(
+    `Usage: capture cdp <Domain.method> [--params '<json>'] [--browser] [--target <id>] [--wait-event <Domain.event>] [--timeout <ms>]
+
+Send a raw CDP command \u2014 the escape hatch for domains no other capture
+command wraps (Browser.grantPermissions, ServiceWorker.*, Target.*, ...).
+
+  --browser           Route through the held connection (session --hold)
+                       instead of a fresh page/tab websocket. Required for
+                       state that must survive across separate commands.
+  --target <id>       With --browser: attach to this target (a flattened CDP
+                       session on the SAME held connection) for target-scoped
+                       domains, e.g. ServiceWorker.enable / .deliverPushMessage.
+                       Without --browser: the page target to run against, as
+                       with every other capture command.
+  --params '<json>'   JSON-encoded params object for the method.
+  --wait-event <name> Wait for (and return) the next occurrence of a CDP
+                       event, e.g. ServiceWorker.workerRegistrationUpdated.
+                       Can be combined with a method (sent first) or alone.
+  --timeout <ms>      Wait timeout (default: ${DEFAULT_TIMEOUT_MS}ms).
+
+Browser-level and target-enablement state reverts the instant its connection
+disconnects \u2014 a one-shot call here only lasts for that single command. Run
+inside a held session to keep it alive across commands:
+
+  capture session start --url http://localhost:3000 --hold
+  capture cdp Browser.grantPermissions --browser \\
+    --params '{"origin":"http://localhost:3000","permissions":["notifications"]}'
+  capture cdp ServiceWorker.enable --browser --target <pageTabId>
+  capture cdp --browser --target <pageTabId> --wait-event ServiceWorker.workerRegistrationUpdated
+  capture cdp ServiceWorker.deliverPushMessage --browser --target <pageTabId> \\
+    --params '{"origin":"...","registrationId":"...","data":"..."}'
+  capture session stop <session-id>
+
+Without --browser, the method runs against the current page target (session
+context or --target), like any other capture command \u2014 e.g. DOM.* or
+Accessibility.* calls beyond what \`capture a11y\` exposes.`,
+  );
+}
+
+export async function cmdCdp(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const method = parsed.positional[0];
+  if (!method && !parsed.waitEvent) {
+    console.error('ERROR: Provide a CDP method (e.g. Browser.grantPermissions) or --wait-event.\n');
+    printHelp();
+    process.exit(1);
+  }
+
+  let params: Record<string, unknown> | undefined;
+  if (parsed.params) {
+    try {
+      params = JSON.parse(parsed.params);
+    } catch (err) {
+      console.error(`ERROR: --params is not valid JSON: ${err instanceof Error ? err.message : err}`);
+      process.exit(1);
+    }
+  }
+
+  const timeoutMs = parsed.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  if (parsed.browser) {
+    await runBrowserScope(method, params, parsed, timeoutMs);
+    return;
+  }
+
+  await runPageScope(method, params, parsed, timeoutMs);
+}
+
+async function runBrowserScope(
+  method: string | undefined,
+  params: Record<string, unknown> | undefined,
+  parsed: ParsedArgs,
+  timeoutMs: number,
+): Promise<void> {
+  const session = getActiveSession();
+  if (session?.bridgeSocket && fs.existsSync(session.bridgeSocket)) {
+    const resp = await sendBridgeRequest(session.bridgeSocket, {
+      method,
+      params,
+      targetId: parsed.target,
+      waitEvent: parsed.waitEvent,
+      timeoutMs,
+    });
+    if (!resp.ok) {
+      console.error(`ERROR: ${resp.error}`);
+      if (!parsed.target) {
+        console.error(
+          '\nMany CDP domains (Storage.*, Page.*, DOM.*, Emulation.*, ...) are scoped to a specific ' +
+            'tab, not the browser connection as a whole \u2014 sent bare like this, Chrome often rejects them ' +
+            'with just "Internal error" and no further detail. Pass --target <tabId> to attach to the tab ' +
+            'the call should apply to (run "capture list" to find one).',
+        );
+      }
+      process.exit(1);
+    }
+    console.log(JSON.stringify({ result: resp.result, event: resp.event }, null, 2));
+    return;
+  }
+
+  console.error(
+    'No held session bridge active \u2014 this connection closes when the command exits, ' +
+      'so any browser-level grant or target enablement made here reverts immediately after.\n' +
+      'For state that must survive multiple commands: capture session start --hold\n',
+  );
+
+  const port = parsed.port ?? (await detectCdpPort());
+  const { client } = await getBrowserClient(port);
+  try {
+    let sessionId: string | undefined;
+    if (parsed.target) {
+      // Accept the same 8-char-prefix targeting every other capture command
+      // promises (see the top-level --help TARGETING section) instead of
+      // requiring the full 32-char target id here.
+      const tab = await findTabById(port, parsed.target);
+      if (!tab) {
+        console.error(`ERROR: No target found for "${parsed.target}" on port ${port}. Run "capture list" to see available tabs.`);
+        process.exit(1);
+      }
+      const attached = (await client.send('Target.attachToTarget', {
+        targetId: tab.id,
+        flatten: true,
+      })) as { sessionId: string };
+      sessionId = attached.sessionId;
+    }
+    const eventPromise = parsed.waitEvent ? waitForEventOnce(client, parsed.waitEvent, timeoutMs) : undefined;
+    const result = method ? await client.send(method, params ?? {}, 60000, sessionId) : undefined;
+    const event = eventPromise ? await eventPromise : undefined;
+    console.log(JSON.stringify({ result, event }, null, 2));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`ERROR: ${message}`);
+    if (!parsed.target) {
+      console.error(
+        '\nMany CDP domains (Storage.*, Page.*, DOM.*, Emulation.*, ...) are scoped to a specific ' +
+          'tab, not the browser connection as a whole \u2014 sent bare like this, Chrome often rejects them ' +
+          'with just "Internal error" and no further detail. Pass --target <tabId> to attach to the tab ' +
+          `the call should apply to (run "capture list" to find one${method ? `, e.g. capture cdp ${method} --browser --target <tabId> ...` : ''}).`,
+      );
+    }
+    process.exit(1);
+  } finally {
+    client.close();
+  }
+}
+
+async function runPageScope(
+  method: string | undefined,
+  params: Record<string, unknown> | undefined,
+  parsed: ParsedArgs,
+  timeoutMs: number,
+): Promise<void> {
+  const { client } = await connectForCommand(parsed);
+  try {
+    const eventPromise = parsed.waitEvent ? waitForEventOnce(client, parsed.waitEvent, timeoutMs) : undefined;
+    const result = method ? await client.send(method, params ?? {}) : undefined;
+    const event = eventPromise ? await eventPromise : undefined;
+    console.log(JSON.stringify({ result, event }, null, 2));
+  } finally {
+    client.close();
+  }
+}
+
+function waitForEventOnce(client: CDPClient, eventName: string, timeoutMs: number): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Timed out after ${timeoutMs}ms waiting for event "${eventName}"`)),
+      timeoutMs,
+    );
+    client.on(eventName, (params) => {
+      clearTimeout(timer);
+      resolve(params);
+    });
+  });
+}

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