preact-sigma 2.3.0 → 3.0.2

package/dist/index.d.mts

@@ -2,9 +2,55 @@ import { ReadonlySignal, action, batch, computed, effect, untracked } from "@pre
 import { Patch, freeze, immerable } from "immer";
 
 //#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>;
+//#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>) & {
+  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) & {
+  __eventType?: TEvent;
+} : never;
+/** 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 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;
 //#endregion
 //#region src/immer.d.ts
 type PrimitiveType = number | string | boolean;
@@ -40,6 +86,7 @@ type Draft<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : HasSi
 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;
 //#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;
@@ -60,30 +107,35 @@ 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 AnyState> = { [K in keyof TState]?: DefaultStateValue<TState[K]> };
+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 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; /** 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 : {
-  /** 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> & {
+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<TEvents>;
+  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[];
+  };
 };
-type DefinitionEvents<T extends SigmaDefinition> = T["events"] extends AnyEvents ? T["events"] : {};
-type DefinitionComputeds<T extends SigmaDefinition> = T["computeds"] extends object ? T["computeds"] : {};
-type DefinitionQueries<T extends SigmaDefinition> = T["queries"] extends object ? T["queries"] : {};
-type DefinitionActions<T extends SigmaDefinition> = T["actions"] extends object ? T["actions"] : {};
 /** The public shape shared by all sigma-state instances. */
 interface AnySigmaState extends EventTarget {
   readonly [sigmaStateBrand]: true;
@@ -116,21 +168,25 @@ 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 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;
+};
+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 SetupContext<T extends SigmaDefinition> = SigmaState<T> & {
-  /** 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;
 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]>;
+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;
@@ -176,53 +232,30 @@ declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: T
  * 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<{
+declare class SigmaType<TState extends AnyState, TEvents extends AnyEvents = {}, TDefaults extends AnyDefaultState<TState> = {}> extends Function {
+  readonly [sigmaTypeBrand]: {
     state: TState;
     events: TEvents;
-    computeds: TComputeds;
-    queries: TQueries;
-    actions: TActions;
-    setupArgs: TSetupArgs;
-  }>, SigmaDefinition>>;
-  /**
-   * 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;
-    computeds: TComputeds;
-    queries: TQueries;
-    actions: TActions;
-    setupArgs: TSetupArgs;
-  }>, SigmaDefinition>>;
+  };
+  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<TNextDefaults extends AnyDefaultState<TState>>(defaultState: TNextDefaults): SigmaType<TState, TEvents, MergeObjects<TDefaults, TNextDefaults>, TComputeds, TQueries, TActions, TSetupArgs>;
+  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<TNextComputeds extends object>(computeds: TNextComputeds & ThisType<ComputedContext<TState, MergeObjects<TComputeds, TNextComputeds>>>): SigmaType<TState, TEvents, TDefaults, MergeObjects<TComputeds, TNextComputeds>, TQueries, TActions, TSetupArgs>;
+  computed<TComputeds extends object>(computeds: TComputeds & ThisType<ComputedContext<this, {
+    computeds: TComputeds;
+  }>>): ExtendSigmaType<this, {
+    computeds: TComputeds;
+  }>;
   /**
    * Adds reactive read methods that accept arguments.
    *
@@ -230,17 +263,21 @@ interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefault
    * 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>;
+  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<TState, TComputeds, TQueries>, change: SigmaObserveChange<TState>) => void, options?: SigmaObserveOptions & {
+  observe(listener: (this: ReadonlyContext<this>, change: SigmaObserveChange<TState>) => void, options?: SigmaObserveOptions & {
     patches?: false | undefined;
   }): this;
-  observe(listener: (this: ReadonlyContext<TState, TComputeds, TQueries>, change: SigmaObserveChange<TState, true>) => void, options: SigmaObserveOptions & {
+  observe(listener: (this: ReadonlyContext<this>, change: SigmaObserveChange<TState, true>) => void, options: SigmaObserveOptions & {
     patches: true;
   }): this;
   /**
@@ -254,63 +291,39 @@ interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefault
    * 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>;
+  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<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>;
+  setup<TSetupArgs extends any[]>(setup: (this: SetupContext<this, {
+    setupArgs: TSetupArgs;
+  }>, ...args: TSetupArgs) => readonly AnyResource[]): ExtendSigmaType<this, {
+    setupArgs: TSetupArgs;
+  }>;
 }
-//#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>) & {
-  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) & {
-  __eventType?: TEvent;
-} : never;
-/** 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 & {});
-/**
- * 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;
+interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefaults extends AnyDefaultState<TState>> {
   /**
-   * Emits a typed event from the hub.
+   * Type-only access to the configured instance shape.
    *
-   * Void events dispatch a plain `Event`. Payload events dispatch a
-   * `CustomEvent` whose `detail` holds the payload.
+   * This property does not exist at runtime. Its type is inferred from the
+   * generics on `new SigmaType<TState, TEvents>()` plus the later builder inputs.
    */
-  emit<TEvent extends string & keyof TEvents>(name: TEvent, ...args: [TEvents[TEvent]] extends [void] ? [] : [payload: TEvents[TEvent]]): void;
+  get Instance(): SigmaState<InferSigmaDefinition<this>>;
   /**
-   * Registers a typed event listener and returns an unsubscribe function.
+   * Creates a sigma-state instance.
    *
-   * Payload events pass their payload directly to the listener. Void events
-   * call the listener with no arguments.
+   * Constructor input shallowly overrides `defaultState(...)`. Required keys are
+   * inferred from whichever state properties still do not have defaults.
    */
-  on<TEvent extends string & keyof TEvents>(name: TEvent, listener: (...args: InferListenerArgs<TEvents, this, TEvent>) => void): () => void;
+  new (...args: InitialStateInput<TState, TDefaults>): this["Instance"];
 }
-/** 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;
 //#endregion
 //#region src/hooks.d.ts
 /**
@@ -329,4 +342,4 @@ declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?:
  */
 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, SigmaTarget, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+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, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, reservedKeys, setAutoFreeze, sigmaEventsBrand, sigmaRefBrand, sigmaStateBrand, sigmaTypeBrand, signalPrefix, snapshot, untracked, useListener, useSigma };

package/dist/index.mjs

@@ -105,13 +105,13 @@ function createContext(instance, options, owner) {
 				const signal = getSignal(instance, key);
 				return options.reactiveReads ? signal.value : signal.peek();
 			}
-			if (key in instance.type.computeFunctions) {
+			if (key in instance.type._computeFunctions) {
 				if (owner && options.liveComputeds) return readActionComputedValue(owner, key);
 				const signal = getSignal(instance, key);
 				return options.reactiveReads ? signal.value : signal.peek();
 			}
-			if (options.allowQueries && key in instance.type.queryFunctions) return Reflect.get(instance.publicInstance, key);
-			if (options.allowActions && key in instance.type.actionFunctions) return Reflect.get(instance.publicInstance, key);
+			if (options.allowQueries && key in instance.type._queryFunctions) return Reflect.get(instance.publicInstance, key);
+			if (options.allowActions && key in instance.type._actionFunctions) return Reflect.get(instance.publicInstance, key);
 			if (Reflect.has(publicPrototype, key)) return Reflect.get(publicPrototype, key, owner?.actionContext ?? instance.publicInstance);
 		},
 		set(_target, key, value) {
@@ -172,7 +172,7 @@ function getPublicContext(instance, kind) {
 }
 //#endregion
 //#region src/internal/symbols.ts
-const sigmaStateBrand = Symbol("sigma.v2.state");
+const sigmaStateBrand = Symbol("sigma.state");
 const reservedKeys = new Set([
 	"act",
 	"get",
@@ -212,7 +212,7 @@ function getSignal(instance, key) {
 	return instance.publicInstance["#" + key];
 }
 function initializeSigmaInstance(publicInstance, type, initialState) {
-	const stateKeys = new Set(type.defaultStateKeys);
+	const stateKeys = new Set(type._defaultStateKeys);
 	if (initialState) for (const key in initialState) stateKeys.add(key);
 	const instance = {
 		currentSetupCleanup: void 0,
@@ -224,7 +224,7 @@ function initializeSigmaInstance(publicInstance, type, initialState) {
 	for (const key of stateKeys) {
 		if (reservedKeys.has(key)) throw new Error(`[preact-sigma] Reserved property name: ${key}`);
 		let value = initialState?.[key];
-		if (value === void 0) value = typeof type.defaultState[key] === "function" ? type.defaultState[key].call(void 0) : type.defaultState[key];
+		if (value === void 0) value = typeof type._defaultState[key] === "function" ? type._defaultState[key].call(void 0) : type._defaultState[key];
 		const container = signal(value);
 		Object.defineProperty(publicInstance, "#" + key, { value: container });
 		Object.defineProperty(publicInstance, key, {
@@ -232,7 +232,7 @@ function initializeSigmaInstance(publicInstance, type, initialState) {
 			enumerable: true
 		});
 	}
-	for (const key in type.computeFunctions) Object.defineProperty(publicInstance, "#" + key, { value: computed$1(() => type.computeFunctions[key].call(getContext(instance, "computedReadonly"))) });
+	for (const key in type._computeFunctions) Object.defineProperty(publicInstance, "#" + key, { value: computed$1(() => type._computeFunctions[key].call(getContext(instance, "computedReadonly"))) });
 	registerSigmaInternals(publicInstance, instance);
 }
 function buildQueryMethod(queryFunction) {
@@ -259,7 +259,7 @@ function readActionStateValue(owner, key, options) {
 	return committedValue;
 }
 function readActionComputedValue(owner, key) {
-	return owner.instance.type.computeFunctions[key].call(getContext(owner, "computedDraftAware"));
+	return owner.instance.type._computeFunctions[key].call(getContext(owner, "computedDraftAware"));
 }
 function setActionStateValue(owner, key, value) {
 	ensureOwnerDraft(owner)[key] = value;
@@ -281,10 +281,10 @@ function handleActionBoundary(owner, boundary, actionName) {
 }
 function assertDefinitionKeyAvailable(builder, key, kind) {
 	if (reservedKeys.has(key)) throw new Error(`[preact-sigma] Reserved property name: ${key}`);
-	if (key in builder.computeFunctions || key in builder.queryFunctions || key in builder.actionFunctions) throw new Error(`[preact-sigma] Duplicate key for ${kind}: ${key}`);
+	if (key in builder._computeFunctions || key in builder._queryFunctions || key in builder._actionFunctions) throw new Error(`[preact-sigma] Duplicate key for ${kind}: ${key}`);
 }
 function shouldSetup(publicInstance) {
-	return getSigmaInternals(publicInstance).type.setupFunctions.length > 0;
+	return getSigmaInternals(publicInstance).type._setupFunction !== null;
 }
 function clearCurrentDraft(owner) {
 	owner.currentDraft = void 0;
@@ -396,7 +396,7 @@ function finalizeOwnerDraft(owner) {
 	clearCurrentDraft(owner);
 	let patches;
 	let inversePatches;
-	const newState = owner.instance.type.patchesEnabled ? immer.finishDraft(currentDraft, (nextPatches, nextInversePatches) => {
+	const newState = owner.instance.type._patchesEnabled ? immer.finishDraft(currentDraft, (nextPatches, nextInversePatches) => {
 		patches = nextPatches;
 		inversePatches = nextInversePatches;
 	}) : immer.finishDraft(currentDraft);
@@ -413,7 +413,7 @@ function finalizeReplacementState(instance, oldState, nextState) {
 	for (const key of instance.stateKeys) draft[key] = nextState[key];
 	let patches;
 	let inversePatches;
-	const newState = instance.type.patchesEnabled ? immer.finishDraft(draft, (nextPatches, nextInversePatches) => {
+	const newState = instance.type._patchesEnabled ? immer.finishDraft(draft, (nextPatches, nextInversePatches) => {
 		patches = nextPatches;
 		inversePatches = nextInversePatches;
 	}) : immer.finishDraft(draft);
@@ -440,7 +440,7 @@ function publishState(instance, finalized) {
 			signal.value = nextValue;
 		}
 	});
-	for (const observer of instance.type.observeFunctions) observer.call(getContext(instance, "observe"), finalized);
+	instance.type._observeFunction?.call(getContext(instance, "observe"), finalized);
 }
 /**
 * Returns a shallow snapshot of an instance's committed public state.
@@ -492,15 +492,12 @@ async function resolveAsyncActionResult(owner, result) {
 var Sigma = class extends EventTarget {
 	setup(...args) {
 		const instance = getSigmaInternals(this);
-		if (!instance.type.setupFunctions.length) throw new Error("[preact-sigma] Setup is undefined for this sigma state");
+		if (!instance.type._setupFunction) throw new Error("[preact-sigma] Setup is undefined for this sigma state");
 		if (instance.disposed) throw new Error("[preact-sigma] Cannot set up a disposed sigma state");
 		instance.currentSetupCleanup?.();
 		instance.currentSetupCleanup = void 0;
-		const resources = instance.type.setupFunctions.flatMap((setup) => {
-			const result = setup.apply(getContext(instance, "setup"), args);
-			if (!Array.isArray(result)) throw new Error("[preact-sigma] Sigma setup handlers must return an array");
-			return result;
-		});
+		const resources = instance.type._setupFunction.apply(getContext(instance, "setup"), args);
+		if (!Array.isArray(resources)) throw new Error("[preact-sigma] Sigma setup handlers must return an array");
 		let cleanup;
 		if (resources.length) {
 			let cleaned = false;
@@ -560,73 +557,117 @@ function query(fn) {
 * 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 {
+var SigmaType = class SigmaType extends Function {
 	constructor(name = "Sigma") {
 		super();
-		const type = {
-			actionFunctions: Object.create(null),
-			computeFunctions: Object.create(null),
-			defaultState: Object.create(null),
-			defaultStateKeys: [],
-			observeFunctions: [],
-			patchesEnabled: false,
-			queryFunctions: Object.create(null),
-			setupFunctions: []
-		};
-		const { [name]: SigmaTypeBuilder } = { [name]: class extends Sigma {
+		const { [name]: type } = { [name]: class extends Sigma {
+			static _actionFunctions = Object.create(null);
+			static _computeFunctions = Object.create(null);
+			static _defaultState = Object.create(null);
+			static _defaultStateKeys = [];
+			static _observeFunction = null;
+			static _patchesEnabled = false;
+			static _queryFunctions = Object.create(null);
+			static _setupFunction = null;
 			constructor(initialState) {
 				super();
 				initializeSigmaInstance(this, type, initialState);
 			}
 		} };
-		SigmaTypeBuilder.defaultState = function(defaultState) {
-			for (const key in defaultState) {
-				if (defaultState[key] === void 0) continue;
-				type.defaultState[key] = defaultState[key];
-				type.defaultStateKeys.push(key);
-			}
-			return this;
-		};
-		SigmaTypeBuilder.computed = function(computeFunctions) {
-			for (const key in computeFunctions) {
-				assertDefinitionKeyAvailable(type, key, "computed");
-				type.computeFunctions[key] = computeFunctions[key];
-				Object.defineProperty(this.prototype, key, { get: function() {
-					return this["#" + key].value;
-				} });
-			}
-			return this;
-		};
-		SigmaTypeBuilder.queries = function(queryFunctions) {
-			for (const key in queryFunctions) {
-				assertDefinitionKeyAvailable(type, key, "query");
-				const queryFunction = queryFunctions[key];
-				type.queryFunctions[key] = queryFunction;
-				Object.defineProperty(this.prototype, key, { value: buildQueryMethod(queryFunction) });
-			}
-			return this;
-		};
-		SigmaTypeBuilder.observe = function(listener, options) {
-			type.observeFunctions.push(listener);
-			if (options?.patches) type.patchesEnabled = true;
-			return this;
-		};
-		SigmaTypeBuilder.actions = function(actionFunctions) {
-			for (const key in actionFunctions) {
-				assertDefinitionKeyAvailable(type, key, "action");
-				const actionFunction = actionFunctions[key];
-				type.actionFunctions[key] = actionFunction;
-				Object.defineProperty(this.prototype, key, { value: buildActionMethod(key, actionFunction) });
-			}
-			return this;
-		};
-		SigmaTypeBuilder.setup = function(setup) {
-			type.setupFunctions.push(setup);
-			return this;
-		};
-		return SigmaTypeBuilder;
+		Object.defineProperties(type, Object.getOwnPropertyDescriptors(SigmaType.prototype));
+		return type;
+	}
+	/**
+	* 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(defaultState) {
+		const type = getTypeInternals(this);
+		for (const key in defaultState) {
+			if (defaultState[key] === void 0) continue;
+			type._defaultState[key] = defaultState[key];
+			type._defaultStateKeys.push(key);
+		}
+		return this;
+	}
+	/**
+	* 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(computeds) {
+		const type = getTypeInternals(this);
+		for (const key in computeds) {
+			assertDefinitionKeyAvailable(type, key, "computed");
+			type._computeFunctions[key] = computeds[key];
+			Object.defineProperty(this.prototype, key, { get: function() {
+				return this["#" + key].value;
+			} });
+		}
+		return this;
+	}
+	/**
+	* 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(queries) {
+		const type = getTypeInternals(this);
+		for (const key in queries) {
+			assertDefinitionKeyAvailable(type, key, "query");
+			const queryFunction = queries[key];
+			type._queryFunctions[key] = queryFunction;
+			Object.defineProperty(this.prototype, key, { value: buildQueryMethod(queryFunction) });
+		}
+		return this;
+	}
+	observe(listener, options) {
+		const type = getTypeInternals(this);
+		type._observeFunction = listener;
+		if (options?.patches) type._patchesEnabled = true;
+		return 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(actions) {
+		const type = getTypeInternals(this);
+		for (const key in actions) {
+			assertDefinitionKeyAvailable(type, key, "action");
+			const actionFunction = actions[key];
+			type._actionFunctions[key] = actionFunction;
+			Object.defineProperty(this.prototype, key, { value: buildActionMethod(key, actionFunction) });
+		}
+		return this;
+	}
+	/**
+	* 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(setup) {
+		const type = getTypeInternals(this);
+		type._setupFunction = setup;
+		return this;
 	}
 };
+function getTypeInternals(type) {
+	return type;
+}
 //#endregion
 //#region src/listener.ts
 /**
@@ -640,8 +681,8 @@ var SigmaTarget = class extends EventTarget {
 	* Void events dispatch a plain `Event`. Payload events dispatch a
 	* `CustomEvent` whose `detail` holds the payload.
 	*/
-	emit(name, ...args) {
-		this.dispatchEvent(args.length === 0 ? new Event(name) : new CustomEvent(name, { detail: args[0] }));
+	emit(name, ...[detail]) {
+		this.dispatchEvent(detail === void 0 ? new Event(name) : new CustomEvent(name, { detail }));
 	}
 	/**
 	* Registers a typed event listener and returns an unsubscribe function.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "2.3.0",
+  "version": "3.0.2",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",