@ultimat3/scraping 13.0.0 → 14.0.0

package/README.md

@@ -85,6 +85,32 @@ Both legs replay from **one** fixture directory (`fixtureBrowser(dir)`), so a hy
 login, session handoff, HTTP bulk fetch — is tested end to end. Both legs apply the same robots
 gate, offline included.
 
+## Reading elements, frames, and the network condition
+
+| Read | Answers |
+|---|---|
+| `page.values(selector)` | `ElementValue[]` — tag, text, value, attrs. The projection row assembly wants |
+| `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 |
+
+`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
+`display !== 'none' && visibility !== 'hidden' && opacity !== '0'` a second time, which is the
+copy axiom 1 forbids.
+
+**A frame verb reaches the FRAME.** `fill`, `type`, `select`, `clear`, `click` and `query` through
+a `ScrapeFrame` handle all address that frame's own document — never the parent's, even when the
+two carry the same ids, which is what an iframe'd SSO login looks like. `driver-parity-frames.test.ts`
+drives all six through a frame on all three drivers. The one thing an offline driver cannot do is
+NAVIGATE a frame: a recorded frame is one static document, so a click inside one moves nothing
+(and, in particular, never moves the parent).
+
+**`page.offline()` is set on a browser or refused by name.** The offline drivers answer
+`X_NOT_IMPLEMENTED` rather than resolving: patching `fetch` in a test process cannot reach a
+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.
+
 ## 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
@@ -97,6 +123,14 @@ bound threw away, so a count taken from one is never quietly a floor.
 | `page.pageErrors()` / `page.pageErrorsDropped()` | `PageError[]` — what the page THREW and nobody caught, with the `stack` when the exception carried one |
 | `page.network()` / `page.networkDropped()` | `NetworkEntry[]` — every request, refusals included |
 
+All three are **redacted by value** on the way out, the same pass `page.html()` makes: a login
+endpoint fetched with the password in its query string, or a site that logs the credential it
+rejected, would otherwise put the value in `page.network()`/`page.console()` verbatim and from
+there into the stored failure artifact. The HTTP leg's `X_SCRAPE_HTTP_FAILED` cause is redacted
+too, at its throw site. Values shorter than `MIN_REDACTABLE_LENGTH` are not — a 3-character PIN is
+a substring of ordinary prose — and pixels never can be, which is why a typed secret TAINTS the
+page and `screenshot()`/`pdf()` are refused outright.
+
 `console()` and `pageErrors()` are separate streams because they are separate events: an island
 that throws during hydration calls no console method, so a scrape reading the console alone sees a
 page that looks silent and is broken — and a screenshot of it is a picture of the server-rendered
@@ -141,7 +175,8 @@ on a machine with no browser — the case CI is.
 | `driver-cdp.ts` / `cdp-*.ts` | the real browser, over a structural CDP port |
 | `driver-fake.ts` / `driver-fixture.ts` / `html-*.ts` | the offline drivers, on Bun's `HTMLRewriter` |
 | `http.ts` / `http-recorded.ts` | the second transport, live and replayed |
-| `auth.ts` / `session-state.ts` | acquire → persist → reuse → validate → burn |
+| `auth.ts` / `session-state.ts` | acquire → persist → reuse → validate → burn. The session key encodes each part (`<sanitised>.<digest>`), so two account names that differ only outside `[a-zA-Z0-9._-]` are two sessions |
+| `secrets.ts` / `browser-record.ts` | what may leave this package, and how a browser's own string map is read |
 | `expect.ts` | the silent-green alarm |
 | `watchdog.ts` | the wedge and zombie discipline |
 | `capture-clip.ts` | the one framing rule — crop, whole page, or a refusal — checked before any driver sees it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "13.0.0",
-    "@ultimat3/jobs": "13.0.0",
-    "@ultimat3/schema": "13.0.0",
-    "@ultimat3/storage": "13.0.0"
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/jobs": "14.0.0",
+    "@ultimat3/schema": "14.0.0",
+    "@ultimat3/storage": "14.0.0"
   }
 }

