@ultimat3/scraping 23.0.0 → 24.0.0

package/README.md

@@ -313,8 +313,9 @@ bound threw away, so a count taken from one is never quietly a floor.
 All three are **redacted by value** on the way out, the same pass `page.html()` makes: a login
 endpoint fetched with the password in its query string, or a site that logs the credential it
 rejected, would otherwise put the value in `page.network()`/`page.console()` verbatim and from
-there into the stored failure artifact. The HTTP leg's `X_SCRAPE_HTTP_FAILED` cause is redacted
-too, at its throw site. Values shorter than `MIN_REDACTABLE_LENGTH` are not — a 3-character PIN is
+there into the stored failure artifact — percent-encoded, form-encoded or HTML-escaped as much as
+raw, since a password in a query string is never the raw string. The HTTP leg's
+`X_SCRAPE_HTTP_FAILED` cause is redacted too, at its throw site. Values shorter than `MIN_REDACTABLE_LENGTH` are not — a 3-character PIN is
 a substring of ordinary prose — and pixels never can be, which is why a typed secret TAINTS the
 page and `screenshot()`/`pdf()` are refused outright.
 
@@ -362,7 +363,7 @@ on a machine with no browser — the case CI is.
 | `driver-cdp.ts` / `cdp-*.ts` | the real browser, over a structural CDP port |
 | `driver-fake.ts` / `driver-recorded.ts` / `html-*.ts` | the offline drivers, on Bun's `HTMLRewriter` |
 | `http.ts` / `http-recorded.ts` | the second transport, live and replayed |
-| `auth.ts` / `session-state.ts` | acquire → persist → reuse → validate → burn. The session key encodes each part (`<sanitised>.<digest>`), so two account names that differ only outside `[a-zA-Z0-9._-]` are two sessions. A stored session is sealed |
+| `auth.ts` / `session-state.ts` | acquire → persist → reuse → validate → burn. The session key encodes each part (`<sanitised>.<digest>`), so two account names that differ only outside `[a-zA-Z0-9._-]` are two sessions. A stored session is sealed. `burnSession(plan, seen)` takes `recordVersion(record)` of the record the run used, so a record another run saved since is not burned |
 | `event-prompt.ts` | `eventPrompt()` and `answerPrompt()`: a prompt answered from another process, over the job event bus, with the browser open |
 | `cdp-resolver.ts` | a browser rented per session: acquired once, released once |
 | `usage.ts` | what one run used, counted where the work happens |

package/package.json

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

package/src/auth.ts

@@ -23,7 +23,12 @@ import type { ScrapeClock } from './clock';
 import { authFailed, promptUnanswered, sessionExpired } from './error-throws';
 import type { ScrapePage } from './page';
 import type { ScrapeSecrets } from './secrets';
