@crouton-kit/capture 1.3.18 → 1.3.20

package/src/cdp/color-scheme.ts

@@ -0,0 +1,47 @@
+import type { CDPClient } from './client.js';
+
+export type ColorScheme = 'dark' | 'light';
+
+type MediaClient = Pick<CDPClient, 'send'>;
+
+export function parseColorScheme(value: string | undefined): ColorScheme | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'dark' || value === 'light') return value;
+  throw new Error('--color-scheme must be dark or light');
+}
+
+/** Applies one media-feature override only for the supplied capture operation. */
+export async function withAppliedColorScheme<T>(client: MediaClient, colorScheme: ColorScheme | undefined, fn: () => Promise<T>): Promise<T> {
+  if (!colorScheme) return fn();
+  let ownsMediaOverride = false;
+  let primaryFailed = false;
+  let primaryError: unknown;
+  try {
+    // A rejected response does not prove Chrome rejected the request. Claim
+    // cleanup responsibility before awaiting it, just as viewport capture does.
+    ownsMediaOverride = true;
+    await client.send('Emulation.setEmulatedMedia', {
+      features: [{ name: 'prefers-color-scheme', value: colorScheme }],
+    });
+    return await fn();
+  } catch (error) {
+    primaryFailed = true;
+    primaryError = error;
+    throw error;
+  } finally {
+    if (ownsMediaOverride) {
+      try {
+        await client.send('Emulation.setEmulatedMedia', { features: [] });
+      } catch (cleanupError) {
+        if (primaryFailed) {
+          throw new AggregateError(
+            [primaryError, cleanupError],
+            'Color-scheme capture failed and media-emulation cleanup also failed.',
+            { cause: primaryError },
+          );
+        }
+        throw cleanupError;
+      }
+    }
+  }
+}

package/src/cdp/commands/measure/index.ts