package/src/browser-record.ts

@@ -0,0 +1,35 @@
+// A string-to-string map that came out of the BROWSER — an element's attributes, `localStorage` —
+// read permissively and onto a null prototype. One reader, because the two call sites had the same
+// bug and would have been fixed twice.
+
+/**
+ * The browser's own keys, READ rather than refused by name.
+ *
+ * `t.record()` refuses `__proto__`, `constructor` and `prototype` (`packages/schema/src/
+ * validators.ts`), which is exactly right where a record's keys are a caller's — a request body —
+ * and exactly wrong here. `<div constructor="Foo">` is legal HTML that real build tooling emits,
+ * and `localStorage.setItem('constructor', …)` is legal storage; both threw `X_VALIDATION_FAILED`
+ * out of a page read with nothing wrong with it, and `cdp-target.ts`'s `guard()` then re-labelled
+ * that `X_SCRAPE_BROWSER_UNREACHABLE`, which is registered RETRYABLE — five browser launches and
+ * five arrivals at a login over one benign attribute.
+ *
+ * The null prototype is the other half, and it is why this is not merely a looser schema: on a
+ * `{}` literal `attrs['toString']` answers an `Object.prototype` function the page never sent, and
+ * `attrs['__proto__'] = value` files no own key at all. `Readonly<Record<string, string>>` would
+ * be a lie the caller cannot see through either way. Same construction and the same argument as
+ * `http.ts`'s `headerRecord` makes for response headers, one leg over.
+ *
+ * TOTAL, deliberately: a non-object answers an empty map and a non-string value is skipped. The
+ * caller is a driver reading a live browser, and a refusal from here is read by everything above
+ * it as a browser that went away.
+ */
+export function browserRecord(value: unknown): Record<string, string> {
+  const out = Object.create(null) as Record<string, string>;
+  if (typeof value !== 'object' || value === null) return out;
+  // Assignment, not `defineProperty`: with no prototype there is no inherited `__proto__` setter
+  // to swallow the write, so a key spelled `__proto__` files as an ordinary own key.
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === 'string') out[key] = entry;
+  }
+  return out;
+}

package/src/cdp-fake.ts

@@ -19,11 +19,35 @@ const selectorOf = (expression: string): string | undefined => {
   return JSON.parse(match[1]) as string;
 };
 
+/**
+ * The selector inside `clearExpression()`'s `document.querySelector("…")`, READ rather than
+ * imported. A clear is the one verb this port has no method for — it travels as an expression — so
+ * a fake that recognised it by identity could not tell the page's document from a frame's, which
+ * is precisely the divergence `driver-parity-frames.test.ts` needs it to expose.
+ */
+const clearedSelectorOf = (expression: string): string | undefined => {
+  if (!expression.includes(".value = ''")) return undefined;
+  const match = /querySelector\((".*?")\)/s.exec(expression);
+  if (match?.[1] === undefined) return undefined;
+  return JSON.parse(match[1]) as string;
+};
+
+export interface FakeCdpFrameInit {
+  readonly url: string;
+  readonly html: string;
+}
+
 export interface FakeCdpPageInit {
   readonly url: string;
   readonly html: string;
   /** Selectors a click navigates from, and where to. */
   readonly routes?: Readonly<Record<string, { readonly url: string; readonly html: string }>>;
+  /**
+   * Child frames by NAME, each its own document. A frame with its own markup is what makes a
+   * frame verb aimed at the parent document visible — with `frames(): []` the whole frame half of
+   * `cdp-target.ts` was unreachable from every test in the package.
+   */
+  readonly frames?: Readonly<Record<string, FakeCdpFrameInit>>;
   readonly cookies?: readonly ScrapeCookie[];
   readonly storage?: Readonly<Record<string, string>>;
   readonly userAgent?: string;
@@ -44,6 +68,8 @@ export interface FakeCdpBrowser extends CdpBrowserLike {
   emitPageError(payload: unknown): void;
   readonly aborted: readonly string[];
   readonly closed: boolean;
+  /** What `page.setOfflineMode()` last set, so a test asserts on the CONDITION, not on a call. */
+  readonly offline: boolean;
 }
 
 /** A layout box every element gets, so the CDP path exercises the fields the fake target lacks. */
@@ -53,58 +79,136 @@ const boxed = (snapshot: ElementSnapshot, covered: boolean): ElementSnapshot =>
   hitTarget: !covered,
 });
 
