@zeix/cause-effect 0.18.3 → 0.18.5

package/ARCHITECTURE.md

@@ -106,14 +106,14 @@ The first four flags (`CLEAN`/`CHECK`/`DIRTY`/`RUNNING`) are used by the core gr
 
 `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
+### The `propagate(node, newFlag?)` Function
 
-When a source value changes, `propagate()` walks its sink list:
+When a source value changes, `propagate()` walks its sink list. The `newFlag` parameter defaults to `FLAG_DIRTY` but callers may pass `FLAG_CHECK` for speculative invalidation (e.g., watched callbacks where the source value may not have actually changed).
 
-- **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.
+- **Memo/Task sinks** (have `sinks` field): Flagged with `newFlag` (typically `DIRTY`). Their own sinks are recursively flagged `CHECK`. If the node has an in-flight `AbortController`, it is aborted immediately. Short-circuits if the node already carries an equal or higher flag.
+- **Effect sinks** (no `sinks` field): Flagged with `newFlag` and pushed onto the `queuedEffects` array. An effect is only enqueued once — subsequent propagations escalate the flag (e.g., `CHECK` → `DIRTY`) without re-enqueuing. The flag is assigned (not OR'd) to clear `FLAG_RUNNING`, preserving the existing pattern where a state update inside a running effect triggers a re-run.
 
-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 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. This applies equally to memo, task, and effect nodes.
 
 ### The `refresh(node)` Function
 
@@ -141,7 +141,7 @@ If `FLAG_RUNNING` is encountered, a `CircularDependencyError` is thrown.
 
 ### 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.
+`flush()` iterates over `queuedEffects`, calling `refresh()` on each effect that is still `DIRTY` or `CHECK`. 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. Effects with only `FLAG_CHECK` enter `refresh()`, which walks their sources — if no source value actually changed, the effect is cleaned without running.
 
 ### Effect Lifecycle
 
@@ -209,7 +209,7 @@ The `error` field preserves thrown errors: if `fn` throws, the error is stored a
 
 **Reducer pattern**: The `prev` parameter enables state accumulation across recomputations without writable state.
 
-**Watched lifecycle**: An optional `watched` callback in options provides lazy external invalidation. The callback receives an `invalidate` function and is invoked on first sink attachment. Calling `invalidate()` marks the node `FLAG_DIRTY`, propagates to sinks, and flushes — triggering re-evaluation of the memo's `fn` without changing any tracked dependency. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where the memo re-derives its value in response to external events.
+**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()` calls `propagate(node)` on the memo itself, which marks it `FLAG_DIRTY` and propagates `FLAG_CHECK` to downstream sinks, then flushes. During flush, downstream effects verify the memo via `refresh()` — if the memo's `equals` function determines the recomputed value is unchanged, the effect is cleaned without running. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where a memo re-derives its value in response to external events, with the `equals` check respected at every level of the graph.
 
 ### Task (`src/nodes/task.ts`)
 
