preact-sigma 0.0.0 → 1.0.0

package/README.md

@@ -0,0 +1,509 @@
+# `preact-sigma`
+
+Managed UI state for Preact Signals, with Immer-powered updates and a small public API.
+
+For naming and API design conventions, see [best-practices.md](./best-practices.md).
+
+## Install
+
+```sh
+pnpm add preact-sigma
+```
+
+```sh
+npm install preact-sigma
+```
+
+## Big Picture
+
+Define state once, expose a few methods, and return reactive immutable data from the public instance.
+
+```ts
+import { computed, defineManagedState, type StateHandle } from "preact-sigma";
+
+type CounterEvents = {
+  thresholdReached: [{ count: number }];
+};
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (counter: StateHandle<CounterState, CounterEvents>, step: number) => {
+    const doubled = computed(() => counter.get() * 2);
+
+    return {
+      count: counter,
+      doubled,
+      increment() {
+        counter.set((value) => value + step);
+
+        if (counter.get() >= 10) {
+          counter.emit("thresholdReached", { count: counter.get() });
+        }
+      },
+      reset() {
+        counter.set(0);
+      },
+    };
+  },
+  0,
+);
+
+const counter = new Counter(2);
+const stopThreshold = counter.on("thresholdReached", (event) => {
+  console.log(event.count);
+});
+
+counter.count;
+counter.doubled;
+counter.increment();
+stopThreshold();
+```
+
+- `count: counter` exposes the base state as a reactive immutable property.
+- `doubled` is a memoized reactive value exposed through `computed()`.
+- `increment()` is action-wrapped automatically, so the state update is batched and untracked.
+- `counter.on(...)` returns `stopThreshold`, which unsubscribes the event listener.
+
+## Define Reusable State
+
+Use `defineManagedState()` when you want a reusable managed-state class.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (counter: StateHandle<CounterState>) => ({
+    count: counter,
+    increment() {
+      counter.set((value) => value + 1);
+    },
+  }),
+  0,
+);
+```
+
+## Expose Base State
+
+Return the constructor handle when you want the base state to appear as a reactive immutable property.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (count: StateHandle<CounterState>) => ({
+    count,
+  }),
+  0,
+);
+
+new Counter().count;
+```
+
+## Memoize A Reactive Derivation
+
+Use `computed()` when you want a memoized reactive value on the public instance.
+
+```ts
+import { computed, defineManagedState, type StateHandle } from "preact-sigma";
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (counter: StateHandle<CounterState>) => ({
+    doubled: computed(() => counter.get() * 2),
+  }),
+  0,
+);
+
+new Counter().doubled;
+```
+
+## Create A Tracked Query Method
+
+Use `query()` when you want a public method whose reads stay tracked.
+Query functions read from closed-over handles or signals and do not use
+instance `this`.
+
+```ts
+import { defineManagedState, query, type StateHandle } from "preact-sigma";
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (counter: StateHandle<CounterState>) => ({
+    isPositive: query(() => counter.get() > 0),
+  }),
+  0,
+);
+
+new Counter().isPositive();
+```
+
+## Read Base State Without Tracking
+
+Use `handle.peek()` when you need the current base-state snapshot without creating a reactive dependency.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (counter: StateHandle<CounterState>) => ({
+    logNow() {
+      console.log(counter.peek());
+    },
+  }),
+  0,
+);
+```
+
+## Use Top-Level Lenses
+
+When the base state is object-shaped, the constructor handle exposes a shallow lens for each top-level property, and you can return that lens directly.
+
+```ts
+import { computed, defineManagedState, type StateHandle } from "preact-sigma";
+
+type SearchState = {
+  query: string;
+};
+
+const Search = defineManagedState(
+  (search: StateHandle<SearchState>) => ({
+    query: search.query,
+    trimmedQuery: computed(() => search.query.get().trim()),
+    setQuery(query: string) {
+      search.query.set(query);
+    },
+  }),
+  { query: "" },
+);
+
+new Search().query;
+```
+
+## Spread A Handle To Expose Top-Level Properties
+
+When the base state is object-shaped, spread the handle into the returned object to expose its current top-level lenses at once.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type SearchState = {
+  page: number;
+  query: string;
+};
+
+const Search = defineManagedState(
+  (search: StateHandle<SearchState>) => ({
+    ...search,
+    nextPage() {
+      search.page.set((page) => page + 1);
+    },
+  }),
+  { page: 1, query: "" },
+);
+
+const search = new Search();
+
+search.query;
+search.page;
+```
+
+## Compose Managed States
+
+Return another managed-state instance when you want to expose it unchanged as a property.
+Composed managed states are available through direct property access and whole-state snapshots.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type CounterState = number;
+
+const Counter = defineManagedState(
+  (count: StateHandle<CounterState>) => ({
+    count,
+    increment() {
+      count.set((value) => value + 1);
+    },
+  }),
+  0,
+);
+
+type DashboardState = {
+  ready: boolean;
+};
+
+const Dashboard = defineManagedState(
+  (dashboard: StateHandle<DashboardState>) => ({
+    dashboard,
+    counter: new Counter(),
+  }),
+  { ready: false },
+);
+
+new Dashboard().counter.increment();
+```
+
+## Own Resources And Dispose The Instance
+
+Use `handle.own()` to register cleanup functions or disposables, and call `.dispose()` when the managed state should release them.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type PollerState = {
+  ticks: number;
+};
+
+const Poller = defineManagedState(
+  (poller: StateHandle<PollerState>) => ({
+    ticks: poller.ticks,
+    start() {
+      const interval = window.setInterval(() => {
+        poller.ticks.set((ticks) => ticks + 1);
+      }, 1000);
+
+      poller.own([() => window.clearInterval(interval)]);
+    },
+  }),
+  { ticks: 0 },
+);
+
+const poller = new Poller();
+
+poller.start();
+poller.dispose();
+```
+
+## Update State
+
+Pass an Immer producer to `.set()` when your base state is object-shaped.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type SearchState = {
+  query: string;
+};
+
+const Search = defineManagedState(
+  (search: StateHandle<SearchState>) => ({
+    setQuery(query: string) {
+      search.set((draft) => {
+        draft.query = query;
+      });
+    },
+  }),
+  { query: "" },
+);
+```
+
+## Emit Events
+
+Use `.emit()` to publish a custom event with zero or one argument.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type TodoEvents = {
+  saved: [];
+  selected: [{ id: string }];
+};
+
+type TodoState = {};
+
+const Todo = defineManagedState(
+  (todo: StateHandle<TodoState, TodoEvents>) => ({
+    save() {
+      todo.emit("saved");
+    },
+    select(id: string) {
+      todo.emit("selected", { id });
+    },
+  }),
+  {},
+);
+```
+
+## Listen For Events
+
+Use `.on()` to subscribe to custom events from a managed state instance.
+
+```ts
+const todo = new Todo();
+
+const stopSaved = todo.on("saved", () => {
+  console.log("saved");
+});
+
+const stopSelected = todo.on("selected", (event) => {
+  console.log(event.id);
+});
+
+stopSaved();
+stopSelected();
+```
+
+## Read Signals From A Managed State
+
+Use `.get(key)` for one exposed signal-backed property or `.get()` for the whole public state signal.
+Keyed reads do not target composed managed-state properties.
+
+```ts
+const counter = new Counter();
+
+const countSignal = counter.get("count");
+const counterSignal = counter.get();
+
+countSignal.value;
+counterSignal.value.count;
+```
+
+## Peek At Public State
+
+Use `.peek(key)` for one exposed signal-backed property or `.peek()` for the whole public snapshot.
+Keyed peeks do not target composed managed-state properties.
+
+```ts
+const counter = new Counter();
+
+counter.peek("count");
+counter.peek();
+```
+
+## Subscribe To Public State
+
+Use `.subscribe(key, listener)` for one exposed signal-backed property or `.subscribe(listener)` for the whole public state.
+Listeners receive the current value immediately and then future updates.
+Keyed subscriptions do not target composed managed-state properties.
+
+```ts
+const counter = new Counter();
+
+const stopCount = counter.subscribe("count", (count) => {
+  console.log(count);
+});
+
+const stopState = counter.subscribe((value) => {
+  console.log(value.count);
+});
+
+stopCount();
+stopState();
+```
+
+## Use It Inside A Component
+
+Use `useManagedState()` when you want the same pattern directly inside a component.
+
+```tsx
+import { useManagedState, type StateHandle } from "preact-sigma";
+
+type SearchState = {
+  query: string;
+};
+
+function SearchBox() {
+  const search = useManagedState(
+    (search: StateHandle<SearchState>) => ({
+      query: search.query,
+      setQuery(query: string) {
+        search.query.set(query);
+      },
+    }),
+    () => ({ query: "" }),
+  );
+
+  return (
+    <input value={search.query} onInput={(event) => search.setQuery(event.currentTarget.value)} />
+  );
+}
+```
+
+## Subscribe In `useEffect`
+
+Use `useSubscribe()` with any subscribable source, including managed state and Preact signals.
+The listener receives the current value immediately and then future updates.
+
+```tsx
+import { useSubscribe } from "preact-sigma";
+
+useSubscribe(counter, (value) => {
+  console.log(value.count);
+});
+```
+
+## Listen To DOM Or Managed-State Events In `useEffect`
+
+Use `useEventTarget()` for either DOM events or managed-state events.
+
+```tsx
+import { useEventTarget } from "preact-sigma";
+
+useEventTarget(window, "resize", () => {
+  console.log(window.innerWidth);
+});
+```
+
+```tsx
+useEventTarget(counter, "thresholdReached", (event) => {
+  console.log(event.count);
+});
+```
+
+## Reach For Signals Helpers
+
+`batch` and `untracked` are re-exported from `@preact/signals`.
+
+```ts
+import { batch, untracked } from "preact-sigma";
+
+batch(() => {
+  counter.increment();
+  counter.reset();
+});
+
+untracked(() => {
+  console.log(counter.count);
+});
+```
+
+## Small Feature Model
+
+This pattern works well when a component or UI feature needs a small state model with a few public methods and derived values.
+
+```ts
+import { defineManagedState, type StateHandle } from "preact-sigma";
+
+type DialogState = boolean;
+
+const Dialog = defineManagedState(
+  (dialog: StateHandle<DialogState>) => ({
+    open: dialog,
+    show() {
+      dialog.set(true);
+    },
+    hide() {
+      dialog.set(false);
+    },
+  }),
+  false,
+);
+```
+
+Keep using plain `useState()` when the state is trivial.
+
+```tsx
+const [open, setOpen] = useState(false);
+```
+
+## License
+
+MIT. See [LICENSE-MIT](./LICENSE-MIT).

