@crouton-kit/capture 1.3.8 → 1.3.10

package/src/cdp/screenshot.ts

@@ -1,84 +1,215 @@
-import * as fs from 'fs';
+import { PNG } from 'pngjs';
 import { CDPClient } from './client.js';
 import { nextStepPath } from '../session-context.js';
+import { writeBinaryPrivate } from '../session/artifacts.js';
+import { withScopeSerialization } from './scope-lock.js';
 
+/**
+ * Downscales a PNG so its longest side fits within maxDim, using a box
+ * filter. Used when a clipped/scaled CDP capture is unavailable and the raw
+ * capture exceeds the dimension budget.
+ */
+function downscalePngToFit(png: Buffer, maxDim: number): Buffer {
+  const src = PNG.sync.read(png);
+  const maxSide = Math.max(src.width, src.height);
+  if (maxSide <= maxDim) return png;
+  const ratio = maxDim / maxSide;
+  const dstW = Math.max(1, Math.round(src.width * ratio));
+  const dstH = Math.max(1, Math.round(src.height * ratio));
+  const dst = new PNG({ width: dstW, height: dstH });
+  for (let y = 0; y < dstH; y++) {
+    const sy0 = Math.floor((y * src.height) / dstH);
+    const sy1 = Math.max(sy0 + 1, Math.floor(((y + 1) * src.height) / dstH));
+    for (let x = 0; x < dstW; x++) {
+      const sx0 = Math.floor((x * src.width) / dstW);
+      const sx1 = Math.max(sx0 + 1, Math.floor(((x + 1) * src.width) / dstW));
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let a = 0;
+      let n = 0;
+      for (let sy = sy0; sy < sy1 && sy < src.height; sy++) {
+        for (let sx = sx0; sx < sx1 && sx < src.width; sx++) {
+          const i = (sy * src.width + sx) * 4;
+          r += src.data[i];
+          g += src.data[i + 1];
+          b += src.data[i + 2];
+          a += src.data[i + 3];
+          n++;
+        }
+      }
+      const j = (y * dstW + x) * 4;
+      dst.data[j] = Math.round(r / n);
+      dst.data[j + 1] = Math.round(g / n);
+      dst.data[j + 2] = Math.round(b / n);
+      dst.data[j + 3] = Math.round(a / n);
+    }
+  }
+  return PNG.sync.write(dst);
+}
+
+/**
+ * Captures one screenshot, applying (and always clearing) a device-metrics
+ * override when a viewport or full-page capture is requested. The override
+ * is target-visible state driven over the connection: a direct connection's
+ * override dies with its own websocket session, but the recorder-held
+ * connection is shared across commands, so the entire
+ * setDeviceMetricsOverride→capture→clear scope serializes under the owning
+ * session's `.viewport-scope.lock` (`withScopeSerialization`) when the
+ * client is the recorder-held adapter — otherwise a concurrent routed
+ * caller could clear this capture's live override mid-scope (or capture
+ * inside someone else's).
+ */
 export async function captureScreenshot(
   client: CDPClient,
   viewport?: { width: number; height: number },
   options?: { fullPage?: boolean },
+): Promise<Buffer> {
+  return withScopeSerialization(client, 'viewport', 'screenshot capture', () =>
+    viewportScopedCapture(client, viewport, options),
+  );
+}
+
+/**
+ * The one viewport/capture state transaction: override (when requested) →
+ * capture → clear. Restoration ownership is claimed BEFORE the override is
+ * awaited (a lost response does not prove Chrome rejected it); a clear
+ * failure prevents success — alone it throws, paired with a primary failure
+ * it throws an `AggregateError` preserving both facts.
+ */
+async function viewportScopedCapture(
+  client: CDPClient,
+  viewport?: { width: number; height: number },
+  options?: { fullPage?: boolean },
 ): Promise<Buffer> {
   const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
+  let ownsDeviceMetricsOverride = false;
+  let primaryFailed = false;
+  let primaryError: unknown;
 
-  // Apply viewport emulation if requested
-  if (viewport) {
-    await client.send('Emulation.setDeviceMetricsOverride', {
-      width: viewport.width,
-      height: viewport.height,
-      deviceScaleFactor: 1,
-      mobile: false,
-    });
-    // Let the page re-layout at the new size
-    await new Promise((r) => setTimeout(r, 150));
-  }
+  try {
+    if (viewport) {
+      // A rejected response does not prove that Chrome rejected the request.
+      // Claim cleanup responsibility before awaiting every override request.
+      ownsDeviceMetricsOverride = true;
+      await client.send('Emulation.setDeviceMetricsOverride', {
+        width: viewport.width,
+        height: viewport.height,
+        deviceScaleFactor: 1,
+        mobile: false,
+      });
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
 
-  // For full-page capture, resize viewport to the full content height
-  if (options?.fullPage) {
-    const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
-      contentSize?: { width: number; height: number };
-      cssVisualViewport?: { clientWidth: number };
+    if (options?.fullPage) {
+      const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
+        contentSize?: { width: number; height: number };
+        cssVisualViewport?: { clientWidth: number };
+      };
+      const contentWidth = layoutMetrics.cssVisualViewport?.clientWidth ?? viewport?.width ?? 1280;
+      const contentHeight = layoutMetrics.contentSize?.height ?? viewport?.height ?? 800;
+      ownsDeviceMetricsOverride = true;
+      await client.send('Emulation.setDeviceMetricsOverride', {
+        width: contentWidth,
+        height: Math.ceil(contentHeight),
+        deviceScaleFactor: 1,
+        mobile: false,
+      });
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+
+    let screenshotOpts: Record<string, unknown> = {
+      format: 'png',
+      captureBeyondViewport: false,
     };
-    const contentWidth = layoutMetrics.cssVisualViewport?.clientWidth ?? viewport?.width ?? 1280;
-    const contentHeight = layoutMetrics.contentSize?.height ?? viewport?.height ?? 800;
-    await client.send('Emulation.setDeviceMetricsOverride', {
-      width: contentWidth,
-      height: Math.ceil(contentHeight),
-      deviceScaleFactor: 1,
-      mobile: false,
-    });
-    await new Promise((r) => setTimeout(r, 150));
-  }
 
-  let screenshotOpts: Record<string, unknown> = {
-    format: 'png',
-    captureBeyondViewport: false,
-  };
+    try {
+      const metrics = (await client.send('Page.getLayoutMetrics')) as {
+        cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
+      };
+      // Snap the clip to integer CSS pixels: browser zoom (e.g. 110%) makes the
+      // CSS viewport fractional, and some Chromium-based browsers (Arc, at
+      // least) answer a clipped Page.captureScreenshot whose output dimensions
+      // are fractional with a SUCCESSFUL response carrying empty `data`.
+      const vw = Math.round(metrics.cssVisualViewport?.clientWidth ?? 0);
+      const vh = Math.round(metrics.cssVisualViewport?.clientHeight ?? 0);
+      const sx = Math.floor(metrics.cssVisualViewport?.pageX ?? 0);
+      const sy = Math.floor(metrics.cssVisualViewport?.pageY ?? 0);
 
-  try {
-    const metrics = (await client.send('Page.getLayoutMetrics')) as {
-      cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
-    };
-    const vw = metrics.cssVisualViewport?.clientWidth ?? 0;
-    const vh = metrics.cssVisualViewport?.clientHeight ?? 0;
-    const sx = metrics.cssVisualViewport?.pageX ?? 0;
-    const sy = metrics.cssVisualViewport?.pageY ?? 0;
-
-    const dprResult = (await client.send('Runtime.evaluate', {
-      expression: 'window.devicePixelRatio',
-      returnByValue: true,
-    })) as { result: { value: number } };
-    const dpr = dprResult.result.value ?? 1;
-
-    const actualMaxSide = Math.max(vw, vh) * dpr;
-    const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
-    screenshotOpts = {
-      ...screenshotOpts,
-      clip: { x: sx, y: sy, width: vw, height: vh, scale },
-    };
-  } catch {
-    // Fallback: capture without downscaling
-  }
+      const dprResult = (await client.send('Runtime.evaluate', {
+        expression: 'window.devicePixelRatio',
+        returnByValue: true,
+      })) as { result: { value: number } };
+      const dpr = dprResult.result.value ?? 1;
 
-  const result = (await client.send(
-    'Page.captureScreenshot',
-    screenshotOpts,
-  )) as { data: string };
+      const actualMaxSide = Math.max(vw, vh) * dpr;
+      const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
+      screenshotOpts = {
+        ...screenshotOpts,
+        clip: { x: sx, y: sy, width: vw, height: vh, scale },
+      };
+    } catch {
+      // Capture without downscaling when the optional metrics probe is unavailable.
+    }
 
-  // Reset emulation so the browser window isn't stuck at the overridden size
-  if (viewport || options?.fullPage) {
-    await client.send('Emulation.clearDeviceMetricsOverride');
-  }
+    const result = (await client.send(
+      'Page.captureScreenshot',
+      screenshotOpts,
+    )) as { data?: string };
+    let png = Buffer.from(result.data ?? '', 'base64');
+
+    // A fractional scale (1/devicePixelRatio) can still produce fractional
+    // output dimensions, which the browsers above answer with empty data.
+    // Retry the same integer clip at scale 1, preserving full-page captures,
+    // then enforce the dimension budget locally.
+    if (png.length === 0 && screenshotOpts.clip) {
+      const clip = screenshotOpts.clip as Record<string, unknown>;
+      const retry = (await client.send('Page.captureScreenshot', {
+        ...screenshotOpts,
+        clip: { ...clip, scale: 1 },
+      })) as { data?: string };
+      png = Buffer.from(retry.data ?? '', 'base64');
+      if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
+    }
+
+    // If the browser rejects clipped capture entirely, an unclipped viewport
+    // capture is still better than a false successful 0-byte artifact.
+    if (png.length === 0 && screenshotOpts.clip && !options?.fullPage) {
+      const retry = (await client.send('Page.captureScreenshot', {
+        format: 'png',
+        captureBeyondViewport: false,
+      })) as { data?: string };
+      png = Buffer.from(retry.data ?? '', 'base64');
+      if (png.length > 0) png = downscalePngToFit(png, MAX_DIM);
+    }
 
-  return Buffer.from(result.data, 'base64');
+    if (png.length === 0) {
+      throw new Error(
+        'Page.captureScreenshot returned no image data (the tab may not be rendering); refusing to write a 0-byte PNG',
+      );
+    }
+
+    return png;
+  } catch (error) {
+    primaryFailed = true;
+    primaryError = error;
+    throw error;
+  } finally {
+    if (ownsDeviceMetricsOverride) {
+      try {
+        await client.send('Emulation.clearDeviceMetricsOverride');
+      } catch (cleanupError) {
+        if (primaryFailed) {
+          throw new AggregateError(
+            [primaryError, cleanupError],
+            'Screenshot capture failed and device-metrics cleanup also failed.',
+            { cause: primaryError },
+          );
+        }
+        throw cleanupError;
+      }
+    }
+  }
 }
 
 export async function autoScreenshot(
@@ -88,13 +219,15 @@ export async function autoScreenshot(
   noScreenshot?: boolean,
 ): Promise<string | null> {
   if (noScreenshot) return null;
-  const shotPath = nextStepPath(action, label);
+  const shotPath = await nextStepPath(action, label);
   if (!shotPath) return null;
 
   // Brief settle for UI to update
   await new Promise((r) => setTimeout(r, 300));
   const png = await captureScreenshot(client);
-  fs.writeFileSync(shotPath, png);
+  // Shot path always resolves under the session dir (CAPTURE_ROOT); the
+  // private writer creates the file 0600 and re-ensures shots/ is 0700.
+  writeBinaryPrivate(shotPath, png);
   console.error(`  [screenshot] ${shotPath}`);
   return shotPath;
 }

package/src/cdp/targets.ts

@@ -25,7 +25,7 @@ export async function getBrowserClient(
     throw new Error(
       `Port ${port} answers CDP's /json/version but has no browser-level WebSocket debugger URL — ` +
         `it's not a real browser (e.g. a Node/workerd inspector), so it can't host tabs. ` +
-        `Run "capture detect" to find a real browser endpoint, or pass --port explicitly.`,
+        `Run "capture tab list" to find a real browser endpoint, or pass --port explicitly.`,
     );
   }
   const client = new CDPClient(version.webSocketDebuggerUrl);
@@ -208,6 +208,26 @@ export function requireTargetId(
   return targetId;
 }
 
+/**
+ * Closes exactly one target through the browser-level connection, the mirror of
+ * `openTab`. Transactional owners (session-start rollback) call this to release
+ * ONLY the target this attempt opened; it never touches foreign/pre-existing
+ * tabs. Throws when `Target.closeTarget` reports the target was not closed.
+ */
+export async function closeTarget(port: number, targetId: string): Promise<void> {
+  const { client } = await getBrowserClient(port);
+  try {
+    const result = (await client.send('Target.closeTarget', { targetId })) as {
+      success?: boolean;
+    };
+    if (result?.success === false) {
+      throw new Error(`Target.closeTarget reported no close for target ${targetId} on port ${port}.`);
+    }
+  } finally {
+    client.close();
+  }
+}
+
 export async function openTab(port: number, url: string): Promise<CDPTarget> {
   const { client } = await getBrowserClient(port);
 

package/src/cdp/timing.ts

@@ -20,13 +20,15 @@ export interface BracketedTiming<T> {
 /**
  * Runs `fn`, bracketed by two `performance.now()` reads taken in the page's document execution
  * context. Used to attribute a discrete action (e.g. an `Input.dispatch*` call) to a window in
- * the recorder's authoritative `performance.now()` clock domain — this is the mechanism behind
- * the recorder-client adapter's internal `performance.mark(input_name)` bracketing (U14).
+ * the recorder's authoritative `performance.now()` clock domain. The action's landmark label
+ * (`mark`, when the caller supplied one) is recorded host-side only — appended straight to
+ * `events.jsonl` alongside these two bracket numbers (see `../recorder-bridge.ts`'s `handleCdp`)
+ * — never written into the page's own PerformanceTimeline via `performance.mark()`: that page-
+ * visible side channel was removed (a predictable, page-observable channel the injected
+ * PerformanceObserver would otherwise re-observe as its own event, in violation of the
+ * observational-collector invariant against page-side channels).
  */
-export async function withDocumentPerformanceNow<T>(
-  client: CDPClient,
-  fn: () => Promise<T>,
-): Promise<BracketedTiming<T>> {
+export async function withDocumentPerformanceNow<T>(client: CDPClient, fn: () => Promise<T>): Promise<BracketedTiming<T>> {
   const startPerformanceNow = await readPerformanceNow(client);
   const result = await fn();
   const endPerformanceNow = await readPerformanceNow(client);
@@ -57,10 +59,13 @@ export interface TraceClockBaseline {
 
 /**
  * Reads one synchronized (`performance.now()`, wall-clock) pair from the page in a single
- * round trip. The recorder bridge captures this once at `--start` as the `capture-rec-start`
- * baseline stored in `markers.json`; screencast-frame `metadata.timestamp` (wall-clock seconds)
- * and Tracing `ts` (wall-clock-anchored microseconds) are then converted into the
- * `performance.now()` domain by subtracting this baseline's wall-clock offset.
+ * round trip. The recorder bridge reads this once when it arms (`rec-start`) as the anchor half
+ * of the three-way `markers.json` baseline; the other two members — the first screencast frame's
+ * `metadata.timestamp` (wall-clock seconds) and the first Tracing batch's earliest event `ts`
+ * (trace-clock microseconds) — are captured separately by the recorder bridge itself as those
+ * events arrive (not by this function, since neither exists yet at arm time). Post-processing
+ * converts frame-time and trace-time into the `performance.now()` domain by subtracting this
+ * baseline's wall-clock offset.
  */
 export async function readTraceClockBaseline(client: CDPClient): Promise<TraceClockBaseline> {
   const evaluation = (await client.send('Runtime.evaluate', {

package/src/cdp/types.ts

@@ -12,24 +12,37 @@ export interface ParsedArgs {
   port?: number;
   out?: string;
   json?: boolean;
-  interactive?: boolean;
-  harOut?: string;
-  record?: boolean;
   duration?: number;
   settle?: number;
   file?: string;
-  nested?: boolean;
+  /** Session-filled internal slot: NOT CLI-settable (no --har flag, no env
+   * var). Auto-filled from the active session's harId so withConnection()
+   * can auto-append recorded traffic to the session HAR. */
   har?: string;
   new?: boolean;
   target?: string;
+  /** Where `target` was assigned from: an actual `--target` flag, active-session
+   * autofill, or the ambient `CDP_TARGET` env var. Recorded at the assignment
+   * point — browser-scope CDP (`cdp --browser`) attaches a flattened target
+   * session only when this is `'flag'`; provenance is never inferred later by
+   * comparing final strings. */
+  targetSource?: 'flag' | 'session' | 'env';
   url?: string;
-  role?: string;
   into?: string;
   noScreenshot?: boolean;
   viewport?: string;
   fullPage?: boolean;
-  height?: number;
   help?: boolean;
+  /** `--all` — boolean scope-widener (per-leaf semantics). */
+  all?: boolean;
+  /** `--session <id>` — explicit session id override (per-leaf semantics). */
+  session?: string;
+  /** `session start --hold` — hold one CDP browser connection open for the session's lifetime. */
+  hold?: boolean;
+  /** `session view --filter <section>` — show only one bundle-manifest section. */
+  filter?: string;
+  /** `session log --name <label>` */
+  name?: string;
   filterUrl?: string;
   filterStatus?: string;
   filterMethod?: string;
@@ -78,7 +91,7 @@ export interface ParsedArgs {
   from?: string;
   /** `sweep --to <val>` — raw string; axis units vary (px/dpr/zoom). */
   to?: string;
-  /** `sweep --viewport-height <val>` — raw string, distinct from `--height`. */
+  /** `sweep --viewport-height <val>` — raw string for the viewport-height sweep axis. */
   viewportHeight?: string;
   /** `motion rec --stop --rec-id <id>` — explicit recording id override. */
   recId?: string;
@@ -105,4 +118,6 @@ export interface ParsedArgs {
   prop?: string;
   /** `motion response --action <action>` */
   action?: string;
+  /** `motion response --occurrence <n>` — 1-based occurrence of a repeated action label. */
+  occurrence?: number;
 }

package/src/cdp/viewport.ts

@@ -0,0 +1,21 @@
+import { invalidInput } from '../errors.js';
+
+export interface Viewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+const VIEWPORT_PATTERN = /^([1-9]\d*)x([1-9]\d*)$/;
+
+/** Parses the one viewport grammar used by every live capture command. */
+export function parseViewport(value: string): Viewport {
+  const match = VIEWPORT_PATTERN.exec(value);
+  if (match) {
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (Number.isSafeInteger(width) && Number.isSafeInteger(height)) {
+      return { width, height };
+    }
+  }
+  throw invalidInput(`--viewport must match <positive-safe-int>x<positive-safe-int> using lowercase x with no whitespace; received "${value}"`, 'invalid_viewport');
+}

package/src/cdp.ts

@@ -1,38 +1,16 @@
-#!/usr/bin/env tsx
 /**
- * CDP (Chrome DevTools Protocol) — browser automation via exec-first design.
+ * CDP (Chrome DevTools Protocol) — the library barrel over the CDP substrate.
  *
- * The agent writes arbitrary JS and passes it to `exec`. No training-wheel
- * commands for click/type/wait — the agent composes whatever it needs.
- *
- * Commands:
- *   capture exec <code>         Execute JS in a tab (the primary interface)
- *   capture exec --file <path>  Execute JS from file
- *   capture detect              Detect CDP port
- *   capture list                List all browser tabs
- *   capture open <url>          Open URL in browser (returns tab ID)
- *   capture reset-tab <url>    Abandon stuck tab, open fresh one
- *   capture screenshot          Capture screenshot
- *   capture a11y                Get accessibility tree
- *   capture record              Passive HAR recording
- *   capture navigate <url>      Navigate + record HAR
- *   capture har create|read|delete  Manage HAR recordings
- *
- * Options:
- *   --port <port>       Override CDP port (auto-detects if not specified)
- *   --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
- *   --new               Force open a new tab (open command)
- *   --record            Enable HAR recording (exec)
- *   --har <id>          Append traffic to a HAR recording
- *   --har-out <path>    HAR output path
- *   --file <path>       Read JS from file (exec)
- *   --duration <secs>   Recording duration (record, default: 10)
- *   --settle <ms>       Settle time after navigation (navigate, default: 2000)
- *   --out <path>        Output path (screenshot)
- *   --height <px>       Override viewport height (screenshot)
- *   --full-page         Capture entire scrollable page (screenshot)
- *   --json              JSON output (a11y)
- *   --interactive       Interactive elements only (a11y)
+ * Re-exports the client, target discovery, screenshot, a11y, console-recording,
+ * and tab-lock building blocks, plus `cdpMain` (the routed command dispatch).
+ * HAR ownership is NOT exported here: the session HAR manager
+ * (`src/har-manager.ts`) fed by the internal streaming recorder
+ * (`src/cdp/har-recorder.ts`, a direct import of the recorder bridge) is the
+ * sole HAR lane.
+ * The command surface itself lives under `src/cdp/commands/` and is routed by
+ * `src/capture.ts` → `src/cdp/dispatch.ts`. This module is a pure barrel:
+ * `src/capture.ts` is the ONLY entrypoint and the ONLY error/termination
+ * boundary — nothing here executes, renders, or exits.
  */
 
 export { CDPClient } from './cdp/client.js';
@@ -42,32 +20,8 @@ export { listTargets, findTab, findTabById, openTab } from './cdp/targets.js';
 export { captureScreenshot } from './cdp/screenshot.js';
 export type { A11yNode } from './cdp/a11y.js';
 export { getAccessibilityTree } from './cdp/a11y.js';
-export { executeInBrowser } from './cdp/execute.js';
-export type { ExecuteOptions, ExecuteResult } from './cdp/execute.js';
-export { recordTraffic, navigateAndRecord, navigateAndWait } from './cdp/record.js';
-export type { RecordOptions, RecordResult, NavigateAndRecordOptions, NavigateAndRecordResult } from './cdp/record.js';
-export { HARRecorder } from './cdp/har-recorder.js';
+export { navigateAndWait } from './cdp/record.js';
 export { ConsoleRecorder } from './cdp/console-recorder.js';
 export type { ConsoleEntry } from './cdp/console-recorder.js';
 export { acquireTabLock, isTabLocked, releaseTabLock, withTabLock } from './cdp/tab-lock.js';
 export { cdpMain } from './cdp/dispatch.js';
-
-// Only run CLI when executed directly (not imported via capture.ts)
-const isMainModule =
-  process.argv[1]?.endsWith('cdp.ts') ||
-  process.argv[1]?.endsWith('cdp.mjs');
-if (isMainModule) {
-  cdpMain()
-    .then(() => {
-      // Flush stdout before exiting — process.exit() doesn't wait for stream drain
-      if (process.stdout.writableNeedDrain) {
-        process.stdout.once('drain', () => process.exit(0));
-      } else {
-        process.exit(0);
-      }
-    })
-    .catch((err) => {
-      console.error(err.message);
-      process.exit(1);
-    });
-}

package/src/command-help.ts

@@ -0,0 +1,29 @@
+/** Pure specification-help assembly from Capture's descriptor tree. */
+import { type RegistryNode } from './registry.js';
+
+const usage = (node: RegistryNode): string => `capture${node.path ? ` ${node.path}` : ''}`;
+const parameter = (name: string, grammar: string, required: boolean, variadic = false): string => `  ${required ? '<' : '['}${name}${required ? '>' : ']'}  ${grammar}${variadic ? ' (variadic)' : ''}`;
+
+/** Renders only descriptor-owned content; help never parses inputs or performs effects. */
+export function assembleHelp(node: RegistryNode): string {
+  const { help } = node;
+  const lines = [usage(node), '', help.description, '', `When to use: ${help.whenToUse}`, `Model: ${help.model ?? help.rubric}`];
+  if (help.globals) lines.push('', 'Globals:', help.globals);
+  if (help.ioContract) lines.push('', `I/O contract: ${help.ioContract}`);
+  if (node.kind === 'branch') {
+    const children = node.children.filter((child) => child.visibility === 'public');
+    if (children.length) {
+      lines.push('', 'Commands:');
+      for (const child of children) lines.push(`  ${child.path.split(' ').at(-1)}  ${child.help.description} When to use: ${child.help.whenToUse}`);
+    }
+  } else {
+    if (node.positionals.length || node.flags.length) {
+      lines.push('', 'Parameters:');
+      for (const positional of node.positionals) lines.push(parameter(positional.name, positional.grammar, positional.required, positional.variadic));
+      for (const flag of node.flags) lines.push(`  ${flag.name}${flag.grammar === 'boolean' ? '' : ` <${flag.grammar}>`}${flag.required ? ' required' : ''}${flag.repeatable ? ' repeatable' : ''}${flag.default === undefined ? '' : ` default=${flag.default}`}${flag.values ? ` values=${flag.values.join('|')}` : ''}${flag.units ? ` units=${flag.units}` : ''}`);
+    }
+    lines.push('', `Constraints: ${help.constraints}`, `Output: ${help.orderedOutput}`, `Artifact ownership: ${help.artifactOwnership}`, `Effects: browser=${node.effects.browser}, session=${node.effects.session}, artifact=${node.effects.artifact}, environment=${node.effects.environment}`, `Recovery: ${node.recovery}`);
+  }
+  lines.push('', `Next action: ${help.followUp}`);
+  return `${lines.join('\n')}\n`;
+}

package/src/command-resolution.ts

@@ -0,0 +1,22 @@
+/** Pure pre-dispatch control precedence for U15's future launcher wiring. */
+import { assembleHelp } from './command-help.js';
+import { hasHelpFlag, hasRootVersionFlag, walkCommand } from './command-walker.js';
+import { CAPTURE_REGISTRY, type RegistryBranch, type RegistryNode } from './registry.js';
+
+export type CommandResolution =
+  | { readonly kind: 'version' }
+  | { readonly kind: 'help'; readonly node: RegistryNode; readonly text: string }
+  | { readonly kind: 'dispatch'; readonly node: RegistryNode; readonly argv: readonly string[] }
+  | { readonly kind: 'unknown-path'; readonly received: string; readonly expected: readonly string[]; readonly path: string };
+
+/**
+ * Applies only control precedence. It deliberately does not parse leaf argv,
+ * validate `--json`, invoke a handler, or allocate any effectful dependency.
+ */
+export function resolveCommand(argv: readonly string[], root: RegistryBranch = CAPTURE_REGISTRY): CommandResolution {
+  if (hasRootVersionFlag(argv)) return { kind: 'version' };
+  const walked = walkCommand(argv, root);
+  if (walked.kind === 'unknown-path') return { kind: 'unknown-path', received: walked.received, expected: walked.expected, path: walked.resolved.path };
+  if (hasHelpFlag(walked.remaining)) return { kind: 'help', node: walked.node, text: assembleHelp(walked.node) };
+  return { kind: 'dispatch', node: walked.node, argv: walked.remaining };
+}

package/src/command-walker.ts

@@ -0,0 +1,35 @@
+/** Pure exact command-path resolution for the descriptor registry. */
+import { CAPTURE_REGISTRY, type RegistryBranch, type RegistryNode } from './registry.js';
+
+export type WalkResult =
+  | { readonly kind: 'resolved'; readonly node: RegistryNode; readonly remaining: readonly string[] }
+  | { readonly kind: 'unknown-path'; readonly received: string; readonly resolved: RegistryBranch; readonly expected: readonly string[]; readonly remaining: readonly string[] };
+
+/**
+ * Resolves only exact canonical path tokens. It stops before the first option,
+ * resolves the deepest known leaf/branch, and leaves all leaf argv untouched.
+ * Parsing, output compatibility, effects, and handler dispatch are intentionally
+ * outside this pure walker.
+ */
+export function walkCommand(argv: readonly string[], root: RegistryBranch = CAPTURE_REGISTRY): WalkResult {
+  let current: RegistryNode = root;
+  let index = 0;
+  while (current.kind === 'branch' && index < argv.length) {
+    const token = argv[index];
+    if (token.startsWith('-')) break;
+    const child: RegistryNode | undefined = current.children.find((candidate: RegistryNode) => candidate.path.split(' ').at(-1) === token);
+    if (!child) return { kind: 'unknown-path', received: token, resolved: current, expected: current.children.filter((candidate) => candidate.visibility === 'public').map((candidate) => candidate.path.split(' ').at(-1)!), remaining: argv.slice(index) };
+    current = child;
+    index += 1;
+  }
+  return { kind: 'resolved', node: current, remaining: argv.slice(index) };
+}
+
+export function hasHelpFlag(argv: readonly string[]): boolean {
+  return argv.includes('-h') || argv.includes('--help');
+}
+
+/** Root version is the sole accepted version spelling and wins before walking. */
+export function hasRootVersionFlag(argv: readonly string[]): boolean {
+  return argv[0] === '--version';
+}