preact-sigma 1.0.0 → 2.0.0

package/dist/index.d.mts

@@ -1,215 +1,229 @@
-import { ReadonlySignal, Signal, batch, computed, untracked } from "@preact/signals";
-import { Immutable, Producer } from "immer";
+import { ReadonlySignal, action, batch, computed, effect, untracked } from "@preact/signals";
+import { Patch, freeze, immerable } from "immer";
 
-//#region src/internal.d.ts
-type Cleanup = () => void;
-type Disposable = {
-  [Symbol.dispose](): void;
-};
-type OwnedResource = Cleanup | Disposable;
-type OwnedResources = OwnedResource | readonly OwnedResource[];
-declare class AnyStateHandle<TState = any, TEvents extends EventsDefinition = any> {
-  private readonly state;
-  /**
-   * Emit a custom event with zero or one argument.
-   */
-  readonly emit: [TEvents] extends [{}] ? <TEvent extends string & keyof TEvents>(name: TEvent, ...args: TEvents[TEvent]) => void : never;
-  /**
-   * Attach cleanup functions or disposables to the managed state instance.
-   */
-  readonly own: (resources: OwnedResources) => void;
-  constructor(state: Signal<Immutable<TState>>,
-  /**
-   * Emit a custom event with zero or one argument.
-   */
-
-  emit: [TEvents] extends [{}] ? <TEvent extends string & keyof TEvents>(name: TEvent, ...args: TEvents[TEvent]) => void : never,
-  /**
-   * Attach cleanup functions or disposables to the managed state instance.
-   */
-
-  own: (resources: OwnedResources) => void);
-  /** Read the current immutable base state. This read is tracked. */
-  get(): Immutable<TState>;
-  /** Read the current immutable base state snapshot without tracking. */
-  peek(): Immutable<TState>;
-  /** Replace the base state, or update it with an Immer producer. */
-  set(value: TState | Producer<TState>): void;
-}
-/** Check whether a value is a managed-state instance. */
-declare function isManagedState(value: unknown): value is AnyManagedState;
-//#endregion
-//#region src/framework.d.ts
-type EventsDefinition = Record<string, [any?]>;
-type FilterProperties$1<T extends object, U> = {} & { [P in { [K in keyof T]: [T[K]] extends [never] ? never : T[K] extends U ? K : never }[keyof T]]: T[P] };
-type InferActions$1<TProps extends object> = {} & FilterProperties$1<TProps, (...args: any[]) => any>;
-type InferManagedStates$1<TProps extends object> = {} & FilterProperties$1<TProps, AnyManagedState>;
-type InferPublicProps$1<TProps extends object> = InferActions$1<TProps> & InferManagedStates$1<TProps>;
-type OmitManagedStates<TState> = TState extends object ? Omit<TState, keyof InferManagedStates$1<TState>> : TState;
-type InferState$1<TProps extends object> = {} & Immutable<{ [K in keyof FilterProperties$1<TProps, ReadonlySignal | StateHandle<any, any> | Lens>]: TProps[K] extends ReadonlySignal<infer T> | StateHandle<infer T> | Lens<infer T> ? T : never }> & Readonly<InferManagedStates$1<TProps>>;
-type AnyManagedState<TState = any, TEvents extends EventsDefinition = any> = {
-  /** Get the underlying signal for an exposed signal-backed public property. */get<K extends keyof OmitManagedStates<TState>>(key: K): ReadonlySignal<OmitManagedStates<TState>[K]>;
-  get(): ReadonlySignal<TState>; /** Read the current immutable public state snapshot without tracking. */
-  peek<K extends keyof OmitManagedStates<TState>>(key: K): OmitManagedStates<TState>[K];
-  peek(): TState;
-  /**
-   * Subscribe to the current and future immutable values of one signal-backed
-   * public property. Returns a function to unsubscribe.
-   */
-  subscribe<K extends keyof OmitManagedStates<TState>>(key: K, listener: (value: OmitManagedStates<TState>[K]) => void): () => void; /** Subscribe to the current and future immutable public state snapshots. */
-  subscribe(listener: (value: TState) => void): () => void;
-  /**
-   * Subscribe to a custom event emitted by this managed state.
-   *
-   * Your listener receives the emitted argument directly, or no argument at all.
-   */
-  on<TEvent extends string & keyof TEvents>(name: TEvent, listener: (...args: TEvents[TEvent]) => void): () => void; /** Dispose this managed state instance and its owned resources. */
-  dispose(): void;
-  [Symbol.dispose](): void;
-};
+//#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;
 /**
- * Public instance shape produced by `defineManagedState()` and `useManagedState()`.
- *
- * Returned signals and top-level lenses are exposed as tracked getter
- * properties. Returning the `StateHandle` itself exposes the base state
- * directly as a reactive immutable property.
+ * 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 ManagedState<TState, TEvents extends EventsDefinition = EventsDefinition, TProps extends object = Record<string, unknown>> = AnyManagedState<TState, TEvents> & Immutable<TState> & TProps;
+type IfAvailable<T, Fallback = void> = true | false extends (T extends never ? true : false) ? Fallback : keyof T extends never ? Fallback : T;
 /**
- * Mark a constructor-returned method as a tracked query.
- *
- * Query methods wrap their body in `computed()`, so reads inside the method
- * participate in signal tracking even after the method is exposed publicly.
- * Query functions read from closed-over handles or signals and do not use an
- * instance receiver. Tagged query methods also skip the default `action()`
- * wrapping step.
+ * These should also never be mapped but must be tested after regular Map and
+ * Set
  */
