@gyral/core 0.0.0 → 0.2.0

package/dist/props.d.ts

@@ -0,0 +1,26 @@
+import type { PropertyDeclaration } from 'lit';
+type Bag = Readonly<Record<string, unknown>>;
+/** Gyral's view of a declaration: Lit's options plus `required` and `default`. */
+export interface PropInfo extends PropertyDeclaration {
+    readonly required?: boolean;
+    readonly default?: unknown;
+}
+export type PropTable = Readonly<Record<string, PropInfo>>;
+/** The element's declared props as set on it (no defaults): what a seed must carry. */
+export declare function readRawProps(el: object, table: PropTable): Bag;
+/** The element's declared props as components see them: `default` fills `undefined`. */
+export declare function readProps(el: object, table: PropTable): Bag;
+/** Required props that are still `undefined` (ADR 0007 addendum). */
+export declare function missingRequired(el: object, table: PropTable): string[];
+/** True when every declared prop is identical (`Object.is`) in both snapshots. */
+export declare function sameProps<P>(names: readonly string[], a: P, b: P): boolean;
+/** Hydration: sets props that only travelled in the seed, unless the page already set them. */
+export declare function restoreProps(el: object, names: readonly string[], seeded: Bag): void;
+/**
+ * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).
+ * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the
+ * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:
+ * the server's DOM shim doesn't model the full prototype chain.
+ */
+export declare function shadowedBuiltins(names: readonly string[]): string[];
+export {};

package/dist/props.js

@@ -0,0 +1,44 @@
+/** The element's declared props as set on it (no defaults): what a seed must carry. */
+export function readRawProps(el, table) {
+    const self = el;
+    return Object.fromEntries(Object.keys(table).map((name) => [name, self[name]]));
+}
+/** The element's declared props as components see them: `default` fills `undefined`. */
+export function readProps(el, table) {
+    const self = el;
+    return Object.fromEntries(Object.entries(table).map(([name, info]) => {
+        const value = self[name];
+        return [name, value === undefined && 'default' in info ? info.default : value];
+    }));
+}
+/** Required props that are still `undefined` (ADR 0007 addendum). */
+export function missingRequired(el, table) {
+    const self = el;
+    return Object.entries(table)
+        .filter(([name, info]) => info.required === true && self[name] === undefined)
+        .map(([name]) => name);
+}
+/** True when every declared prop is identical (`Object.is`) in both snapshots. */
+export function sameProps(names, a, b) {
+    return names.every((name) => Object.is(a[name], b[name]));
+}
+/** Hydration: sets props that only travelled in the seed, unless the page already set them. */
+export function restoreProps(el, names, seeded) {
+    const self = el;
+    for (const [name, value] of Object.entries(seeded)) {
+        if (names.includes(name) && self[name] === undefined)
+            self[name] = value;
+    }
+}
+/**
+ * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).
+ * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the
+ * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:
+ * the server's DOM shim doesn't model the full prototype chain.
+ */
+export function shadowedBuiltins(names) {
+    if (typeof HTMLElement === 'undefined')
+        return [];
+    return names.filter((name) => name in HTMLElement.prototype);
+}
+//# sourceMappingURL=props.js.map

package/dist/props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.js","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAaA,uFAAuF;AACvF,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAgB;IACvD,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,KAAgB;IACpD,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,IAAI,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjF,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,EAAU,EAAE,KAAgB;IAC1D,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;SAC5E,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,SAAS,CAAI,KAAwB,EAAE,CAAI,EAAE,CAAI;IAC/D,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAE,CAAS,CAAC,IAAI,CAAC,EAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAwB,EAAE,MAAW;IAC5E,MAAM,IAAI,GAAG,EAA6B,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC3E,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,IAAI,OAAO,WAAW,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;AAC/D,CAAC","sourcesContent":["// Prop bookkeeping for define() (ADR 0007): snapshots, defaults, change detection, seed restore.\nimport type { PropertyDeclaration } from 'lit';\n\ntype Bag = Readonly<Record<string, unknown>>;\n\n/** Gyral's view of a declaration: Lit's options plus `required` and `default`. */\nexport interface PropInfo extends PropertyDeclaration {\n  readonly required?: boolean;\n  readonly default?: unknown;\n}\n\nexport type PropTable = Readonly<Record<string, PropInfo>>;\n\n/** The element's declared props as set on it (no defaults): what a seed must carry. */\nexport function readRawProps(el: object, table: PropTable): Bag {\n  const self = el as Bag;\n  return Object.fromEntries(Object.keys(table).map((name) => [name, self[name]]));\n}\n\n/** The element's declared props as components see them: `default` fills `undefined`. */\nexport function readProps(el: object, table: PropTable): Bag {\n  const self = el as Bag;\n  return Object.fromEntries(\n    Object.entries(table).map(([name, info]) => {\n      const value = self[name];\n      return [name, value === undefined && 'default' in info ? info.default : value];\n    }),\n  );\n}\n\n/** Required props that are still `undefined` (ADR 0007 addendum). */\nexport function missingRequired(el: object, table: PropTable): string[] {\n  const self = el as Bag;\n  return Object.entries(table)\n    .filter(([name, info]) => info.required === true && self[name] === undefined)\n    .map(([name]) => name);\n}\n\n/** True when every declared prop is identical (`Object.is`) in both snapshots. */\nexport function sameProps<P>(names: readonly string[], a: P, b: P): boolean {\n  return names.every((name) => Object.is((a as Bag)[name], (b as Bag)[name]));\n}\n\n/** Hydration: sets props that only travelled in the seed, unless the page already set them. */\nexport function restoreProps(el: object, names: readonly string[], seeded: Bag): void {\n  const self = el as Record<string, unknown>;\n  for (const [name, value] of Object.entries(seeded)) {\n    if (names.includes(name) && self[name] === undefined) self[name] = value;\n  }\n}\n\n/**\n * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).\n * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the\n * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:\n * the server's DOM shim doesn't model the full prototype chain.\n */\nexport function shadowedBuiltins(names: readonly string[]): string[] {\n  if (typeof HTMLElement === 'undefined') return [];\n  return names.filter((name) => name in HTMLElement.prototype);\n}\n"]}

