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

package/src/internal/input/dispatch.ts

@@ -0,0 +1,161 @@
+/**
+ * Sending input to the browser. Each mouse event, key and inserted text goes out on the page's
+ * protocol session, stamped with the browser's clock when its run has a mapping, and is published
+ * as it is submitted.
+ */
+import { Effect, MutableRef, Option } from "effect";
+
+import {
+  KeyChanged,
+  PointerPressed,
+  PointerReleased,
+  TextInserted,
+  WheelScrolled,
+} from "../../BrowserEvent.ts";
+import { type PageContext, reasonOf, undispatched } from "../page/context.ts";
+import * as BrowserClock from "../pictures/clock.ts";
+import type * as Replies from "./replies.ts";
+
+export type MouseEvent = {
+  readonly type: "mouseMoved" | "mousePressed" | "mouseReleased" | "mouseWheel";
+  readonly x: number;
+  readonly y: number;
+  readonly button?: "none" | "left" | "right" | "middle";
+  readonly buttons?: number;
+  readonly clickCount?: number;
+  readonly deltaX?: number;
+  readonly deltaY?: number;
+};
+
+export const make = (page: PageContext) => {
+  const { id, pointer, publish, now, noteInput, closedBy } = page;
+  const { send } = page.protocol;
+  // Each run's clock mapping, recorded when it begins.
+  const inputClocks = new WeakMap<Replies.Run, BrowserClock.Estimate>();
+
+  // Every run records its mapping when it begins; a missing one leaves Chromium's own receipt time.
+  const stamp = (estimate: BrowserClock.Estimate | undefined, at: number) =>
+    estimate === undefined ? {} : { timestamp: BrowserClock.toBrowserSeconds(estimate, at) };
+
+  const inputCall = <A>(operation: string, effect: Effect.Effect<A, Replies.InputFailure>) =>
+    effect.pipe(
+      Effect.mapError((error) =>
+        undispatched(operation, reasonOf(error.cause, undefined, closedBy())),
+      ),
+    );
+
+  const dispatchMouse = (
+    event: MouseEvent,
+    estimate: BrowserClock.Estimate | undefined,
+    submitted?: () => void,
+  ): Promise<unknown> => {
+    const at = now();
+    const point = { x: event.x, y: event.y };
+    const button = event.button ?? "left";
+
+    // Construct boundary data before dispatch: validation must never abandon the native reply.
+    const ButtonEvent = event.type === "mousePressed" ? PointerPressed : PointerReleased;
+
+    const track =
+      (event.type === "mousePressed" || event.type === "mouseReleased") && button !== "none"
+        ? new ButtonEvent({ at, page: id, ...point, button, clickCount: event.clickCount ?? 1 })
+        : event.type === "mouseWheel"
+          ? new WheelScrolled({
+              at,
+              page: id,
+              ...point,
+              dx: event.deltaX ?? 0,
+              dy: event.deltaY ?? 0,
+            })
+          : undefined;
+
+    const response = send("Input.dispatchMouseEvent", { ...event, ...stamp(estimate, at) });
+
+    noteInput();
+    if (event.type === "mouseMoved") MutableRef.set(pointer, Option.some(point));
+    if (track !== undefined) publish(track);
+    submitted?.();
+
+    return response;
+  };
+
+  const sendMouse = (
+    operation: string,
+    run: Replies.Run,
+    event: MouseEvent,
+    submitted?: () => void,
+  ) =>
+    inputCall(
+      operation,
+      Effect.gen(function* () {
+        const held = `mouse:${event.button ?? "left"}`;
+        const estimate = inputClocks.get(run);
+
+        if (event.type === "mouseReleased") return yield* run.up(held);
+        if (event.type === "mousePressed") {
+          yield* run.reserve(2);
+          yield* run.down(
+            held,
+            () => dispatchMouse(event, estimate, submitted),
+            () =>
+              dispatchMouse(
+                {
+                  type: "mouseReleased",
+                  ...Option.getOrElse(MutableRef.get(pointer), () => ({ x: event.x, y: event.y })),
+                  button: event.button ?? "left",
+                  buttons: 0,
+                  clickCount: event.clickCount ?? 1,
+                },
+                estimate,
+              ),
+          );
+        } else {
+          yield* run.reserve(1);
+          yield* run.send(() => dispatchMouse(event, estimate, submitted));
+        }
+      }),
+    );
+
+  // Keys and text bound for a secret field are recorded without their content.
+  const dispatchKey = (
+    key: string,
+    phase: "down" | "up",
+    command: (at: number, estimate: BrowserClock.Estimate | undefined) => Promise<unknown>,
+    run: Replies.Run,
+    secret = false,
+  ) => {
+    const at = now();
+    const event = new KeyChanged({ at, page: id, key: secret ? "Unidentified" : key, phase });
+    const response = command(at, inputClocks.get(run));
+
+    noteInput();
+    publish(event);
+
+    return response;
+  };
+
+  const dispatchText = (text: string, secret: boolean): Promise<unknown> => {
+    const track = new TextInserted({ at: now(), page: id, text: secret ? "•" : text });
+    const response = send("Input.insertText", { text });
+
+    noteInput();
+    publish(track);
+
+    return response;
+  };
+
+  const flush = (operation: string, run: Replies.Run) => inputCall(operation, run.drain);
+
+  return {
+    inputClocks,
+    stamp,
+    inputCall,
+    dispatchMouse,
+    sendMouse,
+    dispatchKey,
+    dispatchText,
+    flush,
+  };
+};
+
+export type Dispatch = ReturnType<typeof make>;

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

