@raphy-js/raph 1.0.0-dev.2 → 1.0.1-dev.20

package/README.md

@@ -0,0 +1,1096 @@
+# Raph: from your first signal to a state machine
+
+Raph has three layers that you can use independently: a reactive graph,
+a runtime that owns and schedules work, and a state machine for processes
+with explicit transitions. This guide builds them up in that order.
+
+```sh
+npm install @raphy-js/raph@dev
+```
+
+The examples are independent unless a section says otherwise. Short
+fragments reuse names from their section. Imports use public package
+entrypoints.
+
+```mermaid
+flowchart LR
+    A["Reactivity<br/>signal, computed, effect"] --> B["Runtime<br/>ownership, lifecycle, scheduler"]
+    B --> C["Phases<br/>update, render, commit..."]
+    B --> D["Machine execution<br/>createMachine"]
+    E["Pure machine<br/>defineMachine, transition"] --> D
+    D --> F["Reactive snapshot"]
+    F --> C
+```
+
+## 1. Standalone reactivity
+
+Start with the low-level reactive graph:
+
+```ts
+import {
+  signal,
+  computed,
+  effect,
+  watch,
+  batch,
+  untracked,
+} from '@raphy-js/raph/reactivity'
+```
+
+There is no runtime, ownership tree, phase scheduler, or state machine here.
+
+### 1.1. Signal
+
+A signal holds a mutable reactive value:
+
+```ts
+const counter = signal(0)
+
+console.log(counter.get()) // 0
+counter.set(1)
+console.log(counter.get()) // 1
+```
+
+Its main operations are `get()` (read and track a dependency), `peek()`
+(read without tracking), and `set(value)` (write). Call the method to read
+the value: `counter.get` is the function itself.
+
+### 1.2. Computed
+
+`computed` derives a value from other reactive values:
+
+```ts
+const counter = signal(2)
+const doubled = computed(() => counter.get() * 2)
+
+console.log(doubled.get()) // 4
+counter.set(5)
+console.log(doubled.get()) // 10
+```
+
+It has no independent mutable state. Raph discovers its dependencies,
+caches the result, and recomputes lazily when it is read again.
+
+```mermaid
+flowchart LR
+    C["counter<br/>signal"] --> D["doubled<br/>computed"]
+```
+
+### 1.3. Effect
+
+An effect reacts to values read while it runs:
+
+```ts
+const counter = signal(0)
+
+const stop = effect(() => {
+  console.log('counter:', counter.get())
+})
+
+// Immediately: counter: 0
+counter.set(1) // counter: 1
+counter.set(2) // counter: 2
+
+stop()
+counter.set(3) // No further effect run
+```
+
+The call to `counter.get()` establishes the dependency. An effect may
+return cleanup, which runs before its next execution and when stopped:
+
+```ts
+const stop = effect(() => {
+  const value = counter.get()
+  console.log('start', value)
+
+  return () => console.log('cleanup', value)
+})
+```
+
+### 1.4. A complete reactive graph
+
+```ts
+const c = signal(0)
+const d = computed(() => c.get() * 2)
+
+const stop = effect(() => {
+  console.log({ c: c.get(), d: d.get() })
+})
+```
+
+The first effect run creates three edges:
+
+```mermaid
+flowchart LR
+    C["C: signal"] -->|E1| D["D: computed"]
+    D -->|E2| E["E: effect"]
+    C -->|E3| E
+```
+
+After `c.set(1)`, `d` becomes stale and the effect is scheduled. When the
+effect reads `d.get()`, it recomputes and logs `{ c: 1, d: 2 }`.
+
+### 1.5. Dynamic dependencies
+
+Dependencies can change between effect runs:
+
+```ts
+const enabled = signal(true)
+const first = signal(10)
+const second = signal(20)
+
+effect(() => {
+  console.log(enabled.get() ? first.get() : second.get())
+})
+```
+
+When `enabled` is true, the effect depends on `enabled` and `first`.
+When it becomes false, the edge to `first` is removed and an edge to
+`second` is added.
+
+### 1.6. Watch
+
+Use `watch` when you need the previous and current values of an explicit
+source:
+
+```ts
+const counter = signal(0)
+
+const stop = watch(
+  counter,
+  (value, previous) => console.log({ previous, value }),
+  { immediate: true },
+)
+
+counter.set(1)
+counter.set(2)
+```
+
+An `effect` tracks everything it reads. A `watch` observes the source you
+provide; reads inside its callback do not add dependencies.
+
+### 1.7. Batch
+
+`batch` groups writes into one reactive boundary:
+
+```ts
+const firstName = signal('John')
+const lastName = signal('Smith')
+const fullName = computed(() => `${firstName.get()} ${lastName.get()}`)
+
+effect(() => console.log(fullName.get()))
+
+batch(() => {
+  firstName.set('Jane')
+  lastName.set('Doe')
+})
+```
+
+The effect sees `Jane Doe`, rather than the intermediate `Jane Smith`.
+`batch` does not provide rollback: writes already made remain if its
+callback throws.
+
+### 1.8. Untracked
+
+`untracked` reads a value without creating a dependency:
+
+```ts
+effect(() => {
+  const reactiveValue = counter.get()
+  const informationalValue = untracked(() => someOtherSignal.get())
+  console.log(reactiveValue, informationalValue)
+})
+```
+
+This effect depends on `counter`, but not `someOtherSignal`.
+
+## 2. Add a runtime
+
+Standalone reactivity does not know who owns a signal, when to dispose an
+effect, or which phase should deliver it. A runtime supplies those rules:
+
+```ts
+import {
+  RaphRuntime,
+  RaphSchedulerType,
+} from '@raphy-js/raph/runtime'
+
+const runtime = new RaphRuntime({
+  id: 'application',
+  scheduler: RaphSchedulerType.Microtask,
+})
+```
+
+`Sync` flushes in the current call stack, `Microtask` in the next
+microtask, and `AnimationFrame` in an animation frame.
+
+### 2.1. Phases
+
+Define phases before registering effects:
+
+```ts
+runtime.definePhases([
+  { name: 'update' },
+  { name: 'render' },
+])
+```
+
+They run in array order: `update -> render`. A phase is a named work queue,
+not a callback you must supply. Without `process`, the runtime runs its
+queued tasks automatically.
+
+### 2.2. Nodes and ownership
+
+```ts
+const counterNode = runtime.node({ id: 'counter' })
+const counter = counterNode.signal(0)
+
+counterNode.effect('render', () => {
+  console.log('render counter:', counter.get())
+})
+```
+
+The node owns its signal and effect. `counterNode.dispose()` releases
+owned effects, watchers, signals, computed values, machines, custom
+cleanup, and child nodes. With standalone reactivity, you normally keep
+each disposer yourself.
+
+### 2.3. What a signal write does
+
+`counter.set(1)` invalidates the graph. It queues a persistent phase task,
+and the scheduler requests a flush:
+
+```mermaid
+sequenceDiagram
+    participant Code
+    participant Signal
+    participant Graph
+    participant Phase
+    participant Scheduler
+    participant Effect
+
+    Code->>Signal: set(1)
+    Signal->>Graph: invalidate
+    Graph->>Phase: enqueue persistent task
+    Phase->>Scheduler: request flush
+    Scheduler->>Phase: begin render
+    Phase->>Effect: task.run()
+    Effect->>Signal: get()
+```
+
+With `Microtask`, the effect does not run inside `set()`:
+
+```ts
+counter.set(1)
+console.log('This runs before the render effect')
+await runtime.afterFlush()
+console.log('All scheduled phases have finished')
+```
+
+`Sync` may flush in the same call stack, but effects still pass through
+phase tasks.
+
+### 2.4. Complete runtime example
+
+```ts
+import {
+  RaphRuntime,
+  RaphSchedulerType,
+} from '@raphy-js/raph/runtime'
+
+async function main() {
+  const runtime = new RaphRuntime({
+    id: 'counter-app',
+    scheduler: RaphSchedulerType.Microtask,
+  })
+
+  runtime.definePhases([
+    { name: 'update' },
+    { name: 'render' },
+  ])
+
+  const counterNode = runtime.node({ id: 'counter' })
+  const counter = counterNode.signal(0)
+  const doubled = counterNode.computed(() => counter.get() * 2)
+
+  counterNode.effect('render', () => {
+    console.log({ counter: counter.get(), doubled: doubled.get() })
+  })
+
+  await runtime.afterFlush() // Initial effect delivery
+
+  counter.set(1)
+  counter.set(2)
+  await runtime.afterFlush() // Both writes coalesce into one phase delivery
+
+  runtime.dispose()
+}
+
+void main()
+```
+
+### 2.5. Custom phase processing
+
+The default phase runner calls `task.run()` for each task. Define
+`process` only when the phase needs to control delivery:
+
+```ts
+runtime.definePhases([
+  {
+    name: 'render',
+    process(batch) {
+      console.log('frame:', batch.frame.frame)
+      for (const task of batch.tasks) task.run()
+    },
+  },
+])
+```
+
+A custom processor must resolve every task with `run()` (now), `defer()`
+(next scheduler turn), or `cancel()` (discard this delivery). Leaving a
+task unresolved makes the runtime defer it and report
+`RaphPhaseProcessError`. An implicit effect's initial task may not be
+cancelled before its first dependency collection.
+
+### 2.6. Effects and watches in a runtime
+
+An effect collects implicit dependencies:
+
+```ts
+node.effect('render', () => console.log(nodeSignal.get()))
+```
+
+A watch names its source explicitly:
+
+```ts
+viewNode.watch(modelSignal, 'render', () => {
+  console.log('model changed:', modelSignal.peek())
+})
+```
+
+An effect may implicitly read producers owned by its own node, an
+ancestor, or the runtime root scope. A sibling branch requires an
+explicit `watch`:
+
+```text
+root
+├── modelNode
+│   └── signal
+└── viewNode
+    └── watch(modelSignal)
+```
+
+The task belongs to `viewNode`; the signal owned by `modelNode` causes it.
+
+### 2.7. Actions
+
+An action is a reusable named operation run as `batch + untracked`:
+
+```ts
+const increment = counterNode.action('increment', () => {
+  counter.set(counter.peek() + 1)
+})
+
+increment()
+```
+
+When the runtime is created with `enforceActions: true`, writes are
+allowed only inside an action or batch.
+
+## 3. Why use a state machine?
+
+You could model a dialog with three signals:
+
+```ts
+const isOpen = signal(false)
+const isClosing = signal(false)
+const hasOverlay = signal(false)
+```
+
+That leaves room for combinations that make no sense, such as a closed
+dialog that is still closing. A machine names the allowed states and the
+events that move between them:
+
+```mermaid
+stateDiagram-v2
+    [*] --> closed
+    closed --> open: OPEN
+    open --> closed: CLOSE
+```
+
+A signal answers "what value is there?" A computed value derives another
+value; an effect runs after change. A machine answers "which mode is this
+process in, and which transitions are allowed?"
+
+## 4. Machine vocabulary
+
+| Term | Meaning |
+| --- | --- |
+| Model | Compiled machine description |
+| State | Allowed mode of the process |
+| Event | External occurrence or intent |
+| Transition | Current state's response to an event |
+| Context | Data carried across states |
+| Guard | Pure check that permits or rejects a transition |
+| Reducer | Pure calculation of the next context |
+| Snapshot | Immutable view of the machine state |
+| Output | One-time side effect after commit |
+| Resource | Side effect active for a state's lifetime |
+| Task | Asynchronous work tied to a state |
+| Delay | Timed transition driven by a `MachineClock` |
+| Actor | Child machine with its own queue and lifecycle |
+
+### 4.1. State and context are different
+
+```text
+state: open
+context: {
+  opens: 4,
+  lastCloseReason: "escape"
+}
+```
+
+The state names the mode. The context stores data. A counter belongs in
+context; it does not need states such as `openWithTwoPreviousOpens`.
+
+## 5. A pure machine without a runtime
+
+Machine APIs live in their own entrypoint:
+
+```ts
+import {
+  defineMachine,
+  getInitialSnapshot,
+  transition,
+} from '@raphy-js/raph/machine'
+```
+
+They are separate from the reactivity and runtime entrypoints.
+
+### 5.1. Define context and events
+
+```ts
+interface DialogContext {
+  readonly opens: number
+  readonly lastCloseReason?: 'button' | 'escape'
+}
+
+type DialogEvent =
+  | { readonly type: 'OPEN' }
+  | {
+      readonly type: 'CLOSE'
+      readonly reason: 'button' | 'escape'
+    }
+```
+
+### 5.2. Define the model
+
+```ts
+import {
+  defineMachine,
+  type MachineBindings,
+} from '@raphy-js/raph/machine'
+
+const dialogModel = defineMachine<DialogContext, DialogEvent>({
+  id: 'dialog',
+  context: { opens: 0 },
+  initial: 'closed',
+  states: {
+    closed: {
+      on: {
+        OPEN: {
+          target: 'open',
+          reduce: 'countOpen',
+          emit: 'opened',
+        },
+      },
+    },
+    open: {
+      tags: ['visible'],
+      on: {
+        CLOSE: {
+          target: 'closed',
+          reduce: 'rememberCloseReason',
+        },
+      },
+    },
+  },
+})
+```
+
+`defineMachine()` validates the description, compiles paths and
+transitions, and returns an immutable `MachineModel`. It does not start
+anything.
+
+### 5.3. Bind the named operations
+
+The names in the model are connected to implementations separately:
+
+```ts
+const dialogBindings: MachineBindings<
+  DialogContext,
+  DialogEvent,
+  void
+> = {
+  reducers: {
+    countOpen: ({ context }) => ({
+      ...context,
+      opens: context.opens + 1,
+    }),
+
+    rememberCloseReason: ({ context, event }) => ({
+      ...context,
+      lastCloseReason:
+        event.type === 'CLOSE'
+          ? event.reason
+          : context.lastCloseReason,
+    }),
+  },
+
+  outputs: {
+    opened: ({ snapshot }) => {
+      console.log('Dialog committed:', snapshot.active)
+    },
+  },
+}
+```
+
+A reducer computes `next context` from context, event, and input. It
+should not mutate the DOM, fetch data, write a signal, or start a timer.
+Use outputs, resources, or tasks for those effects.
+
+### 5.4. Get the initial snapshot
+
+```ts
+let snapshot = getInitialSnapshot(dialogModel)
+console.log(snapshot)
+```
+
+In simplified form:
+
+```ts
+{
+  active: ['closed'],
+  context: { opens: 0 },
+  history: {},
+  revision: 0,
+  status: 'active',
+}
+```
+
+Snapshots are immutable; do not edit them by hand.
+
+### 5.5. Run a pure transition
+
+```ts
+snapshot = transition(
+  dialogModel,
+  snapshot,
+  { type: 'OPEN' },
+  dialogBindings,
+)
+
+console.log(snapshot.active)        // ['open']
+console.log(snapshot.context.opens) // 1
+console.log(snapshot.revision)      // 1
+```
+
+`transition()` calculates the next snapshot. It does not run outputs,
+resources, timers, or tasks, so the `opened` output above does not log.
+This pure path is useful for transition analysis, deterministic replay,
+SSR, and tests without a runtime.
+
+### 5.6. Ignored events
+
+The `open` state has no handler for another `OPEN`:
+
+```ts
+const sameSnapshot = transition(
+  dialogModel,
+  snapshot,
+  { type: 'OPEN' },
+  dialogBindings,
+)
+
+console.log(sameSnapshot === snapshot) // true
+```
+
+An ignored event returns the same snapshot object.
+
+## 6. A live machine inside a runtime
+
+`createMachine` connects the pure model to runtime execution:
+
+```ts
+import { createMachine } from '@raphy-js/raph/machine'
+
+const machine = createMachine(
+  dialogNode,
+  dialogModel,
+  dialogBindings,
+).start()
+```
+
+The owner is a `RaphNode` or `RaphScope`. A standalone reactive scope
+does not provide the lifecycle and execution boundary a live machine
+needs. The following example uses `dialogModel` and `dialogBindings`
+from section 5.
+
+### 6.1. Complete live example
+
+```ts
+import {
+  RaphRuntime,
+  RaphSchedulerType,
+} from '@raphy-js/raph/runtime'
+import { createMachine } from '@raphy-js/raph/machine'
+
+async function main() {
+  const runtime = new RaphRuntime({
+    id: 'dialog-app',
+    scheduler: RaphSchedulerType.Microtask,
+  })
+
+  runtime.definePhases([
+    { name: 'update' },
+    { name: 'render' },
+  ])
+
+  const dialogNode = runtime.node({ id: 'dialog' })
+  const machine = createMachine(
+    dialogNode,
+    dialogModel,
+    dialogBindings,
+  ).start()
+
+  dialogNode.effect('render', () => {
+    // snapshot is a regular ReadonlySignal.
+    const snapshot = machine.snapshot.get()
+    console.log('render dialog', {
+      active: snapshot.active,
+      context: snapshot.context,
+      revision: snapshot.revision,
+    })
+  })
+
+  await runtime.afterFlush() // Initial render
+
+  const result = machine.send({ type: 'OPEN' })
+
+  // send() has already updated the snapshot synchronously.
+  console.log(result.status)            // transitioned
+  console.log(machine.matches('open'))  // true
+  console.log(machine.hasTag('visible')) // true
+
+  await runtime.afterFlush() // Deliver the render effect
+
+  machine.send({ type: 'CLOSE', reason: 'escape' })
+  await runtime.afterFlush()
+
+  console.log(
+    machine.snapshot.peek().context.lastCloseReason,
+  ) // escape
+
+  runtime.dispose()
+}
+
+void main()
+```
+
+### 6.2. What happens during `send()`
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Machine
+    participant PureCore
+    participant Snapshot
+    participant Lifecycle
+    participant Phase
+
+    Caller->>Machine: send(OPEN)
+    Machine->>Machine: enqueue event in FIFO
+    Machine->>PureCore: guards + reducers + transition
+    PureCore-->>Machine: next snapshot + effect plan
+    Machine->>Snapshot: one commit inside runtime.batch
+    Machine->>Lifecycle: outputs/resources/timers/tasks
+    Snapshot->>Phase: invalidate render effect
+    Machine-->>Caller: MachineSendResult
+    Phase->>Phase: scheduler flush
+    Phase->>Snapshot: effect reads snapshot.get()
+```
+
+Guards, reducers, transition calculation, snapshot commit, and machine
+lifecycle work happen in the machine macrostep. Effects and explicit
+watches that read `machine.snapshot` run through runtime phases. A phase
+controls reactive runtime delivery; it is not the sole executor of
+machine logic.
+
+## 7. Guards
+
+A guard decides whether a transition is allowed:
+
+```ts
+interface Context {
+  readonly canClose: boolean
+}
+
+type Event =
+  | { readonly type: 'OPEN' }
+  | { readonly type: 'CLOSE' }
+
+const model = defineMachine<Context, Event>({
+  id: 'guarded-dialog',
+  context: { canClose: false },
+  initial: 'closed',
+  states: {
+    closed: {
+      on: { OPEN: 'open' },
+    },
+    open: {
+      on: {
+        CLOSE: {
+          target: 'closed',
+          guard: 'canClose',
+        },
+      },
+    },
+  },
+})
+
+const bindings = {
+  guards: {
+    canClose: ({ context }: { context: Readonly<Context> }) => {
+      return context.canClose
+    },
+  },
+}
+```
+
+When a guard returns `false`, Raph checks the next transition in
+declaration order. If none matches, the event is ignored. Guards should
+be pure.
+
+## 8. Outputs and resources
+
+### 8.1. Output
+
+An output is one-time work after a successful commit. A transition can
+name one:
+
+```ts
+closed: {
+  on: {
+    OPEN: {
+      target: 'open',
+      emit: 'notifyOpened',
+    },
+  },
+}
+```
+
+Bind its implementation separately:
+
+```ts
+outputs: {
+  notifyOpened: ({ event, snapshot }) => {
+    console.log(event.type)
+    console.log(snapshot.active) // Already ['open']
+  },
+}
+```
+
+The snapshot has already been published. An output error does not roll
+back that commit.
+
+### 8.2. Resource
+
+A resource lives while its state is active:
+
+```ts
+open: {
+  resources: ['presence'],
+  on: { CLOSE: 'closed' },
+}
+```
+
+```ts
+resources: {
+  presence: ({ signal }) => {
+    console.log('open-state resource started')
+
+    signal.addEventListener('abort', () => {
+      console.log('resource aborted')
+    })
+
+    return () => console.log('open-state resource cleaned')
+  },
+}
+```
+
+Raph starts it when entering `open`. It cleans up when leaving `open`,
+stopping the machine, disposing its owner, or disposing the runtime.
+
+## 9. Delays
+
+A state may request a timed transition:
+
+```ts
+visible: {
+  after: {
+    autoClose: 'hidden',
+  },
+}
+```
+
+The binding supplies the duration:
+
+```ts
+const machine = createMachine(owner, model, {
+  delays: { autoClose: 2_000 },
+}).start()
+```
+
+You can pass a custom `MachineClock` to test time without waiting for a
+real timer.
+
+## 10. Asynchronous tasks
+
+An invoked task belongs to the state that starts it:
+
+```ts
+const loaderModel = defineMachine({
+  id: 'loader',
+  context: {},
+  initial: 'idle',
+  states: {
+    idle: {
+      on: { LOAD: 'loading' },
+    },
+    loading: {
+      invoke: {
+        src: 'loadData',
+        onDone: 'success',
+        onError: 'failed',
+      },
+      on: { CANCEL: 'idle' },
+    },
+    success: {},
+    failed: {},
+  },
+})
+```
+
+Bind the task at runtime:
+
+```ts
+const loader = createMachine(owner, loaderModel, {
+  tasks: {
+    loadData: async ({ signal }) => {
+      const response = await fetch('/api/data', { signal })
+      return response.json()
+    },
+  },
+}).start()
+```
+
+If `loader.send({ type: 'CANCEL' })` leaves `loading`, the task is
+aborted. A late result from that old task is ignored and cannot change
+the current state.
+
+## 11. Nested states
+
+Machines support compound states:
+
+```ts
+const model = defineMachine({
+  id: 'dialog',
+  context: {},
+  initial: 'closed',
+  states: {
+    closed: {
+      on: { OPEN: 'open.idle' },
+    },
+    open: {
+      initial: 'idle',
+      states: {
+        idle: {
+          on: { CLOSE: 'open.closing' },
+        },
+        closing: {
+          always: 'closed',
+        },
+      },
+    },
+  },
+})
+```
+
+An active leaf path looks like `['open.idle']`. While there,
+`machine.matches('open')` and `machine.matches('open.idle')` are both
+true. Machines also support parallel states, shallow and deep history,
+final states, `onDone`, `always`, `raise`, tags, metadata, and actors.
+
+Within a macrostep, Raph stabilizes internal transitions. A limit of 100
+microsteps protects against endless `always` or `raise` cycles.
+
+## 12. The event queue
+
+If an output, task, or actor sends an event while another is being
+processed, Raph puts it in one FIFO queue. It does not recursively run a
+nested transition:
+
+```text
+OPEN
+  ├── commit open
+  └── output sends FOCUS
+
+FIFO:
+  finish OPEN
+  then process FOCUS
+```
+
+This keeps ordering deterministic and avoids reentrant transitions.
+
+## 13. Lifecycle order
+
+A transition performs lifecycle work in this order:
+
+```text
+1. Clean up resources, tasks, and timers for exited states
+2. Exit outputs
+3. Transition outputs
+4. Entry outputs
+5. Entry resources
+6. Timers and invokes
+```
+
+Guards and reducers run before commit; outputs and resources run after
+commit. A guard or reducer error prevents a new snapshot. An output or
+resource error does not undo an already published snapshot.
+
+## 14. Persistence
+
+Save a running machine with:
+
+```ts
+const persisted = machine.persist()
+```
+
+The persisted snapshot contains active states, context, history, status,
+revision, final output, and the model ID and version. It does not save
+live timers, promises, resources, actors, or the event queue.
+
+Restore it with the same model and bindings:
+
+```ts
+machine.stop()
+
+const restored = createMachine(
+  owner,
+  dialogModel,
+  dialogBindings,
+  { persisted },
+).start()
+```
+
+Restore does not replay old outputs. It restarts resources for active
+states, restarts delays at their full duration, and creates tasks and
+actors again. Migrations handle context format changes between model
+versions.
+
+## 15. Testing machines
+
+Testing helpers have a separate entrypoint:
+
+```ts
+import {
+  inspectMachine,
+  enumerateMachinePaths,
+  createMachineCoverage,
+  createManualMachineClock,
+} from '@raphy-js/raph/machine/testing'
+```
+
+A manual clock makes timed transitions deterministic:
+
+```ts
+const clock = createManualMachineClock()
+
+const machine = createMachine(
+  owner,
+  model,
+  bindings,
+  { clock },
+).start()
+
+clock.advance(1_999)
+console.log(machine.matches('visible')) // true
+
+clock.advance(1)
+console.log(machine.matches('hidden')) // true
+```
+
+## 16. Choosing the right layer
+
+```text
+Reactivity
+├── signal      mutable value
+├── computed    derived value
+├── effect      automatic reaction
+├── watch       explicit observation
+├── batch       grouped writes
+└── untracked   read without a dependency
+
+Runtime
+├── RaphScope   resource owner
+├── RaphNode    owner with a tree position
+├── Scheduler   decides when a flush starts
+├── Phase       named work queue
+├── Task        delivery of one phase effect
+├── Watch       explicit producer-to-consumer link
+├── Action      batch + untracked + diagnostics
+└── Disposal    automatic cleanup of an ownership subtree
+
+Pure machine core
+├── Model
+├── State
+├── Event
+├── Transition
+├── Snapshot
+├── Context
+├── Guard
+└── Reducer
+
+Machine runtime execution
+├── createMachine(owner, model)
+├── FIFO events
+├── one snapshot commit per macrostep
+├── outputs
+├── resources
+├── delays
+├── tasks
+├── actors
+├── persistence
+└── reactive snapshot
+```
+
+Use a signal for a simple mutable value, a computed value for a
+derivation, and an effect for a reaction. Add a runtime when execution
+timing, local lifecycle, or cleanup matters. Use a machine for a process
+with discrete modes and allowed transitions. A simple button rarely
+needs one; a dialog, loader, connection lifecycle, or multistep workflow
+often does.
+
+## 17. Public entrypoints
+
+| Import | Purpose |
+| --- | --- |
+| `@raphy-js/raph/reactivity` | Standalone reactive graph |
+| `@raphy-js/raph/runtime` | Ownership, nodes, phases, and scheduling |
+| `@raphy-js/raph/machine` | Pure machine model and runtime execution |
+| `@raphy-js/raph/machine/testing` | Inspection, coverage, and manual clock |
+
+The complete Raph package also exposes paths and other runtime APIs.
+This guide follows the signal-to-machine route; each entrypoint exports
+its public TypeScript declarations.