@zeix/cause-effect 0.18.1 → 0.18.3

package/.ai-context.md

@@ -19,7 +19,7 @@ The reactive engine is a linked graph of source and sink nodes connected by `Edg
 ### Node Types
 ```
 StateNode<T>  — source-only with equality + guard (State, Sensor)
-MemoNode<T>   — source + sink (Memo, Store, List, Collection)
+MemoNode<T>   — source + sink (Memo, Slot, Store, List, Collection)
 TaskNode<T>   — source + sink + async (Task)
 EffectNode    — sink + owner (Effect)
 Scope         — owner-only (createScope)
@@ -33,6 +33,7 @@ Scope         — owner-only (createScope)
 - **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
+- **Slot** (`createSlot`): Stable delegation signal with swappable backing signal, designed for integration layers (property descriptors, custom elements)
 - **Effect** (`createEffect`): Side effect handlers that react to signal changes
 
 ### Key Principles
@@ -56,7 +57,8 @@ cause-effect/
 │   │   ├── effect.ts      # createEffect, match — side effects
 │   │   ├── store.ts       # createStore — reactive object stores
 │   │   ├── list.ts        # createList — reactive arrays with stable keys
-│   │   └── collection.ts  # createCollection — externally-driven and derived collections
+│   │   ├── collection.ts  # createCollection — externally-driven and derived collections
+│   │   └── slot.ts        # createSlot — stable delegation with swappable backing signal
 │   ├── util.ts            # Utility functions and type checks
 │   └── ...
 ├── index.ts           # Entry point / main export file
@@ -135,6 +137,12 @@ const feed = createCollection<{ id: string; text: string }>((applyChanges) => {
   ws.onmessage = (e) => applyChanges(JSON.parse(e.data))
   return () => ws.close()
 }, { keyConfig: item => item.id })
+
+// Slot for stable property delegation
+const local = createState('default')
+const slot = createSlot(local)
+Object.defineProperty(element, 'label', slot)
+slot.replace(createMemo(() => parentState.get())) // swap backing signal
 ```
 
 ### Reactivity
@@ -195,8 +203,8 @@ const processed = items.deriveCollection(item => item.toUpperCase())
 - Pure function annotations: `/*#__PURE__*/` for tree-shaking
 
 ### Naming Conventions
-- Factory functions: `create*` prefix (createState, createMemo, createEffect, createStore, createList, createCollection, createSensor)
-- Type predicates: `is*` prefix (isState, isMemo, isTask, isStore, isList, isCollection, isSensor)
+- Factory functions: `create*` prefix (createState, createMemo, createEffect, createStore, createList, createCollection, createSensor, createSlot)
+- Type predicates: `is*` prefix (isState, isMemo, isTask, isStore, isList, isCollection, isSensor, isSlot)
 - Type constants: `TYPE_*` format (TYPE_STATE, TYPE_STORE, TYPE_SENSOR, TYPE_COLLECTION)
 - Callback types: `*Callback` suffix (MemoCallback, TaskCallback, EffectCallback, SensorCallback, CollectionCallback, DeriveCollectionCallback)
 

package/.github/copilot-instructions.md

@@ -20,6 +20,7 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - **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
+- **Slot** (`createSlot`): Stable delegation signal with swappable backing signal, designed for integration layers (property descriptors, custom elements)
 - **Effect** (`createEffect`): Side effects that react to signal changes
 
 ## Key Files Structure
@@ -34,6 +35,7 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - `src/nodes/store.ts` - createStore, isStore, Store type, diff, isEqual
 - `src/nodes/list.ts` - createList, isList, List type
 - `src/nodes/collection.ts` - createCollection, isCollection, Collection type, deriveCollection (internal)
+- `src/nodes/slot.ts` - createSlot, isSlot, Slot type
 - `src/util.ts` - Utility functions and type checks
 - `index.ts` - Entry point / main export file
 
@@ -47,8 +49,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - JSDoc comments for all public APIs
 
 ### Naming Conventions
-- Factory functions: `create*` (e.g., `createState`, `createMemo`, `createEffect`, `createStore`, `createList`, `createCollection`, `createSensor`)
-- Type predicates: `is*` (e.g., `isState`, `isMemo`, `isStore`, `isList`, `isCollection`, `isSensor`)
+- Factory functions: `create*` (e.g., `createState`, `createMemo`, `createEffect`, `createStore`, `createList`, `createCollection`, `createSensor`, `createSlot`)
+- Type predicates: `is*` (e.g., `isState`, `isMemo`, `isStore`, `isList`, `isCollection`, `isSensor`, `isSlot`)
 - Type constants: `TYPE_*` for internal type tags
 - Callback types: `*Callback` suffix (MemoCallback, TaskCallback, EffectCallback, SensorCallback, CollectionCallback, DeriveCollectionCallback)
 - Private variables: use descriptive names, no underscore prefix
@@ -148,6 +150,12 @@ const feed = createCollection<{ id: string; text: string }>((applyChanges) => {
   ws.onmessage = (e) => applyChanges(JSON.parse(e.data))
   return () => ws.close()
 }, { keyConfig: item => item.id })
+
+// Slot for stable property delegation
+const local = createState('default')
+const slot = createSlot(local)
+Object.defineProperty(element, 'label', slot)
+slot.replace(createMemo(() => parentState.get())) // swap backing signal
 ```
 
 ### Reactivity

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
 
@@ -168,7 +178,7 @@ Creates an ownership scope without an effect. The scope becomes `activeOwner` du
 
 ### State (`src/nodes/state.ts`)
 
-**Graph node**: `StateNode<T>` (source only)
+**Graph node**: `MemoNode<T>` (source + sink, single delegated dependency)
 
 A mutable value container. The simplest signal type — `get()` links and returns the value, `set()` validates, calls `setState()`, which propagates changes to dependents.
 
@@ -221,6 +231,18 @@ A side-effecting computation that runs immediately and re-runs when dependencies
 
 Effects double as owners: they have a `cleanup` field and become `activeOwner` during execution. Child effects and scopes created during execution are automatically disposed when the parent effect re-runs or is disposed.
 
+### Slot (`src/nodes/slot.ts`)
+
+**Graph node**: `MemoNode<T>` (source + sink)
+
+A stable reactive source that delegates reads and writes to a swappable backing signal. Designed for integration layers (e.g. custom element systems) where a property position must switch its backing signal — from a local `State` to a parent-controlled `Memo`, for example — without breaking existing subscribers.
+
+The slot object doubles as a property descriptor: its `get`, `set`, `configurable`, and `enumerable` fields can be passed directly to `Object.defineProperty()`. Control methods (`replace()`, `current()`) live on the same object but are ignored by the property definition; integration code should retain the slot reference for later `replace()` calls.
+
+**Graph behavior**: Sinks link to the slot (stable across replacements). The slot links upstream to exactly one delegated signal at a time. On `replace(nextSignal)`, the slot updates its internal reference, flags sinks dirty via `propagate()`, and flushes. Re-running sinks call `slot.get()`, which triggers `refresh()` — dependency tracking (`link` + `trimSources`) re-subscribes to the new backing signal and drops stale edges to the old one. Setter calls forward to the delegated signal when writable; `ReadonlySignalError` is thrown otherwise.
+
+Options mirror State: optional `guard` and `equals`. Type-level replacement follows `replace<U extends T>(next)` — narrowing is allowed, widening is not.
+
 ### Store (`src/nodes/store.ts`)
 
 **Graph node**: `MemoNode<T>` (source + sink, used for structural reactivity)
@@ -229,7 +251,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.
 
@@ -241,11 +263,11 @@ 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`)
 
@@ -259,9 +281,9 @@ An externally-driven reactive collection with a watched lifecycle, mirroring `cr
 
 **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
 
@@ -271,6 +293,18 @@ An internal factory (not exported from the public API) that creates a read-only
 
 **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.
 
-**Two-path access with structural fallback**: Same pattern as Store/List — first `get()` uses `refresh()` to establish edges; subsequent reads use `untrack(buildValue)`. A `syncKeys()` step inside `buildValue` syncs the signals map with `source.keys()`. If keys changed, `syncKeys` nulls `node.sources` to force edge re-establishment via `refresh()`, ensuring new child signals are properly linked.
+**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:
+
+| 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. |
+
+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 value caching 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

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.18.3
+
+### Added
+
+- **Slot signal (`createSlot`, `isSlot`)**: A stable reactive source that delegates reads and writes to a swappable backing signal. Designed for integration layers (e.g. custom element systems) where a property position must switch its backing signal — from a local writable `State` to a parent-controlled `Memo` — without breaking existing subscribers. The slot object doubles as a property descriptor for `Object.defineProperty()`. `replace(nextSignal)` swaps the backing signal and invalidates downstream subscribers; `current()` returns the currently delegated signal. Options mirror State: optional `guard` and `equals`.
+
+### Fixed
+
+- **`match()` now preserves tuple types**: The `ok` handler correctly receives per-position types (e.g., `[number, string]`) instead of a widened union (e.g., `(number | string)[]`). The `signals` parameter and `MatchHandlers` type now use `readonly [...T]` to preserve tuple inference.
+
+## 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

package/CLAUDE.md

@@ -20,6 +20,7 @@ Think of signals as **observable cells** in a spreadsheet:
 - **Store signals** are structured tables where individual columns (properties) are reactive
 - **List signals** are tables with stable row IDs that survive sorting and reordering
 - **Collection signals** are externally-fed reactive tables with a watched lifecycle (WebSocket, SSE), or derived tables from Lists/Collections via `.deriveCollection()`
+- **Slot signals** are stable cell references that delegate to a swappable backing cell — used by integration layers to swap a property's backing signal without breaking subscribers
 - **Effects** are event handlers that trigger side effects when cells change
 
 ## Architectural Deep Dive
@@ -37,7 +38,7 @@ The core of reactivity lies in the linked graph system (`src/graph.ts`):
 
 ```
 StateNode<T>  — source-only with equality + guard (State, Sensor)
-MemoNode<T>   — source + sink (Memo, Store, List, Collection)
+MemoNode<T>   — source + sink (Memo, Slot, Store, List, Collection)
 TaskNode<T>   — source + sink + async (Task)
 EffectNode    — sink + owner (Effect)
 Scope         — owner-only (createScope)
@@ -70,6 +71,14 @@ type Task<T extends {}> = {
   abort(): void
 }
 
+// Slot delegates to a swappable backing signal
+type Slot<T extends {}> = {
+  get(): T
+  set(next: T): void
+  replace<U extends T>(next: Signal<U>): void
+  current(): Signal<T>
+}
+
 // Collection interface
 type Collection<T extends {}> = {
   get(): T[]
@@ -168,6 +177,8 @@ const user = createStore({ name: 'Alice', email: 'alice@example.com' }, {
 2. Last effect stops watching → returned cleanup function executed
 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.
 
 ## Advanced Patterns and Best Practices
@@ -295,6 +306,21 @@ const userData = createTask(async (prev, abort) => {
 })
 ```
 
+**Slot (`createSlot`)**:
+- Property positions that must swap their backing signal without breaking subscribers
+- Integration layers (custom elements, component systems) using `Object.defineProperty()`
+- The slot object is a valid property descriptor (`get`, `set`, `configurable`, `enumerable`)
+
+```typescript
+const local = createState('default')
+const slot = createSlot(local)
+Object.defineProperty(element, 'label', slot)
+
+// Swap backing signal — subscribers re-run automatically
+const parentLabel = createMemo(() => parentState.get())
+slot.replace(parentLabel)
+```
+
 ### Error Handling Strategies
 
 The library provides several layers of error handling:
@@ -346,6 +372,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 })
 
@@ -296,3 +296,25 @@ const windowSize = createSensor((set) => {
 ```
 
 The start callback runs lazily — only when an effect first reads the sensor. When no effects are watching, the cleanup runs automatically. When an effect reads it again, the start callback runs again. No manual setup/teardown.
+
+### Slot: stable property delegation
+
+If you are building a component system, you often need to expose signals as object properties via `Object.defineProperty()`. The challenge arises when a property must switch its backing signal — for example, from a local writable `State` to a parent-controlled read-only `Memo` — without breaking existing subscribers.
+
+`createSlot()` solves this by providing a stable reactive source that delegates to a swappable backing signal. The slot object itself is a valid property descriptor:
+
+```ts
+import { createState, createMemo, createSlot, createEffect } from '@zeix/cause-effect'
+
+const local = createState('default')
+const slot = createSlot(local)
+Object.defineProperty(element, 'label', slot)
+
+createEffect(() => console.log(element.label)) // logs: "default"
+
+// Parent provides a derived value — swap without breaking the effect
+const parentLabel = createMemo(() => `Parent: ${parentState.get()}`)
+slot.replace(parentLabel) // effect re-runs with new value
+```
+
+Setter calls forward to the current backing signal when it is writable. If the backing signal is read-only (e.g. a Memo), setting throws `ReadonlySignalError`. The `replace()` and `current()` methods are on the slot object but not on the installed property — keep the slot reference for later control.

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.18.1
+Version 0.18.3
 
 **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.
 
@@ -27,6 +27,7 @@ Every signal type participates in the same dependency graph with the same propag
 | **Store** | Reactive object (keyed properties, proxy-based) | `createStore()` |
 | **List** | Reactive array (keyed items, stable identity) | `createList()` |
 | **Collection** | Reactive collection (external source or derived, item-level memoization) | `createCollection()` |
+| **Slot** | Stable delegation for integration layers (swappable backing signal) | `createSlot()` |
 | **Effect** | Side-effect sink (terminal) | `createEffect()` |
 
 ## Design Principles
@@ -322,6 +323,33 @@ const processed = users
   .deriveCollection(user => user.active ? `Active: ${user.name}` : `Inactive: ${user.name}`)
 ```
 
+### Slot
+
+A stable reactive source that delegates to a swappable backing signal. Designed for integration layers (e.g. custom element systems) where a property must switch its backing signal without breaking subscribers. The slot object doubles as a property descriptor for `Object.defineProperty()`:
+
+```js
+import { createState, createMemo, createSlot, createEffect } from '@zeix/cause-effect'
+
+const local = createState(1)
+const slot = createSlot(local)
+
+// Use as a property descriptor
+const target = {}
+Object.defineProperty(target, 'value', slot)
+
+createEffect(() => console.log(target.value)) // logs: 1
+
+// Swap the backing signal — subscribers re-run automatically
+const derived = createMemo(() => 42)
+slot.replace(derived) // logs: 42
+
+// Write through to the current backing signal
+slot.replace(local)
+target.value = 10 // sets local to 10
+```
+
+`replace()` and `current()` are available on the slot object but are not installed on the property — keep the slot reference for later control. Setting via the property forwards to the delegated signal; throws `ReadonlySignalError` if the current backing signal is read-only.
+
 ### Effect
 
 A side-effect sink that runs whenever the signals it reads change. Effects are terminal — they consume values but produce none. The returned function disposes the effect:
@@ -418,6 +446,10 @@ Does the data come from *outside* the reactive system?
         └─ Is it derived / read-only transformation of a `List` or `Collection`?
               └─ Yes → `.deriveCollection()`
                  (memoized + supports async mapping + chaining)
+
+Do you need a *stable property position* that can swap its backing signal?
+└─ Yes → `createSlot(existingSignal)`
+   (integration layers, custom elements, property descriptors)
 ```
 
 ## Advanced Usage
@@ -517,6 +549,19 @@ 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

package/REQUIREMENTS.md

@@ -32,7 +32,7 @@ All signals enforce `T extends {}`, excluding `null` and `undefined` at the type
 Every signal type participates in the same dependency graph with the same propagation, batching, and cleanup semantics. Composite signals (Store, List, Collection) and async signals (Task) are first-class citizens, not afterthoughts. The goal is that all state which is derivable can be derived.
 
 ### Minimal Surface, Maximum Coverage
-The library ships 8 signal types — each justified by a distinct role in the graph and a distinct data structure it manages:
+The library ships 9 signal types — each justified by a distinct role in the graph and a distinct data structure it manages:
 
 | Type | Role | Data Structure |
 |------|------|----------------|
@@ -41,6 +41,7 @@ The library ships 8 signal types — each justified by a distinct role in the gr
 | **Memo** | Synchronous derivation | Single value (memoized) |
 | **Task** | Asynchronous derivation | Single value (memoized, cancellable) |
 | **Effect** | Side-effect sink | None (terminal) |
+| **Slot** | Stable delegation (integration layer) | Single value (swappable backing signal) |
 | **Store** | Reactive object | Keyed properties (proxy-based) |
 | **List** | Reactive array | Keyed items (stable identity) |
 | **Collection** | Reactive collection (external source or derived) | Keyed items (lazy lifecycle, item-level memoization) |
@@ -63,7 +64,7 @@ The library uses no browser-specific APIs in its core. Environment-specific beha
 | Usage | Target |
 |-------|--------|
 | Core signals only (State, Memo, Task, Effect) | Below 5 kB gzipped |
-| Full library (all 8 signal types + utilities) | Below 10 kB gzipped |
+| Full library (all 9 signal types + utilities) | Below 10 kB gzipped |
 
 The library must remain tree-shakable: importing only what you use should not pull in unrelated signal types.
 
@@ -79,7 +80,7 @@ The following are explicitly out of scope and will not be added to the library:
 - **Persistence**: No serialization, no local storage, no database integration. State enters and leaves the graph through signals; how it is stored is not this library's concern.
 - **Framework-specific bindings**: No React hooks, no Vue composables, no Angular decorators. Consuming libraries build their own integrations.
 - **DevTools protocol**: Debugging is straightforward by design — attaching an effect to any signal reveals its current value and update behavior. A dedicated debugging protocol adds complexity without proportional value.
-- **Additional signal types**: The 8 signal types are considered complete. New types would only be considered if major Web Platform changes shift the optimal way to achieve the library's existing goals.
+- **Additional signal types**: The 9 signal types are considered complete. New types would only be considered if major Web Platform changes shift the optimal way to achieve the library's existing goals.
 
 ## Stability