mutts 1.0.5 → 1.0.7

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/node.esm.js

@@ -0,0 +1,45 @@
+import { createHook } from 'node:async_hooks';
+import { a as asyncHooks } from './chunks/index-CNR6QRUl.esm.js';
+export { A as AZone, b as ArrayReadForward, D as DecoratorError, c as Destroyable, d as DestructionError, E as Eventful, F as FoolProof, I as Indexable, e as IterableWeakMap, f as IterableWeakSet, R as ReactiveBase, g as ReactiveError, h as ReactiveErrorCode, i as Register, Z as Zone, j as ZoneAggregator, k as ZoneHistory, l as addBatchCleanup, m as allocated, n as allocatedValues, o as arrayEquals, p as asyncZone, q as atomic, r as biDi, s as buildReactivityGraph, t as cache, u as cached, v as callOnGC, w as chainPromise, x as cleanedBy, y as cleanup, z as contentRef, B as debounce, C as decorator, G as deepCompare, H as deepWatch, J as defer, K as deprecated, L as derived, M as describe, N as destructor, O as effect, P as enableDevTools, Q as forwardArray, S as getActivationLog, T as getActiveProjection, U as getAt, V as getState, W as immutables, X as isCached, Y as isConstructor, _ as isDevtoolsEnabled, $ as isNonReactive, a0 as isOwnAccessor, a1 as isReactive, a2 as legacyDecorator, a3 as memoize, a4 as mixin, a5 as modernDecorator, a6 as named, a7 as organize, a8 as organized, a9 as profileInfo, aa as project, ab as reactive, ac as reactiveOptions, ad as register, ae as registerEffectForDebug, af as registerNativeReactivity, ag as registerObjectForDebug, ah as renamed, ai as root, aj as scan, ak as setAt, al as setEffectName, am as setObjectName, an as tag, ao as throttle, ap as touched, aq as touched1, ar as trackEffect, as as unreactive, at as untracked, au as unwrap, av as watch, aw as zip } from './chunks/index-CNR6QRUl.esm.js';
+
+const hooks = new Set();
+const restorersPerAsyncId = new Map();
+const undoersPerAsyncId = new Map();
+createHook({
+    init(asyncId) {
+        const restorers = new Set();
+        for (const hook of hooks) {
+            restorers.add(hook());
+        }
+        restorersPerAsyncId.set(asyncId, restorers);
+    },
+    before(asyncId) {
+        const restorers = restorersPerAsyncId.get(asyncId);
+        if (restorers) {
+            const undoers = new Set();
+            for (const restore of restorers) {
+                undoers.add(restore());
+            }
+            undoersPerAsyncId.set(asyncId, undoers);
+        }
+    },
+    after(asyncId) {
+        const undoers = undoersPerAsyncId.get(asyncId);
+        if (undoers) {
+            for (const undo of undoers)
+                undo();
+            undoersPerAsyncId.delete(asyncId);
+        }
+    },
+    destroy(asyncId) {
+        restorersPerAsyncId.delete(asyncId);
+        undoersPerAsyncId.delete(asyncId);
+    }
+}).enable();
+asyncHooks.addHook = function (hook) {
+    hooks.add(hook);
+    return () => {
+        hooks.delete(hook);
+    };
+};
+//# sourceMappingURL=node.esm.js.map

