mutts 1.0.7 → 1.0.9

package/src/reactive/effects.ts

@@ -1,24 +1,29 @@
+import { named } from '../utils'
+import { getTriggerChain, isDevtoolsEnabled, registerEffectForDebug } from '../../debug/debug'
+import { effectMarker, getStackFrame, type StackFrame } from '../../debug/lineage'
 import { decorator } from '../decorator'
+import { flavored, flavorOptions } from '../flavored'
 import { IterableWeakSet } from '../iterableWeak'
-import { getTriggerChain, isDevtoolsEnabled, registerEffectForDebug } from './debug'
-import {
-	effectAggregator,
-	effectHistory,
-	getActiveEffect,
-} from './effect-context'
+import { effectAggregator, effectHistory, getActiveEffect } from './effect-context'
+import { unwrap } from './proxy-state'
 import {
-	effectChildren,
-	effectParent,
 	effectToReactiveObjects,
+	getEffectNode,
 	getRoot,
 	markWithRoot,
+	resetRegistry,
 	watchers,
 } from './registry'
 import {
+	type CatchFunction,
 	cleanup as cleanupSymbol,
-	type DependencyAccess,
+	type EffectAccess,
+	type EffectCleanup,
+	type EffectCloser,
 	type EffectOptions,
+	type EffectTrigger,
 	type Evolution,
+	optionCall,
 	options,
 	ReactiveError,
 	ReactiveErrorCode,
@@ -27,8 +32,6 @@ import {
 	stopped,
 } from './types'
 
-import { unwrap } from './proxy-state'
-
 /**
  * Finds a cycle in a sequence of functions by looking for the first repetition
  */
@@ -55,10 +58,10 @@ function formatRoots(roots: Function[], limit = 20): string {
 	return `${start.join(' → ')} ... (${names.length - 15} more) ... ${end.join(' → ')}`
 }
 
-type EffectTracking = (obj: any, evolution: Evolution, prop: any) => void
+type EffectTracking = (obj: any, evolution: Evolution, prop: any, effect: EffectTrigger) => void
 
 export interface ActivationRecord {
-	effect: ScopedCallback
+	effect: EffectTrigger
 	obj: any
 	evolution: Evolution
 	prop: any
@@ -71,16 +74,17 @@ let activationRegistry: Map<Function, Map<any, Map<any, number>>> | undefined
 
 export const activationLog: Omit<ActivationRecord, 'batchId'>[] = new Array(100)
 
+/**
+ * Returns the activation log containing recent effect activations for debugging.
+ * The log is a circular buffer of the last 100 activations.
+ *
+ * @returns Array of activation records
+ */
 export function getActivationLog() {
 	return activationLog
 }
 
-export function recordActivation(
-	effect: ScopedCallback,
-	obj: any,
-	evolution: Evolution,
-	prop: any
-) {
+export function recordActivation(effect: EffectTrigger, obj: any, evolution: Evolution, prop: any) {
 	const root = getRoot(effect)
 
 	if (!activationRegistry) return
@@ -130,7 +134,7 @@ export function recordActivation(
  * - The specific property that changed
  *
  * **Note:** The tracker callback is automatically removed after being called once. If you need
- * to track multiple triggers, call `trackEffect` again within the effect.
+ * to track multiple triggers, call `onEffectTrigger` again within the effect.
  *
  * @param onTouch - Callback function that receives (obj, evolution, prop) when the effect is triggered
  * @throws {Error} If called outside of an effect context
@@ -141,7 +145,7 @@ export function recordActivation(
  *
  * effect(() => {
  *   // Register a tracker to see what triggers this effect
- *   trackEffect((obj, evolution, prop) => {
+ *   onEffectTrigger((obj, evolution, prop) => {
  *     console.log(`Effect triggered by:`, {
  *       object: obj,
  *       change: evolution.type,
@@ -154,33 +158,53 @@ export function recordActivation(
  * })
  *
  * state.count = 5
- * // Logs: Effect triggered by: { object: state, change: 'set', property: 'count' }
  * ```
  */
-export function trackEffect(onTouch: EffectTracking) {
-	const activeEffect = getActiveEffect()
-	if (!activeEffect) throw new Error('Not in an effect')
-	if (!effectTrackers.has(activeEffect)) effectTrackers.set(activeEffect, new Set([onTouch]))
-	else effectTrackers.get(activeEffect)!.add(onTouch)
+export function onEffectTrigger(onTouch: EffectTracking, effect?: EffectTrigger) {
+	effect ??= getActiveEffect()
+	if (!effect) throw new Error('Tracking an effect trigger while not in an effect')
+	const node = getEffectNode(effect)
+	if (!node.trackers) node.trackers = [onTouch]
+	else node.trackers.push(onTouch)
 }
 
-const effectTrackers = new WeakMap<ScopedCallback, Set<EffectTracking>>()
-
-export const opaqueEffects = new WeakSet<ScopedCallback>()
+export function raiseEffectTrackers(
+	effect: EffectTrigger,
+	obj: any,
+	evolution: Evolution,
+	prop: any
+) {
+	const node = getEffectNode(effect)
+	const trackers = node.trackers
+	if (trackers) {
+		for (const tracker of trackers) tracker(obj, evolution, prop, effect)
+	}
+}
+export function onEffectThrow(onThrow: CatchFunction, effect?: EffectTrigger) {
+	effect ??= getActiveEffect()
+	if (!effect) throw new Error('Tracking an effect throw while not in an effect')
+	const node = getEffectNode(effect)
+	if (!node.catchers) node.catchers = [onThrow]
+	else node.catchers.push(onThrow)
+}
 
 // Dependency graph: tracks which effects trigger which other effects
 // Uses roots (Function) as keys for consistency
-const effectTriggers = new WeakMap<Function, IterableWeakSet<Function>>()
-const effectTriggeredBy = new WeakMap<Function, IterableWeakSet<Function>>()
+let effectTriggers = new WeakMap<Function, IterableWeakSet<Function>>()
+let effectTriggeredBy = new WeakMap<Function, IterableWeakSet<Function>>()
 
 // Transitive closures: track all indirect relationships
 // causesClosure: for each effect, all effects that trigger it (directly or indirectly)
 // consequencesClosure: for each effect, all effects that it triggers (directly or indirectly)
-const causesClosure = new WeakMap<Function, IterableWeakSet<Function>>()
-const consequencesClosure = new WeakMap<Function, IterableWeakSet<Function>>()
+let causesClosure = new WeakMap<Function, IterableWeakSet<Function>>()
+let consequencesClosure = new WeakMap<Function, IterableWeakSet<Function>>()
+
+// Batch re-entrance depth and broken state
+let batchDepth = 0
+let broken = false
 
 // Debug: Capture where an effect was created
-export const effectCreationStacks = new WeakMap<Function, string>()
+export const effectCreationStacks = new WeakMap<Function, StackFrame[]>()
 
 /**
  * Gets or creates an IterableWeakSet for a closure map
@@ -204,14 +228,10 @@ function getOrCreateClosure(
  * @param targetRoot - Root function of the effect being triggered
  */
 function addGraphEdge(callerRoot: Function, targetRoot: Function) {
-	if (options.cycleHandling === 'none') return
-	// Skip if edge already exists
+	if (options.cycleHandling === 'production') return
+	// Add to forward graph: callerRoot → targetRoot
 	const triggers = effectTriggers.get(callerRoot)
-	if (triggers?.has(targetRoot)) {
-		return // Edge already exists
-	}
 
-	// Add to forward graph: callerRoot → targetRoot
 	if (!triggers) {
 		const newTriggers = new IterableWeakSet<Function>()
 		newTriggers.add(targetRoot)
@@ -274,7 +294,7 @@ function addGraphEdge(callerRoot: Function, targetRoot: Function) {
 	}
 
 	// 4. Cross-product: for each X in causesClosure(U) and Y in consequencesClosure(V): X→Y
-	if (uCausesSet && vConsequencesSet) {
+	if (uCausesSet?.size && vConsequencesSet?.size) {
 		for (const x of uCausesSet) {
 			const xConsequences = getOrCreateClosure(consequencesClosure, x)
 			for (const y of vConsequencesSet) {
@@ -295,7 +315,6 @@ 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
@@ -329,8 +348,8 @@ function hasPathExcluding(start: Function, end: Function, exclude: Function): bo
  * Called when an effect is stopped/cleaned up
  * @param effect - The effect being cleaned up
  */
-function cleanupEffectFromGraph(effect: ScopedCallback) {
-	if (options.cycleHandling === 'none') return
+function cleanupEffectFromGraph(effect: EffectTrigger) {
+	if (options.cycleHandling === 'production') return
 	const root = getRoot(effect)
 
 	// Get closures before removing direct edges (needed for propagation)
@@ -435,7 +454,7 @@ function cleanupEffectFromGraph(effect: ScopedCallback) {
 // Batch queue structure - optimized with cached in-degrees
 interface BatchQueue {
 	// All effects in the current batch that still need to be executed (todos)
-	all: Map<Function, ScopedCallback> // root → effect
+	all: Map<Function, EffectTrigger> // root → effect
 	// Cached in-degrees for each effect in the batch (number of causes in batch)
 	inDegrees: Map<Function, number> // root → in-degree count
 }
@@ -443,17 +462,17 @@ interface BatchQueue {
 // Track currently executing effects to prevent re-execution
 // These are all the effects triggered under `activeEffect`
 let batchQueue: BatchQueue | undefined
-export function hasBatched(effect: ScopedCallback) {
+export function hasBatched(effect: EffectTrigger) {
 	return batchQueue?.all.has(getRoot(effect))
 }
-const batchCleanups = new Set<ScopedCallback>()
+const batchCleanups = new Set<EffectCleanup>()
 
 /**
  * Computes and caches in-degrees for all effects in the batch
  * Called once when batch starts or when new effects are added
  */
 function computeAllInDegrees(batch: BatchQueue): void {
-	if (options.cycleHandling === 'none') return
+	if (options.cycleHandling === 'production') return
 	const activeEffect = getActiveEffect()
 	const activeRoot = activeEffect ? getRoot(activeEffect) : null
 
@@ -495,44 +514,6 @@ function decrementInDegreesForExecuted(batch: BatchQueue, executedRoot: Function
 	}
 }
 
-/**
- * Computes the in-degree (number of dependencies) for an effect in the current batch
- * Uses causesClosure to count all effects (directly or indirectly) that trigger this effect
- * @param root - Root function of the effect
- * @param batchEffects - Map of all effects in current batch (todos - effects that still need execution)
- * @returns Number of effects in batch that trigger this effect (directly or indirectly)
- *
- * TODO: Optimization - For large graphs with small batches, iterating over all causes in the closure
- * can be expensive. Consider maintaining a separate "batch causes" set or caching in-degrees.
- */
-/* function computeInDegreeInBatch(
-	root: Function,
-	batchEffects: Map<Function, ScopedCallback>
-): number {
-	let inDegree = 0
-	const activeEffect = getActiveEffect()
-	const activeRoot = activeEffect ? getRoot(activeEffect) : null
-
-	// Count effects in batch that trigger this effect (directly or indirectly)
-	// Using causesClosure which contains all transitive causes
-	// Note: batchEffects only contains effects that still need execution (todos),
-	// so we don't need to check if causes have been executed - they're not in the map if executed
-	const causes = causesClosure.get(root)
-	if (causes) {
-		for (const causeRoot of causes) {
-			// Only count if it's in the batch (still needs execution)
-			// BUT: don't count the currently executing effect (active effect)
-			// This handles the case where an effect is triggered during another effect's execution
-			// Note: Self-loops are ignored - they should not appear in closures, but we check to be safe
-			if (batchEffects.has(causeRoot) && causeRoot !== activeRoot && causeRoot !== root) {
-				inDegree++
-			}
-		}
-	}
-
-	return inDegree
-}
-
 /**
  * Finds a path from startRoot to endRoot in the dependency graph
  * Uses DFS to find the path through direct edges
@@ -625,84 +606,69 @@ function wouldCreateCycle(callerRoot: Function, targetRoot: Function): boolean {
  * @param caller - The active effect that triggered this one (optional)
  * @param immediate - If true, don't create edges in the dependency graph
  */
-function addToBatch(effect: ScopedCallback, caller?: ScopedCallback, immediate?: boolean) {
-	(effect as any)[cleanupSymbol]?.()
+function addToBatch(effect: EffectTrigger, caller?: EffectTrigger, immediate?: boolean) {
+	const node = getEffectNode(effect)
+	node.cleanup?.()
 	// 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 (node.stopped) {
+		// console.log(`[DEBUG] addToBatch: ${effect.name} is stopped`)
+		return
+	}
 
-	if (!batchQueue) return
+	if (!batchQueue) {
+		// console.log(`[DEBUG] addToBatch: no batchQueue`)
+		return
+	}
 
 	const root = getRoot(effect)
 
 	// 1. Add to batch first (needed for cycle detection)
-	if (options.cycleHandling === 'none' && batchQueue.all.has(root)) {
-		// If already present in flat mode, remove it so that the next set puts it at the end
-		batchQueue.all.delete(root)
+	if (options.cycleHandling === 'production') {
+		// Production mode: FIFO (delete and re-add to move to end)
+		if (batchQueue.all.has(root)) {
+			batchQueue.all.delete(root)
+		}
+		batchQueue.all.set(root, effect)
+	} else {
+		// Dev/Debug mode: Set if not present (preserve order?)
+		// actually, we might want to update it?
+		// For now, simple set
+		if (batchQueue.all.has(root)) {
+			// console.log(`[DEBUG] ${root.name} already in batch`)
+			return
+		}
+		batchQueue.all.set(root, effect)
+		// console.log(`[DEBUG] ${root.name} added to batch`)
 	}
 
-	batchQueue.all.set(root, effect)
-
-	// 2. Add to global graph (if caller exists and not immediate) - USE ROOTS ONLY
-	// When immediate is true, don't create edges - the effect is not considered as a consequence
-	if (caller && !immediate && options.cycleHandling !== 'none') {
+	// batchQueue.all.set(root, effect)
+	// console.log(`[DEBUG] addToBatch: ${root.name} added to batch`)
+	if (caller && !immediate && options.cycleHandling !== 'production') {
 		const callerRoot = getRoot(caller)
+		// const root = getRoot(effect) // Already have root
 
 		// Check for cycle BEFORE adding edge
-		// We check if adding callerRoot -> root would create a cycle
-		// This means checking if root already triggers callerRoot (directly or transitively)
 		if (wouldCreateCycle(callerRoot, root)) {
-			// Cycle detected! Get the full cycle path for debugging
 			const cyclePath = getCyclePathForEdge(callerRoot, root)
 			const cycleMessage =
 				cyclePath.length > 0
 					? `Cycle detected: ${cyclePath.map((r) => r.name || r.toString()).join(' → ')}`
 					: `Cycle detected: ${callerRoot.name || callerRoot.toString()} → ${root.name || root.toString()} (and back)`
 
-			const cycleHandling = options.cycleHandling
-
-			// In strict mode, we throw immediately on detection
-			if (cycleHandling === 'strict') {
-				batchQueue.all.delete(root)
-				const causalChain = getTriggerChain(effect)
-				const creationStack = effectCreationStacks.get(root)
-
-				throw new ReactiveError(`[reactive] Strict Cycle Prevention: ${cycleMessage}`, {
-					code: ReactiveErrorCode.CycleDetected,
-					cycle: cyclePath.map((r) => r.name || r.toString()),
-					details: cycleMessage,
-					causalChain,
-					creationStack,
-				})
-			}
+			batchQueue.all.delete(root)
+			const causalChain = getTriggerChain(effect)
+			const creationStack = getEffectNode(effect).creationStack
 
-			switch (cycleHandling) {
-				case 'throw': {
-					// Remove from batch before throwing
-					batchQueue.all.delete(root)
-					const causalChain = getTriggerChain(effect)
-					const creationStack = effectCreationStacks.get(root)
-
-					throw new ReactiveError(`[reactive] ${cycleMessage}`, {
-						code: ReactiveErrorCode.CycleDetected,
-						cycle: cyclePath.map((r) => r.name || r.toString()),
-						details: cycleMessage,
-						causalChain,
-						creationStack,
-					})
-				}
-				case 'warn':
-					options.warn(`[reactive] ${cycleMessage}`)
-					// Don't add the edge, break the cycle
-					batchQueue.all.delete(root)
-					return
-				case 'break':
-					// Silently break cycle, don't add the edge
-					batchQueue.all.delete(root)
-					return
-			}
+			throw new ReactiveError(`[reactive] ${cycleMessage}`, {
+				code: ReactiveErrorCode.CycleDetected,
+				cycle: cyclePath.map((r) => r.name || r.toString()),
+				details: cycleMessage,
+				causalChain,
+				creationStack,
+			})
 		}
 
-		addGraphEdge(callerRoot, root) // Add to persistent graph using roots
+		addGraphEdge(callerRoot, root)
 	}
 }
 
@@ -710,7 +676,7 @@ function addToBatch(effect: ScopedCallback, caller?: ScopedCallback, immediate?:
  * Adds a cleanup function to be called when the current batch of effects completes
  * @param cleanup - The cleanup function to add
  */
-export function addBatchCleanup(cleanup: ScopedCallback) {
+export function addBatchCleanup(cleanup: EffectCleanup) {
 	if (!batchQueue) cleanup()
 	else batchCleanups.add(cleanup)
 }
@@ -808,10 +774,10 @@ function findCycle(
  */
 function executeNext(effectuatedRoots: Function[]): any {
 	// Find an effect with in-degree 0 using cached values
-	let nextEffect: ScopedCallback | null = null
+	let nextEffect: EffectTrigger | null = null
 	let nextRoot: Function | null = null
 
-	if (options.cycleHandling === 'none') {
+	if (options.cycleHandling === 'production') {
 		// In flat mode, we just take the first effect in the queue (FIFO)
 		const first = batchQueue!.all.entries().next().value
 		if (first) {
@@ -822,6 +788,7 @@ function executeNext(effectuatedRoots: Function[]): any {
 		// Using cached in-degrees for O(n) lookup instead of O(n²)
 		for (const [root, effect] of batchQueue!.all) {
 			const inDegree = batchQueue!.inDegrees.get(root) ?? 0
+			// console.log(`[DEBUG] executeNext: checking ${root.name}, inDegree: ${inDegree}`)
 			if (inDegree === 0) {
 				nextEffect = effect
 				nextRoot = root
@@ -865,34 +832,11 @@ function executeNext(effectuatedRoots: Function[]): any {
 					? `Cycle detected: ${cycle.map((r) => r.name || '<anonymous>').join(' → ')}`
 					: 'Cycle detected in effect batch - all effects have dependencies that prevent execution'
 
-			const cycleHandling = options.cycleHandling
-			switch (cycleHandling) {
-				case 'throw':
-					throw new ReactiveError(`[reactive] ${cycleMessage}`)
-				case 'warn': {
-					options.warn(`[reactive] ${cycleMessage}`)
-					// Break the cycle by executing one effect anyway
-					const firstEffect = batchQueue!.all.values().next().value
-					if (firstEffect) {
-						const firstRoot = getRoot(firstEffect)
-						batchQueue!.all.delete(firstRoot)
-						batchQueue!.inDegrees.delete(firstRoot)
-						return firstEffect()
-					}
-					break
-				}
-				case 'break': {
-					// Silently break cycle
-					const firstEffect2 = batchQueue!.all.values().next().value
-					if (firstEffect2) {
-						const firstRoot2 = getRoot(firstEffect2)
-						batchQueue!.all.delete(firstRoot2)
-						batchQueue!.inDegrees.delete(firstRoot2)
-						return firstEffect2()
-					}
-					break
-				}
-			}
+			throw new ReactiveError(`[reactive] ${cycleMessage}`, {
+				code: ReactiveErrorCode.CycleDetected,
+				cycle: cycle.map((r) => r.name || r.toString()),
+				details: cycleMessage,
+			})
 		}
 		return null // Batch complete
 	}
@@ -911,16 +855,23 @@ function executeNext(effectuatedRoots: Function[]): any {
 
 // Track which sub-effects have been executed to prevent infinite loops
 // These are all the effects triggered under `activeEffect` and all their sub-effects
-export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'immediate') {
+export function batch(effect: EffectTrigger | EffectTrigger[], immediate?: 'immediate') {
+	if (broken) {
+		throw new ReactiveError(
+			'[reactive] Reactive system is broken after an unrecoverable error. Call reset() to recover.',
+			{ code: ReactiveErrorCode.BrokenEffects }
+		)
+	}
 	if (!Array.isArray(effect)) effect = [effect]
 	const roots = effect.map(getRoot)
 
+	batchDepth++
+	try {
 	if (batchQueue) {
 		// Nested batch - add to existing
 		options?.chain(roots, getRoot(getActiveEffect()))
 		const caller = getActiveEffect()
-		for (let i = 0; i < effect.length; i++)
-			addToBatch(effect[i], caller, immediate === 'immediate')
+		for (let i = 0; i < effect.length; i++) addToBatch(effect[i], caller, immediate === 'immediate')
 		if (immediate) {
 			const firstReturn: { value?: any } = {}
 			// Execute immediately (before batch returns)
@@ -940,15 +891,16 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
 		// New batch - initialize
 		if (!activationRegistry) activationRegistry = new Map()
 		else throw new Error('Batch already in progress')
-		options.beginChain(roots)
+		optionCall('beginChain', roots)
 		batchQueue = {
 			all: new Map(),
 			inDegrees: new Map(),
 		}
 
 		const caller = getActiveEffect()
-		const effectuatedRoots: ScopedCallback[] = []
+		const effectuatedRoots: Function[] = []
 		const firstReturn: { value?: any } = {}
+		let success = false
 
 		try {
 			if (immediate) {
@@ -963,11 +915,14 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
 				}
 			} else {
 				// Add initial effects to batch and compute dependencies
-				for (let i = 0; i < effect.length; i++) addToBatch(effect[i], caller, false)
+				const len = effect.length
+				for (let i = 0; i < len; i++) {
+					addToBatch(effect[i], caller, false)
+				}
 				computeAllInDegrees(batchQueue)
 			}
 
-			// Processing loop for all triggered effects and cleanups
+			// Process the batch
 			while (batchQueue.all.size > 0 || batchCleanups.size > 0) {
 				if (batchQueue.all.size > 0) {
 					if (effectuatedRoots.length > options.maxEffectChain) {
@@ -1021,22 +976,53 @@ export function batch(effect: ScopedCallback | ScopedCallback[], immediate?: 'im
 					// If we want to keep that behavior: if (immediate) break
 				}
 			}
-			return firstReturn.value
-		} catch (error) {
-			throw error instanceof ReactiveError
-				? error
-				: new ReactiveError('Effects are broken', { code: ReactiveErrorCode.BrokenEffects, cause: error })
+				success = true
 		} finally {
+			if (!success) panicThrow()
 			activationRegistry = undefined
 			batchQueue = undefined
-			options.endChain()
+			batchCleanups.clear()
+			optionCall('endChain')
 		}
+		return firstReturn.value
 	}
+	} finally {
+		batchDepth--
+	}
+}
+
+function panicThrow() {
+	broken = true
+}
+
+/**
+ * Resets the reactive system to a consistent state.
+ * Call this after an unrecoverable error has set the system to "broken".
+ * This clears all batch state, effect dependency graphs, and watcher registrations.
+ * All existing effects become orphaned and must be recreated.
+ */
+export function reset() {
+	broken = false
+	batchDepth = 0
+	activationRegistry = undefined
+	batchQueue = undefined
+	batchCleanups.clear()
+	effectTriggers = new WeakMap()
+	effectTriggeredBy = new WeakMap()
+	causesClosure = new WeakMap()
+	consequencesClosure = new WeakMap()
+	resetRegistry()
+	effectHistory.present.active = undefined
 }
 
+export { reset as resetBatchQueueForTest }
+
 // Inject batch function to allow atomic game loops in requestAnimationFrame/setTimeout/...
-// TODO: perhaps introduce somewhere a way to wrap async functions - find out if it's necessary
-// wrapAsync(fn=> batch(fn, 'immediate'))
+// Note: Automatic batching of async callbacks (setTimeout, Promise.then, etc.) is NOT implemented.
+// Rationale: (1) asyncHooks.addHook API doesn't support knowing when callbacks complete (needed for batching),
+// (2) hooking all callback-creating functions adds overhead without guaranteed benefit,
+// (3) incomplete coverage in Node (async_hooks misses user-land patterns).
+// Solution: Use explicit @atomic decorator or manual batch() calls where optimization is needed.
 
 /**
  * Decorator that makes methods atomic - batches all effects triggered within the method
@@ -1047,7 +1033,7 @@ export const atomic = decorator({
 			const atomicEffect = () => original.apply(this, args)
 			// Debug: helpful to have a name
 			Object.defineProperty(atomicEffect, 'name', { value: `atomic(${original.name})` })
-			return batch(atomicEffect, 'immediate')
+			return batch(atomicEffect as EffectTrigger, 'immediate')
 		}
 	},
 	default<Args extends any[], Return>(
@@ -1057,7 +1043,7 @@ export const atomic = decorator({
 			const atomicEffect = () => original.apply(this, args)
 			// Debug: helpful to have a name
 			Object.defineProperty(atomicEffect, 'name', { value: `atomic(${original.name})` })
-			return batch(atomicEffect, 'immediate')
+			return batch(atomicEffect as EffectTrigger, 'immediate')
 		}
 	},
 })
@@ -1074,226 +1060,294 @@ const fr = new FinalizationRegistry<() => void>((f) => f())
  * @param options - Options for effect execution
  * @returns A cleanup function to stop the effect
  */
-export function effect(
-	//biome-ignore lint/suspicious/noConfusingVoidType: We have to
-	fn: (access: DependencyAccess) => ScopedCallback | undefined | void | Promise<any>,
-	effectOptions?: EffectOptions
-): ScopedCallback & {
-	[stopped]: boolean
-	[cleanupSymbol]: () => void
-} {
-
-	// Use per-effect asyncMode or fall back to global option
-	const asyncMode = effectOptions?.asyncMode ?? options.asyncMode ?? 'cancel'
-	if (options.introspection.enableHistory) {
-		const stack = new Error().stack
-		if (stack) {
-			// Clean up the stack trace to remove internal frames
-			const cleanStack = stack.split('\n').slice(2).join('\n')
-			effectCreationStacks.set(getRoot(fn), cleanStack)
-		}
-	}
-	let cleanup: (() => void) | null = null
-	const tracked = effectHistory.present.with(runEffect, ()=> effectAggregator.zoned)
-	const ascend = effectHistory.zoned
-	//const parent = effectHistory.present.active // TODO: Double-check parenting (untracked -> stop children) - use case or untracked(effect)
-	let parent = effectHistory.present.active
-	/*if (!parent) {
-		for (const h of effectHistory.active.history) parent = h
-	}*/
-	let effectStopped = false
-	let hasReacted = false
-	let runningPromise: Promise<any> | null = null
-	let cancelPrevious: (() => void) | null = null
-
-	function runEffect() {
-		// Clear previous dependencies
-		if (cleanup) {
-			const prevCleanup = cleanup
-			cleanup = null
-			untracked(() => prevCleanup())
-		}
+export const effect = named(effectMarker.leave, flavored(
+	function effect(
+		fn: (access: EffectAccess) => EffectCloser | undefined | void | Promise<any>,
+		effectOptions?: EffectOptions
+	): EffectCleanup {
+		if (effectOptions?.name) Object.defineProperty(fn, 'name', { value: effectOptions.name })
+		// Use per-effect asyncMode or fall back to global option
+		const asyncMode = effectOptions?.asyncMode ?? options.asyncMode ?? 'cancel'
+		
+		// Create the effect function - naming it for debug
+		const runEffect: EffectTrigger = () => {
+			const node = getEffectNode(runEffect)
+			// Clear previous dependencies
+			if (node.cleanup) {
+				const prevCleanup = node.cleanup
+				node.cleanup = undefined
+				try {
+					untracked(() => prevCleanup())
+				} catch (error) {
+					// If we want to report them, we could use options.warn or similar
+					options.warn('Error during effect cleanup', error)
+				}
+			}
 
-		// Handle async modes when effect is retriggered
-		if (runningPromise) {
-			if (asyncMode === 'cancel' && cancelPrevious) {
-				// Cancel previous execution
-				cancelPrevious()
-				cancelPrevious = null
-				runningPromise = null
-			} else if (asyncMode === 'ignore') {
-				// Ignore new execution while async work is running
-				return
+			// Handle async modes when effect is retriggered
+			if (runningPromise) {
+				if (asyncMode === 'cancel' && cancelPrevious) {
+					// Cancel previous execution
+					cancelPrevious()
+					cancelPrevious = null
+					runningPromise = null
+				} else if (asyncMode === 'ignore') {
+					// Ignore new execution while async work is running
+					return
+				}
+				// Note: 'queue' mode not yet implemented
 			}
-			// Note: 'queue' mode not yet implemented
-		}
 
-		// The effect has been stopped after having been planned
-		if (effectStopped) return
+			// The effect has been stopped after having been planned
+			if (effectStopped) return
+
+			optionCall('enter', getRoot(fn))
+			let reactionCleanup: EffectCloser | undefined
+			let result: any
+			let caught = 0
+			
+			// Default thrower (self)
+			let thrower: CatchFunction = (error: any) => {
+				throw error
+			}
+			node.forwardThrow = thrower
+
+			let errorToThrow: Error | undefined
+			try {
+				result = tracked(named(effectMarker.enter, () => fn.call(null, access)))
+				optionCall('leave', fn)
+				if (
+					result &&
+					typeof result !== 'function' &&
+					(typeof result !== 'object' || !('then' in result))
+				)
+					throw new ReactiveError(`[reactive] Effect returned a non-function value: ${result}`)
+				// Check if result is a Promise (async effect)
+				if (result && typeof result === 'object' && typeof result.then === 'function') {
+					const originalPromise = result as Promise<any>
+
+					// Create a cancellation promise that we can reject
+					let cancelReject: ((reason: any) => void) | null = null
+					const cancelPromise = new Promise<never>((_, reject) => {
+						cancelReject = reject
+					})
 
-		options.enter(getRoot(fn))
-		let reactionCleanup: ScopedCallback | undefined
-		let result: any
-		try {
-			result = tracked(() => fn({ tracked, ascend, reaction: hasReacted }))
-			if (
-				result &&
-				typeof result !== 'function' &&
-				(typeof result !== 'object' || !('then' in result))
-			)
-				throw new ReactiveError(`[reactive] Effect returned a non-function value: ${result}`)
-			// Check if result is a Promise (async effect)
-			if (result && typeof result === 'object' && typeof result.then === 'function') {
-				const originalPromise = result as Promise<any>
-
-				// Create a cancellation promise that we can reject
-				let cancelReject: ((reason: any) => void) | null = null
-				const cancelPromise = new Promise<never>((_, reject) => {
-					cancelReject = reject
-				})
-
-				const cancelError = new ReactiveError('[reactive] Effect canceled due to dependency change')
-
-				// Race between the actual promise and cancellation
-				// If canceled, the race rejects, which will propagate through any promise chain
-				runningPromise = Promise.race([originalPromise, cancelPromise])
-
-				// Store the cancellation function
-				cancelPrevious = () => {
-					if (cancelReject) {
-						cancelReject(cancelError)
+					const cancelError = new ReactiveError(
+						'[reactive] Effect canceled due to dependency change'
+					)
+
+					// Race between the actual promise and cancellation
+					// If canceled, the race rejects, which will propagate through any promise chain
+					runningPromise = Promise.race([originalPromise, cancelPromise])
+
+					// Store the cancellation function
+					cancelPrevious = () => {
+						if (cancelReject) {
+							cancelReject(cancelError)
+						}
 					}
-				}
 
-				// Wrap the original promise chain so cancellation propagates
-				// This ensures that when we cancel, the original promise's .catch() handlers are triggered
-				// We do this by rejecting the race promise, which makes the original promise chain see the rejection
-				// through the zone-wrapped .then()/.catch() handlers
-			} else {
-				// Synchronous result - treat as cleanup function
-				reactionCleanup = result as undefined | ScopedCallback
+					// Wrap the original promise chain so cancellation propagates
+					// This ensures that when we cancel, the original promise's .catch() handlers are triggered
+					// We do this by rejecting the race promise, which makes the original promise chain see the rejection
+					// through the zone-wrapped .then()/.catch() handlers
+					runningPromise = runningPromise.catch((error) => {
+						// Propagate async errors to the effect's error handler
+						// This ensures onEffectThrow handlers are triggered for async errors
+						if (error !== cancelError) {
+							thrower(error)
+						}
+						// If thrower didn't throw (handled), we absorb the error.
+						// If thrower threw (unhandled), it propagates as a new unhandled rejection, which is correct.
+					})
+				} else {
+					// Synchronous result - treat as cleanup function
+					reactionCleanup = result as undefined | EffectCloser
+				}
+			} catch (error) {
+				// catcher:self`
+				errorToThrow = error
+			} finally {
+				access.reaction = true
 			}
-		} finally {
-			hasReacted = true
-			options.leave(fn)
-		}
 
-		// Create cleanup function for next run
-		cleanup = () => {
-			cleanup = null
-			reactionCleanup?.()
-			// Remove this effect from all reactive objects it's watching
-			const effectObjects = effectToReactiveObjects.get(runEffect)
-			if (effectObjects) {
-				for (const reactiveObj of effectObjects) {
-					const objectWatchers = watchers.get(reactiveObj)
-					if (objectWatchers) {
-						for (const [prop, deps] of objectWatchers.entries()) {
-							deps.delete(runEffect)
-							if (deps.size === 0) {
-								objectWatchers.delete(prop)
+			// Create cleanup function for next run
+			node.cleanup = () => {
+				node.cleanup = undefined
+				reactionCleanup?.()
+				reactionCleanup = undefined
+				delete node.trackers
+				delete node.catchers
+				// Remove this effect from all reactive objects it's watching
+				const effectObjects = effectToReactiveObjects.get(runEffect)
+				if (effectObjects) {
+					for (const reactiveObj of effectObjects) {
+						const objectWatchers = watchers.get(reactiveObj)
+						if (objectWatchers) {
+							for (const [prop, deps] of objectWatchers.entries()) {
+								deps.delete(runEffect)
+								if (deps.size === 0) {
+									objectWatchers.delete(prop)
+								}
+							}
+							if (objectWatchers.size === 0) {
+								watchers.delete(reactiveObj)
 							}
 						}
-						if (objectWatchers.size === 0) {
-							watchers.delete(reactiveObj)
+					}
+					effectToReactiveObjects.delete(runEffect)
+				}
+				// Invoke all child stops (recursive via subEffectCleanup calling its own mainCleanup)
+				const children = node.children
+				if (children) {
+					for (const childCleanup of children) childCleanup()
+					delete node.children
+				}
+			}
+
+			// Define bubbling thrower
+			thrower = (error: any) => {
+				const catches = node.catchers
+				if (catches)
+					while (caught < catches.length) {
+						reactionCleanup?.(error)
+						reactionCleanup = undefined
+						try {
+							reactionCleanup = catches[caught](error) as EffectCloser | undefined
+							return
+						} catch (e) {
+							caught++
 						}
 					}
+				if (parent) {
+					const parentNode = getEffectNode(parent)
+					if (parentNode.forwardThrow) parentNode.forwardThrow(error)
+					else throw error
 				}
-				effectToReactiveObjects.delete(runEffect)
+				else throw error
 			}
-			// Invoke all child stops (recursive via subEffectCleanup calling its own mainCleanup)
-			const children = effectChildren.get(runEffect)
-			if (children) {
-				for (const childCleanup of children) childCleanup()
-				effectChildren.delete(runEffect)
+			// Update the node's forwardThrow to the bubbling one
+			node.forwardThrow = thrower
+
+			if (errorToThrow) thrower(errorToThrow)
+		}
+		
+		// Initialize metadata node
+		const node = getEffectNode(runEffect)
+		
+		if (isDevtoolsEnabled()) {
+			const stack = getStackFrame() // Robustly skips internal mutts frames
+			if (stack.length > 0) {
+				node.creationStack = stack
 			}
 		}
-	}
-	// Mark the runEffect callback with the original function as its root
-	markWithRoot(runEffect, fn)
-	function augmentedRv(rv: ScopedCallback) {
-		return Object.defineProperties(rv, {
-			[stopped]: {
-				get() {
-					return effectStopped
-				},
-			},
-			[cleanupSymbol]: {
-				value: () => {
-					if (cleanup) {
-						const prevCleanup = cleanup
-						cleanup = null
-						untracked(() => prevCleanup())
-					}
+
+		let cleanup: (() => void) | null = null
+		const tracked = named(effectMarker.leave, effectHistory.present.with(runEffect, () => named(effectMarker.leave, effectAggregator.zoned)))
+		const ascended = named(effectMarker.leave, effectHistory.zoned)
+		const parent = effectHistory.present.active
+		// Set parent relationship in node
+		node.parent = parent
+		
+		// let thrower: CatchFunction | undefined // Moved inside runEffect
+		let effectStopped = false
+		const access: EffectAccess = {
+			tracked,
+			ascend: named(effectMarker.leave, (fn) => ascended(named(effectMarker.enter, ()=> fn.call(null)))),
+			//named(effectMarker.enter, (fn) => ascended(fn)),
+			reaction: false,
+		}
+		let runningPromise: Promise<any> | null = null
+		let cancelPrevious: (() => void) | null = null
+		if (effectOptions?.dependencyHook) {
+			node.dependencyHook = effectOptions.dependencyHook
+		}
+		// Mark the runEffect callback with the original function as its root
+		markWithRoot(runEffect, fn)
+		function augmentedRv(rv: ScopedCallback): EffectCleanup {
+			return Object.defineProperties(rv, {
+				[stopped]: {
+					get: () => effectStopped,
 				},
-			},
-		}) as ScopedCallback & {
-			[stopped]: boolean
-			[cleanupSymbol]: () => void
+			}) as EffectCleanup
 		}
-	}
-	augmentedRv(runEffect)
 
-	// Register strict mode if enabled
-	if (effectOptions?.opaque) {
-		opaqueEffects.add(runEffect)
-	}
+		// Register strict mode if enabled
+		if (effectOptions?.opaque) {
+			node.isOpaque = true
+		}
 
-	if (isDevtoolsEnabled()) {
-		registerEffectForDebug(runEffect)
-	}
+		if (isDevtoolsEnabled()) {
+			registerEffectForDebug(runEffect)
+		}
+
+		// Store parent relationship for hierarchy traversal - ALREADY DONE ABOVE via getEffectNode
 
-	batch(runEffect, 'immediate')
-
-	// Store parent relationship for hierarchy traversal
-	effectParent.set(runEffect, parent)
-	// Only ROOT effects are registered for GC cleanup and zone tracking
-	const isRootEffect = !parent
-
-	const stopEffect = (): void => {
-		if (effectStopped) return
-		effectStopped = true
-		// Cancel any running async work
-		if (cancelPrevious) {
-			cancelPrevious()
-			cancelPrevious = null
-			runningPromise = null
+		batch(runEffect, 'immediate')
+		// Only ROOT effects are registered for GC cleanup and zone tracking
+		const isRootEffect = !parent
+
+		const stopEffect = (): void => {
+			if (effectStopped) return
+			effectStopped = true
+			node.stopped = true
+			// Cancel any running async work
+			if (cancelPrevious) {
+				cancelPrevious()
+				cancelPrevious = null
+				runningPromise = null
+			}
+			try {
+				node.cleanup?.()
+			} catch (error) {
+				// Cleanup errors should basically be ignored or at least not stop the world
+				// If we want to report them, we could use options.warn or similar
+				options.warn('Error during effect cleanup', error)
+			}
+			// Clean up dependency graph edges
+			cleanupEffectFromGraph(runEffect)
+			fr.unregister(stopEffect)
 		}
-		cleanup?.()
-		// Clean up dependency graph edges
-		cleanupEffectFromGraph(runEffect)
-		fr.unregister(stopEffect)
-	}
-	if (isRootEffect) {
-		const callIfCollected = augmentedRv(() => stopEffect())
-		fr.register(
-			callIfCollected,
-			() => {
+		if (isRootEffect) {
+			const callIfCollected = augmentedRv(() => stopEffect())
+			fr.register(
+				callIfCollected,
+				() => {
+					stopEffect()
+					optionCall('garbageCollected', fn)
+				},
+				stopEffect
+			)
+			return callIfCollected
+		}
+		// Register this effect to be stopped when the parent effect is cleaned up
+		if (parent) {
+			const parentNode = getEffectNode(parent)
+			if (!parentNode.children) {
+				parentNode.children = new Set()
+			}
+			const children = parentNode.children
+			
+			const subEffectCleanup = augmentedRv(() => {
+				children.delete(subEffectCleanup)
+				// Execute this child effect cleanup (which triggers its own mainCleanup)
 				stopEffect()
-				options.garbageCollected(fn)
-			},
-			stopEffect
-		)
-		return callIfCollected
-	}
-	// Register this effect to be stopped when the parent effect is cleaned up
-	let children = effectChildren.get(parent)
-	if (!children) {
-		children = new Set()
-		effectChildren.set(parent, children)
-	}
-	const subEffectCleanup = augmentedRv(() => {
-		children.delete(subEffectCleanup)
-		if (children.size === 0) {
-			effectChildren.delete(parent)
+			})
+			children.add(subEffectCleanup)
+			return subEffectCleanup
 		}
-		// Execute this child effect cleanup (which triggers its own mainCleanup)
-		stopEffect()
-	})
-	children.add(subEffectCleanup)
-
-	return subEffectCleanup
-}
+		// Should not be reachable given isRootEffect check, but for type safety
+		return augmentedRv(stopEffect)
+	},
+	{
+		get opaque() {
+			return flavorOptions(this, { opaque: true }, 'opaque')
+		},
+		named(name: string) {
+			return flavorOptions(this, { name }, 'named')
+		},
+	}
+))
 
 /**
  * Executes a function without tracking dependencies but maintains parent cleanup relationship
@@ -1313,8 +1367,6 @@ export function root<T>(fn: () => T): T {
 	return effectHistory.root(fn)
 }
 
-export { effectTrackers }
-
 /**
  * Creates a bidirectional binding between a reactive value and a non-reactive external value
  * Prevents infinite loops by automatically suppressing circular notifications
@@ -1366,16 +1418,16 @@ export function biDi<T>(
 		set = get.set
 		get = get.get
 	}
-	let programatticallySetValue: any = Symbol()
+	let programmaticallySetValue: any = Symbol()
 	effect(
 		markWithRoot(() => {
 			const newValue = get()
-			if (unwrap(newValue) !== programatticallySetValue) received(newValue)
+			if (unwrap(newValue) !== programmaticallySetValue) received(newValue)
 		}, received)
 	)
 	return set
 		? atomic((value: T) => {
-				programatticallySetValue = unwrap(value)
+				programmaticallySetValue = unwrap(value)
 				set(value)
 			})
 		: () => {}