@gyral/core 0.3.0 → 0.3.1

package/dist/states.js

@@ -1,20 +1,34 @@
 // 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.
+// Reached through core's `#spec-features` (spec-features.ts): compiled builds bundle it only
+// when a module names `states` (compiler/features.ts, gyral-c5d.12).
+import { internalsOf } from './element-internals.js';
+/** Each host's state set; `false` when the platform lacks custom states. */
+const sets = new WeakMap();
 /**
- * A function that mirrors boolean states onto `internals.states`, or `false` when the platform
- * lacks custom states.
+ * Mirrors a component's boolean states onto its CustomStateSet. ElementInternals is attached
+ * lazily, once per element, by the first sync (view/05-element.md "ElementInternals").
  */
-export function stateSync(internals) {
-    if (!('states' in internals))
-        return false;
-    const set = internals.states;
-    return (states) => {
+export function syncStates(el, states) {
+    let set = sets.get(el);
+    if (set === undefined) {
+        const internals = internalsOf(el);
+        set = 'states' in internals ? internals.states : false;
+        sets.set(el, set);
+    }
+    if (set === false)
+        return;
+    try {
         for (const [name, on] of Object.entries(states)) {
             if (on)
                 set.add(name);
             else
                 set.delete(name);
         }
-    };
+    }
+    catch {
+        // Chromium 90–124 accept only `--`-prefixed names: no `:state()` support, so skip states.
+        sets.set(el, false);
+    }
 }
 //# sourceMappingURL=states.js.map

package/dist/states.js.map

@@ -1 +1 @@
-{"version":3,"file":"states.js","sourceRoot":"","sources":["../src/states.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,0FAA0F;AAU1F;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,SAA2B;IACnD,IAAI,CAAC,CAAC,QAAQ,IAAI,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,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 * A function that mirrors boolean states onto `internals.states`, or `false` when the platform\n * lacks custom states.\n */\nexport function stateSync(internals: ElementInternals): StateSync | false {\n  if (!('states' in internals)) return false;\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"]}
+{"version":3,"file":"states.js","sourceRoot":"","sources":["../src/states.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,0FAA0F;AAC1F,6FAA6F;AAC7F,qEAAqE;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAOrD,4EAA4E;AAC5E,MAAM,IAAI,GAAG,IAAI,OAAO,EAAqC,CAAC;AAE9D;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EAAe,EAAE,MAAyC;IACnF,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACvB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAClC,GAAG,GAAG,QAAQ,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;QACvD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO;IAC1B,IAAI,CAAC;QACH,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;IAAC,MAAM,CAAC;QACP,0FAA0F;QAC1F,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,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// Reached through core's `#spec-features` (spec-features.ts): compiled builds bundle it only\n// when a module names `states` (compiler/features.ts, gyral-c5d.12).\n\nimport { internalsOf } from './element-internals.js';\n\ninterface StateSetLike {\n  add(name: string): void;\n  delete(name: string): boolean;\n}\n\n/** Each host's state set; `false` when the platform lacks custom states. */\nconst sets = new WeakMap<HTMLElement, StateSetLike | false>();\n\n/**\n * Mirrors a component's boolean states onto its CustomStateSet. ElementInternals is attached\n * lazily, once per element, by the first sync (view/05-element.md \"ElementInternals\").\n */\nexport function syncStates(el: HTMLElement, states: Readonly<Record<string, boolean>>): void {\n  let set = sets.get(el);\n  if (set === undefined) {\n    const internals = internalsOf(el);\n    set = 'states' in internals ? internals.states : false;\n    sets.set(el, set);\n  }\n  if (set === false) return;\n  try {\n    for (const [name, on] of Object.entries(states)) {\n      if (on) set.add(name);\n      else set.delete(name);\n    }\n  } catch {\n    // Chromium 90–124 accept only `--`-prefixed names: no `:state()` support, so skip states.\n    sets.set(el, false);\n  }\n}\n"]}

package/dist/storage.d.ts

@@ -0,0 +1,69 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Driver } from './command.js';
+export type StorageInput<T> = {
+    readonly _tag: 'Read';
+    readonly key: string;
+} | {
+    readonly _tag: 'Write';
+    readonly key: string;
+    readonly value: T;
+} | {
+    readonly _tag: 'Remove';
+    readonly key: string;
+} | {
+    readonly _tag: 'Clear';
+} | {
+    readonly _tag: 'Watch';
+    readonly key: string;
+};
+/** Absence differs from a decoded value, even when the schema accepts null or undefined. */
+export type StoredValue<T> = {
+    readonly found: false;
+} | {
+    readonly found: true;
+    readonly value: T;
+};
+export type StorageChangeSource = 'initial' | 'driver' | 'tab';
+export interface StorageDecodeError {
+    readonly _tag: 'StorageDecodeError';
+    readonly key: string;
+    readonly issues: readonly StandardSchemaV1.Issue[];
+}
+export type StorageError = StorageDecodeError | {
+    readonly _tag: 'StorageAccessError';
+    readonly operation: StorageInput<unknown>['_tag'];
+    readonly key: string | undefined;
+    readonly message: string;
+};
+export type StorageOutput<T> = {
+    readonly _tag: 'StorageValue';
+    readonly key: string;
+    readonly entry: StoredValue<T>;
+} | {
+    readonly _tag: 'StorageWritten' | 'StorageRemoved';
+    readonly key: string;
+} | {
+    readonly _tag: 'StorageCleared';
+} | {
+    readonly _tag: 'StorageChanged';
+    readonly key: string;
+    readonly source: StorageChangeSource;
+    readonly entry: StoredValue<T>;
+} | {
+    readonly _tag: 'StorageDecodeFailed';
+    readonly key: string;
+    readonly source: StorageChangeSource;
+    readonly error: StorageDecodeError;
+};
+export interface LocalStorageOptions<T> {
+    /** Name for normal driver substitution. Default localStorage. */
+    readonly name?: string;
+    /** Keys and Clear are restricted to this namespace. Default empty (all keys). */
+    readonly prefix?: string;
+    /** Accessed only when a command runs. Default native localStorage. */
+    readonly storage?: () => Storage;
+    /** A transformed schema may need to encode model values back into its input shape. */
+    readonly encode?: (value: T) => unknown;
+}
+/** JSON storage with typed reads/writes and cancellable native + own-write change streams. */
+export declare function makeLocalStorageDriver<T>(schema: StandardSchemaV1<unknown, T>, options?: LocalStorageOptions<T>): Driver<StorageInput<T>, StorageOutput<T>, StorageError>;

package/dist/storage.js

@@ -0,0 +1,158 @@
+import { subscription } from './subscription.js';
+const listeners = new WeakMap();
+const notify = (storage, change) => {
+    for (const listen of listeners.get(storage) ?? [])
+        listen(change);
+};
+class StorageFailure extends Error {
+    constructor(error) {
+        super(error._tag);
+        this.error = error;
+    }
+}
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+const keyOf = (input) => 'key' in input ? input.key : undefined;
+/** JSON storage with typed reads/writes and cancellable native + own-write change streams. */
+export function makeLocalStorageDriver(schema, options = {}) {
+    const name = options.name ?? 'localStorage';
+    const prefix = options.prefix ?? '';
+    const storageOf = options.storage ??
+        (() => {
+            if (typeof localStorage === 'undefined')
+                throw new Error('localStorage is unavailable.');
+            return localStorage;
+        });
+    const decode = async (raw, key) => {
+        if (raw === null)
+            return { found: false };
+        try {
+            const value = JSON.parse(raw);
+            const result = await schema['~standard'].validate(value);
+            if (result.issues !== undefined)
+                throw new StorageFailure({ _tag: 'StorageDecodeError', key, issues: result.issues });
+            return { found: true, value: result.value };
+        }
+        catch (cause) {
+            if (cause instanceof StorageFailure)
+                throw cause;
+            throw new StorageFailure({
+                _tag: 'StorageDecodeError',
+                key,
+                issues: [{ message: messageOf(cause) }],
+            });
+        }
+    };
+    const watch = subscription(name, (emit, { input, signal }) => {
+        const storage = storageOf();
+        const key = prefix + input.key;
+        const initial = storage.getItem(key);
+        let chain = Promise.resolve();
+        // Re-read after each awaited decoder: cancellation can happen while it runs.
+        const active = () => !signal.aborted;
+        const publish = (raw, source) => {
+            chain = chain.then(async () => {
+                if (!active())
+                    return;
+                try {
+                    const entry = await decode(raw, input.key);
+                    if (active())
+                        emit({ _tag: 'StorageChanged', key: input.key, source, entry });
+                }
+                catch (cause) {
+                    if (active() &&
+                        cause instanceof StorageFailure &&
+                        cause.error._tag === 'StorageDecodeError') {
+                        emit({ _tag: 'StorageDecodeFailed', key: input.key, source, error: cause.error });
+                    }
+                }
+            });
+        };
+        const own = (change) => {
+            if (change.key === null || change.key === key)
+                publish(change.value, 'driver');
+        };
+        const other = (event) => {
+            if (event.storageArea === storage && (event.key === null || event.key === key))
+                publish(event.newValue, 'tab');
+        };
+        const hub = listeners.get(storage) ?? new Set();
+        listeners.set(storage, hub);
+        hub.add(own);
+        if (typeof window !== 'undefined')
+            window.addEventListener('storage', other);
+        publish(initial, 'initial');
+        return () => {
+            hub.delete(own);
+            if (typeof window !== 'undefined')
+                window.removeEventListener('storage', other);
+        };
+    });
+    return {
+        name,
+        concurrency: 'merge',
+        toError: (cause) => cause instanceof StorageFailure
+            ? cause.error
+            : {
+                _tag: 'StorageAccessError',
+                operation: 'Read',
+                key: undefined,
+                message: messageOf(cause),
+            },
+        run: async (input, ctx) => {
+            ctx.signal.throwIfAborted();
+            try {
+                if (input._tag === 'Watch')
+                    return await watch.run(input, ctx);
+                const storage = storageOf();
+                if (input._tag === 'Clear') {
+                    if (prefix === '') {
+                        storage.clear();
+                        notify(storage, { key: null, value: null });
+                    }
+                    else {
+                        const keys = [];
+                        for (let i = 0; i < storage.length; i += 1) {
+                            const key = storage.key(i);
+                            if (key?.startsWith(prefix))
+                                keys.push(key);
+                        }
+                        for (const key of keys) {
+                            storage.removeItem(key);
+                            notify(storage, { key, value: null });
+                        }
+                    }
+                    return { _tag: 'StorageCleared' };
+                }
+                const key = prefix + input.key;
+                if (input._tag === 'Read') {
+                    const entry = await decode(storage.getItem(key), input.key);
+                    ctx.signal.throwIfAborted();
+                    return { _tag: 'StorageValue', key: input.key, entry };
+                }
+                if (input._tag === 'Write') {
+                    const value = JSON.stringify(options.encode === undefined ? input.value : options.encode(input.value));
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- JSON.stringify(undefined) returns undefined despite its lib type
+                    if (value === undefined)
+                        throw new TypeError('Storage values must have a JSON encoding.');
+                    storage.setItem(key, value);
+                    notify(storage, { key, value });
+                    return { _tag: 'StorageWritten', key: input.key };
+                }
+                storage.removeItem(key);
+                notify(storage, { key, value: null });
+                return { _tag: 'StorageRemoved', key: input.key };
+            }
+            catch (cause) {
+                if (ctx.signal.aborted || cause instanceof StorageFailure)
+                    throw cause;
+                throw new StorageFailure({
+                    _tag: 'StorageAccessError',
+                    operation: input._tag,
+                    key: keyOf(input),
+                    message: messageOf(cause),
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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","sourcesContent":["// Optional native Web Storage commands (ADR 0028). Never touches storage at import/factory time.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Driver } from './command.js';\nimport { subscription } from './subscription.js';\n\nexport type StorageInput<T> =\n  | { readonly _tag: 'Read'; readonly key: string }\n  | { readonly _tag: 'Write'; readonly key: string; readonly value: T }\n  | { readonly _tag: 'Remove'; readonly key: string }\n  | { readonly _tag: 'Clear' }\n  | { readonly _tag: 'Watch'; readonly key: string };\n\n/** Absence differs from a decoded value, even when the schema accepts null or undefined. */\nexport type StoredValue<T> =\n  { readonly found: false } | { readonly found: true; readonly value: T };\nexport type StorageChangeSource = 'initial' | 'driver' | 'tab';\nexport interface StorageDecodeError {\n  readonly _tag: 'StorageDecodeError';\n  readonly key: string;\n  readonly issues: readonly StandardSchemaV1.Issue[];\n}\nexport type StorageError =\n  | StorageDecodeError\n  | {\n      readonly _tag: 'StorageAccessError';\n      readonly operation: StorageInput<unknown>['_tag'];\n      readonly key: string | undefined;\n      readonly message: string;\n    };\nexport type StorageOutput<T> =\n  | { readonly _tag: 'StorageValue'; readonly key: string; readonly entry: StoredValue<T> }\n  | { readonly _tag: 'StorageWritten' | 'StorageRemoved'; readonly key: string }\n  | { readonly _tag: 'StorageCleared' }\n  | {\n      readonly _tag: 'StorageChanged';\n      readonly key: string;\n      readonly source: StorageChangeSource;\n      readonly entry: StoredValue<T>;\n    }\n  | {\n      readonly _tag: 'StorageDecodeFailed';\n      readonly key: string;\n      readonly source: StorageChangeSource;\n      readonly error: StorageDecodeError;\n    };\nexport interface LocalStorageOptions<T> {\n  /** Name for normal driver substitution. Default localStorage. */\n  readonly name?: string;\n  /** Keys and Clear are restricted to this namespace. Default empty (all keys). */\n  readonly prefix?: string;\n  /** Accessed only when a command runs. Default native localStorage. */\n  readonly storage?: () => Storage;\n  /** A transformed schema may need to encode model values back into its input shape. */\n  readonly encode?: (value: T) => unknown;\n}\n\ninterface Change {\n  readonly key: string | null;\n  readonly value: string | null;\n}\nconst listeners = new WeakMap<Storage, Set<(change: Change) => void>>();\nconst notify = (storage: Storage, change: Change): void => {\n  for (const listen of listeners.get(storage) ?? []) listen(change);\n};\nclass StorageFailure extends Error {\n  constructor(readonly error: StorageError) {\n    super(error._tag);\n  }\n}\nconst messageOf = (cause: unknown): string =>\n  cause instanceof Error ? cause.message : String(cause);\nconst keyOf = (input: StorageInput<unknown>): string | undefined =>\n  'key' in input ? input.key : undefined;\n\n/** JSON storage with typed reads/writes and cancellable native + own-write change streams. */\nexport function makeLocalStorageDriver<T>(\n  schema: StandardSchemaV1<unknown, T>,\n  options: LocalStorageOptions<T> = {},\n): Driver<StorageInput<T>, StorageOutput<T>, StorageError> {\n  const name = options.name ?? 'localStorage';\n  const prefix = options.prefix ?? '';\n  const storageOf =\n    options.storage ??\n    (() => {\n      if (typeof localStorage === 'undefined') throw new Error('localStorage is unavailable.');\n      return localStorage;\n    });\n  const decode = async (raw: string | null, key: string): Promise<StoredValue<T>> => {\n    if (raw === null) return { found: false };\n    try {\n      const value: unknown = JSON.parse(raw);\n      const result = await schema['~standard'].validate(value);\n      if (result.issues !== undefined)\n        throw new StorageFailure({ _tag: 'StorageDecodeError', key, issues: result.issues });\n      return { found: true, value: result.value };\n    } catch (cause) {\n      if (cause instanceof StorageFailure) throw cause;\n      throw new StorageFailure({\n        _tag: 'StorageDecodeError',\n        key,\n        issues: [{ message: messageOf(cause) }],\n      });\n    }\n  };\n  const watch = subscription<StorageOutput<T>, { readonly key: string }, StorageError>(\n    name,\n    (emit, { input, signal }) => {\n      const storage = storageOf();\n      const key = prefix + input.key;\n      const initial = storage.getItem(key);\n      let chain = Promise.resolve();\n      // Re-read after each awaited decoder: cancellation can happen while it runs.\n      const active = (): boolean => !signal.aborted;\n      const publish = (raw: string | null, source: StorageChangeSource): void => {\n        chain = chain.then(async () => {\n          if (!active()) return;\n          try {\n            const entry = await decode(raw, input.key);\n            if (active()) emit({ _tag: 'StorageChanged', key: input.key, source, entry });\n          } catch (cause) {\n            if (\n              active() &&\n              cause instanceof StorageFailure &&\n              cause.error._tag === 'StorageDecodeError'\n            ) {\n              emit({ _tag: 'StorageDecodeFailed', key: input.key, source, error: cause.error });\n            }\n          }\n        });\n      };\n      const own = (change: Change): void => {\n        if (change.key === null || change.key === key) publish(change.value, 'driver');\n      };\n      const other = (event: StorageEvent): void => {\n        if (event.storageArea === storage && (event.key === null || event.key === key))\n          publish(event.newValue, 'tab');\n      };\n      const hub = listeners.get(storage) ?? new Set<(change: Change) => void>();\n      listeners.set(storage, hub);\n      hub.add(own);\n      if (typeof window !== 'undefined') window.addEventListener('storage', other);\n      publish(initial, 'initial');\n      return () => {\n        hub.delete(own);\n        if (typeof window !== 'undefined') window.removeEventListener('storage', other);\n      };\n    },\n  );\n  return {\n    name,\n    concurrency: 'merge',\n    toError: (cause) =>\n      cause instanceof StorageFailure\n        ? cause.error\n        : {\n            _tag: 'StorageAccessError',\n            operation: 'Read',\n            key: undefined,\n            message: messageOf(cause),\n          },\n    run: async (input, ctx) => {\n      ctx.signal.throwIfAborted();\n      try {\n        if (input._tag === 'Watch') return await watch.run(input, ctx);\n        const storage = storageOf();\n        if (input._tag === 'Clear') {\n          if (prefix === '') {\n            storage.clear();\n            notify(storage, { key: null, value: null });\n          } else {\n            const keys: string[] = [];\n            for (let i = 0; i < storage.length; i += 1) {\n              const key = storage.key(i);\n              if (key?.startsWith(prefix)) keys.push(key);\n            }\n            for (const key of keys) {\n              storage.removeItem(key);\n              notify(storage, { key, value: null });\n            }\n          }\n          return { _tag: 'StorageCleared' };\n        }\n        const key = prefix + input.key;\n        if (input._tag === 'Read') {\n          const entry = await decode(storage.getItem(key), input.key);\n          ctx.signal.throwIfAborted();\n          return { _tag: 'StorageValue', key: input.key, entry };\n        }\n        if (input._tag === 'Write') {\n          const value = JSON.stringify(\n            options.encode === undefined ? input.value : options.encode(input.value),\n          );\n          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- JSON.stringify(undefined) returns undefined despite its lib type\n          if (value === undefined) throw new TypeError('Storage values must have a JSON encoding.');\n          storage.setItem(key, value);\n          notify(storage, { key, value });\n          return { _tag: 'StorageWritten', key: input.key };\n        }\n        storage.removeItem(key);\n        notify(storage, { key, value: null });\n        return { _tag: 'StorageRemoved', key: input.key };\n      } catch (cause) {\n        if (ctx.signal.aborted || cause instanceof StorageFailure) throw cause;\n        throw new StorageFailure({\n          _tag: 'StorageAccessError',\n          operation: input._tag,\n          key: keyOf(input),\n          message: messageOf(cause),\n        });\n      }\n    },\n  };\n}\n"]}

package/dist/store-binding.js

@@ -1,4 +1,5 @@
 import { scopeFor } from './store-scope.js';
+import { message } from './view/index.js';
 export class StoreBinding {
     #host;
     #tag;
@@ -21,8 +22,7 @@ export class StoreBinding {
     #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.`);
+            throw new Error(message(50, this.#tag, name));
         }
         return store;
     }

package/dist/store-binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-binding.js","sourceRoot":"","sources":["../src/store-binding.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAK5C,MAAM,OAAO,YAAY;IACd,KAAK,CAAc;IACnB,IAAI,CAAS;IACb,SAAS,CAAgC;IACzC,SAAS,CAAW;IAC7B,kFAAkF;IACzE,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IACtD,YAAY,GAAmB,EAAE,CAAC;IAElC,YAAY,IAAiB,EAAE,GAAW,EAAE,QAA6B,EAAE,QAAkB;QAC3F,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,SAAS,CAAC,KAAe;QACvB,OAAO,CACL,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAC7B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAChC,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,IAAY;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,IAAI,IAAI,CAAC,IAAI,iBAAiB,IAAI,8CAA8C;gBAC9E,YAAY,IAAI,2DAA2D,CAC9E,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,oFAAoF;IACpF,IAAI,CAAI,GAAgB;QACtB,yFAAyF;QACzF,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAU,CAAC;IAClE,CAAC;IAED,uFAAuF;IACvF,IAAI,CAAC,KAAqB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAkC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1E,CAAC;IAED,0FAA0F;IAC1F,OAAO;QACL,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtC,IAAI,CAAC,YAAY,CAAC,IAAI,CACpB,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;gBACjC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YACrC,CAAC,CAAC,CACH,CAAC;YACF,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,UAAU;QACR,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY;YAAE,WAAW,EAAE,CAAC;QAC3D,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,IAAiB,EACjB,GAAW,EACX,QAA6B,EAC7B,QAAkB,EACP,EAAE,CAAC,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC","sourcesContent":["// A component's connection to the stores it declares (ADR 0013): resolve, read, subscribe, send.\n// `defineStore()` registers `bindStores` (features.ts), so apps without stores don't bundle it.\nimport type { FeatureHost, StoreLink } from './features.js';\nimport { scopeFor } from './store-scope.js';\nimport type { AnyStore, AnyStoreInstance, StoreRef, StoreSendInput } from './store.js';\n\ntype OnChange = (store: AnyStore, state: unknown, prev: unknown) => void;\n\nexport class StoreBinding implements StoreLink {\n  readonly #host: FeatureHost;\n  readonly #tag: string;\n  readonly #declared: ReadonlyMap<string, AnyStore>;\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(host: FeatureHost, tag: string, declared: readonly AnyStore[], onChange: OnChange) {\n    this.#host = host;\n    this.#tag = tag;\n    this.#declared = new Map(declared.map((s) => [s.name, s]));\n    this.#onChange = onChange;\n  }\n\n  #instance(store: AnyStore): AnyStoreInstance {\n    return (\n      this.#bound.get(store.name) ??\n      this.#host.stores[store.name] ??\n      scopeFor(this.#host).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\n/** The store feature (features.ts): a host's binding to its declared stores. */\nexport const bindStores = (\n  host: FeatureHost,\n  tag: string,\n  declared: readonly AnyStore[],\n  onChange: OnChange,\n): StoreLink => new StoreBinding(host, tag, declared, onChange);\n"]}
+{"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.\n// `defineStore()` registers `bindStores` (features.ts), so apps without stores don't bundle it.\nimport type { FeatureHost, StoreLink } from './features.js';\nimport { scopeFor } from './store-scope.js';\nimport type { AnyStore, AnyStoreInstance, StoreRef, StoreSendInput } from './store.js';\nimport { message } from './view/index.js';\n\ntype OnChange = (store: AnyStore, state: unknown, prev: unknown) => void;\n\nexport class StoreBinding implements StoreLink {\n  readonly #host: FeatureHost;\n  readonly #tag: string;\n  readonly #declared: ReadonlyMap<string, AnyStore>;\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(host: FeatureHost, tag: string, declared: readonly AnyStore[], onChange: OnChange) {\n    this.#host = host;\n    this.#tag = tag;\n    this.#declared = new Map(declared.map((s) => [s.name, s]));\n    this.#onChange = onChange;\n  }\n\n  #instance(store: AnyStore): AnyStoreInstance {\n    return (\n      this.#bound.get(store.name) ??\n      this.#host.stores[store.name] ??\n      scopeFor(this.#host).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(message(50, this.#tag, name));\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\n/** The store feature (features.ts): a host's binding to its declared stores. */\nexport const bindStores = (\n  host: FeatureHost,\n  tag: string,\n  declared: readonly AnyStore[],\n  onChange: OnChange,\n): StoreLink => new StoreBinding(host, tag, declared, onChange);\n"]}

package/dist/store-scope.d.ts

@@ -1,5 +1,5 @@
 import type { AnyStore, AnyStoreInstance } from './store.js';
-/** Page-level seed written by @gyral/ssr: `<script type="application/json" data-gyral-stores>`. */
+/** Page-level seed from `@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";
@@ -16,12 +16,10 @@ export declare class StoreRegistry {
 }
 /**
  * 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
+ * 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

package/dist/store-scope.js

@@ -1,4 +1,5 @@
-/** Page-level seed written by @gyral/ssr: `<script type="application/json" data-gyral-stores>`. */
+import { message } from './view/index.js';
+/** Page-level seed from `@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';
@@ -28,8 +29,7 @@ export class StoreRegistry {
         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('; ')}`);
+        console.error(message(51, store.name, check.issues.join('; ')));
         return store.instance();
     }
     /** Every instance's state by store name (what the SSR seed carries). */
@@ -46,7 +46,7 @@ export class StoreRegistry {
 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
+ * 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) {
@@ -59,15 +59,6 @@ export function withStoreScope(registry, fn) {
         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)
@@ -77,7 +68,7 @@ function parseSeeds(raw, where) {
         return parsed !== null && typeof parsed === 'object' ? parsed : {};
     }
     catch (error) {
-        console.error(`unreadable ${STORE_SEED_ATTRIBUTE} seed on ${where}`, error);
+        console.error(message(52, STORE_SEED_ATTRIBUTE, where), error);
         return {};
     }
 }
@@ -111,8 +102,7 @@ export function providerScope(el) {
 export function serverScopeFor(tag, store) {
     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 }).");
+    throw new Error(message(53, tag, store.name));
 }
 /** The scope for a component: its nearest provider (across shadow roots) or the default. */
 export function scopeFor(host) {

package/dist/store-scope.js.map

@@ -1 +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 type { AnyStore, AnyStoreInstance } from './store.js';\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 = 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/**\n * The scope for a server render: the request's, set by `withStoreScope`. Nested\n * `<gyral-stores>` providers on the server are the server renderer's job (Phase 4, gyral-g1r.9).\n */\nexport function serverScopeFor(tag: string, store: AnyStore): StoreRegistry {\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\n/** The scope for a component: its nearest provider (across shadow roots) or the default. */\nexport function scopeFor(host: Element): StoreRegistry {\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"]}
+{"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 type { AnyStore, AnyStoreInstance } from './store.js';\nimport { message } from './view/index.js';\n\n/** Page-level seed from `@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(message(51, store.name, check.issues.join('; ')));\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\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(message(52, STORE_SEED_ATTRIBUTE, 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 = 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/**\n * The scope for a server render: the request's, set by `withStoreScope`. Nested\n * `<gyral-stores>` providers on the server are the server renderer's job (Phase 4, gyral-g1r.9).\n */\nexport function serverScopeFor(tag: string, store: AnyStore): StoreRegistry {\n  if (serverScope !== undefined) return serverScope;\n  throw new Error(message(53, tag, store.name));\n}\n\n/** The scope for a component: its nearest provider (across shadow roots) or the default. */\nexport function scopeFor(host: Element): StoreRegistry {\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.js

@@ -1,8 +1,11 @@
 import { DEVTOOLS_ENABLED, devCommands, devStore } from '#devtools';
 import { splitNext, } from './command.js';
+import { fail } from './errors.js';
 import { features } from './features.js';
 import { makeInterpreter } from './internal/interpreter.js';
+import { noteActivity } from './scheduler.js';
 import { bindStores } from './store-binding.js';
+import { message } from './view/index.js';
 /** No DOM means a server render: store commands never run there (ADR 0012). */
 const onServer = typeof document === 'undefined';
 /** Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. */
@@ -45,8 +48,7 @@ function createInstance(store, initial) {
     // 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.');
+            console.warn(message(54, store.name, target.name));
             return;
         }
         scope(target).send(msg);
@@ -63,7 +65,15 @@ function createInstance(store, initial) {
                 // Stores have no IntentRejected reducer; only their own messages apply.
                 if (msg._tag !== 'IntentRejected')
                     instance.send(msg);
-            }, DEVTOOLS_ENABLED ? devCommands(() => `store:${store.name}`) : undefined);
+            }, DEVTOOLS_ENABLED ? devCommands(() => `store:${store.name}`) : undefined, (cause, code, driver) => {
+                const owner = `store "${store.name}"`;
+                const text = code === 40
+                    ? message(40, owner, driver)
+                    : code === 41
+                        ? message(41, owner, driver)
+                        : message(43, owner, driver);
+                fail(cause, 'command', text, { msg: driver });
+            });
             interpreter.run(cmd);
         }
     };
@@ -74,19 +84,37 @@ function createInstance(store, initial) {
         },
         drivers: {},
         send(msg) {
+            noteActivity(); // settled() keeps waiting while messages arrive (04)
             const reducer = reducers[msg._tag];
             if (reducer === undefined) {
-                console.warn(`store "${store.name}" has no update for message "${msg._tag}".`);
+                console.warn(message(55, store.name, msg._tag));
                 return;
             }
             const prev = state;
-            const [next, commands] = splitNext(reducer(prev, msg));
+            let result;
+            try {
+                result = reducer(prev, msg);
+            }
+            catch (cause) {
+                // A store reducer that throws changes nothing (ADR 0024).
+                fail(cause, 'store', message(76, store.name, msg._tag), { msg: msg._tag });
+                return;
+            }
+            const [next, commands] = splitNext(result);
             state = next;
             if (DEVTOOLS_ENABLED)
                 devStore(store.name, msg, prev, next);
-            if (!Object.is(next, prev))
-                for (const listener of [...listeners])
-                    listener(next, prev);
+            if (!Object.is(next, prev)) {
+                // Each subscriber on its own: one that throws doesn't keep the others stale (ADR 0024).
+                for (const listener of [...listeners]) {
+                    try {
+                        listener(next, prev);
+                    }
+                    catch (cause) {
+                        fail(cause, 'store', message(77, store.name), { msg: msg._tag });
+                    }
+                }
+            }
             run(commands);
         },
         subscribe(listener) {