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

package/src/internal/input/perform.ts

@@ -0,0 +1,322 @@
+/**
+ * Performing one action: its turn on the page, the input guard's step, the input run that owns its
+ * replies, and the action's record. Its deadline leaves out the time its style takes to show it.
+ */
+import { Duration, Effect, Exit, Option, Ref } from "effect";
+
+import { BrowserError, PolicyTimeout, Timeout } from "../../BrowserError.ts";
+import { Action, type ActionOptions, Subject } from "../../BrowserEvent.ts";
+import { type Point, redacted, type ResolvedTarget } from "../../Page.ts";
+import { failWith, type PageContext, undispatched } from "../page/context.ts";
+import { Correlation } from "../page/lane.ts";
+import type * as BrowserClock from "../pictures/clock.ts";
+import type { Dispatch } from "./dispatch.ts";
+import type { Approval, PolicyPlan } from "./guard.ts";
+import * as Replies from "./replies.ts";
+import { plain, type Style } from "./style.ts";
+
+export interface InputMarks {
+  /** How the action's input is sent: plainly, or performed for viewers. */
+  readonly style: Style;
+  /**
+   * Time the style spends showing the input, such as a glide or typing at a person's pace, planned
+   * from now: the deadline moves back by as much, so presentation has a budget of its own.
+   */
+  readonly present: (millis: number) => Effect.Effect<void>;
+  /** The action's own input, such as a press, key or wheel, has reached the page. */
+  readonly sent: Effect.Effect<void>;
+  /** Preparatory input, such as the pointer travelling to a target, has reached the page. */
+  readonly touched: Effect.Effect<void>;
+  readonly at: (point: Point) => Effect.Effect<void>;
+  /** What the input acts on, and for a drag where it ends, as the page names them now. */
+  readonly on: (subject: Named, to?: Named) => Effect.Effect<void>;
+  /** The action's text is not bound for a secret field, so its record may keep it. */
+  readonly reveal: Effect.Effect<void>;
+  readonly input: Replies.Run;
+}
+
+/** What the page names a target: a resolved one, or the field that has focus. */
+type Named = Pick<ResolvedTarget, "role" | "name" | "tag" | "context" | "box">;
+
+const subjectOf = (target: Named) =>
+  new Subject({ role: target.role, name: target.name, tag: target.tag, context: target.context });
+
+/** What an action records of what it acted on: subjects, and a point target's box. */
+const actedOn = (subject: Named, to?: Named) => ({
+  subject: subjectOf(subject),
+  box: subject.box,
+  ...(to === undefined ? {} : { to: subjectOf(to) }),
+});
+
+/** A subject as span attributes under `prefix`, without a role it does not have. */
+const subjectAttributes = (prefix: string, subject: Subject | undefined) =>
+  subject === undefined
+    ? {}
+    : {
+        ...(subject.role === null ? {} : { [`${prefix}.role`]: subject.role }),
+        [`${prefix}.name`]: subject.name,
+        [`${prefix}.tag`]: subject.tag,
+      };
+
+/** What an action's record keeps of its call. */
+export interface Call {
+  readonly target?: string | undefined;
+  /** The rest of what the caller asked, recorded so a plan can ask it again. */
+  readonly options?: ActionOptions | undefined;
+  readonly text?: string | undefined;
+  /** The text may be a secret: it is recorded only once the action reveals that it is not. */
+  readonly secret?: boolean | undefined;
+  /** False for navigation, which sends no input. */
+  readonly input?: boolean | undefined;
+  /** False for the pointer's travel ahead of an action, which is no action of its own. */
+  readonly recorded?: boolean | undefined;
+}
+
+const timedOut = (operation: string, timeout: Duration.Duration) =>
+  failWith(operation, new Timeout({ millis: Duration.toMillis(timeout) }));
+
+/**
+ * Fail `effect` with `Timeout` once `timeout` has passed, and as much later again as `presented`
+ * says presentation has planned meanwhile.
+ */
+const deadline =
+  (operation: string, timeout: Duration.Duration, now: () => number, presented: () => number) =>
+  <A>(effect: Effect.Effect<A, BrowserError>) =>
+    Effect.suspend(() => {
+      const due = now() + Duration.toMillis(timeout);
+
+      const expiry: Effect.Effect<never, BrowserError> = Effect.suspend(() => {
+        const left = due + presented() - now();
+
+        return left <= 0
+          ? timedOut(operation, timeout)
+          : Effect.sleep(Duration.millis(left)).pipe(Effect.andThen(expiry));
+      });
+
+      return Effect.raceFirst(effect, expiry);
+    });
+
+export const make = (page: PageContext, sender: Dispatch) => {
+  const { id, settings, mapping, lane, publish, now, noteInput, span, owned } = page;
+  const { inputClocks, flush } = sender;
+  const input = Replies.make();
+
+  // Record the whole operation, but never hold the page's turn or spend its action timeout while
+  // a policy is waiting. Validation binds approval to the document and targets it saw.
+  const perform = <A>(
+    name: string,
+    info: Call,
+    timeout: Duration.Duration,
+    prepare: Effect.Effect<PolicyPlan, BrowserError>,
+    body: (marks: InputMarks, approval: Approval | undefined) => Effect.Effect<A, BrowserError>,
+    style: Style = plain,
+  ): Effect.Effect<A, BrowserError> =>
+    Effect.gen(function* () {
+      const startedAt = now();
+      const sent = yield* Ref.make(false);
+      const at = yield* Ref.make(Option.none<Point>());
+      const acted = yield* Ref.make<Pick<Action, "subject" | "to" | "box">>({});
+
+      // The page may react to preparatory input, as to script changes such as a selection, so
+      // paint from before either is not current; only the action's own input can have given it
+      // effect.
+      const touch = Effect.sync(noteInput);
+
+      // A failure before the action checks its field, a denial included, records no text.
+      let revealed = info.secret !== true;
+      // The time the style has planned to show the input, which the deadline leaves out.
+      let presented = 0;
+
+      const marks = {
+        style,
+        present: (millis: number) =>
+          Effect.sync(() => {
+            presented += Math.max(0, millis);
+          }),
+        sent: Ref.set(sent, true).pipe(Effect.andThen(touch)),
+        touched: touch,
+        at: (point: Point) => Ref.set(at, Option.some(point)),
+        on: (subject: Named, to?: Named) => Ref.set(acted, actedOn(subject, to)),
+        reveal: Effect.sync(() => {
+          revealed = true;
+        }),
+      };
+
+      // Admission waits only on this page's own unresolved replies, in its turn, so a stalled page
+      // cannot delay input on other pages. Input never waits for the clock mapping: until a
+      // capture has measured one, it keeps Chromium's own receipt time.
+      let estimate: BrowserClock.Estimate | undefined;
+
+      const admit = input.idle.pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            estimate = (info.input ?? true) ? mapping.latest() : undefined;
+          }),
+        ),
+      );
+
+      const useInput = <Value>(action: (run: Replies.Run) => Effect.Effect<Value, BrowserError>) =>
+        input.begin.pipe(
+          // A capture can recalibrate while input is running. One run, including delayed cleanup
+          // releases, keeps one mapping so epoch stamps cannot jump backwards during a stroke.
+          Effect.tap((run) =>
+            Effect.sync(() => {
+              if (estimate !== undefined) inputClocks.set(run, estimate);
+            }),
+          ),
+          Effect.flatMap((run) =>
+            action(run).pipe(
+              Effect.matchEffect({
+                onFailure: (error) =>
+                  run.close.pipe(
+                    Effect.andThen(flush(name, run).pipe(Effect.ignore)),
+                    Effect.andThen(Effect.fail(error)),
+                  ),
+                onSuccess: (value) =>
+                  run.close.pipe(Effect.andThen(flush(name, run)), Effect.as(value)),
+              }),
+              // The finalizer only submits missing releases. It cannot wait forever for a
+              // disconnected peer; the page retains those replies and gates its next action.
+              Effect.ensuring(run.close.pipe(Effect.andThen(page.openings.clear))),
+            ),
+          ),
+        );
+
+      // How long its turn and the page's replies kept the action waiting, once it had both.
+      let queuedMillis: number | undefined;
+
+      // The page's turn and its earlier input's replies are waited for within the action's
+      // deadline, undispatched: a turn not given by then is `Busy`, and replies not answered by
+      // then a `Timeout`. The turn starts a full deadline of its own, so a wait never truncates
+      // input under way.
+      const dispatch = <Value>(action: Effect.Effect<Value, BrowserError>) =>
+        Effect.suspend(() => {
+          const asked = now();
+
+          return lane.write(
+            name,
+            timeout,
+          )(
+            Effect.suspend(() =>
+              admit.pipe(
+                Effect.timeoutOrElse({
+                  duration: Duration.millis(
+                    Math.max(0, Duration.toMillis(timeout) - (now() - asked)),
+                  ),
+                  orElse: () => timedOut(name, timeout),
+                }),
+              ),
+            ).pipe(
+              Effect.tap(() =>
+                Effect.sync(() => {
+                  queuedMillis = Math.round(now() - asked);
+                }),
+              ),
+              Effect.andThen(deadline(name, timeout, now, () => presented)(action)),
+            ),
+          );
+        });
+
+      const guard = settings.guard;
+
+      // Only an approval needs binding: without a guard, input goes straight to the page.
+      const run =
+        guard === undefined
+          ? dispatch(useInput((run) => body({ ...marks, input: run }, undefined)))
+          : Effect.gen(function* () {
+              const plan = yield* lane
+                .read(name)(deadline(name, settings.actionTimeout, now, () => 0)(prepare))
+                .pipe(span("Page.prepare", {}, "Debug"));
+
+              // A hold lasts as long as this span; a judge's model call is its child.
+              yield* guard(plan.request).pipe(
+                Effect.mapError((reason) => undispatched(name, reason)),
+                Effect.timeoutOrElse({
+                  duration: settings.policyTimeout,
+                  orElse: () =>
+                    failWith(
+                      name,
+                      new PolicyTimeout({ millis: Duration.toMillis(settings.policyTimeout) }),
+                    ),
+                }),
+                span("Page.guard"),
+              );
+
+              return yield* dispatch(
+                useInput((run) =>
+                  plan.validate.pipe(
+                    Effect.flatMap((approval) => body({ ...marks, input: run }, approval)),
+                  ),
+                ),
+              );
+            });
+
+      const record = info.recorded === false ? () => 0 : publish;
+
+      // Record the outcome even when the caller interrupts: its input may already be in the page.
+      return yield* Effect.uninterruptibleMask((restore) =>
+        Effect.gen(function* () {
+          const exit = yield* Effect.exit(restore(run));
+          const dispatched = yield* Ref.get(sent);
+          const point = yield* Ref.get(at);
+          const { subject, to, box } = yield* Ref.get(acted);
+          const failure = Exit.isFailure(exit) ? Exit.findErrorOption(exit) : Option.none();
+
+          // What the Action records, less its text: only a revealed text's length.
+          yield* Effect.annotateCurrentSpan({
+            dispatched,
+            ...(queuedMillis === undefined ? {} : { queuedMillis }),
+            ...(info.text !== undefined && revealed ? { chars: info.text.length } : {}),
+            ...subjectAttributes("subject", subject),
+            ...subjectAttributes("to", to),
+            ...Option.match(failure, {
+              onNone: () => ({}),
+              onSome: (error) => ({ "error.type": error.reason._tag }),
+            }),
+          });
+
+          record(
+            new Action({
+              at: now(),
+              startedAt,
+              page: id,
+              name,
+              correlation: yield* Correlation,
+              target: info.target,
+              options: Exit.isSuccess(exit) ? info.options : undefined,
+              subject,
+              to,
+              box,
+              text:
+                info.text === undefined ? undefined : revealed ? info.text.slice(0, 200) : redacted,
+              x: Option.getOrUndefined(Option.map(point, (p) => p.x)),
+              y: Option.getOrUndefined(Option.map(point, (p) => p.y)),
+              ok: Exit.isSuccess(exit),
+              dispatched,
+              error: Option.match(failure, {
+                onNone: () => (Exit.hasInterrupts(exit) ? "interrupted" : undefined),
+                onSome: (error) => error.message,
+              }),
+            }),
+          );
+          if (Exit.isSuccess(exit)) return exit.value;
+          if (dispatched)
+            return yield* Exit.mapError(exit, (error) =>
+              error.dispatched
+                ? error
+                : new BrowserError({
+                    operation: error.operation,
+                    reason: error.reason,
+                    dispatched: true,
+                  }),
+            );
+
+          return yield* exit;
+        }),
+      );
+    }).pipe(span(`Page.${name}`, info.target === undefined ? {} : { target: info.target }), owned);
+
+  return perform;
+};
+
+export type Perform = ReturnType<typeof make>;

