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

package/src/internal/timeline/changes.ts

@@ -0,0 +1,100 @@
+/**
+ * Reading a page's record of what changed, in one call to the page. The first read also registers
+ * the recorder with the page's own session, in the same round trip, so that every later document
+ * records from its start. The page's times map to the owner's clock through the browser's one
+ * clock mapping, as frames' do, which a browser's first read measures, once, where no capture has;
+ * and a window can begin on the page's own clock where the previous one ended, so consecutive
+ * reads neither miss nor repeat a change. A read takes its turn on the page as other reads do, and
+ * identical ones in flight share it; none is kept for a later caller, since its window ends when
+ * it was read.
+ */
+import { Effect, Schema } from "effect";
+
+import type { BrowserError } from "../../BrowserError.ts";
+import { Change, Changes } from "../../Change.ts";
+import type { Frame } from "../../Frame.ts";
+import type { ChangesOptions } from "../../Page.ts";
+import { type Bridge, scriptCall } from "../page/bridge.ts";
+import { decodeWith, type PageContext } from "../page/context.ts";
+import * as BrowserClock from "../pictures/clock.ts";
+import { type ChangesRequest, ChangesResultSchema } from "./changes.inpage.ts";
+
+const isChanges = Schema.is(Changes);
+
+// Where a window starts or ends as its caller gave it, which tells identical reads apart.
+const markOf = (time: Changes | Frame | number | undefined) =>
+  time === undefined || typeof time === "number"
+    ? time
+    : isChanges(time)
+      ? `cursor ${time.cursor}`
+      : `frame ${time.timestamp ?? time.hostTime}`;
+
+export const make = (
+  page: PageContext,
+  bridge: Bridge,
+  estimate: Effect.Effect<BrowserClock.Estimate, BrowserError>,
+) => {
+  const reads = page.lane.shared<Changes>("changes", false);
+
+  return (options: ChangesOptions = {}) =>
+    reads(
+      JSON.stringify([markOf(options.since), markOf(options.until), options.unmask ?? false]),
+      Effect.gen(function* () {
+        const mapping = yield* estimate;
+        const host = (epoch: number) => BrowserClock.toHostTime(mapping, epoch);
+
+        // A frame's paint is on the page's clock already; a screenshot has only its host time.
+        const onPage = (time: Frame | number) =>
+          typeof time === "number"
+            ? time + mapping.offsetMillis
+            : (time.timestamp ?? time.hostTime + mapping.offsetMillis);
+
+        const request: ChangesRequest = {
+          since:
+            options.since === undefined
+              ? null
+              : isChanges(options.since)
+                ? options.since.cursor
+                : onPage(options.since),
+          until: options.until === undefined ? null : onPage(options.until),
+          unmask: options.unmask ?? false,
+        };
+
+        const [, result] = yield* Effect.all(
+          [
+            bridge.registerRecorder("changes"),
+            bridge
+              .evaluate("changes", scriptCall("changes", request))
+              .pipe(Effect.flatMap(decodeWith("changes", ChangesResultSchema))),
+          ],
+          { concurrency: "unbounded" },
+        );
+
+        yield* Effect.annotateCurrentSpan({
+          changes: result.records.length,
+          dropped: result.dropped,
+        });
+
+        const later = (epoch: number | undefined) =>
+          epoch === undefined ? undefined : host(epoch);
+
+        return new Changes({
+          document: bridge.frameTag().document,
+          from: host(result.from),
+          until: host(result.until),
+          cursor: result.until,
+          dropped: result.dropped,
+          changes: result.records.map(
+            (one) =>
+              new Change({
+                ...one,
+                startedAt: host(one.startedAt),
+                at: host(one.at),
+                earlier: later(one.earlier),
+                cause: later(one.cause),
+              }),
+          ),
+        });
+      }).pipe(page.within("changes")),
+    ).pipe(page.span("Page.changes"), page.owned);
+};

package/src/internal/timeline/events.ts

@@ -0,0 +1,94 @@
+/**
+ * The browser's bounded event history and replay cursors. Readers share the same records and
+ * wakeup generation, so a delayed reader cannot block input or retain an unbounded private queue.
+ */
+import { Cause, Deferred, Effect, Stream } from "effect";
+
+import { type BrowserError, EventHistoryExpired, InvalidRequest } from "../../BrowserError.ts";
+import { type BrowserEvent, RecordedEvent } from "../../BrowserEvent.ts";
+import { undispatched } from "../page/context.ts";
+
+/** The owning Browser validates capacity and closes this timeline with its scope. */
+export const make = (capacity: number) => {
+  let records: ReadonlyArray<RecordedEvent> = [];
+  let sequence = 0;
+  let closed = false;
+  let changed = Deferred.makeUnsafe<void>();
+
+  const wake = () => {
+    const previous = changed;
+
+    changed = Deferred.makeUnsafe<void>();
+    Deferred.doneUnsafe(previous, Effect.void);
+  };
+
+  const publish = (event: BrowserEvent): number => {
+    // Native callbacks may finish after their owning scope. They must not revive closed readers.
+    if (closed) return sequence;
+    sequence += 1;
+    const recorded = new RecordedEvent({ sequence, event });
+
+    records = records.length < capacity ? [...records, recorded] : [...records.slice(1), recorded];
+    wake();
+
+    return sequence;
+  };
+
+  const stream = (after?: number): Stream.Stream<RecordedEvent, BrowserError> =>
+    Stream.unwrap(
+      Effect.sync(() => {
+        // This runs for each subscription, rather than when the reusable stream is constructed.
+        let cursor = after ?? sequence;
+
+        if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > sequence)
+          return Stream.fail(
+            undispatched(
+              "events",
+              new InvalidRequest({
+                detail:
+                  "the event cursor must be a nonnegative integer no greater than the latest sequence",
+              }),
+            ),
+          );
+
+        return Stream.fromEffectRepeat(
+          Effect.gen(function* () {
+            while (true) {
+              const oldest = records[0]?.sequence ?? sequence + 1;
+
+              if (cursor < oldest - 1)
+                return yield* undispatched(
+                  "events",
+                  new EventHistoryExpired({ after: cursor, oldest, latest: sequence }),
+                );
+              const next = records[cursor - oldest + 1];
+
+              if (next !== undefined) {
+                cursor = next.sequence;
+
+                return next;
+              }
+              if (closed) return yield* Cause.done();
+              // Capture the generation in the same synchronous read as the empty history check.
+              // A publish before await completes this exact Deferred, so no wakeup can be missed.
+              const waiting = changed;
+
+              yield* Deferred.await(waiting);
+            }
+          }),
+        );
+      }),
+    );
+
+  return {
+    publish,
+    sequence: () => sequence,
+    recent: Effect.sync(() => records),
+    stream,
+    close: Effect.sync(() => {
+      if (closed) return;
+      closed = true;
+      wake();
+    }),
+  };
+};

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

