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

package/src/internal/pictures/transport.ts

@@ -0,0 +1,242 @@
+/**
+ * Where a page's screencast runs: on the page's own session, or on a capture connection that the
+ * provider supplies, where frames and their acknowledgements never wait behind a large message on
+ * the connection that drives the page. There the page's session attaches as its first capture
+ * starts, with the Page domain on, and stays until the page closes or the session ends; the next
+ * capture then attaches again.
+ *
+ * Frames take their document from the commits their own session reports, in the order the browser
+ * sent them, so a frame never shows a document after the one it carries, as on the page's own
+ * session. They are numbered as the page's own session counts documents: a commit it has counted
+ * keeps its number, and one the capture connection sees first takes the next, until it is counted.
+ */
+import { Effect, Exit, Option, Schema, Scope } from "effect";
+
+import type { CaptureSource } from "../../Browser.ts";
+import { type BrowserError, Failed } from "../../BrowserError.ts";
+import { type Bridge, Commit, commitOf, mainFrame, MainFrameEvent } from "../page/bridge.ts";
+import { type PageContext, undispatched } from "../page/context.ts";
+
+/** Where a capture's screencast runs. Its calls never throw: a failure rejects. */
+export interface Transport {
+  readonly start: (settings: {
+    readonly format: "jpeg";
+    readonly quality: number;
+    readonly maxWidth?: number;
+    readonly maxHeight?: number;
+  }) => Promise<unknown>;
+  readonly acknowledge: (frame: number) => Promise<unknown>;
+  readonly stop: () => Promise<unknown>;
+  /**
+   * A round trip whose answer comes behind every frame sent before it. On the page's own session,
+   * the page's own calls are such round trips already, so it sends nothing.
+   */
+  readonly sync: () => Promise<unknown>;
+  /**
+   * Hand its frames to `on.frame` as they arrive, and its end to `on.lost` should it end, until
+   * the returned function is called.
+   */
+  readonly listen: (on: {
+    readonly frame: (frame: NativeFrame) => void;
+    readonly lost: (error: BrowserError) => void;
+  }) => () => void;
+  /** What a frame arriving now shows: its session, the document it followed and the address then. */
+  readonly frameTag: () => {
+    readonly session: string;
+    readonly document: number;
+    readonly url: string;
+  };
+}
+
+/** The page's own session. */
+export const own = (page: PageContext, bridge: Bridge): Transport => {
+  const { send } = page.protocol;
+
+  return {
+    start: (settings) => send("Page.startScreencast", settings),
+    acknowledge: (frame) => send("Page.screencastFrameAck", { sessionId: frame }),
+    stop: () => send("Page.stopScreencast"),
+    sync: () => Promise.resolve(),
+    listen: ({ frame }) => {
+      page.cdp.on("Page.screencastFrame", frame);
+
+      return () => {
+        page.cdp.off("Page.screencastFrame", frame);
+      };
+    },
+    frameTag: bridge.frameTag,
+  };
+};
+
+const FrameTree = Schema.Struct({ frameTree: Schema.Struct({ frame: Commit }) });
+
+/** A native screencast frame, as Chromium sends it. */
+const ScreencastFrame = Schema.Struct({
+  data: Schema.String,
+  sessionId: Schema.Int,
+  metadata: Schema.Struct({
+    timestamp: Schema.optionalKey(Schema.Finite),
+    deviceWidth: Schema.Finite,
+    deviceHeight: Schema.Finite,
+  }),
+});
+
+export type NativeFrame = typeof ScreencastFrame.Type;
+
+/**
+ * The document and address a capture connection's frames show, from the commits its session
+ * reports after `first`, the main frame's document as the session began.
+ */
+const documents = (bridge: Bridge, first: ReturnType<typeof commitOf>) => {
+  // The number the page's own session gave the latest commit of `loader`, if it has counted one.
+  const counted = (loader: string) => bridge.documentOf(loader) ?? -1;
+  const latest = bridge.frameTag().document;
+
+  // A loader the page's own session hasn't counted began the document it had from the start, or
+  // a commit still on its way to it.
+  const shown = {
+    ...first,
+    document: counted(first.loader) >= 0 ? counted(first.loader) : latest === 0 ? 0 : latest + 1,
+  };
+
+  return {
+    /** A commit or a move the session reported, in the order the browser sent them. */
+    see: (seen: ReturnType<typeof mainFrame>) => {
+      if (seen?.loader !== undefined) {
+        shown.document = Math.max(shown.document + 1, counted(seen.loader));
+        shown.loader = seen.loader;
+      }
+      if (seen !== undefined) shown.url = seen.url;
+    },
+    tag: () => {
+      shown.document = Math.max(shown.document, counted(shown.loader));
+
+      return { document: shown.document, url: shown.url };
+    },
+  };
+};
+
+type State =
+  | { readonly _tag: "Detached" }
+  | { readonly _tag: "Attaching"; readonly scope: Scope.Closeable }
+  | { readonly _tag: "Attached"; readonly scope: Scope.Closeable; readonly transport: Transport }
+  | { readonly _tag: "Ended"; readonly scope: Scope.Closeable; readonly error: BrowserError };
+
+/**
+ * The page's session on the capture connection, attached when a capture asks for it and kept for
+ * the page's scope. Its state changes only here: attaching, attached, or ended by the session's
+ * end, which also ends the capture listening to it.
+ */
+export const apart = (
+  page: PageContext,
+  bridge: Bridge,
+  source: CaptureSource,
+  error: (cause: unknown) => BrowserError,
+  pageScope: Scope.Scope,
+): Effect.Effect<Transport, BrowserError> => {
+  let state: State = { _tag: "Detached" };
+  let listening: Parameters<Transport["listen"]>[0] | undefined;
+  const latest = (): State => state;
+
+  const end = (scope: Scope.Closeable, ended: BrowserError) => {
+    if ((state._tag !== "Attaching" && state._tag !== "Attached") || state.scope !== scope) return;
+    const attached = state._tag === "Attached";
+
+    state = { _tag: "Ended", scope, error: ended };
+    if (attached) listening?.lost(ended);
+  };
+
+  const unreadable = undispatched(
+    "screencast",
+    new Failed({ detail: "the capture connection sent an event it could not read" }),
+  );
+
+  const attach = (scope: Scope.Closeable) =>
+    Effect.gen(function* () {
+      let shown: ReturnType<typeof documents> | undefined;
+
+      // Commits before the frame tree's answer are in it already.
+      const event = (method: string, params: unknown) => {
+        const decoded = <A>(schema: Schema.Codec<A, unknown>, act: (value: A) => void) =>
+          Option.match(Schema.decodeUnknownOption(schema)(params), {
+            onNone: () => end(scope, unreadable),
+            onSome: act,
+          });
+
+        if (method === "Page.screencastFrame")
+          decoded(ScreencastFrame, (frame: NativeFrame) => listening?.frame(frame));
+        else if (method === "Page.frameNavigated" || method === "Page.navigatedWithinDocument")
+          decoded(MainFrameEvent, (event) => shown?.see(mainFrame(page.id, event)));
+        else if (method === "Target.detachedFromTarget")
+          end(scope, error(new Error("Target page has been closed")));
+      };
+
+      const send = yield* source.attach(page.id, { event, lost: (lost) => end(scope, lost) });
+
+      // Tracked from the frame tree's answer on, set as it arrives so that no commit after it is
+      // missed.
+      const tracked = yield* Effect.tryPromise({
+        try: () =>
+          Promise.all([send("Page.enable"), send("Page.getFrameTree")]).then(([, tree]) =>
+            Option.match(Schema.decodeUnknownOption(FrameTree)(tree), {
+              onNone: () => Promise.reject(unreadable),
+              onSome: ({ frameTree }) => (shown = documents(bridge, commitOf(frameTree.frame))),
+            }),
+          ),
+        catch: error,
+      });
+
+      return {
+        start: (settings) => send("Page.startScreencast", settings),
+        acknowledge: (frame) => send("Page.screencastFrameAck", { sessionId: frame }),
+        stop: () => send("Page.stopScreencast"),
+        sync: () => send("Page.getFrameTree"),
+        listen: (on) => {
+          listening = on;
+
+          return () => {
+            if (listening === on) listening = undefined;
+          };
+        },
+        frameTag: () => ({ session: page.session, ...tracked.tag() }),
+      } satisfies Transport;
+    }).pipe(Scope.provide(scope));
+
+  const current: Effect.Effect<Transport, BrowserError> = Effect.suspend(() => {
+    switch (state._tag) {
+      case "Attached":
+        return Effect.succeed(state.transport);
+      case "Ended": {
+        const { scope } = state;
+
+        state = { _tag: "Detached" };
+
+        return Scope.close(scope, Exit.void).pipe(Effect.andThen(current));
+      }
+      case "Detached":
+      case "Attaching":
+        return Effect.gen(function* () {
+          const scope = yield* Scope.fork(pageScope);
+
+          state = { _tag: "Attaching", scope };
+          const attached = yield* Effect.exit(attach(scope).pipe(page.within("screencast")));
+          // `end` may have changed it meanwhile.
+          const settled = latest();
+
+          // A session that ended as it attached is never handed out.
+          if (Exit.isSuccess(attached) && settled._tag === "Attaching" && settled.scope === scope) {
+            state = { _tag: "Attached", scope, transport: attached.value };
+
+            return attached.value;
+          }
+          state = { _tag: "Detached" };
+          yield* Scope.close(scope, Exit.void);
+          if (Exit.isFailure(attached)) return yield* attached;
+
+          return yield* settled._tag === "Ended" ? settled.error : unreadable;
+        });
+    }
+  });
+
+  return current;
+};

