@ultimat3/scraping 2.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "2.0.0",
+  "version": "4.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": "2.0.0",
-    "@ultimat3/jobs": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/storage": "2.0.0"
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/storage": "4.0.0"
   }
 }

package/src/artifacts.ts

@@ -30,17 +30,26 @@ export interface ArtifactWriterInit {
 
 export const DEFAULT_ARTIFACT_PREFIX = 'scrape';
 
-const CONTENT_TYPES: Readonly<Record<string, string>> = {
-  html: 'text/html; charset=utf-8',
-  png: 'image/png',
-  pdf: 'application/pdf',
-  json: 'application/json',
-  csv: 'text/csv',
-  txt: 'text/plain; charset=utf-8',
-};
+export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+
+/**
+ * A `Map`, not an object literal — the same choice `failures.ts` makes, for the same reason. The
+ * extension comes off a caller-supplied filename, and on a download that filename came off the
+ * site's own `Content-Disposition`: indexing a plain object with it answered a FUNCTION for
+ * `report.constructor` and an object for `report.__proto__`, where the type says `string`, and
+ * that non-string went on to be `ref.contentType` and an S3 header.
+ */
+const CONTENT_TYPES: ReadonlyMap<string, string> = new Map([
+  ['html', 'text/html; charset=utf-8'],
+  ['png', 'image/png'],
+  ['pdf', 'application/pdf'],
+  ['json', 'application/json'],
+  ['csv', 'text/csv'],
+  ['txt', 'text/plain; charset=utf-8'],
+]);
 
 export const contentTypeFor = (name: string): string =>
-  CONTENT_TYPES[name.split('.').pop()?.toLowerCase() ?? ''] ?? 'application/octet-stream';
+  CONTENT_TYPES.get(name.split('.').pop()?.toLowerCase() ?? '') ?? DEFAULT_CONTENT_TYPE;
 
 /**
  * A writer with no storage driver is a NO-OP that still answers a key — never a throw. An app

package/src/cdp-target.ts

@@ -1,6 +1,7 @@
 // `ScrapeTarget` over a real browser, through the structural CDP port. Everything driver-specific
 // in this package lives here and in `driver-cdp.ts`; the vocabulary above it does not change.
 
+import { isUltimateError } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
 import type { CdpBrowserLike, CdpFrameLike, CdpPageLike, CdpRequestLike } from './cdp-port';
@@ -87,6 +88,26 @@ const readStringFrom = (owner: unknown, key: string): string | undefined => {
   return typeof answer === 'string' ? answer : undefined;
 };
 
+/**
+ * The one failure `guard()` must NOT re-label, and the line is drawn at exactly one code.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ * `isUltimateError`, not `instanceof`: the brand survives a duplicated module instance.
+ */
+const isStructuralRefusal = (thrown: unknown): boolean =>
+  isUltimateError(thrown) && thrown.code === 'X_NOT_IMPLEMENTED';
+
 export interface CdpTargetInit {
   readonly page: CdpPageLike;
   readonly browser: CdpBrowserLike;
@@ -185,6 +206,7 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       return await run();
     } catch (thrown) {
       live();
+      if (isStructuralRefusal(thrown)) throw thrown;
       throw browserUnreachable(`${CDP_DRIVER} ${what}`, thrown);
     }
   };
@@ -256,15 +278,20 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         }
         return parse(cookieSchema, await source.cookies());
       }),
-    download: (_options): Promise<ScrapeDownloadFile> => {
-      // Honest stub, in the shape `packages/jobs/src/driver-redis.ts` uses. A real one needs
-      // `Browser.setDownloadBehavior` over a raw CDP session plus a directory watch, and a
-      // half-written version that silently returned empty bytes is worse than this line.
-      throw scrapeNotImplemented(
-        'download() on the puppeteer driver',
-        'fetch the file inside the page — page.evaluate("fetch(url).then(r => r.text())") — or run this scrape on fixtureBrowser(), whose download() is complete',
-      );
-    },
+    // Honest stub, in the shape `packages/jobs/src/driver-redis.ts` uses. A real one needs
+    // `Browser.setDownloadBehavior` over a raw CDP session plus a directory watch, and a
+    // half-written version that silently returned empty bytes is worse than this line.
+    //
+    // REJECTS rather than throws: the method is typed `Promise<ScrapeDownloadFile>` and every
+    // caller of a promise-typed method handles its failure with `.catch()` or an `await` inside a
+    // `try` — a synchronous `throw` jumps over the first of those entirely.
+    download: (_options): Promise<ScrapeDownloadFile> =>
+      Promise.reject(
+        scrapeNotImplemented(
+          'download() on the puppeteer driver',
+          'fetch the file inside the page — page.evaluate("fetch(url).then(r => r.text())") — or run this scrape on fixtureBrowser(), whose download() is complete',
+        ),
+      ),
     frames: () =>
       guard('frames', () =>
         Promise.resolve(

package/src/driver-cdp.ts

@@ -67,6 +67,19 @@ async function opened(browser: CdpBrowserLike, init: SessionInit): Promise<Scrap
   }
 }
 
+/**
+ * The run's cancellation and the watchdog's, as ONE signal handed to every wait.
+ *
+ * The guard's abort half had no reader: both legs below were passed `init.signal`, so the
+ * watchdog's only production effect was `kill()` — and `Browser.process()` answers `null` for a
+ * browser obtained through `connect()`, which is `remoteBrowser()`, this file's primary path. A
+ * wedge therefore killed nothing and aborted a signal nobody composed, and the blocked await on
+ * the CDP socket stayed blocked past `ctx.signal` and past the watchdog. Verbatim incident #1 in
+ * `watchdog.ts`, unfixed for the attach path until the composition below.
+ */
+const withWedgeSignal = (run: AbortSignal | undefined, guard: AbortSignal): AbortSignal =>
+  run === undefined ? guard : AbortSignal.any([run, guard]);
+
 async function sessionOver(
   browser: CdpBrowserLike,
   init: SessionInit,
@@ -99,15 +112,21 @@ async function sessionOver(
     guard.touch();
     init.onActivity?.();
   };
+  const signal = withWedgeSignal(init.signal, guard.signal);
   return {
     driver: CDP_DRIVER,
+    // The exit the browser was launched or attached with, handed back so the run's robots read
+    // presents the SAME client identity to the origin the page loads from. `options.proxy` and
+    // not `init.proxy`: this is what the launch args and the HTTP leg below actually carry, and a
+    // reported exit that nothing dialled would be worse than none.
+    ...(options.proxy === undefined ? {} : { proxy: options.proxy }),
     page: pageOverTarget(target, {
       clock: init.clock,
       allowHosts: init.rules.allowHosts,
       defaultTimeoutMs: init.timeoutMs,
       secrets: init.secrets,
       robots: init.robots,
-      signal: init.signal,
+      signal,
       onActivity,
       pace: init.pace,
     }),
@@ -121,7 +140,7 @@ async function sessionOver(
       session: () => target.session(),
       robots: init.robots,
       pace: init.pace,
-      signal: init.signal,
+      signal,
       onActivity,
       proxy: options.proxy,
     }),

package/src/driver.ts

@@ -42,6 +42,15 @@ export interface SessionInit {
 
 export interface ScrapeSession {
   readonly driver: string;
+  /**
+   * The exit this session ACTUALLY dialled — `undefined` for a direct one. Reported because the
+   * proxy is resolved inside `open()`, after the robots gate handed to it was built: without this
+   * the default `/robots.txt` read leaves from the worker's IP while every page load leaves
+   * through the proxy, which is a second client identity presented to the same origin — and an
+   * origin reachable only through the proxy then reads as "no robots.txt", which the gate treats
+   * as allow-everything. A driver that omits it is asked for its rules directly, as before.
+   */
+  readonly proxy?: string | undefined;
   readonly page: ScrapePage;
   /**
    * The second transport, bound to the SAME session as the page: the browser's cookies, headers

package/src/error-throws.ts

@@ -75,6 +75,21 @@ export const notActionable = (selector: string, reason: string, waitedMs: number
     meta: { selector, reason, waitedMs },
   });
 
+/**
+ * Declared, and structurally unable to fire. `maxDrop` is a fraction of a TRAILING MEDIAN, and the
+ * only source of one is a `history:` store — with none, `guardYield` reads an empty array and the
+ * `MIN_BASELINE_RUNS` gate is true forever, so the alarm never raises `X_SCRAPE_YIELD_COLLAPSED`
+ * on any run. Two halves that must be set together, where setting one alone did nothing and
+ * nothing said so.
+ */
+export const yieldHistoryMissing = (scrapeName: string): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_YIELD_HISTORY_MISSING',
+    cause: `scrape "${scrapeName}" declares expect.maxDrop with no history: store, so there is no baseline to measure a drop against and the alarm can never fire`,
+    fix: `add history: memoryYieldHistory() to scrape("${scrapeName}") for a test, or your own YieldHistory in production — or drop expect.maxDrop and keep expect.minRows, which needs no baseline`,
+    meta: { scrape: scrapeName },
+  });
+
 export const scrapeTimeout = (what: string, ms: number): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_TIMEOUT',
@@ -203,6 +218,19 @@ export const httpFailed = (url: string, status: number, body: string): ScrapeErr
     retry: status >= 400 && status < 500 && status !== 429 ? 'terminal' : 'retryable',
   });
 
