preact-sigma 2.2.1 → 2.2.3

package/README.md

@@ -1,18 +1,16 @@
 # preact-sigma
 
-`preact-sigma` is a typed state-model builder for apps that want Preact's fine-grained reactivity, Immer-backed writes, and explicit lifecycle.
+## Purpose
 
-You define a reusable state type once, then create instances wherever they make sense: inside components, in shared modules, or in plain TypeScript code. Each instance exposes readonly public state, tracked derived reads, imperative actions, and optional setup and event APIs.
+`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.
 
-## Getting Started
-
-To add `preact-sigma` to your project:
+## Installation
 
 ```bash
 npm install preact-sigma
 ```
 
-## Smallest Useful Example
+## Quick Example
 
 ```ts
 import { SigmaType } from "preact-sigma";
@@ -40,157 +38,10 @@ console.log(counter.count); // 1
 console.log(counter.doubled); // 2
 ```
 
-## What It Is
-
-At its core, `preact-sigma` lets you describe a stateful model as a constructor:
-
-- top-level state stays reactive through one signal per state property
-- computed values become tracked getters
-- queries become tracked methods, including queries with arguments
-- actions batch reads and writes through Immer drafts
-- setup handlers own side effects and cleanup
-- typed events let instances notify the outside world without exposing mutable internals
-
-The result feels like a small stateful object from application code, while still behaving like signal-driven state from rendering code.
-
-## What You Can Do With It
-
-`preact-sigma` is useful when you want state logic to live in one reusable unit instead of being split across loose signals, reducers, and effect cleanup code.
-
-With it, you can:
-
-- model domain state as reusable constructors instead of one-off store objects
-- read public state directly while keeping writes inside typed action methods
-- derive reactive values with computed getters and parameterized queries
-- publish state changes from synchronous or async actions
-- observe committed state changes and optional Immer patches
-- snapshot committed top-level state and replace committed state for undo-like flows
-- manage timers, listeners, nested state setup, and teardown through explicit cleanup
-- use the same model inside Preact components with `useSigma(...)` and `useListener(...)`
-
-## Why This Shape Exists
-
-This package exists to keep stateful logic cohesive without giving up signal-level reactivity.
-
-It is a good fit when plain signals start to sprawl across modules, but heavier store abstractions feel too opaque or too tied to component structure. `preact-sigma` keeps the "model object" ergonomics of a class-like API, while preserving readonly public reads, explicit write boundaries, and explicit ownership of side effects.
-
-## Big Picture Example
-
-```ts
-import { computed, SigmaType } from "preact-sigma";
-
-type Todo = {
-  id: string;
-  title: string;
-  done: boolean;
-};
-
-const TodoList = new SigmaType<
-  { draft: string; todos: Todo[]; saving: boolean },
-  { saved: { count: number } }
->("TodoList")
-  .defaultState({
-    draft: "",
-    todos: [],
-    saving: false,
-  })
-  .computed({
-    // Computeds are tracked getters with no arguments.
-    remainingCount() {
-      return this.todos.filter((todo) => !todo.done).length;
-    },
-  })
-  .queries({
-    // Queries stay reactive at the call site and can accept arguments.
-    visibleTodos(filter: "all" | "open" | "done") {
-      return this.todos.filter((todo) => {
-        if (filter === "open") return !todo.done;
-        if (filter === "done") return todo.done;
-        return true;
-      });
-    },
-  })
-  .actions({
-    // Public state is readonly, so writes live in actions.
-    setDraft(draft: string) {
-      this.draft = draft;
-    },
-    addTodo() {
-      if (!this.draft.trim()) return;
-
-      this.todos.push({
-        id: crypto.randomUUID(),
-        title: this.draft,
-        done: false,
-      });
-      this.draft = "";
-    },
-    toggleTodo(id: string) {
-      const todo = this.todos.find((todo) => todo.id === id);
-      if (todo) todo.done = !todo.done;
-    },
-    async save() {
-      this.saving = true;
-      this.commit(); // Publish the loading state before awaiting.
-
-      await fetch("/api/todos", {
-        method: "POST",
-        body: JSON.stringify(this.todos),
-      });
-
-      this.saving = false;
-      this.commit(); // Publish post-await writes explicitly.
-      this.emit("saved", { count: this.todos.length });
-    },
-  })
-  .setup(function (storageKey: string) {
-    // Setup is explicit and returns cleanup resources.
-    const interval = window.setInterval(() => {
-      localStorage.setItem(storageKey, JSON.stringify(this.todos));
-    }, 1000);
-
-    return [() => window.clearInterval(interval)];
-  });
-
-const todoList = new TodoList();
-
-// setup(...) returns one cleanup function for everything this instance owns.
-const cleanup = todoList.setup("todos-demo");
-
-// Queries are reactive where they are read.
-const firstOpenTitle = computed(() => {
-  return todoList.visibleTodos("open")[0]?.title ?? "Nothing open";
-});
-
-// Events are typed and unsubscribe cleanly.
-const stop = todoList.on("saved", ({ count }) => {
-  console.log(`Saved ${count} todos`);
-});
-
-todoList.setDraft("Write the README");
-todoList.addTodo();
-await todoList.save();
-
-console.log(todoList.remainingCount);
-console.log(firstOpenTitle.value);
-
-stop();
-cleanup();
-```
-
-In Preact, the same constructor can be used with `useSigma(() => new TodoList(), ["todos-demo"])` so the component owns one instance and `setup(...)` cleanup runs automatically. Use `useListener(...)` when you want component-scoped event subscriptions with automatic teardown.
-
-Cleanup resources can be returned as functions, `AbortController`, objects with `dispose()`, or objects with `Symbol.dispose`.
-
-Inside setup, `this` exposes the public instance plus `emit(...)` and `act(fn)`. Use `this.act(function () { ... })` when setup needs one synchronous anonymous action with normal draft, `commit()`, and `emit(...)` semantics, whether that work happens immediately in the setup body or later from a setup-owned callback, but should not become a public action method.
-
-## Constructor and Defaults
-
-- `defaultState` values may be plain values or zero-argument initializer functions. Use initializer functions when each instance needs a fresh object, array, or class instance.
-- Constructor input shallowly overrides `defaultState`, so `new TodoList({ draft: "ready" })` replaces only the top-level keys you pass.
-
-## More Docs
+## Documentation Map
 
-- [llms.txt](./llms.txt) provides the exhaustive machine-oriented API guide and terminology.
-- Companion skills are available via `npx skills add alloc/preact-sigma`.
-- The `preact-sigma` skill packages the procedural guidance and agent-oriented workflow for this library.
+- Concepts, lifecycle, invariants, and API selection live in [`docs/context.md`](./docs/context.md).
+- Quick-start usage lives in [`examples/basic-counter.ts`](./examples/basic-counter.ts).
+- An advanced end-to-end example lives in [`examples/command-palette.tsx`](./examples/command-palette.tsx).
+- Focused examples for non-obvious APIs live in [`examples/async-commit.ts`](./examples/async-commit.ts), [`examples/observe-and-restore.ts`](./examples/observe-and-restore.ts), [`examples/signal-access.ts`](./examples/signal-access.ts), and [`examples/setup-act.ts`](./examples/setup-act.ts).
+- Exact exported signatures live in `dist/index.d.mts` after `pnpm build`.

package/dist/index.d.mts

@@ -59,7 +59,7 @@ type SigmaRef<T = unknown> = T & SigmaRefBrand;
 type AnyEvents = Record<string, object | void>;
 /** The top-level state object shape used by sigma types. */
 type AnyState = Record<string, unknown>;
-/** The object accepted by `.defaultState(...)`. */
+/** The object accepted by `.defaultState(...)`, where each property may be a value or a zero-argument initializer. */
 type AnyDefaultState<TState extends AnyState> = { [K in keyof TState]?: DefaultStateValue<TState[K]> };
 /** A cleanup resource supported by `.setup(...)`, including function, `dispose()`, and `Symbol.dispose` cleanup. */
 type AnyResource = Cleanup | Disposable | DisposableLike | AbortController;
@@ -68,16 +68,16 @@ type ComputedContext<TState extends AnyState, TComputeds extends object> = Immut
 type QueryMethods<TQueries extends object | undefined> = [undefined] extends [TQueries] ? never : { [K in keyof TQueries]: TQueries[K] extends AnyFunction ? (...args: Parameters<TQueries[K]>) => ReturnType<TQueries[K]> : never };
 type ActionMethods<TActions extends object | undefined> = [undefined] extends [TActions] ? never : { [K in keyof TActions]: TActions[K] extends AnyFunction ? (...args: Parameters<TActions[K]>) => ReturnType<TActions[K]> : never };
 type EventMethods<TEvents extends AnyEvents | undefined> = [undefined] extends [TEvents] ? never : {
-  readonly [sigmaEventsBrand]: TEvents;
+  readonly [sigmaEventsBrand]: TEvents; /** Registers a typed event listener and returns an unsubscribe function. */
   on<TEvent extends string & keyof TEvents>(name: TEvent, listener: [TEvents[TEvent]] extends [void] ? () => void : (payload: TEvents[TEvent]) => void): Cleanup;
 };
 type SetupMethods<TSetupArgs extends any[] | undefined> = [TSetupArgs] extends [undefined] ? never : {
-  setup(...args: Extract<TSetupArgs, any[]>): Cleanup;
+  /** Runs every registered setup handler and returns one cleanup function for the active setup. */setup(...args: Extract<TSetupArgs, any[]>): Cleanup;
 };
 type ReadonlyContext<TState extends AnyState, TComputeds extends object, TQueries extends object> = Immutable<TState> & ComputedValues<TComputeds> & QueryMethods<TQueries>;
 type Emit<TEvents extends AnyEvents> = <TEvent extends string & keyof TEvents>(name: TEvent, ...args: [TEvents[TEvent]] extends [void] ? [] : [payload: TEvents[TEvent]]) => void;
 type ActionContext<TState extends AnyState, TEvents extends AnyEvents, TComputeds extends object, TQueries extends object, TActions extends object> = Draft<TState> & ComputedValues<TComputeds> & QueryMethods<TQueries> & ActionMethods<TActions> & {
-  /** Publishes the current action draft immediately so later boundaries use committed state. */commit(): void;
+  /** Publishes the current action draft immediately so later boundaries use committed state. */commit(): void; /** Emits a typed event from the current action. */
   emit: Emit<TEvents>;
 };
 type DefinitionEvents<T extends SigmaDefinition> = T["events"] extends AnyEvents ? T["events"] : {};
@@ -94,7 +94,7 @@ type AnySigmaStateWithEvents<TEvents extends AnyEvents> = AnySigmaState & {
 };
 /** Options accepted by `.observe(...)`. */
 type SigmaObserveOptions = {
-  patches?: boolean;
+  /** Includes Immer patches and inverse patches on the delivered change object. */patches?: boolean;
 };
 /** The change object delivered to `.observe(...)` listeners. */
 type SigmaObserveChange<TState extends AnyState, TWithPatches extends boolean = false> = {
@@ -113,15 +113,16 @@ type SigmaDefinition = {
   setupArgs?: any[];
 };
 interface SignalAccessors<T extends object> {
+  /** Returns the underlying signal for a top-level state property or computed. */
   get<K extends keyof T>(key: K): ReadonlySignal<T[K]>;
 }
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
 type Simplify<T> = {} & { [K in keyof T]: T[K] };
 type MapSigmaDefinition<T extends SigmaDefinition> = keyof T extends infer K ? K extends "state" ? Immutable<T[K]> & SignalAccessors<Immutable<T[K]>> : K extends "computeds" ? ComputedValues<T[K]> & SignalAccessors<ComputedValues<T[K]>> : K extends "queries" ? QueryMethods<T[K]> : K extends "actions" ? ActionMethods<T[K]> : K extends "events" ? EventMethods<T[K]> : K extends "setupArgs" ? SetupMethods<T[K]> : never : never;
-/** The public instance shape produced by a configured sigma type. */
+/** The public instance shape produced by a configured sigma type, including signal access inferred from the definition. */
 type SigmaState<T extends SigmaDefinition = SigmaDefinition> = AnySigmaState & Simplify<UnionToIntersection<MapSigmaDefinition<T>>>;
 type SetupContext<T extends SigmaDefinition> = SigmaState<T> & {
-  act<TResult>(fn: (this: ActionContext<T["state"], DefinitionEvents<T>, DefinitionComputeds<T>, DefinitionQueries<T>, DefinitionActions<T>>) => TResult): TResult;
+  /** Runs a synchronous anonymous action from setup so reads and writes use normal action semantics. */act<TResult>(fn: (this: ActionContext<T["state"], DefinitionEvents<T>, DefinitionComputeds<T>, DefinitionQueries<T>, DefinitionActions<T>>) => TResult): TResult; /** Emits a typed event from setup. */
   emit: T["events"] extends object ? Emit<T["events"]> : never;
 };
 type MergeObjects<TLeft extends object, TRight> = [TRight] extends [object] ? Extract<Simplify<Omit<TLeft, keyof TRight> & TRight>, TLeft> : TLeft;
@@ -136,39 +137,56 @@ type InferSetupArgs<T extends AnySigmaState> = T extends {
 } ? TArgs : never;
 //#endregion
 //#region src/internal/runtime.d.ts
-/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled. */
+/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled and the setting is shared across instances. */
 declare function setAutoFreeze(autoFreeze: boolean): void;
 /**
  * Returns a shallow snapshot of an instance's committed public state.
  *
  * The snapshot includes one own property for each top-level state key and reads
- * the current committed value for that key. Its type is inferred from the
- * instance's sigma-state definition.
+ * the current committed value for that key. Nested sigma states remain as
+ * referenced values. Its type is inferred from the instance's sigma-state
+ * definition.
  */
 declare function snapshot<T extends AnySigmaState>(publicInstance: T): T extends SigmaState<infer TDefinition> ? Immutable<TDefinition["state"]> : never;
 /**
  * Replaces an instance's committed public state from a snapshot object.
  *
  * The replacement snapshot must be a plain object with exactly the instance's
- * top-level state keys. Its type is inferred from the instance's sigma-state
- * definition.
+ * top-level state keys. It updates committed state outside action semantics and
+ * notifies observers when the committed state changes. Its type is inferred
+ * from the instance's sigma-state definition.
  */
 declare function replaceState<T extends AnySigmaState>(publicInstance: T, nextState: T extends SigmaState<infer TDefinition> ? Immutable<TDefinition["state"]> : never): void;
 //#endregion
 //#region src/framework.d.ts
-/** Checks whether a value is a sigma-state instance. */
+/** Checks whether a value is an instance created by a configured sigma type. */
 declare function isSigmaState(value: unknown): value is AnySigmaState;
-/** Creates a standalone tracked query function with the same signature as `fn`. */
+/**
+ * Creates a standalone tracked query helper with the same signature as `fn`.
+ *
+ * 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.
+ */
 declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: TArgs) => TResult): typeof fn;
 /**
- * Builds sigma-state constructors by accumulating default state, computeds, queries,
- * observers, actions, and setup handlers.
+ * Builds sigma-state constructors by accumulating default state, computeds,
+ * queries, observers, 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.
  */
 declare class SigmaType<TState extends AnyState, TEvents extends AnyEvents = {}, TDefaults extends AnyDefaultState<TState> = {}, TComputeds extends object = {}, TQueries extends object = {}, TActions extends object = {}, TSetupArgs extends any[] = never> extends Function {
   constructor(name?: string);
 }
 /** The constructor shape exposed by a configured sigma type. */
 interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefaults extends AnyDefaultState<TState>, TComputeds extends object, TQueries extends object, TActions extends object, TSetupArgs extends any[]> {
+  /**
+   * Creates a sigma-state instance.
+   *
+   * Constructor input shallowly overrides `defaultState(...)`. Required keys are
+   * inferred from whichever state properties still do not have defaults.
+   */
   new (...args: InitialStateInput<TState, TDefaults>): SigmaState<Extract<OmitEmpty<{
     state: TState;
     events: TEvents;
@@ -177,7 +195,12 @@ interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefault
     actions: TActions;
     setupArgs: TSetupArgs;
   }>, SigmaDefinition>>;
-  /** Does not exist at runtime, only for type inference. */
+  /**
+   * Type-only access to the configured instance shape.
+   *
+   * This property does not exist at runtime. Its type is inferred from the
+   * generics on `new SigmaType<TState, TEvents>()` plus the later builder inputs.
+   */
   get Instance(): SigmaState<Extract<OmitEmpty<{
     state: TState;
     events: TEvents;
@@ -186,9 +209,34 @@ interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefault
     actions: TActions;
     setupArgs: TSetupArgs;
   }>, SigmaDefinition>>;
+  /**
+   * 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<TNextDefaults extends AnyDefaultState<TState>>(defaultState: TNextDefaults): SigmaType<TState, TEvents, MergeObjects<TDefaults, TNextDefaults>, TComputeds, TQueries, TActions, TSetupArgs>;
+  /**
+   * 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<TNextComputeds extends object>(computeds: TNextComputeds & ThisType<ComputedContext<TState, MergeObjects<TComputeds, TNextComputeds>>>): SigmaType<TState, TEvents, TDefaults, MergeObjects<TComputeds, TNextComputeds>, TQueries, TActions, TSetupArgs>;
+  /**
+   * 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<TNextQueries extends object>(queries: TNextQueries & ThisType<ReadonlyContext<TState, TComputeds, MergeObjects<TQueries, TNextQueries>>>): SigmaType<TState, TEvents, TDefaults, TComputeds, MergeObjects<TQueries, TNextQueries>, TActions, TSetupArgs>;
+  /**
+   * Adds a committed-state observer.
+   *
+   * Observers run after successful publishes and can opt into Immer patches
+   * with `{ patches: true }`.
+   */
   observe(listener: (this: ReadonlyContext<TState, TComputeds, TQueries>, change: SigmaObserveChange<TState>) => void, options?: SigmaObserveOptions & {
     patches?: false | undefined;
   }): this;
@@ -207,6 +255,12 @@ interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefault
    * returns a promise, sigma throws so async boundaries stay explicit.
    */
   actions<TNextActions extends object>(actions: TNextActions & ThisType<ActionContext<TState, TEvents, TComputeds, TQueries, MergeObjects<TActions, TNextActions>>>): SigmaType<TState, TEvents, TDefaults, TComputeds, TQueries, MergeObjects<TActions, TNextActions>, TSetupArgs>;
+  /**
+   * 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<TNextSetupArgs extends ([TSetupArgs] extends [never] ? any[] : NonNullable<TSetupArgs>)>(setup: (this: SetupContext<{
     state: TState;
     events: TEvents;
@@ -224,21 +278,32 @@ type TypedEventListener<TEventMap, TEvent extends string, TCurrentTarget extends
 }) => void) & {
   __eventType?: string extends TEvent ? keyof TEventMap : TEvent;
 };
-/** Infers the supported event names for a listener target. */
+/** Infers the event names accepted by `listen(...)` or `useListener(...)` for a target. */
 type InferEventType<TTarget extends EventTarget> = (InferListener<TTarget> extends {
   __eventType?: infer TEvent;
 } ? string & TEvent : never) | (string & {});
-/** Infers the listener function signature for a target and event name. */
+/** Infers the listener callback shape for a target and event name. Sigma states receive payloads directly, while DOM targets receive typed events. */
 type InferListener<TTarget extends EventTarget, TEvent extends string = string> = TTarget extends AnySigmaStateWithEvents<infer TEvents> ? TEvent extends keyof TEvents ? (event: TEvents[TEvent]) => void : never : TTarget extends Window ? TypedEventListener<WindowEventMap, TEvent, TTarget> : TTarget extends Document ? TypedEventListener<DocumentEventMap, TEvent, TTarget> : TTarget extends HTMLBodyElement ? TypedEventListener<HTMLBodyElementEventMap, TEvent, TTarget> : TTarget extends HTMLMediaElement ? TypedEventListener<HTMLMediaElementEventMap, TEvent, TTarget> : TTarget extends HTMLElement ? TypedEventListener<HTMLElementEventMap, TEvent, TTarget> : TTarget extends SVGSVGElement ? TypedEventListener<SVGSVGElementEventMap, TEvent, TTarget> : TTarget extends SVGElement ? TypedEventListener<SVGElementEventMap, TEvent, TTarget> : (event: Event & {
   readonly currentTarget: TTarget;
 }) => void;
-/** Adds an event listener and returns a cleanup function that removes it. */
+/** Adds a listener to a sigma state or DOM target and returns a cleanup function that removes it. */
 declare function listen<TTarget extends EventTarget, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, fn: InferListener<TTarget, TEvent>): () => void;
 //#endregion
 //#region src/hooks.d.ts
-/** Creates one sigma-state instance for a component and manages its setup cleanup. */
+/**
+ * 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.
+ */
 declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?: InferSetupArgs<T>): T;
-/** Attaches an event listener in a component and cleans it up when dependencies change. */
+/**
+ * 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 EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
 export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/dist/index.mjs

@@ -198,7 +198,7 @@ function getSigmaInternals(context) {
 function isAutoFreeze() {
 	return autoFreezeEnabled;
 }
-/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled. */
+/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled and the setting is shared across instances. */
 function setAutoFreeze(autoFreeze) {
 	autoFreezeEnabled = autoFreeze;
 	immer.setAutoFreeze(autoFreeze);
@@ -446,8 +446,9 @@ function publishState(instance, finalized) {
 * Returns a shallow snapshot of an instance's committed public state.
 *
 * The snapshot includes one own property for each top-level state key and reads
-* the current committed value for that key. Its type is inferred from the
-* instance's sigma-state definition.
+* the current committed value for that key. Nested sigma states remain as
+* referenced values. Its type is inferred from the instance's sigma-state
+* definition.
 */
 function snapshot(publicInstance) {
 	return snapshotState(getSigmaInternals(publicInstance));
@@ -456,8 +457,9 @@ function snapshot(publicInstance) {
 * Replaces an instance's committed public state from a snapshot object.
 *
 * The replacement snapshot must be a plain object with exactly the instance's
-* top-level state keys. Its type is inferred from the instance's sigma-state
-* definition.
+* top-level state keys. It updates committed state outside action semantics and
+* notifies observers when the committed state changes. Its type is inferred
+* from the instance's sigma-state definition.
 */
 function replaceState(publicInstance, nextState) {
 	const instance = getSigmaInternals(publicInstance);
@@ -537,17 +539,26 @@ var Sigma = class extends EventTarget {
 Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 //#endregion
 //#region src/framework.ts
-/** Checks whether a value is a sigma-state instance. */
+/** Checks whether a value is an instance created by a configured sigma type. */
 function isSigmaState(value) {
 	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
 }
-/** Creates a standalone tracked query function with the same signature as `fn`. */
+/**
+* Creates a standalone tracked query helper with the same signature as `fn`.
+*
+* 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.
+*/
 function query(fn) {
 	return ((...args) => computed$1(() => fn(...args)).value);
 }
 /**
-* Builds sigma-state constructors by accumulating default state, computeds, queries,
-* observers, actions, and setup handlers.
+* Builds sigma-state constructors by accumulating default state, computeds,
+* queries, observers, 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 extends Function {
 	constructor(name = "Sigma") {
@@ -618,7 +629,7 @@ var SigmaType = class extends Function {
 };
 //#endregion
 //#region src/listener.ts
-/** Adds an event listener and returns a cleanup function that removes it. */
+/** Adds a listener to a sigma state or DOM target and returns a cleanup function that removes it. */
 function listen(target, name, fn) {
 	const listener = isSigmaState(target) ? (event) => fn(event.detail) : fn;
 	target.addEventListener(name, listener);
@@ -628,7 +639,13 @@ function listen(target, name, fn) {
 }
 //#endregion
 //#region src/hooks.ts
-/** Creates one sigma-state instance for a component and manages its setup cleanup. */
+/**
+* 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)) {
@@ -637,7 +654,12 @@ function useSigma(create, setupArgs) {
 	}
 	return sigmaState;
 }
-/** Attaches an event listener in a component and cleans it up when dependencies change. */
+/**
+* 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.
+*/
 function useListener(target, name, listener) {
 	const listenerRef = useRef(listener);
 	listenerRef.current = listener;

package/docs/context.md

@@ -0,0 +1,102 @@
+# Overview
+
+`preact-sigma` builds reusable state models from one definition. A configured `SigmaType` owns top-level state, derived reads, writes, setup handlers, and typed events. Each top-level state property is exposed as a reactive public property backed by its own Preact signal, while actions use Immer-style mutation semantics to publish committed state.
+
+# When to Use
+
+- State, derived reads, mutations, and lifecycle need to stay together.
+- You need multiple instances of the same model.
+- Public reads should stay reactive and readonly while writes stay explicit.
+- A model needs to own timers, subscriptions, listeners, nested setup, or other cleanup-aware resources.
+- Components should consume the same model shape used outside Preact.
+
+# When Not to Use
+
+- A few plain signals already cover the state without extra coordination.
+- You want side effects to start implicitly during construction.
+- The main problem is remote caching, normalization, or cross-app store tooling rather than local state behavior.
+- You need ad hoc mutable objects with no benefit from typed actions, setup, or signal-backed reads.
+
+# Core Abstractions
+
+- Sigma type: the builder returned by `new SigmaType<TState, TEvents>()`. After configuration, it is also the constructor for instances.
+- Sigma state: an instance created from a configured sigma type.
+- State property: a top-level key from `TState`. Each one becomes a readonly reactive public property and gets its own signal.
+- Computed: an argument-free derived getter declared with `.computed(...)`.
+- Query: a reactive read that accepts arguments, declared with `.queries(...)` or built locally with `query(fn)`.
+- Action: a method declared with `.actions(...)` that reads and writes through sigma's draft and commit semantics.
+- Setup handler: a function declared with `.setup(...)` that owns side effects and cleanup resources explicitly.
+- Event: a typed notification emitted through `this.emit(...)` and observed through `.on(...)`, `listen(...)`, or `useListener(...)`.
+
+# Data Flow / Lifecycle
+
+1. Define a sigma type with `new SigmaType<TState, TEvents>()`. Let later builder methods infer names and types from the objects you pass to them.
+2. Add `defaultState(...)` for top-level public state and optional per-instance initializers.
+3. Add `computed(...)`, `queries(...)`, and `actions(...)` for derived reads and writes.
+4. Instantiate the configured type. Constructor input shallowly overrides `defaultState(...)`.
+5. Read state, computeds, and queries reactively from the public instance.
+6. Mutate state inside actions. Sync nested actions on the same instance share one draft. Boundaries like `await`, `emit(...)`, or separate action invocations may require `this.commit()` before the boundary.
+7. Run `setup(...)` explicitly when the instance should start owning side effects. `useSigma(...)` does this automatically for component-owned instances that define setup.
+8. Dispose the cleanup returned from `setup(...)` when the owned resources should stop.
+
+# Common Tasks -> Recommended APIs
+
+- Define reusable model state: `new SigmaType<TState, TEvents>().defaultState(...)`
+- Derive an argument-free value: `.computed(...)`
+- Derive a reactive read with arguments: `.queries(...)`
+- Keep a tracked helper local to one consumer module: `query(fn)`
+- Mutate state and emit typed notifications: `.actions(...)`
+- Publish before `await`, `emit(...)`, or another action boundary: `this.commit()`
+- React to committed state changes: `.observe(...)`
+- Own timers, listeners, subscriptions, or nested setup: `.setup(...)`
+- Use a sigma state inside a component: `useSigma(...)`
+- Subscribe to sigma or DOM events in a component: `useListener(...)`
+- Subscribe outside components: `.on(...)` or `listen(...)`
+- Read or restore committed top-level state: `snapshot(...)` and `replaceState(...)`
+
+# Practical Guidelines
+
+- Put explicit type arguments on `new SigmaType<TState, TEvents>()` and let later builder methods infer from the objects you pass.
+- Keep frequently read values as separate top-level state properties. Each top-level key gets its own signal.
+- Use `.computed(...)` for argument-free derived reads.
+- Use `.queries(...)` for tracked reads with arguments.
+- Keep one-off calculations local until they become reusable model behavior.
+- Reach for `instance.get(key)` only when code specifically needs the underlying `ReadonlySignal`.
+- Treat `emit(...)`, `await`, and any action call other than a same-instance synchronous nested action call as draft boundaries. Call `this.commit()` only when pending changes need to become public before one of those boundaries.
+- Use ordinary actions for routine writes. Reserve `snapshot(...)` and `replaceState(...)` for replay, reset, or undo-like flows on committed top-level state.
+- Put owned side effects in `.setup(...)`.
+- Use `this.act(function () { ... })` for setup-owned callbacks that need action semantics.
+- Call Immer's `enablePatches()` before relying on `.observe(..., { patches: true })`.
+
+# Invariants and Constraints
+
+- Sigma only tracks top-level state properties. Each top-level key gets its own signal.
+- Public state is readonly outside actions and `this.act(...)` inside setup.
+- Duplicate names across state properties, computeds, queries, and actions are rejected at runtime. Reserved public names include `act`, `emit`, `get`, `on`, and `setup`.
+- Query calls are reactive at the call site but do not memoize across invocations.
+- Setup handlers return arrays of cleanup resources, and cleanup runs in reverse order.
+- `replaceState(...)` works on committed top-level state and requires the exact state-key shape.
+- Published draftable public state is deep-frozen by default. `setAutoFreeze(false)` disables that behavior globally.
+
+# Error Model
+
+- Crossing an action boundary with unpublished changes throws until `this.commit()` publishes them. Async actions also reject when they finish with unpublished changes.
+- If another invocation crosses a boundary while unpublished changes still exist, sigma warns and discards those changes before continuing.
+- Calling `setup(...)` on a sigma state without registered setup handlers throws.
+- Cleanup rethrows an `AggregateError` when more than one cleanup resource fails.
+- `replaceState(...)` throws when the replacement value is not a plain object, has the wrong top-level keys, or runs while an action still owns unpublished changes.
+
+# Terminology
+
+- Draft boundary: a point where sigma cannot keep reusing the current unpublished draft.
+- Committed state: the published top-level public state visible outside the current action draft.
+- Signal access: reading the underlying `ReadonlySignal` for a top-level state key or computed through `instance.get(key)`.
+- Cleanup resource: a cleanup function, `AbortController`, object with `dispose()`, or object with `[Symbol.dispose]()`.
+- Nested sigma state: a sigma-state instance stored in top-level state as a value; it stays usable as a value rather than exposing its internals through parent actions.
+
+# Non-Goals
+
+- Replacing every plain-signal use case with a builder abstraction.
+- Hiding lifecycle behind implicit setup or constructor side effects.
+- Memoizing every query call or turning queries into a global cache.
+- Acting as a large tutorial framework or hand-maintained API reference. Exact signatures come from declaration output, and factual behavior lives beside source.

package/examples/async-commit.ts

@@ -0,0 +1,42 @@
+import { SigmaType } from "preact-sigma";
+
+const SaveIndicator = new SigmaType<
+  {
+    savedCount: number;
+    saving: boolean;
+  },
+  {
+    saved: {
+      count: number;
+    };
+  }
+>("SaveIndicator")
+  .defaultState({
+    savedCount: 0,
+    saving: false,
+  })
+  .actions({
+    async save() {
+      this.saving = true;
+      this.commit(); // Publish before the async boundary.
+
+      await Promise.resolve();
+
+      this.savedCount += 1;
+      this.saving = false;
+      this.commit(); // Publish before emitting the event boundary.
+
+      this.emit("saved", { count: this.savedCount });
+    },
+  });
+
+const indicator = new SaveIndicator();
+
+indicator.on("saved", ({ count }) => {
+  console.log(`Saved ${count} times`);
+});
+
+await indicator.save();
+
+console.log(indicator.saving); // false
+console.log(indicator.savedCount); // 1