preact-sigma 4.0.0 → 6.0.0

package/README.md

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

package/dist/index.d.mts

@@ -1,345 +1,61 @@
-import { ReadonlySignal } from "@preact/signals";
-import { Patch } from "immer";
+import { a as SigmaState, c as query, d as Draft, f as Immutable, i as SigmaRef, l as setAutoFreeze, m as Cleanup, n as Sigma, o as SigmaTarget, p as typeSymbol, r as SigmaDefinition, s as castProtected, t as Protected, u as sigma } from "./sigma-DD7HfTvw.mjs";
 
-//#region src/internal/symbols.d.ts
-declare const signalPrefix = "#";
-declare const sigmaTypeBrand: unique symbol;
-declare const sigmaStateBrand: unique symbol;
-declare const sigmaEventsBrand: unique symbol;
-declare const sigmaRefBrand: unique symbol;
-declare const reservedKeys: Set<string>;
+//#region src/defaults.d.ts
+/**
+ * Shallowly applies defined initial values over a defaults object.
+ *
+ * `undefined` initial values leave their matching default value in place.
+ */
+declare function mergeDefaults<T extends object>(initial: Partial<T> | undefined, defaults: T): T;
 //#endregion
 //#region src/listener.d.ts
-type InferEventMap<TTarget extends EventTarget> = TTarget extends {
-  [sigmaEventsBrand]: infer TEvents extends AnyEvents;
-} ? TEvents : TTarget extends Window ? WindowEventMap : TTarget extends Document ? DocumentEventMap : TTarget extends HTMLBodyElement ? HTMLBodyElementEventMap : TTarget extends HTMLMediaElement ? HTMLMediaElementEventMap : TTarget extends HTMLElement ? HTMLElementEventMap : TTarget extends SVGSVGElement ? SVGSVGElementEventMap : TTarget extends SVGElement ? SVGElementEventMap : never;
-type InferListenerArgs<TEvents extends object, TTarget extends EventTarget, TEvent extends string> = [(TEvent extends keyof TEvents ? TEvents[TEvent] : never) extends infer TPayload ? TTarget extends {
-  [sigmaEventsBrand]: TEvents;
-} ? [TPayload] extends [never] ? never : [TPayload] extends [void] ? undefined : TPayload : ([TPayload] extends [never] ? CustomEvent : Extract<TPayload, Event>) & {
+/** Sigma targets and protected sigma target views that carry typed event metadata. */
+type SigmaListenable<TEvents extends object = any> = {
+  readonly [typeSymbol]: {
+    readonly events: TEvents;
+  };
+};
+/** Target types supported by `listen(...)` and `useListener(...)`. */
+type Listenable = SigmaListenable | EventTarget;
+type InferEventMap<TTarget extends Listenable> = TTarget extends SigmaListenable<infer TEvents> ? TEvents : TTarget extends Window ? WindowEventMap : TTarget extends Document ? DocumentEventMap : TTarget extends HTMLBodyElement ? HTMLBodyElementEventMap : TTarget extends HTMLMediaElement ? HTMLMediaElementEventMap : TTarget extends HTMLElement ? HTMLElementEventMap : TTarget extends SVGSVGElement ? SVGSVGElementEventMap : TTarget extends SVGElement ? SVGElementEventMap : TTarget extends EventTarget ? Record<string, Event> : never;
+type InferListenerArgs<TEvents extends object, TTarget extends Listenable, TEvent extends string> = [(TEvent extends keyof TEvents ? TEvents[TEvent] : never) extends infer TPayload ? TTarget extends SigmaListenable<any> ? [TPayload] extends [never] ? never : [TPayload] extends [void] ? undefined : TPayload : ([TPayload] extends [never] ? CustomEvent : Extract<TPayload, Event>) & {
   readonly currentTarget: TTarget;
 } : never];
-/** Infers the listener callback shape for a target and event name. Sigma states receive payloads directly, while DOM targets receive typed events. */
-type InferListener<TTarget extends EventTarget, TEvent extends string = string> = InferEventMap<TTarget> extends infer TEvents extends object ? ((...args: InferListenerArgs<TEvents, TTarget, TEvent>) => void) & {
+/** Infers the listener callback shape for a target and event name. Sigma targets receive payloads directly, while DOM targets receive typed events. */
+type InferListener<TTarget extends Listenable, TEvent extends string = string> = InferEventMap<TTarget> extends infer TEvents extends object ? ((...args: InferListenerArgs<TEvents, TTarget, TEvent>) => void) & {
   __eventType?: TEvent;
 } : never;
 /** Infers the event names accepted by `listen(...)` or `useListener(...)` for a target. */
-type InferEventType<TTarget extends EventTarget> = (InferListener<TTarget> extends {
+type InferEventType<TTarget extends Listenable> = (InferListener<TTarget> extends {
   __eventType?: infer TEvent;
 } ? string & TEvent : never) | (string & {});
-/** 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];
-/**
- * A standalone typed event hub with `emit(...)` and `on(...)` methods and full
- * `EventTarget`, `listen(...)`, and `useListener(...)` compatibility.
- */
-declare class SigmaTarget<TEvents extends AnyEvents = {}> extends EventTarget {
-  readonly [sigmaEventsBrand]: TEvents;
-  /**
-   * Emits a typed event from the hub.
-   *
-   * Void events dispatch a plain `Event`. Payload events dispatch a
-   * `CustomEvent` whose `detail` holds the payload.
-   */
-  emit<TEvent extends string & keyof TEvents>(name: TEvent, ...[detail]: EventParameters<TEvents[TEvent]>): void;
-  /**
-   * Registers a typed event listener and returns an unsubscribe function.
-   *
-   * Payload events pass their payload directly to the listener. Void events
-   * call the listener with no arguments.
-   */
-  on<TEvent extends string & keyof TEvents>(name: TEvent, listener: (...args: InferListenerArgs<TEvents, this, TEvent>) => void): () => void;
-}
-/** 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, listener: InferListener<TTarget, TEvent>): () => void;
+/** Adds a listener to a sigma target or DOM target and returns a cleanup function that removes it. */
+declare function listen<TTarget extends Listenable, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, listener: InferListener<TTarget, TEvent>): Cleanup;
 //#endregion
-//#region src/immer.d.ts
-type PrimitiveType = number | string | boolean;
-/** Object types that should never be mapped */
-type AtomicObject = Function | Promise<any> | Date | RegExp | EventTarget | AnySigmaState;
-/**
- * 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 HasSigmaRefBrand<T> = [T] extends [object] ? typeof sigmaRefBrand extends keyof T ? true : false : false;
-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 : HasSigmaRefBrand<T> extends true ? 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;
+//#region src/hooks/useListener.d.ts
 /**
- * Convert a mutable type into a readonly type.
+ * Attaches an event listener in a component and cleans it up automatically.
  *
- * Use this instead of `immer.Immutable`
+ * Passing `null` disables the listener. The latest callback is used without
+ * forcing the effect to resubscribe on every render.
  */
-type Immutable<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : HasSigmaRefBrand<T> extends true ? 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;
+declare function useListener<TTarget extends Listenable, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
-//#region src/internal/types.d.ts
-type Def = typeof sigmaTypeBrand;
-type AnyFunction = (...args: any[]) => any;
-type Cleanup = () => void;
-type DefaultStateInitializer<TValue> = (this: void) => TValue;
-type DefaultStateValue<TValue> = TValue | DefaultStateInitializer<TValue>;
-type Disposable = {
-  [Symbol.dispose](): void;
-};
-type DisposableLike = {
-  dispose(): void;
-};
-interface SigmaRefBrand {
-  [sigmaRefBrand]?: true;
-}
-/** A type brand that keeps a value by reference in sigma's `Draft` and `Immutable` helpers. */
-type SigmaRef<T = unknown> = T & SigmaRefBrand;
-/** The event map shape used by sigma types. */
-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(...)`, where each property may be a value or a zero-argument initializer. */
-type AnyDefaultState<TState extends object> = { [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;
-type ComputedValues<TComputeds> = { readonly [K in keyof TComputeds]: TComputeds[K] extends AnyFunction ? Immutable<ReturnType<TComputeds[K]>> : never };
-type QueryMethods<TQueries> = { [K in keyof TQueries]: TQueries[K] extends AnyFunction ? (...args: Parameters<TQueries[K]>) => ReturnType<TQueries[K]> : never };
-type ActionMethods<TActions> = { [K in keyof TActions]: TActions[K] extends AnyFunction ? (...args: Parameters<TActions[K]>) => ReturnType<TActions[K]> : never };
-type MergeObjects<TLeft, TRight, TConstraint extends object = object> = TRight extends TConstraint ? TLeft extends TConstraint ? Simplify<Omit<TLeft, keyof TRight> & TRight> : TRight : TLeft extends TConstraint ? TLeft : {};
-type Simplify<T> = {} & { [K in keyof T]: T[K] };
-type ComputedContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<Immutable<MergeObjects<T[Def]["state"], TOverrides["state"]>> & ComputedValues<MergeObjects<T[Def]["computeds"], TOverrides["computeds"]>>>;
-type ReadonlyContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<Immutable<MergeObjects<T[Def]["state"], TOverrides["state"]>> & ComputedValues<MergeObjects<T[Def]["computeds"], TOverrides["computeds"]>> & QueryMethods<MergeObjects<T[Def]["queries"], TOverrides["queries"]>>>;
-type Emit<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = MergeObjects<T[Def]["events"], TOverrides["events"], AnyEvents> extends infer TEvents ? [TEvents] extends [AnyEvents] ? <TEvent extends string & keyof TEvents>(name: TEvent, ...[detail]: EventParameters<TEvents[TEvent]>) => void : never : never;
-type ActionContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<Draft<MergeObjects<T[Def]["state"], TOverrides["state"]>> & ComputedValues<MergeObjects<T[Def]["computeds"], TOverrides["computeds"]>> & QueryMethods<MergeObjects<T[Def]["queries"], TOverrides["queries"]>> & ActionMethods<MergeObjects<T[Def]["actions"], TOverrides["actions"]>> & {
-  /** Publishes the current action draft immediately so later boundaries use committed state. */commit(): void; /** Emits a typed event from the current action. */
-  emit: Emit<T, TOverrides>;
-}>;
-type SetupContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<SigmaState<T[Def] & TOverrides> & {
-  /** Runs a synchronous anonymous action from setup so reads and writes use normal action semantics. */act<TResult>(fn: (this: ActionContext<T>) => TResult): TResult; /** Emits a typed event from setup. */
-  emit: Emit<T, TOverrides>;
-}>;
-type AnySigmaType = SigmaType<any, any, any> & {
-  readonly [sigmaTypeBrand]: {
-    state: object;
-    events?: object;
-    computeds?: object;
-    queries?: object;
-    actions?: object;
-    setupArgs?: any[];
-  };
-};
-/** The public shape shared by all sigma-state instances. */
-interface AnySigmaState extends EventTarget {
-  readonly [sigmaStateBrand]: true;
-}
-/** A sigma-state instance with a typed event map. */
-type AnySigmaStateWithEvents<TEvents extends AnyEvents> = AnySigmaState & {
-  readonly [sigmaEventsBrand]: TEvents;
-};
-/** Options accepted by `.observe(...)`. */
-type SigmaObserveOptions = {
-  /** 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> = {
-  readonly newState: Immutable<TState>;
-  readonly oldState: Immutable<TState>;
-} & (TWithPatches extends true ? {
-  readonly inversePatches: readonly Patch[];
-  readonly patches: readonly Patch[];
-} : {});
-type SigmaDefinition = {
-  state: AnyState;
-  events?: AnyEvents;
-  computeds?: object;
-  queries?: object;
-  actions?: object;
-  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 EventMethods<TEvents extends AnyEvents | undefined> = [undefined] extends [TEvents] ? never : {
-  readonly [sigmaEventsBrand]: TEvents; /** Registers a typed event listener and returns an unsubscribe function. */
-  on<TEvent extends string & keyof TEvents>(name: TEvent, listener: (...[detail]: EventParameters<TEvents[TEvent]>) => void): Cleanup;
+//#region src/hooks/useSigma.d.ts
+/** Setup arguments and recreation dependencies for `useSigma(...)`. */
+type UseSigmaOptions<TSetup extends readonly any[] = any[]> = {
+  /** Arguments passed to the sigma instance's `onSetup(...)` method. */setup: TSetup | (() => TSetup); /** Dependencies that recreate the sigma instance when they change. */
+  deps?: readonly any[];
 };
-type SetupMethods<TSetupArgs extends any[] | undefined> = [TSetupArgs] extends [undefined] ? never : {
-  /** Runs every registered setup handler and returns one cleanup function for the active setup. */setup(...args: Extract<TSetupArgs, any[]>): Cleanup;
-};
-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;
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
-/** 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 RequiredKeys<TObject extends object> = { [K in keyof TObject]-?: {} extends Pick<TObject, K> ? never : K }[keyof TObject];
-type MissingInitialKeys<TState extends AnyState, TDefaults extends object> = Exclude<RequiredKeys<TState>, keyof TDefaults>;
-type InitialStateInput<TState extends AnyState, TDefaults extends object> = [MissingInitialKeys<TState, TDefaults>] extends [never] ? [initialState?: Partial<TState>] : [initialState: Pick<TState, MissingInitialKeys<TState, TDefaults>> & Partial<TState>];
-type ExtendSigmaType<T extends SigmaType<any, any, any>, TExtension extends Partial<SigmaDefinition>> = T & {
-  readonly [sigmaTypeBrand]: T[Def] & TExtension;
-};
-type OmitEmpty<T extends object> = Omit<T, { [K in keyof T]: [undefined] extends [T[K]] ? K : [{}] extends [T[K]] ? K : never }[keyof T]>;
-type InferSigmaDefinition<T extends SigmaType<any, any, any>> = Extract<Simplify<OmitEmpty<T[Def]>>, SigmaDefinition>;
-/** Infers the `setup(...)` argument list for a sigma-state instance. */
-type InferSetupArgs<T extends AnySigmaState> = T extends {
-  setup(...args: infer TArgs extends any[]): Cleanup;
-} ? TArgs : never;
-//#endregion
-//#region src/internal/runtime.d.ts
-/** 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. 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. 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 an instance created by a configured sigma type. */
-declare function isSigmaState(value: object): value is AnySigmaState;
-/**
- * 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.
- *
- * 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> = {}> extends Function {
-  readonly [sigmaTypeBrand]: {
-    state: TState;
-    events: TEvents;
-  };
-  constructor(name?: string);
-  /**
-   * 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<TDefaults extends AnyDefaultState<TState>>(defaultState: TDefaults): SigmaType<TState, TEvents, TDefaults>;
-  /**
-   * 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<TComputeds extends object>(computeds: TComputeds & ThisType<ComputedContext<this, {
-    computeds: TComputeds;
-  }>>): ExtendSigmaType<this, {
-    computeds: TComputeds;
-  }>;
-  /**
-   * 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<TQueries extends object>(queries: TQueries & ThisType<ReadonlyContext<this, {
-    queries: TQueries;
-  }>>): ExtendSigmaType<this, {
-    queries: TQueries;
-  }>;
-  /**
-   * Adds a committed-state observer.
-   *
-   * Observers run after successful publishes and can opt into Immer patches
-   * with `{ patches: true }`.
-   */
-  observe(listener: (this: ReadonlyContext<this>, change: SigmaObserveChange<TState>) => void, options?: SigmaObserveOptions & {
-    patches?: false | undefined;
-  }): this;
-  observe(listener: (this: ReadonlyContext<this>, change: SigmaObserveChange<TState, true>) => void, options: SigmaObserveOptions & {
-    patches: true;
-  }): this;
-  /**
-   * Adds action methods whose `this` receives draft state, typed events, `commit()`,
-   * and the computeds, queries, and actions already defined on the builder.
-   *
-   * Actions create drafts lazily as they need them. Sync actions on the same
-   * instance reuse the current draft, so they can compose and publish once when
-   * the outer action returns. Declared async actions publish their initial
-   * synchronous work on return, then require `this.commit()` to publish later
-   * writes made after `await`. Non-async actions stay synchronous; if one
-   * returns a promise, sigma throws so async boundaries stay explicit.
-   */
-  actions<TActions extends object>(actions: TActions & ThisType<ActionContext<this, {
-    actions: TActions;
-  }>>): ExtendSigmaType<this, {
-    actions: TActions;
-  }>;
-  /**
-   * 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<TSetupArgs extends any[]>(setup: (this: SetupContext<this, {
-    setupArgs: TSetupArgs;
-  }>, ...args: TSetupArgs) => readonly AnyResource[]): ExtendSigmaType<this, {
-    setupArgs: TSetupArgs;
-  }>;
-}
-interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefaults extends AnyDefaultState<TState>> {
-  /**
-   * 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<InferSigmaDefinition<this>>;
-  /**
-   * 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>): this["Instance"];
-}
-//#endregion
-//#region src/hooks.d.ts
+/** Infers the accepted `useSigma(...)` call shape from a sigma class and its setup parameters. */
+type UseSigmaArgs<T extends Sigma<any>> = T extends {
+  onSetup: (...params: infer TParams) => any;
+} ? [] extends TParams ? [create: () => T, options?: Partial<UseSigmaOptions<TParams>>] : [create: () => T, options: UseSigmaOptions<TParams>] : [create: () => T, deps?: readonly any[]];
 /**
- * Creates one sigma-state instance for a component.
+ * Creates or reuses a sigma instance for a component and returns its protected consumer view.
  *
- * `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 automatically.
- *
- * Passing `null` disables the listener. The latest callback is used without
- * forcing the effect to resubscribe on every render.
+ * Classes with `onSetup(...)` run setup in an effect and clean it up on unmount.
  */
-declare function useListener<TTarget extends EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
+declare function useSigma<T extends Sigma<any>>(...args: UseSigmaArgs<T>): Protected<T>;
 //#endregion
-export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, EventParameters, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaTarget, SigmaType, isSigmaState, listen, query, replaceState, reservedKeys, setAutoFreeze, sigmaEventsBrand, sigmaRefBrand, sigmaStateBrand, sigmaTypeBrand, signalPrefix, snapshot, useListener, useSigma };
+export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };