mutts 1.0.12 → 1.0.14

package/docs/reactive/advanced.md

@@ -45,7 +45,7 @@ The wrapped function preserves its signature (parameters and return value), and
 
 ### `atom()` - Immediate Atomic Execution
 
-While `atomic()` **wraps** a function for later calls, `atom()` **runs** a function immediately and atomically. It always executes right away, even inside a nested batch.
+While `atomic()` **wraps** a function for later calls, `atom()` **runs** a function immediately and atomically. It uses `batch(fn, { immediate: true })`, so it executes right away even inside an existing batch while still contributing its triggered effects to the active transaction.
 
 ```typescript
 import { atom, reactive, effect } from 'mutts'
@@ -80,6 +80,122 @@ const update = atomic((a, b) => { state.a = a; state.b = b })
 update(1, 2)  // runs when called
 ```
 
+### `batch()` - Explicit Batch Control
+
+`batch()` now uses an options object:
+
+```typescript
+batch(effectOrEffects, {
+  immediate?: boolean,
+  contained?: boolean,
+  caller?: EffectTrigger,
+})
+```
+
+The main modes are:
+
+- default nested behavior: if a batch is already active, `batch(fn)` joins that existing batch instead of creating an implicit child batch
+- `immediate: true`: execute the provided function now, but keep all triggered effects inside the current batch
+- `contained: true`: force a fresh local batch that drains before returning, even when called from inside another batch
+- `caller`: advanced internal override for causal chaining; most user code should omit it
+
+```typescript
+import { batch, effect, reactive } from 'mutts'
+
+const state = reactive({ a: 0, b: 0 })
+
+effect(() => {
+  console.log(state.a, state.b)
+})
+
+batch(() => {
+  state.a = 1
+  state.b = 2
+})
+
+batch(() => {
+  state.a = 3
+}, { immediate: true })
+
+batch(() => {
+  state.b = 4
+}, { immediate: true, contained: true })
+```
+
+#### Nested semantics
+
+Nested batching is no longer implicitly contained.
+
+- `batch(fn)` inside another batch joins the parent batch
+- `batch(fn, { immediate: true })` runs `fn` now and queues its consequences into the parent batch
+- `batch(fn, { contained: true })` creates an isolated sub-batch and flushes it before returning
+
+Use `contained: true` only when you explicitly need sub-transaction behavior.
+
+### Effect Ordering with Phase Tokens
+
+Effects are usually ordered by their data dependencies: an effect that reads a reactive property is eligible to re-run after another effect changes that property. Mutts uses those causal links as an execution graph by default. The `reactiveOptions.scheduler` option controls how much of that graph is maintained for scheduling and diagnostics:
+
+- `scheduler: 'ordered'` (default): effects that are already queued together are processed in dependency order when possible, so consequences run after the effects that caused them. Parent effects also run before their queued child effects, which lets parent cleanup stop stale children before they re-run.
+- `scheduler: 'debug'`: ordered scheduling plus heavier diagnostics for investigation.
+- `scheduler: 'raw'`: graph maintenance is disabled for speed, and already-queued effects use FIFO ordering with heuristic cycle protection.
+
+When you need to make a render phase or other side-effect phase explicit, use an ordinary reactive "phase token": one effect advances the token, and later effects read it.
+
+```typescript
+import { effect, reactive } from 'mutts'
+
+const phase = reactive({
+  measured: 0,
+  positioned: 0,
+})
+
+effect`render:measure`(() => {
+  measureDom()
+  phase.measured++
+})
+
+effect`render:position`(() => {
+  phase.measured
+  positionDom()
+  phase.positioned++
+})
+
+effect`render:paint`(() => {
+  phase.positioned
+  paintDom()
+})
+```
+
+This is sometimes called a beacon, barrier, or phase marker in application code, but it does not need a special primitive: the token is just reactive state. The important part is that the dependency is visible. The second effect does not merely rely on incidental registration order; it declares "I am downstream of `phase.measured`."
+
+This phase-token pattern also works in `scheduler: 'raw'` when the token is the downstream effect's actual scheduling dependency: the producer runs, advances the token, and that write queues the consumer afterward. That ordering comes from normal queuing, not from the dependency graph. What raw mode does not do is topologically reorder two effects that were already queued independently by some other write.
+
+If the downstream effect should be scheduled only by the phase token, and not directly by the raw state used by the producer, read the raw payload untracked:
+
+```typescript
+import { effect, reactive, untracked } from 'mutts'
+
+const state = reactive({ input: '' })
+const phase = reactive({ rendered: 0 })
+
+effect`render:first-pass`(() => {
+  state.input
+  renderFirstPass()
+  phase.rendered++
+})
+
+effect`render:second-pass`(() => {
+  phase.rendered
+
+  untracked`render:second-pass:payload`(() => {
+    renderSecondPass(state.input)
+  })
+})
+```
+
+Use `defer()` instead when the desired ordering is "after the whole current batch has settled" rather than "after this producer effect advances this phase."
+
 ### `addBatchCleanup()` / `defer()` - Deferring Work to Avoid Cycles
 
 When an effect needs to perform an action that would modify state the effect depends on, this can create a reactive cycle. The `addBatchCleanup` function (also exported as `defer` for semantic clarity) allows you to defer such work until after the current batch of effects completes.
