@ultimat3/scraping 29.3.2 → 30.0.0

package/README.md

@@ -4,6 +4,8 @@ Browser automation as a **job**. `scrape()` returns a `JobHandle` — one row of
 `PRIMITIVE_FACTORIES` in `@ultimat3/core`, the derived list of every factory that ships. There is
 no ninth primitive, and no ordinal here to go stale when the next factory lands.
 
+`bun add @ultimat3/scraping` · guide: [Scraping](https://github.com/developerz-ai/ultimate/wiki/Scraping)
+
 ```ts
 import { t } from '@ultimat3/schema';
 import { scrape, storageSessionStore } from '@ultimat3/scraping';
@@ -327,6 +329,12 @@ bound threw away, so a count taken from one is never quietly a floor.
 | `page.pageErrors()` / `page.pageErrorsDropped()` | `PageError[]` — what the page THREW and nobody caught, with the `stack` when the exception carried one |
 | `page.network()` / `page.networkDropped()` | `NetworkEntry[]` — every request, refusals included |
 
+None of the three reads is activity; every verb that reaches the browser is, `cookies()`,
+`session()`, `screenshot()` and `pdf()` included. Work on a channel the page cannot see — the app's
+own CDP session, a long warm-up — is reported with `page.activity()`: the wedge watchdog's idle
+clock only, no usage counted. When the watchdog fires it closes the browser then, not at unwind,
+so a call blocked on an attached browser's socket rejects as `X_SCRAPE_WEDGED`.
+
 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
@@ -363,6 +371,17 @@ whole-viewport picture spends them on everything that is not the component under
 | `clip` with no area, or entirely in negative coordinates | `X_SCRAPE_CAPTURE_INVALID` — a blank picture that reads as a successful capture is the failure this exists to remove |
 | `clip` on `page.pdf()` | `X_SCRAPE_CAPTURE_INVALID` — a print engine paginates the document and has no crop |
 
+### A PDF laid out as asked
+
+`page.pdf(layout)` takes `PdfRequest`: `format` (`PDF_FORMATS` — `a4`, `letter`, …) **or**
+`widthMm` + `heightMm`, `marginMm: { top, right, bottom, left }`, `printBackground`,
+`preferCssPageSize` (the document's own `@page`), and `headerHtml` / `footerHtml` (Chrome's print
+templates). `pdf-request.ts` checks it once, before any driver, beside the clip rule: two sizes,
+half a size, a size beside `preferCssPageSize` or a non-finite measure is
+`X_SCRAPE_PDF_OPTIONS_INVALID` (422, terminal). The CDP driver forwards the layout in puppeteer's
+words (`pdf-print.ts`: `'210mm'`, `'A4'`, a blank template for the band the caller left empty); the
+offline drivers stamp it into deterministic bytes, so a dropped field fails a test. `As of 2026-11`.
+
 A rectangle **below the fold is accepted**. It is not checked against a viewport: this package
 neither sets nor reads one, and a component under the fold is the case a component crop is for.
 

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "scraping",
+    "browser",
+    "automation",
+    "cdp"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Scraping",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -31,9 +41,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/jobs": "29.3.2",
-    "@ultimat3/schema": "29.3.2",
-    "@ultimat3/storage": "29.3.2"
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/jobs": "30.0.0",
+    "@ultimat3/schema": "30.0.0",
+    "@ultimat3/storage": "30.0.0"
   }
 }

package/src/cdp-port.ts

@@ -31,6 +31,28 @@ export interface CdpScreenshotOptions {
   };
 }
 
+/**
+ * Puppeteer's `PDFOptions`, the part this package sends — restated for the screenshot options'
+ * reason. Lengths are CSS length strings (`'210mm'`); `format` is the library's own capitalised
+ * spelling (`'A4'`, `'Letter'`), which every version since 1.x accepts.
+ */
+export interface CdpPdfOptions {
+  readonly format?: string;
+  readonly width?: string;
+  readonly height?: string;
+  readonly margin?: {
+    readonly top?: string;
+    readonly right?: string;
+    readonly bottom?: string;
+    readonly left?: string;
+  };
+  readonly printBackground?: boolean;
+  readonly preferCSSPageSize?: boolean;
+  readonly displayHeaderFooter?: boolean;
+  readonly headerTemplate?: string;
+  readonly footerTemplate?: string;
+}
+
 export interface CdpRequestLike {
   url(): string;
   resourceType(): string;
@@ -77,7 +99,7 @@ export interface CdpPageLike {
   type(selector: string, text: string): Promise<void>;
   select(selector: string, ...values: string[]): Promise<string[]>;
   screenshot(options: CdpScreenshotOptions): Promise<Uint8Array | string>;
-  pdf(options?: Record<string, unknown>): Promise<Uint8Array>;
+  pdf(options?: CdpPdfOptions): Promise<Uint8Array>;
   setRequestInterception(enabled: boolean): Promise<void>;
   /**
    * The browser's own network condition — `Network.emulateNetworkConditions` under CDP.

package/src/cdp-target.ts

@@ -18,6 +18,7 @@ import {
 import { type ColorScheme, colorSchemeFeatures } from './color-scheme';
 import { browserUnreachable, pageCrashed } from './error-throws';
 import { parseKeyChord } from './key-chord';
+import { printOptionsOf } from './pdf-print';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
 import { boundedRing } from './rings';
 import type { SessionSnapshot } from './session-state';
@@ -26,6 +27,7 @@ import type {
   CaptureOptions,
   FrameRef,
   GotoOptions,
+  PdfOptions,
   ScrapeCookie,
   ScrapeDownloadFile,
   ScrapeTarget,
@@ -91,6 +93,13 @@ const isStructuralRefusal = (thrown: unknown): boolean =>
  */
 export interface CdpTargetInit extends CdpArmInit {
   readonly browser: CdpBrowserLike;
+  /**
+   * Why the session was ended from OUTSIDE the call, if it was — the fired wedge guard's reason.
+   * A thunk, because the guard is built after the target. Read before a failure is re-labelled:
+   * the fire closes the socket, so a call pending on it rejects, and that rejection is the fire's
+   * consequence. Labelled `X_SCRAPE_BROWSER_UNREACHABLE` it hides the cause and its fix.
+   */
+  readonly ended?: (() => unknown) | undefined;
 }
 
 export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
@@ -141,6 +150,8 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     try {
       return await run();
     } catch (thrown) {
+      const ended = init.ended?.();
+      if (ended !== undefined) throw ended;
       live();
       if (isStructuralRefusal(thrown)) throw thrown;
       throw browserUnreachable(`${CDP_DRIVER} ${what}`, thrown);
@@ -336,7 +347,7 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
           ? Uint8Array.from(atob(shot), (character) => character.charCodeAt(0))
           : shot;
       }),
-    pdf: (_options: CaptureOptions) => guard('pdf', () => init.page.pdf()),
+    pdf: (options: PdfOptions) => guard('pdf', () => init.page.pdf(printOptionsOf(options))),
     cookies: () =>
       guard('cookies', async () => {
         const source = init.browser as { cookies?: () => Promise<unknown> };

package/src/clock.ts

@@ -131,18 +131,3 @@ export function deadline(clock: Clock, totalMs: number, subject = 'a scrape wait
   const remainingMs = (): number => Math.max(0, budgetMs - (clock.monotonic() - startedAt));
   return { totalMs: budgetMs, remainingMs, expired: () => remainingMs() <= 0 };
 }
-
-/**
- * The timer a request DEADLINE is armed on (`deadline-signal.ts`) — not a wait this package
- * performs, but a timer all the same, so it lives here. Cleared when the request settles, where
- * `AbortSignal.timeout` stayed armed for its whole span after the answer had landed.
- */
-export interface DeadlineTimer {
-  set(fire: () => void, ms: number): unknown;
-  clear(handle: unknown): void;
-}
-
-export const platformDeadlineTimer: DeadlineTimer = Object.freeze({
-  set: (fire: () => void, ms: number): unknown => setTimeout(fire, ms),
-  clear: (handle: unknown): void => clearTimeout(handle as ReturnType<typeof setTimeout>),
-});

package/src/driver-cdp.ts

@@ -88,6 +88,7 @@ async function opened(
   browser: CdpBrowserLike,
   init: SessionInit,
   wiring: SessionWiring,
+  ended: () => unknown,
 ): Promise<ScrapeTarget> {
   try {
     const page = await browser.newPage();
@@ -105,7 +106,13 @@ async function opened(
       const { username, password } = splitCredentials(wiring.proxy);
       await page.authenticate({ username, password });
     }
-    const target = await cdpTarget({ page, browser, rules: init.rules, clock: init.clock });
+    const target = await cdpTarget({
+      page,
+      browser,
+      rules: init.rules,
+      clock: init.clock,
+      ended,
+    });
     if (init.restore !== undefined) await target.restore(init.restore);
     return target;
   } catch (thrown) {
@@ -140,7 +147,10 @@ async function sessionOver(
   // `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, wiring);