package/dist/index.d.mts

@@ -0,0 +1,215 @@
+import { ReadonlySignal, Signal, batch, computed, untracked } from "@preact/signals";
+import { Immutable, Producer } 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;
+};
+/**
+ * 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.
+ */
+type ManagedState<TState, TEvents extends EventsDefinition = EventsDefinition, TProps extends object = Record<string, unknown>> = AnyManagedState<TState, TEvents> & Immutable<TState> & TProps;
+/**
+ * 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.
+ */
+declare function query<TFunction extends (this: void, ...args: any[]) => any>(fn: TFunction): TFunction;
+/**
+ * Constructor-local access to one top-level property of an object-shaped base
+ * state.
+ *
+ * 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.
+ */
+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;
+};
+/**
+ * Constructor-local access to the base state.
+ *
+ * `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.
+ */
+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>;
+};
+/**
+ * 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>>;
+//#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>>;
+/**
+ * Clean encapsulation of complex UI 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.
+ */
+type SubscribeTarget<T> = {
+  subscribe: (listener: (value: T) => void) => () => void;
+};
+/**
+ * Subscribe to future values from a subscribable source inside `useEffect`.
+ *
+ * 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.
+ */
+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;
+/**
+ * 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.
+ */
+declare function useEventTarget<T extends EventTarget | AnyManagedState, TEvent extends InferEvent<T>>(target: T | null, name: TEvent, listener: InferEventListener<T, TEvent>): void;
+//#endregion
+export { AnyManagedState, EventsDefinition, Lens, ManagedState, StateConstructor, StateHandle, SubscribeTarget, batch, computed, defineManagedState, isManagedState, query, untracked, useEventTarget, useManagedState, useSubscribe };

package/dist/index.mjs

@@ -0,0 +1,301 @@
+import { Signal, action, batch, computed, computed as computed$1, signal, untracked } from "@preact/signals";
+import { castImmutable, freeze, produce } from "immer";
+import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+//#region src/internal.ts
+const lensKeys = /* @__PURE__ */ new WeakMap();
+const queryMethods = /* @__PURE__ */ new WeakSet();
+var StateContainer = class extends EventTarget {
+	_signals = /* @__PURE__ */ new Map();
+	_view = computed$1(() => ({ ...this }));
+	constructor(state, handle, props, dispose) {
+		super();
+		this.dispose = dispose;
+		const propDescriptors = Object.getOwnPropertyDescriptors(props);
+		for (const key in propDescriptors) {
+			const propDescriptor = propDescriptors[key];
+			if ("value" in propDescriptor) {
+				let { value } = propDescriptor;
+				if (typeof value === "function") {
+					Object.defineProperty(this, key, { value: queryMethods.has(value) ? value : action(value) });
+					continue;
+				}
+				const signal = getExposedSignal(value, state, handle);
+				if (signal) {
+					this._signals.set(key, signal);
+					Object.defineProperty(this, key, {
+						get: () => signal.value,
+						enumerable: true
+					});
+				} else if (isManagedState(value)) Object.defineProperty(this, key, {
+					value,
+					enumerable: true
+				});
+				else throw new Error(`Invalid property: ${key}. Must be a function, a signal, a top-level lens, the state handle, or a managed state.`);
+			} else throw new Error(`\`get ${key}() {}\` syntax is forbidden`);
+		}
+	}
+	get(key) {
+		if (!key) return this._view;
+		return this._signals.get(key);
+	}
+	peek(key) {
+		const signal = this.get(key);
+		if (!signal) return;
+		return signal.peek();
+	}
+	subscribe(...args) {
+		if (args.length > 1) {
+			const [key, listener] = args;
+			const signal = this.get(key);
+			if (!signal) throw new Error(`Property ${key} is not a signal`);
+			return signal.subscribe(listener);
+		}
+		return this._view.subscribe(args[0]);
+	}
+	on(name, listener) {
+		const adapter = (event) => {
+			const detail = event.detail;
+			if (detail === void 0) listener();
+			else listener(detail);
+		};
+		this.addEventListener(name, adapter);
+		return () => {
+			this.removeEventListener(name, adapter);
+		};
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+};
+function isProducer(value) {
+	return typeof value === "function";
+}
+function makeNonEnumerable(object, keys) {
+	for (const key of keys) Object.defineProperty(object, key, {
+		...Object.getOwnPropertyDescriptor(object, key),
+		enumerable: false
+	});
+}
+var AnyStateHandle = class {
+	constructor(state, emit, own) {
+		this.state = state;
+		this.emit = emit;
+		this.own = own;
+		makeNonEnumerable(this, ["emit", "own"]);
+	}
+	/** Read the current immutable base state. This read is tracked. */
+	get() {
+		return this.state.value;
+	}
+	/** Read the current immutable base state snapshot without tracking. */
+	peek() {
+		return this.state.peek();
+	}
+	/** Replace the base state, or update it with an Immer producer. */
+	set(value) {
+		this.state.value = isProducer(value) ? produce(this.state.value, value) : castImmutable(value);
+	}
+};
+function createStateHandle(state, emit, own) {
+	const handle = new AnyStateHandle(state, emit, own);
+	let lenses;
+	const getLensDescriptor = (key) => {
+		const currentState = state.value;
+		if (!isLensableState(currentState)) return;
+		return Reflect.getOwnPropertyDescriptor(currentState, key);
+	};
+	const getLens = (key) => {
+		let lens = (lenses ||= /* @__PURE__ */ new Map()).get(key);
+		if (!lens) {
+			lens = {
+				get: () => handle.get()[key],
+				set: (update) => {
+					handle.set((draft) => {
+						draft[key] = isProducer(update) ? produce(draft[key], update) : update;
+					});
+				}
+			};
+			lensKeys.set(lens, key);
+			lenses.set(key, lens);
+		}
+		return lens;
+	};
+	return new Proxy(handle, {
+		get(target, key, receiver) {
+			if (Reflect.has(target, key)) return Reflect.get(target, key, receiver);
+			if (!getLensDescriptor(key)) return;
+			return getLens(key);
+		},
+		ownKeys(_target) {
+			const currentState = state.value;
+			if (!isLensableState(currentState)) return [];
+			return Reflect.ownKeys(currentState);
+		},
+		getOwnPropertyDescriptor(_target, key) {
+			const lensDescriptor = getLensDescriptor(key);
+			if (!lensDescriptor) return;
+			return {
+				configurable: true,
+				enumerable: lensDescriptor.enumerable,
+				value: getLens(key),
+				writable: false
+			};
+		}
+	});
+}
+function isLensableState(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function getExposedSignal(value, state, handle) {
+	if (value === handle) return state;
+	if (value instanceof Signal) return value;
+	const lensKey = getLensKey(value);
+	if (lensKey !== void 0) return computed$1(() => state.value[lensKey]);
+}
+function getLensKey(value) {
+	if (!value || typeof value !== "object") return;
+	return lensKeys.get(value);
+}
+function disposeOwnedResources(resources) {
+	let errors;
+	for (let index = resources.length - 1; index >= 0; index -= 1) try {
+		const resource = resources[index];
+		if (typeof resource === "function") resource();
+		else resource[Symbol.dispose]();
+	} catch (error) {
+		errors ||= [];
+		errors.push(error);
+	}
+	if (errors) throw new AggregateError(errors, "Failed to dispose one or more resources");
+}
+/** Check whether a value is a managed-state instance. */
+function isManagedState(value) {
+	return value instanceof StateContainer;
+}
+//#endregion
+//#region src/framework.ts
+/**
+* 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.
+*/
+function query(fn) {
+	const wrapped = ((...args) => computed$1(() => fn(...args)).value);
+	queryMethods.add(wrapped);
+	return wrapped;
+}
+/**
+* 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.
+*/
+function defineManagedState(constructor, initialState) {
+	initialState = freeze(initialState);
+	return class extends StateContainer {
+		constructor(...params) {
+			const state = signal(initialState);
+			let owned;
+			let disposed = false;
+			const dispose = () => {
+				if (disposed) return;
+				disposed = true;
+				const current = owned;
+				owned = void 0;
+				if (!current) return;
+				disposeOwnedResources(current);
+			};
+			const handle = createStateHandle(state, (name, detail) => this.dispatchEvent(new CustomEvent(name, { detail })), (resources) => {
+				const nextResources = Array.isArray(resources) ? resources : [resources];
+				if (!nextResources.length) return;
+				if (disposed) disposeOwnedResources(nextResources);
+				else (owned ??= []).push(...nextResources);
+			});
+			const props = constructor(handle, ...params);
+			super(state, handle, props, dispose);
+		}
+	};
+}
+//#endregion
+//#region src/hooks.ts
+function isFunction(value) {
+	return typeof value === "function";
+}
+/**
+* Clean encapsulation of complex UI 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.
+*/
+function useManagedState(constructor, initialState) {
+	const managedState = useState(() => new (defineManagedState(constructor, isFunction(initialState) ? initialState() : initialState))())[0];
+	useEffect(() => () => managedState.dispose(), [managedState]);
+	return managedState;
+}
+/**
+* Subscribe to future values from a subscribable source inside `useEffect`.
+*
+* 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.
+*/
+function useSubscribe(target, listener) {
+	listener = useStableCallback(listener);
+	useEffect(() => target?.subscribe(listener), [target]);
+}
+/**
+* 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.
+*/
+function useEventTarget(target, name, listener) {
+	listener = useStableCallback(listener);
+	useEffect(() => {
+		if (!target) return;
+		if (isManagedState(target)) return target.on(name, listener);
+		target.addEventListener(name, listener);
+		return () => target.removeEventListener(name, listener);
+	}, [target, name]);
+}
+function useStableCallback(callback) {
+	const ref = useRef(callback);
+	ref.current = callback;
+	return useCallback((...params) => (0, ref.current)(...params), []);
+}
+//#endregion
+export { batch, computed, defineManagedState, isManagedState, query, untracked, useEventTarget, useManagedState, useSubscribe };

package/llms.txt

@@ -0,0 +1,302 @@
+# `preact-sigma` for LLMs
+
+## Glossary
+
+- `base state`: The private mutable state owned by one managed state definition. It may be any non-function value, including a primitive.
+- `public state`: The immutable data exposed on a managed state instance. It is derived from returned signals, returned top-level lenses, returned handles, and returned nested managed states.
+- `managed state`: An instance created by `defineManagedState()` or returned by `useManagedState()`. It exposes immutable public data, public methods, subscriptions, events, and disposal.
+- `manager class`: The class returned by `defineManagedState()`. Best practice is to name it with a `Manager` suffix.
+- `constructor`: The function passed to `defineManagedState()` or `useManagedState()`. It receives a typed `StateHandle`.
+- `handle`: The first constructor parameter. Its type must be `StateHandle<...>`. It is the private control surface for reading, writing, owning resources, and emitting.
+- `lens`: A constructor-local object for one top-level property of an object-shaped base state. A lens has `get()` and `set()`.
+- `signal`: A `ReadonlySignal` from `@preact/signals`.
+- `signal-backed public property`: A public property backed by a returned signal, returned lens, or returned handle. Keyed `get`, `peek`, and `subscribe` target only these properties.
+- `derived value`: A value computed from state rather than stored directly.
+- `public action`: A returned method intended to change state. Returned methods are action-wrapped by default.
+- `query method`: A returned method wrapped with `query()`. Query methods are tracked reads and are not action-wrapped.
+- `event map`: A type mapping event names to zero-or-one-argument tuples, for example `{ saved: []; selected: [{ id: string }] }`.
+- `cleanup`: A function of type `() => void`.
+- `disposable`: An object with a `[Symbol.dispose]()` method.
+- `owned resource`: A cleanup function or disposable registered through `handle.own()`.
+- `object-shaped state`: A base state that is a plain object. It is not a function, array, `Map`, or `Set`.
+- `top-level property`: A direct property on an object-shaped base state, such as `query` in `{ query: string }`.
+- `composition`: Returning one managed state instance from another managed state constructor so the nested instance is exposed unchanged as a public property.
+- `tracked read`: A read that participates in Signals tracking.
+- `untracked read`: A read that does not participate in Signals tracking.
+- `unsubscribe`: The cleanup function returned by `.on()` and `.subscribe()`.
+
+## Purpose
+
+`preact-sigma` is a small state-management layer built on top of `@preact/signals` and `immer`.
+
+It is designed to:
+
+- keep mutable implementation details private
+- expose immutable public data
+- express state transitions through public methods
+- support derived reactive values
+- support typed custom events
+- support composition of nested managed states
+- support instance-owned resource cleanup
+
+## Runtime Exports
+
+- `defineManagedState`
+- `useManagedState`
+- `useSubscribe`
+- `useEventTarget`
+- `isManagedState`
+- `query`
+- `computed`
+- `batch`
+- `untracked`
+
+## Public Type Exports
+
+- `ManagedState`
+- `StateConstructor`
+- `StateHandle`
+- `Lens`
+- `SubscribeTarget`
+
+## Core Rules
+
+- The first constructor parameter must be explicitly typed as `StateHandle<...>`.
+- The constructor should be side-effect free.
+- The constructor may return only:
+  - methods
+  - signals
+  - top-level lenses from the provided handle
+  - the provided handle itself
+  - a managed state instance
+- Event payloads may have zero or one argument only.
+- Returned methods are action-wrapped automatically unless wrapped with `query()`.
+- Returned signals and returned top-level lenses become tracked getter properties on the public instance.
+- Returning the handle exposes the full base state as one reactive immutable public property.
+- Returning a managed state instance exposes that nested managed state unchanged.
+- Keyed `get`, `peek`, and `subscribe` apply only to signal-backed public properties, not to composed managed-state properties.
+
+## `defineManagedState()`
+
+Use `defineManagedState(constructor, initialState)` to create a reusable managed-state class.
+
+Behavior:
+
+- `initialState` is the initial base state
+- constructor parameters after the handle become runtime constructor parameters for the class
+- internal state and event types are inferred from the typed `StateHandle` parameter
+- the resulting instance exposes immutable public data plus public methods
+- the resulting instance owns any resources registered through `handle.own()`
+
+## `useManagedState()`
+
+Use `useManagedState(constructor, initialState)` to create a managed state directly inside a component.
+
+Behavior:
+
+- follows the same constructor rules as `defineManagedState()`
+- accepts either a concrete initial state or a lazy initializer function
+- returns one stable managed state instance for the component
+
+## `StateHandle`
+
+`StateHandle<TState, TEvents>` is the constructor-local control surface.
+
+Methods:
+
+- `get()`: tracked read of the current immutable base state
+- `peek()`: untracked read of the current immutable base state
+- `set(next)`: replace the base state or update it with an Immer producer
+- `own(resources)`: attach cleanup functions or disposables to the managed state instance
+- `emit(name, arg?)`: emit a typed custom event with zero or one argument
+
+For object-shaped base state only:
+
+- each top-level property is available as a `Lens`
+- spreading the handle into the returned constructor object exposes all current top-level lenses as tracked public properties
+
+## `Lens`
+
+`Lens<T>` exists only on object-shaped `StateHandle`s.
+
+Methods:
+
+- `get()`: tracked read of that top-level property
+- `set(next)`: replace that property or update it with an Immer producer for that property
+
+Important:
+
+- lenses are constructor-local unless returned
+- returning one lens exposes one reactive public property
+- spreading an object-shaped handle exposes all current top-level lenses at once
+
+## `ManagedState`
+
+A managed state instance exposes:
+
+- immutable public data as normal properties
+- public methods returned by the constructor
+- subscription methods
+- event subscription methods
+- disposal methods
+
+Read APIs:
+
+- `get(key)`: return the underlying signal for one exposed signal-backed public property
+- `get()`: return the underlying signal for the whole public state
+- `peek(key)`: untracked read of one exposed signal-backed public property
+- `peek()`: untracked read of the whole public state
+
+Subscription APIs:
+
+- `subscribe(key, listener)`: subscribe to the current and future values of one exposed signal-backed public property
+- `subscribe(listener)`: subscribe to the current and future whole public state
+- both forms return an unsubscribe function
+
+Event API:
+
+- `on(name, listener)`: subscribe to one custom event
+- listener receives the emitted argument directly, or no argument at all
+- returns an unsubscribe function
+
+Disposal API:
+
+- `dispose()`: dispose the managed state instance and its owned resources
+- `[Symbol.dispose]()` does the same thing as `dispose()`
+
+## `query()`
+
+`query(fn)` marks a returned method as a tracked public read.
+
+Behavior:
+
+- wraps the method body in `computed()`
+- lets reads inside the method participate in Signals tracking after the method is exposed publicly
+- query functions read from closed-over handles or signals and do not use an instance receiver
+- skips the default `action()` wrapping step
+
+Use `query()` for public methods that conceptually answer a question.
+
+Do not use `query()` for ordinary mutating actions.
+
+## `computed`
+
+`computed` is re-exported from `@preact/signals`.
+
+Use it when a public derived value should be memoized and reactive.
+
+## `batch`
+
+`batch` is re-exported from `@preact/signals`.
+
+Use it when multiple state updates should be grouped into one reactive batch.
+
+## `untracked`
+
+`untracked` is re-exported from `@preact/signals`.
+
+Use it when code must read reactive values without subscribing to them.
+
+## `useSubscribe()`
+
+Use `useSubscribe(target, listener)` inside a component.
+
+Behavior:
+
+- accepts any subscribable target, including a managed state or a Preact signal
+- keeps the listener fresh automatically
+- calls the listener immediately with the current value, then with future updates
+- does not take a dependency array
+- accepts `null` to disable the subscription temporarily
+
+## `useEventTarget()`
+
+Use `useEventTarget(target, name, listener)` inside a component.
+
+Behavior:
+
+- accepts either a DOM-style `EventTarget` or a managed state
+- keeps the listener fresh automatically
+- does not take a dependency array
+- accepts `null` to disable the subscription temporarily
+- for managed-state events, the listener receives the emitted argument directly, or no argument at all
+
+## `isManagedState()`
+
+Use `isManagedState(value)` to check whether a value is a managed-state instance.
+
+## Supported Patterns
+
+- primitive base state
+- plain-object base state
+- Immer producer updates
+- lifecycle-owned cleanup via `handle.own()`
+- disposal via `dispose()` or `[Symbol.dispose]()`
+- reactive derived properties via returned signals
+- tracked read methods via `query()`
+- public exposure of one top-level property via a returned lens
+- public exposure of all top-level properties via `...handle`
+- public exposure of the whole base state via the returned handle
+- nested managed-state composition
+- keyed and whole-state signal access
+- keyed and whole-state snapshot access
+- keyed and whole-state subscriptions
+- typed custom events with zero or one argument
+- component-local managed state via `useManagedState`
+- hook-based subscriptions via `useSubscribe`
+- hook-based event subscriptions via `useEventTarget`
+
+## Unsupported Or Disallowed Patterns
+
+- function-valued base state
+- returning arbitrary plain objects from the constructor unless each returned property is one of the supported public shapes
+- multi-argument event payloads outside a single object payload
+- relying on untyped constructor parameters for state or event inference
+- using arrays, `Map`, or `Set` as object-shaped state for lens generation
+
+## Best Practices
+
+### Inference And Naming
+
+- Explicitly type the first constructor parameter as `StateHandle<...>`.
+- Prefer a `${ModelName}State` alias near the constructor, even for simple state.
+- Prefer a `${ModelName}Events` alias when events exist.
+- Name the class returned by `defineManagedState()` with a `Manager` suffix.
+- Name the handle like an instance of the state model, not a generic word like `state` or `value`.
+
+### State Shape And Exposure
+
+- Use top-level lenses for constructor-local reads and writes to top-level object fields.
+- Return one top-level lens when one public field should stay reactive.
+- Spread an object-shaped handle when the public managed state should mirror the base state's top-level shape.
+- Return the full handle only when the whole base state should be one public property.
+- Use `handle.own()` when the managed-state instance should control external cleanup.
+
+### Derivations
+
+- Prefer plain external derivation functions for ordinary derived values so unused helpers can be tree-shaken.
+- Use `computed(() => derive(handle.get()))` only when a derived value needs memoized reactive reads for performance.
+- Use `query()` for tracked public read methods.
+
+### Public API Design
+
+- Keep public actions domain-specific.
+- Prefer verbs like `save`, `submit`, `open`, `close`, and `rename` over low-level mutation names.
+- Avoid unnecessary binding. Public methods work through closure over the typed handle, not through `this`.
+- Keep nested features as separate managed states when they already have a clean public API.
+- Prefer explicit disposal when a managed state owns external resources.
+
+### Events
+
+- Keep events domain-specific.
+- Do not use generic event names like `changed` or `updated` for ordinary state observation.
+- When you need multiple event fields, wrap them in one object payload.
+
+## Example Interpretation Rules For Agents
+
+- If a snippet assigns `const stop = thing.on(...)`, `stop` is an unsubscribe function.
+- If a snippet assigns `const stop = thing.subscribe(...)`, `stop` is an unsubscribe function.
+- If a snippet calls `handle.own([...])`, those resources are released by `instance.dispose()` or `instance[Symbol.dispose]()`.
+- If a returned method is wrapped with `query()`, treat it as a tracked read, not a mutating action.
+- If a constructor returns `...handle`, treat each top-level object property as a public tracked property.
+- If a constructor returns `field: handle.someField`, treat `field` as a public tracked property whose value is the lens's current value, not as the lens object itself.

package/package.json

@@ -1,13 +1,47 @@
 {
   "name": "preact-sigma",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
+  "version": "1.0.0",
   "keywords": [],
-  "author": "",
   "license": "MIT",
-  "type": "commonjs"
-}
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alloc/preact-sigma.git"
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@preact/signals": "^2.8.2",
+    "immer": "^11.1.4",
+    "preact": "11.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@preact/preset-vite": "^2.10.5",
+    "@types/node": "^25.5.0",
+    "jsdom": "^29.0.1",
+    "lucide-react": "^1.6.0",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "preact-sigma": "link:",
+    "tsdown": "^0.21.4",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.2",
+    "vitest": "^4.1.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
+    "fmt": "oxfmt",
+    "lint": "oxlint"
+  }
+}

package/readme.md

@@ -1 +0,0 @@
-Coming soon...