@earendil-works/chord 1.5.0 → 1.5.1

package/dist/surfaces/active-language.d.ts

@@ -0,0 +1,20 @@
+import { type Context } from "../context/index.ts";
+import type { Principal } from "../data/index.ts";
+import type { Host } from "../host/index.ts";
+import { type Language, type MessagesReport } from "./language.ts";
+import { type PageState } from "./page-state.ts";
+/** A client's active language as it follows it: the device's languages can change (a browser's), and it ends. */
+export type LanguageFollower = {
+    /** The device's languages changed: the locale is resolved again. */
+    setDevice(preferred: readonly string[]): void;
+    stop(): void;
+};
+/**
+ * Follows the active language on `host` for the device's `preferred` languages: sets the host's language (and calls
+ * `changed` with it) at once and at every change of the registry, the user's pick or the device's languages that
+ * changes the locale or the catalogs, until `stop`. `report` gets each distinct report once.
+ */
+export declare function followActiveLanguage<P extends Principal>(host: Host<P>, preferred: readonly string[], changed: (language: Language) => void, report: (report: MessagesReport) => void, context: Context): Promise<LanguageFollower>;
+/** `host`'s active language, kept as its page state: `undefined` until a follower sets it (then `t` renders the first catalog). */
+export declare function hostLanguage<P extends Principal>(host: Host<P>): PageState<Language | undefined>;
+//# sourceMappingURL=active-language.d.ts.map

package/dist/surfaces/active-language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-language.d.ts","sourceRoot":"","sources":["../../src/surfaces/active-language.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAiB,MAAM,eAAe,CAAC;AAElG,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,iBAAiB,CAAC;AAG5D,iHAAiH;AACjH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,oEAAoE;IACpE,SAAS,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9C,IAAI,IAAI,IAAI,CAAC;CACb,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,SAAS,EAC7D,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,EACrC,MAAM,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,EACxC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,gBAAgB,CAAC,CA4C3B;AAKD,mIAAmI;AACnI,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,CAEhG"}

package/dist/surfaces/active-language.js

@@ -0,0 +1,78 @@
+// The active language of a client (decision "Messages and languages in the app kit" (3)): the `Translations` registry
+// on the client's host (served there by the kit), the user's `LocaleChoice` (held on the server; until it binds, or
+// when the app serves none, no pick) and the device's languages, combined. The host keeps it as page state
+// (`hostLanguage`), where `useMessages` and `TuiScope.messages` read and follow it; each change also calls the client's
+// writer (`lang` and `dir` on a page). Reports are passed on once each.
+import { withAbortSignal } from "../context/index.js";
+import { createLanguage, resolveLocale } from "./language.js";
+import { LocaleChoice } from "./locale-choice.js";
+import { pageState } from "./page-state.js";
+import { NO_TRANSLATIONS, Translations } from "./translations.js";
+/**
+ * Follows the active language on `host` for the device's `preferred` languages: sets the host's language (and calls
+ * `changed` with it) at once and at every change of the registry, the user's pick or the device's languages that
+ * changes the locale or the catalogs, until `stop`. `report` gets each distinct report once.
+ */
+export async function followActiveLanguage(host, preferred, changed, report, context) {
+    const abort = new AbortController();
+    const ctx = withAbortSignal(abort.signal, context);
+    const state = hostLanguage(host);
+    const once = reportOnce(report);
+    let translations = NO_TRANSLATIONS;
+    let pick = null;
+    let device = preferred;
+    const update = () => {
+        const locale = resolveLocale(pick, device, translations.locales);
+        const current = state.read();
+        if (current?.locale === locale && current.translations === translations)
+            return;
+        const language = createLanguage(locale, translations, once);
+        state.set(language);
+        changed(language);
+    };
+    update();
+    const registry = await host.registry(Translations, ctx);
+    translations = registry.value;
+    update();
+    (await registry.watch(ctx)).start(async (call) => {
+        if (call.kind === "value")
+            translations = call.value;
+        update();
+    });
+    const choice = host.hold(LocaleChoice, {}, ctx);
+    choice.pick.watch(ctx).then((watch) => watch.start(async (call) => {
+        if (call.kind === "value")
+            pick = call.value;
+        update();
+    }), 
+    // The hold ended (the follower stopped) before its first value.
+    () => { });
+    return {
+        setDevice: (next) => {
+            device = next;
+            update();
+        },
+        stop: () => {
+            abort.abort();
+            choice.release();
+        },
+    };
+}
+/** The page state key of a host's language. */
+const LANGUAGE = "chord.language";
+/** `host`'s active language, kept as its page state: `undefined` until a follower sets it (then `t` renders the first catalog). */
+export function hostLanguage(host) {
+    return pageState(host, LANGUAGE, undefined);
+}
+/** `report`, called once per distinct report (by kind, namespace, locale and key). */
+function reportOnce(report) {
+    const seen = new Set();
+    return (each) => {
+        const id = `${each.kind}|${each.namespace}|${"locale" in each ? each.locale : ""}|${each.key}`;
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        report(each);
+    };
+}
+//# sourceMappingURL=active-language.js.map

