@gyral/core 0.0.0 → 0.1.0

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":"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","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 {};

package/dist/store.js

@@ -0,0 +1,129 @@
+import { isServer } from 'lit';
+import { DEVTOOLS_ENABLED, devCommands, devStore } from '#devtools';
+import { splitNext, } from './command.js';
+import { makeInterpreter } from './internal/interpreter.js';
+const onServer = isServer;
+/** Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. */
+export function defineStore(name, spec) {
+    const store = {
+        name,
+        spec,
+        instance: (initial) => createInstance(store, initial),
+        checkSeed: (seed) => checkSeed(spec.schema, seed),
+    };
+    return store;
+}
+const issuePath = (issue) => (issue.path ?? []).map((s) => String(typeof s === 'object' ? s.key : s)).join('.');
+function checkSeed(schema, seed) {
+    // Sound without a schema: the seed is this store's state, serialized by the server.
+    if (schema === undefined)
+        return { ok: true, state: seed };
+    const result = schema['~standard'].validate(seed);
+    if (result instanceof Promise) {
+        return { ok: false, issues: ['the store schema is async; seeds need a synchronous schema'] };
+    }
+    if (result.issues === undefined)
+        return { ok: true, state: result.value };
+    return {
+        ok: false,
+        issues: result.issues.map((i) => `${issuePath(i) || '(root)'}: ${i.message}`),
+    };
+}
+function createInstance(store, initial) {
+    // Sound: send() only calls the reducer whose key equals msg._tag.
+    const reducers = store.spec.update;
+    const listeners = new Set();
+    let interpreter;
+    let disposed = false;
+    const [initState, initCommands] = splitNext(store.spec.init());
+    let state = initial === undefined ? initState : initial;
+    const resolve = (driver) => instance.drivers[driver.name] ?? store.spec.drivers?.[driver.name] ?? driver;
+    let scope;
+    // Store-to-store writes: delivered synchronously to the other store's instance in scope.
+    const deliver = ({ store: target, msg }) => {
+        if (scope === undefined) {
+            console.warn(`store "${store.name}" sends to "${target.name}" but is not held by a store scope ` +
+                '(a registry, <gyral-stores> or the page default), so the message is dropped.');
+            return;
+        }
+        scope(target).send(msg);
+    };
+    const run = (commands) => {
+        if (onServer || disposed || commands.length === 0)
+            return; // never on the server (ADR 0012)
+        for (const cmd of commands) {
+            if (cmd.driver === STORE_SEND) {
+                deliver(cmd.input);
+                continue;
+            }
+            interpreter ??= makeInterpreter(resolve, (msg) => {
+                // Stores have no IntentRejected reducer; only their own messages apply.
+                if (msg._tag !== 'IntentRejected')
+                    instance.send(msg);
+            }, DEVTOOLS_ENABLED ? devCommands(() => `store:${store.name}`) : undefined);
+            interpreter.run(cmd);
+        }
+    };
+    const instance = {
+        store,
+        get state() {
+            return state;
+        },
+        drivers: {},
+        send(msg) {
+            const reducer = reducers[msg._tag];
+            if (reducer === undefined) {
+                console.warn(`store "${store.name}" has no update for message "${msg._tag}".`);
+                return;
+            }
+            const prev = state;
+            const [next, commands] = splitNext(reducer(prev, msg));
+            state = next;
+            if (DEVTOOLS_ENABLED)
+                devStore(store.name, msg, prev, next);
+            if (!Object.is(next, prev))
+                for (const listener of [...listeners])
+                    listener(next, prev);
+            run(commands);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        dispose() {
+            disposed = true;
+            interpreter?.dispose();
+            listeners.clear();
+        },
+        bindScope(resolver) {
+            scope = resolver;
+        },
+    };
+    // A seeded instance (hydration) starts init's commands after the hydrating renders flushed,
+    // so a fast driver can't change state under them (same reason as ADR 0012 for components).
+    if (initial === undefined)
+        run(initCommands);
+    else if (initCommands.length > 0)
+        setTimeout(() => {
+            run(initCommands);
+        }, 0);
+    return instance;
+}
+/** Marker driver for `send()`: `define()` delivers these to the resolved store instance. */
+export const STORE_SEND = {
+    name: '@gyral/store-send',
+    run: () => undefined,
+};
+/** A command that sends `msg` to the component's instance of `store`. Writes are commands. */
+// NoInfer: the store decides the message type, so a literal (`{ _tag: 'Track', … }`) is checked
+// against it instead of widening `_tag` to string (store-to-store sends have no other context).
+export function send(store, msg) {
+    const input = { store, msg };
+    return { driver: STORE_SEND, input, onSuccess: () => undefined };
+}
+/** Narrows a `StoreChanged` message to one store's typed state, or `undefined`. */
+export function changed(store, msg) {
+    // Sound: the message was built from this store's instance (matched by unique name).
+    return msg.store === store.name ? { state: msg.state, prev: msg.prev } : undefined;
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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","sourcesContent":["// Shared state: stores as \"props from the side\" (docs/design-docs/0013-shared-state.md).\n// A store is MVI without a view: init + pure update, commands run by its own interpreter.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { isServer } from 'lit';\nimport { DEVTOOLS_ENABLED, devCommands, devStore } from '#devtools';\nimport {\n  splitNext,\n  type AnyDriver,\n  type Command,\n  type DriverOverrides,\n  type Next,\n} from './command.js';\nimport { makeInterpreter, type Interpreter } from './internal/interpreter.js';\nimport type { IntentRejected, Tagged } from './types.js';\n\nconst onServer: boolean = isServer;\n\ntype Variant<M extends Tagged, K extends M['_tag']> = Extract<M, { readonly _tag: K }>;\n\n/** One pure reducer per message tag, like a component's `update` but without context. */\nexport type StoreUpdate<S, M extends Tagged> = {\n  readonly [K in M['_tag']]: (state: S, msg: Variant<M, K>) => Next<S, M>;\n};\n\nexport interface StoreSpec<S, M extends Tagged> {\n  /** Initial state (and optional commands, e.g. load a saved cart). */\n  readonly init: () => Next<S, M>;\n  readonly update: StoreUpdate<S, M>;\n  /** Driver substitutions by name for this store's commands. */\n  readonly drivers?: DriverOverrides;\n  /**\n   * Validates the server's page seed before the client uses it (any synchronous Standard\n   * Schema). An invalid seed is reported with console.error and the store starts from `init`.\n   */\n  readonly schema?: StandardSchemaV1<unknown, S>;\n}\n\n/** The result of checking a seed against a store's schema. */\nexport type SeedCheck<S> =\n  | { readonly ok: true; readonly state: S }\n  | { readonly ok: false; readonly issues: readonly string[] };\n\n/** What `ctx.read()` accepts: anything that names a store and carries its state type. */\nexport interface StoreRef<S> {\n  readonly name: string;\n  /** Type-only marker for the state type. Never set at runtime. */\n  readonly stateType?: (state: S) => S;\n}\n\n/** A live store: one per page on the client, one per request on the server, one per test. */\nexport interface StoreInstance<S, M extends Tagged> {\n  readonly store: Store<S, M>;\n  readonly state: S;\n  /** Feeds a message through the store's `update` and notifies subscribers on change. */\n  send(msg: M): void;\n  /** Called after every state change. Returns an unsubscribe function. */\n  subscribe(listener: (state: S, prev: S) => void): () => void;\n  /** Per-instance driver substitutions (test fakes). Checked before the spec's. */\n  drivers: DriverOverrides;\n  /** Stops running commands and drops subscribers. */\n  dispose(): void;\n  /** Set by the registry that holds the instance (store-to-store `send`). */\n  bindScope(resolve: StoreResolver): void;\n}\n\nexport interface Store<S, M extends Tagged> extends StoreRef<S> {\n  readonly spec: StoreSpec<S, M>;\n  /**\n   * A fresh, independent instance. `initial` skips `init`'s state (a server seed, a test\n   * fixture); `init`'s commands still run on the client.\n   */\n  instance(initial?: S): StoreInstance<S, M>;\n  /** Checks a seed with `spec.schema` (ok as-is without one). */\n  checkSeed(seed: unknown): SeedCheck<S>;\n  /** Type-only marker for the message type. Never set at runtime. */\n  readonly messageType?: (msg: M) => M;\n}\n\n/** Any store, with its types erased (for declarations and registries). */\nexport interface AnyStore {\n  readonly name: string;\n  instance(initial?: never): AnyStoreInstance;\n  checkSeed(seed: unknown): SeedCheck<unknown>;\n}\n\n/** Any store instance, with its types erased. */\nexport interface AnyStoreInstance {\n  readonly store: AnyStore;\n  readonly state: unknown;\n  send(msg: never): void;\n  subscribe(listener: (state: unknown, prev: unknown) => void): () => void;\n  dispose(): void;\n  /**\n   * Called by the registry that holds this instance, so the store's `send(other, msg)`\n   * commands reach `other`'s instance in the same scope (gyral-czi.20).\n   */\n  bindScope?(resolve: StoreResolver): void;\n}\n\n/** Finds a store's instance in a scope (a registry). */\nexport type StoreResolver = (store: AnyStore) => AnyStoreInstance;\n\n/** Store instances substituted by store name (tests, islands). */\nexport type StoreOverrides = Readonly<Record<string, AnyStoreInstance>>;\n\n/** Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. */\nexport function defineStore<S, M extends Tagged>(name: string, spec: StoreSpec<S, M>): Store<S, M> {\n  const store: Store<S, M> = {\n    name,\n    spec,\n    instance: (initial?: S) => createInstance(store, initial),\n    checkSeed: (seed) => checkSeed(spec.schema, seed),\n  };\n  return store;\n}\n\nconst issuePath = (issue: StandardSchemaV1.Issue): string =>\n  (issue.path ?? []).map((s) => String(typeof s === 'object' ? s.key : s)).join('.');\n\nfunction checkSeed<S>(\n  schema: StandardSchemaV1<unknown, S> | undefined,\n  seed: unknown,\n): SeedCheck<S> {\n  // Sound without a schema: the seed is this store's state, serialized by the server.\n  if (schema === undefined) return { ok: true, state: seed as S };\n  const result = schema['~standard'].validate(seed);\n  if (result instanceof Promise) {\n    return { ok: false, issues: ['the store schema is async; seeds need a synchronous schema'] };\n  }\n  if (result.issues === undefined) return { ok: true, state: result.value };\n  return {\n    ok: false,\n    issues: result.issues.map((i) => `${issuePath(i) || '(root)'}: ${i.message}`),\n  };\n}\n\nfunction createInstance<S, M extends Tagged>(\n  store: Store<S, M>,\n  initial: S | undefined,\n): StoreInstance<S, M> {\n  // Sound: send() only calls the reducer whose key equals msg._tag.\n  const reducers = store.spec.update as unknown as Readonly<\n    Record<string, ((state: S, msg: M) => Next<S, M>) | undefined>\n  >;\n  const listeners = new Set<(state: S, prev: S) => void>();\n  let interpreter: Interpreter<M | IntentRejected> | undefined;\n  let disposed = false;\n\n  const [initState, initCommands] = splitNext(store.spec.init());\n  let state = initial === undefined ? initState : initial;\n\n  const resolve = (driver: AnyDriver): AnyDriver =>\n    instance.drivers[driver.name] ?? store.spec.drivers?.[driver.name] ?? driver;\n\n  let scope: StoreResolver | undefined;\n\n  // Store-to-store writes: delivered synchronously to the other store's instance in scope.\n  const deliver = ({ store: target, msg }: StoreSendInput): void => {\n    if (scope === undefined) {\n      console.warn(\n        `store \"${store.name}\" sends to \"${target.name}\" but is not held by a store scope ` +\n          '(a registry, <gyral-stores> or the page default), so the message is dropped.',\n      );\n      return;\n    }\n    (scope(target) as { send(msg: unknown): void }).send(msg);\n  };\n\n  const run = (commands: ReadonlyArray<Command<M | IntentRejected>>): void => {\n    if (onServer || disposed || commands.length === 0) return; // never on the server (ADR 0012)\n    for (const cmd of commands) {\n      if (cmd.driver === STORE_SEND) {\n        deliver(cmd.input as StoreSendInput);\n        continue;\n      }\n      interpreter ??= makeInterpreter<M | IntentRejected>(\n        resolve,\n        (msg) => {\n          // Stores have no IntentRejected reducer; only their own messages apply.\n          if (msg._tag !== 'IntentRejected') instance.send(msg as M);\n        },\n        DEVTOOLS_ENABLED ? devCommands(() => `store:${store.name}`) : undefined,\n      );\n      interpreter.run(cmd);\n    }\n  };\n\n  const instance: StoreInstance<S, M> = {\n    store,\n    get state() {\n      return state;\n    },\n    drivers: {},\n    send(msg) {\n      const reducer = reducers[msg._tag];\n      if (reducer === undefined) {\n        console.warn(`store \"${store.name}\" has no update for message \"${msg._tag}\".`);\n        return;\n      }\n      const prev = state;\n      const [next, commands] = splitNext(reducer(prev, msg));\n      state = next;\n      if (DEVTOOLS_ENABLED) devStore(store.name, msg, prev, next);\n      if (!Object.is(next, prev)) for (const listener of [...listeners]) listener(next, prev);\n      run(commands);\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    dispose() {\n      disposed = true;\n      interpreter?.dispose();\n      listeners.clear();\n    },\n    bindScope(resolver) {\n      scope = resolver;\n    },\n  };\n\n  // A seeded instance (hydration) starts init's commands after the hydrating renders flushed,\n  // so a fast driver can't change state under them (same reason as ADR 0012 for components).\n  if (initial === undefined) run(initCommands);\n  else if (initCommands.length > 0)\n    setTimeout(() => {\n      run(initCommands);\n    }, 0);\n  return instance;\n}\n\n/** Marker driver for `send()`: `define()` delivers these to the resolved store instance. */\nexport const STORE_SEND = {\n  name: '@gyral/store-send',\n  run: () => undefined,\n} as const;\n\n/** The input of a `send()` command. */\nexport interface StoreSendInput {\n  readonly store: AnyStore;\n  readonly msg: Tagged;\n}\n\n/** A command that sends `msg` to the component's instance of `store`. Writes are commands. */\n// NoInfer: the store decides the message type, so a literal (`{ _tag: 'Track', … }`) is checked\n// against it instead of widening `_tag` to string (store-to-store sends have no other context).\nexport function send<S, M extends Tagged>(store: Store<S, M>, msg: NoInfer<M>): Command<never> {\n  const input: StoreSendInput = { store, msg };\n  return { driver: STORE_SEND, input, onSuccess: () => undefined };\n}\n\n/** Framework message: a store this component reads changed (ADR 0013). Optional reducer. */\nexport interface StoreChanged {\n  readonly _tag: 'StoreChanged';\n  /** The store's name. Narrow with `changed(store, msg)`. */\n  readonly store: string;\n  readonly state: unknown;\n  readonly prev: unknown;\n}\n\n/** Narrows a `StoreChanged` message to one store's typed state, or `undefined`. */\nexport function changed<S>(\n  store: StoreRef<S>,\n  msg: StoreChanged,\n): { readonly state: S; readonly prev: S } | undefined {\n  // Sound: the message was built from this store's instance (matched by unique name).\n  return msg.store === store.name ? { state: msg.state as S, prev: msg.prev as S } : undefined;\n}\n"]}

package/dist/stores-provider.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Registers `<gyral-stores>` for server renders; `@gyral/ssr` calls it. A no-op in the browser,
+ * where a plain `<gyral-stores>` element already scopes stores and the server's shadow root
+ * (a `<slot>`) needs no JavaScript. Idempotent.
+ */
+export declare function defineStoresProvider(): void;