package/dist/node.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.esm.js","sources":["../src/async/node.ts"],"sourcesContent":["import { createHook } from 'node:async_hooks'\nimport { Hook, Restorer, asyncHooks } from '.'\n\nconst hooks = new Set<Hook>()\nconst restorersPerAsyncId = new Map<number, Set<Restorer>>()\nconst undoersPerAsyncId = new Map<number, Set<() => void>>()\n\ncreateHook({\n\tinit(asyncId) {\n\t\tconst restorers = new Set<Restorer>()\n\t\tfor (const hook of hooks) {\n\t\t\trestorers.add(hook())\n\t\t}\n\t\trestorersPerAsyncId.set(asyncId, restorers)\n\t},\n\tbefore(asyncId) {\n\t\tconst restorers = restorersPerAsyncId.get(asyncId)\n\t\tif (restorers) {\n\t\t\tconst undoers = new Set<() => void>()\n\t\t\tfor (const restore of restorers) {\n\t\t\t\tundoers.add(restore())\n\t\t\t}\n\t\t\tundoersPerAsyncId.set(asyncId, undoers)\n\t\t}\n\t},\n\tafter(asyncId) {\n\t\tconst undoers = undoersPerAsyncId.get(asyncId)\n\t\tif (undoers) {\n\t\t\tfor (const undo of undoers) undo()\n\t\t\tundoersPerAsyncId.delete(asyncId)\n\t\t}\n\t},\n\tdestroy(asyncId) {\n\t\trestorersPerAsyncId.delete(asyncId)\n\t\tundoersPerAsyncId.delete(asyncId)\n\t}\n}).enable()\n\nasyncHooks.addHook = function (hook: Hook) {\n\thooks.add(hook)\n\treturn () => {\n\t\thooks.delete(hook)\n\t}\n}\n\nexport * from '../index'\n"],"names":[],"mappings":";;;;AAGA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAQ;AAC7B,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAyB;AAC5D,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA2B;AAE5D,UAAU,CAAC;AACV,IAAA,IAAI,CAAC,OAAO,EAAA;AACX,QAAA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAY;AACrC,QAAA,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;AACzB,YAAA,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACtB;AACA,QAAA,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5C,CAAC;AACD,IAAA,MAAM,CAAC,OAAO,EAAA;QACb,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC;QAClD,IAAI,SAAS,EAAE;AACd,YAAA,MAAM,OAAO,GAAG,IAAI,GAAG,EAAc;AACrC,YAAA,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE;AAChC,gBAAA,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACvB;AACA,YAAA,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC;QACxC;IACD,CAAC;AACD,IAAA,KAAK,CAAC,OAAO,EAAA;QACZ,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC;QAC9C,IAAI,OAAO,EAAE;YACZ,KAAK,MAAM,IAAI,IAAI,OAAO;AAAE,gBAAA,IAAI,EAAE;AAClC,YAAA,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC;QAClC;IACD,CAAC;AACD,IAAA,OAAO,CAAC,OAAO,EAAA;AACd,QAAA,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC;AACnC,QAAA,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC;IAClC;CACA,CAAC,CAAC,MAAM,EAAE;AAEX,UAAU,CAAC,OAAO,GAAG,UAAU,IAAU,EAAA;AACxC,IAAA,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;AACf,IAAA,OAAO,MAAK;AACX,QAAA,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;AACnB,IAAA,CAAC;AACF,CAAC"}

package/dist/node.js

