@earendil-works/chord 1.5.0 → 1.5.1

package/dist/surfaces/loaded.js

@@ -0,0 +1,116 @@
+// A host's loaded plugins (slice 10 D11, slice 11 §2): the facet loaded for each plugin, and loads and reloads with
+// complete sets, the same on a server or worker (the plugins runtime, scripts evaluated with `vm`) and in a page or a
+// terminal (scripts that registered themselves). Unchanged plugins (the same digest) pass as the same facet objects,
+// removed ones are left out; a plugin whose script failed (its build, its evaluation) keeps its loaded facet (left out
+// at the first load) and is named to the host, so its closure rule and its report see it.
+import { isChordError } from "../data/index.js";
+/** A host's loaded plugins: its core facets, each plugin's loaded facet, and its reloads, one after another. */
+export class LoadedFacets {
+    #core;
+    #loaded;
+    #reloading = Promise.resolve();
+    constructor(core, loaded) {
+        this.#core = core;
+        this.#loaded = loaded;
+    }
+    /**
+     * Prepares `entries` and loads them on `host` with `core` (the app's own facets): a plugin whose script failed is left
+     * out and reported in the report's `failed`, with the host's own. The host's loaded plugins, and the report.
+     */
+    static async load(host, core, entries, context) {
+        const prepared = entries.map((entry) => [entry.name, entry.prepare()]);
+        const failed = [];
+        const facets = [...core];
+        for (const [plugin, each] of prepared) {
+            if (each.kind === "failed")
+                failed.push({ plugin, error: each.error });
+            // Evaluated for this host's principal type: the facets are the app's (`Facet<P>` is invariant in `P`).
+            else
+                facets.push({ name: plugin, facet: each.facet });
+        }
+        const report = await host.load(facets, context);
+        const left = new Set(report.failed.map(({ plugin }) => plugin));
+        const loaded = new Map();
+        for (const [plugin, each] of prepared) {
+            if (each.kind === "facet" && !left.has(plugin))
+                loaded.set(plugin, each);
+        }
+        // The host's own facets, for its later reloads.
+        const kept = new LoadedFacets(core, loaded);
+        return { loaded: kept, report: { failed: [...failed, ...report.failed] } };
+    }
+    /**
+     * Reloads `host` with `entries`, the complete set now, after its earlier reloads: core facets and unchanged plugins as
+     * the same objects, new scripts prepared, a plugin whose script failed passed as its loaded facet (an added one left
+     * out; both named to the host's closure rule), plugins not in `entries` left out. What the host committed becomes
+     * the loaded set, also when the reload rejects `aborted` after its commit.
+     */
+    reload(host, entries, context) {
+        // One after another: a reload computing its set from a loaded map an earlier one is about to change would pass
+        // that plugin's old facet and roll it back.
+        const reload = this.#reloading.then(() => this.#reload(host, entries, context));
+        // The tail settles to nothing: a report kept as its value would keep a rejected facet's closure (its error).
+        this.#reloading = reload.then(() => { }, () => { });
+        return reload;
+    }
+    /** One reload of `host` with the complete set `entries`. */
+    async #reload(host, entries, context) {
+        const failed = [];
+        const next = new Map();
+        for (const entry of entries) {
+            const loaded = this.#loaded.get(entry.name);
+            if (entry.digest !== undefined && entry.digest === loaded?.digest) {
+                next.set(entry.name, loaded);
+                continue;
+            }
+            const prepared = entry.prepare();
+            if (prepared.kind === "facet") {
+                next.set(entry.name, prepared);
+                continue;
+            }
+            failed.push({ plugin: entry.name, error: prepared.error });
+            if (loaded !== undefined)
+                next.set(entry.name, loaded);
+        }
+        const facets = [...this.#core, ...[...next].map(([name, { facet }]) => ({ name, facet }))];
+        let report;
+        try {
+            // The host takes facets of its own principal type: they were loaded for it.
+            report = await host.reload(facets, context, { failed });
+        }
+        catch (error) {
+            // Aborted after its commit: the commit stands, and is what the host runs now.
+            const committed = committedOf(error);
+            if (committed !== undefined)
+                this.#adopt(next, committed.failed);
+            throw error;
+        }
+        this.#adopt(next, report.failed.map(({ plugin }) => plugin));
+        return report;
+    }
+    /**
+     * Adopts the set `next` a reload committed: a plugin the host kept old (`failed`) stays loaded as it was, an added one
+     * it left out is not loaded.
+     */
+    #adopt(next, failed) {
+        for (const plugin of failed) {
+            const loaded = this.#loaded.get(plugin);
+            if (loaded === undefined)
+                next.delete(plugin);
+            else
+                next.set(plugin, loaded);
+        }
+        this.#loaded.clear();
+        for (const [name, each] of next)
+            this.#loaded.set(name, each);
+    }
+}
+/** What the commit of a reload that rejected applied: an `aborted` error after its commit says (`details.committed`). */
+function committedOf(error) {
+    if (!isChordError(error, "aborted"))
+        return undefined;
+    const details = error.details;
+    // The kernel's own error: its `committed` is a `CommittedReload`.
+    return typeof details === "object" && details !== null ? details.committed : undefined;
+}
+//# sourceMappingURL=loaded.js.map

package/dist/surfaces/loaded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaded.js","sourceRoot":"","sources":["../../src/surfaces/loaded.ts"],"names":[],"mappings":"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","sourcesContent":["// A host's loaded plugins (slice 10 D11, slice 11 §2): the facet loaded for each plugin, and loads and reloads with\n// complete sets, the same on a server or worker (the plugins runtime, scripts evaluated with `vm`) and in a page or a\n// terminal (scripts that registered themselves). Unchanged plugins (the same digest) pass as the same facet objects,\n// removed ones are left out; a plugin whose script failed (its build, its evaluation) keeps its loaded facet (left out\n// at the first load) and is named to the host, so its closure rule and its report see it.\n\nimport type { Context } from \"../context/index.ts\";\nimport { isChordError, type Principal } from \"../data/index.ts\";\nimport type {\n\tCommittedReload,\n\tFacet,\n\tHost,\n\tLoadReport,\n\tPluginFacet,\n\tPluginFailure,\n\tReloadReport,\n} from \"../host/index.ts\";\n\n/** A plugin's facet for a host, or why there is none: its script failed. */\nexport type Prepared =\n\t| { readonly kind: \"facet\"; readonly facet: Facet<Principal>; readonly digest: string }\n\t| { readonly kind: \"failed\"; readonly error: unknown };\n\n/**\n * One plugin of a complete set: its name, its script's digest (`undefined` when its build failed: nothing to compare)\n * and how to get its facet (evaluated only when the digest is new).\n */\nexport type SetEntry = { readonly name: string; readonly digest: string | undefined; prepare(): Prepared };\n\n/** A plugin's facet as the host loaded it, with its script's digest. */\ntype LoadedFacet = { readonly facet: Facet<Principal>; readonly digest: string };\n\n/** A host's loaded plugins: its core facets, each plugin's loaded facet, and its reloads, one after another. */\nexport class LoadedFacets {\n\treadonly #core: readonly PluginFacet<Principal>[];\n\treadonly #loaded: Map<string, LoadedFacet>;\n\t#reloading: Promise<void> = Promise.resolve();\n\n\tprivate constructor(core: readonly PluginFacet<Principal>[], loaded: Map<string, LoadedFacet>) {\n\t\tthis.#core = core;\n\t\tthis.#loaded = loaded;\n\t}\n\n\t/**\n\t * Prepares `entries` and loads them on `host` with `core` (the app's own facets): a plugin whose script failed is left\n\t * out and reported in the report's `failed`, with the host's own. The host's loaded plugins, and the report.\n\t */\n\tstatic async load<P extends Principal>(\n\t\thost: Host<P>,\n\t\tcore: readonly PluginFacet<P>[],\n\t\tentries: readonly SetEntry[],\n\t\tcontext: Context,\n\t): Promise<{ readonly loaded: LoadedFacets; readonly report: LoadReport }> {\n\t\tconst prepared = entries.map((entry) => [entry.name, entry.prepare()] as const);\n\t\tconst failed: PluginFailure[] = [];\n\t\tconst facets: PluginFacet<P>[] = [...core];\n\t\tfor (const [plugin, each] of prepared) {\n\t\t\tif (each.kind === \"failed\") failed.push({ plugin, error: each.error });\n\t\t\t// Evaluated for this host's principal type: the facets are the app's (`Facet<P>` is invariant in `P`).\n\t\t\telse facets.push({ name: plugin, facet: each.facet as unknown as Facet<P> });\n\t\t}\n\t\tconst report = await host.load(facets, context);\n\t\tconst left = new Set(report.failed.map(({ plugin }) => plugin));\n\t\tconst loaded = new Map<string, LoadedFacet>();\n\t\tfor (const [plugin, each] of prepared) {\n\t\t\tif (each.kind === \"facet\" && !left.has(plugin)) loaded.set(plugin, each);\n\t\t}\n\t\t// The host's own facets, for its later reloads.\n\t\tconst kept = new LoadedFacets(core as unknown as readonly PluginFacet<Principal>[], loaded);\n\t\treturn { loaded: kept, report: { failed: [...failed, ...report.failed] } };\n\t}\n\n\t/**\n\t * Reloads `host` with `entries`, the complete set now, after its earlier reloads: core facets and unchanged plugins as\n\t * the same objects, new scripts prepared, a plugin whose script failed passed as its loaded facet (an added one left\n\t * out; both named to the host's closure rule), plugins not in `entries` left out. What the host committed becomes\n\t * the loaded set, also when the reload rejects `aborted` after its commit.\n\t */\n\treload<P extends Principal>(host: Host<P>, entries: readonly SetEntry[], context: Context): Promise<ReloadReport> {\n\t\t// One after another: a reload computing its set from a loaded map an earlier one is about to change would pass\n\t\t// that plugin's old facet and roll it back.\n\t\tconst reload = this.#reloading.then(() => this.#reload(host, entries, context));\n\t\t// The tail settles to nothing: a report kept as its value would keep a rejected facet's closure (its error).\n\t\tthis.#reloading = reload.then(\n\t\t\t() => {},\n\t\t\t() => {},\n\t\t);\n\t\treturn reload;\n\t}\n\n\t/** One reload of `host` with the complete set `entries`. */\n\tasync #reload<P extends Principal>(\n\t\thost: Host<P>,\n\t\tentries: readonly SetEntry[],\n\t\tcontext: Context,\n\t): Promise<ReloadReport> {\n\t\tconst failed: PluginFailure[] = [];\n\t\tconst next = new Map<string, LoadedFacet>();\n\t\tfor (const entry of entries) {\n\t\t\tconst loaded = this.#loaded.get(entry.name);\n\t\t\tif (entry.digest !== undefined && entry.digest === loaded?.digest) {\n\t\t\t\tnext.set(entry.name, loaded);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst prepared = entry.prepare();\n\t\t\tif (prepared.kind === \"facet\") {\n\t\t\t\tnext.set(entry.name, prepared);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tfailed.push({ plugin: entry.name, error: prepared.error });\n\t\t\tif (loaded !== undefined) next.set(entry.name, loaded);\n\t\t}\n\t\tconst facets = [...this.#core, ...[...next].map(([name, { facet }]) => ({ name, facet }))];\n\t\tlet report: ReloadReport;\n\t\ttry {\n\t\t\t// The host takes facets of its own principal type: they were loaded for it.\n\t\t\treport = await host.reload(facets as unknown as readonly PluginFacet<P>[], context, { failed });\n\t\t} catch (error) {\n\t\t\t// Aborted after its commit: the commit stands, and is what the host runs now.\n\t\t\tconst committed = committedOf(error);\n\t\t\tif (committed !== undefined) this.#adopt(next, committed.failed);\n\t\t\tthrow error;\n\t\t}\n\t\tthis.#adopt(\n\t\t\tnext,\n\t\t\treport.failed.map(({ plugin }) => plugin),\n\t\t);\n\t\treturn report;\n\t}\n\n\t/**\n\t * Adopts the set `next` a reload committed: a plugin the host kept old (`failed`) stays loaded as it was, an added one\n\t * it left out is not loaded.\n\t */\n\t#adopt(next: Map<string, LoadedFacet>, failed: readonly string[]): void {\n\t\tfor (const plugin of failed) {\n\t\t\tconst loaded = this.#loaded.get(plugin);\n\t\t\tif (loaded === undefined) next.delete(plugin);\n\t\t\telse next.set(plugin, loaded);\n\t\t}\n\t\tthis.#loaded.clear();\n\t\tfor (const [name, each] of next) this.#loaded.set(name, each);\n\t}\n}\n\n/** What the commit of a reload that rejected applied: an `aborted` error after its commit says (`details.committed`). */\nfunction committedOf(error: unknown): CommittedReload | undefined {\n\tif (!isChordError(error, \"aborted\")) return undefined;\n\tconst details = error.details as { readonly committed?: CommittedReload } | null | undefined;\n\t// The kernel's own error: its `committed` is a `CommittedReload`.\n\treturn typeof details === \"object\" && details !== null ? details.committed : undefined;\n}\n"]}

