@zeix/cause-effect 0.18.0 → 0.18.2

package/.ai-context.md

@@ -28,8 +28,8 @@ Scope         — owner-only (createScope)
 ### Signal Types
 - **State** (`createState`): Mutable signals for primitive values and objects
 - **Sensor** (`createSensor`): Read-only signals for external input streams with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization and reducer capabilities
-- **Task** (`createTask`): Async derived computations with automatic abort/cancellation
+- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
+- **Task** (`createTask`): Async derived computations with automatic abort/cancellation and optional `watched(invalidate)` for external invalidation
 - **Store** (`createStore`): Mutable object signals with individually reactive properties via Proxy
 - **List** (`createList`): Mutable array signals with stable keys and reactive items
 - **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
@@ -223,7 +223,7 @@ const processed = items.deriveCollection(item => item.toUpperCase())
 
 ## Resource Management
 
-**Sensor and Collection** use a start callback that returns a Cleanup function:
+**Sensor and Collection** use a watched callback that returns a Cleanup function:
 ```typescript
 const sensor = createSensor<T>((set) => {
   // setup input tracking, call set(value) to update
@@ -236,6 +236,17 @@ const feed = createCollection<T>((applyChanges) => {
 }, { keyConfig: item => item.id })
 ```
 
+**Memo and Task** use an optional `watched` callback in options that receives an `invalidate` function:
+```typescript
+const derived = createMemo(() => element.get().textContent ?? '', {
+  watched: (invalidate) => {
+    const obs = new MutationObserver(() => invalidate())
+    obs.observe(element.get(), { childList: true })
+    return () => obs.disconnect()
+  }
+})
+```
+
 **Store and List** use an optional `watched` callback in options:
 ```typescript
 const store = createStore(initialValue, {

package/.github/copilot-instructions.md

@@ -15,8 +15,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 ### Signal Types (all in `src/nodes/`)
 - **State** (`createState`): Mutable signals for values (`get`, `set`, `update`)
 - **Sensor** (`createSensor`): Read-only signals for external input with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization and reducer capabilities
-- **Task** (`createTask`): Async derived computations with automatic AbortController cancellation
+- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
+- **Task** (`createTask`): Async derived computations with automatic AbortController cancellation and optional `watched(invalidate)` for external invalidation
 - **Store** (`createStore`): Proxy-based reactive objects with per-property State/Store signals
 - **List** (`createList`): Reactive arrays with stable keys and per-item State signals
 - **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
@@ -72,7 +72,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - All signals have `.get()` for value access
 - Mutable signals (State) have `.set(value)` and `.update(fn)`
 - Store properties are automatically reactive signals via Proxy
-- Sensor/Collection use a start callback returning Cleanup (lazy activation)
+- Sensor/Collection use a watched callback returning Cleanup (lazy activation)
+- Memo/Task use optional `watched(invalidate)` callback in options for external invalidation
 - Store/List use optional `watched` callback in options returning Cleanup
 - Effects return a dispose function (Cleanup)
 
@@ -191,18 +192,27 @@ const count = createState(0, {
 ## Resource Management
 
 ```typescript
-// Sensor: lazy external input tracking
+// Sensor: lazy external input tracking (watched callback with set)
 const sensor = createSensor<T>((set) => {
   // setup — call set(value) to update
   return () => { /* cleanup — called when last effect stops watching */ }
 })
 
-// Collection: lazy external data source
+// Collection: lazy external data source (watched callback with applyChanges)
 const feed = createCollection<T>((applyChanges) => {
   // setup — call applyChanges(diffResult) on changes
   return () => { /* cleanup */ }
 }, { keyConfig: item => item.id })
 