package/src/internal/input/pointer.ts

@@ -0,0 +1,153 @@
+/**
+ * The pointer's travel and the wheel, as the action's style sends them. Travel follows a motion
+ * plan, published before its first move, from where viewers last saw the pointer when it is
+ * shown, and a wheel scroll goes in the style's steps.
+ */
+import { Duration, Effect, MutableRef, Option, Schema } from "effect";
+
+import { InvalidRequest } from "../../BrowserError.ts";
+import { CursorChanged, TrackPerformed, TrackPlanned } from "../../BrowserEvent.ts";
+import * as Motion from "../../Motion.ts";
+import type { Point } from "../../Page.ts";
+import { failWith, type PageContext } from "../page/context.ts";
+import type { Viewport } from "../page/viewport.ts";
+import type { Dispatch } from "./dispatch.ts";
+import type { InputMarks } from "./perform.ts";
+
+export const make = (page: PageContext, dispatch: Dispatch, viewport: Viewport) => {
+  const { id, pointer, publish, now, span } = page;
+  const { inputClocks, inputCall, dispatchMouse, sendMouse } = dispatch;
+
+  // Travel toward a press only prepares the action; a hover is its travel, and a drag holds the
+  // button it has already pressed.
+  const moveTo = (
+    operation: string,
+    marks: InputMarks,
+    to: Point,
+    cursor?: string,
+    travel: "approach" | "hover" | "drag" = "approach",
+  ) =>
+    Effect.gen(function* () {
+      const dragging = travel === "drag";
+      const { style } = marks;
+      const drawn = style.pointer ?? pointer;
+      const size = yield* viewport.viewportFor(operation);
+
+      const previous = Option.getOrElse(MutableRef.get(drawn), () => ({
+        x: Math.round(size.width / 2),
+        y: Math.round(size.height / 2),
+      }));
+
+      const from = {
+        x: Math.max(0, Math.min(size.width - 1, previous.x)),
+        y: Math.max(0, Math.min(size.height - 1, previous.y)),
+      };
+
+      const planned = yield* style.glide(from, to, dragging);
+
+      // A custom planner is a boundary. Decoding reads each sample once into a fresh copy and
+      // checks that copy, so neither accessors nor later mutation can change what is admitted.
+      const invalid = failWith(
+        operation,
+        new InvalidRequest({
+          detail: "motion must be a bounded, ordered schedule ending at the target",
+        }),
+      );
+
+      const samples = yield* Schema.decodeEffect(Motion.Plan)(planned).pipe(
+        Effect.catch(() => invalid),
+      );
+
+      if (samples.at(-1)?.x !== to.x || samples.at(-1)?.y !== to.y) return yield* invalid;
+      yield* Effect.annotateCurrentSpan("samples", samples.length);
+      yield* marks.present(samples.at(-1)?.afterMillis ?? 0);
+      const run = marks.input;
+
+      // Admit the whole motion before starting its clock. Dense original samples must not be
+      // stretched by per-sample reply backpressure; unsent reservations belong to this run.
+      yield* inputCall(operation, run.reserveMotion(samples.length));
+      MutableRef.set(pointer, Option.some(from));
+      const estimate = inputClocks.get(run);
+      const at = now();
+      let dispatched = 0;
+      let last = from;
+
+      // The complete plan exists before its first move. A canceled performer always clips
+      // that future to the prefix it actually submitted, including interruption during sleep.
+      yield* Effect.acquireUseRelease(
+        Effect.sync(() => publish(new TrackPlanned({ at, page: id, from, samples }))),
+        () =>
+          Effect.gen(function* () {
+            for (const sample of samples) {
+              const remaining = at + sample.afterMillis - now();
+
+              if (remaining > 0) yield* Effect.sleep(Duration.millis(remaining));
+              yield* travel === "approach" ? marks.touched : marks.sent;
+              yield* inputCall(
+                operation,
+                run.send(() =>
+                  dispatchMouse(
+                    {
+                      type: "mouseMoved",
+                      x: sample.x,
+                      y: sample.y,
+                      button: dragging ? "left" : "none",
+                      ...(dragging ? { buttons: 1 } : {}),
+                    },
+                    estimate,
+                    () => {
+                      dispatched++;
+                      last = { x: sample.x, y: sample.y };
+                      MutableRef.set(drawn, Option.some(last));
+                      if (dispatched === samples.length && cursor !== undefined)
+                        publish(new CursorChanged({ at: now(), page: id, cursor }));
+                    },
+                  ),
+                ),
+              );
+            }
+          }),
+        (plan) =>
+          Effect.sync(() =>
+            publish(
+              new TrackPerformed({
+                at: now(),
+                page: id,
+                plan,
+                dispatched,
+                ...last,
+                complete: dispatched === samples.length,
+              }),
+            ),
+          ),
+      );
+    }).pipe(span("Page.move", {}, "Debug"));
+
+  const wheel = Effect.fnUntraced(function* (
+    operation: string,
+    marks: InputMarks,
+    point: Point,
+    dx: number,
+    dy: number,
+  ) {
+    const steps = yield* marks.style.wheel(dx, dy);
+    const at = now();
+
+    yield* marks.present(steps.at(-1)?.afterMillis ?? 0);
+    for (const step of steps) {
+      const remaining = at + step.afterMillis - now();
+
+      if (remaining > 0) yield* Effect.sleep(Duration.millis(remaining));
+      yield* sendMouse(operation, marks.input, {
+        type: "mouseWheel",
+        ...point,
+        deltaX: step.dx,
+        deltaY: step.dy,
+      });
+    }
+  });
+
+  return { moveTo, wheel };
+};
+
+export type Pointer = ReturnType<typeof make>;

package/src/internal/input/replies.ts

@@ -0,0 +1,159 @@
+/**
+ * Bounded input replies owned by the page, including after an action is interrupted.
+ * Canceling a caller cannot cancel a protocol command already sent. The next action waits for
+ * those replies, while a stopped run releases only held keys or buttons whose release was never submitted.
+ */
+import { Data, Effect } from "effect";
+
+import { maximumSamples } from "../../Motion.ts";
+
+export const capacity = 64;
+
+export class InputFailure extends Data.TaggedError("InputFailure")<{
+  readonly cause: unknown;
+}> {}
+
+export interface Run {
+  /** Reserve a complete stroke, including its releases, before sending its first event. */
+  readonly reserve: (commands: number) => Effect.Effect<void, InputFailure>;
+  /** Admit every sample before a motion starts its published clock; ordinary input stays bounded separately. */
+  readonly reserveMotion: (commands: number) => Effect.Effect<void, InputFailure>;
+  readonly send: (command: () => Promise<unknown>) => Effect.Effect<void, InputFailure>;
+  readonly down: (
+    key: string,
+    press: () => Promise<unknown>,
+    release: () => Promise<unknown>,
+  ) => Effect.Effect<void, InputFailure>;
+  readonly up: (key: string) => Effect.Effect<void, InputFailure>;
+  readonly drain: Effect.Effect<void, InputFailure>;
+  /** Stop future input and submit missing releases without waiting indefinitely for replies. */
+  readonly close: Effect.Effect<void>;
+}
+
+export const make = () => {
+  const outstanding = new Set<Promise<void>>();
+
+  // A timed-out action keeps capacity until its real replies arrive. Waiting for them sends
+  // nothing, so cancellation here cannot leave a detached continuation that later types.
+  const idle = Effect.gen(function* () {
+    while (outstanding.size > 0) yield* Effect.promise(() => Promise.all(outstanding));
+  });
+
+  const begin = Effect.gen(function* () {
+    yield* idle;
+    const pending = new Set<Promise<void>>();
+    const held: Array<{ readonly key: string; readonly release: () => Promise<unknown> }> = [];
+    let failure: InputFailure | undefined;
+    let reserved = 0;
+    let closed = false;
+
+    const requireOpen = Effect.suspend(() =>
+      closed
+        ? Effect.fail(new InputFailure({ cause: new Error("the input run has stopped") }))
+        : Effect.void,
+    );
+
+    const requireSuccess = Effect.suspend(() =>
+      failure === undefined ? Effect.void : Effect.fail(failure),
+    );
+
+    const submit = (command: () => Promise<unknown>) => {
+      if (reserved < 1) throw new Error("input must reserve capacity before dispatch");
+      reserved--;
+      let response: Promise<unknown>;
+
+      try {
+        response = command();
+      } catch (cause) {
+        failure ??= new InputFailure({ cause });
+
+        return;
+      }
+
+      // Every rejection is observed immediately; a failure does not abandon later replies.
+      const reply = response.then(
+        () => {
+          pending.delete(reply);
+          outstanding.delete(reply);
+        },
+        (cause: unknown) => {
+          failure ??= new InputFailure({ cause });
+          pending.delete(reply);
+          outstanding.delete(reply);
+        },
+      );
+
+      pending.add(reply);
+      outstanding.add(reply);
+    };
+
+    const reserve = (commands: number, maximum: number, limit: number) =>
+      Effect.gen(function* () {
+        yield* requireOpen;
+        yield* requireSuccess;
+        if (!Number.isInteger(commands) || commands < 1 || commands > maximum)
+          return yield* Effect.die(new Error("invalid input reservation"));
+        while (outstanding.size + reserved + commands > limit) {
+          yield* Effect.promise(() => Promise.race(outstanding));
+          yield* requireOpen;
+          yield* requireSuccess;
+        }
+        reserved += commands;
+      });
+
+    const run: Run = {
+      reserve: (commands) => reserve(commands, capacity, capacity),
+      // A dense stroke cannot wait for replies midway without changing its published timing.
+      // Its finite reservation also leaves room for the ordinary pool's already-owned releases.
+      reserveMotion: (commands) => reserve(commands, maximumSamples, capacity + maximumSamples),
+      send: (command) =>
+        Effect.gen(function* () {
+          yield* requireOpen;
+          yield* requireSuccess;
+          yield* Effect.sync(() => submit(command));
+          yield* requireSuccess;
+        }),
+      down: (key, press, release) =>
+        Effect.gen(function* () {
+          yield* requireOpen;
+          yield* requireSuccess;
+          yield* Effect.sync(() => {
+            held.push({ key, release });
+            submit(press);
+          });
+          yield* requireSuccess;
+        }),
+      up: (key) =>
+        Effect.gen(function* () {
+          yield* requireOpen;
+          yield* Effect.sync(() => {
+            const index = held.findLastIndex((entry) => entry.key === key);
+            const entry = held[index];
+
+            if (entry === undefined) return;
+            // Submission owns the release, even if its reply fails. Retrying an uncertain
+            // release could run page handlers twice, so cleanup never sends it again.
+            held.splice(index, 1);
+            submit(entry.release);
+          });
+          yield* requireSuccess;
+        }),
+      drain: Effect.gen(function* () {
+        while (pending.size > 0) yield* Effect.promise(() => Promise.all(pending));
+        yield* requireSuccess;
+      }),
+      close: Effect.sync(() => {
+        if (closed) return;
+        closed = true;
+        for (const entry of held.toReversed()) submit(entry.release);
+        held.length = 0;
+        reserved = 0;
+      }),
+    };
+
+    return run;
+  });
+
+  /** `idle` lets an action wait, in its page's turn, for the page's earlier replies. */
+  return { idle, begin };
+};

package/src/internal/input/settle.ts

@@ -0,0 +1,50 @@
+/**
+ * The wait after input: one task and one frame in the page, in one call, then a document only if
+ * one committed meanwhile, until it is parsed. Chromium answers a call to a page that a link, a form
+ * or a script's timer has asked to navigate only once the new document commits, or the navigation
+ * stops without one, as on a 204, so the call spans the navigation the input asked for. A
+ * `pushState` asks for no document, and a navigation a handler starts after a fetch answers is the
+ * next look's to see. A tab the input opened waits for the browser's registration too.
+ */
+import { Deferred, Duration, Effect, Exit } from "effect";
+
+import { type Bridge, scriptCall } from "../page/bridge.ts";
+import { contextGone, type PageContext } from "../page/context.ts";
+
+// A document still loading after this, or a closed page, is the next look's to show.
+const settling = Duration.seconds(5);
+
+export const make = (page: PageContext, bridge: Bridge) => {
+  const document = () => bridge.frameTag().document;
+  // The latest document whose DOMContentLoaded came, and what wakes a wait for the next.
+  let parsed = -1;
+  let changed = Deferred.makeUnsafe<void>();
+
+  page.cdp.on("Page.domContentEventFired", () => {
+    parsed = document();
+    Deferred.doneUnsafe(changed, Exit.void);
+    changed = Deferred.makeUnsafe<void>();
+  });
+
+  /** The page's document before input, which `settle` measures from. */
+  const mark = () => ({ document: document(), openings: page.openings.mark() });
+
+  /** Wait for the page to settle after input sent since `before`. */
+  const settle = (operation: string, before: ReturnType<typeof mark>) =>
+    Effect.gen(function* () {
+      // A commit ends the call's world; the loop then waits for that document.
+      yield* bridge
+        .evaluate(operation, scriptCall("settle"))
+        .pipe(Effect.catchIf(contextGone, () => Effect.void));
+      while (document() > before.document && parsed < document()) yield* Deferred.await(changed);
+    }).pipe(
+      Effect.timeoutOrElse({ duration: settling, orElse: () => Effect.fail("unsettled") }),
+      Effect.catch(() => Effect.annotateCurrentSpan("settled", false)),
+      Effect.andThen(page.openings.settle(before.openings)),
+      page.span("Page.settle", {}, "Debug"),
+    );
+
+  return { mark, settle };
+};
+
+export type Settle = ReturnType<typeof make>;