@@ -36,7 +36,7 @@ Every leaf defaults to rendered prose; --json mirrors the same result.
 Findings exit 0 — a report, not a failure.
 \`--gate\` (exit 2 on findings/changes) is accepted only by check and diff.
 
-<subcommand name="snap" args="[url|snap] [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled] [--pixels] [--state <state[:selector]>]... [--viewport <WxH>]..." whenToUse="drive + write the settled snapshot substrate every other leaf reads"/>
+<subcommand name="snap" args="[url|snap] [--freeze-animations] [--settle-timeout <ms>] [--capture-unsettled] [--pixels] [--state <state[:selector]>]... [--viewport <WxH>]... [--color-scheme <dark|light>]" whenToUse="drive + write the settled snapshot substrate every other leaf reads"/>
 <subcommand name="check" args="[url|snap] [--for <checks>] [--gate]" whenToUse="read threshold/fact measurements from one snapshot"/>
 <subcommand name="diff" args="--before <snap> --after <snap> [--pixels] [--full] [--gate]" whenToUse="structured before/after delta between two snapshots"/>
 <subcommand name="census" args="[--snap <id>]... [--url <url>]... [--set-file <path>] --axis <axis>" whenToUse="value distributions across one or more snapshots"/>

package/src/cdp/commands/measure/snap.ts

@@ -6,7 +6,9 @@ import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
 import { isRecorderHeldClient } from '../../recorder-client.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
-import { captureSnapshotSubstrate } from '../../measure/snapshot.js';
+import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
+import { captureSnapshotSubstrate, COLLECTOR_NAMES, SnapshotCaptureTimeout } from '../../measure/snapshot.js';
+import type { CollectorOutcome } from '../../measure/types.js';
 import { sanitizeString } from '../../measure/redaction.js';
 import { DEFAULT_SETTLE_TIMEOUT_MS } from '../../measure/settle.js';
 import { createOneshotSession } from '../../../session/commands.js';
@@ -31,11 +33,13 @@ input:
   --freeze-animations         pause CSS/WAAPI animation before capture
   --settle-timeout <ms>       override the default 5000ms settle wait
   --capture-unsettled         write the full substrate despite non-settlement, marking unstable regions
+  --skip-collector <name>     leave one collector out entirely (repeatable): ax, styles, queries, animation, layers, media, geometry, hittest, text, forms, focus, scroll, states, pixels. A collector that fails is recorded and skipped; every other collector's substrate is still written
   --pixels                    also write per-element raster crops
   --state <state[:selector]>  force a pseudo-state or real control state (repeatable)
   --viewport <WxH>            temporarily capture at a CSS-pixel viewport (repeatable); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
+  --color-scheme <dark|light> temporarily capture under this prefers-color-scheme value; cleared afterward
 output: <snapshot id=… path=…> — the settled artifact directory (geometry, styles, hit-test, text, forms, animation, ax, queries, focus, scroll, layers; per-element crops with --pixels) every other measure/motion query leaf reads instead of re-driving the browser; --json mirrors
-effects: drives the target page to capture; writes one snapshot artifact directory under the active (or a private one-shot) session`;
+effects: drives the target page to capture; writes one snapshot artifact directory under the active (or a private one-shot) session. --color-scheme transiently applies Emulation.setEmulatedMedia and clears it after capture.`;
 
 interface SnapshotMetaForBase {
   readonly url?: string | null;
@@ -188,6 +192,17 @@ export async function withAppliedViewport<T>(client: ViewportClient, viewport: V
   }
 }
 
+/** One line naming every collector whose substrate is absent or degraded, and what to do about it. */
+function collectorNote(incomplete: readonly CollectorOutcome[]) {
+  const described = incomplete
+    .map((c) => `${sanitizeString(c.name)} (${c.status}${c.requestTimeouts ? `, ${c.requestTimeouts} timed-out request(s)` : ''})`)
+    .join(', ');
+  const failed = incomplete.some((c) => c.status === 'error' || c.status === 'degraded');
+  return fact`collectors incomplete: ${described}. Every other collector's substrate is valid and queryable.${
+    failed ? ` Re-run with \`--skip-collector <name>\` to omit one deliberately rather than have it fail.` : ''
+  }`;
+}
+
 function settledNote(settled: boolean, captured: boolean, settleMs: number, settleTimeoutMs: number, unstableCount: number) {
   if (settled) {
     return fact`Settled after ${settleMs}ms (two consecutive identical captures; DOM quiet ≥300ms).`;
@@ -203,16 +218,22 @@ function settledNote(settled: boolean, captured: boolean, settleMs: number, sett
  * seam rather than importing the substrate directly, preserving snap as the
  * sole live-driving primitive.
  */
-export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.positional[0], viewportValue = parsed.viewport): Promise<MeasureSnapCapture> {
+export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.positional[0], viewportValue = parsed.viewport, colorSchemeValue = parsed.colorScheme): Promise<MeasureSnapCapture> {
   if (parsed.positional.length > 1) {
     throw invalidInput('measure snap accepts at most one positional URL or snapshot reference');
   }
   if (parsed.settleTimeout !== undefined && (!Number.isFinite(parsed.settleTimeout) || parsed.settleTimeout <= 0)) {
     throw invalidInput('--settle-timeout must be a positive number of milliseconds');
   }
+  for (const name of parsed.skipCollector ?? []) {
+    if (!COLLECTOR_NAMES.includes(name)) {
+      throw invalidInput(`--skip-collector must name a collector: ${COLLECTOR_NAMES.join(', ')} (got ${sanitizeString(name)})`);
+    }
+  }
   const viewport: ViewportSpec | undefined = viewportValue === undefined
     ? undefined
     : { label: viewportValue, ...parseViewport(viewportValue) };
+  const colorScheme = parseColorScheme(colorSchemeValue);
 
   let base: SnapRef | undefined;
   let baseUrl: string | null = null;
@@ -238,7 +259,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
   try {
     let artifacts: readonly string[] = [];
     await withConnection(connectionArgs, async (client, tab) => {
-      await withAppliedViewport(client, viewport, async () => {
+      await withAppliedColorScheme(client, colorScheme, async () => withAppliedViewport(client, viewport, async () => {
         const oneshot = active ? undefined : createOneshotSession('measure');
         const destination = active ? path.join(active.dir, 'measure', 'snaps') : oneshot!.artifactsDir;
         snapDir = path.join(destination, snapId);
@@ -254,15 +275,17 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
           pixels: parsed.pixels,
           state: parsed.state ?? [],
           viewport: viewport?.label ?? null,
+          colorScheme,
+          skipCollectors: parsed.skipCollector ?? [],
         });
         artifacts = result.artifacts;
-      });
+      }));
     }, { settle: 0 });
 
     if (!snapDir) throw new Error('measure snap did not allocate an artifact directory');
     return { id: snapId, dir: snapDir, artifacts, ...(base ? { base } : {}) };
   } catch (err) {
-    if (allocatedRoot) removeArtifactTree(allocatedRoot);
+    if (allocatedRoot && !(err instanceof SnapshotCaptureTimeout)) removeArtifactTree(allocatedRoot);
     throw err;
   }
 }
@@ -271,12 +294,15 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
   const meta = readMeta<{
     url: string | null;
     viewport: string | null;
+    colorScheme?: ColorScheme;
     settled: boolean;
     settleMs: number;
     settleTimeoutMs: number;
     unstableRegionCount: number;
     states: readonly string[];
+    collectors?: readonly CollectorOutcome[];
   }>({ kind: 'snap', id: captured.id, dir: captured.dir });
+  const incomplete = (meta.collectors ?? []).filter((c) => c.status !== 'ok');
   const elements = readArrayCount(path.join(captured.dir, 'geometry.json'), 'elements');
   const artifacts = artifactEntries(captured.dir, captured.artifacts);
   const capturedFullSubstrate = fs.existsSync(path.join(captured.dir, 'geometry.json'));
@@ -292,6 +318,7 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
     attrs: {
       url: meta.url ?? undefined,
       viewport: meta.viewport ?? undefined,
+      'color-scheme': meta.colorScheme,
       elements,
       settled: meta.settled,
       'settle-ms': meta.settleMs,
@@ -301,6 +328,11 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
     summary: meta.settled || capturedFullSubstrate
       ? text`Snapshot substrate captured.`
       : text`The evidence snapshot is not queryable because the settledness requirement was not met.`,
+    // A collector that did not complete cleanly must be visible in the block,
+    // not only in meta.json — its artifact is absent (timeout/error/skipped)
+    // or partly built from timed-out reads (degraded), and a caller who reads
+    // the remaining substrate as a whole page would be reading a hole.
+    ...(incomplete.length ? { sections: [collectorNote(incomplete)] } : {}),
     artifacts: formatArtifactList(artifacts),
     followUp: meta.settled || capturedFullSubstrate
       ? fact`Query snapshot ${captured.id} with \`capture measure check ${captured.id}\`, \`capture measure census --snap ${captured.id} --axis color\`, or \`capture measure map focus ${captured.id}\`.`
@@ -312,6 +344,9 @@ interface SnapErrorDetails {
   readonly status: string;
   readonly message: string;
   readonly resolution?: ArtifactResolutionError;
+  readonly phase?: string;
+  readonly method?: string;
+  readonly partialPath?: string;
 }
 
 function safeErrorDetail(value: unknown): string {
@@ -319,6 +354,9 @@ function safeErrorDetail(value: unknown): string {
 }
 
 export function classifySnapError(err: unknown): SnapErrorDetails {
+  if (err instanceof SnapshotCaptureTimeout) {
+    return { status: 'snapshot_capture_timeout', message: safeErrorDetail(err), phase: err.phase, method: err.method, partialPath: err.partialPath };
+  }
   if (err instanceof ArtifactResolutionError) {
     return { status: 'snapshot_ref_unavailable', message: safeErrorDetail(err), resolution: err };
   }
@@ -326,7 +364,7 @@ export function classifySnapError(err: unknown): SnapErrorDetails {
   if (message.startsWith('--viewport cannot ')) {
     return { status: 'viewport_unavailable', message };
   }
-  if (message.startsWith('measure snap accepts') || message.startsWith('--settle-timeout') || message.startsWith('--viewport')) {
+  if (message.startsWith('measure snap accepts') || message.startsWith('--settle-timeout') || message.startsWith('--viewport') || message.startsWith('--color-scheme')) {
     return { status: 'invalid_input', message };
   }
   if (message.includes('No tab found') || message.includes('Use --target') || message.includes('Tab has no WebSocket debugger URL')) {
@@ -376,9 +414,10 @@ export async function cmdMeasureSnap(parsed: ParsedArgs, _args: string[]): Promi
       if (value === undefined) return undefined;
       return { label: value, ...parseViewport(value) };
     });
+    const colorScheme = parseColorScheme(parsed.colorScheme);
     const results = [] as RenderableResult[];
     for (const viewport of viewports) {
-      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport?.label);
+      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport?.label, colorScheme);
       captures.push(capture);
       results.push(buildSnapshotResult(capture));
     }
@@ -399,6 +438,9 @@ export async function cmdMeasureSnap(parsed: ParsedArgs, _args: string[]): Promi
       attrs: {
         command: 'measure snap',
         status: classified.status,
+        ...(classified.phase ? { phase: classified.phase } : {}),
+        ...(classified.method ? { method: classified.method } : {}),
+        ...(classified.partialPath ? { 'partial-path': classified.partialPath } : {}),
         ...(classified.resolution ? {
           recovery: 'artifact-resolution-error',
           ref: sanitizeString(classified.resolution.ref),

package/src/cdp/commands/motion/mask.ts

@@ -24,9 +24,15 @@ export async function cmdMotionMask(parsed: ParsedArgs, _args: string[]): Promis
 
   try {
     const ref = resolveRecRef(parsed.positional[0]);
-    const meta = readMeta<{ state?: unknown }>(ref);
+    const meta = readMeta<{ state?: unknown; reason?: unknown }>(ref);
     const state = typeof meta.state === 'string' ? meta.state : 'unknown';
-    if (state !== 'finalized' && state !== 'orphaned-finalized') {
+    // A one-shot recording that captured zero screencast frames is a completed
+    // recording, not one awaiting `--stop` (which only finalizes an active
+    // composed lifecycle recording) — let it through and rely on
+    // createMotionMask's own accurate "needs at least two frames" rejection
+    // below, matching the same exception in response.ts's loadResponseTimeline.
+    const readablePartial = state === 'partial' && meta.reason === 'no_frames';
+    if (state !== 'finalized' && state !== 'orphaned-finalized' && !readablePartial) {
       return emitCommandError(parsed, 'recording_not_finalized', `Recording ${ref.id} has state ${state}; finalize it with \`capture motion rec --stop\` before creating a mask.`);
     }
     const mask = createMotionMask(ref);

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

@@ -94,6 +94,20 @@ export function emitResolutionError(parsed: ParsedArgs, command: string, failure
     return;
   }
 
+  if (failure.code === 'invalid-css-selector') {
+    emitResult(
+      {
+        tag: 'error',
+        attrs: { command, code: 'invalid_css_selector' },
+        summary: fact`received: bare target \`${failure.input}\` was rejected by DOM.querySelectorAll as a CSS selector.`,
+        followUp: fact`Retry \`capture ${command} ax:${failure.input}\` to target that accessible name, or use \`backend:<id>\` from \`capture page elements\`.`,
+      },
+      { json: parsed.json },
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   const code = failure.code === 'no-match' ? 'no_match' : 'ambiguous_target';
   const candidateRows: FactLine[] = failure.candidates.map((c) =>
     line(data(c.role ?? 'unknown'), text` "`, data(c.name ?? ''), text`" — backend:`, data(c.backendNodeId)),

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

@@ -42,7 +42,7 @@ Input:
   --json              mirror the result as JSON
 
 Output:
-  <elements scope="interactive|all" count=<total>> — one row per element: role "name" backend:<id>
+  <elements scope="interactive|all" count=<total>> — one row per element: role "name" target:ax:<name> backend:<id>; copy the target value into a driving verb
 
 Effects: read-only — the accessibility fetch is CDP-side, no page-observable writes; routes unmarked through an active composed recording.`;
 
@@ -106,7 +106,7 @@ export function buildElementsResult(
 
   const rows = shown.map((r) =>
     r.backendNodeId !== null
-      ? fact`${r.role} "${r.name}" backend:${r.backendNodeId}`
+      ? fact`${r.role} "${r.name}" target:ax:${r.name} backend:${r.backendNodeId}`
       : fact`${r.role} "${r.name}"`,
   );
 

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

@@ -39,7 +39,7 @@ During a live composed recording every verb routes through the recorder.
 <subcommand name="scroll" args="<target> --to <top|bottom|px> [--no-screenshot]" whenToUse="scroll one resolved container to a position"/>
 <subcommand name="navigate" args="<url> [--settle <ms>]" whenToUse="navigate the tab and wait for load + settle"/>
 <subcommand name="exec" args="<code> | --file <path>" whenToUse="run arbitrary JS in the tab (expressions, return, await)"/>
-<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--out <path>]" whenToUse="look at the page right now without acting"/>
+<subcommand name="shot" args="[--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]" whenToUse="look at the page right now without acting"/>
 <subcommand name="elements" args="[--all] [--limit <n>]" whenToUse="list what can be acted on — role, name, backend:<id> per element"/>
 
 capture page <leaf> -h    Per-leaf usage`;

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

@@ -4,8 +4,9 @@
  * 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)
+ * only when explicitly asked (`--viewport <WxH>` / `--full-page` /
+ * `--color-scheme dark|light`), applied transiently; viewport emulation uses
+ * `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).
@@ -18,8 +19,9 @@ 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 { captureScreenshotWithCssViewport, type CapturedRegion } from '../../screenshot.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
+import { parseColorScheme, withAppliedColorScheme, type ColorScheme } from '../../color-scheme.js';
 import { nextStepPath } from '../../../session-context.js';
 import { createOneshotSession } from '../../../session/commands.js';
 import { assertUnderCaptureRoot, writeBinaryPrivate } from '../../../session/artifacts.js';
@@ -36,13 +38,14 @@ 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
+  --color-scheme <dark|light>  transient prefers-color-scheme override for this capture; cleared afterward
   --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)
+  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page color-scheme=dark|light> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, byte size, and any requested transient emulation
 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)`;
+  no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. --viewport/--full-page applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture.`;
 
 // ---------------------------------------------------------------------------
 // Test-injectable dependency seam (the CDP-stub test pattern; the capture
@@ -116,21 +119,40 @@ function writeScreenshot(outPath: string, png: Buffer): void {
 
 export type EmulationMode = 'none' | 'viewport' | 'full-page';
 
+/** Renders a CSS-pixel measurement without inventing precision: an integer stays an integer, a fractional zoomed viewport keeps six decimals. */
+function round6(value: number): number {
+  return Math.round(value * 1e6) / 1e6;
+}
+
 export function buildScreenshotResult(f: {
   path: string;
   bytes: number;
   dimensions: { width: number; height: number } | null;
+  cssViewport?: CapturedRegion;
   emulation: EmulationMode;
   viewport?: { width: number; height: number };
+  colorScheme?: ColorScheme;
 }): RenderableResult {
+  // The denominator is the CSS region the image was actually cut from, so the
+  // ratio stays true under page zoom, device pixel ratio, and the local
+  // downscale — the layout viewport is a different space and is never used here.
+  const scale = f.dimensions && f.cssViewport
+    ? { x: f.dimensions.width / f.cssViewport.width, y: f.dimensions.height / f.cssViewport.height }
+    : undefined;
   const sections: FactLine[] = [
+    scale && f.cssViewport
+      ? fact`CSS-to-image scale: ${scale.x.toFixed(6)} image px/CSS px horizontally and ${scale.y.toFixed(6)} image px/CSS px vertically (captured CSS region ${round6(f.cssViewport.width)}×${round6(f.cssViewport.height)} at page origin ${round6(f.cssViewport.x)},${round6(f.cssViewport.y)}).`
+      : text`CSS-to-image scale unavailable: the browser did not return the CSS region this capture covers.`,
     f.emulation === 'none'
-      ? text`emulation: none — the browser's actual current viewport was captured; no Emulation call was made.`
+      ? text`viewport emulation: none — the browser's actual current viewport was captured.`
       : 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.`,
+    f.colorScheme
+      ? fact`color scheme: transient prefers-color-scheme=${f.colorScheme} override applied for the capture and cleared after.`
+      : text`color scheme: browser default — no Emulation.setEmulatedMedia call was made.`,
   ];
   return {
     tag: 'screenshot',
@@ -138,7 +160,14 @@ export function buildScreenshotResult(f: {
       path: f.path,
       width: f.dimensions?.width,
       height: f.dimensions?.height,
+      'css-width': f.cssViewport === undefined ? undefined : round6(f.cssViewport.width),
+      'css-height': f.cssViewport === undefined ? undefined : round6(f.cssViewport.height),
+      'css-x': f.cssViewport === undefined ? undefined : round6(f.cssViewport.x),
+      'css-y': f.cssViewport === undefined ? undefined : round6(f.cssViewport.y),
+      'css-to-image-x': scale?.x.toFixed(6),
+      'css-to-image-y': scale?.y.toFixed(6),
       emulation: f.emulation,
+      'color-scheme': f.colorScheme,
     },
     summary: f.dimensions
       ? fact`saved ${f.path} — ${f.dimensions.width}x${f.dimensions.height}px, ${f.bytes} bytes.`
@@ -162,7 +191,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
       {
         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>]\`.`,
+        summary: fact`received: ${parsed.positional.length} positional arguments; expected none — \`capture page shot [--viewport <WxH>] [--full-page] [--color-scheme <dark|light>] [--out <path>]\`.`,
       },
       { json: parsed.json },
     );
@@ -188,6 +217,22 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
     }
   }
 
+  let colorScheme: ColorScheme | undefined;
+  try {
+    colorScheme = parseColorScheme(parsed.colorScheme);
+  } catch {
+    emitResult(
+      {
+        tag: 'error',
+        attrs: { command: 'page shot', code: 'invalid_color_scheme' },
+        summary: fact`received: --color-scheme ${parsed.colorScheme}; expected dark or light.`,
+      },
+      { 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
@@ -195,14 +240,14 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
   // 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 });
+    async (client) => withAppliedColorScheme(client, colorScheme, async () => {
+      const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage });
       const outPath = await resolveOutPath(parsed);
-      writeScreenshot(outPath, png);
-      return { path: outPath, bytes: png.length, dimensions: pngDimensions(png) };
-    },
+      writeScreenshot(outPath, screenshot.png);
+      return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport };
+    }),
     { settle: 0 },
   );
 
-  emitResult(buildScreenshotResult({ ...result, emulation, viewport }), { json: parsed.json });
+  emitResult(buildScreenshotResult({ ...result, emulation, viewport, colorScheme }), { json: parsed.json });
 }

package/src/cdp/commands/tab/index.ts

@@ -10,6 +10,8 @@
  */
 import { invalidInput } from '../../../errors.js';
 import { type ParsedArgs } from '../../types.js';
+import { cmdTabLaunch } from './launch.js';
+import { cmdTabQuit } from './quit.js';
 import { cmdTabList } from './list.js';
 import { cmdTabOpen } from './open.js';
 import { cmdTabClose } from './close.js';
@@ -18,19 +20,24 @@ import { cmdTabNetwork } from './network.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="tab">
-tab and connection plumbing — endpoint/tab discovery, lifecycle, connection-level network emulation
-use when finding a CDP endpoint or tab, opening/closing/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
-  list · open · close · reset · network — \`capture tab -h\`
+browser and tab plumbing — starting/stopping a browser capture owns, endpoint/tab discovery, tab lifecycle, connection-level network emulation
+use when nothing is running yet (\`tab launch\` starts a browser capture owns and reaps), when finding a CDP endpoint or tab, opening/closing/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
+  launch · quit · list · open · close · reset · network — \`capture tab -h\`
 </command>`;
 
-export const TAB_USAGE = `capture tab — tab and connection plumbing: discovery, lifecycle, network emulation.
+export const TAB_USAGE = `capture tab — browser and tab plumbing: browser lifecycle, discovery, tab lifecycle, network emulation.
 
 \`tab list\` with no --port performs full endpoint discovery and is the probe
-for whether a CDP-enabled browser is running at all. \`tab reset\` replaces a
-stuck tab with a fresh one; under an active session it refuses while a
-recording is active (stop it first), reaps dead recorder handles, and updates
-the session's {target, port} pair together.
+for whether a CDP-enabled browser is running at all; when nothing is running,
+\`tab launch\` starts one capture owns — never hand-roll a detached browser,
+since nothing reaps that. Capture signals only browsers it launched itself
+(verified by process-birth identity): an endpoint you reach with --port stays
+untouched. \`tab reset\` replaces a stuck tab with a fresh one; under an active
+session it refuses while a recording is active (stop it first), reaps dead
+recorder handles, and updates the session's {target, port} pair together.
 
+<subcommand name="launch" args="[--url <url>] [--port <port>] [--headed]" whenToUse="start a browser capture owns (and reaps) when none is running"/>
+<subcommand name="quit" args="[<port>] [--all]" whenToUse="stop a browser capture launched; never touches a browser capture did not start"/>
 <subcommand name="list" args="[--port <port>]" whenToUse="discover CDP endpoints and the tabs open on them"/>
 <subcommand name="open" args="<url> [--new] [--port <port>]" whenToUse="open a URL and get its tab id"/>
 <subcommand name="close" args="<target> [--port <port>]" whenToUse="close one explicitly identified background tab"/>
@@ -44,6 +51,10 @@ export async function tabMain(parsed: ParsedArgs, args: string[]): Promise<void>
   const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
 
   switch (leaf) {
+    case 'launch':
+      return cmdTabLaunch(rest, args);
+    case 'quit':
+      return cmdTabQuit(rest, args);
     case 'list':
       return cmdTabList(rest, args);
     case 'open':

package/src/cdp/commands/tab/launch.ts

@@ -0,0 +1,73 @@
+/**
+ * `capture tab launch [--url <url>] [--port <port>] [--headed]` — start a
+ * browser capture owns, and report the endpoint every other capture command can
+ * now be pointed at.
+ *
+ * This is the answer to "a CDP-enabled browser must be running": without it the
+ * only way to satisfy that precondition was a hand-rolled detached Chrome with
+ * an invented port and an invented scratch profile, which nothing ever reaped.
+ * Ownership, registry, and reaping all live in `../../browser-process.ts`; this
+ * leaf is the surface over them.
+ */
+import { launchOwnedBrowser, sweepOwnedBrowsers, IDLE_REAP_MS } from '../../browser-process.js';
+import { type ParsedArgs } from '../../types.js';
+import { data, emitResult, fact, line, lineList, text, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture tab launch — start a browser capture owns and report its CDP endpoint.
+
+input:
+  --url <url>     first page to open (default: about:blank)
+  --port <port>   pin the debugging port (default: a free port chosen by the kernel)
+  --headed        run with a visible window instead of headless
+
+output: <browser-launched port=… pid=…> — the port to pass as --port (or CDP_PORT), the pid capture owns, and the executable that answered with its provenance (CAPTURE_BROWSER, puppeteer-cache, or system).
+effects: spawns a detached browser with a private profile under CAPTURE_ROOT, and registers it as capture-owned. Capture stops it on \`capture tab quit\`, or on the first later capture invocation once it has been unused for ${IDLE_REAP_MS / 60000} minutes; a browser capture did not start is never signalled. Also sweeps previously-launched browsers that have exited, stopped answering CDP, or gone idle.`;
+
+/** Pure `<browser-launched>` result builder — exported for tests. */
+export function buildBrowserLaunchedResult(
+  browser: { port: number; pid: number; executablePath: string; source: string; headless: boolean },
+  swept: number,
+): RenderableResult {
+  const sections = [
+    lineList([
+      line(text`executable `, data(browser.executablePath, 300), text` (`, data(browser.source), text`)`),
+      line(text`mode `, data(browser.headless ? 'headless' : 'headed')),
+    ]),
+  ];
+  if (swept > 0) sections.push(fact`swept ${swept} previously-launched browser(s) that had exited, stopped answering CDP, or gone idle.`);
+  return {
+    tag: 'browser-launched',
+    attrs: { port: browser.port, pid: browser.pid, headless: browser.headless },
+    summary: line(
+      text`capture-owned browser on port `,
+      data(browser.port),
+      fact` (pid ${browser.pid}) is answering CDP.`,
+    ),
+    sections,
+    followUp: line(text`capture tab quit `, data(browser.port)),
+  };
+}
+
+export async function cmdTabLaunch(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const swept = await sweepOwnedBrowsers();
+  const browser = await launchOwnedBrowser({
+    url: parsed.url,
+    port: parsed.port,
+    headless: !parsed.headed,
+  });
+
+  emitResult(
+    buildBrowserLaunchedResult(
+      // A launched browser always reports a port — `launchOwnedBrowser` only
+      // returns once its endpoint answered on one.
+      { ...browser, port: browser.port! },
+      swept.length,
+    ),
+    { json: parsed.json },
+  );
+}