package/dist/surfaces/locale-choice.d.ts

@@ -0,0 +1,25 @@
+import type { Principal } from "../data/index.ts";
+import type { Facet } from "../host/index.ts";
+/** The caller's locale choice, on the server: its pick, and `choose` to change it. */
+export declare const LocaleChoice: import("../contracts/contract.ts").Contract<{
+    kind: "remote";
+    name: "chord.locale.choice";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            readonly main: {
+                state: {
+                    readonly pick: import("../contracts/index.ts").Schema<string | null>;
+                };
+                methods: {
+                    readonly choose: import("../contracts/schema.ts").Method<import("../contracts/index.ts").Schema<string | null>, import("../contracts/schema.ts").NullSchema>;
+                };
+            };
+        };
+        changes: never;
+    }];
+}>;
+/** The kit's server facet for locale choices: the store of picks and each principal's `LocaleChoice`. */
+export declare function localeChoiceFacet<P extends Principal>(): Facet<P>;
+//# sourceMappingURL=locale-choice.d.ts.map

package/dist/surfaces/locale-choice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-choice.d.ts","sourceRoot":"","sources":["../../src/surfaces/locale-choice.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAM9C,sFAAsF;AACtF,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;EAAkD,CAAC;AAE5E,yGAAyG;AACzG,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,CAEjE"}

package/dist/surfaces/locale-choice.js

@@ -0,0 +1,14 @@
+// The user's locale choice (decision "Messages and languages in the app kit" (3)): one locale per principal, a
+// preference the server keeps (the kit serves it) and every page and terminal of that principal holds, so choosing a
+// language re-renders them all at once, without a reload. `null` until the user chooses: the device's languages decide.
+import { nul, str, union } from "../contracts/index.js";
+import { preferenceContract, preferenceFacet } from "./preference.js";
+/** A language tag (`de`, `pt-BR`; at most 35 characters, BCP 47's practical bound), or `null`: the device's. */
+const Pick = union([str({ max: 35, pattern: "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$" }), nul()]);
+/** The caller's locale choice, on the server: its pick, and `choose` to change it. */
+export const LocaleChoice = preferenceContract("chord.locale.choice", Pick);
+/** The kit's server facet for locale choices: the store of picks and each principal's `LocaleChoice`. */
+export function localeChoiceFacet() {
+    return preferenceFacet(LocaleChoice, "chord.locale.picks", Pick, null);
+}
+//# sourceMappingURL=locale-choice.js.map

package/dist/surfaces/locale-choice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-choice.js","sourceRoot":"","sources":["../../src/surfaces/locale-choice.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,qHAAqH;AACrH,wHAAwH;AAExH,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtE,gHAAgH;AAChH,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AAE9F,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;AAE5E,yGAAyG;AACzG,MAAM,UAAU,iBAAiB;IAChC,OAAO,eAAe,CAAI,YAAY,EAAE,oBAAoB,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["// The user's locale choice (decision \"Messages and languages in the app kit\" (3)): one locale per principal, a\n// preference the server keeps (the kit serves it) and every page and terminal of that principal holds, so choosing a\n// language re-renders them all at once, without a reload. `null` until the user chooses: the device's languages decide.\n\nimport { nul, str, union } from \"../contracts/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport type { Facet } from \"../host/index.ts\";\nimport { preferenceContract, preferenceFacet } from \"./preference.ts\";\n\n/** A language tag (`de`, `pt-BR`; at most 35 characters, BCP 47's practical bound), or `null`: the device's. */\nconst Pick = union([str({ max: 35, pattern: \"^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$\" }), nul()]);\n\n/** The caller's locale choice, on the server: its pick, and `choose` to change it. */\nexport const LocaleChoice = preferenceContract(\"chord.locale.choice\", Pick);\n\n/** The kit's server facet for locale choices: the store of picks and each principal's `LocaleChoice`. */\nexport function localeChoiceFacet<P extends Principal>(): Facet<P> {\n\treturn preferenceFacet<P>(LocaleChoice, \"chord.locale.picks\", Pick, null);\n}\n"]}

package/dist/surfaces/messages.d.ts

@@ -0,0 +1,67 @@
+import { type Language } from "./language.ts";
+import { type Translation } from "./translations.ts";
+/** A message's value: a text, or a function of its arguments returning one. */
+export type MessageValue = string | ((...args: never[]) => string);
+/** A catalog: the messages of one namespace in one language, by key. */
+export type Catalog = {
+    readonly [key: string]: MessageValue;
+};
+/** A catalog's shape as other catalogs must match it: its keys, strings as `string`, functions with their signatures. */
+export type CatalogShape<M> = {
+    readonly [K in keyof M]: M[K] extends string ? string : M[K];
+};
+/** The arguments of a message: its function's parameters, none for a text. */
+export type MessageArgs<V> = V extends (...args: infer A) => string ? A : [];
+/** A parameter of a message as data: plain JSON (a date as an ISO string or a number), so it crosses links. */
+export type MessageParam = string | number | boolean | null;
+/**
+ * A message as data: its namespace, its key and its parameters; typed by `t.message` (`MessageData<"notes", "saved">`),
+ * any namespace and key as `MessageSchema` carries it across a link. (`Message` is the link protocol's.)
+ */
+export type MessageData<N extends string = string, K extends string = string> = {
+    readonly namespace: N;
+    readonly key: K;
+    readonly params: MessageParam[];
+};
+/** The schema of a message as data, for contract members (`notice: union([MessageSchema, nul()])`). */
+export declare const MessageSchema: import("../contracts/index.ts").Schema<{
+    namespace: string;
+    key: string;
+    params: (string | number | boolean | null)[];
+}>;
+/** The keys of `M` whose arguments are all `MessageParam`s: those `t.message` can build. */
+export type DataKeys<M> = {
+    [K in keyof M & string]: MessageArgs<M[K]> extends readonly MessageParam[] ? K : never;
+}[keyof M & string];
+/** A message of namespace `N`, or one of any namespace (`string`, from a schema): another literal namespace is refused. */
+type OfNamespace<G extends MessageData, N extends string> = string extends G["namespace"] ? unknown : {
+    readonly namespace: N;
+};
+/** Renders the messages of namespace `N` with catalog shape `M` in one language. */
+export type Translator<N extends string, M> = {
+    /** The message `key` with its arguments. */
+    <K extends keyof M & string>(key: K, ...args: MessageArgs<M[K]>): string;
+    /** A message as data; a foreign namespace or an unknown key shows the key (and is reported). */
+    render<G extends MessageData>(message: G & OfNamespace<G, N>): string;
+};
+/** A plugin's messages: `t` itself (in the current language), its namespace, its catalogs as contributions, `message`. */
+export type Messages<N extends string, M> = Translator<N, M> & {
+    readonly namespace: N;
+    /** Its catalogs as `Translations` entries: a facet that renders contributes them. */
+    readonly translations: readonly Translation[];
+    /** The message `key` with its arguments as data, for state that clients render. */
+    message<K extends DataKeys<M>>(key: K, ...args: MessageArgs<M[K]>): MessageData<N, K>;
+    /** `t` in `language` (`undefined`: the first catalog). */
+    in(language: Language | undefined): Translator<N, M>;
+};
+/** The catalog shape of a plugin's messages: what a translation fills (`const fr: MessagesOf<typeof t> = {...}`). */
+export type MessagesOf<T> = T extends Messages<string, infer M> ? M : never;
+/**
+ * The messages of `namespace` (a name like a type's, `[a-z0-9@/._~-]`) in `catalogs` by locale; the first catalog
+ * defines the keys and signatures, the others match it.
+ */
+export declare function defineMessages<const N extends string, M extends Catalog>(namespace: N, catalogs: {
+    readonly [locale: string]: CatalogShape<M>;
+}): Messages<N, CatalogShape<M>>;
+export {};
+//# sourceMappingURL=messages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/surfaces/messages.ts"],"names":[],"mappings":"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"}