package/dist/random.d.ts

@@ -0,0 +1,13 @@
+import { type Command, type Driver } from './command.js';
+export interface RandomInput {
+    /** How many numbers to draw. */
+    readonly count: number;
+}
+/** Uniform numbers in [0, 1). Substitute it in tests: `el.drivers = { random: fake }`. */
+export declare const randomDriver: Driver<RandomInput, readonly number[]>;
+/** Draws `count` uniform numbers in [0, 1) and turns them into a message. */
+export declare function random<M>(count: number, toMsg: (values: readonly number[]) => M | undefined): Command<M>;
+/** Maps a uniform number in [0, 1) to an integer in `min..max` (inclusive). Pure. */
+export declare const toInt: (u: number, min: number, max: number) => number;
+/** Draws one integer in `min..max` (inclusive). */
+export declare function randomInt<M>(min: number, max: number, toMsg: (value: number) => M | undefined): Command<M>;

package/dist/random.js

@@ -0,0 +1,19 @@
+// Randomness as an effect (gyral-czi.10): reducers ask for random numbers with a command,
+// so models stay pure and tests substitute a deterministic driver by name.
+import { command, defineDriver } from './command.js';
+/** Uniform numbers in [0, 1). Substitute it in tests: `el.drivers = { random: fake }`. */
+export const randomDriver = defineDriver({
+    name: 'random',
+    run: ({ count }) => Array.from({ length: count }, () => Math.random()),
+});
+/** Draws `count` uniform numbers in [0, 1) and turns them into a message. */
+export function random(count, toMsg) {
+    return command(randomDriver, { count }, { onSuccess: toMsg });
+}
+/** Maps a uniform number in [0, 1) to an integer in `min..max` (inclusive). Pure. */
+export const toInt = (u, min, max) => min + Math.min(max - min, Math.floor(u * (max - min + 1)));
+/** Draws one integer in `min..max` (inclusive). */
+export function randomInt(min, max, toMsg) {
+    return random(1, ([u = 0]) => toMsg(toInt(u, min, max)));
+}
+//# sourceMappingURL=random.js.map

package/dist/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,2EAA2E;AAC3E,OAAO,EAAE,OAAO,EAAE,YAAY,EAA6B,MAAM,cAAc,CAAC;AAOhF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,YAAY,GAA2C,YAAY,CAAC;IAC/E,IAAI,EAAE,QAAQ;IACd,GAAG,EAAE,CAAC,EAAE,KAAK,EAAe,EAAqB,EAAE,CACjD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;CACrD,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,UAAU,MAAM,CACpB,KAAa,EACb,KAAmD;IAEnD,OAAO,OAAO,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,GAAW,EAAE,GAAW,EAAU,EAAE,CACnE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7D,mDAAmD;AACnD,MAAM,UAAU,SAAS,CACvB,GAAW,EACX,GAAW,EACX,KAAuC;IAEvC,OAAO,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC","sourcesContent":["// Randomness as an effect (gyral-czi.10): reducers ask for random numbers with a command,\n// so models stay pure and tests substitute a deterministic driver by name.\nimport { command, defineDriver, type Command, type Driver } from './command.js';\n\nexport interface RandomInput {\n  /** How many numbers to draw. */\n  readonly count: number;\n}\n\n/** Uniform numbers in [0, 1). Substitute it in tests: `el.drivers = { random: fake }`. */\nexport const randomDriver: Driver<RandomInput, readonly number[]> = defineDriver({\n  name: 'random',\n  run: ({ count }: RandomInput): readonly number[] =>\n    Array.from({ length: count }, () => Math.random()),\n});\n\n/** Draws `count` uniform numbers in [0, 1) and turns them into a message. */\nexport function random<M>(\n  count: number,\n  toMsg: (values: readonly number[]) => M | undefined,\n): Command<M> {\n  return command(randomDriver, { count }, { onSuccess: toMsg });\n}\n\n/** Maps a uniform number in [0, 1) to an integer in `min..max` (inclusive). Pure. */\nexport const toInt = (u: number, min: number, max: number): number =>\n  min + Math.min(max - min, Math.floor(u * (max - min + 1)));\n\n/** Draws one integer in `min..max` (inclusive). */\nexport function randomInt<M>(\n  min: number,\n  max: number,\n  toMsg: (value: number) => M | undefined,\n): Command<M> {\n  return random(1, ([u = 0]) => toMsg(toInt(u, min, max)));\n}\n"]}

package/dist/states.d.ts

@@ -0,0 +1,7 @@
+/** Writes a component's boolean states to its CustomStateSet. */
+export type StateSync = (states: Readonly<Record<string, boolean>>) => void;
+/**
+ * Attaches ElementInternals to `host` and returns a function that mirrors boolean states onto
+ * `internals.states`, or `undefined` when the platform lacks custom states.
+ */
+export declare function attachStates(host: HTMLElement): StateSync | undefined;

package/dist/states.js

