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

package/src/internal/reading/ready.ts

@@ -0,0 +1,105 @@
+/**
+ * Waiting until a page is ready to be shown. The page's own evidence leads: one page-script call
+ * that checks in the page until nothing is left to wait for, or the time is up. A caller that also
+ * needs the screen still, such as after spinning a canvas game's reels, gives a quiet spell, and
+ * the capture must then show no frame that long. A capture's silence cannot prove the last paint
+ * arrived: a frame can be held on its way by a stalled connection, and Chromium sends frames only
+ * while few acknowledgements are unanswered. So the spell counts only while every acknowledgement
+ * is answered, and it ends with the page's evidence once more and, where the capture runs on a
+ * connection of its own, a round trip there: each answer comes behind every frame sent before it on
+ * its connection, and a frame that arrives first starts the spell again. Where the page's changes
+ * are recorded, its evidence includes them: nothing in view may have changed for the spell, which a
+ * DOM page's changes show better than its paint, and no stall on the way can hide.
+ */
+import { Duration, Effect, Schedule, Stream } from "effect";
+
+import { Timeout } from "../../BrowserError.ts";
+import type { ReadyOptions } from "../../Page.ts";
+import { type Bridge, scriptCall } from "../page/bridge.ts";
+import { decodeWith, failWith, type PageContext } from "../page/context.ts";
+import type * as Capture from "../pictures/capture.ts";
+import { ReadinessSchema } from "./ready.inpage.ts";
+
+export const make =
+  (page: PageContext, bridge: Bridge, capture: Capture.Controller) =>
+  (options: ReadyOptions = {}) => {
+    const timeout = options.timeout ?? Duration.seconds(15);
+
+    // The page's own evidence, checked in the page until nothing is left or `until` has come.
+    const settled = (until: number) =>
+      Effect.suspend(() =>
+        bridge.evaluate(
+          "ready",
+          scriptCall(
+            "ready",
+            Math.max(0, Math.round(until - page.now())),
+            options.quietMillis ?? 0,
+          ),
+        ),
+      ).pipe(
+        Effect.flatMap(decodeWith("ready", ReadinessSchema)),
+        Effect.tap((waiting) => Effect.annotateCurrentSpan({ waiting: waiting.join(",") })),
+        Effect.filterOrElse(
+          (waiting) => waiting.length === 0,
+          () => failWith("ready", new Timeout({ millis: Duration.toMillis(timeout) })),
+        ),
+      );
+
+    // A capture the wait starts sends its first frame late, over half a second from a hosted
+    // browser, so the spell counts from that frame (#202); Chrome sends one as a capture starts,
+    // even of a still page.
+    const quiet = (millis: number, until: number) =>
+      Effect.gen(function* () {
+        const running = yield* capture.active;
+        let { received } = yield* capture.stats();
+        let stirred = running ? page.now() : Number.POSITIVE_INFINITY;
+
+        // How long the screen has been still: since a frame, or an unanswered acknowledgement.
+        const look = Effect.map(capture.stats(), (stats) => {
+          if (stats.received !== received || stats.ackBacklog > 0) {
+            received = stats.received;
+            stirred = page.now();
+          }
+
+          return page.now() - stirred;
+        });
+
+        const spell = Effect.repeat(look, {
+          schedule: Schedule.spaced(Duration.millis(25)),
+          until: (still) => still >= millis,
+        });
+
+        const capturing = running
+          ? Effect.never
+          : capture.stream().pipe(Stream.runDrain, Effect.andThen(Effect.never));
+
+        const still = Effect.gen(function* () {
+          for (;;) {
+            yield* spell;
+            const before = received;
+
+            yield* Effect.all([settled(until), capture.sync], { concurrency: 2, discard: true });
+            if ((yield* look) >= millis && received === before) return;
+          }
+        });
+
+        return yield* Effect.raceFirst(capturing, still);
+      });
+
+    // The wait follows the action in flight, as a read does, but holds no later one back while it
+    // watches the page settle, which can take its whole timeout.
+    return page.lane
+      .read("ready")(Effect.void)
+      .pipe(
+        Effect.andThen(
+          Effect.gen(function* () {
+            const until = page.now() + Duration.toMillis(timeout);
+
+            yield* settled(until);
+            if (options.quietMillis !== undefined) yield* quiet(options.quietMillis, until);
+          }).pipe(page.within("ready", timeout)),
+        ),
+        page.span("Page.ready"),
+        page.owned,
+      );
+  };

package/src/internal/reading/subjects.inpage.ts

@@ -0,0 +1,188 @@
+/**
+ * In the page: subjects, and `find`. A subject is what an action acts on and what `find` finds:
+ * an element's role, name and tag, plus its context (see `context.inpage.ts`). Its state is read
+ * beside it. See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { SubjectContext } from "../../BrowserEvent.ts";
+import type { ContextReader } from "./context.inpage.ts";
+import type { FindRequest, Match } from "./match.inpage.ts";
+import type { Names } from "./names.inpage.ts";
+import type { Walk } from "./walk.inpage.ts";
+
+export const subjects = (names: Names, walked: Walk, matching: Match, placing: ContextReader) => {
+  const { isDisabled, isInput, nameOf, refFor, refs, roleOf, textOf } = names;
+  const { acts, boxOf, controlOf, hitAt, inView } = walked;
+  const { contextOf, known } = placing;
+
+  /** What the outline lists as a control, with a ref: something a person would act on. */
+  const isControl = (
+    element: Element,
+    role: string | null,
+    style: CSSStyleDeclaration,
+    rect: DOMRect,
+    insidePointer: boolean,
+  ): boolean =>
+    acts(element, role) ||
+    (style.cursor === "pointer" && !insidePointer && rect.width > 0 && rect.height > 0);
+
+  const stateOf = (element: Element, role: string | null) => {
+    // A state the page gives either way, or none.
+    const given = (attribute: string) => {
+      const value = element.getAttribute(attribute);
+
+      return value === "true" || (value === "false" ? false : undefined);
+    };
+
+    const checkable =
+      element.hasAttribute("aria-checked") ||
+      ["checkbox", "radio", "switch", "menuitemcheckbox", "menuitemradio"].includes(role ?? "");
+
+    // In the order the outline shows them.
+    return {
+      disabled: isDisabled(element),
+      checked: checkable
+        ? (isInput(element) && element.checked) || element.getAttribute("aria-checked") === "true"
+        : undefined,
+      expanded: given("aria-expanded"),
+      selected: given("aria-selected"),
+      pressed: given("aria-pressed"),
+      focused: element.ownerDocument.activeElement === element,
+      level:
+        role === "heading"
+          ? Number(element.getAttribute("aria-level")) ||
+            Number(/^H([1-6])$/.exec(element.tagName)?.[1]) ||
+            2
+          : undefined,
+    };
+  };
+
+  /**
+   * The elements in scope that match a query, in tree order. Without text, an element matches
+   * when it has a role or is a control. With text, any element can, but text inside a control or
+   * heading is that control's or heading's, and an element is left out when one inside it
+   * matches too: the smallest element showing the text is found, not each one around it.
+   */
+  const matched = (request: FindRequest) => {
+    const { at } = request;
+    const matches = matching.compile(request);
+    const byText = request.text !== null;
+    const viewport = request.scope === "viewport";
+    const read = known();
+
+    interface Entry {
+      readonly element: Element;
+      readonly rect: DOMRect;
+      readonly role: string | null;
+      name?: string;
+      context?: SubjectContext;
+      matched: boolean;
+    }
+
+    // An element the walk is inside: its entry if it may match, whether text flows into it
+    // without a break, the text read in it so far, and whether something in it matched.
+    interface Open {
+      readonly entry: Entry | undefined;
+      readonly inline: boolean;
+      readonly parts: Array<string>;
+      inside: boolean;
+    }
+
+    const entries: Array<Entry> = [];
+    const open: Array<Open> = [];
+
+    const named = (entry: Entry) => (entry.name ??= nameOf(entry.element, entry.role));
+    const placed = (entry: Entry) => (entry.context ??= contextOf(entry.element, read));
+
+    const judge = (entry: Entry, text: () => string) =>
+      matches({ role: entry.role, name: () => named(entry), text, context: () => placed(entry) });
+
+    // At a point, the one element a point action there would reach, if it meets the other rules.
+    const hit = at === null ? null : hitAt(document, at.x, at.y);
+
+    if (hit !== null) {
+      const element = controlOf(hit);
+      const { x, y, width, height } = boxOf(element);
+      const rect = new DOMRect(x, y, width, height);
+      const entry: Entry = { element, rect, role: roleOf(element), matched: false };
+
+      entry.matched = judge(entry, () => textOf(element));
+      entries.push(entry);
+    }
+    if (at === null)
+      walked.visit(
+        null,
+        viewport,
+        { pointer: false, owned: false },
+        {
+          enter: (element, style, rect, state) => {
+            const role = roleOf(element);
+            const control = isControl(element, role, style, rect, state.pointer);
+            const unit = control || role === "heading";
+            const candidate = byText ? unit || !state.owned : role !== null || control;
+
+            const entry =
+              candidate && (!viewport || inView(rect))
+                ? { element, rect, role, matched: false }
+                : undefined;
+
+            if (entry !== undefined) entries.push(entry);
+            open.push({ entry, inline: style.display === "inline", parts: [], inside: false });
+
+            return {
+              pointer: state.pointer || style.cursor === "pointer",
+              owned: state.owned || unit,
+            };
+          },
+          text: byText ? (node) => open.at(-1)?.parts.push(node.textContent ?? "") : undefined,
+          leave: () => {
+            const closed = open.pop();
+            const parent = open.at(-1);
+
+            if (closed === undefined) return;
+            const { entry } = closed;
+            const text = closed.parts.join("");
+
+            if (parent !== undefined) parent.parts.push(closed.inline ? text : ` ${text} `);
+            if (entry !== undefined && !(byText && closed.inside))
+              entry.matched = judge(entry, () => text);
+            if (parent !== undefined) parent.inside ||= closed.inside || entry?.matched === true;
+          },
+        },
+      );
+
+    return { entries: entries.filter((entry) => entry.matched), named, placed };
+  };
+
+  const find = (request: FindRequest) => {
+    if (refs.next < request.firstRef) refs.next = request.firstRef;
+    const { entries, named, placed } = matched(request);
+
+    const found = entries.map((entry) => ({
+      ref: refFor(entry.element),
+      subject: {
+        role: entry.role,
+        name: named(entry),
+        tag: entry.element.tagName.toLowerCase(),
+        context: placed(entry),
+      },
+      box: {
+        x: Math.round(entry.rect.x),
+        y: Math.round(entry.rect.y),
+        width: Math.round(entry.rect.width),
+        height: Math.round(entry.rect.height),
+      },
+      inViewport: inView(entry.rect),
+      state: stateOf(entry.element, entry.role),
+    }));
+
+    return { found, nextRef: refs.next };
+  };
+
+  /** The elements `find` would find, in tree order, with no refs given. */
+  const elementsOf = (request: FindRequest) =>
+    matched(request).entries.map((entry) => entry.element);
+
+  return { find, elementsOf, isControl, stateOf };
+};
+
+export type Subjects = ReturnType<typeof subjects>;

package/src/internal/reading/text.inpage.ts

@@ -0,0 +1,135 @@
+/**
+ * In the page: the text a page shows, and the one rule for what a field shows. A field's value
+ * reads `••••` unless a caller unmasks it, and a secret field's always does, including a field
+ * that was secret when the library saw it, such as a password its page now reveals. Text, and the
+ * outline, are cut at a line. See `names.inpage.ts` for what a page-side part may use.
+ */
+import { Schema } from "effect";
+
+import type { Names } from "./names.inpage.ts";
+import type { Walk } from "./walk.inpage.ts";
+
+export interface TextRequest {
+  /** An element to read whole, or null for what the viewport shows. */
+  readonly ref: string | null;
+  readonly maxChars: number;
+  readonly unmask: boolean;
+}
+
+/** What `read` sends back, or null when its ref no longer names an element. */
+export const TextResultSchema = Schema.NullOr(
+  Schema.Struct({
+    text: Schema.String,
+    truncated: Schema.Boolean,
+    url: Schema.String,
+    title: Schema.String,
+  }),
+);
+
+export type TextResult = typeof TextResultSchema.Type;
+
+export const text = (names: Names, walked: Walk) => {
+  const { isHtml, isInput, isSecret, isSelect, isTextArea, lookup } = names;
+
+  // Input types whose value is a label or a choice rather than something entered.
+  const valueless = ["checkbox", "radio", "button", "submit", "reset", "image", "file"];
+
+  /** What a field holds, or undefined for an element that holds nothing entered. */
+  const valueOf = (element: Element): string | undefined => {
+    if (isInput(element)) return valueless.includes(element.type) ? undefined : element.value;
+    if (isTextArea(element)) return element.value;
+    if (isSelect(element))
+      return Array.from(element.selectedOptions, (option) => option.text).join(", ");
+    const parent = element.parentElement;
+
+    // An editable region's own root holds what was typed into it.
+    return isHtml(element) &&
+      element.isContentEditable &&
+      !(parent !== null && isHtml(parent) && parent.isContentEditable)
+      ? element.innerText
+      : undefined;
+  };
+
+  /** What a field shows: `••••` unless `unmask`, and always for a secret field; "" when empty. */
+  const shown = (element: Element, unmask: boolean): string | undefined => {
+    const value = valueOf(element);
+
+    if (value === undefined || value.trim() === "") return value === undefined ? undefined : "";
+
+    return unmask && !isSecret(element) ? value : "••••";
+  };
+
+  /** Lines cut after the last whole line within `max` characters, or at `max` when none is. */
+  const cut = (lines: string, max: number) => {
+    if (lines.length <= max) return { text: lines, truncated: false };
+    const end = lines.lastIndexOf("\n", max);
+
+    return { text: lines.slice(0, end > 0 ? end : max), truncated: true };
+  };
+
+  /**
+   * What the viewport, or one element whole, shows as text: a line per block, table cells apart by
+   * a tab, and each field as `shown` gives it.
+   */
+  const lines = (root: Element | null, unmask: boolean): string => {
+    const lines: Array<string> = [];
+    let line = "";
+
+    const end = () => {
+      const words = line
+        .replace(/[^\S\t]+/g, " ")
+        .replace(/ ?\t ?/g, "\t")
+        .trim();
+
+      if (words !== "") lines.push(words);
+      line = "";
+    };
+
+    walked.visit(root, root === null, false, {
+      enter: (element, style) => {
+        const { display } = style;
+        const value = shown(element, unmask);
+
+        const block =
+          !display.startsWith("inline") && display !== "contents" && display !== "table-cell";
+
+        if (display === "table-cell") line += "\t";
+        if (block || element.tagName === "BR") end();
+        if (value === undefined && !(isInput(element) && valueless.includes(element.type)))
+          return block;
+        // A button's value is its label; a box or a choice shows no text of its own.
+        const label = isInput(element) && /^(button|submit|reset)$/.test(element.type);
+
+        line += ` ${value ?? (label ? element.value : "")} `;
+        if (block) end();
+
+        return undefined;
+      },
+      text: (node) => {
+        line += node.textContent ?? "";
+      },
+      leave: (_, block) => {
+        if (block) end();
+      },
+    });
+    end();
+
+    return lines.join("\n");
+  };
+
+  const read = (request: TextRequest): TextResult => {
+    const root = request.ref === null ? null : lookup(request.ref);
+
+    return root === undefined
+      ? null
+      : {
+          ...cut(lines(root, request.unmask), request.maxChars),
+          url: location.href,
+          title: document.title,
+        };
+  };
+
+  return { cut, lines, read, shown };
+};
+
+export type Texts = ReturnType<typeof text>;

package/src/internal/reading/walk.inpage.ts

@@ -0,0 +1,220 @@
+/**
+ * In the page: the walk every read shares, what is in view and shows, and what is painted at a
+ * point. The walk visits visible elements in tree order, into shadow roots and same-origin frames.
+ * Reading the viewport, it skips a subtree whose box lies outside the viewport before it styles
+ * anything in it, which spares a long table all but its rows in view. A box says nothing of what
+ * is positioned out of it, so a subtree is kept when its box is empty, such as a wrapper of a
+ * pinned dialog, when it holds what is painted at the viewport's edges, corners or middle, under
+ * any transparent layer too, or in its top layer, or when it holds what its style attribute pins
+ * in view. Something a stylesheet pins inside a subtree out of view, away from those points or
+ * ignoring the pointer, is missed. See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { Names } from "./names.inpage.ts";
+
+export interface Visitor<S> {
+  /** The state for the element's children, or undefined to leave them out. */
+  readonly enter: (
+    element: Element,
+    style: CSSStyleDeclaration,
+    rect: DOMRect,
+    state: S,
+  ) => S | undefined;
+  /** Whether to visit a child of an element entered with `state`; all by default. */
+  readonly admit?: ((child: Element, state: S) => boolean) | undefined;
+  /** Each text node of an entered element, in order among its children. */
+  readonly text?: ((node: Node, state: S) => void) | undefined;
+  /** After the children of an element `enter` went into, with the state it returned. */
+  readonly leave?: ((element: Element, state: S) => void) | undefined;
+  /** A subtree left out because its box lies outside the viewport, in top-document pixels. */
+  readonly outside?: ((rect: DOMRect) => void) | undefined;
+}
+
+export const walk = (names: Names) => {
+  const { interactiveRoles, isElement, isFrame, parentOf, roleOf } = names;
+
+  const skipped = new Set("SCRIPT STYLE NOSCRIPT TEMPLATE HEAD META LINK SVG".split(" "));
+
+  /** Whether a box, in top-document pixels, meets the viewport. */
+  const inView = (rect: DOMRect, width = innerWidth, height = innerHeight): boolean =>
+    rect.right > 0 && rect.bottom > 0 && rect.left < width && rect.top < height;
+
+  /** Whether an element reached on its own shows, by the walk's rule and its ancestors'. */
+  const visible = (element: Element): boolean =>
+    element.checkVisibility({ opacityProperty: true, visibilityProperty: true }) &&
+    element.closest("[aria-hidden=true]") === null;
+
+  const isVisible = (element: Element, style: CSSStyleDeclaration, rect: DOMRect): boolean =>
+    style.display !== "none" &&
+    style.visibility === "visible" &&
+    style.opacity !== "0" &&
+    element.getAttribute("aria-hidden") !== "true" &&
+    (rect.width > 0 || rect.height > 0 || style.display === "contents");
+
+  // Coordinate subtraction is valid only for an untransformed frame. Report the frame itself
+  // otherwise: the real pixel input still works, and its receipt must not name a guessed child.
+  const untransformed = (frame: HTMLIFrameElement, rect: DOMRect): boolean => {
+    if (rect.width !== frame.offsetWidth || rect.height !== frame.offsetHeight) return false;
+    let ancestor: Element | null = frame;
+
+    while (ancestor !== null) {
+      const view = ancestor.ownerDocument.defaultView ?? window;
+      const style = view.getComputedStyle(ancestor);
+
+      if (
+        style.transform !== "none" ||
+        style.scale !== "none" ||
+        style.rotate !== "none" ||
+        style.perspective !== "none" ||
+        style.zoom !== "1"
+      )
+        return false;
+      ancestor = parentOf(ancestor);
+    }
+
+    return true;
+  };
+
+  /** The element painted at a point, inside shadow roots and same-origin frames. */
+  const hitAt = (root: Document | ShadowRoot, x: number, y: number): Element | null => {
+    let hit = root.elementFromPoint(x, y);
+
+    while (hit?.shadowRoot !== null && hit?.shadowRoot !== undefined) {
+      const inner = hit.shadowRoot.elementFromPoint(x, y);
+
+      if (inner === null || inner === hit) break;
+      hit = inner;
+    }
+    if (hit !== null && isFrame(hit)) {
+      const document = hit.contentDocument;
+
+      if (document !== null) {
+        const rect = hit.getBoundingClientRect();
+
+        if (untransformed(hit, rect))
+          return (
+            hitAt(document, x - rect.left - hit.clientLeft, y - rect.top - hit.clientTop) ?? hit
+          );
+      }
+    }
+
+    return hit;
+  };
+
+  /** Whether its role or a click handler makes an element a control. */
+  const acts = (element: Element, role: string | null): boolean =>
+    (role !== null && (interactiveRoles.has(role) || role === "canvas" || role === "iframe")) ||
+    element.hasAttribute("onclick");
+
+  // A painted child of a control still activates the control; keep its name without moving the point.
+  const controlOf = (hit: Element): Element => {
+    let element: Element | null = hit;
+
+    while (element !== null) {
+      if (acts(element, roleOf(element))) return element;
+      element = parentOf(element);
+    }
+
+    return hit;
+  };
+
+  /** An element's box in top-document viewport pixels, through the frames around it. */
+  const boxOf = (element: Element): { x: number; y: number; width: number; height: number } => {
+    const { x, y, width, height } = element.getBoundingClientRect();
+    const frame = element.ownerDocument.defaultView?.frameElement ?? null;
+
+    if (frame === null) return { x, y, width, height };
+    const outer = boxOf(frame);
+
+    return { x: x + outer.x + frame.clientLeft, y: y + outer.y + frame.clientTop, width, height };
+  };
+
+  /** What is painted where pinned things sit, what is pinned in view, and every element holding it. */
+  const painted = (width: number, height: number): Set<Element> => {
+    const keep = new Set<Element>();
+
+    const hold = (element: Element | null) => {
+      for (
+        let node = element;
+        node !== null && !keep.has(node);
+        node = parentOf(node) ?? node.ownerDocument.defaultView?.frameElement ?? null
+      )
+        keep.add(node);
+    };
+
+    for (const y of [8, 48, height / 2, height - 48, height - 8])
+      for (const x of [8, 48, width / 4, width / 2, (width * 3) / 4, width - 48, width - 8])
+        if (x >= 0 && y >= 0 && x < width && y < height) {
+          hold(hitAt(document, x, y));
+          // What a transparent layer, such as one over a video player, covers.
+          for (const beneath of document.elementsFromPoint(x, y)) hold(beneath);
+        }
+    for (const element of Array.from(document.querySelectorAll(":modal, :popover-open")))
+      hold(element);
+    // What a style attribute pins, wherever it sits; a stylesheet's pins only at the points.
+    for (const element of Array.from(document.querySelectorAll('[style*="fixed" i]')))
+      if (inView(element.getBoundingClientRect(), width, height)) hold(element);
+
+    return keep;
+  };
+
+  /**
+   * Visit `root` and what it holds, or the whole document when `root` is null. With `viewport`,
+   * a subtree outside the viewport is skipped, as described above.
+   */
+  const visit = <S>(root: Element | null, viewport: boolean, state: S, visitor: Visitor<S>) => {
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    let keep: Set<Element> | undefined;
+
+    const children = (parent: ParentNode, inner: S, dx: number, dy: number) => {
+      // Text nodes are touched only for a visitor that reads them.
+      const nodes = visitor.text === undefined ? parent.children : parent.childNodes;
+
+      for (const node of Array.from<Node>(nodes)) {
+        if (node.nodeType === Node.TEXT_NODE) visitor.text?.(node, inner);
+        else if (isElement(node) && (visitor.admit === undefined || visitor.admit(node, inner)))
+          one(node, inner, dx, dy);
+      }
+    };
+
+    const one = (element: Element, outer: S, dx: number, dy: number): void => {
+      if (skipped.has(element.tagName.toUpperCase())) return;
+      const local = element.getBoundingClientRect();
+      const rect = new DOMRect(local.x + dx, local.y + dy, local.width, local.height);
+
+      if (
+        viewport &&
+        local.width > 0 &&
+        local.height > 0 &&
+        !inView(rect, width, height) &&
+        !(keep ??= painted(width, height)).has(element)
+      ) {
+        visitor.outside?.(rect);
+
+        return;
+      }
+      const style = getComputedStyle(element);
+
+      if (!isVisible(element, style, local)) return;
+      const inner = visitor.enter(element, style, rect, outer);
+
+      if (inner === undefined) return;
+      if (isFrame(element)) {
+        const body = element.contentDocument?.body;
+
+        if (body !== null && body !== undefined) children(body, inner, rect.x, rect.y);
+      } else {
+        if (element.shadowRoot !== null) children(element.shadowRoot, inner, dx, dy);
+        children(element, inner, dx, dy);
+      }
+      visitor.leave?.(element, inner);
+    };
+
+    if (root === null) children(document, state, 0, 0);
+    else one(root, state, 0, 0);
+  };
+
+  return { acts, boxOf, controlOf, hitAt, inView, visible, visit };
+};
+
+export type Walk = ReturnType<typeof walk>;