@@ -0,0 +1,136 @@
+'use strict';
+
+var node_async_hooks = require('node:async_hooks');
+var index = require('./chunks/index-BFYK02LG.js');
+
+const hooks = new Set();
+const restorersPerAsyncId = new Map();
+const undoersPerAsyncId = new Map();
+node_async_hooks.createHook({
+    init(asyncId) {
+        const restorers = new Set();
+        for (const hook of hooks) {
+            restorers.add(hook());
+        }
+        restorersPerAsyncId.set(asyncId, restorers);
+    },
+    before(asyncId) {
+        const restorers = restorersPerAsyncId.get(asyncId);
+        if (restorers) {
+            const undoers = new Set();
+            for (const restore of restorers) {
+                undoers.add(restore());
+            }
+            undoersPerAsyncId.set(asyncId, undoers);
+        }
+    },
+    after(asyncId) {
+        const undoers = undoersPerAsyncId.get(asyncId);
+        if (undoers) {
+            for (const undo of undoers)
+                undo();
+            undoersPerAsyncId.delete(asyncId);
+        }
+    },
+    destroy(asyncId) {
+        restorersPerAsyncId.delete(asyncId);
+        undoersPerAsyncId.delete(asyncId);
+    }
+}).enable();
+index.asyncHooks.addHook = function (hook) {
+    hooks.add(hook);
+    return () => {
+        hooks.delete(hook);
+    };
+};
+
+exports.AZone = index.AZone;
+exports.ArrayReadForward = index.ArrayReadForward;
+exports.DecoratorError = index.DecoratorError;
+exports.Destroyable = index.Destroyable;
+exports.DestructionError = index.DestructionError;
+exports.Eventful = index.Eventful;
+exports.FoolProof = index.FoolProof;
+exports.Indexable = index.Indexable;
+exports.IterableWeakMap = index.IterableWeakMap;
+exports.IterableWeakSet = index.IterableWeakSet;
+exports.ReactiveBase = index.ReactiveBase;
+exports.ReactiveError = index.ReactiveError;
+Object.defineProperty(exports, "ReactiveErrorCode", {
+	enumerable: true,
+	get: function () { return index.ReactiveErrorCode; }
+});
+exports.Register = index.Register;
+exports.Zone = index.Zone;
+exports.ZoneAggregator = index.ZoneAggregator;
+exports.ZoneHistory = index.ZoneHistory;
+exports.addBatchCleanup = index.addBatchCleanup;
+exports.allocated = index.allocated;
+exports.allocatedValues = index.allocatedValues;
+exports.arrayEquals = index.arrayEquals;
+exports.asyncZone = index.asyncZone;
+exports.atomic = index.atomic;
+exports.biDi = index.biDi;
+exports.buildReactivityGraph = index.buildReactivityGraph;
+exports.cache = index.cache;
+exports.cached = index.cached;
+exports.callOnGC = index.callOnGC;
+exports.chainPromise = index.chainPromise;
+exports.cleanedBy = index.cleanedBy;
+exports.cleanup = index.cleanup;
+exports.contentRef = index.contentRef;
+exports.debounce = index.debounce;
+exports.decorator = index.decorator;
+exports.deepCompare = index.deepCompare;
+exports.deepWatch = index.deepWatch;
+exports.defer = index.defer;
+exports.deprecated = index.deprecated;
+exports.derived = index.derived;
+exports.describe = index.describe;
+exports.destructor = index.destructor;
+exports.effect = index.effect;
+exports.enableDevTools = index.enableDevTools;
+exports.forwardArray = index.forwardArray;
+exports.getActivationLog = index.getActivationLog;
+exports.getActiveProjection = index.getActiveProjection;
+exports.getAt = index.getAt;
+exports.getState = index.getState;
+exports.immutables = index.immutables;
+exports.isCached = index.isCached;
+exports.isConstructor = index.isConstructor;
+exports.isDevtoolsEnabled = index.isDevtoolsEnabled;
+exports.isNonReactive = index.isNonReactive;
+exports.isOwnAccessor = index.isOwnAccessor;
+exports.isReactive = index.isReactive;
+exports.legacyDecorator = index.legacyDecorator;
+exports.memoize = index.memoize;
+exports.mixin = index.mixin;
+exports.modernDecorator = index.modernDecorator;
+exports.named = index.named;
+exports.organize = index.organize;
+exports.organized = index.organized;
+exports.profileInfo = index.profileInfo;
+exports.project = index.project;
+exports.reactive = index.reactive;
+exports.reactiveOptions = index.options;
+exports.register = index.register;
+exports.registerEffectForDebug = index.registerEffectForDebug;
+exports.registerNativeReactivity = index.registerNativeReactivity;
+exports.registerObjectForDebug = index.registerObjectForDebug;
+exports.renamed = index.renamed;
+exports.root = index.root;
+exports.scan = index.scan;
+exports.setAt = index.setAt;
+exports.setEffectName = index.setEffectName;
+exports.setObjectName = index.setObjectName;
+exports.tag = index.tag;
+exports.throttle = index.throttle;
+exports.touched = index.touched;
+exports.touched1 = index.touched1;
+exports.trackEffect = index.trackEffect;
+exports.unreactive = index.unreactive;
+exports.untracked = index.untracked;
+exports.unwrap = index.unwrap;
+exports.watch = index.watch;
+exports.zip = index.zip;
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sources":["../src/async/node.ts"],"sourcesContent":["import { createHook } from 'node:async_hooks'\nimport { Hook, Restorer, asyncHooks } from '.'\n\nconst hooks = new Set<Hook>()\nconst restorersPerAsyncId = new Map<number, Set<Restorer>>()\nconst undoersPerAsyncId = new Map<number, Set<() => void>>()\n\ncreateHook({\n\tinit(asyncId) {\n\t\tconst restorers = new Set<Restorer>()\n\t\tfor (const hook of hooks) {\n\t\t\trestorers.add(hook())\n\t\t}\n\t\trestorersPerAsyncId.set(asyncId, restorers)\n\t},\n\tbefore(asyncId) {\n\t\tconst restorers = restorersPerAsyncId.get(asyncId)\n\t\tif (restorers) {\n\t\t\tconst undoers = new Set<() => void>()\n\t\t\tfor (const restore of restorers) {\n\t\t\t\tundoers.add(restore())\n\t\t\t}\n\t\t\tundoersPerAsyncId.set(asyncId, undoers)\n\t\t}\n\t},\n\tafter(asyncId) {\n\t\tconst undoers = undoersPerAsyncId.get(asyncId)\n\t\tif (undoers) {\n\t\t\tfor (const undo of undoers) undo()\n\t\t\tundoersPerAsyncId.delete(asyncId)\n\t\t}\n\t},\n\tdestroy(asyncId) {\n\t\trestorersPerAsyncId.delete(asyncId)\n\t\tundoersPerAsyncId.delete(asyncId)\n\t}\n}).enable()\n\nasyncHooks.addHook = function (hook: Hook) {\n\thooks.add(hook)\n\treturn () => {\n\t\thooks.delete(hook)\n\t}\n}\n\nexport * from '../index'\n"],"names":["createHook","asyncHooks"],"mappings":";;;;;AAGA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAQ;AAC7B,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAyB;AAC5D,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA2B;AAE5DA,2BAAU,CAAC;AACV,IAAA,IAAI,CAAC,OAAO,EAAA;AACX,QAAA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAY;AACrC,QAAA,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;AACzB,YAAA,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACtB;AACA,QAAA,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5C,CAAC;AACD,IAAA,MAAM,CAAC,OAAO,EAAA;QACb,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC;QAClD,IAAI,SAAS,EAAE;AACd,YAAA,MAAM,OAAO,GAAG,IAAI,GAAG,EAAc;AACrC,YAAA,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE;AAChC,gBAAA,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACvB;AACA,YAAA,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC;QACxC;IACD,CAAC;AACD,IAAA,KAAK,CAAC,OAAO,EAAA;QACZ,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC;QAC9C,IAAI,OAAO,EAAE;YACZ,KAAK,MAAM,IAAI,IAAI,OAAO;AAAE,gBAAA,IAAI,EAAE;AAClC,YAAA,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC;QAClC;IACD,CAAC;AACD,IAAA,OAAO,CAAC,OAAO,EAAA;AACd,QAAA,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC;AACnC,QAAA,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC;IAClC;CACA,CAAC,CAAC,MAAM,EAAE;AAEXC,gBAAU,CAAC,OAAO,GAAG,UAAU,IAAU,EAAA;AACxC,IAAA,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;AACf,IAAA,OAAO,MAAK;AACX,QAAA,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;AACnB,IAAA,CAAC;AACF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/docs/ai/api-reference.md

@@ -68,8 +68,6 @@ export interface Register<T, K extends PropertyKey = PropertyKey> extends Iterab
 }
 
 export declare function register<T, K extends PropertyKey = PropertyKey>(keyFn: (item: T) => K, initial?: Iterable<T>): Register<T, K>;
-export declare function mapped<T, U>(inputs: readonly T[], compute: (input: T, index: number, output: U[]) => U): readonly U[];
-export declare function reduced<T, U, R extends object = any>(inputs: readonly T[], compute: (input: T, factor: R) => readonly U[]): readonly U[];
 export declare function project<S, R>(source: S, apply: (access: any, target: any) => any): R;
 export declare function organized<S, T>(source: S, apply: (access: any, target: T) => any, baseTarget?: T): T;
 

package/docs/ai/manual.md

@@ -2,104 +2,23 @@
 
 > [!IMPORTANT]
 > **Identity**: You are an AI Agent. This document is written for **YOU**.
-> **Purpose**: This file defines the protocols, schemas, and capabilities available to you when working with the `mutts` reactivity system.
->
-> For exact TypeScript signatures of the entire library, consult the **[API Reference for Agents](./api-reference.md)**.
+> **Purpose**: This file defines the protocols and high-level strategy for working with the `mutts` reactivity system.
 
-## 1. Introspection Capability
-When you encounter reactivity bugs (infinite loops, unexpected updates), **DO NOT GUESS**. Use the introspection API to "see" the system state.
+## 1. Technical Documentation
+Do not rely on outdated internal knowledge. Use the current documentation as your primary source of truth:
 
-### Enabling Introspection
-Introspection is often disabled by default for performance. Enable it before debugging.
-```typescript
-import { enableIntrospection, options } from 'mutts/introspection'
+- **[Debugging Tools](../reactive/debugging.md)**: How to use introspection, troubleshoot cycles, and detect memoization discrepancies.
+- **[API Reference](./api-reference.md)**: Exact TypeScript signatures for library functions.
 
-// Enable history tracking (memory expensive, use only for debugging)
-enableIntrospection({ historySize: 50 })
-```
+## 2. Debugging Protocol
+When you encounter reactivity bugs (infinite loops, unexpected updates), **DO NOT GUESS**. 
 
-### Dependency Graph
-Understanding "Who depends on What".
-```typescript
-import { getDependencyGraph } from 'mutts/introspection'
+1. **Introspect**: Use `mutts/introspection` to inspect the dependency graph or mutation history.
+2. **Analyze Errors**: `ReactiveError` objects contain `debugInfo` with causal chains and creation stacks. Use them to trace the fault.
+3. **Verify**: Use `reactiveOptions.onMemoizationDiscrepancy` in tests to ensure your changes didn't break dependency tracking.
 
-const graph = getDependencyGraph()
-// Returns: { nodes: { id: string, type: 'effect'|'object', label: string }[], edges: { from: string, to: string, type: 'dependency' }[] }
-```
-**Agent Protocol**: If valid code is behaving unexpectedly, inspect the graph to ensure dependencies are actually linked as you expect.
+## 3. Architecture Constraints
+1. **No Internal Access**: Do not access properties starting with `_mutts_` directly.
+2. **Explicit Naming**: Always name your effects (`effect(fn, { name: '...' })`) to make future debugging easier for yourself or other agents.
+3. **Affirmative State**: Prefer derived state and effects over imperative event-driven updates.
 
-### Mutation History
-Understanding "What just happened".
-```typescript
-import { getMutationHistory } from 'mutts/introspection'
-
-const history = getMutationHistory()
-/*
- Returns Array<{
-   id: number,
-   type: 'set' | 'add' | 'delete',
-   prop: string | symbol,
-   oldValue: any,
-   newValue: any,
-   objectName: string,   // "Human readable name"
-   source: string,       // "Effect X" or "External"
-   timestamp: number
- }>
-*/
-```
-**Agent Protocol**: When diagnosing "why is this value wrong?", check the *last mutation* of that property in history.
-
-## 2. Structured Error Handling
-`mutts` throws `ReactiveError` instances. These are designed to be machine-parseable.
-
-### ReactiveErrorCode
-Always check `error.debugInfo.code`.
-```typescript
-enum ReactiveErrorCode {
-    CycleDetected = 'CYCLE_DETECTED',
-    MaxDepthExceeded = 'MAX_DEPTH_EXCEEDED',
-    MaxReactionExceeded = 'MAX_REACTION_EXCEEDED',
-    WriteInComputed = 'WRITE_IN_COMPUTED',
-    TrackingError = 'TRACKING_ERROR'
-}
-```
-
-### Debugging Protocols
-
-#### Protocol: Handling `CycleDetected` / `MaxDepthExceeded`
-**Symptom**: `ReactiveError` with code `CycleDetected` or `MaxDepthExceeded`.
-**Action**:
-1.  Read `error.debugInfo.cycle` (Array of effect names).
-2.  **CRITICAL**: Read `error.debugInfo.causalChain`.
-    *   It tells you the *logical path*: `Effect A` -> (modifies `x`) -> `Effect B` -> (modifies `y`) -> `Effect A`.
-3.  **CRITICAL**: Read `error.debugInfo.creationStack`.
-    *   This gives you the **File path and Line number** where the problematic effect was defined.
-
-**Example Error Object**:
-```json
-{
-  "message": "[reactive] Max effect chain reached...",
-  "debugInfo": {
-    "code": "MAX_DEPTH_EXCEEDED",
-    "causalChain": [
-      "Effect(Anonymous) -> (set 'count') -> Effect(Display)",
-      "Effect(Display) -> (set 'dummy') -> Effect(Anonymous)"
-    ],
-    "creationStack": "    at tests/my-test.ts:45:10\n    at ...",
-    "cycle": ["Effect(Anonymous)", "Effect(Display)"]
-  }
-}
-```
-
-## 3. Strict Mode
-If you are writing new code that might be complex, verify it with "Strict Mode".
-This forces a graph check *before* execution, preventing infinite loops from hanging the runtime.
-```typescript
-import { options } from 'mutts/introspection'
-options.cycleHandling = 'strict'
-```
-
-## 4. Architecture Constraints for Agents
-1.  **Do not** access properties starting with `_mutts_` directly unless instructed. These are internal implementation details.
-2.  **Do not** rely on `batchQueue` global state in your reasoning; it is ephemeral.
-3.  **Do** name your effects when possible (`effect(() => {}, { name: 'MyEffect' })`) to make your own future debugging easier.

package/docs/reactive/advanced.md

@@ -1161,120 +1161,16 @@ class Example {
 }
 ```
 
-### Working with `mapped()`
-
-Pair `memoize()` with [`mapped()`](#mapped) to keep derived array elements stable across reorders (see [Identity-preserving mapped arrays](#identity-preserving-mapped-arrays)). Memoizing the mapper ensures each input object is processed at most once and its derived state persists while the input reference lives.
-
 ## Debugging and Development
 
-### Cycle Detection
-
-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.
-
-#### Cycle Detection Behavior
-
-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:
+The `mutts` reactive system includes built-in tools for troubleshooting complex dependency graphs and identifying performance bottlenecks.
 
-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
+For a full guide on debugging, including cycle detection and memoization discrepancy tools, see the dedicated **[Debugging Tools](./debugging.md)** documentation.
 
-**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
-    }
-  })
-})
-```
+### Quick Summary
 
-**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`. Note: Instant mathematical detection requires choosing a mode other than `'none'`.
+- **Flat Mode**: The default `reactiveOptions.cycleHandling = 'none'` provides maximum performance in high-frequency update scenarios by disabling graph maintenance.
+- **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/collections.md

@@ -352,115 +352,6 @@ Notes:
 - Assigning to an index (`list[i] = value`) uses the key function to bind that slot to `value`’s key.
 
 ## Class Reactivity
-## Array Mapping
-
-### `mapped()`
-
-Creates a reactive array by mapping over an input array. The mapper receives the current item value, its index, and the previous mapped value for that index.
-
-```typescript
-import { mapped, reactive } from 'mutts/reactive'
-
-const input = reactive([1, 2, 3])
-const doubles = mapped(input, (value, index, oldValue) => value * 2)
-
-console.log(doubles) // [2, 4, 6]
-
-// When input changes, the mapped output updates in place
-input.push(4)
-console.log(doubles) // [2, 4, 6, 8]
-```
-
-**Mapper signature:**
-
-```typescript
-(value: T, index: number, oldValue?: U) => U
-```
-
-- **value**: current element from the input array
-- **index**: current element index
-- **oldValue**: previously computed value at the same index (useful for incremental updates)
-
-**Key features:**
-
-- **Live reactivity**: Output array updates when the input array changes (push/pop/splice/assignments).
-- **Granular recompute**: Only indices that change are recomputed; `oldValue` enables incremental updates.
-- **Simple contract**: Mapper works directly with `(value, index, oldValue)` and can freely return reactive objects.
-
-**Performance characteristics:**
-
-```typescript
-const users = reactive([
-  { name: 'John', age: 30 },
-  { name: 'Jane', age: 25 }
-])
-
-let computeCount = 0
-const processedUsers = mapped(users, (user) => {
-  computeCount++
-  return `${user.name} (${user.age})`
-})
-
-console.log(computeCount) // 2 (initial computation)
-
-// Modify one user - only that index recomputes
-users[0].age = 31
-console.log(processedUsers[0]) // "John (31)"
-console.log(computeCount) // 3
-```
-
-**Advanced usage:**
-
-```typescript
-const orders = reactive([
-  { items: [{ price: 10 }, { price: 20 }] },
-  { items: [{ price: 15 }] }
-])
-
-const orderTotals = mapped(orders, (order) => (
-  order.items.reduce((sum, item) => sum + item.price, 0)
-))
-```
-
-### Identity-preserving mapped arrays
-
-Combine `mapped()` with [`memoize()`](#memoize) when you need to reuse mapped results for the same input identity. The memoized mapper runs at most once per input object, even when the source array is reordered, and it can host additional reactive state that should survive reordering.
-
-```typescript
-import { effect, mapped, memoize, reactive } from 'mutts/reactive'
-
-const inputs = reactive([{ name: 'John' }, { name: 'Jane' }])
-
-const memoizedCard = memoize((user: { name: string }) => {
-  const view: { name?: string; setName(next: string): void } = {
-    setName(next) {
-      user.name = next
-    },
-  }
-
-  effect(() => {
-    view.name = user.name.toUpperCase()
-  })
-
-  return view
-})
-
-const cards = mapped(inputs, (user) => memoizedCard(user))
-
-cards[0].setName('Johnny')
-console.log(cards[0].name) // 'JOHNNY'
-
-// Reorder: cached output follows the original object
-const first = inputs.shift()!
-inputs.push(first)
-console.log(cards[1].name) // still 'JOHNNY'
-```
-
-Use this pattern when:
-
-- You are mapping an array of reactive objects and want to keep derived objects stable across reorders.
-- The mapper returns objects with internal state or nested effects that should survive reordering.
-- You prefer to share memoized helpers across multiple mapped arrays.
 
 ## Projection
 
@@ -468,8 +359,6 @@ Use this pattern when:
 
 `project()` provides a unified API for transforming reactive collections (arrays, records, and maps) into new reactive collections. Each source entry gets its own reactive effect that recomputes only when that specific entry changes, enabling granular updates perfect for rendering pipelines.
 
-**Note:** `project()` is the modern replacement for `mapped()`. It offers the same per-entry reactivity benefits but works across all collection types with a consistent API.
-
 #### Basic Usage
 
 ```typescript
@@ -617,23 +506,10 @@ result[cleanup]() // Stops all effects and cleans up
 - **Data Transformation**: Convert between collection types while maintaining reactivity
 - **Performance Optimization**: Avoid full recomputation when only a few entries change
 
-#### Comparison with `mapped()`
-
-`project()` is designed to eventually replace `mapped()`. Key differences:
-
-- **Unified API**: Works with arrays, records, and maps (vs. `mapped()` only for arrays)
-- **Access Pattern**: Uses an access object with `get()`/`set()` instead of direct value/index parameters
-- **Automatic Target Creation**: Creates its own reactive target container (no need to provide a base target)
-- **Consistent Behavior**: Same per-entry reactivity model across all collection types
-
-For new code, prefer `project()` over `mapped()`. Existing `mapped()` code will continue to work, but consider migrating for better consistency and future features.
-
 ## Record Organization
 
 ### `organized()`
 
-`organized()` is the record companion to [`mapped()`](#mapped). Instead of iterating over numeric indices, it reacts to property additions, updates, and deletions on any `Record<PropertyKey, T>` (plain objects, dictionaries, even reactive proxies) and lets you build **whatever target structure you need**—a new record, nested buckets, a `Map`, or a more elaborate object with metadata.
-
 ```typescript
 import { cleanup, organized, reactive } from 'mutts/reactive'
 
@@ -677,7 +553,6 @@ function organized<
 
 Under the hood there is:
 
-- One effect watching `Reflect.ownKeys(source)` (similar to how `mapped()` tracks `length`)
 - A child effect per key that re-runs whenever that key’s value changes, automatically reusing and replacing the cleanup you returned.
 - Automatic disposal when keys disappear or when `target[cleanup]()` is invoked.