package/dist/surfaces/active-language.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-language.js","sourceRoot":"","sources":["../../src/surfaces/active-language.ts"],"names":[],"mappings":"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","sourcesContent":["// The active language of a client (decision \"Messages and languages in the app kit\" (3)): the `Translations` registry\n// on the client's host (served there by the kit), the user's `LocaleChoice` (held on the server; until it binds, or\n// when the app serves none, no pick) and the device's languages, combined. The host keeps it as page state\n// (`hostLanguage`), where `useMessages` and `TuiScope.messages` read and follow it; each change also calls the client's\n// writer (`lang` and `dir` on a page). Reports are passed on once each.\n\nimport { type Context, withAbortSignal } from \"../context/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport type { Host } from \"../host/index.ts\";\nimport { createLanguage, type Language, type MessagesReport, resolveLocale } from \"./language.ts\";\nimport { LocaleChoice } from \"./locale-choice.ts\";\nimport { type PageState, pageState } from \"./page-state.ts\";\nimport { NO_TRANSLATIONS, type TranslationIndex, Translations } from \"./translations.ts\";\n\n/** A client's active language as it follows it: the device's languages can change (a browser's), and it ends. */\nexport type LanguageFollower = {\n\t/** The device's languages changed: the locale is resolved again. */\n\tsetDevice(preferred: readonly string[]): void;\n\tstop(): void;\n};\n\n/**\n * Follows the active language on `host` for the device's `preferred` languages: sets the host's language (and calls\n * `changed` with it) at once and at every change of the registry, the user's pick or the device's languages that\n * changes the locale or the catalogs, until `stop`. `report` gets each distinct report once.\n */\nexport async function followActiveLanguage<P extends Principal>(\n\thost: Host<P>,\n\tpreferred: readonly string[],\n\tchanged: (language: Language) => void,\n\treport: (report: MessagesReport) => void,\n\tcontext: Context,\n): Promise<LanguageFollower> {\n\tconst abort = new AbortController();\n\tconst ctx = withAbortSignal(abort.signal, context);\n\tconst state = hostLanguage(host);\n\tconst once = reportOnce(report);\n\tlet translations: TranslationIndex = NO_TRANSLATIONS;\n\tlet pick: string | null = null;\n\tlet device = preferred;\n\tconst update = (): void => {\n\t\tconst locale = resolveLocale(pick, device, translations.locales);\n\t\tconst current = state.read();\n\t\tif (current?.locale === locale && current.translations === translations) return;\n\t\tconst language = createLanguage(locale, translations, once);\n\t\tstate.set(language);\n\t\tchanged(language);\n\t};\n\tupdate();\n\tconst registry = await host.registry(Translations, ctx);\n\ttranslations = registry.value;\n\tupdate();\n\t(await registry.watch(ctx)).start(async (call) => {\n\t\tif (call.kind === \"value\") translations = call.value;\n\t\tupdate();\n\t});\n\tconst choice = host.hold(LocaleChoice, {}, ctx);\n\tchoice.pick.watch(ctx).then(\n\t\t(watch) =>\n\t\t\twatch.start(async (call) => {\n\t\t\t\tif (call.kind === \"value\") pick = call.value;\n\t\t\t\tupdate();\n\t\t\t}),\n\t\t// The hold ended (the follower stopped) before its first value.\n\t\t() => {},\n\t);\n\treturn {\n\t\tsetDevice: (next) => {\n\t\t\tdevice = next;\n\t\t\tupdate();\n\t\t},\n\t\tstop: () => {\n\t\t\tabort.abort();\n\t\t\tchoice.release();\n\t\t},\n\t};\n}\n\n/** The page state key of a host's language. */\nconst LANGUAGE = \"chord.language\";\n\n/** `host`'s active language, kept as its page state: `undefined` until a follower sets it (then `t` renders the first catalog). */\nexport function hostLanguage<P extends Principal>(host: Host<P>): PageState<Language | undefined> {\n\treturn pageState<Language | undefined, P>(host, LANGUAGE, undefined);\n}\n\n/** `report`, called once per distinct report (by kind, namespace, locale and key). */\nfunction reportOnce(report: (report: MessagesReport) => void): (report: MessagesReport) => void {\n\tconst seen = new Set<string>();\n\treturn (each) => {\n\t\tconst id = `${each.kind}|${each.namespace}|${\"locale\" in each ? each.locale : \"\"}|${each.key}`;\n\t\tif (seen.has(id)) return;\n\t\tseen.add(id);\n\t\treport(each);\n\t};\n}\n"]}

package/dist/surfaces/active-theme.d.ts

@@ -0,0 +1,16 @@
+import { type Context } from "../context/index.ts";
+import type { Principal } from "../data/index.ts";
+import type { Host } from "../host/index.ts";
+import { type Theme } from "./themes.ts";
+/** A client's active theme as it follows it: its mode can change (a page's colour scheme), and it ends. */
+export type ThemeFollower = {
+    /** The client's mode changed: the active theme is chosen again. */
+    setMode(mode: Theme["mode"]): void;
+    stop(): void;
+};
+/**
+ * Follows the active theme on `host` for `mode`, calling `changed` with it at once (the fallback or the first of its
+ * mode) and at every change of the registry, the user's pick or the mode, until `stop`.
+ */
+export declare function followActiveTheme<P extends Principal>(host: Host<P>, mode: Theme["mode"], changed: (theme: Theme) => void, context: Context): Promise<ThemeFollower>;
+//# sourceMappingURL=active-theme.d.ts.map

package/dist/surfaces/active-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-theme.d.ts","sourceRoot":"","sources":["../../src/surfaces/active-theme.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAe,KAAK,KAAK,EAA0B,MAAM,aAAa,CAAC;AAE9E,2GAA2G;AAC3G,MAAM,MAAM,aAAa,GAAG;IAC3B,mEAAmE;IACnE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACnC,IAAI,IAAI,IAAI,CAAC;CACb,CAAC;AAEF;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,SAAS,EAC1D,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EACnB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAC/B,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,aAAa,CAAC,CAmCxB"}

package/dist/surfaces/active-theme.js

