import { ReadonlySignal } from '@preact/signals-core';

/**
 * `defineStore({ initial, actions })` — composable testable stores layered on
 * top of `reactive.ts`'s signals.
 *
 * Three rules:
 * 1. `state` is read-only. Consumers read via `state.value` or subscribe via
 *    `effect()`. They cannot write directly.
 * 2. `actions` is the only mutation surface. All writes go through named
 *    action functions. This is what makes stores testable — assert against
 *    actions, not against arbitrary writes.
 * 3. `reset()` resets to `initial()`. Always defined; tests use it for
 *    setup, lifecycle hooks (route change, sign-out, etc.) use it for
 *    tear-down.
 *
 * A module-level registry tracks every store created via `defineStore()`;
 * `resetAllStores()` walks the registry and calls each `reset()`. Useful for
 * tests + project-switch / logout / route-reset scenarios where every piece
 * of client state should return to its initial shape.
 */

interface Store<TState, TActions> {
    /** Read-only reactive view. Consumers read `state.value` or subscribe via `effect()`. */
    readonly state: ReadonlySignal<TState>;
    /** Named mutators — the only way to change state. */
    readonly actions: TActions;
    /** Reset state to `initial()`. Used by tests and lifecycle hooks. */
    reset(): void;
}
interface DefineStoreSpec<TState, TActions> {
    initial: () => TState;
    actions: (set: (next: TState) => void, get: () => Readonly<TState>) => TActions;
}
declare function defineStore<TState, TActions>(spec: DefineStoreSpec<TState, TActions>): Store<TState, TActions>;
/**
 * Reset every store registered via `defineStore()` to its `initial()` value.
 * Used by tests and by application lifecycle hooks (project switch, logout,
 * route reset).
 */
declare function resetAllStores(): void;
/**
 * Test helper — clears the registry. Exposed via the `kerfjs/testing` subpath,
 * not the main `kerfjs` entry. Unit tests use it to isolate stores between cases.
 */
declare function clearStoreRegistry(): void;

export { type Store as S, clearStoreRegistry as c, defineStore as d, resetAllStores as r };