@crouton-kit/capture 1.3.8 → 1.3.9

package/src/cdp/commands/page/navigate.ts

@@ -0,0 +1,330 @@
+/**
+ * `capture page navigate <url>` — navigate the SOURCE tab to a destination
+ * URL, then report the load outcome as a fact separate from the settle.
+ *
+ * Source targeting is ordinary page targeting: `--target <id>` / `--url
+ * <pattern>` (or, in a session, the session's own tab) selects which tab
+ * navigates; the single positional is the destination only. Navigate never
+ * creates a tab — `tab open` is the sole tab-creating verb — so an
+ * unresolvable source is `connectForCommand`'s structured targeting error,
+ * not a silently-opened tab.
+ *
+ * Dispatch is single-shot: exactly one `Page.navigate` for the destination
+ * (plus a `dest → about:blank → dest` bounce only when the target is a
+ * same-document/fragment change that returns no loaderId). The load wait
+ * (`Page.loadEventFired`) is armed BEFORE the destination send and reported
+ * as its own factual outcome — `observed` (the event fired inside the
+ * load-wait window) or `bounded-timeout` (it did not; the navigation still
+ * dispatched). A load-wait timeout NEVER discards the navigation's own
+ * result (its loaderId), and the navigation is never redispatched to chase a
+ * missing event.
+ */
+import { connectForCommand, withPageAction, type SettleFacts } from '../../connection.js';
+import { EventBroker } from '../../bridge/server.js';
+import { isRecorderHeldClient, type RecorderHeldClient } from '../../recorder-client.js';
+import { type CDPClient } from '../../client.js';
+import { type ParsedArgs } from '../../types.js';
+import { CaptureError, captureError, invalidInput } from '../../../errors.js';
+import { isParseableUrl } from '../../leaf-grammar.js';
+import { emitResult, fact, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+
+const LOAD_EVENT_NAME = 'Page.loadEventFired';
+const DEFAULT_SETTLE_MS = 2000;
+
+/** Load-wait window (inner) and total nav-phase deadline (outer) in ms.
+ * Injectable so tests drive the timing with tiny timers instead of the real
+ * multi-second waits — mirrors `connection.ts`'s `__setConnectionSeamsForTest`
+ * seam pattern. */
+interface NavigateTiming {
+  innerTimeoutMs: number;
+  outerDeadlineMs: number;
+}
+let timing: NavigateTiming = { innerTimeoutMs: 10_000, outerDeadlineMs: 60_000 };
+export function __setNavigateTimingForTest(overrides: Partial<NavigateTiming>): () => void {
+  const previous = timing;
+  timing = { ...timing, ...overrides };
+  return () => { timing = previous; };
+}
+
+const USAGE = `capture page navigate <url> [--settle <ms>] — navigate the source tab to a URL and report the load outcome.
+
+Input:
+  <url>          Destination URL (absolute, WHATWG-parseable). This is the
+                 destination only — it never selects or creates a tab.
+  --settle <ms>  Post-load settle wait; default ${DEFAULT_SETTLE_MS}ms. 0 disables.
+  --target <id>  Select the SOURCE tab to navigate (ordinary page targeting).
+  --url <pat>    Select the SOURCE tab by URL pattern (ordinary page targeting).
+
+Source resolution: --target / --url (or, in a session, the session's own tab)
+picks which tab navigates. Navigate never creates a tab — use "tab open" for
+that; an unresolvable source is a targeting error, not a new tab.
+
+Output:
+  One <navigated url=… settle=… load-outcome=… deadline-exceeded=…> block:
+  the tab URL after navigation, the measured settle, and — reported
+  separately — the load outcome (observed | bounded-timeout), whether the
+  nav phase exceeded its deadline, the dispatched navigation's loaderId (and
+  any about:blank bounce for a same-document target), and whether the CDP
+  routed through an active recording. --json mirrors the same fields.
+
+Effects:
+  Navigates the source tab (exactly one Page.navigate for the destination;
+  one dest→about:blank→dest bounce only for a same-document/fragment target).
+  During a live composed recording the CDP routes through the recorder socket
+  and Page.navigate carries a labeled performance.mark landmark; local
+  console/HAR collectors are skipped while routed — traffic streams into the
+  session HAR via the recording's held connection.`;
+
+/** Load outcome plus the dispatched navigation's own facts, produced by one
+ * navigation core (recorder-routed or direct). Distinct fields so the render
+ * layer can report the load result separately from the method result. */
+interface NavCore {
+  loadOutcome: 'observed' | 'bounded-timeout';
+  /** The dispatched navigation's loaderId (present on a real cross-document
+   * navigation; absent for a same-document target before the bounce). */
+  loaderId?: string;
+  /** True when a same-document (fragment-only) target forced the
+   * dest→about:blank→dest bounce so a freshly-mounted document sees it. */
+  bounced: boolean;
+}
+
+/**
+ * Recorder-routed navigation. The load wait is bundled atomically onto the
+ * destination `Page.navigate` via `dispatch()` (the bridge arms the wait
+ * before sending), so a fast load cannot race a separate subscription and a
+ * wait timeout no longer discards the navigation's loaderId. A same-document
+ * target returns no loaderId — recover with exactly one dest→about:blank→dest
+ * bounce, bundling the wait only on the final re-navigate.
+ */
+async function navigateViaRecorder(client: RecorderHeldClient, url: string): Promise<NavCore> {
+  const first = await client.dispatch('Page.navigate', { url }, LOAD_EVENT_NAME, timing.innerTimeoutMs);
+  const loaderId = (first.result as { loaderId?: string } | undefined)?.loaderId;
+  if (loaderId) {
+    return { loadOutcome: first.waitOutcome ?? 'bounded-timeout', loaderId, bounced: false };
+  }
+  // Same-document target: the destination is already committed (no loaderId);
+  // bounce through about:blank and re-navigate so a fresh document mounts.
+  await client.dispatch('Page.navigate', { url: 'about:blank' });
+  const final = await client.dispatch('Page.navigate', { url }, LOAD_EVENT_NAME, timing.innerTimeoutMs);
+  const finalLoaderId = (final.result as { loaderId?: string } | undefined)?.loaderId;
+  return { loadOutcome: final.waitOutcome ?? 'bounded-timeout', loaderId: finalLoaderId, bounced: true };
+}
+
+/** Arms a bounded `Page.loadEventFired` wait on a direct client's broker and
+ * returns the wait handle plus a never-rejecting outcome promise
+ * (`observed` | `bounded-timeout`). Arm this BEFORE the paired
+ * `Page.navigate` send so a synchronous load event cannot be missed. */
+function armLoadWait(broker: EventBroker): {
+  wait: ReturnType<EventBroker['wait']>;
+  outcome: Promise<'observed' | 'bounded-timeout'>;
+} {
+  const wait = broker.wait(LOAD_EVENT_NAME, undefined, timing.innerTimeoutMs);
+  const outcome = wait.result().then(
+    () => 'observed' as const,
+    () => 'bounded-timeout' as const,
+  );
+  return { wait, outcome };
+}
+
+/**
+ * Direct (non-recorder) navigation over a real CDP client. The load wait is
+ * armed before the destination send (via the shared `EventBroker`), so a
+ * synchronous `Page.loadEventFired` is still observed. A method throw
+ * propagates (no retry). A same-document target (no loaderId) recovers with
+ * exactly one dest→about:blank→dest bounce, re-arming the wait before the
+ * final send.
+ */
+async function navigateDirect(
+  client: CDPClient,
+  url: string,
+  armed?: { cancel: () => void },
+): Promise<NavCore> {
+  await client.send('Page.enable');
+  const broker = new EventBroker(client);
+
+  const first = armLoadWait(broker);
+  // Publish the currently-armed wait's canceller so an outer-deadline
+  // abandonment can clear its inner timer instead of letting it fire on its own.
+  if (armed) armed.cancel = () => first.wait.cancel();
+  let nav: { loaderId?: string } | undefined;
+  try {
+    nav = (await client.send('Page.navigate', { url })) as { loaderId?: string };
+  } catch (err) {
+    first.wait.cancel();
+    throw err;
+  }
+  if (nav?.loaderId) {
+    return { loadOutcome: await first.outcome, loaderId: nav.loaderId, bounced: false };
+  }
+
+  // Same-document target: discard the first wait, bounce through about:blank,
+  // re-arm the wait, then re-navigate to the destination.
+  first.wait.cancel();
+  await client.send('Page.navigate', { url: 'about:blank' });
+  const second = armLoadWait(broker);
+  if (armed) armed.cancel = () => second.wait.cancel();
+  let navFinal: { loaderId?: string } | undefined;
+  try {
+    navFinal = (await client.send('Page.navigate', { url })) as { loaderId?: string };
+  } catch (err) {
+    second.wait.cancel();
+    throw err;
+  }
+  return { loadOutcome: await second.outcome, loaderId: navFinal?.loaderId, bounced: true };
+}
+
+/** Races the nav+load phase against the outer deadline. The deadline never
+ * throws — on elapse it returns `{ completed: false }` and the caller reports
+ * `deadline-exceeded` as a fact alongside whatever partial outcome it holds.
+ * A method rejection from `work` propagates (no retry). */
+async function raceNavDeadline(work: Promise<NavCore>): Promise<{ completed: true; core: NavCore } | { completed: false }> {
+  let timer: ReturnType<typeof setTimeout>;
+  const deadline = new Promise<{ completed: false }>((resolve) => {
+    timer = setTimeout(() => resolve({ completed: false }), timing.outerDeadlineMs);
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref();
+  });
+  const workOutcome = work.then((core) => ({ completed: true as const, core }));
+  // If the deadline wins the race, `work` is still pending and may later
+  // reject (e.g. a hung dispatch that eventually errors) — mark it handled so
+  // that late rejection is not an unhandled promise. This does not suppress a
+  // rejection that arrives BEFORE the deadline: Promise.race still observes it.
+  workOutcome.catch(() => {});
+  try {
+    return await Promise.race([workOutcome, deadline]);
+  } finally {
+    clearTimeout(timer!);
+  }
+}
+
+interface NavigatedFacts {
+  tabUrl: string;
+  requestedUrl: string;
+  loadOutcome: 'observed' | 'bounded-timeout';
+  deadlineExceeded: boolean;
+  loaderId?: string;
+  bounced: boolean;
+  routed: boolean;
+  settle: SettleFacts;
+}
+
+function buildNavigatedResult(f: NavigatedFacts): RenderableResult {
+  const sections: FactLine[] = [
+    f.loadOutcome === 'observed'
+      ? fact`load: ${LOAD_EVENT_NAME} observed within the ${timing.innerTimeoutMs}ms load-wait window.`
+      : fact`load: ${LOAD_EVENT_NAME} not observed within the ${timing.innerTimeoutMs}ms load-wait window (bounded-timeout); the navigation still dispatched.`,
+    fact`navigation dispatched: loaderId ${f.loaderId ?? '(none)'}${f.bounced ? '; delivered via dest→about:blank→dest bounce (same-document target)' : ''}.`,
+    fact`settle: requested ${f.settle.requestedMs}ms, waited ${f.settle.waitedMs}ms.`,
+  ];
+  if (f.deadlineExceeded) {
+    sections.push(fact`navigation phase exceeded its ${timing.outerDeadlineMs / 1000}s deadline before completing.`);
+  }
+  if (f.routed) {
+    sections.push(
+      text`Page.navigate routed through the active recording with a labeled performance.mark; local console/HAR collectors skipped while routed — traffic streams into the session HAR via the recording's held connection.`,
+    );
+  }
+  return {
+    tag: 'navigated',
+    attrs: {
+      url: f.tabUrl,
+      settle: f.settle.requestedMs,
+      'load-outcome': f.loadOutcome,
+      'deadline-exceeded': f.deadlineExceeded || undefined,
+      routed: f.routed || undefined,
+    },
+    summary: fact`tab at ${f.tabUrl} after Page.navigate to ${f.requestedUrl}.`,
+    sections,
+  };
+}
+
+export async function cmdPageNavigate(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  // Positional cardinality (exactly 1) is enforced by `validateCliInvocation`
+  // before dispatch reaches this leaf; this guard covers direct programmatic
+  // callers only. Failures cross the boundary as typed CaptureErrors —
+  // capture.ts is the sole renderer/exit-status owner.
+  const url = parsed.positional[0];
+  if (!url) {
+    throw invalidInput('received: no URL; expected: `capture page navigate <url> [--settle <ms>]`.', 'missing_url');
+  }
+  // Validate the destination BEFORE any effect (connect/send). connectForCommand
+  // never runs for an unparseable URL, so no tab is touched.
+  if (!isParseableUrl(url)) {
+    throw invalidInput(`received: \`${url}\`; expected: an absolute, WHATWG-parseable URL.`, 'invalid_url');
+  }
+
+  const settle = parsed.settle ?? DEFAULT_SETTLE_MS;
+
+  // Session admission is owned by dispatch.ts's `withActiveSessionAdmission`,
+  // which wraps every `page` command already — this leaf mirrors its
+  // siblings (click/type/scroll) and does NOT re-admit here.
+  //
+  // connection.ts derives the recorder landmark label from parsed.command,
+  // which the router leaves as the branch token 'page' — restore the verb
+  // so a routed navigate's landmark stays `navigate:<url>`.
+  //
+  // Connection/targeting failures from `connectForCommand` (e.g. its
+  // "Use --target/--url" or "No tab found" errors) surface with their own
+  // message; only a genuinely raw navigation dispatch failure is re-tagged as
+  // `navigate_failed` (scoped to the nav core below), so a valid-URL targeting
+  // miss is never mislabeled with a URL/browser hint that doesn't apply.
+  const { result: core, settle: settleFacts } = await withPageAction(
+    { ...parsed, command: 'navigate' },
+    { settleMs: settle },
+    async (client, _tab) => {
+      const routed = isRecorderHeldClient(client);
+      // Holder for the direct path's currently-armed load wait, so an
+      // outer-deadline abandonment can cancel it (clearing its inner timer).
+      const armed = { cancel: () => {} };
+      const work = routed
+        ? navigateViaRecorder(client as unknown as RecorderHeldClient, url)
+        : navigateDirect(client, url, armed);
+      let raced: Awaited<ReturnType<typeof raceNavDeadline>>;
+      try {
+        raced = await raceNavDeadline(work);
+      } catch (err) {
+        // A raw navigation dispatch failure — tag it. Typed capture errors
+        // (recorder/targeting) pass through unmodified.
+        if (err instanceof CaptureError) throw err;
+        throw captureError(
+          'world',
+          'navigate_failed',
+          `${err instanceof Error ? err.message : String(err)} — check the URL is absolute and a CDP-enabled browser is running (probe: capture tab list).`,
+          err,
+        );
+      }
+      if (raced.completed) {
+        return { ...raced.core, deadlineExceeded: false, routed, tabUrl: url };
+      }
+      // Deadline elapsed before the nav phase completed — cancel the armed
+      // load wait and report partial facts (load unconfirmed) rather than throwing.
+      armed.cancel();
+      return {
+        loadOutcome: 'bounded-timeout' as const,
+        loaderId: undefined,
+        bounced: false,
+        deadlineExceeded: true,
+        routed,
+        tabUrl: url,
+      };
+    },
+  );
+
+  emitResult(
+    buildNavigatedResult({
+      tabUrl: core.tabUrl,
+      requestedUrl: url,
+      loadOutcome: core.loadOutcome,
+      deadlineExceeded: core.deadlineExceeded,
+      loaderId: core.loaderId,
+      bounced: core.bounced,
+      routed: core.routed,
+      settle: settleFacts,
+    }),
+    { json: parsed.json },
+  );
+}

package/src/cdp/commands/page/scroll.ts

@@ -0,0 +1,107 @@
+/**
+ * `page scroll <target> --to <top|bottom|px>` — scroll exactly one
+ * live-resolved container to a destination (design D3).
+ *
+ * Drives through `interact.ts`'s shared `scrollResolved` helper, passing a
+ * landmark label so a recorder-routed scroll's one mutating call
+ * (`Runtime.callFunctionOn`) lands the same labeled input landmark
+ * `motion rec --do scroll:` records.
+ */
+import { type ParsedArgs } from '../../types.js';
+import { isScrollDestination } from '../../leaf-grammar.js';
+import { resolveLiveTarget, scrollResolved, type LiveClient } from '../../../interact.js';
+import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
+import {
+  pageInputDeps,
+  effectiveSettle,
+  emitInvalidInput,
+  emitResolutionError,
+} from './click.js';
+
+const USAGE = `capture page scroll <target> --to <top|bottom|px> — scroll one resolved container to a position
+
+input:
+  <target>          resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required — zero or many matches is a structured error listing candidates
+  --to <dest>       required destination: top, bottom, or a pixel offset (scrollTop value)
+  --settle <ms>     network-settle window applied after the scroll (default: 1000; 2500 with an active session; 0 disables)
+  --no-screenshot   skip the auto-screenshot
+output:
+  <scrolled backend-node-id=… role=… name=…> — resolved identity, destination, the container's resulting scrollTop, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+effects:
+  assigns the container's scrollTop in-page (may trigger lazy-load network); writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
+
+export async function cmdPageScroll(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  const target = parsed.positional[0];
+  if (!target || parsed.positional.length !== 1) {
+    return emitInvalidInput(
+      parsed,
+      'page scroll',
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one target (CSS selector, ax:<name>, axid:<id>, or backend:<id>) plus --to <top|bottom|px>.`,
+    );
+  }
+  if (parsed.to === undefined) {
+    return emitInvalidInput(
+      parsed,
+      'page scroll',
+      fact`received: no --to destination; expected --to <top|bottom|px>.`,
+    );
+  }
+  const to = parsed.to;
+  if (!isScrollDestination(to)) {
+    return emitInvalidInput(
+      parsed,
+      'page scroll',
+      fact`received: --to \`${to}\`; expected top, bottom, or a pixel offset.`,
+    );
+  }
+
+  const deps = pageInputDeps();
+  const settle = effectiveSettle(parsed, { standalone: 1000, session: 2500 });
+  // connection.ts derives the recorder landmark label from parsed.command,
+  // which the router leaves as the branch token 'page' — restore the verb so
+  // a routed scroll's connection-level label stays `scroll:<target>`.
+  const { result: outcome, settle: settleFacts } = await deps.withPageAction(
+    { ...parsed, command: 'scroll' },
+    { settleMs: settle },
+    async (client) => {
+      const live = client as unknown as LiveClient;
+      const resolved = await resolveLiveTarget(live, target);
+      if (!resolved.ok) return { failure: resolved } as const;
+      // Same landmark shape `motion rec --do scroll:` records; carried by
+      // the one mutating call when the transport records landmarks.
+      const dispatch = await scrollResolved(live, resolved, to, { mark: `scroll:${target},to=${to}` });
+      const screenshot = await deps.autoScreenshot(client, 'scroll', target, parsed.noScreenshot);
+      return { dispatch, screenshot } as const;
+    },
+  );
+
+  if ('failure' in outcome) {
+    return emitResolutionError(parsed, 'page scroll', outcome.failure);
+  }
+
+  const { dispatch, screenshot } = outcome;
+  const rows: FactLine[] = [
+    fact`scrolled ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}) to ${dispatch.to} — scrollTop now ${dispatch.scrollTop}`,
+    fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
+  ];
+  if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+
+  emitResult(
+    {
+      tag: 'scrolled',
+      attrs: {
+        'backend-node-id': dispatch.backendNodeId,
+        role: dispatch.role ?? undefined,
+        name: dispatch.name ?? undefined,
+        to: dispatch.to,
+        'scroll-top': dispatch.scrollTop,
+      },
+      summary: lineList(rows),
+    },
+    { json: parsed.json },
+  );
+}

