mutts 1.0.4 → 1.0.6

package/docs/reactive/advanced.md

@@ -1167,114 +1167,13 @@ Pair `memoize()` with [`mapped()`](#mapped) to keep derived array elements stabl
 
 ## Debugging and Development
 
-### Cycle Detection
+The `mutts` reactive system includes built-in tools for troubleshooting complex dependency graphs and identifying performance bottlenecks.
 
-The reactive system automatically detects circular dependencies between effects. When one effect triggers another effect that eventually triggers the first effect again, a cycle is detected.
+For a full guide on debugging, including cycle detection and memoization discrepancy tools, see the dedicated **[Debugging Tools](./debugging.md)** documentation.
 
-#### Cycle Detection Behavior
+### Quick Summary
 
-By default, cycles are detected and an error is thrown. You can configure the behavior using `reactiveOptions.cycleHandling`:
-
-```typescript
-import { reactiveOptions } from 'mutts/reactive'
-
-// Options: 'throw' (default), 'warn', or 'break'
-reactiveOptions.cycleHandling = 'warn' // Warn instead of throwing
-reactiveOptions.cycleHandling = 'break' // Silently break the cycle
-```
-
-**Cycle handling modes:**
-
-- **`'throw'`** (default): Throws a `ReactiveError` with a detailed cycle path when a cycle is detected
-- **`'warn'`**: Logs a warning message with the cycle path but continues execution (breaks the cycle)
-- **`'break'`**: Silently breaks the cycle without any message
-- **`'strict'`**: Checks the graph BEFORE execution. Prevents infinite loops at the source (higher overhead).
-
-#### Cycle Error Messages
-
-When a cycle is detected, the error message includes the full cycle path showing which effects form the cycle:
-
-```typescript
-const state = reactive({ a: 0, b: 0, c: 0 })
-
-effect(() => {
-  state.b = state.a + 1 // Effect A
-})
-
-effect(() => {
-  state.c = state.b + 1 // Effect B
-})
-
-// This will throw with a detailed cycle path
-try {
-  effect(() => {
-    state.a = state.c + 1 // Effect C - creates cycle: A → B → C → A
-  })
-} catch (e) {
-  console.error(e.message)
-  // "[reactive] Cycle detected: effectA → effectB → effectC → effectA"
-}
-```
-
-The cycle path shows the sequence of effects that form the circular dependency, making it easier to identify and fix the issue.
-
-#### Common Cycle Patterns
-
-**Direct cycle:**
-```typescript
-const state = reactive({ a: 0, b: 0 })
-
-effect(() => {
-  state.b = state.a + 1 // Effect A
-})
-
-effect(() => {
-  state.a = state.b + 1 // Effect B - creates cycle: A → B → A
-})
-```
-
-**Indirect cycle:**
-```typescript
-const state = reactive({ a: 0, b: 0, c: 0 })
-
-effect(() => {
-  state.b = state.a + 1 // Effect A
-})
-
-effect(() => {
-  state.c = state.b + 1 // Effect B
-})
-
-effect(() => {
-  state.a = state.c + 1 // Effect C - creates cycle: A → B → C → A
-})
-```
-
-#### Preventing Cycles
-
-To avoid cycles, consider:
-
-1. **Separate read and write effects**: Don't have an effect that both reads and writes the same reactive properties
-2. **Use `untracked()`**: For operations that shouldn't create dependencies
-3. **Use `atomic()`**: To batch operations and prevent intermediate triggers
-4. **Restructure logic**: Break circular dependencies by introducing intermediate state or computed values
-
-**Example - Using `untracked()` to break cycles:**
-```typescript
-const state = reactive({ count: 0 })
-
-effect(() => {
-  // Read count
-  const current = state.count
-  
-  // Write to count without creating a dependency cycle
-  untracked(() => {
-    if (current < 10) {
-      state.count = current + 1
-    }
-  })
-})
-```
-
-**Note:** Self-loops (an effect reading and writing the same property, like `obj.prop++`) are automatically ignored and do not create dependency relationships or cycles.
+- **Cycle Detection**: Automatically catch circular dependencies via `reactiveOptions.cycleHandling`.
+- **Memoization Discrepancy**: Detect "missing dependencies" by running computations twice during development using `reactiveOptions.onMemoizationDiscrepancy`.
+- **Global Hooks**: Use `reactiveOptions.touched`, `enter`, and `leave` to observe system activity.
 

package/docs/reactive/core.md

@@ -7,22 +7,22 @@
   - [5-Minute Quick Start](#5-minute-quick-start)
 - [Core API](#core-api)
 - [Effect System](#effect-system)
-- [Atomic Operations](#atomic-operations)
-- [Advanced Effects](#advanced-effects)
-- [Evolution Tracking](#evolution-tracking)
-- [Prototype Chains and Pure Objects](#prototype-chains-and-pure-objects)
-- [Recursive Touching](#recursive-touching)
-  - [Why Not Deep Watching?](#why-not-deep-watching)
-- [Collections](#collections)
-  - [Register](#register)
-- [Class Reactivity](#class-reactivity)
-- [Non-Reactive System](#non-reactive-system)
-- [Array Mapping](#array-mapping)
-- [Projection](#projection)
-- [Record Organization](#record-organization)
-- [Memoization](#memoization)
-- [Debugging and Development](#debugging-and-development)
-  - [Cycle Detection](#cycle-detection)
+- [Atomic Operations](./advanced.md#atomic-operations)
+- [Advanced Effects](./advanced.md#advanced-effects)
+- [Evolution Tracking](./advanced.md#evolution-tracking)
+- [Prototype Chains and Pure Objects](./advanced.md#prototype-chains-and-pure-objects)
+- [Recursive Touching](./advanced.md#recursive-touching)
+  - [Why Not Deep Watching?](./advanced.md#why-not-deep-watching)
+- [Collections](./advanced.md#collections)
+  - [Register](./advanced.md#register)
+- [Class Reactivity](./advanced.md#class-reactivity)
+- [Non-Reactive System](./advanced.md#non-reactive-system)
+- [Array Mapping](./advanced.md#array-mapping)
+- [Projection](./advanced.md#projection)
+- [Record Organization](./advanced.md#record-organization)
+- [Memoization](./advanced.md#memoization)
+- [Debugging and Development](./advanced.md#debugging-and-development)
+  - [Cycle Detection](./advanced.md#cycle-detection)
 
 ## Introduction
 

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

@@ -19,3 +19,11 @@ The Mutts Reactive System documentation has been split into focused sections for
 *   **[Prototype Chains](./reactive/advanced.md#prototype-chains-and-pure-objects)**: Advanced inheritance patterns
 *   **[Memoization](./reactive/advanced.md#memoization)**: Caching strategies
 *   **[Debugging](./reactive/advanced.md#debugging-and-development)**: Cycle detection and troubleshooting
+
+## [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
+
+*   **[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.4",
-  "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

@@ -117,7 +117,7 @@ export function Destroyable<
 		base = undefined
 	}
 	if (!base) {
-		base = class {} as T
+		base = class { } as T
 	}
 
 	return class Destroyable extends (base as T) {
@@ -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
@@ -139,7 +139,7 @@ export function Destroyable<
 			return Destroyable.destructors.has(obj)
 		}
 
-		declare [forwardProperties]: PropertyKey[]
+		[forwardProperties]!: PropertyKey[]
 		readonly [allocatedValues]: Allocated
 		constructor(...args: any[]) {
 			super(...args)
@@ -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/array.ts

@@ -10,13 +10,12 @@ export const native = Symbol('native')
 const isArray = Array.isArray
 Array.isArray = ((value: any) =>
 	isArray(value) ||
-	// biome-ignore lint/suspicious/useIsArray: We are defining it
 	(value &&
 		typeof value === 'object' &&
 		prototypeForwarding in value &&
 		Array.isArray(value[prototypeForwarding]))) as any
 export class ReactiveBaseArray {
-	declare readonly [native]: any[]
+	readonly [native]!: any[]
 
 	// Safe array access with negative indices
 	at(index: number): any {
@@ -293,7 +292,6 @@ export class ReactiveArray extends Indexable(ReactiveBaseArray, {
 		}
 	},
 }) {
-	declare length: number
 	constructor(original: any[]) {
 		super()
 		Object.defineProperties(this, {
@@ -364,8 +362,8 @@ export class ReactiveArray extends Indexable(ReactiveBaseArray, {
 				deleteCount === items.length
 					? range(start, start + deleteCount)
 					: range(start, oldLength + Math.max(items.length - deleteCount, 0), {
-							length: true,
-						})
+						length: true,
+					})
 			)
 		}
 	}