@ultimat3/scraping 13.0.0 → 14.0.0

package/src/html-target.ts

@@ -7,7 +7,13 @@
 
 import type { CaptureClip } from './capture-clip';
 import type { ScrapeClock } from './clock';
-import { browserUnreachable, downloadTimeout, fixtureMissing, fixtureStale } from './error-throws';
+import {
+  browserUnreachable,
+  downloadTimeout,
+  fixtureMissing,
+  fixtureStale,
+  scrapeNotImplemented,
+} from './error-throws';
 import { queryHtml } from './html-query';
 import { markupRequests } from './html-requests';
 import type { InterceptRules } from './intercept';
@@ -88,6 +94,20 @@ const keyOf = (selector: string, element: ElementSnapshot | undefined): string =
   return selector;
 };
 
+/**
+ * ONE browsing context: the page's document, or a frame's. A browser gives every context its own
+ * DOM and its own form state, so this target gives every one its own markup and its own overlay.
+ *
+ * It is the whole fix for the frame half. The frame target used to be `{ ...base }` with `query`
+ * overridden, so `type`, `clear` and `select` read the element out of the PARENT's markup and
+ * wrote into the PARENT's overlay — a value typed into an iframe'd login form then read back out
+ * of `page.values()`, and a `fill` seeded itself from the parent field's value.
+ */
+interface OfflineDocument {
+  html(): string;
+  readonly overlay: Map<string, string>;
+}
+
 export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
   const consoleRing = createRing<ConsoleLine>();
   const networkRing = createRing<NetworkEntry>();
@@ -98,6 +118,13 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
   // `driver-parity.test.ts` pins the divergence, beside the box/hit-target one it already carries.
   const pageErrorRing = createRing<PageError>();
   const overlay = new Map<string, string>();
+  /**
+   * One overlay per FRAME, held here rather than in the frame target, because `frames()` builds a
+   * fresh target on every call — `page.frame(name)` re-resolves per operation, by design — so an
+   * overlay owned by the target would be discarded between the `clear` and the `type` a single
+   * `fill` performs. Keyed by name and URL together: two frames may share either one alone.
+   */
+  const frameOverlays = new Map<string, Map<string, string>>();
   let page: PageRecording = init.start ?? EMPTY;
   let armed: string | undefined;
   let closed = false;
@@ -110,19 +137,57 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     if (closed) throw browserUnreachable(init.driver, 'the offline target is already closed');
   };
 
-  const withOverlay = (selector: string, elements: readonly ElementSnapshot[]): ElementSnapshot[] =>
+  const withOverlay = (
+    document: OfflineDocument,
+    selector: string,
+    elements: readonly ElementSnapshot[],
+  ): ElementSnapshot[] =>
     elements.map((element) => {
-      const typed = overlay.get(keyOf(selector, element));
+      const typed = document.overlay.get(keyOf(selector, element));
       return typed === undefined ? element : { ...element, value: typed };
     });
 
-  const query = async (selector: string): Promise<readonly ElementSnapshot[]> => {
+  const queryIn = async (
+    document: OfflineDocument,
+    selector: string,
+  ): Promise<readonly ElementSnapshot[]> => {
     live();
-    return withOverlay(selector, await queryHtml(page.html, selector));
+    return withOverlay(document, selector, await queryHtml(document.html(), selector));
+  };
+
+  const atIn = (
+    document: OfflineDocument,
+    selector: string,
+    index: number,
+  ): Promise<ElementSnapshot | undefined> =>
+    queryIn(document, selector).then((elements) => elements[index]);
+
+  /** Appends, exactly as typing does — the port's contract. `fill` is a `clear` and then this. */
+  const typeIn = async (
+    document: OfflineDocument,
+    selector: string,
+    text: string,
+  ): Promise<void> => {
+    const element = await atIn(document, selector, 0);
+    const key = keyOf(selector, element);
+    document.overlay.set(key, `${document.overlay.get(key) ?? element?.value ?? ''}${text}`);
   };
 
+  const setIn = async (
+    document: OfflineDocument,
+    selector: string,
+    value: string,
+  ): Promise<void> => {
+    document.overlay.set(keyOf(selector, await atIn(document, selector, 0)), value);
+  };
+
+  const pageDocument: OfflineDocument = { html: () => page.html, overlay };
+
+  const query = (selector: string): Promise<readonly ElementSnapshot[]> =>
+    queryIn(pageDocument, selector);
+
   const at = (selector: string, index: number): Promise<ElementSnapshot | undefined> =>
-    query(selector).then((elements) => elements[index]);
+    atIn(pageDocument, selector, index);
 
   /** Interception, offline: every request the markup would make, judged by the same rule. */
   const intercept = async (recording: PageRecording): Promise<void> => {
@@ -152,6 +217,9 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     }
     page = found;
     overlay.clear();
+    // A navigation is a new document tree, frames included: a value typed into the old page's
+    // frame must not answer a query on the new one's.
+    frameOverlays.clear();
     armed = undefined;
     networkRing.push({
       method: 'GET',
@@ -175,13 +243,46 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     await load(absolute);
   };
 
-  const frameTarget = (html: string, url: string): ScrapeTarget => ({
-    ...base,
-    url: () => url,
-    content: () => Promise.resolve(html),
-    query: async (selector) => withOverlay(selector, await queryHtml(html, selector)),
-    frames: () => Promise.resolve([]),
-  });
+  const overlayFor = (key: string): Map<string, string> => {
+    const found = frameOverlays.get(key);
+    if (found !== undefined) return found;
+    const created = new Map<string, string>();
+    frameOverlays.set(key, created);
+    return created;
+  };
+
+  /**
+   * A frame target: the parent's, with every verb that touches a DOCUMENT re-pointed at this
+   * frame's. `...base` is what makes the spread dangerous — a verb nobody overrides silently acts
+   * on the parent — so the act-verbs are listed here even where the body is one line.
+   *
+   * `click` navigates NOTHING, and that is a real limit rather than an oversight: a
+   * `PageRecording.frames` entry is one static document, so there is no second frame document for
+   * a click to land on. What it must never do is navigate the PARENT, which is what inheriting
+   * `base.click` did — `driver-parity-frames.test.ts` pins that on all three drivers. `evaluate` and
+   * `download` stay the parent's: the recording format keys evaluations and downloads per PAGE,
+   * so a frame has no map of its own to read.
+   */
+  const frameTarget = (html: string, url: string, key: string): ScrapeTarget => {
+    const document: OfflineDocument = { html: () => html, overlay: overlayFor(key) };
+    return {
+      ...base,
+      url: () => url,
+      content: () => Promise.resolve(html),
+      query: (selector) => queryIn(document, selector),
+      async click(selector: string): Promise<void> {
+        const element = await atIn(document, selector, 0);
+        if (element === undefined) throw fixtureMissing(`${url} ${selector}`, init.source);
+        const download =
+          recorded(page.downloads, selector) ?? recorded(page.downloads, element.attrs['id'] ?? '');
+        if (download !== undefined) armed = download;
+      },
+      type: (selector, text) => typeIn(document, selector, text),
+      clear: (selector) => setIn(document, selector, ''),
+      select: (selector, values) => setIn(document, selector, values[0] ?? ''),
+      frames: () => Promise.resolve([]),
+    };
+  };
 
   const base: ScrapeTarget = {
     driver: init.driver,
@@ -205,17 +306,10 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
         element.attrs['data-goto'] ?? (element.tag === 'a' ? element.attrs['href'] : undefined);
       if (href !== undefined && href !== '') await navigate(href);
     },
-    async type(selector: string, text: string): Promise<void> {
-      const element = await at(selector, 0);
-      const key = keyOf(selector, element);
-      overlay.set(key, `${overlay.get(key) ?? element?.value ?? ''}${text}`);
-    },
-    async clear(selector: string): Promise<void> {
-      overlay.set(keyOf(selector, await at(selector, 0)), '');
-    },
-    async select(selector: string, values: readonly string[]): Promise<void> {
-      overlay.set(keyOf(selector, await at(selector, 0)), values[0] ?? '');
-    },
+    type: (selector: string, text: string): Promise<void> => typeIn(pageDocument, selector, text),
+    clear: (selector: string): Promise<void> => setIn(pageDocument, selector, ''),
+    select: (selector: string, values: readonly string[]): Promise<void> =>
+      setIn(pageDocument, selector, values[0] ?? ''),
     evaluate(expression: string): Promise<unknown> {
       live();
       const answer = recorded(page.evaluate, expression);
@@ -225,6 +319,20 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
         throw fixtureMissing(`${page.url} evaluate(${expression})`, init.source);
       return Promise.resolve(JSON.parse(answer) as unknown);
     },
+    /**
+     * REFUSED, and `async` so it REJECTS. There is no browser here and no service worker, so
+     * there is no network to cut — and a resolved promise would let "a like taken offline is
+     * queued" pass against an app that was online for the whole test. That is the exact shape of
+     * lie `packages/testing`'s `fetch` patch already tells about a browser's own requests.
+     */
+    // `async`, so the refusal REJECTS: the method is typed `Promise<void>` and a synchronous
+    // `throw` from one jumps straight over `page.offline(true).catch(…)` at every caller.
+    async setOfflineMode(_enabled: boolean): Promise<void> {
+      throw scrapeNotImplemented(
+        `setOfflineMode() on the ${init.driver} driver`,
+        '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',
+      );
+    },
     screenshot: (options: CaptureOptions): Promise<Uint8Array> =>
       Promise.resolve(options.clip === undefined ? FAKE_PNG : clippedPng(options.clip)),
     pdf: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PDF),
@@ -255,7 +363,7 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
           name,
           url,
           selector: element.attrs['id'] === undefined ? undefined : `#${element.attrs['id']}`,
-          target: frameTarget(html, url),
+          target: frameTarget(html, url, `${name}\u0000${url}`),
         });
       }
       return refs;

package/src/http-recorded.ts

@@ -14,6 +14,7 @@ import { interceptVerdict } from './intercept';
 import type { HttpRecording } from './recording';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
+import type { ScrapeSecrets } from './secrets';
 
 export type HttpRecordingLookup = (
   method: string,
@@ -33,6 +34,8 @@ export interface RecordedHttpInit {
    */
   readonly robots?: RobotsGate | undefined;
   readonly maxAgeMs?: number | undefined;
+  /** The SAME bag the live leg holds, so a recorded 4xx body redacts the way a real one does. */
+  readonly secrets?: ScrapeSecrets | undefined;
 }
 
 /** `GET https://api.example.com/v1/orders?page=2` -> `http-get-api-example-com-v1-orders-page-2`. */
@@ -67,8 +70,12 @@ export function recordedHttp(init: RecordedHttpInit): ScrapeHttp {
         resourceType: 'fetch',
         at: init.clock.now().getTime(),
       });
-      return responseOver(url, found.status, found.headers ?? {}, () =>
-        Promise.resolve(found.body),
+      return responseOver(
+        url,
+        found.status,
+        found.headers ?? {},
+        () => Promise.resolve(found.body),
+        init.secrets,
       );
     },
   };

package/src/http.ts

@@ -20,6 +20,8 @@ import type { InterceptRules } from './intercept';
 import { interceptVerdict } from './intercept';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
+import type { ScrapeSecrets } from './secrets';
+import { redactSecrets } from './secrets';
 import type { SessionSnapshot } from './session-state';
 
 /**
@@ -98,6 +100,14 @@ export interface HttpTransportInit {
   readonly onActivity?: (() => void) | undefined;
   /** The SAME proxy the browser dialled through. A different exit IP is a different client. */
   readonly proxy?: string | undefined;
