@ultimat3/scraping 2.0.0

package/src/clock.ts

@@ -0,0 +1,97 @@
+// The ONE file in this package allowed to make time pass. Every wait a scraper does — the
+// actionability poll, the wedge watchdog, the rate limiter, the graceful-quit ceiling — goes
+// through `ScrapeClock`, so a suite that exercises a 30-second timeout finishes in microseconds.
+//
+// `clock-discipline.test.ts` fails the build if a second file reaches for a timer directly.
+
+import type { Clock } from '@ultimat3/core';
+
+export interface ScrapeClock extends Clock {
+  /**
+   * Resolve after `ms` of this clock's time, or reject with the signal's reason the moment it
+   * aborts. Every poll loop here composes a wait with a cancellation, so a clock whose sleep
+   * ignored the signal would leave a killed run still counting.
+   */
+  sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+
+export const systemScrapeClock: ScrapeClock = Object.freeze({
+  now(): Date {
+    return new Date();
+  },
+  monotonic(): number {
+    return performance.now();
+  },
+  async sleep(ms: number, signal?: AbortSignal): Promise<void> {
+    if (signal === undefined) {
+      await Bun.sleep(ms);
+      return;
+    }
+    throwIfAborted(signal);
+    // A timer raced against the signal, never `Bun.sleep(ms).then(check)`: the watchdog aborts a
+    // wedged run precisely so nothing waits out the rest of a five-minute budget, and a sleep
+    // that only notices the abort when it expires would wait out every one of them.
+    await new Promise<void>((resolve, reject) => {
+      // The reason is rejected VERBATIM, never wrapped: whoever aborted put a `ScrapeError` with
+      // a code and a fix there, and re-wrapping it would replace an instruction with `Error`.
+      const onAbort = (): void => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      };
+      const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort);
+        resolve();
+      }, ms);
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+  },
+});
+
+/** The abort reason, unwrapped — a caller's `AbortSignal.reason` is whatever they put there. */
+export function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw signal.reason;
+}
+
+/**
+ * A clock in which sleeping IS advancing: `await clock.sleep(30_000)` returns on the next
+ * microtask with thirty seconds elapsed. This is what makes a poll-until-deadline test instant
+ * without the test knowing how many polls the loop makes — a count a test that asserted it would
+ * pin to the implementation rather than to the behaviour.
+ */
+export interface TestScrapeClock extends ScrapeClock {
+  advance(ms: number): void;
+}
+
+export function testClock(at: Date | number = 0): TestScrapeClock {
+  let epochMs = at instanceof Date ? at.getTime() : at;
+  let mono = 0;
+  const advance = (ms: number): void => {
+    epochMs += ms;
+    mono += ms;
+  };
+  return {
+    now: () => new Date(epochMs),
+    monotonic: () => mono,
+    advance,
+    sleep: async (ms: number, signal?: AbortSignal) => {
+      advance(ms);
+      // Yield the microtask queue anyway: a loop that never awaits anything real starves whatever
+      // the test armed to cancel it, and the wedge tests arm exactly that.
+      await Promise.resolve();
+      if (signal !== undefined) throwIfAborted(signal);
+    },
+  };
+}
+
+/** Elapsed-time budget, read from one clock. Built once per waiting call, never shared. */
+export interface Deadline {
+  readonly totalMs: number;
+  remainingMs(): number;
+  expired(): boolean;
+}
+
+export function deadline(clock: Clock, totalMs: number): Deadline {
+  const startedAt = clock.monotonic();
+  const remainingMs = (): number => Math.max(0, totalMs - (clock.monotonic() - startedAt));
+  return { totalMs, remainingMs, expired: () => remainingMs() <= 0 };
+}

package/src/cookie-scope.ts