+/**
+ * ONE document — the page's, or a frame's. A browser gives every browsing context its own DOM, so
+ * the fake gives every one its own typed values: a verb that reaches the wrong document then shows
+ * up as text in the wrong place rather than as nothing at all.
+ */
+interface FakeDocument {
+  html(): string;
+  /** Typed text, keyed the way `keyOf` keys it offline: `#id` when there is one, else the selector. */
+  readonly typed: Map<string, string>;
+}
+
+const keyFor = (selector: string, element: ElementSnapshot | undefined): string => {
+  const id = element?.attrs['id'];
+  return id === undefined ? selector : `#${id}`;
+};
+
+/** What the DOM would answer after a `type()`: the element, carrying whatever was typed into it. */
+const withTyped = (
+  document: FakeDocument,
+  selector: string,
+  elements: readonly ElementSnapshot[],
+): readonly ElementSnapshot[] =>
+  elements.map((element) => {
+    const typed = document.typed.get(keyFor(selector, element));
+    return typed === undefined ? element : { ...element, value: typed };
+  });
+
 export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
   const handlers: Handlers = new Map();
   const aborted: string[] = [];
   let url = init.url;
   let html = init.html;
   let closed = false;
+  let offline = false;
   const covered = new Set(init.covered ?? []);
   const storage: Record<string, string> = { ...init.storage };
   let cookies: readonly ScrapeCookie[] = init.cookies ?? [];
 