+/**
+ * The body outgrew its cap. `AbortSignal.timeout` bounds TIME, not bytes — a 30s stream at 50MB/s
+ * is a 1.5GB allocation — so a hostile or merely paginated endpoint could OOM-kill the worker
+ * mid-run, taking every other job on it with it.
+ */
+export const bodyTooLarge = (url: string, readBytes: number, maxBytes: number): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_BODY_TOO_LARGE',
+    cause: `${url} sent more than ${String(maxBytes)} bytes (${String(readBytes)} read before the read was cancelled)`,
+    fix: `raise the cap on this one call — http.request(url, { maxBytes: ${String(maxBytes * 2)} }) — or ask the endpoint for a page instead of the whole collection`,
+    meta: { url, readBytes, maxBytes },
+  });
+
 /**
  * TERMINAL, and the retry table cannot be talked out of it. A site that locks an account after
  * three wrong attempts turns a retrying framework into the thing that destroys the user's

package/src/errors.ts

@@ -25,6 +25,7 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_PAGE_CRASHED',
   'X_SCRAPE_OUTPUT_INVALID',
   'X_SCRAPE_YIELD_COLLAPSED',
+  'X_SCRAPE_YIELD_HISTORY_MISSING',
   'X_SCRAPE_DOWNLOAD_TIMEOUT',
   'X_SCRAPE_ROBOTS_DISALLOWED',
   'X_SCRAPE_FIXTURE_MISSING',
@@ -33,6 +34,7 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_RECOVER_REFUSED',
   'X_SCRAPE_SECRET_EXPOSED',
   'X_SCRAPE_HTTP_FAILED',
+  'X_SCRAPE_BODY_TOO_LARGE',
   'X_SCRAPE_AUTH_FAILED',
   'X_SCRAPE_SESSION_EXPIRED',
   'X_SCRAPE_PROMPT_UNANSWERED',
@@ -69,6 +71,8 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_PAGE_CRASHED: 'the renderer process died',
   X_SCRAPE_OUTPUT_INVALID: 'the extracted rows do not match the extract schema',
   X_SCRAPE_YIELD_COLLAPSED: 'the run succeeded and returned far too little',
+  X_SCRAPE_YIELD_HISTORY_MISSING:
+    'a maxDrop is declared and no history store can supply its baseline',
   X_SCRAPE_DOWNLOAD_TIMEOUT: 'the download never landed',
   X_SCRAPE_ROBOTS_DISALLOWED: 'robots.txt disallows this path',
   X_SCRAPE_FIXTURE_MISSING: 'the fixture driver has no recording for this request',
@@ -77,6 +81,7 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_RECOVER_REFUSED: 'the recovery hook declined to recover this failure',
   X_SCRAPE_SECRET_EXPOSED: 'an artifact would have carried a secret this run typed',
   X_SCRAPE_HTTP_FAILED: 'the site answered the HTTP leg with a non-2xx status',
+  X_SCRAPE_BODY_TOO_LARGE: 'the HTTP response body passed its byte cap',
   X_SCRAPE_AUTH_FAILED: 'the credentials were rejected',
   X_SCRAPE_SESSION_EXPIRED: 'the restored session is no longer valid and nothing can renew it',
   X_SCRAPE_PROMPT_UNANSWERED: 'a login step asked for a code and nothing answered',
@@ -126,7 +131,13 @@ export const SCRAPE_ERROR_RETRY = {
   // half-submitted form is the incident, not the recovery.
   X_SCRAPE_PAGE_CRASHED: 'terminal',
   X_SCRAPE_OUTPUT_INVALID: 'terminal',
+  // A response size is a property of the endpoint, not of the moment: attempt 2 buffers the same
+  // gigabyte and dies the same way. The fix is a number on the request, so a human decides it.
+  X_SCRAPE_BODY_TOO_LARGE: 'terminal',
   X_SCRAPE_YIELD_COLLAPSED: 'terminal',
+  // A declaration error, raised by `scrape()` before any attempt exists — there is no run to
+  // retry, and the same definition would refuse identically forever.
+  X_SCRAPE_YIELD_HISTORY_MISSING: 'terminal',
   X_SCRAPE_ROBOTS_DISALLOWED: 'terminal',
   X_SCRAPE_FIXTURE_MISSING: 'terminal',
   X_SCRAPE_FIXTURE_STALE: 'terminal',

package/src/html-target.ts

@@ -49,6 +49,18 @@ export interface HtmlTargetInit {
 
 const EMPTY: PageRecording = { url: 'about:blank', html: '' };
 
+/**
+ * A recorded map, read by a key that came out of the RECORDING's own markup — a selector, an
+ * expression, an `<iframe name>`. Plain indexing walks the prototype chain, so `name="constructor"`
+ * resolved to `Object` rather than to `undefined` and `fixtureMissing` never threw; the run then
+ * carried a function where an HTML string belongs. Offline driver only, and it is still worth
+ * closing: the confusing test failure it produces costs more to read than this line does.
+ */
+const recorded = (
+  map: Readonly<Record<string, string>> | undefined,
+  key: string,
+): string | undefined => (map !== undefined && Object.hasOwn(map, key) ? map[key] : undefined);
+
 /** Typed text is an overlay keyed by `id`, then `name`, then the selector used to type it. */
 const keyOf = (selector: string, element: ElementSnapshot | undefined): string => {
   if (element === undefined) return selector;
@@ -159,10 +171,11 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
       return Promise.resolve(page.html);
     },
     query,
-    async click(selector: string, index: number): Promise<void> {
-      const element = await at(selector, index);
+    async click(selector: string): Promise<void> {
+      const element = await at(selector, 0);
       if (element === undefined) throw fixtureMissing(`${page.url} ${selector}`, init.source);
-      const download = page.downloads?.[selector] ?? page.downloads?.[element.attrs['id'] ?? ''];
+      const download =
+        recorded(page.downloads, selector) ?? recorded(page.downloads, element.attrs['id'] ?? '');
       if (download !== undefined) armed = download;
       const href =
         element.attrs['data-goto'] ?? (element.tag === 'a' ? element.attrs['href'] : undefined);
@@ -181,12 +194,12 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     },
     evaluate(expression: string): Promise<unknown> {
       live();
-      const recorded = page.evaluate?.[expression];
+      const answer = recorded(page.evaluate, expression);
       // Unrecorded and therefore refused, for the same reason an unrecorded page is: an offline
       // driver that invented an answer here would make the assertion above it meaningless.
-      if (recorded === undefined)
+      if (answer === undefined)
         throw fixtureMissing(`${page.url} evaluate(${expression})`, init.source);
-      return Promise.resolve(JSON.parse(recorded) as unknown);
+      return Promise.resolve(JSON.parse(answer) as unknown);
     },
     screenshot: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PNG),
     pdf: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PDF),
@@ -196,18 +209,20 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
       session = next;
       return Promise.resolve();
     },
