preact-sigma 1.0.0 → 2.0.0

package/dist/index.mjs

@@ -1,301 +1,629 @@
-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);
-		};
+import { action, batch, batch as batch$1, computed, computed as computed$1, effect, signal, untracked, untracked as untracked$1 } from "@preact/signals";
+import * as immer from "immer";
+import { freeze, immerable } from "immer";
+import { useEffect, useRef, useState } from "preact/hooks";
+//#region src/internal/context.ts
+const disabledContextOptions = {
+	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,
+		allowActions: true,
+		allowEmit: true,
+		allowQueries: true
 	}
-	[Symbol.dispose]() {
-		this.dispose();
+};
+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
 	}
 };
-function isProducer(value) {
-	return typeof value === "function";
+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 makeNonEnumerable(object, keys) {
-	for (const key of keys) Object.defineProperty(object, key, {
-		...Object.getOwnPropertyDescriptor(object, key),
-		enumerable: false
-	});
+function getContextOwner(context) {
+	return contextOwnerMap.get(context);
 }
-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);
+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) {
+			if (typeof key !== "string") return Reflect.get(publicPrototype, key, owner?.actionContext ?? instance.publicInstance);
+			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.dispatchEvent(new CustomEvent(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);
 		},
-		ownKeys(_target) {
-			const currentState = state.value;
-			if (!isLensableState(currentState)) return [];
-			return Reflect.ownKeys(currentState);
+		set(_target, key, value) {
+			if (!owner || !options.allowWrites || typeof key !== "string" || !instance.stateKeys.has(key)) return false;
+			setActionStateValue(owner, key, value);
+			return true;
 		},
-		getOwnPropertyDescriptor(_target, key) {
-			const lensDescriptor = getLensDescriptor(key);
-			if (!lensDescriptor) return;
-			return {
-				configurable: true,
-				enumerable: lensDescriptor.enumerable,
-				value: getLens(key),
-				writable: false
-			};
-		}
+		apply: unsupportedOperation,
+		construct: unsupportedOperation,
+		defineProperty: unsupportedOperation,
+		deleteProperty: unsupportedOperation,
+		getOwnPropertyDescriptor: unsupportedOperation,
+		has: unsupportedOperation,
+		isExtensible: unsupportedOperation,
+		ownKeys: unsupportedOperation,
+		preventExtensions: unsupportedOperation,
+		setPrototypeOf: unsupportedOperation
 	});
 }
-function isLensableState(value) {
+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/symbols.ts
+const sigmaStateBrand = Symbol("sigma.v2.state");
+const reservedKeys = new Set([
+	"get",
+	"emit",
+	"commit",
+	"on",
+	"setup"
+]);
+//#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;
+}
+function isAutoFreeze() {
+	return autoFreezeEnabled;
+}
+/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled. */
+function setAutoFreeze(autoFreeze) {
+	autoFreezeEnabled = autoFreeze;
+	immer.setAutoFreeze(autoFreeze);
+}
+function isPlainObject(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);
+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 = {
+		currentSetupCleanup: void 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
+		});
 	}
-	if (errors) throw new AggregateError(errors, "Failed to dispose one or more resources");
+	for (const key in type.computeFunctions) Object.defineProperty(publicInstance, "#" + key, { value: computed$1(() => type.computeFunctions[key].call(getContext(instance, "computedReadonly"))) });
+	registerSigmaInternals(publicInstance, instance);
 }
-/** Check whether a value is a managed-state instance. */
-function isManagedState(value) {
-	return value instanceof StateContainer;
+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$1(() => queryFunction.apply(getContext(instance, "queryCommitted"), args)).value;
+	};
+}
+function buildActionMethod(actionName, actionFn) {
+	const actionIsAsync = isAsyncFunction(actionFn);
+	return function(...args) {
+		const instance = getSigmaInternals(this);
+		if (instance.disposed) throw new Error("[preact-sigma] Cannot run an action on a disposed sigma state");
+		return untracked$1(() => {
+			let owner;
+			const callerOwner = getContextOwner(this);
+			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 (!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 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"}".`, createDraftMetadata(draftOwner));
+}
+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.setupFunctions.length > 0;
+}
+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 createCommitError(owner) {
+	return /* @__PURE__ */ new Error(`[preact-sigma] Async action "${owner.actionName}" finished with unpublished changes. Call this.commit() before await or return.`);
+}
+function createDraftMetadata(owner) {
+	return {
+		action: owner.actionFn,
+		actionArgs: owner.args,
+		actionId: owner.id,
+		actionName: owner.actionName,
+		draftedInstance: currentDraftOwner?.publicInstance ?? owner.publicInstance,
+		instance: owner.instance.publicInstance
+	};
+}
+function disposeCleanupResource(resource) {
+	if (typeof resource === "function") resource();
+	else if (resource instanceof AbortController) resource.abort();
+	else resource[Symbol.dispose]();
+}
+function assertExactStateKeys(instance, nextState) {
+	const extraKeys = Object.keys(nextState).filter((key) => !instance.stateKeys.has(key));
+	const missingKeys = [...instance.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.type.patchesEnabled ? 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.type.patchesEnabled ? immer.finishDraft(draft, (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	}) : immer.finishDraft(draft);
+	return {
+		changed: newState !== oldState,
+		inversePatches,
+		newState,
+		oldState,
+		patches
+	};
+}
+function isAsyncFunction(fn) {
+	return fn.constructor.name === "AsyncFunction";
+}
+function isPromiseLike(value) {
+	return value != null && typeof value.then === "function";
+}
+function publishState(instance, finalized) {
+	batch$1(() => {
+		for (const key of instance.stateKeys) {
+			const nextValue = finalized.newState[key];
+			if (isAutoFreeze()) immer.freeze(nextValue, true);
+			const signal = getSignal(instance, key);
+			signal.value = nextValue;
+		}
+	});
+	for (const observer of instance.type.observeFunctions) observer.call(getContext(instance, "observe"), finalized);
 }
-//#endregion
-//#region src/framework.ts
 /**
-* Mark a constructor-returned method as a tracked query.
+* Returns a shallow snapshot of an instance's committed public state.
 *
-* 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.
+* The snapshot includes one own property for each top-level state key and reads
+* the current committed value for that key. Its type is inferred from the
+* instance's sigma-state definition.
 */
-function query(fn) {
-	const wrapped = ((...args) => computed$1(() => fn(...args)).value);
-	queryMethods.add(wrapped);
-	return wrapped;
+function snapshot(publicInstance) {
+	return snapshotState(getSigmaInternals(publicInstance));
 }
 /**
-* 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()`.
+* Replaces an instance's committed public state from a snapshot object.
 *
-* 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.
+* The replacement snapshot must be a plain object with exactly the instance's
+* top-level state keys. Its type is inferred from the instance's sigma-state
+* definition.
 */
-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);
+function 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, nextState);
+	const finalized = finalizeReplacementState(instance, snapshot(publicInstance), nextState);
+	if (finalized.changed) publishState(instance, finalized);
+}
+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 = createCommitError(owner);
+			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 extends EventTarget {
+	setup(...args) {
+		const instance = getSigmaInternals(this);
+		if (!instance.type.setupFunctions.length) throw new Error("[preact-sigma] Setup is undefined for this sigma state");
+		if (instance.disposed) throw new Error("[preact-sigma] Cannot set up a disposed sigma state");
+		instance.currentSetupCleanup?.();
+		instance.currentSetupCleanup = void 0;
+		const resources = instance.type.setupFunctions.flatMap((setup) => {
+			const result = setup.apply(getContext(instance, "setup"), args);
+			if (!Array.isArray(result)) throw new Error("[preact-sigma] Sigma setup handlers must return an array");
+			return result;
+		});
+		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;
+	}
+	get(key) {
+		return getSignal(getSigmaInternals(this), key);
+	}
+	on(name, listener) {
+		const adapter = (event) => {
+			const payload = event.detail;
+			if (payload === void 0) listener();
+			else listener(payload);
+		};
+		this.addEventListener(name, adapter);
+		return () => {
+			this.removeEventListener(name, adapter);
+		};
+	}
+};
+Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 //#endregion
-//#region src/hooks.ts
-function isFunction(value) {
-	return typeof value === "function";
+//#region src/framework.ts
+/** Checks whether a value is a sigma-state instance. */
+function isSigmaState(value) {
+	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
 }
-/**
-* 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;
+/** Creates a standalone tracked query function with the same signature as `fn`. */
+function query(fn) {
+	return ((...args) => computed$1(() => fn(...args)).value);
 }
 /**
-* 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.
+* Builds sigma-state constructors by accumulating default state, computeds, queries,
+* observers, actions, and setup handlers.
 */
-function useSubscribe(target, listener) {
-	listener = useStableCallback(listener);
-	useEffect(() => target?.subscribe(listener), [target]);
+var SigmaType = class extends Function {
+	constructor(name = "Sigma") {
+		super();
+		const type = {
+			actionFunctions: Object.create(null),
+			computeFunctions: Object.create(null),
+			defaultState: Object.create(null),
+			defaultStateKeys: [],
+			observeFunctions: [],
+			patchesEnabled: false,
+			queryFunctions: Object.create(null),
+			setupFunctions: []
+		};
+		const { [name]: SigmaTypeBuilder } = { [name]: class extends Sigma {
+			constructor(initialState) {
+				super();
+				initializeSigmaInstance(this, type, initialState);
+			}
+		} };
+		SigmaTypeBuilder.defaultState = function(defaultState) {
+			for (const key in defaultState) {
+				if (defaultState[key] === void 0) continue;
+				type.defaultState[key] = defaultState[key];
+				type.defaultStateKeys.push(key);
+			}
+			return this;
+		};
+		SigmaTypeBuilder.computed = function(computeFunctions) {
+			for (const key in computeFunctions) {
+				assertDefinitionKeyAvailable(type, key, "computed");
+				type.computeFunctions[key] = computeFunctions[key];
+				Object.defineProperty(this.prototype, key, { get: function() {
+					return this["#" + key].value;
+				} });
+			}
+			return this;
+		};
+		SigmaTypeBuilder.queries = function(queryFunctions) {
+			for (const key in queryFunctions) {
+				assertDefinitionKeyAvailable(type, key, "query");
+				const queryFunction = queryFunctions[key];
+				type.queryFunctions[key] = queryFunction;
+				Object.defineProperty(this.prototype, key, { value: buildQueryMethod(queryFunction) });
+			}
+			return this;
+		};
+		SigmaTypeBuilder.observe = function(listener, options) {
+			type.observeFunctions.push(listener);
+			if (options?.patches) type.patchesEnabled = true;
+			return this;
+		};
+		SigmaTypeBuilder.actions = function(actionFunctions) {
+			for (const key in actionFunctions) {
+				assertDefinitionKeyAvailable(type, key, "action");
+				const actionFunction = actionFunctions[key];
+				type.actionFunctions[key] = actionFunction;
+				Object.defineProperty(this.prototype, key, { value: buildActionMethod(key, actionFunction) });
+			}
+			return this;
+		};
+		SigmaTypeBuilder.setup = function(setup) {
+			type.setupFunctions.push(setup);
+			return this;
+		};
+		return SigmaTypeBuilder;
+	}
+};
+//#endregion
+//#region src/listener.ts
+/** Adds an event listener and returns a cleanup function that removes it. */
+function listen(target, name, fn) {
+	const listener = isSigmaState(target) ? (event) => fn(event.detail) : fn;
+	target.addEventListener(name, listener);
+	return () => {
+		target.removeEventListener(name, listener);
+	};
 }
-/**
-* 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);
+//#endregion
+//#region src/hooks.ts
+/** Creates one sigma-state instance for a component and manages its setup cleanup. */
+function useSigma(create, setupArgs) {
+	const sigmaState = useState(create)[0];
+	if (shouldSetup(sigmaState)) {
+		const args = setupArgs ?? [];
+		useEffect(() => sigmaState.setup(...args), [sigmaState, ...args]);
+	}
+	return sigmaState;
+}
+/** Attaches an event listener in a component and cleans it up when dependencies change. */
+function useListener(target, name, listener) {
+	const listenerRef = useRef(listener);
+	listenerRef.current = listener;
 	useEffect(() => {
 		if (!target) return;
-		if (isManagedState(target)) return target.on(name, listener);
-		target.addEventListener(name, listener);
-		return () => target.removeEventListener(name, listener);
+		return listen(target, name, ((event) => listenerRef.current(event)));
 	}, [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 };
+export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };