preact-sigma 5.0.0 → 6.0.1

package/dist/sigma-DTMODzf8.mjs

@@ -0,0 +1,457 @@
+import { action, batch, computed, signal } from "@preact/signals";
+import { createDraft as createDraft$1, finishDraft, freeze, isDraft, isDraftable, original, setAutoFreeze as setAutoFreeze$1 } from "immer";
+//#region src/internal/symbols.ts
+const instanceSymbol = Symbol.for("sigma:instance");
+const listenersSymbol = Symbol.for("sigma:listeners");
+const snapshotSymbol = Symbol.for("sigma:snapshot");
+//#endregion
+//#region src/internal/listener.ts
+/** Listener registry used by sigma targets and sigma states for typed event delivery. */
+var SigmaListenerMap = class extends Map {
+	/** Delivers one event payload to the current listeners for `name`. */
+	emit(name, detail) {
+		const listeners = this.get(name);
+		if (!listeners?.size) return;
+		for (const listener of [...listeners]) listener(detail);
+	}
+	/** Adds one listener for `name`, creating the listener set on first use. */
+	addListener(name, listener) {
+		let listeners = this.get(name);
+		if (!listeners) {
+			listeners = /* @__PURE__ */ new Set();
+			this.set(name, listeners);
+		}
+		listeners.add(listener);
+	}
+	/** Removes one listener for `name` and prunes the empty listener set. */
+	removeListener(name, listener) {
+		const listeners = this.get(name);
+		if (!listeners) return;
+		listeners.delete(listener);
+		if (!listeners.size) this.delete(name);
+	}
+};
+//#endregion
+//#region src/internal/utils.ts
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function isPromiseLike(value) {
+	return value != null && typeof value.then === "function";
+}
+//#endregion
+//#region src/sigma.ts
+let autoFreezeEnabled = true;
+/**
+* Configures Immer auto-freezing for values published through sigma state.
+*
+* Auto-freezing is enabled by default, so draftable public values are deeply frozen after publish.
+*/
+function setAutoFreeze(autoFreeze) {
+	setAutoFreeze$1(autoFreeze);
+	autoFreezeEnabled = autoFreeze;
+}
+const signalSuffix = "$";
+const changeListenersMap = /* @__PURE__ */ new WeakMap();
+const patchListeners = /* @__PURE__ */ new WeakSet();
+const initializedPrototypes = /* @__PURE__ */ new WeakSet();
+const queries = /* @__PURE__ */ new WeakSet();
+const emptySentinel = {};
+let activeActionInstance = null;
+let activeDraftInstance = null;
+let activeDraft;
+let activeDerivedReadDepth = 0;
+let activeSetupInstance = null;
+const pendingAsyncActions = /* @__PURE__ */ new WeakMap();
+function hasPendingAsyncAction(instance) {
+	return pendingAsyncActions.has(instance);
+}
+function addPendingAsyncAction(instance) {
+	pendingAsyncActions.set(instance, (pendingAsyncActions.get(instance) ?? 0) + 1);
+}
+function removePendingAsyncAction(instance) {
+	const count = pendingAsyncActions.get(instance);
+	if (!count) return;
+	if (count === 1) pendingAsyncActions.delete(instance);
+	else pendingAsyncActions.set(instance, count - 1);
+}
+function hasActionContext(instance) {
+	if (activeActionInstance) return activeActionInstance === instance;
+	return hasPendingAsyncAction(instance);
+}
+function createExternalActionError() {
+	const constructorName = (activeDraftInstance ?? activeActionInstance)?.constructor.name;
+	const owner = constructorName ? `Draft for ${constructorName}` : "Draft";
+	return /* @__PURE__ */ new Error(`[preact-sigma] ${owner} was not committed before an external action was invoked.`);
+}
+function beginActionContext(instance) {
+	if (!activeActionInstance) {
+		if (activeDraftInstance && activeDraftInstance !== instance) throw createExternalActionError();
+		activeActionInstance = instance;
+		return false;
+	}
+	if (instance !== activeActionInstance) throw createExternalActionError();
+	return true;
+}
+function endActionContext(instance) {
+	if (activeActionInstance === instance) activeActionInstance = null;
+}
+function clearActiveAction() {
+	activeActionInstance = null;
+	activeDraftInstance = null;
+	activeDraft = null;
+}
+function assertActionContext(instance, message) {
+	if (activeActionInstance && activeActionInstance !== instance) throw createExternalActionError();
+	if (!hasActionContext(instance)) throw new Error(message);
+}
+function isStateKey(instance, key) {
+	return Object.hasOwn(instance, key + signalSuffix);
+}
+function getStateSignal(instance, key) {
+	return instance[key + signalSuffix];
+}
+function createSnapshot(instance) {
+	if (instance[snapshotSymbol]) return instance[snapshotSymbol];
+	const state = {};
+	for (const key in instance) if (isStateKey(instance, key)) state[key] = getStateSignal(instance, key).value;
+	return state;
+}
+function createDraft(instance) {
+	return createDraft$1(createSnapshot(instance));
+}
+function ensureDraft(instance) {
+	if (activeDraftInstance && activeDraftInstance !== instance) throw createExternalActionError();
+	activeDraftInstance = instance;
+	activeDraft ??= createDraft(instance);
+	return activeDraft;
+}
+function readStateProperty(instance, key) {
+	const signal = getStateSignal(instance, key);
+	if (!activeDerivedReadDepth && hasActionContext(instance)) {
+		if (activeDraftInstance === instance) return activeDraft[key];
+		if (isDraftable(signal.value)) return ensureDraft(instance)[key];
+	}
+	return signal.value;
+}
+function writeStateProperty(instance, key, value) {
+	assertActionContext(instance, `[preact-sigma] Cannot set state property "${key}" outside an action.`);
+	ensureDraft(instance)[key] = value;
+}
+function runDerivedRead(callback) {
+	activeDerivedReadDepth += 1;
+	try {
+		return callback();
+	} finally {
+		activeDerivedReadDepth -= 1;
+	}
+}
+function assertActionResult(key, result) {
+	if (isDraft(result)) throw new Error(`[preact-sigma] Action named "${key}" returned an active draft.`);
+}
+function hasPatchListeners(instance) {
+	const listeners = changeListenersMap.get(instance);
+	if (!listeners) return false;
+	for (const sub of listeners) if (patchListeners.has(sub)) return true;
+	return false;
+}
+function publishState(instance, nextState, baseState, patches, inversePatches) {
+	instance[snapshotSymbol] = nextState;
+	batch(() => {
+		const missingKeys = new Set(Object.keys(baseState));
+		for (const key in nextState) {
+			const nextValue = nextState[key];
+			if (autoFreezeEnabled) freeze(nextValue, true);
+			const signal = getStateSignal(instance, key);
+			if (signal) signal.value = nextValue;
+			else defineSignalProperty(instance, key, nextValue);
+			missingKeys.delete(key);
+		}
+		for (const key of missingKeys) {
+			const signal = getStateSignal(instance, key);
+			if (signal) signal.value = void 0;
+		}
+	});
+	changeListenersMap.get(instance)?.forEach((listener) => {
+		listener(nextState, baseState, patches, inversePatches);
+	});
+}
+function getActionInstance(context) {
+	return context[instanceSymbol];
+}
+function commitDraft(instance) {
+	if (activeDraftInstance && instance !== activeDraftInstance) throw createExternalActionError();
+	if (!activeDraft) return false;
+	const draft = activeDraft;
+	activeDraft = null;
+	activeDraftInstance = null;
+	let patches;
+	let inversePatches;
+	let patchListener;
+	if (hasPatchListeners(instance)) patchListener = (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	};
+	const baseState = original(draft);
+	const nextState = finishDraft(draft, patchListener);
+	const changed = baseState !== nextState;
+	if (changed) publishState(instance, nextState, baseState, patches, inversePatches);
+	return changed;
+}
+function hasStateChanges(baseState, nextState) {
+	const baseKeys = Object.keys(baseState);
+	const nextKeys = Object.keys(nextState);
+	if (baseKeys.length !== nextKeys.length) return true;
+	for (const key of nextKeys) if (!Object.hasOwn(baseState, key) || !Object.is(baseState[key], nextState[key])) return true;
+	return false;
+}
+function createReplacementPatches(baseState, nextState) {
+	let patches;
+	let inversePatches;
+	const draft = createDraft$1(baseState);
+	const missingKeys = new Set(Object.keys(baseState));
+	for (const key in nextState) {
+		draft[key] = nextState[key];
+		missingKeys.delete(key);
+	}
+	for (const key of missingKeys) delete draft[key];
+	finishDraft(draft, (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	});
+	return {
+		inversePatches,
+		patches
+	};
+}
+function initializePrototype(prototype) {
+	const descriptors = Object.getOwnPropertyDescriptors(prototype);
+	for (const key in descriptors) {
+		if (key === "constructor" || key === "onSetup") continue;
+		const { get, value } = descriptors[key];
+		if (get) descriptors[key].get = function() {
+			const instance = getActionInstance(this);
+			return (instance[key + signalSuffix] ??= computed(() => runDerivedRead(() => get.call(instance)))).value;
+		};
+		else if (typeof value === "function" && !queries.has(value)) {
+			const actionFn = action(value);
+			descriptors[key].value = function(...args) {
+				if (activeDerivedReadDepth) throw new Error("[preact-sigma] Computeds and queries cannot call actions.");
+				const instance = getActionInstance(this);
+				if (beginActionContext(instance)) {
+					const result = value.apply(instance, args);
+					assertActionResult(key, result);
+					return result;
+				}
+				let result;
+				try {
+					result = actionFn.apply(instance, args);
+					assertActionResult(key, result);
+				} catch (error) {
+					clearActiveAction();
+					throw error;
+				}
+				let changed;
+				try {
+					changed = commitDraft(instance);
+				} catch (error) {
+					clearActiveAction();
+					throw error;
+				}
+				if (isPromiseLike(result)) {
+					if (changed) {
+						endActionContext(instance);
+						throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before returning a promise.`);
+					}
+					addPendingAsyncAction(instance);
+					endActionContext(instance);
+					const onResolveAsyncAction = (promiseResult) => {
+						try {
+							if (activeDraft && instance === activeDraftInstance) {
+								if (commitDraft(instance)) throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before its promise resolved.`);
+							}
+							return promiseResult;
+						} finally {
+							removePendingAsyncAction(instance);
+						}
+					};
+					const onRejectAsyncAction = (error) => {
+						if (activeDraftInstance === instance) {
+							activeDraft = null;
+							activeDraftInstance = null;
+						}
+						removePendingAsyncAction(instance);
+						throw error;
+					};
+					return result.then(onResolveAsyncAction, onRejectAsyncAction);
+				}
+				endActionContext(instance);
+				return result;
+			};
+		}
+	}
+	Object.defineProperties(prototype, descriptors);
+}
+function initializeType(type) {
+	for (let prototype = type.prototype; prototype && prototype !== Sigma.prototype && prototype !== SigmaTarget.prototype; prototype = Object.getPrototypeOf(prototype)) {
+		if (initializedPrototypes.has(prototype)) break;
+		initializePrototype(prototype);
+		initializedPrototypes.add(prototype);
+	}
+}
+function disposeCleanupResource(resource) {
+	if (typeof resource === "function") resource();
+	else if ("dispose" in resource) resource.dispose();
+	else resource[Symbol.dispose]();
+}
+function defineSignalProperty(instance, key, value) {
+	Object.defineProperty(instance, key + signalSuffix, { value: signal(value) });
+	if (!Object.hasOwn(instance.constructor.prototype, key)) Object.defineProperty(instance.constructor.prototype, key, {
+		get() {
+			return readStateProperty(this, key);
+		},
+		set(value) {
+			writeStateProperty(this, key, value);
+		},
+		enumerable: true
+	});
+}
+/**
+* Base class for signal-backed state models.
+*
+* `TState` is the source of typing for top-level state keys, subscriptions, signals, and replacement snapshots.
+* Private class fields stay ordinary instance storage and are not signal-backed, captured, or persisted.
+* Merge a same-named interface with the class when direct property reads should be typed on the instance.
+*/
+var Sigma = class {
+	get [instanceSymbol]() {
+		return this;
+	}
+	constructor(initialState) {
+		initializeType(this.constructor);
+		if (initialState === emptySentinel) return;
+		for (const key in initialState) {
+			const initialValue = initialState[key];
+			if (autoFreezeEnabled) freeze(initialValue, true);
+			defineSignalProperty(this, key, initialValue);
+		}
+	}
+	/** Runs `onSetup(...)` and returns a cleanup that disposes returned resources in reverse order. */
+	setup(...args) {
+		const instance = getActionInstance(this);
+		const previousSetupInstance = activeSetupInstance;
+		activeSetupInstance = instance;
+		let resources;
+		try {
+			resources = this.onSetup.apply(instance, args);
+		} finally {
+			activeSetupInstance = previousSetupInstance;
+		}
+		return () => {
+			for (let i = resources.length - 1; i >= 0; i--) disposeCleanupResource(resources[i]);
+		};
+	}
+	/**
+	* Publishes the current action draft.
+	*
+	* Use this before unpublished changes cross an async, event, or external-action boundary.
+	* A callback runs after publish in an action context.
+	*/
+	commit(callback) {
+		const instance = getActionInstance(this);
+		assertActionContext(instance, "Cannot commit() from outside an action.");
+		commitDraft(instance);
+		if (callback) return callback.call(instance);
+	}
+	/** Runs a synchronous setup-owned callback with action semantics from an `onSetup(...)` context. */
+	act(fn) {
+		const instance = getActionInstance(this);
+		if (activeSetupInstance !== instance) throw new Error("Cannot act() from outside an onSetup() context.");
+		if (activeActionInstance === instance) throw new Error("Cannot act() from inside an action.");
+		beginActionContext(instance);
+		try {
+			if (isPromiseLike(action(fn).call(instance))) throw new Error("[preact-sigma] act() callbacks must be synchronous");
+			commitDraft(instance);
+		} catch (error) {
+			clearActiveAction();
+			throw error;
+		}
+		endActionContext(instance);
+	}
+};
+/** Casts a sigma instance to its readonly public consumer view. */
+function castProtected(instance) {
+	return instance;
+}
+/**
+* Sigma state model that can emit typed events.
+*
+* `TEvents` maps event names to payload types, and `TState` types reactive state.
+*/
+var SigmaTarget = class extends Sigma {
+	[listenersSymbol] = new SigmaListenerMap();
+	constructor(state) {
+		super(state ?? emptySentinel);
+	}
+	/** Emits a typed event from an action after unpublished draft changes are committed. */
+	emit(name, ...[detail]) {
+		const instance = getActionInstance(this);
+		assertActionContext(instance, "Cannot emit() from outside an action.");
+		if (instance === activeDraftInstance && activeDraft) throw new Error("Cannot emit() until you commit() your draft.");
+		this[listenersSymbol].emit(name, detail);
+	}
+};
+/** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
+const sigma = /* @__PURE__ */ Object.freeze({
+	subscribe: ((instance, keyOrListener, listenerOrOptions) => {
+		if (typeof keyOrListener === "string") {
+			const signal = getStateSignal(instance, keyOrListener);
+			if (!signal) throw new Error(`[preact-sigma] Property named "${keyOrListener}" is not signal-backed.`);
+			return signal.subscribe(listenerOrOptions);
+		}
+		const listener = keyOrListener;
+		if (listenerOrOptions?.patches) patchListeners.add(listener);
+		let subscriptions = changeListenersMap.get(instance);
+		if (!subscriptions) {
+			subscriptions = /* @__PURE__ */ new Set();
+			changeListenersMap.set(instance, subscriptions);
+		}
+		subscriptions.add(listener);
+		return () => {
+			subscriptions.delete(listener);
+			if (!subscriptions.size) changeListenersMap.delete(instance);
+		};
+	}),
+	getSignal(instance, key) {
+		return getStateSignal(instance, key);
+	},
+	captureState(instance) {
+		return Object.freeze(createSnapshot(instance));
+	},
+	replaceState(target, nextState) {
+		if (!isPlainObject(nextState)) throw new Error("[preact-sigma] replaceState() requires a plain object snapshot");
+		if (activeDraft) throw new Error(`[preact-sigma] replaceState() cannot run while an action has unpublished changes.`);
+		const instance = getActionInstance(target);
+		const baseState = createSnapshot(instance);
+		if (!hasStateChanges(baseState, nextState)) return;
+		const { inversePatches, patches } = hasPatchListeners(instance) ? createReplacementPatches(baseState, nextState) : {
+			inversePatches: void 0,
+			patches: void 0
+		};
+		publishState(instance, nextState, baseState, patches, inversePatches);
+	}
+});
+/** Marks a class method as a committed-state reactive read with arguments instead of an action. */
+function query(method) {
+	queries.add(method);
+	function queryMethod(...args) {
+		const instance = getActionInstance(this);
+		return computed(() => runDerivedRead(() => method.apply(instance, args))).value;
+	}
+	queries.add(queryMethod);
+	return queryMethod;
+}
+//#endregion
+export { setAutoFreeze as a, listenersSymbol as c, query as i, SigmaTarget as n, sigma as o, castProtected as r, isPlainObject as s, Sigma as t };

