effect-browser 0.2.0-beta.9 → 0.3.0-beta.5

package/src/internal/page/bridge.ts

@@ -0,0 +1,386 @@
+/**
+ * The bridge to the page script, and the page's documents as its own session sees them commit and
+ * load, so a load follows its commit. At the library's first read of a page, its own protocol
+ * session registers the script, so every later document runs it in an isolated world from its
+ * start; calls go to the current document's world. The script is composed from the domains'
+ * page-side parts, the `*.inpage.ts` modules, in the order they depend on one another. At the first
+ * read of a page's changes, its session registers the recorder too, so every later document
+ * records from its start.
+ */
+import { Effect, Schema, SynchronizedRef } from "effect";
+
+import { type BrowserError, Failed } from "../../BrowserError.ts";
+import { Navigated, PageLoaded } from "../../BrowserEvent.ts";
+import { edit, type Edit } from "../input/edit.inpage.ts";
+import { evidence } from "../input/evidence.inpage.ts";
+import { guard, type Guard } from "../input/guard.inpage.ts";
+import { targets, type Targets } from "../input/targets.inpage.ts";
+import { context } from "../reading/context.inpage.ts";
+import { controls, type Controls } from "../reading/controls.inpage.ts";
+import { expectations, type Expectations } from "../reading/expect.inpage.ts";
+import { match } from "../reading/match.inpage.ts";
+import { names } from "../reading/names.inpage.ts";
+import { outline, type Outline } from "../reading/outline.inpage.ts";
+import { ready } from "../reading/ready.inpage.ts";
+import { subjects, type Subjects } from "../reading/subjects.inpage.ts";
+import { text, type Texts } from "../reading/text.inpage.ts";
+import { walk } from "../reading/walk.inpage.ts";
+import { changes, type Changes } from "../timeline/changes.inpage.ts";
+import { fold } from "../timeline/fold.inpage.ts";
+import { history } from "../timeline/history.inpage.ts";
+import { marks } from "../timeline/marks.inpage.ts";
+import { record, type Recorder } from "../timeline/record.inpage.ts";
+import { sight } from "../timeline/sight.inpage.ts";
+import { contextGone, failWith, type PageContext, undispatched } from "./context.ts";
+import * as Url from "./url.ts";
+
+/** What the script installs: a version, and a function of one of its parts for each call. */
+export interface PageApi {
+  readonly version: number;
+  snapshot: Outline["snapshot"];
+  find: Subjects["find"];
+  until: Expectations["until"];
+  waitUntil: Controls["waitUntil"];
+  text: Texts["read"];
+  record: Recorder["start"];
+  changes: Changes["read"];
+  ready: ReturnType<typeof ready>["wait"];
+  settle: ReturnType<typeof ready>["settle"];
+  point: Targets["point"];
+  scrollPlan: Targets["scrollPlan"];
+  viewport: Outline["viewport"];
+  /** The screen as the page reads it, which another session may emulate. */
+  screenSize: () => { readonly width: number; readonly height: number };
+  prepareInput: Guard["prepareInput"];
+  validateInput: Guard["validateInput"];
+  typeable: Edit["typeable"];
+  focus: Edit["focus"];
+  focusOn: Edit["focusOn"];
+  select: Edit["select"];
+}
+
+declare global {
+  // The API this script installs, which exists only inside the library's isolated world.
+  var __effectBrowser: PageApi | undefined;
+}
+
+// Like the parts it receives, this is evaluated from its source text.
+const install = (
+  makeNames: typeof names,
+  makeWalk: typeof walk,
+  makeMatch: typeof match,
+  makeContext: typeof context,
+  makeSubjects: typeof subjects,
+  makeExpectations: typeof expectations,
+  makeText: typeof text,
+  makeControls: typeof controls,
+  makeFold: typeof fold,
+  makeHistory: typeof history,
+  makeSight: typeof sight,
+  makeMarks: typeof marks,
+  makeRecord: typeof record,
+  makeChanges: typeof changes,
+  makeReady: typeof ready,
+  makeOutline: typeof outline,
+  makeTargets: typeof targets,
+  makeEvidence: typeof evidence,
+  makeGuard: typeof guard,
+  makeEdit: typeof edit,
+  makeAddresses: typeof Url.addresses,
+): PageApi => {
+  const installed = globalThis.__effectBrowser;
+
+  if (installed !== undefined && installed.version === 18) return installed;
+  const named = makeNames();
+  const walked = makeWalk(named);
+  const placing = makeContext(named, walked);
+  const subjected = makeSubjects(named, walked, makeMatch(), placing);
+  const texts = makeText(named, walked);
+  const controlled = makeControls(named, walked, subjected, texts);
+  const kept = makeHistory(makeFold());
+  const seeing = makeSight(named, walked, texts, kept);
+  const marking = makeMarks(named, kept, seeing);
+  const recorder = makeRecord(named, texts, kept, seeing, marking);
+  const read = makeOutline(named, walked, subjected, texts, controlled, makeAddresses());
+  const located = makeTargets(named, walked, placing);
+  const guarded = makeGuard(named, located, makeEvidence(named, placing));
+  const edited = makeEdit(named, guarded, placing);
+  const readiness = makeReady(walked, texts, kept);
+
+  const api: PageApi = {
+    version: 18,
+    snapshot: read.snapshot,
+    find: subjected.find,
+    until: makeExpectations(named, subjected).until,
+    waitUntil: controlled.waitUntil,
+    text: texts.read,
+    record: recorder.start,
+    changes: makeChanges(named, placing, kept, seeing, marking, recorder).read,
+    ready: readiness.wait,
+    settle: readiness.settle,
+    point: located.point,
+    scrollPlan: located.scrollPlan,
+    viewport: read.viewport,
+    screenSize: () => ({ width: screen.width, height: screen.height }),
+    prepareInput: guarded.prepareInput,
+    validateInput: guarded.validateInput,
+    typeable: edited.typeable,
+    focus: edited.focus,
+    focusOn: edited.focusOn,
+    select: edited.select,
+  };
+
+  globalThis.__effectBrowser = api;
+
+  return api;
+};
+
+/** The expression that installs the script and evaluates to its API. */
+export const installSource = `(${install.toString()})(${[names, walk, match, context, subjects, expectations, text, controls, fold, history, sight, marks, record, changes, ready, outline, targets, evidence, guard, edit, Url.addresses].join(", ")})`;
+
+const worldName = "effect-browser";
+
+// What starts the recorder in each new document, after the script installed itself there.
+const recorderSource = `if (globalThis === globalThis.top) globalThis.__effectBrowser?.record();`;
+
+// What a call reads in a world without the script's API. A context id can name another world once
+// the page has moved to a new process, so a cached id that reads this is not the library's world.
+const missing = "effect-browser: no __effectBrowser in this world";
+
+const isMissing = (error: BrowserError) =>
+  error.reason._tag === "Failed" && error.reason.detail === missing;
+
+/** A frame as a page session reports its commit. */
+export const Commit = Schema.Struct({
+  parentId: Schema.optionalKey(Schema.String),
+  loaderId: Schema.String,
+  url: Schema.String,
+  urlFragment: Schema.optionalKey(Schema.String),
+});
+
+/** `Page.frameNavigated` or `Page.navigatedWithinDocument`, as far as `mainFrame` reads them. */
+export const MainFrameEvent = Schema.Union([
+  Schema.Struct({ frame: Commit }),
+  Schema.Struct({ frameId: Schema.String, url: Schema.String }),
+]);
+
+/** A commit's loader and its address, redacted. */
+export const commitOf = ({ loaderId, url, urlFragment = "" }: typeof Commit.Type) => ({
+  loader: loaderId,
+  url: Url.redact(url + urlFragment),
+});
+
+/**
+ * What a page session's commit or move says of `page`'s main frame: a new document's `loader` and
+ * its address, or a move's address; nothing for another frame. Only a commit is a new document:
+ * `frameStartedLoading` also fires on `pushState`, a move within the document.
+ */
+export const mainFrame = (page: string, event: typeof MainFrameEvent.Type) =>
+  "frame" in event
+    ? event.frame.parentId === undefined
+      ? commitOf(event.frame)
+      : undefined
+    : event.frameId === page
+      ? { loader: undefined, url: Url.redact(event.url) }
+      : undefined;
+
+/** A call to the page script, its arguments quoted as JavaScript literals. */
+export const scriptCall = (name: string, ...args: ReadonlyArray<unknown>): string =>
+  `${name}(${args.map((arg) => JSON.stringify(arg)).join(", ")})`;
+
+export const make = Effect.fnUntraced(function* (page: PageContext) {
+  const { id, cdp, native, span, publish, now } = page;
+  const { send } = page.protocol;
+  // How far this session has registered: the script, then the recorder, which the first read of
+  // changes asks for. One caller takes each step, once, while the others wait.
+  const registration = yield* SynchronizedRef.make<"none" | "script" | "recorder">("none");
+  // The current document's world, forgotten when the main frame commits another document; the
+  // commits this session has seen, the latest marked on the page; the page's address; and how far
+  // the current document has loaded.
+  let world: number | undefined;
+  let documents = 0;
+  let url = Url.redact(page.url);
+  let loaded: PageLoaded | undefined;
+  // The latest commits' loaders and the documents they began, newest last: a capture connection
+  // sees the same commits, and numbers its frames by them.
+  const loaders = new Map<string, number>();
+
+  const onMainFrame = (event: typeof MainFrameEvent.Type) => {
+    const seen = mainFrame(id, event);
+
+    if (seen === undefined) return;
+    if (seen.loader !== undefined) {
+      documents++;
+      loaders.delete(seen.loader);
+      loaders.set(seen.loader, documents);
+      const [oldest] = loaders.keys();
+
+      if (loaders.size > 8 && oldest !== undefined) loaders.delete(oldest);
+      page.activity.documentAt = now();
+      world = undefined;
+      loaded = undefined;
+    }
+    url = seen.url;
+    const sameDocument = seen.loader === undefined;
+
+    publish(new Navigated({ at: now(), page: id, url, document: documents, sameDocument }));
+  };
+
+  // The session tells these of the main frame alone.
+  const onLoaded = (state: PageLoaded["state"]) => () => {
+    loaded = new PageLoaded({ at: now(), page: id, state });
+    publish(loaded);
+  };
+
+  cdp.on("Page.frameNavigated", onMainFrame);
+  cdp.on("Page.navigatedWithinDocument", onMainFrame);
+  cdp.on("Page.domContentEventFired", onLoaded("domcontentloaded"));
+  cdp.on("Page.loadEventFired", onLoaded("load"));
+
+  /**
+   * The main-frame commits seen so far, once the Page domain, which registration turned on, has
+   * answered, so that every later one counts. A commit within about one round trip of the count
+   * can still be missed.
+   */
+  const currentDocument = (operation: string) =>
+    page.paging(operation).pipe(Effect.map(() => documents));
+
+  /** What a frame that arrives now shows: its session, the page's current document and address. */
+  const frameTag = () => ({ session: page.session, document: documents, url });
+
+  /** The document the main frame's latest commit of `loader` began, if this session counted it. */
+  const documentOf = (loader: string) => loaders.get(loader);
+
+  // The registration belongs to this session and the world to the page, so a session that attaches
+  // later, as after a reconnect, registers again and finds the script already installed. With the
+  // Page domain enabled, a source runs in each new document, in the order registered;
+  // `runImmediately` runs it now.
+  const addScript = (operation: string, source: string) =>
+    native(operation, () =>
+      send("Page.addScriptToEvaluateOnNewDocument", { source, worldName, runImmediately: true }),
+    );
+
+  const register = (operation: string) =>
+    Effect.all(
+      [
+        page.paging(operation),
+        addScript(operation, `if (globalThis === globalThis.top) ${installSource};`),
+      ],
+      { concurrency: "unbounded" },
+    ).pipe(span("Page.register", {}, "Debug"));
+
+  /** Take registration from `from` to `to` by `step`, unless it is past `from` already. */
+  const advance = (
+    from: "none" | "script",
+    to: "script" | "recorder",
+    step: Effect.Effect<unknown, BrowserError>,
+  ) =>
+    SynchronizedRef.updateEffect(registration, (state) =>
+      state === from ? Effect.as(step, to) : Effect.succeed(state),
+    );
+
+  /** Register the script once, and the recorder after it once a read of changes asks for it. */
+  const ensure = (operation: string, recorder: boolean) =>
+    Effect.andThen(
+      advance("none", "script", register(operation)),
+      recorder ? advance("script", "recorder", addScript(operation, recorderSource)) : Effect.void,
+    );
+
+  const createWorld = (operation: string) =>
+    Effect.gen(function* () {
+      yield* ensure(operation, false);
+      const document = documents;
+
+      // The main frame's id is the page's target id.
+      const created = yield* native(operation, () =>
+        send("Page.createIsolatedWorld", { frameId: id, worldName }),
+      );
+
+      // A world the page replaced while it was being looked up serves this call, not later ones.
+      if (document === documents) world = created.executionContextId;
+
+      return created.executionContextId;
+    }).pipe(span("Page.createWorld", {}, "Debug"));
+
+  /** The current document's world, created if it has none yet. */
+  const current = (operation: string) =>
+    Effect.suspend(() => (world === undefined ? createWorld(operation) : Effect.succeed(world)));
+
+  /** A world of the current document without the page script, as the clock probe needs. */
+  const bareWorld = (operation: string) =>
+    native(operation, () =>
+      send("Page.createIsolatedWorld", { frameId: id, worldName: `${worldName}-clock` }),
+    ).pipe(Effect.map((created) => created.executionContextId));
+
+  const run = (operation: string, expression: string, contextId: number) =>
+    native(operation, () =>
+      send("Runtime.evaluate", { contextId, expression, returnByValue: true, awaitPromise: true }),
+    ).pipe(
+      Effect.flatMap(({ result, exceptionDetails: thrown }) =>
+        thrown === undefined
+          ? Effect.succeed<unknown>(result.value)
+          : failWith(
+              operation,
+              new Failed({ detail: thrown.exception?.description ?? thrown.text }),
+            ),
+      ),
+    );
+
+  const evaluateIn = (operation: string, call: string, contextId: number) =>
+    run(
+      operation,
+      `globalThis.__effectBrowser === undefined ? ${JSON.stringify(missing)} : globalThis.__effectBrowser.${call}`,
+      contextId,
+    ).pipe(
+      Effect.filterOrFail(
+        (value) => value !== missing,
+        () => undispatched(operation, new Failed({ detail: missing })),
+      ),
+      // One round trip to the page. Its arguments can hold typed text, so only the call is named.
+      span("Page.evaluate", { function: call.split("(")[0] }, "Trace"),
+    );
+
+  // Ordinary reads can recreate a document's world. Approval validation deliberately cannot. A
+  // world found by its name that lacks the script, in a document the registration missed, gets it.
+  const evaluateWithContext = (operation: string, call: string) => {
+    const attempt = (contextId: number) =>
+      evaluateIn(operation, call, contextId).pipe(Effect.map((value) => ({ contextId, value })));
+
+    const again = createWorld(operation).pipe(
+      Effect.flatMap((contextId) =>
+        attempt(contextId).pipe(
+          Effect.catchIf(isMissing, () =>
+            run(operation, `${installSource}.version`, contextId).pipe(
+              Effect.andThen(attempt(contextId)),
+            ),
+          ),
+        ),
+      ),
+    );
+
+    return current(operation).pipe(
+      Effect.flatMap(attempt),
+      Effect.catchIf(contextGone, () => again),
+    );
+  };
+
+  const evaluate = (operation: string, call: string) =>
+    evaluateWithContext(operation, call).pipe(Effect.map(({ value }) => value));
+
+  return {
+    current,
+    bareWorld,
+    evaluate,
+    evaluateIn,
+    evaluateWithContext,
+    currentDocument,
+    frameTag,
+    documentOf,
+    /** How far the current document has loaded, as this session heard; nothing until parsed. */
+    loaded: () => loaded,
+    /** Register the recorder, so every later document records from its start. */
+    registerRecorder: (operation: string) => ensure(operation, true),
+  };
+});
+
+export type Bridge = Effect.Success<ReturnType<typeof make>>;

