@zeix/cause-effect 0.17.3 → 0.18.1

package/.github/copilot-instructions.md

@@ -2,70 +2,84 @@
 
 ## Project Overview
 
-Cause & Effect is a reactive state management library for JavaScript/TypeScript that provides signals-based reactivity. The library is built with modern JavaScript/TypeScript and follows functional programming principles with a focus on performance and type safety.
+Cause & Effect is a reactive state management library for JavaScript/TypeScript that provides signals-based reactivity. The library is built on a linked graph of source and sink nodes (`src/graph.ts`) with functional factory functions for all signal types.
 
 ## Core Architecture
 
-- **Signals**: Base reactive primitives with `.get()` method
-- **State**: Mutable signals for primitive values (`new State()`)
-- **Ref**: Signal wrappers for external objects that change outside reactive system (`new Ref()`)
-- **Computed**: Derived read-only signals with memoization, reducer capabilities and async support (`new Memo()`, `new Task()`)
-- **Store**: Mutable signals for objects with reactive properties (`createStore()`)
-- **List**: Mutable signals for arrays with stable keys and reactive entries (`new List()`)
-- **Collection**: Interface for reactive collections (implemented by `DerivedCollection`)
-- **Effects**: Side effect handlers that react to signal changes (`createEffect()`)
+### Graph Engine (`src/graph.ts`)
+- **Nodes**: StateNode (source + equality), MemoNode (source + sink), TaskNode (source + sink + async), EffectNode (sink + owner)
+- **Edges**: Doubly-linked list connecting sources to sinks
+- **Operations**: `link()` creates edges, `propagate()` flags sinks dirty, `flush()` runs queued effects, `batch()` defers flushing
+- **Flags**: FLAG_CLEAN, FLAG_CHECK, FLAG_DIRTY, FLAG_RUNNING for efficient dirty checking
+
+### 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, 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
+- **Effect** (`createEffect`): Side effects that react to signal changes
 
 ## Key Files Structure
 
-- `src/classes/state.ts` - Mutable state signals
-- `src/classes/ref.ts` - Signal wrappers for external objects (DOM, Map, Set, etc.)
-- `src/classes/store.ts` - Object stores with reactive properties
-- `src/classes/list.ts` - Array stores with stable keys and reactive items
-- `src/classes/collection.ts` - Collection interface and DerivedCollection implementation
-- `src/classes/computed.ts` - Computed/derived signals
-- `src/signal.ts` - Base signal types and utilities
-- `src/effect.ts` - Effect system
-- `src/system.ts` - Core reactivity system (watchers, batching)
-- `src/util.ts` - Utility functions and constants
-- `index.ts` - Main export file
+- `src/graph.ts` - Core reactive engine (nodes, edges, link, propagate, flush, batch)
+- `src/errors.ts` - Error classes and validation functions
+- `src/nodes/state.ts` - createState, isState, State type
+- `src/nodes/sensor.ts` - createSensor, isSensor, SensorCallback type
+- `src/nodes/memo.ts` - createMemo, isMemo, Memo type
+- `src/nodes/task.ts` - createTask, isTask, Task type
+- `src/nodes/effect.ts` - createEffect, match, MatchHandlers type
+- `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/util.ts` - Utility functions and type checks
+- `index.ts` - Entry point / main export file
 
 ## Coding Conventions
 
 ### TypeScript Style
 - Use `const` for immutable values, prefer immutability
 - Generic constraints: `T extends {}` to exclude nullish values
-- Function overloads for complex type inference
+- Function overloads for complex type inference (e.g., `createCollection`, `deriveCollection`)
 - Pure functions marked with `/*#__PURE__*/` for tree-shaking
 - JSDoc comments for all public APIs
 
 ### Naming Conventions
-- Factory functions: `create*` (e.g., `createEffect`, `createStore`)
-- Type predicates: `is*` (e.g., `isSignal`, `isState`)
-- Constants: `TYPE_*` for type tags, `UPPER_CASE` for values
+- Factory functions: `create*` (e.g., `createState`, `createMemo`, `createEffect`, `createStore`, `createList`, `createCollection`, `createSensor`)
+- Type predicates: `is*` (e.g., `isState`, `isMemo`, `isStore`, `isList`, `isCollection`, `isSensor`)
+- 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
 
 ### Error Handling
