@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/guide/advanced/architecture.md

@@ -0,0 +1,1234 @@
+# Architecture
+
+This document provides a deep dive into PicoFlow's internal architecture. Whether you're a curious user wanting to understand how things work under the hood, or a potential contributor looking to get oriented before diving into the source code, this guide will help you understand the core concepts, design patterns, and implementation details that make PicoFlow tick.
+
+## Why Understanding Architecture Matters
+
+Understanding PicoFlow's architecture helps you:
+
+- **Debug effectively** - Know where to look when things go wrong
+- **Optimize performance** - Understand the performance implications of different patterns
+- **Contribute confidently** - Navigate the codebase with a mental model
+- **Make better design decisions** - Use PicoFlow in ways that align with its design
+
+## Document Organization
+
+This guide progresses from high-level concepts to implementation details:
+
+1. **Architecture Overview** - The layered structure
+2. **Core Concepts** - Fundamental patterns and ideas
+3. **Layer Deep Dives** - Detailed exploration of each layer
+4. **Design Patterns** - Key patterns used throughout
+5. **Data Flows** - How data moves through the system
+6. **For Contributors** - Practical guidance for contributing
+
+## Architecture Overview
+
+PicoFlow follows a **layered architecture** with clear separation of concerns. Each layer has a specific responsibility and builds upon the layer below it.
+
+```mermaid
+graph TB
+    API["Public API Layer<br/>(src/api/)<br/>────────────────<br/>Factory functions & Interfaces<br/>state(), derivation(), etc."]
+    Nodes["Nodes Layer<br/>(src/nodes/)<br/>────────────────<br/>Concrete implementations<br/>ValueSyncNode, EffectNode, etc."]
+    Base["Base Layer<br/>(src/base/)<br/>────────────────<br/>Abstract classes & patterns<br/>Observable, Observer, Node"]
+    Schedulers["Schedulers Layer<br/>(src/schedulers/)<br/>────────────────<br/>Computation lifecycle<br/>SyncScheduler, AsyncScheduler"]
+    
+    API --> Nodes
+    Nodes --> Base
+    Nodes --> Schedulers
+    Base --> Schedulers
+    
+    style API fill:#e1f5ff
+    style Nodes fill:#fff4e1
+    style Base fill:#ffe1f5
+    style Schedulers fill:#e1ffe1
+```
+
+### Layer Responsibilities
+
+**Public API Layer** (`src/api/`)
+- Factory functions that users call (`state()`, `derivation()`, etc.)
+- TypeScript interfaces that define contracts (`FlowState`, `FlowObservable`)
+- Hides implementation details from users
+- Provides a stable, semantic API
+
+**Nodes Layer** (`src/nodes/`)
+- Concrete implementations of reactive primitives
+- Each primitive type has its own class (`ValueSyncNode`, `EffectNode`, etc.)
+- Manages the reactive value lifecycle
+- Coordinates between Base and Schedulers
+
+**Base Layer** (`src/base/`)
+- Abstract classes implementing core patterns
+- Observable/Observer pattern implementation
+- Dependency graph management
+- Execution batching and ordering
+
+**Schedulers Layer** (`src/schedulers/`)
+- Manages computation execution lifecycle
+- Handles synchronous vs asynchronous execution
+- Prevents race conditions with iteration tracking
+- Provides consistent promise settling behavior
+
+## Core Concepts
+
+### The Observer Pattern
+
+PicoFlow is built on the **Observer Pattern**, where objects (observables) can notify other objects (observers) when their state changes.
+
+```mermaid
+graph LR
+    Observable["Observable<br/>(can be watched)"]
+    Observer1["Observer 1<br/>(watches changes)"]
+    Observer2["Observer 2<br/>(watches changes)"]
+    Observer3["Observer 3<br/>(watches changes)"]
+    
+    Observable -->|notifies| Observer1
+    Observable -->|notifies| Observer2
+    Observable -->|notifies| Observer3
+    
+    style Observable fill:#ffeb99
+    style Observer1 fill:#99e1ff
+    style Observer2 fill:#99e1ff
+    style Observer3 fill:#99e1ff
+```
+
+**Key insight**: In PicoFlow, most primitives are *both* observable AND observer. A derivation observes a state (it's an observer), but can itself be observed by an effect (it's an observable).
+
+```typescript
+// $count is an Observable
+const $count = state(0)
+
+// $doubled is both:
+// - An Observer (observes $count)
+// - An Observable (can be observed by others)
+const $doubled = derivation((t) => $count.get(t) * 2)
+
+// effect is an Observer
+const fx = subscribe(
+  (t) => $doubled.get(t),
+  (value) => console.log(value)
+)
+```
+
+### Dependency Graph
+
+Primitives form a **directed acyclic graph (DAG)** of dependencies:
+
+```mermaid
+graph TB
+    State1["state(0)<br/>Observable"]
+    State2["state(1)<br/>Observable"]
+    Deriv["derivation()<br/>Observer + Observable"]
+    Effect["effect()<br/>Observer"]
+    
+    State1 --> Deriv
+    State2 --> Deriv
+    Deriv --> Effect
+    
+    style State1 fill:#ffe1e1
+    style State2 fill:#ffe1e1
+    style Deriv fill:#e1ffe1
+    style Effect fill:#e1e1ff
+```
+
+When a state changes:
+1. It notifies its dependents (the derivation)
+2. The derivation recomputes and notifies its dependents (the effect)
+3. The effect re-executes
+
+This creates a **push-based** reactive system where changes automatically propagate through the graph.
+
+### Reactive Tracking
+
+How does PicoFlow know which primitives depend on which? Through **automatic dependency tracking**.
+
+When you call `get(tracker)` on a primitive, it registers itself as a dependency:
+
+```typescript
+const $count = state(0)
+
+// When this derivation executes...
+const $doubled = derivation((tracker) => {
+  // ...this get() call automatically registers $count as a dependency
+  return $count.get(tracker) * 2
+})
+```
+
+**The FlowTracker** is the key. It's passed to all computation functions and used to record dependencies:
+
+```mermaid
+sequenceDiagram
+    participant D as Derivation
+    participant T as Tracker
+    participant S as State
+    
+    D->>D: execute()
+    D->>S: get(tracker)
+    S->>T: registerDependency(this)
+    T->>T: Add state to dependencies
+    S->>D: Return value
+```
+
+This automatic tracking means you don't manually wire up subscriptions - just read values and PicoFlow handles the rest.
+
+## Base Layer (src/base/)
+
+The base layer provides the fundamental abstractions that all reactive primitives build upon.
+
+### Disposable
+
+The simplest building block - explicit resource management:
+
+```typescript
+abstract class Disposable {
+  protected _disposed = false
+  
+  get disposed(): boolean {
+    return this._disposed
+  }
+  
+  dispose(): void {
+    if (this._disposed) throw new Error("Already disposed")
+    this._disposed = true
+  }
+}
+```
+
+**Why this matters**: Every PicoFlow primitive is disposable. This prevents memory leaks by allowing explicit cleanup of subscriptions and resources.
+
+### Observable
+
+Manages a list of dependents and notifies them of changes:
+
+```typescript
+abstract class Observable<T> extends Disposable {
+  private _dependents = new Set<IObserver>()
+  
+  registerDependent(dependent: IObserver): void {
+    this._dependents.add(dependent)
+  }
+  
+  notifyDependents(): void {
+    this._dependents.forEach(dep => dep.notify())
+  }
+  
+  watch(tracker: FlowTracker): void {
+    (tracker as IObserver).registerDependency(this)
+  }
+}
+```
+
+**Key methods**:
+- `watch()` - Register this observable as a dependency of a tracker
+- `trigger()` - Manually notify all dependents
+- `notifyDependents()` - Internal method to propagate changes
+
+### Observer
+
+Manages a list of dependencies and reacts to changes:
+
+```typescript
+abstract class Observer extends Disposable {
+  private _dependencies = new Set<IObservable<unknown>>()
+  
+  registerDependency(dependency: IObservable<unknown>): void {
+    this._dependencies.add(dependency)
+    dependency.registerDependent(this)
+  }
+  
+  clearDependencies(): void {
+    this._dependencies.forEach(dep => 
+      dep.unregisterDependent(this)
+    )
+    this._dependencies.clear()
+  }
+  
+  abstract notify(): void
+  abstract execute(): void
+}
+```
+
+**Key methods**:
+- `registerDependency()` - Add a new dependency
+- `clearDependencies()` - Clear all dependencies (before recomputing)
+- `notify()` - Called when a dependency changes
+- `execute()` - Run the observer's computation
+
+### Node
+
+The `Node` class combines Observable and Observer, creating primitives that can both watch others and be watched:
+
+```typescript
+abstract class Node<T> extends Disposable 
+  implements IObservable<T>, IObserver {
+  
+  private _dependencies = new Set<IObservable<unknown>>()
+  private _dependents = new Set<IObserver>()
+  
+  // Observable behavior
+  registerDependent(dependent: IObserver): void { /*...*/ }
+  notifyDependents(): void { /*...*/ }
+  
+  // Observer behavior  
+  registerDependency(dependency: IObservable<unknown>): void { /*...*/ }
+  notify(): void {
+    if (this.status === "dirty") return
+    this.status = "dirty"
+    this.notifyDependents()
+  }
+  
+  abstract execute(): void
+  abstract subscribe(...): () => void
+}
+```
+
+This dual nature is what enables chaining: state → derivation → derivation → effect.
+
+### ExecutionStack
+
+The `ExecutionStack` is a global singleton that batches reactive updates to prevent unnecessary cascading executions:
+
+```typescript
+class ExecutionStack {
+  private static _pendingQueue: IObserver[] = []
+  private static _effectQueue: IObserver[] = []
+  private static _executionScheduled?: Promise<void>
+  
+  static pushPending(node: IObserver): void {
+    this._scheduleExecution()
+    this._pendingQueue.push(node)
+  }
+  
+  static pushEffect(effect: IObserver): void {
+    this._scheduleExecution()
+    this._effectQueue.push(effect)
+  }
+  
+  private static _execute(): void {
+    // First, resolve all pending computations
+    this._pendingQueue.forEach(node => node.execute())
+    this._pendingQueue.length = 0
+    
+    // Then, run effects
+    this._effectQueue.forEach(effect => effect.execute())
+    this._effectQueue.length = 0
+  }
+}
+```
+
+**Why two queues?**
+- **Pending queue**: For value computations (derivations) that other things depend on
+- **Effect queue**: For side effects that don't produce values
+
+This ordering ensures that all values are computed before any effects run, preventing effects from running with stale data.
+
+**Async scheduling**: Executions are batched with `setTimeout(..., 0)` to:
+- Allow the current call stack to complete
+- Batch multiple synchronous changes into one execution
+- Prevent stack overflow from deep reactive chains
+
+## Nodes Layer (src/nodes/)
+
+The nodes layer contains concrete implementations of reactive primitives.
+
+### ValueNode
+
+The abstract `ValueNode` is the foundation for all value-holding primitives (state, derivation, constant, etc.):
+
+```typescript
+abstract class ValueNode<T> extends Node<T> {
+  protected abstract _scheduler: Scheduler
+  protected _value?: NotPromise<T>
+  protected _error?: unknown
+  protected _status: ObservableStatus = "resolved"
+  
+  get(tracker: FlowTracker): T {
+    this.watch(tracker)
+    
+    switch (this.status) {
+      case "resolved": return this._value as T
+      case "error": throw this._error
+      case "pending": throw new PendingError(this._scheduler.settled)
+      case "dirty": 
+        this.execute()
+        // Check status again after execution
+        // ...
+    }
+  }
+  
+  async pick(): Promise<T> {
+    switch (this.status) {
+      case "resolved": return this._value as T
+      case "pending": 
+        await this._scheduler.settled
+        return this._value as T
+      case "dirty":
+        this.execute()
+        // ...
+    }
+  }
+}
+```
+
+**Value states**:
+- `resolved` - Has a computed value, ready to use
+- `pending` - Async computation in progress
+- `error` - Computation failed
+- `dirty` - Needs recomputation (dependency changed)
+
+**Two access methods**:
+- `get(tracker)` - Reactive read that registers a dependency
+- `pick()` - Non-reactive async read
+
+### ValueSyncNode
+
+Handles synchronous computations:
+
+```typescript
+class ValueSyncNode<T> extends ValueNode<T> {
+  protected _scheduler: SyncScheduler<T>
+  private _compute: () => T
+  
+  constructor(valueOrCompute: T | ComputeFunction<T>) {
+    super()
+    
+    if (typeof valueOrCompute === "function") {
+      this._compute = () => valueOrCompute(this, this._value)
+    } else {
+      this._compute = () => valueOrCompute
+    }
+    
+    this._scheduler = new SyncScheduler(
+      () => this._compute(),
+      (value) => this._onResolve(value),
+      (error) => this._onReject(error)
+    )
+  }
+  
+  set(value: T): void {
+    this._scheduler.overwrite(value)
+    this.notifyDependents()
+  }
+  
+  refresh(): void {
+    this.execute()
+    this.notifyDependents()
+  }
+}
+```
+
+Used by: `state()`, `constant()`, `derivation()`, `writableDerivation()`
+
+### ValueAsyncNode
+
+Handles asynchronous computations with promises:
+
+```typescript
+class ValueAsyncNode<T> extends ValueNode<T> {
+  protected _scheduler: AsyncScheduler<T>
+  private _compute: () => Promise<T>
+  
+  constructor(promiseOrCompute: Promise<T> | ComputeFunctionAsync<T>) {
+    super()
+    
+    if (typeof promiseOrCompute === "function") {
+      this._compute = () => promiseOrCompute(this, this._value)
+    } else {
+      this._compute = () => promiseOrCompute
+    }
+    
+    this._scheduler = new AsyncScheduler(
+      () => this._compute(),
+      (value) => {
+        this._onResolve(value)
+        this.notifyDependents() // Async: notify after resolution
+      },
+      (error) => {
+        this._onReject(error)
+        this.notifyDependents()
+      }
+    )
+  }
+  
+  set(promise: Promise<T>): void {
+    this._scheduler.overwrite(promise)
+    this.notifyDependents() // Immediately notify (status becomes pending)
+  }
+}
+```
+
+**Key difference from sync**: Async nodes notify dependents twice:
+1. Immediately when computation starts (status becomes "pending")
+2. Again when computation completes (status becomes "resolved" or "error")
+
+Used by: `stateAsync()`, `constantAsync()`, `derivationAsync()`, `writableDerivationAsync()`
+
+### EffectNode
+
+Effects are observers that execute side effects but don't produce values:
+
+```typescript
+class EffectNode<T> extends Observer {
+  private _data: FlowDataTracker<T>
+  private _onData: FlowOnDataListener<T>
+  private _onError?: FlowOnErrorListener
+  private _onPending?: FlowOnPendingListener
+  
+  constructor(
+    data: FlowDataTracker<T>,
+    onData: FlowOnDataListener<T>,
+    onError?: FlowOnErrorListener,
+    onPending?: FlowOnPendingListener
+  ) {
+    super()
+    this._data = data
+    this._onData = onData
+    this._onError = onError
+    this._onPending = onPending
+    this.execute() // Run immediately
+  }
+  
+  execute(): void {
+    try {
+      this.clearDependencies() // Clear old dependencies
+      const data = this._data(this) // Track new dependencies
+      this._onData(data)
+    } catch (error) {
+      if (error instanceof PendingError) {
+        this._onPending?.()
+      } else {
+        if (this._onError) {
+          this._onError(error)
+        } else {
+          throw error // Re-throw if no error handler
+        }
+      }
+    }
+  }
+  
+  notify(): void {
+    ExecutionStack.pushEffect(this)
+  }
+}
+```
+
+Used by: `subscribe()` (the public API for effects)
+
+### SignalNode
+
+Signals are events without values:
+
+```typescript
+class SignalNode extends Observable<void> {
+  subscribe(
+    onTrigger: FlowOnDataListener<void>,
+    onError?: FlowOnErrorListener,
+    onPending?: FlowOnPendingListener
+  ): () => void {
+    const effect = new EffectNode(
+      (t) => this.watch(t),
+      onTrigger,
+      onError,
+      onPending
+    )
+    return () => effect.dispose()
+  }
+}
+```
+
+Signals are useful for:
+- User actions (button clicks, form submissions)
+- Timer events
+- Custom events that don't carry data
+
+### Collections (ArrayNode, MapNode)
+
+Collections provide fine-grained reactivity with mutation tracking:
+
+```typescript
+class ArrayNode<T> extends ValueSyncNode<T[]> {
+  $lastAction: ValueSyncNode<FlowArrayAction<T>>
+  
+  push(item: T): void {
+    this._value.push(item)
+    this.notifyDependents()
+    this.$lastAction.set({ 
+      type: "push", 
+      addedItem: item 
+    })
+  }
+  
+  // Similar for pop, shift, unshift, splice, etc.
+}
+```
+
+The `$lastAction` primitive allows you to react specifically to certain mutation types:
+
+```typescript
+const $todos = array<Todo>([])
+
+// React to any change
+subscribe(
+  (t) => $todos.get(t),
+  (todos) => console.log("Todos changed", todos)
+)
+
+// React only to additions
+subscribe(
+  (t) => {
+    const action = $todos.$lastAction.get(t)
+    if (action.type === "push") return action.addedItem
+    throw new PendingError(Promise.resolve())
+  },
+  (item) => console.log("Todo added", item)
+)
+```
+
+## Schedulers Layer (src/schedulers/)
+
+Schedulers manage the lifecycle of computations, handling both synchronous and asynchronous execution.
+
+### Why Schedulers?
+
+Schedulers solve several problems:
+
+1. **Lifecycle management** - Track whether a computation is pending, resolved, or errored
+2. **Async/sync separation** - Different execution strategies for sync vs async
+3. **Race conditions** - Prevent stale results from async operations
+4. **Promise settling** - Provide consistent `settled` promise for awaiting completion
+
+### Scheduler Interface
+
+All schedulers implement this contract:
+
+```typescript
+interface Scheduler {
+  compute(): void          // Start/restart computation
+  dispose(): void          // Clean up resources
+  settled: Promise<void>   // Promise that resolves when computation settles
+}
+```
+
+### SyncScheduler & SyncResolver
+
+For synchronous computations:
+
+```mermaid
+sequenceDiagram
+    participant N as Node
+    participant SS as SyncScheduler
+    participant SR as SyncResolver
+    
+    N->>SS: compute()
+    SS->>SR: compute()
+    SR->>SR: _compute()
+    alt Success
+        SR->>SS: onResolve(value)
+        SS->>N: callback with value
+    else Error
+        SR->>SS: onReject(error)
+        SS->>N: callback with error
+    end
+    SS->>SS: settled.resolve()
+```
+
+**SyncResolver iteration tracking**:
+
+```typescript
+class SyncResolver<T> {
+  private _iteration = 0
+  
+  compute(): void {
+    this._iteration++
+    const currentIteration = this._iteration
+    
+    try {
+      const value = this._compute()
+      // Only use result if no newer computation started
+      if (this._iteration === currentIteration) {
+        this._onValue(value)
+      }
+    } catch (error) {
+      if (this._iteration === currentIteration) {
+        this._onError(error)
+      }
+    }
+  }
+}
+```
+
+This prevents race conditions if `compute()` is called multiple times rapidly.
+
+### AsyncScheduler & AsyncResolver
+
+For asynchronous computations:
+
+```mermaid
+sequenceDiagram
+    participant N as Node
+    participant AS as AsyncScheduler
+    participant AR as AsyncResolver
+    
+    N->>AS: compute()
+    AS->>AR: compute()
+    AR->>AR: _compute() (returns Promise)
+    AR-->>AS: Promise pending
+    
+    Note over AR: Async work happening...
+    
+    AR->>AS: Promise resolves
+    AS->>N: onResolve(value)
+    AS->>AS: settled.resolve()
+```
+
+**AsyncResolver race condition prevention**:
+
+```typescript
+class AsyncResolver<T> {
+  private _iteration = 0
+  
+  compute(): void {
+    this._iteration++
+    const currentIteration = this._iteration
+    
+    this._compute()
+      .then(value => {
+        // Only use result if no newer computation started
+        if (this._iteration === currentIteration && !this._aborted) {
+          this._computed.resolve(value)
+        }
+      })
+      .catch(error => {
+        if (this._iteration === currentIteration && !this._aborted) {
+          this._computed.reject(error)
+        }
+      })
+  }
+}
+```
+
+If a new computation starts while an async operation is in flight, the old result is discarded.
+
+### PendingError
+
+`PendingError` is a special error type used to propagate pending states:
+
+```typescript
+class PendingError extends Error {
+  readonly pendingPromise: Promise<unknown>
+  
+  constructor(promise: Promise<unknown>) {
+    super("[PicoFlow] PendingResolver pending")
+    this.pendingPromise = promise
+  }
+}
+```
+
+**How it's used**:
+
+```typescript
+const $user = stateAsync(fetchUser()) // Async state
+
+const $userName = derivation((t) => {
+  const user = $user.get(t) // Throws PendingError while loading
+  return user.name
+})
+
+subscribe(
+  (t) => $userName.get(t),
+  (name) => console.log("Name:", name),
+  (error) => console.error("Error:", error),
+  () => console.log("Loading...") // Called when PendingError is caught
+)
+```
+
+When `$user` is pending, `$user.get()` throws a `PendingError`. This propagates up, the effect catches it, and calls the `onPending` callback.
+
+## Public API Layer (src/api/)
+
+The API layer provides the user-facing interface to PicoFlow.
+
+### Factory Pattern
+
+Users never instantiate node classes directly. Instead, they use factory functions:
+
+```typescript
+// In src/api/nodes/sync/flowState.ts
+export function state<T>(value: T): FlowState<T> {
+  return new ValueSyncNode(value)
+}
+
+// In src/api/nodes/sync/flowDerivation.ts
+export function derivation<T>(
+  compute: DerivationFunction<T>
+): FlowDerivation<T> {
+  return new ValueSyncNode(compute)
+}
+```
+
+**Benefits**:
+- **Encapsulation** - Users don't need to know about implementation classes
+- **Flexibility** - We can change implementations without breaking the API
+- **Semantic naming** - `state()` is clearer than `new ValueSyncNode()`
+- **Type safety** - Return types are specific interfaces, not implementation classes
+
+### Interface Design
+
+Public interfaces define contracts, not implementations:
+
+```typescript
+// Public interface
+export interface FlowState<T> extends FlowValue<T> {
+  set(value: T): void
+  set(updater: UpdateFunction<T>): void
+}
+
+// Users interact with FlowState interface
+// Implementation (ValueSyncNode) is hidden
+const $count: FlowState<number> = state(0)
+```
+
+This separation allows:
+- Documentation to focus on contracts, not implementations
+- Implementation changes without API changes
+- Clear separation of public vs internal
+
+### Type Hierarchy
+
+```mermaid
+graph TB
+    FlowDisposable["FlowDisposable<br/>disposed, dispose()"]
+    FlowSubscribable["FlowSubscribable<br/>subscribe()"]
+    FlowObservable["FlowObservable<br/>watch(), trigger()"]
+    FlowTracker["FlowTracker<br/>(for dependency tracking)"]
+    FlowValue["FlowValue<br/>get(), pick()"]
+    
+    FlowState["FlowState<br/>set()"]
+    FlowDerivation["FlowDerivation<br/>refresh()"]
+    FlowConstant["FlowConstant<br/>(no mutations)"]
+    
+    FlowDisposable --> FlowObservable
+    FlowSubscribable --> FlowObservable
+    FlowTracker --> FlowDisposable
+    FlowObservable --> FlowValue
+    
+    FlowValue --> FlowState
+    FlowValue --> FlowDerivation
+    FlowValue --> FlowConstant
+    
+    style FlowDisposable fill:#ffe1e1
+    style FlowObservable fill:#e1ffe1
+    style FlowValue fill:#e1e1ff
+    style FlowState fill:#fff4e1
+```
+
+This hierarchy expresses capabilities:
+- All primitives are **Disposable**
+- All primitives are **Subscribable** (can create effects)
+- All primitives are **Observable** (can be watched)
+- Value primitives add **get/pick** methods
+- Specific types add their own methods (set, refresh, etc.)
+
+## Key Design Patterns
+
+### Factory Pattern
+
+**Intent**: Provide a simple creation interface while hiding complex construction logic.
+
+**Implementation**:
+```typescript
+// Factory function (public API)
+export function state<T>(value: T): FlowState<T> {
+  return new ValueSyncNode(value)
+}
+
+// Complex internal class (hidden from users)
+class ValueSyncNode<T> extends ValueNode<T> {
+  // Complex internal logic...
+}
+```
+
+**Benefits**: Semantic naming, encapsulation, flexibility to change implementations.
+
+### Strategy Pattern
+
+**Intent**: Define a family of algorithms (sync vs async execution) and make them interchangeable.
+
+**Implementation**:
+```typescript
+// Strategy interface
+interface Scheduler {
+  compute(): void
+  dispose(): void
+  settled: Promise<void>
+}
+
+// Concrete strategies
+class SyncScheduler implements Scheduler { /* sync logic */ }
+class AsyncScheduler implements Scheduler { /* async logic */ }
+
+// Context uses the strategy
+class ValueNode {
+  protected abstract _scheduler: Scheduler // Can be either strategy
+}
+```
+
+**Benefits**: Separate sync/async concerns, easy to add new execution strategies.
+
+### Observer Pattern
+
+**Intent**: Define a one-to-many dependency where changes in one object notify all dependents.
+
+**Implementation**:
+```typescript
+class Observable {
+  private _dependents = new Set<IObserver>()
+  
+  notifyDependents(): void {
+    this._dependents.forEach(dep => dep.notify())
+  }
+}
+
+class Observer {
+  notify(): void {
+    // React to change
+  }
+}
+```
+
+**Benefits**: Decoupling, automatic propagation, dynamic subscription.
+
+### Disposable Pattern
+
+**Intent**: Explicit resource management to prevent memory leaks.
+
+**Implementation**:
+```typescript
+class Disposable {
+  protected _disposed = false
+  
+  dispose(): void {
+    if (this._disposed) throw new Error("Already disposed")
+    // Clean up resources
+    this._disposed = true
+  }
+}
+```
+
+**Benefits**: Explicit cleanup, prevents memory leaks, clear resource ownership.
+
+## Data Flow Examples
+
+### Creating a State
+
+```mermaid
+sequenceDiagram
+    participant U as User Code
+    participant API as state()
+    participant VSN as ValueSyncNode
+    participant SS as SyncScheduler
+    participant SR as SyncResolver
+    
+    U->>API: state(0)
+    API->>VSN: new ValueSyncNode(0)
+    VSN->>SS: new SyncScheduler(compute, onResolve, onReject)
+    SS->>SR: new SyncResolver(compute, onResolve, onReject)
+    VSN->>VSN: status = "dirty"
+    Note over VSN: Lazy - won't compute until accessed
+    API->>U: return VSN (as FlowState)
+```
+
+### Reactive Read with Tracking
+
+```mermaid
+sequenceDiagram
+    participant D as Derivation
+    participant S as State
+    
+    Note over D: Creating derivation
+    D->>D: new ValueSyncNode(compute)
+    
+    Note over D: First access triggers execution
+    D->>D: get(tracker)
+    D->>D: execute()
+    D->>S: get(tracker)
+    S->>D: registerDependency(this)
+    Note over D,S: Dependency registered!
+    S->>D: return value
+    D->>D: compute result
+    D->>D: status = "resolved"
+```
+
+### Update Propagation
+
+```mermaid
+sequenceDiagram
+    participant U as User Code
+    participant S as State
+    participant D as Derivation
+    participant E as Effect
+    participant ES as ExecutionStack
+    
+    U->>S: set(1)
+    S->>S: _value = 1
+    S->>D: notifyDependents()
+    D->>D: notify()
+    D->>D: status = "dirty"
+    D->>E: notifyDependents()
+    E->>E: notify()
+    E->>ES: pushEffect(this)
+    ES->>ES: scheduleExecution()
+    
+    Note over ES: setTimeout completes
+    
+    ES->>E: execute()
+    E->>E: clearDependencies()
+    E->>D: get(tracker)
+    D->>D: status is "dirty", recompute
+    D->>S: get(tracker)
+    S->>D: return new value
+    D->>E: return computed value
+    E->>E: call onData callback
+```
+
+### Async Computation Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User Code
+    participant VAN as ValueAsyncNode
+    participant AS as AsyncScheduler
+    participant AR as AsyncResolver
+    
+    U->>VAN: stateAsync(fetchUser())
+    VAN->>AS: new AsyncScheduler()
+    AS->>AR: new AsyncResolver()
+    
+    Note over VAN: First access
+    U->>VAN: get(tracker)
+    VAN->>VAN: status is "dirty"
+    VAN->>VAN: execute()
+    VAN->>AS: compute()
+    AS->>AR: compute()
+    AR->>AR: _compute() returns Promise
+    VAN->>VAN: status = "pending"
+    VAN->>U: throw PendingError
+    
+    Note over AR: Async operation completes
+    
+    AR->>AS: Promise resolves
+    AS->>VAN: onResolve(value)
+    VAN->>VAN: status = "resolved"
+    VAN->>VAN: notifyDependents()
+    
+    Note over VAN: Dependents re-execute
+    Note over VAN: Next get() returns value immediately
+```
+
+## Performance Considerations
+
+### Batching with ExecutionStack
+
+Multiple synchronous state changes are batched into a single update cycle:
+
+```typescript
+const $a = state(0)
+const $b = state(0)
+
+const $sum = derivation((t) => $a.get(t) + $b.get(t))
+
+subscribe((t) => $sum.get(t), (sum) => console.log(sum))
+
+// These changes are batched
+$a.set(1) // Doesn't immediately trigger effect
+$b.set(2) // Doesn't immediately trigger effect
+// Effect runs once after current call stack completes
+// Output: 3 (not 1, then 3)
+```
+
+**Performance benefit**: O(1) updates regardless of number of changes, prevents redundant computations.
+
+### Lazy Evaluation
+
+Primitives don't compute until accessed:
+
+```typescript
+const $expensive = derivation((t) => {
+  // This only runs when something actually uses $expensive
+  return expensiveComputation()
+})
+
+// No computation yet...
+// Still no computation...
+
+// Now it computes
+subscribe((t) => $expensive.get(t), console.log)
+```
+
+**Performance benefit**: Unused primitives have zero overhead.
+
+### Memoization
+
+Computed values are cached until dependencies change:
+
+```typescript
+const $count = state(0)
+const $squared = derivation((t) => {
+  console.log("Computing...")
+  return $count.get(t) ** 2
+})
+
+$squared.get(tracker) // "Computing..." → returns 0
+$squared.get(tracker) // Uses cached value → returns 0 (no log)
+$squared.get(tracker) // Uses cached value → returns 0 (no log)
+
+$count.set(1)
+$squared.get(tracker) // "Computing..." → returns 1 (recomputed)
+```
+
+**Performance benefit**: Expensive computations only run when necessary.
+
+### Dirty Checking
+
+Changes short-circuit if the value hasn't actually changed:
+
+```typescript
+const $count = state(0)
+const $effect = subscribe(
+  (t) => $count.get(t),
+  (value) => console.log(value)
+)
+
+$count.set(0) // Same value - effect doesn't run
+$count.set(1) // Different value - effect runs
+```
+
+**Performance benefit**: Prevents unnecessary downstream updates.
+
+## For Contributors
+
+### Adding a New Primitive
+
+To add a new reactive primitive:
+
+1. **Decide on the base class**:
+   - Extends `ValueNode` if it holds a value
+   - Extends `Observer` if it's an effect-like primitive
+   - Extends `Node` if it needs custom observable/observer behavior
+
+2. **Implement the node class** in `src/nodes/`:
+   ```typescript
+   class MyNewNode extends ValueNode<T> {
+     protected _scheduler: SyncScheduler<T>
+     
+     constructor(/* params */) {
+       super()
+       // Initialize scheduler
+       this._scheduler = new SyncScheduler(/* ... */)
+     }
+     
+     execute(): void {
+       // Computation logic
+     }
+   }
+   ```
+
+3. **Create public API** in `src/api/`:
+   ```typescript
+   export interface FlowMyNew<T> extends FlowValue<T> {
+     // Add any specific methods
+   }
+   
+   export function myNew<T>(/* params */): FlowMyNew<T> {
+     return new MyNewNode(/* params */)
+   }
+   ```
+
+4. **Write tests** in `test/`:
+   ```typescript
+   describe("myNew", () => {
+     it("should work correctly", () => {
+       const $val = myNew(/* ... */)
+       // Test behavior
+     })
+   })
+   ```
+
+### Code Conventions
+
+**@internal vs @public tags**:
+- Use `@public` on API elements (in `src/api/`)
+- Use `@internal` on implementation elements (in `src/base/`, `src/nodes/`, `src/schedulers/`)
+
+**Naming conventions**:
+- Classes: PascalCase (`ValueSyncNode`, `AsyncScheduler`)
+- Functions: camelCase (`state`, `derivation`)
+- Private fields: underscore prefix (`_value`, `_dependencies`)
+- Public interfaces: Flow prefix (`FlowState`, `FlowObservable`)
+
+**Error handling**:
+- Throw errors for programmer mistakes (wrong usage)
+- Use PendingError for async pending states
+- Provide onError callbacks for runtime errors
+
+### Testing Structure
+
+Tests are organized by concern:
+
+```
+test/
+├── base/               # Tests for base classes
+├── converters/         # Tests for integrations
+├── reactivity/         # Tests for reactive behavior
+│   └── nodes/         # Tests for specific node types
+└── vitest.d.ts        # Type definitions
+```
+
+Run tests:
+```bash
+pnpm test              # Run all tests
+pnpm test:watch        # Watch mode
+pnpm test:coverage     # With coverage
+```
+
+## Glossary
+
+**Disposable** - An object that can be explicitly cleaned up to free resources and prevent memory leaks. All PicoFlow primitives are disposable.
+
+**Observable** - An object that can be watched and notifies its dependents when it changes. Can have multiple observers.
+
+**Observer** - An object that watches one or more observables and reacts to their changes. Can have multiple dependencies.
+
+**Tracker** - An object (typically an Observer) passed to computation functions to automatically record dependencies when values are accessed.
+
+**Primitive** - A fundamental reactive building block in PicoFlow (state, derivation, effect, signal, etc.).
+
+**Node** - An internal implementation class that combines Observable and Observer behavior. Users never interact with nodes directly.
+
+**Scheduler** - Manages the execution lifecycle of computations, handling both synchronous and asynchronous execution strategies.
+
+**Resolver** - Manages iteration tracking within a scheduler to prevent race conditions from rapid recomputations.
+
+**Dependency Graph** - The directed acyclic graph formed by primitives observing each other. Changes propagate from sources (states) through intermediaries (derivations) to sinks (effects).
+
+**Batching** - Combining multiple synchronous changes into a single update cycle to optimize performance.
+
+**Lazy Evaluation** - Deferring computation until a value is actually needed, avoiding work for unused primitives.
+
+**PendingError** - A special error type thrown when an async computation is in progress, used to propagate pending states through the dependency graph.
+
+**ExecutionStack** - A global singleton that batches and orders reactive executions to prevent cascading updates and stack overflow.
+
+---
+
+## Further Reading
+
+- **[Concepts](/guide/introduction/concepts)** - High-level reactive concepts
+- **[Lifecycle](/guide/introduction/lifecycle)** - Primitive lifecycle and states
+- **[Disposal](/guide/advanced/disposal)** - Memory management best practices
+- **[API Reference](/api/)** - Complete API documentation
+
+---
+
+This architecture enables PicoFlow to provide fine-grained, explicit, and performant reactivity with a clean separation between public API and internal implementation. Whether you're debugging a tricky reactive chain or contributing a new feature, understanding these architectural patterns will help you work effectively with PicoFlow.