@ultimat3/scraping 20.2.0 → 20.2.1

package/package.json

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

package/src/cdp-fake.ts

@@ -98,6 +98,12 @@ export interface FakeCdpBrowser extends CdpBrowserLike {
   readonly pressed: readonly string[];
   /** Every selector `page.focus()` was handed, in order. */
   readonly focused: readonly string[];
+  /**
+   * Every expression `page.evaluateOnNewDocument()` was handed, in order — the scripts a real
+   * browser would run ahead of each document's own. Recorded, never executed: this fake has no JS
+   * engine, and a test asserts on WHAT was prepared and that it was prepared before `goto`.
+   */
+  readonly prepared: readonly string[];
   /** How many raw CDP sessions were created and how many detached — a leak is a difference. */
   readonly sessions: { readonly created: number; readonly detached: number };
 }
@@ -149,6 +155,7 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
   let cookies: readonly ScrapeCookie[] = init.cookies ?? [];
   const pressed: string[] = [];
   const focused: string[] = [];
+  const prepared: string[] = [];
   const sessions = { created: 0, detached: 0 };
   const axBySelector = init.accessibility ?? {};
 
@@ -316,6 +323,10 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
       focused.push(selector);
       return Promise.resolve();
     },
+    evaluateOnNewDocument: (expression: string) => {
+      prepared.push(expression);
+      return Promise.resolve(undefined);
+    },
     createCDPSession: () => {
       sessions.created += 1;
       return Promise.resolve(cdpSession());
@@ -391,6 +402,7 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
     },
     pressed,
     focused,
+    prepared,
     sessions,
   };
 }

package/src/cdp-port.ts

@@ -129,6 +129,14 @@ export interface CdpPageLike {
   readonly keyboard?: CdpKeyboardLike | undefined;
   /** `page.focus(selector)`. OPTIONAL for `keyboard`'s reason, and refused by name when absent. */
   focus?(selector: string): Promise<void>;
+  /**
+   * `page.evaluateOnNewDocument(expression)`: a script the browser runs in EVERY document this
+   * page navigates to, before any of the document's own scripts — `Page.addScriptToEvaluateOnNewDocument`
+   * under CDP. It is the only moment that beats an inlined boot script, which is what a
+   * storage-seeded theme choice needs (`ScrapePage.prepare`). The string form, for `evaluate`'s
+   * reason. OPTIONAL for `keyboard`'s reason, and refused by name when absent.
+   */
+  evaluateOnNewDocument?(expression: string): Promise<unknown>;
   /**
    * A raw protocol session, for the one read this package makes that the library has no method
    * for: the accessibility tree (`Accessibility.getPartialAXTree`). OPTIONAL for `keyboard`'s

package/src/cdp-target.ts

@@ -300,6 +300,18 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         // puppeteer's own `Page` needs it.
         await emulate.call(init.page, colorSchemeFeatures(scheme));
       }),
+    prepare: (expression: string): Promise<void> =>
+      guard('prepare', async () => {
+        // 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',
+          );
+        }
+        await evaluateOnNewDocument.call(init.page, expression);
+      }),
     screenshot: (options: CaptureOptions) =>
       guard('screenshot', async () => {
         // `fullPage` is OMITTED when a clip is given rather than sent as `false`: the two are

package/src/html-target.ts

@@ -412,6 +412,18 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
       colorScheme = scheme === 'no-preference' ? null : scheme;
       return Promise.resolve();
     },
+    /**
+     * ACCEPTED, for `setColorScheme`'s reason and not `setOfflineMode`'s. This driver parses
+     * markup and executes none of it, so there is no document script for the expression to run
+     * ahead of — and no assertion a resolved promise could let through: what a prepared script
+     * seeds is the INPUT to a boot this driver never runs. Refusing would cost `x shot` and every
+     * `ui.*` tool their unit tests on a machine with no Chrome, for an outcome that does not exist
+     * here. `live()` still refuses a closed target, which is the one thing this can be wrong about
+     * — and `async`, so that refusal REJECTS rather than escaping a caller's `.catch()`.
+     */
+    async prepare(_expression: string): Promise<void> {
+      live();
+    },
     screenshot: (options: CaptureOptions): Promise<Uint8Array> =>
       Promise.resolve(framedPng(options.clip, colorScheme)),
     pdf: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PDF),

package/src/page-over-target.ts

@@ -274,6 +274,10 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     async colorScheme(scheme: ColorScheme): Promise<void> {
       await target.setColorScheme(scheme);
     },
+    // `async`, for `offline()`'s reason.
+    async prepare(expression: string): Promise<void> {
+      await target.prepare(expression);
+    },
     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

package/src/page.ts

@@ -154,6 +154,18 @@ export interface ScrapePage extends ScrapeFrame {
    * method, which is a fact about the build rather than about the driver.
    */
   colorScheme(scheme: ColorScheme): Promise<void>;
+  /**
+   * A script the browser runs in EVERY document this page navigates to, BEFORE the document's
+   * own scripts — the one moment that beats an inlined boot script. Call it before `goto()`: what
+   * it seeds (a `localStorage` key a boot reads, a flag a component checks) is then in place for
+   * the first script the page executes, where an `evaluate()` after navigation is one boot too
+   * late. Same string discipline as `evaluate()`: an expression, never a closure.
+   *
+   * ACCEPTED on every driver, for `colorScheme()`'s reason: the offline drivers run no scripts,
+   * so nothing there could be wrong about it. `X_NOT_IMPLEMENTED` is reserved for a LAUNCHER
+   * that lacks the method, which is a fact about the build rather than about the driver.
+   */
+  prepare(expression: string): Promise<void>;
   /**
    * The handoff, made explicit: what the HTTP leg will send, as a value an author can inspect and
    * a fixture can assert on. `http` uses it automatically — this is for seeing what carried over.

package/src/target.ts

@@ -201,6 +201,20 @@ export interface ScrapeTarget {
    * so a driver that dropped the preference fails a test rather than passing every one.
    */
   setColorScheme(scheme: ColorScheme): Promise<void>;
+  /**
+   * A script every document this target navigates to runs BEFORE its own — the browser's
+   * `evaluateOnNewDocument`. REQUIRED here where `CdpPageLike.evaluateOnNewDocument` is optional,
+   * for `setOfflineMode`'s reason: the asymmetry is the enforcement, and a launcher without the
+   * method is `X_NOT_IMPLEMENTED`.
+   *
+   * A DRIVER WITH NO JS ENGINE ACCEPTS IT, for `setColorScheme`'s reason and not
+   * `setOfflineMode`'s: the offline drivers execute nothing, so there is no document script for
+   * the expression to run ahead of and no assertion a resolved promise could let through — a
+   * seeded `localStorage` key is the INPUT to a boot script this driver never runs. Refusing
+   * would make `x shot` and every `ui.*` tool untestable on a machine with no Chrome, and the
+   * outcome it would protect does not exist here. The call is still checked for a closed target.
+   */
+  prepare(expression: string): Promise<void>;
   screenshot(options: CaptureOptions): Promise<Uint8Array>;
   pdf(options: CaptureOptions): Promise<Uint8Array>;
   cookies(): Promise<readonly ScrapeCookie[]>;