@@ -221,7 +221,7 @@ During dependency tracking, only the synchronous preamble of `fn` is tracked (be
 
 `isPending()` returns `true` while a computation is in flight. `abort()` cancels the current computation manually. Errors are preserved like Memo, but old values are retained on errors (the last successful result remains accessible).
 
-**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` marks the node dirty and triggers re-execution, which aborts any in-flight computation via the existing `AbortController` mechanism before starting a new one.
+**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` calls `propagate(node)` on the task itself, which marks it dirty, aborts any in-flight computation eagerly via the `AbortController`, and propagates `FLAG_CHECK` to downstream sinks. Effects only re-run if the task's resolved value actually changes.
 
 ### Effect (`src/nodes/effect.ts`)
 

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.18.5
+
+### Added
+
+- **`unown(fn)` — escape hatch for DOM-owned component lifecycles**: Runs a callback with `activeOwner` set to `null`, preventing any `createScope` or `createEffect` calls inside from being registered as children of the current active owner. Use this in `connectedCallback` (or any external lifecycle hook) when a component manages its own cleanup independently via `disconnectedCallback` rather than through the reactive ownership tree.
+
+### Fixed
+
+- **Scope disposal bug when `connectedCallback` fires inside a re-runnable effect**: Previously, calling `createScope` inside a reactive effect (e.g. a list sync effect) registered the scope's `dispose` on that effect's cleanup list. When the effect re-ran — for example, because a `MutationObserver` fired — it called `runCleanup`, disposing all child scopes including those belonging to already-connected custom elements. This silently removed event listeners and reactive subscriptions from components that were still live in the DOM. Wrapping the `connectedCallback` body in `unown(() => createScope(...))` detaches the scope from the effect's ownership, so effect re-runs no longer dispose it.
+
+## 0.18.4
+
+### Fixed
+
+- **Watched `invalidate()` now respects `equals` at every graph level**: Previously, calling `invalidate()` from a Memo or Task `watched` callback propagated `FLAG_DIRTY` directly to effect sinks, causing unconditional re-runs even when the recomputed value was unchanged. Now `invalidate()` delegates to `propagate(node)`, which marks the node itself `FLAG_DIRTY` and propagates `FLAG_CHECK` to downstream sinks. During flush, effects verify their sources via `refresh()` — if the memo's `equals` function determines the value is unchanged, the effect is cleaned without running. This eliminates unnecessary effect executions for watched memos with custom equality or stable return values.
+
+### Changed
+
+- **`propagate()` supports `FLAG_CHECK` for effect nodes**: The effect branch of `propagate()` now respects the `newFlag` parameter instead of unconditionally setting `FLAG_DIRTY`. Effects are enqueued only on first notification; subsequent propagations escalate the flag (e.g., `CHECK` → `DIRTY`) without re-enqueuing.
+- **`flush()` processes `FLAG_CHECK` effects**: The flush loop now calls `refresh()` on effects with either `FLAG_DIRTY` or `FLAG_CHECK`, enabling the check-sources-first path for effects.
+- **Task `invalidate()` aborts eagerly**: Task watched callbacks now abort in-flight computations immediately during `propagate()` rather than deferring to `recomputeTask()`, consistent with the normal dependency-change path.
+
 ## 0.18.3
 
 ### Added

package/CLAUDE.md

@@ -1,381 +1,41 @@
 # Claude Context for Cause & Effect
 
-## Library Overview and Philosophy
-
-Cause & Effect is a reactive state management library that implements the signals pattern for JavaScript and TypeScript applications. The library is designed around the principle of **explicit reactivity** - where dependencies are automatically tracked but relationships remain clear and predictable.
-
-### Core Philosophy
-- **Granular Reactivity**: Changes propagate only to dependent computations, minimizing unnecessary work
-- **Explicit Dependencies**: Dependencies are tracked through `.get()` calls, no hidden subscriptions
-- **Type Safety First**: Comprehensive TypeScript support with strict generic constraints (`T extends {}`)
-- **Performance Conscious**: Minimal overhead through efficient dependency tracking and batching
-
-## Mental Model for Understanding the System
+## Mental Model
 
 Think of signals as **observable cells** in a spreadsheet:
-- **State signals** are input cells for primitive values and objects
-- **Sensor signals** are read-only cells that track external input (mouse position, resize, mutable objects) and update lazily
-- **Memo signals** are formula cells that automatically recalculate when dependencies change
-- **Task signals** are async formula cells with abort semantics and pending state
-- **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
 
-### The Graph System
-The core of reactivity lies in the linked graph system (`src/graph.ts`):
-- Each source node maintains a linked list of `Edge` entries pointing to sink nodes
-- When a signal's `.get()` method is called during effect/memo/task execution, it automatically links the source to the active sink via `link()`
-- When a signal changes, it calls `propagate()` on all linked sinks, which flags them dirty
-- `flush()` processes queued effects after propagation
-- `batch()` defers flushing until the outermost batch completes
-- `trimSources()` removes stale edges after recomputation
+- **State** — input cell you write to
+- **Sensor** — read-only cell driven by an external source (mouse, resize, MutationObserver); activates lazily
+- **Memo** — formula cell; recomputes synchronously when dependencies change
+- **Task** — async formula cell; auto-cancels in-flight work when dependencies change
+- **Store** — structured row where each column is its own reactive cell
+- **List** — table with stable row IDs that survive sorting and reordering
+- **Collection** — externally-fed table (WebSocket, SSE) or a derived table via `.deriveCollection()`
+- **Slot** — a stable cell reference that delegates to a swappable backing cell
+- **Effect** — a sink that runs side effects; the only node that never has downstream dependents
 
-### Node Types in the Graph
+## Internal Node Shapes
 
 ```
-StateNode<T>  — source-only with equality + guard (State, Sensor)
-MemoNode<T>   — source + sink (Memo, Slot, Store, List, Collection)
-TaskNode<T>   — source + sink + async (Task)
+StateNode<T>  — source only (State, Sensor)
+MemoNode<T>   — source + sink (Memo, Slot, Store, List, Collection internals)
+TaskNode<T>   — source + sink + AbortController (Task)
 EffectNode    — sink + owner (Effect)
-Scope         — owner-only (createScope)
-```
-
-### Signal Hierarchy and Type System
-
-```typescript
-// Base Signal interface - all signals implement this
-interface Signal<T extends {}> {
-  get(): T
-}
-
-// State adds mutation methods
-type State<T extends {}> = {
-  get(): T
-  set(value: T): void
-  update(fn: (current: T) => T): void
-}
-
-// Memo is read-only computed
-type Memo<T extends {}> = {
-  get(): T
-}
-
-// Task adds async control
-type Task<T extends {}> = {
-  get(): T
-  isPending(): boolean
-  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[]
-  at(index: number): Signal<T> | undefined
-  byKey(key: string): Signal<T> | undefined
-  keys(): IterableIterator<string>
-  deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R>
-  deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R>
-}
-```
-
-The generic constraint `T extends {}` is crucial - it excludes `null` and `undefined` at the type level, preventing common runtime errors and making the API more predictable.
-
-### Collection Architecture
-
-**Collections** (`createCollection`): Externally-driven collections with watched lifecycle
-- Created via `createCollection(watched, options?)` — mirrors `createSensor(watched, options?)`
-- The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
-- `options.value` provides initial items (default `[]`), `options.keyConfig` configures key generation
-- Lazy activation: `watched` callback invoked on first effect access, cleanup when unwatched
-
-**Derived Collections** (`deriveCollection`): Transformed from Lists or other Collections
-- Created via `list.deriveCollection(callback)` or `collection.deriveCollection(callback)`
-- Also available as `deriveCollection(source, callback)` (internal helper, exported for advanced use)
-- Item-level memoization: sync callbacks use `createMemo`, async callbacks use `createTask`
-- Structural changes tracked via an internal `MemoNode` that reads `source.keys()`
-- Chainable for data pipelines
-
-### Store and List Architecture
-
-**Store signals** (`createStore`): Transform objects into reactive data structures
-- Each property becomes its own State signal (primitives) or nested Store (objects) via Proxy
-- Uses an internal `MemoNode` for structural reactivity (add/remove properties)
-- `diff()` computes granular changes when calling `set()`
-- Dynamic property addition/removal with `add()`/`remove()`
-
-**List signals** (`createList`): Arrays with stable keys and reactive items
-- Each item becomes a `State` signal in a `Map<string, State<T>>`
-- Uses an internal `MemoNode` for structural reactivity
-- Configurable key generation: auto-increment, string prefix, or function
-- Provides `byKey()`, `keyAt()`, `indexOfKey()` for key-based access
-- `deriveCollection()` creates derived Collections
-
-### Computed Signal Memoization Strategy
-
-Computed signals implement smart memoization:
-- **Dependency Tracking**: Automatically tracks which signals are accessed during computation via `link()`
-- **Stale Detection**: Flag-based dirty checking (CLEAN, CHECK, DIRTY) — only recalculates when dependencies actually change
-- **Async Support**: `createTask` handles Promise-based computations with automatic AbortController cancellation
-- **Error Handling**: Preserves error states and prevents cascade failures
-- **Reducer Capabilities**: Access to previous value enables state accumulation and transitions
-
-## Resource Management with Watch Callbacks
-
-Sensor, Collection, Memo (with `watched` option), and Task (with `watched` option) use a **watched callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
-
-```typescript
-// Sensor: track external input with state updates
-const mousePos = createSensor<{ x: number; y: number }>((set) => {
-  const handler = (e: MouseEvent) => set({ x: e.clientX, y: e.clientY })
-  window.addEventListener('mousemove', handler)
-  return () => window.removeEventListener('mousemove', handler)
-})
-
-// Sensor: observe a mutable external object (SKIP_EQUALITY)
-const element = createSensor<HTMLElement>((set) => {
-  const node = document.getElementById('status')!
-  set(node)
-  const observer = new MutationObserver(() => set(node))
-  observer.observe(node, { attributes: true })
-  return () => observer.disconnect() // cleanup when unwatched
-}, { value: node, equals: SKIP_EQUALITY })
-
-// Collection: receive keyed data from external source
-const feed = createCollection<{ id: string; text: string }>((applyChanges) => {
-  const es = new EventSource('/feed')
-  es.onmessage = (e) => applyChanges(JSON.parse(e.data))
-  return () => es.close()
-}, { keyConfig: item => item.id })
-```
-
-Store and List signals support an optional `watched` callback in their options:
-
-```typescript
-const user = createStore({ name: 'Alice', email: 'alice@example.com' }, {
-  watched: () => {
-    console.log('Store is now being watched')
-    const ws = new WebSocket('/updates')
-    return () => ws.close() // cleanup returned as Cleanup
-  }
-})
-```
-
-**Watch Lifecycle**:
-1. First effect accesses signal → watched callback executed
-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
-
-### When to Use Each Signal Type
-
-**State (`createState`)**:
-- Primitive values (numbers, strings, booleans)
-- Objects that you replace entirely rather than mutating properties
-- Simple toggles and flags
-
-```typescript
-const count = createState(0)
-const theme = createState<'light' | 'dark'>('light')
-```
-
-**Sensor (`createSensor`)**:
-- External input streams (mouse position, window size, media queries)
-- External mutable objects observed via MutationObserver, IntersectionObserver, etc.
-- Returns a read-only signal that activates lazily and tears down when unwatched
-- Starts undefined until first `set()` unless `options.value` is provided
-
-```typescript
-// Tracking external values (default equality)
-const windowSize = createSensor<{ w: number; h: number }>((set) => {
-  const update = () => set({ w: innerWidth, h: innerHeight })
-  update()
-  window.addEventListener('resize', update)
-  return () => window.removeEventListener('resize', update)
-})
-
-// Observing a mutable object (SKIP_EQUALITY)
-const el = 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 (`createStore`)**:
-- Objects where individual properties change independently
-- Proxy-based: access properties directly as signals
-
-```typescript
-const user = createStore({ name: 'Alice', email: 'alice@example.com' })
-user.name.set('Bob') // Only name subscribers react
-```
-
-**List (`createList`)**:
-- Arrays with stable keys and reactive items
-
-```typescript
-const todoList = createList([
-  { id: 'task1', text: 'Learn signals' }
-], { keyConfig: todo => todo.id })
-const firstTodo = todoList.byKey('task1') // Access by stable key
-```
-
-**Collection (`createCollection`)**:
-- Externally-driven keyed collections (WebSocket streams, SSE, external data feeds)
-- Mirrors `createSensor(watched, options?)` — watched callback pattern with lazy lifecycle
-- Same `Collection` interface — `.get()`, `.byKey()`, `.keys()`, `.deriveCollection()`
-
-```typescript
-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 })
-```
-
-**Derived Collection** (`.deriveCollection()`):
-- Read-only derived transformations of Lists or other Collections
-- Created via `.deriveCollection()` method on List or Collection
-
-```typescript
-const doubled = numbers.deriveCollection((value: number) => value * 2)
-
-// Async transformation
-const enriched = users.deriveCollection(async (user, abort) => {
-  const response = await fetch(`/api/${user.id}`, { signal: abort })
-  return { ...user, details: await response.json() }
-})
-
-// Chain collections for data pipelines
-const processed = todoList
-  .deriveCollection(todo => ({ ...todo, urgent: todo.priority > 8 }))
-  .deriveCollection(todo => todo.urgent ? `URGENT: ${todo.text}` : todo.text)
-```
-
-**Memo (`createMemo`)**:
-- Synchronous derived computations with memoization
-- Reducer pattern with previous value access
-- Optional `watched(invalidate)` callback for lazy external invalidation (e.g., MutationObserver)
-
-```typescript
-const doubled = createMemo(() => count.get() * 2)
-
-// Reducer pattern for state machines
-const gameState = createMemo(prev => {
-  const action = playerAction.get()
-  switch (prev) {
-    case 'menu': return action === 'start' ? 'playing' : 'menu'
-    case 'playing': return action === 'pause' ? 'paused' : 'playing'
-    default: return prev
-  }
-}, { value: 'menu' })
-
-// Accumulating values
-const runningTotal = createMemo(prev => prev + currentValue.get(), { value: 0 })
-```
-
-**Task (`createTask`)**:
-- Async computations with automatic cancellation
-- Optional `watched(invalidate)` callback for lazy external invalidation
-
-```typescript
-const userData = createTask(async (prev, abort) => {
-  const id = userId.get()
-  if (!id) return prev
-  const response = await fetch(`/users/${id}`, { signal: abort })
-  return response.json()
-})
-```
-
-**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:
-
-1. **Input Validation**: `validateSignalValue()` and `validateCallback()` with custom error classes
-2. **Async Cancellation**: AbortSignal integration prevents stale async operations
-3. **Error Propagation**: Memo and Task preserve error states and throw on `.get()`
-4. **Match Helper**: `match()` for ergonomic signal value extraction inside effects
-
-```typescript
-const apiData = createTask(async (prev, abort) => {
-  const response = await fetch('/api/data', { signal: abort })
-  if (!response.ok) throw new Error(`HTTP ${response.status}`)
-  return response.json()
-})
-
-createEffect(() => {
-  match([apiData], {
-    ok: ([data]) => updateUI(data),
-    nil: () => showLoading(),
-    err: errors => showError(errors[0].message)
-  })
-})
+Scope         — owner only (createScope)
 ```
 
-### Performance Optimization
+`activeOwner` tracks the current owner for cleanup registration. `activeSink` tracks the current sink for dependency tracking. These are separate: `untrack()` nulls `activeSink` (stops dependency edges), `unown()` nulls `activeOwner` (stops scope registration). You can read signals without tracking them, or create scopes without parenting them, independently.
 
-**Batching**: Use `batch()` for multiple updates
-```typescript
-batch(() => {
-  user.name.set('Alice')
-  user.email.set('alice@example.com')
-}) // Single effect trigger
-```
+## Non-Obvious Behaviors
 
-**Granular Dependencies**: Structure computed signals to minimize dependencies
-```typescript
-// Bad: depends on entire user object
-const display = createMemo(() => user.get().name + user.get().email)
-// Good: only depends on specific properties
-const display = createMemo(() => user.name.get() + user.email.get())
-```
+**`T extends {}` excludes `null` and `undefined` at the type level.** Every signal generic uses this constraint. Signals cannot hold nullish values — use a wrapper type or a union with a sentinel if you need to represent absence.
 
-## Common Pitfalls
+**`byKey()`, `at()`, `keyAt()`, and `indexOfKey()` do NOT create graph edges.** They are direct lookups. An effect that only calls `collection.byKey('x')?.get()` will react to value changes of key `'x'` but will *not* re-run if that key is added or removed. To track structural changes, read `get()`, `keys()`, or `length`.
 
-1. **Infinite Loops**: Don't update signals within their own computed callbacks
-2. **Memory Leaks**: Clean up effects when components unmount
-3. **Over-reactivity**: Structure data to minimize unnecessary updates
-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:
+**Conditional reads delay `watched` activation.** Dependencies are tracked only for `.get()` calls that actually execute during a given effect run. If a signal read is inside a branch that doesn't execute (e.g. the `ok` arm of `match()` while a Task is still pending), no edge is created and `watched` does not fire. Read signals eagerly before conditional logic when lifecycle activation matters:
 
 ```typescript
