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

package/src/internal/input/replies.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { Context, 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 {
+  /** A native call made by this operation: cancellation cannot cancel its actual reply. */
+  readonly track: <A>(reply: Promise<A>) => Promise<A>;
+  /** End ownership after the record and all this operation's native replies have settled. */
+  readonly afterIdle: (ended: () => void) => void;
+  /** 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>;
+}
+
+/** Native page calls join their operation's reply ownership, including script mutations. */
+export const Current = Context.Reference<Run | undefined>("effect-browser/internal/input/Current", {
+  defaultValue: () => undefined,
+});
+
+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 observed = new WeakMap<Promise<unknown>, { input: boolean }>();
+    const endings = new Set<() => void>();
+
+    const track = <A>(response: Promise<A>, input = false): Promise<A> => {
+      const existing = observed.get(response);
+
+      if (existing !== undefined) {
+        existing.input ||= input;
+
+        return response;
+      }
+      const entry = { input };
+
+      observed.set(response, entry);
+
+      const reply = response
+        .then(
+          () => undefined,
+          (cause: unknown) => {
+            if (entry.input) failure ??= new InputFailure({ cause });
+          },
+        )
+        .then(() => {
+          pending.delete(reply);
+          outstanding.delete(reply);
+          if (pending.size === 0) {
+            for (const end of endings) end();
+            endings.clear();
+          }
+        });
+
+      pending.add(reply);
+      outstanding.add(reply);
+
+      return response;
+    };
+
+    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;
+      }
+
+      void track(response, true);
+    };
+
+    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 = {
+      track,
+      afterIdle: (end) => {
+        if (pending.size === 0) end();
+        else endings.add(end);
+      },
+      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>;

package/src/internal/input/style.ts

@@ -0,0 +1,186 @@
+/**
+ * How input is sent: plainly, as fast as the page takes it, or performed for viewers, with a
+ * pointer that glides, keys typed at a person's pace, held buttons and wheels in bursts. A page's
+ * actions take one, and the input reaches the same controls either way; only its timing, and
+ * what viewers see of it, differ. A presenter builds the performed one.
+ */
+import { Effect, type MutableRef, type Option, Random } from "effect";
+
+import type * as Motion from "../../Motion.ts";
+import type { Point } from "../../Page.ts";
+import * as Keys from "./keys.ts";
+
+export interface TypingEvent {
+  /** From the start of the typing. */
+  readonly afterMillis: number;
+  readonly phase: "down" | "up" | "insert";
+  readonly key: string;
+}
+
+export interface WheelStep {
+  readonly dx: number;
+  readonly dy: number;
+  /** From the first step. */
+  readonly afterMillis: number;
+}
+
+export interface Style {
+  /**
+   * Whether viewers watch the input: then the pointer clicks into a field before typing, finds
+   * what lies under it as it scrolls, and scrolls to a target out of view with the wheel.
+   */
+  readonly shown: boolean;
+  /** Where viewers last saw the pointer, which the next glide starts from; else the page's own. */
+  readonly pointer: MutableRef.MutableRef<Option.Option<Point>> | undefined;
+  /** The pointer's path to `to`, ending exactly there. */
+  readonly glide: (
+    from: Point,
+    to: Point,
+    dragging: boolean,
+  ) => Effect.Effect<ReadonlyArray<Motion.Sample>>;
+  /** How long a button stays down when a click does not say. */
+  readonly hold: Effect.Effect<number>;
+  /** The key events that type `text`, or one insertion of it under a guard, timed from the start. */
+  readonly typing: (text: string, guarded: boolean) => Effect.Effect<ReadonlyArray<TypingEvent>>;
+  /** The pause between repeated presses of the same keys. */
+  readonly keyGap: Effect.Effect<number>;
+  /** A wheel scroll as the wheel turns: in one step, or in notches and bursts. */
+  readonly wheel: (dx: number, dy: number) => Effect.Effect<ReadonlyArray<WheelStep>>;
+}
+
+/** Each key as it comes, with no pause; a drag moves in eight short steps so its target sees it. */
+export const plain: Style = {
+  shown: false,
+  pointer: undefined,
+  glide: (from, to, dragging) =>
+    Effect.succeed(
+      dragging
+        ? Array.from({ length: 8 }, (_, index) => ({
+            x: index === 7 ? to.x : from.x + ((to.x - from.x) * (index + 1)) / 8,
+            y: index === 7 ? to.y : from.y + ((to.y - from.y) * (index + 1)) / 8,
+            afterMillis: (index + 1) * 8,
+          }))
+        : [{ ...to, afterMillis: 0 }],
+    ),
+  hold: Effect.succeed(0),
+  typing: (text, guarded) =>
+    Effect.succeed(
+      guarded && text !== ""
+        ? [{ afterMillis: 0, phase: "insert", key: text }]
+        : [...text].flatMap((key): ReadonlyArray<TypingEvent> =>
+            Keys.description(key) === undefined
+              ? [{ afterMillis: 0, phase: "insert", key }]
+              : [
+                  { afterMillis: 0, phase: "down", key },
+                  { afterMillis: 0, phase: "up", key },
+                ],
+          ),
+    ),
+  keyGap: Effect.succeed(0),
+  wheel: (dx, dy) => Effect.succeed([{ dx, dy, afterMillis: 0 }]),
+};
+
+// A right-skewed draw, clamped so that cleanup and deadlines stay predictable; 1 - U keeps the
+// logarithm defined when Random returns zero.
+const lognormal = Effect.fnUntraced(function* (
+  median: number,
+  sigma: number,
+  minimum: number,
+  maximum: number,
+) {
+  const radius = Math.sqrt(-2 * Math.log(1 - (yield* Random.next)));
+  const normal = radius * Math.cos(2 * Math.PI * (yield* Random.next));
+
+  return Math.max(minimum, Math.min(maximum, median * Math.exp(sigma * normal)));
+});
+
+/** A pause around `median`, as the research measured reactions: at most four times it. */
+export const pause = (median: number, sigma: number) =>
+  median <= 0 ? Effect.succeed(0) : lognormal(median, sigma, 0, median * 4);
+
+// A mouse press about 80 ms long on average, a key about 110 ms, each now and then longer: their
+// medians are the means times exp(-sigma^2 / 2).
+const pressHold = lognormal(75.2, 0.35, 35, 200);
+const keyHold = lognormal(107.8, 0.2, 60, 220);
+const eventOrder = { up: 0, insert: 1, down: 2 };
+
+/**
+ * Plan the whole text before any key goes, so holds overlap without waiting on the network. A
+ * physical key is never held twice, as with A and a, or ! and 1. The first key waits for the hand
+ * to reach the keys, each later one follows the last by a gap drawn around `gap`, and a word's
+ * first key comes 60 ms later.
+ */
+const typing = Effect.fnUntraced(function* (
+  text: string,
+  gap: number,
+): Effect.fn.Return<ReadonlyArray<TypingEvent>> {
+  const events: Array<TypingEvent> = [];
+  const releases = new Map<string, number>();
+  let due = text === "" ? 0 : yield* Random.nextBetween(150, 400);
+  let previous = "";
+
+  for (const character of text) {
+    if (/\s/u.test(previous) && /[\p{L}\p{N}]/u.test(character)) due += 60;
+    const description = Keys.description(character);
+
+    if (description === undefined)
+      events.push({ afterMillis: due, phase: "insert", key: character });
+    else {
+      due = Math.max(due, (releases.get(description.code) ?? -1) + 1);
+      const released = due + (yield* keyHold);
+
+      events.push(
+        { afterMillis: due, phase: "down", key: character },
+        { afterMillis: released, phase: "up", key: character },
+      );
+      releases.set(description.code, released);
+    }
+    due += yield* Random.nextBetween(gap / 2, (gap * 3) / 2);
+    previous = character;
+  }
+
+  return events.toSorted(
+    (left, right) =>
+      left.afterMillis - right.afterMillis || eventOrder[left.phase] - eventOrder[right.phase],
+  );
+});
+
+/** A word is five characters; the gap leaves room for each word's later start. */
+export const keyGap = (wordsPerMinute: number) => 12_000 / wordsPerMinute - 10;
+
+/**
+ * The wheel in 100 px notches, 30 to 140 ms apart, in bursts of at most nine, with 0.6 to 2.6 s
+ * between bursts, as people scroll.
+ */
+const bursts = Effect.fnUntraced(function* (dx: number, dy: number) {
+  const notches = Math.max(1, Math.ceil(Math.hypot(dx, dy) / 100));
+  const steps: Array<WheelStep> = [];
+  let due = 0;
+
+  for (let index = 0; index < notches; index++) {
+    if (index > 0)
+      due += yield* index % 9 === 0 ? Random.nextBetween(600, 2600) : Random.nextBetween(30, 140);
+    steps.push({ dx: dx / notches, dy: dy / notches, afterMillis: due });
+  }
+
+  return steps;
+});
+
+/** Input performed for viewers, with this pointer and pace. */
+export const performed = (options: {
+  readonly pointer: MutableRef.MutableRef<Option.Option<Point>>;
+  readonly motion: Motion.Service;
+  readonly wordsPerMinute: number;
+}): Style => {
+  const gap = keyGap(options.wordsPerMinute);
+
+  return {
+    shown: true,
+    pointer: options.pointer,
+    glide: (from, to) => options.motion.plan(from, to),
+    hold: pressHold,
+    typing: (text) => typing(text, gap),
+    keyGap: Random.nextBetween(gap / 2, (gap * 3) / 2),
+    wheel: bursts,
+  };
+};