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

package/src/internal/timeline/marks.inpage.ts

@@ -0,0 +1,207 @@
+/**
+ * In the page: what one batch of mutations changed, marked for the record as cheaply as it can be.
+ *
+ * - **An element whose own text changed.** One that holds only text, as most prices and labels do,
+ *   is read whole at once, since that text is all it shows, and the batch is undone to say what it
+ *   said before; any other is read as it renders. Once followed, a text-only element's changes are
+ *   taken as its text's, with no look at the nodes that came and went.
+ * - **An element added** is read as it renders; one that moved in the same batch did not arrive.
+ *   What came with text its parent gained is part of the parent's change, and what takes a removed
+ *   element's place, as a re-rendered price does, takes its history. **An element removed** is
+ *   noted only if the record follows it, so a removal it never saw is not told.
+ * - **`hidden`, `open`, `aria-hidden`, `class` or `style`** may show or hide an element. The old
+ *   value says whether it was hidden before, except for a class, where only the element's state as
+ *   the record last saw it can: what it follows, what alerts, status lines, dialogs and popovers
+ *   showed when it started, and what an earlier class change showed. A style that neither hid it
+ *   nor hides it, such as a transform, shows nothing new.
+ * - **The document's title.**
+ *
+ * See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { Names } from "../reading/names.inpage.ts";
+import type { Shown } from "./fold.inpage.ts";
+import type { History } from "./history.inpage.ts";
+import type { Sight } from "./sight.inpage.ts";
+
+interface Batch {
+  readonly at: number;
+  readonly owners: Set<Element>;
+  readonly arrived: Set<Node>;
+  readonly left: Set<Node>;
+}
+
+export const marks = (names: Names, kept: History, seeing: Sight) => {
+  const { clean, isElement, isHtml } = names;
+  const unwritten = new Set("SCRIPT STYLE NOSCRIPT TEMPLATE TITLE".split(" "));
+  const hiding = /display\s*:\s*none|visibility\s*:\s*hidden|opacity\s*:\s*0(?![.\d])/i;
+  // Where removed elements were, which gives their context, and the title as last seen.
+  let places = new WeakMap<object, Element>();
+  let title = "";
+
+  const words = (text: string | null | undefined): Shown => clean(text, 200) || null;
+
+  const content = (element: Element, at: number, shown: Shown, initial: () => Shown) => {
+    const sample = kept.note(element, "content", at, shown, initial);
+
+    if (sample !== undefined) seeing.look(element, sample);
+  };
+
+  /** What a text-only element said before this batch: its text with the batch undone. */
+  const before = (leaf: Element, records: ReadonlyArray<MutationRecord>): Shown => {
+    let nodes: Array<Node> = Array.from(leaf.childNodes);
+    const old = new Map<Node, string>();
+
+    for (const record of records.toReversed())
+      if (record.type === "characterData") old.set(record.target, record.oldValue ?? "");
+      else {
+        const added = new Set(Array.from(record.addedNodes));
+
+        nodes = nodes.filter((node) => !added.has(node));
+        const next = record.nextSibling === null ? -1 : nodes.indexOf(record.nextSibling);
+
+        nodes.splice(next === -1 ? nodes.length : next, 0, ...Array.from(record.removedNodes));
+      }
+
+    return words(nodes.map((node) => old.get(node) ?? node.textContent).join(""));
+  };
+
+  const attribute = (
+    element: Element,
+    { attributeName: name, oldValue: old }: MutationRecord,
+    at: number,
+  ) => {
+    // Whether the old value hid it; a class can say only through the page's style.
+    const was =
+      name === "hidden"
+        ? old !== null
+        : name === "aria-hidden"
+          ? old === "true"
+          : name === "open"
+            ? element.tagName === "DIALOG" && old === null
+            : name === "style" && hiding.test(old ?? "");
+
+    if (name === "style" && !was && !hiding.test(element.getAttribute("style") ?? "")) return;
+    const state = seeing.state(element);
+
+    if (!kept.has(element) && !was && state === undefined && name !== "open")
+      return seeing.glance(element);
+    content(element, at, undefined, () =>
+      was || state === false
+        ? null
+        : name === "open" && old === null
+          ? words(element.querySelector(":scope > summary")?.textContent)
+          : words(element.textContent),
+    );
+  };
+
+  /** What one mutation added to and removed from `target`. */
+  const nodes = (change: MutationRecord, target: Element, batch: Batch) => {
+    const added = Array.from(change.addedNodes).slice(0, 64);
+    const removed = Array.from(change.removedNodes).slice(0, 64);
+
+    const text = [...added, ...removed].some(
+      (node) => !isElement(node) && /\S/.test(node.textContent ?? ""),
+    );
+
+    kept.lose(batch.at, Math.max(change.addedNodes.length, change.removedNodes.length) - 64);
+    if (text) batch.owners.add(target);
+    removed.forEach((gone, index) => {
+      const node = added[index];
+
+      if (!isElement(gone)) return;
+      batch.left.add(gone);
+      if (node !== undefined && isElement(node) && kept.rekey(gone, node)) seeing.unwatch(gone);
+      else if (kept.has(gone)) {
+        places.set(gone, target);
+        const sample = kept.note(gone, "content", batch.at, null, () => undefined);
+
+        if (sample !== undefined) sample.seen = seeing.viewed(gone);
+        seeing.unwatch(gone);
+      }
+    });
+    for (const node of added)
+      if (
+        isElement(node) &&
+        isHtml(node) &&
+        !unwritten.has(node.tagName) &&
+        !node.isContentEditable
+      )
+        if (kept.has(node) || (!text && !batch.left.has(node))) {
+          batch.arrived.add(node);
+          content(node, batch.at, undefined, () => null);
+        }
+  };
+
+  /** Whether `element` is inside something this batch added, which tells it with its own words. */
+  const inside = (element: Element, arrived: ReadonlySet<Node>): boolean => {
+    for (let up = element.parentElement; arrived.size > 0 && up !== null; up = up.parentElement)
+      if (arrived.has(up)) return true;
+
+    return false;
+  };
+
+  const ownerOf = (change: MutationRecord): Node | null =>
+    change.type === "characterData" ? change.target.parentElement : change.target;
+
+  /** Mark what one batch of mutations changed, at `at`. */
+  const mark = (records: ReadonlyArray<MutationRecord>, at: number) => {
+    const batch: Batch = { at, owners: new Set(), arrived: new Set(), left: new Set() };
+    let byOwner: Map<Node | null, Array<MutationRecord>> | undefined;
+
+    for (const change of records) {
+      const target = ownerOf(change);
+
+      if (target === null || !isElement(target) || inside(target, batch.arrived)) continue;
+      // A text-only element the record follows, or has let go, changes only its text, as a
+      // ticking price does, so its nodes need no look: each would cost this world a wrapper.
+      const known = kept.has(target) || kept.refuses(target);
+
+      if (change.type !== "attributes")
+        if (change.type === "characterData" || (target.childElementCount === 0 && known))
+          batch.owners.add(target);
+        else nodes(change, target, batch);
+      else if (isHtml(target) && target !== document.body && target !== document.documentElement)
+        attribute(target, change, at);
+    }
+    for (const owner of batch.owners) {
+      const leaf = owner.childElementCount === 0;
+
+      // What the record let go is counted, with no word of it read.
+      if (kept.refuses(owner)) kept.lose(at, 1);
+      if (kept.refuses(owner) || !isHtml(owner) || unwritten.has(owner.tagName)) continue;
+      // What is typed into an editable region is a field's value, told masked as one.
+      if (owner === document.body || owner.isContentEditable) continue;
+      if (batch.arrived.has(owner) || inside(owner, batch.arrived)) continue;
+      content(owner, at, leaf ? words(owner.textContent) : undefined, () => {
+        byOwner ??= Map.groupBy(records, ownerOf);
+
+        return leaf ? before(owner, byOwner.get(owner) ?? []) : undefined;
+      });
+    }
+    if (document.title === title) return;
+    const previous = words(title);
+
+    const sample = kept.note(
+      document,
+      "title",
+      at,
+      words((title = document.title)),
+      () => previous,
+    );
+
+    if (sample !== undefined) sample.seen = true;
+  };
+
+  return {
+    mark,
+    /** Where a removed element was, which gives its context. */
+    placeOf: (key: object): Element | undefined => places.get(key),
+    /** Start afresh, from the document's title now. */
+    reset: () => {
+      places = new WeakMap();
+      title = document.title;
+    },
+  };
+};
+
+export type Marks = ReturnType<typeof marks>;

package/src/internal/timeline/record.inpage.ts

@@ -0,0 +1,133 @@
+/**
+ * In the page: the change recorder. It starts at a read of the page's changes, and from then on at
+ * the start of each document the page loads, once that document is parsed; it stops in a document
+ * nobody has read for two minutes. While it runs, a MutationObserver hands each batch to
+ * `marks.inpage.ts`, and an IntersectionObserver judges as the page renders whether what was marked
+ * was in view (`sight.inpage.ts`). A field reports its value as it is edited, a secret one only as
+ * `••••`, and trusted pointer and key input is kept, for a read to name causes by. Nothing unmarked
+ * is read: no walk, no words, no layout. See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { Names } from "../reading/names.inpage.ts";
+import type { Texts } from "../reading/text.inpage.ts";
+import type { History } from "./history.inpage.ts";
+import type { Marks } from "./marks.inpage.ts";
+import type { Sight } from "./sight.inpage.ts";
+
+export const record = (
+  names: Names,
+  texts: Texts,
+  kept: History,
+  seeing: Sight,
+  marking: Marks,
+) => {
+  const { isElement, isInput } = names;
+  const epoch = () => performance.timeOrigin + performance.now();
+
+  const declared =
+    "[role=alert],[role=status],[role=log],[role=dialog],[role=alertdialog],[aria-live],dialog,[popover]";
+
+  let running = false;
+  let lastRead = 0;
+  // What fields held as they took focus, and the latest trusted input, newest last.
+  let focused = new WeakMap<Element, string>();
+  const inputs: Array<{ readonly at: number; readonly target: Element }> = [];
+
+  const targetOf = (event: Event): Element | undefined => {
+    const target = event.composedPath()[0];
+
+    return target instanceof Node && isElement(target) ? target : undefined;
+  };
+
+  /** A field's value as the record keeps it: a secret one's as `••••`, a box's checked or not. */
+  const valueOf = (field: Element): string | undefined =>
+    isInput(field) && (field.type === "checkbox" || field.type === "radio")
+      ? field.checked
+        ? "checked"
+        : "not checked"
+      : texts.shown(field, true);
+
+  const onFocus = (event: Event) => {
+    const field = targetOf(event);
+    const value = field === undefined ? undefined : valueOf(field);
+
+    if (field !== undefined && value !== undefined) focused.set(field, value);
+  };
+
+  const onValue = (event: Event) => {
+    const field = targetOf(event);
+    const value = field === undefined ? undefined : valueOf(field);
+
+    if (field === undefined || value === undefined) return;
+    const sample = kept.note(field, "value", epoch(), value, () => focused.get(field) ?? null);
+
+    if (sample !== undefined) seeing.look(field, sample);
+  };
+
+  const onInput = (event: Event) => {
+    const target = targetOf(event);
+
+    if (!event.isTrusted || target === undefined) return;
+    inputs.push({ at: performance.timeOrigin + event.timeStamp, target });
+    if (inputs.length > 8) inputs.shift();
+  };
+
+  const listeners = [
+    ["focusin", onFocus],
+    ["input", onValue],
+    ["change", onValue],
+    ["pointerdown", onInput],
+    ["keydown", onInput],
+  ] as const;
+
+  const options = { capture: true, passive: true };
+
+  const stop = () => {
+    running = false;
+    observer.disconnect();
+    for (const [type, listener] of listeners) document.removeEventListener(type, listener, options);
+    seeing.clear();
+    kept.clear();
+    kept.forgotten();
+    inputs.length = 0;
+    focused = new WeakMap();
+  };
+
+  const observer = new MutationObserver((records) => {
+    const at = epoch();
+
+    if (at - lastRead > 120_000) stop();
+    else marking.mark(records, at);
+  });
+
+  const begin = () => {
+    if (!running || kept.begun()) return;
+    observer.observe(document, {
+      subtree: true,
+      childList: true,
+      characterData: true,
+      characterDataOldValue: true,
+      attributeFilter: ["hidden", "open", "aria-hidden", "class", "style"],
+      attributeOldValue: true,
+    });
+    for (const [type, listener] of listeners) document.addEventListener(type, listener, options);
+    marking.reset();
+    for (const element of Array.from(document.querySelectorAll(declared)).slice(0, 64))
+      seeing.glance(element, true);
+    kept.begin(epoch());
+  };
+
+  return {
+    /** Record from now, once the document is parsed; each read keeps the record going. */
+    start: () => {
+      lastRead = epoch();
+      if (running) return;
+      running = true;
+      if (document.readyState === "loading")
+        document.addEventListener("DOMContentLoaded", begin, { once: true });
+      else begin();
+    },
+    inputs: (): ReadonlyArray<{ readonly at: number; readonly target: Element }> => inputs,
+  };
+};
+
+export type Recorder = ReturnType<typeof record>;