-  const evaluate = async (expression: string): Promise<unknown> => {
+  const documentOf = (read: () => string): FakeDocument => ({ html: read, typed: new Map() });
+  const pageDocument = documentOf(() => html);
+
+  /** Every expression this package sends, answered against the document it was sent to. */
+  const evaluateIn = async (target: FakeDocument, expression: string): Promise<unknown> => {
     const selector = selectorOf(expression);
     if (selector !== undefined) {
-      const found = await queryHtml(html, selector);
+      const found = withTyped(target, selector, await queryHtml(target.html(), selector));
       return JSON.stringify(found.map((element) => boxed(element, covered.has(selector))));
     }
-    if (expression.includes('localStorage')) {
-      if (expression.includes('setItem')) return undefined;
-      return JSON.stringify(storage);
+    const cleared = clearedSelectorOf(expression);
+    if (cleared !== undefined) {
+      const [first] = await queryHtml(target.html(), cleared);
+      target.typed.set(keyFor(cleared, first), '');
+      return undefined;
     }
-    if (expression.includes('navigator.userAgent')) return init.userAgent ?? 'fake-agent';
     return undefined;
   };
 
+  const typeIn = async (target: FakeDocument, selector: string, text: string): Promise<void> => {
+    const [first] = await queryHtml(target.html(), selector);
+    const key = keyFor(selector, first);
+    target.typed.set(key, `${target.typed.get(key) ?? first?.value ?? ''}${text}`);
+  };
+
+  const selectIn = async (target: FakeDocument, selector: string, value: string): Promise<void> => {
+    const [first] = await queryHtml(target.html(), selector);
+    target.typed.set(keyFor(selector, first), value);
+  };
+
+  const frames: readonly CdpFrameLike[] = Object.entries(init.frames ?? {}).map(([name, frame]) => {
+    const frameDocument = documentOf(() => frame.html);
+    return {
+      name: () => name,
+      url: () => frame.url,
+      content: () => Promise.resolve(frame.html),
+      evaluate: (expression: string) => evaluateIn(frameDocument, expression),
+      click: () => Promise.resolve(),
+      type: (selector: string, text: string) => typeIn(frameDocument, selector, text),
+      select: async (selector: string, ...values: string[]): Promise<string[]> => {
+        await selectIn(frameDocument, selector, values[0] ?? '');
+        return [...values];
+      },
+    };
+  });
+
   const page: CdpPageLike = {
     url: () => url,
     goto: (next: string) => {
       url = next;
+      // A navigation is a new document, so what was typed into the old one is gone. Keeping it
+      // would let a stale value answer a query on a page that never had it.
+      pageDocument.typed.clear();
       return Promise.resolve(undefined);
     },
     content: () => Promise.resolve(html),
-    evaluate,
+    async evaluate(expression: string): Promise<unknown> {
+      if (expression.includes('localStorage')) {
+        if (expression.includes('setItem')) return undefined;
+        return JSON.stringify(storage);
+      }
+      if (expression.includes('navigator.userAgent')) return init.userAgent ?? 'fake-agent';
+      return await evaluateIn(pageDocument, expression);
+    },
     click: (selector: string) => {
       const route = init.routes?.[selector];
       if (route !== undefined) {
         url = route.url;
         html = route.html;
+        pageDocument.typed.clear();
       }
       return Promise.resolve();
     },
-    type: () => Promise.resolve(),
-    select: () => Promise.resolve([]),
+    type: (selector: string, text: string) => typeIn(pageDocument, selector, text),
+    select: async (selector: string, ...values: string[]): Promise<string[]> => {
+      await selectIn(pageDocument, selector, values[0] ?? '');
+      return [...values];
+    },
     screenshot: () => Promise.resolve(new Uint8Array([1, 2, 3])),
     pdf: () => Promise.resolve(new Uint8Array([4, 5])),
     setRequestInterception: () => Promise.resolve(),
+    setOfflineMode: (enabled: boolean) => {
+      offline = enabled;
+      return Promise.resolve();
+    },
     on: (event: string, handler: (payload: unknown) => void) => {
       const listeners = handlers.get(event) ?? [];
       listeners.push(handler);
       handlers.set(event, listeners);
       return undefined;
     },
-    frames: (): readonly CdpFrameLike[] => [],
+    frames: (): readonly CdpFrameLike[] => frames,
     close: () => {
       closed = true;
       return Promise.resolve();
@@ -143,6 +247,9 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
     get closed(): boolean {
       return closed;
     },
+    get offline(): boolean {
+      return offline;
+    },
   };
 }
 

package/src/cdp-port.ts

@@ -56,6 +56,19 @@ export interface CdpPageLike {
   screenshot(options: CdpScreenshotOptions): Promise<Uint8Array | string>;
   pdf(options?: Record<string, unknown>): Promise<Uint8Array>;
   setRequestInterception(enabled: boolean): Promise<void>;
+  /**
+   * The browser's own network condition — `Network.emulateNetworkConditions` under CDP.
+   *
+   * OPTIONAL, read defensively, for `CdpRequestLike.method` and `CdpBrowserLike.cookies`' reason:
+   * this file is the shape of somebody ELSE's object, and 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,
+   * exactly as `cookies()` does, so the gap is a coded refusal rather than a silent no-op.
+   *
+   * Required instead would cost every existing launcher, every provider SDK and every test double
+   * a type error for a capability the port cannot make them have.
+   */
+  setOfflineMode?(enabled: boolean): 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-snapshot.ts

@@ -1,4 +1,4 @@
-// The one in-page expression this package runs, and the schema that reads its answer back.
+// The in-page expressions this package runs, and the schema that reads their answer back.
 //
 // It computes exactly `ElementSnapshot` — including the two fields the offline drivers cannot
 // have: the layout box, and whether the element is what a click at its own centre would hit. A
@@ -7,6 +7,7 @@
 
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
+import { browserRecord } from './browser-record';
 import type { ElementSnapshot } from './target';
 
 /**
@@ -36,6 +37,18 @@ export const snapshotExpression = (selector: string): string => `(() => {
   return JSON.stringify(out);
 })()`;
 
+/**
+ * Emptying a control, as an expression — the one verb `CdpPageLike`/`CdpFrameLike` has no method
+ * for, so it travels as text and is `evaluate`d against whichever document it is handed to.
+ *
+ * ONE declaration, and that is the whole point of it living here: the page target and the frame
+ * target each `evaluate` it, and a second copy is how the frame half came to send the page's
+ * expression to the page's own document — emptying the PARENT's same-named field while the
+ * frame's kept its value and a `fill` appended to it.
+ */
+export const clearExpression = (selector: string): string =>
+  `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (el) { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); } })()`;
+
 /**
  * `t.string` refuses an empty string, and an element's `text` and `value` are legitimately empty
  * far more often than not — a `<div>` wrapper, an unfilled input. `.min(0)` says "a string, and
@@ -43,10 +56,16 @@ export const snapshotExpression = (selector: string): string => `(() => {
  */
 const anyString = t.string.min(0);
 
+/**
+ * `attrs` is absent from the shape and read by `browserRecord` instead — the one field whose KEYS
+ * are the page's rather than a schema's. `t.record()` refuses `__proto__`, `constructor` and
+ * `prototype` by name, so `<div constructor="Foo">` on any queried element refused the whole read;
+ * see `browser-record.ts` for why the refusal is right for a request body and wrong for a DOM.
+ * Every other field is still parsed, and a `tag` that is not a string still refuses.
+ */
 const snapshotSchema = t.array(
   t.object({
     tag: t.string,
-    attrs: t.record(anyString),
     text: anyString,
     value: anyString,
     visible: t.boolean,
@@ -54,10 +73,22 @@ const snapshotSchema = t.array(
     box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
     hitTarget: t.boolean,
   }),
-) as unknown as StandardSchemaV1<unknown, ElementSnapshot[]>;
+) as unknown as StandardSchemaV1<unknown, Omit<ElementSnapshot, 'attrs'>[]>;
+
+const attrsOf = (row: unknown): unknown =>
+  typeof row === 'object' && row !== null ? (row as { readonly attrs?: unknown }).attrs : undefined;
 
-/** The browser's answer is `unknown` and stays `unknown` until this parses it. Never a cast. */
+/**
+ * The browser's answer is `unknown` and stays `unknown` until this reads it. Never a cast.
+ *
+ * The parsed rows and the raw rows are zipped by INDEX, which is sound because the array schema
+ * preserves order and length: a row that failed makes the whole parse throw before this runs.
+ */
 export function parseSnapshots(raw: unknown): readonly ElementSnapshot[] {
-  if (typeof raw !== 'string') return parse(snapshotSchema, raw);
-  return parse(snapshotSchema, JSON.parse(raw) as unknown);
+  const value = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
+  const rows: readonly unknown[] = Array.isArray(value) ? (value as readonly unknown[]) : [];
+  return parse(snapshotSchema, value).map((element, index) => ({
+    ...element,
+    attrs: browserRecord(attrsOf(rows[index])),
+  }));
 }

package/src/cdp-target.ts

@@ -4,8 +4,9 @@
 import { isUltimateError } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
+import { browserRecord } from './browser-record';
 import type { CdpBrowserLike, CdpFrameLike, CdpPageLike, CdpRequestLike } from './cdp-port';
-import { parseSnapshots, snapshotExpression } from './cdp-snapshot';
+import { clearExpression, parseSnapshots, snapshotExpression } from './cdp-snapshot';
 import type { ScrapeClock } from './clock';
 import { browserUnreachable, pageCrashed, scrapeNotImplemented } from './error-throws';
 import type { InterceptRules } from './intercept';
@@ -47,11 +48,6 @@ const cookieSchema = t.array(
   }),
 ) as unknown as StandardSchemaV1<unknown, ScrapeCookie[]>;
 
-const storageSchema = t.record(anyString) as unknown as StandardSchemaV1<
-  unknown,
-  Record<string, string>
->;
-
 const asResourceType = (raw: string): ResourceType =>
   (RESOURCE_TYPES as readonly string[]).includes(raw) ? (raw as ResourceType) : 'other';
 
@@ -130,31 +126,51 @@ const readPageError = (payload: unknown, at: number): PageError => {
 };
 
 /**
- * The one failure `guard()` must NOT re-label, and the line is drawn at exactly one code.
+ * The failures `guard()` must NOT re-label. Two codes, each because a SECOND attempt reaches the
+ * identical answer — never because the error looked coded.
+ *
+ * | Code | Why a retry cannot change it |
+ * |---|---|
+ * | `X_NOT_IMPLEMENTED` | a fact about the launcher's own shape. A browser cannot produce it; only this file's `scrapeNotImplemented()` can, and the method is still missing on attempt five |
+ * | `X_VALIDATION_FAILED` | the browser ANSWERED, and the answer did not match the shape this driver reads it with. The page is what it is; attempt five reads the same DOM |
  *
- * `X_NOT_IMPLEMENTED` is the only code that says "this build does not have the feature" — a fact
- * about the launcher's own shape, never about the connection. A browser cannot produce it; only
- * this file's own `scrapeNotImplemented()` can, from inside a guarded closure. Re-labelled as
- * `X_SCRAPE_BROWSER_UNREACHABLE` (registered `retryable` in `errors.ts`) it spends every attempt
- * in the scrape's retry policy on a method that is still missing on attempt five, and tells the
- * operator the browser went away while the browser is answering fine.
+ * Both were re-labelled `X_SCRAPE_BROWSER_UNREACHABLE`, which `errors.ts` registers `retryable`,
+ * so each spent the whole retry policy — five browser launches, five arrivals at a login — while
+ * telling the operator the browser went away about a browser that was answering perfectly.
  *
  * Every OTHER coded error stays wrapped, deliberately. `thrown instanceof UltimateError` is the
  * naive version of this check and it is wrong: an `X_SCRAPE_TIMEOUT` raised while the socket was
  * already dead would then arrive unwrapped, and "the browser went away mid-run" is the frame that
  * makes a disconnect legible — which is the whole reason this wrapper exists.
  *
+ * The half this package cannot close: both codes belong to `@ultimat3/core`/`@ultimat3/schema` and
+ * NEITHER is classified, so `classifyThrown` reads them as unclassified and the job's attempt
+ * count still governs. Passing them through stops the wrong TITLE and the false `retryable`
+ * claim; making them terminal is a `registerErrorRetry` beside the code that declares it.
+ *
  * `isUltimateError`, not `instanceof`: the brand survives a duplicated module instance.
  */
+const PASSED_THROUGH_CODES: ReadonlySet<string> = new Set([
+  'X_NOT_IMPLEMENTED',
+  'X_VALIDATION_FAILED',
+]);
+
 const isStructuralRefusal = (thrown: unknown): boolean =>
-  isUltimateError(thrown) && thrown.code === 'X_NOT_IMPLEMENTED';
+  isUltimateError(thrown) && PASSED_THROUGH_CODES.has(thrown.code);
 
+/**
+ * `ringCapacity` was declared here, exported, read three lines into `cdpTarget` — and passed by
+ * NOBODY: `driver-cdp.ts` constructs without it and no `BrowserOptions` or `ScrapeDefinition`
+ * field reaches it, so an app could not set it at any distance. Deleted rather than threaded, the
+ * same call `CaptureOptions.timeoutMs` got: wiring it through only the CDP driver would give one
+ * of three drivers a bound the other two ignore, which is precisely the divergence
+ * `driver-parity.test.ts` exists to refuse. `DEFAULT_RING_CAPACITY` is the one bound.
+ */
 export interface CdpTargetInit {
   readonly page: CdpPageLike;
   readonly browser: CdpBrowserLike;
   readonly rules: InterceptRules;
   readonly clock: ScrapeClock;
-  readonly ringCapacity?: number | undefined;
 }
 
 /**
@@ -228,9 +244,9 @@ async function arm(init: CdpTargetInit, sinks: CdpSinks): Promise<void> {
 }
 
 export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
-  const console_ = createRing<ConsoleLine>(init.ringCapacity);
-  const network = createRing<NetworkEntry>(init.ringCapacity);
-  const pageErrors = createRing<PageError>(init.ringCapacity);
+  const console_ = createRing<ConsoleLine>();
+  const network = createRing<NetworkEntry>();
+  const pageErrors = createRing<PageError>();
   const crashed: { value: string | undefined } = { value: undefined };
   await arm(init, { network, console: console_, pageErrors, crashed });
   let pendingStorage: SessionSnapshot | undefined;
@@ -288,6 +304,15 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       ),
     click: (selector) => guard('click', () => frame.click(selector)),
     type: (selector, text) => guard('type', () => frame.type(selector, text)),
+    // Listed even though `type` above already covers the pair a `fill` performs: `clear` is the
+    // one verb with no port method, so it is the one an author of a new frame verb forgets. It was
+    // forgotten — the spread handed the frame the PAGE's closure, so `frame.fill()` emptied the
+    // parent document's same-named field and merely APPENDED to the frame's, which is how an
+    // iframe'd login submits `oldUserNEWUSER` and passes its own offline test doing it.
+    clear: (selector) =>
+      guard('clear', async () => {
+        await frame.evaluate(clearExpression(selector));
+      }),
     select: (selector, values) =>
       guard('select', async () => {
         await frame.select(selector, ...values);
@@ -318,15 +343,24 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     type: (selector, text) => guard('type', () => init.page.type(selector, text)),
     clear: (selector) =>
       guard('clear', async () => {
-        await init.page.evaluate(
-          `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (el) { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); } })()`,
-        );
+        await init.page.evaluate(clearExpression(selector));
       }),
     select: (selector, values) =>
       guard('select', async () => {
         await init.page.select(selector, ...values);
       }),
     evaluate: (expression) => guard('evaluate', () => init.page.evaluate(expression)),
+    setOfflineMode: (enabled: boolean): Promise<void> =>
+      guard('setOfflineMode', async () => {
+        const source = init.page as { setOfflineMode?: (value: boolean) => Promise<void> };
+        if (typeof source.setOfflineMode !== 'function') {
+          throw scrapeNotImplemented(
+            'setOfflineMode() on a CDP page with no setOfflineMode() method',
+            'upgrade the launcher to a puppeteer-core that exposes page.setOfflineMode(), or drive the condition from the app under test instead of the browser',
+          );
+        }
+        await source.setOfflineMode(enabled);
+      }),
     screenshot: (options: CaptureOptions) =>
       guard('screenshot', async () => {
         // `fullPage` is OMITTED when a clip is given rather than sent as `false`: the two are
@@ -398,7 +432,9 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
           cookies:
             typeof source.cookies === 'function' ? parse(cookieSchema, await source.cookies()) : [],
           headers: {},
-          storage: parse(storageSchema, JSON.parse(typeof storage === 'string' ? storage : '{}')),
+          // `browserRecord` and not `t.record()`: a page may legitimately hold a key called
+          // `constructor`, and the schema refuses that name outright — see `browser-record.ts`.
+          storage: browserRecord(JSON.parse(typeof storage === 'string' ? storage : '{}')),
           userAgent: typeof agent === 'string' ? agent : '',
           origin,
         };

package/src/driver-cdp.ts

@@ -143,6 +143,10 @@ async function sessionOver(
       signal,
       onActivity,
       proxy: options.proxy,
+      // The run's secrets, so the ONE thing this leg quotes from the site — the first 200 bytes
+      // of a non-2xx body, in `X_SCRAPE_HTTP_FAILED`'s cause — cannot carry the password the
+      // login endpoint echoed back. The bag was in scope here and unread.
+      secrets: init.secrets,
     }),
     close: () => guard.shutdown(),
   };