package/src/cdp/commands/page/shot.ts

@@ -0,0 +1,208 @@
+/**
+ * `page shot` — capture a PNG of the tab as it is right now (design D2/D10).
+ *
+ * The navigational look: vision as navigator, never inspector — cheap, no
+ * settling, no collectors. With no flags it captures the browser's ACTUAL
+ * current viewport and performs zero `Emulation.*` calls; emulation exists
+ * only when explicitly asked (`--viewport <WxH>` / `--full-page`), applied
+ * as a transient `Emulation.setDeviceMetricsOverride` (+ ~150ms re-layout)
+ * and cleared after — two page-observable resizes, declared as the leaf's
+ * effect in `-h` (I-1/I-2 posture). Explicit viewport emulation uses the
+ * single `WxH` grammar (D10).
+ *
+ * Destination: `--out <path>` wins; otherwise the active session's `shots/`
+ * sequence; sessionless with no `--out` → a fresh `oneshot-{id}/page` dir
+ * under the capture root (never a loose /tmp file).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { type ParsedArgs } from '../../types.js';
+import { withConnection } from '../../connection.js';
+import { captureScreenshot } from '../../screenshot.js';
+import { parseViewport, type Viewport } from '../../viewport.js';
+import { nextStepPath } from '../../../session-context.js';
+import { createOneshotSession } from '../../../session/commands.js';
+import { assertUnderCaptureRoot, writeBinaryPrivate } from '../../../session/artifacts.js';
+import {
+  emitResult,
+  fact,
+  text,
+  type FactLine,
+  type RenderableResult,
+} from '../../../output/render.js';
+
+const USAGE = `capture page shot — capture a PNG of the tab as it is right now
+
+input:
+  --viewport <WxH>  transient device-metrics override for this capture; grammar: <positive-safe-int>x<positive-safe-int>, exact lowercase x with no whitespace — preset names are not accepted. Absent → no emulation, the browser's actual current viewport is captured
+  --full-page       transient override to the full scrollable content height for this capture
+  --out <path>      destination file; default: the active session's shots/ sequence, or a fresh oneshot-*/page/ dir under the capture root when no session is active
+  --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
+  --json            mirror the result as JSON
+output:
+  <screenshot path=… width=… height=… emulation=none|viewport|full-page> — saved path, PNG pixel dimensions, byte size, and the emulation fact (whether a transient override was applied, or its absence)
+effects:
+  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. With --viewport/--full-page: applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes (resize events fire; media queries flip and flip back)`;
+
+// ---------------------------------------------------------------------------
+// Test-injectable dependency seam (the CDP-stub test pattern; the capture
+// pipeline itself — captureScreenshot — is NOT injectable, so the tests
+// prove the real CDP traffic against a stub client).
+// ---------------------------------------------------------------------------
+
+export interface PageShotDeps {
+  withConnection: typeof withConnection;
+  nextStepPath: typeof nextStepPath;
+  createOneshotSession: typeof createOneshotSession;
+}
+
+let deps: PageShotDeps = { withConnection, nextStepPath, createOneshotSession };
+
+/** Swap the connection/session seams for the CDP-stub tests. */
+export function __setPageShotDepsForTest(overrides: Partial<PageShotDeps>): () => void {
+  const previous = deps;
+  deps = { ...deps, ...overrides };
+  return () => { deps = previous; };
+}
+
+// ---------------------------------------------------------------------------
+// PNG dimensions — measured from the actual bytes written, not echoed input
+// ---------------------------------------------------------------------------
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Reads width/height from the IHDR chunk (always first per the PNG spec).
+ * Returns null for anything that is not a parseable PNG. */
+export function pngDimensions(png: Buffer): { width: number; height: number } | null {
+  if (png.length < 24) return null;
+  if (!png.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+}
+
+// ---------------------------------------------------------------------------
+// Destination + private write
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves the output path: explicit `--out` > active session's `shots/`
+ * sequence > a fresh `oneshot-{id}/page` dir under the capture root.
+ */
+async function resolveOutPath(parsed: ParsedArgs): Promise<string> {
+  if (parsed.out) return parsed.out;
+  const sessionPath = await deps.nextStepPath('shot', 'manual');
+  if (sessionPath) return sessionPath;
+  return path.join(deps.createOneshotSession('page').artifactsDir, 'shot.png');
+}
+
+/**
+ * Writes the PNG privately (0600 under a 0700 dir) when it lands under
+ * CAPTURE_ROOT (auto-generated session/oneshot paths), and with a plain
+ * write when the user gave an explicit `--out` outside the capture tree —
+ * a user-chosen destination whose permissions are the user's to decide.
+ */
+function writeScreenshot(outPath: string, png: Buffer): void {
+  try {
+    assertUnderCaptureRoot(outPath);
+  } catch {
+    fs.writeFileSync(outPath, png);
+    return;
+  }
+  writeBinaryPrivate(outPath, png);
+}
+
+// ---------------------------------------------------------------------------
+// Result assembly
+// ---------------------------------------------------------------------------
+
+export type EmulationMode = 'none' | 'viewport' | 'full-page';
+
+export function buildScreenshotResult(f: {
+  path: string;
+  bytes: number;
+  dimensions: { width: number; height: number } | null;
+  emulation: EmulationMode;
+  viewport?: { width: number; height: number };
+}): RenderableResult {
+  const sections: FactLine[] = [
+    f.emulation === 'none'
+      ? text`emulation: none — the browser's actual current viewport was captured; no Emulation call was made.`
+      : f.emulation === 'viewport'
+        ? fact`emulation: transient ${f.viewport!.width}x${f.viewport!.height} device-metrics override applied for the capture and cleared after — two page-observable resizes.`
+        : f.viewport
+          ? fact`emulation: transient full-page device-metrics override (from ${f.viewport.width}x${f.viewport.height}) applied for the capture and cleared after — two page-observable resizes.`
+          : text`emulation: transient full-page device-metrics override applied for the capture and cleared after — two page-observable resizes.`,
+  ];
+  return {
+    tag: 'screenshot',
+    attrs: {
+      path: f.path,
+      width: f.dimensions?.width,
+      height: f.dimensions?.height,
+      emulation: f.emulation,
+    },
+    summary: f.dimensions
+      ? fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes.`
+      : fact`saved ${f.path} — ${f.bytes} bytes.`,
+    sections,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// page shot
+// ---------------------------------------------------------------------------
+
+export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  if (parsed.positional.length > 0) {
+    emitResult(
+      {
+        tag: 'error',
+        attrs: { command: 'page shot', code: 'invalid_input' },
+        summary: fact`received: ${parsed.positional.length} positional arguments; expected none — \`capture page shot [--viewport <WxH>] [--full-page] [--out <path>]\`.`,
+      },
+      { json: parsed.json },
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let viewport: Viewport | undefined;
+  if (parsed.viewport !== undefined) {
+    try {
+      viewport = parseViewport(parsed.viewport);
+    } catch {
+      emitResult(
+        {
+          tag: 'error',
+          attrs: { command: 'page shot', code: 'invalid_viewport' },
+          summary: fact`received: --viewport ${parsed.viewport}; expected: <positive-safe-int>x<positive-safe-int> with exact lowercase x and no whitespace. Preset names are not accepted.`,
+        },
+        { json: parsed.json },
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const emulation: EmulationMode = parsed.fullPage ? 'full-page' : viewport ? 'viewport' : 'none';
+
+  // connection.ts derives the recorder-routed action label from
+  // parsed.command, which the router leaves as the branch token 'page' —
+  // restore the verb so stderr diagnostics identify this leaf.
+  const result = await deps.withConnection(
+    { ...parsed, command: 'shot' },
+    async (client) => {
+      const png = await captureScreenshot(client, viewport, { fullPage: parsed.fullPage });
+      const outPath = await resolveOutPath(parsed);
+      writeScreenshot(outPath, png);
+      return { path: outPath, bytes: png.length, dimensions: pngDimensions(png) };
+    },
+    { settle: 0 },
+  );
+
+  emitResult(buildScreenshotResult({ ...result, emulation, viewport }), { json: parsed.json });
+}