package/dist/surfaces/messages.js

@@ -0,0 +1,112 @@
+// Messages in code (decision "Messages and languages in the app kit" (1), (4), refined in the build): a plugin defines
+// its texts once, per namespace, in a shared `messages.ts` every facet that renders imports: `defineMessages("notes", {
+// en: {...}, de: {...} })` returns a typed `t`. The first catalog defines the keys and their argument types; every
+// other catalog must have the same keys with the same signatures (a missing key, an unknown one or a wrong argument is
+// a type error); values are strings or functions (plurals, word order). `t` renders in a language: bound to a host's
+// (`useMessages`, `scope.messages`, `t.in`), or plain, in the render under way's, else in the first catalog.
+// `t.message` builds a message as data (`{ namespace, key, params }`) for state, notices and errors, which each client
+// renders with `t.render` in its own language, checked at runtime (it crossed a link).
+import { arr, bool, nul, num, obj, str, union } from "../contracts/index.js";
+import { checkName } from "../contracts/names.js";
+import { currentLanguage, inLanguage } from "./language.js";
+import { canonicalLocale } from "./translations.js";
+/** The schema of a message as data, for contract members (`notice: union([MessageSchema, nul()])`). */
+export const MessageSchema = obj({
+    namespace: str(),
+    key: str(),
+    params: arr(union([str(), num(), bool(), nul()])),
+});
+/**
+ * The messages of `namespace` (a name like a type's, `[a-z0-9@/._~-]`) in `catalogs` by locale; the first catalog
+ * defines the keys and signatures, the others match it.
+ */
+export function defineMessages(namespace, catalogs) {
+    // Declaration policy: a namespace is a name, a catalog's key a language tag (JavaScript callers reach both).
+    checkName(namespace, "A messages namespace");
+    const own = new Map();
+    for (const [locale, catalog] of Object.entries(catalogs)) {
+        const canonical = canonicalLocale(locale);
+        if (canonical === undefined)
+            throw new Error(`${namespace}: "${locale}" is no language tag`);
+        own.set(canonical, catalog);
+    }
+    const first = own.values().next().value;
+    if (first === undefined)
+        throw new Error(`${namespace}: defineMessages needs a catalog`);
+    const source = { namespace, own, first };
+    const translations = [...own].map(([locale, messages]) => ({ namespace, locale, messages }));
+    // The overloads `Messages` types are these functions', keyed by the catalog's shape.
+    return Object.assign(translator(source, currentLanguage), {
+        namespace,
+        translations,
+        message: (key, ...params) => ({ namespace, key, params }),
+        in: (language) => translator(source, () => language),
+    });
+}
+/** A translator of `source`'s messages in the language `language` reads at each call. */
+function translator(source, language) {
+    const t = (key, ...args) => renderKey(source, language(), key, args);
+    const render = (message) => renderData(source, language(), message);
+    // The overloads `Translator` types are this one function's, keyed by the catalog's shape.
+    return Object.assign(t, { render });
+}
+/**
+ * `key` of `source` in `language`: down its chain, at each locale the host's contributed catalog, then the plugin's own;
+ * else the first catalog.
+ */
+function renderKey(source, language, key, args) {
+    if (language === undefined)
+        return call(source.first[key], args);
+    return inLanguage(language, () => {
+        for (const [index, locale] of language.chain.entries()) {
+            const contributed = language.translations.catalogs.get(source.namespace)?.get(locale);
+            if (contributed !== undefined && Object.hasOwn(contributed.value.messages, key)) {
+                try {
+                    return found(language, source, key, index, call(contributed.value.messages[key], args));
+                }
+                catch (error) {
+                    // A contributed catalog is a plugin's code: reported, and the chain goes on (design §17).
+                    const { plugin } = contributed;
+                    language.report({ kind: "failed", namespace: source.namespace, locale, key, plugin, error });
+                }
+            }
+            const own = source.own.get(locale);
+            if (own !== undefined && own !== contributed?.value.messages && Object.hasOwn(own, key)) {
+                return found(language, source, key, index, call(own[key], args));
+            }
+        }
+        return found(language, source, key, language.chain.length, call(source.first[key], args));
+    });
+}
+/** `text`, found at `index` in `language`'s chain (its length: the first catalog), a fallback reported past the first. */
+function found(language, source, key, index, text) {
+    if (index > 0) {
+        const used = language.chain[index];
+        language.report({ kind: "fallback", namespace: source.namespace, locale: language.locale, key, used });
+    }
+    return text;
+}
+/** A message's text: the text, or the function called with `args` (typed by the catalog's signature). */
+function call(value, args) {
+    return typeof value === "string" ? value : value(...args);
+}
+/**
+ * A message as data in `language`. Checked first (wire input: the message crossed a link as state): another namespace,
+ * a key the first catalog lacks or params that are no list show the key, reported; so does a message that throws.
+ */
+function renderData(source, language, message) {
+    const { namespace, key, params } = message;
+    const known = namespace === source.namespace && Object.hasOwn(source.first, key) && Array.isArray(params);
+    if (!known) {
+        language?.report({ kind: "unknown", namespace, key, expected: source.namespace });
+        return key;
+    }
+    try {
+        return renderKey(source, language, key, params);
+    }
+    catch (error) {
+        language?.report({ kind: "failed", namespace, locale: language.locale, key, plugin: undefined, error });
+        return key;
+    }
+}
+//# sourceMappingURL=messages.js.map

package/dist/surfaces/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/surfaces/messages.ts"],"names":[],"mappings":"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","sourcesContent":["// Messages in code (decision \"Messages and languages in the app kit\" (1), (4), refined in the build): a plugin defines\n// its texts once, per namespace, in a shared `messages.ts` every facet that renders imports: `defineMessages(\"notes\", {\n// en: {...}, de: {...} })` returns a typed `t`. The first catalog defines the keys and their argument types; every\n// other catalog must have the same keys with the same signatures (a missing key, an unknown one or a wrong argument is\n// a type error); values are strings or functions (plurals, word order). `t` renders in a language: bound to a host's\n// (`useMessages`, `scope.messages`, `t.in`), or plain, in the render under way's, else in the first catalog.\n// `t.message` builds a message as data (`{ namespace, key, params }`) for state, notices and errors, which each client\n// renders with `t.render` in its own language, checked at runtime (it crossed a link).\n\nimport { arr, bool, nul, num, obj, str, union } from \"../contracts/index.ts\";\nimport { checkName } from \"../contracts/names.ts\";\nimport { currentLanguage, inLanguage, type Language } from \"./language.ts\";\nimport { canonicalLocale, type Translation } from \"./translations.ts\";\n\n/** A message's value: a text, or a function of its arguments returning one. */\nexport type MessageValue = string | ((...args: never[]) => string);\n\n/** A catalog: the messages of one namespace in one language, by key. */\nexport type Catalog = { readonly [key: string]: MessageValue };\n\n/** A catalog's shape as other catalogs must match it: its keys, strings as `string`, functions with their signatures. */\nexport type CatalogShape<M> = { readonly [K in keyof M]: M[K] extends string ? string : M[K] };\n\n/** The arguments of a message: its function's parameters, none for a text. */\nexport type MessageArgs<V> = V extends (...args: infer A) => string ? A : [];\n\n/** A parameter of a message as data: plain JSON (a date as an ISO string or a number), so it crosses links. */\nexport type MessageParam = string | number | boolean | null;\n\n/**\n * A message as data: its namespace, its key and its parameters; typed by `t.message` (`MessageData<\"notes\", \"saved\">`),\n * any namespace and key as `MessageSchema` carries it across a link. (`Message` is the link protocol's.)\n */\nexport type MessageData<N extends string = string, K extends string = string> = {\n\treadonly namespace: N;\n\treadonly key: K;\n\t// Not a readonly array: a message goes into documents, whose drafts are mutable (immutable by convention).\n\treadonly params: MessageParam[];\n};\n\n/** The schema of a message as data, for contract members (`notice: union([MessageSchema, nul()])`). */\nexport const MessageSchema = obj({\n\tnamespace: str(),\n\tkey: str(),\n\tparams: arr(union([str(), num(), bool(), nul()])),\n});\n\n/** The keys of `M` whose arguments are all `MessageParam`s: those `t.message` can build. */\nexport type DataKeys<M> = {\n\t[K in keyof M & string]: MessageArgs<M[K]> extends readonly MessageParam[] ? K : never;\n}[keyof M & string];\n\n/** A message of namespace `N`, or one of any namespace (`string`, from a schema): another literal namespace is refused. */\ntype OfNamespace<G extends MessageData, N extends string> = string extends G[\"namespace\"]\n\t? unknown\n\t: { readonly namespace: N };\n\n/** Renders the messages of namespace `N` with catalog shape `M` in one language. */\nexport type Translator<N extends string, M> = {\n\t/** The message `key` with its arguments. */\n\t<K extends keyof M & string>(key: K, ...args: MessageArgs<M[K]>): string;\n\t/** A message as data; a foreign namespace or an unknown key shows the key (and is reported). */\n\trender<G extends MessageData>(message: G & OfNamespace<G, N>): string;\n};\n\n/** A plugin's messages: `t` itself (in the current language), its namespace, its catalogs as contributions, `message`. */\nexport type Messages<N extends string, M> = Translator<N, M> & {\n\treadonly namespace: N;\n\t/** Its catalogs as `Translations` entries: a facet that renders contributes them. */\n\treadonly translations: readonly Translation[];\n\t/** The message `key` with its arguments as data, for state that clients render. */\n\tmessage<K extends DataKeys<M>>(key: K, ...args: MessageArgs<M[K]>): MessageData<N, K>;\n\t/** `t` in `language` (`undefined`: the first catalog). */\n\tin(language: Language | undefined): Translator<N, M>;\n};\n\n/** The catalog shape of a plugin's messages: what a translation fills (`const fr: MessagesOf<typeof t> = {...}`). */\nexport type MessagesOf<T> = T extends Messages<string, infer M> ? M : never;\n\n/**\n * The messages of `namespace` (a name like a type's, `[a-z0-9@/._~-]`) in `catalogs` by locale; the first catalog\n * defines the keys and signatures, the others match it.\n */\nexport function defineMessages<const N extends string, M extends Catalog>(\n\tnamespace: N,\n\tcatalogs: { readonly [locale: string]: CatalogShape<M> },\n): Messages<N, CatalogShape<M>> {\n\t// Declaration policy: a namespace is a name, a catalog's key a language tag (JavaScript callers reach both).\n\tcheckName(namespace, \"A messages namespace\");\n\tconst own = new Map<string, Catalog>();\n\tfor (const [locale, catalog] of Object.entries(catalogs)) {\n\t\tconst canonical = canonicalLocale(locale);\n\t\tif (canonical === undefined) throw new Error(`${namespace}: \"${locale}\" is no language tag`);\n\t\town.set(canonical, catalog);\n\t}\n\tconst first = own.values().next().value;\n\tif (first === undefined) throw new Error(`${namespace}: defineMessages needs a catalog`);\n\tconst source: Source = { namespace, own, first };\n\tconst translations = [...own].map(([locale, messages]) => ({ namespace, locale, messages }));\n\t// The overloads `Messages` types are these functions', keyed by the catalog's shape.\n\treturn Object.assign(translator<N, CatalogShape<M>>(source, currentLanguage), {\n\t\tnamespace,\n\t\ttranslations,\n\t\tmessage: (key: string, ...params: MessageParam[]) => ({ namespace, key, params }),\n\t\tin: (language: Language | undefined) => translator<N, CatalogShape<M>>(source, () => language),\n\t}) as Messages<N, CatalogShape<M>>;\n}\n\n/** A namespace's own catalogs, by canonical locale, and its first. */\ntype Source = { readonly namespace: string; readonly own: ReadonlyMap<string, Catalog>; readonly first: Catalog };\n\n/** A translator of `source`'s messages in the language `language` reads at each call. */\nfunction translator<N extends string, M>(source: Source, language: () => Language | undefined): Translator<N, M> {\n\tconst t = (key: string, ...args: unknown[]): string => renderKey(source, language(), key, args);\n\tconst render = (message: MessageData): string => renderData(source, language(), message);\n\t// The overloads `Translator` types are this one function's, keyed by the catalog's shape.\n\treturn Object.assign(t, { render }) as unknown as Translator<N, M>;\n}\n\n/**\n * `key` of `source` in `language`: down its chain, at each locale the host's contributed catalog, then the plugin's own;\n * else the first catalog.\n */\nfunction renderKey(source: Source, language: Language | undefined, key: string, args: readonly unknown[]): string {\n\tif (language === undefined) return call(source.first[key]!, args);\n\treturn inLanguage(language, () => {\n\t\tfor (const [index, locale] of language.chain.entries()) {\n\t\t\tconst contributed = language.translations.catalogs.get(source.namespace)?.get(locale);\n\t\t\tif (contributed !== undefined && Object.hasOwn(contributed.value.messages, key)) {\n\t\t\t\ttry {\n\t\t\t\t\treturn found(language, source, key, index, call(contributed.value.messages[key]!, args));\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// A contributed catalog is a plugin's code: reported, and the chain goes on (design §17).\n\t\t\t\t\tconst { plugin } = contributed;\n\t\t\t\t\tlanguage.report({ kind: \"failed\", namespace: source.namespace, locale, key, plugin, error });\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst own = source.own.get(locale);\n\t\t\tif (own !== undefined && own !== contributed?.value.messages && Object.hasOwn(own, key)) {\n\t\t\t\treturn found(language, source, key, index, call(own[key]!, args));\n\t\t\t}\n\t\t}\n\t\treturn found(language, source, key, language.chain.length, call(source.first[key]!, args));\n\t});\n}\n\n/** `text`, found at `index` in `language`'s chain (its length: the first catalog), a fallback reported past the first. */\nfunction found(language: Language, source: Source, key: string, index: number, text: string): string {\n\tif (index > 0) {\n\t\tconst used = language.chain[index];\n\t\tlanguage.report({ kind: \"fallback\", namespace: source.namespace, locale: language.locale, key, used });\n\t}\n\treturn text;\n}\n\n/** A message's text: the text, or the function called with `args` (typed by the catalog's signature). */\nfunction call(value: MessageValue, args: readonly unknown[]): string {\n\treturn typeof value === \"string\" ? value : (value as (...params: readonly unknown[]) => string)(...args);\n}\n\n/**\n * A message as data in `language`. Checked first (wire input: the message crossed a link as state): another namespace,\n * a key the first catalog lacks or params that are no list show the key, reported; so does a message that throws.\n */\nfunction renderData(source: Source, language: Language | undefined, message: MessageData): string {\n\tconst { namespace, key, params } = message;\n\tconst known = namespace === source.namespace && Object.hasOwn(source.first, key) && Array.isArray(params);\n\tif (!known) {\n\t\tlanguage?.report({ kind: \"unknown\", namespace, key, expected: source.namespace });\n\t\treturn key;\n\t}\n\ttry {\n\t\treturn renderKey(source, language, key, params);\n\t} catch (error) {\n\t\tlanguage?.report({ kind: \"failed\", namespace, locale: language.locale, key, plugin: undefined, error });\n\t\treturn key;\n\t}\n}\n"]}

package/dist/surfaces/page-state.d.ts

@@ -0,0 +1,14 @@
+import type { Principal } from "../data/index.ts";
+import type { Host } from "../host/index.ts";
+/** One key's value in a host's page state. Its functions are bound: React's `useSyncExternalStore` takes them as is. */
+export type PageState<T> = {
+    /** The value now. */
+    readonly read: () => T;
+    /** Sets the value; a new value (by identity) calls every subscriber. */
+    readonly set: (value: T) => void;
+    /** Calls `changed` after every set that changed the value, until the returned unsubscribe. */
+    readonly subscribe: (changed: () => void) => () => void;
+};
+/** The page state of `host` at `key`: what was kept there, or `initial` when the key is new. */
+export declare function pageState<T, P extends Principal = Principal>(host: Host<P>, key: string, initial: T): PageState<T>;
+//# sourceMappingURL=page-state.d.ts.map

package/dist/surfaces/page-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-state.d.ts","sourceRoot":"","sources":["../../src/surfaces/page-state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,wHAAwH;AACxH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACjC,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CACxD,CAAC;AAKF,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAalH"}

package/dist/surfaces/page-state.js

@@ -0,0 +1,43 @@
+// Page state (decision "Tutorial gaps" (1), refining "Slice 11, P4"): values a client host keeps for its UI by key,
+// beside its plugins, so a component of a reloaded plugin (a new function, which React or a terminal scope mounts
+// anew) finds what it had: a half-typed message, a scroll position. Same-host values of any kind, never on the wire;
+// gone with the host (a page reload, a terminal's new base bundle). `usePageState` and `TuiScope.pageState` read it.
+/** Each client host's page state by key, kept as long as the host. */
+const PAGE_STATES = new WeakMap();
+/** The page state of `host` at `key`: what was kept there, or `initial` when the key is new. */
+export function pageState(host, key, initial) {
+    let states = PAGE_STATES.get(host);
+    if (states === undefined) {
+        states = new Map();
+        PAGE_STATES.set(host, states);
+    }
+    let state = states.get(key);
+    if (state === undefined) {
+        state = keptValue(initial);
+        states.set(key, state);
+    }
+    // A key is the app's: whoever names it names its type too.
+    return state;
+}
+/** A value with its subscribers. */
+function keptValue(initial) {
+    let value = initial;
+    const subscribers = new Set();
+    return {
+        read: () => value,
+        set: (next) => {
+            if (next === value)
+                return;
+            value = next;
+            for (const changed of subscribers)
+                changed();
+        },
+        subscribe: (changed) => {
+            subscribers.add(changed);
+            return () => {
+                subscribers.delete(changed);
+            };
+        },
+    };
+}
+//# sourceMappingURL=page-state.js.map

package/dist/surfaces/page-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-state.js","sourceRoot":"","sources":["../../src/surfaces/page-state.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,kHAAkH;AAClH,qHAAqH;AACrH,qHAAqH;AAerH,sEAAsE;AACtE,MAAM,WAAW,GAAG,IAAI,OAAO,EAA2C,CAAC;AAE3E,gGAAgG;AAChG,MAAM,UAAU,SAAS,CAAqC,IAAa,EAAE,GAAW,EAAE,OAAU;IACnG,IAAI,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACnB,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,KAAK,GAAG,SAAS,CAAU,OAAO,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;IACD,2DAA2D;IAC3D,OAAO,KAAqB,CAAC;AAC9B,CAAC;AAED,oCAAoC;AACpC,SAAS,SAAS,CAAI,OAAU;IAC/B,IAAI,KAAK,GAAG,OAAO,CAAC;IACpB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAc,CAAC;IAC1C,OAAO;QACN,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK;QACjB,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE;YACb,IAAI,IAAI,KAAK,KAAK;gBAAE,OAAO;YAC3B,KAAK,GAAG,IAAI,CAAC;YACb,KAAK,MAAM,OAAO,IAAI,WAAW;gBAAE,OAAO,EAAE,CAAC;QAC9C,CAAC;QACD,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YACtB,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzB,OAAO,GAAG,EAAE;gBACX,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["// Page state (decision \"Tutorial gaps\" (1), refining \"Slice 11, P4\"): values a client host keeps for its UI by key,\n// beside its plugins, so a component of a reloaded plugin (a new function, which React or a terminal scope mounts\n// anew) finds what it had: a half-typed message, a scroll position. Same-host values of any kind, never on the wire;\n// gone with the host (a page reload, a terminal's new base bundle). `usePageState` and `TuiScope.pageState` read it.\n\nimport type { Principal } from \"../data/index.ts\";\nimport type { Host } from \"../host/index.ts\";\n\n/** One key's value in a host's page state. Its functions are bound: React's `useSyncExternalStore` takes them as is. */\nexport type PageState<T> = {\n\t/** The value now. */\n\treadonly read: () => T;\n\t/** Sets the value; a new value (by identity) calls every subscriber. */\n\treadonly set: (value: T) => void;\n\t/** Calls `changed` after every set that changed the value, until the returned unsubscribe. */\n\treadonly subscribe: (changed: () => void) => () => void;\n};\n\n/** Each client host's page state by key, kept as long as the host. */\nconst PAGE_STATES = new WeakMap<object, Map<string, PageState<unknown>>>();\n\n/** The page state of `host` at `key`: what was kept there, or `initial` when the key is new. */\nexport function pageState<T, P extends Principal = Principal>(host: Host<P>, key: string, initial: T): PageState<T> {\n\tlet states = PAGE_STATES.get(host);\n\tif (states === undefined) {\n\t\tstates = new Map();\n\t\tPAGE_STATES.set(host, states);\n\t}\n\tlet state = states.get(key);\n\tif (state === undefined) {\n\t\tstate = keptValue<unknown>(initial);\n\t\tstates.set(key, state);\n\t}\n\t// A key is the app's: whoever names it names its type too.\n\treturn state as PageState<T>;\n}\n\n/** A value with its subscribers. */\nfunction keptValue<T>(initial: T): PageState<T> {\n\tlet value = initial;\n\tconst subscribers = new Set<() => void>();\n\treturn {\n\t\tread: () => value,\n\t\tset: (next) => {\n\t\t\tif (next === value) return;\n\t\t\tvalue = next;\n\t\t\tfor (const changed of subscribers) changed();\n\t\t},\n\t\tsubscribe: (changed) => {\n\t\t\tsubscribers.add(changed);\n\t\t\treturn () => {\n\t\t\t\tsubscribers.delete(changed);\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/surfaces/preference.d.ts

@@ -0,0 +1,32 @@
+import { type Schema } from "../contracts/index.ts";
+import type { Principal } from "../data/index.ts";
+import { type Facet } from "../host/index.ts";
+import type { JsonValue } from "../json.ts";
+/** A preference's contract as its facet serves it: the caller's `pick` (JSON) and `choose`, remote on the server. */
+export type PreferenceContract = ReturnType<typeof preferenceContract<string, JsonValue>>;
+/** A preference's remote contract `name`: the caller's pick on the server (`pick`), and `choose` to change it. */
+export declare function preferenceContract<const N extends string, T>(name: N, pick: Schema<T>): import("../contracts/contract.ts").Contract<{
+    kind: "remote";
+    name: N;
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            readonly main: {
+                state: {
+                    readonly pick: Schema<T>;
+                };
+                methods: {
+                    readonly choose: import("../contracts/schema.ts").Method<Schema<T>, import("../contracts/schema.ts").NullSchema>;
+                };
+            };
+        };
+        changes: never;
+    }];
+}>;
+/**
+ * The kit's server facet of the preference `Choice`: every principal's pick in one persisted document of the store
+ * `store` by principal key, and each principal's `Choice` (`none` before a choice).
+ */
+export declare function preferenceFacet<P extends Principal>(Choice: PreferenceContract, store: string, pick: Schema<JsonValue>, none: JsonValue): Facet<P>;
+//# sourceMappingURL=preference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preference.d.ts","sourceRoot":"","sources":["../../src/surfaces/preference.ts"],"names":[],"mappings":"AAOA,OAAO,EAA6C,KAAK,MAAM,EAAO,MAAM,uBAAuB,CAAC;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,qHAAqH;AACrH,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAE1F,kHAAkH;AAClH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;GAOrF;AAKD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EAClD,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,EACvB,IAAI,EAAE,SAAS,GACb,KAAK,CAAC,CAAC,CAAC,CA4CV"}

package/dist/surfaces/preference.js

