@voltro/client 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -174,6 +174,16 @@ export declare interface ApiHandle {
     readonly errorBus: RpcErrorBus;
 }
 
+/**
+ * Apply seeds from the hydration payload, BEFORE the first client render.
+ *
+ * Unknown store names are skipped rather than throwing: a payload can outlive a
+ * deploy (a cached document, a user with a stale tab), and refusing to boot the
+ * app over a store somebody deleted would turn a cosmetic staleness into a
+ * blank page.
+ */
+export declare const applyStoreSeeds: (seeds: ReadonlyArray<StoreSeed> | undefined) => void;
+
 export declare interface AsyncValidationResult {
     readonly status: ValidationStatus;
     readonly valid: boolean | undefined;
@@ -351,6 +361,9 @@ export declare const clearMutations: () => void;
 /** Drop successfully-sent entries (call after a drain to compact the queue). */
 export declare const clearSent: (queue: Outbox) => Outbox;
 
+/** Drop the recorded history (tests, and a devtools "clear"). */
+export declare const clearStoreHistory: () => void;
+
 export declare const CLIENT_NAME: "framework-client";
 
 export declare interface ClientErrorEvent {
@@ -533,11 +546,28 @@ export declare interface DataTableState<Row> {
     readonly hasMore: boolean;
 }
 
+/** All defined stores, in definition order. */
+export declare const definedStores: () => ReadonlyArray<StoreHandle<never>>;
+
 /** Declare a typed analytics event. */
 export declare const defineEvent: <const Name extends string, A, I>(name: Name, payload: Schema.Schema<A, I>) => EventDescriptor<Name, A>;
 
-/** Identity helper (like `defineTracking('CheckoutButton', { onMount: 'checkout.viewed' })`). */
-export declare const defineTracking: (name: string, map: TrackingMap) => TrackingSpec;
+/**
+ * Define a store.
+ *
+ * `initial` is a FUNCTION, not a value, so every keyed instance gets its own
+ * fresh state rather than sharing one object — the bug you find weeks later
+ * when editing order A also edits order B.
+ */
+export declare const defineStore: <S extends object>(name: string, initial: () => S, options?: {
+    readonly persist?: PersistOptions<S>;
+}) => StoreHandle<S>;
+
+/** Identity helper (like `defineTracking('CheckoutButton', { onMount: 'checkout.viewed' })`).
+ *
+ *  Pass the component's props as the type argument to get a typed catalogue:
+ *  `defineTracking<ComposerProps>('TodoComposer', { onSubmit: (p) => … })`. */
+export declare const defineTracking: <P = Record<string, unknown>>(name: string, map: TrackingMap<P>) => TrackingSpec<P>;
 
 /**
  * Pure projection: turn a capability manifest into one `EntityAdminSpec` per
@@ -588,6 +618,9 @@ declare interface EntryState<T> {
     cachedSnapshot: CacheSnapshot<T> | null;
 }
 
+/** Compares two selector results. Return true to keep the previous value. */
+export declare type Equals<T> = (a: T, b: T) => boolean;
+
 /** Helper: pattern-match the `_tag` field on a thrown error value. Works
  *  on Schema.TaggedError instances + plain `{_tag: ..., …}` objects the
  *  rpc wire emits. Returns undefined for non-tagged errors. */
@@ -711,6 +744,8 @@ export declare const getMutationNotifier: () => MutationNotifier | undefined;
 /** Read the current feed. Newest-first; up to MAX_MUTATIONS entries. */
 export declare const getMutations: () => ReadonlyArray<MutationEvent>;
 
+declare type Listener = () => void;
+
 /**
  * Non-fetching cache used as a LOADING baseline:
  *   - during SSR (no runtime / no provider), and
@@ -737,6 +772,8 @@ export declare class LoadingSubscriptionCache extends SubscriptionCache {
     };
 }
 
+export declare const makeStoreSeedBag: () => StoreSeedBag;
+
 /** Exported for tests: the inspect URL this hook fetches. */
 export declare const manifestUrl: (base: string) => string;
 
@@ -884,6 +921,31 @@ declare interface PermissionState_2 {
 }
 export { PermissionState_2 as PermissionState }
 
+/**
+ * Where a store's state survives a reload.
+ *
+ * Declarative because the hand-rolled version is always the same three bugs:
+ * reading before the browser exists (SSR crashes), writing on every keystroke
+ * (a synchronous localStorage write per character), and a parse that throws on
+ * a value written by an older version of the app and takes the boot with it.
+ */
+export declare interface PersistOptions<S> {
+    /** Storage key. Namespaced by the caller — this is written verbatim. */
+    readonly key: string;
+    /** `local` survives a browser restart; `session` lasts the tab. */
+    readonly storage?: 'local' | 'session';
+    /** Persist only part of the state — a draft, not a whole UI tree. */
+    readonly pick?: (state: S) => Partial<S>;
+    /**
+     * Migrate a value written by an older shape.
+     *
+     * Returning `undefined` DISCARDS it, which is the right answer far more often
+     * than guessing: a stale draft is an annoyance, a half-migrated one is a bug
+     * report nobody can reproduce.
+     */
+    readonly migrate?: (stored: unknown) => Partial<S> | undefined;
+}
+
 /** Structural mirror of @voltro/runtime's PreviewDiff (client stays decoupled). */
 export declare interface PreviewDiff {
     readonly rows: ReadonlyArray<PreviewRowDiff>;
@@ -996,10 +1058,13 @@ export declare const reportClientError: (error: unknown, context?: Record<string
  *  module-global flags + any pending grace-period timer). */
 export declare const _resetFrameworkRuntimesWarning: () => void;
 
+/** Test helper: forget every defined store. NEVER call this in app code. */
+export declare const resetStoreRegistryForTests: () => void;
+
 export declare const resolveByTag: (client: unknown, tag: string) => unknown;
 
 /** Resolve one map entry against the props. Pure. */
-export declare const resolveTrackingEvent: (entry: TrackingEntry | undefined, props: Record<string, unknown>) => TrackingEvent | null;
+export declare const resolveTrackingEvent: <P>(entry: TrackingEntry<P> | undefined, props: P) => TrackingEvent | null;
 
 export declare interface ResourceCanInput {
     /** The action being gated (e.g. `'read'`, `'write'`, `'delete'`). */
@@ -1163,6 +1228,18 @@ export declare const schemaToColumns: (schema: Schema.Schema.Any) => ReadonlyArr
  */
 export declare const schemaToFields: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
 
+/**
+ * Seed a store for THIS request's hydration. Call it anywhere on the server
+ * during a render — a loader, a layout loader — and the value reaches the
+ * client's first render without any serialization step of your own.
+ */
+export declare const seedStore: <S extends object>(handle: StoreHandle<S>, value: Partial<S>, opts?: {
+    readonly key?: string;
+}) => void;
+
+/** Reads a slice out of the state. Its RESULT identity decides re-render. */
+export declare type Selector<S, T> = (state: S) => T;
+
 /** One persisted/wire element of a resumable stream. Mirrors `@voltro/ai`'s
  *  `SeqEvent` without taking a dependency on it (the client stays AI-agnostic). */
 export declare interface SeqElement<E> {
@@ -1220,6 +1297,12 @@ export declare type SequenceResult<Ctx> = {
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
 
+/**
+ * Install the request-scoped bag resolver. Server-side only; pass `null` to
+ * uninstall (tests).
+ */
+export declare const setStoreSeedResolver: (resolver: (() => StoreSeedBag | null) | null) => void;
+
 /**
  * Transition a pending mutation to 'success' or 'error'. Updates the
  * existing entry in-place (preserves order in the buffer) so the
@@ -1236,6 +1319,17 @@ export declare const settleMutation: (id: string, outcome: {
     readonly error: unknown;
 }) => void;
 
+/**
+ * Shallow equality over own enumerable entries — the comparator a selector that
+ * BUILDS something needs.
+ *
+ * `(s) => ({ a: s.a, b: s.b })` and `(s) => s.items.filter(…)` return a fresh
+ * reference every call, so the default identity check always reports "changed".
+ * Comparing one level deep is what makes those selectors behave the way reading
+ * a single field already does.
+ */
+export declare const shallow: <T>(a: T, b: T) => boolean;
+
 /** Shallow element-wise array equality. Pure — the cache-invalidation core. */
 export declare const shallowArrayEqual: (a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>) => boolean;
 
@@ -1337,6 +1431,141 @@ export declare interface StepOptions<Ctx, Result> {
  *  from a step that is being rolled back after it. */
 export declare type StepUndo<Result, Ctx = Record<string, unknown>> = (result: Result, ctx: Ctx) => unknown | Promise<unknown>;
 
+export declare interface StoreHandle<S> {
+    readonly name: string;
+    /**
+     * Read a slice in a component. Re-renders ONLY when the selector's RESULT
+     * changes, so a store with fifty fields re-renders a component that reads one
+     * of them exactly as often as that one field changes.
+     *
+     * "Changes" means `Object.is` by default. A selector that BUILDS something —
+     * an object literal, a mapped or filtered array — returns a fresh reference
+     * every call, so pass `{ equals: shallow }` for those. In dev the framework
+     * warns, once, when it detects the case.
+     */
+    readonly use: <T>(selector: Selector<S, T>, opts?: StoreUseOptions<T>) => T;
+    /** The underlying instance — for actions, effects and tests. */
+    readonly instance: (key?: string) => StoreInstance<S>;
+    /** Shorthand for `instance(key).get()`. */
+    readonly get: (key?: string) => S;
+    /** Shorthand for `instance(key).set(...)`. */
+    readonly set: (next: Partial<S> | Updater<S>, key?: string, label?: string) => void;
+    /**
+     * Run several writes as ONE — one notification, one devtools entry named
+     * `label`, one undo step.
+     *
+     * Without it, an action that touches three fields is three of each: the
+     * devtools show three anonymous writes instead of the thing the user did,
+     * and Ctrl-Z walks back through a third of a change at a time. React batches
+     * the RE-RENDERS on its own; it cannot batch the meaning.
+     *
+     * ```ts
+     * checkout.batch('applyCoupon', () => {
+     *   checkout.set({ coupon })
+     *   checkout.set({ total: recompute(coupon) })
+     * })
+     * ```
+     *
+     * If `fn` throws, every write it made is rolled back — nothing was announced
+     * yet, so a failed action cannot leave the half-applied state that is the
+     * usual reason people reach for a transaction. A nested batch joins its
+     * parent. Passing an `async` function is an error: everything after its
+     * first `await` would land outside the batch.
+     */
+    readonly batch: (label: string, fn: () => void, key?: string) => void;
+    /**
+     * Revert the most recent write to this instance.
+     *
+     * Possible only because every write goes through one seam — the previous
+     * state is recorded there, so undo is a lookup rather than a feature the
+     * store had to be designed around. Returns false when there is nothing to
+     * undo (nothing recorded, or the history has scrolled past it).
+     */
+    readonly undo: (key?: string) => boolean;
+    /** Re-apply the write an `undo` reverted. False when there is nothing ahead. */
+    readonly redo: (key?: string) => boolean;
+    /** Whether `undo` / `redo` would do anything — for disabling a button. */
+    readonly canUndo: (key?: string) => boolean;
+    readonly canRedo: (key?: string) => boolean;
+    /** Drop a keyed instance's state. The global instance cannot be dropped. */
+    readonly release: (key: string) => void;
+    /** Every live key — for devtools and for tests that assert cleanup. */
+    readonly keys: () => ReadonlyArray<string>;
+}
+
+export declare const storeHistory: () => ReadonlyArray<StoreMutation>;
+
+/** One store instance: the global one, or one per key. */
+export declare interface StoreInstance<S> {
+    /** Current state. For actions and tests — components read via a selector. */
+    readonly get: () => S;
+    /** Replace the state. A partial object is merged; a function is applied. */
+    readonly set: (next: Partial<S> | Updater<S>, label?: string) => void;
+    /** Apply many writes as ONE. See {@link StoreHandle.batch}. */
+    readonly batch: (label: string, fn: () => void) => void;
+    /** Reset to the initial state this instance was created with. */
+    readonly reset: () => void;
+    /** Low-level subscribe (what `use` is built on). Returns an unsubscribe. */
+    readonly subscribe: (listener: Listener) => () => void;
+}
+
+/** One recorded write. `prev`/`next` are the state objects themselves — they
+ *  are immutable by convention, so holding them costs a reference. */
+export declare interface StoreMutation {
+    readonly store: string;
+    /** The keyed instance, or undefined for the global one. */
+    readonly key?: string;
+    /** Whatever the caller passed as `set(next, label)`. */
+    readonly label?: string;
+    /**
+     * True when this write WAS an undo.
+     *
+     * Recorded so a devtools feed shows the complete story, and skipped by
+     * `undo()` so repeated calls walk BACK through the stack instead of toggling
+     * between the last two states. Undoing an undo is a redo, and a redo that
+     * pretends to be an undo is the kind of surprise nobody debugs twice.
+     */
+    readonly isUndo?: true;
+    readonly prev: unknown;
+    readonly next: unknown;
+    readonly at: number;
+}
+
+/** One seeded value, as it travels in the hydration payload. */
+export declare interface StoreSeed {
+    readonly store: string;
+    readonly key?: string;
+    readonly value: unknown;
+}
+
+/** Collects seeds for ONE request. The server creates one per render. */
+export declare interface StoreSeedBag {
+    readonly seeds: StoreSeed[];
+}
+
+export declare interface StoreUseOptions<T> {
+    /** Which instance to read. Omitted = the global one. */
+    readonly key?: string;
+    /**
+     * How to decide the selected value is unchanged. Defaults to `Object.is`.
+     *
+     * Pass {@link shallow} whenever the selector builds something new — an object
+     * literal, a mapped or filtered array. Identity comparison can never see two
+     * fresh references as equal, so without it such a selector re-renders on
+     * every change to any field in the store.
+     */
+    readonly equals?: Equals<T>;
+    /**
+     * Keep this keyed instance alive after its last subscriber unmounts.
+     *
+     * The default is to drop it, because instances are created on demand and
+     * nothing else would ever remove them: a table keyed by row id would
+     * accumulate one per row ever rendered. Set this for state that must survive
+     * navigating away and back — a half-filled form, say.
+     */
+    readonly retain?: boolean;
+}
+
 /** Subscribe to client errors. Returns an unsubscribe fn. */
 export declare const subscribeClientErrors: (listener: ClientErrorListener) => (() => void);
 
@@ -1345,6 +1574,9 @@ export declare const subscribeClientTraces: (listener: ClientTraceListener) => (
 
 export declare const subscribeMutations: (cb: () => void) => (() => void);
 
+/** Subscribe to writes — the devtools panel's feed. Returns an unsubscribe. */
+export declare const subscribeStoreHistory: (listener: Listener) => (() => void);
+
 export declare class SubscriptionCache {
     private readonly entries;
     private readonly inactiveTtlMs;
@@ -1649,8 +1881,14 @@ export declare interface SubscriptionStateWithFallback<T> extends SubscriptionMe
     readonly isEmpty: boolean;
 }
 
-/** A map entry: a bare event name, or a function of the component's props. */
-export declare type TrackingEntry = string | ((props: Record<string, unknown>) => TrackingEvent);
+/** A map entry: a bare event name, or a function of the component's props.
+ *
+ *  `P` is the component's prop type. It defaults to an untyped bag so a
+ *  catalogue can stay loose, but naming it is what makes the payload builders
+ *  read real fields instead of indexing into `unknown` and casting — and a cast
+ *  is exactly what an event catalogue must not need, because it is also the
+ *  list of what leaves the browser. */
+export declare type TrackingEntry<P = Record<string, unknown>> = string | ((props: P) => TrackingEvent);
 
 /** A resolved analytics event: a name + arbitrary payload. */
 export declare type TrackingEvent = {
@@ -1659,21 +1897,38 @@ export declare type TrackingEvent = {
 
 /** The declarative map. `onMount`/`onUnmount` are lifecycle; every other key is
  *  a CALLBACK PROP name to wrap (so calling `onClick` also fires its event). */
-export declare interface TrackingMap {
-    readonly onMount?: TrackingEntry;
-    readonly onUnmount?: TrackingEntry;
-    readonly [callback: string]: TrackingEntry | undefined;
+export declare interface TrackingMap<P = Record<string, unknown>> {
+    readonly onMount?: TrackingEntry<P>;
+    readonly onUnmount?: TrackingEntry<P>;
+    readonly [callback: string]: TrackingEntry<P> | undefined;
 }
 
 /** Where resolved events go — the analytics sink (the client→server transport
  *  provides this; tests provide a recorder). */
 export declare type TrackingSink = (event: TrackingEvent) => void;
 
-export declare interface TrackingSpec {
+export declare interface TrackingSpec<P = Record<string, unknown>> {
     readonly name: string;
-    readonly map: TrackingMap;
+    readonly map: TrackingMap<P>;
 }
 
+/**
+ * Jump one instance to the state recorded at `index` — the devtools panel's
+ * back/forward.
+ *
+ * Deliberately NOT built on `undo`. Undo is a stack that CONSUMES entries, so
+ * stepping forward again would be impossible; time travel needs the log to stay
+ * intact and a cursor to move over it. `side` picks which half of the recorded
+ * step to restore, so stepping back from entry i means `('before', i)` and
+ * forward means `('after', i)`.
+ *
+ * The jump is itself recorded — the log should show what happened, including
+ * that somebody travelled — but marked so `undo()` skips it, exactly as an undo
+ * is skipped. Returns false for an index that no longer exists (the log is
+ * bounded, so a long session scrolls past the beginning).
+ */
+export declare const travelToStoreState: (index: number, side: "before" | "after") => boolean;
+
 export declare const UNDO_APPLY_TAG = "__voltro.undo.apply";
 
 export declare const UNDO_LOG_TAG = "__voltro.undo.log";
@@ -1733,6 +1988,9 @@ declare type UpdatePayload<Messages extends WorkflowClientMessages, Name extends
     readonly payload: infer Payload;
 } ? Payload : unknown : unknown;
 
+/** Applied to the current state to produce the next one. */
+export declare type Updater<S> = (state: S) => S;
+
 declare type UpdateResult<Messages extends WorkflowClientMessages, Name extends string> = NonNullable<Messages['updates']> extends Readonly<Record<Name, infer Update>> ? Update extends {
     readonly result: infer Result;
 } ? Omit<WorkflowUpdateResult, 'result'> & {
@@ -2112,7 +2370,7 @@ export declare const useTableSkeleton: (apiName: string, queryTag: string) => Re
  * the returned props. The sink is the analytics transport (injected, so the
  * kernel stays transport-agnostic — and testable).
  */
-export declare const useTracking: (spec: TrackingSpec, props: Record<string, unknown>, sink: TrackingSink) => Record<string, unknown>;
+export declare const useTracking: <P extends object>(spec: TrackingSpec<P>, props: P, sink: TrackingSink) => P;
 
 export declare const useUndo: (options: UseUndoOptions) => UndoControls;
 
@@ -2376,6 +2634,6 @@ export declare interface WorkflowWaitingFor {
  * Lifecycle keys (onMount/onUnmount) are skipped — those fire from effects.
  * Pure: returns a new props object, mutates nothing.
  */
-export declare const wrapTrackedCallbacks: (spec: TrackingSpec, props: Record<string, unknown>, sink: TrackingSink) => Record<string, unknown>;
+export declare const wrapTrackedCallbacks: <P extends object>(spec: TrackingSpec<P>, props: P, sink: TrackingSink) => P;
 
 export { }