package/docs/context.md

@@ -1,12 +1,12 @@
 # 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. For event-only flows, `SigmaTarget` provides a standalone typed event hub with no managed state.
+`preact-sigma` builds reusable state models as TypeScript classes. A `Sigma<TState>` subclass owns top-level state, derived reads, writes, and setup. A `SigmaTarget<TEvents, TState>` subclass adds typed events. Each top-level state key is exposed as a reactive public property backed by a Preact signal, while actions use Immer-style mutation semantics to publish committed state.
 
 # When to Use
 
 - State, derived reads, mutations, and lifecycle need to stay together.
-- You need multiple instances of the same model.
-- Public reads should stay reactive and readonly while writes stay explicit.
+- You need multiple instances of the same model class.
+- Public reads should stay reactive while writes stay explicit.
 - A model needs to own timers, subscriptions, listeners, nested setup, or other cleanup-aware resources.
 - Components should consume the same model shape used outside Preact.
 
@@ -19,105 +19,115 @@
 
 # Core Abstractions
 
-- 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)`.
-- Action: a method declared with `.actions(...)` that reads and writes through sigma's draft and commit semantics.
-- Setup handler: a function declared with `.setup(...)` that owns side effects and cleanup resources explicitly.
-- Event: a typed notification emitted through `this.emit(...)` and observed through `listen(...)` or `useListener(...)`.
+- Sigma class: a class that extends `Sigma<TState>` and passes its initial top-level state to `super(...)`. The `TState` argument drives helper typing for subscriptions, signals, and replacement snapshots; a same-named merged interface gives direct property reads their instance types.
+- Sigma target: a class that extends `SigmaTarget<TEvents, TState>` when it also emits typed events. Use `SigmaTarget<TEvents>` for event-only targets.
+- State property: a top-level key from `TState`. Each key becomes a reactive public property and has its own signal.
+- Private field: an ECMAScript `#field` on the model class. Private fields are ordinary instance storage, not signal-backed state.
+- Computed: an argument-free derived getter on the class prototype that reads committed state.
+- Query: a reactive read method that accepts arguments, is marked with the `query` decorator, and reads committed state.
+- Action: a prototype method that is not marked as a query. Actions read and write state properties through sigma's draft and commit semantics.
+- Setup handler: an optional `onSetup(...)` method that owns side effects and returns cleanup resources.
+- Event: a typed notification emitted with `this.emit(...)` inside an action and observed through `listen(...)` or `useListener(...)`.
+- Protected view: the readonly consumer view returned by `castProtected(...)` and `useSigma(...)`.
 
 # Data Flow / Lifecycle
 
-1. Define a sigma type with `new SigmaType<TState, TEvents>()`. Let later builder methods infer names and types from the objects you pass to them.
-2. Add `defaultState(...)` for top-level public state and optional per-instance initializers.
-3. Add `computed(...)`, `queries(...)`, and `actions(...)` for derived reads and writes.
-4. Instantiate the configured type. Constructor input shallowly overrides `defaultState(...)`.
+1. Define a class that extends `Sigma<TState>` or `SigmaTarget<TEvents, TState>`.
+2. Define the state as a named type, pass it to `Sigma<TState>`, then merge `interface Model extends ModelState {}` after the class so direct property reads are typed.
+3. Add getters for computed values, `@query` methods for argument-based reactive reads, and ordinary methods for actions.
+4. Instantiate the class. Constructor input can be merged with defaults before `super(...)` when instances need partial overrides.
 5. Read state, computeds, and queries reactively from the public instance.
-6. Mutate state inside actions. Sync nested actions on the same instance share one draft. Boundaries like `await`, `emit(...)`, or separate action invocations may require `this.commit()` before the boundary.
-7. Run `setup(...)` explicitly when the instance should start owning side effects. `useSigma(...)` does this automatically for component-owned instances that define setup.
+6. Mutate state inside actions. Synchronous actions publish automatically when they return, and sync nested actions on the same instance share one draft. Computeds and queries still read the last committed state while an action has unpublished draft changes. Call `this.commit()` when derived reads or unpublished changes must cross a boundary, such as before an `await`, before the action promise resolves, before `emit(...)`, or before invoking another instance's action.
+7. Run `setup(...)` explicitly when the instance should start owning side effects. `useSigma(...)` does this automatically for component-owned instances that define `onSetup(...)`.
 8. Dispose the cleanup returned from `setup(...)` when the owned resources should stop.
 
 # Common Tasks -> Recommended APIs
 
