@zeix/cause-effect 0.18.2 → 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

@@ -178,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.
 
@@ -231,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)

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

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[]
@@ -297,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:

package/GUIDE.md

@@ -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.2
+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

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