@@ -0,0 +1,47 @@
+// The active theme of a client (slice 11 §4b): the `Themes` registry on the client's host (served there by the kit),
+// the user's `ThemeChoice` (held on the server; until it binds, or when the app serves none, the first theme of each
+// mode) and the client's mode, combined; each change calls the client's writer (CSS variables on a page, the colour
+// lookup in a terminal).
+import { withAbortSignal } from "../context/index.js";
+import { ThemeChoice } from "./theme-choice.js";
+import { activeTheme, Themes } from "./themes.js";
+/**
+ * Follows the active theme on `host` for `mode`, calling `changed` with it at once (the fallback or the first of its
+ * mode) and at every change of the registry, the user's pick or the mode, until `stop`.
+ */
+export async function followActiveTheme(host, mode, changed, context) {
+    const abort = new AbortController();
+    const ctx = withAbortSignal(abort.signal, context);
+    let themes = [];
+    let pick = { dark: null, light: null };
+    let current = mode;
+    const update = () => changed(activeTheme(themes, pick, current));
+    update();
+    const registry = await host.registry(Themes, ctx);
+    themes = registry.value;
+    update();
+    (await registry.watch(ctx)).start(async (call) => {
+        if (call.kind === "value")
+            themes = call.value;
+        update();
+    });
+    const choice = host.hold(ThemeChoice, {}, ctx);
+    choice.pick.watch(ctx).then((watch) => watch.start(async (call) => {
+        if (call.kind === "value")
+            pick = call.value;
+        update();
+    }), 
+    // The hold ended (the follower stopped) before its first value.
+    () => { });
+    return {
+        setMode: (next) => {
+            current = next;
+            update();
+        },
+        stop: () => {
+            abort.abort();
+            choice.release();
+        },
+    };
+}
+//# sourceMappingURL=active-theme.js.map

package/dist/surfaces/active-theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-theme.js","sourceRoot":"","sources":["../../src/surfaces/active-theme.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,qHAAqH;AACrH,oHAAoH;AACpH,yBAAyB;AAEzB,OAAO,EAAgB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGpE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAA8B,MAAM,EAAE,MAAM,aAAa,CAAC;AAS9E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,IAAa,EACb,IAAmB,EACnB,OAA+B,EAC/B,OAAgB;IAEhB,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,MAAM,GAAqB,EAAE,CAAC;IAClC,IAAI,IAAI,GAAc,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClD,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,MAAM,EAAE,CAAC;IACT,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC;IACxB,MAAM,EAAE,CAAC;IACT,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QAChD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;QAC/C,MAAM,EAAE,CAAC;IACV,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;IAC/C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAC1B,CAAC,KAAK,EAAE,EAAE,CACT,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,IAAI,GAAG,IAAI,CAAC,KAAkB,CAAC;QAC1D,MAAM,EAAE,CAAC;IACV,CAAC,CAAC;IACH,gEAAgE;IAChE,GAAG,EAAE,GAAE,CAAC,CACR,CAAC;IACF,OAAO;QACN,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACjB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,EAAE,CAAC;QACV,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACV,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["// The active theme of a client (slice 11 §4b): the `Themes` registry on the client's host (served there by the kit),\n// the user's `ThemeChoice` (held on the server; until it binds, or when the app serves none, the first theme of each\n// mode) and the client's mode, combined; each change calls the client's writer (CSS variables on a page, the colour\n// lookup in a terminal).\n\nimport { type Context, withAbortSignal } from \"../context/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport type { Host } from \"../host/index.ts\";\nimport { ThemeChoice } from \"./theme-choice.ts\";\nimport { activeTheme, type Theme, type ThemePick, Themes } from \"./themes.ts\";\n\n/** A client's active theme as it follows it: its mode can change (a page's colour scheme), and it ends. */\nexport type ThemeFollower = {\n\t/** The client's mode changed: the active theme is chosen again. */\n\tsetMode(mode: Theme[\"mode\"]): void;\n\tstop(): void;\n};\n\n/**\n * Follows the active theme on `host` for `mode`, calling `changed` with it at once (the fallback or the first of its\n * mode) and at every change of the registry, the user's pick or the mode, until `stop`.\n */\nexport async function followActiveTheme<P extends Principal>(\n\thost: Host<P>,\n\tmode: Theme[\"mode\"],\n\tchanged: (theme: Theme) => void,\n\tcontext: Context,\n): Promise<ThemeFollower> {\n\tconst abort = new AbortController();\n\tconst ctx = withAbortSignal(abort.signal, context);\n\tlet themes: readonly Theme[] = [];\n\tlet pick: ThemePick = { dark: null, light: null };\n\tlet current = mode;\n\tconst update = (): void => changed(activeTheme(themes, pick, current));\n\tupdate();\n\tconst registry = await host.registry(Themes, ctx);\n\tthemes = registry.value;\n\tupdate();\n\t(await registry.watch(ctx)).start(async (call) => {\n\t\tif (call.kind === \"value\") themes = call.value;\n\t\tupdate();\n\t});\n\tconst choice = host.hold(ThemeChoice, {}, ctx);\n\tchoice.pick.watch(ctx).then(\n\t\t(watch) =>\n\t\t\twatch.start(async (call) => {\n\t\t\t\tif (call.kind === \"value\") pick = call.value as ThemePick;\n\t\t\t\tupdate();\n\t\t\t}),\n\t\t// The hold ended (the follower stopped) before its first value.\n\t\t() => {},\n\t);\n\treturn {\n\t\tsetMode: (next) => {\n\t\t\tcurrent = next;\n\t\t\tupdate();\n\t\t},\n\t\tstop: () => {\n\t\t\tabort.abort();\n\t\t\tchoice.release();\n\t\t},\n\t};\n}\n"]}

package/dist/surfaces/client.d.ts

@@ -0,0 +1,96 @@
+import type { TelemetryContext } from "@earendil-works/pi-telemetry";
+import { type Context } from "../context/index.ts";
+import type { Principal } from "../data/index.ts";
+import { type Host, type HostError, type PluginFacet, type PluginFailure } from "../host/index.ts";
+import type { Link } from "../link/index.ts";
+import { type ConnectionState, type LoopEnvironment, type SocketEvents } from "./connection.ts";
+import type { MessagesReport } from "./language.ts";
+import { type ClientModules, type RegisteredScript } from "./registered.ts";
+import type { ScriptEntry, ScriptSet, ScriptsContract } from "./scripts.ts";
+/**
+ * What a client reports: its host's errors, plugins left out at a load or kept old at a reload, a failed update, a
+ * plugin's stylesheet that did not load (`error`) or not within 10 s (`timeout`; this does not itself prevent the
+ * plugin's new code).
+ */
+export type ClientError = {
+    readonly kind: "host";
+    readonly error: HostError;
+} | {
+    readonly kind: "plugins";
+    readonly failed: readonly PluginFailure[];
+} | {
+    readonly kind: "update_failed";
+    readonly error: unknown;
+} | {
+    readonly kind: "stylesheet_failed";
+    readonly plugin: string;
+    readonly url: string;
+    readonly reason: "error" | "timeout";
+}
+/** A message rendered by a fallback, a contributed message that threw, a foreign message (each once). */
+ | {
+    readonly kind: "messages";
+    readonly report: MessagesReport;
+};
+/** What `startClient` takes. */
+export type ClientOptions<P extends Principal> = {
+    /** The kind's scripts object (`WebScripts`, `TuiScripts`). */
+    readonly scripts: ScriptsContract;
+    /** The hash of the base bundle this client runs. */
+    readonly base: string;
+    /** The plugin scripts it started with (the combined file's), in any order. */
+    readonly initial: readonly RegisteredScript[];
+    /** The modules its plugin scripts import, by specifier. */
+    readonly modules: ClientModules;
+    /** The app's own facets, loaded with the plugins. */
+    readonly core: readonly PluginFacet<P>[];
+    /** Opens one socket to the server and its link; the socket reports to `events`. */
+    readonly open: (events: SocketEvents) => Link;
+    /** Fetches a plugin's script of a set (at its `url`), which registers itself. */
+    readonly fetchScript: (entry: ScriptEntry) => Promise<RegisteredScript>;
+    /**
+     * The server's current base bundle hash, asked before each reconnect (`undefined`: unknown, try again): another one
+     * means this client is outdated (a new protocol comes with a new base bundle).
+     */
+    readonly serverBase: () => Promise<string | undefined>;
+    /** This client's code is outdated: the app starts it over (a page reloads); the loop has stopped. */
+    readonly outdated: () => void;
+    /** Asked before each reconnect; `false` stops the loop (a guest's ended share). */
+    readonly canRetry?: () => Promise<boolean>;
+    readonly onConnection?: (state: ConnectionState) => void;
+    /** The plugins' stylesheets (a page's; a terminal has none). */
+    readonly styles?: ClientStyles;
+    readonly environment: LoopEnvironment;
+    /**
+     * Makes the host's telemetry adapter (none: NOOP); `incarnation` names the host's run (it is read at the adapter's
+     * first span, after the host was made).
+     */
+    readonly telemetry?: (incarnation: () => string) => TelemetryContext;
+    readonly onError: (error: ClientError) => void;
+};
+/**
+ * A page's plugin stylesheets around each update: `prepare` before the host reloads, `settle` after it (or alone when
+ * no script changed).
+ */
+export type ClientStyles = {
+    /**
+     * Fetches, without applying them, the stylesheets of `set` that differ from those of the code each plugin runs or
+     * did not load; resolves once each loaded, failed or waited 10 s, or when `signal` aborts (the client stops: what it
+     * prepared is removed, `settle` never follows).
+     */
+    prepare(set: ScriptSet, signal: AbortSignal): Promise<void>;
+    /**
+     * Applies each prepared stylesheet whose plugin runs its new code now and retires the one it replaces; a plugin that
+     * `kept` names (its new script failed: it kept its old code) keeps its old one, its prepared one dropped unapplied;
+     * the stylesheets of plugins no longer in `set` go.
+     */
+    settle(set: ScriptSet, kept: ReadonlySet<string>): void;
+};
+/** A running client: its host, once its plugins are loaded, and its stop. */
+export type Client<P extends Principal> = {
+    readonly host: Host<P>;
+    stop(context: Context): Promise<void>;
+};
+/** Starts a client: its host loaded with the initial scripts, its link kept, its plugins kept current. */
+export declare function startClient<P extends Principal>(options: ClientOptions<P>): Promise<Client<P>>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/surfaces/client.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAsB,KAAK,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAc,KAAK,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC/G,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,KAAK,eAAe,EAAiB,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,KAAK,aAAa,EAAsB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC3D;IACA,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AACH,yGAAyG;GACvG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAElE,gCAAgC;AAChC,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,SAAS,IAAI;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IACzC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvD,qGAAqG;IACrG,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,mFAAmF;IACnF,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,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,MAAM,KAAK,gBAAgB,CAAC;IACrE,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CACxD,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,SAAS,IAAI;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAE5G,0GAA0G;AAC1G,wBAAsB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAuBpG"}

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":"AAAA,mHAAmH;AACnH,sHAAsH;AACtH,oHAAoH;AACpH,sHAAsH;AACtH,sHAAsH;AACtH,oHAAoH;AACpH,wGAAwG;AAGxG,OAAO,EAAE,kBAAkB,EAAgB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAExF,OAAO,EAAE,UAAU,EAAmE,MAAM,kBAAkB,CAAC;AAE/G,OAAO,EAAwB,aAAa,EAA2C,MAAM,iBAAiB,CAAC;AAE/G,OAAO,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAsB,kBAAkB,EAAyB,MAAM,iBAAiB,CAAC;AAgFhG,0GAA0G;AAC1G,MAAM,CAAC,KAAK,UAAU,WAAW,CAAsB,OAAyB;IAC/E,MAAM,OAAO,GAAG,kBAAkB,CAAC;IACnC,IAAI,IAAyB,CAAC;IAC9B,2FAA2F;IAC3F,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,IAAK,CAAC,WAAW,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,UAAU,CAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACxG,IAAI,GAAG,IAAI,CAAC;IACZ,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAClF,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACzF,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACvG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC7C,IAAI,KAAK,KAAK,WAAW;YAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO;QACN,IAAI;QACJ,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACnB,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;KACD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,OAAO,CACf,IAAa,EACb,OAAyB,EACzB,OAAyC;IAEzC,OAAO,aAAa,CAAC;QACpB,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE;YAChB,qFAAqF;YACrF,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACnD,yGAAyG;YACzG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAkB,EAAE,EAAE,kBAAkB,CAAC,CAAC;YAC1F,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAClB,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;YAC9B,OAAO,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC;QACD,QAAQ,EAAE,KAAK,IAAI,EAAE;YACpB,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;YACxC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjD,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACnB,OAAO,KAAK,CAAC;YACd,CAAC;YACD,OAAO,CAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;QAC7C,CAAC;QACD,WAAW,EAAE,OAAO,CAAC,WAAW;KAChC,CAAC,CAAC;AACJ,CAAC;AAED,qHAAqH;AACrH,MAAM,WAAW;IACP,KAAK,CAAO;IACZ,UAAU,GAAmB,EAAE,CAAC;IACzC,OAAO,GAAG,KAAK,CAAC;IAEhB,YAAY,IAAU;QACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YACjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;gBAAE,QAAQ,EAAE,CAAC;QAC9D,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,OAAmB;QACvB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,SAAS,CAAC,QAAuC;QAChD,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACJ,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,CAAC,QAAoB;QAC3B,IAAI,IAAI,CAAC,OAAO;YAAE,QAAQ,EAAE,CAAC;;YACxB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;CACD;AAED,8GAA8G;AAC9G,SAAS,OAAO,CAAC,MAAwB,EAAE,OAAsB;IAChE,OAAO;QACN,IAAI,EAAE,MAAM,CAAC,MAAM;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,GAAG,EAAE;YACb,IAAI,CAAC;gBACJ,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;YAC7F,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YAClC,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAErC,gEAAgE;AAChE,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,OAAO;IACH,KAAK,CAAU;IACf,OAAO,CAAe;IACtB,QAAQ,CAAmB;IACpC;;;OAGG;IACM,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC/C,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACxC,QAAQ,CAA2B;IACnC,qDAAqD;IACrD,OAAO,CAAwB;IAC/B,iEAAiE;IACjE,SAAS,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7C,+EAA+E;IAC/E,MAAM,CAAqC;IAC3C,MAAM,GAAG,CAAC,CAAC;IAEX,YAAY,IAAa,EAAE,MAAoB,EAAE,IAAyB,EAAE,OAAyB;QACpG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9G,CAAC;IAED,gHAAgH;IAChH,KAAK,CAAC,MAAM,CAAC,OAAgB;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACjF,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;gBAAE,OAAO;YAClC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAkB,CAAC;YACpC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;YACnB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACxB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAChB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,OAAgB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC;QACzB,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,IAAI;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;IACnB,CAAC;IAED,2FAA2F;IAC3F,MAAM,CAAC,GAAc,EAAE,OAAgB;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAC9C,IAAI,IAAI,CAAC,OAAO,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC/D,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBAAE,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;QACzB,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,qEAAqE;IACrE,WAAW,CAAC,GAAc,EAAE,OAAgB;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAC3G,IAAI,CAAC,MAAM,GAAG;YACb,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;gBACzD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAChC,CAAC,CAAC;SACF,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,GAAc,EAAE,OAAgB;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;YAC/B,OAAO,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,kFAAkF;QAClF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC;YACJ,MAAM,OAAO,GAAuB,EAAE,CAAC;YACvC,IAAI,OAAO,EAAE,CAAC;gBACb,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;oBACjC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;gBACzF,CAAC;YACF,CAAC;YACD,MAAM,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAU,CAAC;YAChF,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAClC,OAAO,IAAI,CAAC;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;YAClD,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IAED,uEAAuE;IACvE,QAAQ,CAAC,GAAc;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,OAAO,CACN,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI;YACnC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAC9E,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,OAAoC,EAAE,OAAgB;QACnE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;QACpD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACjF,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1E,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1F,OAAO,IAAI,CAAC;IACb,CAAC;CACD","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"]}