preact-sigma 5.0.0 → 6.0.0

package/dist/sigma-DD7HfTvw.d.mts

@@ -0,0 +1,162 @@
+import { ReadonlySignal } from "@preact/signals";
+import { Patch } from "immer";
+
+//#region src/internal/utils.d.ts
+type AnyFunction = (...args: any[]) => any;
+type Cleanup = () => void;
+type AnyResource = Cleanup | {
+  dispose(): void;
+} | {
+  [Symbol.dispose](): void;
+};
+//#endregion
+//#region src/internal/listener.d.ts
+/** Untyped listener shape stored internally by `SigmaListenerMap`. */
+type RawSigmaListener = (detail: unknown) => void;
+/** Listener registry used by sigma targets and sigma states for typed event delivery. */
+declare class SigmaListenerMap extends Map<string, Set<RawSigmaListener>> {
+  /** Delivers one event payload to the current listeners for `name`. */
+  emit(name: string, detail: unknown): void;
+  /** Adds one listener for `name`, creating the listener set on first use. */
+  addListener(name: string, listener: RawSigmaListener): void;
+  /** Removes one listener for `name` and prunes the empty listener set. */
+  removeListener(name: string, listener: RawSigmaListener): void;
+}
+/** Infers the detail parameter for a typed emit. */
+type EventParameters<T> = [void] extends [T] ? [detail?: T extends void ? undefined : T] : [undefined] extends [T] ? [detail?: T] : [detail: T];
+//#endregion
+//#region src/internal/symbols.d.ts
+declare const instanceSymbol: unique symbol;
+declare const listenersSymbol: unique symbol;
+declare const refSymbol: unique symbol;
+declare const snapshotSymbol: unique symbol;
+declare const typeSymbol: unique symbol;
+//#endregion
+//#region src/immer.d.ts
+type PrimitiveType = number | string | boolean;
+/** Object types that should never be mapped */
+type AtomicObject = AbortController | Date | EventTarget | Function | Promise<any> | RegExp | Sigma<any>;
+/**
+ * If the lib "ES2015.Collection" is not included in tsconfig.json,
+ * types like ReadonlyArray, WeakMap etc. fall back to `any` (specified nowhere)
+ * or `{}` (from the node types), in both cases entering an infinite recursion in
+ * pattern matching type mappings
+ * This type can be used to cast these types to `void` in these cases.
+ */
+type IfAvailable<T, Fallback = void> = true | false extends (T extends never ? true : false) ? Fallback : keyof T extends never ? Fallback : T;
+/**
+ * These should also never be mapped but must be tested after regular Map and
+ * Set
+ */
+type WeakReferences = IfAvailable<WeakMap<any, any>> | IfAvailable<WeakSet<any>>;
+type WritableDraft<T> = T extends any[] ? number extends T["length"] ? Draft<T[number]>[] : WritableNonArrayDraft<T> : WritableNonArrayDraft<T>;
+type WritableNonArrayDraft<T> = { -readonly [K in keyof T]: T[K] extends infer V ? (V extends object ? Draft<V> : V) : never };
+/**
+ * Convert a readonly type into a mutable type, if possible.
+ *
+ * Use this instead of `immer.Draft`
+ */
+type Draft<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : keyof SigmaRef extends keyof T ? T : T extends ReadonlyMap<infer K, infer V> ? Map<Draft<K>, Draft<V>> : T extends ReadonlySet<infer V> ? Set<Draft<V>> : T extends WeakReferences ? T : T extends object ? WritableDraft<T> : T;
+/**
+ * Convert a mutable type into a readonly type.
+ *
+ * Use this instead of `immer.Immutable`
+ */
+type Immutable<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : keyof SigmaRef extends keyof T ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Immutable<K>, Immutable<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<Immutable<V>> : T extends WeakReferences ? T : T extends object ? { readonly [K in keyof T]: Immutable<T[K]> } : T;
+//#endregion
+//#region src/sigma.d.ts
+/**
+ * Configures Immer auto-freezing for values published through sigma state.
+ *
+ * Auto-freezing is enabled by default, so draftable public values are deeply frozen after publish.
+ */
+declare function setAutoFreeze(autoFreeze: boolean): void;
+/** Marks object values that should keep their reference-like type in `Draft` and `Immutable` mappings. */
+type SigmaRef<T extends object = {}> = T & {
+  [refSymbol]?: true;
+};
+/** Definition shape used by helper types that need both state and event maps. */
+type SigmaDefinition = {
+  state: object;
+  events?: object;
+};
+/** Instance type for a sigma definition with state typing preserved for public helpers. */
+type SigmaState<T extends SigmaDefinition> = Sigma<T["state"]> & {
+  [typeSymbol]: T;
+};
+/**
+ * Base class for signal-backed state models.
+ *
+ * `TState` is the source of typing for top-level state keys, subscriptions, signals, and replacement snapshots.
+ * Merge a same-named interface with the class when direct property reads should be typed on the instance.
+ */
+declare abstract class Sigma<TState extends object> {
+  [typeSymbol]: {
+    state: TState;
+    events: unknown;
+  };
+  [snapshotSymbol]: Record<string, unknown> | undefined;
+  protected get [instanceSymbol](): this;
+  constructor(initialState: TState);
+  /** Optional setup hook that owns side effects and returns cleanup resources. */
+  onSetup?(...args: any[]): readonly AnyResource[];
+  /** Runs `onSetup(...)` and returns a cleanup that disposes returned resources in reverse order. */
+  setup(...args: Parameters<Extract<this["onSetup"], AnyFunction>>): () => void;
+  /**
+   * Publishes the current action draft.
+   *
+   * Use this before unpublished changes cross an async, event, or external-action boundary.
+   * A callback runs after publish in an action context.
+   */
+  commit<T = void>(callback?: (this: typeof this) => T): T | undefined;
+  /** Runs a synchronous setup-owned callback with action semantics from an `onSetup(...)` context. */
+  act(fn: (this: typeof this) => void): void;
+}
+/** Casts a sigma instance to its readonly public consumer view. */
+declare function castProtected<T extends Sigma<any>>(instance: T): Protected<T>;
+/**
+ * Sigma state model that can emit typed events.
+ *
+ * `TEvents` maps event names to payload types, and `TState` types reactive state.
+ */
+declare class SigmaTarget<TEvents extends object = {}, TState extends object = {}> extends Sigma<TState> {
+  [typeSymbol]: {
+    state: TState;
+    events: TEvents;
+  };
+  protected [listenersSymbol]: SigmaListenerMap;
+  constructor(state?: TState);
+  /** Emits a typed event from an action after unpublished draft changes are committed. */
+  emit<TEvent extends string & keyof TEvents>(name: TEvent, ...[detail]: EventParameters<TEvents[TEvent]>): void;
+}
+/** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
+declare const sigma: Readonly<{
+  /** Subscribes to committed state publishes or to one signal-backed top-level state key. */subscribe: {
+    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[], inversePatches: Patch[]) => void, options: {
+      patches: true;
+    }): Cleanup;
+    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[] | undefined, inversePatches: Patch[] | undefined) => void, options: {
+      patches: boolean;
+    }): Cleanup;
+    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>) => void): Cleanup;
+    <TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
+  }; /** Returns the readonly signal backing one top-level state key. */
+  getSignal<TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey): ReadonlySignal<Immutable<TState[TKey]>>; /** Captures the current committed top-level state snapshot. */
+  captureState<TState extends object>(instance: Sigma<TState>): Immutable<TState>; /** Publishes a plain-object snapshot as the current committed state. */
+  replaceState<TState extends object>(target: Sigma<TState>, nextState: TState): void;
+}>;
+/** Marks a class method as a committed-state reactive read with arguments instead of an action. */
+declare function query<TThis extends object, TArgs extends any[], TReturn>(method: (this: TThis, ...args: TArgs) => TReturn): (this: TThis, ...args: TArgs) => TReturn;
+declare const protectedSymbol: unique symbol;
+type ProtectedKey = typeof listenersSymbol | typeof snapshotSymbol | "act" | "commit" | "emit" | "onSetup";
+type BrandProtected<T> = T & {
+  [protectedSymbol]: true;
+};
+/** Readonly public view returned by `castProtected(...)` and `useSigma(...)`. */
+type Protected<T extends Sigma<any>> = BrandProtected<T extends {
+  [typeSymbol]: {
+    state: infer TState extends object;
+  };
+} ? { [K in keyof T as K extends ProtectedKey ? never : K]: K extends typeof typeSymbol ? T[K] : K extends keyof TState ? Immutable<T[K]> : T[K] extends AnyFunction ? (...params: Parameters<T[K]>) => Immutable<ReturnType<T[K]>> : Immutable<T[K]> } : never>;
+//#endregion
+export { SigmaState as a, query as c, Draft as d, Immutable as f, SigmaRef as i, setAutoFreeze as l, Cleanup as m, Sigma as n, SigmaTarget as o, typeSymbol as p, SigmaDefinition as r, castProtected as s, Protected as t, sigma as u };