@@ -0,0 +1,97 @@
+// Which cookies a URL may see — RFC 6265 §5.1.3 (domain-match) and §5.1.4 (path-match), as one
+// decision every transport asks.
+//
+// It is a SECURITY rule and not a formatting one: a session snapshot's jar is `browser.cookies()`,
+// i.e. every domain the session ever touched — an SSO hop's included — and the HTTP leg picks from
+// it by hand rather than by a browser's own jar. A suffix test with no dot boundary sends a
+// `bank.test` session cookie to `evilbank.test`; one with no host-only rule sends it to
+// `sub.bank.test`. Both are the same one-line mistake, in opposite directions.
+
+import type { ScrapeCookie } from './target';
+
+/**
+ * The dot IS the rule, in both directions.
+ *
+ * A stored `.bank.test` is DOMAIN-scoped — a browser records the leading dot for a cookie set with
+ * a `Domain=` attribute, and that is what CDP's `Network.getAllCookies` hands back — so it reaches
+ * `bank.test` and any subdomain of it. A stored `bank.test` is HOST-ONLY and reaches exactly that
+ * host. `ScrapeCookie` carries no `hostOnly` flag because the CDP cookie shape has none to carry
+ * (`cdp-port.ts`), so the leading dot is the only signal there is, and it is enough.
+ */
+export function cookieDomainMatches(host: string, domain: string): boolean {
+  const requested = host.trim().toLowerCase();
+  const stored = domain.trim().toLowerCase();
+  const scoped = stored.startsWith('.');
+  const bare = scoped ? stored.slice(1) : stored;
+  if (bare === '' || requested === '') return false;
+  if (requested === bare) return true;
+  return scoped && requested.endsWith(`.${bare}`);
+}
+
+/**
+ * RFC 6265 §5.1.4. `/admin` covers `/admin` and `/admin/users`, and never `/administrators` —
+ * the boundary is a `/`, exactly as it is for a domain. An empty stored path is `/`, which is what
+ * a jar entry written by hand usually means.
+ */
+export function cookiePathMatches(requestPath: string, cookiePath: string): boolean {
+  const wanted = requestPath === '' ? '/' : requestPath;
+  const stored = cookiePath === '' ? '/' : cookiePath;
+  if (wanted === stored) return true;
+  if (!wanted.startsWith(stored)) return false;
+  return stored.endsWith('/') || wanted.charAt(stored.length) === '/';
+}
+
+/**
+ * A `secure` cookie over plaintext is the same leak one hop further down: `http:` on a hostile
+ * network is readable. `localhost` is the one exception every browser makes, and a fixture host
+ * that is not is simply refused the cookie rather than silently downgraded.
+ */
+const trustworthy = (url: URL): boolean =>
+  url.protocol === 'https:' ||
+  url.hostname === 'localhost' ||
+  url.hostname === '127.0.0.1' ||
+  url.hostname === '[::1]';
+
+/**
+ * Fails CLOSED, like `hostDecision()`: a URL that will not parse gets no cookies at all. Expiry is
+ * deliberately NOT filtered here — `ScrapeCookie.expires` carries no unit (CDP answers seconds,
+ * a hand-written jar tends to hold milliseconds) and dropping a live session cookie over a guess
+ * is worse than sending one the site will refuse itself.
+ */
+export function cookiesForUrl(
+  cookies: readonly ScrapeCookie[],
+  url: string,
+): readonly ScrapeCookie[] {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return [];
+  }
+  const secureOk = trustworthy(parsed);
+  return cookies.filter(
+    (cookie) =>
+      cookieDomainMatches(parsed.hostname, cookie.domain) &&
+      cookiePathMatches(parsed.pathname, cookie.path) &&
+      (!cookie.secure || secureOk),
+  );
+}
+
+/** An absent path is `/` here too — §5.1.4's rule, so it cannot outrank a real path on length. */
+const pathLength = (path: string): number => (path === '' ? 1 : path.length);
+
+/**
+ * The `cookie:` header this URL earns, or `undefined` when the jar has nothing for it.
+ *
+ * ORDERED, RFC 6265 §5.4: longer paths first. Two cookies may share a name — a `sid` at `/` and a
+ * `sid` at `/admin` — and a server reading the first occurrence has to see the specific one; jar
+ * order is an accident of how the browser filled it. The sort is stable, so a tie keeps jar order,
+ * which is the nearest thing this jar has to §5.4's creation-time tiebreak (`ScrapeCookie` carries
+ * no creation time, and CDP's cookie shape has none to carry).
+ */
+export function cookieHeaderFor(cookies: readonly ScrapeCookie[], url: string): string | undefined {
+  const jar = [...cookiesForUrl(cookies, url)].sort(
+    (left, right) => pathLength(right.path) - pathLength(left.path),
+  );
+  return jar.length === 0 ? undefined : jar.map((c) => `${c.name}=${c.value}`).join('; ');
+}