package/src/internal/reading/choose.ts

@@ -0,0 +1,100 @@
+/**
+ * Choosing the one element a recorded subject names, among those `find` gives for its role and
+ * name. Context tells them apart, and an element that does not repeat every part of the recorded
+ * context is another subject, so a sole element left once its own has gone, such as Alice's
+ * "Remove" after Bob has left, drifts rather than stands in:
+ *
+ * - a row is read whole: a row named "Wrapped BTC" is not the row "BTC". Laid out again without
+ *   rows, as cards, one of the element's fields must start with the row's words;
+ * - a column counts where the element is under one;
+ * - a label or heading must read the same, or its words appear, whole and in order, in one of the
+ *   element's fields, as `near` reads them.
+ *
+ * The rest are ranked by how much of the recorded context they read the same. There is no
+ * ordinal, so a tie stays a tie.
+ */
+import { Effect, Schema } from "effect";
+
+import type { Subject, SubjectContext } from "../../BrowserEvent.ts";
+import type { Found } from "../../Page.ts";
+import { match } from "./match.inpage.ts";
+
+/** Nothing on the page has the step's role and name. */
+export class Missing extends Schema.TaggedError<Missing>()("Missing", {}) {
+  override get message() {
+    return "nothing on the page has the recorded role and name";
+  }
+}
+
+/** Several elements match the step's subject equally well, and nothing tells them apart. */
+export class Ambiguous extends Schema.TaggedError<Ambiguous>()("Ambiguous", {
+  count: Schema.Int,
+}) {
+  override get message() {
+    return `${this.count} elements match the recorded subject equally well`;
+  }
+}
+
+/** The page is not where the recording was: another site, or no element with its context. */
+export class Drifted extends Schema.TaggedError<Drifted>()("Drifted", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+const { holds, normalize } = match();
+const fields = ["row", "column", "label", "heading"] as const;
+
+const said = (context: SubjectContext) =>
+  Object.values(context).filter((value) => typeof value === "string");
+
+/** How an element repeats one recorded field: 2 read the same, 1 found as words, 0 not at all. */
+const repeats = (field: (typeof fields)[number], value: string, context: SubjectContext) => {
+  const own = context[field];
+
+  if (own !== undefined && normalize(own) === normalize(value)) return 2;
+  if (field === "column") return own === undefined ? 1 : 0;
+  if (field === "row")
+    return own === undefined &&
+      said(context).some((other) => `${normalize(other)} `.startsWith(`${normalize(value)} `))
+      ? 1
+      : 0;
+
+  return said(context).some((other) => holds(other, value)) ? 1 : 0;
+};
+
+export const choose = (
+  subject: Subject,
+  found: ReadonlyArray<Found>,
+): Effect.Effect<Found, Missing | Ambiguous | Drifted> => {
+  // `find` matched the role; a subject without one only matches elements without one.
+  const named = found.filter((one) => subject.role !== null || one.subject.role === null);
+
+  const kept = named.flatMap((one) => {
+    let score = 0;
+
+    for (const field of fields) {
+      const value = subject.context[field];
+      const repeated = value === undefined ? 0 : repeats(field, value, one.subject.context);
+
+      if (value !== undefined && repeated === 0) return [];
+      score += repeated;
+    }
+
+    return [{ one, score }];
+  });
+
+  const best = Math.max(...kept.map(({ score }) => score));
+  const top = kept.filter(({ score }) => score === best);
+  const [only] = top;
+
+  if (named.length === 0) return Effect.fail(new Missing());
+  if (kept.length === 0)
+    return Effect.fail(new Drifted({ detail: "no element named so repeats the recorded context" }));
+
+  return top.length === 1 && only !== undefined
+    ? Effect.succeed(only.one)
+    : Effect.fail(new Ambiguous({ count: top.length }));
+};

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

@@ -0,0 +1,201 @@
+/**
+ * In the page: an element's context, the words around it that say which one it is:
+ *
+ * - in a table, its row, named by the row's header or else its first cell with letters, so a rank
+ *   or a price never names it, and its column, named by the header over it, so a value is never
+ *   read under the wrong header;
+ * - elsewhere, the words just before it in its row, item, group or block;
+ * - the heading above it, unless it is pinned to the viewport, where the markup says nothing.
+ *
+ * See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { SubjectContext } from "../../BrowserEvent.ts";
+import type { Names } from "./names.inpage.ts";
+import type { Walk } from "./walk.inpage.ts";
+
+/** What one read has learnt of the page: each table's header row and each tree's headings. */
+export interface Known {
+  readonly headers: Map<Element, Element | null>;
+  readonly headings: Map<Node, ReadonlyArray<Element>>;
+}
+
+export const context = (names: Names, walked: Walk) => {
+  const { clean, isButton, isDocument, isHtml, isInput, isRoot } = names;
+  const { isSelect, isTextArea, roleOf, textOf } = names;
+  const { visible } = walked;
+
+  const known = (): Known => ({ headers: new Map(), headings: new Map() });
+
+  // Text in these says what a control is called, not what the page says around it.
+  const unspoken =
+    "button,select,textarea,option,script,style,noscript,template,[role=button],[role=menuitem],[role=option],[role=tab],[role=switch],[role=checkbox],[role=radio],[aria-hidden=true]";
+
+  // Containers whose text usually describes the controls in them: a row, an item, a group or a form.
+  const groups =
+    "tr,li,article,fieldset,form,section,dialog,[role=row],[role=listitem],[role=group],[role=region],[role=dialog],[role=alertdialog]";
+
+  /** The visible text just before (or after) a target within `scope`, nearest kept, ≤120 characters. */
+  const textBeside = (target: Element, scope: Node, backwards: boolean): string => {
+    const walker = target.ownerDocument.createTreeWalker(scope, NodeFilter.SHOW_TEXT);
+
+    const labels =
+      isInput(target) || isTextArea(target) || isSelect(target) || isButton(target)
+        ? Array.from(target.labels ?? [])
+        : [];
+
+    let text = "";
+
+    walker.currentNode = target;
+    for (let steps = 0; steps < 400 && text.replace(/\s+/g, "").length < 120; steps++) {
+      const node = backwards ? walker.previousNode() : walker.nextNode();
+
+      if (node === null) break;
+      const parent = node.parentElement;
+
+      if (
+        parent === null ||
+        target.contains(parent) ||
+        parent.closest(unspoken) !== null ||
+        (isHtml(parent) && parent.isContentEditable) ||
+        labels.some((label) => label.contains(parent)) ||
+        !visible(parent)
+      )
+        continue;
+      text = backwards ? `${node.textContent ?? ""} ${text}` : `${text} ${node.textContent ?? ""}`;
+    }
+    const words = text.replace(/\s+/g, " ").trim();
+
+    return words.length <= 120
+      ? words
+      : backwards
+        ? `…${words.slice(-119).trimStart()}`
+        : `${words.slice(0, 119).trimEnd()}…`;
+  };
+
+  /** The nearest visible heading before `target` in tree order, within `scope`. */
+  const headingBefore = (
+    target: Element,
+    scope: ParentNode,
+    read = known(),
+  ): string | undefined => {
+    let headings = read.headings.get(scope);
+
+    if (headings === undefined) {
+      headings = Array.from(scope.querySelectorAll("h1,h2,h3,h4,h5,h6,[role=heading]")).filter(
+        (element) => roleOf(element) === "heading",
+      );
+      read.headings.set(scope, headings);
+    }
+    // Headings are in tree order, so the nearest before the target is the last one before it.
+    for (const heading of headings.toReversed()) {
+      if ((heading.compareDocumentPosition(target) & Node.DOCUMENT_POSITION_FOLLOWING) === 0)
+        continue;
+      const text = visible(heading) ? clean(textOf(heading), 120) : "";
+
+      if (text !== "") return text;
+    }
+
+    return undefined;
+  };
+
+  /** Whether an element is pinned to the viewport, where the markup around it says nothing. */
+  const pinned = (element: Element): boolean => {
+    if (!isHtml(element)) return false;
+    let top: HTMLElement = element;
+
+    while (top.offsetParent !== null && isHtml(top.offsetParent)) top = top.offsetParent;
+
+    return (
+      top !== element.ownerDocument.body &&
+      top !== element.ownerDocument.documentElement &&
+      getComputedStyle(top).position === "fixed"
+    );
+  };
+
+  const span = (cell: Element): number => Math.max(1, Number(cell.getAttribute("colspan")) || 1);
+  const tables = "table,[role=table],[role=grid],[role=treegrid]";
+
+  /** A cell's row and column names, or nothing when it is not in a table with either. */
+  const tableContext = (cell: Element, read: Known): SubjectContext => {
+    const row = cell.closest("tr,[role=row]");
+    const table = row?.closest(tables);
+
+    if (row === null || row === undefined || table === null || table === undefined) return {};
+    let header = read.headers.get(table);
+
+    if (header === undefined) {
+      const first = table.querySelector(
+        "thead tr, tr:has(> th), [role=row]:has(> [role=columnheader])",
+      );
+
+      header = first?.closest(tables) === table ? first : null;
+      read.headers.set(table, header);
+    }
+    if (row === header) return {};
+    const cells = Array.from(row.children);
+    const index = cells.indexOf(cell);
+    // A rank, a checkbox, a star or a price says where a row is, not which one it is.
+    const lettered = (other: Element) => /\p{L}/u.test(textOf(other));
+
+    const named =
+      cells.find((other) => other.matches("th,[role=rowheader]") && lettered(other)) ??
+      cells.find((other) => other !== cell && lettered(other));
+
+    // Columns count spanned cells, so a cell after one spanning two is under the third header.
+    let left = cells.slice(0, index).reduce((sum, other) => sum + span(other), 0);
+
+    const over =
+      index === -1 || header === null
+        ? undefined
+        : Array.from(header.children).find((candidate) => (left -= span(candidate)) < 0);
+
+    return {
+      row:
+        named === undefined || named === cell ? undefined : clean(textOf(named), 60) || undefined,
+      column: over === undefined ? undefined : clean(textOf(over), 60) || undefined,
+    };
+  };
+
+  /** Where text around an element is read: its dialog, else its own tree, never across a shadow root. */
+  const treeOf = (element: Element): ParentNode => {
+    const root = element.getRootNode();
+
+    return (
+      element.closest("dialog,[role=dialog],[role=alertdialog]") ??
+      (isDocument(root) ? (root.body ?? root) : isRoot(root) ? root : element.ownerDocument)
+    );
+  };
+
+  /** The words around an element that say which one it is. */
+  const contextOf = (element: Element, read = known()): SubjectContext => {
+    const cell = element.closest(
+      "td,th,[role=cell],[role=gridcell],[role=rowheader],[role=columnheader]",
+    );
+
+    const table = cell === null ? {} : tableContext(cell, read);
+    const parent = element.parentElement;
+
+    const scope =
+      element.closest(groups) ??
+      (parent === null || parent === element.ownerDocument.body || parent.tagName === "HTML"
+        ? undefined
+        : parent);
+
+    const beside =
+      table.row !== undefined || table.column !== undefined || scope === undefined
+        ? ""
+        : textBeside(element, scope, true);
+
+    const heading = pinned(element) ? undefined : headingBefore(element, treeOf(element), read);
+
+    return {
+      ...table,
+      label: beside.length > 40 ? `…${beside.slice(-39).trimStart()}` : beside || undefined,
+      heading: heading === undefined ? undefined : clean(heading, 60),
+    };
+  };
+
+  return { contextOf, groups, headingBefore, known, textBeside, treeOf };
+};
+
+export type ContextReader = ReturnType<typeof context>;