preact-sigma 2.2.2 → 2.2.3

package/README.md

@@ -1,56 +1,21 @@
 # preact-sigma
 
-`preact-sigma` lets you define state once and reuse it as a model.
+## Purpose
 
-It is built for Preact and TypeScript, and combines:
+`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.
 
-- fine-grained reactive reads
-- Immer-style writes
-- explicit setup and cleanup
-- typed events
-- a constructor you can instantiate anywhere
-
-Use it when your state has started to feel like more than "some values in a component."
-
-Instead of spreading logic across loose signals, reducers, effects, and cleanup code, you define one model with:
-
-- top-level state
-- derived reads
-- write methods
-- side-effect setup
-- optional events
-
-Then you create instances wherever they make sense: inside a component, in a shared module, or in plain TypeScript.
-
-Under the hood, each top-level state property is backed by its own Preact signal, while writes happen through actions with Immer-backed mutation semantics.
-
-## Why you would use it
-
-`preact-sigma` is a good fit when you want state and behavior to live together.
-
-It is especially useful when you need to:
-
-- keep state, derived values, mutations, and lifecycle in one place
-- create multiple instances of the same state model
-- expose readonly public state while keeping writes explicit
-- get fine-grained reactivity without wiring together a pile of loose signals
-- own timers, subscriptions, listeners, or nested setup with clear cleanup
-
-If a couple of plain signals are enough, use plain signals.  
-`preact-sigma` is for the point where state starts acting like a small system.
-
-## Install
+## Installation
 
 ```bash
 npm install preact-sigma
 ```
 
-## 30-second example
+## Quick Example
 
 ```ts
 import { SigmaType } from "preact-sigma";
 
-const Counter = new SigmaType<{ count: number }>()
+const Counter = new SigmaType<{ count: number }>("Counter")
   .defaultState({
     count: 0,
   })
@@ -73,255 +38,10 @@ console.log(counter.count); // 1
 console.log(counter.doubled); // 2
 ```
 
-That example shows the basic shape:
-
-- state is public and reactive
-- derived values live in `computed(...)`
-- writes happen in `actions(...)`
-- an instance behaves like a small stateful object
-
-## The mental model
-
-A sigma model is made from a few simple pieces.
-
-### `defaultState(...)`
-
-Defines the top-level state for each instance.
-
-Each top-level property becomes a reactive public property on the instance.
-
-Use plain values for simple defaults, or zero-argument functions when each instance needs a fresh object or array.
-
-### `computed(...)`
-
-Use computeds for derived values that take no arguments.
-
-They behave like tracked getters:
-
-```ts
-.completedCount() // no
-todoList.completedCount // yes
-```
-
-### `queries(...)`
-
-Use queries for reactive reads that need arguments.
-
-```ts
-visibleTodos("open");
-```
-
-Queries are for reading, not writing.
-
-### `actions(...)`
-
-Actions are where state changes happen.
-
-Outside an action, public state is readonly. Inside an action, you write with normal mutation syntax and sigma handles the draft/update flow for you.
-
-```ts
-.actions({
-  rename(title: string) {
-    this.title = title;
-  },
-})
-```
-
-### `setup(...)`
-
-Setup is where side effects belong.
-
-Use it for things like:
-
-- timers
-- event listeners
-- subscriptions
-- nested model setup
-- storage sync
-
-Setup is explicit. A new instance does not automatically run setup. When setup does run, it returns one cleanup function that tears down everything that instance owns.
-
-### Events
-
-Use events when the model needs to notify the outside world without exposing mutable internals.
-
-Emit inside actions or setup:
-
-```ts
-this.emit("saved", { count: 3 });
-```
-
-Listen from the outside:
-
-```ts
-const stop = instance.on("saved", ({ count }) => {
-  console.log(count);
-});
-```
-
-## A more realistic example
-
-```ts
-import { 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 } }
->()
-  .defaultState({
-    draft: "",
-    todos: [],
-    saving: false,
-  })
-  .computed({
-    remainingCount() {
-      return this.todos.filter((todo) => !todo.done).length;
-    },
-  })
-  .queries({
-    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({
-    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 "saving" before awaiting
-
-      await fetch("/api/todos", {
-        method: "POST",
-        body: JSON.stringify(this.todos),
-      });
-
-      this.saving = false;
-      this.commit(); // publish before emitting
-      this.emit("saved", { count: this.todos.length });
-    },
-  })
-  .setup(function (storageKey: string) {
-    const interval = window.setInterval(() => {
-      localStorage.setItem(storageKey, JSON.stringify(this.todos));
-    }, 1000);
-
-    return [() => window.clearInterval(interval)];
-  });
-
-const todoList = new TodoList();
-const cleanup = todoList.setup("todos-demo");
-
-const stop = todoList.on("saved", ({ count }) => {
-  console.log(`Saved ${count} todos`);
-});
-
-todoList.setDraft("Rewrite the README");
-todoList.addTodo();
-
-console.log(todoList.remainingCount);
-console.log(todoList.visibleTodos("open"));
-
-await todoList.save();
-
-stop();
-cleanup();
-```
-
-## The one rule to remember about actions
-
-For normal synchronous actions, mutate state and return. You usually do **not** need `this.commit()`.
-
-Use `this.commit()` when you have unpublished changes and the action is about to cross a boundary like:
-
-- `await`
-- `emit(...)`
-- another action boundary that should not keep using the current draft
-
-In practice, that means:
-
-- sync action with no boundary: mutate and return
-- async action before `await`: `commit()` if you want those changes published first
-- action before `emit(...)`: `commit()` if there are pending changes
-
-That rule is the main thing to learn beyond the basic API.
-
-## In Preact
-
-`preact-sigma` works outside components, but it also has a nice component story.
-
-Use `useSigma(...)` when the component should own one instance:
-
-```ts
-import { useSigma } from "preact-sigma";
-
-const todoList = useSigma(() => new TodoList(), ["todos-demo"]);
-```
-
-If the model defines setup handlers, `useSigma(...)` runs setup for that component-owned instance and cleans it up automatically when setup params change or the component unmounts.
-
-Use `useListener(...)` for component-scoped event subscriptions:
-
-```ts
-import { useListener } from "preact-sigma";
-
-useListener(todoList, "saved", ({ count }) => {
-  console.log(`Saved ${count} todos`);
-});
-```
-
-## What you get out of the box
-
-Beyond the core model API, `preact-sigma` also includes:
-
-- `observe(...)` for reacting to committed state changes
-- optional Immer patch delivery in observers
-- `snapshot(...)` and `replaceState(...)` for restore/undo-like flows
-- `get(key)` when you need direct signal access for a state key or computed
-
-## Why this shape exists
-
-`preact-sigma` exists for the space between two extremes:
-
-- **too small for a big store abstraction**
-- **too stateful for a handful of loose signals**
-
-It keeps the ergonomics of working with a model object, while preserving:
-
-- readonly public reads
-- explicit write boundaries
-- fine-grained reactivity
-- explicit ownership of side effects
-
-That makes it useful for app state that has real behavior, not just values.
-
-## More docs
+## Documentation Map
 
-- [`llms.txt`](./llms.txt) contains the exhaustive API and behavior reference.
-- Companion skills are available via `npx skills add alloc/preact-sigma`.
-- The `preact-sigma` skill packages procedural guidance and agent-oriented workflow for the 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;