@@ -0,0 +1,23 @@
+// Model state → CSS custom states (`:state(loading)`), via ElementInternals (ADR 0001 addendum).
+// An ADR 0003 enhancement: CustomStateSet is feature-detected; without it nothing is set.
+/**
+ * Attaches ElementInternals to `host` and returns a function that mirrors boolean states onto
+ * `internals.states`, or `undefined` when the platform lacks custom states.
+ */
+export function attachStates(host) {
+    if (typeof host.attachInternals !== 'function')
+        return undefined;
+    const internals = host.attachInternals();
+    if (!('states' in internals))
+        return undefined;
+    const set = internals.states;
+    return (states) => {
+        for (const [name, on] of Object.entries(states)) {
+            if (on)
+                set.add(name);
+            else
+                set.delete(name);
+        }
+    };
+}
+//# sourceMappingURL=states.js.map

package/dist/states.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"states.js","sourceRoot":"","sources":["../src/states.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,0FAA0F;AAU1F;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAiB;IAC5C,IAAI,OAAO,IAAI,CAAC,eAAe,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;IACzC,IAAI,CAAC,CAAC,QAAQ,IAAI,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,MAAsB,CAAC;IAC7C,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAChD,IAAI,EAAE;gBAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;;gBACjB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// Model state → CSS custom states (`:state(loading)`), via ElementInternals (ADR 0001 addendum).\n// An ADR 0003 enhancement: CustomStateSet is feature-detected; without it nothing is set.\n\ninterface StateSetLike {\n  add(name: string): void;\n  delete(name: string): boolean;\n}\n\n/** Writes a component's boolean states to its CustomStateSet. */\nexport type StateSync = (states: Readonly<Record<string, boolean>>) => void;\n\n/**\n * Attaches ElementInternals to `host` and returns a function that mirrors boolean states onto\n * `internals.states`, or `undefined` when the platform lacks custom states.\n */\nexport function attachStates(host: HTMLElement): StateSync | undefined {\n  if (typeof host.attachInternals !== 'function') return undefined;\n  const internals = host.attachInternals();\n  if (!('states' in internals)) return undefined;\n  const set = internals.states as StateSetLike;\n  return (states) => {\n    for (const [name, on] of Object.entries(states)) {\n      if (on) set.add(name);\n      else set.delete(name);\n    }\n  };\n}\n"]}

package/dist/store-binding.d.ts

@@ -0,0 +1,14 @@
+import type { AnyStore, StoreOverrides, StoreRef, StoreSendInput } from './store.js';
+type OnChange = (store: AnyStore, state: unknown, prev: unknown) => void;
+export declare class StoreBinding {
+    #private;
+    constructor(host: Element, tag: string, declared: readonly AnyStore[], overrides: () => StoreOverrides, onChange: OnChange);
+    /** `ctx.read(store)`: the current state of this component's instance of `store`. */
+    read<S>(ref: StoreRef<S>): S;
+    /** Delivers a `send(store, msg)` command to this component's instance of the store. */
+    send(input: StoreSendInput): void;
+    /** Resolves and subscribes every declared store. Returns true if any instance changed. */
+    connect(): boolean;
+    disconnect(): void;
+}
+export {};

package/dist/store-binding.js

@@ -0,0 +1,63 @@
+// A component's connection to the stores it declares (ADR 0013): resolve, read, subscribe, send.
+import { scopeFor } from './store-scope.js';
+export class StoreBinding {
+    #host;
+    #tag;
+    #declared;
+    #overrides;
+    #onChange;
+    /** Resolved instances while connected (the scope can't change until it moves). */
+    #bound = new Map();
+    #unsubscribe = [];
+    constructor(host, tag, declared, overrides, onChange) {
+        this.#host = host;
+        this.#tag = tag;
+        this.#declared = new Map(declared.map((s) => [s.name, s]));
+        this.#overrides = overrides;
+        this.#onChange = onChange;
+    }
+    #instance(store) {
+        return (this.#bound.get(store.name) ??
+            this.#overrides()[store.name] ??
+            scopeFor(this.#host, this.#tag, store).get(store));
+    }
+    #declaredStore(name) {
+        const store = this.#declared.get(name);
+        if (store === undefined) {
+            throw new Error(`<${this.#tag}> uses store "${name}" without declaring it. Add it to the spec: ` +
+                `stores: [${name}] (ADR 0013), so the component subscribes to its changes.`);
+        }
+        return store;
+    }
+    /** `ctx.read(store)`: the current state of this component's instance of `store`. */
+    read(ref) {
+        // Sound: instances are keyed by store name, and the ref carries that store's state type.
+        return this.#instance(this.#declaredStore(ref.name)).state;
+    }
+    /** Delivers a `send(store, msg)` command to this component's instance of the store. */
+    send(input) {
+        const store = this.#declaredStore(input.store.name);
+        this.#instance(store).send(input.msg);
+    }
+    /** Resolves and subscribes every declared store. Returns true if any instance changed. */
+    connect() {
+        this.disconnect();
+        let rebound = false;
+        for (const store of this.#declared.values()) {
+            const instance = this.#instance(store);
+            this.#bound.set(store.name, instance);
+            this.#unsubscribe.push(instance.subscribe((state, prev) => {
+                this.#onChange(store, state, prev);
+            }));
+            rebound = true;
+        }
+        return rebound;
+    }
+    disconnect() {
+        for (const unsubscribe of this.#unsubscribe)
+            unsubscribe();
+        this.#unsubscribe = [];
+        this.#bound.clear();
+    }
+}
+//# sourceMappingURL=store-binding.js.map

