mutts 1.0.12 → 1.0.13

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:

package/docs/reactive/advanced.md

@@ -526,6 +526,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 })`
@@ -1170,8 +1177,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**:

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

@@ -212,6 +212,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 +248,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 +269,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,6 +13,7 @@ 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)

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "main": "dist/browser.cjs",
   "module": "dist/browser.esm.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "node": {
@@ -160,7 +159,7 @@
     "@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-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/node": "^22.10.10",
     "@vitest/browser": "^4.0.18",