@earendil-works/chord 1.4.0 → 1.5.1

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"]}

package/dist/surfaces/registered.d.ts

@@ -0,0 +1,33 @@
+import type { Principal } from "../data/index.ts";
+import type { Facet } from "../host/index.ts";
+/** The global function a registered script calls: defined by the client before any plugin script runs. */
+export declare const REGISTER = "chordFacet";
+/** A built facet's function, as its script registers it. */
+export type FacetFunction = (require: (specifier: string) => unknown, module: {
+    exports: unknown;
+}, exports: unknown) => void;
+/** One registered script: its plugin, its digest and its function. */
+export type RegisteredScript = {
+    readonly plugin: string;
+    readonly digest: string;
+    readonly run: FacetFunction;
+};
+/** The modules a client's plugin scripts import, by specifier (the app's API modules for the kind, React, ...). */
+export type ClientModules = Readonly<Record<string, unknown>>;
+/**
+ * The text of a registered script for `plugin`'s facet built as `source` (one function expression, the build's
+ * wrapped CommonJS script) with `digest`. Its source map comment stays on its own line, before the closing call.
+ */
+export declare function registeredSource(plugin: string, digest: string, source: string): string;
+/**
+ * Runs `script`'s function and returns its facet (its default export). Its `require` answers `modules` only (the build
+ * kept nothing else external for a client kind); anything else throws naming the plugin. Throws what the script throws,
+ * and when its default export is no facet.
+ */
+export declare function evaluateRegistered<P extends Principal = Principal>(script: RegisteredScript, modules: ClientModules): Facet<P>;
+/**
+ * A host package as a CommonJS script imports it: an ESM namespace wrapped once with `__esModule` (so esbuild's interop
+ * reads its `default` for a default import, its names for named ones), any other value as it is.
+ */
+export declare function interop(value: unknown): unknown;
+//# sourceMappingURL=registered.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registered.d.ts","sourceRoot":"","sources":["../../src/surfaces/registered.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,0GAA0G;AAC1G,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,CAC3B,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,EACvC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EAC5B,OAAO,EAAE,OAAO,KACZ,IAAI,CAAC;AAEV,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;CAAE,CAAC;AAEjH,mHAAmH;AACnH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EACjE,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,aAAa,GACpB,KAAK,CAAC,CAAC,CAAC,CAiBV;AAKD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAU/C"}

package/dist/surfaces/registered.js

@@ -0,0 +1,51 @@
+// Plugin scripts that register themselves (slice 11 §1, §2, decision "Slice 11's points" (P2)): a facet's built script
+// served as `chordFacet("<plugin>", "<digest>", function (require, module, exports) { … })`, loaded with `<script src>`
+// (a page under a `'self'` CSP: no `eval`, no `new Function`) or run by the terminal's runtime; the client evaluates the
+// registered function with a `require` that answers only its host packages.
+/** The global function a registered script calls: defined by the client before any plugin script runs. */
+export const REGISTER = "chordFacet";
+/**
+ * The text of a registered script for `plugin`'s facet built as `source` (one function expression, the build's
+ * wrapped CommonJS script) with `digest`. Its source map comment stays on its own line, before the closing call.
+ */
+export function registeredSource(plugin, digest, source) {
+    return `${REGISTER}(${JSON.stringify(plugin)},${JSON.stringify(digest)},${source}\n);\n`;
+}
+/**
+ * Runs `script`'s function and returns its facet (its default export). Its `require` answers `modules` only (the build
+ * kept nothing else external for a client kind); anything else throws naming the plugin. Throws what the script throws,
+ * and when its default export is no facet.
+ */
+export function evaluateRegistered(script, modules) {
+    const where = `plugin "${script.plugin}"`;
+    const module = { exports: {} };
+    script.run((specifier) => {
+        if (Object.hasOwn(modules, specifier))
+            return interop(modules[specifier]);
+        throw new Error(`${where}: "${specifier}" is not one of this client's host packages`);
+    }, module, module.exports);
+    // A trust boundary: plugin code; its default export is checked to be a facet.
+    const facet = module.exports?.default;
+    if (typeof facet !== "object" || facet === null || typeof facet.setup !== "function") {
+        throw new Error(`${where}: its default export is not a facet (defineFacet)`);
+    }
+    return facet;
+}
+/** ESM namespaces wrapped for a CommonJS script, by namespace: one wrapper per namespace, held as long as it is. */
+const wrapped = new WeakMap();
+/**
+ * A host package as a CommonJS script imports it: an ESM namespace wrapped once with `__esModule` (so esbuild's interop
+ * reads its `default` for a default import, its names for named ones), any other value as it is.
+ */
+export function interop(value) {
+    if (typeof value !== "object" || value === null || Object.prototype.toString.call(value) !== "[object Module]") {
+        return value;
+    }
+    let made = wrapped.get(value);
+    if (made === undefined) {
+        made = { ...value, __esModule: true };
+        wrapped.set(value, made);
+    }
+    return made;
+}
+//# sourceMappingURL=registered.js.map