-declare function query<TFunction extends (this: void, ...args: any[]) => any>(fn: TFunction): TFunction;
+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 };
 /**
- * Constructor-local access to one top-level property of an object-shaped base
- * state.
+ * Convert a readonly type into a mutable type, if possible.
  *
- * Lenses only exist on `StateHandle`, and `get()` reads are tracked in the
- * same way as `StateHandle.get()`. `set()` accepts either a replacement value
- * or an Immer producer for that property value.
+ * Use this instead of `immer.Draft`
  */
-type Lens<TState = any> = {
-  /** Read the current immutable property value. This read is tracked. */get: () => Immutable<TState>;
-  /**
-   * Replace the property value, or update it with an Immer producer for that
-   * property value.
-   */
-  set: (value: TState | Producer<TState>) => void;
-};
+type Draft<T> = T extends PrimitiveType ? T : T extends AtomicObject ? 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;
 /**
- * Constructor-local access to the base state.
+ * Convert a mutable type into a readonly type.
  *
- * `TState` may be any non-function value, including primitives.
- *
- * Return this handle from the constructor when you want to expose the base
- * state directly as a reactive immutable property on the managed state.
- *
- * When the base state is object-shaped, the handle also exposes a shallow
- * `Lens` for each top-level property key. Spreading an object-shaped handle
- * into the returned constructor object exposes those top-level lenses as
- * tracked public properties.
- *
- * For ordinary derived values, prefer external functions like
- * `getVisibleTodos(state)` so unused helpers can be tree-shaken. Reach for
- * `computed(() => derive(handle.get()))` only when you need memoized reactive
- * reads as a performance optimization.
+ * Use this instead of `immer.Immutable`
  */
-type StateHandle<TState, TEvents extends EventsDefinition = never> = AnyStateHandle<TState, TEvents> & (TState extends object ? TState extends ((...args: any[]) => any) | readonly any[] | ReadonlyMap<any, any> | ReadonlySet<any> ? {} : { readonly [K in keyof TState]: Lens<TState[K]> } : {});
-/**
- * Pure constructor function for a managed state definition.
- *
- * The first parameter should be explicitly typed as `StateHandle<...>`. The
- * library infers the internal state and event types from that parameter type.
- *
- * Return only methods, signals, top-level `Lens` values from the provided
- * `StateHandle`, the provided `StateHandle`, or a managed state instance.
- * Returned signals and lenses become tracked getter properties, returning the
- * handle exposes the base state directly as a reactive immutable property, and
- * managed state instances are passed through unchanged.
- */
-type StateConstructor<TState, TEvents extends EventsDefinition, TParams extends any[], TProps extends object = {}> = (handle: StateHandle<TState, TEvents>, ...params: TParams) => TProps & {
-  [key: string]: ((...args: any[]) => any) | AnyManagedState | Lens | ReadonlySignal | StateHandle<any, any>;
+type Immutable<T> = T extends PrimitiveType ? T : T extends AtomicObject ? 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/internal/symbols.d.ts
+declare const sigmaStateBrand: unique symbol;
+declare const sigmaEventsBrand: unique symbol;
+//#endregion
+//#region src/internal/types.d.ts
+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;
 };