package/src/driver-cdp.ts

@@ -0,0 +1,184 @@
+// The real browser driver: `localBrowser()` starts one in this container, `remoteBrowser()`
+// ATTACHES to one somebody else started over a CDP URL.
+//
+// Attach is the PRIMARY production path, not an afterthought. Real deployments create a hardened
+// browser elsewhere — a provider, a sidecar, a stealth build — and the app connects to it. Which
+// is why `close()` here stops BOTH halves: the local connection and the remote session. A close
+// that only disconnects leaves a browser somebody is billing for running until its provider times
+// it out, and nobody attributes that bill to the run that caused it.
+//
+// The library is passed IN (`launcher`), never imported — see `cdp-port.ts` for why that seam is
+// what keeps a puppeteer type out of the vocabulary and this package free of a dependency.
+
+import type { CdpBrowserLike, CdpLauncherLike } from './cdp-port';
+import { CDP_DRIVER, cdpTarget } from './cdp-target';
+import type { ScrapeDriver, ScrapeSession, SessionInit } from './driver';
+import { browserUnreachable, cdpAttachFailed, remoteRequired } from './error-throws';
+import { isScrapeError } from './errors';
+import { httpOverFetch } from './http';
+import { pageOverTarget } from './page-over-target';
+import type { ScrapeTarget } from './target';
+import { createWedgeGuard } from './watchdog';
+
+export { CDP_DRIVER } from './cdp-target';
+
+export interface BrowserOptions {
+  /** `puppeteer` itself, or anything with the same two methods. */
+  readonly launcher: CdpLauncherLike;
+  readonly proxy?: string | undefined;
+  /** Extra launch/connect arguments, passed through untouched. */
+  readonly options?: Record<string, unknown> | undefined;
+  /** How long a graceful `close()` may take before the process is killed. */
+  readonly graceMs?: number | undefined;
+}
+
+export interface LocalBrowserOptions extends BrowserOptions {
+  readonly executablePath?: string | undefined;
+  readonly headless?: boolean | undefined;
+  /**
+   * The user-data directory. Two runs sharing one is `X_SCRAPE_PROFILE_LOCKED`; a run that must
+   * arrive as a NEW identity gets its own, which is what burning a session means on disk.
+   */
+  readonly profileDir?: string | undefined;
+}
+
+export interface RemoteBrowserOptions extends BrowserOptions {
+  /** The `webSocketDebuggerUrl` from `/json/version`, or a provider's connect URL. */
+  readonly cdpUrl: string;
+}
+
+/**
+ * The page, its interception and its restored session — or a closed browser and the failure.
+ * A throw from here is classified before it leaves: `newPage()` and `setRequestInterception()` are
+ * outside `cdpTarget`'s own `guard()`, so a bare library `Error` would otherwise reach the job's
+ * retry classifier with no code at all.
+ */
+async function opened(browser: CdpBrowserLike, init: SessionInit): Promise<ScrapeTarget> {
+  try {
+    const page = await browser.newPage();
+    const target = await cdpTarget({ page, browser, rules: init.rules, clock: init.clock });
+    if (init.restore !== undefined) await target.restore(init.restore);
+    return target;
+  } catch (thrown) {
+    // Best effort, and it may never replace the failure that caused it: a close that also throws
+    // would hide the tab limit or the refused interception the reader actually needs.
+    await browser.close().catch(() => undefined);
+    throw isScrapeError(thrown) ? thrown : browserUnreachable(CDP_DRIVER, thrown);
+  }
+}
+
+async function sessionOver(
+  browser: CdpBrowserLike,
+  init: SessionInit,
+  options: BrowserOptions,
+): Promise<ScrapeSession> {
+  // Acquire, then roll back on ANY throw — the shape `releaseBoot` uses in `packages/cli/src/
+  // serve.ts`. Between the launch and the `WedgeGuard` below, nothing else holds this browser:
+  // `runScrape`'s `finally { session.close() }` never runs for a session `open()` did not return,
+  // so a tab limit, a refused interception or a restore that threw left a real Chrome process —
+  // or a remote session somebody is billing for — running per attempt, unattributed.
+  const target = await opened(browser, init);
+  const guard = createWedgeGuard({
+    clock: init.clock,
+    what: `scrape "${init.name}"`,
+    graceMs: init.watchdog?.graceMs ?? options.graceMs,
+    idleMs: init.watchdog?.idleMs,
+    // `close()` and NOT `disconnect()`, on BOTH drivers. Disconnecting ends the local half and
+    // leaves the remote browser running until its provider times it out — a bill nobody
+    // attributes to the run that caused it. An app that genuinely wants the remote session to
+    // survive keeps its own handle and never hands it to a driver.
+    quit: () => browser.close(),
+    kill: () => {
+      // The OS process, when there is one to reach. Killing it is what makes the socket a wedged
+      // await is blocked on close, which is what turns an infinite wait into a catchable error.
+      const child = browser.process?.();
+      child?.kill(9);
+    },
+  });
+  const onActivity = (): void => {
+    guard.touch();
+    init.onActivity?.();
+  };
+  return {
+    driver: CDP_DRIVER,
+    page: pageOverTarget(target, {
+      clock: init.clock,
+      allowHosts: init.rules.allowHosts,
+      defaultTimeoutMs: init.timeoutMs,
+      secrets: init.secrets,
+      robots: init.robots,
+      signal: init.signal,
+      onActivity,
+      pace: init.pace,
+    }),
+    http: httpOverFetch({
+      rules: init.rules,
+      clock: init.clock,
+      timeoutMs: init.timeoutMs,
+      network: target.network,
+      // Straight through to the live browser: the HTTP leg must see the cookies a login two calls
+      // ago produced, and a snapshot taken at open time would be the logged-out one forever.
+      session: () => target.session(),
+      robots: init.robots,
+      pace: init.pace,
+      signal: init.signal,
+      onActivity,
+      proxy: options.proxy,
+    }),
+    close: () => guard.shutdown(),
+  };
+}
+
+/**
+ * A browser in this container. `executablePath` is required by every puppeteer-core build — it
+ * ships no browser — so it is passed through rather than guessed at.
+ */
+export function localBrowser(options: LocalBrowserOptions): ScrapeDriver {
+  return {
+    name: CDP_DRIVER,
+    async open(init: SessionInit): Promise<ScrapeSession> {
+      const launch = options.launcher.launch;
+      if (launch === undefined) {
+        throw remoteRequired('local browser: the launcher has no launch()');
+      }
+      let browser: CdpBrowserLike;
+      try {
+        browser = await launch.call(options.launcher, {
+          headless: options.headless ?? true,
+          ...(options.executablePath === undefined
+            ? {}
+            : { executablePath: options.executablePath }),
+          ...(options.profileDir === undefined ? {} : { userDataDir: options.profileDir }),
+          ...(options.proxy === undefined ? {} : { args: [`--proxy-server=${options.proxy}`] }),
+          ...options.options,
+        });
+      } catch (thrown) {
+        throw browserUnreachable(CDP_DRIVER, thrown);
+      }
+      return sessionOver(browser, init, options);
+    },
+  };
+}
+
+/** Attach to a browser somebody else started. The production path. */
+export function remoteBrowser(options: RemoteBrowserOptions): ScrapeDriver {
+  return {
+    name: CDP_DRIVER,
+    async open(init: SessionInit): Promise<ScrapeSession> {
+      const connect = options.launcher.connect;
+      if (connect === undefined || options.cdpUrl === '') {
+        throw remoteRequired(CDP_DRIVER);
+      }
+      let browser: CdpBrowserLike;
+      try {
+        browser = await connect.call(options.launcher, {
+          browserWSEndpoint: options.cdpUrl,
+          ...options.options,
+        });
+      } catch (thrown) {
+        throw cdpAttachFailed(options.cdpUrl, thrown);
+      }
+      return sessionOver(browser, init, options);
+    },
+  };
+}

package/src/driver-fake.ts

@@ -0,0 +1,119 @@
+// The DEFAULT driver under `bun test`: no process, no port, no CDP, no Chrome. A scraper's tests
+// are the point of this package, and a test suite that needs a browser installed is a test suite
+// that runs on one machine.
+//
+// It covers BOTH legs. `fakeBrowser({ pages, http })` replays the browser walk and the JSON
+// endpoints behind it from one declaration, so a hybrid scrape is tested the way it runs.
+
+import type { ScrapeClock } from './clock';
+import { systemScrapeClock } from './clock';
+import type { ScrapeDriver, ScrapeSession, SessionInit } from './driver';
+import { htmlTarget } from './html-target';
+import { httpRecordingsOf } from './http-recorded';
+import { openOfflineSession } from './offline-session';
+import type { ScrapePage } from './page';
+import type { PageContext } from './page-over-target';
+import { pageOverTarget } from './page-over-target';
+import type { HttpRecording, PageRecording } from './recording';
+import type { SessionSnapshot } from './session-state';
+import type { ScrapeCookie } from './target';
+
+export const FAKE_DRIVER = 'fake';
+
+/** `{ 'https://example.com/': '<html>…' }`, or full recordings when a page needs frames. */
+export type FakePages = Readonly<Record<string, string>> | readonly PageRecording[];
+
+const normalise = (url: string): string => {
+  try {
+    const parsed = new URL(url);
+    // `https://example.com` and `https://example.com/` are one page to every browser, and two
+    // keys to a `Map` — which is a `X_SCRAPE_FIXTURE_MISSING` for a page the author did record.
+    if (parsed.pathname === '') parsed.pathname = '/';
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+};
+
+export function recordingsOf(pages: FakePages): readonly PageRecording[] {
+  return Array.isArray(pages)
+    ? (pages as readonly PageRecording[])
+    : Object.entries(pages as Readonly<Record<string, string>>).map(([url, html]) => ({
+        url,
+        html,
+      }));
+}
+
+export interface FakeBrowserOptions {
+  readonly cookies?: readonly ScrapeCookie[] | undefined;
+  /** What `page.session()` answers — the browser-to-HTTP handoff, as data a test can assert on. */
+  readonly session?: SessionSnapshot | undefined;
+  /** The JSON endpoints the hybrid leg calls. An unrecorded one throws, like an unrecorded page. */
+  readonly http?: readonly HttpRecording[] | undefined;
+}
+
+/**
+ * An in-memory site. Every request it cannot answer — page or HTTP — THROWS
+ * `X_SCRAPE_FIXTURE_MISSING`, never a pass-through to the network, which is the one behaviour
+ * that would make an offline suite secretly live.
+ */
+export function fakeBrowser(pages: FakePages, options: FakeBrowserOptions = {}): ScrapeDriver {
+  const byUrl = new Map(recordingsOf(pages).map((page) => [normalise(page.url), page]));
+  const byRequest = httpRecordingsOf(options.http ?? []);
+  return {
+    name: FAKE_DRIVER,
+    open: (session: SessionInit): Promise<ScrapeSession> =>
+      openOfflineSession({
+        driver: FAKE_DRIVER,
+        source: 'fakeBrowser()',
+        lookup: (url) => Promise.resolve(byUrl.get(normalise(url))),
+        http: (method, url) => Promise.resolve(byRequest.get(`${method} ${url}`)),
+        session,
+        cookies: options.cookies,
+        snapshot: options.session,
+      }),
+  };
+}
+
+export interface FakePageOptions {
+  readonly url?: string | undefined;
+  readonly clock?: ScrapeClock | undefined;
+  readonly allowHosts?: readonly string[] | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly context?: Partial<PageContext> | undefined;
+  /** Extra pages this one can navigate to — `data-goto` and `<a href>` both land here. */
+  readonly pages?: FakePages | undefined;
+  readonly session?: SessionSnapshot | undefined;
+}
+
+export const FAKE_PAGE_URL = 'https://fake.test/';
+
+/**
+ * One page of markup as a `ScrapePage`, for a test that wants to assert on the vocabulary and
+ * nothing else. No session and no driver: `page.html()`, `page.click()` and `page.values()` are
+ * the whole surface under test.
+ */
+export function fakePage(dom: string, options: FakePageOptions = {}): ScrapePage {
+  const url = options.url ?? FAKE_PAGE_URL;
+  const start: PageRecording = { url, html: dom };
+  const clock = options.clock ?? systemScrapeClock;
+  const allowHosts = options.allowHosts ?? ['*'];
+  const byUrl = new Map(
+    [start, ...recordingsOf(options.pages ?? [])].map((page) => [normalise(page.url), page]),
+  );
+  const target = htmlTarget({
+    driver: FAKE_DRIVER,
+    lookup: (next) => Promise.resolve(byUrl.get(normalise(next))),
+    rules: { allowHosts },
+    clock,
+    source: 'fakePage()',
+    start,
+    session: options.session,
+  });
+  return pageOverTarget(target, {
+    clock,
+    allowHosts,
+    defaultTimeoutMs: options.timeoutMs ?? 1_000,
+    ...options.context,
+  });
+}

package/src/driver-fixture.ts

@@ -0,0 +1,65 @@
+// Recorded pages AND recorded HTTP on disk, replayed from ONE directory. The difference from
+// `fakeBrowser()` is only where the recordings live — and the difference from a live driver is
+// that this one CANNOT reach the network: a request with no file under `dir` is
+// `X_SCRAPE_FIXTURE_MISSING`, never a fetch.
+//
+// One directory for both legs is the point. A hybrid scrape — browser login, session handoff,
+// HTTP bulk fetch — replays end to end, so the part of a scraper that is hardest to get right is
+// not the part that has no test.
+//
+// Recordings age. A fixture recorded eighteen months ago proves that a scraper still parses a
+// page that no longer exists, which is worse than no test at all — hence `maxAge`.
+
+import type { ScrapeDriver, ScrapeSession, SessionInit } from './driver';
+import { httpRecordingFilename } from './http-recorded';
+import { openOfflineSession } from './offline-session';
+import type { HttpRecording, PageRecording } from './recording';
+import { parseHttpRecording, parseRecording } from './recording';
+
+export const FIXTURE_DRIVER = 'fixture';
+
+/**
+ * `https://example.com/a/b?q=1` -> `example.com-a-b-q-1.json`. Deterministic and readable, so the
+ * `X_SCRAPE_FIXTURE_MISSING` fix can name the exact file to create and a reviewer can tell which
+ * page a recording is without opening it.
+ */
+export function recordingFilename(url: string): string {
+  const withoutScheme = url.replace(/^[a-z]+:\/\//i, '');
+  const slug = withoutScheme
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return `${slug === '' ? 'index' : slug}.json`;
+}
+
+export interface FixtureBrowserOptions {
+  /** Milliseconds. A recording older than this refuses the run rather than passing on old HTML. */
+  readonly maxAge?: number | undefined;
+}
+
+export function fixtureBrowser(dir: string, options: FixtureBrowserOptions = {}): ScrapeDriver {
+  const lookup = async (url: string): Promise<PageRecording | undefined> => {
+    const file = Bun.file(`${dir}/${recordingFilename(url)}`);
+    if (!(await file.exists())) return undefined;
+    // Parsed, never cast: a recording is an edited file on somebody's disk, so it is `unknown`
+    // until a schema says otherwise.
+    return parseRecording(await file.json());
+  };
+  const http = async (method: string, url: string): Promise<HttpRecording | undefined> => {
+    const file = Bun.file(`${dir}/${httpRecordingFilename(method, url)}`);
+    if (!(await file.exists())) return undefined;
+    return parseHttpRecording(await file.json());
+  };
+  return {
+    name: FIXTURE_DRIVER,
+    open: (session: SessionInit): Promise<ScrapeSession> =>
+      openOfflineSession({
+        driver: FIXTURE_DRIVER,
+        source: dir,
+        lookup,
+        http,
+        session,
+        maxAgeMs: options.maxAge,
+      }),
+  };
+}

package/src/driver.ts

@@ -0,0 +1,88 @@
+// The browser contract. Every driver implements exactly this, so a scrape's body never names one
+// — the same shape `packages/jobs/src/driver.ts` gives the queue, for the same reason: swapping
+// the browser is `setScrapeDriver(other)` and ZERO run-body change.
+//
+// Two methods. `open` hands back a session; `close` ends it. Everything else a scraper does goes
+// through `ScrapePage`, which is driver-blind by construction.
+
+import type { ScrapeClock } from './clock';
+import type { ScrapeHttp } from './http';
+import type { InterceptRules } from './intercept';
+import type { ScrapePage } from './page';
+import type { RobotsGate } from './robots';
+import type { ScrapeSecrets } from './secrets';
+import type { SessionSnapshot } from './session-state';
+
+export interface SessionInit {
+  /** The scrape's name — every error cause raised inside the session carries it. */
+  readonly name: string;
+  readonly rules: InterceptRules;
+  readonly clock: ScrapeClock;
+  /** Per-operation default, in ms. A `waitFor` with its own `timeout` overrides it. */
+  readonly timeoutMs: number;
+  readonly secrets?: ScrapeSecrets | undefined;
+  readonly robots?: RobotsGate | undefined;
+  /** The run's cancellation. A driver that ignores it leaves a browser behind on every kill. */
+  readonly signal?: AbortSignal | undefined;
+  /** A previously captured session, put back before the first navigation. */
+  readonly restore?: SessionSnapshot | undefined;
+  /** BOTH transports dial through it. A different exit IP mid-session is a different client. */
+  readonly proxy?: string | undefined;
+  /** Awaited before every navigation AND every HTTP request — one budget across both legs. */
+  readonly pace?: ((signal?: AbortSignal) => Promise<void>) | undefined;
+  /** Called on every operation on either transport. The wedge watchdog measures the gaps. */
+  readonly onActivity?: (() => void) | undefined;
+  /**
+   * The wedge discipline, as the scrape declared it: kill the browser after `idleMs` of silence,
+   * and give a graceful quit `graceMs` before killing it anyway. A driver with no OS process to
+   * reach still honours the abort half.
+   */
+  readonly watchdog?: { readonly idleMs?: number; readonly graceMs?: number } | undefined;
+}
+
+export interface ScrapeSession {
+  readonly driver: string;
+  readonly page: ScrapePage;
+  /**
+   * The second transport, bound to the SAME session as the page: the browser's cookies, headers
+   * and proxy, the same `allowHosts`, the same rate limit, the same cancellation. A driver hands
+   * both back together because the two legs of a hybrid scrape are one client, and a session that
+   * could hand out only one of them would leave the other to be hand-rolled per app.
+   */
+  readonly http: ScrapeHttp;
+  /**
+   * Ends the session — and for a remote driver that means BOTH halves: the local connection AND
+   * the browser somebody else is billing for. A `close()` that only disconnects leaves a paid
+   * session running until its provider times it out, which is the bill nobody attributes.
+   *
+   * Idempotent, and never throws: it runs in a `finally`, and a close that threw would replace
+   * the run's real failure with a teardown failure.
+   */
+  close(): Promise<void>;
+}
+
+export interface ScrapeDriver {
+  /** `puppeteer` | `fixture` | `fake`. Appears in every error cause raised against it. */
+  readonly name: string;
+  open(init: SessionInit): Promise<ScrapeSession>;
+}
+
+let ambient: ScrapeDriver | undefined;
+
+/** Set once at boot from `app.config.ts`. A scrape's own `driver:` overrides it per definition. */
+export function setScrapeDriver(driver: ScrapeDriver): void {
+  ambient = driver;
+}
+
+export function scrapeDriver(): ScrapeDriver | undefined {
+  return ambient;
+}
+
+/**
+ * Test/CLI seam: forget the ambient driver. The counterpart to `resetJobDriver()` — a test that
+ * installs a browser has to be able to put the process back, or every later file in the same bun
+ * process runs against a driver it never asked for.
+ */
+export function resetScrapeDriver(): void {
+  ambient = undefined;
+}