preact-sigma 3.1.0 → 5.0.0

package/dist/runtime-nX4Aygb8.mjs

@@ -0,0 +1,595 @@
+import { batch, computed, signal, untracked } from "@preact/signals";
+import * as immer from "immer";
+//#region src/internal/symbols.ts
+const sigmaStateBrand = Symbol("sigma.state");
+const sigmaTargetBrand = Symbol("sigma.target");
+const reservedKeys = new Set([
+	"act",
+	"emit",
+	"commit",
+	"setup"
+]);
+//#endregion
+//#region src/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);
+	}
+};
+/**
+* A standalone typed event hub with `emit(...)` and `on(...)` methods.
+*
+* `SigmaTarget` also works with `listen(...)` and `useListener(...)`.
+*/
+var SigmaTarget = class {
+	[sigmaTargetBrand] = new SigmaListenerMap();
+	/**
+	* Emits a typed event from the hub.
+	*
+	* Void events notify listeners with `undefined`. Payload events pass their
+	* payload directly to listeners.
+	*/
+	emit(name, ...[detail]) {
+		this[sigmaTargetBrand].emit(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) {
+		this[sigmaTargetBrand].addListener(name, listener);
+		return () => {
+			this[sigmaTargetBrand].removeListener(name, listener);
+		};
+	}
+};
+function listen(target, name, listener) {
+	if (Object.hasOwn(target, sigmaTargetBrand)) {
+		const sigmaTarget = target;
+		sigmaTarget[sigmaTargetBrand].addListener(name, listener);
+		return () => {
+			sigmaTarget[sigmaTargetBrand].removeListener(name, listener);
+		};
+	}
+	const eventTarget = target;
+	const eventListener = listener;
+	eventTarget.addEventListener(name, eventListener);
+	return () => {
+		eventTarget.removeEventListener(name, eventListener);
+	};
+}
+//#endregion
+//#region src/internal/context.ts
+const disabledContextOptions = {
+	allowAct: false,
+	allowActions: false,
+	allowCommit: false,
+	allowEmit: false,
+	allowQueries: false,
+	allowWrites: false,
+	draftAware: false,
+	draftOnRead: false,
+	liveComputeds: false,
+	reactiveReads: false
+};
+const publicContextOptions = {
+	computedReadonly: {
+		...disabledContextOptions,
+		reactiveReads: true
+	},
+	observe: {
+		...disabledContextOptions,
+		allowQueries: true
+	},
+	queryCommitted: {
+		...disabledContextOptions,
+		allowQueries: true,
+		reactiveReads: true
+	},
+	setup: {
+		...disabledContextOptions,
+		allowAct: true,
+		allowActions: true,
+		allowEmit: true,
+		allowQueries: true
+	}
+};
+const ownerContextOptions = {
+	action: {
+		...disabledContextOptions,
+		allowActions: true,
+		allowCommit: true,
+		allowEmit: true,
+		allowQueries: true,
+		allowWrites: true,
+		draftAware: true,
+		draftOnRead: true,
+		liveComputeds: true
+	},
+	computedDraftAware: {
+		...disabledContextOptions,
+		draftAware: true,
+		liveComputeds: true
+	},
+	queryDraftAware: {
+		...disabledContextOptions,
+		allowQueries: true,
+		draftAware: true,
+		liveComputeds: true
+	}
+};
+const dirtyContexts = {
+	computedReadonly: /* @__PURE__ */ new Set(),
+	observe: /* @__PURE__ */ new Set(),
+	queryCommitted: /* @__PURE__ */ new Set(),
+	setup: /* @__PURE__ */ new Set()
+};
+const contextKinds = Object.keys(dirtyContexts);
+const contextCache = {
+	computedReadonly: /* @__PURE__ */ new WeakMap(),
+	observe: /* @__PURE__ */ new WeakMap(),
+	queryCommitted: /* @__PURE__ */ new WeakMap(),
+	setup: /* @__PURE__ */ new WeakMap()
+};
+const contextOwnerMap = /* @__PURE__ */ new WeakMap();
+let contextCacheFlushScheduled = false;
+function getContext(target, kind) {
+	if (isOwnerContextKind(kind)) return getOwnerContext(target, kind);
+	return getPublicContext(target, kind);
+}
+function getContextOwner(context) {
+	return contextOwnerMap.get(context);
+}
+function registerContextOwner(context, owner) {
+	contextOwnerMap.set(context, owner);
+}
+function createContext(instance, options, owner) {
+	const publicPrototype = Object.getPrototypeOf(instance.publicInstance);
+	return new Proxy(publicPrototype, {
+		get(_target, key, receiver) {
+			if (typeof key !== "string") return Reflect.get(publicPrototype, key, owner?.actionContext ?? instance.publicInstance);
+			if (key === "act") return options.allowAct ? (actionFn) => {
+				if (typeof actionFn !== "function") throw new Error("[preact-sigma] act() requires a function");
+				return runAdHocAction(receiver, actionFn);
+			} : void 0;
+			if (key === "commit") return options.allowCommit && owner ? () => commitActionOwner(owner) : void 0;
+			if (key === "emit") return options.allowEmit && owner ? (name, detail) => {
+				handleActionBoundary(owner, "emit");
+				instance.publicInstance[sigmaTargetBrand].emit(name, detail);
+			} : void 0;
+			if (instance.stateKeys.has(key)) {
+				if (owner && options.draftAware) return readActionStateValue(owner, key, options);
+				const signal = getSignal(instance, key);
+				return options.reactiveReads ? signal.value : signal.peek();
+			}
+			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 (Reflect.has(publicPrototype, key)) return Reflect.get(publicPrototype, key, owner?.actionContext ?? instance.publicInstance);
+		},
+		set(_target, key, value) {
+			if (!owner || !options.allowWrites || typeof key !== "string" || !instance.stateKeys.has(key)) return false;
+			setActionStateValue(owner, key, value);
+			return true;
+		},
+		apply: unsupportedOperation,
+		construct: unsupportedOperation,
+		defineProperty: unsupportedOperation,
+		deleteProperty: unsupportedOperation,
+		getOwnPropertyDescriptor: unsupportedOperation,
+		has: unsupportedOperation,
+		isExtensible: unsupportedOperation,
+		ownKeys: unsupportedOperation,
+		preventExtensions: unsupportedOperation,
+		setPrototypeOf: unsupportedOperation
+	});
+}
+function unsupportedOperation() {
+	throw new Error("[preact-sigma] This operation is not supported by context proxies");
+}
+const kindToOwnerContextKey = {
+	action: "actionContext",
+	computedDraftAware: "computedContext",
+	queryDraftAware: "queryContext"
+};
+function isOwnerContextKind(kind) {
+	return kind in kindToOwnerContextKey;
+}
+function getOwnerContext(owner, kind) {
+	const contextKey = kindToOwnerContextKey[kind];
+	if (owner[contextKey]) return owner[contextKey];
+	const context = createContext(owner.instance, ownerContextOptions[kind], owner);
+	registerSigmaInternals(context, owner.instance);
+	registerContextOwner(context, owner);
+	owner[contextKey] = context;
+	return context;
+}
+function getPublicContext(instance, kind) {
+	const cachedContext = contextCache[kind].get(instance);
+	if (cachedContext) return cachedContext;
+	const context = createContext(instance, publicContextOptions[kind], void 0);
+	registerSigmaInternals(context, instance);
+	contextCache[kind].set(instance, context);
+	dirtyContexts[kind].add(instance);
+	if (!contextCacheFlushScheduled) {
+		contextCacheFlushScheduled = true;
+		setTimeout(() => {
+			for (const queuedKind of contextKinds) {
+				for (const queuedInstance of dirtyContexts[queuedKind]) contextCache[queuedKind].delete(queuedInstance);
+				dirtyContexts[queuedKind].clear();
+			}
+			contextCacheFlushScheduled = false;
+		}, 0);
+	}
+	return context;
+}
+//#endregion
+//#region src/internal/runtime.ts
+const sigmaInternalsMap = /* @__PURE__ */ new WeakMap();
+let autoFreezeEnabled = true;
+let nextActionOwnerId = 1;
+let currentDraftOwner;
+function registerSigmaInternals(context, instance) {
+	sigmaInternalsMap.set(context, instance);
+}
+function getSigmaInternals(context) {
+	const instance = sigmaInternalsMap.get(context);
+	if (!instance) throw new Error("[preact-sigma] Invalid sigma context");
+	return instance;
+}
+/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled and the setting is shared across instances. */
+function setAutoFreeze(autoFreeze) {
+	autoFreezeEnabled = autoFreeze;
+	immer.setAutoFreeze(autoFreeze);
+}
+function getSignal(instance, key) {
+	return instance.publicInstance["#" + key];
+}
+function initializeSigmaInstance(publicInstance, type, initialState) {
+	const stateKeys = new Set(type._defaultStateKeys);
+	if (initialState) for (const key in initialState) stateKeys.add(key);
+	const instance = {
+		changeSubscriptions: /* @__PURE__ */ new Set(),
+		currentSetupCleanup: void 0,
+		patchSubscriptions: 0,
+		publicInstance,
+		stateKeys,
+		type,
+		disposed: false
+	};
+	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];
+		const container = signal(value);
+		Object.defineProperty(publicInstance, "#" + key, { value: container });
+		Object.defineProperty(publicInstance, key, {
+			get: () => container.value,
+			enumerable: true
+		});
+	}
+	for (const key in type._computeFunctions) Object.defineProperty(publicInstance, "#" + key, { value: computed(() => type._computeFunctions[key].call(getContext(instance, "computedReadonly"))) });
+	registerSigmaInternals(publicInstance, instance);
+}
+function buildQueryMethod(queryFunction) {
+	return function(...args) {
+		const instance = getSigmaInternals(this);
+		const owner = getContextOwner(this);
+		if (owner) return queryFunction.apply(getContext(owner, "queryDraftAware"), args);
+		return computed(() => queryFunction.apply(getContext(instance, "queryCommitted"), args)).value;
+	};
+}
+function buildActionMethod(actionName, actionFn) {
+	return function(...args) {
+		return runActionInvocation(this, actionName, actionFn, args);
+	};
+}
+function runAdHocAction(context, actionFn) {
+	return runActionInvocation(context, "act()", actionFn, []);
+}
+function readActionStateValue(owner, key, options) {
+	if (owner.currentDraft) return owner.currentDraft[key];
+	const signal = getSignal(owner.instance, key);
+	const committedValue = options.reactiveReads ? signal.value : signal.peek();
+	if (options.draftOnRead && immer.isDraftable(committedValue)) return ensureOwnerDraft(owner)[key];
+	return committedValue;
+}
+function readActionComputedValue(owner, key) {
+	return owner.instance.type._computeFunctions[key].call(getContext(owner, "computedDraftAware"));
+}
+function setActionStateValue(owner, key, value) {
+	ensureOwnerDraft(owner)[key] = value;
+}
+function commitActionOwner(owner) {
+	const finalized = finalizeOwnerDraft(owner);
+	if (finalized?.changed) publishState(owner.instance, finalized);
+}
+function handleActionBoundary(owner, boundary, actionName) {
+	const draftOwner = currentDraftOwner;
+	if (!draftOwner?.currentDraft) return;
+	if (!finalizeOwnerDraft(draftOwner)?.changed) return;
+	if (draftOwner === owner) {
+		const message = boundary === "emit" ? `[preact-sigma] Action "${draftOwner.actionName}" has unpublished changes. Call this.commit() before emit().` : `[preact-sigma] Action "${draftOwner.actionName}" has unpublished changes. Call this.commit() before calling another action.`;
+		throw new Error(message);
+	}
+	if (boundary === "emit") throw new Error("[preact-sigma] Unexpected emit boundary. This is a bug.");
+	console.warn(`[preact-sigma] Discarded unpublished action changes from "${draftOwner.actionName}" before running "${actionName ?? "another action"}".`, {
+		action: draftOwner.actionFn,
+		actionArgs: draftOwner.args,
+		actionId: draftOwner.id,
+		actionName: draftOwner.actionName,
+		draftedInstance: currentDraftOwner?.publicInstance ?? draftOwner.publicInstance,
+		instance: draftOwner.instance.publicInstance
+	});
+}
+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}`);
+}
+function shouldSetup(publicInstance) {
+	return getSigmaInternals(publicInstance).type._setupFunction !== null;
+}
+function clearCurrentDraft(owner) {
+	owner.currentDraft = void 0;
+	owner.currentBase = void 0;
+	if (currentDraftOwner === owner) currentDraftOwner = void 0;
+}
+function createActionOwner(instance, actionName, actionFn, args) {
+	const owner = {
+		actionFn,
+		actionName,
+		args,
+		id: nextActionOwnerId++,
+		instance,
+		publicInstance: instance.publicInstance
+	};
+	owner.actionContext = getContext(owner, "action");
+	registerSigmaInternals(owner.actionContext, instance);
+	registerContextOwner(owner.actionContext, owner);
+	return owner;
+}
+function runActionInvocation(context, actionName, actionFn, args) {
+	const instance = getSigmaInternals(context);
+	if (instance.disposed) throw new Error("[preact-sigma] Cannot run an action on a disposed sigma state");
+	const isAdHocAction = actionName === "act()";
+	const actionIsAsync = actionFn.constructor.name === "AsyncFunction";
+	if (actionIsAsync && isAdHocAction) throw new Error("[preact-sigma] act() callbacks must stay synchronous");
+	return untracked(() => {
+		let owner;
+		const callerOwner = getContextOwner(context);
+		if (callerOwner && callerOwner.instance === instance && !actionIsAsync) owner = callerOwner;
+		else {
+			handleActionBoundary(callerOwner, "action", actionName);
+			owner = createActionOwner(instance, actionName, actionFn, args);
+		}
+		let result;
+		try {
+			result = actionFn.apply(owner.actionContext, args);
+		} catch (error) {
+			clearCurrentDraft(owner);
+			throw error;
+		}
+		if (isAdHocAction && isPromiseLike(result)) {
+			clearCurrentDraft(owner);
+			Promise.resolve(result).catch(() => {});
+			throw new Error("[preact-sigma] act() callbacks must stay synchronous");
+		}
+		if (!actionIsAsync && isPromiseLike(result)) {
+			clearCurrentDraft(owner);
+			Promise.resolve(result).catch(() => {});
+			throw new Error(`[preact-sigma] Action "${actionName}" must use native async-await syntax to return a promise.`);
+		}
+		if (owner === callerOwner) return result;
+		const finalized = finalizeOwnerDraft(owner);
+		if (finalized?.changed) publishState(instance, finalized);
+		if (isPromiseLike(result)) return resolveAsyncActionResult(owner, result);
+		return result;
+	});
+}
+function disposeCleanupResource(resource) {
+	if (typeof resource === "function") resource();
+	else if (resource instanceof AbortController) resource.abort();
+	else if ("dispose" in resource) resource.dispose();
+	else resource[Symbol.dispose]();
+}
+function assertExactStateKeys(stateKeys, nextState) {
+	const extraKeys = Object.keys(nextState).filter((key) => !stateKeys.has(key));
+	const missingKeys = [...stateKeys].filter((key) => !Object.prototype.hasOwnProperty.call(nextState, key));
+	if (!extraKeys.length && !missingKeys.length) return;
+	let message = "[preact-sigma] replaceState() requires exactly the instance's state keys";
+	if (missingKeys.length) message += `. Missing: ${missingKeys.join(", ")}`;
+	if (extraKeys.length) message += `. Extra: ${extraKeys.join(", ")}`;
+	throw new Error(message);
+}
+function assertNoPendingDraft(operationName) {
+	const owner = currentDraftOwner;
+	if (!owner?.currentDraft) return;
+	throw new Error(`[preact-sigma] ${operationName}() cannot run while action "${owner.actionName}" has unpublished changes. Call this.commit() before ${operationName}().`);
+}
+function snapshotState(instance) {
+	const snapshot = Object.create(null);
+	for (const key of instance.stateKeys) snapshot[key] = getSignal(instance, key).peek();
+	return snapshot;
+}
+function ensureOwnerDraft(owner) {
+	if (owner.currentDraft) return owner.currentDraft;
+	handleActionBoundary(owner, "action", owner.actionName);
+	owner.currentBase = snapshotState(owner.instance);
+	owner.currentDraft = immer.createDraft(owner.currentBase);
+	currentDraftOwner = owner;
+	return owner.currentDraft;
+}
+function finalizeOwnerDraft(owner) {
+	const currentDraft = owner.currentDraft;
+	const oldState = owner.currentBase;
+	if (!currentDraft || !oldState) return;
+	clearCurrentDraft(owner);
+	let patches;
+	let inversePatches;
+	const newState = owner.instance.patchSubscriptions > 0 ? immer.finishDraft(currentDraft, (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	}) : immer.finishDraft(currentDraft);
+	return {
+		changed: newState !== oldState,
+		inversePatches,
+		newState,
+		oldState,
+		patches
+	};
+}
+function finalizeReplacementState(instance, oldState, nextState) {
+	const draft = immer.createDraft(oldState);
+	for (const key of instance.stateKeys) draft[key] = nextState[key];
+	let patches;
+	let inversePatches;
+	const newState = instance.patchSubscriptions > 0 ? immer.finishDraft(draft, (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	}) : immer.finishDraft(draft);
+	return {
+		changed: newState !== oldState,
+		inversePatches,
+		newState,
+		oldState,
+		patches
+	};
+}
+function isPromiseLike(value) {
+	return value != null && typeof value.then === "function";
+}
+function publishState(instance, finalized) {
+	batch(() => {
+		for (const key of instance.stateKeys) {
+			const nextValue = finalized.newState[key];
+			if (autoFreezeEnabled) immer.freeze(nextValue, true);
+			const signal = getSignal(instance, key);
+			signal.value = nextValue;
+		}
+	});
+	if (instance.changeSubscriptions.size) {
+		const context = getContext(instance, "observe");
+		for (const subscription of instance.changeSubscriptions) subscription.listener.call(context, finalized);
+	}
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Utility helpers for sigma-state instances.
+*
+* The helpers expose instance-specific built-ins without reserving names on the
+* public instance object.
+*/
+const sigma = Object.freeze({
+	getSignal: (publicInstance, key) => {
+		return publicInstance["#" + key];
+	},
+	getState: (publicInstance) => {
+		return snapshotState(getSigmaInternals(publicInstance));
+	},
+	replaceState: (publicInstance, nextState) => {
+		const instance = getSigmaInternals(publicInstance);
+		if (!isPlainObject(nextState)) throw new Error("[preact-sigma] replaceState() requires a plain object snapshot");
+		assertNoPendingDraft("replaceState");
+		assertExactStateKeys(instance.stateKeys, nextState);
+		const finalized = finalizeReplacementState(instance, snapshotState(instance), nextState);
+		if (finalized.changed) publishState(instance, finalized);
+	},
+	subscribe: ((publicInstance, keyOrListener, listenerOrOptions) => {
+		const instance = getSigmaInternals(publicInstance);
+		if (typeof keyOrListener === "string") return getSignal(instance, keyOrListener).subscribe(listenerOrOptions);
+		const subscription = {
+			listener: keyOrListener,
+			patches: listenerOrOptions?.patches ?? false
+		};
+		instance.changeSubscriptions.add(subscription);
+		if (subscription.patches) instance.patchSubscriptions += 1;
+		return () => {
+			if (!instance.changeSubscriptions.delete(subscription)) return;
+			if (subscription.patches) instance.patchSubscriptions -= 1;
+		};
+	})
+});
+async function resolveAsyncActionResult(owner, result) {
+	let settledValue;
+	let settledError;
+	let rejected = false;
+	try {
+		settledValue = await result;
+	} catch (error) {
+		rejected = true;
+		settledError = error;
+	}
+	if (currentDraftOwner === owner && owner.currentDraft) {
+		if (finalizeOwnerDraft(owner)?.changed) {
+			const commitError = /* @__PURE__ */ new Error(`[preact-sigma] Async action "${owner.actionName}" finished with unpublished changes. Call this.commit() before await or return.`);
+			if (rejected) throw new AggregateError([settledError, commitError], `[preact-sigma] Async action "${owner.actionName}" rejected and left unpublished changes`);
+			throw commitError;
+		}
+	}
+	if (rejected) throw settledError;
+	return settledValue;
+}
+var Sigma = class {
+	[sigmaTargetBrand] = new SigmaListenerMap();
+	setup(...args) {
+		const instance = getSigmaInternals(this);
+		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._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;
+			cleanup = () => {
+				if (instance.currentSetupCleanup === cleanup) instance.currentSetupCleanup = void 0;
+				if (cleaned) return;
+				cleaned = true;
+				let errors;
+				for (let index = resources.length - 1; index >= 0; index -= 1) try {
+					disposeCleanupResource(resources[index]);
+				} catch (error) {
+					errors ||= [];
+					errors.push(error);
+				}
+				if (errors) throw new AggregateError(errors, "Failed to dispose one or more sigma resources");
+			};
+			instance.currentSetupCleanup = cleanup;
+		} else cleanup = () => {};
+		return cleanup;
+	}
+};
+Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
+//#endregion
+export { initializeSigmaInstance as a, sigma as c, listen as d, sigmaStateBrand as f, buildQueryMethod as i, SigmaListenerMap as l, assertDefinitionKeyAvailable as n, setAutoFreeze as o, buildActionMethod as r, shouldSetup as s, Sigma as t, SigmaTarget as u };

package/docs/context.md

@@ -27,7 +27,7 @@
 - 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 `.on(...)`, `listen(...)`, or `useListener(...)`.
+- Event: a typed notification emitted through `this.emit(...)` and observed through `listen(...)` or `useListener(...)`.
 
 # Data Flow / Lifecycle
 
@@ -48,36 +48,55 @@
 - 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: `.observe(...)`
+- 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 `hub.on(...)`
-- Subscribe outside components: `.on(...)` or `listen(...)`
-- Read or restore committed top-level state: `snapshot(...)` and `replaceState(...)`
+- 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(...)`
 
-# Practical Guidelines
+# Recommended Patterns
 
 - Put explicit type arguments on `new SigmaType<TState, TEvents>()` and let later builder methods infer from the objects you pass.
 - 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.
-- Reach for `instance.get(key)` only when code specifically needs the underlying `ReadonlySignal`.
-- Treat `emit(...)`, `await`, and any action call other than a same-instance synchronous nested action call as draft boundaries. Call `this.commit()` only when pending changes need to become public before one of those boundaries.
-- Use ordinary actions for routine writes. Reserve `snapshot(...)` and `replaceState(...)` for replay, reset, or undo-like flows on committed top-level state.
+- 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.
+  ```ts
+  .setup(function () {
+    return [
+      sigma.subscribe(this, (change) => {
+        console.log(change.newState);
+      }),
+    ];
+  })
+  ```
 - Use `this.act(function () { ... })` for setup-owned callbacks that need action semantics.
-- Call Immer's `enablePatches()` before relying on `.observe(..., { patches: true })`.
+
+# 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()`.
+- Starting side effects during construction instead of through explicit `setup(...)`.
+- Encoding storage, hydration, or migration policy directly into `SigmaType` definitions.
+- 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`, `emit`, `get`, `on`, and `setup`.
+- Duplicate names across state properties, computeds, queries, and actions are rejected at runtime. Reserved public names include `act`, `commit`, `emit`, and `setup`.
 - 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.
-- `replaceState(...)` works on committed top-level state and requires the exact state-key shape.
+- 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.
 
 # Error Model
@@ -86,13 +105,13 @@
 - 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.
-- `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.
+- `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.
 
 # 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 `instance.get(key)`.
+- 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]()`.
 - 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.