package/dist/surfaces/registered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered.js","sourceRoot":"","sources":["../../src/surfaces/registered.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,wHAAwH;AACxH,yHAAyH;AACzH,4EAA4E;AAK5E,0GAA0G;AAC1G,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAerC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,MAAc,EAAE,MAAc;IAC9E,OAAO,GAAG,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,QAAQ,CAAC;AAC1F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CACjC,MAAwB,EACxB,OAAsB;IAEtB,MAAM,KAAK,GAAG,WAAW,MAAM,CAAC,MAAM,GAAG,CAAC;IAC1C,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,MAAM,CAAC,GAAG,CACT,CAAC,SAAS,EAAE,EAAE;QACb,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,MAAM,SAAS,6CAA6C,CAAC,CAAC;IACvF,CAAC,EACD,MAAM,EACN,MAAM,CAAC,OAAO,CACd,CAAC;IACF,8EAA8E;IAC9E,MAAM,KAAK,GAAI,MAAM,CAAC,OAAiD,EAAE,OAAO,CAAC;IACjF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAA6B,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QAC/G,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,mDAAmD,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,KAAiB,CAAC;AAC1B,CAAC;AAED,oHAAoH;AACpH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAkB,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,EAAE,CAAC;QAChH,OAAO,KAAK,CAAC;IACd,CAAC;IACD,IAAI,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,GAAG,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC","sourcesContent":["// Plugin scripts that register themselves (slice 11 §1, §2, decision \"Slice 11's points\" (P2)): a facet's built script\n// served as `chordFacet(\"<plugin>\", \"<digest>\", function (require, module, exports) { … })`, loaded with `<script src>`\n// (a page under a `'self'` CSP: no `eval`, no `new Function`) or run by the terminal's runtime; the client evaluates the\n// registered function with a `require` that answers only its host packages.\n\nimport type { Principal } from \"../data/index.ts\";\nimport type { Facet } from \"../host/index.ts\";\n\n/** The global function a registered script calls: defined by the client before any plugin script runs. */\nexport const REGISTER = \"chordFacet\";\n\n/** A built facet's function, as its script registers it. */\nexport type FacetFunction = (\n\trequire: (specifier: string) => unknown,\n\tmodule: { exports: unknown },\n\texports: unknown,\n) => void;\n\n/** One registered script: its plugin, its digest and its function. */\nexport type RegisteredScript = { readonly plugin: string; readonly digest: string; readonly run: FacetFunction };\n\n/** The modules a client's plugin scripts import, by specifier (the app's API modules for the kind, React, ...). */\nexport type ClientModules = Readonly<Record<string, unknown>>;\n\n/**\n * The text of a registered script for `plugin`'s facet built as `source` (one function expression, the build's\n * wrapped CommonJS script) with `digest`. Its source map comment stays on its own line, before the closing call.\n */\nexport function registeredSource(plugin: string, digest: string, source: string): string {\n\treturn `${REGISTER}(${JSON.stringify(plugin)},${JSON.stringify(digest)},${source}\\n);\\n`;\n}\n\n/**\n * Runs `script`'s function and returns its facet (its default export). Its `require` answers `modules` only (the build\n * kept nothing else external for a client kind); anything else throws naming the plugin. Throws what the script throws,\n * and when its default export is no facet.\n */\nexport function evaluateRegistered<P extends Principal = Principal>(\n\tscript: RegisteredScript,\n\tmodules: ClientModules,\n): Facet<P> {\n\tconst where = `plugin \"${script.plugin}\"`;\n\tconst module = { exports: {} as unknown };\n\tscript.run(\n\t\t(specifier) => {\n\t\t\tif (Object.hasOwn(modules, specifier)) return interop(modules[specifier]);\n\t\t\tthrow new Error(`${where}: \"${specifier}\" is not one of this client's host packages`);\n\t\t},\n\t\tmodule,\n\t\tmodule.exports,\n\t);\n\t// A trust boundary: plugin code; its default export is checked to be a facet.\n\tconst facet = (module.exports as { readonly default?: unknown } | null)?.default;\n\tif (typeof facet !== \"object\" || facet === null || typeof (facet as { setup?: unknown }).setup !== \"function\") {\n\t\tthrow new Error(`${where}: its default export is not a facet (defineFacet)`);\n\t}\n\treturn facet as Facet<P>;\n}\n\n/** ESM namespaces wrapped for a CommonJS script, by namespace: one wrapper per namespace, held as long as it is. */\nconst wrapped = new WeakMap<object, object>();\n\n/**\n * A host package as a CommonJS script imports it: an ESM namespace wrapped once with `__esModule` (so esbuild's interop\n * reads its `default` for a default import, its names for named ones), any other value as it is.\n */\nexport function interop(value: unknown): unknown {\n\tif (typeof value !== \"object\" || value === null || Object.prototype.toString.call(value) !== \"[object Module]\") {\n\t\treturn value;\n\t}\n\tlet made = wrapped.get(value);\n\tif (made === undefined) {\n\t\tmade = { ...value, __esModule: true };\n\t\twrapped.set(value, made);\n\t}\n\treturn made;\n}\n"]}

