@ultimat3/scraping 17.0.0 → 18.0.0

package/README.md

@@ -93,6 +93,7 @@ gate, offline included.
 | `page.query(selector)` | `ElementSnapshot[]` — the same matches PLUS `visible`, `enabled`, and the layout `box`/`hitTarget` a driver with a layout engine can answer. The read for a decision ABOUT an element |
 | `page.frame(nameOrSelector)` | a `ScrapeFrame`, re-resolved on every call through it |
 | `page.offline(enabled)` | cuts the BROWSER's network, or restores it |
+| `page.colorScheme(scheme)` | what the browser reports as the user's OS colour preference — `'light'`, `'dark'`, or `'no-preference'` to CLEAR the override |
 
 `query()` exists because there is exactly one definition of "visible" in this framework and it is
 the port's. A caller that had to compute its own wrote
@@ -111,6 +112,31 @@ NAVIGATE a frame: a recorded frame is one static document, so a click inside one
 browser's own requests, so a driver that quietly answered "done" would let "a like taken offline is
 queued" pass against an app that was online for the whole test.
 
+**`page.colorScheme()` sets the INPUT to a theme decision, never its outcome.** An attribute on the
+document — `data-theme`, `class="dark"` — is the outcome, and the component owns it: one that
+resolves `'system'` itself overwrites or deletes the attribute on mount, so a harness that set it is
+silently overruled. Measured on `examples/dummy`, `As of 2026-08`: `x shot --island` photographed
+every state in both themes and the two files came back byte-identical, same md5, from two addresses
+that really did serve different documents. Emulating the preference is what reaches a component that
+decides for itself; set the attribute as well for one that reads a theme it does not own.
+
+**`'no-preference'` CLEARS the override, and is not a third value.** CDP treats an explicit
+`prefers-color-scheme: no-preference` as an override and an EMPTY feature list as a reset, so that
+is what this sends. Measured on Chrome 150 headless, `As of 2026-08`: after either one,
+`(prefers-color-scheme: dark)` is false and `(prefers-color-scheme: light)` is true — the same
+answers an untouched page gives. They diverge on a browser that has a real preference, where the
+override forces the light answer and the reset gives the machine's own back, which is what this
+value promises. (`no-preference` left the `prefers-color-scheme` query itself in 2020, so nothing
+matches it in any of those readings.)
+
+Accepted and RECORDED on the offline drivers rather than refused, which is the opposite of
+`offline()` — and the line between them is which side of a capture the verb is on. An offline
+*assertion* is reachable on a driver that answers content, so a resolved `setOfflineMode` would let
+it pass against an app that never went offline; a colour preference has no such assertion, and the
+only thing it could be wrong about is a picture. So the offline drivers answer **different
+deterministic bytes per scheme**, exactly as they already do per `clip` — a fake returning one
+constant for both themes is precisely what let the defect above ship.
+
 ## What the page reports back, and the one thing a picture cannot say
 
 Three bounded rings, read off `ScrapePage`. Bounded because a ten-thousand-page run that kept

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "17.0.0",
+  "version": "18.0.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
   "license": "MIT",
   "type": "module",
@@ -23,16 +23,16 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "17.0.0",
-    "@ultimat3/jobs": "17.0.0",
-    "@ultimat3/schema": "17.0.0",
-    "@ultimat3/storage": "17.0.0"
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/jobs": "18.0.0",
+    "@ultimat3/schema": "18.0.0",
+    "@ultimat3/storage": "18.0.0"
   }
 }

package/src/cdp-fake.ts

@@ -9,6 +9,7 @@
 // Precedent: `packages/storage/src/driver-s3-fixture.ts` ships the same way.
 
 import type { CdpBrowserLike, CdpFrameLike, CdpLauncherLike, CdpPageLike } from './cdp-port';
+import { COLOR_SCHEME_FEATURE } from './color-scheme';
 import { queryHtml } from './html-query';
 import type { ElementSnapshot, ScrapeCookie } from './target';
 
@@ -70,6 +71,12 @@ export interface FakeCdpBrowser extends CdpBrowserLike {
   readonly closed: boolean;
   /** What `page.setOfflineMode()` last set, so a test asserts on the CONDITION, not on a call. */
   readonly offline: boolean;
+  /**
+   * What `page.emulateMediaFeatures()` last set `prefers-color-scheme` to, for `offline`'s reason
+   * — the condition the page is now in, never the fact that a method was called. `null` until
+   * something sets one, which is the launcher's own default and not a value this fake invents.
+   */
+  readonly colorScheme: string | null;
 }
 
 /** A layout box every element gets, so the CDP path exercises the fields the fake target lacks. */
