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

package/src/internal/input/perform.ts

@@ -0,0 +1,376 @@
+/**
+ * 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 { Deferred, 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 { redact } from "../page/url.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);
+    });
+
+/** An admitted operation stays owned through its Action and any unanswered native replies. */
+const admission = (page: PageContext, pending: Set<Deferred.Deferred<void>>, name: string) => {
+  let run: Replies.Run | undefined;
+  let end: (() => void) | undefined;
+
+  const enter = Effect.uninterruptible(
+    Effect.gen(function* () {
+      const released = page.inputGate === undefined ? undefined : yield* page.inputGate.enter(name);
+      const done = Deferred.makeUnsafe<void>();
+
+      pending.add(done);
+      end = () => {
+        const finish = () => {
+          released?.();
+          pending.delete(done);
+          Deferred.doneUnsafe(done, Exit.void);
+        };
+
+        if (run === undefined) finish();
+        else run.afterIdle(finish);
+      };
+    }),
+  );
+
+  return {
+    enter,
+    using: (current: Replies.Run) => {
+      run = current;
+    },
+    end: Effect.sync(() => end?.()),
+  };
+};
+
+/** Close a run on every exit while preserving its native replies for the page's next input. */
+const useRun = <A>(
+  page: PageContext,
+  sender: Dispatch,
+  name: string,
+  run: Replies.Run,
+  action: Effect.Effect<A, BrowserError>,
+) =>
+  action.pipe(
+    Effect.matchEffect({
+      onFailure: (error) =>
+        run.close.pipe(
+          Effect.andThen(sender.flush(name, run).pipe(Effect.ignore)),
+          Effect.andThen(Effect.fail(error)),
+        ),
+      onSuccess: (value) =>
+        run.close.pipe(Effect.andThen(sender.flush(name, run)), Effect.as(value)),
+    }),
+    // Cleanup submits missing releases; the page retains replies after caller interruption.
+    Effect.ensuring(run.close.pipe(Effect.andThen(page.openings.clear))),
+    Effect.provideService(Replies.Current, run),
+  );
+
+export const make = (page: PageContext, sender: Dispatch) => {
+  const { id, settings, mapping, lane, publish, now, noteInput, span, owned } = page;
+  const { inputClocks } = sender;
+  const input = Replies.make();
+  const admitted = new Set<Deferred.Deferred<void>>();
+
+  // 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 ticket = admission(page, admitted, name);
+
+      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((current) =>
+            Effect.sync(() => {
+              ticket.using(current);
+              if (estimate !== undefined) inputClocks.set(current, estimate);
+            }),
+          ),
+          Effect.flatMap((run) => useRun(page, sender, name, run, action(run))),
+        );
+
+      // 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,
+          )(
+            ticket.enter.pipe(
+              Effect.andThen(
+                Effect.suspend(() =>
+                  admit.pipe(
+                    Effect.timeoutOrElse({
+                      duration: Duration.millis(
+                        Math.max(0, Duration.toMillis(timeout) - (now() - asked)),
+                      ),
+                      orElse: () => timedOut(name, timeout),
+                    }),
+                  ),
+                ),
+              ),
+              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 action =
+        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((page.inputGate?.check(name) ?? Effect.void).pipe(Effect.andThen(action))),
+          );
+
+          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,
+              url: redact(page.playwright.url()),
+              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(Effect.ensuring(ticket.end));
+    }).pipe(span(`Page.${name}`, info.target === undefined ? {} : { target: info.target }), owned);
+
+  return Object.assign(perform, {
+    idle: Effect.suspend(() => Effect.forEach(admitted, Deferred.await, { discard: true })),
+  });
+};
+
+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>;