@@ -0,0 +1,123 @@
+/**
+ * In the page: one element's history in the change record, and its fold over a window. A fold gives
+ * what the element showed at the window's start and at its end, how often that changed between,
+ * the lowest and highest of a number that changed more than once, and when it last changed before
+ * the window. Only what was seen in view as it changed is told. It touches no DOM, so it also runs
+ * outside a page. See `names.inpage.ts` for what a page-side part may use.
+ */
+
+/** What an element shows: its words, `null` while it shows nothing, `undefined` until judged. */
+export type Shown = string | null | undefined;
+
+export interface Sample {
+  readonly at: number;
+  shown: Shown;
+  /** Whether it was in view as the page rendered it; undefined until then. */
+  seen: boolean | undefined;
+}
+
+/** One element's history, oldest change first. */
+export interface Track {
+  key: object;
+  readonly kind: "content" | "value" | "title";
+  /** What it showed before its oldest kept change; undefined when that is unknown. */
+  initial: Shown;
+  /** Before this, the record let some of its changes go. */
+  known: number;
+  readonly samples: Array<Sample>;
+}
+
+export type Kind = "text" | "appeared" | "disappeared" | "brief" | "value" | "title";
+
+/** One element's changes over a window, before the page names the element. */
+export interface Folded {
+  readonly track: Track;
+  readonly kind: Kind;
+  readonly startedAt: number;
+  readonly at: number;
+  readonly before: string | undefined;
+  readonly after: string | undefined;
+  readonly count: number;
+  readonly lowest: string | undefined;
+  readonly highest: string | undefined;
+  readonly earlier: number | undefined;
+}
+
+export const fold = () => {
+  /** The one number some words show, such as 61240 in "$61,240"; none for none or several. */
+  const number = (words: string): ReadonlyArray<number> => {
+    const found = words.match(/[-+−]?\d[\d,]*(?:\.\d+)?/g);
+
+    const value = Number(
+      found?.length === 1 ? found[0]?.replaceAll(",", "").replace("−", "-") : "",
+    );
+
+    return found?.length === 1 && Number.isFinite(value) ? [value] : [];
+  };
+
+  /** A track's changes after `since`, up to `until`, if one was seen in view. */
+  const over = (track: Track, since: number, until: number): Folded | undefined => {
+    const inside = track.samples.filter((sample) => sample.at > since && sample.at <= until);
+    const first = inside[0];
+    const last = inside.at(-1);
+
+    if (first === undefined || last === undefined || !inside.some((sample) => sample.seen === true))
+      return undefined;
+    const prior = track.samples[track.samples.indexOf(first) - 1];
+    // What it showed at `since` is lost when the record let go of changes after it.
+    const lost = track.known <= since ? track.known : undefined;
+
+    const start =
+      prior === undefined ? (lost === undefined ? undefined : track.initial) : prior.shown;
+
+    const words = [start, ...inside.map((sample) => sample.shown)].filter(
+      (each) => typeof each === "string",
+    );
+
+    const numbers = words.flatMap(number);
+    const ranged = inside.length > 1 && numbers.length === words.length;
+
+    const kind: Kind =
+      track.kind !== "content"
+        ? track.kind
+        : last.shown === null
+          ? start === null
+            ? "brief"
+            : "disappeared"
+          : start === null
+            ? "appeared"
+            : "text";
+
+    return {
+      track,
+      kind,
+      startedAt: first.at,
+      at: last.at,
+      before: kind === "disappeared" ? words.at(-1) : (start ?? undefined),
+      after: kind === "brief" ? words.at(-1) : (last.shown ?? undefined),
+      count: inside.length,
+      lowest: ranged ? words[numbers.indexOf(Math.min(...numbers))] : undefined,
+      highest: ranged ? words[numbers.indexOf(Math.max(...numbers))] : undefined,
+      earlier: prior?.at ?? (lost === Number.NEGATIVE_INFINITY ? undefined : lost),
+    };
+  };
+
+  /**
+   * How readily a track gives way when the record is full: one that holds no change first, then
+   * one that keeps changing, one never seen in view and one that has gone; news never does.
+   */
+  const rank = ({ samples: [only, ...more] }: Track): number =>
+    only === undefined
+      ? 4
+      : more.length > 0
+        ? 3
+        : only.seen === false
+          ? 2
+          : only.shown === null
+            ? 1
+            : 0;
+
+  return { number, over, rank };
+};
+
+export type Fold = ReturnType<typeof fold>;

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