package/docs/context.md

@@ -1,12 +1,12 @@
 # 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. For event-only flows, `SigmaTarget` provides a standalone typed event hub with no managed state.
+`preact-sigma` builds reusable state models as TypeScript classes. A `Sigma<TState>` subclass owns top-level state, derived reads, writes, and setup. A `SigmaTarget<TEvents, TState>` subclass adds typed events. Each top-level state key is exposed as a reactive public property backed by a 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.
+- You need multiple instances of the same model class.
+- Public reads should stay reactive 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.
 
@@ -19,105 +19,112 @@
 
 # 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.
-- Sigma target: a standalone typed event hub created with `new SigmaTarget<TEvents>()` when you need typed events without managed state.
-- 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 `listen(...)` or `useListener(...)`.
+- Sigma class: a class that extends `Sigma<TState>` and passes its initial top-level state to `super(...)`. The `TState` argument drives helper typing for subscriptions, signals, and replacement snapshots; a same-named merged interface gives direct property reads their instance types.
+- Sigma target: a class that extends `SigmaTarget<TEvents, TState>` when it also emits typed events. Use `SigmaTarget<TEvents>` for event-only targets.
+- State property: a top-level key from `TState`. Each key becomes a reactive public property and has its own signal.
+- Computed: an argument-free derived getter on the class prototype that reads committed state.
+- Query: a reactive read method that accepts arguments, is marked with the `query` decorator, and reads committed state.
+- Action: a prototype method that is not marked as a query. Actions read and write state properties through sigma's draft and commit semantics.
+- Setup handler: an optional `onSetup(...)` method that owns side effects and returns cleanup resources.
+- Event: a typed notification emitted with `this.emit(...)` inside an action and observed through `listen(...)` or `useListener(...)`.
+- Protected view: the readonly consumer view returned by `castProtected(...)` and `useSigma(...)`.
 
 # 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(...)`.
