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

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,
+  };
+};

package/src/internal/input/targets.inpage.ts

@@ -0,0 +1,293 @@
+/**
+ * In the page: where input lands. It resolves a ref or a point to the control under it, in
+ * top-document viewport pixels, with the subject's context, and plans a wheel scroll that brings a
+ * ref into view. See `reading/names.inpage.ts` for what a page-side part may use.
+ */
+import { Schema } from "effect";
+
+import { Box, SubjectContext } from "../../BrowserEvent.ts";
+import type { ContextReader } from "../reading/context.inpage.ts";
+import type { Names } from "../reading/names.inpage.ts";
+import type { Walk } from "../reading/walk.inpage.ts";
+
+export type ResolvedPoint = typeof ResolvedPointSchema.Type;
+export type PointResult = typeof PointResultSchema.Type;
+
+export const targets = (names: Names, walked: Walk, placing: ContextReader) => {
+  const { describe, isDisabled, lookup, nameOf, parentOf, roleOf } = names;
+  const { boxOf, controlOf, hitAt } = walked;
+  const { contextOf } = placing;
+
+  /** Whether `node` is `ancestor` or inside it, across shadow roots and same-origin frames. */
+  const within = (ancestor: Element, node: Element): boolean => {
+    for (let current: Element | null = node; current !== null;) {
+      if (current === ancestor) return true;
+      current = parentOf(current) ?? current.ownerDocument.defaultView?.frameElement ?? null;
+    }
+
+    return false;
+  };
+
+  // A press at a point reaches the element when the top-document hit is the element, inside it,
+  // or one of its containers (whose activation the element's own facts already cover).
+  const receives = (element: Element, hit: Element): boolean =>
+    within(element, hit) || within(hit, element);
+
+  // HTML links, SVG links and image-map areas all navigate; SVG keeps lowercase tag names.
+  const hrefAttribute = (element: Element): string | null =>
+    element.localName === "a" || element.localName === "area"
+      ? (element.getAttribute("href") ??
+        element.getAttributeNS("http://www.w3.org/1999/xlink", "href"))
+      : null;
+
+  const linkOf = (element: Element): Element | undefined => {
+    for (let node: Element | null = element; node !== null; node = parentOf(node))
+      if (hrefAttribute(node) !== null) return node;
+
+    return undefined;
+  };
+
+  const details = (
+    element: Element,
+    hit: Element,
+    x: number,
+    y: number,
+  ): Omit<ResolvedPoint, "context"> => {
+    const link = linkOf(element);
+    let href: string | undefined;
+
+    if (link !== undefined) {
+      try {
+        href = new URL(hrefAttribute(link) ?? "", link.ownerDocument.baseURI).href;
+      } catch {
+        href = undefined;
+      }
+    }
+    const role = roleOf(element);
+    const view = hit.ownerDocument.defaultView ?? window;
+
+    return {
+      x,
+      y,
+      element: describe(element),
+      tag: element.tagName.toLowerCase(),
+      role,
+      name: nameOf(element, role),
+      cursor: view.getComputedStyle(hit).cursor,
+      ...(href === undefined ? {} : { href }),
+    };
+  };
+
+  const point = (
+    target: string | { readonly x: number; readonly y: number },
+    scroll = true,
+  ): PointResult => {
+    if (typeof target !== "string") {
+      const { x, y } = target;
+
+      if (
+        !Number.isFinite(x) ||
+        !Number.isFinite(y) ||
+        x < 0 ||
+        y < 0 ||
+        x >= window.innerWidth ||
+        y >= window.innerHeight
+      )
+        return { error: "outside", detail: `(${x}, ${y}) is outside the viewport` };
+      const hit = hitAt(document, x, y);
+
+      if (hit === null) return { error: "offscreen", detail: `nothing is painted at (${x}, ${y})` };
+      const control = controlOf(hit);
+
+      return { ...details(control, hit, x, y), context: contextOf(control), box: boxOf(control) };
+    }
+    const ref = target;
+    const element = lookup(ref);
+
+    if (element === undefined)
+      return { error: "stale", detail: `${ref} is not on the page any more` };
+    if (isDisabled(element)) return { error: "disabled", detail: `${ref} is disabled` };
+    const rect = element.getBoundingClientRect();
+
+    if (rect.width === 0 && rect.height === 0)
+      return { error: "hidden", detail: `${ref} has no size on the page` };
+
+    // Input arrives in top-document viewport pixels, so geometry and occlusion are measured
+    // there: a frame's own viewport cannot say whether the frame is scrolled away or covered.
+    let box = { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom };
+    let visible = { ...box };
+    let outside = false;
+
+    for (let inner: Element = element; ;) {
+      const view = inner.ownerDocument.defaultView ?? window;
+
+      outside ||=
+        box.left < 0 || box.top < 0 || box.right > view.innerWidth || box.bottom > view.innerHeight;
+      visible = {
+        left: Math.max(visible.left, 0),
+        top: Math.max(visible.top, 0),
+        right: Math.min(visible.right, view.innerWidth),
+        bottom: Math.min(visible.bottom, view.innerHeight),
+      };
+
+      // A field can be inside the viewport and still clipped by a nested scrolling panel.
+      for (let ancestor = parentOf(inner); ancestor !== null; ancestor = parentOf(ancestor)) {
+        const style = view.getComputedStyle(ancestor);
+        const clip = ancestor.getBoundingClientRect();
+
+        if (/(auto|scroll|hidden|clip)/.test(style.overflowX)) {
+          visible.left = Math.max(visible.left, clip.left + ancestor.clientLeft);
+          visible.right = Math.min(
+            visible.right,
+            clip.left + ancestor.clientLeft + ancestor.clientWidth,
+          );
+        }
+        if (/(auto|scroll|hidden|clip)/.test(style.overflowY)) {
+          visible.top = Math.max(visible.top, clip.top + ancestor.clientTop);
+          visible.bottom = Math.min(
+            visible.bottom,
+            clip.top + ancestor.clientTop + ancestor.clientHeight,
+          );
+        }
+      }
+
+      const frame = view.frameElement;
+
+      if (frame === null) break;
+      const frameBox = frame.getBoundingClientRect();
+      const dx = frameBox.left + frame.clientLeft;
+      const dy = frameBox.top + frame.clientTop;
+
+      box = {
+        left: box.left + dx,
+        top: box.top + dy,
+        right: box.right + dx,
+        bottom: box.bottom + dy,
+      };
+      visible = {
+        left: Math.max(visible.left + dx, dx),
+        top: Math.max(visible.top + dy, dy),
+        right: Math.min(visible.right + dx, dx + frame.clientWidth),
+        bottom: Math.min(visible.bottom + dy, dy + frame.clientHeight),
+      };
+      inner = frame;
+    }
+
+    if (outside || visible.right <= visible.left || visible.bottom <= visible.top) {
+      if (scroll) {
+        element.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+
+        return point(target, false);
+      }
+
+      return {
+        error: "offscreen",
+        detail: outside
+          ? ref + " is outside the viewport"
+          : `${ref} could not be scrolled into view`,
+      };
+    }
+    const x = (visible.left + visible.right) / 2;
+    const y = (visible.top + visible.bottom) / 2;
+    const hit = hitAt(document, x, y);
+
+    if (hit !== null && !receives(element, hit))
+      return { error: "covered", detail: `${ref} is covered by ${describe(hit)}` };
+
+    return {
+      ...details(element, hit ?? element, Math.round(x), Math.round(y)),
+      context: contextOf(element),
+    };
+  };
+
+  // Suggest one visible wheel origin. Unsupported frame geometry and fully clipped panels use
+  // the bounded instant fallback; guessing their coordinates could scroll an unrelated control.
+  const scrollPlan = (ref: string) => {
+    const element = lookup(ref);
+
+    if (element === undefined || element.ownerDocument !== document) return null;
+    const target = element.getBoundingClientRect();
+    const centerX = (target.left + target.right) / 2;
+    const centerY = (target.top + target.bottom) / 2;
+
+    for (let ancestor = parentOf(element); ancestor !== null; ancestor = parentOf(ancestor)) {
+      const style = window.getComputedStyle(ancestor);
+
+      const horizontal =
+        /^(auto|scroll)$/.test(style.overflowX) && ancestor.scrollWidth > ancestor.clientWidth;
+
+      const vertical =
+        /^(auto|scroll)$/.test(style.overflowY) && ancestor.scrollHeight > ancestor.clientHeight;
+
+      if (!horizontal && !vertical) continue;
+      const box = ancestor.getBoundingClientRect();
+      const left = Math.max(0, box.left + ancestor.clientLeft);
+      const top = Math.max(0, box.top + ancestor.clientTop);
+
+      const right = Math.min(
+        window.innerWidth,
+        box.left + ancestor.clientLeft + ancestor.clientWidth,
+      );
+
+      const bottom = Math.min(
+        window.innerHeight,
+        box.top + ancestor.clientTop + ancestor.clientHeight,
+      );
+
+      if (right <= left || bottom <= top) continue;
+      const x = (left + right) / 2;
+      const y = (top + bottom) / 2;
+      const dx = horizontal && (target.left < left || target.right > right) ? centerX - x : 0;
+      const dy = vertical && (target.top < top || target.bottom > bottom) ? centerY - y : 0;
+
+      if (dx === 0 && dy === 0) continue;
+      const hit = hitAt(document, x, y);
+
+      if (hit !== null && (hit === ancestor || ancestor.contains(hit))) return { x, y, dx, dy };
+    }
+
+    const dx =
+      target.left < 0 || target.right > window.innerWidth ? centerX - window.innerWidth / 2 : 0;
+
+    const dy =
+      target.top < 0 || target.bottom > window.innerHeight ? centerY - window.innerHeight / 2 : 0;
+
+    return dx === 0 && dy === 0
+      ? null
+      : { x: window.innerWidth / 2, y: window.innerHeight / 2, dx, dy };
+  };
+
+  return { controlOf, details, hitAt, hrefAttribute, linkOf, point, receives, scrollPlan, within };
+};
+
+export type Targets = ReturnType<typeof targets>;
+
+const ResolvedPointSchema = Schema.Struct({
+  x: Schema.Finite,
+  y: Schema.Finite,
+  element: Schema.String,
+  tag: Schema.String,
+  role: Schema.NullOr(Schema.String),
+  name: Schema.String,
+  context: SubjectContext,
+  box: Schema.optional(Box),
+  cursor: Schema.String,
+  href: Schema.optional(Schema.String),
+});
+
+export const PointResultSchema = Schema.Union([
+  ResolvedPointSchema,
+  Schema.Struct({
+    error: Schema.Literals(["stale", "hidden", "offscreen", "disabled", "covered", "outside"]),
+    detail: Schema.String,
+  }),
+]);
+
+export const ScrollPlanSchema = Schema.NullOr(
+  Schema.Struct({
+    x: Schema.Finite,
+    y: Schema.Finite,
+    dx: Schema.Finite,
+    dy: Schema.Finite,
+  }),
+);

package/src/internal/input/targets.ts

@@ -0,0 +1,148 @@
+/**
+ * Where an action's input goes: a ref or a point resolved to a control and a viewport point,
+ * scrolled into view first when it is outside the viewport: at once, or with the wheel where
+ * viewers watch.
+ */
+import { Effect } from "effect";
+
+import { InvalidRequest, NotActionable, StaleRef } from "../../BrowserError.ts";
+import { ResolvedTarget, type Target } from "../../Page.ts";
+import { type Bridge, scriptCall } from "../page/bridge.ts";
+import { decodeWith, failWith } from "../page/context.ts";
+import type { Viewport } from "../page/viewport.ts";
+import type { Dispatch } from "./dispatch.ts";
+import type { Approval, Guard } from "./guard.ts";
+import type { InputMarks } from "./perform.ts";
+import type { Pointer } from "./pointer.ts";
+import type { Settle } from "./settle.ts";
+import * as Script from "./targets.inpage.ts";
+
+const pointFailure = (
+  operation: string,
+  target: Target,
+  result: Extract<Script.PointResult, { readonly error: string }>,
+) =>
+  failWith(
+    operation,
+    result.error === "stale" && typeof target === "string"
+      ? new StaleRef({ ref: target })
+      : result.error === "outside"
+        ? new InvalidRequest({ detail: result.detail })
+        : new NotActionable({ detail: result.detail }),
+  );
+
+const resolvedTarget = (result: Script.ResolvedPoint): ResolvedTarget =>
+  new ResolvedTarget({
+    point: { x: result.x, y: result.y },
+    element: result.element,
+    tag: result.tag,
+    role: result.role,
+    name: result.name,
+    context: result.context,
+    box: result.box,
+    cursor: result.cursor,
+    ...(result.href === undefined ? {} : { href: result.href }),
+  });
+
+export const make = (
+  bridge: Bridge,
+  viewport: Viewport,
+  guard: Guard,
+  pointer: Pointer,
+  dispatch: Dispatch,
+  settling: Settle,
+) => {
+  const { evaluate } = bridge;
+  const { mutate } = guard;
+  const { moveTo, wheel } = pointer;
+  const { flush } = dispatch;
+
+  const readPoint = (
+    operation: string,
+    target: Target,
+    approval: Approval | undefined,
+    scroll: boolean,
+  ) =>
+    (approval === undefined
+      ? evaluate(operation, scriptCall("point", target, scroll))
+      : mutate(operation, scriptCall("point", target, scroll), approval)
+    ).pipe(Effect.flatMap(decodeWith(operation, Script.PointResultSchema)));
+
+  const resolve = (operation: string, target: Target, approval?: Approval, scroll = true) => {
+    if (typeof target === "string" && !/^e\d+$/.test(target))
+      return failWith(
+        operation,
+        new InvalidRequest({ detail: target + " is not a ref; refs look like e12" }),
+      );
+    if (typeof target !== "string" && (!Number.isFinite(target.x) || !Number.isFinite(target.y)))
+      return failWith(
+        operation,
+        new InvalidRequest({ detail: "point coordinates must be finite" }),
+      );
+
+    return readPoint(operation, target, approval, scroll).pipe(
+      Effect.flatMap((result) =>
+        "error" in result
+          ? pointFailure(operation, target, result)
+          : Effect.succeed(resolvedTarget(result)),
+      ),
+    );
+  };
+
+  const targetFor = Effect.fnUntraced(function* (
+    operation: string,
+    target: Target,
+    approval: Approval | undefined,
+    marks: InputMarks,
+  ) {
+    if (!marks.style.shown || typeof target !== "string")
+      return yield* resolve(operation, target, approval);
+
+    // Inspection and policy approval happen before this point. Every retry is geometry only;
+    // scrolling never obtains a fresh approval or silently follows a replacement document.
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const result = yield* readPoint(operation, target, approval, false);
+
+      if (!("error" in result)) return resolvedTarget(result);
+      if (result.error !== "offscreen") return yield* pointFailure(operation, target, result);
+
+      const plan = yield* mutate(operation, scriptCall("scrollPlan", target), approval).pipe(
+        Effect.flatMap(decodeWith(operation, Script.ScrollPlanSchema)),
+      );
+
+      if (plan === null) break;
+      const size = yield* viewport.viewportFor(operation);
+      const point = { x: plan.x, y: plan.y };
+
+      yield* marks.at(point);
+      yield* moveTo(operation, marks, point);
+      const before = settling.mark();
+
+      yield* wheel(
+        operation,
+        marks,
+        point,
+        Math.max(-size.width * 0.9, Math.min(size.width * 0.9, plan.dx)),
+        Math.max(-size.height * 0.9, Math.min(size.height * 0.9, plan.dy)),
+      );
+      yield* flush(operation, marks.input);
+      yield* settling.settle(operation, before);
+      if (approval !== undefined) yield* approval.check();
+    }
+
+    // Wheels may be prevented or the target may need unsupported nested/frame geometry. One
+    // explicit fallback preserves reachability without a distance-dependent protocol loop.
+    yield* marks.touched;
+    const before = settling.mark();
+
+    yield* resolve(operation, target, approval);
+    yield* settling.settle(operation, before);
+    if (approval !== undefined) yield* approval.check();
+
+    return yield* resolve(operation, target, approval, false);
+  });
+
+  return { resolve, targetFor };
+};
+
+export type Targets = ReturnType<typeof make>;