package/src/internal/timeline/sight.inpage.ts

@@ -0,0 +1,122 @@
+/**
+ * In the page: whether what the recorder marked was in view, and what it showed, judged as the page
+ * renders it. An IntersectionObserver watches each element the record follows: it reports as the
+ * page renders, forces no layout, and leaves a removed element the state it last reported. What
+ * changed counts as seen when it was in the viewport and its style showed it; what went counts as
+ * seen when it was in view before it went. Words that need the page's layout are read on render
+ * too, as `text` reads an element, by the walk's one rule for what shows and with fields masked.
+ * An element whose state alone the record wants, as for a class change on something it does not
+ * follow, is looked at once. See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { Names } from "../reading/names.inpage.ts";
+import type { Texts } from "../reading/text.inpage.ts";
+import type { Walk } from "../reading/walk.inpage.ts";
+import type { Sample, Shown } from "./fold.inpage.ts";
+import type { History } from "./history.inpage.ts";
+
+export const sight = (names: Names, walked: Walk, texts: Texts, kept: History) => {
+  const { clean } = names;
+  const { visible } = walked;
+  // Whether each watched element was in view as the page last rendered it, and whether the style
+  // of one looked at once showed it.
+  let viewed = new WeakMap<Element, boolean>();
+  let watching = new WeakSet<Element>();
+  let states = new WeakMap<Element, boolean>();
+  const waiting = new Map<Element, Array<Sample>>();
+
+  /** What an element shows: its words, if its style shows it. */
+  const shownBy = (element: Element): Shown =>
+    element.isConnected && visible(element)
+      ? clean(texts.lines(element, false), 200) || null
+      : null;
+
+  /** Settle what waited on an element; its words are read once, if one of them needs them. */
+  const judge = (element: Element, pending: ReadonlyArray<Sample>, seen: boolean, was: boolean) => {
+    const shown = pending.some((sample) => sample.shown === undefined)
+      ? shownBy(element)
+      : undefined;
+
+    for (const sample of pending) {
+      const now = sample.shown === undefined ? shown : sample.shown;
+
+      kept.settle(element, sample, now, now === null ? was : seen);
+    }
+  };
+
+  const observer = new IntersectionObserver((entries) => {
+    for (const { target, isIntersecting } of entries) {
+      const was = viewed.get(target) ?? false;
+      const seen = isIntersecting && visible(target);
+      const pending = waiting.get(target);
+
+      viewed.set(target, seen);
+      waiting.delete(target);
+      if (pending !== undefined) judge(target, pending, seen, was);
+      if (!kept.has(target)) {
+        states.set(target, visible(target));
+        unwatch(target);
+      }
+    }
+  });
+
+  /** Watch an element, asking for a fresh report even if it is watched already. */
+  const watch = (element: Element) => {
+    watching.add(element);
+    observer.unobserve(element);
+    observer.observe(element);
+  };
+
+  const unwatch = (element: Element) => {
+    watching.delete(element);
+    observer.unobserve(element);
+  };
+
+  return {
+    /** Judge a sample at once if what it shows and whether it is in view are known, else on render. */
+    look: (element: Element, sample: Sample) => {
+      const view = viewed.get(element);
+
+      if (sample.shown !== undefined && view !== undefined && watching.has(element)) {
+        sample.seen = view;
+
+        return;
+      }
+      waiting.set(element, [...(waiting.get(element) ?? []), sample]);
+      watch(element);
+    },
+    /**
+     * Look at an element once, for its state when it next changes: as it renders, or `now`, by its
+     * style, as for the few the record looks at as it starts.
+     */
+    glance: (element: Element, now = false) => {
+      if (now) states.set(element, visible(element));
+      if (!watching.has(element)) watch(element);
+    },
+    /** Whether the style of an element looked at once showed it, if it was. */
+    state: (element: Element): boolean | undefined => states.get(element),
+    /** Whether a watched element was in view as the page last rendered it. */
+    viewed: (element: Element): boolean => viewed.get(element) ?? false,
+    unwatch,
+    /** Judge now what the page has not rendered since it changed, as a hidden tab never does. */
+    settle: () => {
+      for (const [element, pending] of waiting) {
+        const seen =
+          element.isConnected && walked.inView(element.getBoundingClientRect()) && visible(element);
+
+        judge(element, pending, seen, viewed.get(element) ?? false);
+        viewed.set(element, seen);
+      }
+      waiting.clear();
+      for (const key of kept.forgotten()) if (key instanceof Element) unwatch(key);
+    },
+    clear: () => {
+      observer.disconnect();
+      waiting.clear();
+      viewed = new WeakMap();
+      watching = new WeakSet();
+      states = new WeakMap();
+    },
+  };
+};
+
+export type Sight = ReturnType<typeof sight>;

