mutts 1.0.12 → 1.0.14

package/docs/ai/manual.md

@@ -6,14 +6,14 @@
 
 ## 1. MENTAL MODEL
 
-Proxy-based **fine-grained reactivity** — changes propagate synchronously through dependency-tracked effects. No VDOM, no scheduler, no hooks.
+Proxy-based **fine-grained reactivity** — changes propagate synchronously through dependency-tracked effects. No VDOM, no async render scheduler, no hooks.
 
 | Concept | Mutts |
 |---------|-------|
 | State | `reactive(obj)` — proxy wraps, tracks reads/writes |
 | Reactions | `effect(() => {})` — auto-tracks deps, re-runs on change |
 | Computed | `memoize(fn)` — cached, invalidates on tracked deps |
-| Collections | `project(arr, fn)` — per-entry effects, not `.map()` |
+| Collections | `morph(arr, fn)` — per-entry reactive transform |
 | Async context | `Zone` + `asyncZone` — propagates across await |
 | Batching | `atomic(() => {})` wraps, `atom(() => {})` runs immediately — fire effects once after all mutations |
 | Cleanup | Return fn from effect — runs before re-run/disposal |
@@ -22,11 +22,11 @@ Proxy-based **fine-grained reactivity** — changes propagate synchronously thro
 
 ```ts
 import { reactive, effect, memoize, morph, attend, lift, cleanup,
-  atom, atomic, defer, untracked, unreactive, watch, when, biDi, caught, why,
-  cleanedBy, organized,
+  atom, atomic, defer, untracked, unreactive, watch, when, biDi, caught,
+  organized, organize, resource, root,
   Zone, asyncZone, ZoneHistory, ZoneAggregator,
   decorator, mixin, Eventful, Destroyable, flavored, Indexable, chainPromise,
-  reactiveOptions, isReactive, unwrap, getState
+  reactiveOptions, isReactive, unwrap, getState, ReactiveBase
 } from 'mutts'
 ```
 
@@ -107,14 +107,14 @@ array.splice(0)   // also works — explicit clear
 ```
 
 ### TRAP 6: Using .map() for reactive transforms
-`.map()` is static — full rebuild on any change. Use `project()` for per-entry reactivity.
+`.map()` is static — full rebuild on any change. Use `morph()` for per-entry reactivity.
 
 ```ts
 // BAD — full rebuild
 const doubled = items.map(x => x.value * 2)
 
 // GOOD — per-entry effects
-const doubled = project(items, ({ get }) => get().value * 2)
+const doubled = morph(items, (value) => value * 2)
 ```
 
 ### TRAP 7: Deep watch overhead
@@ -164,7 +164,11 @@ state.count++ // triggers
 stop()        // disposes
 ```
 
-- **Access object**: `{ reaction, tracked(fn), ascend(fn) }` — `reaction` = false on first run, true after. `tracked` restores context in async. `ascend` tracks in parent effect.
+- **Access object**: `{ reaction, tracked(fn), ascend(fn), signal }`
+- `reaction` is `false` on first run, then `true` or a `CleanupReason` on re-runs.
+- `tracked` restores effect tracking in async or escaped callbacks.
+- `ascend` records dependencies on the parent effect context.
+- `signal` aborts when the effect is cleaned up or invalidated.
 - **Parent-child**: effects inside effects are children — parent disposal cascades.
 - **GC**: unreferenced top-level effects may GC — store `stop` to keep alive.
 - **Modifiers**: `effect.opaque(() => {})` (identity-only), `effect.named('x')(() => {})` (debug label). Chainable.
@@ -198,6 +202,8 @@ const updateBoth = atomic((a, b) => { state.a = a; state.b = b }) // effects fir
 // Decorator: @atomic on methods
 ```
 
+`atomic()` wraps for later invocation but still executes synchronously when called. Internally it behaves like `batch(fn, { immediate: true })`, so nested atomic calls join the active batch by default instead of creating an implicit child batch.
+
 ### 3.7 atom() — Immediate atomic execution
 
 ```ts
