@pyreon/reactivity 0.15.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":"22680e1b-1","name":"batch.ts"},{"uid":"22680e1b-3","name":"cell.ts"},{"uid":"22680e1b-5","name":"scope.ts"},{"uid":"22680e1b-7","name":"tracking.ts"},{"uid":"22680e1b-9","name":"effect.ts"},{"uid":"22680e1b-11","name":"computed.ts"},{"uid":"22680e1b-13","name":"createSelector.ts"},{"uid":"22680e1b-15","name":"debug.ts"},{"uid":"22680e1b-17","name":"signal.ts"},{"uid":"22680e1b-19","name":"store.ts"},{"uid":"22680e1b-21","name":"reconcile.ts"},{"uid":"22680e1b-23","name":"resource.ts"},{"uid":"22680e1b-25","name":"watch.ts"},{"uid":"22680e1b-27","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"22680e1b-1":{"renderedLength":2427,"gzipLength":977,"brotliLength":0,"metaUid":"22680e1b-0"},"22680e1b-3":{"renderedLength":1636,"gzipLength":786,"brotliLength":0,"metaUid":"22680e1b-2"},"22680e1b-5":{"renderedLength":1977,"gzipLength":786,"brotliLength":0,"metaUid":"22680e1b-4"},"22680e1b-7":{"renderedLength":2227,"gzipLength":858,"brotliLength":0,"metaUid":"22680e1b-6"},"22680e1b-9":{"renderedLength":7391,"gzipLength":2397,"brotliLength":0,"metaUid":"22680e1b-8"},"22680e1b-11":{"renderedLength":4548,"gzipLength":1464,"brotliLength":0,"metaUid":"22680e1b-10"},"22680e1b-13":{"renderedLength":1810,"gzipLength":833,"brotliLength":0,"metaUid":"22680e1b-12"},"22680e1b-15":{"renderedLength":2469,"gzipLength":1092,"brotliLength":0,"metaUid":"22680e1b-14"},"22680e1b-17":{"renderedLength":2626,"gzipLength":1125,"brotliLength":0,"metaUid":"22680e1b-16"},"22680e1b-19":{"renderedLength":2879,"gzipLength":1056,"brotliLength":0,"metaUid":"22680e1b-18"},"22680e1b-21":{"renderedLength":2109,"gzipLength":867,"brotliLength":0,"metaUid":"22680e1b-20"},"22680e1b-23":{"renderedLength":1029,"gzipLength":475,"brotliLength":0,"metaUid":"22680e1b-22"},"22680e1b-25":{"renderedLength":1249,"gzipLength":582,"brotliLength":0,"metaUid":"22680e1b-24"},"22680e1b-27":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"22680e1b-26"}},"nodeMetas":{"22680e1b-0":{"id":"/src/batch.ts","moduleParts":{"index.js":"22680e1b-1"},"imported":[],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-10"},{"uid":"22680e1b-16"},{"uid":"22680e1b-6"}]},"22680e1b-2":{"id":"/src/cell.ts","moduleParts":{"index.js":"22680e1b-3"},"imported":[],"importedBy":[{"uid":"22680e1b-26"}]},"22680e1b-4":{"id":"/src/scope.ts","moduleParts":{"index.js":"22680e1b-5"},"imported":[],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-10"},{"uid":"22680e1b-8"}]},"22680e1b-6":{"id":"/src/tracking.ts","moduleParts":{"index.js":"22680e1b-7"},"imported":[{"uid":"22680e1b-0"}],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-10"},{"uid":"22680e1b-12"},{"uid":"22680e1b-8"},{"uid":"22680e1b-22"},{"uid":"22680e1b-16"}]},"22680e1b-8":{"id":"/src/effect.ts","moduleParts":{"index.js":"22680e1b-9"},"imported":[{"uid":"22680e1b-4"},{"uid":"22680e1b-6"}],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-10"},{"uid":"22680e1b-12"},{"uid":"22680e1b-22"},{"uid":"22680e1b-24"}]},"22680e1b-10":{"id":"/src/computed.ts","moduleParts":{"index.js":"22680e1b-11"},"imported":[{"uid":"22680e1b-0"},{"uid":"22680e1b-8"},{"uid":"22680e1b-4"},{"uid":"22680e1b-6"}],"importedBy":[{"uid":"22680e1b-26"}]},"22680e1b-12":{"id":"/src/createSelector.ts","moduleParts":{"index.js":"22680e1b-13"},"imported":[{"uid":"22680e1b-8"},{"uid":"22680e1b-6"}],"importedBy":[{"uid":"22680e1b-26"}]},"22680e1b-14":{"id":"/src/debug.ts","moduleParts":{"index.js":"22680e1b-15"},"imported":[],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-16"}]},"22680e1b-16":{"id":"/src/signal.ts","moduleParts":{"index.js":"22680e1b-17"},"imported":[{"uid":"22680e1b-0"},{"uid":"22680e1b-14"},{"uid":"22680e1b-6"}],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-22"},{"uid":"22680e1b-18"}]},"22680e1b-18":{"id":"/src/store.ts","moduleParts":{"index.js":"22680e1b-19"},"imported":[{"uid":"22680e1b-16"}],"importedBy":[{"uid":"22680e1b-26"},{"uid":"22680e1b-20"}]},"22680e1b-20":{"id":"/src/reconcile.ts","moduleParts":{"index.js":"22680e1b-21"},"imported":[{"uid":"22680e1b-18"}],"importedBy":[{"uid":"22680e1b-26"}]},"22680e1b-22":{"id":"/src/resource.ts","moduleParts":{"index.js":"22680e1b-23"},"imported":[{"uid":"22680e1b-8"},{"uid":"22680e1b-16"},{"uid":"22680e1b-6"}],"importedBy":[{"uid":"22680e1b-26"}]},"22680e1b-24":{"id":"/src/watch.ts","moduleParts":{"index.js":"22680e1b-25"},"imported":[{"uid":"22680e1b-8"}],"importedBy":[{"uid":"22680e1b-26"}]},"22680e1b-26":{"id":"/src/index.ts","moduleParts":{"index.js":"22680e1b-27"},"imported":[{"uid":"22680e1b-0"},{"uid":"22680e1b-2"},{"uid":"22680e1b-10"},{"uid":"22680e1b-12"},{"uid":"22680e1b-14"},{"uid":"22680e1b-8"},{"uid":"22680e1b-20"},{"uid":"22680e1b-22"},{"uid":"22680e1b-4"},{"uid":"22680e1b-16"},{"uid":"22680e1b-18"},{"uid":"22680e1b-6"},{"uid":"22680e1b-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

@@ -30,7 +30,19 @@ function batch(fn) {
 					pendingRecomputes.clear();
 					if (pendingEffects.size > 0) {
 						if (++effectPass > MAX_PASSES) {
-							if (__DEV__) console.warn(`[pyreon] batch effect flush exceeded MAX_PASSES (32) — possible infinite re-enqueue loop. ${pendingEffects.size} pending effects dropped. See packages/core/reactivity/src/batch.ts for the multi-pass flush contract.`);
+							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();
@@ -167,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);
 	}
@@ -208,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
@@ -728,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;
@@ -749,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
@@ -866,7 +920,11 @@ function _set(newValue) {
 	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);
@@ -959,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;
@@ -969,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);
 }
-function wrap(raw) {
-	const cached = proxyCache.get(raw);
+/**
+* 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, 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);
@@ -986,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) {
@@ -1009,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;
 		},
@@ -1026,7 +1138,7 @@ function wrap(raw) {
 			return Reflect.getOwnPropertyDescriptor(target, key);
 		}
 	});
-	proxyCache.set(raw, proxy);
+	cache.set(raw, proxy);
 	return proxy;
 }
 
@@ -1117,7 +1229,8 @@ function createResource(source, fetcher) {
 			loading.set(false);
 		});
 	};
-	effect(() => {
+	let disposed = false;
+	const sourceEffect = effect(() => {
 		const param = source();
 		runUntracked(() => doFetch(param));
 	});
@@ -1126,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();
 		}
 	};
 }
@@ -1187,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, setSnapshotCapture, 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

package/lib/types/index.d.ts

@@ -71,6 +71,19 @@ interface ComputedOptions<T> {
 declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): Computed<T>;
 //#endregion
 //#region src/createSelector.d.ts
+/** Selector predicate with a `dispose()` method to release internal state. */
+interface Selector<T> {
+  (value: T): boolean;
+  /**
+   * Stop the source-tracking effect AND clear the per-value subscriber/host
+   * Maps. After dispose, calls to the selector return the last-known result
+   * but no longer track. Required for selectors over dynamic value spaces
+   * (UUIDs, ephemeral IDs) created outside an `EffectScope` — without it,
+   * each unique queried value adds a permanent entry to the internal Maps,
+   * leaking memory for the lifetime of the program. Idempotent.
+   */
+  dispose(): void;
+}
 /**
  * Create an equality selector — returns a reactive predicate that is true
  * only for the currently selected value.
@@ -83,8 +96,13 @@ declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): Compute
  * 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())
  */
-declare function createSelector<T>(source: () => T): (value: T) => boolean;
+declare function createSelector<T>(source: () => T): Selector<T>;
 //#endregion
 //#region src/signal.d.ts
 interface SignalDebugInfo<T> {
@@ -120,7 +138,11 @@ interface Signal<T> {
    * Returns a disposer that nulls the slot.
    */
   direct(updater: () => void): () => void;
-  /** Debug name — useful for devtools and logging. */
+  /**
+   * Debug name — useful for devtools and logging. Set via the `name` option at
+   * creation; can be reassigned at any time (`s.label = 'renamed'`) since it's
+   * stored as a regular own property on the signal function.
+   */
   label: string | undefined;
   /** Returns a snapshot of the signal's debug info (value, name, subscriber count). */
   debug(): SignalDebugInfo<T>;
@@ -286,6 +308,13 @@ interface Resource<T> {
   error: Signal<unknown>;
   /** Re-run the fetcher with the current source value. */
   refetch(): void;
+  /**
+   * Stop the source-tracking effect. After dispose(), source changes no
+   * longer trigger fetches and any in-flight response is ignored. Idempotent.
+   * Required for resources created outside an `EffectScope` to avoid leaking
+   * the source-tracking effect for the lifetime of the program.
+   */
+  dispose(): void;
 }
 /**
  * Async data primitive. Fetches data reactively whenever `source()` changes.
@@ -330,6 +359,24 @@ declare function getCurrentScope(): EffectScope | null;
 declare function setCurrentScope(scope: EffectScope | null): void;
 /** Create a new EffectScope. */
 declare function effectScope(): 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
+ * })
+ */
+declare function onScopeDispose(fn: () => void): void;
 //#endregion
 //#region src/store.d.ts
 /**
@@ -346,6 +393,20 @@ declare function effectScope(): EffectScope;
  * state.count++                           // only the count effect re-runs
  * state.items[0].text = "world"           // only text-tracking effects re-run
  */
+/**
+ * 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.
+ */
+declare function markRaw<T extends object>(value: T): T;
 /** Returns true if the value is a createStore proxy. */
 declare function isStore(value: unknown): boolean;
 /**
@@ -353,6 +414,24 @@ declare function isStore(value: unknown): boolean;
  * Returns a proxy — mutations to the proxy trigger fine-grained reactive updates.
  */
 declare function createStore<T extends object>(initial: T): T;
+/**
+ * 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
+ */
+declare function shallowReactive<T extends object>(initial: T): T;
 //#endregion
 //#region src/tracking.d.ts
 /** Read signals without subscribing. Alias: `untrack`. */
@@ -386,5 +465,5 @@ interface WatchOptions {
  */
 declare function watch<T>(source: () => T, callback: (newVal: T, oldVal: T | undefined) => void | (() => void), opts?: WatchOptions): () => void;
 //#endregion
-export { Cell, type Computed, type ComputedOptions, type Effect, EffectScope, type ReactiveSnapshotCapture, type ReadonlySignal, type Resource, type Signal, type SignalDebugInfo, type SignalOptions, type WatchOptions, _bind, batch, cell, computed, createResource, createSelector, createStore, effect, effectScope, getCurrentScope, inspectSignal, isStore, nextTick, onCleanup, onSignalUpdate, reconcile, renderEffect, runUntracked, runUntracked as untrack, setCurrentScope, setErrorHandler, setSnapshotCapture, signal, watch, why };
+export { Cell, type Computed, type ComputedOptions, type Effect, EffectScope, type ReactiveSnapshotCapture, type ReadonlySignal, type Resource, type Signal, type SignalDebugInfo, type SignalOptions, type WatchOptions, _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=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/reactivity",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Signals-based reactivity system for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/reactivity#readme",
   "bugs": {

package/src/batch.ts

@@ -102,13 +102,33 @@ export function batch(fn: () => void): void {
           if (pendingEffects.size > 0) {
             if (++effectPass > MAX_PASSES) {
               if (__DEV__) {
+                // Surface labels of dropped effects when available — helps
+                // identify the offending effect in a real app. Falls back to
+                // bare count for anonymous effects.
+                const droppedCount = pendingEffects.size
+                const labels: string[] = []
+                for (const notify of pendingEffects) {
+                  const label = (notify as { _label?: string })._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` : ''}.`
+                  : ''
                 // oxlint-disable-next-line no-console
                 console.warn(
                   '[pyreon] batch effect flush exceeded MAX_PASSES (32) — possible infinite re-enqueue loop. ' +
-                    `${pendingEffects.size} pending effects dropped. ` +
+                    `${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.',
                 )
               }
+              // Drop the queue so subsequent batches start clean — without
+              // this, the next batch would re-encounter the offending effect
+              // immediately on its first pass and trip MAX_PASSES instantly,
+              // making the original error harder to diagnose.
+              pendingEffects.clear()
+              _nextEffectPass.clear()
               break
             }
             _visitedThisPass = new Set<() => void>()

package/src/createSelector.ts

@@ -21,6 +21,20 @@ function notifyBucket(bucket: Set<() => void>): void {
   }
 }
 
+/** Selector predicate with a `dispose()` method to release internal state. */
+export interface Selector<T> {
+  (value: T): boolean
+  /**
+   * Stop the source-tracking effect AND clear the per-value subscriber/host
+   * Maps. After dispose, calls to the selector return the last-known result
+   * but no longer track. Required for selectors over dynamic value spaces
+   * (UUIDs, ephemeral IDs) created outside an `EffectScope` — without it,
+   * each unique queried value adds a permanent entry to the internal Maps,
+   * leaking memory for the lifetime of the program. Idempotent.
+   */
+  dispose(): void
+}
+
 /**
  * Create an equality selector — returns a reactive predicate that is true
  * only for the currently selected value.
@@ -33,13 +47,19 @@ function notifyBucket(bucket: Set<() => void>): void {
  * 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())
  */
-export function createSelector<T>(source: () => T): (value: T) => boolean {
+export function createSelector<T>(source: () => T): Selector<T> {
   const subs = new Map<T, Set<() => void>>()
   let current: T
   let initialized = false
+  let disposed = false
 
-  effect(() => {
+  const sourceEffect = effect(() => {
     const next = source()
     if (!initialized) {
       initialized = true
@@ -60,18 +80,30 @@ export function createSelector<T>(source: () => T): (value: T) => boolean {
   // Reusable hosts per value — avoids allocating a closure per trackSubscriber call
   const hosts = new Map<T, { _s: Set<() => void> | null }>()
 
-  return (value: T): boolean => {
-    let host = hosts.get(value)
-    if (!host) {
-      let bucket = subs.get(value)
-      if (!bucket) {
-        bucket = new Set()
-        subs.set(value, bucket)
+  const selector = ((value: T): boolean => {
+    if (!disposed) {
+      let host = hosts.get(value)
+      if (!host) {
+        let bucket = subs.get(value)
+        if (!bucket) {
+          bucket = 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)
+  }) as Selector<T>
+
+  selector.dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    sourceEffect.dispose()
+    subs.clear()
+    hosts.clear()
   }
+
+  return selector
 }

package/src/index.ts

@@ -17,7 +17,13 @@ export {
 } from './effect'
 export { reconcile } from './reconcile'
 export { createResource, type Resource } from './resource'
-export { EffectScope, effectScope, getCurrentScope, setCurrentScope } from './scope'
+export {
+  EffectScope,
+  effectScope,
+  getCurrentScope,
+  onScopeDispose,
+  setCurrentScope,
+} from './scope'
 export {
   type ReadonlySignal,
   type Signal,
@@ -25,6 +31,6 @@ export {
   type SignalOptions,
   signal,
 } from './signal'
-export { createStore, isStore } from './store'
+export { createStore, isStore, markRaw, shallowReactive } from './store'
 export { runUntracked, runUntracked as untrack } from './tracking'
 export { type WatchOptions, watch } from './watch'