+  // Late-bound: the target is built before the guard that can end it. Until the guard exists no
+  // fire can have happened, so a failure inside `opened()` keeps its own label.
+  let ended = (): unknown => undefined;
+  const target = await opened(browser, init, wiring, () => ended());
   const guard = createWedgeGuard({
     clock: init.clock,
     what: `scrape "${init.name}"`,
@@ -158,6 +168,7 @@ async function sessionOver(
       child?.kill(9);
     },
   });
+  ended = () => (guard.fired ? guard.signal.reason : undefined);
   const onActivity = (): void => {
     guard.touch();
     init.onActivity?.();

package/src/error-throws-pdf.ts

@@ -0,0 +1,16 @@
+// The failure mode of a PDF layout request. Split from `error-throws.ts`, which stands at its size
+// ceiling; the code itself stays declared in `errors.ts` — one registry, one place.
+
+import { ScrapeError } from './errors';
+
+/**
+ * A layout no print engine lays out as asked. `reason` is built by `pdf-request.ts` from the
+ * caller's own numbers and literal format names — never from an unknown value.
+ */
+export const pdfOptionsInvalid = (reason: string, meta: { readonly field: string }): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_PDF_OPTIONS_INVALID',
+    cause: `page.pdf() cannot lay this document out: ${reason}`,
+    fix: "page.pdf({ format: 'a4', marginMm: { top: 12, bottom: 12 } }) — exactly one size: a format, or widthMm with heightMm, or preferCssPageSize alone",
+    meta: { field: meta.field },
+  });

package/src/error-throws.ts

@@ -203,7 +203,7 @@ export const wedged = (what: string, idleMs: number): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_WEDGED',
     cause: `${what} produced no browser activity for ${String(idleMs)}ms, so the process was killed`,
-    fix: 'raise watchdog: { idleMs } on the scrape() definition if the site is genuinely this slow, otherwise re-run — the browser was killed and its session is gone',
+    fix: 'raise watchdog: { idleMs } on the scrape() definition if the site is genuinely this slow, or call page.activity() from the channel the framework cannot see (your own CDP session, a warm-up), otherwise re-run — the browser was closed and its session is gone',
     meta: { what, idleMs },
   });
 