@@ -0,0 +1,229 @@
+/**
+ * In the page: a document's record of what changed, element by element, within fixed bounds. It
+ * touches no DOM, so it also runs outside a page.
+ *
+ * - **A change** is a new state: other words, or presence gained or lost. Within one batch of
+ *   mutations the latest state stands, so an element moved in one step has not changed.
+ * - **Bounds.** 256 elements, each with its latest 32 changes, kept a minute. On a busier page an
+ *   element that keeps changing gives way first, then one never seen in view, then one that has
+ *   gone, so news stays. What gives way, and what finds no room, is counted, and the record says it
+ *   is whole only after the latest such loss.
+ *
+ * Each element's history is folded over a window by `fold.inpage.ts`. See `names.inpage.ts` for
+ * what a page-side part may use.
+ */
+import type { Fold, Sample, Shown, Track } from "./fold.inpage.ts";
+
+/** How much the record keeps: elements, changes of each, and for how long. */
+export interface Bounds {
+  readonly tracks: number;
+  readonly samples: number;
+  readonly retention: number;
+}
+
+export const history = (
+  folding: Fold,
+  bounds: Bounds = { tracks: 256, samples: 32, retention: 60_000 },
+) => {
+  const { tracks: maxTracks, samples: maxSamples, retention } = bounds;
+  const tracks = new Map<object, Track>();
+  // Keys that gave way or found no room: their later changes are counted, not kept.
+  let refused = new WeakSet<object>();
+  // When the record let changes go, and how many, and the latest such time; keys whose tracks went.
+  let losses: Array<[number, number]> = [];
+  let lastLoss = Number.NEGATIVE_INFINITY;
+  const gone: Array<object> = [];
+  let begun: number | undefined;
+
+  // Losses at one time count together. Beyond 256 times the first noted go, so a count falls short
+  // rather than over.
+  const lose = (at: number, count: number) => {
+    const last = losses.at(-1);
+
+    if (count <= 0) return;
+    lastLoss = Math.max(lastLoss, at);
+    if (last?.[0] === at) last[1] += count;
+    else losses.push([at, count]);
+    if (losses.length > 256) losses.shift();
+  };
+
+  const latest = (track: Track) => track.samples.at(-1)?.at ?? Number.NEGATIVE_INFINITY;
+
+  const drop = (track: Track) => {
+    tracks.delete(track.key);
+    gone.push(track.key);
+  };
+
+  // How often the tracks' samples have changed, and when a search found none to give way, which
+  // holds until they change again, so a burst of newcomers pays for one search.
+  let version = 0;
+  let barren = -1;
+
+  /** What gives way for a newcomer: one that holds no change, then one that keeps changing. */
+  const victim = (): Track | undefined => {
+    let chosen: Track | undefined;
+    let rank = 0;
+
+    for (const track of barren === version ? [] : tracks.values()) {
+      const next = folding.rank(track);
+
+      if (next > rank) [chosen, rank] = [track, next];
+      if (rank === 4) break;
+    }
+    if (chosen === undefined) barren = version;
+
+    return chosen;
+  };
+
+  const evict = (track: Track) => {
+    drop(track);
+    if (track.samples.length > 0) refused.add(track.key);
+    for (const sample of track.samples) lose(sample.at, 1);
+  };
+
+  /** A key the record cannot keep: its change is counted. */
+  const refuse = (key: object, at: number): undefined => {
+    refused.add(key);
+    lose(at, 1);
+
+    return undefined;
+  };
+
+  /**
+   * A new state for `key` at `at`: its sample, or none when it is no change or finds no room.
+   * `initial` says what a key not yet kept showed before.
+   */
+  const note = (
+    key: object,
+    kind: Track["kind"],
+    at: number,
+    shown: Shown,
+    initial: () => Shown,
+  ): Sample | undefined => {
+    let track = tracks.get(key);
+
+    if (track === undefined) {
+      const full = !refused.has(key) && tracks.size >= maxTracks;
+      const out = full ? victim() : undefined;
+
+      if (refused.has(key) || (full && out === undefined)) return refuse(key, at);
+      const before = initial();
+
+      if (shown !== undefined && shown === before) return undefined;
+      if (out !== undefined) evict(out);
+      track = { key, kind, initial: before, known: Number.NEGATIVE_INFINITY, samples: [] };
+      tracks.set(key, track);
+    }
+    const { samples } = track;
+
+    version++;
+
+    if (samples.at(-1)?.at === at) samples.pop();
+    const previous = samples.length === 0 ? track.initial : samples.at(-1)?.shown;
+
+    if (shown !== undefined && shown === previous) return undefined;
+    const oldest = samples.length >= maxSamples ? samples.shift() : undefined;
+
+    if (oldest !== undefined) {
+      track.initial = oldest.shown;
+      track.known = oldest.at;
+      lose(oldest.at, 1);
+    }
+    const sample: Sample = { at, shown, seen: undefined };
+
+    samples.push(sample);
+
+    return sample;
+  };
+
+  /** Judge a sample as the page rendered it; a state that repeats the one before is no change. */
+  const settle = (key: object, sample: Sample, shown: Shown, seen: boolean) => {
+    const track = tracks.get(key);
+
+    // `null` is a state, what shows nothing, so only `undefined` is unjudged.
+    version++;
+    if (sample.shown === undefined) sample.shown = shown;
+    if (sample.seen === undefined) sample.seen = seen;
+    if (track === undefined) return;
+    let previous = track.initial;
+
+    const changes = track.samples.filter((each) => {
+      const same = each.shown !== undefined && each.shown === previous;
+
+      if (!same) previous = each.shown;
+
+      return !same;
+    });
+
+    track.samples.splice(0, track.samples.length, ...changes);
+  };
+
+  /**
+   * The window after `since`, up to `until`: where the record is whole, how many changes in it the
+   * record let go, and each element's changes, oldest first by when they began.
+   */
+  const read = (since: number, until: number, now: number) => {
+    for (const track of tracks.values()) if (latest(track) < now - retention) drop(track);
+
+    return {
+      from: Math.min(until, Math.max(begun ?? now, now - retention, lastLoss)),
+      dropped: losses.reduce(
+        (sum, [at, count]) => (at > since && at <= until ? sum + count : sum),
+        0,
+      ),
+      folded: [...tracks.values()]
+        .flatMap((track) => folding.over(track, since, until) ?? [])
+        .toSorted((left, right) => left.startedAt - right.startedAt),
+    };
+  };
+
+  /** When something in view last changed, or something not yet judged; for a wait for stillness. */
+  const changing = (): number =>
+    Math.max(
+      Number.NEGATIVE_INFINITY,
+      ...Array.from(
+        tracks.values(),
+        (track) =>
+          track.samples.findLast((sample) => sample.seen !== false)?.at ?? Number.NEGATIVE_INFINITY,
+      ),
+    );
+
+  return {
+    begin: (at: number) => {
+      begun = at;
+    },
+    begun: () => begun !== undefined,
+    clear: () => {
+      for (const track of tracks.values()) drop(track);
+      refused = new WeakSet();
+      losses = [];
+      lastLoss = Number.NEGATIVE_INFINITY;
+      begun = undefined;
+    },
+    changing,
+    /** Keys whose tracks went since this was last asked, for the recorder to stop watching. */
+    forgotten: (): ReadonlyArray<object> => gone.splice(0),
+    has: (key: object) => tracks.has(key),
+    /** Whether the record has let `key` go: its later changes are counted, never kept. */
+    refuses: (key: object) => refused.has(key),
+    lose,
+    note,
+    read,
+    /** Each element's history, and when the record let changes go, for a read to judge causes. */
+    recent: () => ({ tracks: [...tracks.values()], losses: losses.map(([at]) => at) }),
+    /** A track moves to the element that took its key's place, as a re-rendered price does. */
+    rekey: (from: object, to: object): boolean => {
+      const track = tracks.get(from);
+
+      if (track === undefined || tracks.has(to)) return false;
+      tracks.delete(from);
+      track.key = to;
+      tracks.set(to, track);
+
+      return true;
+    },
+    settle,
+  };
+};
+
+export type History = ReturnType<typeof history>;