preact-sigma 2.2.3 → 3.0.1

package/README.md

@@ -43,5 +43,5 @@ console.log(counter.doubled); // 2
 - Concepts, lifecycle, invariants, and API selection live in [`docs/context.md`](./docs/context.md).
 - Quick-start usage lives in [`examples/basic-counter.ts`](./examples/basic-counter.ts).
 - An advanced end-to-end example lives in [`examples/command-palette.tsx`](./examples/command-palette.tsx).
-- Focused examples for non-obvious APIs live in [`examples/async-commit.ts`](./examples/async-commit.ts), [`examples/observe-and-restore.ts`](./examples/observe-and-restore.ts), [`examples/signal-access.ts`](./examples/signal-access.ts), and [`examples/setup-act.ts`](./examples/setup-act.ts).
+- 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`.

package/dist/index.d.mts

@@ -2,10 +2,54 @@ import { ReadonlySignal, action, batch, computed, effect, untracked } from "@pre
 import { Patch, freeze, immerable } from "immer";
 
 //#region src/internal/symbols.d.ts
+declare const sigmaTypeBrand: unique symbol;
 declare const sigmaStateBrand: unique symbol;
 declare const sigmaEventsBrand: unique symbol;
 declare const sigmaRefBrand: unique symbol;
 //#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;
 /** Object types that should never be mapped */
@@ -40,6 +84,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 +105,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 +166,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;
@@ -160,7 +214,7 @@ declare function replaceState<T extends AnySigmaState>(publicInstance: T, nextSt
 //#endregion
 //#region src/framework.d.ts
 /** Checks whether a value is an instance created by a configured sigma type. */
-declare function isSigmaState(value: unknown): value is AnySigmaState;
+declare function isSigmaState(value: object): value is AnySigmaState;
 /**
  * Creates a standalone tracked query helper with the same signature as `fn`.
  *
@@ -176,53 +230,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<{
-    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<{
+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>>;
+  };
+  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 +261,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,40 +289,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;
+  }>;
+}
+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/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 event names accepted by `listen(...)` or `useListener(...)` for a target. */
-type InferEventType<TTarget extends EventTarget> = (InferListener<TTarget> extends {
-  __eventType?: infer TEvent;
-} ? string & TEvent : never) | (string & {});
-/** Infers the listener callback shape for a target and event name. Sigma states receive payloads directly, while DOM targets receive typed events. */
-type InferListener<TTarget extends EventTarget, TEvent extends string = string> = TTarget extends AnySigmaStateWithEvents<infer TEvents> ? TEvent extends keyof TEvents ? (event: TEvents[TEvent]) => void : never : TTarget extends Window ? TypedEventListener<WindowEventMap, TEvent, TTarget> : TTarget extends Document ? TypedEventListener<DocumentEventMap, TEvent, TTarget> : TTarget extends HTMLBodyElement ? TypedEventListener<HTMLBodyElementEventMap, TEvent, TTarget> : TTarget extends HTMLMediaElement ? TypedEventListener<HTMLMediaElementEventMap, TEvent, TTarget> : TTarget extends HTMLElement ? TypedEventListener<HTMLElementEventMap, TEvent, TTarget> : TTarget extends SVGSVGElement ? TypedEventListener<SVGSVGElementEventMap, TEvent, TTarget> : TTarget extends SVGElement ? TypedEventListener<SVGElementEventMap, TEvent, TTarget> : (event: Event & {
-  readonly currentTarget: TTarget;
-}) => void;
-/** Adds a listener to a sigma state or DOM target and returns a cleanup function that removes it. */
-declare function listen<TTarget extends EventTarget, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, fn: InferListener<TTarget, TEvent>): () => void;
 //#endregion
 //#region src/hooks.d.ts
 /**
@@ -306,4 +340,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, 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, setAutoFreeze, 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;
@@ -541,7 +538,7 @@ Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 //#region src/framework.ts
 /** Checks whether a value is an instance created by a configured sigma type. */
 function isSigmaState(value) {
-	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
+	return Boolean(value[sigmaStateBrand]);
 }
 /**
 * Creates a standalone tracked query helper with the same signature as `fn`.
@@ -560,81 +557,153 @@ 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
+/**
+* A standalone typed event hub with `emit(...)` and `on(...)` methods and full
+* `EventTarget`, `listen(...)`, and `useListener(...)` compatibility.
+*/
+var SigmaTarget = class extends EventTarget {
+	/**
+	* Emits a typed event from the hub.
+	*
+	* Void events dispatch a plain `Event`. Payload events dispatch a
+	* `CustomEvent` whose `detail` holds the payload.
+	*/
+	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.
+	*
+	* Payload events pass their payload directly to the listener. Void events
+	* call the listener with no arguments.
+	*/
+	on(name, listener) {
+		const adapter = (event) => listener(event.detail);
+		this.addEventListener(name, adapter);
+		return () => {
+			this.removeEventListener(name, adapter);
+		};
+	}
+};
 /** Adds a listener to a sigma state or DOM target and returns a cleanup function that removes it. */
-function listen(target, name, fn) {
-	const listener = isSigmaState(target) ? (event) => fn(event.detail) : fn;
-	target.addEventListener(name, listener);
+function listen(target, name, listener) {
+	const adapter = isSigmaState(target) || target instanceof SigmaTarget ? (event) => listener(event.detail) : listener;
+	target.addEventListener(name, adapter);
 	return () => {
-		target.removeEventListener(name, listener);
+		target.removeEventListener(name, adapter);
 	};
 }
 //#endregion
@@ -669,4 +738,4 @@ function useListener(target, name, listener) {
 	}, [target, name]);
 }
 //#endregion
-export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { SigmaTarget, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/docs/context.md

@@ -1,6 +1,6 @@
 # Overview
 
-`preact-sigma` builds reusable state models from one definition. A configured `SigmaType` owns top-level state, derived reads, writes, setup handlers, and typed events. Each top-level state property is exposed as a reactive public property backed by its own Preact signal, while actions use Immer-style mutation semantics to publish committed state.
+`preact-sigma` builds reusable state models from one definition. A configured `SigmaType` owns top-level state, derived reads, writes, setup handlers, and typed events. Each top-level state property is exposed as a reactive public property backed by its own Preact signal, while actions use Immer-style mutation semantics to publish committed state. For event-only flows, `SigmaTarget` provides a standalone typed event hub with no managed state.
 
 # When to Use
 
@@ -21,6 +21,7 @@
 
 - Sigma type: the builder returned by `new SigmaType<TState, TEvents>()`. After configuration, it is also the constructor for instances.
 - Sigma state: an instance created from a configured sigma type.
+- Sigma target: a standalone typed event hub created with `new SigmaTarget<TEvents>()` when you need typed events without managed state.
 - State property: a top-level key from `TState`. Each one becomes a readonly reactive public property and gets its own signal.
 - Computed: an argument-free derived getter declared with `.computed(...)`.
 - Query: a reactive read that accepts arguments, declared with `.queries(...)` or built locally with `query(fn)`.
@@ -51,6 +52,7 @@
 - Own timers, listeners, subscriptions, or nested setup: `.setup(...)`
 - Use a sigma state inside a component: `useSigma(...)`
 - Subscribe to sigma or DOM events in a component: `useListener(...)`
+- Create a standalone typed event hub with no managed state: `new SigmaTarget<TEvents>()`, `hub.emit(...)`, and `hub.on(...)`
 - Subscribe outside components: `.on(...)` or `listen(...)`
 - Read or restore committed top-level state: `snapshot(...)` and `replaceState(...)`
 

package/examples/sigma-target.ts

@@ -0,0 +1,26 @@
+import { listen, SigmaTarget } from "preact-sigma";
+
+const notifications = new SigmaTarget<{
+  saved: {
+    id: string;
+    title: string;
+  };
+  reset: void;
+}>();
+
+const stopSaved = notifications.on("saved", ({ id, title }) => {
+  console.log(`Saved ${id}: ${title}`);
+});
+
+const stopReset = listen(notifications, "reset", () => {
+  console.log("Reset");
+});
+
+notifications.emit("saved", {
+  id: "note-1",
+  title: "Draft post",
+});
+notifications.emit("reset");
+
+stopSaved();
+stopReset();

package/package.json

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