mutts 1.0.13 → 1.0.15

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:**
@@ -935,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:**
@@ -981,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
 
@@ -1243,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**
@@ -1261,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**
@@ -1281,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
@@ -1491,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/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
 }
 ```
 

package/docs/reactive.md

@@ -19,6 +19,7 @@ The Mutts Reactive System documentation has been split into focused sections for
 ## [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
@@ -30,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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "main": "dist/browser.cjs",
   "module": "dist/browser.esm.js",
   "exports": {
@@ -90,7 +90,8 @@
   "files": [
     "dist",
     "README.md",
-    "docs"
+    "docs",
+    "BROWSER_ASYNC_POLYFILL.md"
   ],
   "scripts": {
     "build:js": "rollup -c",
@@ -142,6 +143,8 @@
     "./src/entry-browser.dev.ts",
     "./src/entry-node.ts",
     "./src/entry-node.dev.ts",
+    "./debug/index.ts",
+    "./debug/debug.ts",
     "./dist/browser.esm.js",
     "./dist/browser.dev.esm.js",
     "./dist/browser.cjs",
@@ -149,7 +152,9 @@
     "./dist/node.esm.js",
     "./dist/node.dev.esm.js",
     "./dist/node.cjs",
-    "./dist/node.dev.cjs"
+    "./dist/node.dev.cjs",
+    "./dist/debug.esm.js",
+    "./dist/debug.cjs"
   ],
   "engines": {
     "node": ">=16.0.0"
@@ -162,8 +167,8 @@
     "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/node": "^22.10.10",
-    "@vitest/browser": "^4.0.18",
-    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "^4.1.4",
     "playwright": "^1.58.1",
     "rollup": "^4.52.2",
     "rollup-plugin-copy": "^3.5.0",
@@ -174,7 +179,7 @@
     "tsx": "^4.20.4",
     "typescript": "^5.8.3",
     "vis-network": "^9.1.9",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@10.7.1+sha512.2d92c86b7928dc8284f53494fb4201f983da65f0fb4f0d40baafa5cf628fa31dae3e5968f12466f17df7e97310e30f343a648baea1b9b350685dafafffdf5808"
-}
+}