-import { type ScrapeSessionStore, type SessionState, sessionDigest } from './session-state';
+import {
+  recordVersion,
+  type ScrapeSessionStore,
+  type SessionState,
+  sessionDigest,
+} from './session-state';
 
 export interface PromptRequest<I = unknown> {
   /**
@@ -167,10 +172,30 @@ export interface AuthPlanInput<I> {
 export async function restorableSession<I>(
   plan: AuthPlanInput<I>,
 ): Promise<SessionState | undefined> {
+  return (await observeSession(plan)).restorable;
+}
+
+/** What `observeSession` answers: the session to restore, and the version of what was found. */
+export interface ObservedSession {
+  readonly restorable: SessionState | undefined;
+  /**
+   * `recordVersion` of the record found — restorable or NOT. A `reuse: false` run, or one whose
+   * record is past `maxAge`, still saw that record: a refused login must tombstone over it, and a
+   * run that compared against "nothing" let the rejected credential through again.
+   */
+  readonly seen: string | undefined;
+}
+
+/** `restorableSession`, plus the version of the record found, for the run's later writes. */
+export async function observeSession<I>(plan: AuthPlanInput<I>): Promise<ObservedSession> {
   const store = plan.auth?.store;
-  if (store === undefined) return undefined;
+  if (store === undefined) return { restorable: undefined, seen: undefined };
   const found = await store.load(plan.key);
-  if (found === undefined) return undefined;
+  if (found === undefined) return { restorable: undefined, seen: undefined };
+  return { restorable: restorableFrom(plan, found), seen: recordVersion(found) };
+}
+
+function restorableFrom<I>(plan: AuthPlanInput<I>, found: SessionState): SessionState | undefined {
   // The tombstone is read BEFORE `reuse` is honoured. `reuse: false` says "do not restore this
   // session"; it does not say "present the rejected credential again", and reading it first meant
   // a `reuse: false` scrape walked a refused password back to the login form on every requeue.
@@ -194,13 +219,42 @@ export async function restorableSession<I>(
   return found;
 }
 
-/** Written down so the next attempt cannot reach the login form with the same credentials. */
-export async function markRefused<I>(plan: AuthPlanInput<I>): Promise<void> {
+/**
+ * True when the stored record is still the one this run last saw — `seen` is the `recordVersion`
+ * it found or persisted, `undefined` when it found none. The store has no compare-and-set (nor has
+ * `StorageDriver` a conditional write to build one from), so a
+ * burn or a tombstone is a blind write: two runs on one key, and the one that failed destroyed the
+ * session the other had just persisted. Compared before the write, which narrows the race to the
+ * gap between this read and that write rather than the whole run. A record moved on is left alone.
+ */
+async function stillSeen<I>(
+  plan: AuthPlanInput<I>,
+  store: ScrapeSessionStore,
+  seen: string | undefined,
+  step: 'session.burn' | 'session.refuse',
+): Promise<boolean> {
+  const current = await store.load(plan.key);
+  if (current === undefined || recordVersion(current) === seen) return true;
+  plan.logger.warn('scrape.session.superseded', { step });
+  return false;
+}
+
+/**
+ * Written down so the next attempt cannot reach the login form with the same credentials — unless
+ * another run saved a session after this one read the record: that login SUCCEEDED, so this
+ * refusal is older news than the record it would overwrite.
+ */
+export async function markRefused<I>(
+  plan: AuthPlanInput<I>,
+  seen: string | undefined,
+): Promise<void> {
   const store = plan.auth?.store;
   if (store === undefined) return;
+  if (!(await stillSeen(plan, store, seen, 'session.refuse'))) return;
   await store.save({
     key: plan.key,
     savedAt: plan.clock.now().toISOString(),
+    version: crypto.randomUUID(),
     refusedAt: plan.clock.now().toISOString(),
     cookies: [],
     headers: {},
@@ -210,10 +264,19 @@ export async function markRefused<I>(plan: AuthPlanInput<I>): Promise<void> {
   });
 }
 
-/** New identity, from scratch. One call, because a flagged profile is unusable and must go. */
-export async function burnSession<I>(plan: AuthPlanInput<I>): Promise<void> {
-  if (plan.auth?.store === undefined) return;
-  await plan.auth.store.burn(plan.key);
+/**
+ * New identity, from scratch. One call, because a flagged profile is unusable and must go — the
+ * profile THIS run used: `seen` is that record's `recordVersion` (`observeSession`'s, or the one
+ * `persistSession` answered), and a record another run saved since is not burned.
+ */
+export async function burnSession<I>(
+  plan: AuthPlanInput<I>,
+  seen: string | undefined,
+): Promise<void> {
+  const store = plan.auth?.store;
+  if (store === undefined) return;
+  if (!(await stillSeen(plan, store, seen, 'session.burn'))) return;
+  await store.burn(plan.key);
   plan.logger.warn('scrape.session.burned', { burned: true });
 }
 
@@ -251,18 +314,31 @@ export async function ensureAuthenticated<I>(args: EnsureAuthInput<I>): Promise<
       return false;
     }
     args.logger.info('scrape.session.expired', { reused: false });
-    await burnSession(args);
+    await burnSession(args, recordVersion(args.restored));
   }
   if (auth.login === undefined) throw sessionExpired(args.scrape, args.key);
   await auth.login(context);
   return true;
 }
 
-/** After a login: keep what it produced. A 2FA code somebody typed is worth exactly this. */
-export async function persistSession<I>(plan: AuthPlanInput<I>, page: ScrapePage): Promise<void> {
+/**
+ * After a login: keep what it produced. A 2FA code somebody typed is worth exactly this. Answers
+ * the `version` it wrote — the record this run now owns, for a later burn to compare against.
+ */
+export async function persistSession<I>(
+  plan: AuthPlanInput<I>,
+  page: ScrapePage,
+): Promise<string | undefined> {
   const store = plan.auth?.store;
-  if (store === undefined) return;
+  if (store === undefined) return undefined;
   const snapshot = await page.session();
-  await store.save({ ...snapshot, key: plan.key, savedAt: plan.clock.now().toISOString() });
+  const version = crypto.randomUUID();
+  await store.save({
+    ...snapshot,
+    key: plan.key,
+    savedAt: plan.clock.now().toISOString(),
+    version,
+  });
   plan.logger.info('scrape.session.saved', sessionDigest(snapshot));
+  return version;
 }

package/src/cdp-arm.ts

@@ -4,7 +4,7 @@
 // three verbs `press`/`focus`/`accessibility` did not fit under it. The extraction is VERBATIM —
 // the request, console, `pageerror` and `error` handlers are the same code, one file over.
 
-import type { CdpPageLike, CdpRequestLike } from './cdp-port';
+import type { CdpBrowserLike, CdpPageLike, CdpRequestLike } from './cdp-port';
 import type { ScrapeClock } from './clock';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict, refusalEntry } from './intercept';
@@ -174,3 +174,67 @@ export async function arm(init: CdpArmInit, sinks: CdpSinks): Promise<void> {
     crashed.value = readStringFrom(payload, 'message') ?? 'renderer crashed';
   });
 }