package/dist/surfaces/scripts.d.ts

@@ -0,0 +1,84 @@
+import { type Static } from "../contracts/index.ts";
+/** One plugin's script of the set: its name, its script's digest and URL, its stylesheet's URL when it has one. */
+declare const ScriptEntry: import("../contracts/index.ts").Schema<{
+    name: string;
+    digest: string;
+    url: string;
+    css?: string | undefined;
+}>;
+/** One plugin's script of a set (see `ScriptEntry`). */
+export type ScriptEntry = Static<typeof ScriptEntry>;
+/**
+ * A client kind's current scripts: `base` (the base bundle's hash: a change reloads the client), `combined` (the URL of
+ * one file holding every plugin's script, what a fresh client loads), `plugins` (each one's script, in name order).
+ */
+export declare const ScriptSet: import("../contracts/index.ts").Schema<{
+    base: string;
+    combined: string;
+    plugins: {
+        name: string;
+        digest: string;
+        url: string;
+        css?: string | undefined;
+    }[];
+}>;
+/** A client kind's current scripts (see `ScriptSet`). */
+export type ScriptSet = Static<typeof ScriptSet>;
+/** The current web scripts (`ScriptSet`), served by the server's web surface to any principal that may load the app. */
+export declare const WebScripts: import("../contracts/contract.ts").Contract<{
+    kind: "remote";
+    name: "chord.web.scripts";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            readonly main: {
+                state: {
+                    readonly set: import("../contracts/index.ts").Schema<{
+                        base: string;
+                        combined: string;
+                        plugins: {
+                            name: string;
+                            digest: string;
+                            url: string;
+                            css?: string | undefined;
+                        }[];
+                    }>;
+                };
+                methods: Record<never, never>;
+            };
+        };
+        changes: never;
+    }];
+}>;
+/** The current terminal scripts (`ScriptSet`), served by the server's terminal surface as `WebScripts` is. */
+export declare const TuiScripts: import("../contracts/contract.ts").Contract<{
+    kind: "remote";
+    name: "chord.tui.scripts";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            readonly main: {
+                state: {
+                    readonly set: import("../contracts/index.ts").Schema<{
+                        base: string;
+                        combined: string;
+                        plugins: {
+                            name: string;
+                            digest: string;
+                            url: string;
+                            css?: string | undefined;
+                        }[];
+                    }>;
+                };
+                methods: Record<never, never>;
+            };
+        };
+        changes: never;
+    }];
+}>;
+/** The contract of a client kind's scripts, as clients hold it (`WebScripts`, `TuiScripts`). */
+export type ScriptsContract = typeof WebScripts | typeof TuiScripts;
+export {};
+//# sourceMappingURL=scripts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/surfaces/scripts.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmC,KAAK,MAAM,EAAO,MAAM,uBAAuB,CAAC;AAK1F,mHAAmH;AACnH,QAAA,MAAM,WAAW;;;;;EAAmE,CAAC;AAErF,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;EAAmE,CAAC;AAE1F,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEjD,wHAAwH;AACxH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;EAAuC,CAAC;AAE/D,8GAA8G;AAC9G,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;EAAuC,CAAC;AAY/D,gGAAgG;AAChG,MAAM,MAAM,eAAe,GAAG,OAAO,UAAU,GAAG,OAAO,UAAU,CAAC"}

package/dist/surfaces/scripts.js

@@ -0,0 +1,28 @@
+// The current plugin scripts of a client kind (slice 11 §1, decision "Slice 11, P5"): what the server's surface serves
+// as a remote object every page and terminal holds. Its state is the set: the base bundle's hash, the combined file of
+// every plugin script, and each plugin's script (and stylesheet); a rollout shipping the kind publishes a new set, and
+// each client fetches what changed.
+import { arr, hostKind, obj, opt, remote, str } from "../contracts/index.js";
+/** The server's host kind as the surfaces place their objects: the app kit's server is `Server()`. */
+const Server = hostKind("server");
+/** One plugin's script of the set: its name, its script's digest and URL, its stylesheet's URL when it has one. */
+const ScriptEntry = obj({ name: str(), digest: str(), url: str(), css: opt(str()) });
+/**
+ * A client kind's current scripts: `base` (the base bundle's hash: a change reloads the client), `combined` (the URL of
+ * one file holding every plugin's script, what a fresh client loads), `plugins` (each one's script, in name order).
+ */
+export const ScriptSet = obj({ base: str(), combined: str(), plugins: arr(ScriptEntry) });
+/** The current web scripts (`ScriptSet`), served by the server's web surface to any principal that may load the app. */
+export const WebScripts = scriptsContract("chord.web.scripts");
+/** The current terminal scripts (`ScriptSet`), served by the server's terminal surface as `WebScripts` is. */
+export const TuiScripts = scriptsContract("chord.tui.scripts");
+/** The contract of a client kind's current scripts, named `name`: a remote object on the server, its state the set. */
+function scriptsContract(name) {
+    return remote(name, {
+        version: 1,
+        params: {},
+        hostAddress: () => Server(),
+        variants: { main: { state: { set: ScriptSet } } },
+    });
+}
+//# sourceMappingURL=scripts.js.map

package/dist/surfaces/scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.js","sourceRoot":"","sources":["../../src/surfaces/scripts.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,uHAAuH;AACvH,uHAAuH;AACvH,oCAAoC;AAEpC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAe,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAE1F,sGAAsG;AACtG,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAElC,mHAAmH;AACnH,MAAM,WAAW,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAKrF;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;AAK1F,wHAAwH;AACxH,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CAAC,mBAAmB,CAAC,CAAC;AAE/D,8GAA8G;AAC9G,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CAAC,mBAAmB,CAAC,CAAC;AAE/D,uHAAuH;AACvH,SAAS,eAAe,CAAyB,IAAO;IACvD,OAAO,MAAM,CAAC,IAAI,EAAE;QACnB,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,EAAE;QACV,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE;QAC3B,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE;KACjD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// The current plugin scripts of a client kind (slice 11 §1, decision \"Slice 11, P5\"): what the server's surface serves\n// as a remote object every page and terminal holds. Its state is the set: the base bundle's hash, the combined file of\n// every plugin script, and each plugin's script (and stylesheet); a rollout shipping the kind publishes a new set, and\n// each client fetches what changed.\n\nimport { arr, hostKind, obj, opt, remote, type Static, str } from \"../contracts/index.ts\";\n\n/** The server's host kind as the surfaces place their objects: the app kit's server is `Server()`. */\nconst Server = hostKind(\"server\");\n\n/** One plugin's script of the set: its name, its script's digest and URL, its stylesheet's URL when it has one. */\nconst ScriptEntry = obj({ name: str(), digest: str(), url: str(), css: opt(str()) });\n\n/** One plugin's script of a set (see `ScriptEntry`). */\nexport type ScriptEntry = Static<typeof ScriptEntry>;\n\n/**\n * A client kind's current scripts: `base` (the base bundle's hash: a change reloads the client), `combined` (the URL of\n * one file holding every plugin's script, what a fresh client loads), `plugins` (each one's script, in name order).\n */\nexport const ScriptSet = obj({ base: str(), combined: str(), plugins: arr(ScriptEntry) });\n\n/** A client kind's current scripts (see `ScriptSet`). */\nexport type ScriptSet = Static<typeof ScriptSet>;\n\n/** The current web scripts (`ScriptSet`), served by the server's web surface to any principal that may load the app. */\nexport const WebScripts = scriptsContract(\"chord.web.scripts\");\n\n/** The current terminal scripts (`ScriptSet`), served by the server's terminal surface as `WebScripts` is. */\nexport const TuiScripts = scriptsContract(\"chord.tui.scripts\");\n\n/** The contract of a client kind's current scripts, named `name`: a remote object on the server, its state the set. */\nfunction scriptsContract<const N extends string>(name: N) {\n\treturn remote(name, {\n\t\tversion: 1,\n\t\tparams: {},\n\t\thostAddress: () => Server(),\n\t\tvariants: { main: { state: { set: ScriptSet } } },\n\t});\n}\n\n/** The contract of a client kind's scripts, as clients hold it (`WebScripts`, `TuiScripts`). */\nexport type ScriptsContract = typeof WebScripts | typeof TuiScripts;\n"]}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"theme-choice.d.ts","sourceRoot":"","sources":["../../src/surfaces/theme-choice.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAU9C,qFAAqF;AACrF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;EAAkD,CAAC;AAK3E,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,CAEhE"}