package/src/internal/page/context.ts

@@ -0,0 +1,302 @@
+/**
+ * What a page's parts share: the browser state they act on, the page's own lane, pointer and
+ * clock, and how they call the browser and report its failures. The assembly in `page.ts` builds
+ * one context per page.
+ */
+import {
+  Clock,
+  Context,
+  Duration,
+  Effect,
+  Fiber,
+  MutableRef,
+  Option,
+  Schema,
+  type Scope,
+} from "effect";
+import type { CDPSession, Page as PlaywrightPage } from "playwright-core";
+
+import type { CaptureSource } from "../../Browser.ts";
+import { BrowserError, Closed, Failed, type Reason, Timeout } from "../../BrowserError.ts";
+import type { BrowserEvent } from "../../BrowserEvent.ts";
+import type { InputGuard, Point } from "../../Page.ts";
+import type * as BrowserClock from "../pictures/clock.ts";
+import * as Lane from "./lane.ts";
+import type { Openings } from "./openings.ts";
+import * as Url from "./url.ts";
+
+/** Why a page is gone. */
+export type ClosedCause = Closed["cause"];
+
+/** What every page of a browser shares, from its options. */
+export interface Settings {
+  readonly actionTimeout: Duration.Duration;
+  readonly policyTimeout: Duration.Duration;
+  readonly navigationTimeout: Duration.Duration;
+  /** How long screencast frames stay in `recentFrames`, measured back from the newest. */
+  readonly frameHistory: Duration.Duration;
+  readonly guard: InputGuard | undefined;
+}
+
+export interface MakeOptions {
+  /** The page's CDP target id, which is also its main frame's id. */
+  readonly id: string;
+  /** The id of the browser's session, which its frames carry. */
+  readonly session: string;
+  /** The page's address when the browser began tracking it. */
+  readonly url: string;
+  readonly playwright: PlaywrightPage;
+  readonly cdp: CDPSession;
+  /** A call's reply, or a failure as for a closed page once the browser is lost first. */
+  readonly untilLost: <A>(reply: Promise<A>) => Promise<A>;
+  readonly settings: Settings;
+  readonly clock: Clock.Clock;
+  /** The browser's epoch mapping: its first capture measures it, and later ones renew it. */
+  readonly mapping: BrowserClock.Mapping;
+  readonly publish: (event: BrowserEvent) => number;
+  /** This page's retained events, oldest first. */
+  readonly recentEvents: Effect.Effect<ReadonlyArray<BrowserEvent>>;
+  /** Registration of the actual popups this page's current input opened. */
+  readonly openings: Openings;
+  /** Succeeds once the page's own session holds focus emulation, which keeps it painting behind. */
+  readonly focused: Effect.Effect<void, BrowserError>;
+  /** Succeeds once the page's own session has the Page domain on, so it sees every later commit. */
+  readonly paging: (operation: string) => Effect.Effect<void, BrowserError>;
+  /** Why the page is gone, once it is: its browser's loss, else its own close or crash. */
+  readonly closedBy: () => ClosedCause;
+  /** Where the page's screencast runs, if not on its own session. */
+  readonly capture?: CaptureSource | undefined;
+}
+
+const messageOf = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : typeof cause === "string" ? cause : "unknown error";
+
+const closedPattern =
+  /has been closed|Target closed|Session closed|browser has disconnected|Target page, context or browser/i;
+
+/**
+ * Map a Playwright or protocol failure to a reason, `Closed` with `closed` as its cause for a page
+ * or browser that is gone. A call that gives Playwright a timeout passes the same bound, so its
+ * `Timeout` reports it; without one, Playwright's own message stays.
+ */
+export const reasonOf = (
+  cause: unknown,
+  timeoutMillis?: number,
+  closed: ClosedCause = "connection",
+): Reason => {
+  const message = messageOf(cause);
+
+  if (closedPattern.test(message)) return new Closed({ cause: closed });
+  if (cause instanceof Error && cause.name === "TimeoutError" && timeoutMillis !== undefined)
+    return new Timeout({ millis: timeoutMillis });
+  const line = message.split("\n")[0] ?? message;
+
+  return new Failed({ detail: Url.redactWithin(line.replace(/^[\w.]+: /, "")) });
+};
+
+/**
+ * One Playwright or protocol call, failing undispatched. A closed page says why it is gone as the
+ * browser knows then: the library's own calls fail with the browser's loss, and Playwright fails
+ * its calls on a dropped connection after reporting the context closed.
+ */
+export const call = <A>(
+  operation: string,
+  run: () => Promise<A>,
+  closedBy: () => ClosedCause,
+  timeoutMillis?: number,
+) =>
+  Effect.tryPromise({
+    try: run,
+    catch: (cause) => undispatched(operation, reasonOf(cause, timeoutMillis, closedBy())),
+  });
+
+export const contextGone = (error: BrowserError) =>
+  error.reason._tag === "Failed" &&
+  /Cannot find context|Execution context was destroyed|__effectBrowser|Inspected target navigated/i.test(
+    error.reason.detail,
+  );
+
+/**
+ * What a page operation spent on the page's own protocol session: its calls, the bytes of their
+ * parameters and results, and how long at least one of them awaited its reply. An operation inside
+ * another counts toward both.
+ */
+interface Cost {
+  readonly enclosing: Cost | undefined;
+  calls: number;
+  bytesOut: number;
+  bytesIn: number;
+  waitedMillis: number;
+  awaiting: number;
+  awaitingSince: number;
+}
+
+/** The cost of the page operation the current fiber runs, if any. */
+const CurrentCost = Context.Reference<Cost | undefined>(
+  "effect-browser/internal/page/CurrentCost",
+  {
+    defaultValue: () => undefined,
+  },
+);
+
+// A message's size on the wire, give or take its envelope.
+const sizeOf = (value: unknown) =>
+  value === undefined ? 0 : Buffer.byteLength(JSON.stringify(value));
+
+/** A failure of `operation` before any of its input reached the browser. */
+export const undispatched = (operation: string, reason: Reason) =>
+  new BrowserError({ operation, reason, dispatched: false });
+
+export const failWith = (operation: string, reason: Reason) =>
+  Effect.fail(undispatched(operation, reason));
+
+export const decodeWith =
+  <A>(operation: string, schema: Schema.Codec<A, unknown>) =>
+  (value: unknown) =>
+    Schema.decodeUnknownEffect(schema)(value).pipe(
+      Effect.mapError((error) => undispatched(operation, new Failed({ detail: error.message }))),
+    );
+
+export const make = (options: MakeOptions, scope: Scope.Scope) => {
+  const { id, clock } = options;
+  const now = () => Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
+  // Deadlines and pacing guard the page's lane, so page operations run on the owner's clock; a
+  // caller's clock, such as a TestClock, cannot stall or stretch them.
+  const owned = Effect.provideService(Clock.Clock, clock);
+
+  // This page's spans name it and report what the operation cost on the protocol. Fine-grained
+  // ones carry a level below the default Info, so an application keeps only the coarse ones by
+  // raising `Tracer.MinimumTraceLevel`.
+  const span =
+    (name: string, attributes: Record<string, unknown> = {}, level?: "Debug" | "Trace") =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      Effect.gen(function* () {
+        const cost: Cost = {
+          enclosing: yield* CurrentCost,
+          calls: 0,
+          bytesOut: 0,
+          bytesIn: 0,
+          waitedMillis: 0,
+          awaiting: 0,
+          awaitingSince: 0,
+        };
+
+        return yield* effect.pipe(
+          Effect.provideService(CurrentCost, cost),
+          Effect.ensuring(
+            Effect.suspend(() =>
+              Effect.annotateCurrentSpan({
+                calls: cost.calls,
+                bytesOut: cost.bytesOut,
+                bytesIn: cost.bytesIn,
+                waitedMillis: Math.round(cost.waitedMillis * 10) / 10,
+              }),
+            ),
+          ),
+        );
+      }).pipe(
+        Effect.withSpan(
+          name,
+          { attributes: { page: id, ...attributes }, ...(level === undefined ? {} : { level }) },
+          { captureStackTrace: false },
+        ),
+      );
+
+  // Every call on the page's own protocol session, counted into the operation that sends it and
+  // the operations around that one. It is looked up when the call is sent, so input pipelined
+  // from inside an operation counts toward it too.
+  const send: CDPSession["send"] = (method, params) => {
+    const cost = Fiber.getCurrent()?.getRef(CurrentCost);
+    const sentAt = now();
+    const bytesOut = sizeOf(params);
+
+    for (let each = cost; each !== undefined; each = each.enclosing) {
+      each.calls++;
+      each.bytesOut += bytesOut;
+      if (each.awaiting++ === 0) each.awaitingSince = sentAt;
+    }
+    const reply = options.untilLost(options.cdp.send(method, params));
+
+    if (cost === undefined) return reply;
+
+    const settle = (bytesIn: number) => {
+      const at = now();
+
+      for (let each: Cost | undefined = cost; each !== undefined; each = each.enclosing) {
+        each.bytesIn += bytesIn;
+        if (--each.awaiting === 0) each.waitedMillis += at - each.awaitingSince;
+      }
+    };
+
+    return reply.then(
+      (result) => {
+        settle(sizeOf(result));
+
+        return result;
+      },
+      (cause: unknown) => {
+        settle(0);
+
+        return Promise.reject(cause);
+      },
+    );
+  };
+
+  // Every protocol or Playwright call. Errors are undispatched here; `perform` marks them
+  // dispatched once input has gone out.
+  const native = <A>(operation: string, run: () => Promise<A>, timeoutMillis?: number) =>
+    call(operation, run, options.closedBy, timeoutMillis);
+
+  /** Fail with `Timeout` once `duration` has passed, the action timeout unless another is given. */
+  const within =
+    (operation: string, duration: Duration.Input = options.settings.actionTimeout) =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      Effect.timeoutOrElse(effect, {
+        duration,
+        orElse: () => failWith(operation, new Timeout({ millis: Duration.toMillis(duration) })),
+      });
+
+  // The latest submitted input or page change. A read that must follow it waits for the action in
+  // flight, so only paint from after its latest input is current. An action ends after its input
+  // was handled, so if that input changed the page, newer paint follows; a lost final paint is
+  // bounded by recency instead. Paint from before the current document began, when the page's own
+  // session saw the main frame commit it, shows a page the tab has left, so no read reuses it,
+  // whatever it asks.
+  const activity = { inputAt: 0, documentAt: Number.NEGATIVE_INFINITY };
+
+  const noteInput = () => {
+    activity.inputAt = Math.max(activity.inputAt, now());
+  };
+
+  const lane = Lane.make({
+    now,
+    actionTimeout: options.settings.actionTimeout,
+    documentAt: () => activity.documentAt,
+    gone: (operation) => undispatched(operation, new Closed({ cause: options.closedBy() })),
+    scope,
+  });
+
+  // Where this page's latest move left its pointer, which is where its next plain glide starts and
+  // where a held button is released. Its lane orders the page's input, and Chromium keeps a
+  // pointer per page too.
+  const pointer = MutableRef.make(Option.none<Point>());
+
+  // Named, so that the declarations of what holds it need not spell out Playwright's protocol types.
+  const protocol: Pick<CDPSession, "send"> = { send };
+
+  return {
+    ...options,
+    lane,
+    pointer,
+    now,
+    owned,
+    span,
+    protocol,
+    native,
+    within,
+    activity,
+    noteInput,
+  };
+};
+
+export type PageContext = ReturnType<typeof make>;