-/**
- * Define a managed state class with a private mutable implementation and an
- * immutable public surface.
- *
- * `TState` may be any non-function value, including primitives.
- *
- * The constructor function's explicitly typed `StateHandle` parameter is what
- * the library uses to infer the internal state and event types.
- *
- * Methods are automatically wrapped with `action()` from `@preact/signals`, so
- * they are untracked and batched unless you opt into tracked reads with
- * `query()`.
- *
- * The state constructor must return an object with properties that are either:
- * - A function (to expose methods)
- * - A signal (to expose derived state)
- * - A top-level lens from the state handle (to expose one reactive property)
- * - The state handle (to expose the reactive immutable base state directly)
- * - A managed state instance (to compose another managed state as a property)
- *
- * Returned signals and top-level lenses are turned into getter properties, so
- * reads are tracked by the `@preact/signals` runtime. When the base state is
- * object-shaped, spreading the `StateHandle` into the returned object exposes
- * its current top-level lenses at once.
- *
- * Events can carry at most one argument.
- *
- * The state constructor should be side-effect free.
- */
-declare function defineManagedState<TState, TEvents extends EventsDefinition, TParams extends any[], TProps extends object = {}, TInitialState extends TState = TState>(constructor: StateConstructor<TState, TEvents, TParams, TProps>, initialState: TInitialState): new (...params: TParams) => ManagedState<InferState$1<TProps>, TEvents, InferPublicProps$1<TProps>>;
+/** 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(...)`. */
+type AnyDefaultState<TState extends AnyState> = { [K in keyof TState]?: DefaultStateValue<TState[K]> };
+/** A cleanup resource supported by `.setup(...)`. */
+type AnyResource = Cleanup | Disposable | AbortController;
+type ComputedValues<TComputeds extends object | undefined> = [undefined] extends [TComputeds] ? never : { readonly [K in keyof TComputeds]: TComputeds[K] extends AnyFunction ? Immutable<ReturnType<TComputeds[K]>> : never };
+type ComputedContext<TState extends AnyState, TComputeds extends object> = Immutable<TState> & ComputedValues<TComputeds>;
+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;
+  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;
+};
+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;
+  emit: Emit<TEvents>;
+};
+/** 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 = {
+  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> {
+  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. */
+type SigmaState<T extends SigmaDefinition = SigmaDefinition> = AnySigmaState & Simplify<UnionToIntersection<MapSigmaDefinition<T>>>;
+type SetupContext<T extends SigmaDefinition> = SigmaState<T> & {
+  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;
+type RequiredKeys<TObject extends object> = { [K in keyof TObject]-?: {} extends Pick<TObject, K> ? never : K }[keyof TObject];
+type MissingInitialKeys<TState extends AnyState, TDefaults extends AnyDefaultState<TState> | undefined> = Exclude<RequiredKeys<TState>, keyof NonNullable<TDefaults>>;
+type InitialStateInput<TState extends AnyState, TDefaults extends AnyDefaultState<TState> | undefined> = [MissingInitialKeys<TState, TDefaults>] extends [never] ? [initialState?: Partial<TState>] : [initialState: Pick<TState, MissingInitialKeys<TState, TDefaults>> & Partial<TState>];
+type Omit<T, K> = {} & { [P in Exclude<keyof T, K>]: T[P] };
+type OmitEmpty<T extends object> = {} & Omit<T, { [K in keyof T]: [undefined] extends [T[K]] ? K : [{}] extends [T[K]] ? K : never }[keyof T]>;
+/** 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/hooks.d.ts
-type FilterProperties<T extends object, U> = {} & { [P in { [K in keyof T]: [T[K]] extends [never] ? never : T[K] extends U ? K : never }[keyof T]]: T[P] };
-type InferActions<TProps extends object> = {} & FilterProperties<TProps, (...args: any[]) => any>;
-type InferManagedStates<TProps extends object> = {} & FilterProperties<TProps, AnyManagedState>;
-type InferPublicProps<TProps extends object> = InferActions<TProps> & InferManagedStates<TProps>;
-type InferState<TProps extends object> = {} & Immutable<{ [K in keyof FilterProperties<TProps, ReadonlySignal | StateHandle<any, any> | Lens>]: TProps[K] extends ReadonlySignal<infer T> | StateHandle<infer T> | Lens<infer T> ? T : never }> & Readonly<InferManagedStates<TProps>>;
+//#region src/internal/runtime.d.ts
+/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled. */
+declare function setAutoFreeze(autoFreeze: boolean): void;
 /**
- * Clean encapsulation of complex UI state.
+ * Returns a shallow snapshot of an instance's committed public state.
  *
- * Use this when a component needs the same managed-state API without defining a
- * separate class. The constructor follows the same rules as
- * `defineManagedState()`, including explicit typing of the `StateHandle`
- * parameter for state and event inference.
- */
-declare function useManagedState<TState, TEvents extends EventsDefinition, TProps extends object = {}, TInitialState extends TState = TState>(constructor: StateConstructor<TState, TEvents, [], TProps>, initialState: TInitialState | (() => TInitialState)): ManagedState<InferState<TProps>, TEvents, InferPublicProps<TProps>>;
-/**
- * Any subscribable source, including a managed state or any Preact signal.
+ * 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.
  */
-type SubscribeTarget<T> = {
-  subscribe: (listener: (value: T) => void) => () => void;
-};
+declare function snapshot<T extends AnySigmaState>(publicInstance: T): T extends SigmaState<infer TDefinition> ? Immutable<TDefinition["state"]> : never;
 /**
- * Subscribe to future values from a subscribable source inside `useEffect`.
+ * Replaces an instance's committed public state from a snapshot object.
  *
- * The listener is kept fresh automatically, so a dependency array is not part
- * of this API. The listener receives the current value immediately and then
- * future updates. Pass `null` to disable the subscription temporarily.
+ * 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.
  */
-declare function useSubscribe<T>(target: SubscribeTarget<T> | null, listener: (value: T) => void): void;
-type InferEvent<T extends EventTarget | AnyManagedState> = T extends AnyManagedState<any, infer TEvents extends EventsDefinition> ? string & keyof TEvents : T extends {
-  addEventListener: (name: infer TEvent) => any;
-} ? string & TEvent : string;
-type InferEventListener<T extends EventTarget | AnyManagedState, TEvent extends string = any> = T extends AnyManagedState<any, infer TEvents extends EventsDefinition> ? TEvent extends string & keyof TEvents ? (...args: TEvents[TEvent]) => void : never : T extends {
-  addEventListener: (name: TEvent, listener: infer TListener extends (event: any) => any) => any;
-} ? TListener : (event: Event) => void;
+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. */
+declare function isSigmaState(value: unknown): value is AnySigmaState;
+/** Creates a standalone tracked query function with the same signature as `fn`. */
+declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: TArgs) => TResult): typeof fn;
 /**
- * Subscribe to events from an `EventTarget` or managed state inside `useEffect`.
- *
- * The listener is kept fresh automatically, so a dependency array is not part
- * of this API. Pass `null` to disable the subscription temporarily.
- *
- * For managed-state events, your listener receives the emitted argument
- * directly, or no argument at all.
+ * Builds sigma-state constructors by accumulating default state, computeds, queries,
+ * observers, actions, and setup handlers.
  */
