@earendil-works/chord 1.4.0 → 1.5.1

package/dist/surfaces/client.js

@@ -0,0 +1,264 @@
+// A client host with its plugins (slice 11 §2, §4, decisions "Slice 11, P4" to "P6"): what a page and a terminal's
+// sandbox both run. A client host (no address) loads the plugin scripts it started with beside the app's core facets,
+// keeps its link to the server with the connection loop, and holds the kind's scripts object: a new set fetches the
+// changed scripts and reloads the host in place (a failed plugin keeps its old facet; a failed fetch is tried again),
+// a page's new stylesheets loaded before the reload and each plugin left with the one of the code it runs; a new base
+// bundle means this client's code is outdated, which the app answers by starting over (a page reloads). The surface
+// specifics (how a socket opens, how a script is fetched, what is outdated, the stylesheets) are given.
+import { BACKGROUND_CONTEXT, withAbortSignal } from "../context/index.js";
+import { createHost } from "../host/index.js";
+import { keepConnected } from "./connection.js";
+import { LoadedFacets } from "./loaded.js";
+import { evaluateRegistered } from "./registered.js";
+/** Starts a client: its host loaded with the initial scripts, its link kept, its plugins kept current. */
+export async function startClient(options) {
+    const context = BACKGROUND_CONTEXT;
+    let made;
+    // Read at the first span, which starts once the host exists (in its load at the earliest).
+    const telemetry = options.telemetry?.(() => made.incarnation);
+    const host = createHost({ telemetry, onError: (error) => options.onError({ kind: "host", error }) });
+    made = host;
+    const entries = options.initial.map((script) => entryOf(script, options.modules));
+    const { loaded, report } = await LoadedFacets.load(host, options.core, entries, context);
+    if (report.failed.length > 0)
+        options.onError({ kind: "plugins", failed: report.failed });
+    const updates = new Updates(host, loaded, new Set(report.failed.map(({ plugin }) => plugin)), options);
+    const loop = connect(host, options, (state) => {
+        if (state === "connected")
+            updates.reconnected(context);
+    });
+    await updates.follow(context);
+    return {
+        host,
+        stop: async (ctx) => {
+            loop.stop();
+            await updates.stop();
+            await host.close(ctx);
+        },
+    };
+}
+/**
+ * Keeps `host`'s parent link to the server, asking `serverBase` and `canRetry` before every reconnect; `onState` hears
+ * each state after the app's `onConnection`.
+ */
+function connect(host, options, onState) {
+    return keepConnected({
+        open: (events) => {
+            // The loop and the host both follow the link's close; a link has one close listener.
+            const link = new SharedClose(options.open(events));
+            // A client's parent is the server; the principal only labels the link (a client serves no remote types).
+            host.connect(link, { principal: { kind: "server" } }, BACKGROUND_CONTEXT);
+            return link;
+        },
+        onState: (state) => {
+            options.onConnection?.(state);
+            onState(state);
+        },
+        canRetry: async () => {
+            const base = await options.serverBase();
+            if (base !== undefined && base !== options.base) {
+                options.outdated();
+                return false;
+            }
+            return (await options.canRetry?.()) ?? true;
+        },
+        environment: options.environment,
+    });
+}
+/** A link whose close several follow (the host and the connection loop): each listener added runs once it closes. */
+class SharedClose {
+    #link;
+    #listeners = [];
+    #closed = false;
+    constructor(link) {
+        this.#link = link;
+        link.onClose(() => {
+            this.#closed = true;
+            for (const listener of this.#listeners.splice(0))
+                listener();
+        });
+    }
+    send(message) {
+        this.#link.send(message);
+    }
+    onMessage(listener) {
+        this.#link.onMessage(listener);
+    }
+    close() {
+        this.#link.close();
+    }
+    onClose(listener) {
+        if (this.#closed)
+            listener();
+        else
+            this.#listeners.push(listener);
+    }
+}
+/** `script` as one plugin of a complete set: its digest, and its evaluation with `modules` when it is new. */
+function entryOf(script, modules) {
+    return {
+        name: script.plugin,
+        digest: script.digest,
+        prepare: () => {
+            try {
+                return { kind: "facet", facet: evaluateRegistered(script, modules), digest: script.digest };
+            }
+            catch (error) {
+                return { kind: "failed", error };
+            }
+        },
+    };
+}
+/** The first pause before a failed update is tried again: 1 s, doubling from there. */
+const UPDATE_RETRY_INITIAL_MS = 1000;
+/** The longest pause between tries of a failed update: 30 s. */
+const UPDATE_RETRY_MAX_MS = 30_000;
+/**
+ * The client's plugin updates: it holds the scripts object and applies each new set in order (fetching the changed
+ * scripts, loading their stylesheets, reloading the host with the complete set, settling the stylesheets); a new base
+ * calls `outdated` instead. An update that failed (a script that did not load) is tried again after a growing pause (1 s
+ * doubling to 30 s) until it applies or a newer set replaces it: the scripts object shows nothing new until the next
+ * rollout or reconnect.
+ */
+class Updates {
+    #host;
+    #loaded;
+    #options;
+    /**
+     * The script each plugin runs, by plugin: a plugin whose new script failed keeps its old one here, so a later set
+     * with that script (a reconnect's snapshot) tries it again.
+     */
+    #scripts = new Map();
+    #abort = new AbortController();
+    #release;
+    /** The newest set shown: a retry applies only it. */
+    #latest;
+    /** The updates in order: one at a time, a retry's among them. */
+    #applying = Promise.resolve();
+    /** The pending retry's cancel and the pause it waited (0: none waited yet). */
+    #retry;
+    #pause = 0;
+    constructor(host, loaded, left, options) {
+        this.#host = host;
+        this.#loaded = loaded;
+        this.#options = options;
+        for (const script of options.initial)
+            if (!left.has(script.plugin))
+                this.#scripts.set(script.plugin, script);
+    }
+    /** Holds the scripts object and applies every set it shows, the first included (a reconnect's snapshot too). */
+    async follow(context) {
+        const held = this.#host.hold(this.#options.scripts, {}, context);
+        this.#release = () => held.release();
+        const watch = await held.set.watch(withAbortSignal(this.#abort.signal, context));
+        watch.start(async (call, ctx) => {
+            if (call.kind !== "value")
+                return;
+            const set = call.value;
+            this.#latest = set;
+            this.#retry?.cancel();
+            this.#retry = undefined;
+            this.#pause = 0;
+            await this.#queue(set, ctx);
+        });
+    }
+    /**
+     * The link is back: the newest set is applied again when this client does not run all of it (a plugin kept its old
+     * code), since the scripts object shows an unchanged set no second time.
+     */
+    reconnected(context) {
+        const set = this.#latest;
+        if (set !== undefined && !this.#runsAll(set))
+            void this.#queue(set, context);
+    }
+    /** Stops following: the watch ends, the hold is released, a pending retry is dropped. */
+    async stop() {
+        this.#abort.abort();
+        this.#retry?.cancel();
+        this.#retry = undefined;
+        this.#release?.();
+    }
+    /** Applies `set` after the updates before it, unless a newer set replaced it meanwhile. */
+    #queue(set, context) {
+        const applied = this.#applying.then(async () => {
+            if (this.#latest !== set || this.#abort.signal.aborted)
+                return;
+            if (!(await this.#apply(set, context)))
+                this.#retryLater(set, context);
+        });
+        this.#applying = applied;
+        return applied;
+    }
+    /** Tries `set` again after the next pause (1 s doubling to 30 s). */
+    #retryLater(set, context) {
+        this.#pause = this.#pause === 0 ? UPDATE_RETRY_INITIAL_MS : Math.min(this.#pause * 2, UPDATE_RETRY_MAX_MS);
+        this.#retry = {
+            cancel: this.#options.environment.after(this.#pause, () => {
+                this.#retry = undefined;
+                void this.#queue(set, context);
+            }),
+        };
+    }
+    /**
+     * Applies `set`: a new base calls `outdated`; else the changed scripts fetched, their new stylesheets loaded, the
+     * host reloaded with all and the stylesheets settled. `false` when it failed (reported `update_failed`): it is tried
+     * again.
+     */
+    async #apply(set, context) {
+        const options = this.#options;
+        if (set.base !== options.base) {
+            options.outdated();
+            return true;
+        }
+        // The first frame usually shows what this client runs already: nothing to reload.
+        const changed = !this.#runsAll(set);
+        try {
+            const scripts = [];
+            if (changed) {
+                for (const entry of set.plugins) {
+                    const known = this.#scripts.get(entry.name);
+                    scripts.push(known?.digest === entry.digest ? known : await options.fetchScript(entry));
+                }
+            }
+            await options.styles?.prepare(set, this.#abort.signal);
+            if (this.#abort.signal.aborted)
+                return true;
+            const kept = changed ? await this.#reload(scripts, context) : new Set();
+            options.styles?.settle(set, kept);
+            return true;
+        }
+        catch (error) {
+            options.onError({ kind: "update_failed", error });
+            return false;
+        }
+    }
+    /** Whether this client runs every script of `set` and nothing else. */
+    #runsAll(set) {
+        const running = this.#scripts;
+        return (set.plugins.length === running.size &&
+            set.plugins.every((entry) => running.get(entry.name)?.digest === entry.digest));
+    }
+    /**
+     * Reloads the host with `scripts`, the complete set, and records the script each plugin runs now; the plugins that
+     * kept their old code (or, added, were left out).
+     */
+    async #reload(scripts, context) {
+        const options = this.#options;
+        const entries = scripts.map((script) => entryOf(script, options.modules));
+        const report = await this.#loaded.reload(this.#host, entries, context);
+        const kept = new Set(report.failed.map(({ plugin }) => plugin));
+        const running = new Map();
+        for (const script of scripts) {
+            const runs = kept.has(script.plugin) ? this.#scripts.get(script.plugin) : script;
+            if (runs !== undefined)
+                running.set(script.plugin, runs);
+        }
+        this.#scripts.clear();
+        for (const [plugin, script] of running)
+            this.#scripts.set(plugin, script);
+        if (report.failed.length > 0)
+            options.onError({ kind: "plugins", failed: report.failed });
+        return kept;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/surfaces/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/surfaces/client.ts"],"names":[],"mappings":"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","sourcesContent":["// A client host with its plugins (slice 11 §2, §4, decisions \"Slice 11, P4\" to \"P6\"): what a page and a terminal's\n// sandbox both run. A client host (no address) loads the plugin scripts it started with beside the app's core facets,\n// keeps its link to the server with the connection loop, and holds the kind's scripts object: a new set fetches the\n// changed scripts and reloads the host in place (a failed plugin keeps its old facet; a failed fetch is tried again),\n// a page's new stylesheets loaded before the reload and each plugin left with the one of the code it runs; a new base\n// bundle means this client's code is outdated, which the app answers by starting over (a page reloads). The surface\n// specifics (how a socket opens, how a script is fetched, what is outdated, the stylesheets) are given.\n\nimport type { TelemetryContext } from \"@earendil-works/pi-telemetry\";\nimport { BACKGROUND_CONTEXT, type Context, withAbortSignal } from \"../context/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport { createHost, type Host, type HostError, type PluginFacet, type PluginFailure } from \"../host/index.ts\";\nimport type { Link } from \"../link/index.ts\";\nimport { type ConnectionState, keepConnected, type LoopEnvironment, type SocketEvents } from \"./connection.ts\";\nimport type { MessagesReport } from \"./language.ts\";\nimport { LoadedFacets, type SetEntry } from \"./loaded.ts\";\nimport { type ClientModules, evaluateRegistered, type RegisteredScript } from \"./registered.ts\";\nimport type { ScriptEntry, ScriptSet, ScriptsContract } from \"./scripts.ts\";\n\n/**\n * What a client reports: its host's errors, plugins left out at a load or kept old at a reload, a failed update, a\n * plugin's stylesheet that did not load (`error`) or not within 10 s (`timeout`; this does not itself prevent the\n * plugin's new code).\n */\nexport type ClientError =\n\t| { readonly kind: \"host\"; readonly error: HostError }\n\t| { readonly kind: \"plugins\"; readonly failed: readonly PluginFailure[] }\n\t| { readonly kind: \"update_failed\"; readonly error: unknown }\n\t| {\n\t\t\treadonly kind: \"stylesheet_failed\";\n\t\t\treadonly plugin: string;\n\t\t\treadonly url: string;\n\t\t\treadonly reason: \"error\" | \"timeout\";\n\t  }\n\t/** A message rendered by a fallback, a contributed message that threw, a foreign message (each once). */\n\t| { readonly kind: \"messages\"; readonly report: MessagesReport };\n\n/** What `startClient` takes. */\nexport type ClientOptions<P extends Principal> = {\n\t/** The kind's scripts object (`WebScripts`, `TuiScripts`). */\n\treadonly scripts: ScriptsContract;\n\t/** The hash of the base bundle this client runs. */\n\treadonly base: string;\n\t/** The plugin scripts it started with (the combined file's), in any order. */\n\treadonly initial: readonly RegisteredScript[];\n\t/** The modules its plugin scripts import, by specifier. */\n\treadonly modules: ClientModules;\n\t/** The app's own facets, loaded with the plugins. */\n\treadonly core: readonly PluginFacet<P>[];\n\t/** Opens one socket to the server and its link; the socket reports to `events`. */\n\treadonly open: (events: SocketEvents) => Link;\n\t/** Fetches a plugin's script of a set (at its `url`), which registers itself. */\n\treadonly fetchScript: (entry: ScriptEntry) => Promise<RegisteredScript>;\n\t/**\n\t * The server's current base bundle hash, asked before each reconnect (`undefined`: unknown, try again): another one\n\t * means this client is outdated (a new protocol comes with a new base bundle).\n\t */\n\treadonly serverBase: () => Promise<string | undefined>;\n\t/** This client's code is outdated: the app starts it over (a page reloads); the loop has stopped. */\n\treadonly outdated: () => void;\n\t/** Asked before each reconnect; `false` stops the loop (a guest's ended share). */\n\treadonly canRetry?: () => Promise<boolean>;\n\treadonly onConnection?: (state: ConnectionState) => void;\n\t/** The plugins' stylesheets (a page's; a terminal has none). */\n\treadonly styles?: ClientStyles;\n\treadonly environment: LoopEnvironment;\n\t/**\n\t * Makes the host's telemetry adapter (none: NOOP); `incarnation` names the host's run (it is read at the adapter's\n\t * first span, after the host was made).\n\t */\n\treadonly telemetry?: (incarnation: () => string) => TelemetryContext;\n\treadonly onError: (error: ClientError) => void;\n};\n\n/**\n * A page's plugin stylesheets around each update: `prepare` before the host reloads, `settle` after it (or alone when\n * no script changed).\n */\nexport type ClientStyles = {\n\t/**\n\t * Fetches, without applying them, the stylesheets of `set` that differ from those of the code each plugin runs or\n\t * did not load; resolves once each loaded, failed or waited 10 s, or when `signal` aborts (the client stops: what it\n\t * prepared is removed, `settle` never follows).\n\t */\n\tprepare(set: ScriptSet, signal: AbortSignal): Promise<void>;\n\t/**\n\t * Applies each prepared stylesheet whose plugin runs its new code now and retires the one it replaces; a plugin that\n\t * `kept` names (its new script failed: it kept its old code) keeps its old one, its prepared one dropped unapplied;\n\t * the stylesheets of plugins no longer in `set` go.\n\t */\n\tsettle(set: ScriptSet, kept: ReadonlySet<string>): void;\n};\n\n/** A running client: its host, once its plugins are loaded, and its stop. */\nexport type Client<P extends Principal> = { readonly host: Host<P>; stop(context: Context): Promise<void> };\n\n/** Starts a client: its host loaded with the initial scripts, its link kept, its plugins kept current. */\nexport async function startClient<P extends Principal>(options: ClientOptions<P>): Promise<Client<P>> {\n\tconst context = BACKGROUND_CONTEXT;\n\tlet made: Host<P> | undefined;\n\t// Read at the first span, which starts once the host exists (in its load at the earliest).\n\tconst telemetry = options.telemetry?.(() => made!.incarnation);\n\tconst host = createHost<P>({ telemetry, onError: (error) => options.onError({ kind: \"host\", error }) });\n\tmade = host;\n\tconst entries = options.initial.map((script) => entryOf(script, options.modules));\n\tconst { loaded, report } = await LoadedFacets.load(host, options.core, entries, context);\n\tif (report.failed.length > 0) options.onError({ kind: \"plugins\", failed: report.failed });\n\tconst updates = new Updates(host, loaded, new Set(report.failed.map(({ plugin }) => plugin)), options);\n\tconst loop = connect(host, options, (state) => {\n\t\tif (state === \"connected\") updates.reconnected(context);\n\t});\n\tawait updates.follow(context);\n\treturn {\n\t\thost,\n\t\tstop: async (ctx) => {\n\t\t\tloop.stop();\n\t\t\tawait updates.stop();\n\t\t\tawait host.close(ctx);\n\t\t},\n\t};\n}\n\n/**\n * Keeps `host`'s parent link to the server, asking `serverBase` and `canRetry` before every reconnect; `onState` hears\n * each state after the app's `onConnection`.\n */\nfunction connect<P extends Principal>(\n\thost: Host<P>,\n\toptions: ClientOptions<P>,\n\tonState: (state: ConnectionState) => void,\n): { stop(): void } {\n\treturn keepConnected({\n\t\topen: (events) => {\n\t\t\t// The loop and the host both follow the link's close; a link has one close listener.\n\t\t\tconst link = new SharedClose(options.open(events));\n\t\t\t// A client's parent is the server; the principal only labels the link (a client serves no remote types).\n\t\t\thost.connect(link, { principal: { kind: \"server\" } as unknown as P }, BACKGROUND_CONTEXT);\n\t\t\treturn link;\n\t\t},\n\t\tonState: (state) => {\n\t\t\toptions.onConnection?.(state);\n\t\t\tonState(state);\n\t\t},\n\t\tcanRetry: async () => {\n\t\t\tconst base = await options.serverBase();\n\t\t\tif (base !== undefined && base !== options.base) {\n\t\t\t\toptions.outdated();\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\treturn (await options.canRetry?.()) ?? true;\n\t\t},\n\t\tenvironment: options.environment,\n\t});\n}\n\n/** A link whose close several follow (the host and the connection loop): each listener added runs once it closes. */\nclass SharedClose implements Link {\n\treadonly #link: Link;\n\treadonly #listeners: (() => void)[] = [];\n\t#closed = false;\n\n\tconstructor(link: Link) {\n\t\tthis.#link = link;\n\t\tlink.onClose(() => {\n\t\t\tthis.#closed = true;\n\t\t\tfor (const listener of this.#listeners.splice(0)) listener();\n\t\t});\n\t}\n\n\tsend(message: Uint8Array): void {\n\t\tthis.#link.send(message);\n\t}\n\n\tonMessage(listener: (message: Uint8Array) => void): void {\n\t\tthis.#link.onMessage(listener);\n\t}\n\n\tclose(): void {\n\t\tthis.#link.close();\n\t}\n\n\tonClose(listener: () => void): void {\n\t\tif (this.#closed) listener();\n\t\telse this.#listeners.push(listener);\n\t}\n}\n\n/** `script` as one plugin of a complete set: its digest, and its evaluation with `modules` when it is new. */\nfunction entryOf(script: RegisteredScript, modules: ClientModules): SetEntry {\n\treturn {\n\t\tname: script.plugin,\n\t\tdigest: script.digest,\n\t\tprepare: () => {\n\t\t\ttry {\n\t\t\t\treturn { kind: \"facet\", facet: evaluateRegistered(script, modules), digest: script.digest };\n\t\t\t} catch (error) {\n\t\t\t\treturn { kind: \"failed\", error };\n\t\t\t}\n\t\t},\n\t};\n}\n\n/** The first pause before a failed update is tried again: 1 s, doubling from there. */\nconst UPDATE_RETRY_INITIAL_MS = 1000;\n\n/** The longest pause between tries of a failed update: 30 s. */\nconst UPDATE_RETRY_MAX_MS = 30_000;\n\n/**\n * The client's plugin updates: it holds the scripts object and applies each new set in order (fetching the changed\n * scripts, loading their stylesheets, reloading the host with the complete set, settling the stylesheets); a new base\n * calls `outdated` instead. An update that failed (a script that did not load) is tried again after a growing pause (1 s\n * doubling to 30 s) until it applies or a newer set replaces it: the scripts object shows nothing new until the next\n * rollout or reconnect.\n */\nclass Updates<P extends Principal> {\n\treadonly #host: Host<P>;\n\treadonly #loaded: LoadedFacets;\n\treadonly #options: ClientOptions<P>;\n\t/**\n\t * The script each plugin runs, by plugin: a plugin whose new script failed keeps its old one here, so a later set\n\t * with that script (a reconnect's snapshot) tries it again.\n\t */\n\treadonly #scripts = new Map<string, RegisteredScript>();\n\treadonly #abort = new AbortController();\n\t#release: (() => void) | undefined;\n\t/** The newest set shown: a retry applies only it. */\n\t#latest: ScriptSet | undefined;\n\t/** The updates in order: one at a time, a retry's among them. */\n\t#applying: Promise<void> = Promise.resolve();\n\t/** The pending retry's cancel and the pause it waited (0: none waited yet). */\n\t#retry: { cancel: () => void } | undefined;\n\t#pause = 0;\n\n\tconstructor(host: Host<P>, loaded: LoadedFacets, left: ReadonlySet<string>, options: ClientOptions<P>) {\n\t\tthis.#host = host;\n\t\tthis.#loaded = loaded;\n\t\tthis.#options = options;\n\t\tfor (const script of options.initial) if (!left.has(script.plugin)) this.#scripts.set(script.plugin, script);\n\t}\n\n\t/** Holds the scripts object and applies every set it shows, the first included (a reconnect's snapshot too). */\n\tasync follow(context: Context): Promise<void> {\n\t\tconst held = this.#host.hold(this.#options.scripts, {}, context);\n\t\tthis.#release = () => held.release();\n\t\tconst watch = await held.set.watch(withAbortSignal(this.#abort.signal, context));\n\t\twatch.start(async (call, ctx) => {\n\t\t\tif (call.kind !== \"value\") return;\n\t\t\tconst set = call.value as ScriptSet;\n\t\t\tthis.#latest = set;\n\t\t\tthis.#retry?.cancel();\n\t\t\tthis.#retry = undefined;\n\t\t\tthis.#pause = 0;\n\t\t\tawait this.#queue(set, ctx);\n\t\t});\n\t}\n\n\t/**\n\t * The link is back: the newest set is applied again when this client does not run all of it (a plugin kept its old\n\t * code), since the scripts object shows an unchanged set no second time.\n\t */\n\treconnected(context: Context): void {\n\t\tconst set = this.#latest;\n\t\tif (set !== undefined && !this.#runsAll(set)) void this.#queue(set, context);\n\t}\n\n\t/** Stops following: the watch ends, the hold is released, a pending retry is dropped. */\n\tasync stop(): Promise<void> {\n\t\tthis.#abort.abort();\n\t\tthis.#retry?.cancel();\n\t\tthis.#retry = undefined;\n\t\tthis.#release?.();\n\t}\n\n\t/** Applies `set` after the updates before it, unless a newer set replaced it meanwhile. */\n\t#queue(set: ScriptSet, context: Context): Promise<void> {\n\t\tconst applied = this.#applying.then(async () => {\n\t\t\tif (this.#latest !== set || this.#abort.signal.aborted) return;\n\t\t\tif (!(await this.#apply(set, context))) this.#retryLater(set, context);\n\t\t});\n\t\tthis.#applying = applied;\n\t\treturn applied;\n\t}\n\n\t/** Tries `set` again after the next pause (1 s doubling to 30 s). */\n\t#retryLater(set: ScriptSet, context: Context): void {\n\t\tthis.#pause = this.#pause === 0 ? UPDATE_RETRY_INITIAL_MS : Math.min(this.#pause * 2, UPDATE_RETRY_MAX_MS);\n\t\tthis.#retry = {\n\t\t\tcancel: this.#options.environment.after(this.#pause, () => {\n\t\t\t\tthis.#retry = undefined;\n\t\t\t\tvoid this.#queue(set, context);\n\t\t\t}),\n\t\t};\n\t}\n\n\t/**\n\t * Applies `set`: a new base calls `outdated`; else the changed scripts fetched, their new stylesheets loaded, the\n\t * host reloaded with all and the stylesheets settled. `false` when it failed (reported `update_failed`): it is tried\n\t * again.\n\t */\n\tasync #apply(set: ScriptSet, context: Context): Promise<boolean> {\n\t\tconst options = this.#options;\n\t\tif (set.base !== options.base) {\n\t\t\toptions.outdated();\n\t\t\treturn true;\n\t\t}\n\t\t// The first frame usually shows what this client runs already: nothing to reload.\n\t\tconst changed = !this.#runsAll(set);\n\t\ttry {\n\t\t\tconst scripts: RegisteredScript[] = [];\n\t\t\tif (changed) {\n\t\t\t\tfor (const entry of set.plugins) {\n\t\t\t\t\tconst known = this.#scripts.get(entry.name);\n\t\t\t\t\tscripts.push(known?.digest === entry.digest ? known : await options.fetchScript(entry));\n\t\t\t\t}\n\t\t\t}\n\t\t\tawait options.styles?.prepare(set, this.#abort.signal);\n\t\t\tif (this.#abort.signal.aborted) return true;\n\t\t\tconst kept = changed ? await this.#reload(scripts, context) : new Set<string>();\n\t\t\toptions.styles?.settle(set, kept);\n\t\t\treturn true;\n\t\t} catch (error) {\n\t\t\toptions.onError({ kind: \"update_failed\", error });\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Whether this client runs every script of `set` and nothing else. */\n\t#runsAll(set: ScriptSet): boolean {\n\t\tconst running = this.#scripts;\n\t\treturn (\n\t\t\tset.plugins.length === running.size &&\n\t\t\tset.plugins.every((entry) => running.get(entry.name)?.digest === entry.digest)\n\t\t);\n\t}\n\n\t/**\n\t * Reloads the host with `scripts`, the complete set, and records the script each plugin runs now; the plugins that\n\t * kept their old code (or, added, were left out).\n\t */\n\tasync #reload(scripts: readonly RegisteredScript[], context: Context): Promise<ReadonlySet<string>> {\n\t\tconst options = this.#options;\n\t\tconst entries = scripts.map((script) => entryOf(script, options.modules));\n\t\tconst report = await this.#loaded.reload(this.#host, entries, context);\n\t\tconst kept = new Set(report.failed.map(({ plugin }) => plugin));\n\t\tconst running = new Map<string, RegisteredScript>();\n\t\tfor (const script of scripts) {\n\t\t\tconst runs = kept.has(script.plugin) ? this.#scripts.get(script.plugin) : script;\n\t\t\tif (runs !== undefined) running.set(script.plugin, runs);\n\t\t}\n\t\tthis.#scripts.clear();\n\t\tfor (const [plugin, script] of running) this.#scripts.set(plugin, script);\n\t\tif (report.failed.length > 0) options.onError({ kind: \"plugins\", failed: report.failed });\n\t\treturn kept;\n\t}\n}\n"]}

package/dist/surfaces/connection.d.ts

@@ -0,0 +1,49 @@
+/** The first retry pause after a failed or short-lived connection: 250 ms, doubling from there. */
+export declare const RETRY_INITIAL_MS = 250;
+/** The longest retry pause: 5 s (and the pause while offline). */
+export declare const RETRY_MAX_MS = 5000;
+/** A connection that stayed open this long counted as working: the next retry starts at the initial pause again. */
+export declare const STABLE_MS = 10000;
+/** A socket not open after this long is given up (browsers have no handshake timeout). */
+export declare const CONNECT_TIMEOUT_MS = 20000;
+/** The server's heartbeat pings every 15 s: an open socket silent for longer than this is presumed dead on a wake. */
+export declare const STALE_MS = 25000;
+/** After a wake, messages held while the client was frozen get this long to arrive before the socket is judged. */
+export declare const WAKE_GRACE_MS = 1000;
+/** The connection as the app shows it: an attempt under way, open, or waiting for the next attempt. */
+export type ConnectionState = "connecting" | "connected" | "waiting";
+/** What one socket reports to the loop. */
+export interface SocketEvents {
+    opened(): void;
+    /** Any frame: the server's pings keep an open socket from looking silent. */
+    received(): void;
+}
+/** One attempt's connection as the loop sees it: it closes once, and closing it ends it at once. */
+export interface LoopLink {
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/** What the loop runs in: the clock, timers, whether the device is online, and its wake events. */
+export interface LoopEnvironment {
+    now(): number;
+    /** Runs `callback` after `ms`; returns its cancel. */
+    after(ms: number, callback: () => void): () => void;
+    /** `false` when the device is known to be offline. */
+    online(): boolean;
+    /** Calls `listener` when the client may have been away (visible again, online, network changed); returns its removal. */
+    onWake(listener: () => void): () => void;
+}
+/** What the loop takes. */
+export type LoopOptions = {
+    /** Opens one socket and its link; the socket reports to `events`. */
+    readonly open: (events: SocketEvents) => LoopLink;
+    readonly onState: (state: ConnectionState) => void;
+    /** Asked after every close; `false` stops the loop. A rejection counts as `true` (unreachable, try again). */
+    readonly canRetry: () => Promise<boolean>;
+    readonly environment: LoopEnvironment;
+};
+/** Keeps a client connected until `stop`. */
+export declare function keepConnected(options: LoopOptions): {
+    stop(): void;
+};
+//# sourceMappingURL=connection.d.ts.map

package/dist/surfaces/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/surfaces/connection.ts"],"names":[],"mappings":"AAOA,mGAAmG;AACnG,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,kEAAkE;AAClE,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,oHAAoH;AACpH,eAAO,MAAM,SAAS,QAAS,CAAC;AAEhC,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,sHAAsH;AACtH,eAAO,MAAM,QAAQ,QAAS,CAAC;AAE/B,mHAAmH;AACnH,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,uGAAuG;AACvG,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;AAErE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC5B,MAAM,IAAI,IAAI,CAAC;IACf,6EAA6E;IAC7E,QAAQ,IAAI,IAAI,CAAC;CACjB;AAED,oGAAoG;AACpG,MAAM,WAAW,QAAQ;IACxB,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;CACd;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC/B,GAAG,IAAI,MAAM,CAAC;IACd,sDAAsD;IACtD,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACpD,sDAAsD;IACtD,MAAM,IAAI,OAAO,CAAC;IAClB,yHAAyH;IACzH,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CACzC;AAED,2BAA2B;AAC3B,MAAM,MAAM,WAAW,GAAG;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,QAAQ,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACnD,8GAA8G;IAC9G,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;CACtC,CAAC;AAEF,6CAA6C;AAC7C,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG;IAAE,IAAI,IAAI,IAAI,CAAA;CAAE,CAIpE"}

package/dist/surfaces/connection.js

@@ -0,0 +1,142 @@
+// The connection loop (slice 11 §2, decision "Slice 11, P6"; p2's `keepConnected`): a client keeps one link to the
+// server and replaces it when it ends. After a drop it reconnects after a growing pause (250 ms doubling to 5 s; a
+// connection that stayed open 10 s resets it), at once on a wake (visible again, back online, network changed); it
+// replaces an open socket silent past the server's ping interval on a wake, gives up a socket not open after 20 s, and
+// stops when the app's `canRetry` says no (an outdated client, a guest's ended share). The environment (time, timers,
+// wakes) is given, so the same loop runs in a page and in a terminal's sandbox.
+/** The first retry pause after a failed or short-lived connection: 250 ms, doubling from there. */
+export const RETRY_INITIAL_MS = 250;
+/** The longest retry pause: 5 s (and the pause while offline). */
+export const RETRY_MAX_MS = 5000;
+/** A connection that stayed open this long counted as working: the next retry starts at the initial pause again. */
+export const STABLE_MS = 10_000;
+/** A socket not open after this long is given up (browsers have no handshake timeout). */
+export const CONNECT_TIMEOUT_MS = 20_000;
+/** The server's heartbeat pings every 15 s: an open socket silent for longer than this is presumed dead on a wake. */
+export const STALE_MS = 25_000;
+/** After a wake, messages held while the client was frozen get this long to arrive before the socket is judged. */
+export const WAKE_GRACE_MS = 1000;
+/** Keeps a client connected until `stop`. */
+export function keepConnected(options) {
+    const loop = new Loop(options);
+    loop.connect();
+    return { stop: () => loop.stop() };
+}
+class Loop {
+    #options;
+    #env;
+    #removeWake;
+    #failures = 0;
+    #current;
+    #cancelRetry;
+    #cancelStaleCheck;
+    /** Between a close and `canRetry`'s answer; a wake meanwhile retries at once. */
+    #deciding = false;
+    #wokeWhileDeciding = false;
+    #stopped = false;
+    constructor(options) {
+        this.#options = options;
+        this.#env = options.environment;
+        this.#removeWake = this.#env.onWake(() => this.#wake());
+    }
+    /** Starts an attempt. */
+    connect() {
+        this.#cancelRetry = undefined;
+        const env = this.#env;
+        const attempt = {
+            link: undefined,
+            startedAt: env.now(),
+            openedAt: undefined,
+            lastFrame: env.now(),
+            cancelTimeout: () => { },
+        };
+        this.#current = attempt;
+        this.#options.onState("connecting");
+        const link = this.#options.open({
+            opened: () => {
+                if (this.#current !== attempt)
+                    return;
+                attempt.openedAt = attempt.lastFrame = env.now();
+                attempt.cancelTimeout();
+                this.#options.onState("connected");
+            },
+            received: () => {
+                attempt.lastFrame = env.now();
+            },
+        });
+        attempt.link = link;
+        attempt.cancelTimeout = env.after(CONNECT_TIMEOUT_MS, () => {
+            if (attempt.openedAt === undefined)
+                link.close();
+        });
+        link.onClose(() => this.#closed(attempt));
+    }
+    /** Stops the loop and closes the current link. */
+    stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#removeWake();
+        this.#cancelRetry?.();
+        this.#cancelRetry = undefined;
+        this.#current?.link?.close();
+    }
+    /** `attempt`'s link closed: asks `canRetry`, then schedules the next attempt. */
+    #closed(attempt) {
+        if (this.#current !== attempt)
+            return;
+        this.#current = undefined;
+        attempt.cancelTimeout();
+        this.#cancelStaleCheck?.();
+        this.#cancelStaleCheck = undefined;
+        if (this.#stopped)
+            return;
+        this.#options.onState("waiting");
+        const { openedAt } = attempt;
+        if (openedAt !== undefined && this.#env.now() - openedAt >= STABLE_MS)
+            this.#failures = 0;
+        this.#deciding = true;
+        this.#wokeWhileDeciding = false;
+        const decided = (retry) => {
+            this.#deciding = false;
+            if (retry)
+                this.#schedule(this.#wokeWhileDeciding);
+        };
+        this.#options.canRetry().then(decided, () => decided(true));
+    }
+    /** Schedules the next attempt: at once (`now`), else after the backoff (offline: the longest pause). */
+    #schedule(now) {
+        if (this.#stopped)
+            return;
+        const backoff = Math.min(RETRY_MAX_MS, RETRY_INITIAL_MS * 2 ** this.#failures);
+        this.#failures += 1;
+        // Offline an attempt fails at once; the `online` wake retries sooner than this.
+        const delay = now ? 0 : this.#env.online() ? backoff : RETRY_MAX_MS;
+        this.#cancelRetry = this.#env.after(delay, () => this.connect());
+    }
+    /** A wake: a pending retry runs now; an open socket silent too long is replaced once its overdue ping is checked. */
+    #wake() {
+        if (this.#cancelRetry !== undefined) {
+            this.#cancelRetry();
+            this.connect();
+            return;
+        }
+        if (this.#deciding) {
+            this.#wokeWhileDeciding = true;
+            return;
+        }
+        const attempt = this.#current;
+        // A connecting attempt has its own timeout.
+        if (attempt?.openedAt === undefined)
+            return;
+        this.#cancelStaleCheck?.();
+        // After a network change the socket looks fine until the server's next ping is missing: check when it is due.
+        const due = Math.max(WAKE_GRACE_MS, attempt.lastFrame + STALE_MS + 1 - this.#env.now());
+        this.#cancelStaleCheck = this.#env.after(due, () => {
+            this.#cancelStaleCheck = undefined;
+            if (this.#current === attempt && this.#env.now() - attempt.lastFrame > STALE_MS)
+                attempt.link?.close();
+        });
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/surfaces/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/surfaces/connection.ts"],"names":[],"mappings":"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","sourcesContent":["// The connection loop (slice 11 §2, decision \"Slice 11, P6\"; p2's `keepConnected`): a client keeps one link to the\n// server and replaces it when it ends. After a drop it reconnects after a growing pause (250 ms doubling to 5 s; a\n// connection that stayed open 10 s resets it), at once on a wake (visible again, back online, network changed); it\n// replaces an open socket silent past the server's ping interval on a wake, gives up a socket not open after 20 s, and\n// stops when the app's `canRetry` says no (an outdated client, a guest's ended share). The environment (time, timers,\n// wakes) is given, so the same loop runs in a page and in a terminal's sandbox.\n\n/** The first retry pause after a failed or short-lived connection: 250 ms, doubling from there. */\nexport const RETRY_INITIAL_MS = 250;\n\n/** The longest retry pause: 5 s (and the pause while offline). */\nexport const RETRY_MAX_MS = 5000;\n\n/** A connection that stayed open this long counted as working: the next retry starts at the initial pause again. */\nexport const STABLE_MS = 10_000;\n\n/** A socket not open after this long is given up (browsers have no handshake timeout). */\nexport const CONNECT_TIMEOUT_MS = 20_000;\n\n/** The server's heartbeat pings every 15 s: an open socket silent for longer than this is presumed dead on a wake. */\nexport const STALE_MS = 25_000;\n\n/** After a wake, messages held while the client was frozen get this long to arrive before the socket is judged. */\nexport const WAKE_GRACE_MS = 1000;\n\n/** The connection as the app shows it: an attempt under way, open, or waiting for the next attempt. */\nexport type ConnectionState = \"connecting\" | \"connected\" | \"waiting\";\n\n/** What one socket reports to the loop. */\nexport interface SocketEvents {\n\topened(): void;\n\t/** Any frame: the server's pings keep an open socket from looking silent. */\n\treceived(): void;\n}\n\n/** One attempt's connection as the loop sees it: it closes once, and closing it ends it at once. */\nexport interface LoopLink {\n\tonClose(listener: () => void): void;\n\tclose(): void;\n}\n\n/** What the loop runs in: the clock, timers, whether the device is online, and its wake events. */\nexport interface LoopEnvironment {\n\tnow(): number;\n\t/** Runs `callback` after `ms`; returns its cancel. */\n\tafter(ms: number, callback: () => void): () => void;\n\t/** `false` when the device is known to be offline. */\n\tonline(): boolean;\n\t/** Calls `listener` when the client may have been away (visible again, online, network changed); returns its removal. */\n\tonWake(listener: () => void): () => void;\n}\n\n/** What the loop takes. */\nexport type LoopOptions = {\n\t/** Opens one socket and its link; the socket reports to `events`. */\n\treadonly open: (events: SocketEvents) => LoopLink;\n\treadonly onState: (state: ConnectionState) => void;\n\t/** Asked after every close; `false` stops the loop. A rejection counts as `true` (unreachable, try again). */\n\treadonly canRetry: () => Promise<boolean>;\n\treadonly environment: LoopEnvironment;\n};\n\n/** Keeps a client connected until `stop`. */\nexport function keepConnected(options: LoopOptions): { stop(): void } {\n\tconst loop = new Loop(options);\n\tloop.connect();\n\treturn { stop: () => loop.stop() };\n}\n\n/** One attempt: its link, when it started and opened, its last frame, its timeout's cancel. */\ntype Attempt = {\n\tlink: LoopLink | undefined;\n\treadonly startedAt: number;\n\topenedAt: number | undefined;\n\tlastFrame: number;\n\tcancelTimeout: () => void;\n};\n\nclass Loop {\n\treadonly #options: LoopOptions;\n\treadonly #env: LoopEnvironment;\n\treadonly #removeWake: () => void;\n\t#failures = 0;\n\t#current: Attempt | undefined;\n\t#cancelRetry: (() => void) | undefined;\n\t#cancelStaleCheck: (() => void) | undefined;\n\t/** Between a close and `canRetry`'s answer; a wake meanwhile retries at once. */\n\t#deciding = false;\n\t#wokeWhileDeciding = false;\n\t#stopped = false;\n\n\tconstructor(options: LoopOptions) {\n\t\tthis.#options = options;\n\t\tthis.#env = options.environment;\n\t\tthis.#removeWake = this.#env.onWake(() => this.#wake());\n\t}\n\n\t/** Starts an attempt. */\n\tconnect(): void {\n\t\tthis.#cancelRetry = undefined;\n\t\tconst env = this.#env;\n\t\tconst attempt: Attempt = {\n\t\t\tlink: undefined,\n\t\t\tstartedAt: env.now(),\n\t\t\topenedAt: undefined,\n\t\t\tlastFrame: env.now(),\n\t\t\tcancelTimeout: () => {},\n\t\t};\n\t\tthis.#current = attempt;\n\t\tthis.#options.onState(\"connecting\");\n\t\tconst link = this.#options.open({\n\t\t\topened: () => {\n\t\t\t\tif (this.#current !== attempt) return;\n\t\t\t\tattempt.openedAt = attempt.lastFrame = env.now();\n\t\t\t\tattempt.cancelTimeout();\n\t\t\t\tthis.#options.onState(\"connected\");\n\t\t\t},\n\t\t\treceived: () => {\n\t\t\t\tattempt.lastFrame = env.now();\n\t\t\t},\n\t\t});\n\t\tattempt.link = link;\n\t\tattempt.cancelTimeout = env.after(CONNECT_TIMEOUT_MS, () => {\n\t\t\tif (attempt.openedAt === undefined) link.close();\n\t\t});\n\t\tlink.onClose(() => this.#closed(attempt));\n\t}\n\n\t/** Stops the loop and closes the current link. */\n\tstop(): void {\n\t\tif (this.#stopped) return;\n\t\tthis.#stopped = true;\n\t\tthis.#removeWake();\n\t\tthis.#cancelRetry?.();\n\t\tthis.#cancelRetry = undefined;\n\t\tthis.#current?.link?.close();\n\t}\n\n\t/** `attempt`'s link closed: asks `canRetry`, then schedules the next attempt. */\n\t#closed(attempt: Attempt): void {\n\t\tif (this.#current !== attempt) return;\n\t\tthis.#current = undefined;\n\t\tattempt.cancelTimeout();\n\t\tthis.#cancelStaleCheck?.();\n\t\tthis.#cancelStaleCheck = undefined;\n\t\tif (this.#stopped) return;\n\t\tthis.#options.onState(\"waiting\");\n\t\tconst { openedAt } = attempt;\n\t\tif (openedAt !== undefined && this.#env.now() - openedAt >= STABLE_MS) this.#failures = 0;\n\t\tthis.#deciding = true;\n\t\tthis.#wokeWhileDeciding = false;\n\t\tconst decided = (retry: boolean): void => {\n\t\t\tthis.#deciding = false;\n\t\t\tif (retry) this.#schedule(this.#wokeWhileDeciding);\n\t\t};\n\t\tthis.#options.canRetry().then(decided, () => decided(true));\n\t}\n\n\t/** Schedules the next attempt: at once (`now`), else after the backoff (offline: the longest pause). */\n\t#schedule(now: boolean): void {\n\t\tif (this.#stopped) return;\n\t\tconst backoff = Math.min(RETRY_MAX_MS, RETRY_INITIAL_MS * 2 ** this.#failures);\n\t\tthis.#failures += 1;\n\t\t// Offline an attempt fails at once; the `online` wake retries sooner than this.\n\t\tconst delay = now ? 0 : this.#env.online() ? backoff : RETRY_MAX_MS;\n\t\tthis.#cancelRetry = this.#env.after(delay, () => this.connect());\n\t}\n\n\t/** A wake: a pending retry runs now; an open socket silent too long is replaced once its overdue ping is checked. */\n\t#wake(): void {\n\t\tif (this.#cancelRetry !== undefined) {\n\t\t\tthis.#cancelRetry();\n\t\t\tthis.connect();\n\t\t\treturn;\n\t\t}\n\t\tif (this.#deciding) {\n\t\t\tthis.#wokeWhileDeciding = true;\n\t\t\treturn;\n\t\t}\n\t\tconst attempt = this.#current;\n\t\t// A connecting attempt has its own timeout.\n\t\tif (attempt?.openedAt === undefined) return;\n\t\tthis.#cancelStaleCheck?.();\n\t\t// After a network change the socket looks fine until the server's next ping is missing: check when it is due.\n\t\tconst due = Math.max(WAKE_GRACE_MS, attempt.lastFrame + STALE_MS + 1 - this.#env.now());\n\t\tthis.#cancelStaleCheck = this.#env.after(due, () => {\n\t\t\tthis.#cancelStaleCheck = undefined;\n\t\t\tif (this.#current === attempt && this.#env.now() - attempt.lastFrame > STALE_MS) attempt.link?.close();\n\t\t});\n\t}\n}\n"]}

package/dist/surfaces/format.d.ts

@@ -0,0 +1,5 @@
+/** A time (a `Date`, milliseconds, or an ISO string as messages carry it) in the current locale; `14:05` by default. */
+export declare function formatTime(at: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+/** A number in the current locale (`1.234,5` in German). */
+export declare function formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/surfaces/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/surfaces/format.ts"],"names":[],"mappings":"AAMA,wHAAwH;AACxH,wBAAgB,UAAU,CAAC,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAAG,MAAM,CAOnG;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAOtF"}

package/dist/surfaces/format.js

@@ -0,0 +1,37 @@
+// Dates, times and numbers in the viewer's locale (decision "Messages and languages in the app kit" (1)): `Intl` with
+// the current language's locale, so a message function's `formatTime(at)` follows the language it renders in. Outside a
+// render the platform's default locale applies. A language's default formatters are made once, kept as long as it is.
+import { currentLanguage } from "./language.js";
+/** A time (a `Date`, milliseconds, or an ISO string as messages carry it) in the current locale; `14:05` by default. */
+export function formatTime(at, options) {
+    const language = currentLanguage();
+    const format = options === undefined && language !== undefined
+        ? formattersOf(language).time
+        : new Intl.DateTimeFormat(language?.locale, options ?? TIME);
+    return format.format(new Date(at));
+}
+/** A number in the current locale (`1.234,5` in German). */
+export function formatNumber(value, options) {
+    const language = currentLanguage();
+    const format = options === undefined && language !== undefined
+        ? formattersOf(language).number
+        : new Intl.NumberFormat(language?.locale, options);
+    return format.format(value);
+}
+/** `formatTime`'s default: hours and minutes. */
+const TIME = { timeStyle: "short" };
+/** The default formatters of each language, made at its first use: a formatter costs far more than a format. */
+const FORMATTERS = new WeakMap();
+/** `language`'s default formatters. */
+function formattersOf(language) {
+    let formatters = FORMATTERS.get(language);
+    if (formatters === undefined) {
+        formatters = {
+            time: new Intl.DateTimeFormat(language.locale, TIME),
+            number: new Intl.NumberFormat(language.locale),
+        };
+        FORMATTERS.set(language, formatters);
+    }
+    return formatters;
+}
+//# sourceMappingURL=format.js.map

package/dist/surfaces/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/surfaces/format.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,wHAAwH;AACxH,sHAAsH;AAEtH,OAAO,EAAE,eAAe,EAAiB,MAAM,eAAe,CAAC;AAE/D,wHAAwH;AACxH,MAAM,UAAU,UAAU,CAAC,EAA0B,EAAE,OAAoC;IAC1F,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,MAAM,MAAM,GACX,OAAO,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS;QAC9C,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,IAAI;QAC7B,CAAC,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,OAAkC;IAC7E,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,MAAM,MAAM,GACX,OAAO,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS;QAC9C,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,MAAM;QAC/B,CAAC,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,iDAAiD;AACjD,MAAM,IAAI,GAA+B,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAKhE,gHAAgH;AAChH,MAAM,UAAU,GAAG,IAAI,OAAO,EAAwB,CAAC;AAEvD,uCAAuC;AACvC,SAAS,YAAY,CAAC,QAAkB;IACvC,IAAI,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC9B,UAAU,GAAG;YACZ,IAAI,EAAE,IAAI,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;YACpD,MAAM,EAAE,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC;SAC9C,CAAC;QACF,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,UAAU,CAAC;AACnB,CAAC","sourcesContent":["// Dates, times and numbers in the viewer's locale (decision \"Messages and languages in the app kit\" (1)): `Intl` with\n// the current language's locale, so a message function's `formatTime(at)` follows the language it renders in. Outside a\n// render the platform's default locale applies. A language's default formatters are made once, kept as long as it is.\n\nimport { currentLanguage, type Language } from \"./language.ts\";\n\n/** A time (a `Date`, milliseconds, or an ISO string as messages carry it) in the current locale; `14:05` by default. */\nexport function formatTime(at: Date | number | string, options?: Intl.DateTimeFormatOptions): string {\n\tconst language = currentLanguage();\n\tconst format =\n\t\toptions === undefined && language !== undefined\n\t\t\t? formattersOf(language).time\n\t\t\t: new Intl.DateTimeFormat(language?.locale, options ?? TIME);\n\treturn format.format(new Date(at));\n}\n\n/** A number in the current locale (`1.234,5` in German). */\nexport function formatNumber(value: number, options?: Intl.NumberFormatOptions): string {\n\tconst language = currentLanguage();\n\tconst format =\n\t\toptions === undefined && language !== undefined\n\t\t\t? formattersOf(language).number\n\t\t\t: new Intl.NumberFormat(language?.locale, options);\n\treturn format.format(value);\n}\n\n/** `formatTime`'s default: hours and minutes. */\nconst TIME: Intl.DateTimeFormatOptions = { timeStyle: \"short\" };\n\n/** A language's default formatters. */\ntype Formatters = { readonly time: Intl.DateTimeFormat; readonly number: Intl.NumberFormat };\n\n/** The default formatters of each language, made at its first use: a formatter costs far more than a format. */\nconst FORMATTERS = new WeakMap<Language, Formatters>();\n\n/** `language`'s default formatters. */\nfunction formattersOf(language: Language): Formatters {\n\tlet formatters = FORMATTERS.get(language);\n\tif (formatters === undefined) {\n\t\tformatters = {\n\t\t\ttime: new Intl.DateTimeFormat(language.locale, TIME),\n\t\t\tnumber: new Intl.NumberFormat(language.locale),\n\t\t};\n\t\tFORMATTERS.set(language, formatters);\n\t}\n\treturn formatters;\n}\n"]}

package/dist/surfaces/index.d.ts

@@ -0,0 +1,15 @@
+export { followActiveLanguage, hostLanguage, type LanguageFollower } from "./active-language.ts";
+export { followActiveTheme, type ThemeFollower } from "./active-theme.ts";
+export { type Client, type ClientError, type ClientOptions, type ClientStyles, startClient, } from "./client.ts";
+export { type ConnectionState, keepConnected, type LoopEnvironment, type LoopLink, type LoopOptions, type SocketEvents, } from "./connection.ts";
+export { formatNumber, formatTime } from "./format.ts";
+export { createLanguage, type Language, type MessagesReport } from "./language.ts";
+export { LoadedFacets, type Prepared, type SetEntry } from "./loaded.ts";
+export { LocaleChoice, localeChoiceFacet } from "./locale-choice.ts";
+export { type Catalog, type CatalogShape, type DataKeys, defineMessages, type MessageArgs, type MessageData, type MessageParam, MessageSchema, type Messages, type MessagesOf, type MessageValue, type Translator, } from "./messages.ts";
+export { type ClientModules, evaluateRegistered, type FacetFunction, REGISTER, type RegisteredScript, registeredSource, } from "./registered.ts";
+export { type ScriptEntry, ScriptSet, type ScriptsContract, TuiScripts, WebScripts } from "./scripts.ts";
+export { ThemeChoice, themeChoiceFacet } from "./theme-choice.ts";
+export { activeTheme, BASE_ROLES, type BaseRole, type ColorDepth, FALLBACK_THEMES, type Theme, type ThemePick, Themes, terminalColor, themesFacet, themeVariables, } from "./themes.ts";
+export { type Translation, type TranslationIndex, Translations, translationsFacet, } from "./translations.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/surfaces/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EACN,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,WAAW,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,KAAK,eAAe,EACpB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,KAAK,aAAa,EAClB,kBAAkB,EAClB,KAAK,aAAa,EAClB,QAAQ,EACR,KAAK,gBAAgB,EACrB,gBAAgB,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EACN,WAAW,EACX,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,eAAe,EACf,KAAK,KAAK,EACV,KAAK,SAAS,EACd,MAAM,EACN,aAAa,EACb,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,YAAY,EACZ,iBAAiB,GACjB,MAAM,mBAAmB,CAAC"}