@@ -113,6 +120,7 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
   let html = init.html;
   let closed = false;
   let offline = false;
+  let colorScheme: string | null = null;
   const covered = new Set(init.covered ?? []);
   const storage: Record<string, string> = { ...init.storage };
   let cookies: readonly ScrapeCookie[] = init.cookies ?? [];
@@ -202,6 +210,20 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
       offline = enabled;
       return Promise.resolve();
     },
+    // CDP's own two rules, both of them. An EMPTY list is a RESET — measured on Chrome 150, after
+    // `emulateMediaFeatures([])` the page answers exactly what an untouched one does — so it must
+    // clear here rather than be ignored, or `'no-preference'` records the previous scheme forever.
+    // And a non-empty list is read by NAME, never `features[0].value`: the port's shape is a list,
+    // and a caller setting `prefers-reduced-motion` beside the scheme must not overwrite it.
+    emulateMediaFeatures: (features: readonly { name: string; value: string }[]) => {
+      if (features.length === 0) {
+        colorScheme = null;
+        return Promise.resolve();
+      }
+      const found = features.find((feature) => feature.name === COLOR_SCHEME_FEATURE);
+      if (found !== undefined) colorScheme = found.value;
+      return Promise.resolve();
+    },
     on: (event: string, handler: (payload: unknown) => void) => {
       const listeners = handlers.get(event) ?? [];
       listeners.push(handler);
@@ -250,6 +272,9 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
     get offline(): boolean {
       return offline;
     },
+    get colorScheme(): string | null {
+      return colorScheme;
+    },
   };
 }
 

package/src/cdp-port.ts

