@ultimat3/scraping 16.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": "16.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": "16.0.0",
-    "@ultimat3/jobs": "16.0.0",
-    "@ultimat3/schema": "16.0.0",
-    "@ultimat3/storage": "16.0.0"
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/jobs": "18.0.0",
+    "@ultimat3/schema": "18.0.0",
+    "@ultimat3/storage": "18.0.0"
   }
 }

package/src/actionability.ts

@@ -4,6 +4,7 @@
 // `waitForSelector('#aceptar:not([disabled])')`, which is this rule, spelled once, by hand, at
 // one call site out of forty.
 
+import { finiteCount } from '@ultimat3/core';
 import type { ScrapeClock } from './clock';
 import { deadline } from './clock';
 import { notActionable, selectorMissing } from './error-throws';
@@ -85,8 +86,12 @@ export interface ActionabilityWait {
  * a scraper failure take an afternoon.
  */
 export async function awaitActionable(wait: ActionabilityWait): Promise<ElementSnapshot> {
-  const budget = deadline(wait.clock, wait.timeoutMs);
-  const pollMs = wait.pollMs ?? DEFAULT_POLL_MS;
+  const budget = deadline(wait.clock, wait.timeoutMs, 'page.waitFor');
+  // At least 1ms, and the floor is the point: `Math.min(0, remainingMs())` is 0, `clock.sleep(0)`
+  // returns on the next turn, and the poll is then one full round trip to the browser per
+  // event-loop turn for the whole budget. `NaN` is the same loop by a different route —
+  // `Math.min(NaN, x)` is `NaN` and `setTimeout(fn, NaN)` is `setTimeout(fn, 0)`.
+  const pollMs = finiteCount('page.waitFor', 'pollMs', wait.pollMs ?? DEFAULT_POLL_MS, 1);
   let previous: ElementSnapshot | undefined;
   let lastProblem: string | undefined;
   let everSeen = false;

package/src/auth.ts

@@ -18,6 +18,7 @@
 // is written into the session record so the NEXT attempt fails before reaching the login form.
 
 import type { Logger } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 import type { ScrapeClock } from './clock';
 import { authFailed, promptUnanswered, sessionExpired } from './error-throws';
 import type { ScrapePage } from './page';
@@ -121,8 +122,17 @@ export async function restorableSession<I>(
   if (plan.auth?.reuse === false) return undefined;
   const maxAge = plan.auth?.maxAge;
   if (maxAge !== undefined) {
+    // Screened, because `age > NaN` is false and false here means RESTORED: a `NaN` maxAge hands
+    // back a session of any age, with no re-login and nothing in the report. `0` is legal — it
+    // means "restore nothing stored before now" — so the floor stays there.
+    const limit = finiteCount('the scrape auth', 'maxAge', maxAge);
     const age = plan.clock.now().getTime() - new Date(found.savedAt).getTime();
-    if (age > maxAge) return undefined;
+    // `!(age <= limit)` and not `age > limit`, which is the same test for every finite age and the
+    // OPPOSITE one for a `NaN`. `savedAt` is data, not configuration: it comes back off a bucket
+    // and `parseSessionState` only asks that it is a string, so an edited or half-written record
+    // produces a `NaN` age against a perfectly good `maxAge`. Failing closed costs one re-login;
+    // failing open acts as somebody else, indefinitely.
+    if (!(age <= limit)) return undefined;
   }
   plan.logger.debug('scrape.session.restored', sessionDigest(found));
   return found;

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/clock.ts

@@ -5,6 +5,7 @@
 // `clock-discipline.test.ts` fails the build if a second file reaches for a timer directly.
 
 import type { Clock } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 
 export interface ScrapeClock extends Clock {
   /**
@@ -90,8 +91,14 @@ export interface Deadline {
   expired(): boolean;
 }
 
-export function deadline(clock: Clock, totalMs: number): Deadline {
+export function deadline(clock: Clock, totalMs: number, subject = 'a scrape wait'): Deadline {
+  // Screened HERE because this is the one constructor of a budget, and every `for (;;)` in this
+  // package asks `expired()` to leave it. `Math.max(0, NaN - elapsed)` is `NaN` and `NaN <= 0` is
+  // false, so a budget that is not a number never expires: the loop in `awaitActionable` and the
+  // one in `page-over-target.ts`'s `frame()` both become unbounded, re-reading a live browser once
+  // per `Math.min(pollMs, NaN)` — which is `NaN`, which `setTimeout` reads as 0.
+  const budgetMs = finiteCount(subject, 'timeoutMs', totalMs);
   const startedAt = clock.monotonic();
-  const remainingMs = (): number => Math.max(0, totalMs - (clock.monotonic() - startedAt));
-  return { totalMs, remainingMs, expired: () => remainingMs() <= 0 };
+  const remainingMs = (): number => Math.max(0, budgetMs - (clock.monotonic() - startedAt));
+  return { totalMs: budgetMs, remainingMs, expired: () => remainingMs() <= 0 };
 }

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/driver-fake.ts

@@ -5,6 +5,7 @@
 // It covers BOTH legs. `fakeBrowser({ pages, http })` replays the browser walk and the JSON
 // endpoints behind it from one declaration, so a hybrid scrape is tested the way it runs.
 
+import { finiteCount } from '@ultimat3/core';
 import type { ScrapeClock } from './clock';
 import { systemScrapeClock } from './clock';
 import type { ScrapeDriver, ScrapeSession, SessionInit } from './driver';
@@ -113,7 +114,10 @@ export function fakePage(dom: string, options: FakePageOptions = {}): ScrapePage
   return pageOverTarget(target, {
     clock,
     allowHosts,
-    defaultTimeoutMs: options.timeoutMs ?? 1_000,
+    // The default budget for every wait AND every navigation on this page, so the floor is 1: a
+    // session default of 0 is already out of time everywhere, which a per-call `{ timeout: 0 }` —
+    // "is it there right now" — is not. Non-finite is the loop that never leaves.
+    defaultTimeoutMs: finiteCount('fakePage', 'timeoutMs', options.timeoutMs ?? 1_000, 1),
     ...options.context,
   });
 }

package/src/expect.ts

@@ -3,6 +3,7 @@
 // where the data went. `expect` turns that into a red run: a yield under `minRows`, or under
 // `maxDrop` of what this scrape normally returns, throws.
 
+import { finiteCount, finiteOption } from '@ultimat3/core';
 import { yieldCollapsed } from './error-throws';
 import type { ScrapeError } from './errors';
 
@@ -61,7 +62,23 @@ export interface YieldCheck {
  * fifty histories without a queue, a browser or a clock.
  */
 export function yieldProblem(check: YieldCheck): ScrapeError | undefined {
-  const { minRows, maxDrop } = check.expect;
+  // Screened where the rule is, because this is the alarm and both directions are silent. A `NaN`
+  // minRows makes `rows < minRows` false for every yield, so the floor never fires and the scrape
+  // is green on zero rows forever — the exact failure this file exists to prevent. A `NaN` maxDrop
+  // makes `rows >= baseline * (1 - NaN)` false for every yield, which fires the alarm on every run
+  // instead, and an alarm that always fires is an alarm somebody turns off.
+  //
+  // `minRows: 0` is legal and stays legal: this file asks an author whose answer is legitimately
+  // sometimes zero to declare exactly that. `maxDrop` is a FRACTION of a median, so `finiteOption`
+  // and not `finiteCount` — `0.5` is the documented value.
+  const minRows =
+    check.expect.minRows === undefined
+      ? undefined
+      : finiteCount('the scrape expect', 'minRows', check.expect.minRows);
+  const maxDrop =
+    check.expect.maxDrop === undefined
+      ? undefined
+      : finiteOption('the scrape expect', 'maxDrop', check.expect.maxDrop);
   if (minRows !== undefined && check.rows < minRows) {
     return yieldCollapsed({ scrape: check.scrape, rows: check.rows, reason: 'min-rows', minRows });
   }
@@ -101,7 +118,15 @@ export async function guardYield(input: YieldGuardInput): Promise<void> {
   // `maxDrop` needs `MIN_BASELINE_RUNS` runs after it is declared before it can fire — a delay,
   // not a hole. `expect.test.ts` pins both halves.
   if (input.expect === undefined) return;
-  const window = input.expect.window ?? DEFAULT_YIELD_WINDOW;
+  // At least 1: `[…].slice(-0)` is `slice(0)`, the WHOLE history, so a zero window is the largest
+  // baseline rather than no baseline — and the number is handed to an app's own `recent()`, where
+  // it is usually a SQL `limit`.
+  const window = finiteCount(
+    'the scrape expect',
+    'window',
+    input.expect.window ?? DEFAULT_YIELD_WINDOW,
+    1,
+  );
   const history =
     input.history === undefined ? [] : await input.history.recent(input.scrape, window);
   const problem = yieldProblem({

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/http.ts

@@ -10,7 +10,7 @@
 // guarantee the page vocabulary makes — and a different exit IP mid-session is exactly what
 // anti-bot systems look for.
 
-import { readWithinLimit } from '@ultimat3/core';
+import { finiteCount, readWithinLimit } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse } from '@ultimat3/schema';
 import type { ScrapeClock } from './clock';
@@ -172,6 +172,29 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
   const call: ScrapeFetch = init.fetch ?? fetch;
   return {
     async request(url: string, request: HttpRequestInit = {}): Promise<ScrapeResponse> {
+      // Screened FIRST — before the activity touch, before the robots read this method performs
+      // and before a byte leaves. `AbortSignal.timeout(NaN)` THROWS, and it throws a bare
+      // `TypeError` ("Value NaN is outside the range [0, 9007199254740991]"), which is the one
+      // thing the deadline below exists to prevent: an unclassified platform error reaching a
+      // job's retry classifier instead of this package's own `X_SCRAPE_TIMEOUT`. And the cap is
+      // the only thing between a hostile stream and the worker's heap, so `readWithinLimit`'s own
+      // refusal is too late: it arrives once the request — a POST included — has been performed.
+      //
+      // Both floors are 1. A zero deadline aborts on the tick it is armed and a zero cap puts
+      // every response over, so either one makes every request on this leg fail; neither is a
+      // caller declining a feature the way `watchdog.graceMs: 0` is.
+      const timeoutMs = finiteCount(
+        'http.request',
+        'timeout',
+        request.timeout ?? init.timeoutMs,
+        1,
+      );
+      const maxBytes = finiteCount(
+        'http.request',
+        'maxBytes',
+        request.maxBytes ?? DEFAULT_HTTP_MAX_BYTES,
+        1,
+      );
       init.onActivity?.();
       if (interceptVerdict(url, 'fetch', init.rules) !== 'allow') {
         throw hostBlocked(url, init.rules.allowHosts);
@@ -180,7 +203,6 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
       await init.pace?.(init.signal);
       const session = await init.session();
       const cookies = cookieHeaderFor(session.cookies, url);
-      const timeoutMs = request.timeout ?? init.timeoutMs;
       // `AbortSignal.timeout` and NOT `clock.sleep`: this is a deadline handed to the platform's
       // own fetch, not a wait this package performs — and under a test clock a slept deadline
       // would fire on the microtask after it was armed, cancelling every request instantly.
@@ -210,7 +232,6 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
         // Counted as it arrives rather than `.text()`, which materialises first and checks never:
         // a 30s stream at 50MB/s is a 1.5GB allocation the worker does not get back, and it takes
         // every other job on that worker with it. The same read `robots-fetch.ts` performs.
-        const maxBytes = request.maxBytes ?? DEFAULT_HTTP_MAX_BYTES;
         const capped = await readWithinLimit(response.body, maxBytes);
         if ('over' in capped) throw bodyTooLarge(url, capped.over, maxBytes);
         const body = new TextDecoder().decode(capped.bytes);

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/robots-fetch.ts

@@ -8,7 +8,7 @@
 // The exit is a RESOLVER, not a string: `scrape-run.ts` builds this gate as an argument to
 // `driver.open()`, and the proxy is a driver option the session only reports on the way back out.
 
-import { readWithinLimit } from '@ultimat3/core';
+import { finiteCount, readWithinLimit } from '@ultimat3/core';
 import type { ScrapeFetch } from './http';
 import type { RobotsFetch } from './robots';
 
@@ -56,11 +56,29 @@ export interface RobotsFetchInit {
  */
 export function robotsFetcher(init: RobotsFetchInit = {}): RobotsFetch {
   const call: ScrapeFetch = init.fetch ?? fetch;
-  const limit = init.maxBytes ?? DEFAULT_ROBOTS_MAX_BYTES;
+  // Both bounds are screened HERE, at construction, and both floors are 1 — because every way this
+  // read can fail is the same answer, `undefined`, which the gate reads as "no restrictions". A
+  // `NaN` deadline throws a bare `TypeError` out of `AbortSignal.timeout` (measured: "Value NaN is
+  // outside the range [0, 9007199254740991]") straight into the gate's own `.catch`, and a `NaN`
+  // cap makes `readWithinLimit` refuse after the request already left. A zero of either is the
+  // same outcome spelled deliberately: an expired deadline and a cap every file is over. Robots
+  // enforcement off, for the whole run, with nothing in the log.
+  const limit = finiteCount(
+    'robotsFetcher',
+    'maxBytes',
+    init.maxBytes ?? DEFAULT_ROBOTS_MAX_BYTES,
+    1,
+  );
+  const timeoutMs = finiteCount(
+    'robotsFetcher',
+    'timeoutMs',
+    init.timeoutMs ?? DEFAULT_ROBOTS_TIMEOUT_MS,
+    1,
+  );
   return async (robotsUrl: string): Promise<string | undefined> => {
     // Armed per read, not per gate: the gate is long-lived and reads once per origin, so a
     // deadline created alongside it would already have expired by the second origin.
-    const deadline = AbortSignal.timeout(init.timeoutMs ?? DEFAULT_ROBOTS_TIMEOUT_MS);
+    const deadline = AbortSignal.timeout(timeoutMs);
     const signal = init.signal === undefined ? deadline : AbortSignal.any([deadline, init.signal]);
     // Resolved here, at the read, because the session that owns the exit did not exist when this
     // fetcher was built. An empty string is not an exit and is dropped with the absent one.

package/src/scrape-run.ts

@@ -9,6 +9,7 @@
 // A step record saying "logged in" would be a checkpoint asserting something about a session that
 // may have expired an hour ago.
 
+import { finiteCount, finiteOption } from '@ultimat3/core';
 import type { JobRunArgs } from '@ultimat3/jobs';
 import { parse } from '@ultimat3/schema';
 import { createArtifactWriter } from './artifacts';
@@ -41,13 +42,23 @@ const orgOf = (ctx: unknown): string | undefined => {
   return typeof actor?.orgId === 'string' ? actor.orgId : undefined;
 };
 
-const toMillis = (value: string | number | undefined, fallback: number): number => {
+/**
+ * `'30s'` | `30_000` | absent, as milliseconds — screened under the name the DEFINITION uses.
+ *
+ * The number branch is the one that needs it: the string branch can only ever produce digits, and
+ * a number a definition declares is whatever the app computed. What it lands on is the reason the
+ * refusal is here rather than downstream — this one value becomes the robots read's deadline
+ * (where a non-finite one turns robots enforcement off silently, because every failure of that
+ * read answers "no restrictions"), the session's `timeoutMs`, and through it every actionability
+ * budget in the run, where `NaN <= 0` is false so the poll loop never leaves.
+ */
+const toMillis = (value: string | number | undefined, fallback: number, option: string): number => {
   if (value === undefined) return fallback;
-  if (typeof value === 'number') return value;
+  if (typeof value === 'number') return finiteCount('the scrape definition', option, value, 1);
   const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(value.trim());
   if (match === null) return fallback;
   const scale = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 }[match[2] ?? 'ms'] ?? 1;
-  return Number(match[1]) * scale;
+  return finiteCount('the scrape definition', option, Number(match[1]) * scale, 1);
 };
 
 export const DEFAULT_PAGE_TIMEOUT_MS = 30_000;
@@ -69,7 +80,14 @@ export async function runScrape<I, Row>(
   });
   const secrets = createSecretBag(definition.secrets ?? []);
   const rules = { allowHosts: definition.allowHosts, block: definition.block };
-  const pace = createPacer(definition.rate ?? DEFAULT_NAVIGATION_RATE, clock);
+  // Screened here as well as in `scrape()`, and the two are not one check written twice: that one
+  // refuses the DECLARATION and never sees a definition assembled by hand, which `runScrape` is
+  // exported to accept. `finiteOption` and not `finiteCount` — a rate of 0.5 is one navigation
+  // every two seconds, and `scrape()` owns the "greater than zero" half.
+  const pace = createPacer(
+    finiteOption('the scrape definition', 'rate', definition.rate ?? DEFAULT_NAVIGATION_RATE),
+    clock,
+  );
   const artifact = createArtifactWriter({
     storage: definition.artifacts?.storage,
     scrape: definition.name,
@@ -94,7 +112,7 @@ export async function runScrape<I, Row>(
   // Read BEFORE the browser opens: a refused credential must not reach a login form again, and
   // opening a session first would already have spent an identity on a run that cannot succeed.
   const restored = await restorableSession(plan);
-  const pageTimeoutMs = toMillis(definition.pageTimeout, DEFAULT_PAGE_TIMEOUT_MS);
+  const pageTimeoutMs = toMillis(definition.pageTimeout, DEFAULT_PAGE_TIMEOUT_MS, 'pageTimeout');
   // The exit the session dials, readable only AFTER `driver.open()` — the proxy is a driver
   // option and the gate below is an argument to `open()`, so the gate asks for it per read
   // instead of being handed a value that cannot exist yet. Every read happens during a

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[]>;

package/src/watchdog.ts

@@ -10,6 +10,7 @@
 // socket die, which is what turns an infinite await into a catchable `X_SCRAPE_WEDGED` — and a
 // graceful-quit CEILING on shutdown, past which the same kill runs.
 
+import { finiteCount } from '@ultimat3/core';
 import type { ScrapeClock } from './clock';
 import { watchdogStopped, wedged } from './error-throws';
 
@@ -49,8 +50,19 @@ export interface WedgeGuard {
 }
 
 export function createWedgeGuard(init: WedgeGuardInit): WedgeGuard {
-  const idleMs = init.idleMs ?? DEFAULT_IDLE_MS;
-  const graceMs = init.graceMs ?? DEFAULT_GRACE_MS;
+  // Screened before the watch loop starts, because both failures are silent in the expensive
+  // direction. `elapsed < NaN` is FALSE, so a `NaN` idleMs fires on the first 250ms poll and every
+  // run dies as `X_SCRAPE_WEDGED` against a browser that answered; `elapsed < Infinity` is always
+  // true, so the loop never fires and the guard is incident #1 with nothing armed. A `NaN` graceMs
+  // is `clock.sleep(NaN)`, which `setTimeout` reads as 0: `browser.close()` cannot win the race, so
+  // `kill()` runs instead — and on `remoteBrowser()`, where `process()` is `null`, that reaches
+  // nothing and the paid remote session survives the run.
+  //
+  // The floors differ because zero means two different things. `idleMs: 0` is "kill at the first
+  // poll", which is the NaN outcome spelled deliberately; `graceMs: 0` is "do not wait for the
+  // polite close", which is a policy a caller may hold.
+  const idleMs = finiteCount('the scrape watchdog', 'idleMs', init.idleMs ?? DEFAULT_IDLE_MS, 1);
+  const graceMs = finiteCount('the scrape watchdog', 'graceMs', init.graceMs ?? DEFAULT_GRACE_MS);
   const controller = new AbortController();
   let lastTouch = init.clock.monotonic();
   // TWO latches, not one. `stopped` ends the watch loop; `shuttingDown` guards the teardown. They