package/dist/store-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-binding.js","sourceRoot":"","sources":["../src/store-binding.ts"],"names":[],"mappings":"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","sourcesContent":["// A component's connection to the stores it declares (ADR 0013): resolve, read, subscribe, send.\nimport { scopeFor } from './store-scope.js';\nimport type {\n  AnyStore,\n  AnyStoreInstance,\n  StoreOverrides,\n  StoreRef,\n  StoreSendInput,\n} from './store.js';\n\ntype OnChange = (store: AnyStore, state: unknown, prev: unknown) => void;\n\nexport class StoreBinding {\n  readonly #host: Element;\n  readonly #tag: string;\n  readonly #declared: ReadonlyMap<string, AnyStore>;\n  readonly #overrides: () => StoreOverrides;\n  readonly #onChange: OnChange;\n  /** Resolved instances while connected (the scope can't change until it moves). */\n  readonly #bound = new Map<string, AnyStoreInstance>();\n  #unsubscribe: (() => void)[] = [];\n\n  constructor(\n    host: Element,\n    tag: string,\n    declared: readonly AnyStore[],\n    overrides: () => StoreOverrides,\n    onChange: OnChange,\n  ) {\n    this.#host = host;\n    this.#tag = tag;\n    this.#declared = new Map(declared.map((s) => [s.name, s]));\n    this.#overrides = overrides;\n    this.#onChange = onChange;\n  }\n\n  #instance(store: AnyStore): AnyStoreInstance {\n    return (\n      this.#bound.get(store.name) ??\n      this.#overrides()[store.name] ??\n      scopeFor(this.#host, this.#tag, store).get(store)\n    );\n  }\n\n  #declaredStore(name: string): AnyStore {\n    const store = this.#declared.get(name);\n    if (store === undefined) {\n      throw new Error(\n        `<${this.#tag}> uses store \"${name}\" without declaring it. Add it to the spec: ` +\n          `stores: [${name}] (ADR 0013), so the component subscribes to its changes.`,\n      );\n    }\n    return store;\n  }\n\n  /** `ctx.read(store)`: the current state of this component's instance of `store`. */\n  read<S>(ref: StoreRef<S>): S {\n    // Sound: instances are keyed by store name, and the ref carries that store's state type.\n    return this.#instance(this.#declaredStore(ref.name)).state as S;\n  }\n\n  /** Delivers a `send(store, msg)` command to this component's instance of the store. */\n  send(input: StoreSendInput): void {\n    const store = this.#declaredStore(input.store.name);\n    (this.#instance(store) as { send(msg: unknown): void }).send(input.msg);\n  }\n\n  /** Resolves and subscribes every declared store. Returns true if any instance changed. */\n  connect(): boolean {\n    this.disconnect();\n    let rebound = false;\n    for (const store of this.#declared.values()) {\n      const instance = this.#instance(store);\n      this.#bound.set(store.name, instance);\n      this.#unsubscribe.push(\n        instance.subscribe((state, prev) => {\n          this.#onChange(store, state, prev);\n        }),\n      );\n      rebound = true;\n    }\n    return rebound;\n  }\n\n  disconnect(): void {\n    for (const unsubscribe of this.#unsubscribe) unsubscribe();\n    this.#unsubscribe = [];\n    this.#bound.clear();\n  }\n}\n"]}

package/dist/store-scope.d.ts

@@ -0,0 +1,40 @@
+import type { AnyStore, AnyStoreInstance } from './store.js';
+/** Page-level seed written by @gyral/ssr: `<script type="application/json" data-gyral-stores>`. */
+export declare const STORE_SEED_ATTRIBUTE = "data-gyral-stores";
+/** Provider element name. Set `.instances=${[cart.instance()]}`, or let it create its own. */
+export declare const STORES_ELEMENT = "gyral-stores";
+/** A set of store instances by store name, created on demand from optional seeds. */
+export declare class StoreRegistry {
+    #private;
+    constructor(instances?: readonly AnyStoreInstance[], seeds?: Readonly<Record<string, unknown>>);
+    /** The instance for `store`, creating it (from its seed, if any) on first use. */
+    get(store: AnyStore): AnyStoreInstance;
+    /** Every instance's state by store name (what the SSR seed carries). */
+    snapshot(): Readonly<Record<string, unknown>>;
+    /** Disposes every instance (stops their commands). */
+    dispose(): void;
+}
+/**
+ * Runs `fn` with `registry` as the server's store scope. Server renders are synchronous per
+ * render step, so @gyral/ssr wraps every step: interleaved requests never see each other's
+ * stores, without AsyncLocalStorage (works on any runtime).
+ */
+export declare function withStoreScope<T>(registry: StoreRegistry, fn: () => T): T;
+/** JSON for an inline `<script type="application/json">`: `</script>` and friends escaped. */
+export declare function scriptSafeJson(value: unknown): string;
+/**
+ * A `<gyral-stores>` provider's scope, created on first use. On the client a server-rendered
+ * provider carries its instances' states in `data-gyral-stores` (gyral-czi.20): seeded stores
+ * are restored from it (so hydration matches the server), and `.instances` supplies the rest.
+ */
+export declare function providerScope(el: Element): StoreRegistry;
+/** Event a component dispatches on the server to find its nearest `<gyral-stores>` provider. */
+export declare const STORES_REQUEST = "gyral-stores-request";
+/** The detail of a STORES_REQUEST event; the provider fills in `registry`. */
+export interface StoresRequest {
+    registry?: StoreRegistry;
+}
+/** The scope for a component: its nearest provider (across shadow roots) or the default. */
+export declare function scopeFor(host: Element, tag: string, store: AnyStore): StoreRegistry;
+/** Tests only: forget the document default so each test starts clean. */
+export declare function resetDocumentStores(): void;