@@ -205,6 +211,16 @@ atom(() => { state.a = 1; state.b = 2 }) // runs now, effects fire once
 // Unlike atomic() which wraps for later, atom() executes immediately
 ```
 
+The explicit batching API is now:
+
+```ts
+batch(fnOrEffects, { immediate?: boolean, contained?: boolean, caller?: EffectTrigger })
+```
+
+- `batch(fn)` joins the current batch when nested
+- `batch(fn, { immediate: true })` runs `fn` now and queues its consequences into the active batch
+- `batch(fn, { contained: true })` creates an isolated nested batch that flushes before returning
+
 ### 3.8 defer() — Avoid cycles
 
 ```ts
@@ -231,16 +247,15 @@ input.addEventListener('input', () => provide(input.value))
 ```ts
 watch(() => state.count, (newVal, oldVal) => {}) // specific derivation
 watch(state, () => {}) // any property
-watch(state, () => {}, { deep: true }) // deep (expensive)
+watch.deep(state, () => {}) // deep (expensive)
+watch.immediate(() => state.count, (newVal, oldVal) => {}) // immediate first call
 ```
 
-### 3.10 cleanedBy() — Attach cleanup to objects
+`watch` has 3 useful shapes:
 
-```ts
-const obj = cleanedBy({ data: [] }, () => console.log('cleaned up'))
-obj[cleanup]() // triggers cleanup
-// Chains: if obj already has a cleanup, both run
-```
+- `watch(() => value, callback)`
+- `watch.deep(() => object, callback)`
+- `watch(object, callback)`
 
 ### 3.11 Lazy computed values
 
@@ -258,9 +273,25 @@ effect(() => console.log(d.value)) // recomputes immediately, .value is reactive
 
 ```ts
 await when(() => state.loaded)        // resolves when truthy
-await when(() => state.ready, { timeout: 5000 }) // rejects after 5s
+await when(() => state.ready, 5000)   // rejects after 5s
+```
+
+### 3.13 resource() — Async reactive state
+
+```ts
+const user = resource(async () => fetchUser(state.userId), { initialValue: null })
+
+effect(() => {
+  if (user.loading) return
+  console.log(user.value)
+})
+
+user.reload()
+await user.promise
 ```
 
+`resource()` returns `{ value, loading, error, latest, reload(), promise }`.
+
 ---
 
 ## 4. COLLECTIONS
@@ -280,15 +311,22 @@ Array methods (`push`, `splice`, `sort`, etc.) all trigger reactivity.
 
 All transforms return reactive results. Cleanup via `result[cleanup]()`.
 
-### 5.1 project() — Per-entry reactive map
+### 5.1 morph() — Per-entry reactive map
 
 ```ts
-const names = project(users, ({ get }) => get().name.toUpperCase())
+const names = morph(users, (user) => user.name.toUpperCase())
 // names[0] recomputes ONLY when users[0] changes
-// Variants: project.record(), project.map() — auto-dispatches by source type
+// Use morph.pure(...) when the callback has no reactive reads
 ```
 
-**Access object**: `{ get(), set(v), key, source, old, value }`
+For arrays the callback is `(value, access?) => mapped`.
+For Maps and records it also receives the key.
+
+The mapper can also be captioned, even though it is the second argument:
+
+```ts
+const names = morph`user:names`(users, (user) => user.name.toUpperCase())
+```
 
 ### 5.2 attend() — Per-key lifecycle
 
@@ -297,9 +335,17 @@ attend(reactiveRecord, (key) => {
   console.log(`${key} = ${reactiveRecord[key]}`)
   return () => console.log(`cleanup: ${key}`) // disposed when key disappears
 })
-// Works with: arrays, Maps, Sets, or raw () => Iterable<Key>
 ```
 
+`attend` also supports callback captions on its second argument:
+
+```ts
+attend`record:entries`(reactiveRecord, (key) => {
+  console.log(`${key} = ${reactiveRecord[key]}`)
+})
+```
+Works with: arrays, Maps, Sets, or raw `() => Iterable<Key>`.
+
 ### 5.3 organized() — Per-key record transform
 
 ```ts
@@ -309,7 +355,7 @@ const doubled = organized(source, (access, target) => {
 })
 ```
 
-### 5.6 lift() — Sync a computed array/object
+### 5.4 lift() — Sync a computed array/object
 
 ```ts
 const filtered = lift(() => items.filter(x => x.active))