-- Custom error classes in `src/errors.ts`
-- Validate inputs and throw descriptive errors
-- Use `UNSET` symbol for uninitialized/pending states
-- Support AbortSignal for cancellation in async operations
+- Error classes defined in `src/errors.ts`: CircularDependencyError, NullishSignalValueError, InvalidSignalValueError, InvalidCallbackError, RequiredOwnerError, UnsetSignalValueError
+- `validateSignalValue()` and `validateCallback()` for input validation at public API boundaries
+- Optional `guard` function in SignalOptions for runtime type checking
+- AbortSignal for cancellation in async Tasks
 
 ### Performance Patterns
-- Use `Set<Watcher>` for efficient subscription management
-- Batch updates to minimize effect re-runs
-- Memoization in computed signals
-- Shallow equality checks with `isEqual()` utility
-- Tree-shaking friendly with pure function annotations
+- Linked-list edges for O(1) link/unlink
+- Flag-based dirty checking avoids unnecessary recomputation
+- `batch()` defers `flush()` to minimize effect re-runs
+- Lazy evaluation: Memos only recompute when accessed and dirty
+- `trimSources()` removes stale edges after recomputation
+- `unlink()` calls `source.stop()` when last sink disconnects (auto-cleanup)
 
 ### API Design Principles
-- All signals have `.get()` method for value access
-- Mutable signals have `.set(value)` and `.update(fn)` methods
-- Store properties are automatically reactive signals
-- Effects receive AbortSignal for async cancellation
-- Helper functions like `resolve()`, `match()`, `diff()` for ergonomics
+- All signals created via `create*()` factory functions (no class constructors)
+- 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 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)
 
 ### Testing Patterns
-- Use Bun test runner
+- Use Bun test runner (`bun test`)
+- Test files: `test/*.next.test.ts`
 - Test reactivity chains and dependency tracking
 - Test async cancellation behavior
 - Test error conditions and edge cases
@@ -74,114 +88,160 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 
 ### Creating Signals
 ```typescript
-// State for primitives
-const count = new State(42)
-const name = new State('Alice')
-const actions = new State<'increment' | 'decrement'>('increment')
+// State for values
+const count = createState(42)
+const name = createState('Alice')
+
+// Sensor for external input
+const mouse = createSensor<{ x: number; y: number }>((set) => {
+  const h = (e: MouseEvent) => set({ x: e.clientX, y: e.clientY })
+  window.addEventListener('mousemove', h)
+  return () => window.removeEventListener('mousemove', h)
+})
 
-// Ref for external objects
-const elementRef = new Ref(document.getElementById('status'))
-const cacheRef = new Ref(new Map())
+// Sensor for mutable object observation (SKIP_EQUALITY)
+const element = createSensor<HTMLElement>((set) => {
+  const node = document.getElementById('box')!
+  set(node)
+  const obs = new MutationObserver(() => set(node))
+  obs.observe(node, { attributes: true })
+  return () => obs.disconnect()
+}, { value: node, equals: SKIP_EQUALITY })
 
-// Store for objects
+// Store for reactive objects
 const user = createStore({ name: 'Alice', age: 30 })
 
-// List with stable keys for arrays
-const items = new List(['apple', 'banana', 'cherry'])
-const users = new List([{ id: 'alice', name: 'Alice' }], user => user.id)
+// List with stable keys
+const items = createList(['apple', 'banana'], { keyConfig: 'fruit' })
+const users = createList(
+  [{ id: 'alice', name: 'Alice' }],
+  { keyConfig: u => u.id }
+)
 
-// Computed for derived values
-const doubled = new Memo(() => count.get() * 2)
+// Memo for synchronous derived values
+const doubled = createMemo(() => count.get() * 2)
 
-// Computed with reducer capabilities
-const counter = new Memo(prev => {
+// Memo with reducer capabilities
+const counter = createMemo(prev => {
   const action = actions.get()
   return action === 'increment' ? prev + 1 : prev - 1
-}, 0) // Initial value
+}, { value: 0 })
+
+// Task for async derived values
+const userData = createTask(async (prev, abort) => {
+  const id = userId.get()
+  if (!id) return prev
+  const response = await fetch(`/users/${id}`, { signal: abort })
+  return response.json()
+})
+
+// Collection for derived transformations
+const doubled = numbers.deriveCollection((n: number) => n * 2)
+const enriched = users.deriveCollection(async (user, abort) => {
+  const res = await fetch(`/api/${user.id}`, { signal: abort })
+  return { ...user, details: await res.json() }
+})
+
+// Collection for externally-driven data
+const feed = createCollection<{ id: string; text: string }>((applyChanges) => {
+  const ws = new WebSocket('/feed')
+  ws.onmessage = (e) => applyChanges(JSON.parse(e.data))
+  return () => ws.close()
+}, { keyConfig: item => item.id })
 ```
 
 ### Reactivity
 ```typescript
-// Effects run when dependencies change
-createEffect(() => {
+// Effects run when dependencies change, return Cleanup
+const dispose = createEffect(() => {
   console.log(`Count is ${count.get()}`)
 })
 
-// Async effects with cancellation
-createEffect(async (abort) => {
-  const response = await fetch('/api', { signal: abort })
-  return response.json()
+// Effects can return cleanup functions
+createEffect(() => {
+  const timer = setInterval(() => console.log(count.get()), 1000)
+  return () => clearInterval(timer)
 })
 
-// Async computed with old value access
-const userData = new Task(async (prev, abort) => {
-  if (!userId.get()) return prev // Keep previous data if no user
-  const response = await fetch(`/users/${userId.get()}`, { signal: abort })
-  return response.json()
+// match() for ergonomic signal value handling
+createEffect(() => {
+  match([userData], {
+    ok: ([data]) => updateUI(data),
+    nil: () => showLoading(),
+    err: errors => showError(errors[0].message)
+  })
 })
 ```
 
 ### Type Safety
 ```typescript
-// Use proper generic constraints
+// Generic constraints exclude nullish
 function createSignal<T extends {}>(value: T): Signal<T>
 
 // Type predicates for runtime checks
-function isSignal<T extends {}>(value: unknown): value is Signal<T>
+if (isState(value)) value.set(newValue)
+if (isMemo(value)) console.log(value.get())
+if (isStore(value)) value.name.set('Bob')
+
+// Guards for runtime type validation
+const count = createState(0, {
+  guard: (v): v is number => typeof v === 'number'
+})
 ```
 
-## Build System
-- Uses Bun as build tool and runtime
-- TypeScript compilation with declaration files
-- Minified production build
-- ES modules only (`"type": "module"`)
+## Resource Management
 
-## Store Methods and Stable Keys
+```typescript
+// 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 */ }
+})
 
-### List Methods
-- `byKey(key)` - Access signals by stable key instead of index
-- `keyAt(index)` - Get stable key at specific position
-- `indexOfKey(key)` - Get position of stable key in current order
-- `splice(start, deleteCount, ...items)` - Array-like splicing with stable key preservation
-- `sort(compareFn)` - Sort items while maintaining stable key associations
+// 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()
+  }
+})
 
-### Stable Keys Usage
-```typescript
-// Default auto-incrementing keys
-const items = new List(['a', 'b', 'c'])
-
-// String prefix keys
-const items = new List(['apple', 'banana'], 'fruit')
-// Creates keys: 'fruit0', 'fruit1'
-
-// Function-based keys
-const users = new List([
-  { id: 'user1', name: 'Alice' },
-  { id: 'user2', name: 'Bob' }
-], user => user.id) // Uses user.id as stable key
-
-// Collections derived from lists
-const userProfiles = new DerivedCollection(users, user => ({
-  ...user,
-  displayName: `${user.name} (ID: ${user.id})`
-}))
-
-// Chained collections for data pipelines
-const activeUserSummaries = users
-  .deriveCollection(user => ({ ...user, active: user.lastLogin > Date.now() - 86400000 }))
-  .deriveCollection(user => user.active ? `Active: ${user.name}` : null)
-  .filter(Boolean)
-```
+// Store/List: optional watched callback
+const store = createStore(initialValue, {
+  watched: () => {
+    // setup
+    return () => { /* cleanup */ }
+  }
+})
 
-## Resource Management
+// Scope for hierarchical cleanup
+const dispose = createScope(() => {
+  const state = createState(0)
+  createEffect(() => console.log(state.get()))
+  return () => console.log('scope disposed')
+})
+dispose() // cleans up effect and runs the returned cleanup
+```
 