+1. Define a class that extends `Sigma<TState>` or `SigmaTarget<TEvents, TState>`.
+2. Define the state as a named type, pass it to `Sigma<TState>`, then merge `interface Model extends ModelState {}` after the class so direct property reads are typed.
+3. Add getters for computed values, `@query` methods for argument-based reactive reads, and ordinary methods for actions.
+4. Instantiate the class. Constructor input can be merged with defaults before `super(...)` when instances need partial overrides.
 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.
+6. Mutate state inside actions. Synchronous actions publish automatically when they return, and sync nested actions on the same instance share one draft. Computeds and queries still read the last committed state while an action has unpublished draft changes. Call `this.commit()` when derived reads or unpublished changes must cross a boundary, such as before an `await`, before the action promise resolves, before `emit(...)`, or before invoking another instance's action.
+7. Run `setup(...)` explicitly when the instance should start owning side effects. `useSigma(...)` does this automatically for component-owned instances that define `onSetup(...)`.
 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: `sigma.subscribe(instance, handler)` or `sigma.subscribe(instance, key, handler)`
-- Read one top-level state property or computed as a `ReadonlySignal`: `sigma.getSignal(instance, key)`
-- 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(...)`
-- Create a standalone typed event hub with no managed state: `new SigmaTarget<TEvents>()`, `hub.emit(...)`, and `listen(hub, ...)`
-- Subscribe outside components: `listen(instance, ...)`
-- Read or restore committed top-level state: `sigma.getState(...)` and `sigma.replaceState(...)`
+- Define reusable model state: `class Model extends Sigma<TState>`.
+- Define reusable model state with events: `class Model extends SigmaTarget<TEvents, TState>`.
+- Merge partial constructor input with defaults: `mergeDefaults(initial, defaults)`.
+- Derive an argument-free value: a class getter.
+- Derive a reactive read with arguments: an `@query` class method.
+- Mutate state and emit typed notifications: ordinary class methods plus `this.emit(...)`.
+- Publish unpublished changes before `await`, `emit(...)`, promise resolution, or another instance's action: `this.commit()`.
+- React to committed state changes: `sigma.subscribe(instance, handler)` or `sigma.subscribe(instance, key, handler)`.
+- Read one top-level state property as a `ReadonlySignal`: `sigma.getSignal(instance, key)`.
+- Own timers, listeners, subscriptions, or nested setup: `onSetup(...)` plus `setup(...)`.
+- Use a sigma instance inside a component: `useSigma(...)`.
+- Cast an instance to its readonly consumer view outside a component: `castProtected(instance)`.
+- Subscribe to sigma or DOM events in a component: `useListener(...)`.
+- Subscribe outside components: `listen(instance, ...)`.
+- Read or restore committed top-level state: `sigma.captureState(...)` and `sigma.replaceState(...)`.
 
 # Recommended Patterns
 
-- Put explicit type arguments on `new SigmaType<TState, TEvents>()` and let later builder methods infer from the objects you pass.
+- Put the state shape in a named `State` type, pass it to `Sigma<TState>` or `SigmaTarget<TEvents, TState>`, then merge a same-named interface with the class for direct property typing.
 - 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.
-- Use ordinary actions for routine writes. Reserve `sigma.getState(...)` and `sigma.replaceState(...)` for replay, reset, or undo-like flows on committed top-level state.
-- Prefer `listen(...)` for external event subscriptions. It works with sigma states, `SigmaTarget`, and DOM targets.
-- Put owned side effects in `.setup(...)`.
-- Use `sigma.subscribe(this, ...)` inside `.setup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
+- Use getters for argument-free derived reads.
+- Use `@query` for tracked reads with arguments.
+- Derive directly from state properties inside an action when the calculation needs unpublished draft values.
+- Use ordinary actions for routine writes. Reserve `sigma.captureState(...)` and `sigma.replaceState(...)` for replay, reset, restore, or undo-like flows on committed top-level state.
+- Emit directly from actions that have no unpublished draft changes. After mutating state, publish first with `this.commit(); this.emit(...)`.
+- Prefer `listen(...)` for external event subscriptions. It works with sigma targets and DOM targets.
+- Put owned side effects in `onSetup(...)`.
+- Use `sigma.subscribe(this, ...)` inside `onSetup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
   ```ts
