@pyreon/reactivity 0.14.0 → 0.16.0

package/README.md

@@ -56,7 +56,8 @@ batch(() => {
 ### Scopes
 
 - **`effectScope(): EffectScope`** -- Creates a scope that collects effects for bulk disposal. Internal arrays (`_effects`, `_updateHooks`) are lazy-allocated on first use -- scopes with no effects cost only the object itself.
-- **`getCurrentScope(): EffectScope | undefined`** -- Returns the active effect scope.
+- **`getCurrentScope(): EffectScope | null`** -- Returns the active effect scope, or `null` if none.
+- **`onScopeDispose(fn)`** -- Register a callback to run when the current scope stops (Vue 3 parity).
 - **`setCurrentScope(scope)`** -- Manually sets the current effect scope.
 
 ### Selectors and Resources
@@ -69,6 +70,8 @@ batch(() => {
 - **`createStore(initial)`** -- Creates a deeply reactive store object.
 - **`isStore(value): boolean`** -- Checks whether a value is a reactive store.
 - **`reconcile(target, source)`** -- Efficiently patches a store to match a new value.
+- **`shallowReactive<T>(initial): T`** -- Creates a SHALLOWLY reactive store: top-level property writes notify, but nested object mutations don't (Vue 3 parity). Use for large object graphs where deep proxying would be wasteful.
+- **`markRaw<T>(value): T`** -- Mark an object as RAW so `createStore` and `shallowReactive` return it unwrapped (Vue 3 parity). Useful for class instances, third-party objects, DOM nodes, or any shape that shouldn't be deeply proxied. Marking is one-way (no `unmarkRaw`); mark BEFORE the object enters a store.
 
 ## License
 

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"1ddc8440-1","name":"batch.ts"},{"uid":"1ddc8440-3","name":"cell.ts"},{"uid":"1ddc8440-5","name":"scope.ts"},{"uid":"1ddc8440-7","name":"tracking.ts"},{"uid":"1ddc8440-9","name":"effect.ts"},{"uid":"1ddc8440-11","name":"computed.ts"},{"uid":"1ddc8440-13","name":"createSelector.ts"},{"uid":"1ddc8440-15","name":"debug.ts"},{"uid":"1ddc8440-17","name":"signal.ts"},{"uid":"1ddc8440-19","name":"store.ts"},{"uid":"1ddc8440-21","name":"reconcile.ts"},{"uid":"1ddc8440-23","name":"resource.ts"},{"uid":"1ddc8440-25","name":"watch.ts"},{"uid":"1ddc8440-27","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"1ddc8440-1":{"renderedLength":1079,"gzipLength":520,"brotliLength":0,"metaUid":"1ddc8440-0"},"1ddc8440-3":{"renderedLength":1636,"gzipLength":786,"brotliLength":0,"metaUid":"1ddc8440-2"},"1ddc8440-5":{"renderedLength":1977,"gzipLength":786,"brotliLength":0,"metaUid":"1ddc8440-4"},"1ddc8440-7":{"renderedLength":2227,"gzipLength":858,"brotliLength":0,"metaUid":"1ddc8440-6"},"1ddc8440-9":{"renderedLength":5389,"gzipLength":1826,"brotliLength":0,"metaUid":"1ddc8440-8"},"1ddc8440-11":{"renderedLength":4068,"gzipLength":1253,"brotliLength":0,"metaUid":"1ddc8440-10"},"1ddc8440-13":{"renderedLength":1810,"gzipLength":833,"brotliLength":0,"metaUid":"1ddc8440-12"},"1ddc8440-15":{"renderedLength":2469,"gzipLength":1092,"brotliLength":0,"metaUid":"1ddc8440-14"},"1ddc8440-17":{"renderedLength":2671,"gzipLength":1169,"brotliLength":0,"metaUid":"1ddc8440-16"},"1ddc8440-19":{"renderedLength":2879,"gzipLength":1056,"brotliLength":0,"metaUid":"1ddc8440-18"},"1ddc8440-21":{"renderedLength":2109,"gzipLength":867,"brotliLength":0,"metaUid":"1ddc8440-20"},"1ddc8440-23":{"renderedLength":1029,"gzipLength":475,"brotliLength":0,"metaUid":"1ddc8440-22"},"1ddc8440-25":{"renderedLength":1249,"gzipLength":582,"brotliLength":0,"metaUid":"1ddc8440-24"},"1ddc8440-27":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"1ddc8440-26"}},"nodeMetas":{"1ddc8440-0":{"id":"/src/batch.ts","moduleParts":{"index.js":"1ddc8440-1"},"imported":[],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-16"},{"uid":"1ddc8440-6"}]},"1ddc8440-2":{"id":"/src/cell.ts","moduleParts":{"index.js":"1ddc8440-3"},"imported":[],"importedBy":[{"uid":"1ddc8440-26"}]},"1ddc8440-4":{"id":"/src/scope.ts","moduleParts":{"index.js":"1ddc8440-5"},"imported":[],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-10"},{"uid":"1ddc8440-8"}]},"1ddc8440-6":{"id":"/src/tracking.ts","moduleParts":{"index.js":"1ddc8440-7"},"imported":[{"uid":"1ddc8440-0"}],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-10"},{"uid":"1ddc8440-12"},{"uid":"1ddc8440-8"},{"uid":"1ddc8440-22"},{"uid":"1ddc8440-16"}]},"1ddc8440-8":{"id":"/src/effect.ts","moduleParts":{"index.js":"1ddc8440-9"},"imported":[{"uid":"1ddc8440-4"},{"uid":"1ddc8440-6"}],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-10"},{"uid":"1ddc8440-12"},{"uid":"1ddc8440-22"},{"uid":"1ddc8440-24"}]},"1ddc8440-10":{"id":"/src/computed.ts","moduleParts":{"index.js":"1ddc8440-11"},"imported":[{"uid":"1ddc8440-8"},{"uid":"1ddc8440-4"},{"uid":"1ddc8440-6"}],"importedBy":[{"uid":"1ddc8440-26"}]},"1ddc8440-12":{"id":"/src/createSelector.ts","moduleParts":{"index.js":"1ddc8440-13"},"imported":[{"uid":"1ddc8440-8"},{"uid":"1ddc8440-6"}],"importedBy":[{"uid":"1ddc8440-26"}]},"1ddc8440-14":{"id":"/src/debug.ts","moduleParts":{"index.js":"1ddc8440-15"},"imported":[],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-16"}]},"1ddc8440-16":{"id":"/src/signal.ts","moduleParts":{"index.js":"1ddc8440-17"},"imported":[{"uid":"1ddc8440-0"},{"uid":"1ddc8440-14"},{"uid":"1ddc8440-6"}],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-22"},{"uid":"1ddc8440-18"}]},"1ddc8440-18":{"id":"/src/store.ts","moduleParts":{"index.js":"1ddc8440-19"},"imported":[{"uid":"1ddc8440-16"}],"importedBy":[{"uid":"1ddc8440-26"},{"uid":"1ddc8440-20"}]},"1ddc8440-20":{"id":"/src/reconcile.ts","moduleParts":{"index.js":"1ddc8440-21"},"imported":[{"uid":"1ddc8440-18"}],"importedBy":[{"uid":"1ddc8440-26"}]},"1ddc8440-22":{"id":"/src/resource.ts","moduleParts":{"index.js":"1ddc8440-23"},"imported":[{"uid":"1ddc8440-8"},{"uid":"1ddc8440-16"},{"uid":"1ddc8440-6"}],"importedBy":[{"uid":"1ddc8440-26"}]},"1ddc8440-24":{"id":"/src/watch.ts","moduleParts":{"index.js":"1ddc8440-25"},"imported":[{"uid":"1ddc8440-8"}],"importedBy":[{"uid":"1ddc8440-26"}]},"1ddc8440-26":{"id":"/src/index.ts","moduleParts":{"index.js":"1ddc8440-27"},"imported":[{"uid":"1ddc8440-0"},{"uid":"1ddc8440-2"},{"uid":"1ddc8440-10"},{"uid":"1ddc8440-12"},{"uid":"1ddc8440-14"},{"uid":"1ddc8440-8"},{"uid":"1ddc8440-20"},{"uid":"1ddc8440-22"},{"uid":"1ddc8440-4"},{"uid":"1ddc8440-16"},{"uid":"1ddc8440-18"},{"uid":"1ddc8440-6"},{"uid":"1ddc8440-24"}],"importedBy":[],"isEntry":true}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"a1cf068b-1","name":"batch.ts"},{"uid":"a1cf068b-3","name":"cell.ts"},{"uid":"a1cf068b-5","name":"scope.ts"},{"uid":"a1cf068b-7","name":"tracking.ts"},{"uid":"a1cf068b-9","name":"effect.ts"},{"uid":"a1cf068b-11","name":"computed.ts"},{"uid":"a1cf068b-13","name":"createSelector.ts"},{"uid":"a1cf068b-15","name":"debug.ts"},{"uid":"a1cf068b-17","name":"signal.ts"},{"uid":"a1cf068b-19","name":"store.ts"},{"uid":"a1cf068b-21","name":"reconcile.ts"},{"uid":"a1cf068b-23","name":"resource.ts"},{"uid":"a1cf068b-25","name":"watch.ts"},{"uid":"a1cf068b-27","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"a1cf068b-1":{"renderedLength":3016,"gzipLength":1167,"brotliLength":0,"metaUid":"a1cf068b-0"},"a1cf068b-3":{"renderedLength":1636,"gzipLength":786,"brotliLength":0,"metaUid":"a1cf068b-2"},"a1cf068b-5":{"renderedLength":3026,"gzipLength":1226,"brotliLength":0,"metaUid":"a1cf068b-4"},"a1cf068b-7":{"renderedLength":2227,"gzipLength":858,"brotliLength":0,"metaUid":"a1cf068b-6"},"a1cf068b-9":{"renderedLength":7391,"gzipLength":2397,"brotliLength":0,"metaUid":"a1cf068b-8"},"a1cf068b-11":{"renderedLength":4548,"gzipLength":1464,"brotliLength":0,"metaUid":"a1cf068b-10"},"a1cf068b-13":{"renderedLength":2244,"gzipLength":981,"brotliLength":0,"metaUid":"a1cf068b-12"},"a1cf068b-15":{"renderedLength":2469,"gzipLength":1092,"brotliLength":0,"metaUid":"a1cf068b-14"},"a1cf068b-17":{"renderedLength":2818,"gzipLength":1191,"brotliLength":0,"metaUid":"a1cf068b-16"},"a1cf068b-19":{"renderedLength":5143,"gzipLength":1835,"brotliLength":0,"metaUid":"a1cf068b-18"},"a1cf068b-21":{"renderedLength":2109,"gzipLength":867,"brotliLength":0,"metaUid":"a1cf068b-20"},"a1cf068b-23":{"renderedLength":1205,"gzipLength":524,"brotliLength":0,"metaUid":"a1cf068b-22"},"a1cf068b-25":{"renderedLength":1249,"gzipLength":582,"brotliLength":0,"metaUid":"a1cf068b-24"},"a1cf068b-27":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"a1cf068b-26"}},"nodeMetas":{"a1cf068b-0":{"id":"/src/batch.ts","moduleParts":{"index.js":"a1cf068b-1"},"imported":[],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-10"},{"uid":"a1cf068b-16"},{"uid":"a1cf068b-6"}]},"a1cf068b-2":{"id":"/src/cell.ts","moduleParts":{"index.js":"a1cf068b-3"},"imported":[],"importedBy":[{"uid":"a1cf068b-26"}]},"a1cf068b-4":{"id":"/src/scope.ts","moduleParts":{"index.js":"a1cf068b-5"},"imported":[],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-10"},{"uid":"a1cf068b-8"}]},"a1cf068b-6":{"id":"/src/tracking.ts","moduleParts":{"index.js":"a1cf068b-7"},"imported":[{"uid":"a1cf068b-0"}],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-10"},{"uid":"a1cf068b-12"},{"uid":"a1cf068b-8"},{"uid":"a1cf068b-22"},{"uid":"a1cf068b-16"}]},"a1cf068b-8":{"id":"/src/effect.ts","moduleParts":{"index.js":"a1cf068b-9"},"imported":[{"uid":"a1cf068b-4"},{"uid":"a1cf068b-6"}],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-10"},{"uid":"a1cf068b-12"},{"uid":"a1cf068b-22"},{"uid":"a1cf068b-24"}]},"a1cf068b-10":{"id":"/src/computed.ts","moduleParts":{"index.js":"a1cf068b-11"},"imported":[{"uid":"a1cf068b-0"},{"uid":"a1cf068b-8"},{"uid":"a1cf068b-4"},{"uid":"a1cf068b-6"}],"importedBy":[{"uid":"a1cf068b-26"}]},"a1cf068b-12":{"id":"/src/createSelector.ts","moduleParts":{"index.js":"a1cf068b-13"},"imported":[{"uid":"a1cf068b-8"},{"uid":"a1cf068b-6"}],"importedBy":[{"uid":"a1cf068b-26"}]},"a1cf068b-14":{"id":"/src/debug.ts","moduleParts":{"index.js":"a1cf068b-15"},"imported":[],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-16"}]},"a1cf068b-16":{"id":"/src/signal.ts","moduleParts":{"index.js":"a1cf068b-17"},"imported":[{"uid":"a1cf068b-0"},{"uid":"a1cf068b-14"},{"uid":"a1cf068b-6"}],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-22"},{"uid":"a1cf068b-18"}]},"a1cf068b-18":{"id":"/src/store.ts","moduleParts":{"index.js":"a1cf068b-19"},"imported":[{"uid":"a1cf068b-16"}],"importedBy":[{"uid":"a1cf068b-26"},{"uid":"a1cf068b-20"}]},"a1cf068b-20":{"id":"/src/reconcile.ts","moduleParts":{"index.js":"a1cf068b-21"},"imported":[{"uid":"a1cf068b-18"}],"importedBy":[{"uid":"a1cf068b-26"}]},"a1cf068b-22":{"id":"/src/resource.ts","moduleParts":{"index.js":"a1cf068b-23"},"imported":[{"uid":"a1cf068b-8"},{"uid":"a1cf068b-16"},{"uid":"a1cf068b-6"}],"importedBy":[{"uid":"a1cf068b-26"}]},"a1cf068b-24":{"id":"/src/watch.ts","moduleParts":{"index.js":"a1cf068b-25"},"imported":[{"uid":"a1cf068b-8"}],"importedBy":[{"uid":"a1cf068b-26"}]},"a1cf068b-26":{"id":"/src/index.ts","moduleParts":{"index.js":"a1cf068b-27"},"imported":[{"uid":"a1cf068b-0"},{"uid":"a1cf068b-2"},{"uid":"a1cf068b-10"},{"uid":"a1cf068b-12"},{"uid":"a1cf068b-14"},{"uid":"a1cf068b-8"},{"uid":"a1cf068b-20"},{"uid":"a1cf068b-22"},{"uid":"a1cf068b-4"},{"uid":"a1cf068b-16"},{"uid":"a1cf068b-18"},{"uid":"a1cf068b-6"},{"uid":"a1cf068b-24"}],"importedBy":[],"isEntry":true}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -1,24 +1,65 @@
 //#region src/batch.ts
+const __DEV__ = process.env.NODE_ENV !== "production";
 let batchDepth = 0;
-const setA = /* @__PURE__ */ new Set();
-const setB = /* @__PURE__ */ new Set();
-let pendingNotifications = setA;
+const pendingRecomputes = /* @__PURE__ */ new Set();
+const pendingEffects = /* @__PURE__ */ new Set();
+const _nextEffectPass = /* @__PURE__ */ new Set();
+let _visitedThisPass = null;
+const _recomputes = /* @__PURE__ */ new WeakSet();
+const MAX_PASSES = 32;
+/**
+* Mark a callback as a computed recompute (called from computed.ts at
+* creation time). Routes future enqueues into the recompute queue so they
+* settle before any effects fire.
+*/
+function _markRecompute(fn) {
+	_recomputes.add(fn);
+}
 function batch(fn) {
 	batchDepth++;
 	try {
 		fn();
 	} finally {
 		batchDepth--;
-		if (batchDepth === 0 && pendingNotifications.size > 0) {
+		if (batchDepth === 0 && (pendingRecomputes.size > 0 || pendingEffects.size > 0)) {
 			batchDepth = 1;
 			try {
-				while (pendingNotifications.size > 0) {
-					const flush = pendingNotifications;
-					pendingNotifications = flush === setA ? setB : setA;
-					for (const notify of flush) notify();
-					flush.clear();
+				let effectPass = 0;
+				while (pendingRecomputes.size > 0 || pendingEffects.size > 0) {
+					for (const r of pendingRecomputes) r();
+					pendingRecomputes.clear();
+					if (pendingEffects.size > 0) {
+						if (++effectPass > MAX_PASSES) {
+							if (__DEV__) {
+								const droppedCount = pendingEffects.size;
+								const labels = [];
+								for (const notify of pendingEffects) {
+									const label = notify._label;
+									if (label) labels.push(label);
+									if (labels.length >= 5) break;
+								}
+								const labelHint = labels.length ? ` Sample labels: ${labels.join(", ")}${droppedCount > labels.length ? `, …${droppedCount - labels.length} more` : ""}.` : "";
+								console.warn(`[pyreon] batch effect flush exceeded MAX_PASSES (32) — possible infinite re-enqueue loop. ${droppedCount} pending effects dropped.${labelHint} Common cause: an effect that writes to a signal it also reads, without a guard. See packages/core/reactivity/src/batch.ts for the multi-pass flush contract.`);
+							}
+							pendingEffects.clear();
+							_nextEffectPass.clear();
+							break;
+						}
+						_visitedThisPass = /* @__PURE__ */ new Set();
+						for (const notify of pendingEffects) {
+							_visitedThisPass.add(notify);
+							notify();
+						}
+						pendingEffects.clear();
+						for (const next of _nextEffectPass) pendingEffects.add(next);
+						_nextEffectPass.clear();
+					}
 				}
 			} finally {
+				pendingRecomputes.clear();
+				pendingEffects.clear();
+				_nextEffectPass.clear();
+				_visitedThisPass = null;
 				batchDepth = 0;
 			}
 		}
@@ -28,7 +69,9 @@ function isBatching() {
 	return batchDepth > 0;
 }
 function enqueuePendingNotification(notify) {
-	pendingNotifications.add(notify);
+	if (_recomputes.has(notify)) pendingRecomputes.add(notify);
+	else if (_visitedThisPass !== null && _visitedThisPass.has(notify)) _nextEffectPass.add(notify);
+	else pendingEffects.add(notify);
 }
 /**
 * Returns a Promise that resolves after all currently-pending microtasks have flushed.
@@ -136,6 +179,7 @@ var EffectScope = class {
 	}
 	/** Register a callback to run after any reactive update in this scope. */
 	addUpdateHook(fn) {
+		if (!this._active) return;
 		if (this._updateHooks === null) this._updateHooks = [];
 		this._updateHooks.push(fn);
 	}
@@ -177,6 +221,31 @@ function setCurrentScope(scope) {
 function effectScope() {
 	return new EffectScope();
 }
+/**
+* Register a callback to run when the current `EffectScope` stops. Vue 3
+* parity. Must be called inside `scope.runInScope(fn)` — the registration
+* captures the ambient scope, so calling outside any scope is a no-op (with
+* a dev warning to surface the missing scope).
+*
+* Use to clean up resources tied to a scope's lifetime: timers, listeners,
+* external subscriptions. Equivalent to calling `getCurrentScope()?.add({
+* dispose: fn })` but with the scope capture handled.
+*
+* @example
+* scope.runInScope(() => {
+*   const ws = new WebSocket(url)
+*   onScopeDispose(() => ws.close())
+*   // ws.close() runs when scope.stop() is called
+* })
+*/
+function onScopeDispose(fn) {
+	const scope = _currentScope;
+	if (!scope) {
+		if (process.env.NODE_ENV !== "production") console.warn("[pyreon] onScopeDispose() called without an active EffectScope — callback will never run. Wrap the call in `scope.runInScope(() => { ... })` or check `getCurrentScope()` before calling.");
+		return;
+	}
+	scope.add({ dispose: fn });
+}
 
 //#endregion
 //#region src/tracking.ts
@@ -273,6 +342,17 @@ function runUntracked(fn) {
 //#endregion
 //#region src/effect.ts
 const _countSink$2 = globalThis;
+let _snapshotCapture = null;
+/**
+* Register a capture/restore pair so reactivity-layer effects (`_bind`,
+* `renderEffect`, `effect`) can preserve external context (e.g. the core
+* provide/useContext stack) across signal-driven re-runs. Called by
+* `@pyreon/core`'s context module at import time. Idempotent — calling again
+* replaces the previously registered hook.
+*/
+function setSnapshotCapture(hook) {
+	_snapshotCapture = hook;
+}
 let _cleanupCollector = null;
 /**
 * Register a cleanup function inside an effect. The cleanup runs:
@@ -295,11 +375,17 @@ function onCleanup(fn) {
 	if (_cleanupCollector) _cleanupCollector.push(fn);
 }
 let _innerEffectCollector = null;
-let _errorHandler = (err) => {
+const _errorBridge = globalThis;
+function _defaultErrorHandler(err) {
 	console.error("[pyreon] Unhandled effect error:", err);
+}
+let _userErrorHandler;
+const _errorHandler = (err) => {
+	(_userErrorHandler ?? _defaultErrorHandler)(err);
+	_errorBridge.__pyreon_report_error__?.(err, "effect");
 };
 function setErrorHandler(fn) {
-	_errorHandler = fn;
+	_userErrorHandler = fn;
 }
 /** Remove an effect from all dependency subscriber sets (local deps array). */
 function cleanupLocalDeps$1(deps, fn) {
@@ -312,7 +398,11 @@ function cleanupLocalDeps$1(deps, fn) {
 	}
 }
 function effect(fn) {
+	if (process.env.NODE_ENV !== "production") {
+		if (fn.constructor && fn.constructor.name === "AsyncFunction") console.warn("[pyreon] effect() received an async function. Signal reads after the first `await` are NOT tracked — only the synchronous prefix is. Read every tracked signal BEFORE any await, or split into separate effects, or use `watch(source, asyncCb)` for async-in-callback patterns.");
+	}
 	const scope = getCurrentScope();
+	const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null;
 	let disposed = false;
 	let isFirstRun = true;
 	let cleanup;
@@ -347,7 +437,7 @@ function effect(fn) {
 	};
 	const run = () => {
 		if (disposed) return;
-		if (import.meta.env?.DEV === true) _countSink$2.__pyreon_count__?.("reactivity.effectRun");
+		if (process.env.NODE_ENV !== "production") _countSink$2.__pyreon_count__?.("reactivity.effectRun");
 		runCleanup();
 		const outerCollector = _innerEffectCollector;
 		const myInners = [];
@@ -357,7 +447,7 @@ function effect(fn) {
 			setDepsCollector(deps);
 			const collected = [];
 			_cleanupCollector = collected;
-			cleanup = withTracking(run, fn) || void 0;
+			cleanup = withTracking(run, isFirstRun || snapshot === null || _snapshotCapture === null ? fn : () => _snapshotCapture.restore(snapshot, fn)) || void 0;
 			_cleanupCollector = null;
 			if (collected.length > 0) cleanups = collected;
 			setDepsCollector(null);
@@ -411,9 +501,11 @@ function effect(fn) {
 function _bind(fn) {
 	const deps = [];
 	let disposed = false;
+	const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null;
 	const run = () => {
 		if (disposed) return;
-		fn();
+		if (snapshot !== null && _snapshotCapture) _snapshotCapture.restore(snapshot, fn);
+		else fn();
 	};
 	setDepsCollector(deps);
 	withTracking(run, fn);
@@ -446,9 +538,14 @@ function renderEffectFullTrack(deps, run, fn) {
 	}
 }
 function renderEffect(fn) {
+	if (process.env.NODE_ENV !== "production") {
+		if (fn.constructor && fn.constructor.name === "AsyncFunction") console.warn("[pyreon] renderEffect() received an async function. Signal reads after the first `await` are NOT tracked — only the synchronous prefix is. Read every tracked signal BEFORE any await, or split into separate effects, or use `watch(source, asyncCb)` for async-in-callback patterns.");
+	}
 	const deps = [];
 	let disposed = false;
 	let isFirstRun = true;
+	const snapshot = _snapshotCapture ? _snapshotCapture.capture() : null;
+	const trackedFn = snapshot !== null && _snapshotCapture ? () => _snapshotCapture.restore(snapshot, fn) : fn;
 	const run = () => {
 		if (disposed) return;
 		if (isFirstRun) {
@@ -461,7 +558,7 @@ function renderEffect(fn) {
 				_restoreActiveEffect();
 				setDepsCollector(null);
 			}
-		} else renderEffectFullTrack(deps, run, fn);
+		} else renderEffectFullTrack(deps, run, trackedFn);
 	};
 	run();
 	const dispose = () => {
@@ -491,6 +588,9 @@ function trackWithLocalDeps(deps, effect, fn) {
 	return result;
 }
 function computed(fn, options) {
+	if (process.env.NODE_ENV !== "production") {
+		if (fn.constructor && fn.constructor.name === "AsyncFunction") console.warn("[pyreon] computed() received an async function. The result type becomes `Computed<Promise<T>>`, and signal reads after the first `await` are NOT tracked. Use `createResource` for async-derived state, or compute synchronously over a signal that holds the awaited value.");
+	}
 	return options?.equals ? computedWithEquals(fn, options.equals) : computedLazy(fn);
 }
 /**
@@ -517,10 +617,11 @@ function computedLazy(fn) {
 		if (host._s) notifySubscribers(host._s);
 		if (directFns) for (const f of directFns) f?.();
 	};
+	_markRecompute(recompute);
 	const read = () => {
 		trackSubscriber(host);
 		if (dirty) {
-			if (import.meta.env?.DEV === true) _countSink$1.__pyreon_count__?.("reactivity.computedRecompute");
+			if (process.env.NODE_ENV !== "production") _countSink$1.__pyreon_count__?.("reactivity.computedRecompute");
 			try {
 				if (tracked) {
 					setSkipDepsCollection(true);
@@ -576,7 +677,7 @@ function computedWithEquals(fn, equals) {
 	let directFns = null;
 	const recompute = () => {
 		if (disposed) return;
-		if (import.meta.env?.DEV === true) _countSink$1.__pyreon_count__?.("reactivity.computedRecompute");
+		if (process.env.NODE_ENV !== "production") _countSink$1.__pyreon_count__?.("reactivity.computedRecompute");
 		cleanupLocalDeps(deps, recompute);
 		try {
 			const next = trackWithLocalDeps(deps, recompute, fn);
@@ -591,10 +692,11 @@ function computedWithEquals(fn, equals) {
 		if (host._s) notifySubscribers(host._s);
 		if (directFns) for (const f of directFns) f?.();
 	};
+	_markRecompute(recompute);
 	const read = () => {
 		trackSubscriber(host);
 		if (dirty) {
-			if (import.meta.env?.DEV === true) _countSink$1.__pyreon_count__?.("reactivity.computedRecompute");
+			if (process.env.NODE_ENV !== "production") _countSink$1.__pyreon_count__?.("reactivity.computedRecompute");
 			cleanupLocalDeps(deps, recompute);
 			try {
 				value = trackWithLocalDeps(deps, recompute, fn);
@@ -664,12 +766,18 @@ function notifyBucket(bucket) {
 * const isSelected = createSelector(selectedId)
 * // In each row:
 * class: () => (isSelected(row.id) ? "selected" : "")
+*
+* @example
+* // Dynamic value spaces — call dispose() to release the per-value cache:
+* const isCurrentTab = createSelector(() => currentTabId())
+* onUnmount(() => isCurrentTab.dispose())
 */
 function createSelector(source) {
 	const subs = /* @__PURE__ */ new Map();
 	let current;
 	let initialized = false;
-	effect(() => {
+	let disposed = false;
+	const sourceEffect = effect(() => {
 		const next = source();
 		if (!initialized) {
 			initialized = true;
@@ -685,20 +793,30 @@ function createSelector(source) {
 		if (newBucket) notifyBucket(newBucket);
 	});
 	const hosts = /* @__PURE__ */ new Map();
-	return (value) => {
-		let host = hosts.get(value);
-		if (!host) {
-			let bucket = subs.get(value);
-			if (!bucket) {
-				bucket = /* @__PURE__ */ new Set();
-				subs.set(value, bucket);
+	const selector = ((value) => {
+		if (!disposed) {
+			let host = hosts.get(value);
+			if (!host) {
+				let bucket = subs.get(value);
+				if (!bucket) {
+					bucket = /* @__PURE__ */ new Set();
+					subs.set(value, bucket);
+				}
+				host = { _s: bucket };
+				hosts.set(value, host);
 			}
-			host = { _s: bucket };
-			hosts.set(value, host);
+			trackSubscriber(host);
 		}
-		trackSubscriber(host);
 		return Object.is(current, value);
+	});
+	selector.dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		sourceEffect.dispose();
+		subs.clear();
+		hosts.clear();
 	};
+	return selector;
 }
 
 //#endregion
@@ -793,17 +911,20 @@ function inspectSignal(sig) {
 
 //#endregion
 //#region src/signal.ts
-const __DEV__ = typeof process !== "undefined" && process?.env?.NODE_ENV !== "production";
 const _countSink = globalThis;
 function _peek() {
 	return this._v;
 }
 function _set(newValue) {
 	if (Object.is(this._v, newValue)) return;
-	if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("reactivity.signalWrite");
+	if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("reactivity.signalWrite");
 	const prev = this._v;
 	this._v = newValue;
-	if (isTracing()) _notifyTraceListeners(this, prev, newValue);
+	if (isTracing()) try {
+		_notifyTraceListeners(this, prev, newValue);
+	} catch (err) {
+		if (process.env.NODE_ENV !== "production") console.error("[pyreon] signal trace listener threw — listener is buggy. Subscribers continue uninterrupted.", err);
+	}
 	if (isBatching()) {
 		if (this._d) notifyDirect(this._d);
 		if (this._s) notifySubscribers(this._s);
@@ -860,9 +981,9 @@ function _debug() {
 * update, subscribe) are shared across all signals — not per-signal closures.
 */
 function signal(initialValue, options) {
-	if (import.meta.env?.DEV === true) _countSink.__pyreon_count__?.("reactivity.signalCreate");
+	if (process.env.NODE_ENV !== "production") _countSink.__pyreon_count__?.("reactivity.signalCreate");
 	const read = ((...args) => {
-		if (__DEV__ && args.length > 0) console.warn("[Pyreon] signal() was called with an argument. Use signal.set(value) or signal.update(fn) to write. signal(value) only reads — the argument is ignored.");
+		if (process.env.NODE_ENV !== "production" && args.length > 0) console.warn("[Pyreon] signal() was called with an argument. Use signal.set(value) or signal.update(fn) to write. signal(value) only reads — the argument is ignored.");
 		trackSubscriber(read);
 		return read._v;
 	});
@@ -896,7 +1017,38 @@ function signal(initialValue, options) {
 * state.items[0].text = "world"           // only text-tracking effects re-run
 */
 const proxyCache = /* @__PURE__ */ new WeakMap();
+const shallowProxyCache = /* @__PURE__ */ new WeakMap();
 const IS_STORE = Symbol("pyreon.store");
+const IS_RAW = Symbol("pyreon.raw");
+/**
+* Mark an object as RAW — `createStore` and `shallowReactive` will return it
+* unwrapped. Useful when storing class instances, third-party objects, or
+* other shapes that shouldn't be deeply proxied (Vue 3 parity).
+*
+* @example
+* const cm = markRaw(new CodeMirrorView(...))
+* const store = createStore({ editor: cm })
+* store.editor === cm  // true (not wrapped)
+*
+* Note: marking is one-way — there's no `unmarkRaw`. Mark BEFORE the object
+* enters a store; marking after wrap doesn't unwrap an existing proxy.
+*/
+function markRaw(value) {
+	Object.defineProperty(value, IS_RAW, {
+		value: true,
+		enumerable: false,
+		configurable: true,
+		writable: false
+	});
+	return value;
+}
+/** Returns true if the value was marked with `markRaw()`. */
+function isMarkedRaw(value) {
+	return value[IS_RAW] === true;
+}
+function isBuiltinNonProxiable(obj) {
+	return obj instanceof Map || obj instanceof Set || obj instanceof WeakMap || obj instanceof WeakSet || obj instanceof Date || obj instanceof RegExp || obj instanceof Promise || obj instanceof Error;
+}
 /** Returns true if the value is a createStore proxy. */
 function isStore(value) {
 	return value !== null && typeof value === "object" && value[IS_STORE] === true;
@@ -906,10 +1058,33 @@ function isStore(value) {
 * Returns a proxy — mutations to the proxy trigger fine-grained reactive updates.
 */
 function createStore(initial) {
-	return wrap(initial);
+	return wrap(initial, false);
+}
+/**
+* Create a SHALLOW reactive store — only top-level mutations trigger updates.
+* Nested objects are NOT auto-wrapped; reading a nested object returns the
+* raw reference. Use when:
+*   - the nested objects are immutable (frozen API responses)
+*   - you want explicit control over which subtrees are reactive
+*   - you need to store class instances or third-party objects without
+*     paying the deep-proxy overhead
+*
+* @example
+* const store = shallowReactive({ user: { name: 'Alice' }, count: 0 })
+* effect(() => console.log(store.user))  // tracks store.user reference
+* effect(() => console.log(store.count)) // tracks store.count
+* store.user.name = 'Bob'                // does NOT trigger any effect
+* store.count = 5                        // triggers the count effect
+* store.user = { name: 'Bob' }           // triggers the user effect
+*/
+function shallowReactive(initial) {
+	return wrap(initial, true);
 }
-function wrap(raw) {
-	const cached = proxyCache.get(raw);
+function wrap(raw, shallow) {
+	if (isBuiltinNonProxiable(raw)) return raw;
+	if (isMarkedRaw(raw)) return raw;
+	const cache = shallow ? shallowProxyCache : proxyCache;
+	const cached = cache.get(raw);
 	if (cached) return cached;
 	const propSignals = /* @__PURE__ */ new Map();
 	const isArray = Array.isArray(raw);
@@ -923,9 +1098,12 @@ function wrap(raw) {
 			if (key === IS_STORE) return true;
 			if (typeof key === "symbol") return target[key];
 			if (isArray && key === "length") return lengthSig?.();
-			if (!Object.hasOwn(target, key)) return target[key];
+			if (!Object.hasOwn(target, key)) {
+				if (propSignals.has(key)) return propSignals.get(key)?.();
+				return target[key];
+			}
 			const value = getOrCreateSignal(key)();
-			if (value !== null && typeof value === "object") return wrap(value);
+			if (!shallow && value !== null && typeof value === "object") return wrap(value, false);
 			return value;
 		},
 		set(target, key, value) {
@@ -946,10 +1124,7 @@ function wrap(raw) {
 		},
 		deleteProperty(target, key) {
 			delete target[key];
-			if (typeof key !== "symbol" && propSignals.has(key)) {
-				propSignals.get(key)?.set(void 0);
-				propSignals.delete(key);
-			}
+			if (typeof key !== "symbol" && propSignals.has(key)) propSignals.get(key)?.set(void 0);
 			if (isArray) lengthSig?.set(target.length);
 			return true;
 		},
@@ -963,7 +1138,7 @@ function wrap(raw) {
 			return Reflect.getOwnPropertyDescriptor(target, key);
 		}
 	});
-	proxyCache.set(raw, proxy);
+	cache.set(raw, proxy);
 	return proxy;
 }
 
@@ -1054,7 +1229,8 @@ function createResource(source, fetcher) {
 			loading.set(false);
 		});
 	};
-	effect(() => {
+	let disposed = false;
+	const sourceEffect = effect(() => {
 		const param = source();
 		runUntracked(() => doFetch(param));
 	});
@@ -1063,7 +1239,14 @@ function createResource(source, fetcher) {
 		loading,
 		error,
 		refetch() {
+			if (disposed) return;
 			runUntracked(() => doFetch(source()));
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			requestId++;
+			sourceEffect.dispose();
 		}
 	};
 }
@@ -1124,5 +1307,5 @@ function watch(source, callback, opts = {}) {
 }
 
 //#endregion
-export { Cell, EffectScope, _bind, batch, cell, computed, createResource, createSelector, createStore, effect, effectScope, getCurrentScope, inspectSignal, isStore, nextTick, onCleanup, onSignalUpdate, reconcile, renderEffect, runUntracked, runUntracked as untrack, setCurrentScope, setErrorHandler, signal, watch, why };
+export { Cell, EffectScope, _bind, batch, cell, computed, createResource, createSelector, createStore, effect, effectScope, getCurrentScope, inspectSignal, isStore, markRaw, nextTick, onCleanup, onScopeDispose, onSignalUpdate, reconcile, renderEffect, runUntracked, runUntracked as untrack, setCurrentScope, setErrorHandler, setSnapshotCapture, shallowReactive, signal, watch, why };
 //# sourceMappingURL=index.js.map