@stone-js/store 0.8.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# Stone.js · Store
+
+> Application state written once, read by any view engine. Vanilla core, SSR hydration built in, and
+> no knowledge of React, Vue, Svelte or the DOM.
+
+Part of **[Stone.js](https://stonejs.dev)**, the reference implementation of the
+[Continuum Architecture](https://evens-stone.github.io/continuum-manifesto/manifesto): write your
+domain once, and the context (runtime, protocol, caller) applies to it at run time.
+
+- **Agnostic**: runs during server rendering, in the browser and in React Native, unchanged.
+- **Hydration is not glue**: the state the server rendered is adopted *before* the first render.
+- **Request-isolated by default**: two visitors rendering at once never see each other's state.
+- **A container citizen**: reached with `useContainer()` in a component, injected into a service.
+
+## Install
+
+```bash
+npm i @stone-js/store
+```
+
+## Enabling it
+
+Like every Stone.js module, one of two ways.
+
+```ts
+import { Store, defineStore } from '@stone-js/store'
+import { StoneApp } from '@stone-js/core'
+
+@Store({ stores: [defineStore({ name: 'tasks', state: { items: [], filter: 'all' } })] })
+@StoneApp({ name: 'my-app' })
+export class Application {}
+```
+
+```ts
+import { defineStoneApp, defineConfig } from '@stone-js/core'
+import { defineStore, storeBlueprint } from '@stone-js/store'
+
+export const Application = defineStoneApp({ name: 'my-app' }, [storeBlueprint])
+
+export const AppConfig = defineConfig((blueprint) => blueprint.set('stone.store.stores', [
+  defineStore({ name: 'tasks', state: { items: [], filter: 'all' } })
+]))
+```
+
+## Using it
+
+Every store is registered as `store.<name>`, so anything with the container reaches it.
+
+```ts
+// in a component, on any view engine
+const tasks = useContainer().make<IStore<Tasks>>('store.tasks')
+
+// in a service, through the constructor
+constructor ({ 'store.tasks': tasks }: { 'store.tasks': IStore<Tasks> }) { this.tasks = tasks }
+```
+
+```ts
+tasks.getState()
+tasks.setState({ filter: 'done' })                       // merges, like a component's setState
+tasks.setState((s) => ({ items: [...s.items, task] }))   // or from the current state
+tasks.select((s) => s.items.length)                      // read a derived value now
+tasks.watch((s) => s.items.length, (n) => render(n))     // watch it, told only when it changes
+tasks.reset()
+```
+
+`watch` compares before notifying, which is the difference that matters: a selector building a fresh
+object is never equal to itself, so a naive subscription re-renders forever. Select values, or pass
+your own comparison as the third argument.
+
+## SSR hydration
+
+Nothing to wire. Stone.js already ships a keyed, XSS-safe snapshot channel, and a store reads its
+state out of it when it is registered, which is **before** the first render. Hydrating in an effect
+afterwards is what produces the flash of empty state that hand-rolled integrations suffer from.
+
+The state is merged over the initial state, so a snapshot written before a key existed still hydrates
+into a usable state instead of an incomplete one.
+
+This module never imports a view layer: it reads the snapshot through the container, duck-typed. A Vue
+or Svelte layer registering the same binding gets hydration with nothing to add here.
+
+## Request isolation
+
+`perRequest` defaults to `true`, and the default is the point. A store held as a process-wide
+singleton leaks one visitor's state into the next visitor's page during server rendering, and nothing
+in development reveals it because there is only ever one request at a time. Stone.js gives an
+ephemeral container per event, so honouring it costs nothing.
+
+```ts
+defineStore({ name: 'flags', state: { beta: false }, perRequest: false })   // genuinely process-wide
+```
+
+## Documentation
+
+Full documentation: **[stonejs.dev/docs/extensions/store](https://stonejs.dev/docs/extensions/store)**.
+
+## License
+
+MIT

package/dist/StateStore.d.ts

@@ -0,0 +1,106 @@
+import { IStore, StoreEquality, StoreListener, StoreSelector, StoreUpdate } from './declarations.js';
+/**
+ * Reference equality, the default for a derived value.
+ *
+ * The failure it exists to make visible: a selector that builds a fresh object every call is never
+ * equal to itself, so a component subscribed to it re-renders forever. That is the most common way a
+ * store is misused, in every library on the market, so the rule is documented rather than folklore:
+ * select values, or memoise what you build.
+ */
+export declare function sameValue<Value>(a: Value, b: Value): boolean;
+/**
+ * A store: application state written once, read by any view engine.
+ *
+ * Named `StateStore` so the bare `Store` name belongs to the activation decorator, the same rule that
+ * gives `CacheManager`, `RealtimeManager` and `I18nManager` their suffixes. Nobody writes this name
+ * often: stores are declared with `defineStore` or `@Store()`.
+ *
+ * It knows nothing of React, Vue, Svelte, the DOM or Node. That is what lets the same state layer run
+ * during server rendering, in the browser and in React Native, which is the continuum applied to
+ * state rather than to requests.
+ *
+ * Created through {@link defineStore} or the `@Store()` decorator; resolved from the container, so a
+ * component reaches it with `useContainer()` and a service takes it through its constructor.
+ */
+export declare class StateStore<State extends Record<string, any> = Record<string, any>> implements IStore<State> {
+    private state;
+    private readonly initial;
+    private readonly listeners;
+    /**
+     * Create a store.
+     *
+     * @param initialState - The state to start from, and to return to on `reset`.
+     * @returns A new store.
+     */
+    static create<State extends Record<string, any>>(initialState: State): StateStore<State>;
+    /**
+     * @param initialState - The state to start from.
+     */
+    protected constructor(initialState: State);
+    /**
+     * The current state.
+     *
+     * @returns The state.
+     */
+    getState(): State;
+    /**
+     * Commit a change, merging a partial state.
+     *
+     * @param update - The next partial state, or a function of the current one.
+     */
+    setState(update: StoreUpdate<State>): void;
+    /**
+     * Replace the state wholesale.
+     *
+     * @param state - The next state.
+     */
+    replaceState(state: State): void;
+    /**
+     * Watch every change.
+     *
+     * @param listener - Called after each committed change.
+     * @returns The function that stops watching.
+     */
+    subscribe(listener: StoreListener<State>): () => void;
+    /**
+     * Read a derived value now.
+     *
+     * @param selector - Reads the value out of the state.
+     * @returns The value.
+     */
+    select<Value>(selector: StoreSelector<State, Value>): Value;
+    /**
+     * Watch a derived value, notified only when it actually changes.
+     *
+     * @param selector - Reads the value out of the state.
+     * @param listener - Called with the new and previous value.
+     * @param equals - How to compare, reference equality by default.
+     * @returns The function that stops watching.
+     */
+    watch<Value>(selector: StoreSelector<State, Value>, listener: (value: Value, previous: Value) => void, equals?: StoreEquality<Value>): () => void;
+    /**
+     * Put the state back to what it was created with.
+     */
+    reset(): void;
+    /**
+     * The state as it will be handed to the client.
+     *
+     * @returns The state to serialise.
+     */
+    dehydrate(): State;
+    /**
+     * Adopt a state produced on the server.
+     *
+     * Merged over the initial state rather than replacing it, so a snapshot written by an older release
+     * that lacks a newly added key hydrates into a usable state instead of an incomplete one.
+     *
+     * @param state - The state read from the snapshot.
+     */
+    hydrate(state: State): void;
+    /**
+     * Commit a state and tell every listener, once.
+     *
+     * @param next - The next state.
+     */
+    private commit;
+}

package/dist/StoreServiceProvider.d.ts

@@ -0,0 +1,46 @@
+import { IContainer, IServiceProvider, Promiseable } from '@stone-js/core';
+/**
+ * The container alias a store is resolved under.
+ *
+ * `store.<name>`, so a component can ask for exactly the one it needs: `useContainer().make('store.tasks')`.
+ *
+ * @param name - The store name.
+ * @returns The alias.
+ */
+export declare function storeAlias(name: string): string;
+/**
+ * Registers every declared store in the container, and hydrates it when the client is picking up
+ * server-rendered markup.
+ *
+ * Two things make this worth being first-party rather than a third-party store plus glue:
+ *
+ * - **Hydration is not glue.** The framework already ships a keyed, XSS-safe snapshot channel; a store
+ *   registered here reads its state out of it at registration time, which is *before* the first render.
+ *   Hydrating in an effect afterwards is what produces the flash of empty state every hand-rolled
+ *   integration suffers from.
+ * - **Request isolation is the default.** A store declared `perRequest` (the default) is bound as a
+ *   plain binding on the per-event container, so two visitors rendering at once cannot see each
+ *   other's state. A module-level singleton silently shares it, and nothing in development reveals it.
+ */
+export declare class StoreServiceProvider implements IServiceProvider {
+    private readonly container;
+    /**
+     * @param container - The service container.
+     */
+    constructor(container: IContainer);
+    /**
+     * Register and hydrate every declared store.
+     */
+    register(): Promiseable<void>;
+    /**
+     * The states the server put in the snapshot, if any.
+     *
+     * Duck-typed: `@stone-js/use-view` owns the snapshot transport, and this module never imports it, so
+     * the store stays free of any view engine. A Vue or Svelte layer registering the same `snapshot`
+     * binding gets hydration with nothing to add here.
+     *
+     * @param key - The snapshot key the states live under.
+     * @returns The states by store name.
+     */
+    private hydratedStates;
+}

package/dist/declarations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A listener notified after every committed change.
+ */
+export type StoreListener<State> = (state: State, previous: State) => void;
+/**
+ * Reads a value out of the state. Kept pure: it is called on every change.
+ */
+export type StoreSelector<State, Value> = (state: State) => Value;
+/**
+ * How the next state is produced: a value, or a function of the current one.
+ */
+export type StoreUpdate<State> = Partial<State> | ((state: State) => Partial<State>);
+/**
+ * Compares two selected values to decide whether subscribers must be told.
+ */
+export type StoreEquality<Value> = (a: Value, b: Value) => boolean;
+/**
+ * The store contract, deliberately small and free of any view engine.
+ *
+ * Four operations answer every need a view has: read, write, watch, and derive. Anything larger
+ * belongs to the application, not to a store.
+ */
+export interface IStore<State> {
+    /** The current state. */
+    getState: () => State;
+    /** Commit a change. Merges a partial state, like a component's setState. */
+    setState: (update: StoreUpdate<State>) => void;
+    /** Replace the state wholesale, bypassing the merge. */
+    replaceState: (state: State) => void;
+    /** Watch every change. Returns the function that stops watching. */
+    subscribe: (listener: StoreListener<State>) => () => void;
+    /** Read a derived value now. */
+    select: <Value>(selector: StoreSelector<State, Value>) => Value;
+    /** Watch a derived value, notified only when it actually changes. */
+    watch: <Value>(selector: StoreSelector<State, Value>, listener: (value: Value, previous: Value) => void, equals?: StoreEquality<Value>) => () => void;
+    /** Put the state back to what it was created with. */
+    reset: () => void;
+    /** The state as it will be handed to the client, for SSR. */
+    dehydrate: () => State;
+    /** Adopt a state produced on the server. */
+    hydrate: (state: State) => void;
+}
+/**
+ * A duck-typed snapshot: whatever the view layer registered in the container under `snapshot`.
+ *
+ * Duck-typed on purpose. `@stone-js/use-view` owns the snapshot transport and its XSS-safe
+ * serializer; this module never imports it, so the store stays free of any view engine while still
+ * hydrating from the very channel the framework already uses. A Vue or Svelte layer that registers
+ * the same binding gets hydration with no change here.
+ */
+export interface SnapshotLike {
+    get: <T = unknown>(key: string, fallback?: T) => T | undefined;
+    set?: (key: string, value: unknown) => unknown;
+    add?: (key: string, value: unknown) => unknown;
+}

package/dist/decorators/Store.d.ts

@@ -0,0 +1,31 @@
+import { StoreDefinition } from '../defineStore.js';
+import { ClassType } from '@stone-js/core';
+/**
+ * Options for the `@Store` decorator: the stores to declare, and the `stone.store` bucket.
+ */
+export interface StoreDecoratorOptions {
+    /** The stores this application declares. */
+    stores?: StoreDefinition[];
+    /** The snapshot key the hydrated states live under. */
+    snapshotKey?: string;
+}
+/**
+ * Class decorator: give the application a store, declaratively.
+ *
+ * `@Store()` registers the provider that puts every declared store in the container. A component then
+ * reaches one through `useContainer()`, and a service takes it through its constructor, so the same
+ * state layer serves SSR, a SPA and React Native without any of them being named here.
+ *
+ * @param options - The stores to declare. Everything is optional.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Store, defineStore } from '@stone-js/store'
+ *
+ * @Store({ stores: [defineStore({ name: 'tasks', state: { items: [] } })] })
+ * @StoneApp({ name: 'my-app' })
+ * export class Application {}
+ * ```
+ */
+export declare const Store: <T extends ClassType = ClassType>(options?: StoreDecoratorOptions) => ClassDecorator;

package/dist/defineStore.d.ts

@@ -0,0 +1,42 @@
+import { IStore } from './declarations.js';
+/**
+ * What a store declares about itself.
+ */
+export interface StoreDefinition<State extends Record<string, any> = Record<string, any>> {
+    /** The name it is resolved under, in the container and in the snapshot. */
+    name: string;
+    /** The state it starts from. */
+    state: State;
+    /**
+     * Whether the server keeps one instance per request. Default `true`, and the default matters.
+     *
+     * A store held as a module-level singleton leaks one visitor's state into the next visitor's page
+     * during server rendering. It is the most common SSR state bug there is, and it is invisible in
+     * development because there is only ever one request at a time. The kernel already gives an
+     * ephemeral container per event, so honouring it costs nothing and closes the hole by default.
+     * Set `false` only for state that is genuinely process-wide, like a feature-flag cache.
+     */
+    perRequest?: boolean;
+}
+/**
+ * Declare a store, imperatively.
+ *
+ * The counterpart of the `@Store()` decorator: same declaration, same registration, no decorators
+ * required. Both end up in `stone.store.stores`, which is what the provider registers.
+ *
+ * @param definition - What the store declares.
+ * @returns The definition, ready to be handed to the blueprint.
+ *
+ * @example
+ * ```typescript
+ * export const tasksStore = defineStore({ name: 'tasks', state: { items: [], filter: 'all' } })
+ * ```
+ */
+export declare function defineStore<State extends Record<string, any>>(definition: StoreDefinition<State>): StoreDefinition<State>;
+/**
+ * Build a store from its definition.
+ *
+ * @param definition - What the store declares.
+ * @returns A new store.
+ */
+export declare function makeStore<State extends Record<string, any>>(definition: StoreDefinition<State>): IStore<State>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './StateStore.js';
+export * from './StoreServiceProvider.js';
+export * from './declarations.js';
+export * from './decorators/Store.js';
+export * from './defineStore.js';
+export * from './options/StoreBlueprint.js';

package/dist/index.js

@@ -0,0 +1,327 @@
+import { cloneValue } from '@stone-js/config';
+import { classDecoratorLegacyWrapper, addBlueprint } from '@stone-js/core';
+
+/**
+ * Reference equality, the default for a derived value.
+ *
+ * The failure it exists to make visible: a selector that builds a fresh object every call is never
+ * equal to itself, so a component subscribed to it re-renders forever. That is the most common way a
+ * store is misused, in every library on the market, so the rule is documented rather than folklore:
+ * select values, or memoise what you build.
+ */
+function sameValue(a, b) {
+    return a === b;
+}
+/**
+ * A store: application state written once, read by any view engine.
+ *
+ * Named `StateStore` so the bare `Store` name belongs to the activation decorator, the same rule that
+ * gives `CacheManager`, `RealtimeManager` and `I18nManager` their suffixes. Nobody writes this name
+ * often: stores are declared with `defineStore` or `@Store()`.
+ *
+ * It knows nothing of React, Vue, Svelte, the DOM or Node. That is what lets the same state layer run
+ * during server rendering, in the browser and in React Native, which is the continuum applied to
+ * state rather than to requests.
+ *
+ * Created through {@link defineStore} or the `@Store()` decorator; resolved from the container, so a
+ * component reaches it with `useContainer()` and a service takes it through its constructor.
+ */
+class StateStore {
+    state;
+    initial;
+    listeners = new Set();
+    /**
+     * Create a store.
+     *
+     * @param initialState - The state to start from, and to return to on `reset`.
+     * @returns A new store.
+     */
+    static create(initialState) {
+        return new this(initialState);
+    }
+    /**
+     * @param initialState - The state to start from.
+     */
+    constructor(initialState) {
+        // Cloned both ways: a caller keeping a reference to the object it passed in must not be able to
+        // mutate the store behind its back, and `reset` must return to the original, not to whatever the
+        // state has become.
+        this.initial = cloneValue(initialState);
+        this.state = cloneValue(initialState);
+    }
+    /**
+     * The current state.
+     *
+     * @returns The state.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Commit a change, merging a partial state.
+     *
+     * @param update - The next partial state, or a function of the current one.
+     */
+    setState(update) {
+        const patch = typeof update === 'function' ? update(this.state) : update;
+        this.commit({ ...this.state, ...patch });
+    }
+    /**
+     * Replace the state wholesale.
+     *
+     * @param state - The next state.
+     */
+    replaceState(state) {
+        this.commit(state);
+    }
+    /**
+     * Watch every change.
+     *
+     * @param listener - Called after each committed change.
+     * @returns The function that stops watching.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /**
+     * Read a derived value now.
+     *
+     * @param selector - Reads the value out of the state.
+     * @returns The value.
+     */
+    select(selector) {
+        return selector(this.state);
+    }
+    /**
+     * Watch a derived value, notified only when it actually changes.
+     *
+     * @param selector - Reads the value out of the state.
+     * @param listener - Called with the new and previous value.
+     * @param equals - How to compare, reference equality by default.
+     * @returns The function that stops watching.
+     */
+    watch(selector, listener, equals = sameValue) {
+        let current = selector(this.state);
+        return this.subscribe((state) => {
+            const next = selector(state);
+            if (equals(next, current)) {
+                return;
+            }
+            const previous = current;
+            current = next;
+            listener(next, previous);
+        });
+    }
+    /**
+     * Put the state back to what it was created with.
+     */
+    reset() {
+        this.commit(cloneValue(this.initial));
+    }
+    /**
+     * The state as it will be handed to the client.
+     *
+     * @returns The state to serialise.
+     */
+    dehydrate() {
+        return this.state;
+    }
+    /**
+     * Adopt a state produced on the server.
+     *
+     * Merged over the initial state rather than replacing it, so a snapshot written by an older release
+     * that lacks a newly added key hydrates into a usable state instead of an incomplete one.
+     *
+     * @param state - The state read from the snapshot.
+     */
+    hydrate(state) {
+        this.commit({ ...this.initial, ...state });
+    }
+    /**
+     * Commit a state and tell every listener, once.
+     *
+     * @param next - The next state.
+     */
+    commit(next) {
+        const previous = this.state;
+        if (next === previous) {
+            return;
+        }
+        this.state = next;
+        // Iterated over a copy: a listener that unsubscribes (or subscribes) while being notified must not
+        // change what this round notifies, which is how a set-mutation-during-iteration bug hides.
+        const listeners = [...this.listeners];
+        for (const listener of listeners) {
+            listener(next, previous);
+        }
+    }
+}
+
+/**
+ * Declare a store, imperatively.
+ *
+ * The counterpart of the `@Store()` decorator: same declaration, same registration, no decorators
+ * required. Both end up in `stone.store.stores`, which is what the provider registers.
+ *
+ * @param definition - What the store declares.
+ * @returns The definition, ready to be handed to the blueprint.
+ *
+ * @example
+ * ```typescript
+ * export const tasksStore = defineStore({ name: 'tasks', state: { items: [], filter: 'all' } })
+ * ```
+ */
+function defineStore(definition) {
+    return definition;
+}
+/**
+ * Build a store from its definition.
+ *
+ * @param definition - What the store declares.
+ * @returns A new store.
+ */
+function makeStore(definition) {
+    return StateStore.create(definition.state);
+}
+
+/**
+ * The container alias a store is resolved under.
+ *
+ * `store.<name>`, so a component can ask for exactly the one it needs: `useContainer().make('store.tasks')`.
+ *
+ * @param name - The store name.
+ * @returns The alias.
+ */
+function storeAlias(name) {
+    return `store.${name}`;
+}
+/**
+ * Registers every declared store in the container, and hydrates it when the client is picking up
+ * server-rendered markup.
+ *
+ * Two things make this worth being first-party rather than a third-party store plus glue:
+ *
+ * - **Hydration is not glue.** The framework already ships a keyed, XSS-safe snapshot channel; a store
+ *   registered here reads its state out of it at registration time, which is *before* the first render.
+ *   Hydrating in an effect afterwards is what produces the flash of empty state every hand-rolled
+ *   integration suffers from.
+ * - **Request isolation is the default.** A store declared `perRequest` (the default) is bound as a
+ *   plain binding on the per-event container, so two visitors rendering at once cannot see each
+ *   other's state. A module-level singleton silently shares it, and nothing in development reveals it.
+ */
+class StoreServiceProvider {
+    container;
+    /**
+     * @param container - The service container.
+     */
+    constructor(container) {
+        this.container = container;
+    }
+    /**
+     * Register and hydrate every declared store.
+     */
+    register() {
+        const options = this.container
+            .make('blueprint')
+            .get('stone.store', {});
+        const hydrated = this.hydratedStates(options.snapshotKey ?? 'stores');
+        for (const definition of options.stores ?? []) {
+            const build = () => {
+                const store = makeStore(definition);
+                const state = hydrated[definition.name];
+                // Adopted before anything can read the store, so the first render already has real state.
+                if (state !== undefined) {
+                    store.hydrate(state);
+                }
+                return store;
+            };
+            // A per-request store is rebuilt for each resolution on the ephemeral container; a shared one is
+            // a singleton. Both are declared the same way, which is the point.
+            if (definition.perRequest === false) {
+                this.container.singletonIf(storeAlias(definition.name), build);
+            }
+            else {
+                this.container.bindingIf?.(storeAlias(definition.name), build) ?? this.container.singletonIf(storeAlias(definition.name), build);
+            }
+        }
+    }
+    /**
+     * The states the server put in the snapshot, if any.
+     *
+     * Duck-typed: `@stone-js/use-view` owns the snapshot transport, and this module never imports it, so
+     * the store stays free of any view engine. A Vue or Svelte layer registering the same `snapshot`
+     * binding gets hydration with nothing to add here.
+     *
+     * @param key - The snapshot key the states live under.
+     * @returns The states by store name.
+     */
+    hydratedStates(key) {
+        if (this.container.has?.('snapshot') === undefined || !this.container.has('snapshot')) {
+            return {};
+        }
+        const snapshot = this.container.make('snapshot');
+        return snapshot?.get?.(key, {}) ?? {};
+    }
+}
+
+/**
+ * Opt-in blueprint: register it to give the application a store.
+ *
+ * The imperative half of the pair; `@Store()` is the declarative one. It contributes the service
+ * provider that registers every declared store in the container, so a component reaches one with
+ * `useContainer()` and a service takes it through its constructor. Nothing here knows about a view
+ * engine.
+ *
+ * @example
+ * ```typescript
+ * import { defineStore, storeBlueprint } from '@stone-js/store'
+ *
+ * export const Application = defineStoneApp({ name: 'my-app' }, [storeBlueprint])
+ *
+ * export const AppConfig = defineConfig((blueprint) => blueprint.set('stone.store.stores', [
+ *   defineStore({ name: 'tasks', state: { items: [] } })
+ * ]))
+ * ```
+ */
+const storeBlueprint = {
+    stone: {
+        store: {
+            stores: []
+        },
+        providers: [
+            StoreServiceProvider
+        ]
+    }
+};
+
+/**
+ * Class decorator: give the application a store, declaratively.
+ *
+ * `@Store()` registers the provider that puts every declared store in the container. A component then
+ * reaches one through `useContainer()`, and a service takes it through its constructor, so the same
+ * state layer serves SSR, a SPA and React Native without any of them being named here.
+ *
+ * @param options - The stores to declare. Everything is optional.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * import { Store, defineStore } from '@stone-js/store'
+ *
+ * @Store({ stores: [defineStore({ name: 'tasks', state: { items: [] } })] })
+ * @StoneApp({ name: 'my-app' })
+ * export class Application {}
+ * ```
+ */
+const Store = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // The blueprint is the single source of truth for what the module declares; the decorator only
+        // overrides what it can, its options bucket.
+        const blueprint = cloneValue(storeBlueprint);
+        blueprint.stone.store = { ...blueprint.stone.store, ...options };
+        addBlueprint(target, context, blueprint);
+    });
+};
+
+export { StateStore, Store, StoreServiceProvider, defineStore, makeStore, sameValue, storeAlias, storeBlueprint };

package/dist/options/StoreBlueprint.d.ts

@@ -0,0 +1,49 @@
+import { StoreDefinition } from '../defineStore.js';
+import { AppConfig, StoneBlueprint } from '@stone-js/core';
+/**
+ * Store configuration bucket (`stone.store`).
+ */
+export interface StoreConfig {
+    /**
+     * The stores an application declares, by name.
+     *
+     * Filled by `@Store()` and by handing `defineStore(...)` definitions here.
+     */
+    stores?: StoreDefinition[];
+    /**
+     * The snapshot key the hydrated states live under. Default `'stores'`.
+     */
+    snapshotKey?: string;
+}
+/**
+ * Application config augmented with the store bucket.
+ */
+export interface StoreAppConfig extends Partial<AppConfig> {
+    store: StoreConfig;
+}
+/**
+ * Blueprint for the store module.
+ */
+export interface StoreBlueprint extends StoneBlueprint {
+    stone: StoreAppConfig;
+}
+/**
+ * Opt-in blueprint: register it to give the application a store.
+ *
+ * The imperative half of the pair; `@Store()` is the declarative one. It contributes the service
+ * provider that registers every declared store in the container, so a component reaches one with
+ * `useContainer()` and a service takes it through its constructor. Nothing here knows about a view
+ * engine.
+ *
+ * @example
+ * ```typescript
+ * import { defineStore, storeBlueprint } from '@stone-js/store'
+ *
+ * export const Application = defineStoneApp({ name: 'my-app' }, [storeBlueprint])
+ *
+ * export const AppConfig = defineConfig((blueprint) => blueprint.set('stone.store.stores', [
+ *   defineStore({ name: 'tasks', state: { items: [] } })
+ * ]))
+ * ```
+ */
+export declare const storeBlueprint: StoreBlueprint;

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@stone-js/store",
+  "version": "0.8.9",
+  "description": "View-engine-agnostic universal store for Stone.js, with SSR hydration built in.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-resources"
+  },
+  "homepage": "https://stonejs.dev",
+  "bugs": {
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
+  },
+  "keywords": [
+    "Stone.js",
+    "store",
+    "state",
+    "ssr",
+    "hydration",
+    "agnostic"
+  ],
+  "files": [
+    "/dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-multi-entry": "^6.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.44.1",
+    "rollup-plugin-node-externals": "^8.0.1",
+    "ts-standard": "^12.0.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "ts-standard": {
+    "globals": [
+      "it",
+      "test",
+      "vi",
+      "expect",
+      "describe",
+      "beforeEach"
+    ]
+  },
+  "dependencies": {
+    "@stone-js/config": "0.8.9"
+  },
+  "peerDependencies": {
+    "@stone-js/core": "0.8.9"
+  },
+  "scripts": {
+    "lint": "ts-standard src",
+    "lint:fix": "ts-standard --fix src tests",
+    "predoc": "rimraf docs",
+    "doc": "typedoc",
+    "clean": "rimraf dist",
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage",
+    "test:text": "npm run test:cvg -- --coverage.reporter=text",
+    "test:html": "npm run test:cvg -- --coverage.reporter=html",
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+  }
+}