controlled-machine 0.3.2 → 0.4.0

package/README.md

@@ -1,349 +1,617 @@
 # Controlled Machine
 
-A controlled state machine where **state lives outside the machine**.
+Manage your React UI state cleanly.
 
-Machine defines **what** happens. Your component owns **the state**.
+- Separate logic from UI
+- Declarative state transitions
+- Full TypeScript support
 
-## The Killer Example
+```bash
+npm install controlled-machine
+```
+
+---
 
-A reusable dropdown machine — logic lives in the machine, DOM handling in your component:
+## Why?
 
-```ts
-// dropdown-machine.ts — Pure logic, no DOM dependencies
-const dropdownMachine = createMachine<{
-  input: { isOpen: boolean; onOpenChange: (v: boolean) => void }
-  events: { OPEN: undefined; CLOSE: undefined; TOGGLE: undefined }
-  actions: 'open' | 'close' | 'focusTrigger'
-  guards: 'isOpen'
+**Before (useState spaghetti):**
+
+```tsx
+function Select() {
+  const [isOpen, setIsOpen] = useState(false)
+  const [highlightedIndex, setHighlightedIndex] = useState(-1)
+
+  const handleKeyDown = (e) => {
+    if (e.key === 'ArrowDown') {
+      if (!isOpen) setIsOpen(true)
+      else setHighlightedIndex(i => Math.min(i + 1, items.length - 1))
+    }
+    if (e.key === 'Escape') {
+      setIsOpen(false)
+      setHighlightedIndex(-1)
+    }
+    // State dependencies get messy...
+  }
+}
+```
+
+**After (controlled-machine):**
+
+```tsx
+function Select() {
+  const [snapshot, send] = useMachine(selectMachine, { input: { items } })
+
+  const handleKeyDown = (e) => {
+    if (e.key === 'ArrowDown') send('HIGHLIGHT_NEXT')
+    if (e.key === 'Escape') send('CLOSE')
+  }
+  // State logic is encapsulated in the machine
+}
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { createMachine } from 'controlled-machine'
+import { useMachine } from 'controlled-machine/react'
+
+const toggleMachine = createMachine<{
+  internal: { isOpen: boolean }
+  events: { TOGGLE: undefined }
 }>({
+  internal: { isOpen: false },
   on: {
-    OPEN: [{ when: 'isOpen', do: [] }, { do: 'open' }],
-    CLOSE: [{ when: 'isOpen', do: ['close', 'focusTrigger'] }],
-    TOGGLE: [{ when: 'isOpen', do: 'close' }, { do: 'open' }],
-  },
-  actions: {
-    open: (ctx) => ctx.onOpenChange(true),
-    close: (ctx) => ctx.onOpenChange(false),
-    focusTrigger: () => {},  // Default: noop
-  },
-  guards: {
-    isOpen: (ctx) => ctx.isOpen,
+    TOGGLE: (ctx, _, assign) => assign({ isOpen: !ctx.isOpen }),
   },
 })
+
+function Dropdown() {
+  const [snapshot, send] = useMachine(toggleMachine)
+  return (
+    <button onClick={() => send('TOGGLE')}>
+      {snapshot.isOpen ? 'Close' : 'Open'}
+    </button>
+  )
+}
 ```
 
+---
+
+## Full Example
+
+A counter demonstrating most features. Copy and paste to try it out.
+
 ```tsx
-// Dropdown.tsx — Component provides DOM implementation
-function Dropdown() {
-  const [isOpen, setIsOpen] = useState(false)
-  const triggerRef = useRef<HTMLButtonElement>(null)
+import { useState } from 'react'
+import { createMachine } from 'controlled-machine'
+import { useMachine } from 'controlled-machine/react'
 
-  const { send } = useMachine(dropdownMachine, {
-    input: { isOpen, onOpenChange: setIsOpen },
-    actions: {
-      // Override: provide actual DOM implementation
-      focusTrigger: () => triggerRef.current?.focus(),
+const counterMachine = createMachine<{
+  input: {
+    max: number
+    onChange?: (count: number) => void
+  }
+  internal: {
+    count: number
+    mode: 'normal' | 'turbo'
+  }
+  events: {
+    INCREMENT: undefined
+    DECREMENT: undefined
+    RESET: undefined
+    SET: { value: number }
+    TOGGLE_MODE: undefined
+  }
+  computed: {
+    doubled: number
+    isAtMax: boolean
+    step: number
+  }
+  guards: 'canIncrement' | 'canDecrement'
+  actions: 'notifyChange'
+}>({
+  internal: {
+    count: 0,
+    mode: 'normal',
+  },
+  computed: {
+    doubled: (ctx) => ctx.count * 2,
+    isAtMax: (ctx) => ctx.count >= ctx.max,
+    step: (ctx) => (ctx.mode === 'turbo' ? 10 : 1),
+  },
+  guards: {
+    canIncrement: (ctx) => ctx.count < ctx.max,
+    canDecrement: (ctx) => ctx.count > 0,
+  },
+  actions: {
+    notifyChange: (ctx) => ctx.onChange?.(ctx.count),
+  },
+  on: {
+    INCREMENT: [
+      { when: 'canIncrement', do: (ctx, _, assign) => assign({ count: ctx.count + ctx.step }) },
+    ],
+    DECREMENT: [
+      { when: 'canDecrement', do: (ctx, _, assign) => assign({ count: ctx.count - ctx.step }) },
+    ],
+    RESET: [{ do: [(_, __, assign) => assign({ count: 0 }), 'notifyChange'] }],
+    SET: (_, { value }, assign) => assign({ count: value }),
+    TOGGLE_MODE: (ctx, _, assign) =>
+      assign({ mode: ctx.mode === 'normal' ? 'turbo' : 'normal' }),
+  },
+  always: [
+    { when: (ctx) => ctx.count > ctx.max, do: (ctx, __, assign) => assign({ count: ctx.max }) },
+    { when: (ctx) => ctx.count < 0, do: (_, __, assign) => assign({ count: 0 }) },
+  ],
+  effects: [
+    {
+      watch: (ctx) => ctx.count,
+      change: (ctx, _prev, _curr) => ctx.onChange?.(ctx.count),
+    },
+    {
+      watch: (ctx) => ctx.isAtMax,
+      enter: () => console.log('Max reached!'),
+      exit: () => console.log('Left max'),
     },
+  ],
+})
+
+function Counter({ max, onChange }: { max: number; onChange?: (n: number) => void }) {
+  const [snapshot, send] = useMachine(counterMachine, {
+    input: { max, onChange },
   })
 
   return (
-    <>
-      <button ref={triggerRef} onClick={() => send('TOGGLE')}>
-        Menu
+    <div style={{ fontFamily: 'system-ui', padding: 20 }}>
+      <div style={{ fontSize: 48, marginBottom: 16 }}>
+        {snapshot.count}
+        <span style={{ fontSize: 16, color: '#888' }}> (x2 = {snapshot.doubled})</span>
+      </div>
+
+      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
+        <button onClick={() => send('DECREMENT')} disabled={snapshot.count <= 0}>
+          -{snapshot.step}
+        </button>
+        <button onClick={() => send('INCREMENT')} disabled={snapshot.isAtMax}>
+          +{snapshot.step}
+        </button>
+        <button onClick={() => send('RESET')}>Reset</button>
+      </div>
+
+      <button onClick={() => send('TOGGLE_MODE')} style={{ marginBottom: 16 }}>
+        Mode: {snapshot.mode}
       </button>
-      {isOpen && (
-        <ul>
-          <li onClick={() => send('CLOSE')}>Item 1</li>
-        </ul>
-      )}
-    </>
+
+      <input
+        type="range"
+        min={0}
+        max={max}
+        value={snapshot.count}
+        onChange={(e) => send('SET', { value: Number(e.target.value) })}
+        style={{ width: '100%' }}
+      />
+
+      {snapshot.isAtMax && <div style={{ color: 'green', marginTop: 8 }}>Maximum!</div>}
+    </div>
   )
 }
-```
 
-**Why this matters:**
-- Machine is **pure and testable** — no refs, no DOM
-- Component **owns its state** — React's controlled pattern
-- Override **only what you need** — `focusTrigger` gets real implementation
-- Same machine, **different UIs** — reuse logic across components
+export default function App() {
+  const [lastChange, setLastChange] = useState<number | null>(null)
 
----
+  return (
+    <div style={{ padding: 40 }}>
+      <h1>Counter Machine</h1>
+      <Counter max={100} onChange={setLastChange} />
+      {lastChange !== null && <p>Last change: {lastChange}</p>}
+    </div>
+  )
+}
+```
 
-## Installation
+**Features demonstrated:**
 
-```bash
-npm install controlled-machine
-```
+| Feature | Description |
+|---------|-------------|
+| `input` | External values (`max`, `onChange`) |
+| `internal` | Machine-managed state (`count`, `mode`) |
+| `computed` | Derived values (`doubled`, `isAtMax`, `step`) |
+| `guards` | Condition checks (`canIncrement`, `canDecrement`) |
+| `actions` | Named actions (`notifyChange`) |
+| `always` | Auto state correction (0~max clamping) |
+| `effects` | Side effects (onChange callback, logging) |
 
 ---
 
 ## Core Concepts
 
-### 1. External State
+### Internal vs Input
 
-Unlike XState where state lives inside the machine, here **you own the state**:
+```
+┌─────────────────────────────────────────┐
+│  Component (React)                      │
+│  ┌───────────────┐   ┌───────────────┐  │
+│  │    Input      │   │   Snapshot    │  │
+│  │  (pass in)    │   │  (read from)  │  │
+│  └───────┬───────┘   └───────▲───────┘  │
+│          │                   │          │
+│          ▼                   │          │
+│  ┌───────────────────────────┴───────┐  │
+│  │           Machine                 │  │
+│  │  ┌─────────┐  ┌─────────────────┐ │  │
+│  │  │ Internal│  │    Computed     │ │  │
+│  │  │ (state) │  │ (derived values)│ │  │
+│  │  └─────────┘  └─────────────────┘ │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
 
-```tsx
-// Your state, your control
-const [isOpen, setIsOpen] = useState(false)
-const [selectedId, setSelectedId] = useState<string | null>(null)
+**Input** - Values passed from outside:
+- Values controlled by parent component (props)
+- Callback functions (`onChange`, `onSelect`)
+- External data (`items`, `options`)
 
-// Machine just defines handlers
-const { send } = useMachine(machine, {
-  input: { isOpen, onOpenChange: setIsOpen, selectedId, onSelect: setSelectedId },
-})
+**Internal** - State managed by the machine:
+- UI-only state (`isOpen`, `highlightedIndex`)
+- Values initialized on component mount
+- State that doesn't need external control
+
+```tsx
+// Input: controlled by parent
+const [value, setValue] = useState('')
+<Combobox value={value} onChange={setValue} items={items} />
+
+// Internal: controlled by machine (isOpen, highlightedIndex, etc.)
+const comboboxMachine = createMachine<{
+  input: { value: string; onChange: (v: string) => void; items: Item[] }
+  internal: { isOpen: boolean; highlightedIndex: number }
+  // ...
+}>({ ... })
 ```
 
-### 2. Declarative Handlers
+### Context
 
-Define **what** happens on each event with conditional logic:
+Inside handlers, `input + internal + computed` are merged into one flat object:
 
 ```ts
 on: {
-  SELECT: [
-    { when: 'isDisabled', do: [] },           // Guard: skip if disabled
-    { when: 'hasSelection', do: 'deselect' }, // Conditional action
-    { do: ['select', 'close'] },              // Default: multiple actions
-  ],
+  SELECT: (ctx, payload, assign) => {
+    // ctx.value        ← input
+    // ctx.isOpen       ← internal
+    // ctx.selectedItem ← computed
+    // All accessible at the same level
+  }
 }
 ```
 
-### 3. Actions & Guards Override
+### Snapshot
 
-Machine provides defaults. Component can override:
+The value returned by `useMachine`. Contains **Internal + Computed** (excludes Input):
 
-```ts
-// Machine: default implementations
-const machine = createMachine({
-  actions: {
-    scrollToItem: () => {},  // noop default
-    focusInput: () => {},
-  },
-  guards: {
-    canSelect: (ctx) => !ctx.disabled,
-  },
-})
+```tsx
+const [snapshot, send] = useMachine(machine, { input: { value, items } })
 
-// Component: real implementations
-useMachine(machine, {
-  input: { ... },
-  actions: {
-    scrollToItem: (ctx) => itemRefs.get(ctx.highlightedId)?.scrollIntoView(),
-    focusInput: () => inputRef.current?.focus(),
-  },
-  guards: {
-    canSelect: (ctx) => !ctx.disabled && ctx.items.length > 0,
-  },
-})
+snapshot.isOpen       // ← internal
+snapshot.selectedItem // ← computed
+// snapshot.value     // ❌ input is not in snapshot
 ```
 
----
-
-## API Reference
+### Assign
 
-### `createMachine<T>(config)`
+Function to update internal state. The third argument in handlers:
 
 ```ts
-const machine = createMachine<{
-  input: { count: number; setCount: (n: number) => void }
-  events: { INCREMENT: undefined; SET: { value: number } }
-  computed: { isPositive: boolean }
-  actions: 'increment' | 'set'
-  guards: 'canIncrement'
-  state: 'idle' | 'active'  // Optional: for state-based handlers
-}>({
-  computed: {
-    isPositive: (input) => input.count > 0,
-  },
-  on: {
-    INCREMENT: [{ when: 'canIncrement', do: 'increment' }],
-    SET: 'set',
-  },
-  actions: {
-    increment: (ctx) => ctx.setCount(ctx.count + 1),
-    set: (ctx, payload) => ctx.setCount(payload.value),
+on: {
+  OPEN: (ctx, payload, assign) => {
+    assign({ isOpen: true })  // Partial update
   },
-  guards: {
-    canIncrement: (ctx) => ctx.count < 10,
+  RESET: (_, __, assign) => {
+    assign({ isOpen: false, highlightedIndex: -1 })  // Multiple keys
   },
-})
+}
 ```
 
-### `useMachine(machine, options)`
+---
 
-```ts
-const { send, computed, state } = useMachine(machine, {
-  input: { count, setCount },
-  actions: { /* optional overrides */ },
-  guards: { /* optional overrides */ },
-})
+## Event Handlers
 
-send('INCREMENT')
-send('SET', { value: 5 })
-```
+### Handler Patterns
 
----
+| Pattern | Form | When to use |
+|---------|------|-------------|
+| Inline function | `(ctx, payload, assign) => ...` | Simple state changes |
+| Function array | `[fn1, fn2, fn3]` | Sequential operations |
+| String | `'actionName'` | Named action call |
+| String array | `['action1', 'action2']` | Sequential named actions |
+| Rule array | `[{ when, do }, { do }]` | Conditional branching |
+
+### Inline Function
 
-## Features
+```ts
+on: {
+  TOGGLE: (ctx, _, assign) => assign({ isOpen: !ctx.isOpen }),
+  SET_VALUE: (ctx, { value }, assign) => assign({ value }),
+}
+```
 
-### Conditional Handlers
+**Handler parameters:**
+- `ctx` - Context (input + internal + computed)
+- `payload` - Value passed via `send('EVENT', payload)`
+- `assign` - Internal state update function
 
-Branch logic with `when`/`do` rules. Stops at first match:
+### Function Array
+
+Execute multiple operations sequentially. Each function receives fresh context after previous `assign`:
 
 ```ts
 on: {
-  TOGGLE: [
-    { when: 'isDisabled', do: [] },   // Skip if disabled
-    { when: 'isOpen', do: 'close' },  // Close if open
-    { do: 'open' },                    // Default: open
+  SELECT: [
+    (ctx, { value }) => ctx.onChange(value),  // 1. Call callback
+    (_, __, assign) => assign({ isOpen: false }),  // 2. Close
   ],
 }
 ```
 
-### Guards
+### Rule Array (Conditional Branching)
 
-Use named guards, inline functions, or arrays in `when`:
+Only the first rule with matching `when` condition executes (first match wins):
 
 ```ts
 on: {
   TOGGLE: [
-    { when: 'isOpen', do: 'close' },             // Named guard
-    { when: (ctx) => ctx.disabled, do: [] },     // Inline guard function
-  ],
-
-  // Multiple guards - ALL must pass (AND logic)
-  DELETE: [
-    {
-      when: ['isAdmin', 'hasPermission', (ctx) => !ctx.isLocked],
-      do: 'deleteItem',
-    },
-    { do: 'showError' },
+    { when: 'isOpen', do: (_, __, assign) => assign({ isOpen: false }) },
+    { do: (_, __, assign) => assign({ isOpen: true }) },  // default
   ],
 }
 ```
 
-### Inline Actions
+### Named Actions
 
-Use inline functions directly in `do`:
+Define reusable actions:
 
 ```ts
-on: {
-  SELECT: [
-    {
-      when: 'isEnabled',
-      do: (ctx, payload) => ctx.selectItem(payload.id),  // Single inline action
-    },
-  ],
-
-  SUBMIT: [
-    {
-      when: 'isValid',
-      do: [
-        'logSubmit',                              // Named action
-        (ctx, payload) => ctx.submit(payload),    // Inline function
-        'showSuccess',                            // Named action
-      ],
-    },
-  ],
-}
+createMachine<{
+  // ...
+  actions: 'logValue' | 'notifyChange'
+}>({
+  actions: {
+    logValue: (ctx) => console.log(ctx.value),
+    notifyChange: (ctx) => ctx.onChange?.(ctx.value),
+  },
+  on: {
+    CHANGE: ['logValue', 'notifyChange'],  // Call by string
+  },
+})
 ```
 
-### Multiple Actions
+### Mixing Functions and Strings
 
-Execute multiple actions per event:
+**Only possible inside Rule's `do`:**
 
 ```ts
 on: {
-  SELECT: ['highlight', 'select', 'close'],  // Array of named actions
+  // ❌ Doesn't work - mixing at handler level
+  EVENT: [(ctx) => console.log(ctx), 'actionName'],
 
-  CONFIRM: [
-    { when: 'isValid', do: ['save', 'close', 'notify'] },
-    { do: 'showError' },
-  ],
+  // ✅ Works - mixing inside Rule's do
+  EVENT: [{ do: [(ctx) => console.log(ctx), 'actionName'] }],
 }
 ```
 
-### Computed Values
+---
+
+## Guards
 
-Derive values from input:
+Guard functions for conditional execution:
 
 ```ts
-computed: {
-  isEmpty: (input) => input.items.length === 0,
-  canSubmit: (input) => input.value.length > 0 && !input.isLoading,
-},
+createMachine<{
+  // ...
+  guards: 'canIncrement' | 'canDecrement'
+}>({
+  guards: {
+    canIncrement: (ctx) => ctx.count < ctx.max,
+    canDecrement: (ctx) => ctx.count > 0,
+  },
+  on: {
+    INCREMENT: [
+      { when: 'canIncrement', do: (ctx, _, assign) => assign({ count: ctx.count + 1 }) },
+    ],
+  },
+})
+```
 
-// Use in handlers
-on: {
-  SUBMIT: [
-    { when: (ctx) => !ctx.canSubmit, do: [] },
-    { do: 'submit' },
-  ],
-}
+**Guard usage:**
+
+```ts
+// 1. Named guard (string)
+{ when: 'canIncrement', do: ... }
+
+// 2. Inline guard (function)
+{ when: (ctx) => ctx.count < 10, do: ... }
+
+// 3. Multiple guards (AND condition)
+{ when: ['isEnabled', 'canIncrement', (ctx) => !ctx.isLoading], do: ... }
+```
+
+---
+
+## Computed Values
 
-// Access from hook
-const { computed } = useMachine(machine, { input })
-if (computed.isEmpty) { /* ... */ }
+Values derived from Input and Internal:
+
+```ts
+createMachine<{
+  input: { items: Item[] }
+  internal: { selectedIndex: number }
+  computed: { selectedItem: Item | null }
+}>({
+  computed: {
+    selectedItem: (ctx) => ctx.items[ctx.selectedIndex] ?? null,
+  },
+})
+
+// Usage
+const [snapshot] = useMachine(machine, { input: { items } })
+console.log(snapshot.selectedItem)  // Access computed value
 ```
 
-### Effects
+---
+
+## Effects
 
-Watch value changes and react:
+Detect value changes and execute side effects:
 
 ```ts
 effects: [
   {
-    watch: (ctx) => ctx.highlightedId,
+    watch: (ctx) => ctx.searchQuery,  // Value to watch (shallow compare)
+
     enter: (ctx, { send }) => {
-      // When watch becomes truthy
-      const timer = setTimeout(() => send('AUTO_SELECT'), 1000)
-      return () => clearTimeout(timer)  // Cleanup
+      // When watch value becomes falsy → truthy
+      const timer = setTimeout(() => send('SEARCH'), 300)
+      return () => clearTimeout(timer)  // Can return cleanup function
     },
-    exit: () => {
-      // When watch becomes falsy
+
+    exit: (ctx, { send }) => {
+      // When watch value becomes truthy → falsy
+      send('CLEAR_RESULTS')
     },
+
     change: (ctx, prev, curr, { send }) => {
-      // On any change
+      // When watch value changes
       console.log(`${prev} → ${curr}`)
     },
   },
 ]
 ```
 
-### State-based Handlers
+**Trigger conditions:**
+| Callback | When it runs |
+|----------|--------------|
+| `enter` | `watch` returns falsy → truthy |
+| `exit` | `watch` returns truthy → falsy |
+| `change` | `watch` return value changes |
+
+---
+
+## Always Rules
+
+Rules automatically evaluated whenever context changes:
+
+```ts
+always: [
+  {
+    when: (ctx) => ctx.count < 0,
+    do: (_, __, assign) => assign({ count: 0 }),
+  },
+  {
+    when: (ctx) => ctx.count > ctx.max,
+    do: (ctx, __, assign) => assign({ count: ctx.max }),
+  },
+]
+```
+
+### Always vs Effects
+
+| | Always | Effects |
+|---|--------|---------|
+| **Purpose** | State correction/constraints | Side effects |
+| **When** | Synchronous during render | Inside useEffect |
+| **Use for** | Value clamping, validation | API calls, timers, logging |
+| **Cleanup** | None | Can return cleanup |
 
-Different handlers per state:
+---
+
+## State-based Handlers (FSM)
+
+Execute different handlers based on state:
 
 ```ts
-const machine = createMachine<{
-  input: { state: 'idle' | 'loading' | 'error'; setState: (s) => void }
-  events: { FETCH: undefined; RETRY: undefined }
-  state: 'idle' | 'loading' | 'error'
+const fetchMachine = createMachine<{
+  internal: { state: 'idle' | 'loading' | 'success' | 'error'; data: any }
+  events: { FETCH: undefined; SUCCESS: { data: any }; ERROR: undefined; RETRY: undefined }
+  state: 'idle' | 'loading' | 'success' | 'error'
 }>({
+  internal: { state: 'idle', data: null },
+
   states: {
     idle: {
-      on: { FETCH: 'startFetch' },
+      on: {
+        FETCH: (_, __, assign) => assign({ state: 'loading' }),
+      },
     },
     loading: {
-      // FETCH ignored while loading
+      on: {
+        SUCCESS: (_, { data }, assign) => assign({ state: 'success', data }),
+        ERROR: (_, __, assign) => assign({ state: 'error' }),
+        // FETCH is ignored (no handler)
+      },
+    },
+    success: {
+      on: {
+        FETCH: (_, __, assign) => assign({ state: 'loading', data: null }),
+      },
     },
     error: {
-      on: { RETRY: 'startFetch' },
+      on: {
+        RETRY: (_, __, assign) => assign({ state: 'loading' }),
+      },
     },
   },
-  actions: { startFetch: (ctx) => ctx.setState('loading') },
 })
 ```
 
-### Always Rules
+**Where `state` can live:**
+- `internal` - Transition directly with `assign()`
+- `computed` - Derived from other values
+- `input` - Controlled by parent
+
+---
+
+## Action & Guard Overrides
 
-Auto-evaluated on every context change:
+Override actions/guards per component:
 
 ```ts
-always: [
-  { when: (ctx) => ctx.value < 0, do: 'clampToMin' },
-  { when: (ctx) => ctx.value > 100, do: 'clampToMax' },
-]
+const [snapshot, send] = useMachine(machine, {
+  input: { value },
+  actions: {
+    logValue: (ctx) => {
+      // Different implementation for this component
+      analytics.track('value', ctx.value)
+    },
+  },
+  guards: {
+    canSubmit: (ctx) => ctx.value.length > 5,  // Stricter condition
+  },
+})
+```
+
+---
+
+## Factory Pattern
+
+Isolated machine instances per component:
+
+```ts
+const createCounterMachine = (initialCount: number) =>
+  createMachine<{
+    internal: { count: number }
+    events: { INCREMENT: undefined }
+  }>({
+    internal: { count: initialCount },
+    on: {
+      INCREMENT: (ctx, _, assign) => assign({ count: ctx.count + 1 }),
+    },
+  })
+
+// Each component gets its own instance
+function Counter() {
+  const [snapshot, send] = useMachine(() => createCounterMachine(100))
+  // ...
+}
 ```
 
 ---
@@ -353,18 +621,36 @@ always: [
 Use without React:
 
 ```ts
-const machine = createMachine({ /* config */ })
+const machine = createMachine<{
+  input: { multiplier: number }
+  internal: { count: number }
+  computed: { doubled: number }
+  events: { INCREMENT: undefined }
+}>({
+  internal: { count: 0 },
+  computed: { doubled: (ctx) => ctx.count * ctx.multiplier },
+  on: {
+    INCREMENT: (ctx, _, assign) => assign({ count: ctx.count + 1 }),
+  },
+})
 
-// Send events
-machine.send('OPEN', { isOpen: false, onOpenChange: (v) => { /* ... */ } })
+// Send events (input required)
+machine.send('INCREMENT', { multiplier: 2 })
+
+// Get snapshot
+const snapshot = machine.getSnapshot({ multiplier: 2 })
+console.log(snapshot.count)   // 1
+console.log(snapshot.doubled) // 2
 
 // Evaluate effects
-machine.evaluate(input)
+machine.evaluate({ multiplier: 2 })
 
-// Get computed values
-const computed = machine.getComputed(input)
+// Internal state management
+machine.getInternal()              // { count: 1 }
+machine.setInternal({ count: 0 })  // Reset
+machine.getInitialInternal()       // { count: 0 }
 
-// Cleanup
+// Cleanup effects
 machine.cleanup()
 ```
 
@@ -374,24 +660,36 @@ machine.cleanup()
 
 ### Type Parameters
 
-Specify only what you need:
-
 ```ts
-// Minimal
 createMachine<{
-  input: MyInput
-  events: MyEvents
+  input: { ... }      // External data
+  internal: { ... }   // Machine state
+  events: { ... }     // Event → payload
+  computed: { ... }   // Derived values
+  actions: string     // Named action union
+  guards: string      // Named guard union
+  state: string       // FSM state union
 }>({ ... })
+```
 
-// Full
+**Events type:**
+```ts
+events: {
+  TOGGLE: undefined           // No payload: send('TOGGLE')
+  SET: { value: string }      // With payload: send('SET', { value: 'hello' })
+}
+```
+
+### Key Safety
+
+Duplicate keys across `input`, `internal`, `computed` cause compile error:
+
+```ts
 createMachine<{
-  input: MyInput
-  events: MyEvents
-  computed: MyComputed
-  actions: 'action1' | 'action2'
-  guards: 'guard1' | 'guard2'
-  state: 'idle' | 'active'
+  input: { count: number }
+  internal: { count: string }  // ❌ 'count' key duplicated
 }>({ ... })
+// → Context type becomes 'never', causing error
 ```
 
 ### Exports
@@ -400,13 +698,16 @@ createMachine<{
 import { createMachine, effect } from 'controlled-machine'
 import { useMachine } from 'controlled-machine/react'
 import type {
+  MachineTypes,
   Machine,
+  MachineInstance,
+  Context,
+  Snapshot,
   Send,
-  Rule,
-  Handler,
-  ActionItem,   // Named action or inline function
-  GuardItem,    // Named guard or inline function
-  UseMachineOptions,
+  Input,
+  Internal,
+  Computed,
+  AssignFn,
 } from 'controlled-machine'
 ```