mutts 1.0.5 → 1.0.6

package/docs/reactive/debugging.md

@@ -0,0 +1,158 @@
+# Debugging Tools
+
+The `mutts` reactive system provides several built-in tools to help track down synchronization issues, dependency leaks, and infinite loops. These tools are primarily exposed through the `reactiveOptions` object.
+
+> [!WARNING]
+> **Performance Cost**: Most debugging tools incur a significant performance overhead. They should be enabled only during development or within test environments. Re-running computations for discrepancy detection, in particular, effectively doubles the cost of reactive updates.
+
+## The `reactiveOptions` Reference
+
+The `reactiveOptions` object (exported from `mutts/reactive`) allows you to hook into the reactive system's internals.
+
+```typescript
+import { reactiveOptions } from 'mutts/reactive';
+```
+
+### Lifecycle Hooks
+
+These hooks are called during the execution of effects and computed values.
+
+- **`enter(effect: Function)`**: Called when an effect or memoized function starts executing.
+- **`leave(effect: Function)`**: Called when an effect or memoized function finishes.
+- **`touched(obj: any, evolution: Evolution)`**: Called whenever a reactive object is "touched" (accessed or modified). This is the lowest-level hook for observing system activity.
+
+### Effect Chaining & Batching
+
+- **`beginChain(targets: Function[]) / endChain()`**: Called when a batch of effects starts and ends its execution.
+- **`maxEffectChain`**: (Default: `100`) Limits the depth of synchronous effect triggering to prevent stack overflows.
+- **`maxTriggerPerBatch`**: (Default: `10`) Limits how many times a single effect can be triggered within the same batch. Useful for detecting aggressive re-computation.
+
+## Cycle Detection
+
+`mutts` automatically detects circular dependencies (e.g., Effect A updates State X, which triggers Effect B, which updates State Y, which triggers Effect A).
+
+### Configuration
+
+You can control how cycles are handled via `reactiveOptions.cycleHandling`:
+
+- **`'throw'`** (Default): Throws a `ReactiveError` with a detailed path.
+- **`'warn'`**: Logs a warning but breaks the cycle to allow the application to continue.
+- **`'break'`**: Silently breaks the cycle.
+- **`'strict'`**: Performs a graph check *before* execution to prevent cycles from even starting. This has the highest overhead.
+
+## Memoization Discrepancy Detection
+
+The most powerful debugging tool in `mutts` is the **Discrepancy Detector**. It helps identify "missing dependencies"—reactive values used inside a computation that the system isn't tracking.
+
+### How it Works
+
+When `reactiveOptions.onMemoizationDiscrepancy` is set:
+1. Every time a `memoize()` function is called, it checks its cache.
+2. If a cached value exists, the function is immediately **executed a second time** in a completely untracked context.
+3. If the results differ, your callback is triggered.
+
+### Usage
+
+```typescript
+reactiveOptions.onMemoizationDiscrepancy = (cached, fresh, fn, args, cause) => {
+    console.error(`Discrepancy in ${fn.name || 'anonymous'}!`, {
+        cached,
+        fresh,
+        cause // 'calculation' or 'comparison'
+    });
+    throw new Error('Memoization discrepancy detected');
+};
+```
+
+If the cause is 'comparison', it means that, at first computation, calling the function twice gives different results.
+
+If the cause is 'calculation', it means that, when asked the value while the cache was still valid, the function returned a different result.
+
+### `isVerificationRun`
+
+During the "second run" of a discrepancy check, `reactiveOptions.isVerificationRun` is set to `true`. You can use this flag in your own code to avoid side effects (like incrementing counters) that should only happen once during the primary execution.
+
+> [!IMPORTANT]
+> Do not modify `isVerificationRun` manually; it is managed by the engine.
+
+## Introspection API
+
+For programmatic analysis of the reactive system, `mutts` provides a dedicated introspection module. This is particularly useful for AI agents and developer tools.
+
+```typescript
+import { enableIntrospection, getDependencyGraph, getMutationHistory, snapshot } from 'mutts/introspection';
+```
+
+### Enabling Introspection
+
+Introspection features (like history tracking) are memory-intensive and disabled by default.
+
+```typescript
+// Enable history tracking (default size: 50)
+enableIntrospection({ historySize: 100 });
+```
+
+### Dependency Graph
+
+You can retrieve the full dependency graph to understand how objects and effects are linked.
+
+```typescript
+const graph = getDependencyGraph();
+// Returns: { nodes: Array<EffectNode | ObjectNode>, edges: Array<GraphEdge> }
+```
+
+### Mutation History
+
+If `enableHistory` is on, you can inspect the sequence of mutations that have occurred.
+
+```typescript
+const history = getMutationHistory();
+// Each record contains type, property, old/new values, and causal source.
+```
+
+## Structured Error Handling
+
+When the reactive system encounters a critical failure (like a cycle or max depth exceeded), it throws a `ReactiveError` containing rich diagnostic information.
+
+### `ReactiveErrorCode`
+
+Always check `error.debugInfo.code` to identify the failure type:
+- `CYCLE_DETECTED`: A circular dependency was found.
+- `MAX_DEPTH_EXCEEDED`: The synchronous effect chain reached `maxEffectChain`.
+- `MAX_REACTION_EXCEEDED`: An effect was triggered too many times in a single batch.
+- `WRITE_IN_COMPUTED`: An attempt was made to modify reactive state inside a `memoize` or `derived` function.
+
+### Rich Debug Info
+
+The `debugInfo` property on `ReactiveError` includes:
+- **`causalChain`**: A string array describing the logical path of modifications leading to the error.
+- **`creationStack`**: The stack trace of where the effect was originally created, helping you locate the source in your code.
+- **`cycle`**: (For `CYCLE_DETECTED`) The names of the effects that form the loop.
+
+## Best Practices for Debugging
+
+### Naming Effects
+
+Always provide a name for your effects to make debug logs and error messages readable:
+
+```typescript
+effect(() => {
+    // ...
+}, { name: 'UpdateSidebarCounter' });
+```
+
+### Activation & Deactivation
+
+Since these are runtime options, you can toggle them based on your environment:
+
+```typescript
+if (process.env.NODE_ENV === 'development') {
+    reactiveOptions.cycleHandling = 'throw';
+    reactiveOptions.onMemoizationDiscrepancy = myHandler;
+    enableIntrospection();
+} else {
+    // Ensure they are off in production for performance
+    reactiveOptions.onMemoizationDiscrepancy = undefined;
+    reactiveOptions.cycleHandling = 'break';
+}
+```

package/docs/reactive.md

@@ -20,9 +20,10 @@ The Mutts Reactive System documentation has been split into focused sections for
 *   **[Memoization](./reactive/advanced.md#memoization)**: Caching strategies
 *   **[Debugging](./reactive/advanced.md#debugging-and-development)**: Cycle detection and troubleshooting
 
-## Debugging tools
+## [Debugging and Troubleshooting](./reactive/debugging.md)
+*   **[Reactive Options](./reactive/debugging.md#the-reactiveoptions-reference)**: Global debug hooks and configuration
+*   **[Cycle Detection](./reactive/debugging.md#cycle-detection)**: Configuration and troubleshooting circular dependencies
+*   **[Memoization Discrepancy](./reactive/debugging.md#memoization-discrepancy-detection)**: Identifying missing dependencies
+*   **[Introspection API](./reactive/debugging.md#introspection-api)**: Programmatic analysis and dependency graphs
 
-The reactive system is currently in a gamma state. The interface is quite fixed, the debugging tools are in place but :
-- still unfinished
-- not deactivatable
-- harming the performances of the application
+*   **[Performance](./reactive/debugging.md#performance-cost)**: Understanding the cost of debugging tools

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.5",
-  "main": "dist/index.js",
-  "module": "dist/index.esm.js",
-  "types": "dist/index.d.ts",
+  "version": "1.0.6",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,60 +13,7 @@
       "require": "./dist/index.js",
       "script": "./dist/mutts.umd.min.js"
     },
-    "./decorator": {
-      "types": "./dist/decorator.d.ts",
-      "source": "./src/decorator.ts",
-      "import": "./dist/decorator.esm.js",
-      "require": "./dist/decorator.js"
-    },
-    "./reactive": {
-      "types": "./dist/reactive.d.ts",
-      "source": "./src/reactive/index.ts",
-      "import": "./dist/reactive.esm.js",
-      "require": "./dist/reactive.js"
-    },
-    "./eventful": {
-      "types": "./dist/eventful.d.ts",
-      "source": "./src/eventful.ts",
-      "import": "./dist/eventful.esm.js",
-      "require": "./dist/eventful.js"
-    },
-    "./indexable": {
-      "types": "./dist/indexable.d.ts",
-      "source": "./src/indexable.ts",
-      "import": "./dist/indexable.esm.js",
-      "require": "./dist/indexable.js"
-    },
-    "./promiseChain": {
-      "types": "./dist/promiseChain.d.ts",
-      "source": "./src/promiseChain.ts",
-      "import": "./dist/promiseChain.esm.js",
-      "require": "./dist/promiseChain.js"
-    },
-    "./destroyable": {
-      "types": "./dist/destroyable.d.ts",
-      "source": "./src/destroyable.ts",
-      "import": "./dist/destroyable.esm.js",
-      "require": "./dist/destroyable.js"
-    },
-    "./std-decorators": {
-      "types": "./dist/std-decorators.d.ts",
-      "source": "./src/std-decorators.ts",
-      "import": "./dist/std-decorators.esm.js",
-      "require": "./dist/std-decorators.js"
-    },
-    "./src": {
-      "import": "./src/index.ts"
-    },
-    "./src/*": {
-      "import": "./src/*"
-    },
-    "./umd": {
-      "browser": "./dist/mutts.umd.js"
-    },
-    "./umd.min": {
-      "browser": "./dist/mutts.umd.min.js"
-    }
+    "./src/*": "./src/*"
   },
   "files": [
     "dist",
@@ -80,14 +27,14 @@
     "build": "npm run build:js && npm run build:devtools",
     "build:watch": "rollup -c --watch",
     "prepublishOnly": "npm run build",
-    "test": "node --expose-gc node_modules/.bin/jest",
-    "test:coverage": "node --expose-gc node_modules/.bin/jest --coverage",
-    "test:coverage:watch": "node --expose-gc node_modules/.bin/jest --coverage --watch",
-    "test:legacy": "TSCONFIG=tsconfig.legacy.json node node_modules/.bin/jest --detectOpenHandles --testPathPatterns=decorator",
-    "test:modern": "TSCONFIG=tsconfig.modern.json node node_modules/.bin/jest --detectOpenHandles --testPathPatterns=decorator",
-    "test:profile": "RUN_PROFILING=1 node --expose-gc node_modules/.bin/jest --testPathPatterns=profiling",
-    "test:profile:benchmark": "RUN_PROFILING=1 node --expose-gc node_modules/.bin/jest --testPathPatterns=profiling --testNamePattern=benchmark",
-    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/.bin/jest --testPathPatterns=profiling --no-coverage",
+    "test": "NODE_OPTIONS=--expose-gc jest",
+    "test:coverage": "NODE_OPTIONS=--expose-gc jest --coverage",
+    "test:coverage:watch": "NODE_OPTIONS=--expose-gc jest --coverage --watch",
+    "test:legacy": "TSCONFIG=tsconfig.legacy.json jest --detectOpenHandles --testPathPatterns=decorator",
+    "test:modern": "TSCONFIG=tsconfig.modern.json jest --detectOpenHandles --testPathPatterns=decorator",
+    "test:profile": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc jest --testPathPatterns=profiling",
+    "test:profile:benchmark": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc jest --testPathPatterns=profiling --testNamePattern=benchmark",
+    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/jest/bin/jest.js --testPathPatterns=profiling --no-coverage",
     "benchmark:save": "tsx tests/profiling/benchmark.ts save",
     "benchmark:compare": "tsx tests/profiling/benchmark.ts compare",
     "benchmark:list": "tsx tests/profiling/benchmark.ts list",
@@ -123,11 +70,14 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.6",
+    "@jest/globals": "^30.2.0",
     "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.10",
     "jest": "^30.0.4",
     "rollup": "^4.52.2",
     "rollup-plugin-copy": "^3.5.0",

package/src/decorator.ts

@@ -58,13 +58,15 @@ export type ModernClassDecorator<T> = (target: T, context: ClassDecoratorContext
 
 type DDMethod<T> = (
 	original: (this: T, ...args: any[]) => any,
+	target: any,
 	name: PropertyKey
 ) => ((this: T, ...args: any[]) => any) | void
 
-type DDGetter<T> = (original: (this: T) => any, name: PropertyKey) => ((this: T) => any) | void
+type DDGetter<T> = (original: (this: T) => any, target: any, name: PropertyKey) => ((this: T) => any) | void
 
 type DDSetter<T> = (
 	original: (this: T, value: any) => void,
+	target: any,
 	name: PropertyKey
 ) => ((this: T, value: any) => void) | void
 
@@ -153,17 +155,17 @@ export function legacyDecorator<T = any>(description: DecoratorDescription<T>):
 					if (!('getter' in description || 'setter' in description))
 						throw new Error('Decorator cannot be applied to a getter or setter')
 					if ('getter' in description) {
-						const newGetter = description.getter!(descriptor.get as any, propertyKey)
+						const newGetter = description.getter!(descriptor.get as any, target, propertyKey)
 						if (newGetter) descriptor.get = newGetter
 					}
 					if ('setter' in description) {
-						const newSetter = description.setter!(descriptor.set as any, propertyKey)
+						const newSetter = description.setter!(descriptor.set as any, target, propertyKey)
 						if (newSetter) descriptor.set = newSetter
 					}
 					return descriptor
 				} else if (typeof descriptor.value === 'function') {
 					if (!('method' in description)) throw new Error('Decorator cannot be applied to a method')
-					const newMethod = description.method!(descriptor.value, propertyKey)
+					const newMethod = description.method!(descriptor.value, target, propertyKey)
 					if (newMethod) descriptor.value = newMethod
 					return descriptor
 				}
@@ -196,23 +198,23 @@ export function modernDecorator<T = any>(description: DecoratorDescription<T>):
 				throw new Error('Decorator cannot be applied to a field')
 			case 'getter':
 				if (!('getter' in description)) throw new Error('Decorator cannot be applied to a getter')
-				return description.getter!(target, context.name)
+				return description.getter!(target, target, context.name)
 			case 'setter':
 				if (!('setter' in description)) throw new Error('Decorator cannot be applied to a setter')
-				return description.setter!(target, context.name)
+				return description.setter!(target, target, context.name)
 			case 'method':
 				if (!('method' in description)) throw new Error('Decorator cannot be applied to a method')
-				return description.method!(target, context.name)
+				return description.method!(target, target, context.name)
 			case 'accessor': {
 				if (!('getter' in description || 'setter' in description))
 					throw new Error('Decorator cannot be applied to a getter or setter')
 				const rv: Partial<ClassAccessorDecoratorResult<any, any>> = {}
 				if ('getter' in description) {
-					const newGetter = description.getter!(target.get, context.name)
+					const newGetter = description.getter!(target.get, target, context.name)
 					if (newGetter) rv.get = newGetter
 				}
 				if ('setter' in description) {
-					const newSetter = description.setter!(target.set, context.name)
+					const newSetter = description.setter!(target.set, target, context.name)
 					if (newSetter) rv.set = newSetter
 				}
 				return rv

package/src/destroyable.ts

@@ -125,7 +125,7 @@ export function Destroyable<
 		static destroy(obj: Destroyable) {
 			const destructor = Destroyable.destructors.get(obj)
 			if (!destructor) return false
-			fr.unregister(obj)
+			fr.unregister(obj[allocatedValues])
 			Destroyable.destructors.delete(obj)
 			Object.setPrototypeOf(obj, new Proxy({}, destroyedHandler))
 			// Clear all own properties
@@ -154,7 +154,7 @@ export function Destroyable<
 				myDestructor(allocated)
 			}
 			Destroyable.destructors.set(this, destruction)
-			fr.register(this, destruction, this)
+			fr.register(this, destruction, allocated)
 		}
 	}
 }
@@ -165,7 +165,7 @@ const forwardProperties = Symbol('forwardProperties')
  * Use with accessor properties or explicit get/set pairs
  */
 export const allocated = decorator({
-	setter(original, propertyKey) {
+	setter(original, _target, propertyKey) {
 		return function (value) {
 			this[allocatedValues][propertyKey] = value
 			return original.call(this, value)

package/src/index.ts

@@ -7,3 +7,49 @@ export * from './mixins'
 export * from './reactive'
 export * from './std-decorators'
 export * from './utils'
+
+import pkg from '../package.json'
+const { version } = pkg
+
+// Singleton verification
+const GLOBAL_MUTTS_KEY = '__MUTTS_INSTANCE__'
+const globalScope = 
+	(typeof globalThis !== 'undefined' ? globalThis : 
+	(typeof window !== 'undefined' ? window : 
+	(typeof global !== 'undefined' ? global : false))) as any
+if(globalScope) {
+	// Detect the source of this instance safely across different environments
+	let source = 'mutts/index'
+	try {
+		// @ts-ignore
+		if (typeof __filename !== 'undefined') source = __filename
+		// @ts-ignore
+		else {
+			// Using eval to avoid SyntaxError in CJS environments where import.meta is not allowed
+			const meta = eval('import.meta')
+			if (meta && meta.url) source = meta.url
+		}
+	} catch (e) {
+		// Fallback for environments where neither is available or accessible
+	}
+
+	const currentSourceInfo = {
+		version,
+		source,
+		timestamp: Date.now()
+	}
+
+	if (globalScope[GLOBAL_MUTTS_KEY]) {
+		const existing = globalScope[GLOBAL_MUTTS_KEY]
+		throw new Error(
+			`[Mutts] Multiple instances detected!\n` + 
+			`Existing instance: ${JSON.stringify(existing, null, 2)}\n` +
+			`New instance: ${JSON.stringify(currentSourceInfo, null, 2)}\n` +
+			`This usually happens when 'mutts' is both installed as a dependency and bundled, ` +
+			`or when different versions are loaded. ` +
+			`Please check your build configuration (aliases, externals) to ensure a single source of truth.`
+		)
+	}
+
+	globalScope[GLOBAL_MUTTS_KEY] = currentSourceInfo
+}

package/src/reactive/change.ts

@@ -3,7 +3,7 @@ import { bubbleUpChange, objectsWithDeepWatchers } from './deep-watch-state'
 import { getActiveEffect, isRunning } from './effect-context'
 import { batch, effectTrackers, hasBatched, opaqueEffects, recordActivation } from './effects'
 import { unwrap } from './proxy-state'
-import { watchers } from './tracking'
+import { watchers } from './registry'
 import { allProps, type Evolution, options, type ScopedCallback, type State } from './types'
 
 const states = new WeakMap<object, State>()

package/src/reactive/debug.ts

@@ -5,7 +5,7 @@
  * - Provides graph data for tooling (DevTools panel, etc.)
  */
 
-import { effectParent, effectToReactiveObjects, getRoot } from './tracking'
+import { effectParent, effectToReactiveObjects, getRoot } from './registry'
 import { allProps, type Evolution, options, type ScopedCallback } from './types'
 
 const EXTERNAL_SOURCE = Symbol('external-source')

package/src/reactive/deep-touch.ts

@@ -3,7 +3,7 @@ import { bubbleUpChange, objectsWithDeepWatchers } from './deep-watch-state'
 import { batch } from './effects'
 import { isNonReactive } from './non-reactive-state'
 import { unwrap } from './proxy-state'
-import { effectParent, watchers } from './tracking'
+import { effectParent, watchers } from './registry'
 import { allProps, type Evolution, options, type ScopedCallback } from './types'
 
 function isObject(value: any): value is object {

package/src/reactive/deep-watch.ts

@@ -6,7 +6,7 @@ import {
 import { effect } from './effects'
 import { isNonReactive } from './non-reactive-state'
 import { reactive, unwrap } from './proxy'
-import { markWithRoot } from './tracking'
+import { markWithRoot } from './registry'
 import { options, type ScopedCallback } from './types'
 
 function isObject(value: any): value is object {

package/src/reactive/effect-context.ts

@@ -1,4 +1,4 @@
-import { effectParent, getRoot } from './tracking'
+import { effectParent, getRoot } from './registry'
 import { ReactiveError, type ScopedCallback } from './types'
 
 /**
@@ -77,7 +77,7 @@ export function getActiveEffect() {
  * @returns The result of the function
  */
 export function withEffect<T>(effect: ScopedCallback | undefined, fn: () => T): T {
-	// console.log('[Mutts] withEffect', effect ? 'Active' : 'NULL');
+
 	if (getRoot(effect) === getRoot(getActiveEffect())) return fn()
 	stack.unshift(effect)
 	try {

package/src/reactive/effects.ts

@@ -8,16 +8,18 @@ import {
 	withEffect,
 	withEffectStack,
 } from './effect-context'
+import {
+	getTrackingDisabled,
+	setTrackingDisabled,
+} from './tracking'
 import {
 	effectChildren,
 	effectParent,
 	effectToReactiveObjects,
 	getRoot,
-	getTrackingDisabled,
 	markWithRoot,
-	setTrackingDisabled,
 	watchers,
-} from './tracking'
+} from './registry'
 import {
 	type DependencyAccess,
 	type EffectOptions,
@@ -27,6 +29,8 @@ import {
 	ReactiveErrorCode,
 	// type AsyncExecutionMode,
 	type ScopedCallback,
+	cleanup as cleanupSymbol,
+	stopped,
 } from './types'
 
 /**
@@ -297,6 +301,7 @@ function addGraphEdge(callerRoot: Function, targetRoot: Function) {
  * @param end - Target node
  * @param exclude - Node to exclude from the path
  * @returns true if a path exists without going through the excluded node
+ * @todo Can be REALLY costly - optimise or make optional or ...
  */
 function hasPathExcluding(start: Function, end: Function, exclude: Function): boolean {
 	if (start === end) return true
@@ -621,6 +626,11 @@ function wouldCreateCycle(callerRoot: Function, targetRoot: Function): boolean {
  * @param immediate - If true, don't create edges in the dependency graph
  */
 function addToBatch(effect: ScopedCallback, caller?: ScopedCallback, immediate?: boolean) {
+	const cleanupFn = (effect as any)[cleanupSymbol]
+	if (cleanupFn) cleanupFn()
+	// If the effect was stopped during cleanup (e.g. lazy memoization), don't add it to the batch
+	if ((effect as any)[stopped]) return
+
 	if (!batchQueue) return
 
 	const root = getRoot(effect)
@@ -1085,21 +1095,21 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
  */
 export const atomic = decorator({
 	method(original) {
-		return function (...args: any[]) {
-			return batch(
-				markWithRoot(() => original.apply(this, args), original),
-				'immediate'
-			)
+		return function (this: any, ...args: any[]) {
+			const atomicEffect = () => original.apply(this, args)
+			// Debug: helpful to have a name
+			Object.defineProperty(atomicEffect, 'name', { value: `atomic(${original.name})` })
+			return batch(atomicEffect, 'immediate')
 		}
 	},
 	default<Args extends any[], Return>(
 		original: (...args: Args) => Return
 	): (...args: Args) => Return {
 		return function (this: any, ...args: Args) {
-			return batch(
-				markWithRoot(() => original.apply(this, args), original),
-				'immediate'
-			)
+			const atomicEffect = () => original.apply(this, args)
+			// Debug: helpful to have a name
+			Object.defineProperty(atomicEffect, 'name', { value: `atomic(${original.name})` })
+			return batch(atomicEffect, 'immediate')
 		}
 	},
 })
@@ -1138,7 +1148,7 @@ export function effect(
 	let cleanup: (() => void) | null = null
 	// capture the parent effect at creation time for ascend
 	const parentsForAscend = captureEffectStack()
-	const tracked = markWithRoot(<T>(cb: () => T) => withEffect(runEffect, cb), fn)
+	const tracked = <T>(cb: () => T) => withEffect(runEffect, cb)
 	const ascend = <T>(cb: () => T) => withEffectStack(parentsForAscend, cb)
 	let effectStopped = false
 	let hasReacted = false
@@ -1282,8 +1292,25 @@ export function effect(
 		cleanupEffectFromGraph(runEffect)
 		fr.unregister(stopEffect)
 	}
+	function augmentedRv(rv: ScopedCallback): ScopedCallback {
+		Object.defineProperty(rv, stopped, {
+			get() {
+				return effectStopped
+			},
+		})
+		Object.defineProperty(rv, cleanupSymbol, {
+			value: () => {
+				if (cleanup) {
+					const prevCleanup = cleanup
+					cleanup = null
+					withEffect(undefined, () => prevCleanup())
+				}
+			},
+		})
+		return rv
+	}
 	if (isRootEffect) {
-		const callIfCollected = () => stopEffect()
+		const callIfCollected = augmentedRv(() => stopEffect())
 		fr.register(
 			callIfCollected,
 			() => {
@@ -1300,15 +1327,16 @@ export function effect(
 		children = new Set()
 		effectChildren.set(parent, children)
 	}
-	const subEffectCleanup = (): void => {
+	const subEffectCleanup = augmentedRv(() => {
 		children.delete(subEffectCleanup)
 		if (children.size === 0) {
 			effectChildren.delete(parent)
 		}
 		// Execute this child effect cleanup (which triggers its own mainCleanup)
 		stopEffect()
-	}
+	})
 	children.add(subEffectCleanup)
+
 	return subEffectCleanup
 }
 

package/src/reactive/index.ts

@@ -52,7 +52,7 @@ import { ReactiveMap, ReactiveWeakMap } from './map'
 import { nonReactiveObjects, registerNativeReactivity } from './non-reactive-state'
 import { objectToProxy, proxyToObject } from './proxy'
 import { ReactiveSet, ReactiveWeakSet } from './set'
-import { effectToReactiveObjects, watchers } from './tracking'
+import { effectToReactiveObjects, watchers } from './registry'
 
 // Register native collection types to use specialized reactive wrappers
 registerNativeReactivity(WeakMap, ReactiveWeakMap)