@@ -69,6 +69,22 @@ export interface CdpPageLike {
    * a type error for a capability the port cannot make them have.
    */
   setOfflineMode?(enabled: boolean): Promise<void>;
+  /**
+   * The browser's own media features — `Emulation.setEmulatedMedia` under CDP. `prefers-color-scheme`
+   * is the one this package sets; the array shape is the library's and is restated, not narrowed,
+   * because this file is the shape of somebody ELSE's object.
+   *
+   * OPTIONAL, read defensively, for `setOfflineMode`'s reason: a provider SDK or a launcher that
+   * predates the method must still satisfy the port. It does not go unwired by being optional —
+   * `cdp-target.ts` refuses BY NAME with `X_NOT_IMPLEMENTED` and a fix when a launcher lacks it.
+   *
+   * `name` stays a bare `string`. A union of the features this package sets would be this file
+   * naming somebody else's vocabulary, and a launcher accepting more would then fail to satisfy
+   * the port for no reason — the argument `on(event: string, …)` already makes.
+   */
+  emulateMediaFeatures?(
+    features: readonly { readonly name: string; readonly value: string }[],
+  ): Promise<void>;
   /**
    * `event` stays a bare `string` — a union of the four names this package subscribes to would be
    * this file naming somebody else's event vocabulary, which is the thing it exists not to do, and

package/src/cdp-target.ts

@@ -8,6 +8,7 @@ import { browserRecord } from './browser-record';
 import type { CdpBrowserLike, CdpFrameLike, CdpPageLike, CdpRequestLike } from './cdp-port';
 import { clearExpression, parseSnapshots, snapshotExpression } from './cdp-snapshot';
 import type { ScrapeClock } from './clock';
+import { type ColorScheme, colorSchemeFeatures } from './color-scheme';
 import { browserUnreachable, pageCrashed, scrapeNotImplemented } from './error-throws';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict, refusalEntry } from './intercept';
@@ -361,6 +362,23 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         }
         await source.setOfflineMode(enabled);
       }),
+    setColorScheme: (scheme: ColorScheme): Promise<void> =>
+      guard('setColorScheme', async () => {
+        // `CdpPageLike` already declares the member optional, so it is READ, never re-declared in
+        // a local cast: a second copy of somebody else's shape is a copy that can drift from the
+        // seam it is standing in for (axiom 2). `setOfflineMode` above still casts and is the
+        // older spelling.
+        const emulate = init.page.emulateMediaFeatures;
+        if (typeof emulate !== 'function') {
+          throw scrapeNotImplemented(
+            'setColorScheme() on a CDP page with no emulateMediaFeatures() method',
+            'upgrade the launcher to a puppeteer-core that exposes page.emulateMediaFeatures(), or have the page under test set its own theme',
+          );
+        }
+        // `.call`, because the member is read off the object: an unbound method loses `this` and
+        // puppeteer's own `Page` needs it.
+        await emulate.call(init.page, colorSchemeFeatures(scheme));
+      }),
     screenshot: (options: CaptureOptions) =>
       guard('screenshot', async () => {
         // `fullPage` is OMITTED when a clip is given rather than sent as `false`: the two are

package/src/color-scheme.ts

@@ -0,0 +1,49 @@
+// The OS-level colour preference a page is shown, and the CDP media feature that carries it.
+//
+// Its own module for `capture-clip.ts`'s reason: the vocabulary belongs to EVERY driver
+// identically, and `target.ts` is a port declaration, which is not a place a decision lives.
+
+/**
+ * What a browser is told the user prefers — the INPUT to a theme decision, never its outcome.
+ *
+ * Setting `data-theme` on the document models the outcome, and the component owns that: a
+ * component that resolves `'system'` itself deletes or overwrites the attribute on mount, so a
+ * harness that set it is silently overruled and both themes converge on one picture. Measured on
+ * `examples/dummy`'s settings island (issue #338): `<state>-light.png` and `<state>-dark.png` came
+ * back byte-identical, same md5, from two addresses that really did serve different documents.
+ *
+ * The set is closed at THREE. `'light'` and `'dark'` are CSS's own values; `'no-preference'` is
+ * this vocabulary's way of saying **clear the override**, and it earns its place because without
+ * it a preference, once set, is permanent for the session.
+ *
+ * It is a CLEAR and not a value, and the difference is measured. CDP's `Emulation.setEmulatedMedia`
+ * treats an explicit `prefers-color-scheme: no-preference` as an OVERRIDE and an EMPTY feature list
+ * as a reset, so `colorSchemeFeatures` sends the empty list. On Chrome 150 headless the two are
+ * observationally identical — after either, `(prefers-color-scheme: dark)` is false,
+ * `(prefers-color-scheme: light)` is true, and `(prefers-color-scheme: no-preference)` is false,
+ * which is also what an untouched page answers. They diverge on a browser that HAS a real
+ * preference: the override forces the light-equivalent answer, while the reset gives the machine's
+ * own back — and "the launcher's default" is what this value promises.
+ *
+ * `no-preference` was dropped from the `prefers-color-scheme` media query in 2020, which is why
+ * the third row above is false in every one of those readings. It is a control word here, never a
+ * query a stylesheet can match.
+ */
+export const COLOR_SCHEMES = ['light', 'dark', 'no-preference'] as const;
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+
+/** CSS's own feature name, and CDP's. One constant, because two spellings is a silent no-op. */
+export const COLOR_SCHEME_FEATURE = 'prefers-color-scheme';
+
+export function isColorScheme(value: unknown): value is ColorScheme {
+  return typeof value === 'string' && COLOR_SCHEMES.includes(value as ColorScheme);
+}
+
+/**
+ * The CDP feature list for one scheme — the ONE place the clear is spelled, so a driver and a fake
+ * cannot disagree about what `'no-preference'` means.
+ */
+export const colorSchemeFeatures = (
+  scheme: ColorScheme,
+): readonly { readonly name: string; readonly value: string }[] =>
+  scheme === 'no-preference' ? [] : [{ name: COLOR_SCHEME_FEATURE, value: scheme }];

package/src/html-target.ts

@@ -7,6 +7,7 @@
 
 import type { CaptureClip } from './capture-clip';
 import type { ScrapeClock } from './clock';
+import type { ColorScheme } from './color-scheme';
 import {
   browserUnreachable,
   downloadTimeout,
@@ -38,15 +39,27 @@ import type {
 const FAKE_PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
 /**
- * A clipped capture answers DIFFERENT deterministic bytes, one picture per rectangle. CI has no
- * Chrome, so the offline drivers are the only place a crop can be proved at all: a fake that
- * answered the same eight bytes whatever the rectangle would let a driver that silently drops the
- * clip pass every test there is. Unclipped bytes are unchanged, byte for byte.
+ * A capture answers DIFFERENT deterministic bytes for every framing fact that was set — one
+ * picture per rectangle, one per colour preference. CI has no Chrome, so the offline drivers are
+ * the only place a framing knob can be proved at all: a fake that answered the same eight bytes
+ * whatever the rectangle would let a driver that silently drops the clip pass every test there is.
+ *
+ * The colour scheme joined that rule on 2026-08-26, and it is the same defect one axis over. `x
+ * shot --island` photographed every state twice and delivered the second picture as a byte-for-
+ * byte COPY of the first (issue #338), and no test could see it because this fake answered one
+ * constant for both themes.
+ *
+ * Bytes with NO framing fact set are unchanged, and clip-only bytes are unchanged too — the notes
+ * append in a fixed order, so every digest asserted before this existed still holds.
  */
-const clippedPng = (clip: CaptureClip): Uint8Array => {
-  const suffix = new TextEncoder().encode(
-    ` clip ${String(clip.x)},${String(clip.y)},${String(clip.width)},${String(clip.height)}`,
-  );
+const framedPng = (clip: CaptureClip | undefined, scheme: ColorScheme | null): Uint8Array => {
+  const notes =
+    (clip === undefined
+      ? ''
+      : ` clip ${String(clip.x)},${String(clip.y)},${String(clip.width)},${String(clip.height)}`) +
+    (scheme === null ? '' : ` scheme ${scheme}`);
+  if (notes === '') return FAKE_PNG;
+  const suffix = new TextEncoder().encode(notes);
   const out = new Uint8Array(FAKE_PNG.length + suffix.length);
   out.set(FAKE_PNG);
   out.set(suffix, FAKE_PNG.length);
@@ -127,6 +140,9 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
   const frameOverlays = new Map<string, Map<string, string>>();
   let page: PageRecording = init.start ?? EMPTY;
   let armed: string | undefined;
+  // `null` and not `'no-preference'`: nothing set one, which is the launcher's own default and not
+  // a value this driver invents — and it is what keeps an unframed picture's bytes unchanged.
+  let colorScheme: ColorScheme | null = null;
   let closed = false;
   let session: SessionSnapshot = init.session ?? {
     ...EMPTY_SESSION,
@@ -333,8 +349,34 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
         'run this assertion on localBrowser()/remoteBrowser(), whose setOfflineMode() reaches a real browser — an offline driver has no network to cut, so it cannot prove an offline behaviour',
       );
     },
+    /**
+     * ACCEPTED and recorded, where `setOfflineMode` refuses — and the line between them is which
+     * side of a capture the verb is on, not whether this driver has a browser.
+     *
+     * `setOfflineMode` is refused because an offline ASSERTION is reachable here: this driver
+     * answers content, so `expect(page).toShow('queued')` would go green against an app that was
+     * online the whole time. A colour preference has no such assertion to pass. Nothing here
+     * evaluates CSS, and the only thing a preference could be wrong ABOUT is a picture — which on
+     * this driver is `FAKE_PNG`, a constant that claims nothing about a theme, exactly as `pdf()`
+     * answers `FAKE_PDF` rather than refusing.
+     *
+     * Refusing would cost the capability its unit test. `x shot --island` is proved end to end on
+     * a machine with no Chrome by driving this driver, so a refusal here makes the command
+     * untestable offline — and the picture it would be protecting does not exist.
+     *
+     * Observable through the PICTURE, which is the only place it could ever be wrong: `framedPng`
+     * answers different deterministic bytes per scheme, exactly as it already does per clip, so a
+     * driver that silently dropped the preference fails a test rather than passing every one.
+     */
+    setColorScheme(scheme: ColorScheme): Promise<void> {
+      // `'no-preference'` is a CLEAR on the real driver, so it is a clear here — and the picture
+      // goes back to the unframed bytes, which is the same fact stated in the one place a fake can
+      // state it.
+      colorScheme = scheme === 'no-preference' ? null : scheme;
+      return Promise.resolve();
+    },
     screenshot: (options: CaptureOptions): Promise<Uint8Array> =>
-      Promise.resolve(options.clip === undefined ? FAKE_PNG : clippedPng(options.clip)),
+      Promise.resolve(framedPng(options.clip, colorScheme)),
     pdf: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PDF),
     cookies: (): Promise<readonly ScrapeCookie[]> => Promise.resolve(session.cookies),
     session: (): Promise<SessionSnapshot> => Promise.resolve(session),

package/src/index.ts

@@ -34,6 +34,8 @@ export type { CdpTargetInit } from './cdp-target';
 export { CDP_DRIVER, cdpTarget } from './cdp-target';
 export type { Deadline, ScrapeClock, TestScrapeClock } from './clock';
 export { deadline, systemScrapeClock, testClock, throwIfAborted } from './clock';
+export type { ColorScheme } from './color-scheme';
+export { COLOR_SCHEME_FEATURE, COLOR_SCHEMES, isColorScheme } from './color-scheme';
 export {
   cookieDomainMatches,
   cookieHeaderFor,

package/src/page-over-target.ts

@@ -10,6 +10,7 @@ import { awaitActionable } from './actionability';
 import { assertCaptureFraming } from './capture-clip';
 import type { ScrapeClock } from './clock';
 import { deadline } from './clock';
+import type { ColorScheme } from './color-scheme';
 import { hostBlocked, secretExposed, selectorMissing } from './error-throws';
 import { hostDecision } from './hosts';
 import type {
@@ -243,6 +244,11 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     async offline(enabled: boolean): Promise<void> {
       await target.setOfflineMode(enabled);
     },
+    // `async`, for `offline()`'s reason: a driver that throws synchronously from a promise-typed
+    // method would escape the caller's `.catch()`.
+    async colorScheme(scheme: ColorScheme): Promise<void> {
+      await target.setColorScheme(scheme);
+    },
     cookies: (): Promise<readonly ScrapeCookie[]> => target.cookies(),
     session: () => target.session(),
     // Redacted BY VALUE on the way out, the same pass `html()` makes. A console line and a request

package/src/page.ts

@@ -10,6 +10,7 @@
 import type { Secret } from '@ultimat3/core';
 import type { ActionabilityState } from './actionability';
 import type { CaptureFraming } from './capture-clip';
+import type { ColorScheme } from './color-scheme';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
 import type { SessionSnapshot } from './session-state';
 import type { ElementSnapshot, ScrapeCookie, ScrapeDownloadFile } from './target';
@@ -109,6 +110,21 @@ export interface ScrapePage extends ScrapeFrame {
    * "done" would let an offline assertion pass against an app that never went offline.
    */
   offline(enabled: boolean): Promise<void>;
+  /**
+   * Tell the browser what the user's OS colour preference is, so a component that resolves its own
+   * theme resolves to this one. `'no-preference'` CLEARS the override and gives the browser's own
+   * answer back — it is not a third value a stylesheet can match.
+   *
+   * The INPUT, never the outcome: an attribute on the document is the outcome of a theme decision
+   * and the component owns that — one honouring `'system'` overwrites or deletes it on mount, and
+   * the picture then shows the theme the component chose rather than the one that was asked for.
+   *
+   * ACCEPTED on every driver, unlike `offline()`: the offline drivers evaluate no CSS, but they
+   * answer different deterministic bytes per scheme, so the one thing a preference could be wrong
+   * about is still under test. `X_NOT_IMPLEMENTED` is reserved for a LAUNCHER that lacks the
+   * method, which is a fact about the build rather than about the driver.
+   */
+  colorScheme(scheme: ColorScheme): Promise<void>;
   /**
    * The handoff, made explicit: what the HTTP leg will send, as a value an author can inspect and
    * a fixture can assert on. `http` uses it automatically — this is for seeing what carried over.

package/src/target.ts

@@ -4,6 +4,7 @@
 // fixture replayer and the fake alike.
 
 import type { CaptureFraming } from './capture-clip';
+import type { ColorScheme } from './color-scheme';
 import type { ConsoleRing, NetworkRing, PageErrorRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 
@@ -141,6 +142,28 @@ export interface ScrapeTarget {
    * green against an app that was online the whole time.
    */
   setOfflineMode(enabled: boolean): Promise<void>;
+  /**
+   * What the browser reports as the user's OS colour preference — the INPUT to a theme decision.
+   * `'no-preference'` CLEARS the override rather than setting one (`color-scheme.ts`).
+   *
+   * The INPUT and never the outcome. Setting `data-theme` on the document models the outcome, and
+   * the component owns that: one that resolves `'system'` itself overwrites or deletes the
+   * attribute on mount, so a harness that set it is silently overruled and every theme converges
+   * on one picture — measured, and byte-identical, in issue #338.
+   *
+   * REQUIRED here where `CdpPageLike.emulateMediaFeatures` is optional, for `setOfflineMode`'s
+   * reason: the asymmetry is the enforcement, and a driver author gets a type error naming this
+   * member rather than a silent no-op. A launcher without the method is `X_NOT_IMPLEMENTED`.
+   *
+   * A DRIVER WITH NO CSS ENGINE ACCEPTS IT, which is the one place this parts company with
+   * `setOfflineMode`, and the line between them is which side of a capture the verb is on. An
+   * offline ASSERTION is reachable on a driver that answers content, so a resolved
+   * `setOfflineMode` would let it pass against an app that never went offline. A colour preference
+   * has no such assertion: the only thing it could be wrong about is a picture, and the offline
+   * drivers answer different deterministic bytes per scheme — exactly as they do per `clip` —
+   * so a driver that dropped the preference fails a test rather than passing every one.
+   */
+  setColorScheme(scheme: ColorScheme): Promise<void>;
   screenshot(options: CaptureOptions): Promise<Uint8Array>;
   pdf(options: CaptureOptions): Promise<Uint8Array>;
   cookies(): Promise<readonly ScrapeCookie[]>;