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

package/src/internal/supervisor/lifecycle.ts

@@ -0,0 +1,265 @@
+/**
+ * A supervisor's life as one state and one transition function, and the generation states it
+ * publishes. The transition has no effects: `Supervisor.make` applies each input under one lock,
+ * publishes the events in order and runs the commands, so the rules here are tested alone.
+ */
+import { Schema } from "effect";
+
+import { DisconnectCause } from "../../BrowserEvent.ts";
+
+/** The provider confirmed that the generation's browser ended. */
+export class Settled extends Schema.TaggedClass<Settled>()("Settled", {}) {}
+
+/** The provider could not confirm the end by its deadline, so the browser may still run, and bill. */
+export class Unconfirmed extends Schema.TaggedClass<Unconfirmed>()("Unconfirmed", {
+  detail: Schema.String,
+}) {}
+
+export const Released = Schema.Union([Settled, Unconfirmed]);
+
+export type Released = typeof Released.Type;
+
+/** Opening, but not after a loss: the first generation, a rotation, or the one after `Down`. */
+export class Opening extends Schema.TaggedClass<Opening>()("Opening", {}) {}
+
+/** Opening after the generation before it was lost. */
+export class Reopening extends Schema.TaggedClass<Reopening>()("Reopening", {}) {}
+
+/** Open: `browser` gives this generation until the next one opens. */
+export class Open extends Schema.TaggedClass<Open>()("Open", {}) {}
+
+/** Lost: its connection dropped, or its provider ended its session, as `cause` says. */
+export class Lost extends Schema.TaggedClass<Lost>()("Lost", {
+  cause: DisconnectCause,
+}) {}
+
+/**
+ * It never opened: its last try failed with `cause`, which the provider deems definite, or after
+ * which the reopen schedule gave up.
+ */
+export class Down extends Schema.TaggedClass<Down>()("Down", {
+  detail: Schema.String,
+  cause: Schema.Defect(),
+}) {}
+
+/** It ended. `released` says how its release went; one retired while opening has none. */
+export class Closed extends Schema.TaggedClass<Closed>()("Closed", {
+  released: Schema.optional(Released),
+}) {}
+
+/**
+ * It was serving as the supervisor's scope closed, and was left running, not released: its scope
+ * closed, and its provider runs it on, and bills, until something adopts and releases it.
+ */
+export class Kept extends Schema.TaggedClass<Kept>()("Kept", {}) {}
+
+export const GenerationState = Schema.Union([Opening, Reopening, Open, Lost, Down, Closed, Kept]);
+
+export type GenerationState = typeof GenerationState.Type;
+
+/** A generation that opened: its number, and what the runtime keeps to serve and end it. */
+export interface Live<A> {
+  readonly number: number;
+  readonly value: A;
+}
+
+/**
+ * At most one generation opens and at most one serves. Both do while a rotation makes the next
+ * before it breaks the current, and `Down` keeps serving one that a rotation failed to replace.
+ */
+export type State<A> =
+  | { readonly _tag: "Opening"; readonly number: number; readonly serving: Live<A> | undefined }
+  | { readonly _tag: "Open"; readonly serving: Live<A> }
+  | {
+      readonly _tag: "Down";
+      readonly number: number;
+      readonly detail: string;
+      readonly cause: unknown;
+      readonly serving: Live<A> | undefined;
+    }
+  | { readonly _tag: "Retired" };
+
+export type Input<A> =
+  | { readonly _tag: "Opened"; readonly live: Live<A> }
+  /** The open of `number` failed for good. */
+  | {
+      readonly _tag: "Failed";
+      readonly number: number;
+      readonly detail: string;
+      readonly cause: unknown;
+    }
+  /** The open of `number` was stopped, as on retiring, before it opened. */
+  | { readonly _tag: "Abandoned"; readonly number: number }
+  | { readonly _tag: "Lost"; readonly number: number; readonly cause: DisconnectCause }
+  /** A caller asks for the next generation, or the rotation time of `due` came. */
+  | { readonly _tag: "Rotate"; readonly due?: number | undefined }
+  | { readonly _tag: "Retire" }
+  /** Stop as `Retire` does, but leave the serving generation running. */
+  | { readonly _tag: "Keep" }
+  | { readonly _tag: "Released"; readonly number: number; readonly released: Released };
+
+export type Command<A> =
+  /** Open `number`, after the release of `after` has finished. */
+  | { readonly _tag: "Open"; readonly number: number; readonly after: number | undefined }
+  /** Watch a generation that opened for its loss and its rotation time. */
+  | { readonly _tag: "Watch"; readonly live: Live<A> }
+  | { readonly _tag: "Release"; readonly live: Live<A> }
+  /** Close its scope without asking its provider to release it. */
+  | { readonly _tag: "Leave"; readonly live: Live<A> };
+
+export interface Step<A> {
+  readonly state: State<A>;
+  /** Generation numbers and their new states, to publish in this order. */
+  readonly events: ReadonlyArray<readonly [number, GenerationState]>;
+  readonly commands: ReadonlyArray<Command<A>>;
+  /** For `Rotate`, the generation to wait for, unless retired. */
+  readonly reply?: number | undefined;
+}
+
+export const start = <A>(): Step<A> => ({
+  state: { _tag: "Opening", number: 1, serving: undefined },
+  events: [[1, new Opening()]],
+  commands: [{ _tag: "Open", number: 1, after: undefined }],
+});
+
+const servingOf = <A>(state: State<A>) => (state._tag === "Retired" ? undefined : state.serving);
+
+/** The state after `input`, with the events to publish and the commands to run. */
+export const transition = <A>(state: State<A>, input: Input<A>, exclusive: boolean): Step<A> => {
+  const release = (live: Live<A>): Command<A> => ({ _tag: "Release", live });
+  const stay: Step<A> = { state, events: [], commands: [] };
+
+  /**
+   * Open `number`, ending `current` now if it `ends`; exclusive generations open only once its
+   * release has finished. Otherwise `current` serves until the next one opens.
+   */
+  const next = (
+    number: number,
+    reopen: boolean,
+    current: Live<A> | undefined,
+    ends: boolean,
+  ): Step<A> => ({
+    state: { _tag: "Opening", number, serving: ends ? undefined : current },
+    events: [[number, reopen ? new Reopening() : new Opening()]],
+    commands: [
+      ...(ends && current !== undefined ? [release(current)] : []),
+      { _tag: "Open", number, after: ends && exclusive ? current?.number : undefined },
+    ],
+  });
+
+  switch (input._tag) {
+    case "Opened": {
+      const { live } = input;
+
+      // A generation nobody waits for any more, as after `Retire`, is released at once.
+      if (state._tag !== "Opening" || state.number !== live.number)
+        return { ...stay, commands: [release(live)] };
+
+      return {
+        state: { _tag: "Open", serving: live },
+        events: [[live.number, new Open()]],
+        commands: [
+          { _tag: "Watch", live },
+          ...(state.serving === undefined ? [] : [release(state.serving)]),
+        ],
+      };
+    }
+    case "Failed": {
+      const { number, detail, cause } = input;
+      const events = [[number, new Down({ detail, cause })] as const];
+
+      if (state._tag !== "Opening" || state.number !== input.number) return { ...stay, events };
+
+      return {
+        state: { _tag: "Down", number, detail, cause, serving: state.serving },
+        events,
+        commands: [],
+      };
+    }
+    case "Abandoned":
+      return { ...stay, events: [[input.number, new Closed({})]] };
+    case "Released":
+      return { ...stay, events: [[input.number, new Closed({ released: input.released })]] };
+    case "Lost": {
+      const lost = servingOf(state);
+
+      if (state._tag === "Retired" || lost?.number !== input.number) return stay;
+      const events = [[lost.number, new Lost({ cause: input.cause })] as const];
+
+      // A rotation already opening the next generation carries on without the lost one.
+      if (state._tag === "Opening")
+        return { state: { ...state, serving: undefined }, events, commands: [release(lost)] };
+
+      const reopened = next(
+        (state._tag === "Open" ? lost.number : state.number) + 1,
+        true,
+        lost,
+        true,
+      );
+
+      return { ...reopened, events: [...events, ...reopened.events] };
+    }
+    case "Rotate": {
+      if (state._tag === "Retired") return stay;
+      // A rotation time comes only for the generation still serving with nothing opening.
+      if (input.due !== undefined && (state._tag !== "Open" || state.serving.number !== input.due))
+        return stay;
+      if (state._tag === "Opening") return { ...stay, reply: state.number };
+      const number = (state._tag === "Open" ? state.serving.number : state.number) + 1;
+
+      return { ...next(number, false, state.serving, exclusive), reply: number };
+    }
+    case "Retire":
+    case "Keep": {
+      const current = servingOf(state);
+
+      if (state._tag === "Retired") return stay;
+      if (current === undefined) return { state: { _tag: "Retired" }, events: [], commands: [] };
+
+      return input._tag === "Retire"
+        ? { state: { _tag: "Retired" }, events: [], commands: [release(current)] }
+        : {
+            state: { _tag: "Retired" },
+            events: [[current.number, new Kept()]],
+            commands: [{ _tag: "Leave", live: current }],
+          };
+    }
+  }
+};
+
+export type Resolution<A> =
+  | { readonly _tag: "Serve"; readonly live: Live<A> }
+  | {
+      readonly _tag: "Unavailable";
+      readonly reason: "down" | "retired";
+      readonly detail: string;
+      readonly cause?: unknown;
+    };
+
+/**
+ * What a caller waiting for generation `target`, or for any when it is undefined, gets in
+ * `state`; undefined while it should go on waiting.
+ */
+export const resolve = <A>(
+  state: State<A>,
+  target: number | undefined,
+): Resolution<A> | undefined => {
+  const serve = (live: Live<A>) => ({ _tag: "Serve" as const, live });
+
+  switch (state._tag) {
+    case "Retired":
+      return { _tag: "Unavailable", reason: "retired", detail: "the supervisor was retired" };
+    case "Open":
+      return target === undefined || state.serving.number >= target
+        ? serve(state.serving)
+        : undefined;
+    case "Opening":
+      return target === undefined && state.serving !== undefined ? serve(state.serving) : undefined;
+    case "Down":
+      if (target === undefined && state.serving !== undefined) return serve(state.serving);
+
+      return target === undefined || state.number >= target
+        ? { _tag: "Unavailable", reason: "down", detail: state.detail, cause: state.cause }
+        : undefined;
+  }
+};

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

@@ -0,0 +1,216 @@
+/**
+ * In the page: what changed after `since`, up to `until`, as a read returns it. A read starts the
+ * record if it has not, and keeps it going. What waited for the page to render is judged first, as
+ * it stands; then each element's history is folded over the window (`history.inpage.ts`), and only
+ * now named: its role, its name when something else names it, its tag, and its context, where it
+ * is or, for what was removed, where it was. A field's value reads `••••` unless the read unmasks
+ * it, and a secret field's always does. A change names the input it followed only where it was
+ * the input's own doing, by `Change.cause`'s rule. See `names.inpage.ts` for what a page-side part
+ * may use.
+ */
+import { Schema } from "effect";
+
+import { Change } from "../../Change.ts";
+import type { Known, ContextReader } from "../reading/context.inpage.ts";
+import type { Names } from "../reading/names.inpage.ts";
+import type { Folded } from "./fold.inpage.ts";
+import type { History } from "./history.inpage.ts";
+import type { Marks } from "./marks.inpage.ts";
+import type { Recorder } from "./record.inpage.ts";
+import type { Sight } from "./sight.inpage.ts";
+
+/** A window on the page's own clock: epoch milliseconds, or the record's start and now. */
+export interface ChangesRequest {
+  readonly since: number | null;
+  readonly until: number | null;
+  readonly unmask: boolean;
+}
+
+/**
+ * What a read sends back: its window and the record's state, and each change as `Change` encodes
+ * it, all on the page's clock.
+ */
+export const ChangesResultSchema = Schema.Struct({
+  until: Schema.Finite,
+  from: Schema.Finite,
+  dropped: Schema.Int,
+  records: Schema.Array(Change),
+});
+
+export type ChangesResult = typeof ChangesResultSchema.Encoded;
+
+export const changes = (
+  names: Names,
+  placing: ContextReader,
+  kept: History,
+  seeing: Sight,
+  marking: Marks,
+  recorder: Recorder,
+) => {
+  const { clean, isInput, roleOf, nameOf } = names;
+  const groups = "tr,[role=row],form,dialog,[role=dialog],[role=alertdialog]";
+
+  /** Whether `element` lies in what an input on `target` acted on, its group, or what it controls. */
+  const local = (target: Element, element: Element): boolean => {
+    const controls = target.closest("[aria-controls]")?.getAttribute("aria-controls") ?? "";
+    const group = target.closest(groups);
+
+    return (
+      target.contains(element) ||
+      group?.contains(element) === true ||
+      controls
+        .split(/\s+/)
+        .some((id) => id !== "" && document.getElementById(id)?.contains(element) === true)
+    );
+  };
+
+  /** What an element sits in, or sat in as it went. */
+  const parentOf = (key: object): Element | null =>
+    key instanceof Element
+      ? key.isConnected
+        ? key.parentElement
+        : (marking.placeOf(key) ?? null)
+      : null;
+
+  // What changed in the 10 s before an input is in flux at it, and a change in the 2 s before says
+  // the page was not still.
+  const fluxMillis = 10_000;
+  const stillMillis = 2000;
+
+  /**
+   * Each input a change may follow, with what the page did before it: what changed in the 10 s
+   * before, the parents that gained or lost a child then, and whether nothing changed, and nothing
+   * was let go, in the 2 s before. What holds the input's target, as a menu holds its item, came
+   * with it, so it counts only as changing itself.
+   */
+  const before = () => {
+    const inputs = recorder.inputs();
+
+    if (inputs.length === 0) return [];
+    const { tracks, losses } = kept.recent();
+
+    return inputs.map(({ at, target }) => {
+      const changed = new Set<object>();
+      const moved = new Set<Element | null>();
+      let still = losses.every((lost) => lost >= at || lost < at - stillMillis);
+
+      for (const { key, kind, initial, samples } of tracks) {
+        // Whether each change in the 10 s before came or went: it, or what it followed, showed
+        // nothing. A field's own edits are the input's, not the page's.
+        const prior = samples.flatMap(({ at: when, shown }, index) =>
+          kind === "value" || when >= at || when < at - fluxMillis
+            ? []
+            : [shown === null || (index === 0 ? initial : samples[index - 1]?.shown) === null],
+        );
+
+        if (prior.length > 0) changed.add(key);
+        if (prior.length === 0 || (key instanceof Element && key.contains(target))) continue;
+        if (prior.includes(true)) moved.add(parentOf(key));
+        if (samples.some(({ at: when }) => when < at && when >= at - stillMillis)) still = false;
+      }
+
+      return { at, target, changed, moved, still };
+    });
+  };
+
+  /** The input a change followed, on the page's clock, where `Change.cause`'s rule names one. */
+  const causeOf = (
+    one: Folded,
+    element: Element,
+    inputs: ReturnType<typeof before>,
+  ): number | undefined => {
+    const parent = parentOf(one.track.key);
+
+    for (const input of inputs.toReversed()) {
+      const after = one.startedAt - input.at;
+
+      // A change in the input's own tick followed it, as when a busy page runs a press and its
+      // release back to back.
+      if (after < 0) continue;
+      if (after > 3000) break;
+
+      // In flux: it changed, or another came into or left what it sits in, in the 10 s before.
+      const changing =
+        one.track.known >= input.at - fluxMillis ||
+        input.changed.has(one.track.key) ||
+        (parent !== null && input.moved.has(parent));
+
+      if (!changing && (local(input.target, element) || (after <= 500 && input.still)))
+        return input.at;
+    }
+
+    return undefined;
+  };
+
+  const describe = (
+    one: Folded,
+    known: Known,
+    unmask: boolean,
+    inputs: ReturnType<typeof before>,
+  ): typeof Change.Encoded => {
+    const { track, kind, before, after, lowest, highest, ...times } = one;
+    const element = track.key instanceof Element ? track.key : null;
+    const where = element?.isConnected === true ? element : (marking.placeOf(track.key) ?? null);
+    const role = element === null ? null : roleOf(element);
+    const field = kind === "value";
+
+    const checkable =
+      element !== null && isInput(element) && /^(checkbox|radio)$/.test(element.type);
+
+    // A field's value is masked unless asked, empty or a box's state; a secret one never kept more.
+    const masked = (value: string | undefined) =>
+      value === undefined || !field || unmask || checkable || value === "" ? value : "••••";
+
+    return {
+      ...times,
+      kind,
+      subject: {
+        role,
+        // An element's own words are what changed, so it is named only by what else names it.
+        name:
+          element === null
+            ? ""
+            : field
+              ? nameOf(element, role)
+              : clean(element.getAttribute("aria-label"), 120),
+        tag: element === null ? "title" : element.tagName.toLowerCase(),
+        context: kind === "title" || where === null ? {} : placing.contextOf(where, known),
+      },
+      before: masked(before),
+      after: masked(after),
+      lowest: field ? undefined : lowest,
+      highest: field ? undefined : highest,
+      // A field's own edit needs no cause.
+      cause: field || where === null ? undefined : causeOf(one, where, inputs),
+    };
+  };
+
+  /** What changed after `since`, up to `until`, and no later than now. */
+  const read = (request: ChangesRequest): ChangesResult => {
+    const now = performance.timeOrigin + performance.now();
+
+    recorder.start();
+    seeing.settle();
+    const until = Math.min(request.until ?? now, now);
+
+    const { from, dropped, folded } = kept.read(
+      request.since ?? Number.NEGATIVE_INFINITY,
+      until,
+      now,
+    );
+
+    const known = placing.known();
+    const inputs = before();
+
+    return {
+      until,
+      from,
+      dropped,
+      records: folded.map((one) => describe(one, known, request.unmask, inputs)),
+    };
+  };
+
+  return { read };
+};
+
+export type Changes = ReturnType<typeof changes>;

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,93 @@
+/**
+ * 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,
+    recent: Effect.sync(() => records),
+    stream,
+    close: Effect.sync(() => {
+      if (closed) return;
+      closed = true;
+      wake();
+    }),
+  };
+};