+
+/** A `Fetch.requestPaused` payload, read structurally — the fields the verdict needs, or nothing. */
+interface PausedRequest {
+  readonly requestId: string;
+  readonly resourceType: string;
+  readonly url: string;
+  readonly method: string;
+}
+
+const asPaused = (payload: unknown): PausedRequest | undefined => {
+  if (typeof payload !== 'object' || payload === null) return undefined;
+  const event = payload as Record<string, unknown>;
+  const request = event['request'];
+  if (typeof request !== 'object' || request === null) return undefined;
+  const { url, method } = request as Record<string, unknown>;
+  const { requestId, resourceType } = event;
+  if (typeof requestId !== 'string' || typeof url !== 'string') return undefined;
+  return {
+    requestId,
+    url,
+    resourceType: typeof resourceType === 'string' ? resourceType : 'Other',
+    method: typeof method === 'string' ? method : 'GET',
+  };
+};
+
+/**
+ * `allowHosts` and `block` on EVERY target the browser opens. Page-level interception (`arm`)
+ * covers the one page this package created; a popup — `window.open`, a `target=_blank` link — is
+ * a new target it never sees, and on Chrome 150 a scraped page's `window.open` to an off-list host
+ * reached that host. Browser-level `Fetch` pauses those requests too, and the same
+ * `interceptVerdict` decides them. The page's own requests are decided at the page first, so an
+ * allowed one is continued here as well and a refused one never arrives: one ring entry each.
+ *
+ * Enabled BEFORE the first navigation; a browser that refuses `Fetch.enable` rejects here, and
+ * `driver-cdp.ts`'s `opened()` closes it — a session whose rule would hold on one tab is refused.
+ */
+export async function armBrowser(
+  init: {
+    readonly browser: CdpBrowserLike;
+    readonly rules: InterceptRules;
+    readonly clock: ScrapeClock;
+  },
+  network: NetworkRing,
+): Promise<void> {
+  const session = await init.browser.target().createCDPSession();
+  session.on('Fetch.requestPaused', (payload) => {
+    const paused = asPaused(payload);
+    if (paused === undefined) return;
+    const type = asResourceType(paused.resourceType.toLowerCase());
+    const verdict = interceptVerdict(paused.url, type, init.rules);
+    const requestId = { requestId: paused.requestId };
+    // Caught, never floated, for `arm`'s reason: the target may be gone by the time this answers.
+    if (verdict === 'allow') {
+      session.send('Fetch.continueRequest', requestId).catch(() => undefined);
+      return;
+    }
+    const at = init.clock.now().getTime();
+    network.push(refusalEntry(paused.url, type, verdict, at, paused.method));
+    session
+      .send('Fetch.failRequest', { ...requestId, errorReason: 'BlockedByClient' })
+      .catch(() => undefined);
+  });
+  await session.send('Fetch.enable', { patterns: [{ urlPattern: '*' }] });
+}

package/src/cdp-fake-target.ts

@@ -0,0 +1,67 @@
+// The browser TARGET of `cdp-fake.ts`'s browser: one raw session that records what the driver
+// enabled and answers `Fetch.requestPaused` the way Chrome does — a request from a target this
+// package never created (a popup) pauses here and nowhere else. Split out because `cdp-fake.ts`
+// stands near its size ceiling.
+
+import type { CdpBrowserSessionLike, CdpBrowserTargetLike } from './cdp-port';
+
+export interface FakeBrowserTarget {
+  readonly target: CdpBrowserTargetLike;
+  /** A request from another target — a popup — pausing at the browser-level `Fetch` domain. */
+  emitTargetRequest(url: string, resourceType: string, method?: string): void;
+  /** What browser-level interception decided, and whether it was enabled at all. */
+  readonly browserFetch: {
+    readonly enabled: boolean;
+    readonly continued: readonly string[];
+    readonly failed: readonly string[];
+  };
+}
+
+/** `refuseEnable`: the browser answers `Fetch.enable` with a protocol error, as a locked-down provider might. */
+export function fakeBrowserTarget(
+  options: { readonly refuseEnable?: boolean } = {},
+): FakeBrowserTarget {
+  const listeners: ((payload: unknown) => void)[] = [];
+  const byId = new Map<string, string>();
+  const continued: string[] = [];
+  const failed: string[] = [];
+  let enabled = false;
+  const session: CdpBrowserSessionLike = {
+    send: (method, params) => {
+      if (method === 'Fetch.enable') {
+        if (options.refuseEnable === true) {
+          return Promise.reject(new Error("'Fetch.enable' wasn't found"));
+        }
+        enabled = true;
+      }
+      const id = typeof params?.['requestId'] === 'string' ? params['requestId'] : '';
+      if (method === 'Fetch.continueRequest') continued.push(byId.get(id) ?? id);
+      if (method === 'Fetch.failRequest') failed.push(byId.get(id) ?? id);
+      return Promise.resolve({});
+    },
+    detach: () => Promise.resolve(),
+    on: (event, handler) => {
+      if (event === 'Fetch.requestPaused') listeners.push(handler);
+      return undefined;
+    },
+  };
+  return {
+    target: { createCDPSession: () => Promise.resolve(session) },
+    emitTargetRequest(url, resourceType, method = 'GET'): void {
+      // Paused only while enabled, as in Chrome: before `Fetch.enable` the request just leaves.
+      if (!enabled) return;
+      const requestId = `interception-${String(byId.size + 1)}`;
+      byId.set(requestId, url);
+      for (const listener of listeners) {
+        listener({ requestId, resourceType, request: { url, method } });
+      }
+    },
+    browserFetch: {
+      get enabled(): boolean {
+        return enabled;
+      },
+      continued,
+      failed,
+    },
+  };
+}

package/src/cdp-fake.ts

@@ -8,6 +8,8 @@
 //
 // Precedent: `packages/storage/src/driver-s3-fixture.ts` ships the same way.
 
+import type { FakeBrowserTarget } from './cdp-fake-target';
+import { fakeBrowserTarget } from './cdp-fake-target';
 import type {
   CdpBrowserLike,
   CdpFrameLike,
@@ -72,7 +74,9 @@ export interface FakeCdpPageInit {
 
 type Handlers = Map<string, ((payload: unknown) => void)[]>;
 
-export interface FakeCdpBrowser extends CdpBrowserLike {
+export interface FakeCdpBrowser
+  extends CdpBrowserLike,
+    Pick<FakeBrowserTarget, 'emitTargetRequest' | 'browserFetch'> {
   /** Fire a request event, as a real browser would when the page fetches a subresource. */
   emitRequest(url: string, resourceType: string): void;
   /**
@@ -158,6 +162,7 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
   const prepared: string[] = [];
   const sessions = { created: 0, detached: 0 };
   const axBySelector = init.accessibility ?? {};
+  const browserTarget = fakeBrowserTarget();
 
   /**
    * A raw session answering the four commands `cdp-a11y.ts` sends, in CDP's own wire shapes —
@@ -364,6 +369,9 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
 
   return {
     newPage: () => Promise.resolve(page),
+    target: () => browserTarget.target,
+    emitTargetRequest: (...args) => browserTarget.emitTargetRequest(...args),
+    browserFetch: browserTarget.browserFetch,
     cookies: () => Promise.resolve(cookies),
     setCookie: (...next: readonly unknown[]) => {
       cookies = next as readonly ScrapeCookie[];

package/src/cdp-port.ts

@@ -167,8 +167,29 @@ export interface CdpFrameLike {
   select(selector: string, ...values: string[]): Promise<string[]>;
 }
 
+/**
+ * A raw session on the BROWSER target — `browser.target().createCDPSession()` under puppeteer —
+ * with the event half `CdpSessionLike` does not need: `Fetch.requestPaused` arrives as an event.
+ * `event` stays a bare `string` for `CdpPageLike.on`'s reason.
+ */
+export interface CdpBrowserSessionLike extends CdpSessionLike {
+  on(event: string, handler: (payload: unknown) => void): unknown;
+}
+
+/** The browser's own target — `browser.target()` under puppeteer. */
+export interface CdpBrowserTargetLike {
+  createCDPSession(): Promise<CdpBrowserSessionLike>;
+}
+
 export interface CdpBrowserLike {
   newPage(): Promise<CdpPageLike>;
+  /**
+   * REQUIRED, unlike the page's optional verbs: it is how `allowHosts` reaches every target the
+   * browser opens — a popup, a `target=_blank` link — and not only the one page this package
+   * created. Page-level interception never sees those, and a rule that holds on one tab of a
+   * browser a scraped site controls is advisory. A launcher without it does not compile.
+   */
+  target(): CdpBrowserTargetLike;
   /** Present on a browser that owns a cookie jar. Absent ones answer `X_NOT_IMPLEMENTED`. */
   cookies?(): Promise<unknown>;
   setCookie?(...cookies: readonly unknown[]): Promise<void>;

package/src/cdp-target.ts

@@ -1,13 +1,13 @@
 // `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 { isUltimateError, NotImplementedError } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
 import { browserRecord } from './browser-record';
 import { axNodesFor } from './cdp-a11y';
 import type { CdpArmInit } from './cdp-arm';
-import { arm } from './cdp-arm';
+import { arm, armBrowser } from './cdp-arm';
 import type { CdpBrowserLike, CdpFrameLike } from './cdp-port';
 import {
   clearExpression,
@@ -16,7 +16,7 @@ import {
   snapshotExpression,
 } from './cdp-snapshot';
 import { type ColorScheme, colorSchemeFeatures } from './color-scheme';
-import { browserUnreachable, pageCrashed, scrapeNotImplemented } from './error-throws';
+import { browserUnreachable, pageCrashed } from './error-throws';
 import { parseKeyChord } from './key-chord';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
 import { createRing } from './rings';
@@ -54,7 +54,7 @@ const cookieSchema = t.array(
  *
  * | Code | Why a retry cannot change it |
  * |---|---|
- * | `X_NOT_IMPLEMENTED` | a fact about the launcher's own shape. A browser cannot produce it; only this file's `scrapeNotImplemented()` can, and the method is still missing on attempt five |
+ * | `X_NOT_IMPLEMENTED` | a fact about the launcher's own shape. A browser cannot produce it; only this file's own `NotImplementedError` refusals can, and the method is still missing on attempt five |
  * | `X_VALIDATION_FAILED` | the browser ANSWERED, and the answer did not match the shape this driver reads it with. The page is what it is; attempt five reads the same DOM |
  *
  * Both were re-labelled `X_SCRAPE_BROWSER_UNREACHABLE`, which `errors.ts` registers `retryable`,
@@ -99,6 +99,7 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
   const pageErrors = createRing<PageError>();
   const crashed: { value: string | undefined } = { value: undefined };
   await arm(init, { network, console: console_, pageErrors, crashed });
+  await armBrowser(init, network);
   let pendingStorage: SessionSnapshot | undefined;
 
   const originOf = (url: string): string => {
@@ -183,10 +184,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     // rather than answered from the PARENT document, which is what the spread alone would do.
     accessibility: (_selector, _max): Promise<readonly AxNode[]> =>
       Promise.reject(
-        scrapeNotImplemented(
-          'accessibility() on a frame of the puppeteer driver',
-          'read the accessibility tree through the page — page.accessibility(selector) — which covers the top-level document only',
-        ),
+        new NotImplementedError({
+          cause:
+            'accessibility() on a frame of the puppeteer driver is not implemented by this driver',
+          fix: 'read the accessibility tree through the page — page.accessibility(selector) — which covers the top-level document only',
+        }),
       ),
   });
 
@@ -228,10 +230,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       await guard('press', async () => {
         const keyboard = init.page.keyboard;
         if (keyboard === undefined) {
-          throw scrapeNotImplemented(
-            'press() on a CDP page with no keyboard',
-            'upgrade the launcher to a puppeteer-core that exposes page.keyboard, or dispatch the key from the app under test instead of the browser',
-          );
+          throw new NotImplementedError({
+            cause: 'press() on a CDP page with no keyboard is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.keyboard, or dispatch the key from the app under test instead of the browser',
+          });
         }
         // Down in the order written, the key, then up in REVERSE — the order a hand releases
         // them, and the order the browser's own `press` with modifiers performs. `.call`-free:
@@ -248,10 +250,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('focus', async () => {
         const focus = init.page.focus;
         if (typeof focus !== 'function') {
-          throw scrapeNotImplemented(
-            'focus() on a CDP page with no focus() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.focus(), or click the element instead',
-          );
+          throw new NotImplementedError({
+            cause: 'focus() on a CDP page with no focus() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.focus(), or click the element instead',
+          });
         }
         // `.call`, for `setColorScheme`'s reason: the member is read off the object.
         await focus.call(init.page, selector);
@@ -260,10 +262,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('accessibility', async () => {
         const createSession = init.page.createCDPSession;
         if (typeof createSession !== 'function') {
-          throw scrapeNotImplemented(
-            'accessibility() on a CDP page with no createCDPSession() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.createCDPSession(), or assert on the markup with page.query() — which reads attributes, not what the browser computed',
-          );
+          throw new NotImplementedError({
+            cause:
+              'accessibility() on a CDP page with no createCDPSession() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.createCDPSession(), or assert on the markup with page.query() — which reads attributes, not what the browser computed',
+          });
         }
         const session = await createSession.call(init.page);
         try {
@@ -276,10 +279,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('setOfflineMode', async () => {
         const source = init.page as { setOfflineMode?: (value: boolean) => Promise<void> };
         if (typeof source.setOfflineMode !== 'function') {
-          throw scrapeNotImplemented(
-            'setOfflineMode() on a CDP page with no setOfflineMode() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.setOfflineMode(), or drive the condition from the app under test instead of the browser',
-          );
+          throw new NotImplementedError({
+            cause:
+              'setOfflineMode() on a CDP page with no setOfflineMode() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.setOfflineMode(), or drive the condition from the app under test instead of the browser',
+          });
         }
         await source.setOfflineMode(enabled);
       }),
@@ -291,10 +295,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         // older spelling.
         const emulate = init.page.emulateMediaFeatures;
         if (typeof emulate !== 'function') {
-          throw scrapeNotImplemented(
-            'setColorScheme() on a CDP page with no emulateMediaFeatures() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.emulateMediaFeatures(), or have the page under test set its own theme',
-          );
+          throw new NotImplementedError({
+            cause:
+              'setColorScheme() on a CDP page with no emulateMediaFeatures() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.emulateMediaFeatures(), or have the page under test set its own theme',
+          });
         }
         // `.call`, because the member is read off the object: an unbound method loses `this` and
         // puppeteer's own `Page` needs it.
@@ -305,10 +310,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         // Read off the object and called through it, for `setColorScheme`'s reason.
         const evaluateOnNewDocument = init.page.evaluateOnNewDocument;
         if (typeof evaluateOnNewDocument !== 'function') {
-          throw scrapeNotImplemented(
-            'prepare() on a CDP page with no evaluateOnNewDocument() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.evaluateOnNewDocument(), or seed the state from the app under test instead of the browser',
-          );
+          throw new NotImplementedError({
+            cause:
+              'prepare() on a CDP page with no evaluateOnNewDocument() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.evaluateOnNewDocument(), or seed the state from the app under test instead of the browser',
+          });
         }
         await evaluateOnNewDocument.call(init.page, expression);
       }),
@@ -333,10 +339,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       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")',
-          );
+          throw new NotImplementedError({
+            cause:
+              'cookies() on a CDP browser with no cookies() method is not implemented by this driver',
+            fix: '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());
       }),
@@ -349,10 +356,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     // `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',
-        ),
+        new NotImplementedError({
+          cause: 'download() on the puppeteer driver is not implemented by this driver',
+          fix: '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', () =>
@@ -378,10 +385,19 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         } catch {
           origin = '';
         }
-        const source = init.browser as { cookies?: () => Promise<unknown> };
+        // Refused, never `[]`: the HTTP leg reads its cookies from here on every request and
+        // `persistSession` stores what this answers, so an empty jar went out logged-out and was
+        // saved as the session — both silently, while every other missing port method refuses.
+        if (typeof init.browser.cookies !== 'function') {
+          throw new NotImplementedError({
+            cause:
+              'session() on a CDP browser with no cookies() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes browser.cookies() — the HTTP leg and a persisted session both read the jar through it',
+          });
+        }
+        const jar = parse(cookieSchema, await init.browser.cookies());
         return {
-          cookies:
-            typeof source.cookies === 'function' ? parse(cookieSchema, await source.cookies()) : [],
+          cookies: jar,
           headers: {},
           // `browserRecord` and not `t.record()`: a page may legitimately hold a key called
           // `constructor`, and the schema refuses that name outright — see `browser-record.ts`.
@@ -394,11 +410,17 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       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);
+        if (session.cookies.length > 0) {
+          // Refused rather than skipped: a restore that dropped the cookies opened the session
+          // logged-out while the run believed it restored one.
+          if (typeof init.browser.setCookie !== 'function') {
+            throw new NotImplementedError({
+              cause:
+                'restore() of cookies on a CDP browser with no setCookie() method is not implemented by this driver',
+              fix: 'upgrade the launcher to a puppeteer-core that exposes browser.setCookie(), or set auth: { reuse: false } on the scrape() definition so no session is restored',
+            });
+          }
+          await init.browser.setCookie(...session.cookies);
         }
         pendingStorage = Object.keys(session.storage).length > 0 ? session : undefined;
         await applyPendingStorage();