@@ -318,7 +364,7 @@ const filtered = lift(() => items.filter(x => x.active))
 
 **lift vs deep touching**: Deep touching handles `state.items = newArray` (replacement diffs). `lift` is for **derived collections** (filter/map/reshape) where there's no single assignment — the output is recomputed from scratch.
 
-**lift vs memoize**: `memoize` is lazy (invalidate → recompute on next read), returns raw values, keyed by args. `lift` is eager (recompute immediately), returns a **stable reactive proxy** with per-element diffing. Use `lift` for derived collections consumed by `project()`/effects; use `memoize` for parameterized caching or lazy evaluation.
+**lift vs memoize**: `memoize` is lazy (invalidate → recompute on next read), returns raw values, keyed by args. `lift` is eager (recompute immediately), returns a **stable reactive proxy** with per-element diffing. Use `lift` for derived collections consumed by effects; use `memoize` for parameterized caching or lazy evaluation.
 
 ---
 
@@ -362,10 +408,10 @@ effect(() => {
 ```ts
 import { reactiveOptions } from 'mutts'
 
-// Cycle detection
-reactiveOptions.cycleHandling = 'development' // default: graph-based, throws
-reactiveOptions.cycleHandling = 'debug'       // full transitive closure, detailed paths
-reactiveOptions.cycleHandling = 'production'  // heuristic via maxTriggerPerBatch
+// Scheduler / cycle detection
+reactiveOptions.scheduler = 'ordered' // default: causal graph ordering, eager cycles
+reactiveOptions.scheduler = 'raw'     // fastest FIFO mode, heuristic cycles
+reactiveOptions.scheduler = 'debug'   // ordered mode plus heavier diagnostics
 
 // Lifecycle hooks (all wrapped via optionCall for safety)
 reactiveOptions.enter = (effect) => {}    // before effect runs
@@ -387,6 +433,8 @@ const graph = buildReactivityGraph()
 
 **ReactiveError.debugInfo**: `causalChain`, `creationStack`, `cycle` (for CYCLE_DETECTED).
 
+`onEffectThrow` is still exported as a deprecated alias of `caught`.
+
 ---
 
 ## 9. ZONES (Async Context)
@@ -484,7 +532,7 @@ const theme = await chainPromise(api.getUser('123')).getProfile().getSettings().
 ## 11. PHILOSOPHY
 
 - **Affirmative state**: Declare `Y = f(X)`. Don't say "when X changes, update Y".
-- **Events are legacy**: Use reactive derivations (`effect`, `memoize`, `project`) for internal logic. Events only for DOM/external APIs.
+- **Events are legacy**: Use reactive derivations (`effect`, `memoize`, `morph`) for internal logic. Events only for DOM/external APIs.
 - **Cleanup ≠ undo**: Cleanup releases subscriptions, does NOT undo side effects.
 
 ---
@@ -504,5 +552,5 @@ const theme = await chainPromise(api.getUser('123')).getProfile().getSettings().
 | `isReactive(obj)` to check | `obj._mutts_isReactive` |
 | Store `stop = effect(...)` | letting effect GC unintentionally |
 | `import { x } from 'mutts'` | `import { x } from 'mutts/reactive'` (no subpaths) |
-| `cleanedBy(obj, fn)` for cleanup | manual `obj[cleanup] = fn` |
+| `caught(handler)` for effect-local error handling | ad-hoc try/catch around reactive graph edges |
 | `memoize(() => a + b)` for computed | `effect` + manual state sync |

package/docs/debug-getReason.md

@@ -0,0 +1,161 @@
+# `__MUTTS_DEBUG__.getReason()`
+
+## Overview
+
+The `getReason()` function allows you to access the reason why the current effect is being executed from within the effect itself. This is useful for debugging and understanding what triggered an effect to re-run.
+
+## Usage
+
+```typescript
+import * as mutts from 'mutts'
+
+// DevTools are automatically enabled in development mode
+const debug = (globalThis as any).__MUTTS_DEBUG__
+
+const state = mutts.reactive({ count: 0 })
+
+mutts.effect(() => {
+  const reason = debug.getReason()
+  
+  if (!reason) {
+    console.log('First run - no reason')
+  } else if (reason.type === 'propChange') {
+    console.log(`Re-run due to ${reason.triggers.length} property changes:`)
+    for (const trigger of reason.triggers) {
+      console.log(`  - ${trigger.evolution.type} on ${trigger.evolution.prop}`)
+    }
+  }
+  
+  console.log('Count:', state.count)
+})
+
+// Trigger changes
+state.count = 1  // Shows propChange reason
+```
+
+## Return Value
+
+Returns `undefined` or a `CleanupReason` object:
+
+### `undefined`
+- Returned on the first run of an effect
+- No cleanup/reason is available for initial execution
+
+### `CleanupReason` types
+
+#### `{ type: 'propChange', triggers: PropTrigger[] }`
+The effect was re-run because one or more reactive properties changed.
+
+- `triggers`: Array of property changes that triggered this re-run
+  - `obj`: The reactive object that changed
+  - `evolution`: Details about what changed
+    - `type`: `'set' | 'del' | 'add' | 'invalidate' | 'bunch'`
+    - `prop`: The property that changed (or method name for 'bunch')
+  - `dependency`: Stack trace from when the dependency was created (if lineage tracking enabled)
+  - `touch`: Stack trace from when the property was modified (if lineage tracking enabled)
+
+#### `{ type: 'stopped', detail?: string }`
+The effect was explicitly stopped via its cleanup function.
+
+#### `{ type: 'gc' }`
+The effect was cleaned up by garbage collection.
+
+#### `{ type: 'error', error: unknown }`
+The effect is being re-run due to an error in a previous run.
+
+#### `{ type: 'lineage', parent: CleanupReason }`
+A parent effect was cleaned up, causing this child effect to also be cleaned up.
+
+#### `{ type: 'invalidate', cause: CleanupReason }`
+The effect was invalidated for some other reason.
+
+#### `{ type: 'multiple', reasons: CleanupReason[] }`
+Multiple reasons combined (rare, usually from complex cleanup scenarios).
+
+## Examples
+
+### Debugging Multiple Dependencies
+
+```typescript
+const state = mutts.reactive({ 
+  user: { name: 'John' },
+  posts: [{ title: 'Hello' }]
+})
+
+mutts.effect(() => {
+  const reason = debug.getReason()
+  
+  if (reason?.type === 'propChange') {
+    console.log(`Effect triggered by ${reason.triggers.length} changes:`)
+    reason.triggers.forEach(trigger => {
+      if (trigger.evolution.type === 'set') {
+        console.log(`  Property '${trigger.evolution.prop}' changed`)
+      } else if (trigger.evolution.type === 'add') {
+        console.log(`  Property '${trigger.evolution.prop}' added`)
+      }
+    })
+  }
+  
+  console.log(`User: ${state.user.name}, Posts: ${state.posts.length}`)
+})
+
+// Multiple simultaneous changes
+mutts.untracked(() => {
+  state.user.name = 'Jane'
+  state.posts.push({ title: 'New Post' })
+})
+```
+
+### Conditional Logic Based on Reason
+
+```typescript
+mutts.effect(() => {
+  const reason = debug.getReason()
+  
+  if (!reason) {
+    // First run - expensive initialization
+    console.log('Initializing...')
+    // setup expensive resources
+  } else if (reason.type === 'propChange') {
+    // Re-run - can optimize based on what changed
+    const userChanged = reason.triggers.some(t => 
+      t.evolution.prop === 'name'
+    )
+    if (userChanged) {
+      console.log('User name changed - updating UI')
+    }
+  }
+  
+  console.log(`User: ${state.user.name}`)
+})
+```
+
+## Notes
+
+- The reason is only available during the effect's execution
+- After the effect completes, the reason is cleared
+- The reason reflects why the *previous* run was cleaned up, not why the current run started
+- In TypeScript, you can type the return value as:
+  ```typescript
+  type CleanupReason = import('mutts').CleanupReason
+  const reason: CleanupReason | undefined = debug.getReason()
+  ```
+
+## Configuration
+
+Reason gathering is controlled by `options.introspection.gatherReasons`:
+
+```typescript
+import { reactiveOptions } from 'mutts'
+
+// Disable reason gathering for production (performance)
+reactiveOptions.introspection = null
+
+// Or customize what lineage information is captured
+reactiveOptions.introspection = {
+  gatherReasons: { lineages: 'touch' }, // 'none' | 'touch' | 'dependency' | 'both'
+  logErrors: true,
+  enableHistory: true,
+  historySize: 50,
+}
+```

package/docs/flavored.md

@@ -1,7 +1,9 @@
-# Flavored Functions
+# Flavored and Captioned Functions
 
 The `flavored` utility creates extensible functions with chainable property modifiers. It enables a fluent API where properties return specialized variants of the base function.
 
+The `captioned` utility is a sibling concept for callback-oriented APIs. It adds a tagged-template call form that can attach a runtime caption to one callback argument before delegating to the base function.
+
 ## Overview
 
 Flavored functions allow you to:
@@ -10,6 +12,13 @@ Flavored functions allow you to:
 - Use either automatic option merging (`flavorOptions`) or custom argument transformation (`createFlavor`)
 - Return hand-made functions for complete control (the generic case)
 
+Captioned functions allow you to:
+- Keep the normal callback-first call form
+- Add a tagged-template call form like `` effect`render:${id}`(fn) ``
+- Warn when a callback-first API receives an anonymous callback without a caption
+- Preserve captioning across flavored variants created with `createFlavor` or `flavorOptions`
+- Target callbacks that are not in argument position `0`
+
 ## Basic Usage
 
 ### Creating a Flavored Function
@@ -62,6 +71,57 @@ effect.named('myEffect')(fn)  // With name option
 effect.opaque.named('x')(fn)  // Chained
 ```
 
+### `captioned(fn, options?)`
+
+Creates a callback-oriented function that also accepts a tagged-template call form. The caption is applied to the configured callback argument before the base function runs.
+
+**Use when:** Your API takes a callback argument and you want ergonomic call-site naming without turning naming itself into a flavor.
+
+**Parameters:**
+- `fn` - The callback-first base function
+- `options.callbackIndex` - Which argument should be treated as the callback to rename/warn about. Defaults to `0`
+- `options.name` - Human-readable label used in warning messages
+- `options.rename` - Optional function to customize how the caption is applied to the callback
+- `options.warn` - Optional warning sink for anonymous uncaptained callbacks
+- `options.shouldWarnAnonymous` - Optional predicate to suppress warnings for specific argument shapes
+
+**Example:**
+```typescript
+import { captioned } from 'mutts'
+
+const run = captioned(
+  (callback: () => void) => {
+    callback()
+  },
+  { name: 'run' }
+)
+
+run(function namedTask() {})
+run`task:${42}`(() => {})
+```
+
+The two call forms are:
+
+```typescript
+run(callback)
+run`caption`(callback)
+```
+
+If `run(callback)` receives an anonymous callback, `captioned` may warn depending on its `shouldWarnAnonymous` policy.
+
+You can also target callbacks that are not the first argument:
+
+```typescript
+const attendLike = captioned(
+  (source: string[], callback: (value: string) => void) => {
+    for (const value of source) callback(value)
+  },
+  { name: 'attendLike', callbackIndex: 1 }
+)
+
+attendLike`items`(['a', 'b'], () => {})
+```
+
 ### `flavorOptions(fn, defaultOptions)`
 
 Creates a flavored variant that merges options with the last argument.
@@ -192,6 +252,43 @@ calculator.multiply(3, 4)     // 12
 calculator.double()(3, 4)     // 14 (6 + 8)
 ```
 
+## Combining `flavored` and `captioned`
+
+They solve different problems:
+
+- `flavored` changes how a function is configured via chainable properties
+- `captioned` changes how a callback-first function can be called
+
+They compose naturally:
+
+```typescript
+const watch = captioned(
+  flavored(baseWatch, {
+    get immediate() {
+      return flavorOptions(this, { immediate: true })
+    }
+  }),
+  { name: 'watch' }
+)
+
+watch(() => state.count, changed)
+watch`counter:watch`(() => state.count, changed)
+watch.immediate`counter:watch`(() => state.count, changed)
+```
+
+For callback arguments in another position, use `callbackIndex`:
+
+```typescript
+const attend = captioned(baseAttend, {
+  name: 'attend',
+  callbackIndex: 1,
+})
+
+attend`entries`(source, (key) => {
+  console.log(key)
+})
+```
+
 ## TypeScript Considerations
 
 Flavored functions use proxies and require type assertions for complex chaining scenarios: