@ultimat3/scraping 2.0.0

package/src/cdp-fake.ts

@@ -0,0 +1,150 @@
+// A CDP-shaped browser with no browser behind it — the seam `driver-parity.test.ts` needs to run
+// the SAME suite against the real driver's code path without Chrome.
+//
+// It exists for one reason, and it is the reason `mock.module('puppeteer-core')` is banned in this
+// package: `mock.module` replaces a module for the whole run, `bun test` does not fully serialise
+// test files, and a mock installed here has been observed leaking into a concurrently-running
+// file's assertions. An INJECTED launcher is a value; a value cannot leak.
+//
+// Precedent: `packages/storage/src/driver-s3-fixture.ts` ships the same way.
+
+import type { CdpBrowserLike, CdpFrameLike, CdpLauncherLike, CdpPageLike } from './cdp-port';
+import { queryHtml } from './html-query';
+import type { ElementSnapshot, ScrapeCookie } from './target';
+
+/** The selector inside `snapshotExpression()`'s `document.querySelectorAll("…")`. */
+const selectorOf = (expression: string): string | undefined => {
+  const match = /querySelectorAll\((".*?")\)/s.exec(expression);
+  if (match?.[1] === undefined) return undefined;
+  return JSON.parse(match[1]) as 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 }>>;
+  readonly cookies?: readonly ScrapeCookie[];
+  readonly storage?: Readonly<Record<string, string>>;
+  readonly userAgent?: string;
+  /** Selectors whose element is covered at its centre — what only a layout engine can see. */
+  readonly covered?: readonly string[];
+}
+
+type Handlers = Map<string, ((payload: unknown) => void)[]>;
+
+export interface FakeCdpBrowser extends CdpBrowserLike {
+  /** Fire a request event, as a real browser would when the page fetches a subresource. */
+  emitRequest(url: string, resourceType: string): void;
+  readonly aborted: readonly string[];
+  readonly closed: boolean;
+}
+
+/** A layout box every element gets, so the CDP path exercises the fields the fake target lacks. */
+const boxed = (snapshot: ElementSnapshot, covered: boolean): ElementSnapshot => ({
+  ...snapshot,
+  box: { x: 10, y: 10, width: 100, height: 20 },
+  hitTarget: !covered,
+});
+
+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;
+  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 selector = selectorOf(expression);
+    if (selector !== undefined) {
+      const found = await queryHtml(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);
+    }
+    if (expression.includes('navigator.userAgent')) return init.userAgent ?? 'fake-agent';
+    return undefined;
+  };
+
+  const page: CdpPageLike = {
+    url: () => url,
+    goto: (next: string) => {
+      url = next;
+      return Promise.resolve(undefined);
+    },
+    content: () => Promise.resolve(html),
+    evaluate,
+    click: (selector: string) => {
+      const route = init.routes?.[selector];
+      if (route !== undefined) {
+        url = route.url;
+        html = route.html;
+      }
+      return Promise.resolve();
+    },
+    type: () => Promise.resolve(),
+    select: () => Promise.resolve([]),
+    screenshot: () => Promise.resolve(new Uint8Array([1, 2, 3])),
+    pdf: () => Promise.resolve(new Uint8Array([4, 5])),
+    setRequestInterception: () => 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[] => [],
+    close: () => {
+      closed = true;
+      return Promise.resolve();
+    },
+  };
+
+  return {
+    newPage: () => Promise.resolve(page),
+    cookies: () => Promise.resolve(cookies),
+    setCookie: (...next: readonly unknown[]) => {
+      cookies = next as readonly ScrapeCookie[];
+      return Promise.resolve();
+    },
+    close: () => {
+      closed = true;
+      return Promise.resolve();
+    },
+    process: () => null,
+    emitRequest(requestUrl: string, resourceType: string): void {
+      for (const handler of handlers.get('request') ?? []) {
+        handler({
+          url: () => requestUrl,
+          resourceType: () => resourceType,
+          abort: () => {
+            aborted.push(requestUrl);
+            return Promise.resolve();
+          },
+          continue: () => Promise.resolve(),
+        });
+      }
+    },
+    aborted,
+    get closed(): boolean {
+      return closed;
+    },
+  };
+}
+
+/** A launcher over `fakeCdpBrowser`, for `localBrowser({ launcher })` in a test. */
+export function fakeCdpLauncher(init: FakeCdpPageInit): CdpLauncherLike & {
+  readonly browser: FakeCdpBrowser;
+} {
+  const browser = fakeCdpBrowser(init);
+  return {
+    browser,
+    launch: () => Promise.resolve(browser),
+    connect: () => Promise.resolve(browser),
+  };
+}