package/src/errors.ts

@@ -42,6 +42,7 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_EGRESS_UNSUPPORTED',
   'X_SCRAPE_EGRESS_IN_PAYLOAD',
   'X_SCRAPE_LAUNCH_ARGS_INVALID',
+  'X_SCRAPE_PDF_OPTIONS_INVALID',
 ] as const;
 
 /**
@@ -98,6 +99,8 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_EGRESS_IN_PAYLOAD: 'the run exit carries a credential that is also in the job payload',
   X_SCRAPE_LAUNCH_ARGS_INVALID:
     'the launch options carry arguments this driver cannot hand the browser',
+  X_SCRAPE_PDF_OPTIONS_INVALID:
+    'the PDF request names no single page size a print engine can lay out',
 };
 
 // One unconditional call, so a second package claiming one of these codes throws
@@ -208,6 +211,9 @@ export const SCRAPE_ERROR_RETRY = {
   // The args are the deploy's own literal: attempt 2 launches with the same list and is refused
   // the same way. Launching anyway is the retry that "works" from the worker's own address.
   X_SCRAPE_LAUNCH_ARGS_INVALID: 'terminal',
+  // The request is the caller's literal, refused before any driver sees it: attempt 2 asks for the
+  // same two sizes and is refused identically.
+  X_SCRAPE_PDF_OPTIONS_INVALID: 'terminal',
 } as const satisfies Readonly<Record<ScrapeOwnedErrorCode, 'retryable' | 'terminal'>>;
 
 registerErrorRetry(SCRAPE_ERROR_RETRY);

package/src/html-target.ts

@@ -15,6 +15,7 @@ import { markupRequests } from './html-requests';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict, refusalEntry } from './intercept';
 import { parseKeyChord } from './key-chord';
+import { pdfLayoutText } from './pdf-request';
 import type { PageRecording } from './recording';
 import { splitDownload } from './recording';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
@@ -27,6 +28,7 @@ import type {
   ElementSnapshot,
   FrameRef,
   GotoOptions,
+  PdfOptions,
   ScrapeCookie,
   ScrapeDownloadFile,
   ScrapeTarget,
@@ -64,6 +66,18 @@ const framedPng = (clip: CaptureClip | undefined, scheme: ColorScheme | null): U
 };
 const FAKE_PDF = new TextEncoder().encode('%PDF-1.4 offline');
 
+/**
+ * The PDF rule `framedPng` keeps for pictures: different deterministic bytes per layout, so a
+ * driver that dropped `format` or a margin fails a test instead of passing every one. No layout
+ * asked for is the old constant, so every digest asserted before this existed still holds.
+ */
+const laidOutPdf = (options: PdfOptions): Uint8Array => {
+  // The framing is not layout: a PDF has no clip (refused upstream) and is always the document.
+  const { fullPage: _fullPage, clip: _clip, ...layout } = options;
+  const notes = pdfLayoutText(layout);
+  return notes === '' ? FAKE_PDF : new TextEncoder().encode(`%PDF-1.4 offline ${notes}`);
+};
+
 export type RecordingLookup = (url: string) => Promise<PageRecording | undefined>;
 
 export interface HtmlTargetInit {
@@ -421,7 +435,7 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     },
     screenshot: (options: CaptureOptions): Promise<Uint8Array> =>
       Promise.resolve(framedPng(options.clip, colorScheme)),
-    pdf: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PDF),
+    pdf: (options: PdfOptions): Promise<Uint8Array> => Promise.resolve(laidOutPdf(options)),
     cookies: (): Promise<readonly ScrapeCookie[]> => Promise.resolve(session.cookies),
     session: (): Promise<SessionSnapshot> => Promise.resolve(session),
     restore: (next: SessionSnapshot): Promise<void> => {

package/src/http.ts

@@ -11,18 +11,18 @@
 // anti-bot systems look for.
 
 import { finiteCount, readWithinLimit } from '@ultimat3/core';
+import { type DeadlineTimer, deadlineSignal, resolveDialHost } from '@ultimat3/core/outbound';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse } from '@ultimat3/schema';
 import type { ScrapeClock } from './clock';
 import { cookieHeaderFor } from './cookie-scope';
-import { type DeadlineTimer, deadlineSignal } from './deadline-signal';
 import { bodyTooLarge, hostBlocked, httpFailed, redirectLoop, scrapeTimeout } from './error-throws';
 import type { RedirectHop } from './http-redirect';
 import { MAX_REDIRECT_HOPS, redirectHop } from './http-redirect';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict } from './intercept';
 import type { DialTarget, HostResolve } from './pinned-host';
-import { dialTarget, resolveHost } from './pinned-host';
+import { dialTarget } from './pinned-host';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
@@ -279,7 +279,7 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
    * The three gates, in one place, so the initial URL and hop seven are screened by the same code
    * in the same order. A second copy for redirects is how the two drift.
    */