-All signals support `watched` and `unwatched` callbacks in signal configuration (optional second parameter) for lazy resource allocation. Resources are only created when signals are accessed by effects and automatically cleaned up when no longer watched.
+## Build System
+- Uses Bun as build tool and runtime
+- TypeScript compilation with declaration files
+- ES modules only (`"type": "module"`)
+- Biome for code formatting and linting
 
 ## When suggesting code:
-1. Follow the established patterns for signal creation and usage
-2. Use proper TypeScript types and generics
-3. Include JSDoc for public APIs
-4. Consider performance implications
-5. Handle errors appropriately
-6. Support async operations with AbortSignal when relevant
-7. Use the established utility functions (`UNSET`, `isEqual`, etc.)
+1. Use `create*()` factory functions, not class constructors
+2. Follow the established patterns for signal creation and usage
+3. Use proper TypeScript types and generics with `T extends {}`
+4. Include JSDoc for public APIs
+5. Consider performance implications (batching, granular dependencies)
+6. Handle errors with the existing error classes and validation functions
+7. Support async operations with AbortSignal when relevant
+8. Use function overloads when callback signatures have sync/async variants

package/ARCHITECTURE.md

@@ -0,0 +1,276 @@
+# Cause & Effect v0.18 - Signal Graph Architecture
+
+This document describes the reactive signal graph engine implemented in `src/graph.ts` and the node types built on top of it in `src/nodes/`.
+
+## Overview
+
+The engine maintains a directed acyclic graph (DAG) of signal nodes connected by edges. Nodes come in two roles: **sources** produce values, **sinks** consume them. Some nodes (Memo, Task, Store, List, Collection) are both source and sink. Edges are created and destroyed automatically as computations run, ensuring the graph always reflects the true dependency structure.
+
+The design optimizes for three properties:
+
+1. **Minimal work**: Only dirty nodes recompute; unchanged values stop propagation.
+2. **Minimal memory**: Edges are stored as doubly-linked lists embedded in nodes, avoiding separate data structures.
+3. **Correctness**: Dynamic dependency tracking means the graph never has stale edges.
+
+## Core Data Structures
+
+### Edges
+
+An `Edge` connects a source to a sink. Each edge participates in two linked lists simultaneously:
+
+```
+type Edge = {
+  source: SourceNode       // the node being depended on
+  sink: SinkNode           // the node that depends on source
+  nextSource: Edge | null  // next edge in the sink's source list
+  prevSink: Edge | null    // previous edge in the source's sink list
+  nextSink: Edge | null    // next edge in the source's sink list
+}
+```
+
+Each source maintains a singly-linked list of its sinks (`sinks` → `sinksTail`), threaded through `nextSink`/`prevSink`. Each sink maintains a singly-linked list of its sources (`sources` → `sourcesTail`), threaded through `nextSource`. The `prevSink` pointer enables O(1) removal from the source's sink list.
+
+### Node Field Mixins
+
+Nodes are composed from field groups rather than using class inheritance:
+
+| Mixin | Fields | Purpose |
+|-------|--------|---------|
+| `SourceFields<T>` | `value`, `sinks`, `sinksTail`, `stop?` | Holds a value and tracks dependents |
+| `OptionsFields<T>` | `equals`, `guard?` | Equality check and type validation |
+| `SinkFields` | `fn`, `flags`, `sources`, `sourcesTail` | Holds a computation and tracks dependencies |
+| `OwnerFields` | `cleanup` | Manages disposal of child effects/scopes |
+| `AsyncFields` | `controller`, `error` | AbortController for async cancellation |
+
+### Concrete Node Types
+
+| Node | Composed From | Role |
+|------|---------------|------|
+| `StateNode<T>` | SourceFields + OptionsFields | Source only |
+| `MemoNode<T>` | SourceFields + OptionsFields + SinkFields + `error` | Source + Sink |
+| `TaskNode<T>` | SourceFields + OptionsFields + SinkFields + AsyncFields | Source + Sink |
+| `EffectNode` | SinkFields + OwnerFields | Sink only |
+| `Scope` | OwnerFields | Owner only (not in graph) |
+
+## Automatic Dependency Tracking
+
+### The `activeSink` Protocol
+
+A module-level variable `activeSink` points to the sink node currently executing its computation. When a signal's `.get()` method is called, it checks `activeSink` and, if non-null, calls `link(source, activeSink)` to establish an edge.
+
+```
+signal.get()
+  └─ if (activeSink) link(thisNode, activeSink)
+```
+
+Before a sink recomputes, the engine sets `activeSink = node`, ensuring all `.get()` calls during execution are captured. After execution, `activeSink` is restored.
+
+### Edge Creation: `link(source, sink)`
+
+`link()` creates a new edge from source to sink, appending it to both the source's sink list and the sink's source list. It includes three fast-path optimizations:
+
+1. **Same source as last**: If `sink.sourcesTail.source === source`, the edge already exists — skip.
+2. **Edge reuse during recomputation**: When `FLAG_RUNNING` is set, `link()` checks if the next existing edge in the sink's source list already points to this source. If so, it advances the `sourcesTail` pointer instead of creating a new edge. This handles the common case where dependencies are the same across recomputations.
+3. **Duplicate sink check**: If the source's last sink edge already points to this sink, skip creating a duplicate.
+
+### Edge Removal: `trimSources(node)` and `unlink(edge)`
+
+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.
+
+### Dependency Tracking Opt-Out: `untrack(fn)`
+
+`untrack()` temporarily sets `activeSink = null`, executing `fn` without creating any edges. This prevents dependency pollution when an effect creates subcomponents with their own internal signals.
+
+## Change Propagation
+
+### Flag-Based Dirty Tracking
+
+Each sink node has a `flags` field with four states:
+
+| Flag | Value | Meaning |
+|------|-------|---------|
+| `FLAG_CLEAN` | 0 | Value is up to date |
+| `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) |
+
+### The `propagate(node)` Function
+
+When a source value changes, `propagate()` walks its sink list:
+
+- **Memo/Task sinks** (have `sinks` field): Flagged `DIRTY`. Their own sinks are recursively flagged `CHECK`. If the node has an in-flight `AbortController`, it is aborted immediately.
+- **Effect sinks** (no `sinks` field): Flagged `DIRTY` and pushed onto the `queuedEffects` array for later execution.
+
+The two-level flagging (`DIRTY` for direct dependents, `CHECK` for transitive) avoids unnecessary recomputation. A `CHECK` node only recomputes if, upon inspection during `refresh()`, one of its sources turns out to have actually changed.
+
+### The `refresh(node)` Function
+
+`refresh()` is called when a sink's value is read (pull-based evaluation). It handles two cases:
+
+1. **FLAG_CHECK**: Walk the node's source list. For each source that is itself a sink (Memo/Task), recursively `refresh()` it. If at any point the node gets upgraded to `DIRTY`, stop checking.
+2. **FLAG_DIRTY**: Recompute the node by calling `recomputeMemo()`, `recomputeTask()`, or `runEffect()` depending on the node type.
+
+If `FLAG_RUNNING` is encountered, a `CircularDependencyError` is thrown.
+
+### The `setState(node, next)` Function
+
+`setState()` is the entry point for value changes on `StateNode`-based signals (State, Sensor). It:
+
+1. Checks equality — if unchanged, returns immediately.
+2. Updates `node.value`.
+3. Walks the sink list, calling `propagate()` on each dependent.
+4. If not inside a `batch()`, calls `flush()` to execute queued effects.
+
+## Effect Scheduling
+
+### Batching
+
+`batch(fn)` increments a `batchDepth` counter before executing `fn` and decrements it after. Effects are only flushed when `batchDepth` returns to 0. Batches nest — only the outermost batch triggers a flush.
+
+### The `flush()` Function
+
+`flush()` iterates over `queuedEffects`, calling `refresh()` on each effect that is still `DIRTY`. A `flushing` guard prevents re-entrant flushes. Effects that were enqueued during the flush (due to async resolution or nested state changes) are processed in the same pass, since `flush()` reads the array length dynamically.
+
+### Effect Lifecycle
+
+When an effect runs:
+
+1. `runCleanup(node)` disposes previous cleanup callbacks.
+2. `activeSink` and `activeOwner` are set to the effect node.
+3. The effect function executes; `.get()` calls create edges.
+4. If the function returns a cleanup function, it is registered via `registerCleanup()`.
+5. `activeSink` and `activeOwner` are restored.
+6. `trimSources()` removes stale edges.
+
+## Ownership and Cleanup
+
+### The `activeOwner` Protocol
+
+`activeOwner` points to the current owner node (an `EffectNode` or `Scope`). When `createEffect()` is called, the new effect's dispose function is registered on `activeOwner`. This creates a tree of ownership: disposing a parent disposes all children.
+
+### Cleanup Storage
+
+Cleanup functions are stored on the `cleanup` field of owner nodes. The field is polymorphic for efficiency:
+
+- `null` — no cleanups registered.
+- A single function — one cleanup registered.
+- An array of functions — multiple cleanups registered.
+
+`registerCleanup()` promotes from `null` → function → array as needed. `runCleanup()` executes all registered cleanups and resets the field to `null`.
+
+### `createScope(fn)`
+
+Creates an ownership scope without an effect. The scope becomes `activeOwner` during `fn` execution. Returns a `dispose` function. If the scope is created inside another owner, its disposal is automatically registered on the parent.
+
+## Signal Types
+
+### State (`src/nodes/state.ts`)
+
+**Graph node**: `StateNode<T>` (source only)
+
+A mutable value container. The simplest signal type — `get()` links and returns the value, `set()` validates, calls `setState()`, which propagates changes to dependents.
+
+`update(fn)` is sugar for `set(fn(get()))` with validation.
+
+### Sensor (`src/nodes/sensor.ts`)
+
+**Graph node**: `StateNode<T>` (source only)
+
+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 (`===` 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 `watched` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
+
+**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`)
+
+**Graph node**: `MemoNode<T>` (source + sink)
+
+A synchronous derived computation. The `fn` receives the previous value (or `undefined` on first run) and returns a new value. Dependencies are tracked automatically during execution.
+
+Memos use lazy evaluation — they only recompute when read (`get()` calls `refresh()`). If the recomputed value is equal to the previous (per the `equals` function), downstream sinks are not flagged dirty, stopping propagation. This is the key mechanism for avoiding unnecessary work.
+
+The `error` field preserves thrown errors: if `fn` throws, the error is stored and re-thrown on subsequent `get()` calls until the memo successfully recomputes.
+
+**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)
+
+An asynchronous derived computation. Like Memo but `fn` returns a `Promise` and receives an `AbortSignal`. When dependencies change while a task is in flight, the `AbortController` is aborted and a new computation starts.
+
+During dependency tracking, only the synchronous preamble of `fn` is tracked (before the first `await`). The promise resolution triggers propagation and flush asynchronously.
+
+`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)
+
+A side-effecting computation that runs immediately and re-runs when dependencies change. Effects are terminal — they have no value and no sinks. They are pushed onto the `queuedEffects` array during propagation and executed during `flush()`.
+
+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.
+
+### Store (`src/nodes/store.ts`)
+
+**Graph node**: `MemoNode<T>` (source + sink, used for structural reactivity)
+
+A reactive object where each property is its own signal. Properties are automatically wrapped: primitives become `State`, nested objects become `Store`, arrays become `List`. A `Proxy` provides direct property access (`store.name` returns the `State` signal for that property).
+
+**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.
+
+**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.
+
+**Watched lifecycle**: An optional `watched` callback in options provides lazy resource allocation, following the same pattern as Sensor — activated on first sink, cleaned up when the last sink detaches.
+
+### List (`src/nodes/list.ts`)
+
+**Graph node**: `MemoNode<T[]>` (source + sink, used for structural reactivity)
+
+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.
+
+**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()`.
+
+### Collection (`src/nodes/collection.ts`)
+
+Collection implements two creation patterns that share the same `Collection<T>` interface:
+
+#### `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(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 `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.
+
+**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.
+
+#### `deriveCollection(source, callback)` — internally derived
+
+**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.
+
+**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.
+
+**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.