package/src/internal/timeline/window.ts

@@ -0,0 +1,96 @@
+/**
+ * A page's window over its three tracks on the browser's host clock: the events and frames it
+ * keeps, at no call, and one read of its changes, the first starting its record. A read that fails
+ * is missing, with why, and the window is still made.
+ */
+import { Duration, Effect, Option, Result, Schema } from "effect";
+
+import { type BrowserError, InvalidRequest } from "../../BrowserError.ts";
+import { type BrowserEvent, TrackEvent } from "../../BrowserEvent.ts";
+import type { Changes } from "../../Change.ts";
+import { Frame } from "../../Frame.ts";
+import { Window } from "../../Moment.ts";
+import type { ChangesOptions, WindowOptions } from "../../Page.ts";
+import { failWith, type PageContext } from "../page/context.ts";
+
+const isWindow = Schema.is(Window);
+const isFrame = Schema.is(Frame);
+const isTrackEvent = Schema.is(TrackEvent);
+
+/**
+ * Where a window asked at `now` starts and ends: never after now, nor starting after it ends.
+ * Nothing for a bound that is not finite, or a negative reach back.
+ */
+export const boundsOf = ({ since, until }: Pick<WindowOptions, "since" | "until">, now: number) => {
+  const end = until === undefined ? now : isFrame(until) ? until.hostTime : Math.min(until, now);
+
+  const start = isWindow(since)
+    ? since.until
+    : isFrame(since)
+      ? since.hostTime
+      : !Duration.isDuration(since)
+        ? since
+        : Duration.isNegative(since)
+          ? Number.NaN
+          : end - Duration.toMillis(since);
+
+  return Number.isFinite(start) && Number.isFinite(end)
+    ? Option.some({ since: Math.min(start, end), until: end })
+    : Option.none();
+};
+
+/**
+ * A window's share of the kept tracks: events after its start, frames painted from it, both up to
+ * its end, so consecutive windows hold each event once and the next begins with the frame the last
+ * ended on. Pointer, key and wheel input is the presentation track, not an event here.
+ */
+export const within = (
+  { since, until }: { readonly since: number; readonly until: number },
+  events: ReadonlyArray<BrowserEvent>,
+  frames: ReadonlyArray<Frame>,
+) => ({
+  events: events.filter((event) => event.at > since && event.at <= until && !isTrackEvent(event)),
+  frames: frames.filter((frame) => frame.hostTime >= since && frame.hostTime <= until),
+});
+
+export const make =
+  (
+    page: PageContext,
+    read: (options: ChangesOptions) => Effect.Effect<Changes, BrowserError>,
+    frames: Effect.Effect<ReadonlyArray<Frame>>,
+  ) =>
+  ({ since, until, unmask }: WindowOptions) =>
+    Effect.gen(function* () {
+      const asked = boundsOf({ since, until }, page.now());
+
+      if (Option.isNone(asked))
+        return yield* failWith(
+          "window",
+          new InvalidRequest({
+            detail: "a window's bounds must be finite, its reach not negative",
+          }),
+        );
+      const bounds = asked.value;
+
+      // A previous window's changes go on exactly where they ended, on the page's own clock, and a
+      // frame bounds them at its paint, so that they hold nothing it does not show.
+      const changes = yield* Effect.result(
+        read({
+          since: isWindow(since)
+            ? (since.changes ?? bounds.since)
+            : isFrame(since)
+              ? since
+              : bounds.since,
+          until: isFrame(until) ? until : bounds.until,
+          unmask,
+        }),
+      );
+
+      return new Window({
+        page: page.id,
+        ...bounds,
+        ...within(bounds, yield* page.recentEvents, yield* frames),
+        changes: Result.getOrUndefined(changes),
+        missing: Option.toArray(Result.getFailure(changes)),
+      });
+    }).pipe(page.span("Page.window"), page.owned);

package/src/internal/timeline/words.ts

@@ -0,0 +1,65 @@
+/**
+ * What changed on a page, in words for a model: a change with where it is, and what it is. A moment
+ * tells its changes this way, and a tool's receipt the changes its action caused.
+ */
+import type { Subject, SubjectContext } from "../../BrowserEvent.ts";
+import type { Change } from "../../Change.ts";
+
+export const quoted = (value: string | undefined) => JSON.stringify(value ?? "");
+
+/** A subject in words, such as `button "Play"`; one without a name says where it was. */
+export const named = (subject: Subject, point: string | undefined) => {
+  const kind = subject.role ?? subject.tag;
+
+  if (subject.name !== "") return `${kind} ${JSON.stringify(subject.name)}`;
+
+  return point === undefined ? kind : `${kind} at ${point}`;
+};
+
+/** A change's context in words: `row "Ether", column "1h"` or `beside "Price", under "Bitcoin"`. */
+export const where = ({ row, column, label, heading }: SubjectContext, grouped = false) => {
+  const parts = [
+    row === undefined ? "" : `row ${quoted(row)}`,
+    column === undefined || grouped ? "" : `column ${quoted(column)}`,
+    label === undefined ? "" : `beside ${quoted(label)}`,
+    heading === undefined || grouped ? "" : `under ${quoted(heading)}`,
+  ].filter((part) => part !== "");
+
+  return parts.length === 0 ? "" : ` (${parts.join(", ")})`;
+};
+
+/** A change in words, such as `"$61,240" became "$62,010" (row "Bitcoin", column "Price")`. */
+export const describe = (change: Change, grouped = false): string => {
+  const { subject, before, after, count, lowest, highest } = change;
+  const context = where(subject.context, grouped);
+
+  const range =
+    lowest === undefined || highest === undefined ? "" : `, from ${lowest} to ${highest}`;
+
+  const times = count > 1 ? ` (it changed ${count} times${range})` : "";
+
+  switch (change.kind) {
+    case "title":
+      return `the title ${before === undefined ? "now reads" : `${quoted(before)} became`} ${quoted(after)}`;
+    case "value": {
+      const field = named(subject, undefined);
+
+      if (after === "checked" || after === "not checked") return `${field} is now ${after}`;
+      if (after === undefined || after === "") return `${field} was cleared`;
+
+      return after === "••••" || before === undefined || before === ""
+        ? `${field} was ${after === "••••" ? "edited" : `set to ${quoted(after)}`}`
+        : `${field} changed from ${quoted(before)} to ${quoted(after)}`;
+    }
+    case "appeared":
+      return `${quoted(after)} appeared${context}`;
+    case "disappeared":
+      return `${quoted(before)} disappeared${context}`;
+    case "brief":
+      return `${quoted(after)} appeared and went away again${context}`;
+    case "text":
+      return before === undefined
+        ? `now reads ${quoted(after)}${context}${times}`
+        : `${quoted(before)} became ${quoted(after)}${context}${times}`;
+  }
+};