package/dist/store-scope.js

@@ -0,0 +1,146 @@
+// Which store instance a component uses (docs/design-docs/0013-shared-state.md):
+// el.stores override → nearest <gyral-stores> ancestor → the document default (client), or the
+// request scope set by @gyral/ssr around each render step (server).
+import { isServer } from 'lit';
+const onServer = isServer;
+/** Page-level seed written by @gyral/ssr: `<script type="application/json" data-gyral-stores>`. */
+export const STORE_SEED_ATTRIBUTE = 'data-gyral-stores';
+/** Provider element name. Set `.instances=${[cart.instance()]}`, or let it create its own. */
+export const STORES_ELEMENT = 'gyral-stores';
+/** A set of store instances by store name, created on demand from optional seeds. */
+export class StoreRegistry {
+    #instances = new Map();
+    #seeds;
+    constructor(instances = [], seeds = {}) {
+        for (const instance of instances)
+            this.#hold(instance);
+        this.#seeds = seeds;
+    }
+    /** The instance for `store`, creating it (from its seed, if any) on first use. */
+    get(store) {
+        return this.#instances.get(store.name) ?? this.#hold(this.#create(store));
+    }
+    /** Keeps an instance and lets its `send(other, msg)` commands reach this scope. */
+    #hold(instance) {
+        this.#instances.set(instance.store.name, instance);
+        instance.bindScope?.((store) => this.get(store));
+        return instance;
+    }
+    /** A new instance from its seed (checked by the store's schema), or from `init`. */
+    #create(store) {
+        if (!(store.name in this.#seeds))
+            return store.instance();
+        const check = store.checkSeed(this.#seeds[store.name]);
+        if (check.ok)
+            return store.instance(check.state);
+        console.error(`store "${store.name}": the server's seed failed its schema, so it starts from init. ` +
+            `Issues: ${check.issues.join('; ')}`);
+        return store.instance();
+    }
+    /** Every instance's state by store name (what the SSR seed carries). */
+    snapshot() {
+        return Object.fromEntries([...this.#instances].map(([name, i]) => [name, i.state]));
+    }
+    /** Disposes every instance (stops their commands). */
+    dispose() {
+        for (const instance of this.#instances.values())
+            instance.dispose();
+        this.#instances.clear();
+    }
+}
+let serverScope;
+/**
+ * Runs `fn` with `registry` as the server's store scope. Server renders are synchronous per
+ * render step, so @gyral/ssr wraps every step: interleaved requests never see each other's
+ * stores, without AsyncLocalStorage (works on any runtime).
+ */
+export function withStoreScope(registry, fn) {
+    const previous = serverScope;
+    serverScope = registry;
+    try {
+        return fn();
+    }
+    finally {
+        serverScope = previous;
+    }
+}
+/** JSON for an inline `<script type="application/json">`: `</script>` and friends escaped. */
+export function scriptSafeJson(value) {
+    return JSON.stringify(value)
+        .replaceAll('<', '\\u003c')
+        .replaceAll('>', '\\u003e')
+        .replaceAll('&', '\\u0026')
+        .replaceAll('
', '\\u2028')
+        .replaceAll('
', '\\u2029');
+}
+let documentRegistry;
+function parseSeeds(raw, where) {
+    if (raw == null)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' ? parsed : {};
+    }
+    catch (error) {
+        console.error(`unreadable ${STORE_SEED_ATTRIBUTE} seed on ${where}`, error);
+        return {};
+    }
+}
+/** The client's default scope, restored from the server's page seed on first use. */
+function documentScope() {
+    const script = document.querySelector(`script[${STORE_SEED_ATTRIBUTE}]`);
+    documentRegistry ??= new StoreRegistry([], parseSeeds(script?.textContent, 'the page'));
+    return documentRegistry;
+}
+const providers = new WeakMap();
+/**
+ * A `<gyral-stores>` provider's scope, created on first use. On the client a server-rendered
+ * provider carries its instances' states in `data-gyral-stores` (gyral-czi.20): seeded stores
+ * are restored from it (so hydration matches the server), and `.instances` supplies the rest.
+ */
+export function providerScope(el) {
+    let registry = providers.get(el);
+    if (registry === undefined) {
+        const { instances = [] } = el;
+        const seeds = onServer
+            ? {}
+            : parseSeeds(el.getAttribute(STORE_SEED_ATTRIBUTE), `<${el.localName}>`);
+        const unseeded = instances.filter((i) => !(i.store.name in seeds));
+        registry = new StoreRegistry(unseeded, seeds);
+        providers.set(el, registry);
+    }
+    return registry;
+}
+/** Event a component dispatches on the server to find its nearest `<gyral-stores>` provider. */
+export const STORES_REQUEST = 'gyral-stores-request';
+// The server has no DOM ancestry, but Lit's SSR DOM shim bubbles events through the custom
+// elements being rendered (the mechanism @lit/context uses), so a registered provider can answer.
+function serverProvider(host) {
+    const detail = {};
+    host.dispatchEvent(new CustomEvent(STORES_REQUEST, { bubbles: true, composed: true, detail }));
+    return detail.registry;
+}
+/** The scope for a component: its nearest provider (across shadow roots) or the default. */
+export function scopeFor(host, tag, store) {
+    if (onServer) {
+        const provided = serverProvider(host);
+        if (provided !== undefined)
+            return provided;
+        if (serverScope !== undefined)
+            return serverScope;
+        throw new Error(`<${tag}> reads store "${store.name}" during a server render without a store scope. ` +
+            "Pass the request's store instances to page({ stores }) or renderToString(value, { stores }).");
+    }
+    for (let node = host.parentNode; node !== null;) {
+        if (node instanceof Element && node.localName === STORES_ELEMENT)
+            return providerScope(node);
+        node = node instanceof ShadowRoot ? node.host : node.parentNode;
+    }
+    return documentScope();
+}
+/** Tests only: forget the document default so each test starts clean. */
+export function resetDocumentStores() {
+    documentRegistry?.dispose();
+    documentRegistry = undefined;
+}
+//# sourceMappingURL=store-scope.js.map

package/dist/store-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-scope.js","sourceRoot":"","sources":["../src/store-scope.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,+FAA+F;AAC/F,oEAAoE;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAG/B,MAAM,QAAQ,GAAY,QAAQ,CAAC;AAEnC,mGAAmG;AACnG,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAExD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC;AAE7C,qFAAqF;AACrF,MAAM,OAAO,aAAa;IACf,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAC;IACjD,MAAM,CAAoC;IAEnD,YACE,YAAyC,EAAE,EAC3C,QAA2C,EAAE;QAE7C,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kFAAkF;IAClF,GAAG,CAAC,KAAe;QACjB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,QAA0B;QAC9B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACnD,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,oFAAoF;IACpF,OAAO,CAAC,KAAe;QACrB,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,IAAI,KAAK,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAc,CAAC,CAAC;QAC1D,OAAO,CAAC,KAAK,CACX,UAAU,KAAK,CAAC,IAAI,kEAAkE;YACpF,WAAW,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvC,CAAC;QACF,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAED,wEAAwE;IACxE,QAAQ;QACN,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACtF,CAAC;IAED,sDAAsD;IACtD,OAAO;QACL,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACpE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,IAAI,WAAsC,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,QAAuB,EAAE,EAAW;IACpE,MAAM,QAAQ,GAAG,WAAW,CAAC;IAC7B,WAAW,GAAG,QAAQ,CAAC;IACvB,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,WAAW,GAAG,QAAQ,CAAC;IACzB,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;SAC1B,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;SAC1B,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;SAC1B,UAAU,CAAC;CACf,EAAE,SAAS,CAAC;SACR,UAAU,CAAC;CACf,EAAE,SAAS,CAAC,CAAC;AACd,CAAC;AAED,IAAI,gBAA2C,CAAC;AAEhD,SAAS,UAAU,CACjB,GAA8B,EAC9B,KAAa;IAEb,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QAC1C,OAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,cAAc,oBAAoB,YAAY,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;QAC5E,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,SAAS,aAAa;IACpB,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,oBAAoB,GAAG,CAAC,CAAC;IACzE,gBAAgB,KAAK,IAAI,aAAa,CAAC,EAAE,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IACxF,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,OAAO,EAA0B,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,EAAE,SAAS,GAAG,EAAE,EAAE,GAAG,EAAiD,CAAC;QAC7E,MAAM,KAAK,GAAG,QAAQ;YACpB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,YAAY,CAAC,oBAAoB,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;QACnE,QAAQ,GAAG,IAAI,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC9C,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,gGAAgG;AAChG,MAAM,CAAC,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAOrD,2FAA2F;AAC3F,kGAAkG;AAClG,SAAS,cAAc,CAAC,IAAa;IACnC,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,cAAc,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC/F,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,IAAa,EAAE,GAAW,EAAE,KAAe;IAClE,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAC5C,IAAI,WAAW,KAAK,SAAS;YAAE,OAAO,WAAW,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,IAAI,GAAG,kBAAkB,KAAK,CAAC,IAAI,kDAAkD;YACnF,8FAA8F,CACjG,CAAC;IACJ,CAAC;IACD,KAAK,IAAI,IAAI,GAAgB,IAAI,CAAC,UAAU,EAAE,IAAI,KAAK,IAAI,GAAG,CAAC;QAC7D,IAAI,IAAI,YAAY,OAAO,IAAI,IAAI,CAAC,SAAS,KAAK,cAAc;YAAE,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;QAC7F,IAAI,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IAClE,CAAC;IACD,OAAO,aAAa,EAAE,CAAC;AACzB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB;IACjC,gBAAgB,EAAE,OAAO,EAAE,CAAC;IAC5B,gBAAgB,GAAG,SAAS,CAAC;AAC/B,CAAC","sourcesContent":["// Which store instance a component uses (docs/design-docs/0013-shared-state.md):\n// el.stores override → nearest <gyral-stores> ancestor → the document default (client), or the\n// request scope set by @gyral/ssr around each render step (server).\nimport { isServer } from 'lit';\nimport type { AnyStore, AnyStoreInstance } from './store.js';\n\nconst onServer: boolean = isServer;\n\n/** Page-level seed written by @gyral/ssr: `<script type=\"application/json\" data-gyral-stores>`. */\nexport const STORE_SEED_ATTRIBUTE = 'data-gyral-stores';\n\n/** Provider element name. Set `.instances=${[cart.instance()]}`, or let it create its own. */\nexport const STORES_ELEMENT = 'gyral-stores';\n\n/** A set of store instances by store name, created on demand from optional seeds. */\nexport class StoreRegistry {\n  readonly #instances = new Map<string, AnyStoreInstance>();\n  readonly #seeds: Readonly<Record<string, unknown>>;\n\n  constructor(\n    instances: readonly AnyStoreInstance[] = [],\n    seeds: Readonly<Record<string, unknown>> = {},\n  ) {\n    for (const instance of instances) this.#hold(instance);\n    this.#seeds = seeds;\n  }\n\n  /** The instance for `store`, creating it (from its seed, if any) on first use. */\n  get(store: AnyStore): AnyStoreInstance {\n    return this.#instances.get(store.name) ?? this.#hold(this.#create(store));\n  }\n\n  /** Keeps an instance and lets its `send(other, msg)` commands reach this scope. */\n  #hold(instance: AnyStoreInstance): AnyStoreInstance {\n    this.#instances.set(instance.store.name, instance);\n    instance.bindScope?.((store) => this.get(store));\n    return instance;\n  }\n\n  /** A new instance from its seed (checked by the store's schema), or from `init`. */\n  #create(store: AnyStore): AnyStoreInstance {\n    if (!(store.name in this.#seeds)) return store.instance();\n    const check = store.checkSeed(this.#seeds[store.name]);\n    if (check.ok) return store.instance(check.state as never);\n    console.error(\n      `store \"${store.name}\": the server's seed failed its schema, so it starts from init. ` +\n        `Issues: ${check.issues.join('; ')}`,\n    );\n    return store.instance();\n  }\n\n  /** Every instance's state by store name (what the SSR seed carries). */\n  snapshot(): Readonly<Record<string, unknown>> {\n    return Object.fromEntries([...this.#instances].map(([name, i]) => [name, i.state]));\n  }\n\n  /** Disposes every instance (stops their commands). */\n  dispose(): void {\n    for (const instance of this.#instances.values()) instance.dispose();\n    this.#instances.clear();\n  }\n}\n\nlet serverScope: StoreRegistry | undefined;\n\n/**\n * Runs `fn` with `registry` as the server's store scope. Server renders are synchronous per\n * render step, so @gyral/ssr wraps every step: interleaved requests never see each other's\n * stores, without AsyncLocalStorage (works on any runtime).\n */\nexport function withStoreScope<T>(registry: StoreRegistry, fn: () => T): T {\n  const previous = serverScope;\n  serverScope = registry;\n  try {\n    return fn();\n  } finally {\n    serverScope = previous;\n  }\n}\n\n/** JSON for an inline `<script type=\"application/json\">`: `</script>` and friends escaped. */\nexport function scriptSafeJson(value: unknown): string {\n  return JSON.stringify(value)\n    .replaceAll('<', '\\\\u003c')\n    .replaceAll('>', '\\\\u003e')\n    .replaceAll('&', '\\\\u0026')\n    .replaceAll('
', '\\\\u2028')\n    .replaceAll('
', '\\\\u2029');\n}\n\nlet documentRegistry: StoreRegistry | undefined;\n\nfunction parseSeeds(\n  raw: string | null | undefined,\n  where: string,\n): Readonly<Record<string, unknown>> {\n  if (raw == null) return {};\n  try {\n    const parsed = JSON.parse(raw) as unknown;\n    return parsed !== null && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {};\n  } catch (error) {\n    console.error(`unreadable ${STORE_SEED_ATTRIBUTE} seed on ${where}`, error);\n    return {};\n  }\n}\n\n/** The client's default scope, restored from the server's page seed on first use. */\nfunction documentScope(): StoreRegistry {\n  const script = document.querySelector(`script[${STORE_SEED_ATTRIBUTE}]`);\n  documentRegistry ??= new StoreRegistry([], parseSeeds(script?.textContent, 'the page'));\n  return documentRegistry;\n}\n\nconst providers = new WeakMap<Element, StoreRegistry>();\n\n/**\n * A `<gyral-stores>` provider's scope, created on first use. On the client a server-rendered\n * provider carries its instances' states in `data-gyral-stores` (gyral-czi.20): seeded stores\n * are restored from it (so hydration matches the server), and `.instances` supplies the rest.\n */\nexport function providerScope(el: Element): StoreRegistry {\n  let registry = providers.get(el);\n  if (registry === undefined) {\n    const { instances = [] } = el as { instances?: readonly AnyStoreInstance[] };\n    const seeds = onServer\n      ? {}\n      : parseSeeds(el.getAttribute(STORE_SEED_ATTRIBUTE), `<${el.localName}>`);\n    const unseeded = instances.filter((i) => !(i.store.name in seeds));\n    registry = new StoreRegistry(unseeded, seeds);\n    providers.set(el, registry);\n  }\n  return registry;\n}\n\n/** Event a component dispatches on the server to find its nearest `<gyral-stores>` provider. */\nexport const STORES_REQUEST = 'gyral-stores-request';\n\n/** The detail of a STORES_REQUEST event; the provider fills in `registry`. */\nexport interface StoresRequest {\n  registry?: StoreRegistry;\n}\n\n// The server has no DOM ancestry, but Lit's SSR DOM shim bubbles events through the custom\n// elements being rendered (the mechanism @lit/context uses), so a registered provider can answer.\nfunction serverProvider(host: Element): StoreRegistry | undefined {\n  const detail: StoresRequest = {};\n  host.dispatchEvent(new CustomEvent(STORES_REQUEST, { bubbles: true, composed: true, detail }));\n  return detail.registry;\n}\n\n/** The scope for a component: its nearest provider (across shadow roots) or the default. */\nexport function scopeFor(host: Element, tag: string, store: AnyStore): StoreRegistry {\n  if (onServer) {\n    const provided = serverProvider(host);\n    if (provided !== undefined) return provided;\n    if (serverScope !== undefined) return serverScope;\n    throw new Error(\n      `<${tag}> reads store \"${store.name}\" during a server render without a store scope. ` +\n        \"Pass the request's store instances to page({ stores }) or renderToString(value, { stores }).\",\n    );\n  }\n  for (let node: Node | null = host.parentNode; node !== null;) {\n    if (node instanceof Element && node.localName === STORES_ELEMENT) return providerScope(node);\n    node = node instanceof ShadowRoot ? node.host : node.parentNode;\n  }\n  return documentScope();\n}\n\n/** Tests only: forget the document default so each test starts clean. */\nexport function resetDocumentStores(): void {\n  documentRegistry?.dispose();\n  documentRegistry = undefined;\n}\n"]}

package/dist/store.d.ts

@@ -0,0 +1,114 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type Command, type DriverOverrides, type Next } from './command.js';
+import type { Tagged } from './types.js';
+type Variant<M extends Tagged, K extends M['_tag']> = Extract<M, {
+    readonly _tag: K;
+}>;
+/** One pure reducer per message tag, like a component's `update` but without context. */
+export type StoreUpdate<S, M extends Tagged> = {
+    readonly [K in M['_tag']]: (state: S, msg: Variant<M, K>) => Next<S, M>;
+};
+export interface StoreSpec<S, M extends Tagged> {
+    /** Initial state (and optional commands, e.g. load a saved cart). */
+    readonly init: () => Next<S, M>;
+    readonly update: StoreUpdate<S, M>;
+    /** Driver substitutions by name for this store's commands. */
+    readonly drivers?: DriverOverrides;
+    /**
+     * Validates the server's page seed before the client uses it (any synchronous Standard
+     * Schema). An invalid seed is reported with console.error and the store starts from `init`.
+     */
+    readonly schema?: StandardSchemaV1<unknown, S>;
+}
+/** The result of checking a seed against a store's schema. */
+export type SeedCheck<S> = {
+    readonly ok: true;
+    readonly state: S;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+/** What `ctx.read()` accepts: anything that names a store and carries its state type. */
+export interface StoreRef<S> {
+    readonly name: string;
+    /** Type-only marker for the state type. Never set at runtime. */
+    readonly stateType?: (state: S) => S;
+}
+/** A live store: one per page on the client, one per request on the server, one per test. */
+export interface StoreInstance<S, M extends Tagged> {
+    readonly store: Store<S, M>;
+    readonly state: S;
+    /** Feeds a message through the store's `update` and notifies subscribers on change. */
+    send(msg: M): void;
+    /** Called after every state change. Returns an unsubscribe function. */
+    subscribe(listener: (state: S, prev: S) => void): () => void;
+    /** Per-instance driver substitutions (test fakes). Checked before the spec's. */
+    drivers: DriverOverrides;
+    /** Stops running commands and drops subscribers. */
+    dispose(): void;
+    /** Set by the registry that holds the instance (store-to-store `send`). */
+    bindScope(resolve: StoreResolver): void;
+}
+export interface Store<S, M extends Tagged> extends StoreRef<S> {
+    readonly spec: StoreSpec<S, M>;
+    /**
+     * A fresh, independent instance. `initial` skips `init`'s state (a server seed, a test
+     * fixture); `init`'s commands still run on the client.
+     */
+    instance(initial?: S): StoreInstance<S, M>;
+    /** Checks a seed with `spec.schema` (ok as-is without one). */
+    checkSeed(seed: unknown): SeedCheck<S>;
+    /** Type-only marker for the message type. Never set at runtime. */
+    readonly messageType?: (msg: M) => M;
+}
+/** Any store, with its types erased (for declarations and registries). */
+export interface AnyStore {
+    readonly name: string;
+    instance(initial?: never): AnyStoreInstance;
+    checkSeed(seed: unknown): SeedCheck<unknown>;
+}
+/** Any store instance, with its types erased. */
+export interface AnyStoreInstance {
+    readonly store: AnyStore;
+    readonly state: unknown;
+    send(msg: never): void;
+    subscribe(listener: (state: unknown, prev: unknown) => void): () => void;
+    dispose(): void;
+    /**
+     * Called by the registry that holds this instance, so the store's `send(other, msg)`
+     * commands reach `other`'s instance in the same scope (gyral-czi.20).
+     */
+    bindScope?(resolve: StoreResolver): void;
+}
+/** Finds a store's instance in a scope (a registry). */
+export type StoreResolver = (store: AnyStore) => AnyStoreInstance;
+/** Store instances substituted by store name (tests, islands). */
+export type StoreOverrides = Readonly<Record<string, AnyStoreInstance>>;
+/** Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. */
+export declare function defineStore<S, M extends Tagged>(name: string, spec: StoreSpec<S, M>): Store<S, M>;
+/** Marker driver for `send()`: `define()` delivers these to the resolved store instance. */
+export declare const STORE_SEND: {
+    readonly name: "@gyral/store-send";
+    readonly run: () => undefined;
+};
+/** The input of a `send()` command. */
+export interface StoreSendInput {
+    readonly store: AnyStore;
+    readonly msg: Tagged;
+}
+/** A command that sends `msg` to the component's instance of `store`. Writes are commands. */
+export declare function send<S, M extends Tagged>(store: Store<S, M>, msg: NoInfer<M>): Command<never>;
+/** Framework message: a store this component reads changed (ADR 0013). Optional reducer. */
+export interface StoreChanged {
+    readonly _tag: 'StoreChanged';
+    /** The store's name. Narrow with `changed(store, msg)`. */
+    readonly store: string;
+    readonly state: unknown;
+    readonly prev: unknown;
+}
+/** Narrows a `StoreChanged` message to one store's typed state, or `undefined`. */
+export declare function changed<S>(store: StoreRef<S>, msg: StoreChanged): {
+    readonly state: S;
+    readonly prev: S;
+} | undefined;
+export {};