-  const resolve = init.resolve ?? resolveHost;
+  const resolve = init.resolve ?? resolveDialHost;
   const screen = async (target: string): Promise<DialTarget> => {
     if (interceptVerdict(target, 'fetch', init.rules) !== 'allow') {
       throw hostBlocked(target, init.rules.allowHosts);

package/src/index.ts

@@ -25,6 +25,7 @@ export type {
   CdpKeyboardLike,
   CdpLauncherLike,
   CdpPageLike,
+  CdpPdfOptions,
   CdpRequestLike,
   CdpScreenshotOptions,
   CdpSessionLike,
@@ -145,6 +146,8 @@ export type {
 } from './page';
 export type { PageContext } from './page-over-target';
 export { pageOverTarget } from './page-over-target';
+export type { PdfFormat, PdfLayout, PdfMarginMm, PdfRequest } from './pdf-request';
+export { PDF_FORMATS } from './pdf-request';
 export type { Pacer } from './rate';
 export { scrapePacer } from './rate';
 export type { HttpRecording, PageRecording } from './recording';
@@ -229,6 +232,7 @@ export type {
   ElementSnapshot,
   FrameRef,
   GotoOptions,
+  PdfOptions,
   QueryOptions,
   ScrapeCookie,
   ScrapeDownloadFile,

package/src/page-over-target.ts

@@ -22,6 +22,7 @@ import type {
   WaitOptions,
 } from './page';
 import { DEFAULT_ACCESSIBILITY_MAX } from './page';
+import { type PdfRequest, pdfLayoutOf } from './pdf-request';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
 import { safeConsole, safeHtml, safeNetwork, safePageErrors } from './secrets';
@@ -232,9 +233,16 @@ async function guardNavigation(url: string, ctx: PageContext): Promise<void> {
 export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePage {
   const state: PageState = { tainted: false };
   const frame = frameOver(() => Promise.resolve(target), ctx, state, target.url());
+  // The page-level verbs hold their target rather than resolving it, so they skip `watched()` —
+  // and a minutes-long capture or cookie read then looked like a dead browser to the watchdog.
+  // Every one that reaches the browser goes through this instead.
+  const reported = (): ScrapeTarget => {
+    ctx.onActivity?.();
+    return target;
+  };
   const capture = async (
     kind: 'screenshot' | 'pdf',
-    options: CaptureRequest | undefined,
+    options: CaptureRequest | PdfRequest | undefined,
   ): Promise<Uint8Array> => {
     // The leak nobody remembers: a screenshot of a filled login form IS the password, in pixels,
     // in object storage, forever. Refused rather than masked — a mask over pixels is a guess
@@ -248,7 +256,10 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
       fullPage: options?.fullPage,
       ...(options?.clip === undefined ? {} : { clip: options.clip }),
     };
-    return kind === 'screenshot' ? target.screenshot(request) : target.pdf(request);
+    if (kind === 'screenshot') return reported().screenshot(request);
+    // The layout is checked here too, for the framing's reason: once, before any driver.
+    const layout = pdfLayoutOf(options ?? {});
+    return reported().pdf({ ...request, ...layout });
   };
   return {
     ...frame,
@@ -274,24 +285,30 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     // 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 });
+      return await reported().download({ timeoutMs: options?.timeout ?? ctx.defaultTimeoutMs });
     },
     // `async`, for `download()`'s reason: `ScrapeTarget` is the seam a third party implements, and
     // a driver that throws synchronously from a promise-typed method would escape `.catch()`.
     async offline(enabled: boolean): Promise<void> {
-      await target.setOfflineMode(enabled);
+      await reported().setOfflineMode(enabled);
     },
     // `async`, for `offline()`'s reason: a driver that throws synchronously from a promise-typed
     // method would escape the caller's `.catch()`.
     async colorScheme(scheme: ColorScheme): Promise<void> {
-      await target.setColorScheme(scheme);
+      await reported().setColorScheme(scheme);
     },
     // `async`, for `offline()`'s reason.
     async prepare(expression: string): Promise<void> {
-      await target.prepare(expression);
+      await reported().prepare(expression);
+    },
+    cookies: (): Promise<readonly ScrapeCookie[]> => reported().cookies(),
+    session: () => reported().session(),
+    // The app's own statement that work is happening on a channel this page cannot see — its own
+    // CDP session, a long warm-up. The watchdog's clock only: no usage is counted, because no
+    // navigation or request was made through the framework.
+    activity: (): void => {
+      ctx.onActivity?.();
     },
-    cookies: (): Promise<readonly ScrapeCookie[]> => target.cookies(),
-    session: () => target.session(),
     // Redacted BY VALUE on the way out, the same pass `html()` makes. A console line and a request
     // URL are two of the four surfaces `secrets.ts` names, and neither had a redaction caller: a
     // login endpoint fetched with the password in its query string, or a site that logs the

package/src/page.ts

@@ -11,6 +11,7 @@ import type { Secret } from '@ultimat3/core';
 import type { ActionabilityState } from './actionability';
 import type { CaptureFraming } from './capture-clip';
 import type { ColorScheme } from './color-scheme';
+import type { PdfRequest } from './pdf-request';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
 import type { SessionSnapshot } from './session-state';
 import type { AxNode, ElementSnapshot, ScrapeCookie, ScrapeDownloadFile } from './target';
@@ -127,11 +128,22 @@ export interface ScrapePage extends ScrapeFrame {
   goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<void>;
   /** PNG bytes. REFUSED once a secret has been typed into this page — see `secrets.ts`. */
   screenshot(options?: CaptureRequest): Promise<Uint8Array>;
-  /** PDF bytes. Refused on the same condition, for the same reason. */
-  pdf(options?: CaptureRequest): Promise<Uint8Array>;
+  /**
+   * PDF bytes, laid out as asked: paper (`format`, or `widthMm` + `heightMm`), `marginMm`,
+   * `printBackground`, `headerHtml`/`footerHtml`. Two sizes are `X_SCRAPE_PDF_OPTIONS_INVALID`.
+   * Refused once a secret was typed, for `screenshot()`'s reason.
+   */
+  pdf(options?: PdfRequest): Promise<Uint8Array>;
   /** The file the last click produced, or `X_SCRAPE_DOWNLOAD_TIMEOUT`. */
   download(options?: DownloadRequest): Promise<ScrapeDownloadFile>;
   cookies(): Promise<readonly ScrapeCookie[]>;
+  /**
+   * Tell the wedge watchdog the run is working on a channel this page cannot see — the app's own
+   * CDP session, a long warm-up. Every verb here already reports; this is for the work that does
+   * not go through one. Touches the watchdog's idle clock only and counts no usage. Present on
+   * every driver, so a run body never branches on which one it has.
+   */
+  activity(): void;
   /**
    * Cut the BROWSER's network, or restore it — what a PWA's offline behaviour has to be tested
    * against. Refused with `X_NOT_IMPLEMENTED` on a driver that has no browser: patching `fetch`

package/src/pdf-print.ts

@@ -0,0 +1,61 @@
+// A checked PDF layout in the CDP library's own words: millimetres become CSS lengths, a format its
+// capitalised name, a header or footer turns the print engine's header band on. Only the fields
+// the caller gave are sent — the engine's defaults stay the engine's.
+
+import type { CdpPdfOptions } from './cdp-port';
+import type { PdfFormat, PdfLayout } from './pdf-request';
+
+/** A `Map`, never a record indexed by the caller's string: `format: 'constructor'` names nothing. */
+const LIBRARY_FORMAT: ReadonlyMap<PdfFormat, string> = new Map([
+  ['letter', 'Letter'],
+  ['legal', 'Legal'],
+  ['tabloid', 'Tabloid'],
+  ['ledger', 'Ledger'],
+  ['a0', 'A0'],
+  ['a1', 'A1'],
+  ['a2', 'A2'],
+  ['a3', 'A3'],
+  ['a4', 'A4'],
+  ['a5', 'A5'],
+  ['a6', 'A6'],
+]);
+
+const mm = (value: number): string => `${String(value)}mm`;
+
+/**
+ * An empty template, never an absent one, for the band the caller left blank: with the band on and
+ * a template missing, Chrome prints its own date and URL there — an invoice footer nobody wrote.
+ */
+const BLANK_TEMPLATE = '<span></span>';
+
+export function printOptionsOf(layout: PdfLayout): CdpPdfOptions {
+  const margin = layout.marginMm;
+  const format = layout.format === undefined ? undefined : LIBRARY_FORMAT.get(layout.format);
+  const band = layout.headerHtml !== undefined || layout.footerHtml !== undefined;
+  return {
+    ...(format === undefined ? {} : { format }),
+    ...(layout.widthMm === undefined ? {} : { width: mm(layout.widthMm) }),
+    ...(layout.heightMm === undefined ? {} : { height: mm(layout.heightMm) }),
+    ...(margin === undefined
+      ? {}
+      : {
+          margin: {
+            ...(margin.top === undefined ? {} : { top: mm(margin.top) }),
+            ...(margin.right === undefined ? {} : { right: mm(margin.right) }),
+            ...(margin.bottom === undefined ? {} : { bottom: mm(margin.bottom) }),
+            ...(margin.left === undefined ? {} : { left: mm(margin.left) }),
+          },
+        }),
+    ...(layout.printBackground === undefined ? {} : { printBackground: layout.printBackground }),
+    ...(layout.preferCssPageSize === undefined
+      ? {}
+      : { preferCSSPageSize: layout.preferCssPageSize }),
+    ...(band
+      ? {
+          displayHeaderFooter: true,
+          headerTemplate: layout.headerHtml ?? BLANK_TEMPLATE,
+          footerTemplate: layout.footerHtml ?? BLANK_TEMPLATE,
+        }
+      : {}),
+  };
+}

package/src/pdf-request.ts

@@ -0,0 +1,125 @@
+// The print layout a PDF is asked for — paper, margins, background, header and footer — and the
+// one check that refuses a request no print engine can honour. Decided ONCE, in `page-over-target.ts`,
+// before any driver: two sizes resolve silently in Chrome (the format wins), which is an invoice
+// laid out on paper nobody asked for.
+
+import type { CaptureFraming } from './capture-clip';
+import { pdfOptionsInvalid } from './error-throws-pdf';
+
+/** The named paper sizes every print engine knows. Lowercase: the spelling is this package's. */
+export const PDF_FORMATS = [
+  'letter',
+  'legal',
+  'tabloid',
+  'ledger',
+  'a0',
+  'a1',
+  'a2',
+  'a3',
+  'a4',
+  'a5',
+  'a6',
+] as const;
+
+export type PdfFormat = (typeof PDF_FORMATS)[number];
+
+/** Millimetres on each side. An absent side is the engine's own default. */
+export interface PdfMarginMm {
+  readonly top?: number | undefined;
+  readonly right?: number | undefined;
+  readonly bottom?: number | undefined;
+  readonly left?: number | undefined;
+}
+
+/**
+ * What a print engine lays a document out on. Exactly one size: a `format`, or `widthMm` WITH
+ * `heightMm`, or `preferCssPageSize` (the document's own `@page`) — or none, the engine's letter.
+ * `headerHtml` / `footerHtml` are print templates: Chrome fills `.pageNumber`, `.totalPages`,
+ * `.date`, `.title` and `.url` inside them.
+ */
+export interface PdfLayout {
+  readonly format?: PdfFormat | undefined;
+  readonly widthMm?: number | undefined;
+  readonly heightMm?: number | undefined;
+  readonly marginMm?: PdfMarginMm | undefined;
+  readonly printBackground?: boolean | undefined;
+  readonly preferCssPageSize?: boolean | undefined;
+  readonly headerHtml?: string | undefined;
+  readonly footerHtml?: string | undefined;
+}
+
+/** `page.pdf()`'s argument: the layout, plus the framing every capture shares (a clip is refused). */
+export interface PdfRequest extends CaptureFraming, PdfLayout {}
+
+const SIDES = ['top', 'right', 'bottom', 'left'] as const;
+
+const isFormat = (value: string): value is PdfFormat =>
+  (PDF_FORMATS as readonly string[]).includes(value);
+
+function measure(field: string, value: number | undefined, floor: 'positive' | 'zero'): void {
+  if (value === undefined) return;
+  const ok = Number.isFinite(value) && (floor === 'positive' ? value > 0 : value >= 0);
+  if (!ok) {
+    throw pdfOptionsInvalid(
+      `${field} is ${String(value)}, and a page measure is a finite number of millimetres${floor === 'positive' ? ' above zero' : ', zero or more'}`,
+      { field },
+    );
+  }
+}
+
+/**
+ * The layout half of a request, checked. Answers only the fields that were given, so a driver sees
+ * exactly what the caller asked for and supplies its own default for the rest.
+ */
+export function pdfLayoutOf(request: PdfRequest): PdfLayout {
+  const { format, widthMm, heightMm, preferCssPageSize } = request;
+  if (format !== undefined && !isFormat(format)) {
+    throw pdfOptionsInvalid(`format "${String(format)}" is not one of ${PDF_FORMATS.join(', ')}`, {
+      field: 'format',
+    });
+  }
+  measure('widthMm', widthMm, 'positive');
+  measure('heightMm', heightMm, 'positive');
+  for (const side of SIDES) measure(`marginMm.${side}`, request.marginMm?.[side], 'zero');
+  const sized = widthMm !== undefined || heightMm !== undefined;
+  if (format !== undefined && sized) {
+    throw pdfOptionsInvalid(
+      `the request names format "${format}" and widthMm/heightMm, and Chrome silently lays it out on the format`,
+      { field: 'format' },
+    );
+  }
+  if (sized && (widthMm === undefined || heightMm === undefined)) {
+    throw pdfOptionsInvalid(
+      `the request names ${widthMm === undefined ? 'heightMm' : 'widthMm'} alone, which is half a page`,
+      { field: widthMm === undefined ? 'heightMm' : 'widthMm' },
+    );
+  }
+  if (preferCssPageSize === true && (format !== undefined || sized)) {
+    throw pdfOptionsInvalid(
+      'the request names a size and preferCssPageSize: true, and the document @page rule then silently wins over it',
+      { field: 'preferCssPageSize' },
+    );
+  }
+  return {
+    ...(format === undefined ? {} : { format }),
+    ...(widthMm === undefined ? {} : { widthMm }),
+    ...(heightMm === undefined ? {} : { heightMm }),
+    ...(request.marginMm === undefined ? {} : { marginMm: { ...request.marginMm } }),
+    ...(request.printBackground === undefined ? {} : { printBackground: request.printBackground }),
+    ...(preferCssPageSize === undefined ? {} : { preferCssPageSize }),
+    ...(request.headerHtml === undefined ? {} : { headerHtml: request.headerHtml }),
+    ...(request.footerHtml === undefined ? {} : { footerHtml: request.footerHtml }),
+  };
+}
+
+/** The same layout as one deterministic line — what an offline driver stamps into its bytes. */
+export function pdfLayoutText(layout: PdfLayout): string {
+  // Sorted by hand: a replacer ARRAY would also filter `marginMm`'s own keys out of the line.
+  const margin = layout.marginMm;
+  const sides = margin === undefined ? '' : SIDES.map((side) => String(margin[side])).join('/');
+  return Object.entries({ ...layout, marginMm: sides === '' ? undefined : sides })
+    .filter(([, value]) => value !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]) => `${key}=${String(value)}`)
+    .join(' ');
+}

package/src/pinned-host.ts

@@ -2,19 +2,17 @@
 // robots read. Core's `hostDecision` is synchronous and judges NAMES: a wildcard never admits an
 // address literal inside the network, but `allowHosts: ['*']` still admits a hostname that
 // resolves inward. So a name admitted by a wildcard alone is resolved here, every address
-// classified by core's one classifier, and the connection PINNED to the approved address — the
-// shape `@ultimat3/jobs`' `webhook-target.ts` takes for a webhook.
+// classified and the connection PINNED to the approved address by core's `screenDial` — the one
+// screen `@ultimat3/jobs`' `webhook-target.ts` and `outbound()` call too. This keeps its own code.
 
 import type { HostRule } from '@ultimat3/core';
 import { classifyAddress, hostMatches } from '@ultimat3/core';
+import type { DialResolve } from '@ultimat3/core/outbound';
+import { screenDial } from '@ultimat3/core/outbound';
 import { hostResolvesInward } from './error-throws-session';
 
 /** Every address a hostname answers. Injected in tests: the network is sealed in this repo. */
-export type HostResolve = (hostname: string) => Promise<readonly string[]>;
-
-/** `Bun.dns.lookup` — the runtime's own resolver, every family, every address. */
-export const resolveHost: HostResolve = async (hostname) =>
-  (await Bun.dns.lookup(hostname)).map((entry) => entry.address);
+export type HostResolve = DialResolve;
 
 /** What the transport connects to: the URL to dial, and the name it proves when pinned. */
 export interface DialTarget {
@@ -49,17 +47,10 @@ export async function dialTarget(
   const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
   if (classifyAddress(hostname) !== undefined) return { url };
   if (allowHosts.some((rule) => !isWildcard(rule) && hostMatches(hostname, rule))) return { url };
-  const addresses = await resolve(hostname);
-  const inward = addresses.map((address) => classifyAddress(address) ?? 'unclassifiable');
-  const refused =
-    addresses.length === 0 ? 'unresolvable' : inward.find((kind) => kind !== 'public');
-  if (refused !== undefined) throw hostResolvesInward(url, hostname, refused);
-  const pinned = addresses[0] ?? hostname;
-  const target = new URL(parsed.href);
-  target.hostname = pinned.includes(':') ? `[${pinned}]` : pinned;
-  return {
-    url: target.href,
-    host: parsed.host,
-    ...(parsed.protocol === 'https:' ? { serverName: hostname } : {}),
-  };
+  const verdict = await screenDial(parsed, { resolve });
+  if ('pin' in verdict) return verdict.pin;
+  // A resolver failure propagates as itself: nothing unscreened is dialled, and the same name
+  // would not have resolved for `fetch` either. No address at all is refused, as before.
+  if ('unresolved' in verdict && verdict.error !== undefined) throw verdict.error;
+  throw hostResolvesInward(url, hostname, 'refused' in verdict ? verdict.refused : 'unresolvable');
 }

package/src/robots-fetch.ts

@@ -10,12 +10,12 @@
 
 import type { HostRule } from '@ultimat3/core';
 import { finiteCount, isUltimateError, readWithinLimit } from '@ultimat3/core';
-import { type DeadlineTimer, deadlineSignal } from './deadline-signal';
+import { type DeadlineTimer, deadlineSignal, resolveDialHost } from '@ultimat3/core/outbound';
 import type { ScrapeFetch } from './http';
 import { redirectHop } from './http-redirect';
 import { interceptVerdict } from './intercept';
 import type { HostResolve } from './pinned-host';
-import { dialTarget, resolveHost } from './pinned-host';
+import { dialTarget } from './pinned-host';
 import type { RobotsAnswer, RobotsFetch } from './robots';
 
 /**
@@ -116,7 +116,7 @@ const answerOf = async (response: Response, limit: number): Promise<RobotsAnswer
  */
 export function robotsFetcher(init: RobotsFetchInit = {}): RobotsFetch {
   const call: ScrapeFetch = init.fetch ?? fetch;
-  const resolve = init.resolve ?? resolveHost;
+  const resolve = init.resolve ?? resolveDialHost;
   // Both bounds are screened HERE, at construction, and both floors are 1 — because a bad bound
   // turns into a failed read on every origin, and a read that fails is never evidence of a rule. A
   // `NaN` deadline throws a bare `TypeError` out of `AbortSignal.timeout` (measured: "Value NaN is

package/src/target.ts

@@ -5,6 +5,7 @@
 
 import type { CaptureFraming } from './capture-clip';
 import type { ColorScheme } from './color-scheme';
+import type { PdfLayout } from './pdf-request';
 import type { ConsoleRing, NetworkRing, PageErrorRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 
@@ -122,6 +123,12 @@ export interface GotoOptions {
  */
 export type CaptureOptions = CaptureFraming;
 
+/**
+ * A PDF capture: the framing plus the print layout, already checked by `pdfLayoutOf` — a driver
+ * forwards every field it is given and invents none.
+ */
+export type PdfOptions = CaptureOptions & PdfLayout;
+
 /**
  * The port. Every member is something a browser genuinely does and nothing a scraper's vocabulary
  * should be re-deriving per driver. NO COUNT: this comment said "Twelve methods" while the
@@ -228,7 +235,7 @@ export interface ScrapeTarget {
    */
   prepare(expression: string): Promise<void>;
   screenshot(options: CaptureOptions): Promise<Uint8Array>;
-  pdf(options: CaptureOptions): Promise<Uint8Array>;
+  pdf(options: PdfOptions): Promise<Uint8Array>;
   cookies(): Promise<readonly ScrapeCookie[]>;
   /** Whatever the last click/navigation produced as a file, or a `X_SCRAPE_DOWNLOAD_TIMEOUT`. */
   download(options: { readonly timeoutMs: number }): Promise<ScrapeDownloadFile>;

package/src/watchdog.ts

@@ -65,15 +65,45 @@ export function createWedgeGuard(init: WedgeGuardInit): WedgeGuard {
   const graceMs = finiteCount('the scrape watchdog', 'graceMs', init.graceMs ?? DEFAULT_GRACE_MS);
   const controller = new AbortController();
   let lastTouch = init.clock.monotonic();
-  // TWO latches, not one. `stopped` ends the watch loop; `shuttingDown` guards the teardown. They
-  // were the same flag, so a fire — which sets `stopped` — made `shutdown()` return on its first
-  // line and NEVER call `quit()`. `localBrowser()` hid it, because the fire's `kill()` still
-  // reaches a pid; `remoteBrowser()` is `driver-cdp.ts`'s primary path, `browser.process()` is
-  // `null` there, and `browser.close()` is then the only thing that ends the paid remote session.
+  // TWO latches, not one. `stopped` ends the watch loop; the memoised `teardown` below guards
+  // the quit. They were the same flag, so a fire — which sets `stopped` — made `shutdown()`
+  // return on its first line and NEVER call `quit()`. `localBrowser()` hid it, because the fire's
+  // `kill()` still reaches a pid; `remoteBrowser()` is `driver-cdp.ts`'s primary path,
+  // `browser.process()` is `null` there, and `browser.close()` is then the only thing that ends
+  // the paid remote session.
   let stopped = false;
-  let shuttingDown = false;
   let fired = false;
 
+  const ceilinged = async (): Promise<void> => {
+    let quit = false;
+    // A ceiling, not a hope: whichever finishes first wins, and if it is the clock the process
+    // is killed. `browser.close()` on a wedged renderer never returns.
+    await Promise.race([
+      init.quit().then(
+        () => {
+          quit = true;
+        },
+        () => {
+          quit = false;
+        },
+      ),
+      // The ceiling's own sleep is caught for the same reason the quit is: this runs in
+      // `runScrape`'s `finally`, `close()` is documented never to throw, and a clock that
+      // rejected here would replace the run's real failure with a teardown one. A ceiling that
+      // cannot be timed has already expired, which lands on `kill()` — the safe direction.
+      init.clock.sleep(graceMs).catch(() => undefined),
+    ]);
+    if (!quit) init.kill();
+  };
+
+  // ONE teardown, shared by the fire and `shutdown()`: the polite quit raced against the ceiling,
+  // then the kill. Memoised, so a fire followed by the run's own `close()` quits once and kills at
+  // most twice (the fire's, and the ceiling's) rather than starting a second race.
+  let teardown: Promise<void> | undefined;
+  const end = (): Promise<void> => {
+    teardown ??= ceilinged();
+    return teardown;
+  };
   const watch = async (): Promise<void> => {
     while (!stopped) {
       await init.clock.sleep(WATCH_POLL_MS);
@@ -84,8 +114,19 @@ export function createWedgeGuard(init: WedgeGuardInit): WedgeGuard {
       // Kill FIRST, abort second. The abort is what the awaiting code sees; the kill is what
       // makes the socket it is blocked on close. Reversing them leaves the run cancelled and the
       // browser alive, which is the zombie half of the same incident.
-      init.kill();
-      controller.abort(wedged(init.what, idleMs));
+      // `finally`: a throwing `kill()` still ends the run — `stopped` is already set, so the loop's
+      // catch below would return early and leave the run unaborted behind a dead guard.
+      try {
+        init.kill();
+      } finally {
+        // And the QUIT, now, not at unwind. On an attached browser the kill above reaches nothing —
+        // `process()` is `null` — and a call blocked on the socket (`evaluate` takes no signal) never
+        // unwinds to `close()`. Closing the browser is what rejects it. Unawaited: the abort below
+        // must not wait out a hung quit; `shutdown()` awaits this same promise. Its only rejection
+        // is a throwing `kill()`, which `shutdown()` hands its caller exactly as before.
+        void end().catch(() => undefined);
+        controller.abort(wedged(init.what, idleMs));
+      }
     }
   };
   // Never floating. `ScrapeClock` is a seam an app implements and `init.kill()` comes from a
@@ -109,28 +150,8 @@ export function createWedgeGuard(init: WedgeGuardInit): WedgeGuard {
       lastTouch = init.clock.monotonic();
     },
     async shutdown(): Promise<void> {
-      if (shuttingDown) return;
-      shuttingDown = true;
       stopped = true;
-      let quit = false;
-      // A ceiling, not a hope: whichever finishes first wins, and if it is the clock the process
-      // is killed. `browser.close()` on a wedged renderer never returns.
-      await Promise.race([
-        init.quit().then(
-          () => {
-            quit = true;
-          },
-          () => {
-            quit = false;
-          },
-        ),
-        // The ceiling's own sleep is caught for the same reason the quit is: this runs in
-        // `runScrape`'s `finally`, `close()` is documented never to throw, and a clock that
-        // rejected here would replace the run's real failure with a teardown one. A ceiling that
-        // cannot be timed has already expired, which lands on `kill()` — the safe direction.
-        init.clock.sleep(graceMs).catch(() => undefined),
-      ]);
-      if (!quit) init.kill();
+      await end();
     },
   };
 }

package/src/deadline-signal.ts

@@ -1,46 +0,0 @@
-// One request's signal: a deadline plus the caller's own signal, undone when the request settles.
-// `AbortSignal.any([AbortSignal.timeout(ms), outer])` composed the same thing and could not be
-// undone — every read hung one listener (and one composite) on a session-long `outer` and armed a
-// timer that outlived the answer. The shape is `@ultimat3/jobs`' `createRunSignal`.
-
-import { type DeadlineTimer, platformDeadlineTimer } from './clock';
-
-export type { DeadlineTimer } from './clock';
-
-export interface DeadlineSignal extends Disposable {
-  /** Aborts at the deadline (a `TimeoutError`, as `AbortSignal.timeout`'s) or with `outer`. */
-  readonly signal: AbortSignal;
-  /** Whether the DEADLINE fired — not the caller cancelling. What the timeout code is chosen by. */
-  timedOut(): boolean;
-}
-
-/**
- * `ms` is the caller's already-screened deadline (a positive finite count). `[Symbol.dispose]`
- * clears the timer and detaches from `outer`; idempotent, and it never aborts.
- */
-export function deadlineSignal(
-  ms: number,
-  outer?: AbortSignal,
-  timer: DeadlineTimer = platformDeadlineTimer,
-): DeadlineSignal {
-  const controller = new AbortController();
-  let fired = false;
-  const handle = timer.set(() => {
-    fired = true;
-    controller.abort(new DOMException('The operation timed out.', 'TimeoutError'));
-  }, ms);
-  const forward = (): void => controller.abort(outer?.reason);
-  if (outer?.aborted === true) forward();
-  else outer?.addEventListener('abort', forward, { once: true });
-  let open = true;
-  return {
-    signal: controller.signal,
-    timedOut: () => fired,
-    [Symbol.dispose]: () => {
-      if (!open) return;
-      open = false;
-      timer.clear(handle);
-      outer?.removeEventListener('abort', forward);
-    },
-  };
-}