-- Define reusable model state: `new SigmaType<TState, TEvents>().defaultState(...)`
-- Derive an argument-free value: `.computed(...)`
-- Derive a reactive read with arguments: `.queries(...)`
-- Keep a tracked helper local to one consumer module: `query(fn)`
-- Mutate state and emit typed notifications: `.actions(...)`
-- Publish before `await`, `emit(...)`, or another action boundary: `this.commit()`
-- React to committed state changes: `sigma.subscribe(instance, handler)` or `sigma.subscribe(instance, key, handler)`
-- Read one top-level state property or computed as a `ReadonlySignal`: `sigma.getSignal(instance, key)`
-- 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 `listen(hub, ...)`
-- Subscribe outside components: `listen(instance, ...)`
-- Read or restore committed top-level state: `sigma.getState(...)` and `sigma.replaceState(...)`
+- Define reusable model state: `class Model extends Sigma<TState>`.
+- Define reusable model state with events: `class Model extends SigmaTarget<TEvents, TState>`.
+- Merge partial constructor input with defaults: `mergeDefaults(initial, defaults)`.
+- Derive an argument-free value: a class getter.
+- Derive a reactive read with arguments: an `@query` class method.
+- Mutate state and emit typed notifications: ordinary class methods plus `this.emit(...)`.
+- Publish unpublished changes before `await`, `emit(...)`, promise resolution, or another instance's action: `this.commit()`.
+- React to committed state changes: `sigma.subscribe(instance, handler)` or `sigma.subscribe(instance, key, handler)`.
+- Read one top-level state property as a `ReadonlySignal`: `sigma.getSignal(instance, key)`.
+- Own timers, listeners, subscriptions, or nested setup: `onSetup(...)` plus `setup(...)`.
+- Use a sigma instance inside a component: `useSigma(...)`.
+- Cast an instance to its readonly consumer view outside a component: `castProtected(instance)`.
+- Subscribe to sigma or DOM events in a component: `useListener(...)`.
+- Subscribe outside components: `listen(instance, ...)`.
+- Read or restore committed top-level state: `sigma.captureState(...)` and `sigma.replaceState(...)`.
 
 # Recommended Patterns
 
-- Put explicit type arguments on `new SigmaType<TState, TEvents>()` and let later builder methods infer from the objects you pass.
+- Put the state shape in a named `State` type, pass it to `Sigma<TState>` or `SigmaTarget<TEvents, TState>`, then merge a same-named interface with the class for direct property typing.
 - Keep frequently read values as separate top-level state properties. Each top-level key gets its own signal.
-- Use `.computed(...)` for argument-free derived reads.
-- Use `.queries(...)` for tracked reads with arguments.
-- Keep one-off calculations local until they become reusable model behavior.
-- Use ordinary actions for routine writes. Reserve `sigma.getState(...)` and `sigma.replaceState(...)` for replay, reset, or undo-like flows on committed top-level state.
-- Prefer `listen(...)` for external event subscriptions. It works with sigma states, `SigmaTarget`, and DOM targets.
-- Put owned side effects in `.setup(...)`.
-- Use `sigma.subscribe(this, ...)` inside `.setup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
+- Use private fields for ephemeral caches, handles, or bookkeeping that should not be captured, restored, persisted, or used as subscription keys.
+- Use getters for argument-free derived reads.
+- Use `@query` for tracked reads with arguments.
+- Derive directly from state properties inside an action when the calculation needs unpublished draft values.
+- Use ordinary actions for routine writes. Reserve `sigma.captureState(...)` and `sigma.replaceState(...)` for replay, reset, restore, or undo-like flows on committed top-level state.
+- Emit directly from actions that have no unpublished draft changes. After mutating state, publish first with `this.commit(); this.emit(...)`.
+- Prefer `listen(...)` for external event subscriptions. It works with sigma targets and DOM targets.
+- Put owned side effects in `onSetup(...)`.
+- Use `sigma.subscribe(this, ...)` inside `onSetup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
   ```ts
-  .setup(function () {
+  onSetup() {
     return [
-      sigma.subscribe(this, (change) => {
-        console.log(change.newState);
+      sigma.subscribe(this, (nextState, baseState) => {
+        console.log(baseState, nextState);
       }),
     ];
-  })
+  }
   ```
 - Use `this.act(function () { ... })` for setup-owned callbacks that need action semantics.
 
 # Patterns to Avoid
 
 - Reaching for `sigma.getSignal(instance, key)` when direct property reads already cover the use case.
-- Crossing `emit(...)`, `await`, or another action boundary with unpublished changes when those changes need to stay visible afterward. Publish them first with `this.commit()`.
+- Crossing `emit(...)`, `await`, promise resolution, or another instance's action with unpublished changes. Publish them first with `this.commit()`.
 - Starting side effects during construction instead of through explicit `setup(...)`.
-- Encoding storage, hydration, or migration policy directly into `SigmaType` definitions.
+- Encoding storage, hydration, or migration policy directly into model classes.
+- Relying on computeds or queries to observe unpublished draft changes inside actions.
 - Treating query calls as memoized across invocations.
 - Relying on patch payloads without enabling Immer patches first.
 
 # Invariants and Constraints
 
-- Sigma only tracks top-level state properties. Each top-level key gets its own signal.
-- Public state is readonly outside actions and `this.act(...)` inside setup.
-- Duplicate names across state properties, computeds, queries, and actions are rejected at runtime. Reserved public names include `act`, `commit`, `emit`, and `setup`.
+- Sigma tracks top-level state properties. Each top-level key gets its own signal.
+- Private fields are not top-level state properties. They do not create signals, appear in committed snapshots, participate in persistence helpers, or drive subscriptions by themselves.
+- Protected consumer views expose immutable state and callable actions.
+- Published draftable public state is deep-frozen by default. `setAutoFreeze(false)` disables that behavior globally.
+- Computeds and queries read committed state, including when called inside actions.
 - Query calls are reactive at the call site but do not memoize across invocations.
 - Setup handlers return arrays of cleanup resources, and cleanup runs in reverse order.
 - Call Immer's `enablePatches()` before relying on `sigma.subscribe(instance, handler, { patches: true })`.
-- `sigma.replaceState(...)` works on committed top-level state and requires the exact state-key shape.
-- Published draftable public state is deep-frozen by default. `setAutoFreeze(false)` disables that behavior globally.
+- `sigma.replaceState(...)` works on committed top-level state and requires a plain object snapshot.
+- `SigmaTarget.emit(...)` runs from an action and requires no active unpublished draft. It does not need a `commit(...)` callback.
 
 # Error Model
 
 - Crossing an action boundary with unpublished changes throws until `this.commit()` publishes them. Async actions also reject when they finish with unpublished changes.
-- If another invocation crosses a boundary while unpublished changes still exist, sigma warns and discards those changes before continuing.
-- Calling `setup(...)` on a sigma state without registered setup handlers throws.
-- Cleanup rethrows an `AggregateError` when more than one cleanup resource fails.
-- `sigma.replaceState(...)` throws when the replacement value is not a plain object, has the wrong top-level keys, or runs while an action still owns unpublished changes.
+- Calling `commit(...)` outside an action throws.
+- Calling `act(...)` outside an `onSetup(...)` setup context throws.
+- Calling `emit(...)` outside an action or before committing the active draft throws.
+- Calling an action from a computed or query throws.
+- Returning an active draft from an action throws.
+- `sigma.replaceState(...)` throws when the replacement value is not a plain object or when an action still owns unpublished changes.
+- Starting an action on another sigma instance while the current instance has an active action context throws.
 
 # Terminology
 
 - Draft boundary: a point where sigma cannot keep reusing the current unpublished draft.
 - Committed state: the published top-level public state visible outside the current action draft.
-- Signal access: reading the underlying `ReadonlySignal` for a top-level state key or computed through `sigma.getSignal(instance, key)`.
-- Cleanup resource: a cleanup function, `AbortController`, object with `dispose()`, or object with `[Symbol.dispose]()`.
+- Signal access: reading the underlying `ReadonlySignal` for a top-level state key through `sigma.getSignal(instance, key)`.
+- Cleanup resource: a cleanup function, object with `dispose()`, or object with `[Symbol.dispose]()`.
 - Nested sigma state: a sigma-state instance stored in top-level state as a value; it stays usable as a value rather than exposing its internals through parent actions.
 
 # Non-Goals
 
-- Replacing every plain-signal use case with a builder abstraction.
+- Replacing every plain-signal use case with a class abstraction.
 - Hiding lifecycle behind implicit setup or constructor side effects.
 - Memoizing every query call or turning queries into a global cache.
 - Acting as a large tutorial framework or hand-maintained API reference. Exact signatures come from declaration output, and factual behavior lives beside source.