@@ -0,0 +1,162 @@
+/**
+ * In the page: editing a field. It refuses text that a focused control could act on, focuses a
+ * field and chooses a select's options. See `reading/names.inpage.ts` for what a page-side part
+ * may use.
+ */
+import { Schema } from "effect";
+
+import { Subject } from "../../BrowserEvent.ts";
+import type { ContextReader } from "../reading/context.inpage.ts";
+import type { Names } from "../reading/names.inpage.ts";
+import type { Guard } from "./guard.inpage.ts";
+
+export type EditResult =
+  | { readonly ok: true; readonly detail: string }
+  | { readonly error: string; readonly stale?: boolean };
+
+/** A focused field, and whether it is secret. */
+export type FocusResult =
+  | { readonly ok: true; readonly detail: string; readonly secret: boolean }
+  | { readonly error: string; readonly stale?: boolean };
+
+/**
+ * Whether text may be typed, and whether its field is secret. Typing into focus also names the
+ * focused field, when it is one, so the action records what it typed into.
+ */
+export type TypeableResult =
+  | { readonly ok: true; readonly secret: boolean; readonly subject?: typeof Subject.Encoded }
+  | { readonly error: "stale" | "untypeable"; readonly detail: string };
+
+export const edit = (names: Names, guard: Guard, placing: ContextReader) => {
+  const {
+    activeElement,
+    clean,
+    describe,
+    isDisabled,
+    isHtml,
+    isInput,
+    isSecret,
+    isSelect,
+    isTextArea,
+    lookup,
+    nameOf,
+    roleOf,
+  } = names;
+
+  const { textEntry, typingRefusal } = guard;
+
+  /** Whether text may be typed into a ref or focus, and, for a `secret`, only into a secret field. */
+  const typeable = (ref: string | null, secret: boolean): TypeableResult => {
+    const element = ref === null ? activeElement() : lookup(ref);
+
+    if (element === undefined)
+      return {
+        error: "stale",
+        detail: `${ref ?? "the focused element"} is not on the page any more`,
+      };
+
+    const refusal =
+      element === null
+        ? secret
+          ? "nothing has focus to type a secret into"
+          : undefined
+        : (typingRefusal(element, ref !== null) ??
+          (secret && !isSecret(element)
+            ? `${describe(element)} is not a secret field`
+            : undefined));
+
+    if (refusal !== undefined) return { error: "untypeable", detail: refusal };
+    if (element === null || ref !== null || !textEntry(element))
+      return { ok: true, secret: element !== null && isSecret(element) };
+    const role = roleOf(element);
+    const tag = element.tagName.toLowerCase();
+
+    return {
+      ok: true,
+      secret: isSecret(element),
+      subject: { role, name: nameOf(element, role), tag, context: placing.contextOf(element) },
+    };
+  };
+
+  const focus = (ref: string, replace: boolean): FocusResult => {
+    const element = lookup(ref);
+
+    if (element === undefined) return { error: `${ref} is not on the page any more`, stale: true };
+    if (isDisabled(element)) return { error: `${ref} is disabled` };
+    if (!textEntry(element)) return { error: `${ref} is ${describe(element)}, not a text field` };
+    if (isHtml(element)) element.focus();
+    if (replace) {
+      if (isInput(element) || isTextArea(element)) element.select();
+      else element.ownerDocument.getSelection()?.selectAllChildren(element);
+    }
+
+    // Decided after focusing: a focus handler can mark the field secret.
+    return { ok: true, detail: describe(element), secret: isSecret(element) };
+  };
+
+  /** Focus any element that takes focus, such as a link or a button, for a key pressed on it. */
+  const focusOn = (ref: string): EditResult => {
+    const element = lookup(ref);
+
+    if (element === undefined) return { error: `${ref} is not on the page any more`, stale: true };
+    if (isDisabled(element)) return { error: `${ref} is disabled` };
+    if (isHtml(element)) element.focus();
+
+    return activeElement() === element
+      ? { ok: true, detail: describe(element) }
+      : { error: `${ref} is ${describe(element)}, which does not take focus` };
+  };
+
+  const select = (ref: string, values: ReadonlyArray<string>): EditResult => {
+    const element = lookup(ref);
+
+    if (element === undefined) return { error: `${ref} is not on the page any more`, stale: true };
+    if (!isSelect(element))
+      return {
+        error: `${ref} is ${describe(element)}, not a <select>; click it and pick an option`,
+      };
+    const wanted = values.map((value) => value.trim().toLowerCase());
+    const options = Array.from(element.options);
+
+    const chosen = options.filter(
+      (option) =>
+        wanted.includes(option.value.toLowerCase()) ||
+        wanted.includes(clean(option.text).toLowerCase()),
+    );
+
+    if (chosen.length === 0)
+      return {
+        error: `no option matches; the options are ${options.map((option) => JSON.stringify(clean(option.text, 40))).join(", ")}`,
+      };
+    for (const option of options) option.selected = chosen.includes(option);
+    element.dispatchEvent(new Event("input", { bubbles: true }));
+    element.dispatchEvent(new Event("change", { bubbles: true }));
+
+    return { ok: true, detail: chosen.map((option) => clean(option.text, 40)).join(", ") };
+  };
+
+  return { focus, focusOn, select, typeable };
+};
+
+export type Edit = ReturnType<typeof edit>;
+
+export const TypeableResultSchema = Schema.Union([
+  Schema.Struct({
+    ok: Schema.Literal(true),
+    secret: Schema.Boolean,
+    subject: Schema.optional(Subject),
+  }),
+  Schema.Struct({ error: Schema.Literals(["stale", "untypeable"]), detail: Schema.String }),
+]);
+
+const EditFailure = Schema.Struct({ error: Schema.String, stale: Schema.optional(Schema.Boolean) });
+
+export const FocusResultSchema = Schema.Union([
+  Schema.Struct({ ok: Schema.Literal(true), detail: Schema.String, secret: Schema.Boolean }),
+  EditFailure,
+]);
+
+export const EditResultSchema = Schema.Union([
+  Schema.Struct({ ok: Schema.Literal(true), detail: Schema.String }),
+  EditFailure,
+]);

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

@@ -0,0 +1,164 @@
+/**
+ * In the page: what the page says about an input's first target, for a judge, and which fields a
+ * form would send. It never reads what a field holds. See `reading/names.inpage.ts` for what a page-side part may use.
+ */
+import { Schema } from "effect";
+
+import type { ContextReader } from "../reading/context.inpage.ts";
+import type { Names } from "../reading/names.inpage.ts";
+
+export interface FormField {
+  readonly type: string;
+  readonly name: string;
+  readonly autocomplete?: string | undefined;
+  readonly filled: boolean;
+}
+
+/** Page text about the first target. It never includes what a field holds. */
+export interface Evidence {
+  readonly title: string;
+  readonly description?: string | undefined;
+  readonly dialog?: string | undefined;
+  readonly heading?: string | undefined;
+  readonly nearby?: string | undefined;
+  readonly form?:
+    | {
+        readonly method: string;
+        readonly action: string;
+        readonly fields: ReadonlyArray<FormField>;
+      }
+    | undefined;
+}
+
+type Field = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+export const evidence = (names: Names, placing: ContextReader) => {
+  const { clean, isDocument, isInput, isSelect, isTextArea, nameOf, parentOf, roleOf, textOf } =
+    names;
+
+  const { groups, headingBefore, textBeside, treeOf } = placing;
+
+  /** A field a submission would send. */
+  const isField = (element: Element): element is Field =>
+    ((isInput(element) && !["button", "submit", "reset", "image"].includes(element.type)) ||
+      isSelect(element) ||
+      isTextArea(element)) &&
+    !element.matches(":disabled");
+
+  const isFilled = (field: Field): boolean =>
+    isInput(field) && (field.type === "checkbox" || field.type === "radio")
+      ? field.checked
+      : isInput(field) && field.type === "file"
+        ? (field.files?.length ?? 0) > 0
+        : field.value !== "";
+
+  const dialogOf = (element: Element): Element | undefined => {
+    for (let node: Element | null = element; node !== null; node = parentOf(node))
+      if (node.tagName === "DIALOG" || /^(?:alert)?dialog$/.test(node.getAttribute("role") ?? ""))
+        return node;
+
+    return undefined;
+  };
+
+  /** What the page says about an input's first target, for a judge. Never a field's value. */
+  const evidenceOf = (
+    element: Element,
+    form: HTMLFormElement | null,
+    method: string | undefined,
+    action: string | undefined,
+  ): Evidence => {
+    const name = nameOf(element, roleOf(element));
+    const ids = element.getAttribute("aria-describedby");
+
+    const description = clean(
+      ids === null
+        ? (element.getAttribute("aria-description") ?? element.getAttribute("title"))
+        : ids
+            .split(/\s+/)
+            .map((id) => element.ownerDocument.getElementById(id)?.textContent ?? "")
+            .join(" "),
+      120,
+    );
+
+    const dialog = dialogOf(element);
+
+    const title = dialog?.querySelector("h1,h2,h3,h4,h5,h6,[role=heading]");
+
+    const dialogName =
+      dialog === undefined
+        ? ""
+        : clean(nameOf(dialog, "dialog"), 120) ||
+          (title === null || title === undefined ? "" : clean(textOf(title), 120));
+
+    // Each scope stays in the target's own tree: a walker cannot leave a shadow root.
+    const root = element.getRootNode();
+    const top = isDocument(root) ? (root.body ?? root) : root;
+    const inTree = element.closest("dialog,[role=dialog],[role=alertdialog]");
+    let nearby = "";
+
+    for (const scope of new Set([element.closest(groups), inTree, top]))
+      if (scope !== null && nearby === "")
+        nearby = textBeside(element, scope, true) || textBeside(element, scope, false);
+
+    const heading = headingBefore(element, treeOf(element));
+
+    const fields =
+      form === null
+        ? []
+        : Array.from(form.elements)
+            .filter(isField)
+            .slice(0, 16)
+            .map((field) => {
+              const autocomplete = clean(field.getAttribute("autocomplete"), 40);
+
+              return {
+                type: isInput(field) ? field.type : field.tagName.toLowerCase(),
+                name: clean(
+                  isInput(field) && field.type === "hidden"
+                    ? field.getAttribute("name")
+                    : nameOf(field, roleOf(field)),
+                  40,
+                ),
+                ...(autocomplete === "" ? {} : { autocomplete }),
+                filled: isFilled(field),
+              };
+            });
+
+    return {
+      title: clean(document.title, 120),
+      ...(description === "" || description === name ? {} : { description }),
+      ...(dialogName === "" ? {} : { dialog: dialogName }),
+      ...(heading === undefined ? {} : { heading }),
+      ...(nearby === "" ? {} : { nearby }),
+      ...(form === null
+        ? {}
+        : { form: { method: method ?? form.method, action: action ?? form.action, fields } }),
+    };
+  };
+
+  return { evidenceOf, isField, isFilled };
+};
+
+export type EvidenceReader = ReturnType<typeof evidence>;
+
+export const FormFieldSchema = Schema.Struct({
+  type: Schema.String,
+  name: Schema.String,
+  autocomplete: Schema.optional(Schema.String),
+  filled: Schema.Boolean,
+});
+
+export const EvidenceSchema = Schema.Struct({
+  title: Schema.String,
+  description: Schema.optional(Schema.String),
+  dialog: Schema.optional(Schema.String),
+  heading: Schema.optional(Schema.String),
+  nearby: Schema.optional(Schema.String),
+  form: Schema.optional(
+    Schema.Struct({
+      method: Schema.String,
+      action: Schema.String,
+      fields: Schema.Array(FormFieldSchema),
+    }),
+  ),
+});