package/dist/surfaces/theme-choice.js

@@ -0,0 +1,18 @@
+// The user's theme choice (slice 11 §4b): one dark and one light theme id per principal, a preference the server keeps
+// (the kit serves it) and every page and terminal of that principal holds, so choosing a theme restyles them all at
+// once. An id is at most 128 characters (fix round 1: Opus M4, Fable L7).
+import { nul, obj, str, union } from "../contracts/index.js";
+import { preferenceContract, preferenceFacet } from "./preference.js";
+/** A theme id (at most 128 characters), or `null` for the first contributed theme of its mode. */
+const ThemeId = union([str({ max: 128 }), nul()]);
+/** A pick: a theme id per mode. */
+const Pick = obj({ dark: ThemeId, light: ThemeId });
+/** The caller's theme choice, on the server: its pick, and `choose` to change it. */
+export const ThemeChoice = preferenceContract("chord.themes.choice", Pick);
+/** No choice yet: the first contributed theme of each mode. */
+const NO_PICK = { dark: null, light: null };
+/** The kit's server facet for theme choices: the store of picks and each principal's `ThemeChoice`. */
+export function themeChoiceFacet() {
+    return preferenceFacet(ThemeChoice, "chord.themes.picks", Pick, NO_PICK);
+}
+//# sourceMappingURL=theme-choice.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"theme-choice.js","sourceRoot":"","sources":["../../src/surfaces/theme-choice.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,oHAAoH;AACpH,0EAA0E;AAE1E,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGtE,kGAAkG;AAClG,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AAElD,mCAAmC;AACnC,MAAM,IAAI,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;AAEpD,qFAAqF;AACrF,MAAM,CAAC,MAAM,WAAW,GAAG,kBAAkB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;AAE3E,+DAA+D;AAC/D,MAAM,OAAO,GAAc,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAEvD,uGAAuG;AACvG,MAAM,UAAU,gBAAgB;IAC/B,OAAO,eAAe,CAAI,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC7E,CAAC","sourcesContent":["// The user's theme choice (slice 11 §4b): one dark and one light theme id per principal, a preference the server keeps\n// (the kit serves it) and every page and terminal of that principal holds, so choosing a theme restyles them all at\n// once. An id is at most 128 characters (fix round 1: Opus M4, Fable L7).\n\nimport { nul, obj, 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\";\nimport type { ThemePick } from \"./themes.ts\";\n\n/** A theme id (at most 128 characters), or `null` for the first contributed theme of its mode. */\nconst ThemeId = union([str({ max: 128 }), nul()]);\n\n/** A pick: a theme id per mode. */\nconst Pick = obj({ dark: ThemeId, light: ThemeId });\n\n/** The caller's theme choice, on the server: its pick, and `choose` to change it. */\nexport const ThemeChoice = preferenceContract(\"chord.themes.choice\", Pick);\n\n/** No choice yet: the first contributed theme of each mode. */\nconst NO_PICK: ThemePick = { dark: null, light: null };\n\n/** The kit's server facet for theme choices: the store of picks and each principal's `ThemeChoice`. */\nexport function themeChoiceFacet<P extends Principal>(): Facet<P> {\n\treturn preferenceFacet<P>(ThemeChoice, \"chord.themes.picks\", Pick, NO_PICK);\n}\n"]}