-    download(options: { readonly timeoutMs: number }): Promise<ScrapeDownloadFile> {
+    // `async`, so the refusal REJECTS: the method is typed `Promise<ScrapeDownloadFile>` and a
+    // synchronous `throw` from one escapes past `download().catch(…)` at every caller.
+    async download(options: { readonly timeoutMs: number }): Promise<ScrapeDownloadFile> {
       if (armed === undefined) throw downloadTimeout(options.timeoutMs, page.url);
       const { filename, contents } = splitDownload(armed);
       armed = undefined;
-      return Promise.resolve({ filename, bytes: new TextEncoder().encode(contents) });
+      return { filename, bytes: new TextEncoder().encode(contents) };
     },
     async frames(): Promise<readonly FrameRef[]> {
       const refs: FrameRef[] = [];
       for (const element of await queryHtml(page.html, 'iframe')) {
         const name = element.attrs['name'] ?? element.attrs['id'] ?? '';
         const src = element.attrs['src'] ?? '';
-        const html = page.frames?.[name] ?? page.frames?.[src];
+        const html = recorded(page.frames, name) ?? recorded(page.frames, src);
         if (html === undefined)
           throw fixtureMissing(`${page.url} iframe ${name || src}`, init.source);
         const url = src === '' ? page.url : new URL(src, page.url).toString();

package/src/http.ts

@@ -10,25 +10,57 @@
 // 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 type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse } from '@ultimat3/schema';
 import type { ScrapeClock } from './clock';
 import { cookieHeaderFor } from './cookie-scope';
-import { hostBlocked, httpFailed, scrapeTimeout } from './error-throws';
+import { bodyTooLarge, hostBlocked, httpFailed, scrapeTimeout } from './error-throws';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict } from './intercept';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
 import type { SessionSnapshot } from './session-state';
 
+/**
+ * Just the call. `typeof fetch` also carries `preconnect`, which no test double and no app wrapper
+ * can supply — so an option typed `typeof fetch` was unusable without a double cast, which is
+ * exactly what every caller of it had written. The same seam `@ultimat3/cache`, `@ultimat3/auth`
+ * and `@ultimat3/mail` already name.
+ */
+export type ScrapeFetch = (input: string, init: ScrapeFetchInit) => Promise<Response>;
+
+/**
+ * `RequestInit` plus the one Bun extension this package sets. Named rather than cast: the DOM's
+ * `RequestInit` has no `proxy`, and an `as RequestInit` over the literal silenced the excess-key
+ * check for `proxy` AND for every neighbouring key it was standing next to.
+ */
+export interface ScrapeFetchInit extends RequestInit {
+  /** The session's exit. A different exit IP mid-session is a different client to an anti-bot. */
+  readonly proxy?: string | undefined;
+}
+
 export interface HttpRequestInit {
   readonly method?: string | undefined;
   readonly headers?: Readonly<Record<string, string>> | undefined;
   readonly body?: string | undefined;
   /** Milliseconds. Falls back to the session's own default. */
   readonly timeout?: number | undefined;
+  /**
+   * Response-body ceiling in bytes. Falls back to `DEFAULT_HTTP_MAX_BYTES`. Never absent: a
+   * deadline bounds time and a scraped endpoint is somebody else's, so the only thing standing
+   * between a hostile stream and the worker's heap is a number.
+   */
+  readonly maxBytes?: number | undefined;
 }
 
+/**
+ * Generous for the JSON endpoint behind a paginated page — the reason this transport exists — and
+ * far under what OOM-kills a worker. Raised per call with `{ maxBytes }`, never globally: a run
+ * that genuinely pulls a large export says so at the call site that pulls it.
+ */
+export const DEFAULT_HTTP_MAX_BYTES = 32 * 1024 * 1024;
+
 export interface ScrapeResponse {
   readonly url: string;
   readonly status: number;
@@ -66,13 +98,26 @@ 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;
-  readonly fetch?: typeof fetch | undefined;
+  readonly fetch?: ScrapeFetch | undefined;
 }
 
+/**
+ * Response headers as data, on a NULL prototype and written with `defineProperty`.
+ *
+ * The header set on a scraping leg is entirely the site's. `out[key] = value` on a plain object
+ * DROPS `__proto__` — a legal HTTP field-name token — because the setter it hits refuses a string
+ * and files no own key, and it leaves `headers['toString']` answering a function the site never
+ * sent. Both make `Readonly<Record<string, string>>` a lie the caller cannot see through.
+ */
 const headerRecord = (headers: Headers): Record<string, string> => {
-  const out: Record<string, string> = {};
+  const out = Object.create(null) as Record<string, string>;
   headers.forEach((value, key) => {
-    out[key] = value;
+    Object.defineProperty(out, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
   });
   return out;
 };
@@ -105,7 +150,7 @@ export function responseOver(
  * robots rule, and neither is re-implemented for the second leg.
  */
 export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
-  const call = init.fetch ?? fetch;
+  const call: ScrapeFetch = init.fetch ?? fetch;
   return {
     async request(url: string, request: HttpRequestInit = {}): Promise<ScrapeResponse> {
       init.onActivity?.();
@@ -135,7 +180,7 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
           ...(request.body === undefined ? {} : { body: request.body }),
           signal: AbortSignal.any(signals),
           ...(init.proxy === undefined ? {} : { proxy: init.proxy }),
-        } as RequestInit);
+        });
         init.network.push({
           method: request.method ?? 'GET',
           url,
@@ -143,7 +188,13 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
           resourceType: 'fetch',
           at: init.clock.now().getTime(),
         });
-        const body = await response.text();
+        // 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);
         return responseOver(url, response.status, headerRecord(response.headers), () =>
           Promise.resolve(body),
         );

package/src/index.ts

@@ -5,7 +5,12 @@
 export type { ActionabilityState, ActionabilityWait } from './actionability';
 export { actionabilityProblem, awaitActionable, DEFAULT_POLL_MS, isStable } from './actionability';
 export type { ArtifactRef, ArtifactWriter, ArtifactWriterInit } from './artifacts';
-export { contentTypeFor, createArtifactWriter, DEFAULT_ARTIFACT_PREFIX } from './artifacts';
+export {
+  contentTypeFor,
+  createArtifactWriter,
+  DEFAULT_ARTIFACT_PREFIX,
+  DEFAULT_CONTENT_TYPE,
+} from './artifacts';
 export type {
   AuthContext,
   PromptHandler,
@@ -42,6 +47,7 @@ export { FIXTURE_DRIVER, fixtureBrowser, recordingFilename } from './driver-fixt
 export {
   authFailed,
   blocked,
+  bodyTooLarge,
   browserUnreachable,
   cdpAttachFailed,
   downloadTimeout,
@@ -97,7 +103,7 @@ export { markupRequests } from './html-requests';
 export type { HtmlTargetInit, RecordingLookup } from './html-target';
 export { htmlTarget } from './html-target';
 export type { HttpRequestInit, HttpTransportInit, ScrapeHttp, ScrapeResponse } from './http';
-export { httpOverFetch, responseOver } from './http';
+export { DEFAULT_HTTP_MAX_BYTES, httpOverFetch, responseOver } from './http';
 export type { HttpRecordingLookup, RecordedHttpInit } from './http-recorded';
 export { httpRecordingFilename, httpRecordingsOf, recordedHttp } from './http-recorded';
 export type { InterceptRules, InterceptVerdict } from './intercept';
@@ -137,6 +143,12 @@ export type {
 export { createRing, DEFAULT_RING_CAPACITY, RESOURCE_TYPES } from './rings';
 export type { RobotsFetch, RobotsGate, RobotsGateInit, RobotsPolicy, RobotsRules } from './robots';
 export { createRobotsGate, DEFAULT_ROBOTS_AGENT, parseRobots, robotsAllows } from './robots';
+export type { RobotsFetchInit } from './robots-fetch';
+export {
+  DEFAULT_ROBOTS_MAX_BYTES,
+  DEFAULT_ROBOTS_TIMEOUT_MS,
+  robotsFetcher,
+} from './robots-fetch';
 export type {
   ScrapeArtifacts,
   ScrapeDefinition,

package/src/page-over-target.ts

@@ -105,7 +105,7 @@ function frameOver(
     waitFor: (selector, options) => wait(selector, options, 'actionable'),
     async click(selector, options): Promise<void> {
       await wait(selector, options, 'actionable');
-      await (await resolve()).click(selector, 0);
+      await (await resolve()).click(selector);
     },
     async type(selector, text, options): Promise<void> {
       await wait(selector, options, 'actionable');
@@ -187,8 +187,7 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     // in object storage, forever. Refused rather than masked — a mask over pixels is a guess
     // about layout, and `page.html()` already gives a redacted artifact that is exact.
     if (state.tainted) throw secretExposed(kind, target.url());
-    const timeoutMs = options?.timeout ?? ctx.defaultTimeoutMs;
-    const request = { fullPage: options?.fullPage, timeoutMs };
+    const request = { fullPage: options?.fullPage };
     return kind === 'screenshot' ? target.screenshot(request) : target.pdf(request);
   };
   return {
@@ -204,8 +203,12 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     },
     screenshot: (options) => capture('screenshot', options),
     pdf: (options) => capture('pdf', options),
-    download: (options?: DownloadRequest): Promise<ScrapeDownloadFile> =>
-      target.download({ timeoutMs: options?.timeout ?? ctx.defaultTimeoutMs }),
+    // `async`, and that is the whole point of the keyword here: `ScrapeTarget` is the seam a third
+    // party implements, and a driver that THROWS from its promise-typed `download()` would escape
+    // past this page's caller `.catch()` if the forward were a bare arrow.
+    async download(options?: DownloadRequest): Promise<ScrapeDownloadFile> {
+      return await target.download({ timeoutMs: options?.timeout ?? ctx.defaultTimeoutMs });
+    },
     cookies: (): Promise<readonly ScrapeCookie[]> => target.cookies(),
     session: () => target.session(),
     console: () => target.console.entries(),

package/src/page.ts

@@ -64,9 +64,9 @@ export interface ScrapeFrame {
   frame(nameOrSelector: string): ScrapeFrame;
 }
 
+/** `fullPage` only. `timeout` is gone with the port's — see `CaptureOptions` for why. */
 export interface CaptureRequest {
   readonly fullPage?: boolean | undefined;
-  readonly timeout?: number | undefined;
 }
 
 export interface DownloadRequest {

package/src/robots-fetch.ts

@@ -0,0 +1,82 @@
+// The ONE `/robots.txt` read the gate performs when the caller injects no `fetchText`.
+//
+// It exists as its own file because the production default was the only network call in this
+// package with no deadline, no size cap and no proxy — and `scrape-run.ts` builds the gate with no
+// `fetchText`, so production always took it. Every existing gate test injected one, which is how a
+// read that could park a run forever stayed green.
+//
+// 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 type { ScrapeFetch } from './http';
+import type { RobotsFetch } from './robots';
+
+/**
+ * A deadline is applied ALWAYS, proxy or no proxy, session or no session: the failure it prevents
+ * is a hung origin whose cached promise then parks every later navigation to that origin, past
+ * `ctx.signal`, the watchdog and the job timeout. Ten seconds is long for a static text file and
+ * short against a slow-loris.
+ */
+export const DEFAULT_ROBOTS_TIMEOUT_MS = 10_000;
+
+/** Google's own documented ceiling for the file, and generous for a list of path prefixes. */
+export const DEFAULT_ROBOTS_MAX_BYTES = 500 * 1024;
+
+export interface RobotsFetchInit {
+  /** Per-read wall clock. Defaults to `DEFAULT_ROBOTS_TIMEOUT_MS`. */
+  readonly timeoutMs?: number | undefined;
+  /** The run's cancellation, when there is one. Composed with the deadline, never replacing it. */
+  readonly signal?: AbortSignal | undefined;
+  /**
+   * The SAME proxy the browser dialled through, when the session has one — asked PER READ, never
+   * captured. A resolver rather than a string because construction order forbids the string: the
+   * gate is an argument to `driver.open()` and the proxy is a driver option resolved inside it,
+   * so a value passed here could only ever be the one nobody has yet. That is how the robots read
+   * came to exit from the worker's IP while every page load exited through the proxy — and how an
+   * origin reachable ONLY through the proxy read as "no robots.txt", which is allow-everything.
+   *
+   * Optional by design: proxies are an opt-in leg, and an origin reachable directly must still be
+   * asked for its rules.
+   */
+  readonly proxy?: (() => string | undefined) | undefined;
+  readonly maxBytes?: number | undefined;
+  /**
+   * The platform `fetch`, injectable so the default path itself is testable. `ScrapeFetch` and not
+   * `typeof fetch`: the latter also carries `preconnect`, so nothing a caller can write satisfies
+   * it and the option was reachable only through a cast.
+   */
+  readonly fetch?: ScrapeFetch | undefined;
+}
+
+/**
+ * Reads `robotsUrl`, or answers `undefined` — which the gate reads as "no restrictions", the
+ * standard's own answer for a file it cannot obtain. A deadline that fires, a body past the cap
+ * and a 404 are all the same answer on purpose: none of them is evidence of a rule.
+ */
+export function robotsFetcher(init: RobotsFetchInit = {}): RobotsFetch {
+  const call: ScrapeFetch = init.fetch ?? fetch;
+  const limit = init.maxBytes ?? DEFAULT_ROBOTS_MAX_BYTES;
+  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 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.
+    const proxy = init.proxy?.();
+    try {
+      const response = await call(robotsUrl, {
+        signal,
+        ...(proxy === undefined || proxy === '' ? {} : { proxy }),
+      });
+      if (!response.ok) return undefined;
+      // Counted as it arrives rather than `.text()`, which materialises the whole body first: a
+      // multi-gigabyte robots.txt is a heap the worker never gets back.
+      const capped = await readWithinLimit(response.body, limit);
+      return 'over' in capped ? undefined : new TextDecoder().decode(capped.bytes);
+    } catch {
+      return undefined;
+    }
+  };
+}

package/src/robots.ts

@@ -6,6 +6,8 @@
 // There is no boolean, because `robots: false` is a decision with no author.
 
 import { robotsDisallowed } from './error-throws';
+import type { RobotsFetchInit } from './robots-fetch';
+import { robotsFetcher } from './robots-fetch';
 
 export type RobotsPolicy = 'obey' | { readonly ignore: string };
 
@@ -56,14 +58,47 @@ export function parseRobots(text: string, agent: string): RobotsRules {
   return { rules: groups.get(wanted) ?? groups.get('*') ?? [] };
 }
 
-const escaped = (literal: string): string => literal.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-/** `/private/*.pdf$` — the two wildcards robots.txt defines, and no others. */
+/**
+ * `/private/*.pdf$` — the two wildcards robots.txt defines, and no others, matched by WALKING the
+ * pattern rather than by compiling one.
+ *
+ * The rule text is remote: robots.txt belongs to the site being scraped, and `robotsAllows` runs on
+ * every navigation and every HTTP-leg request, synchronously, on the worker's only thread. A regex
+ * built as `body.split('*').join('.*')` backtracks catastrophically on a non-matching path — a rule
+ * with 24 wildcards did not return inside 60s, past `ctx.signal`, the watchdog and the job timeout,
+ * all of which are downstream of a `return` that never happens. This walk is O(pattern × path) with
+ * no backtracking beyond the LAST star, so the class is removed rather than bounded.
+ */
 const patternMatches = (pattern: string, path: string): boolean => {
   const anchored = pattern.endsWith('$');
-  const body = anchored ? pattern.slice(0, -1) : pattern;
-  const source = body.split('*').map(escaped).join('.*');
-  return new RegExp(`^${source}${anchored ? '$' : ''}`).test(path);
+  // Unanchored means "matches a PREFIX of the path", which is the same statement as a full match
+  // against the pattern with one more `*` on the end — one code path instead of two.
+  const body = anchored ? pattern.slice(0, -1) : `${pattern}*`;
+  let p = 0;
+  let s = 0;
+  let star = -1;
+  let resume = 0;
+  while (s < path.length) {
+    if (p < body.length && body[p] === '*') {
+      star = p;
+      p += 1;
+      resume = s;
+      continue;
+    }
+    if (p < body.length && body[p] === path[s]) {
+      p += 1;
+      s += 1;
+      continue;
+    }
+    if (star === -1) return false;
+    // Only the most recent star is ever retried, which is what keeps this linear per star instead
+    // of exponential across all of them.
+    p = star + 1;
+    resume += 1;
+    s = resume;
+  }
+  while (p < body.length && body[p] === '*') p += 1;
+  return p === body.length;
 };
 
 /**
@@ -93,14 +128,10 @@ export interface RobotsGate {
 
 export type RobotsFetch = (robotsUrl: string) => Promise<string | undefined>;
 
-const fetchRobots: RobotsFetch = async (robotsUrl) => {
-  const response = await fetch(robotsUrl);
-  return response.ok ? await response.text() : undefined;
-};
-
-export interface RobotsGateInit {
+export interface RobotsGateInit extends RobotsFetchInit {
   readonly policy: RobotsPolicy;
   readonly agent?: string | undefined;
+  /** A caller-supplied read. With none, `robotsFetcher` builds the deadlined, capped default. */
   readonly fetchText?: RobotsFetch | undefined;
 }
 
@@ -116,7 +147,7 @@ export function createRobotsGate(init: RobotsGateInit): RobotsGate {
     return { assertAllowed: () => Promise.resolve(), ignoredBecause: init.policy.ignore };
   }
   const agent = init.agent ?? DEFAULT_ROBOTS_AGENT;
-  const read = init.fetchText ?? fetchRobots;
+  const read = init.fetchText ?? robotsFetcher(init);
   const cache = new Map<string, Promise<RobotsRules>>();
   return {
     ignoredBecause: undefined,

package/src/scrape-run.ts

@@ -94,18 +94,36 @@ 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);
+  // 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
+  // navigation, which is after this is assigned.
+  let sessionProxy: string | undefined;
   const session = await driver.open({
     name: definition.name,
     rules,
     clock,
-    timeoutMs: toMillis(definition.pageTimeout, DEFAULT_PAGE_TIMEOUT_MS),
+    timeoutMs: pageTimeoutMs,
     secrets,
-    robots: createRobotsGate({ policy: definition.robots ?? 'obey' }),
+    // The gate reads `/robots.txt` over the network, so it gets the run's deadline, the run's
+    // cancellation and the run's exit, like every other call this package makes. Without the
+    // first two a hung origin parks every later navigation to it on one cached promise,
+    // unreachable by `ctx.signal`; without the third the read leaves from a different IP than
+    // every page load, and an origin reachable only through the proxy answers nothing — which
+    // this gate reads as "no restrictions".
+    robots: createRobotsGate({
+      policy: definition.robots ?? 'obey',
+      timeoutMs: pageTimeoutMs,
+      signal: args.ctx.signal,
+      proxy: () => sessionProxy,
+    }),
     signal: args.ctx.signal,
     restore: restored,
     pace: (signal) => pace(signal),
     watchdog: definition.watchdog,
   });
+  sessionProxy = session.proxy;
 
   try {
     if (definition.auth !== undefined) {
@@ -155,8 +173,11 @@ export async function runScrape<I, Row>(
     };
   } catch (thrown) {
     logger.error('scrape.failed', { code: errorCode(thrown) });
-    if (errorCode(thrown) === 'X_SCRAPE_AUTH_FAILED') await markRefused(plan);
-    else if (burnsSession(thrown)) await burnSession(plan);
+    if (errorCode(thrown) === 'X_SCRAPE_AUTH_FAILED') {
+      await recordSessionOutcome('session.refuse', logger, () => markRefused(plan));
+    } else if (burnsSession(thrown)) {
+      await recordSessionOutcome('session.burn', logger, () => burnSession(plan));
+    }
     if (definition.artifacts?.onFailure !== false) await saveFailureArtifact(session, artifact);
     throw thrown;
   } finally {
@@ -165,6 +186,29 @@ export async function runScrape<I, Row>(
   }
 }
 
+/**
+ * The tombstone or the burn, on the way out — best effort, and it may NEVER replace the failure
+ * that caused it. `markRefused` reaches `store.save()` reaches `storage.put()`, so an S3 503 or an
+ * `X_STORAGE_PATH_UNSAFE` from a tenant whose key sanitises to nothing used to propagate out of
+ * the catch and REPLACE a terminal `X_SCRAPE_AUTH_FAILED` with a retryable one. Attempt 2 then
+ * found no tombstone — the save is what failed — and walked the same rejected password back to
+ * the login form; attempt 3 locks the account. Same rule as `saveFailureArtifact`, and the same
+ * reason: the run's own error is the one the reader needs.
+ */
+async function recordSessionOutcome(
+  step: 'session.refuse' | 'session.burn',
+  logger: ReturnType<typeof scrapeLogger>,
+  write: () => Promise<void>,
+): Promise<void> {
+  try {
+    await write();
+  } catch (thrown) {
+    // Logged rather than swallowed silently: the tombstone is missing, so the NEXT attempt will
+    // re-probe rather than refuse cheaply, and that is a fact an operator has to be able to see.
+    logger.error('scrape.session.write_failed', { step, code: errorCode(thrown) });
+  }
+}
+
 /**
  * The body, with at most ONE recovery pass. `recover` never runs for a failure that must not be
  * retried — a rejected credential is the case, and asking a model to "fix" a wrong password is

package/src/scrape.ts

@@ -18,6 +18,7 @@ import type { ArtifactWriter } from './artifacts';
 import type { PromptHandler, ScrapeAuth } from './auth';
 import type { ScrapeClock } from './clock';
 import type { ScrapeDriver } from './driver';
+import { yieldHistoryMissing } from './error-throws';
 import type { YieldExpectation, YieldHistory } from './expect';
 import type { HostRule } from './hosts';
 import type { ScrapeHttp } from './http';
@@ -137,6 +138,12 @@ export function scrape<I, Row>(definition: ScrapeDefinition<I, Row>): JobHandle<
     `scrape "${definition.name}" declares rate: ${String(definition.rate)} — a rate is navigations per second, greater than zero`,
     `set rate: 1 on scrape("${definition.name}"), or leave it out — to go faster raise the number, there is no unpaced mode`,
   );
+  // Two halves that must be set together. `maxDrop` is a fraction of a trailing median and only
+  // `history:` can supply one, so declaring it alone is an alarm that cannot fire — refused here,
+  // where it is written, rather than discovered as a scrape that never once went red.
+  if (definition.expect?.maxDrop !== undefined && definition.history === undefined) {
+    throw yieldHistoryMissing(definition.name);
+  }
   return job<I>({
     name: definition.name,
     input: definition.input,

package/src/secrets.ts

@@ -78,11 +78,25 @@ export function redactSecrets(text: string, secrets: ScrapeSecrets | undefined):
   return out;
 }
 
-/** `<input type="password" value="hunter2">` -> `value=""`, whatever the value happened to be. */
+/** 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. */
+const PASSWORD_TYPE = /\btype\s*=\s*(?:"password"|'password'|password)(?=[\s/>])/i;
+const VALUE_ATTR = /\bvalue\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*)/gi;
+
+/**
+ * `<input type="password" value="hunter2">` -> `value=""`, whatever the value happened to be —
+ * and whatever ORDER the site wrote the attributes in.
+ *
+ * One regex over the whole tag required `type` to precede `value`, so `<input value="hunter2"
+ * type="password">` came through untouched. Attribute order is the site's choice, and
+ * `saveFailureArtifact` writes `page.html()` to object storage on every failed run: a
+ * server-rendered password on a reversed-attribute form was durably persisted. So: match the TAG
+ * first, then rewrite `value` inside it.
+ */
 export function blankPasswordFields(html: string): string {
-  return html.replaceAll(
-    /(<input\b[^>]*\btype\s*=\s*['"]?password['"]?[^>]*?)\bvalue\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*)/gi,
-    '$1value=""',
+  return html.replaceAll(INPUT_TAG, (tag) =>
+    PASSWORD_TYPE.test(tag) ? tag.replaceAll(VALUE_ATTR, 'value=""') : tag,
   );
 }
 

package/src/session-state.ts

@@ -157,11 +157,35 @@ export function storageSessionStore(
   };
 }
 
-const isCookie = (value: unknown): value is ScrapeCookie =>
-  typeof value === 'object' &&
-  value !== null &&
-  typeof (value as { name?: unknown }).name === 'string' &&
-  typeof (value as { value?: unknown }).value === 'string';
+/**
+ * A stored cookie is somebody else's JSON. `name` and `value` are what makes it a cookie at all;
+ * the four scope fields `ScrapeCookie` REQUIRES are completed here rather than asserted.
+ *
+ * Asserting them was the bug: this was a `value is ScrapeCookie` predicate that checked two of
+ * that type's six required fields, so a stored `{ name, value }` left `parseSessionState` typed as
+ * a whole cookie with no `domain` — and `cookieHeaderFor`, a public export, hands it to
+ * `cookieDomainMatches`, which calls `.trim()` on it and throws a bare `TypeError`.
+ *
+ * The defaults are the ones `cookie-scope.ts` already documents. An empty `domain` matches NO
+ * host, which is the point: an unscoped cookie must reach nothing, because the only other way to
+ * scope it is to infer the domain from whichever URL is asking, and that is exactly how a
+ * `bank.test` session cookie reaches `evilbank.test`. `/` is §5.1.4's reading of an absent path,
+ * and an attribute a jar never wrote is `false`.
+ */
+const toCookie = (value: unknown): ScrapeCookie | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const entry = value as Partial<ScrapeCookie>;
+  if (typeof entry.name !== 'string' || typeof entry.value !== 'string') return undefined;
+  return {
+    name: entry.name,
+    value: entry.value,
+    domain: typeof entry.domain === 'string' ? entry.domain : '',
+    path: typeof entry.path === 'string' ? entry.path : '/',
+    ...(typeof entry.expires === 'number' ? { expires: entry.expires } : {}),
+    httpOnly: entry.httpOnly === true,
+    secure: entry.secure === true,
+  };
+};
 
 /** Stored JSON is `unknown`. Read structurally, and answer `undefined` rather than half a session. */
 export function parseSessionState(raw: unknown, key: string): SessionState | undefined {
@@ -172,7 +196,7 @@ export function parseSessionState(raw: unknown, key: string): SessionState | und
     key,
     savedAt: value.savedAt,
     ...(typeof value.refusedAt === 'string' ? { refusedAt: value.refusedAt } : {}),
-    cookies: value.cookies.filter((cookie): cookie is ScrapeCookie => isCookie(cookie)),
+    cookies: value.cookies.flatMap((cookie: unknown) => toCookie(cookie) ?? []),
     headers: value.headers ?? {},
     storage: value.storage ?? {},
     userAgent: value.userAgent ?? '',

package/src/target.ts

@@ -74,9 +74,17 @@ export interface GotoOptions {
   readonly signal?: AbortSignal | undefined;
 }
 
+/**
+ * `fullPage` and nothing else. It carried a required `timeoutMs` until 2026-08 that NO driver
+ * honoured — `cdp-target.ts` read only `fullPage`, `html-target.ts` ignored the whole object —
+ * so `page.screenshot({ timeout })` was a documented deadline that bounded nothing. Deleted
+ * rather than implemented: the CDP port's own `screenshot({ fullPage })` has no timeout slot to
+ * forward it to, and a deadline enforced in `page-over-target.ts` would have to race
+ * `ScrapeClock.sleep`, which under `testClock` resolves on the first microtask and would time
+ * out every capture in every test. A driver's own default is the honest bound.
+ */
 export interface CaptureOptions {
   readonly fullPage?: boolean | undefined;
-  readonly timeoutMs: number;
 }
 
 /**
@@ -93,7 +101,16 @@ export interface ScrapeTarget {
   /** Serialised HTML of THIS target — the document for a page, the subtree for a frame. */
   content(): Promise<string>;
   query(selector: string): Promise<readonly ElementSnapshot[]>;
-  click(selector: string, index: number): Promise<void>;
+  /**
+   * Clicks the FIRST match. It took an `index` until 2026-08 that `html-target.ts` honoured and
+   * `cdp-target.ts` dropped — its implementations are `click: (selector) => …`, so puppeteer
+   * clicked match 0 whatever was asked. They agreed only because `page-over-target.ts`, the sole
+   * caller, always passed `0`, and no public vocabulary could set it: `ScrapeFrame.click` takes
+   * `(selector, options?: WaitOptions)`. A port member no app can reach and one driver ignores is
+   * a divergence waiting to be found by an app, so it is gone. `driver-parity.test.ts` pins that
+   * all three drivers click the first match.
+   */
+  click(selector: string): Promise<void>;
   /** Appends, exactly as typing does. Clearing first is `fill`'s job at the page level. */
   type(selector: string, text: string): Promise<void>;
   clear(selector: string): Promise<void>;