@@ -238,7 +354,7 @@ addBatchCleanup(() => {
 
 **Nested Batches:**
 
-Callbacks added in nested batches are collected and run when the **outermost batch** completes:
+Callbacks added in inherited nested batches are collected and run when the **outermost batch** completes:
 
 ```typescript
 effect(() => {
@@ -252,7 +368,15 @@ effect(() => {
 // Output:
 // Outer deferred
 // Inner deferred
-// (Both run after outer batch completes)
+// (Both run after outer batch completes because `atomic()` joins the active batch)
+```
+
+If you need deferred callbacks to flush within an isolated nested batch, use an explicitly contained batch:
+
+```typescript
+batch(() => {
+  addBatchCleanup(() => console.log('Contained deferred'))
+}, { contained: true })
 ```
 
 **Error Handling:**
@@ -526,6 +650,13 @@ watch.immediate.deep(() => state.nested, (v) => {
 })
 ```
 
+As a callback-first API, `watch` also supports tagged-template captions:
+
+```typescript
+watch`count:watch`(() => state.count, (v) => console.log(v))
+watch.immediate`count:watch`(() => state.count, (v) => console.log(v))
+```
+
 These flavors are a shorthand for passing options:
 - `watch.immediate(...)` is equivalent to `watch(..., { immediate: true })`
 - `watch.deep(...)` is equivalent to `watch(..., { deep: true })`
@@ -928,7 +1059,7 @@ When you replace a reactive object with another object that shares the same prot
 
 - Watchers attached to the container are *not* re-fired if the container's prototype did not change (this avoids unnecessary parent effect re-runs).
 - Watchers attached to nested properties are re-evaluated only for keys that actually changed (added, removed, or whose values differ).
-- For arrays, the behaviour stays index-oriented: replacing an element at index `i` fires a touch for that index (and `length` if needed) rather than diffing the element recursively. This preserves reorder detection.
+- For arrays, the behavior stays index-oriented: replacing an element at index `i` fires a touch for that index (and `length` if needed) rather than diffing the element recursively. This preserves reorder detection.
 - Prototype chain properties are compared when both objects have prototype chains, ensuring changes to prototype-level properties are detected.
 
 **Integration with Prototype Chains:**
@@ -974,7 +1105,7 @@ expect(titleWatcher).toHaveBeenCalledTimes(2)
 expect(viewsWatcher).toHaveBeenCalledTimes(2)
 ```
 
-This behaviour keeps container-level watchers stable while still delivering fine-grained updates to nested effects—ideal when you replace data structures with freshly fetched objects that share the same prototype.
+This behavior keeps container-level watchers stable while still delivering fine-grained updates to nested effects—ideal when you replace data structures with freshly fetched objects that share the same prototype.
 
 ### Origin Filtering
 
@@ -1170,8 +1301,14 @@ effect(() => console.log(profile.displayName)) // tracks .displayName only
 
 **Derived filtered collection**:
 ```typescript
-const active = lift(() => items.filter(x => x.active))
-// active is a reactive array — project() or effects on active[i] work fine
+const filtered = lift(() => items.filter(x => x.active))
+// Element-wise diff — only changed elements sync, not full rebuild
+```
+
+`lift` also supports the same tagged-template caption form:
+
+```ts
+const filtered = lift`active:items`(() => items.filter(x => x.active))
 ```
 
 **Per-element transform**:
@@ -1230,17 +1367,36 @@ state.items = fetchedItems // deep touch diffs old vs new per-index — no lift
 ```typescript
 import { morph } from 'mutts'
 
+// Arrays: (item, position, access?) => O
 function morph<I, O>(
   source: readonly I[] | (() => readonly I[]),
-  fn: (arg: I) => O,
+  fn: (arg: I, position: { index: number }, access?: EffectAccess) => O,
   options?: { pure?: boolean | ((i: I) => boolean) }
 ): O[]
+
+// Maps: (value, key, access?) => O  
+function morph<K, V, O>(
+  source: Map<K, V>,
+  fn: (arg: V, key: K, access?: EffectAccess) => O,
+  options?: { pure?: boolean | ((i: V) => boolean) }
+): Map<K, O>
+
+// Records: (value, key, access?) => O
+function morph<S extends Record<PropertyKey, any>, O>(
+  source: S,
+  fn: (arg: S[keyof S], key: keyof S, access?: EffectAccess) => O,
+  options?: { pure?: boolean | ((i: S[keyof S]) => boolean) }
+): { [K in keyof S]: O }
 ```
 
 **Parameters**
 
-- `source`: a reactive array or a function returning one. Array mutations are tracked via `arrayDiff`.
-- `fn`: mapping callback. In the default (non-pure) mode, each element's computation runs inside its own effect, so reactive reads inside `fn` are tracked and will invalidate that element's cache when they change.
+- `source`: a reactive array, Map, or record, or a function returning one. Array mutations are tracked via `arrayDiff`.
+- `fn`: mapping callback. Signature varies by source type:
+  - Arrays: `(item, position, access?) => O` where `position.index` is the current index
+  - Maps: `(value, key, access?) => O` 
+  - Records: `(value, key, access?) => O`
+  In the default (non-pure) mode, each element's computation runs inside its own effect, so reactive reads inside `fn` are tracked and will invalidate that element's cache when they change.
 - `options.pure`: controls per-item effect creation. `true` skips effects for all items (same as `morph.pure`). A **predicate function** `(i: I) => boolean` decides per-item: return `true` to skip the effect (pure), `false` to create one (reactive). The predicate receives the input item and is evaluated once per cache slot on first access.
 
 **Behaviour**
@@ -1248,6 +1404,7 @@ function morph<I, O>(
 - **Lazy**: elements are only computed when accessed (e.g. `result[0]`). Unaccessed indices remain `undefined` in the cache.
 - **Identity stable**: the returned reactive array proxy is the same object across source mutations. Only affected indices are invalidated.
 - **Per-item effects** (default): each accessed element gets its own effect. If `fn` reads reactive values beyond its argument, changes to those values invalidate and recompute only the affected elements.
+- **Reactive position**: For arrays, the `position` object is stable per item and its `index` updates reactively when items move due to shifts/reorders.
 - **Cleanup**: the returned array is `cleanedBy` the internal morph effect. When the parent effect is disposed, the morph effect and all per-item effects are cleaned up.
 
 **Basic usage**
@@ -1268,6 +1425,21 @@ console.log(upper[3]) // "DAVE"
 items.splice(1, 1) // Remove 'bob' — indices shift, cache invalidated for affected positions
 ```
 
+**Using position.index**
+
+```typescript
+const items = reactive(['a', 'b', 'c'])
+const indexed = morph(items, (item, position) => `${item}@${position.index}`)
+
+console.log(indexed[0]) // "a@0"
+console.log(indexed[1]) // "b@1"
+
+items.unshift('x') // Insert at beginning
+console.log(indexed[0]) // "x@0"  
+console.log(indexed[1]) // "a@1" — position.index updated reactively
+console.log(indexed[2]) // "b@2"
+```
+
 **With reactive callback dependencies**
 
 ```typescript
@@ -1478,7 +1650,7 @@ For a full guide on debugging, including cycle detection and memoization discrep
 
 ### Quick Summary
 
-- **Cycle Detection**: Automatically catch circular dependencies via `reactiveOptions.cycleHandling`. Note: Instant mathematical detection requires choosing `'development'` or `'debug'` mode.
-- **Production Mode**: The default `reactiveOptions.cycleHandling` is set to `'production'`, providing maximum performance in high-frequency update scenarios by disabling graph maintenance.
+- **Cycle Detection**: Automatically catch circular dependencies via `reactiveOptions.scheduler`. Note: Instant mathematical detection requires choosing `'ordered'` or `'debug'` mode.
+- **Ordered Mode**: The default `reactiveOptions.scheduler` is set to `'ordered'`, preserving causal ordering and parent/child effect lifecycle ordering.
 - **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/attend.md

@@ -9,6 +9,7 @@ The `attend` utility reactively iterates over the entries of a collection, runni
 - **Creates** an inner effect for each key, via `ascend`.
 - **Disposes** the inner effect when the key is removed from the collection.
 - Allows the callback to return a **cleanup function** (like a regular effect closer).
+- Supports tagged-template captions on its callback argument.
 
 This is the foundational lifecycle primitive that `organized` is built on.
 
@@ -33,6 +34,18 @@ function attend<S extends Record<PropertyKey, any>>(source: S, callback: (key: k
 - **`source`** or **`enumerate`**: Either a collection (array, record, Map, Set) or a callback returning an `Iterable<Key>`. The enumeration runs inside the outer effect, so reactive reads (e.g. `source.length`, `Object.keys(source)`) are tracked automatically.
 - **`callback`**: Called per key inside an inner effect. May return a cleanup function that runs when the key is removed or before the inner effect re-executes.
 
+### Captioned callback form
+
+Unlike `effect` or `lift`, `attend` receives its callback as the **second** argument. It still supports tagged-template captioning:
+
+```typescript
+attend`entries`(config, (key) => {
+    console.log(`${key} = ${config[key]}`)
+})
+```
+
+The caption is applied to the callback argument and contributes to the runtime names of the inner per-key effects.
+
 ### Returns
 
 A `ScopedCallback` that tears down all inner effects and the outer effect.
@@ -67,6 +80,14 @@ stop()
 // Disposes everything
 ```
 
+The same record form also works with a caption:
+
+```typescript
+const stop = attend`config:entries`(config, (key) => {
+    console.log(`${key} = ${config[key]}`)
+})
+```
+
 ### Array
 
 ```typescript
@@ -123,6 +144,17 @@ attend(
 )
 ```
 
+And likewise with a caption:
+
+```typescript
+attend`ownKeys`(
+    () => Reflect.ownKeys(source),
+    (key) => {
+        console.log(key, source[key])
+    }
+)
+```
+
 ## How it Works
 
 1. An **outer effect** calls `enumerate()` (or derives it from the collection type), collecting the current keys into a `Set`.

package/docs/reactive/core.md

@@ -242,6 +242,18 @@ function effect(
 
 **Returns:** A cleanup function to stop the effect
 
+**Captioned call form:**
+
+`effect` also supports a tagged-template naming form for callback-first calls:
+
+```typescript
+effect`counter:main`(() => {
+    console.log(state.count)
+})
+```
+
+This is the preferred way to attach a runtime/debug name to a new effect.
+
 **Example:**
 
 ```typescript
@@ -264,6 +276,8 @@ state.mood = 'surprised' // Does not trigger the effect
 cleanup() // Stops the effect
 ```
 
+If you use the plain `effect(fn)` form with an anonymous callback, `mutts` may warn and suggest either a named function or the tagged-template caption form.
+
 You can also branch on the `reaction` flag to separate initialisation logic from update logic:
 
 ```typescript
@@ -647,6 +661,8 @@ const stopOuter = effect(() => {
 
 The `untracked()` function allows you to run code without tracking dependencies, which can be useful for creating effects or performing operations that shouldn't be part of the current effect's dependency graph.
 
+`untracked` is captioned. When you use it as a reactive execution root, prefer the template form so debug output and chained `CleanupReason.external` frames stay descriptive.
+
 ```typescript
 import { effect, untracked, reactive } from 'mutts'
 
@@ -661,7 +677,7 @@ effect(() => {
     // Create an inner effect without tracking the creation under the outer effect
     let stopInner: (() => void) | undefined
     
-    untracked(() => {
+    untracked`outer:inner-effect`(() => {
         stopInner = effect(() => {
             state.b
         })
@@ -739,6 +755,8 @@ item.data = { value: 30 } // Triggers BOTH effects
 
 #### `.named(name)`
 
+**Obsolete:** prefer `` effect`name`(fn) `` for new code.
+
 Creates a named effect for easier debugging and profiling. The name appears in DevTools and debug logs.
 
 ```typescript
@@ -748,18 +766,26 @@ const state = reactive({
     count: 0
 })
 
-// Create a named effect
+// Legacy named effect
 effect.named('counter-effect')(() => {
     console.log('Count:', state.count)
 })
 
-// Named effects can also be combined with other options
+// Legacy named effects can also be combined with other options
 effect.named('data-loader').opaque(() => {
     console.log('Loading data...')
 })
 ```
 
-**Benefits of named effects:**
+For new code, prefer:
+
+```typescript
+effect`counter-effect`(() => {
+    console.log('Count:', state.count)
+})
+```
+
+**Benefits of captioned/named effects:**
 - Easier identification in DevTools
 - Better stack traces during debugging
 - Helpful for performance profiling
@@ -769,7 +795,7 @@ effect.named('data-loader').opaque(() => {
 Modifiers can be chained in any order:
 
 ```typescript
-// Named opaque effect
+// Legacy named opaque effect
 effect.named('my-effect').opaque(() => {
     // Effect code
 })
@@ -783,7 +809,7 @@ effect.opaque.named('my-effect')(() => {
 Note: The modifiers return new effect functions with the options pre-applied, so they can be stored and reused:
 
 ```typescript
-// Create a reusable named effect factory
+// Create a reusable legacy named effect factory
 const createDataEffect = effect.named('data-layer')
 
 createDataEffect(() => {
@@ -795,6 +821,14 @@ createDataEffect(() => {
 })
 ```
 
+For single call sites, the tagged-template form is usually shorter:
+
+```typescript
+effect`data-layer`(() => {
+    console.log('Effect 1')
+})
+```
+
 ## Class Reactivity
 
 ### `@reactive` Decorator

package/docs/reactive/debugging.md

@@ -25,7 +25,7 @@ These hooks are called during the execution of effects and computed values.
 
 - **`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 or infinite cycles in `cycleHandling: 'production'` mode.
+- **`maxTriggerPerBatch`**: (Default: `10`) Limits how many times a single effect can be triggered within the same batch. Useful for detecting aggressive re-computation or infinite cycles, especially in `scheduler: 'raw'` mode.
 
 ## Cycle Detection
 
@@ -33,25 +33,27 @@ These hooks are called during the execution of effects and computed values.
 
 ### Configuration
 
-You can control how cycles are handled via `reactiveOptions.cycleHandling`:
+You can control how cycles are handled via `reactiveOptions.scheduler`:
 
-- **`'production'`**: High-performance FIFO mode. Disables the dependency graph and topological sorting. Uses heuristic detection via `maxEffectChain`.
-- **`'development'`** (Default): Maintains direct dependency graph for early cycle detection during edge creation. Throws immediately with basic path information.
-- **`'debug'`**: Full diagnostic mode with transitive closures and topological sorting. Provides detailed cycle path reporting.
+- **`'ordered'`** (Default): Maintains the causal effect graph for dependency ordering, parent/child lifecycle ordering, and early cycle detection. Throws immediately with basic path information.
+- **`'raw'`**: High-performance FIFO mode. Disables the dependency graph and topological sorting. Uses heuristic detection via `maxEffectChain`.
+- **`'debug'`**: Ordered scheduling plus the heaviest diagnostics. Provides detailed cycle path reporting.
+
+`reactiveOptions.cycleHandling` is still accepted as a deprecated alias: `'production'` maps to `'raw'`, and `'development'` maps to `'ordered'`.
 
 ### Topological vs. Flat Mode Detection
 - **Detection**: Cycles are detected when the execution depth exceeds `maxEffectChain` (default 100).
 - **Diagnostics**: The resulting `ReactiveError` includes a `trace` property (the recent execution sequence) and attempts to identify a repeating `cycle`.
-- **Recommendation**: Use this mode only for production to minimize performance overhead.
+- **Recommendation**: Use `raw` only when FIFO scheduling is sufficient and you want minimum overhead.
 
 ### Cycle Handling Modes
 
-You can configure how the system handles cycles via `reactiveOptions.cycleHandling`:
+You can configure how the system handles cycles via `reactiveOptions.scheduler`:
 
 | Mode | Detection Timing | Cycle Information | Performance |
 |------|-----------------|-------------------|-------------|
-| `'production'` | Late (Heuristic) | Trace of last N effects | Fastest |
-| `'development'` | Eager (On edge) | Exact path (DFS) | Moderate |
+| `'ordered'` | Eager (On edge) | Exact path (DFS) | Moderate |
+| `'raw'` | Late (Heuristic) | Trace of last N effects | Fastest |
 | `'debug'` | Structural | Transitive closures | Slowest |
 
 #### Finding Cycle Information
@@ -71,7 +73,7 @@ try {
 
 - **`error.cycle`**: An array of effect names forming the cycle.
 - **`error.causalChain`**: The sequence of triggers that led to the current effect.
-- **`error.lineage`**: The creation stack of the effect (available in `development` or `debug` modes).
+- **`error.lineage`**: The creation stack of the effect (available in `ordered` or `debug` modes).
 
 ### Memoization Discrepancy Detection
 
@@ -190,13 +192,13 @@ Since these are runtime options, you can toggle them based on your environment:
 
 ```typescript
 if (process.env.NODE_ENV === 'development') {
-    reactiveOptions.cycleHandling = 'debug';
+    reactiveOptions.scheduler = 'debug';
     reactiveOptions.onMemoizationDiscrepancy = myHandler;
     enableIntrospection();
 } else {
-    // Ensure they are off in production for performance
+    // Keep heavy diagnostics off in production for performance
     reactiveOptions.onMemoizationDiscrepancy = undefined;
-    reactiveOptions.cycleHandling = 'production';
+    reactiveOptions.scheduler = 'ordered'; // or 'raw' when FIFO scheduling is enough
 }
 ```
 
@@ -212,6 +214,8 @@ import 'mutts/debug';
 
 When an effect or watcher re-runs, it receives a `reaction` property (in `EffectAccess`) that describes *why* it was triggered. This is also passed to the `cleanup` function.
 
+Reasons may be chained. For example, a `propChange` can carry an `external` chain entry when the reactive work ultimately originated from a captioned `root` or `untracked` call such as ``root`event:click`(...)``.
+
 ```typescript
 effect(({ reaction }) => {
     if (reaction && typeof reaction === 'object') {
@@ -246,10 +250,11 @@ effect(()=> {
 
 Lineage tracking allows you to see the "causal path" of an effect—not just the current stack trace, but the stack traces of all parent effects that created the current execution.
 
-When an effect is created, it is assigned a `lineage` property that contains the stack traces of all parent effects that lead to its creation.
+When an effect is created, it is assigned a lineage signature. The raw stack/effect data is captured up front, but digestion into human-readable segments is deferred until display.
 
 - **`logLineage()`**: Prints a formatted, interactive tree of the current effect's lineage to the console.
 - **`captureLineage()`**: Captures the current lineage as a structured object.
+- **`digestLineage()`**: Converts a captured lineage signature into display-ready segments on demand.
 
 #### Lineage Options
 
@@ -266,8 +271,28 @@ When `mutts/debug` is active (or after calling `enableDevTools()`), a global `__
 This object provides low-level access to the graph, lineage capture, and renaming utilities:
 - `__MUTTS_DEBUG__.getGraph()`: Returns the full reactivity graph.
 - `__MUTTS_DEBUG__.logLineage()`: logs the current lineage.
-- `__MUTTS_DEBUG__.browserLineage`: captures lineage for the DevTools panel.
+- `__MUTTS_DEBUG__.logReason()`: logs the current reasons chain.
+- `__MUTTS_DEBUG__.reason`: the current `CleanupReason` for the active effect re-run, if any.
+- `__MUTTS_DEBUG__.lineage`: the current execution lineage, already digested into user-facing segments.
 
 ### Custom DevTools Formatters
 
 `mutts/debug` automatically registers [Custom Formatters](https://bit.ly/chrome-extension-custom-formatters) in Chrome. This makes lineage objects and reactive proxies appear as clean, structured trees in the console instead of opaque Proxy objects.
+
+#### Debugger / DevTools how-to
+
+To inspect reactive debugging data directly in Chrome DevTools:
+
+1. Allow **Custom formatters** in DevTools settings.
+2. Import `mutts/debug` somewhere in your application source during development:
+
+```typescript
+import 'mutts/debug'
+```
+
+3. Open DevTools and inspect the global `__MUTTS_DEBUG__` helper.
+
+The most useful live entry points you can keep on watch are:
+
+- `__MUTTS_DEBUG__.lineage`: Gives you the static "call stack" that produced this effect (without the cuts of batching)
+- `__MUTTS_DEBUG__.reason`: Gives you the chain of reasons who lead the code who is run to be run - starting from initialization or events

package/docs/reactive.md

@@ -5,6 +5,7 @@ The Mutts Reactive System documentation has been split into focused sections for
 ## [Core Concepts](./reactive/core.md)
 *   **[Core API](./reactive/core.md#core-api)**: `reactive`, `effect`, `unwrap`
 *   **[Effect System](./reactive/core.md#effect-system)**: Dependency tracking, cleanups, async effects
+*   **[Captioned Calls](./reactive/core.md#effect)**: tagged-template naming for callback-first APIs such as `effect`
 *   **[Class Reactivity](./reactive/core.md#class-reactivity)**: Decorators and functional syntax
 
 ## [Collections](./reactive/collections.md)
@@ -12,11 +13,13 @@ The Mutts Reactive System documentation has been split into focused sections for
 *   **[Reactive Arrays](./reactive/collections.md#reactivearray)**: Full array method support
 *   **[Morphing](./reactive/collections.md#morph)**: `morph`, `organized`
 *   **[Attend](./reactive/attend.md)**: Reactive enumeration (`attend`)
+*   **[Captioned Collection Callbacks](./reactive/attend.md#captioned-callback-form)**: tagged-template naming for second-argument callbacks like `attend`
 *   **[Resource](./reactive/resource.md)**: Async state tracking (`resource`)
 
 ## [Advanced Topics](./reactive/advanced.md)
 *   **[Choosing the Right Primitive](./reactive/advanced.md#choosing-the-right-reactive-primitive)**: Comparison table of effect-value functions (memoize, lift, project, etc.)
 *   **[Atomic Operations](./reactive/advanced.md#atomic-operations)**: Batching and Bidirectional binding
+*   **[Effect Ordering](./reactive/advanced.md#effect-ordering-with-phase-tokens)**: Use reactive phase tokens to make dependency ordering explicit
 *   **[Evolution Tracking](./reactive/advanced.md#evolution-tracking)**: History introspection
 *   **[Prototype Chains](./reactive/advanced.md#prototype-chains-and-pure-objects)**: Advanced inheritance patterns
 *   **[Memoization](./reactive/advanced.md#memoization)**: Caching strategies
@@ -28,4 +31,4 @@ The Mutts Reactive System documentation has been split into focused sections for
 *   **[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
+*   **[Performance](./reactive/debugging.md#performance-cost)**: Understanding the cost of debugging tools