+  /**
+   * The run's secret bag, for the ONE thing this leg persists that the site wrote: the first 200
+   * bytes of a non-2xx body, in `X_SCRAPE_HTTP_FAILED`'s cause. A login endpoint that echoes the
+   * submitted credential in its 4xx body put a password in an `UltimateError.message`, which the
+   * job driver writes to the dead-letter row and `x jobs show` prints. This field did not exist
+   * until 2026-08-24, so nothing on this leg COULD redact.
+   */
+  readonly secrets?: ScrapeSecrets | undefined;
   readonly fetch?: ScrapeFetch | undefined;
 }
 
@@ -122,11 +132,18 @@ const headerRecord = (headers: Headers): Record<string, string> => {
   return out;
 };
 
+/**
+ * `secrets` is optional and last so every existing caller compiles — but a caller that HAS a bag
+ * and omits it is a caller whose refusal quotes the site verbatim, which is exactly the defect.
+ * Both transports pass it: `httpOverFetch` from the driver's `SessionInit`, `recordedHttp` from
+ * the offline session's, so a fixture proves the redaction the live leg performs.
+ */
 export function responseOver(
   url: string,
   status: number,
   headers: Readonly<Record<string, string>>,
   body: () => Promise<string>,
+  secrets?: ScrapeSecrets | undefined,
 ): ScrapeResponse {
   const ok = status >= 200 && status < 300;
   const text = body;
@@ -138,7 +155,9 @@ export function responseOver(
     text,
     json: async (): Promise<unknown> => JSON.parse(await text()) as unknown,
     async parse<T>(schema: StandardSchemaV1<unknown, T>): Promise<T> {
-      if (!ok) throw httpFailed(url, status, (await text()).slice(0, 200));
+      // Redacted BEFORE the slice, never after: cutting at 200 bytes can leave half a secret,
+      // and half a password is still half a password in a durable row.
+      if (!ok) throw httpFailed(url, status, redactSecrets(await text(), secrets).slice(0, 200));
       return parse(schema, JSON.parse(await text()) as unknown);
     },
   };
@@ -195,8 +214,12 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
         const capped = await readWithinLimit(response.body, maxBytes);
         if ('over' in capped) throw bodyTooLarge(url, capped.over, maxBytes);
         const body = new TextDecoder().decode(capped.bytes);
-        return responseOver(url, response.status, headerRecord(response.headers), () =>
-          Promise.resolve(body),
+        return responseOver(
+          url,
+          response.status,
+          headerRecord(response.headers),
+          () => Promise.resolve(body),
+          init.secrets,
         );
       } catch (thrown) {
         // A deadline that fired is this package's own timeout, with its own code and fix — never

package/src/index.ts

@@ -18,6 +18,7 @@ export type {
   ScrapeAuth,
 } from './auth';
 export { burnSession, createPrompt, ensureAuthenticated, restorableSession } from './auth';
+export { browserRecord } from './browser-record';
 export type { CaptureClip, CaptureFraming } from './capture-clip';
 export { assertCaptureFraming } from './capture-clip';
 export type {
@@ -28,7 +29,7 @@ export type {
   CdpRequestLike,
   CdpScreenshotOptions,
 } from './cdp-port';
-export { parseSnapshots, snapshotExpression } from './cdp-snapshot';
+export { clearExpression, parseSnapshots, snapshotExpression } from './cdp-snapshot';
 export type { CdpTargetInit } from './cdp-target';
 export { CDP_DRIVER, cdpTarget } from './cdp-target';
 export type { Deadline, ScrapeClock, TestScrapeClock } from './clock';
@@ -172,9 +173,13 @@ export type { ScrapeSecrets, SecretResolver } from './secrets';
 export {
   blankPasswordFields,
   createSecretBag,
+  MIN_REDACTABLE_LENGTH,
   redactSecrets,
   SECRET_PLACEHOLDER,
+  safeConsole,
   safeHtml,
+  safeNetwork,
+  safePageErrors,
 } from './secrets';
 export type { ScrapeSessionStore, SessionSnapshot, SessionState } from './session-state';
 export {

package/src/offline-session.ts

@@ -60,6 +60,9 @@ export async function openOfflineSession(init: OfflineSessionInit): Promise<Scra
       source: init.source,
       // The same gate the page above holds, from the same field: two legs, one robots decision.
       robots: init.session.robots,
+      // The same bag, for the same reason: a redaction only the live leg performs is one no
+      // fixture can prove.
+      secrets: init.session.secrets,
       maxAgeMs: init.maxAgeMs,
     }),
     close: () => target.close(),

package/src/page-over-target.ts

@@ -22,7 +22,7 @@ import type {
 } from './page';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
-import { safeHtml } from './secrets';
+import { safeConsole, safeHtml, safeNetwork, safePageErrors } from './secrets';
 import type {
   CaptureOptions,
   ElementSnapshot,
@@ -130,7 +130,16 @@ function frameOver(
       await wait(selector, options, 'actionable');
       await (await resolve()).select(selector, values);
     },
+    // Resolved through `resolve()` like every other verb, which is what makes a FRAME's `query`
+    // read the frame's document: `resolve` is `resolveChild` there, and both drivers override
+    // `query` on the frame target. A forward that reached for a captured page target instead
+    // would be the same defect `clear` had.
+    async query(selector): Promise<readonly ElementSnapshot[]> {
+      return await (await resolve()).query(selector);
+    },
     async values(selector): Promise<readonly ElementValue[]> {
+      // `resolve()` and not `this.query(…)`: a caller who destructures — `const { values } = page`
+      // — loses `this`, and a projection of the read above must not depend on how it was reached.
       return (await (await resolve()).query(selector)).map(toValue);
     },
     async text(selector): Promise<string> {
@@ -229,11 +238,21 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     async download(options?: DownloadRequest): Promise<ScrapeDownloadFile> {
       return await target.download({ timeoutMs: options?.timeout ?? ctx.defaultTimeoutMs });
     },
+    // `async`, for `download()`'s reason: `ScrapeTarget` is the seam a third party implements, and
+    // a driver that throws synchronously from a promise-typed method would escape `.catch()`.
+    async offline(enabled: boolean): Promise<void> {
+      await target.setOfflineMode(enabled);
+    },
     cookies: (): Promise<readonly ScrapeCookie[]> => target.cookies(),
     session: () => target.session(),
-    console: () => target.console.entries(),
-    pageErrors: () => target.pageErrors.entries(),
-    network: () => target.network.entries(),
+    // Redacted BY VALUE on the way out, the same pass `html()` makes. A console line and a request
+    // URL are two of the four surfaces `secrets.ts` names, and neither had a redaction caller: a
+    // login endpoint fetched with the password in its query string, or a site that logs the
+    // credential it rejected, put the value in `page.network()` and `page.console()` verbatim —
+    // and from there into `saveFailureArtifact`'s stored report.
+    console: () => safeConsole(target.console.entries(), ctx.secrets),
+    pageErrors: () => safePageErrors(target.pageErrors.entries(), ctx.secrets),
+    network: () => safeNetwork(target.network.entries(), ctx.secrets),
     networkDropped: () => target.network.dropped,
     pageErrorsDropped: () => target.pageErrors.dropped,
   };

package/src/page.ts

@@ -1,6 +1,7 @@
-// The vocabulary a `run()` body writes against — small, declarative, and driver-blind. Fourteen
-// verbs, chosen because every scraper in the audit re-implemented these and nothing else; a
-// fifteenth would be a second way to do something on this list.
+// The vocabulary a `run()` body writes against — small, declarative, and driver-blind. Every verb
+// is here because every scraper in the audit re-implemented it and nothing else; a new one is a
+// second way to do something already on this list. NO COUNT: this said "Fourteen verbs" against
+// twenty-three, and a prose ordinal is wrong the moment the next verb lands.
 //
 // Nothing here mentions puppeteer, CDP, a frame handle or a locator. That is the seam: a run body
 // written against this file runs unchanged on a real browser, on a recorded fixture and on a
@@ -47,6 +48,17 @@ export interface ScrapeFrame {
   /** Clears first, then types — the spelling a login form wants. */
   fill(selector: string, text: string | Secret, options?: WaitOptions): Promise<void>;
   select(selector: string, values: readonly string[], options?: WaitOptions): Promise<void>;
+  /**
+   * Every match, as SNAPSHOTS — `visible`, `enabled` and (on a driver with a layout engine) the
+   * box and hit-target, which `values()` projects away.
+   *
+   * It exists because `ScrapeTarget.query` already answered all of that and nothing above it
+   * exposed it, so the first caller that needed "is this visible?" wrote its own
+   * `display !== 'none' && visibility !== 'hidden' && opacity !== '0'` — a second definition of
+   * "visible" in one framework. `values()` remains the projection for row assembly; this is the
+   * read for a decision about an element.
+   */
+  query(selector: string): Promise<readonly ElementSnapshot[]>;
   /** Every match, as values. Row assembly is the app's business, never the framework's. */
   values(selector: string): Promise<readonly ElementValue[]>;
   /** The first match's text, or `''`. */
@@ -90,6 +102,13 @@ export interface ScrapePage extends ScrapeFrame {
   /** The file the last click produced, or `X_SCRAPE_DOWNLOAD_TIMEOUT`. */
   download(options?: DownloadRequest): Promise<ScrapeDownloadFile>;
   cookies(): Promise<readonly ScrapeCookie[]>;
+  /**
+   * Cut the BROWSER's network, or restore it — what a PWA's offline behaviour has to be tested
+   * against. Refused with `X_NOT_IMPLEMENTED` on a driver that has no browser: patching `fetch`
+   * in the test process cannot reach a browser's own requests, so a driver that quietly answered
+   * "done" would let an offline assertion pass against an app that never went offline.
+   */
+  offline(enabled: boolean): 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/recording.ts

@@ -22,11 +22,27 @@ export interface PageRecording {
   readonly recordedAt?: string | undefined;
 }
 
+/**
+ * `.min(0)` where empty is a real recorded answer, `t.string` where it could not be — this
+ * package's own idiom, spelled with its reason at `cdp-target.ts` and `cdp-snapshot.ts`.
+ *
+ * `html` and a `frames` entry are the empty ones: a blank document and an empty iframe are both
+ * what real sites serve, and refusing them made `fixtureBrowser()` throw `X_VALIDATION_FAILED` on
+ * a recording `fakeBrowser()` replayed happily — the two offline drivers disagreeing about the
+ * same file, which is the one thing a shared format exists to prevent.
+ *
+ * `url`, an `evaluate` entry and a `downloads` entry stay non-empty, each for a reason: there is
+ * nothing to key a recording by without a URL, an `evaluate` value is JSON TEXT and `''` is not
+ * JSON (`htmlTarget` would throw a bare `SyntaxError` at read time instead), and a download is
+ * `filename:contents`.
+ */
+const recordedText = t.string.min(0);
+
 export const pageRecordingSchema: StandardSchemaV1<unknown, PageRecording> = t.object({
   url: t.string,
-  html: t.string,
+  html: recordedText,
   evaluate: t.optional(t.record(t.string)),
-  frames: t.optional(t.record(t.string)),
+  frames: t.optional(t.record(recordedText)),
   downloads: t.optional(t.record(t.string)),
   recordedAt: t.optional(t.string),
 }) as unknown as StandardSchemaV1<unknown, PageRecording>;
@@ -49,12 +65,17 @@ export interface HttpRecording {
   readonly recordedAt?: string | undefined;
 }
 
+/**
+ * `body` and a header value are the empty ones. A 204 has no body BY DEFINITION — refusing it
+ * meant the one status a `POST /like` answers could not be recorded at all — and a site sending
+ * `x-trace:` with nothing after it is a header it sent.
+ */
 export const httpRecordingSchema: StandardSchemaV1<unknown, HttpRecording> = t.object({
   url: t.string,
   method: t.string,
   status: t.number,
-  body: t.string,
-  headers: t.optional(t.record(t.string)),
+  body: recordedText,
+  headers: t.optional(t.record(recordedText)),
   recordedAt: t.optional(t.string),
 }) as unknown as StandardSchemaV1<unknown, HttpRecording>;
 

package/src/rings.ts

@@ -2,6 +2,8 @@
 // thousand pages that kept every console line and every request holds the run's entire browsing
 // history in the worker's heap, and the incident is an OOM two hours in rather than a scraper bug.
 
+import { assert } from '@ultimat3/core';
+
 export interface ConsoleLine {
   readonly level: 'log' | 'info' | 'warn' | 'error' | 'debug';
   readonly text: string;
@@ -99,7 +101,25 @@ export type ConsoleRing = Ring<ConsoleLine>;
 export type NetworkRing = Ring<NetworkEntry>;
 export type PageErrorRing = Ring<PageError>;
 
+/**
+ * REFUSED rather than clamped, the shape `@ultimat3/storage`'s `resolveListLimit` uses — a bound
+ * with no code of its own is still a coded refusal, never a bare `Error`.
+ *
+ * Both wrong values fail in opposite directions and neither is survivable. A NEGATIVE capacity
+ * makes `while (items.length > capacity) items.shift()` spin forever on an already-empty array
+ * (`0 > -1`): `createRing(-1).push(1)` never returns, and it is a synchronous loop on the worker's
+ * only thread, inside a `page.on('request')` handler — past `ctx.signal`, past the wedge watchdog
+ * and past the job timeout, which is incident #1 in this file's header. `NaN` fails the other way:
+ * the comparison is false forever, the ring is UNBOUNDED, and the OOM the bound exists to prevent
+ * arrives two hours in. Zero is a ring that discards everything silently, and a fraction is a
+ * bound that is not the number anybody asked for.
+ */
 export function createRing<T>(capacity: number = DEFAULT_RING_CAPACITY): Ring<T> {
+  assert(
+    Number.isSafeInteger(capacity) && capacity > 0,
+    `a ring capacity must be a positive integer, got ${String(capacity)}: a negative one spins forever on push() and NaN makes the ring unbounded`,
+    `pass a positive capacity — createRing(${String(DEFAULT_RING_CAPACITY)}) — or omit it and take DEFAULT_RING_CAPACITY`,
+  );
   const items: T[] = [];
   let dropped = 0;
   return {

package/src/secrets.ts

@@ -8,6 +8,7 @@
 
 import type { Secret } from '@ultimat3/core';
 import { revealSecret, secret, UltimateError } from '@ultimat3/core';
+import type { ConsoleLine, NetworkEntry, PageError } from './rings';
 
 export interface ScrapeSecrets {
   readonly names: readonly string[];
@@ -61,9 +62,33 @@ export function createSecretBag(
 export const SECRET_PLACEHOLDER = '[redacted]';
 
 /**
- * Redaction BY VALUE, over any text this package is about to persist: page HTML, a console line,
- * a request URL, an error cause. Name-based redaction only catches a secret travelling under a
- * name somebody remembered to list, and a password pasted into a query string travels under none.
+ * The floor, and it is a real hole rather than an implementation detail: a secret shorter than
+ * this is NOT redacted.
+ *
+ * A three-character value is a substring of ordinary prose — a PIN of `123` would blank every
+ * price, every id and every timestamp fragment on the page, and an artifact redacted into
+ * unreadability is one nobody can diagnose from. So the bound is deliberate, and the answer for a
+ * genuinely short credential is that it must not be one: `page.type(selector, secrets.get(name))`
+ * still TAINTS the page whatever the length, so `screenshot()` and `pdf()` are refused either way.
+ * Only the by-value text pass below skips it. Exported so a caller can check rather than discover.
+ */
+export const MIN_REDACTABLE_LENGTH = 4;
+
+/**
+ * Redaction BY VALUE, over the text this package hands back or persists. Name-based redaction only
+ * catches a secret travelling under a name somebody remembered to list, and a password pasted into
+ * a query string travels under none.
+ *
+ * The four surfaces, and they are the four callers below — page HTML (`safeHtml`), a console line
+ * (`safeConsole`), a request URL (`safeNetwork`) and a thrown message (`safePageErrors`), plus the
+ * HTTP leg's own `X_SCRAPE_HTTP_FAILED` cause, which redacts at its throw site in `http.ts`
+ * because the body is gone by the time anything else could. Three of those had NO caller until
+ * 2026-08-24 while this header claimed all four.
+ *
+ * What is still NOT redacted, stated rather than implied: a URL in any other error's `cause` or
+ * `meta` (`X_SCRAPE_HOST_BLOCKED`, `X_SCRAPE_FIXTURE_MISSING`), a value shorter than
+ * `MIN_REDACTABLE_LENGTH`, and pixels — which is why a secret TAINTS the page and captures are
+ * refused outright.
  *
  * Longest first, so a secret that contains another one does not leave its tail behind.
  */
@@ -71,13 +96,53 @@ export function redactSecrets(text: string, secrets: ScrapeSecrets | undefined):
   if (secrets === undefined || secrets.names.length === 0) return text;
   const values = secrets.names
     .map((name) => revealSecret(secrets.get(name)))
-    .filter((value) => value.length >= 4)
+    .filter((value) => value.length >= MIN_REDACTABLE_LENGTH)
     .sort((a, b) => b.length - a.length);
   let out = text;
   for (const value of values) out = out.split(value).join(SECRET_PLACEHOLDER);
   return out;
 }
 
+/**
+ * The bounded tails, redacted on the way OUT of the page vocabulary rather than on the way into
+ * the ring. A driver fills its rings from the browser's own events, and a `type()` that has not
+ * happened yet cannot redact a line already recorded — so the pass belongs where the entries are
+ * read, which is also the one place every driver shares.
+ *
+ * Each returns the entry UNCHANGED when nothing matched, so a run with no secrets declared pays
+ * one comparison per entry and allocates nothing.
+ */
+export const safeConsole = (
+  lines: readonly ConsoleLine[],
+  secrets: ScrapeSecrets | undefined,
+): readonly ConsoleLine[] =>
+  lines.map((line) => {
+    const text = redactSecrets(line.text, secrets);
+    return text === line.text ? line : { ...line, text };
+  });
+
+/** A password pasted into a query string is the case name-based redaction cannot see at all. */
+export const safeNetwork = (
+  entries: readonly NetworkEntry[],
+  secrets: ScrapeSecrets | undefined,
+): readonly NetworkEntry[] =>
+  entries.map((entry) => {
+    const url = redactSecrets(entry.url, secrets);
+    return url === entry.url ? entry : { ...entry, url };
+  });
+
+/** The stack too: a framework that prints the argument it threw on puts the value in both. */
+export const safePageErrors = (
+  errors: readonly PageError[],
+  secrets: ScrapeSecrets | undefined,
+): readonly PageError[] =>
+  errors.map((error) => {
+    const message = redactSecrets(error.message, secrets);
+    const stack = error.stack === undefined ? undefined : redactSecrets(error.stack, secrets);
+    if (message === error.message && stack === error.stack) return error;
+    return { ...error, message, ...(stack === undefined ? {} : { stack }) };
+  });
+
 /** Every `<input …>` tag, whole, so the rewrite below never has to reason about attribute order. */
 const INPUT_TAG = /<input\b[^>]*>/gi;
 /** `type=password`, quoted either way or bare. */