@@ -0,0 +1,72 @@
+// A user's preference kept by the server (slice 11 §4b; decision "Messages and languages in the app kit" (3)): one pick
+// per principal, kept by the kit's server and held by every page and terminal of that principal, so choosing restyles
+// or re-renders them all at once. The theme choice and the locale choice are two of them. Bounded (fix round 1: Opus
+// M4, Fable L7): the store keeps the picks of the `MAX_PICKS` principals who chose last (a public app's guests choose
+// too).
+import { BACKGROUND_CONTEXT } from "../context/index.js";
+import { hostKind, local, map, method, obj, remote, str } from "../contracts/index.js";
+import { principalKey } from "../data/principal.js";
+import { defineState } from "../documents/index.js";
+import { defineFacet } from "../host/index.js";
+/** A preference's remote contract `name`: the caller's pick on the server (`pick`), and `choose` to change it. */
+export function preferenceContract(name, pick) {
+    return remote(name, {
+        version: 1,
+        params: {},
+        hostAddress: () => hostKind("server")(),
+        variants: { main: { state: { pick }, methods: { choose: method(pick) } } },
+    });
+}
+/** How many principals' picks a store keeps: past it the earliest chooser's goes (they get the preference's none). */
+const MAX_PICKS = 10_000;
+/**
+ * The kit's server facet of the preference `Choice`: every principal's pick in one persisted document of the store
+ * `store` by principal key, and each principal's `Choice` (`none` before a choice).
+ */
+export function preferenceFacet(Choice, store, pick, none) {
+    const Picks = defineState(store, {
+        schema: obj({ picks: map(pick) }),
+        version: 1,
+        initial: () => ({ picks: {} }),
+        persist: true,
+        checkpointWhen: (_value, _ops, { deltasSinceBase }) => deltasSinceBase >= 50,
+    });
+    // A persisted state needs a local type with empty params.
+    const PickStore = local(store, {
+        version: 1,
+        params: {},
+        members: { picks: map(pick), set: method(obj({ key: str(), pick })) },
+    });
+    return defineFacet((host) => {
+        host.serve(PickStore, (_params, self) => {
+            const picks = self.state(Picks);
+            return {
+                picks: self.derive([picks], ([value]) => value.picks),
+                set: async ({ key, pick: next }, ctx) => {
+                    await picks.change((draft) => {
+                        // Re-added last: the keys keep the order of choosing, the first the earliest.
+                        delete draft.picks[key];
+                        draft.picks[key] = next;
+                        const keys = Object.keys(draft.picks);
+                        for (const old of keys.slice(0, Math.max(0, keys.length - MAX_PICKS)))
+                            delete draft.picks[old];
+                    }, ctx);
+                    return null;
+                },
+            };
+        });
+        host.serve(Choice, (_params, principal, self) => {
+            const picks = self.get(PickStore, {});
+            const key = principalKey(principal, BACKGROUND_CONTEXT);
+            return {
+                variant: "main",
+                members: {
+                    // A key that is a principal's canonical JSON: `Object.hasOwn`, no inherited member is a pick.
+                    pick: self.derive([picks.picks], ([all]) => (Object.hasOwn(all, key) ? all[key] : none)),
+                    choose: (next, ctx) => picks.set({ key, pick: next }, ctx),
+                },
+            };
+        });
+    });
+}
+//# sourceMappingURL=preference.js.map

package/dist/surfaces/preference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference.js","sourceRoot":"","sources":["../../src/surfaces/preference.ts"],"names":[],"mappings":"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","sourcesContent":["// A user's preference kept by the server (slice 11 §4b; decision \"Messages and languages in the app kit\" (3)): one pick\n// per principal, kept by the kit's server and held by every page and terminal of that principal, so choosing restyles\n// or re-renders them all at once. The theme choice and the locale choice are two of them. Bounded (fix round 1: Opus\n// M4, Fable L7): the store keeps the picks of the `MAX_PICKS` principals who chose last (a public app's guests choose\n// too).\n\nimport { BACKGROUND_CONTEXT } from \"../context/index.ts\";\nimport { hostKind, local, map, method, obj, remote, type Schema, str } from \"../contracts/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport { principalKey } from \"../data/principal.ts\";\nimport { defineState } from \"../documents/index.ts\";\nimport { defineFacet, type Facet } from \"../host/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\n\n/** A preference's contract as its facet serves it: the caller's `pick` (JSON) and `choose`, remote on the server. */\nexport type PreferenceContract = ReturnType<typeof preferenceContract<string, JsonValue>>;\n\n/** A preference's remote contract `name`: the caller's pick on the server (`pick`), and `choose` to change it. */\nexport function preferenceContract<const N extends string, T>(name: N, pick: Schema<T>) {\n\treturn remote(name, {\n\t\tversion: 1,\n\t\tparams: {},\n\t\thostAddress: () => hostKind(\"server\")(),\n\t\tvariants: { main: { state: { pick }, methods: { choose: method(pick) } } },\n\t});\n}\n\n/** How many principals' picks a store keeps: past it the earliest chooser's goes (they get the preference's none). */\nconst MAX_PICKS = 10_000;\n\n/**\n * The kit's server facet of the preference `Choice`: every principal's pick in one persisted document of the store\n * `store` by principal key, and each principal's `Choice` (`none` before a choice).\n */\nexport function preferenceFacet<P extends Principal>(\n\tChoice: PreferenceContract,\n\tstore: string,\n\tpick: Schema<JsonValue>,\n\tnone: JsonValue,\n): Facet<P> {\n\tconst Picks = defineState(store, {\n\t\tschema: obj({ picks: map(pick) }),\n\t\tversion: 1,\n\t\tinitial: () => ({ picks: {} }),\n\t\tpersist: true,\n\t\tcheckpointWhen: (_value, _ops, { deltasSinceBase }) => deltasSinceBase >= 50,\n\t});\n\t// A persisted state needs a local type with empty params.\n\tconst PickStore = local(store, {\n\t\tversion: 1,\n\t\tparams: {},\n\t\tmembers: { picks: map(pick), set: method(obj({ key: str(), pick })) },\n\t});\n\treturn defineFacet<P>((host) => {\n\t\thost.serve(PickStore, (_params, self) => {\n\t\t\tconst picks = self.state(Picks);\n\t\t\treturn {\n\t\t\t\tpicks: self.derive([picks], ([value]) => value.picks),\n\t\t\t\tset: async ({ key, pick: next }, ctx) => {\n\t\t\t\t\tawait picks.change((draft) => {\n\t\t\t\t\t\t// Re-added last: the keys keep the order of choosing, the first the earliest.\n\t\t\t\t\t\tdelete draft.picks[key];\n\t\t\t\t\t\tdraft.picks[key] = next;\n\t\t\t\t\t\tconst keys = Object.keys(draft.picks);\n\t\t\t\t\t\tfor (const old of keys.slice(0, Math.max(0, keys.length - MAX_PICKS))) delete draft.picks[old];\n\t\t\t\t\t}, ctx);\n\t\t\t\t\treturn null;\n\t\t\t\t},\n\t\t\t};\n\t\t});\n\t\thost.serve(Choice, (_params, principal, self) => {\n\t\t\tconst picks = self.get(PickStore, {});\n\t\t\tconst key = principalKey(principal, BACKGROUND_CONTEXT);\n\t\t\treturn {\n\t\t\t\tvariant: \"main\",\n\t\t\t\tmembers: {\n\t\t\t\t\t// A key that is a principal's canonical JSON: `Object.hasOwn`, no inherited member is a pick.\n\t\t\t\t\tpick: self.derive([picks.picks], ([all]) => (Object.hasOwn(all, key) ? all[key]! : none)),\n\t\t\t\t\tchoose: (next, ctx) => picks.set({ key, pick: next }, ctx),\n\t\t\t\t},\n\t\t\t};\n\t\t});\n\t});\n}\n"]}