package/src/cdp-port.ts

@@ -0,0 +1,75 @@
+// The browser library's shape, declared STRUCTURALLY and imported from nowhere.
+//
+// `puppeteer-core` is the intended implementation and `docs/idea/18-build-vs-wrap.md` permits it
+// at exactly this seam — a driver/transport boundary, never the vocabulary. Declaring the port
+// instead of importing the types is what keeps that promise mechanical rather than aspirational:
+// nothing in `@ultimat3/scraping` can name a `Page`, an `ElementHandle` or a `CDPSession`, so a
+// puppeteer type cannot reach `ScrapePage` even by accident, and this package takes no runtime
+// dependency at all. The app passes its own `puppeteer` in — the same way `s3Driver({ client })`
+// takes a `S3ClientLike` rather than importing a cloud SDK.
+//
+// Verified against puppeteer-core 25.8.0 on Bun 1.3.14 (both `launch` and
+// `connect({ browserWSEndpoint })`, headless Chrome 150): the WebSocket upgrade Playwright's
+// `connectOverCDP` cannot do under Bun works here, which is why this is the intended library.
+
+export interface CdpRequestLike {
+  url(): string;
+  resourceType(): string;
+  /**
+   * OPTIONAL, and read defensively: this is the shape of somebody else's event payload, so a
+   * launcher that predates the method (or a provider SDK that never had it) still satisfies the
+   * port and its requests are recorded as `GET` rather than crashing the interception handler.
+   */
+  method?(): string;
+  abort(): Promise<void>;
+  continue(): Promise<void>;
+}
+
+export interface CdpPageLike {
+  url(): string;
+  goto(url: string, options?: { readonly timeout?: number }): Promise<unknown>;
+  content(): Promise<string>;
+  /** The string form. Every read this package makes is an expression, never a closure. */
+  evaluate(expression: string): Promise<unknown>;
+  click(selector: string): Promise<void>;
+  type(selector: string, text: string): Promise<void>;
+  select(selector: string, ...values: string[]): Promise<string[]>;
+  screenshot(options: { readonly fullPage?: boolean }): Promise<Uint8Array | string>;
+  pdf(options?: Record<string, unknown>): Promise<Uint8Array>;
+  setRequestInterception(enabled: boolean): Promise<void>;
+  on(event: string, handler: (payload: unknown) => void): unknown;
+  frames(): readonly CdpFrameLike[];
+  close(): Promise<void>;
+}
+
+export interface CdpFrameLike {
+  name(): string;
+  url(): string;
+  content(): Promise<string>;
+  evaluate(expression: string): Promise<unknown>;
+  click(selector: string): Promise<void>;
+  type(selector: string, text: string): Promise<void>;
+  select(selector: string, ...values: string[]): Promise<string[]>;
+}
+
+export interface CdpBrowserLike {
+  newPage(): Promise<CdpPageLike>;
+  /** Present on a browser that owns a cookie jar. Absent ones answer `X_NOT_IMPLEMENTED`. */
+  cookies?(): Promise<unknown>;
+  setCookie?(...cookies: readonly unknown[]): Promise<void>;
+  /** Ends the browser. For an attached session this is what stops the REMOTE half. */
+  close(): Promise<void>;
+  /** Drops the local connection and leaves the remote browser running. */
+  disconnect?(): Promise<void>;
+  process?(): { readonly pid?: number | undefined; kill(signal?: number | string): void } | null;
+}
+
+/**
+ * What an app passes in: `puppeteer` itself. Both methods are optional so a launcher that can only
+ * attach (a provider SDK) still satisfies the port — `remoteBrowser()` refuses one with no
+ * `connect` at the call site, with a code, rather than at a property access.
+ */
+export interface CdpLauncherLike {
+  launch?(options: Record<string, unknown>): Promise<CdpBrowserLike>;
+  connect?(options: Record<string, unknown>): Promise<CdpBrowserLike>;
+}

package/src/cdp-snapshot.ts

@@ -0,0 +1,63 @@
+// The one in-page expression this package runs, and the schema that reads its 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
+// cookie banner over the submit button is invisible to every DOM-only check ever written, and
+// visible here.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { parse, t } from '@ultimat3/schema';
+import type { ElementSnapshot } from './target';
+
+/**
+ * Returns JSON TEXT, not an object: a CDP round trip serialises the result anyway, and a string
+ * has one deserialiser here — `parse` against the schema below — instead of an implicit one in
+ * the library plus a cast.
+ */
+export const snapshotExpression = (selector: string): string => `(() => {
+  const out = [];
+  for (const el of document.querySelectorAll(${JSON.stringify(selector)})) {
+    const style = getComputedStyle(el);
+    const rect = el.getBoundingClientRect();
+    const attrs = {};
+    for (const attribute of el.attributes) attrs[attribute.name] = attribute.value;
+    const top = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+    out.push({
+      tag: el.tagName.toLowerCase(),
+      attrs,
+      text: (el.textContent || '').replace(/\\s+/g, ' ').trim(),
+      value: typeof el.value === 'string' ? el.value : '',
+      visible: style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0',
+      enabled: el.disabled !== true && el.getAttribute('aria-disabled') !== 'true',
+      box: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+      hitTarget: top !== null && (top === el || el.contains(top) || el.contains(top.parentNode)),
+    });
+  }
+  return JSON.stringify(out);
+})()`;
+
+/**
+ * `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
+ * empty is a real answer", which is the difference between parsing a page and refusing one.
+ */
+const anyString = t.string.min(0);
+
+const snapshotSchema = t.array(
+  t.object({
+    tag: t.string,
+    attrs: t.record(anyString),
+    text: anyString,
+    value: anyString,
+    visible: t.boolean,
+    enabled: t.boolean,
+    box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
+    hitTarget: t.boolean,
+  }),
+) as unknown as StandardSchemaV1<unknown, ElementSnapshot[]>;
+
+/** The browser's answer is `unknown` and stays `unknown` until this parses it. Never a cast. */
+export function parseSnapshots(raw: unknown): readonly ElementSnapshot[] {
+  if (typeof raw !== 'string') return parse(snapshotSchema, raw);
+  return parse(snapshotSchema, JSON.parse(raw) as unknown);
+}

package/src/cdp-target.ts

