@crouton-kit/capture 1.3.19 → 1.3.20

package/bin/capture

@@ -9154,6 +9154,9 @@ function validateCliInvocation(parsed) {
         throw invalidInput(`Invalid --viewport: ${parsed.viewport}.`);
       }
     }
+    if (leaf === "shot" && parsed.colorScheme !== void 0 && parsed.colorScheme !== "dark" && parsed.colorScheme !== "light") {
+      throw invalidInput(`Invalid --color-scheme: ${parsed.colorScheme}; expected dark or light.`);
+    }
     return;
   }
   if (parsed.command === "tab") {
@@ -9167,6 +9170,9 @@ function validateCliInvocation(parsed) {
   }
   if (parsed.command === "measure") {
     if (leaf === "snap" || leaf === "check" || leaf === "sweep") requireCount(values, 0, 1, `measure ${leaf}`);
+    if (leaf === "snap" && parsed.colorScheme !== void 0 && parsed.colorScheme !== "dark" && parsed.colorScheme !== "light") {
+      throw invalidInput(`Invalid --color-scheme: ${parsed.colorScheme}; expected dark or light.`);
+    }
     if (leaf === "diff" || leaf === "census") requireCount(values, 0, 0, `measure ${leaf}`);
     if (leaf === "diff" && (!parsed.before || !parsed.after)) throw invalidInput("measure diff requires --before and --after.");
     if (leaf === "census" && !["color", "font", "spacing", "radius", "shadow", "animation", "geometry", "media", "queries"].includes(parsed.axis ?? "")) {
@@ -9272,6 +9278,9 @@ function parseCliSyntax(argv) {
       parsed.viewport = value;
       (parsed.viewports ??= []).push(value);
       i++;
+    } else if (arg === "--color-scheme") {
+      parsed.colorScheme = valueFor(arg, next);
+      i++;
     } else if (arg === "--full-page") parsed.fullPage = true;
     else if (arg === "--all") parsed.all = true;
     else if (arg === "--session") {
@@ -9431,6 +9440,7 @@ var init_args = __esm({
       "--url",
       "--into",
       "--viewport",
+      "--color-scheme",
       "--session",
       "--filter",
       "--name",
@@ -10221,7 +10231,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.3.19";
+  const version = "1.3.20";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -11980,7 +11990,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.3.19";
+  const version = "1.3.20";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -227597,6 +227607,49 @@ var init_viewport = __esm({
   }
 });
 
+// src/cdp/color-scheme.ts
+function parseColorScheme(value) {
+  if (value === void 0) return void 0;
+  if (value === "dark" || value === "light") return value;
+  throw new Error("--color-scheme must be dark or light");
+}
+async function withAppliedColorScheme(client, colorScheme, fn) {
+  if (!colorScheme) return fn();
+  let ownsMediaOverride = false;
+  let primaryFailed = false;
+  let primaryError;
+  try {
+    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;
+      }
+    }
+  }
+}
+var init_color_scheme = __esm({
+  "src/cdp/color-scheme.ts"() {
+  }
+});
+
 // src/cdp/commands/page/shot.ts
 function pngDimensions(png) {
   if (png.length < 24) return null;
@@ -227625,7 +227678,8 @@ function buildScreenshotResult(f) {
   const scale = f.dimensions && f.cssViewport ? { x: f.dimensions.width / f.cssViewport.width, y: f.dimensions.height / f.cssViewport.height } : void 0;
   const sections = [
     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.` : 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.emulation === "none" ? 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",
@@ -227639,7 +227693,8 @@ function buildScreenshotResult(f) {
       "css-y": f.cssViewport === void 0 ? void 0 : round6(f.cssViewport.y),
       "css-to-image-x": scale?.x.toFixed(6),
       "css-to-image-y": scale?.y.toFixed(6),
-      emulation: f.emulation
+      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.` : fact`saved ${f.path} — ${f.bytes} bytes.`,
     sections
@@ -227655,7 +227710,7 @@ async function cmdPageShot(parsed, _args) {
       {
         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 }
     );
@@ -227679,18 +227734,33 @@ async function cmdPageShot(parsed, _args) {
       return;
     }
   }
+  let colorScheme;
+  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 = parsed.fullPage ? "full-page" : viewport2 ? "viewport" : "none";
   const result = await deps4.withConnection(
     { ...parsed, command: "shot" },
-    async (client) => {
+    async (client) => withAppliedColorScheme(client, colorScheme, async () => {
       const screenshot = await captureScreenshotWithCssViewport(client, viewport2, { fullPage: parsed.fullPage });
       const outPath = await resolveOutPath(parsed);
       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: viewport2 }), { json: parsed.json });
+  emitResult(buildScreenshotResult({ ...result, emulation, viewport: viewport2, colorScheme }), { json: parsed.json });
 }
 var fs15, path17, USAGE6, deps4, PNG_SIGNATURE;
 var init_shot = __esm({
@@ -227700,6 +227770,7 @@ var init_shot = __esm({
     init_connection();
     init_screenshot();
     init_viewport();
+    init_color_scheme();
     init_session_context();
     init_commands();
     init_artifacts();
@@ -227709,13 +227780,14 @@ var init_shot = __esm({
 input:
   --viewport <WxH>  transient device-metrics override for this capture; grammar: <positive-safe-int>x<positive-safe-int>, exact lowercase x with no whitespace \u2014 preset names are not accepted. Absent \u2192 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=\u2026 width=\u2026 height=\u2026 css-width=\u2026 css-height=\u2026 css-x=\u2026 css-y=\u2026 css-to-image-x=\u2026 css-to-image-y=\u2026 emulation=none|viewport|full-page> \u2014 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 the emulation fact (whether a transient override was applied, or its absence)
+  <screenshot path=\u2026 width=\u2026 height=\u2026 css-width=\u2026 css-height=\u2026 css-x=\u2026 css-y=\u2026 css-to-image-x=\u2026 css-to-image-y=\u2026 emulation=none|viewport|full-page color-scheme=dark|light> \u2014 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 \u2014 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 \u2014 two page-observable resizes (resize events fire; media queries flip and flip back)`;
+  no flags: none \u2014 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 \u2014 two page-observable resizes. --color-scheme applies a transient Emulation.setEmulatedMedia prefers-color-scheme override and clears it after the capture.`;
     deps4 = { withConnection, nextStepPath, createOneshotSession };
     PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
   }
@@ -227856,7 +227928,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 \u2014 role, name, backend:<id> per element"/>
 
 capture page <leaf> -h    Per-leaf usage`;
@@ -235901,6 +235973,7 @@ async function captureSnapshotSubstrate(options) {
   const pixels = options.pixels ?? false;
   const state = options.state ?? [];
   const viewport2 = options.viewport ?? null;
+  const colorScheme = options.colorScheme;
   const url = options.url ? sanitizeString(options.url) : null;
   const artifacts = [];
   const phaseClient = (phase) => boundedClient(client, phase, dir);
@@ -236043,6 +236116,7 @@ async function captureSnapshotSubstrate(options) {
       captureUnsettled,
       pixels,
       states: state.map((spec) => sanitizeString(spec)),
+      ...colorScheme ? { colorScheme } : {},
       unstableRegionCount: unstableRegions.length,
       ...freezeAnimations ? { animationsRestored: animationsRestored ?? false } : {},
       // #8: the browser-wide `Animation.setPlaybackRate({playbackRate:0})`
@@ -236568,7 +236642,7 @@ function settledNote(settled, captured, settleMs, settleTimeoutMs, unstableCount
   }
   return fact`Page did not settle within ${settleTimeoutMs}ms. No queryable substrate was written; evidence artifacts only (${unstableCount} unstable region(s)).`;
 }
-async function captureMeasureSnap(parsed, targetRef = parsed.positional[0], viewportValue = parsed.viewport) {
+async function captureMeasureSnap(parsed, targetRef = parsed.positional[0], viewportValue = parsed.viewport, colorSchemeValue = parsed.colorScheme) {
   if (parsed.positional.length > 1) {
     throw invalidInput("measure snap accepts at most one positional URL or snapshot reference");
   }
@@ -236581,6 +236655,7 @@ async function captureMeasureSnap(parsed, targetRef = parsed.positional[0], view
     }
   }
   const viewport2 = viewportValue === void 0 ? void 0 : { label: viewportValue, ...parseViewport(viewportValue) };
+  const colorScheme = parseColorScheme(colorSchemeValue);
   let base;
   let baseUrl = null;
   if (targetRef && !isUrlRef(targetRef)) {
@@ -236595,7 +236670,7 @@ async function captureMeasureSnap(parsed, targetRef = parsed.positional[0], view
   try {
     let artifacts = [];
     await withConnection(connectionArgs, async (client, tab) => {
-      await withAppliedViewport(client, viewport2, async () => {
+      await withAppliedColorScheme(client, colorScheme, async () => withAppliedViewport(client, viewport2, async () => {
         const oneshot = active ? void 0 : createOneshotSession("measure");
         const destination = active ? path22.join(active.dir, "measure", "snaps") : oneshot.artifactsDir;
         snapDir = path22.join(destination, snapId);
@@ -236611,10 +236686,11 @@ async function captureMeasureSnap(parsed, targetRef = parsed.positional[0], view
           pixels: parsed.pixels,
           state: parsed.state ?? [],
           viewport: viewport2?.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 } : {} };
@@ -236640,6 +236716,7 @@ function buildSnapshotResult(captured) {
     attrs: {
       url: meta.url ?? void 0,
       viewport: meta.viewport ?? void 0,
+      "color-scheme": meta.colorScheme,
       elements,
       settled: meta.settled,
       "settle-ms": meta.settleMs,
@@ -236670,7 +236747,7 @@ function classifySnapError(err) {
   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")) {
@@ -236715,9 +236792,10 @@ async function cmdMeasureSnap(parsed, _args) {
       if (value === void 0) return void 0;
       return { label: value, ...parseViewport(value) };
     });
+    const colorScheme = parseColorScheme(parsed.colorScheme);
     const results = [];
     for (const viewport2 of viewports) {
-      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport2?.label);
+      const capture = await captureMeasureSnap(parsed, parsed.positional[0], viewport2?.label, colorScheme);
       captures.push(capture);
       results.push(buildSnapshotResult(capture));
     }
@@ -236767,6 +236845,7 @@ var init_snap = __esm({
     init_connection();
     init_recorder_client();
     init_viewport();
+    init_color_scheme();
     init_snapshot();
     init_redaction();
     init_settle();
@@ -236787,8 +236866,9 @@ input:
   --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=\u2026 path=\u2026> \u2014 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.`;
   }
 });
 
@@ -240154,7 +240234,7 @@ Every leaf defaults to rendered prose; --json mirrors the same result.
 Findings exit 0 \u2014 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"/>
@@ -242098,7 +242178,7 @@ CDP_PORT / CDP_TARGET pin the browser + tab for orchestrators \u2014 precedence:
 explicit flag > active session > env.`;
 }
 function printVersion() {
-  const declared = "1.3.19";
+  const declared = "1.3.20";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.19",
+  "version": "1.3.20",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/cdp/args.ts

@@ -15,7 +15,7 @@ export function expandEqualsFlags(argv: string[]): string[] {
 }
 
 const VALUE_FLAGS = new Set([
-  '--port', '--out', '--duration', '--settle', '--file', '--target', '--url', '--into', '--viewport', '--session',
+  '--port', '--out', '--duration', '--settle', '--file', '--target', '--url', '--into', '--viewport', '--color-scheme', '--session',
   '--filter', '--name', '--filter-url', '--filter-status', '--filter-method', '--limit', '--params', '--wait-event',
   '--timeout', '--socket', '--settle-timeout', '--state', '--for', '--before', '--after', '--snap', '--set-file',
   '--axis', '--from', '--to', '--viewport-height', '--rec-id', '--selector', '--do', '--element', '--prop', '--action', '--occurrence',
@@ -126,6 +126,9 @@ export function validateCliInvocation(parsed: ParsedArgs): void {
         throw invalidInput(`Invalid --viewport: ${parsed.viewport}.`);
       }
     }
+    if (leaf === 'shot' && parsed.colorScheme !== undefined && parsed.colorScheme !== 'dark' && parsed.colorScheme !== 'light') {
+      throw invalidInput(`Invalid --color-scheme: ${parsed.colorScheme}; expected dark or light.`);
+    }
     return;
   }
 
@@ -143,6 +146,9 @@ export function validateCliInvocation(parsed: ParsedArgs): void {
 
   if (parsed.command === 'measure') {
     if (leaf === 'snap' || leaf === 'check' || leaf === 'sweep') requireCount(values, 0, 1, `measure ${leaf}`);
+    if (leaf === 'snap' && parsed.colorScheme !== undefined && parsed.colorScheme !== 'dark' && parsed.colorScheme !== 'light') {
+      throw invalidInput(`Invalid --color-scheme: ${parsed.colorScheme}; expected dark or light.`);
+    }
     if (leaf === 'diff' || leaf === 'census') requireCount(values, 0, 0, `measure ${leaf}`);
     if (leaf === 'diff' && (!parsed.before || !parsed.after)) throw invalidInput('measure diff requires --before and --after.');
     if (leaf === 'census' && !['color', 'font', 'spacing', 'radius', 'shadow', 'animation', 'geometry', 'media', 'queries'].includes(parsed.axis ?? '')) {
@@ -233,6 +239,7 @@ export function parseCliSyntax(argv: string[]): ParsedArgs {
     else if (arg === '--into') { parsed.into = valueFor(arg, next); i++; }
     else if (arg === '--no-screenshot') parsed.noScreenshot = true;
     else if (arg === '--viewport') { const value = valueFor(arg, next); parsed.viewport = value; (parsed.viewports ??= []).push(value); i++; }
+    else if (arg === '--color-scheme') { parsed.colorScheme = valueFor(arg, next); i++; }
     else if (arg === '--full-page') parsed.fullPage = true;
     else if (arg === '--all') parsed.all = true;
     else if (arg === '--session') { parsed.session = valueFor(arg, next); i++; }

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,6 +6,7 @@ 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 { 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';
@@ -36,8 +37,9 @@ input:
   --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;
@@ -216,7 +218,7 @@ 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');
   }
@@ -231,6 +233,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
   const viewport: ViewportSpec | undefined = viewportValue === undefined
     ? undefined
     : { label: viewportValue, ...parseViewport(viewportValue) };
+  const colorScheme = parseColorScheme(colorSchemeValue);
 
   let base: SnapRef | undefined;
   let baseUrl: string | null = null;
@@ -256,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);
@@ -272,10 +275,11 @@ 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');
@@ -290,6 +294,7 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
   const meta = readMeta<{
     url: string | null;
     viewport: string | null;
+    colorScheme?: ColorScheme;
     settled: boolean;
     settleMs: number;
     settleTimeoutMs: number;
@@ -313,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,
@@ -358,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')) {
@@ -408,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));
     }

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).
@@ -20,6 +21,7 @@ import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.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=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page> — 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 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
@@ -128,6 +131,7 @@ export function buildScreenshotResult(f: {
   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
@@ -140,12 +144,15 @@ export function buildScreenshotResult(f: {
       ? 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',
@@ -160,6 +167,7 @@ export function buildScreenshotResult(f: {
       '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.`
@@ -183,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 },
     );
@@ -209,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
@@ -216,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) => {
+    async (client) => withAppliedColorScheme(client, colorScheme, async () => {
       const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage });
       const outPath = await resolveOutPath(parsed);
       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/measure/snapshot.ts

@@ -250,6 +250,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
   const pixels = options.pixels ?? false;
   const state = options.state ?? [];
   const viewport = options.viewport ?? null;
+  const colorScheme = options.colorScheme;
   // Apply the shared artifact-string cap once at the source. URL contents
   // otherwise survive unchanged in meta.json, the result, and collector context.
   const url = options.url ? sanitizeString(options.url) : null;
@@ -483,6 +484,7 @@ export async function captureSnapshotSubstrate(options: CaptureSnapshotOptions):
       captureUnsettled,
       pixels,
       states: state.map((spec) => sanitizeString(spec)),
+      ...(colorScheme ? { colorScheme } : {}),
       unstableRegionCount: unstableRegions.length,
       ...(freezeAnimations ? { animationsRestored: animationsRestored ?? false } : {}),
       // #8: the browser-wide `Animation.setPlaybackRate({playbackRate:0})`

package/src/cdp/measure/types.ts

@@ -53,6 +53,8 @@ export interface CaptureSnapshotOptions {
   /** `--state <state[:selector]>` (repeatable); default `[]`. */
   readonly state?: readonly string[];
   readonly viewport?: string | null;
+  /** Transient `prefers-color-scheme` media override used while capturing. */
+  readonly colorScheme?: 'dark' | 'light';
   /**
    * Poll interval for the settledness loop; default {@link DEFAULT_POLL_INTERVAL_MS}
    * (100ms). Not part of the CLI surface — a test-only override so the
@@ -109,6 +111,8 @@ export interface SnapshotMeta extends SnapMeta {
   readonly captureUnsettled: boolean;
   readonly pixels: boolean;
   readonly states: readonly string[];
+  /** Present only when this snapshot applied a transient color-scheme override. */
+  readonly colorScheme?: 'dark' | 'light';
   readonly unstableRegionCount: number;
   /** Present only when `freezeAnimations` is true — whether every animation `freezeAnimationsBeforeCapture` paused was confirmed resumed to its pre-freeze `playState` (I-6). `false` means restoration could not be guaranteed (origin capture failed, or the restore call itself threw) — never omitted to imply a clean restore. */
   readonly animationsRestored?: boolean;

package/src/cdp/types.ts

@@ -38,6 +38,8 @@ export interface ParsedArgs {
   into?: string;
   noScreenshot?: boolean;
   viewport?: string;
+  /** `page shot|measure snap --color-scheme dark|light` — transient media override. */
+  colorScheme?: string;
   fullPage?: boolean;
   help?: boolean;
   /** `--all` — boolean scope-widener (per-leaf semantics). */