package/dist/surfaces/themes.d.ts

@@ -0,0 +1,43 @@
+import type { Principal } from "../data/index.ts";
+import { type Facet } from "../host/index.ts";
+import { type Registry } from "../registries/index.ts";
+/** The roles every theme names: the kit's base set. Apps add their own roles; themes fill at least these. */
+export declare const BASE_ROLES: readonly ["accent", "bg", "fg", "muted", "error", "warning", "success"];
+/** A base role. */
+export type BaseRole = (typeof BASE_ROLES)[number];
+/** A theme: an id, a name, its mode, a colour per role (CSS colours; `#rrggbb` for terminals), web and terminal extras. */
+export type Theme = {
+    readonly id: string;
+    readonly name: string;
+    readonly mode: "dark" | "light";
+    readonly colors: Readonly<Record<BaseRole, string>> & Readonly<Record<string, string>>;
+    /** More CSS variables on `:root`, by name without `--` (`radius`, `font`); URLs of the plugin's assets allowed. */
+    readonly web?: Readonly<Record<string, string>>;
+    /** Terminal colours by role, before `colors`: `#rrggbb` or an xterm 256-colour index (`"208"`). */
+    readonly tui?: Readonly<Record<string, string>>;
+};
+/** The themes plugins contribute, in plugin-name order; served on every client and on the server by the kit. */
+export declare const Themes: Registry<Theme, readonly Theme[]>;
+/** The kit's facet serving `Themes` on a host: the contributions as they are, in plugin-name order. */
+export declare function themesFacet<P extends Principal>(): Facet<P>;
+/** The theme used when no plugin contributed one of a mode: neutral colours. */
+export declare const FALLBACK_THEMES: Readonly<Record<Theme["mode"], Theme>>;
+/** The user's choice: a theme id for dark and one for light (`null`: the first contributed of that mode). */
+export type ThemePick = {
+    readonly dark: string | null;
+    readonly light: string | null;
+};
+/** The active theme for `mode`: the one `pick` names if contributed, else the first of that mode, else the fallback. */
+export declare function activeTheme(themes: readonly Theme[], pick: ThemePick, mode: Theme["mode"]): Theme;
+/** The CSS custom properties of `theme`: `--<role>` for every colour, then `--<name>` for each `web` extra. */
+export declare function themeVariables(theme: Theme): Readonly<Record<string, string>>;
+/** How many colours a terminal shows. */
+export type ColorDepth = "truecolor" | "256";
+/**
+ * The SGR parameters of `role`'s colour in `theme` for a terminal of `depth` (`38;2;r;g;b`, `38;5;n`; `48;…` for a
+ * background): the role's `tui` override first, else its colour, else the fallback theme's; a `#rrggbb` colour is the
+ * nearest of the 256 xterm colours on a 256-colour terminal. A role nobody defines, or a colour that is no `#rrggbb`,
+ * gives the terminal's default (`39`, `49`).
+ */
+export declare function terminalColor(theme: Theme, role: string, depth: ColorDepth, layer: "fg" | "bg"): string;
+//# sourceMappingURL=themes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"themes.d.ts","sourceRoot":"","sources":["../../src/surfaces/themes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvE,6GAA6G;AAC7G,eAAO,MAAM,UAAU,YAAI,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAElG,mBAAmB;AACnB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,2HAA2H;AAC3H,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvF,mHAAmH;IACnH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,mGAAmG;IACnG,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD,CAAC;AAEF,gHAAgH;AAChH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,EAAE,CAEnD,CAAC;AAEH,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,CAE3D;AAED,gFAAgF;AAChF,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CA6BlE,CAAC;AAEF,6GAA6G;AAC7G,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAExF,wHAAwH;AACxH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,KAAK,CAIjG;AAED,+GAA+G;AAC/G,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAK7E;AAED,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CASvG"}