-declare function useEventTarget<T extends EventTarget | AnyManagedState, TEvent extends InferEvent<T>>(target: T | null, name: TEvent, listener: InferEventListener<T, TEvent>): void;
+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[]> {
+  new (...args: InitialStateInput<TState, TDefaults>): SigmaState<Extract<OmitEmpty<{
+    state: TState;
+    events: TEvents;
+    computeds: TComputeds;
+    queries: TQueries;
+    actions: TActions;
+    setupArgs: TSetupArgs;
+  }>, SigmaDefinition>>;
+  /** Does not exist at runtime, only for type inference. */
+  get Instance(): SigmaState<Extract<OmitEmpty<{
+    state: TState;
+    events: TEvents;
+    computeds: TComputeds;
+    queries: TQueries;
+    actions: TActions;
+    setupArgs: TSetupArgs;
+  }>, SigmaDefinition>>;
+  defaultState<TNextDefaults extends AnyDefaultState<TState>>(defaultState: TNextDefaults): SigmaType<TState, TEvents, MergeObjects<TDefaults, TNextDefaults>, TComputeds, TQueries, TActions, TSetupArgs>;
+  computed<TNextComputeds extends object>(computeds: TNextComputeds & ThisType<ComputedContext<TState, MergeObjects<TComputeds, TNextComputeds>>>): SigmaType<TState, TEvents, TDefaults, MergeObjects<TComputeds, TNextComputeds>, TQueries, TActions, TSetupArgs>;
+  queries<TNextQueries extends object>(queries: TNextQueries & ThisType<ReadonlyContext<TState, TComputeds, MergeObjects<TQueries, TNextQueries>>>): SigmaType<TState, TEvents, TDefaults, TComputeds, MergeObjects<TQueries, TNextQueries>, TActions, TSetupArgs>;
+  observe(listener: (this: ReadonlyContext<TState, TComputeds, TQueries>, change: SigmaObserveChange<TState>) => void, options?: SigmaObserveOptions & {
+    patches?: false | undefined;
+  }): this;
+  observe(listener: (this: ReadonlyContext<TState, TComputeds, TQueries>, 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<TNextActions extends object>(actions: TNextActions & ThisType<ActionContext<TState, TEvents, TComputeds, TQueries, MergeObjects<TActions, TNextActions>>>): SigmaType<TState, TEvents, TDefaults, TComputeds, TQueries, MergeObjects<TActions, TNextActions>, TSetupArgs>;
+  setup<TNextSetupArgs extends ([TSetupArgs] extends [never] ? any[] : NonNullable<TSetupArgs>)>(setup: (this: SetupContext<{
+    state: TState;
+    events: TEvents;
+    computeds: TComputeds;
+    queries: TQueries;
+    actions: TActions;
+    setupArgs: TNextSetupArgs;
+  }>, ...args: TNextSetupArgs) => readonly AnyResource[]): SigmaType<TState, TEvents, TDefaults, TComputeds, TQueries, TActions, TNextSetupArgs>;
+}
+//#endregion
+//#region src/listener.d.ts
+type TryGet<T, K extends PropertyKey, TCatch = never> = K extends keyof T ? T[K] : TCatch;
+type TypedEventListener<TEventMap, TEvent extends string, TCurrentTarget extends EventTarget> = ((event: TryGet<TEventMap, string extends TEvent ? keyof TEventMap : TEvent, CustomEvent> & {
+  readonly currentTarget: TCurrentTarget;
+}) => void) & {
+  __eventType?: string extends TEvent ? keyof TEventMap : TEvent;
+};
+/** Infers the supported event names for a listener 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. */
+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. */
+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. */
+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. */
+declare function useListener<TTarget extends EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
-export { AnyManagedState, EventsDefinition, Lens, ManagedState, StateConstructor, StateHandle, SubscribeTarget, batch, computed, defineManagedState, isManagedState, query, untracked, useEventTarget, useManagedState, useSubscribe };
+export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };