@earendil-works/chord 1.4.0 → 1.5.1

package/dist/watch.js

@@ -0,0 +1,383 @@
+// Watch handles: the watch types and the one implementation of their lifecycle, for JSON and native values.
+import { withoutAbortSignal } from "./context/index.js";
+import { PendingOps } from "./delta/index.js";
+const STOPPED = { kind: "stopped" };
+const ABORTED = { kind: "aborted" };
+const ENDED = { kind: "ended" };
+/**
+ * The lifecycle both handles share: serialized delivery and termination. A source feeds it and ends it explicitly;
+ * termination drops every reference the watch holds into its source, so a stopped watch that is still referenced keeps
+ * nothing but its last value alive. Subclasses keep what is pending, each call apart from its frame's context, so the
+ * call a listener gets carries nothing but its data.
+ */
+class WatchLifecycle {
+    #detach;
+    #report;
+    #closed = Promise.withResolvers();
+    #value;
+    #listener;
+    #started = false;
+    #scheduled = false;
+    #running = false;
+    /** Set by `endAfterDelivery()`: the source sends nothing more; the watch ends `ended` once it delivered the rest. */
+    #ending = false;
+    /** Set once, by `#terminate()`. */
+    #end;
+    #abortSignal;
+    #abortListener;
+    constructor(value, detach, report) {
+        this.#value = value;
+        this.#detach = detach;
+        this.#report = report;
+    }
+    get value() {
+        return this.#value;
+    }
+    get closed() {
+        return this.#closed.promise;
+    }
+    start(listener) {
+        if (this.#started)
+            throw new Error("Watch is already started");
+        if (this.#end !== undefined)
+            throw new Error("Watch is stopped");
+        this.#started = true;
+        this.#listener = listener;
+        this.#schedule();
+    }
+    stop() {
+        this.#terminate(STOPPED);
+        return this.#closed.promise;
+    }
+    /** End the watch `aborted` when `signal` aborts; installed once. */
+    observeAbort(signal) {
+        if (this.#abortSignal !== undefined)
+            throw new Error("Watch abort is already installed");
+        if (this.#end !== undefined)
+            return;
+        this.#abortSignal = signal;
+        this.#abortListener = () => this.abort();
+        signal.addEventListener("abort", this.#abortListener, { once: true });
+        if (signal.aborted)
+            this.abort();
+    }
+    /** End the watch `aborted`: its acquisition context was aborted. */
+    abort() {
+        this.#terminate(ABORTED);
+    }
+    /**
+     * End the watch with `end` at once, dropping what is pending: the source closed (`ended`), or failed for good
+     * (`failed`). A failure the source may recover from is a `failed` call instead (`fail()`).
+     */
+    end(end) {
+        this.#terminate(end);
+    }
+    /**
+     * The source sends nothing more after its last frames, such as a retirement: take no more frames, deliver what is
+     * pending, then end `ended`, after the running call returns, if one runs. Until then the watch stays attached, so
+     * `end()`, `stop()`, an abort, and a throwing listener still end it first; a watch never started keeps what is
+     * pending until one of them or `start()`.
+     */
+    endAfterDelivery() {
+        if (this.#end !== undefined || this.#ending)
+            return;
+        this.#ending = true;
+        if (!this.#running && this.pendingContext === undefined)
+            this.#terminate(ENDED);
+    }
+    /** Whether the watch still takes frames: it has not ended, and its source has not ended. */
+    get open() {
+        return this.#end === undefined && !this.#ending;
+    }
+    /** Something became pending: deliver it once started, never inline. */
+    pending() {
+        if (this.#started)
+            this.#schedule();
+    }
+    #schedule() {
+        if (this.#scheduled || this.#running || this.#end !== undefined)
+            return;
+        this.#scheduled = true;
+        queueMicrotask(() => {
+            this.#scheduled = false;
+            void this.#drain();
+        });
+    }
+    /**
+     * Deliver until nothing is pending; what arrives during a call is taken after it returns. A watch whose source ended
+     * ends once it delivered the rest and its last call returned.
+     */
+    async #drain() {
+        if (this.#running || this.#end !== undefined || !this.#started)
+            return;
+        this.#running = true;
+        try {
+            while (this.#end === undefined) {
+                const listener = this.#listener;
+                if (listener === undefined)
+                    break;
+                const frameContext = this.pendingContext;
+                if (frameContext === undefined) {
+                    if (this.#ending)
+                        this.#terminate(ENDED);
+                    break;
+                }
+                const call = this.next();
+                if (call.kind === "value")
+                    this.#value = call.value;
+                try {
+                    await listener(call, withoutAbortSignal(frameContext));
+                }
+                catch (error) {
+                    if (this.#end === undefined) {
+                        this.#report?.(error);
+                        this.#terminate({ kind: "listener_error", error: toError(error) });
+                    }
+                    break;
+                }
+            }
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+    /**
+     * End the watch, once: detach, drop what is pending and every reference into the source, and settle `closed`. A
+     * callback already running keeps running.
+     */
+    #terminate(end) {
+        if (this.#end !== undefined)
+            return;
+        this.#end = end;
+        const detach = this.#detach;
+        this.#detach = undefined;
+        this.#report = undefined;
+        this.#listener = undefined;
+        this.release();
+        if (this.#abortListener !== undefined)
+            this.#abortSignal?.removeEventListener("abort", this.#abortListener);
+        this.#abortSignal = undefined;
+        this.#abortListener = undefined;
+        detach?.();
+        this.#closed.resolve(end);
+    }
+}
+function toError(error) {
+    if (error instanceof Error)
+        return error;
+    try {
+        return new Error(String(error));
+    }
+    catch {
+        return new Error(Object.prototype.toString.call(error));
+    }
+}
+/**
+ * The watch handle of a JSON source. Frames that arrive before `start()` or while the listener runs wait in one
+ * `PendingOps` queue; the next call gets the newest value, the folded ops of every frame since the previous call (or
+ * `[["r", newest]]` after the queue overflowed), `retired` when any of them was a retirement, and the newest frame's
+ * context. A frame delivered alone is passed on as the source made it. A failure (`fail()`) drops the pending frames and
+ * waits as one `failed` call; a value after it replaces it, and the first value call after a failure is `[["r",
+ * value]]`. `detach` unsubscribes it from its source on termination; `report` gets a listener's throw, which also ends
+ * the watch.
+ */
+export class Watch extends WatchLifecycle {
+    #ops = new PendingOps();
+    /**
+     * The source's call while it is the only frame pending: the call passes it on, with no allocation. A second frame
+     * drops it, so its ops stay only as long as `PendingOps` keeps them (folded, or dropped by an overflow).
+     */
+    #lone;
+    /** The newest frame's value and context, while a call is pending; the context also marks that one is. */
+    #newestValue;
+    #newestContext;
+    /** A pending frame was a retirement. */
+    #retired = false;
+    /** The newest frame was a failure: the next call is this. */
+    #failure;
+    /** A failure came after the last value call: the next value call replaces the root, and ops are not kept. */
+    #replace = false;
+    /**
+     * Queue the frame `call`. A value's ops turn the previous value into it, and `retired` says the document the watch
+     * follows was retired, which the next value call reports however many frames it folds; a failure is `fail()`.
+     */
+    advance(call, context) {
+        if (call.kind === "failed") {
+            this.#fail(call, context);
+            return;
+        }
+        if (!this.open)
+            return;
+        if (this.#replace) {
+            this.#failure = undefined;
+        }
+        else {
+            this.#lone = this.#newestContext === undefined ? call : undefined;
+            this.#ops.push(call.ops);
+        }
+        this.#newestValue = call.value;
+        this.#newestContext = context;
+        if (call.retired)
+            this.#retired = true;
+        this.pending();
+    }
+    /**
+     * Queue a failure the source may recover from: the pending frames are dropped (`value` keeps the last delivered
+     * value), the listener gets `{ kind: "failed", error }`, and the next value arrives as `[["r", value]]`.
+     */
+    fail(error, context) {
+        this.#fail({ kind: "failed", error }, context);
+    }
+    #fail(call, context) {
+        if (!this.open)
+            return;
+        this.#ops.take();
+        this.#lone = undefined;
+        this.#newestValue = undefined;
+        this.#failure = call;
+        this.#newestContext = context;
+        this.#replace = true;
+        this.pending();
+    }
+    get pendingContext() {
+        return this.#newestContext;
+    }
+    next() {
+        // After a failure the call is that failure, or the value after it; otherwise one field read decides.
+        if (this.#replace)
+            return this.#nextAfterFailure();
+        const lone = this.#lone;
+        // Set with the context, which says a frame is pending.
+        const value = this.#newestValue;
+        const batch = this.#ops.take();
+        const retired = this.#retired;
+        this.#lone = undefined;
+        this.#newestValue = undefined;
+        this.#newestContext = undefined;
+        this.#retired = false;
+        // One frame never folds or overflows: its call is the listener's.
+        if (lone !== undefined)
+            return lone;
+        // Values of a JSON watch are JSON; `T` is the source's narrower or wider view of them (e.g. a typed document).
+        const ops = batch.kind === "ops" ? batch.ops : [["r", value]];
+        return { kind: "value", value, ops, retired };
+    }
+    /** The pending failure, or the value after one as a root replacement (no ops were kept since the failure). */
+    #nextAfterFailure() {
+        const failure = this.#failure;
+        this.#newestContext = undefined;
+        if (failure !== undefined) {
+            this.#failure = undefined;
+            return failure;
+        }
+        const value = this.#newestValue;
+        const retired = this.#retired;
+        this.#newestValue = undefined;
+        this.#retired = false;
+        this.#replace = false;
+        return { kind: "value", value, ops: [["r", value]], retired };
+    }
+    release() {
+        this.#ops.take();
+        this.#lone = undefined;
+        this.#newestValue = undefined;
+        this.#newestContext = undefined;
+        this.#retired = false;
+        this.#failure = undefined;
+        this.#replace = false;
+    }
+}
+/** Maximum values retained behind one unavailable native watch listener. */
+const MAX_PENDING_NATIVE_VALUES = 100;
+/**
+ * The watch handle of a native source: every value in order, one call each; past 100 pending values they collapse to
+ * one, `replace()` or by default the newest value. A failure (`fail()`) drops the pending values and waits as one
+ * `failed` call; a value after it replaces it. `detach` and `report` as for `Watch`.
+ */
+export class NativeWatch extends WatchLifecycle {
+    /**
+     * Pending values in order, each followed by its frame's context, from `#head` on. Values are kept raw: the call a
+     * listener gets is built when it is taken, so a value an overflow drops costs no object. A read index instead of
+     * `shift()` takes a backlog in constant time per value; taken slots are cleared at once, the array is emptied once
+     * all of it was taken, and its taken prefix dropped after 100 values.
+     */
+    #pending = [];
+    #head = 0;
+    #replace;
+    /** A pending failure and its frame's context; nothing else is pending meanwhile. */
+    #failure;
+    #failureContext;
+    constructor(value, detach, report, replace) {
+        super(value, detach, report);
+        this.#replace = replace;
+    }
+    /** Queue `value`, the source's new value; it replaces a pending failure. */
+    advance(value, context) {
+        if (!this.open)
+            return;
+        this.#failure = undefined;
+        this.#failureContext = undefined;
+        if (this.#pending.length - this.#head < 2 * MAX_PENDING_NATIVE_VALUES) {
+            this.#pending.push(value, context);
+        }
+        else {
+            this.#pending.length = 0;
+            this.#head = 0;
+            this.#pending.push(this.#replace === undefined ? value : this.#replace(), context);
+        }
+        this.pending();
+    }
+    /**
+     * Queue a failure the source may recover from: the pending values are dropped (`value` keeps the last delivered
+     * value), and the listener gets `{ kind: "failed", error }`.
+     */
+    fail(error, context) {
+        if (!this.open)
+            return;
+        this.#pending.length = 0;
+        this.#head = 0;
+        this.#failure = { kind: "failed", error };
+        this.#failureContext = context;
+        this.pending();
+    }
+    get pendingContext() {
+        // The slot after a value holds its context; past the end it is empty.
+        return this.#failureContext ?? this.#pending[this.#head + 1];
+    }
+    next() {
+        const failure = this.#failure;
+        if (failure !== undefined) {
+            this.#failure = undefined;
+            this.#failureContext = undefined;
+            return failure;
+        }
+        const head = this.#head;
+        const pending = this.#pending;
+        // The slot at `#head` holds a value.
+        const value = pending[head];
+        if (head + 2 === pending.length) {
+            pending.length = 0;
+            this.#head = 0;
+        }
+        else if (head + 2 >= 2 * MAX_PENDING_NATIVE_VALUES) {
+            // A backlog that never drains: drop the taken prefix, at most once per 100 values, so the array stays bounded.
+            pending.copyWithin(0, head + 2);
+            pending.length -= head + 2;
+            this.#head = 0;
+        }
+        else {
+            pending[head] = undefined;
+            pending[head + 1] = undefined;
+            this.#head = head + 2;
+        }
+        return { kind: "value", value };
+    }
+    release() {
+        this.#pending.length = 0;
+        this.#head = 0;
+        this.#replace = undefined;
+        this.#failure = undefined;
+        this.#failureContext = undefined;
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"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","sourcesContent":["// Watch handles: the watch types and the one implementation of their lifecycle, for JSON and native values.\nimport { type Context, withoutAbortSignal } from \"./context/index.ts\";\nimport { type Op, PendingOps } from \"./delta/index.ts\";\nimport type { JsonValue } from \"./json.ts\";\n\n/**\n * Terminal result of one watch, tagged by `kind`. A watch ends only for good; a failure its source recovers from is a\n * `failed` call (`WatchCall`), and the watch stays open.\n *\n * - `stopped`: `stop()` was called.\n * - `aborted`: the context the watch was acquired with was aborted.\n * - `ended`: the source closed (its owner ended or closed).\n * - `listener_error`: the listener threw or rejected with `error`.\n * - `failed`: the source failed for good with `error`.\n */\nexport type WatchEnd =\n\t| { readonly kind: \"stopped\" | \"aborted\" | \"ended\" }\n\t| { readonly kind: \"listener_error\"; readonly error: Error }\n\t| { readonly kind: \"failed\"; readonly error: unknown };\n\n/**\n * One call of a JSON watch's listener, and one frame a source hands its watch, tagged by `kind`:\n *\n * - `value`: the newest value, the ops that turn the previous value into it, and whether the document the watch follows\n *   was retired since the previous value call. A retirement does not end the watch: `value` is then what the address\n *   shows after it (the source decides; a Durable document keeps the last value the watch was given, with no ops), and a\n *   document created there later arrives as `[[\"r\", value]]`, possibly in the same call.\n * - `failed`: the source cannot compute its value now, with `error`; the watch stays open, and the next value arrives as\n *   `[[\"r\", value]]`. `WatchHandle.value` keeps the last value.\n *\n * Plain data: the frame's context is the listener's second argument, never part of the call.\n */\nexport type WatchCall<T> =\n\t| { readonly kind: \"value\"; readonly value: T; readonly ops: readonly Op[]; readonly retired: boolean }\n\t| { readonly kind: \"failed\"; readonly error: unknown };\n\n/** One call of a native watch's listener: the new value, or a failure its source may recover from, as in `WatchCall`. */\nexport type NativeWatchCall<T> =\n\t| { readonly kind: \"value\"; readonly value: T }\n\t| { readonly kind: \"failed\"; readonly error: unknown };\n\n/**\n * Serialized observation of an immutable value: one listener call at a time; changes made meanwhile arrive folded into\n * the next call.\n */\nexport interface WatchHandle<T> {\n\t/** Acquisition revision before start; latest delivered immutable revision afterward (a `failed` call keeps it). */\n\treadonly value: T;\n\t/** Install the sole asynchronous listener. Never invokes it inline. */\n\tstart(listener: (call: WatchCall<T>, context: Context) => Promise<void>): void;\n\t/** Idempotently stop future callbacks and return this watch's terminal result. */\n\tstop(): Promise<WatchEnd>;\n\t/** Settle when the watch terminates; an already-running callback remains caller-owned. */\n\treadonly closed: Promise<WatchEnd>;\n}\n\n/**\n * A value that changes and can be watched: documents, derives, members of references. Values are immutable by\n * convention (JSON for state); each watch starts at the current value and then gets the changes, folded while its\n * listener is busy.\n */\nexport interface Watchable<T> {\n\t/** The current value. */\n\treadonly value: T;\n\t/** A watch holding the current value, then its changes; aborting the context ends it. */\n\twatch(context: Context): Promise<WatchHandle<T>>;\n}\n\n/**\n * An in-process value that changes and can be watched (it may hold anything, errors and functions included): a change\n * is a new value by identity, delivered without ops.\n */\nexport interface NativeWatchable<T> {\n\t/** The current value. */\n\treadonly value: T;\n\t/** A watch holding the current value, then one frame per new value; aborting the context ends it. */\n\twatch(context: Context): Promise<NativeWatchHandle<T>>;\n}\n\n/**\n * Serialized observation of an in-process value: as `WatchHandle`, but each new value is its own call, in order, without\n * ops.\n */\nexport interface NativeWatchHandle<T> {\n\t/** Acquisition value before start; latest delivered value afterward (a `failed` call keeps it). */\n\treadonly value: T;\n\t/** Install the sole asynchronous listener. Never invokes it inline. */\n\tstart(listener: (call: NativeWatchCall<T>, context: Context) => Promise<void>): void;\n\t/** Idempotently stop future callbacks and return this watch's terminal result. */\n\tstop(): Promise<WatchEnd>;\n\t/** Settle when the watch terminates; an already-running callback remains caller-owned. */\n\treadonly closed: Promise<WatchEnd>;\n}\n\ntype Listener<C> = (call: C, context: Context) => Promise<void>;\n\nconst STOPPED: WatchEnd = { kind: \"stopped\" };\nconst ABORTED: WatchEnd = { kind: \"aborted\" };\nconst ENDED: WatchEnd = { kind: \"ended\" };\n\n/** A failure call, as both call types have it. */\ntype FailedCall = { readonly kind: \"failed\"; readonly error: unknown };\n\n/**\n * The lifecycle both handles share: serialized delivery and termination. A source feeds it and ends it explicitly;\n * termination drops every reference the watch holds into its source, so a stopped watch that is still referenced keeps\n * nothing but its last value alive. Subclasses keep what is pending, each call apart from its frame's context, so the\n * call a listener gets carries nothing but its data.\n */\nabstract class WatchLifecycle<T, C extends { readonly kind: \"value\"; readonly value: T } | FailedCall> {\n\t#detach: (() => void) | undefined;\n\t#report: ((error: unknown) => void) | undefined;\n\treadonly #closed = Promise.withResolvers<WatchEnd>();\n\t#value: T;\n\t#listener: Listener<C> | undefined;\n\t#started = false;\n\t#scheduled = false;\n\t#running = false;\n\t/** Set by `endAfterDelivery()`: the source sends nothing more; the watch ends `ended` once it delivered the rest. */\n\t#ending = false;\n\t/** Set once, by `#terminate()`. */\n\t#end: WatchEnd | undefined;\n\t#abortSignal: AbortSignal | undefined;\n\t#abortListener: (() => void) | undefined;\n\n\tconstructor(value: T, detach: () => void, report: (error: unknown) => void) {\n\t\tthis.#value = value;\n\t\tthis.#detach = detach;\n\t\tthis.#report = report;\n\t}\n\n\tget value(): T {\n\t\treturn this.#value;\n\t}\n\n\tget closed(): Promise<WatchEnd> {\n\t\treturn this.#closed.promise;\n\t}\n\n\tstart(listener: Listener<C>): void {\n\t\tif (this.#started) throw new Error(\"Watch is already started\");\n\t\tif (this.#end !== undefined) throw new Error(\"Watch is stopped\");\n\t\tthis.#started = true;\n\t\tthis.#listener = listener;\n\t\tthis.#schedule();\n\t}\n\n\tstop(): Promise<WatchEnd> {\n\t\tthis.#terminate(STOPPED);\n\t\treturn this.#closed.promise;\n\t}\n\n\t/** End the watch `aborted` when `signal` aborts; installed once. */\n\tobserveAbort(signal: AbortSignal): void {\n\t\tif (this.#abortSignal !== undefined) throw new Error(\"Watch abort is already installed\");\n\t\tif (this.#end !== undefined) return;\n\t\tthis.#abortSignal = signal;\n\t\tthis.#abortListener = () => this.abort();\n\t\tsignal.addEventListener(\"abort\", this.#abortListener, { once: true });\n\t\tif (signal.aborted) this.abort();\n\t}\n\n\t/** End the watch `aborted`: its acquisition context was aborted. */\n\tabort(): void {\n\t\tthis.#terminate(ABORTED);\n\t}\n\n\t/**\n\t * End the watch with `end` at once, dropping what is pending: the source closed (`ended`), or failed for good\n\t * (`failed`). A failure the source may recover from is a `failed` call instead (`fail()`).\n\t */\n\tend(end: WatchEnd): void {\n\t\tthis.#terminate(end);\n\t}\n\n\t/**\n\t * The source sends nothing more after its last frames, such as a retirement: take no more frames, deliver what is\n\t * pending, then end `ended`, after the running call returns, if one runs. Until then the watch stays attached, so\n\t * `end()`, `stop()`, an abort, and a throwing listener still end it first; a watch never started keeps what is\n\t * pending until one of them or `start()`.\n\t */\n\tendAfterDelivery(): void {\n\t\tif (this.#end !== undefined || this.#ending) return;\n\t\tthis.#ending = true;\n\t\tif (!this.#running && this.pendingContext === undefined) this.#terminate(ENDED);\n\t}\n\n\t/** Whether the watch still takes frames: it has not ended, and its source has not ended. */\n\tprotected get open(): boolean {\n\t\treturn this.#end === undefined && !this.#ending;\n\t}\n\n\t/** The context of the newest frame the next call covers, or undefined when nothing is pending. */\n\tprotected abstract get pendingContext(): Context | undefined;\n\n\t/** Take the next call; called only while something is pending. */\n\tprotected abstract next(): C;\n\n\t/** Drop everything pending and every reference into the source; called once, on termination. */\n\tprotected abstract release(): void;\n\n\t/** Something became pending: deliver it once started, never inline. */\n\tprotected pending(): void {\n\t\tif (this.#started) this.#schedule();\n\t}\n\n\t#schedule(): void {\n\t\tif (this.#scheduled || this.#running || this.#end !== undefined) return;\n\t\tthis.#scheduled = true;\n\t\tqueueMicrotask(() => {\n\t\t\tthis.#scheduled = false;\n\t\t\tvoid this.#drain();\n\t\t});\n\t}\n\n\t/**\n\t * Deliver until nothing is pending; what arrives during a call is taken after it returns. A watch whose source ended\n\t * ends once it delivered the rest and its last call returned.\n\t */\n\tasync #drain(): Promise<void> {\n\t\tif (this.#running || this.#end !== undefined || !this.#started) return;\n\t\tthis.#running = true;\n\t\ttry {\n\t\t\twhile (this.#end === undefined) {\n\t\t\t\tconst listener = this.#listener;\n\t\t\t\tif (listener === undefined) break;\n\t\t\t\tconst frameContext = this.pendingContext;\n\t\t\t\tif (frameContext === undefined) {\n\t\t\t\t\tif (this.#ending) this.#terminate(ENDED);\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tconst call = this.next();\n\t\t\t\tif (call.kind === \"value\") this.#value = call.value;\n\t\t\t\ttry {\n\t\t\t\t\tawait listener(call, withoutAbortSignal(frameContext));\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (this.#end === undefined) {\n\t\t\t\t\t\tthis.#report?.(error);\n\t\t\t\t\t\tthis.#terminate({ kind: \"listener_error\", error: toError(error) });\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t} finally {\n\t\t\tthis.#running = false;\n\t\t}\n\t}\n\n\t/**\n\t * End the watch, once: detach, drop what is pending and every reference into the source, and settle `closed`. A\n\t * callback already running keeps running.\n\t */\n\t#terminate(end: WatchEnd): void {\n\t\tif (this.#end !== undefined) return;\n\t\tthis.#end = end;\n\t\tconst detach = this.#detach;\n\t\tthis.#detach = undefined;\n\t\tthis.#report = undefined;\n\t\tthis.#listener = undefined;\n\t\tthis.release();\n\t\tif (this.#abortListener !== undefined) this.#abortSignal?.removeEventListener(\"abort\", this.#abortListener);\n\t\tthis.#abortSignal = undefined;\n\t\tthis.#abortListener = undefined;\n\t\tdetach?.();\n\t\tthis.#closed.resolve(end);\n\t}\n}\n\nfunction toError(error: unknown): Error {\n\tif (error instanceof Error) return error;\n\ttry {\n\t\treturn new Error(String(error));\n\t} catch {\n\t\treturn new Error(Object.prototype.toString.call(error));\n\t}\n}\n\n/**\n * The watch handle of a JSON source. Frames that arrive before `start()` or while the listener runs wait in one\n * `PendingOps` queue; the next call gets the newest value, the folded ops of every frame since the previous call (or\n * `[[\"r\", newest]]` after the queue overflowed), `retired` when any of them was a retirement, and the newest frame's\n * context. A frame delivered alone is passed on as the source made it. A failure (`fail()`) drops the pending frames and\n * waits as one `failed` call; a value after it replaces it, and the first value call after a failure is `[[\"r\",\n * value]]`. `detach` unsubscribes it from its source on termination; `report` gets a listener's throw, which also ends\n * the watch.\n */\nexport class Watch<T> extends WatchLifecycle<T, WatchCall<T>> implements WatchHandle<T> {\n\treadonly #ops = new PendingOps();\n\t/**\n\t * The source's call while it is the only frame pending: the call passes it on, with no allocation. A second frame\n\t * drops it, so its ops stay only as long as `PendingOps` keeps them (folded, or dropped by an overflow).\n\t */\n\t#lone: WatchValueCall<T> | undefined;\n\t/** The newest frame's value and context, while a call is pending; the context also marks that one is. */\n\t#newestValue: T | undefined;\n\t#newestContext: Context | undefined;\n\t/** A pending frame was a retirement. */\n\t#retired = false;\n\t/** The newest frame was a failure: the next call is this. */\n\t#failure: FailedCall | undefined;\n\t/** A failure came after the last value call: the next value call replaces the root, and ops are not kept. */\n\t#replace = false;\n\n\t/**\n\t * Queue the frame `call`. A value's ops turn the previous value into it, and `retired` says the document the watch\n\t * follows was retired, which the next value call reports however many frames it folds; a failure is `fail()`.\n\t */\n\tadvance(call: WatchCall<T>, context: Context): void {\n\t\tif (call.kind === \"failed\") {\n\t\t\tthis.#fail(call, context);\n\t\t\treturn;\n\t\t}\n\t\tif (!this.open) return;\n\t\tif (this.#replace) {\n\t\t\tthis.#failure = undefined;\n\t\t} else {\n\t\t\tthis.#lone = this.#newestContext === undefined ? call : undefined;\n\t\t\tthis.#ops.push(call.ops);\n\t\t}\n\t\tthis.#newestValue = call.value;\n\t\tthis.#newestContext = context;\n\t\tif (call.retired) this.#retired = true;\n\t\tthis.pending();\n\t}\n\n\t/**\n\t * Queue a failure the source may recover from: the pending frames are dropped (`value` keeps the last delivered\n\t * value), the listener gets `{ kind: \"failed\", error }`, and the next value arrives as `[[\"r\", value]]`.\n\t */\n\tfail(error: unknown, context: Context): void {\n\t\tthis.#fail({ kind: \"failed\", error }, context);\n\t}\n\n\t#fail(call: FailedCall, context: Context): void {\n\t\tif (!this.open) return;\n\t\tthis.#ops.take();\n\t\tthis.#lone = undefined;\n\t\tthis.#newestValue = undefined;\n\t\tthis.#failure = call;\n\t\tthis.#newestContext = context;\n\t\tthis.#replace = true;\n\t\tthis.pending();\n\t}\n\n\tprotected get pendingContext(): Context | undefined {\n\t\treturn this.#newestContext;\n\t}\n\n\tprotected next(): WatchCall<T> {\n\t\t// After a failure the call is that failure, or the value after it; otherwise one field read decides.\n\t\tif (this.#replace) return this.#nextAfterFailure();\n\t\tconst lone = this.#lone;\n\t\t// Set with the context, which says a frame is pending.\n\t\tconst value = this.#newestValue as T;\n\t\tconst batch = this.#ops.take();\n\t\tconst retired = this.#retired;\n\t\tthis.#lone = undefined;\n\t\tthis.#newestValue = undefined;\n\t\tthis.#newestContext = undefined;\n\t\tthis.#retired = false;\n\t\t// One frame never folds or overflows: its call is the listener's.\n\t\tif (lone !== undefined) return lone;\n\t\t// Values of a JSON watch are JSON; `T` is the source's narrower or wider view of them (e.g. a typed document).\n\t\tconst ops: readonly Op[] = batch.kind === \"ops\" ? batch.ops : [[\"r\", value as JsonValue]];\n\t\treturn { kind: \"value\", value, ops, retired };\n\t}\n\n\t/** The pending failure, or the value after one as a root replacement (no ops were kept since the failure). */\n\t#nextAfterFailure(): WatchCall<T> {\n\t\tconst failure = this.#failure;\n\t\tthis.#newestContext = undefined;\n\t\tif (failure !== undefined) {\n\t\t\tthis.#failure = undefined;\n\t\t\treturn failure;\n\t\t}\n\t\tconst value = this.#newestValue as T;\n\t\tconst retired = this.#retired;\n\t\tthis.#newestValue = undefined;\n\t\tthis.#retired = false;\n\t\tthis.#replace = false;\n\t\treturn { kind: \"value\", value, ops: [[\"r\", value as JsonValue]], retired };\n\t}\n\n\tprotected release(): void {\n\t\tthis.#ops.take();\n\t\tthis.#lone = undefined;\n\t\tthis.#newestValue = undefined;\n\t\tthis.#newestContext = undefined;\n\t\tthis.#retired = false;\n\t\tthis.#failure = undefined;\n\t\tthis.#replace = false;\n\t}\n}\n\n/** The value call of a JSON watch. */\ntype WatchValueCall<T> = Extract<WatchCall<T>, { readonly kind: \"value\" }>;\n\n/** Maximum values retained behind one unavailable native watch listener. */\nconst MAX_PENDING_NATIVE_VALUES = 100;\n\n/**\n * The watch handle of a native source: every value in order, one call each; past 100 pending values they collapse to\n * one, `replace()` or by default the newest value. A failure (`fail()`) drops the pending values and waits as one\n * `failed` call; a value after it replaces it. `detach` and `report` as for `Watch`.\n */\nexport class NativeWatch<T> extends WatchLifecycle<T, NativeWatchCall<T>> implements NativeWatchHandle<T> {\n\t/**\n\t * Pending values in order, each followed by its frame's context, from `#head` on. Values are kept raw: the call a\n\t * listener gets is built when it is taken, so a value an overflow drops costs no object. A read index instead of\n\t * `shift()` takes a backlog in constant time per value; taken slots are cleared at once, the array is emptied once\n\t * all of it was taken, and its taken prefix dropped after 100 values.\n\t */\n\treadonly #pending: Array<T | Context | undefined> = [];\n\t#head = 0;\n\t#replace: (() => T) | undefined;\n\t/** A pending failure and its frame's context; nothing else is pending meanwhile. */\n\t#failure: FailedCall | undefined;\n\t#failureContext: Context | undefined;\n\n\tconstructor(value: T, detach: () => void, report: (error: unknown) => void, replace?: () => T) {\n\t\tsuper(value, detach, report);\n\t\tthis.#replace = replace;\n\t}\n\n\t/** Queue `value`, the source's new value; it replaces a pending failure. */\n\tadvance(value: T, context: Context): void {\n\t\tif (!this.open) return;\n\t\tthis.#failure = undefined;\n\t\tthis.#failureContext = undefined;\n\t\tif (this.#pending.length - this.#head < 2 * MAX_PENDING_NATIVE_VALUES) {\n\t\t\tthis.#pending.push(value, context);\n\t\t} else {\n\t\t\tthis.#pending.length = 0;\n\t\t\tthis.#head = 0;\n\t\t\tthis.#pending.push(this.#replace === undefined ? value : this.#replace(), context);\n\t\t}\n\t\tthis.pending();\n\t}\n\n\t/**\n\t * Queue a failure the source may recover from: the pending values are dropped (`value` keeps the last delivered\n\t * value), and the listener gets `{ kind: \"failed\", error }`.\n\t */\n\tfail(error: unknown, context: Context): void {\n\t\tif (!this.open) return;\n\t\tthis.#pending.length = 0;\n\t\tthis.#head = 0;\n\t\tthis.#failure = { kind: \"failed\", error };\n\t\tthis.#failureContext = context;\n\t\tthis.pending();\n\t}\n\n\tprotected get pendingContext(): Context | undefined {\n\t\t// The slot after a value holds its context; past the end it is empty.\n\t\treturn this.#failureContext ?? (this.#pending[this.#head + 1] as Context | undefined);\n\t}\n\n\tprotected next(): NativeWatchCall<T> {\n\t\tconst failure = this.#failure;\n\t\tif (failure !== undefined) {\n\t\t\tthis.#failure = undefined;\n\t\t\tthis.#failureContext = undefined;\n\t\t\treturn failure;\n\t\t}\n\t\tconst head = this.#head;\n\t\tconst pending = this.#pending;\n\t\t// The slot at `#head` holds a value.\n\t\tconst value = pending[head] as T;\n\t\tif (head + 2 === pending.length) {\n\t\t\tpending.length = 0;\n\t\t\tthis.#head = 0;\n\t\t} else if (head + 2 >= 2 * MAX_PENDING_NATIVE_VALUES) {\n\t\t\t// A backlog that never drains: drop the taken prefix, at most once per 100 values, so the array stays bounded.\n\t\t\tpending.copyWithin(0, head + 2);\n\t\t\tpending.length -= head + 2;\n\t\t\tthis.#head = 0;\n\t\t} else {\n\t\t\tpending[head] = undefined;\n\t\t\tpending[head + 1] = undefined;\n\t\t\tthis.#head = head + 2;\n\t\t}\n\t\treturn { kind: \"value\", value };\n\t}\n\n\tprotected release(): void {\n\t\tthis.#pending.length = 0;\n\t\tthis.#head = 0;\n\t\tthis.#replace = undefined;\n\t\tthis.#failure = undefined;\n\t\tthis.#failureContext = undefined;\n\t}\n}\n"]}

package/dist/web/environment.d.ts

@@ -0,0 +1,4 @@
+import type { LoopEnvironment } from "../surfaces/index.ts";
+/** The browser page's loop environment. */
+export declare function pageEnvironment(): LoopEnvironment;
+//# sourceMappingURL=environment.d.ts.map

package/dist/web/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/web/environment.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,2CAA2C;AAC3C,wBAAgB,eAAe,IAAI,eAAe,CA4BjD"}

package/dist/web/environment.js

@@ -0,0 +1,37 @@
+/// <reference lib="dom" />
+// The page's environment for the connection loop (slice 11 §2, decision "Slice 11, P6"): the clock and timers, and
+// the wakes that mean the page may have been away: visible again, back online, restored from the back/forward cache,
+// or a network change (Chromium reports it; the old socket then looks fine until it is checked).
+/** The browser page's loop environment. */
+export function pageEnvironment() {
+    return {
+        now: () => Date.now(),
+        after: (ms, callback) => {
+            const timer = setTimeout(callback, ms);
+            return () => clearTimeout(timer);
+        },
+        online: () => navigator.onLine,
+        onWake: (listener) => {
+            const restored = (event) => {
+                if (event.persisted)
+                    listener();
+            };
+            const visible = () => {
+                if (document.visibilityState === "visible")
+                    listener();
+            };
+            const network = navigator.connection;
+            window.addEventListener("online", listener);
+            window.addEventListener("pageshow", restored);
+            document.addEventListener("visibilitychange", visible);
+            network?.addEventListener("change", listener);
+            return () => {
+                window.removeEventListener("online", listener);
+                window.removeEventListener("pageshow", restored);
+                document.removeEventListener("visibilitychange", visible);
+                network?.removeEventListener("change", listener);
+            };
+        },
+    };
+}
+//# sourceMappingURL=environment.js.map

package/dist/web/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/web/environment.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,mHAAmH;AACnH,qHAAqH;AACrH,iGAAiG;AAIjG,2CAA2C;AAC3C,MAAM,UAAU,eAAe;IAC9B,OAAO;QACN,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QACrB,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE;YACvB,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACvC,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM;QAC9B,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;YACpB,MAAM,QAAQ,GAAG,CAAC,KAA0B,EAAQ,EAAE;gBACrD,IAAI,KAAK,CAAC,SAAS;oBAAE,QAAQ,EAAE,CAAC;YACjC,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,GAAS,EAAE;gBAC1B,IAAI,QAAQ,CAAC,eAAe,KAAK,SAAS;oBAAE,QAAQ,EAAE,CAAC;YACxD,CAAC,CAAC;YACF,MAAM,OAAO,GAAI,SAAmD,CAAC,UAAU,CAAC;YAChF,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC5C,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC9C,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;YACvD,OAAO,EAAE,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC9C,OAAO,GAAG,EAAE;gBACX,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAC/C,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;gBACjD,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;gBAC1D,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAClD,CAAC,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["/// <reference lib=\"dom\" />\n// The page's environment for the connection loop (slice 11 §2, decision \"Slice 11, P6\"): the clock and timers, and\n// the wakes that mean the page may have been away: visible again, back online, restored from the back/forward cache,\n// or a network change (Chromium reports it; the old socket then looks fine until it is checked).\n\nimport type { LoopEnvironment } from \"../surfaces/index.ts\";\n\n/** The browser page's loop environment. */\nexport function pageEnvironment(): LoopEnvironment {\n\treturn {\n\t\tnow: () => Date.now(),\n\t\tafter: (ms, callback) => {\n\t\t\tconst timer = setTimeout(callback, ms);\n\t\t\treturn () => clearTimeout(timer);\n\t\t},\n\t\tonline: () => navigator.onLine,\n\t\tonWake: (listener) => {\n\t\t\tconst restored = (event: PageTransitionEvent): void => {\n\t\t\t\tif (event.persisted) listener();\n\t\t\t};\n\t\t\tconst visible = (): void => {\n\t\t\t\tif (document.visibilityState === \"visible\") listener();\n\t\t\t};\n\t\t\tconst network = (navigator as { readonly connection?: EventTarget }).connection;\n\t\t\twindow.addEventListener(\"online\", listener);\n\t\t\twindow.addEventListener(\"pageshow\", restored);\n\t\t\tdocument.addEventListener(\"visibilitychange\", visible);\n\t\t\tnetwork?.addEventListener(\"change\", listener);\n\t\t\treturn () => {\n\t\t\t\twindow.removeEventListener(\"online\", listener);\n\t\t\t\twindow.removeEventListener(\"pageshow\", restored);\n\t\t\t\tdocument.removeEventListener(\"visibilitychange\", visible);\n\t\t\t\tnetwork?.removeEventListener(\"change\", listener);\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/web/index.d.ts

@@ -0,0 +1,5 @@
+export { pageEnvironment } from "./environment.ts";
+export { followLanguage } from "./language.ts";
+export { type PageOptions, startPage } from "./page.ts";
+export { followThemes } from "./themes.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/web/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/web/index.js

@@ -0,0 +1,7 @@
+// Chord v2's web surface, the browser side (`@earendil-works/chord/web`; slice 11 §2): `startPage` in the app's web
+// entry, and the themes and the language it writes. The server side is `/surfaces`.
+export { pageEnvironment } from "./environment.js";
+export { followLanguage } from "./language.js";
+export { startPage } from "./page.js";
+export { followThemes } from "./themes.js";
+//# sourceMappingURL=index.js.map

package/dist/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,oFAAoF;AAEpF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAoB,SAAS,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC","sourcesContent":["// Chord v2's web surface, the browser side (`@earendil-works/chord/web`; slice 11 §2): `startPage` in the app's web\n// entry, and the themes and the language it writes. The server side is `/surfaces`.\n\nexport { pageEnvironment } from \"./environment.ts\";\nexport { followLanguage } from \"./language.ts\";\nexport { type PageOptions, startPage } from \"./page.ts\";\nexport { followThemes } from \"./themes.ts\";\n"]}

package/dist/web/language.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from "../context/index.ts";
+import type { Principal } from "../data/index.ts";
+import type { Host } from "../host/index.ts";
+import { type MessagesReport } from "../surfaces/index.ts";
+/** Follows the language on `host` and writes it on the root element until the returned stop; `report` gets reports. */
+export declare function followLanguage<P extends Principal>(host: Host<P>, report: (report: MessagesReport) => void, context: Context): Promise<() => void>;
+//# sourceMappingURL=language.d.ts.map

package/dist/web/language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../../src/web/language.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEjF,uHAAuH;AACvH,wBAAsB,cAAc,CAAC,CAAC,SAAS,SAAS,EACvD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,EACxC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,IAAI,CAAC,CAkBrB"}

package/dist/web/language.js

@@ -0,0 +1,21 @@
+/// <reference lib="dom" />
+// The page's language (decision "Messages and languages in the app kit" (3)): the active language followed from the
+// browser's `navigator.languages`, the user's `LocaleChoice` and the catalogs, written as `lang` and `dir` on the root
+// element (right to left through the app's logical CSS properties). Components re-render through `useMessages`; nothing
+// reloads.
+import { followActiveLanguage } from "../surfaces/index.js";
+/** Follows the language on `host` and writes it on the root element until the returned stop; `report` gets reports. */
+export async function followLanguage(host, report, context) {
+    const root = document.documentElement;
+    const follower = await followActiveLanguage(host, navigator.languages, (language) => {
+        root.lang = language.locale;
+        root.dir = language.dir;
+    }, report, context);
+    const devicechanged = () => follower.setDevice(navigator.languages);
+    addEventListener("languagechange", devicechanged);
+    return () => {
+        follower.stop();
+        removeEventListener("languagechange", devicechanged);
+    };
+}
+//# sourceMappingURL=language.js.map

package/dist/web/language.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.js","sourceRoot":"","sources":["../../src/web/language.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,oHAAoH;AACpH,uHAAuH;AACvH,wHAAwH;AACxH,WAAW;AAKX,OAAO,EAAE,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AAEjF,uHAAuH;AACvH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,IAAa,EACb,MAAwC,EACxC,OAAgB;IAEhB,MAAM,IAAI,GAAG,QAAQ,CAAC,eAAe,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAC1C,IAAI,EACJ,SAAS,CAAC,SAAS,EACnB,CAAC,QAAQ,EAAE,EAAE;QACZ,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IACzB,CAAC,EACD,MAAM,EACN,OAAO,CACP,CAAC;IACF,MAAM,aAAa,GAAG,GAAS,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC1E,gBAAgB,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;IAClD,OAAO,GAAG,EAAE;QACX,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChB,mBAAmB,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;IACtD,CAAC,CAAC;AACH,CAAC","sourcesContent":["/// <reference lib=\"dom\" />\n// The page's language (decision \"Messages and languages in the app kit\" (3)): the active language followed from the\n// browser's `navigator.languages`, the user's `LocaleChoice` and the catalogs, written as `lang` and `dir` on the root\n// element (right to left through the app's logical CSS properties). Components re-render through `useMessages`; nothing\n// reloads.\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport type { Host } from \"../host/index.ts\";\nimport { followActiveLanguage, type MessagesReport } from \"../surfaces/index.ts\";\n\n/** Follows the language on `host` and writes it on the root element until the returned stop; `report` gets reports. */\nexport async function followLanguage<P extends Principal>(\n\thost: Host<P>,\n\treport: (report: MessagesReport) => void,\n\tcontext: Context,\n): Promise<() => void> {\n\tconst root = document.documentElement;\n\tconst follower = await followActiveLanguage(\n\t\thost,\n\t\tnavigator.languages,\n\t\t(language) => {\n\t\t\troot.lang = language.locale;\n\t\t\troot.dir = language.dir;\n\t\t},\n\t\treport,\n\t\tcontext,\n\t);\n\tconst devicechanged = (): void => follower.setDevice(navigator.languages);\n\taddEventListener(\"languagechange\", devicechanged);\n\treturn () => {\n\t\tfollower.stop();\n\t\tremoveEventListener(\"languagechange\", devicechanged);\n\t};\n}\n"]}

package/dist/web/page.d.ts

@@ -0,0 +1,29 @@
+import type { Principal } from "../data/index.ts";
+import type { PluginFacet } from "../host/index.ts";
+import { type WebSocketLike } from "../link/index.ts";
+import { type Client, type ClientError, type ClientModules, type ConnectionState } from "../surfaces/index.ts";
+/** What `startPage` takes. */
+export type PageOptions<P extends Principal> = {
+    /** Opens the page's socket to the server's links endpoint (`/chord`). */
+    readonly connect: () => WebSocketLike;
+    /** The modules the web plugins import, by specifier: the app's API modules for the web kind, React, ... */
+    readonly modules: ClientModules;
+    /** The app's own web facets. */
+    readonly core?: readonly PluginFacet<P>[];
+    /** Asked before each reconnect; `false` stops reconnecting (a guest's ended share). */
+    readonly canRetry?: () => Promise<boolean>;
+    readonly onConnection?: (state: ConnectionState) => void;
+    /** Renders the app with its host, once the plugins are loaded. */
+    readonly render: (host: Client<P>["host"]) => void;
+    /**
+     * Records the page's telemetry (decision "Telemetry from browser pages"): its spans (a click started with
+     * `host.root(fn, ctx, { trace })`, the calls under it, carriers on its calls) are kept in memory and sent to the
+     * server's telemetry object every few seconds and when the page is hidden. Off by default.
+     */
+    readonly telemetry?: boolean;
+    /** Plugins left out or kept old, a failed update, the host's errors, messages' reports: the console by default. */
+    readonly onError?: (error: ClientError) => void;
+};
+/** Starts the page; resolves with its client once rendered. */
+export declare function startPage<P extends Principal>(options: PageOptions<P>): Promise<Client<P>>;
+//# sourceMappingURL=page.d.ts.map

package/dist/web/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/web/page.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACN,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EAKpB,MAAM,sBAAsB,CAAC;AAQ9B,8BAA8B;AAC9B,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,aAAa,CAAC;IACtC,2GAA2G;IAC3G,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1C,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACzD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,mHAAmH;IACnH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAChD,CAAC;AAKF,+DAA+D;AAC/D,wBAAsB,SAAS,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAiDhG"}