@@ -0,0 +1,320 @@
+// `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 type { StandardSchemaV1 } from '@ultimat3/schema';
+import { parse, t } from '@ultimat3/schema';
+import type { CdpBrowserLike, CdpFrameLike, CdpPageLike, CdpRequestLike } from './cdp-port';
+import { parseSnapshots, snapshotExpression } from './cdp-snapshot';
+import type { ScrapeClock } from './clock';
+import { browserUnreachable, pageCrashed, scrapeNotImplemented } from './error-throws';
+import type { InterceptRules } from './intercept';
+import { interceptVerdict, refusalEntry } from './intercept';
+import type { ConsoleLine, NetworkEntry, ResourceType } from './rings';
+import { createRing, RESOURCE_TYPES } from './rings';
+import type { SessionSnapshot } from './session-state';
+import type {
+  CaptureOptions,
+  FrameRef,
+  GotoOptions,
+  ScrapeCookie,
+  ScrapeDownloadFile,
+  ScrapeTarget,
+} from './target';
+
+export const CDP_DRIVER = 'puppeteer';
+
+// `.min(0)` for the same reason `cdp-snapshot.ts` needs it: a cookie's value is legitimately the
+// empty string (a cleared session cookie), and refusing one would refuse the whole jar.
+const anyString = t.string.min(0);
+
+const cookieSchema = t.array(
+  t.object({
+    name: t.string,
+    value: anyString,
+    domain: anyString,
+    path: anyString,
+    httpOnly: t.boolean,
+    secure: t.boolean,
+  }),
+) 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';
+
+/** The library's event payloads are `unknown` here — read structurally, never cast. */
+const asRequest = (payload: unknown): CdpRequestLike | undefined => {
+  if (typeof payload !== 'object' || payload === null) return undefined;
+  const candidate = payload as Partial<CdpRequestLike>;
+  return typeof candidate.url === 'function' && typeof candidate.abort === 'function'
+    ? (candidate as CdpRequestLike)
+    : undefined;
+};
+
+/**
+ * CDP's console levels, mapped onto this package's five. `warning` is the library's spelling of
+ * `warn`, `verbose` of `debug`, and everything structural (`table`, `startGroup`, `dir`) is a log
+ * line with a shape — never its own level, because `ConsoleLine.level` is what an author filters on.
+ */
+const CONSOLE_LEVELS: Readonly<Record<string, ConsoleLine['level']>> = {
+  error: 'error',
+  assert: 'error',
+  warning: 'warn',
+  warn: 'warn',
+  info: 'info',
+  debug: 'debug',
+  verbose: 'debug',
+};
+
+/**
+ * Reads a string out of somebody else's event payload, calling an accessor THROUGH ITS OWNER.
+ *
+ * `HTTPRequest.method()` and `ConsoleMessage.type()`/`.text()` read `this` — they are methods on
+ * the library's own objects, not closures over a value. Handing the bare function to a helper
+ * (`readString(request.method)`) drops the receiver, so the accessor answers against `undefined`:
+ * on one build that throws inside the interception handler, on another it answers wrong.
+ */
+const readStringFrom = (owner: unknown, key: string): string | undefined => {
+  if (typeof owner !== 'object' || owner === null) return undefined;
+  const value = (owner as Record<string, unknown>)[key];
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'function') return undefined;
+  const answer = (value as (this: unknown) => unknown).call(owner);
+  return typeof answer === 'string' ? answer : undefined;
+};
+
+export interface CdpTargetInit {
+  readonly page: CdpPageLike;
+  readonly browser: CdpBrowserLike;
+  readonly rules: InterceptRules;
+  readonly clock: ScrapeClock;
+  readonly ringCapacity?: number | undefined;
+}
+
+/**
+ * Interception is armed BEFORE the first navigation and refuses at the request, not after the
+ * response — an `allowHosts` that reported afterwards would be a log line about bytes that
+ * already left the container.
+ */
+async function arm(
+  init: CdpTargetInit,
+  network: ReturnType<typeof createRing<NetworkEntry>>,
+  console_: ReturnType<typeof createRing<ConsoleLine>>,
+  crashed: { value: string | undefined },
+): Promise<void> {
+  await init.page.setRequestInterception(true);
+  init.page.on('request', (payload) => {
+    const request = asRequest(payload);
+    if (request === undefined) return;
+    const url = request.url();
+    const type = asResourceType(request.resourceType());
+    // The METHOD the browser is actually sending. Recording every request as a GET made
+    // `page.network()` — which `X_SCRAPE_HTTP_FAILED`'s own fix line tells the reader to open —
+    // misreport every POST and PUT the page made.
+    const method = readStringFrom(request, 'method') ?? 'GET';
+    const verdict = interceptVerdict(url, type, init.rules);
+    const at = init.clock.now().getTime();
+    if (verdict === 'allow') {
+      network.push({ method, url, resourceType: type, at });
+      void request.continue();
+      return;
+    }
+    network.push(refusalEntry(url, type, verdict, at, method));
+    void request.abort();
+  });
+  init.page.on('console', (payload) => {
+    console_.push({
+      level: CONSOLE_LEVELS[(readStringFrom(payload, 'type') ?? '').toLowerCase()] ?? 'log',
+      text: readStringFrom(payload, 'text') ?? '',
+      at: init.clock.now().getTime(),
+    });
+  });
+  // A renderer that dies must be a CODE, not a hang: every later call answers X_SCRAPE_PAGE_CRASHED
+  // instead of waiting out its own timeout against a tab that is gone.
+  init.page.on('error', (payload) => {
+    crashed.value = readStringFrom(payload, 'message') ?? 'renderer crashed';
+  });
+}
+
+export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
+  const console_ = createRing<ConsoleLine>(init.ringCapacity);
+  const network = createRing<NetworkEntry>(init.ringCapacity);
+  const crashed: { value: string | undefined } = { value: undefined };
+  await arm(init, network, console_, crashed);
+  let pendingStorage: SessionSnapshot | undefined;
+
+  const originOf = (url: string): string => {
+    try {
+      return new URL(url).origin;
+    } catch {
+      return '';
+    }
+  };
+
+  /**
+   * `localStorage` is PER ORIGIN, and `restore()` runs before the first navigation — on
+   * `about:blank`, an opaque origin with no storage to write to. So the storage half waits for the
+   * navigation that reaches the origin the session belongs to, and lands there.
+   *
+   * The origin has to MATCH: applying it to whatever page loaded first would write the site's
+   * bearer token — `session-state.ts` says this is where most sites keep it — into a different
+   * site's storage. A session whose origin is never visited simply keeps its storage, which is
+   * the same answer a browser gives.
+   */
+  const applyPendingStorage = async (): Promise<void> => {
+    const pending = pendingStorage;
+    if (pending === undefined) return;
+    if (originOf(init.page.url()) !== pending.origin || pending.origin === '') return;
+    pendingStorage = undefined;
+    await init.page.evaluate(
+      `(() => { const entries = ${JSON.stringify(pending.storage)}; for (const key of Object.keys(entries)) localStorage.setItem(key, entries[key]); })()`,
+    );
+  };
+
+  const live = (): void => {
+    if (crashed.value !== undefined) throw pageCrashed(init.page.url());
+  };
+
+  const guard = async <T>(what: string, run: () => Promise<T>): Promise<T> => {
+    live();
+    try {
+      return await run();
+    } catch (thrown) {
+      live();
+      throw browserUnreachable(`${CDP_DRIVER} ${what}`, thrown);
+    }
+  };
+
+  const frameTarget = (frame: CdpFrameLike, parent: ScrapeTarget): ScrapeTarget => ({
+    ...parent,
+    url: () => frame.url(),
+    content: () => guard('content', () => frame.content()),
+    query: (selector) =>
+      guard('query', async () =>
+        parseSnapshots(await frame.evaluate(snapshotExpression(selector))),
+      ),
+    click: (selector) => guard('click', () => frame.click(selector)),
+    type: (selector, text) => guard('type', () => frame.type(selector, text)),
+    select: (selector, values) =>
+      guard('select', async () => {
+        await frame.select(selector, ...values);
+      }),
+    evaluate: (expression) => guard('evaluate', () => frame.evaluate(expression)),
+    frames: () => Promise.resolve([]),
+  });
+
+  const target: ScrapeTarget = {
+    driver: CDP_DRIVER,
+    console: console_,
+    network,
+    url: () => init.page.url(),
+    goto: (url: string, options: GotoOptions) =>
+      guard('goto', async () => {
+        await init.page.goto(url, { timeout: options.timeoutMs });
+        await applyPendingStorage();
+      }),
+    content: () => guard('content', () => init.page.content()),
+    query: (selector) =>
+      guard('query', async () =>
+        parseSnapshots(await init.page.evaluate(snapshotExpression(selector))),
+      ),
+    click: (selector) => guard('click', () => init.page.click(selector)),
+    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 })); } })()`,
+        );
+      }),
+    select: (selector, values) =>
+      guard('select', async () => {
+        await init.page.select(selector, ...values);
+      }),
+    evaluate: (expression) => guard('evaluate', () => init.page.evaluate(expression)),
+    screenshot: (options: CaptureOptions) =>
+      guard('screenshot', async () => {
+        const shot = await init.page.screenshot({ fullPage: options.fullPage === true });
+        // Some builds answer base64 text, some answer bytes. `atob` is the one decoder both a
+        // browser and Bun agree on, and it keeps this file free of a Buffer import.
+        return typeof shot === 'string'
+          ? Uint8Array.from(atob(shot), (character) => character.charCodeAt(0))
+          : shot;
+      }),
+    pdf: (_options: CaptureOptions) => guard('pdf', () => init.page.pdf()),
+    cookies: () =>
+      guard('cookies', async () => {
+        const source = init.browser as { cookies?: () => Promise<unknown> };
+        if (typeof source.cookies !== 'function') {
+          throw scrapeNotImplemented(
+            'cookies() on a CDP browser with no cookies() method',
+            'upgrade the launcher to a puppeteer-core that exposes browser.cookies(), or read them with page.evaluate("document.cookie")',
+          );
+        }
+        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',
+      );
+    },
+    frames: () =>
+      guard('frames', () =>
+        Promise.resolve(
+          init.page.frames().map(
+            (frame): FrameRef => ({
+              name: frame.name(),
+              url: frame.url(),
+              target: frameTarget(frame, target),
+            }),
+          ),
+        ),
+      ),
+    session: () =>
+      guard('session', async () => {
+        const storage = await init.page.evaluate(
+          '(() => JSON.stringify(Object.fromEntries(Object.entries(localStorage))))()',
+        );
+        const agent = await init.page.evaluate('navigator.userAgent');
+        let origin = '';
+        try {
+          origin = new URL(init.page.url()).origin;
+        } catch {
+          origin = '';
+        }
+        const source = init.browser as { cookies?: () => Promise<unknown> };
+        return {
+          cookies:
+            typeof source.cookies === 'function' ? parse(cookieSchema, await source.cookies()) : [],
+          headers: {},
+          storage: parse(storageSchema, JSON.parse(typeof storage === 'string' ? storage : '{}')),
+          userAgent: typeof agent === 'string' ? agent : '',
+          origin,
+        };
+      }),
+    restore: (session: SessionSnapshot) =>
+      guard('restore', async () => {
+        // Two halves, because they belong to two different moments: cookies are the browser's and
+        // can be put back now, storage is an ORIGIN's and cannot exist until one is loaded.
+        const source = init.browser as {
+          setCookie?: (...cookies: readonly unknown[]) => Promise<void>;
+        };
+        if (typeof source.setCookie === 'function' && session.cookies.length > 0) {
+          await source.setCookie(...session.cookies);
+        }
+        pendingStorage = Object.keys(session.storage).length > 0 ? session : undefined;
+        await applyPendingStorage();
+      }),
+    close: async (): Promise<void> => {
+      await init.page.close();
+    },
+  };
+  return target;
+}