@ultimat3/scraping 24.0.0 → 25.1.0

package/README.md

@@ -84,6 +84,15 @@ Both legs replay from **one** fixture directory (`fixtureBrowser(dir)`), so a hy
 login, session handoff, HTTP bulk fetch — is tested end to end. Both legs apply the same robots
 gate, offline included.
 
+The robots gate follows RFC 9309 §2.3.1: a `4xx` robots.txt is **unavailable** (no rules); a `5xx`,
+a network error or the deadline is **unreachable**, which refuses every path on the origin
+(`X_SCRAPE_ROBOTS_DISALLOWED`) and is not cached. A `429` is a `4xx` the RFC calls unavailable; this
+gate treats it as unreachable anyway — our stricter policy, since a server that is rate-limiting
+the crawler has not said "no rules". A hand-written `fetchText` answers the text,
+`undefined` (no file) or `{ unreachable: '<why>' }` — `RobotsAnswer`. An offline scrape declares
+`robots: { ignore: 'offline fixture' }`: under the sealed test network its robots read is
+unreachable.
+
 ## A session a service is built on
 
 One connection, one run at a time, on its own exit, in a browser rented for that run — with a
@@ -210,7 +219,7 @@ export const answer = (input: { runId: string; index: number; answer: string })
 | `onSettled` | the job's own hook (`@ultimat3/jobs`), with what a scrape adds: `completed` hands over the `ScrapeReport`; `dead-lettered` / `dropped` / `refused` carry `code` and the last attempt's `usage` (`undefined` for `refused` — the body never ran). After the row is settled, under the job's tenant, **at most once** across a crash, and a hook that throws changes nothing |
 | `run({ progress, finalAttempt })` | the job's own, passed through |
 | `prompt` | `eventPrompt({ timeout, pollMs?, bus?, keySource?, env? })` polls the event bus in process — never `step.waitForEvent`, which would close the browser. An in-memory bus (`stored: false`) is refused outside development and test (`X_DRIVER_UNAVAILABLE`): the answer comes from another process. Event `promptEventName(runId, index)`; answered by `answerPrompt({ runId, index, answer })`, sealed for that one name. Timeout is `X_SCRAPE_PROMPT_UNANSWERED` |
-| the bus | the **stored** one (`createPgEventBus`) wherever the worker and the answering process differ. Every `x` boot installs it |
+| the bus | the **stored** one (`postgresEventBus`) wherever the worker and the answering process differ. Every `x` boot installs it |
 
 `PromptRequest` carries the run's `input` and `runId` — what ties a prompt to the app's own row
 for the run — and `index`, `clock`, `signal` and `keepAlive()` beside `label`, `scrape` and `url`:
@@ -240,7 +249,7 @@ resetScrapeClock(); // in the afterEach
 |---|---|---|
 | `systemScrapeClock` | waits | production |
 | `noWaitClock` | one turn of the event loop, whatever was asked; `now()` and deadlines are real | a test whose run waits on something that really happens in the same process — an answer the test publishes |
-| `testClock()` | advances virtual time and yields a microtask | a test of a timeout: thirty seconds pass in none |
+| `testScrapeClock()` | advances virtual time and yields a microtask | a test of a timeout: thirty seconds pass in none |
 
 A third-party driver takes part by reading three `SessionInit` fields: dial `proxy` or throw
 `egressUnsupported()`, pass `usage` to `pageOverTarget` and its HTTP transport, and answer
@@ -261,6 +270,14 @@ the port's. A caller that had to compute its own wrote
 `display !== 'none' && visibility !== 'hidden' && opacity !== '0'` a second time, which is the
 copy axiom 1 forbids.
 
+**An act scrolls its element into view; a read does not.** The `actionable` wait (every `click`,
+`type`, `fill`, `select`, `focus`, and `waitFor` at its default state) calls
+`ScrapeTarget.query(selector, { reveal: true })`, which scrolls the first match to the viewport's
+centre before measuring — `elementFromPoint` answers nothing off-screen, so an element below the
+fold read as covered. `text()`, `count()`, `values()` and `query()` never move the page. A target
+with no layout engine ignores `QueryOptions` (`cdp-target-reveal.test.ts`,
+`cdp-snapshot.e2e.test.ts`).
+
 **A frame verb reaches the FRAME.** `fill`, `type`, `select`, `clear`, `click` and `query` through
 a `ScrapeFrame` handle all address that frame's own document — never the parent's, even when the
 two carry the same ids, which is what an iframe'd SSO login looks like. `driver-parity-frames.test.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
   "license": "MIT",
   "type": "module",
@@ -24,16 +24,16 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/jobs": "24.0.0",
-    "@ultimat3/schema": "24.0.0",
-    "@ultimat3/storage": "24.0.0"
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/jobs": "25.1.0",
+    "@ultimat3/schema": "25.1.0",
+    "@ultimat3/storage": "25.1.0"
   }
 }

package/src/artifacts.ts

@@ -5,7 +5,7 @@
 // Written through `@ultimat3/storage`'s driver, so the same call lands on a local disk in
 // development and on S3 in production, and this package owns no upload path of its own.
 
-import type { StorageDriver } from '@ultimat3/storage';
+import { DEFAULT_CONTENT_TYPE, type StorageDriver } from '@ultimat3/storage';
 
 export interface ArtifactRef {
   readonly key: string;
@@ -31,8 +31,6 @@ export interface ArtifactWriterInit {
 
 export const DEFAULT_ARTIFACT_PREFIX = 'scrape';
 
-export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
-
 /**
  * A `Map`, not an object literal — the same choice `failures.ts` makes, for the same reason. The
  * extension comes off a caller-supplied filename, and on a download that filename came off the
@@ -57,7 +55,7 @@ export const contentTypeFor = (name: string): string =>
  * that has not configured storage should still be able to run a scrape; losing the artifact is a
  * cost, and refusing the run over it is a bigger one.
  */
-export function createArtifactWriter(init: ArtifactWriterInit): ArtifactWriter {
+export function artifactWriter(init: ArtifactWriterInit): ArtifactWriter {
   const saved: ArtifactRef[] = [];
   const prefix = `${init.prefix ?? DEFAULT_ARTIFACT_PREFIX}/${init.scrape}/${init.runId}`;
   return {

package/src/auth.ts

@@ -20,7 +20,7 @@
 import type { Logger } from '@ultimat3/core';
 import { finiteCount } from '@ultimat3/core';
 import type { ScrapeClock } from './clock';
-import { authFailed, promptUnanswered, sessionExpired } from './error-throws';
+import { authFailed, promptUnanswered, scrapeSessionExpired } from './error-throws';
 import type { ScrapePage } from './page';
 import type { ScrapeSecrets } from './secrets';
 import {
@@ -124,7 +124,7 @@ export interface PromptInit<I = unknown> {
  */
 const KEEPALIVE_SELECTOR = 'ultimate-keepalive';
 
-export function createPrompt<I>(init: PromptInit<I>): (label: string) => Promise<string> {
+export function scrapePrompt<I>(init: PromptInit<I>): (label: string) => Promise<string> {
   let asked = 0;
   return async (label: string): Promise<string> => {
     const { scrape, handler, page } = init;
@@ -316,7 +316,7 @@ export async function ensureAuthenticated<I>(args: EnsureAuthInput<I>): Promise<
     args.logger.info('scrape.session.expired', { reused: false });
     await burnSession(args, recordVersion(args.restored));
   }
-  if (auth.login === undefined) throw sessionExpired(args.scrape, args.key);
+  if (auth.login === undefined) throw scrapeSessionExpired(args.scrape, args.key);
   await auth.login(context);
   return true;
 }

package/src/cdp-snapshot.ts

@@ -8,16 +8,24 @@
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
 import { browserRecord } from './browser-record';
-import type { ElementSnapshot } from './target';
+import type { ElementSnapshot, QueryOptions } 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.
+ *
+ * `reveal` scrolls BEFORE the loop, so every box below is measured where the page now is — the
+ * centre a click must land on, and the point `elementFromPoint` is asked about (`QueryOptions`).
  */
-export const snapshotExpression = (selector: string): string => `(() => {
+export const snapshotExpression = (
+  selector: string,
+  options: QueryOptions = {},
+): string => `(() => {
   const out = [];
-  for (const el of document.querySelectorAll(${JSON.stringify(selector)})) {
+  const matches = document.querySelectorAll(${JSON.stringify(selector)});
+  ${options.reveal === true ? "matches[0]?.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });" : ''}
+  for (const el of matches) {
     const style = getComputedStyle(el);
     const rect = el.getBoundingClientRect();
     const attrs = {};

package/src/cdp-target.ts

@@ -19,7 +19,7 @@ import { type ColorScheme, colorSchemeFeatures } from './color-scheme';
 import { browserUnreachable, pageCrashed } from './error-throws';
 import { parseKeyChord } from './key-chord';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
-import { createRing } from './rings';
+import { boundedRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 import type {
   AxNode,
@@ -94,9 +94,9 @@ export interface CdpTargetInit extends CdpArmInit {
 }
 
 export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
-  const console_ = createRing<ConsoleLine>();
-  const network = createRing<NetworkEntry>();
-  const pageErrors = createRing<PageError>();
+  const console_ = boundedRing<ConsoleLine>();
+  const network = boundedRing<NetworkEntry>();
+  const pageErrors = boundedRing<PageError>();
   const crashed: { value: string | undefined } = { value: undefined };
   await arm(init, { network, console: console_, pageErrors, crashed });
   await armBrowser(init, network);
@@ -125,8 +125,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     if (pending === undefined) return;
     if (originOf(init.page.url()) !== pending.origin || pending.origin === '') return;
     pendingStorage = undefined;
+    // PAIRS, never an object literal: `{"__proto__": "…"}` in the page sets the literal's
+    // prototype and files no key, so a token stored under that legal name was never restored.
     await init.page.evaluate(
-      `(() => { const entries = ${JSON.stringify(pending.storage)}; for (const key of Object.keys(entries)) localStorage.setItem(key, entries[key]); })()`,
+      `(() => { for (const [key, value] of ${JSON.stringify(Object.entries(pending.storage))}) localStorage.setItem(key, value); })()`,
     );
   };
 
@@ -149,9 +151,9 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     ...parent,
     url: () => frame.url(),
     content: () => guard('content', () => frame.content()),
-    query: (selector) =>
+    query: (selector, options) =>
       guard('query', async () =>
-        parseSnapshots(await frame.evaluate(snapshotExpression(selector))),
+        parseSnapshots(await frame.evaluate(snapshotExpression(selector, options))),
       ),
     click: (selector) => guard('click', () => frame.click(selector)),
     type: (selector, text) => guard('type', () => frame.type(selector, text)),
@@ -206,9 +208,9 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         await applyPendingStorage();
       }),
     content: () => guard('content', () => init.page.content()),
-    query: (selector) =>
+    query: (selector, options) =>
       guard('query', async () =>
-        parseSnapshots(await init.page.evaluate(snapshotExpression(selector))),
+        parseSnapshots(await init.page.evaluate(snapshotExpression(selector, options))),
       ),
     click: (selector) => guard('click', () => init.page.click(selector)),
     type: (selector, text) => guard('type', () => init.page.type(selector, text)),
@@ -347,7 +349,7 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         }
         return parse(cookieSchema, await source.cookies());
       }),
-    // Honest stub, in the shape `packages/jobs/src/driver-redis.ts` uses. A real one needs
+    // Honest stub: correct types and one labelled `X_NOT_IMPLEMENTED`. 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.
     //

package/src/clock.ts

@@ -28,7 +28,7 @@ export const systemScrapeClock: ScrapeClock = Object.freeze({
       await Bun.sleep(ms);
       return;
     }
-    throwIfAborted(signal);
+    signal.throwIfAborted();
     // A timer raced against the signal, never `Bun.sleep(ms).then(check)`: the watchdog aborts a
     // wedged run precisely so nothing waits out the rest of a five-minute budget, and a sleep
     // that only notices the abort when it expires would wait out every one of them.
@@ -52,7 +52,7 @@ export const systemScrapeClock: ScrapeClock = Object.freeze({
  * The system clock with the waiting taken out: `now()` and `monotonic()` are real, and every
  * `sleep` is ONE turn of the event loop whatever was asked for. For a test whose run waits on
  * something that really happens in the same process — an answer the test publishes, a job another
- * worker holds — where `testClock()`'s "sleeping is advancing" would run a five-minute budget out
+ * worker holds — where `testScrapeClock()`'s "sleeping is advancing" would run a five-minute budget out
  * in microtasks before the test's next line. A deadline is still a real one.
  */
 export const noWaitClock: ScrapeClock = Object.freeze({
@@ -82,11 +82,6 @@ export function resetScrapeClock(): void {
   ambient = undefined;
 }
 
-/** The abort reason, unwrapped — a caller's `AbortSignal.reason` is whatever they put there. */
-export function throwIfAborted(signal: AbortSignal): void {
-  if (signal.aborted) throw signal.reason;
-}
-
 /**
  * A clock in which sleeping IS advancing: `await clock.sleep(30_000)` returns on the next
  * microtask with thirty seconds elapsed. This is what makes a poll-until-deadline test instant
@@ -97,7 +92,7 @@ export interface TestScrapeClock extends ScrapeClock {
   advance(ms: number): void;
 }
 
-export function testClock(at: Date | number = 0): TestScrapeClock {
+export function testScrapeClock(at: Date | number = 0): TestScrapeClock {
   let epochMs = at instanceof Date ? at.getTime() : at;
   let mono = 0;
   const advance = (ms: number): void => {
@@ -113,7 +108,7 @@ export function testClock(at: Date | number = 0): TestScrapeClock {
       // Yield the microtask queue anyway: a loop that never awaits anything real starves whatever
       // the test armed to cancel it, and the wedge tests arm exactly that.
       await Promise.resolve();
-      if (signal !== undefined) throwIfAborted(signal);
+      signal?.throwIfAborted();
     },
   };
 }

package/src/error-throws-session.ts

@@ -51,7 +51,7 @@ export const promptTimedOut = (input: {
   new ScrapeError({
     code: 'X_SCRAPE_PROMPT_UNANSWERED',
     cause: `scrape "${input.scrape}" asked for "${input.label}" and no answer was published to ${input.event} within ${String(input.waitedMs)}ms`,
-    fix: 'call answerPrompt({ runId, index, answer }) with the run id and index the event name in the cause ends with, from a process on the same STORED event bus — setEventBus(createPgEventBus({ executor })) — or raise eventPrompt({ timeout })',
+    fix: 'call answerPrompt({ runId, index, answer }) with the run id and index the event name in the cause ends with, from a process on the same STORED event bus — setEventBus(postgresEventBus({ executor })) — or raise eventPrompt({ timeout })',
     meta: {
       scrape: input.scrape,
       label: input.label,

package/src/error-throws.ts

@@ -401,7 +401,7 @@ export const authFailed = (scrape: string, detail: string): ScrapeError =>
     meta: { scrape },
   });
 
-export const sessionExpired = (scrape: string, key: string): ScrapeError =>
+export const scrapeSessionExpired = (scrape: string, key: string): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_SESSION_EXPIRED',
     cause: `the stored session ${key} for scrape "${scrape}" failed its validate() probe and the definition declares no auth.login`,

package/src/event-prompt.ts

@@ -15,7 +15,7 @@ import { finiteCount, isLocal, isSealed, openText, seal } from '@ultimat3/core';
 import type { EventBus, JobEvent } from '@ultimat3/jobs';
 import { DriverUnavailableError, eventBus } from '@ultimat3/jobs';
 import type { PromptHandler, PromptRequest } from './auth';
-import { deadline, throwIfAborted } from './clock';
+import { deadline } from './clock';
 import { promptAnswerInvalid, promptTimedOut } from './error-throws-session';
 
 /** How often the bus is asked. One indexed read and one browser round trip per interval. */
@@ -73,7 +73,7 @@ export function eventPrompt(options: EventPromptOptions): PromptHandler {
         driver: 'event bus',
         cause:
           'eventPrompt() was asked on the in-memory event bus — the answer is published by another process and can never reach this one',
-        fix: 'call setEventBus(createPgEventBus({ executor })) at boot — x dev and the served roles do — or pass bus: createPgEventBus({ executor }) to eventPrompt()',
+        fix: 'call setEventBus(postgresEventBus({ executor })) at boot — x dev and the served roles do — or pass bus: postgresEventBus({ executor }) to eventPrompt()',
       });
     }
     const event = promptEventName(request.runId, request.index);
@@ -83,7 +83,7 @@ export function eventPrompt(options: EventPromptOptions): PromptHandler {
     const askedAt = await bus.now();
     const budget = deadline(request.clock, timeoutMs, 'eventPrompt');
     for (;;) {
-      if (request.signal !== undefined) throwIfAborted(request.signal);
+      request.signal?.throwIfAborted();
       const found = await bus.find(event, undefined, askedAt);
       if (found !== undefined) {
         if (!isSealed(found.payload)) {

package/src/html-target.ts

@@ -18,7 +18,7 @@ import { parseKeyChord } from './key-chord';
 import type { PageRecording } from './recording';
 import { splitDownload } from './recording';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
-import { createRing } from './rings';
+import { boundedRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 import { EMPTY_SESSION } from './session-state';
 import type {
@@ -119,14 +119,14 @@ interface OfflineDocument {
 }
 
 export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
-  const consoleRing = createRing<ConsoleLine>();
-  const networkRing = createRing<NetworkEntry>();
+  const consoleRing = boundedRing<ConsoleLine>();
+  const networkRing = boundedRing<NetworkEntry>();
   // Built and never pushed to, deliberately: this target parses markup and executes none of it, so
   // there is no uncaught exception for it to have. It ANSWERS rather than omitting the ring —
   // `page.pageErrors()` returning `[]` here is the honest "nothing threw, and nothing could",
   // where a missing ring would be a page method that throws on two of the three drivers.
   // `driver-parity.test.ts` pins the divergence, beside the box/hit-target one it already carries.
-  const pageErrorRing = createRing<PageError>();
+  const pageErrorRing = boundedRing<PageError>();
   const overlay = new Map<string, string>();
   /**
    * One overlay per FRAME, held here rather than in the frame target, because `frames()` builds a

package/src/index.ts

@@ -5,10 +5,7 @@
 export type { ActionabilityState, ActionabilityWait } from './actionability';
 export { awaitActionable } from './actionability';
 export type { ArtifactRef, ArtifactWriter, ArtifactWriterInit } from './artifacts';
-export {
-  createArtifactWriter,
-  DEFAULT_CONTENT_TYPE,
-} from './artifacts';
+export { artifactWriter } from './artifacts';
 export type {
   AuthContext,
   PromptHandler,
@@ -16,7 +13,7 @@ export type {
   PromptRequest,
   ScrapeAuth,
 } from './auth';
-export { burnSession, createPrompt, ensureAuthenticated, restorableSession } from './auth';
+export { burnSession, ensureAuthenticated, restorableSession, scrapePrompt } from './auth';
 export { browserRecord } from './browser-record';
 export type { CaptureClip, CaptureFraming } from './capture-clip';
 export { assertCaptureFraming } from './capture-clip';
@@ -44,8 +41,7 @@ export {
   scrapeClock,
   setScrapeClock,
   systemScrapeClock,
-  testClock,
-  throwIfAborted,
+  testScrapeClock,
 } from './clock';
 export type { ColorScheme } from './color-scheme';
 export { COLOR_SCHEMES, isColorScheme } from './color-scheme';
@@ -81,10 +77,10 @@ export {
   redirectLoop,
   remoteRequired,
   robotsDisallowed,
+  scrapeSessionExpired,
   scrapeTimeout,
   secretExposed,
   selectorMissing,
-  sessionExpired,
   wedged,
   yieldCollapsed,
 } from './error-throws';
@@ -122,8 +118,6 @@ export {
   memoryYieldHistory,
 } from './expect';
 export { BURNS_SESSION, errorCode, NEVER_RETRIED } from './failures';
-export type { HostDecision, HostRule } from './hosts';
-export { ANY_HOST, hostDecision, hostMatches } from './hosts';
 export { queryHtml } from './html-query';
 export type { MarkupRequest } from './html-requests';
 export type { HtmlTargetInit, RecordingLookup } from './html-target';
@@ -152,7 +146,7 @@ export type {
 export type { PageContext } from './page-over-target';
 export { pageOverTarget } from './page-over-target';
 export type { Pacer } from './rate';
-export { createPacer } from './rate';
+export { scrapePacer } from './rate';
 export type { HttpRecording, PageRecording } from './recording';
 export {
   httpRecordingSchema,
@@ -173,13 +167,21 @@ export type {
   Ring,
 } from './rings';
 export {
-  createRing,
+  boundedRing,
   MAX_PAGE_ERROR_CHARS,
   pageErrorEntry,
   RESOURCE_TYPES,
 } from './rings';
-export type { RobotsFetch, RobotsGate, RobotsGateInit, RobotsPolicy, RobotsRules } from './robots';
-export { createRobotsGate, parseRobots, robotsAllows } from './robots';
+export type {
+  RobotsAnswer,
+  RobotsFetch,
+  RobotsGate,
+  RobotsGateInit,
+  RobotsPolicy,
+  RobotsRules,
+  RobotsUnreachable,
+} from './robots';
+export { parseRobots, robotsAllows, robotsGate } from './robots';
 export type { RobotsFetchInit } from './robots-fetch';
 export {
   DEFAULT_ROBOTS_MAX_BYTES,
@@ -197,13 +199,13 @@ export { scrape } from './scrape';
 export { DEFAULT_PAGE_TIMEOUT_MS, runScrape } from './scrape-run';
 export type { ScrapeSecrets, SecretResolver } from './secrets';
 export {
-  createSecretBag,
   MIN_REDACTABLE_LENGTH,
   redactSecrets,
   safeConsole,
   safeHtml,
   safeNetwork,
   safePageErrors,
+  secretBag,
 } from './secrets';
 export type {
   ScrapeSessionStore,
@@ -227,12 +229,13 @@ export type {
   ElementSnapshot,
   FrameRef,
   GotoOptions,
+  QueryOptions,
   ScrapeCookie,
   ScrapeDownloadFile,
   ScrapeTarget,
 } from './target';
 export { endpointLabel, urlSecretValues } from './url-secrets';
 export type { RunUsageMeter, ScrapeUsage, UsageMeter } from './usage';
-export { createUsageMeter } from './usage';
+export { usageMeter } from './usage';
 export type { WedgeGuard, WedgeGuardInit } from './watchdog';
 export { DEFAULT_GRACE_MS } from './watchdog';

package/src/intercept.ts

@@ -5,8 +5,8 @@
 // differently — `driver-parity.test.ts` asserts the same refusal on all three, and a rule
 // re-implemented per driver is a rule that holds only on the driver nobody ships.
 
-import type { HostRule } from './hosts';
-import { hostDecision } from './hosts';
+import type { HostRule } from '@ultimat3/core';
+import { hostDecision } from '@ultimat3/core';
 import type { NetworkEntry, ResourceType } from './rings';
 
 export interface InterceptRules {

package/src/page-over-target.ts

@@ -4,7 +4,7 @@
 // driver a test uses and the driver production uses.
 
 import type { Secret } from '@ultimat3/core';
-import { finiteCount, isSecret, revealSecret } from '@ultimat3/core';
+import { finiteCount, hostDecision, isSecret, revealSecret } from '@ultimat3/core';
 import type { ActionabilityState } from './actionability';
 import { awaitActionable } from './actionability';
 import { assertCaptureFraming } from './capture-clip';
@@ -12,7 +12,6 @@ import type { ScrapeClock } from './clock';
 import { deadline } from './clock';
 import type { ColorScheme } from './color-scheme';
 import { hostBlocked, secretExposed, selectorMissing } from './error-throws';
-import { hostDecision } from './hosts';
 import type {
   AccessibilityOptions,
   CaptureRequest,
@@ -30,6 +29,7 @@ import type {
   AxNode,
   CaptureOptions,
   ElementSnapshot,
+  QueryOptions,
   ScrapeCookie,
   ScrapeDownloadFile,
   ScrapeTarget,
@@ -80,9 +80,13 @@ const toValue = (snapshot: ElementSnapshot): ElementValue => ({
   attrs: snapshot.attrs,
 });
 
-async function first(resolve: Resolve, selector: string): Promise<ElementSnapshot | undefined> {
+async function first(
+  resolve: Resolve,
+  selector: string,
+  options?: QueryOptions,
+): Promise<ElementSnapshot | undefined> {
   const target = await resolve();
-  return (await target.query(selector))[0];
+  return (await target.query(selector, options))[0];
 }
 
 function frameOver(
@@ -103,14 +107,18 @@ function frameOver(
   ): Promise<ElementSnapshot> => {
     const target = await resolve();
     lastUrl = target.url();
+    const state = options?.state ?? fallback;
+    // Only `actionable` reads `hitTarget`, so only it pays for moving the page — on every poll,
+    // because a layout shift between two can carry the element back out of view.
+    const query: QueryOptions = { reveal: state === 'actionable' };
     return awaitActionable({
       selector,
       url: lastUrl,
-      state: options?.state ?? fallback,
+      state,
       timeoutMs: timeoutFor(options),
       clock: ctx.clock,
       signal: ctx.signal,
-      snapshot: () => first(resolve, selector),
+      snapshot: () => first(resolve, selector, query),
     });
   };
 

package/src/rate.ts

@@ -9,7 +9,7 @@ export const DEFAULT_NAVIGATION_RATE = 1;
 
 export type Pacer = (signal?: AbortSignal) => Promise<void>;
 
-export function createPacer(rate: number, clock: ScrapeClock): Pacer {
+export function scrapePacer(rate: number, clock: ScrapeClock): Pacer {
   const intervalMs = 1_000 / rate;
   let nextAt = 0;
   return async (signal?: AbortSignal): Promise<void> => {

package/src/recover.ts

@@ -3,7 +3,7 @@
 // Two shapes. A FUNCTION is complete and shipped — an app writes its own fallback, gets the page
 // and the failure, and answers whether the attempt should be retried. `'agent'` is the seam for
 // letting a model re-derive the selector from the page, and it is an honest
-// `X_NOT_IMPLEMENTED` today, in the shape `packages/jobs/src/driver-redis.ts` uses: correct types
+// `X_NOT_IMPLEMENTED` today: correct types
 // so an app can be written against it, one labelled throw, no silent no-op.
 
 import { NotImplementedError } from '@ultimat3/core';

package/src/rings.ts

@@ -107,18 +107,18 @@ export type PageErrorRing = Ring<PageError>;
  *
  * Both wrong values fail in opposite directions and neither is survivable. A NEGATIVE capacity
  * makes `while (items.length > capacity) items.shift()` spin forever on an already-empty array
- * (`0 > -1`): `createRing(-1).push(1)` never returns, and it is a synchronous loop on the worker's
+ * (`0 > -1`): `boundedRing(-1).push(1)` never returns, and it is a synchronous loop on the worker's
  * only thread, inside a `page.on('request')` handler — past `ctx.signal`, past the wedge watchdog
  * and past the job timeout, which is incident #1 in this file's header. `NaN` fails the other way:
  * the comparison is false forever, the ring is UNBOUNDED, and the OOM the bound exists to prevent
  * arrives two hours in. Zero is a ring that discards everything silently, and a fraction is a
  * bound that is not the number anybody asked for.
  */
-export function createRing<T>(capacity: number = DEFAULT_RING_CAPACITY): Ring<T> {
+export function boundedRing<T>(capacity: number = DEFAULT_RING_CAPACITY): Ring<T> {
   assert(
     Number.isSafeInteger(capacity) && capacity > 0,
     `a ring capacity must be a positive integer, got ${String(capacity)}: a negative one spins forever on push() and NaN makes the ring unbounded`,
-    `pass a positive capacity — createRing(${String(DEFAULT_RING_CAPACITY)}) — or omit it and take DEFAULT_RING_CAPACITY`,
+    `pass a positive capacity — boundedRing(${String(DEFAULT_RING_CAPACITY)}) — or omit it and take DEFAULT_RING_CAPACITY`,
   );
   const items: T[] = [];
   let dropped = 0;