-  .setup(function () {
+  onSetup() {
     return [
-      sigma.subscribe(this, (change) => {
-        console.log(change.newState);
+      sigma.subscribe(this, (nextState, baseState) => {
+        console.log(baseState, nextState);
       }),
     ];
-  })
+  }
   ```
 - Use `this.act(function () { ... })` for setup-owned callbacks that need action semantics.
 
 # Patterns to Avoid
 
 - Reaching for `sigma.getSignal(instance, key)` when direct property reads already cover the use case.
-- Crossing `emit(...)`, `await`, or another action boundary with unpublished changes when those changes need to stay visible afterward. Publish them first with `this.commit()`.
+- Crossing `emit(...)`, `await`, promise resolution, or another instance's action with unpublished changes. Publish them first with `this.commit()`.
 - Starting side effects during construction instead of through explicit `setup(...)`.
-- Encoding storage, hydration, or migration policy directly into `SigmaType` definitions.
+- Encoding storage, hydration, or migration policy directly into model classes.
+- Relying on computeds or queries to observe unpublished draft changes inside actions.
 - Treating query calls as memoized across invocations.
 - Relying on patch payloads without enabling Immer patches first.
 
 # 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`, `commit`, `emit`, and `setup`.
+- Sigma tracks top-level state properties. Each top-level key gets its own signal.
+- Protected consumer views expose immutable state and callable actions.
+- Published draftable public state is deep-frozen by default. `setAutoFreeze(false)` disables that behavior globally.
+- Computeds and queries read committed state, including when called inside actions.
 - 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.
 - Call Immer's `enablePatches()` before relying on `sigma.subscribe(instance, handler, { patches: true })`.
-- `sigma.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.
+- `sigma.replaceState(...)` works on committed top-level state and requires a plain object snapshot.
+- `SigmaTarget.emit(...)` runs from an action and requires no active unpublished draft. It does not need a `commit(...)` callback.
 
 # 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.
-- `sigma.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.
+- Calling `commit(...)` outside an action throws.
+- Calling `act(...)` outside an `onSetup(...)` setup context throws.
+- Calling `emit(...)` outside an action or before committing the active draft throws.
+- Calling an action from a computed or query throws.
+- Returning an active draft from an action throws.
+- `sigma.replaceState(...)` throws when the replacement value is not a plain object or when an action still owns unpublished changes.
+- Starting an action on another sigma instance while the current instance has an active action context throws.
 
 # 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 `sigma.getSignal(instance, key)`.
-- Cleanup resource: a cleanup function, `AbortController`, object with `dispose()`, or object with `[Symbol.dispose]()`.
+- Signal access: reading the underlying `ReadonlySignal` for a top-level state key through `sigma.getSignal(instance, key)`.
+- Cleanup resource: a cleanup function, 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.
+- Replacing every plain-signal use case with a class 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/docs/migrations/v5-to-v6.md

@@ -0,0 +1,273 @@
+# Migrating from v5 to v6
+
+v6 replaces the `SigmaType` builder with class-based models. The runtime contract is still centered on top-level reactive state, derived reads, explicit actions, setup-owned side effects, typed events, and committed snapshots.
+
+## Model Definitions
+
+Define a class that extends `Sigma<TState>` instead of building a configured `SigmaType`.
+
+Before:
+
+```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;
+    },
+  });
+```
+
+After:
+
+```ts
+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 {}
+```
+
+`TState` drives helper typing for subscriptions, signals, and replacement snapshots. The same-named merged interface gives direct state property reads their instance types.
+
+## Constructor Defaults
+
+Constructor input is ordinary TypeScript now. Use `mergeDefaults(...)` when an instance accepts partial initial state.
+
+```ts
+import { mergeDefaults, Sigma } from "preact-sigma";
+
+type SearchState = {
+  draft: string;
+  page: number;
+};
+
+class Search extends Sigma<SearchState> {
+  static defaultState: SearchState = {
+    draft: "",
+    page: 1,
+  };
+
+  constructor(initialState?: Partial<SearchState>) {
+    super(mergeDefaults(initialState, Search.defaultState));
+  }
+}
+
+interface Search extends SearchState {}
+```
+
+## Computeds, Queries, and Actions
+
+Use class getters for argument-free computed reads. Use ordinary prototype methods for actions. Computeds and queries read committed state, including when called inside actions.
+
+Argument-based reactive reads are class methods marked with `@query`.
+
+```ts
+import { query, Sigma } from "preact-sigma";
+
+type TodoListState = {
+  draft: string;
+};
+
+class TodoList extends Sigma<TodoListState> {
+  constructor() {
+    super({ draft: "" });
+  }
+
+  @query
+  canAdd(minLength: number) {
+    return this.draft.trim().length >= minLength;
+  }
+
+  setDraft(draft: string) {
+    this.draft = draft;
+  }
+}
+
+interface TodoList extends TodoListState {}
+```
+
+## Events
+
+`SigmaTarget` now takes event types first. Use `SigmaTarget<TEvents>` for event-only targets and `SigmaTarget<TEvents, TState>` for targets that also own state.
+
+```ts
+import { listen, SigmaTarget } from "preact-sigma";
+
+type NotificationEvents = {
+  saved: {
+    id: string;
+  };
+};
+
+class Notifications extends SigmaTarget<NotificationEvents> {
+  saved(id: string) {
+    this.emit("saved", { id });
+  }
+}
+
+const notifications = new Notifications();
+
+const stop = listen(notifications, "saved", ({ id }) => {
+  console.log(id);
+});
+```
+
+`emit(...)` runs inside actions. If an action mutates state before emitting, publish first with `this.commit()`.
+
+## Commit Boundaries
+
+Synchronous actions publish automatically when they return. Call `this.commit()` only when unpublished changes cross a boundary:
+
+- before `await`
+- before an async action promise resolves
+- before `emit(...)`
+- before invoking another instance's action
+
+```ts
+type SaveIndicatorState = {
+  savedCount: number;
+  saving: boolean;
+};
+
+type SaveIndicatorEvents = {
+  saved: {
+    count: number;
+  };
+};
+
+class SaveIndicator extends SigmaTarget<SaveIndicatorEvents, SaveIndicatorState> {
+  constructor() {
+    super({
+      savedCount: 0,
+      saving: false,
+    });
+  }
+
+  async save() {
+    this.saving = true;
+    this.commit();
+
+    await Promise.resolve();
+
+    this.savedCount += 1;
+    this.saving = false;
+    this.commit();
+
+    this.emit("saved", { count: this.savedCount });
+  }
+}
+
+interface SaveIndicator extends SaveIndicatorState {}
+```
+
+## Setup
+
+Replace builder setup with an `onSetup(...)` method. Call `setup(...)` manually outside Preact, or use `useSigma(...)` for component-owned instances.
+
+```ts
+import { listen, Sigma } from "preact-sigma";
+
+type ClickTrackerState = {
+  clicks: number;
+};
+
+class ClickTracker extends Sigma<ClickTrackerState> {
+  constructor() {
+    super({ clicks: 0 });
+  }
+
+  onSetup(target: EventTarget) {
+    return [
+      listen(target, "click", () => {
+        this.act(function () {
+          this.clicks += 1;
+        });
+      }),
+    ];
+  }
+}
+
+interface ClickTracker extends ClickTrackerState {}
+```
+
+## Protected Views
+
+The instance method `protect()` is gone. Use `castProtected(instance)` outside components, and use `useSigma(...)` inside components.
+
+```ts
+import { castProtected } from "preact-sigma";
+
+const publicCounter = castProtected(new Counter());
+```
+
+Protected sigma targets keep their event metadata, so `useListener(...)` works directly with the value returned by `useSigma(...)`.
+
+```tsx
+const palette = useSigma(() => new CommandPalette());
+
+useListener(palette, "ran", (command) => {
+  console.log(command.title);
+});
+```
+
+## Committed State Helpers
+
+Replace `sigma.getState(...)` with `sigma.captureState(...)`.
+
+```ts
+const saved = sigma.captureState(todoList);
+
+todoList.add("Ship release");
+sigma.replaceState(todoList, saved);
+```
+
+Use `sigma.subscribe(instance, listener)` for committed state publishes and `sigma.subscribe(instance, key, listener)` for one top-level state key.
+
+## Persistence
+
+The `preact-sigma/persist` helpers are named around restore, persist, and hydrate flows:
+
+- `restore(instance, options)`
+- `restoreSync(instance, options)`
+- `persist(instance, options)`
+- `hydrate(instance, options)`
+- `hydrateSync(instance, options)`
+
+Use `pick: ["key"]` options for selected top-level state keys instead of a separate pick codec helper.
+
+See [`../persist.md`](../persist.md) for persistence-specific guidance.
+
+## More References
+
+- [`../context.md`](../context.md): concepts, lifecycle, invariants, and API selection
+- [`../../examples/basic-counter.ts`](../../examples/basic-counter.ts): minimal class model
+- [`../../examples/command-palette.tsx`](../../examples/command-palette.tsx): component usage, setup, events, nested state, and custom helper objects
+- `dist/index.d.mts` and `dist/persist.d.mts` after `pnpm build`: exact exported signatures