-// Good: watched activates immediately, errors/nil in derived are also caught
+// Good: both signals are always tracked; watched activates immediately
 createEffect(() => {
   match([task, derived], {
     ok: ([result, values]) => renderList(values, result),
@@ -383,11 +43,11 @@ createEffect(() => {
   })
 })
 
-// Bad: watched only activates after task resolves
+// Bad: derived is only tracked after task resolves
 createEffect(() => {
   match([task], {
     ok: ([result]) => {
-      const values = derived.get() // only tracked in this branch
+      const values = derived.get()
       renderList(values, result)
     },
     nil: () => showLoading(),
@@ -395,45 +55,24 @@ createEffect(() => {
 })
 ```
 
-## Advanced Patterns
+**`equals` is respected at every level of the graph, not just at the source.** When a Memo recomputes to the same value (per its `equals` function), downstream Memos and Effects receive `FLAG_CHECK` and are cleaned without running. Effects only re-execute if at least one upstream node has actually changed value. This means a custom `equals` on an intermediate Memo can suppress entire subtrees of recomputation.
 
-### Event Bus with Type Safety
-```typescript
-type Events = {
-  userLogin: { userId: number; timestamp: number }
-  userLogout: { userId: number }
-}
-
-const eventBus = createStore<Events>({
-  userLogin: undefined as unknown as Events['userLogin'],
-  userLogout: undefined as unknown as Events['userLogout'],
-})
+**`SKIP_EQUALITY` forces propagation on every update.** Use it with `createSensor` when observing a mutable object where the reference stays the same but internal state changes (e.g. a DOM element passed through a MutationObserver). Without it, `setState` would see `old === new` and suppress propagation entirely.
 
-const emit = <K extends keyof Events>(event: K, data: Events[K]) => {
-  eventBus[event].set(data)
-}
+**`watched` propagates through `.deriveCollection()` chains without restarting on mutations.** When an effect reads a derived collection, the `watched` callback on the source List/Collection activates automatically — even through multiple levels of chaining. Structural mutations (add, remove, sort) on the source do *not* tear down and restart `watched`; the watcher stays active as long as any downstream effect is subscribed. Cleanup cascades upstream only when the last subscriber disposes.
 
-const on = <K extends keyof Events>(event: K, callback: (data: Events[K]) => void) =>
-  createEffect(() => {
-    const data = eventBus[event].get()
-    if (data != null) callback(data)
-  })
-```
+**Memo and Task callbacks receive the previous value as their first argument.** This enables reducer and accumulator patterns without external state:
 
-### Data Processing Pipelines
 ```typescript
-const rawData = createList([{ id: 1, value: 10 }], { keyConfig: item => String(item.id) })
-const processed = rawData
-  .deriveCollection(item => ({ ...item, doubled: item.value * 2 }))
-  .deriveCollection(item => ({ ...item, formatted: `$${item.doubled}` }))
+const runningTotal = createMemo((prev = 0) => prev + tick.get())
+
+const gameState = createMemo((prev = 'menu') => {
+  const action = playerAction.get()
+  if (prev === 'menu' && action === 'start') return 'playing'
+  return prev
+})
 ```
 
-### Stable List Keys
-```typescript
-const playlist = createList([
-  { id: 'track1', title: 'Song A' }
-], { keyConfig: track => track.id })
+**`Slot` is a valid property descriptor.** The object returned by `createSlot()` has `get`, `set`, `configurable`, and `enumerable` — it can be passed directly to `Object.defineProperty()`. `slot.replace(nextSignal)` swaps the backing signal and invalidates all existing subscribers without them needing to re-subscribe.
 
-const firstTrack = playlist.byKey('track1') // Persists through sorting
-playlist.sort((a, b) => a.title.localeCompare(b.title))
-```
+**`unown()` is the correct fix for DOM-owned component lifecycles.** When a custom element's `connectedCallback` fires inside a re-runnable reactive effect, any `createScope` call inside it would register its `dispose` on the effect's cleanup list — causing the component's effects and listeners to be torn down the next time the parent effect re-runs. Wrapping the `connectedCallback` body in `unown(() => createScope(...))` detaches the scope from the effect's ownership entirely, leaving `disconnectedCallback` as the sole lifecycle authority.

package/OWNERSHIP_BUG.md

@@ -0,0 +1,95 @@
+# Ownership Bug: Component Scope Disposed by Parent Effect
+
+## Symptom
+
+In `module-todo`, `form-checkbox` elements wired via `checkboxes: pass(...)` lose their
+reactive effects after the initial render — `setProperty('checked')` stops updating
+`input.checked`, and the `on('change')` event listener is silently removed. Reading
+`fc.checked` (a pull) still works correctly, but reactive push is gone.
+
+## Root Cause
+
+`createScope` registers its `dispose` on `prevOwner` — the `activeOwner` at the time the
+scope is created. This is the right behavior for *hierarchical component trees* where a
+parent component logically owns its children. But custom elements have a different ownership
+model: **the DOM owns them**, via `connectedCallback` / `disconnectedCallback`.
+
+The problem arises when a custom element's `connectedCallback` fires *inside* a
+re-runnable reactive effect:
+
+1. `module-todo`'s list sync effect runs inside `flush()` with `activeOwner = listSyncEffect`.
+2. `list.append(li)` connects the `<li>`, which connects the `<form-checkbox>` inside it.
+3. `form-checkbox.connectedCallback()` calls `runEffects(ui, setup(ui))`, which calls
+   `createScope`. `prevOwner = listSyncEffect`, so `dispose` is **registered on
+   `listSyncEffect`**.
+4. Later, the `items = all('li[data-key]')` MutationObserver fires (the DOM mutation from
+   step 2 is detected) and re-queues `listSyncEffect`.
+5. `runEffect(listSyncEffect)` calls `runCleanup(listSyncEffect)`, which calls all
+   registered cleanups — including `form-checkbox`'s `dispose`.
+6. `dispose()` runs `runCleanup(fc1Scope)`, which removes the `on('change')` event
+   listener and trims the `setProperty` effect's reactive subscriptions.
+7. The `<form-checkbox>` elements are still in the DOM, but their effects are permanently
+   gone. `connectedCallback` does not re-fire on already-connected elements.
+
+The same problem recurs whenever `listSyncEffect` re-runs for any reason (e.g. a new todo
+is added), disposing the scopes of all existing `<form-checkbox>` elements.
+
+## Why `unown` Is the Correct Fix
+
+`createScope`'s "register on `prevOwner`" semantics model one ownership relationship:
+*parent reactive scope owns child*. Custom elements model a different one: *the DOM owns
+the component*. `disconnectedCallback` is the authoritative cleanup trigger, not the
+reactive graph.
+
+`unown` is the explicit handshake that says "this scope is DOM-owned". It prevents
+`createScope` from registering `dispose` on whatever reactive effect happens to be running
+when `connectedCallback` fires, while leaving `this.#cleanup` + `disconnectedCallback` as
+the sole lifecycle authority.
+
+A `createScope`-only approach (without `unown`) has two failure modes:
+
+| Scenario | Problem |
+|---|---|
+| Connects in static DOM (`activeOwner = null`) | `dispose` is discarded; effects never cleaned up on disconnect — memory leak |
+| Connects inside a re-runnable effect | Same disposal bug as described above |
+
+Per-item scopes (manually tracking a `Map<key, Cleanup>`) could also fix the disposal
+problem but require significant restructuring of the list sync effect and still need
+`unown` to prevent re-registration on each effect re-run.
+
+## Required Changes
+
+### `@zeix/cause-effect`
+
+**`src/graph.ts`** — Add `unown` next to `untrack`:
+
+```typescript
+/**
+ * Runs a callback without any active owner.
+ * Any scopes or effects created inside the callback will not be registered as
+ * children of the current active owner (e.g. a re-runnable effect). Use this
+ * when a component or resource manages its own lifecycle independently of the
+ * reactive graph.
+ *
+ * @since 0.18.5
+ */
+function unown<T>(fn: () => T): T {
+    const prev = activeOwner
+    activeOwner = null
+    try {
+        return fn()
+    } finally {
+        activeOwner = prev
+    }
+}
+```
+
+Export it from the internal graph exports and from **`index.ts`**:
+
+```typescript
+export {
+    // ...existing exports...
+    unown,
+    untrack,
+} from './src/graph'
+```