preact-sigma 5.0.0 → 6.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-`preact-sigma` is a typed state-model builder for Preact and TypeScript. It keeps top-level public state reactive, derived reads local to the model, writes explicit through actions, and side effects owned by explicit setup.
+`preact-sigma` is a typed state-model layer for Preact and TypeScript. It keeps top-level public state reactive, derived reads local to the model, writes explicit through class actions, and side effects owned by explicit setup.
 
 ## Installation
 
@@ -13,22 +13,27 @@ npm install preact-sigma @preact/signals immer preact
 ## Quick Example
 
 ```ts
-import { SigmaType } from "preact-sigma";
-
-const Counter = new SigmaType<{ count: number }>("Counter")
-  .defaultState({
-    count: 0,
-  })
-  .computed({
-    doubled() {
-      return this.count * 2;
-    },
-  })
-  .actions({
-    increment() {
-      this.count += 1;
-    },
-  });
+import { Sigma } from "preact-sigma";
+
+type CounterState = { count: number };
+
+class Counter extends Sigma<CounterState> {
+  constructor() {
+    super({
+      count: 0,
+    });
+  }
+
+  get doubled() {
+    return this.count * 2;
+  }
+
+  increment() {
+    this.count += 1;
+  }
+}
+
+interface Counter extends CounterState {}
 
 const counter = new Counter();
 
@@ -42,5 +47,6 @@ console.log(counter.doubled); // 2
 
 - Concepts, lifecycle, invariants, and API selection live in [`docs/context.md`](./docs/context.md).
 - Persistence-specific guidance lives in [`docs/persist.md`](./docs/persist.md).
+- Migration guidance from v5 lives in [`docs/migrations/v5-to-v6.md`](./docs/migrations/v5-to-v6.md).
 - Runnable usage patterns live in [`examples/`](./examples/), starting with [`examples/basic-counter.ts`](./examples/basic-counter.ts) and [`examples/command-palette.tsx`](./examples/command-palette.tsx).
-- Exact exported signatures live in `dist/*.d.mts` after `pnpm build`.
+- Exact exported signatures and public API comments live in `dist/index.d.mts` and `dist/persist.d.mts` after `pnpm build`.

package/dist/index.d.mts

@@ -1,20 +1,61 @@
-import { C as InferListener, D as SigmaTarget, E as SigmaListenerMap, F as sigmaTargetBrand, I as sigmaTypeBrand, L as signalPrefix, M as sigmaEventsBrand, N as sigmaRefBrand, O as SigmaTargetLike, P as sigmaStateBrand, S as InferEventType, T as RawSigmaListener, a as isSigmaState, b as SigmaSubscribeOptions, c as sigma, d as AnyResource, f as AnySigmaState, g as SigmaChange, h as InferSetupArgs, i as immerable, j as reservedKeys, k as listen, l as AnyDefaultState, m as AnyState, n as action, o as query, p as AnySigmaStateWithEvents, r as effect, s as setAutoFreeze, t as SigmaType, u as AnyEvents, v as SigmaRef, w as Listenable, x as EventParameters, y as SigmaState } from "./framework-GgPzRfff.mjs";
+import { a as SigmaState, c as query, d as Draft, f as Immutable, i as SigmaRef, l as setAutoFreeze, m as Cleanup, n as Sigma, o as SigmaTarget, p as typeSymbol, r as SigmaDefinition, s as castProtected, t as Protected, u as sigma } from "./sigma-DD7HfTvw.mjs";
 
-//#region src/hooks.d.ts
+//#region src/defaults.d.ts
 /**
- * Creates one sigma-state instance for a component.
+ * Shallowly applies defined initial values over a defaults object.
  *
- * `create()` runs once per mounted component instance. When the sigma state
- * defines setup, `useSigma(...)` also runs `setup(...setupArgs)` in an effect
- * and cleans it up when the setup arguments change or the component unmounts.
+ * `undefined` initial values leave their matching default value in place.
  */
-declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?: InferSetupArgs<T>): T;
+declare function mergeDefaults<T extends object>(initial: Partial<T> | undefined, defaults: T): T;
+//#endregion
+//#region src/listener.d.ts
+/** Sigma targets and protected sigma target views that carry typed event metadata. */
+type SigmaListenable<TEvents extends object = any> = {
+  readonly [typeSymbol]: {
+    readonly events: TEvents;
+  };
+};
+/** Target types supported by `listen(...)` and `useListener(...)`. */
+type Listenable = SigmaListenable | EventTarget;
+type InferEventMap<TTarget extends Listenable> = TTarget extends SigmaListenable<infer TEvents> ? TEvents : TTarget extends Window ? WindowEventMap : TTarget extends Document ? DocumentEventMap : TTarget extends HTMLBodyElement ? HTMLBodyElementEventMap : TTarget extends HTMLMediaElement ? HTMLMediaElementEventMap : TTarget extends HTMLElement ? HTMLElementEventMap : TTarget extends SVGSVGElement ? SVGSVGElementEventMap : TTarget extends SVGElement ? SVGElementEventMap : TTarget extends EventTarget ? Record<string, Event> : never;
+type InferListenerArgs<TEvents extends object, TTarget extends Listenable, TEvent extends string> = [(TEvent extends keyof TEvents ? TEvents[TEvent] : never) extends infer TPayload ? TTarget extends SigmaListenable<any> ? [TPayload] extends [never] ? never : [TPayload] extends [void] ? undefined : TPayload : ([TPayload] extends [never] ? CustomEvent : Extract<TPayload, Event>) & {
+  readonly currentTarget: TTarget;
+} : never];
+/** Infers the listener callback shape for a target and event name. Sigma targets receive payloads directly, while DOM targets receive typed events. */
+type InferListener<TTarget extends Listenable, TEvent extends string = string> = InferEventMap<TTarget> extends infer TEvents extends object ? ((...args: InferListenerArgs<TEvents, TTarget, TEvent>) => void) & {
+  __eventType?: TEvent;
+} : never;
+/** Infers the event names accepted by `listen(...)` or `useListener(...)` for a target. */
+type InferEventType<TTarget extends Listenable> = (InferListener<TTarget> extends {
+  __eventType?: infer TEvent;
+} ? string & TEvent : never) | (string & {});
+/** Adds a listener to a sigma target or DOM target and returns a cleanup function that removes it. */
+declare function listen<TTarget extends Listenable, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, listener: InferListener<TTarget, TEvent>): Cleanup;
+//#endregion
+//#region src/hooks/useListener.d.ts
 /**
  * Attaches an event listener in a component and cleans it up automatically.
  *
  * Passing `null` disables the listener. The latest callback is used without
  * forcing the effect to resubscribe on every render.
  */
-declare function useListener<TTarget extends Listenable | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
+declare function useListener<TTarget extends Listenable, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
+//#endregion
+//#region src/hooks/useSigma.d.ts
+/** Setup arguments and recreation dependencies for `useSigma(...)`. */
+type UseSigmaOptions<TSetup extends readonly any[] = any[]> = {
+  /** Arguments passed to the sigma instance's `onSetup(...)` method. */setup: TSetup | (() => TSetup); /** Dependencies that recreate the sigma instance when they change. */
+  deps?: readonly any[];
+};
+/** Infers the accepted `useSigma(...)` call shape from a sigma class and its setup parameters. */
+type UseSigmaArgs<T extends Sigma<any>> = T extends {
+  onSetup: (...params: infer TParams) => any;
+} ? [] extends TParams ? [create: () => T, options?: Partial<UseSigmaOptions<TParams>>] : [create: () => T, options: UseSigmaOptions<TParams>] : [create: () => T, deps?: readonly any[]];
+/**
+ * Creates or reuses a sigma instance for a component and returns its protected consumer view.
+ *
+ * Classes with `onSetup(...)` run setup in an effect and clean it up on unmount.
+ */
+declare function useSigma<T extends Sigma<any>>(...args: UseSigmaArgs<T>): Protected<T>;
 //#endregion
-export { AnyDefaultState, AnyEvents, AnyResource, AnySigmaState, AnySigmaStateWithEvents, AnyState, EventParameters, InferEventType, InferListener, InferSetupArgs, Listenable, RawSigmaListener, SigmaChange, SigmaListenerMap, SigmaRef, SigmaState, SigmaSubscribeOptions, SigmaTarget, SigmaTargetLike, SigmaType, action, effect, immerable, isSigmaState, listen, query, reservedKeys, setAutoFreeze, sigma, sigmaEventsBrand, sigmaRefBrand, sigmaStateBrand, sigmaTargetBrand, sigmaTypeBrand, signalPrefix, useListener, useSigma };
+export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };

package/dist/index.mjs

@@ -1,149 +1,34 @@
-import { a as initializeSigmaInstance, c as sigma, d as listen, f as sigmaStateBrand, i as buildQueryMethod, l as SigmaListenerMap, n as assertDefinitionKeyAvailable, o as setAutoFreeze, r as buildActionMethod, s as shouldSetup, t as Sigma, u as SigmaTarget } from "./runtime-nX4Aygb8.mjs";
-import { action, computed, effect } from "@preact/signals";
-import { immerable } from "immer";
-import { useEffect, useRef, useState } from "preact/hooks";
-//#region src/framework.ts
-/** Checks whether a value is an instance created by a configured sigma type. */
-function isSigmaState(value) {
-	return Boolean(value[sigmaStateBrand]);
-}
+import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, t as Sigma } from "./sigma-CJibGQ6g.mjs";
+import { useEffect, useRef } from "preact/hooks";
+//#region src/defaults.ts
 /**
-* Creates a standalone tracked query helper with the same signature as `fn`.
+* Shallowly applies defined initial values over a defaults object.
 *
-* Each call is reactive at the call site and does not memoize results across
-* invocations, which makes `query(fn)` a good fit for local tracked helpers
-* that do not need to live on the sigma-state instance.
+* `undefined` initial values leave their matching default value in place.
 */
-function query(fn) {
-	return ((...args) => computed(() => fn(...args)).value);
-}
-/**
-* Builds sigma-state constructors by accumulating default state, computeds,
-* queries, actions, and setup handlers.
-*
-* State and event inference starts from `new SigmaType<TState, TEvents>()`.
-* Later builder methods infer names and types from the objects you pass to them.
-*/
-var SigmaType = class SigmaType extends Function {
-	constructor(name = "Sigma") {
-		super();
-		const { [name]: type } = { [name]: class extends Sigma {
-			static _actionFunctions = Object.create(null);
-			static _computeFunctions = Object.create(null);
-			static _defaultState = Object.create(null);
-			static _defaultStateKeys = [];
-			static _queryFunctions = Object.create(null);
-			static _setupFunction = null;
-			constructor(initialState) {
-				super();
-				initializeSigmaInstance(this, type, initialState);
-			}
-		} };
-		Object.defineProperties(type, Object.getOwnPropertyDescriptors(SigmaType.prototype));
-		return type;
-	}
-	/**
-	* Adds top-level public state and default values to the builder.
-	*
-	* Each property becomes a reactive public state property on instances. Use a
-	* zero-argument function when each instance needs a fresh object or array.
-	*/
-	defaultState(defaultState) {
-		const type = getTypeInternals(this);
-		for (const key in defaultState) {
-			if (defaultState[key] === void 0) continue;
-			type._defaultState[key] = defaultState[key];
-			type._defaultStateKeys.push(key);
-		}
-		return this;
-	}
-	/**
-	* Adds reactive getter properties for derived values that take no arguments.
-	*
-	* Computed names and return types are inferred from the object you pass.
-	* `this` exposes readonly state plus computeds that are already on the builder.
-	*/
-	computed(computeds) {
-		const type = getTypeInternals(this);
-		for (const key in computeds) {
-			assertDefinitionKeyAvailable(type, key, "computed");
-			type._computeFunctions[key] = computeds[key];
-			Object.defineProperty(this.prototype, key, { get: function() {
-				return this["#" + key].value;
-			} });
-		}
-		return this;
-	}
-	/**
-	* Adds reactive read methods that accept arguments.
-	*
-	* Query names, parameters, and return types are inferred from the object you
-	* pass. Each call tracks reactively at the call site and does not memoize
-	* results across invocations.
-	*/
-	queries(queries) {
-		const type = getTypeInternals(this);
-		for (const key in queries) {
-			assertDefinitionKeyAvailable(type, key, "query");
-			const queryFunction = queries[key];
-			type._queryFunctions[key] = queryFunction;
-			Object.defineProperty(this.prototype, key, { value: buildQueryMethod(queryFunction) });
-		}
-		return this;
-	}
-	/**
-	* Adds action methods whose `this` receives draft state, typed events, `commit()`,
-	* and the computeds, queries, and actions already defined on the builder.
-	*
-	* Actions create drafts lazily as they need them. Sync actions on the same
-	* instance reuse the current draft, so they can compose and publish once when
-	* the outer action returns. Declared async actions publish their initial
-	* synchronous work on return, then require `this.commit()` to publish later
-	* writes made after `await`. Non-async actions stay synchronous; if one
-	* returns a promise, sigma throws so async boundaries stay explicit.
-	*/
-	actions(actions) {
-		const type = getTypeInternals(this);
-		for (const key in actions) {
-			assertDefinitionKeyAvailable(type, key, "action");
-			const actionFunction = actions[key];
-			type._actionFunctions[key] = actionFunction;
-			Object.defineProperty(this.prototype, key, { value: buildActionMethod(key, actionFunction) });
-		}
-		return this;
-	}
-	/**
-	* Adds an explicit setup handler for side effects and owned resources.
-	*
-	* Every registered handler runs when `instance.setup(...)` is called, and the
-	* setup argument list is inferred from the first handler you add.
-	*/
-	setup(setup) {
-		const type = getTypeInternals(this);
-		type._setupFunction = setup;
-		return this;
-	}
-};
-function getTypeInternals(type) {
-	return type;
+function mergeDefaults(initial, defaults) {
+	if (!initial) return defaults;
+	const merged = { ...defaults };
+	for (const key in initial) if (initial[key] !== void 0) merged[key] = initial[key];
+	return merged;
 }
 //#endregion
-//#region src/hooks.ts
-/**
-* Creates one sigma-state instance for a component.
-*
-* `create()` runs once per mounted component instance. When the sigma state
-* defines setup, `useSigma(...)` also runs `setup(...setupArgs)` in an effect
-* and cleans it up when the setup arguments change or the component unmounts.
-*/
-function useSigma(create, setupArgs) {
-	const sigmaState = useState(create)[0];
-	if (shouldSetup(sigmaState)) {
-		const args = setupArgs ?? [];
-		useEffect(() => sigmaState.setup(...args), [sigmaState, ...args]);
+//#region src/listener.ts
+function listen(target, name, listener) {
+	if (target instanceof SigmaTarget) {
+		target[listenersSymbol].addListener(name, listener);
+		return () => {
+			target[listenersSymbol].removeListener(name, listener);
+		};
 	}
-	return sigmaState;
+	const eventTarget = target;
+	eventTarget.addEventListener(name, listener);
+	return () => {
+		eventTarget.removeEventListener(name, listener);
+	};
 }
+//#endregion
+//#region src/hooks/useListener.ts
 /**
 * Attaches an event listener in a component and cleans it up automatically.
 *
@@ -159,4 +44,37 @@ function useListener(target, name, listener) {
 	}, [target, name]);
 }
 //#endregion
-export { SigmaListenerMap, SigmaTarget, SigmaType, action, effect, immerable, isSigmaState, listen, query, setAutoFreeze, sigma, useListener, useSigma };
+//#region src/hooks/useSigma.ts
+const isArray = Array.isArray;
+const depsCache = /* @__PURE__ */ new WeakMap();
+function depsChanged(container, deps) {
+	const cachedDeps = depsCache.get(container);
+	if (!deps && !cachedDeps) return false;
+	if (!deps || !cachedDeps) return true;
+	if (deps.length !== cachedDeps.length || deps.some((dep, index) => !Object.is(dep, cachedDeps[index]))) return true;
+	return false;
+}
+function useSigma(create, optionsOrDeps) {
+	const container = useRef(null);
+	let setup;
+	let deps;
+	if (isArray(optionsOrDeps)) deps = optionsOrDeps;
+	else {
+		setup = optionsOrDeps?.setup;
+		deps = optionsOrDeps?.deps;
+	}
+	if (!container.current || depsChanged(container, deps)) {
+		depsCache.set(container, deps);
+		container.current = create();
+	}
+	const instance = container.current;
+	useEffect(() => {
+		if ("onSetup" in instance) {
+			const setupArgs = setup ? isArray(setup) ? setup : setup() : [];
+			return instance.setup(...setupArgs);
+		}
+	}, [instance, ...isArray(setup) ? setup : []]);
+	return castProtected(instance);
+}
+//#endregion
+export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };

package/dist/persist.d.mts

@@ -1,62 +1,84 @@
-import { A as Immutable, _ as SigmaDefinition, y as SigmaState } from "./framework-GgPzRfff.mjs";
+import { f as Immutable, n as Sigma } from "./sigma-DD7HfTvw.mjs";
 
 //#region src/persist.d.ts
 type MaybePromise<T> = T | Promise<T>;
-type Snapshot<T extends SigmaDefinition> = Immutable<T["state"]>;
-type CodecContext<TState extends object> = {
+/** Decode-time context passed to persistence codecs. */
+interface PersistDecodeContext<TState extends object> {
+  /** Storage key used to read the record being decoded. */
   key: string;
+  /** Version number stored with the record being decoded. */
   storedVersion: number;
-  baseState: Readonly<TState>;
-};
+  /** Current committed snapshot before the decoded value is applied. */
+  baseState: Immutable<TState>;
+}
+/** Context passed to background write error handlers. */
+interface PersistErrorContext<TState extends object> {
+  /** Sigma instance whose state was being persisted. */
+  instance: Sigma<TState>;
+  /** Storage key used for the failed write. */
+  key: string;
+}
 /** A stored persistence record with version and save-time metadata. */
 interface PersistRecord<TStored = unknown> {
   version: number;
   savedAt: number;
   value: TStored;
 }
-/** Storage adapter used by persistence helpers. */
-interface PersistStore<TRecord> {
-  read(key: string): MaybePromise<TRecord | undefined>;
-  write(key: string, record: TRecord): MaybePromise<void>;
-  remove(key: string): MaybePromise<void>;
+/** Key-value storage adapter used by persistence helpers. The method names match Keyv and `Map`. */
+interface PersistStore<TStored = unknown> {
+  get(key: string): MaybePromise<PersistRecord<TStored> | undefined>;
+  set(key: string, record: PersistRecord<TStored>): MaybePromise<unknown>;
+  delete(key: string): MaybePromise<unknown>;
 }
 /** Synchronous storage adapter used by sync restore helpers. */
-interface SyncPersistStore<TRecord> extends PersistStore<TRecord> {
-  read(key: string): TRecord | undefined;
-  write(key: string, record: TRecord): void;
-  remove(key: string): void;
+interface SyncPersistStore<TStored = unknown> extends PersistStore<TStored> {
+  get(key: string): PersistRecord<TStored> | undefined;
+  set(key: string, record: PersistRecord<TStored>): unknown;
+  delete(key: string): unknown;
 }
-/** Codec that maps between in-memory sigma state and stored payloads. */
-interface PersistCodec<TState extends object, TStored = TState> {
+/** Codec that maps between committed sigma snapshots and stored payloads. */
+interface PersistCodec<TState extends object, TStored = Immutable<TState>> {
   version: number;
-  encode(state: Readonly<TState>): TStored;
-  decode(stored: unknown, context: CodecContext<TState>): TState;
+  encode(state: Immutable<TState>): TStored;
+  decode(stored: unknown, context: PersistDecodeContext<TState>): TState;
 }
 /** Scheduling policy for persistence writes. */
 type PersistSchedule = "immediate" | "microtask" | {
   debounceMs: number;
 };
-/** Options shared by restore and persistence helpers. */
-interface PersistOptions<T extends SigmaDefinition, TStored = Snapshot<T>> {
-  /** Storage key used for reads, writes, and removals. */
+interface PersistLifecycleOptions<TState extends object> {
+  /** Storage key used for gets, sets, and deletes. */
   key: string;
-  /** Store adapter that owns persistence I/O. */
-  store: PersistStore<PersistRecord<TStored>>;
-  /** Codec that maps committed snapshots to stored payloads. Defaults to an identity codec with version 1. */
-  codec?: PersistCodec<Snapshot<T>, TStored>;
   /** Scheduling policy for future writes. Defaults to `"microtask"`. */
   schedule?: PersistSchedule;
   /** Writes the current committed snapshot once after persistence becomes active. */
   writeInitial?: boolean;
   /** Receives background write failures without stopping persistence automatically. */
-  onWriteError?: (error: unknown, context: {
-    instance: SigmaState<T>;
-    key: string;
-  }) => void;
+  onWriteError?: (error: unknown, context: PersistErrorContext<TState>) => void;
+}
+/** Options shared by restore and persistence helpers. */
+interface PersistOptions<TState extends object, TStored = Immutable<TState>> extends PersistLifecycleOptions<TState> {
+  /** Store adapter that owns persistence I/O for stored records. */
+  store: PersistStore<TStored>;
+  /** Codec that maps committed snapshots to stored payloads. Defaults to an identity codec with version 1. */
+  codec?: PersistCodec<TState, TStored>;
+  pick?: never;
+}
+/** Options that persist selected top-level state keys without a custom codec. */
+interface PickPersistOptions<TState extends object, TKey extends keyof TState = keyof TState> extends PersistLifecycleOptions<TState> {
+  /** Store adapter that owns persistence I/O for the selected top-level keys. */
+  store: PersistStore<Pick<TState, TKey>>;
+  /** Top-level state keys to persist and restore from the current base snapshot. */
+  pick: readonly TKey[];
+  codec?: never;
 }
 /** Options that require a synchronous store. */
-interface SyncPersistOptions<T extends SigmaDefinition, TStored = Snapshot<T>> extends PersistOptions<T, TStored> {
-  store: SyncPersistStore<PersistRecord<TStored>>;
+interface SyncPersistOptions<TState extends object, TStored = Immutable<TState>> extends PersistOptions<TState, TStored> {
+  store: SyncPersistStore<TStored>;
+}
+/** Pick-based options that require a synchronous store. */
+interface SyncPickPersistOptions<TState extends object, TKey extends keyof TState = keyof TState> extends PickPersistOptions<TState, TKey> {
+  store: SyncPersistStore<Pick<TState, TKey>>;
 }
 /** Result returned by restore helpers. */
 type RestoreResult = {
@@ -75,27 +97,30 @@ interface PersistenceHandle {
   /** Stops future persistence and waits for any active write to settle. */
   stop(): Promise<void>;
 }
-/** Async restore-plus-persist binding result. */
-interface BoundPersistence extends PersistenceHandle {
+/** Async restore-plus-persist handle. */
+interface HydrationHandle extends PersistenceHandle {
   /** Resolves when restore finishes and reports whether a record was applied. */
   readonly restored: Promise<RestoreResult>;
 }
-/** Sync restore-plus-persist binding result. */
-interface SyncBoundPersistence extends PersistenceHandle {
+/** Sync restore-plus-persist handle. */
+interface SyncHydrationHandle extends PersistenceHandle {
   /** Reports the synchronous restore result that ran before persistence started. */
   readonly restored: RestoreResult;
 }
 /** Restores committed state from a persisted record through an async store. */
-declare function restoreState<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: PersistOptions<T, TStored>): Promise<RestoreResult>;
+declare function restore<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): Promise<RestoreResult>;
+declare function restore<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): Promise<RestoreResult>;
 /** Restores committed state from a persisted record through a sync store. */
-declare function restoreStateSync<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: SyncPersistOptions<T, TStored>): RestoreResult;
-/** Creates a codec that persists selected top-level state keys and reconstructs a full snapshot on decode. */
-declare function pickStateCodec<TState extends object, TKey extends keyof TState>(keys: readonly TKey[]): PersistCodec<TState, Pick<TState, TKey>>;
-/** Persists future committed state changes for one sigma-state instance. */
-declare function persistState<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: PersistOptions<T, TStored>): PersistenceHandle;
+declare function restoreSync<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: SyncPickPersistOptions<TState, TKey>): RestoreResult;
+declare function restoreSync<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: SyncPersistOptions<TState, TStored>): RestoreResult;
+/** Persists future committed state changes for one sigma instance. */
+declare function persist<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): PersistenceHandle;
+declare function persist<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): PersistenceHandle;
 /** Restores state, then begins persisting future committed changes. */
-declare function bindPersistence<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: PersistOptions<T, TStored>): BoundPersistence;
+declare function hydrate<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): HydrationHandle;
+declare function hydrate<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): HydrationHandle;
 /** Restores state synchronously, then begins persisting future committed changes. */
-declare function bindPersistenceSync<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: SyncPersistOptions<T, TStored>): SyncBoundPersistence;
+declare function hydrateSync<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: SyncPickPersistOptions<TState, TKey>): SyncHydrationHandle;
+declare function hydrateSync<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: SyncPersistOptions<TState, TStored>): SyncHydrationHandle;
 //#endregion
-export { BoundPersistence, PersistCodec, PersistOptions, PersistRecord, PersistSchedule, PersistStore, PersistenceHandle, RestoreResult, SyncBoundPersistence, SyncPersistOptions, SyncPersistStore, bindPersistence, bindPersistenceSync, persistState, pickStateCodec, restoreState, restoreStateSync };
+export { HydrationHandle, PersistCodec, PersistDecodeContext, PersistErrorContext, PersistOptions, PersistRecord, PersistSchedule, PersistStore, PersistenceHandle, PickPersistOptions, RestoreResult, SyncHydrationHandle, SyncPersistOptions, SyncPersistStore, SyncPickPersistOptions, hydrate, hydrateSync, persist, restore, restoreSync };