+// Memo/Task: optional watched callback with invalidate
+const derived = createMemo(() => element.get().textContent ?? '', {
+  watched: (invalidate) => {
+    const obs = new MutationObserver(() => invalidate())
+    obs.observe(element.get(), { childList: true })
+    return () => obs.disconnect()
+  }
+})
+
 // Store/List: optional watched callback
 const store = createStore(initialValue, {
   watched: () => {

package/ARCHITECTURE.md

@@ -77,7 +77,12 @@ Before a sink recomputes, the engine sets `activeSink = node`, ensuring all `.ge
 
 After a sink finishes recomputing, `trimSources()` removes any edges beyond `sourcesTail` — these are dependencies from the previous execution that were not accessed this time. This is how the graph adapts to conditional dependencies.
 
-`unlink()` removes an edge from the source's sink list. If the source's sink list becomes empty and the source has a `stop` callback, that callback is invoked — this is how lazy resources (Sensor, Collection, watched Store/List) are deallocated when no longer observed.
+`unlink()` removes an edge from the source's sink list. If the source's sink list becomes empty:
+
+1. **Watched cleanup**: If the source has a `stop` callback, it is invoked — this is how lazy resources (Sensor, Collection, watched Store/List) are deallocated when no longer observed.
+2. **Cascading cleanup**: If the source is also a sink (a MemoNode or TaskNode — identified by having a `sources` field), its own sources are trimmed via `trimSources()`. This recursively unlinks the node from its upstream dependencies, allowing their `stop` callbacks to fire if they also become unobserved.
+
+The cascade is critical for intermediate nodes like `deriveCollection`'s internal MemoNode: when the last effect unsubscribes from the derived collection, `unlink()` removes the effect→derived edge, which triggers cascade cleanup of the derived→List edge, which in turn fires the List's `stop` (the `watched` cleanup). Without the cascade, the List would retain a stale sink reference and never clean up its watcher. Recursion depth is bounded by graph depth since the graph is a DAG.
 
 ### Dependency Tracking Opt-Out: `untrack(fn)`
 
@@ -87,7 +92,7 @@ After a sink finishes recomputing, `trimSources()` removes any edges beyond `sou
 
 ### Flag-Based Dirty Tracking
 
-Each sink node has a `flags` field with four states:
+Each sink node has a `flags` field using a bitmap with five flags:
 
 | Flag | Value | Meaning |
 |------|-------|---------|
@@ -95,6 +100,11 @@ Each sink node has a `flags` field with four states:
 | `FLAG_CHECK` | 1 | A transitive dependency may have changed — verify before recomputing |
 | `FLAG_DIRTY` | 2 | A direct dependency changed — recomputation required |
 | `FLAG_RUNNING` | 4 | Currently executing (used for circular dependency detection and edge reuse) |
+| `FLAG_RELINK` | 8 | Structural change requires edge re-establishment on next read |
+
+The first four flags (`CLEAN`/`CHECK`/`DIRTY`/`RUNNING`) are used by the core graph engine in `propagate()` and `refresh()`. They are tested with bitmask operations that ignore higher bits, so `FLAG_RELINK` is invisible to the propagation and refresh machinery.
+
+`FLAG_RELINK` is used exclusively by composite signal types (Store, List, Collection, deriveCollection) that manage their own child signals. When a structural mutation adds or removes child signals, the node is flagged `FLAG_DIRTY | FLAG_RELINK`. On the next `get()`, the composite signal's fast path reads the flag: if `FLAG_RELINK` is set, it forces a tracked `refresh()` after rebuilding the value so that `recomputeMemo()` can call `link()` for new child signals and `trimSources()` for removed ones. This avoids the previous approach of nulling `node.sources`/`node.sourcesTail`, which orphaned edges in upstream sink lists. `FLAG_RELINK` is always cleared by `recomputeMemo()`, which assigns `node.flags = FLAG_RUNNING` (clearing all bits) at the start of recomputation.
 
 ### The `propagate(node)` Function
 
@@ -178,14 +188,14 @@ A mutable value container. The simplest signal type — `get()` links and return
 
 **Graph node**: `StateNode<T>` (source only)
 
-A read-only signal that tracks external input. The `start` callback receives a `set` function that updates the node's value via `setState()`. Sensors cover two patterns:
+A read-only signal that tracks external input. The `watched` callback receives a `set` function that updates the node's value via `setState()`. Sensors cover two patterns:
 
-1. **Tracking external values** (default): Receives replacement values from events (mouse position, resize events). Equality checking (`Object.is` by default) prevents unnecessary propagation.
+1. **Tracking external values** (default): Receives replacement values from events (mouse position, resize events). Equality checking (`===` by default) prevents unnecessary propagation.
 2. **Observing mutable objects** (with `SKIP_EQUALITY`): Holds a stable reference to a mutable object (DOM element, Map, Set). `set(sameRef)` with `equals: SKIP_EQUALITY` always propagates, notifying consumers that the object's internals have changed.
 
-The value starts undefined unless `options.value` is provided. Reading a sensor before its `start` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
+The value starts undefined unless `options.value` is provided. Reading a sensor before its `watched` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
 
-**Lazy lifecycle**: The `start` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`).
+**Lazy lifecycle**: The `watched` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`).
 
 ### Memo (`src/nodes/memo.ts`)
 
@@ -199,6 +209,8 @@ The `error` field preserves thrown errors: if `fn` throws, the error is stored a
 
 **Reducer pattern**: The `prev` parameter enables state accumulation across recomputations without writable state.
 
+**Watched lifecycle**: An optional `watched` callback in options provides lazy external invalidation. The callback receives an `invalidate` function and is invoked on first sink attachment. Calling `invalidate()` marks the node `FLAG_DIRTY`, propagates to sinks, and flushes — triggering re-evaluation of the memo's `fn` without changing any tracked dependency. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where the memo re-derives its value in response to external events.
+
 ### Task (`src/nodes/task.ts`)
 
 **Graph node**: `TaskNode<T>` (source + sink)
@@ -209,6 +221,8 @@ During dependency tracking, only the synchronous preamble of `fn` is tracked (be
 
 `isPending()` returns `true` while a computation is in flight. `abort()` cancels the current computation manually. Errors are preserved like Memo, but old values are retained on errors (the last successful result remains accessible).
 
+**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` marks the node dirty and triggers re-execution, which aborts any in-flight computation via the existing `AbortController` mechanism before starting a new one.
+
 ### Effect (`src/nodes/effect.ts`)
 
 **Graph node**: `EffectNode` (sink only)
@@ -225,7 +239,7 @@ A reactive object where each property is its own signal. Properties are automati
 
 **Structural reactivity**: The internal `MemoNode` tracks edges from child signals to the store node. When consumers call `store.get()`, the node acts as both a source (to the consumer) and a sink (of its child signals). Changes to any child signal propagate through the store to its consumers.
 
-**Two-path access**: On first `get()`, `refresh()` executes `buildValue()` with `activeSink = storeNode`, establishing edges from each child signal to the store. Subsequent reads use a fast path: `untrack(buildValue)` rebuilds the value without re-establishing edges. Structural mutations (`add`/`remove`) call `invalidateEdges()` (nulling `node.sources`) to force re-establishment on the next read.
+**Two-path access with `FLAG_RELINK`**: On first `get()`, `refresh()` executes `buildValue()` with `activeSink = storeNode`, establishing edges from each child signal to the store. Subsequent reads use a fast path: `untrack(buildValue)` rebuilds the value without re-establishing edges. Structural mutations (`add`/`remove`/`set` with additions or removals) set `FLAG_DIRTY | FLAG_RELINK` on the node. The next `get()` detects `FLAG_RELINK` and forces a tracked `refresh()` after rebuilding the value, so `recomputeMemo()` links new child signals and trims removed ones without orphaning edges.
 
 **Diff-based updates**: `store.set(newObj)` diffs the new object against the current state, applying only the granular changes to child signals. This preserves identity of unchanged child signals and their downstream edges.
 
@@ -237,38 +251,48 @@ A reactive object where each property is its own signal. Properties are automati
 
 A reactive array with stable keys and per-item reactivity. Each item becomes a `State<T>` signal, keyed by a configurable key generation strategy (auto-increment, string prefix, or custom function).
 
-**Structural reactivity**: Uses the same `MemoNode` + `invalidateEdges` + two-path access pattern as Store. The `buildValue()` function reads all child signals in key order, establishing edges on the refresh path.
+**Structural reactivity**: Uses the same `MemoNode` + `FLAG_RELINK` + two-path access pattern as Store. The `buildValue()` function reads all child signals in key order, establishing edges on the refresh path.
 
 **Stable keys**: Keys survive sorting and reordering. `byKey(key)` returns a stable `State<T>` reference regardless of the item's current index. `sort()` reorders the keys array without destroying signals.
 
-**Diff-based updates**: `list.set(newArray)` uses `diffArrays()` to compute granular additions, changes, and removals. Changed items update their existing `State` signals; structural changes (add/remove) trigger `invalidateEdges()`.
+**Diff-based updates**: `list.set(newArray)` uses `diffArrays()` to compute granular additions, changes, and removals. Changed items update their existing `State` signals; structural changes (add/remove) set `FLAG_DIRTY | FLAG_RELINK`.
 
 ### Collection (`src/nodes/collection.ts`)
 
 Collection implements two creation patterns that share the same `Collection<T>` interface:
 
-#### `createCollection(start, options?)` — externally driven
+#### `createCollection(watched, options?)` — externally driven
 
 **Graph node**: `MemoNode<T[]>` (source + sink, tracks item values)
 
-An externally-driven reactive collection with a watched lifecycle, mirroring `createSensor(start, options?)`. The `start` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations. Initial items are provided via `options.value` (default `[]`).
+An externally-driven reactive collection with a watched lifecycle, mirroring `createSensor(watched, options?)`. The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations. Initial items are provided via `options.value` (default `[]`).
 
-**Lazy lifecycle**: Like Sensor, the `start` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`). The `startWatching()` guard ensures `start` fires before `link()` so synchronous mutations inside `start` update `node.value` before the activating effect reads it.
+**Lazy lifecycle**: Like Sensor, the `watched` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`). The `startWatching()` guard ensures `watched` fires before `link()` so synchronous mutations inside `watched` update `node.value` before the activating effect reads it.
 
-**External mutation via `applyChanges`**: Additions create new item signals (via configurable `createItem` factory, default `createState`). Changes update existing `State` signals. Removals delete signals and keys. Structural changes null out `node.sources` to force edge re-establishment. The node uses `equals: () => false` since structural changes are managed externally rather than detected by diffing.
+**External mutation via `applyChanges`**: Additions create new item signals (via configurable `createItem` factory, default `createState`). Changes update existing `State` signals. Removals delete signals and keys. Structural changes set `FLAG_DIRTY | FLAG_RELINK` to trigger edge re-establishment on the next read. The node uses `equals: () => false` since structural changes are managed externally rather than detected by diffing.
 
-**Two-path access**: Same pattern as Store/List — first `get()` uses `refresh()` to establish edges from child signals to the collection node; subsequent reads use `untrack(buildValue)` to avoid re-linking.
+**Two-path access with `FLAG_RELINK`**: Same pattern as Store/List — first `get()` uses `refresh()` to establish edges from child signals to the collection node; subsequent reads use `untrack(buildValue)` to avoid re-linking. When `FLAG_RELINK` is set, the next `get()` forces a tracked `refresh()` after rebuilding to link new child signals and trim removed ones.
 
 #### `deriveCollection(source, callback)` — internally derived
 
-**Graph node**: `MemoNode<string[]>` (source + sink, tracks keys not values)
+**Graph node**: `MemoNode<T[]>` (source + sink, tracks item values)
 
 An internal factory (not exported from the public API) that creates a read-only derived transformation of a List or another Collection. Exposed to users via the `.deriveCollection(callback)` method on List and Collection. Each source item is individually memoized: sync callbacks create `Memo` signals, async callbacks create `Task` signals.
 
-**Two-level reactivity**: The derived collection's `MemoNode` tracks structural changes only — its `fn` (`syncKeys`) reads `source.keys()` to detect additions and removals. Value-level changes flow through the individual per-item `Memo`/`Task` signals, which independently track their source item.
+**Consistent with Store/List/createCollection**: The `MemoNode.value` is a `T[]` (cached computed values), and keys are tracked in a separate local `string[]` variable. The `equals` function uses shallow reference equality on array elements to prevent unnecessary downstream propagation when re-evaluation produces the same item references. The node starts `FLAG_DIRTY` to ensure the first `refresh()` establishes edges.
+
+**Initialization**: Source keys are read via `untrack(() => source.keys())` to populate the signals map for direct access (`at()`, `byKey()`, `keyAt()`, `[Symbol.iterator]()`) without triggering premature `watched` activation on the upstream source. The node stays `FLAG_DIRTY` so the first `refresh()` with a real subscriber establishes proper graph edges.
+
+**Non-destructive `syncKeys()` with `FLAG_RELINK`**: Like Store/List/createCollection, `deriveCollection`'s `syncKeys()` sets `FLAG_RELINK` on the node when keys change, without touching the edge lists. This avoids orphaning edges in upstream sink lists, which would prevent the cascading cleanup in `unlink()` from reaching the source List's `watched` lifecycle. All four composite signal types now use the same `FLAG_RELINK` mechanism for structural edge invalidation.
+
+**Three-path `ensureFresh()`**: Access to the derived collection's value follows three distinct paths depending on the node's edge state:
 
-**Key differences from Store/List**: The `MemoNode.value` is a `string[]` (the keys array), not the collection's actual values. The `equals` function is a shallow string array comparison (`keysEqual`). The node starts `FLAG_DIRTY` (unlike Store/List which start clean after initialization) to ensure the first `refresh()` establishes the edge from source to collection.
+| Path | Condition | Behavior |
+|------|-----------|---------|
+| Fast path | `node.sources` exists | `untrack(buildValue)` rebuilds without re-linking. If `FLAG_RELINK` is set, forces a tracked `refresh()` to link new child signals and trim deleted ones. |
+| First subscriber | no `node.sources`, but `node.sinks` | `refresh()` via `recomputeMemo()` establishes all graph edges (source → derived, child signals → derived) in a single tracked pass. This is where `watched` activation propagates upstream. |
+| No subscriber | neither sources nor sinks | `untrack(buildValue)` computes the value without establishing edges. Keeps `FLAG_DIRTY` so the first real subscriber triggers the "first subscriber" path. Used during chained `deriveCollection` initialization. |
 
-**No `invalidateEdges`**: Unlike Store/List, the derived collection never needs to re-establish its source edge because it has exactly one source (the parent List or Collection) that never changes identity. Structural changes (adding/removing per-item signals) happen inside `syncKeys` without affecting the source edge.
+The first-subscriber path is the key to `watched` lifecycle propagation: when an effect first reads a derived collection, `recomputeMemo()` sets `activeSink = derivedNode`, then `buildValue()` calls `source.keys()`, which triggers `subscribe()` on the upstream List with a non-null `activeSink`. This creates the List→derived edge and activates the List's `watched` callback. When the effect later disposes, the cascading cleanup in `unlink()` traverses effect→derived→List, firing the List's `stop` cleanup.
 
-**Chaining**: `.deriveCollection()` creates a new derived collection from an existing one, forming a pipeline. Each level in the chain has its own `MemoNode` for structural tracking and its own set of per-item derived signals.
+**Chaining**: `.deriveCollection()` creates a new derived collection from an existing one, forming a pipeline. Each level in the chain has its own `MemoNode` for value caching and its own set of per-item derived signals. The "no subscriber" path in `ensureFresh()` ensures intermediate levels don't prematurely activate upstream `watched` callbacks during construction — activation cascades through the entire chain only when the terminal effect subscribes.

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.18.2
+
+### Fixed
+
+- **`watched` propagation through `deriveCollection()` chains**: When an effect reads a derived collection, the `watched` callback on the source List, Store, or Collection now activates correctly — even through multiple levels of `.deriveCollection()` chaining. Previously, `deriveCollection` did not propagate sink subscriptions back to the source's `watched` lifecycle.
+- **Stable `watched` lifecycle during mutations**: Adding, removing, or sorting items on a List (or Store/Collection) consumed through `deriveCollection()` no longer tears down and restarts the `watched` callback. The watcher remains active as long as at least one downstream effect is subscribed.
+- **Cleanup cascade on disposal**: When the last effect unsubscribes from a derived collection chain, cleanup now propagates upstream through all intermediate nodes to the source, correctly invoking the `watched` cleanup function.
+
+### Changed
+
+- **`FLAG_RELINK` replaces source-nulling in composite signals**: Store, List, Collection, and deriveCollection no longer null out `node.sources`/`node.sourcesTail` on structural mutations. Instead, a new `FLAG_RELINK` bitmap flag triggers a tracked `refresh()` on the next `.get()` call, re-establishing edges cleanly via `link()`/`trimSources()` without orphaning them.
+- **Cascading `trimSources()` in `unlink()`**: When a MemoNode loses all sinks, its own sources are now trimmed recursively, ensuring upstream `watched` cleanup propagates correctly through intermediate nodes.
+- **Three-path `ensureFresh()` in `deriveCollection`**: The internal freshness check now distinguishes between fast path (has sources, clean), first subscriber (has sinks but no sources yet), and no subscriber (untracked build). This prevents premature `watched` activation during initialization.
+
+## 0.18.1
+
+### Added
+
+- **Memo `watched(invalidate)` option**: `createMemo(fn, { watched })` accepts a lazy lifecycle callback that receives an `invalidate` function. Calling `invalidate()` marks the memo dirty and triggers re-evaluation. The callback is invoked on first sink attachment and cleaned up when the last sink detaches. This enables patterns like DOM observation where a memo re-derives its value in response to external events (e.g., MutationObserver) without needing a separate Sensor.
+- **Task `watched(invalidate)` option**: Same pattern as Memo. Calling `invalidate()` aborts any in-flight computation and triggers re-execution.
+- **`CollectionChanges<T>` type**: New typed interface for collection mutations with `add?: T[]`, `change?: T[]`, `remove?: T[]` arrays. Replaces the untyped `DiffResult` records previously used by `CollectionCallback`.
+- **`SensorOptions<T>` type**: Dedicated options type for `createSensor`, extending `SignalOptions<T>` with optional `value`.
+- **`CollectionChanges` export** from public API (`index.ts`).
+- **`SensorOptions` export** from public API (`index.ts`).
+
+### Changed
+
+- **`createSensor` parameter renamed**: `start` → `watched` for consistency with Store/List lifecycle terminology.
+- **`createSensor` options type**: `ComputedOptions<T>` → `SensorOptions<T>`. This decouples Sensor options from `ComputedOptions`, which now carries the `watched(invalidate)` field for Memo/Task.
+- **`createCollection` parameter renamed**: `start` → `watched` for consistency.
+- **`CollectionCallback` is now generic**: `CollectionCallback` → `CollectionCallback<T>`. The `applyChanges` parameter accepts `CollectionChanges<T>` instead of `DiffResult`.
+- **`CollectionOptions.createItem` signature**: `(key: string, value: T) => Signal<T>` → `(value: T) => Signal<T>`. Key generation is now handled internally.
+- **`KeyConfig<T>` return type relaxed**: Key functions may now return `string | undefined`. Returning `undefined` falls back to synthetic key generation.
+
+### Removed
+
+- **`DiffResult` removed from public API**: No longer re-exported from `index.ts`. The type remains available from `src/nodes/list.ts` for internal use but is superseded by `CollectionChanges<T>` for collection mutations.
+
+## 0.18.0
+
+Baseline release. Factory function API (`createState`, `createMemo`, `createTask`, `createEffect`, `createStore`, `createList`, `createCollection`, `createSensor`) with linked-list graph engine.

package/CLAUDE.md

@@ -86,10 +86,10 @@ The generic constraint `T extends {}` is crucial - it excludes `null` and `undef
 ### Collection Architecture
 
 **Collections** (`createCollection`): Externally-driven collections with watched lifecycle
-- Created via `createCollection(start, options?)` — mirrors `createSensor(start, options?)`
-- The `start` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
+- Created via `createCollection(watched, options?)` — mirrors `createSensor(watched, options?)`
+- The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
 - `options.value` provides initial items (default `[]`), `options.keyConfig` configures key generation
-- Lazy activation: `start` callback invoked on first effect access, cleanup when unwatched
+- Lazy activation: `watched` callback invoked on first effect access, cleanup when unwatched
 
 **Derived Collections** (`deriveCollection`): Transformed from Lists or other Collections
 - Created via `list.deriveCollection(callback)` or `collection.deriveCollection(callback)`
@@ -124,7 +124,7 @@ Computed signals implement smart memoization:
 
 ## Resource Management with Watch Callbacks
 
-Sensor and Collection signals use a **start callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
+Sensor, Collection, Memo (with `watched` option), and Task (with `watched` option) use a **watched callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
 
 ```typescript
 // Sensor: track external input with state updates
@@ -164,9 +164,11 @@ const user = createStore({ name: 'Alice', email: 'alice@example.com' }, {
 ```
 
 **Watch Lifecycle**:
-1. First effect accesses signal → start/watched callback executed
+1. First effect accesses signal → watched callback executed
 2. Last effect stops watching → returned cleanup function executed
-3. New effect accesses signal → start/watched callback executed again
+3. New effect accesses signal → watched callback executed again
+
+**Watched propagation through `deriveCollection()`**: When an effect reads a derived collection, the `watched` callback on the source List, Store, or Collection activates automatically — even through multiple levels of `.deriveCollection()` chaining. The reactive graph establishes edges from effect → derived collection → source, and `watched` fires when the first edge reaches the source. Mutations (add, remove, sort) on the source do **not** tear down and restart `watched` — the watcher remains stable as long as at least one downstream effect is subscribed. When the last effect disposes, cleanup cascades upstream through all intermediate nodes.
 
 This pattern enables **lazy resource allocation** - resources are only consumed when actually needed and automatically freed when no longer used.
 
@@ -230,7 +232,7 @@ const firstTodo = todoList.byKey('task1') // Access by stable key
 
 **Collection (`createCollection`)**:
 - Externally-driven keyed collections (WebSocket streams, SSE, external data feeds)
-- Mirrors `createSensor(start, options?)` — start callback pattern with watched lifecycle
+- Mirrors `createSensor(watched, options?)` — watched callback pattern with lazy lifecycle
 - Same `Collection` interface — `.get()`, `.byKey()`, `.keys()`, `.deriveCollection()`
 
 ```typescript
@@ -263,6 +265,7 @@ const processed = todoList
 **Memo (`createMemo`)**:
 - Synchronous derived computations with memoization
 - Reducer pattern with previous value access
+- Optional `watched(invalidate)` callback for lazy external invalidation (e.g., MutationObserver)
 
 ```typescript
 const doubled = createMemo(() => count.get() * 2)
@@ -283,6 +286,7 @@ const runningTotal = createMemo(prev => prev + currentValue.get(), { value: 0 })
 
 **Task (`createTask`)**:
 - Async computations with automatic cancellation
+- Optional `watched(invalidate)` callback for lazy external invalidation
 
 ```typescript
 const userData = createTask(async (prev, abort) => {
@@ -344,6 +348,28 @@ const display = createMemo(() => user.name.get() + user.email.get())
 4. **Async Race Conditions**: Trust automatic cancellation with AbortSignal
 5. **Circular Dependencies**: The graph detects and throws `CircularDependencyError`
 6. **Untracked `byKey()`/`at()` access**: On Store, List, and Collection, `byKey()`, `at()`, `keyAt()`, and `indexOfKey()` do **not** create graph edges. They are direct lookups that bypass structural tracking. An effect using only `collection.byKey('x')?.get()` will react to value changes of key `'x'`, but will **not** re-run if key `'x'` is added or removed. Use `get()`, `keys()`, or `length` to track structural changes.
+7. **Conditional reads delay `watched` activation**: Dependencies are tracked dynamically based on which `.get()` calls actually execute during each effect run. If a signal read is inside a branch that doesn't execute (e.g., inside the `ok` branch of `match()` while a Task is still pending), no edge is created and `watched` does not activate until that branch runs. **Fix:** read the signal eagerly before conditional logic:
+
+```typescript
+// Good: watched activates immediately, errors/nil in derived are also caught
+createEffect(() => {
+  match([task, derived], {
+    ok: ([result, values]) => renderList(values, result),
+    nil: () => showLoading(),
+  })
+})
+
+// Bad: watched only activates after task resolves
+createEffect(() => {
+  match([task], {
+    ok: ([result]) => {
+      const values = derived.get() // only tracked in this branch
+      renderList(values, result)
+    },
+    nil: () => showLoading(),
+  })
+})
+```
 
 ## Advanced Patterns
 

package/GUIDE.md

@@ -268,7 +268,7 @@ import { createCollection, createEffect } from '@zeix/cause-effect'
 
 const messages = createCollection((applyChanges) => {
   const ws = new WebSocket('/messages')
-  ws.onmessage = (e) => applyChanges({ changed: true, add: JSON.parse(e.data) })
+  ws.onmessage = (e) => applyChanges({ add: JSON.parse(e.data) })
   return () => ws.close()
 }, { keyConfig: msg => msg.id })
 

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.18.0
+Version 0.18.2
 
 **Cause & Effect** is a reactive state management primitives library for TypeScript. It provides the foundational building blocks for managing complex, dynamic, composite, and asynchronous state — correctly and performantly — in a unified signal graph.
 
@@ -266,7 +266,7 @@ Lists have `.keys()`, `.add()`, and `.remove()` methods like stores. Additionall
 
 ### Collection
 
-A reactive collection with item-level memoization. Collections can be externally-driven (via a start callback) or derived from a List or another Collection.
+A reactive collection with item-level memoization. Collections can be externally-driven (via a watched callback) or derived from a List or another Collection.
 
 **Externally-driven collections** receive data from external sources (WebSocket, Server-Sent Events, etc.) via `applyChanges()`:
 
@@ -277,7 +277,7 @@ const items = createCollection((applyChanges) => {
   const ws = new WebSocket('/items')
   ws.onmessage = (e) => {
     const { add, change, remove } = JSON.parse(e.data)
-    applyChanges({ changed: true, add, change, remove })
+    applyChanges({ add, change, remove })
   }
   return () => ws.close()
 }, { keyConfig: item => item.id })
@@ -285,7 +285,7 @@ const items = createCollection((applyChanges) => {
 createEffect(() => console.log('Items:', items.get()))
 ```
 
-The start callback activates lazily when the collection is first accessed by an effect and cleans up when no effects are watching. Options include `value` for initial items (default `[]`) and `keyConfig` for key generation.
+The watched callback activates lazily when the collection is first accessed by an effect and cleans up when no effects are watching. Options include `value` for initial items (default `[]`) and `keyConfig` for key generation.
 
 **Derived collections** transform Lists or other Collections via `.deriveCollection()`:
 
@@ -476,7 +476,7 @@ dispose() // Cleans up the effect and runs the returned cleanup
 
 ### Resource Management with Watch Callbacks
 
-Sensor and Collection signals use a **start callback** for lazy resource management. The callback runs when the signal is first accessed by an effect and the returned cleanup function runs when no effects are watching:
+Sensor and Collection signals use a **watched callback** for lazy resource management. The callback runs when the signal is first accessed by an effect and the returned cleanup function runs when no effects are watching:
 
 ```js
 import { createSensor, createCollection, createEffect } from '@zeix/cause-effect'
@@ -517,11 +517,42 @@ const user = createStore({ name: 'Alice' }, {
 })
 ```
 
+**Watched propagation through `deriveCollection()`**: When an effect reads a derived collection, the `watched` callback on the source List, Store, or Collection activates automatically — even through multiple levels of chaining. Mutations on the source do not tear down the watcher. When the last effect disposes, cleanup cascades upstream through all intermediate nodes.
+
+**Tip — conditional reads delay activation**: Dependencies are tracked based on which `.get()` calls actually execute. If a signal read is inside a branch that doesn't run yet (e.g., inside `match()`'s `ok` branch while a Task is pending), `watched` won't activate until that branch executes. Read signals eagerly before conditional logic to ensure immediate activation:
+
+```js
+createEffect(() => {
+  match([task, derived], { // derived is always tracked
+    ok: ([result, values]) => renderList(values, result),
+    nil: () => showLoading(),
+  })
+})
+```
+
+Memo and Task signals also support a `watched` option, but their callback receives an `invalidate` function that marks the signal dirty and triggers recomputation:
+
+```js
+const changes = createMemo((prev) => {
+  const next = new Set(parent.querySelectorAll(selector))
+  // ... diff prev vs next ...
+  return { current: next, added, removed }
+}, {
+  value: { current: new Set(), added: [], removed: [] },
+  watched: (invalidate) => {
+    const observer = new MutationObserver(() => invalidate())
+    observer.observe(parent, { childList: true, subtree: true })
+    return () => observer.disconnect()
+  }
+})
+```
+
 This pattern is ideal for:
 - Event listeners that should only be active when data is being watched
 - Network connections that can be lazily established
 - Expensive computations that should pause when not needed
 - External subscriptions (WebSocket, Server-Sent Events, etc.)
+- Computed signals that need to react to external events (DOM mutations, timers)
 
 ## Contributing & License
 

package/context7.json

@@ -0,0 +1,4 @@
+{
+	"url": "https://context7.com/zeixcom/cause-effect",
+	"public_key": "pk_opatBUM6blxfIrNVkGw84"
+}