@doeixd/machine 0.0.4 → 0.0.6

package/README.md

@@ -1,8 +1,10 @@
+[![npm version](https://badge.fury.io/js/@doeixd%2Fmachine.svg)](https://badge.fury.io/js/@doeixd%2Fmachine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/doeixd/machine)
 
 # Machine
 
-A minimal, type-safe state machine library for TypeScript built on mathematical foundations.
+A minimal, type-safe state machine library for TypeScript.
 
 > **Philosophy**: Provide minimal primitives that capture the essence of finite state machines, with maximum type safety and flexibility. **Type-State Programming** is our core paradigm—we use TypeScript's type system itself to represent finite states, making illegal states unrepresentable and invalid transitions impossible to write. The compiler becomes your safety net, catching state-related bugs before your code ever runs.
 
@@ -40,7 +42,7 @@ An FSM is a 5-tuple: **M = (S, Σ, δ, s₀, F)** where:
 
 ```typescript
 type Machine<C extends object> = {
-  readonly context: C;  // Encodes the current state (s ∈ S)
+  context: C;  // Encodes the current state (s ∈ S)
 } & Record<string, (...args: any[]) => Machine<any>>; // Transition functions (δ)
 ```
 
@@ -61,6 +63,8 @@ type Machine<C extends object> = {
 
 ### Basic Counter (Simple State)
 
+**Immutable approach (recommended):**
+
 ```typescript
 import { createMachine } from "@doeixd/machine";
 
@@ -84,6 +88,26 @@ console.log(next.context.count); // 1
 console.log(counter.context.count); // 0
 ```
 
+**Mutable approach (also supported):**
+
+```typescript
+// If you prefer mutable state, just return `this`
+const counter = createMachine(
+  { count: 0 },
+  {
+    increment: function() {
+      (this.context as any).count++;
+      return this; // Return same instance
+    }
+  }
+);
+
+counter.increment();
+console.log(counter.context.count); // 1 (mutated in place)
+```
+
+This shows the **flexibility** of the library: immutability is the default pattern because it's safer, but you can choose mutability when it makes sense for your use case.
+
 ### Type-State Programming (Compile-Time State Safety)
 
 The most powerful pattern: different machine types represent different states.
@@ -619,6 +643,462 @@ function enterState(): MachineResult<{ timer: number }> {
 
 ## Advanced Features
 
+### Ergonomic & Integration Patterns
+
+For advanced use cases, the library provides optional patterns that offer better ergonomics and deep framework integration. These are available in @doeixd/machine/multi.
+
+**Runner (createRunner):** A stateful controller that wraps a single machine. It provides a stable actions object (runner.actions.increment()) to eliminate the need for manual state reassignment, which is ideal for complex local state.
+
+**Ensemble (createEnsemble / createMultiMachine):** An orchestration engine that decouples state logic from state storage. It plugs into external stores (like React or Solid state) to create framework-agnostic, global state machines.
+
+### Managed State with Runner & Ensemble
+
+For stateful applications, `@doeixd/machine/multi` provides two advanced patterns that eliminate constant variable reassignment while maintaining immutability:
+
+#### Runner: Stateful Controller for Local State
+
+The `Runner` wraps an immutable machine in a stateful controller, providing stable `actions` object so you can call transitions imperatively without reassigning the machine variable.
+
+```typescript
+import { createRunner } from "@doeixd/machine/multi";
+
+const counterMachine = createCounterMachine({ count: 0 });
+const runner = createRunner(counterMachine, (newState) => {
+  console.log('Count is now:', newState.context.count);
+});
+
+// Call transitions without reassignment - runner updates internally
+runner.actions.increment(); // Logs: "Count is now: 1"
+runner.actions.add(5);      // Logs: "Count is now: 6"
+
+// Access current state
+console.log(runner.context.count); // 6
+console.log(runner.state.context.count); // 6 (full machine)
+
+// Type narrowing works
+if (runner.state.context.status === 'loggedIn') {
+  runner.actions.logout(); // TypeScript knows logout exists
+}
+```
+
+**Benefits:**
+- No more `machine = machine.transition()` reassignment chains
+- Stable `actions` object for clean event handling
+- Perfect for React hooks, component state, or form handling
+- Type-safe state narrowing still works
+
+#### Ensemble: Framework-Agnostic Global State Orchestration
+
+The `Ensemble` decouples state logic (the machine) from state storage, plugging into any state management solution (React hooks, Solid stores, Zustand, Redux, etc.) via a simple `StateStore` interface.
+
+```typescript
+import { createEnsemble } from "@doeixd/machine/multi";
+
+// 1. Define your state store interface
+const store = {
+  getContext: () => sharedContext,
+  setContext: (newCtx) => { sharedContext = newCtx; }
+};
+
+// 2. Define machine factories for each state
+const factories = {
+  idle: (ctx) => createMachine(ctx, {
+    fetch: () => store.setContext({ ...ctx, status: 'loading' })
+  }),
+  loading: (ctx) => createMachine(ctx, {
+    succeed: (data) => store.setContext({ ...ctx, status: 'success', data }),
+    fail: (error) => store.setContext({ ...ctx, status: 'error', error })
+  }),
+  success: (ctx) => createMachine(ctx, {
+    refetch: () => store.setContext({ ...ctx, status: 'loading' })
+  })
+};
+
+// 3. Create the Ensemble with an accessor function for refactoring safety
+const ensemble = createEnsemble(store, factories, (ctx) => ctx.status);
+
+// 4. Use it with type-safe dispatch
+ensemble.actions.fetch();      // Transitions to loading
+console.log(ensemble.context.status); // 'loading'
+
+// Type narrowing
+if (ensemble.state.context.status === 'success') {
+  console.log(ensemble.state.context.data); // TypeScript knows data exists
+}
+```
+
+**Perfect for:**
+- Global application state orchestration
+- Decoupling business logic from framework-specific state management
+- Testing (swap the store for a test stub)
+- Multiple framework support (same machine logic for React, Solid, Vue, etc.)
+
+**Workflow Pattern:**
+```typescript
+// React example
+function MyComponent() {
+  const [context, setContext] = useState(initialContext);
+  
+  const store = { 
+    getContext: () => context,
+    setContext: setContext
+  };
+  
+  const ensemble = useMemo(() => 
+    createEnsemble(store, factories, (ctx) => ctx.status),
+    [context]
+  );
+  
+  return (
+    <div>
+      <p>Status: {ensemble.context.status}</p>
+      <button onClick={() => ensemble.actions.fetch()}>Load Data</button>
+    </div>
+  );
+}
+```
+
+#### Generator-Based Workflows with Runner & Ensemble
+
+Run complex, multi-step workflows imperatively using generators:
+
+```typescript
+import { runWithRunner, runWithEnsemble } from "@doeixd/machine/multi";
+
+// With Runner (local state)
+const result = runWithRunner(function* (runner) {
+  yield runner.actions.increment();
+  yield runner.actions.add(10);
+  if (runner.context.count > 5) {
+    yield runner.actions.reset();
+  }
+  return runner.context;
+}, createCounterMachine());
+
+// With Ensemble (global state)
+const result = runWithEnsemble(function* (ensemble) {
+  yield ensemble.actions.fetch();
+  yield ensemble.actions.process();
+  if (ensemble.context.status === 'success') {
+    yield ensemble.actions.commit();
+  }
+  return ensemble.context.data;
+}, ensemble);
+```
+
+#### Mutable Machine (Experimental)
+
+For non-UI environments where a stable object reference is critical, `createMutableMachine` provides a highly imperative API with direct in-place mutations.
+
+**Key Characteristics:**
+- **Stable Object Reference**: The machine is a single object whose properties mutate in place
+- **Direct Imperative API**: Call transitions like methods (`machine.login('user')`) with immediate updates
+- **No State History**: Previous states are not preserved (no time-travel debugging)
+- **Not for Reactive UIs**: Won't trigger component re-renders in React, Solid, Vue, etc.
+
+**Best for:**
+- Backend services and game loops
+- Complex synchronous scripts and data pipelines
+- Non-UI environments where a stable state object is essential
+
+**Example: Authentication State**
+
+```typescript
+import { createMutableMachine } from "@doeixd/machine/multi";
+
+type AuthContext =
+  | { status: 'loggedOut'; error?: string }
+  | { status: 'loggedIn'; username: string };
+
+const authFactories = {
+  loggedOut: (ctx: AuthContext) => ({
+    context: ctx,
+    login: (username: string) => ({ status: 'loggedIn', username }),
+  }),
+  loggedIn: (ctx: AuthContext) => ({
+    context: ctx,
+    logout: () => ({ status: 'loggedOut' }),
+  }),
+};
+
+const auth = createMutableMachine(
+  { status: 'loggedOut' } as AuthContext,
+  authFactories,
+  (ctx) => ctx.status  // Accessor function - refactor-safe
+);
+
+// Stable reference - keep this, the object will mutate
+const userRef = auth;
+
+console.log(auth.status); // 'loggedOut'
+
+auth.login('alice'); // Mutates in place
+
+console.log(auth.status); // 'loggedIn'
+console.log(auth.username); // 'alice'
+console.log(userRef === auth); // true - same object reference
+```
+
+**Example: Game State Loop**
+
+```typescript
+type PlayerContext = {
+  state: 'idle' | 'walking' | 'attacking';
+  hp: number;
+  position: { x: number; y: number };
+};
+
+const player = createMutableMachine(
+  { state: 'idle', hp: 100, position: { x: 0, y: 0 } },
+  {
+    idle: (ctx) => ({
+      context: ctx,
+      walk: (dx: number, dy: number) => ({
+        ...ctx,
+        state: 'walking',
+        position: { x: ctx.position.x + dx, y: ctx.position.y + dy }
+      }),
+      attack: () => ({ ...ctx, state: 'attacking' }),
+    }),
+    walking: (ctx) => ({
+      context: ctx,
+      stop: () => ({ ...ctx, state: 'idle' }),
+    }),
+    attacking: (ctx) => ({
+      context: ctx,
+      finishAttack: () => ({ ...ctx, state: 'idle' }),
+    }),
+  },
+  (ctx) => ctx.state  // Accessor function - refactor-safe
+);
+
+// Game loop
+player.walk(1, 0);
+console.log(player.position); // { x: 1, y: 0 }
+console.log(player.state); // 'walking'
+
+player.stop();
+console.log(player.state); // 'idle'
+```
+
+⚠️ **Trade-offs**: Breaks immutability principle. Only use when:
+- Working in non-UI environments (backend, CLI, game logic)
+- Stable object reference is critical
+- You accept no reactive UI updates or state history
+
+**Not suitable for**: React, Solid, Vue, or any reactive framework.
+
+#### Comparison: Runner vs Ensemble vs Mutable Machine
+
+| Feature | Runner | Ensemble | Mutable Machine |
+|---------|--------|----------|-----------------|
+| **State Philosophy** | Immutable core with ergonomic wrapper | External immutable state store integration | Mutable in-place context |
+| **Primary Use Case** | Complex local/component state | Global state with framework integration | Backend, game loops, non-UI |
+| **API Style** | `runner.actions.increment()` | `ensemble.actions.increment()` | `machine.increment()` |
+| **UI Frameworks** | ✅ Excellent (React, Solid, Vue) | ✅ Designed for frameworks | ❌ Won't trigger re-renders |
+| **State History** | ✅ Preserved (immutable snapshots) | ✅ Preserved (by external store) | ❌ Lost (mutated in place) |
+| **Object Stability** | Runner reference stable, internal machine changes | Ensemble reference stable, reconstructed per access | ✅ Single object reference |
+| **Time-Travel Debugging** | ✅ Possible | ✅ Possible | ❌ Not possible |
+| **Performance** | Standard | Standard | ✅ Optimal (no allocations) |
+
+**Quick Decision Tree:**
+
+1. **Do you need a UI framework** (React, Solid, Vue)?
+   - **Yes** → Use **Ensemble** if global/shared state, or **Runner** if local/component state
+   - **No** (Backend, game, CLI) → Use **Mutable Machine**
+
+2. **Is state global/shared across your app?**
+   - **Yes** → Use **Ensemble** (hooks into your framework's state manager)
+   - **No** → Use **Runner** (simpler, still immutable)
+
+3. **Do you need immutability for debugging/testing?**
+   - **Yes** → Use **Runner** or **Ensemble**
+   - **No** (performance critical) → Use **Mutable Machine**
+
+##### Deep Dive: Runner (createRunner)
+
+**The Pattern**: A stateful wrapper that handles internal reassignments for you.
+
+```typescript
+// Without Runner (verbose reassignment chain)
+let machine = createCounterMachine();
+machine = machine.increment();
+machine = machine.add(5);
+machine = machine.reset();
+
+// With Runner (stable reference, less boilerplate)
+const runner = createRunner(createCounterMachine());
+runner.actions.increment();
+runner.actions.add(5);
+runner.actions.reset();
+console.log(runner.context); // Access state directly
+```
+
+**How it Works:**
+- Holds a private `currentMachine` variable
+- Wraps each transition method to update `currentMachine` before returning
+- Provides stable `runner.actions` and `runner.context` references
+- The underlying immutable machine is still pure; the Runner just manages the reassignments
+
+**When to Use:**
+- Complex local state (forms, multi-step wizards, component logic)
+- Generator-based workflows (cleaner syntax with `yield runner.actions.xxx()`)
+- You want immutability's safety without constant `machine = machine.xxx()` chains
+- Perfect for React component state or Solid signals
+
+**Analogy**: An automatic transmission. The immutable engine is still doing powerful, pure work. The Runner just handles the "gear shifting" automatically.
+
+##### Deep Dive: Ensemble (createEnsemble)
+
+**The Pattern**: Decouples machine logic from framework-specific state management.
+
+```typescript
+// Your pure machine logic
+const factories = {
+  idle: (ctx) => createMachine(ctx, { fetch: () => { /* ... */ } }),
+  loading: (ctx) => createMachine(ctx, { succeed: (data) => { /* ... */ } }),
+};
+
+// Your framework's state (React example)
+const [context, setContext] = useState(initialContext);
+
+// The Ensemble bridges them - use an accessor function for refactoring safety
+const ensemble = useMemo(() => 
+  createEnsemble(
+    { getContext: () => context, setContext },
+    factories,
+    (ctx) => ctx.status  // Accessor function - fully refactor-safe!
+  ),
+  [context]
+);
+
+// Type-safe dispatch from any part of your app
+ensemble.actions.fetch();
+```
+
+**How it Works:**
+- Takes a `StateStore` (get/set functions) that communicate with your state manager
+- Takes a set of factory functions that create machines for each state
+- When you call `ensemble.actions.fetch()`:
+  1. Gets current context from the store
+  2. Determines the active machine based on discriminant key
+  3. Executes the transition (which calls `store.setContext()` internally)
+  4. Reconstructs the machine with updated context on next access
+
+**When to Use:**
+- Global/application state that multiple components need
+- You want machine logic completely decoupled from your UI framework
+- Testing (swap the store for a test stub)
+- Portable state logic (same machine works with React, Solid, Vue, etc.)
+- Complex state that's read/updated from multiple places in your app
+
+**Analogy**: A custom car build. The machine provides expert logic on "how a car behaves," but you provide the engine (your framework's state manager). Perfect integration, total flexibility.
+
+##### Deep Dive: Mutable Machine (createMutableMachine)
+
+**The Pattern**: A single stable object whose properties mutate in place.
+
+```typescript
+// Single object reference that mutates
+const player = createMutableMachine(
+  { state: 'idle', hp: 100 },
+  factories,
+  (ctx) => ctx.state  // Accessor function - refactor-safe
+);
+
+// Keep the reference - it will always reflect current state
+const playerRef = player;
+
+player.takeDamage(10);
+console.log(playerRef.hp); // 90 - same object!
+console.log(playerRef === player); // true
+```
+
+**How it Works:**
+- Uses a JavaScript Proxy to merge context properties with machine methods
+- Transitions are pure functions that return the next context (not a new machine)
+- When a transition is called, the proxy overwrites the context object's properties in place
+- The object reference never changes; properties mutate
+
+**When to Use:**
+- Backend services (session management, long-running processes)
+- Game development (high-performance loops where allocation matters)
+- CLI tools and scripts (orchestrating steps)
+- Non-UI environments where a stable reference is critical
+- Performance-critical code where garbage collection matters
+
+**Never Use For:**
+- React, Solid, Vue, or any reactive UI framework
+- Anything where you need state history or time-travel debugging
+- Systems where multiple parts read stale references
+
+**Analogy**: A go-kart. Stripped down for performance in a specific environment (the backend). No safety features like immutability, not built for daily-driver complexity, but incredibly direct and efficient on the race track.
+
+#### Class-Based Approach: MultiMachine (createMultiMachine)
+
+For developers who prefer object-oriented patterns, `createMultiMachine` provides a class-based wrapper around the Ensemble pattern.
+
+```typescript
+import { createMultiMachine, MultiMachineBase } from "@doeixd/machine/multi";
+
+type CounterContext = { count: number };
+
+class CounterMachine extends MultiMachineBase<CounterContext> {
+  increment() {
+    this.setContext({ count: this.context.count + 1 });
+  }
+
+  add(n: number) {
+    this.setContext({ count: this.context.count + n });
+  }
+
+  reset() {
+    this.setContext({ count: 0 });
+  }
+}
+
+const store = {
+  getContext: () => ({ count: 0 }),
+  setContext: (ctx) => { /* update your framework's state */ }
+};
+
+const machine = createMultiMachine(CounterMachine, store);
+
+// Direct method calls - feels like traditional OOP
+machine.increment();
+console.log(machine.count); // 1
+
+machine.add(5);
+console.log(machine.count); // 6
+
+machine.reset();
+console.log(machine.count); // 0
+```
+
+**How it Works:**
+- Extend `MultiMachineBase<C>` to define your machine class
+- Methods in the class are your transitions
+- `this.context` gives read-only access to current state
+- `this.setContext()` updates the external store
+- `createMultiMachine()` returns a Proxy that merges context properties with class methods
+
+**When to Use:**
+- You prefer class-based/OOP patterns
+- You want familiar `this` binding and method calls
+- Complex machines with lots of state logic (easier to organize in a class)
+- Integrating with existing OOP codebases
+
+**Benefits vs. Ensemble:**
+- More familiar syntax for OOP developers
+- Methods are co-located with state they manage
+- Can use class constructors for initialization
+- Easier to extend or subclass if needed
+
+**Benefits vs. Runner:**
+- For global/shared state (like Ensemble)
+- Better code organization for complex machines
+- Not limited to immutable snapshots
+
 ### Generator-Based Composition
 
 For complex multi-step workflows, use generator-based composition. This provides an imperative, procedural style while maintaining immutability and type safety.
@@ -685,23 +1165,123 @@ const result = run(function* (m) {
 
 ### React Integration
 
+`@doeixd/machine` offers a full suite of React hooks for everything from simple component state to complex, performance-optimized applications.
+
+Get started by importing the hooks:
 ```typescript
+import { useMachine, useMachineSelector } from '@doeixd/machine/react';
+```
+
+#### `useMachine` - For Local Component State
+
+This is the primary hook for managing self-contained state within a component. It returns the reactive `machine` instance and a stable `actions` object for triggering transitions, providing an ergonomic and type-safe API.
+
+```tsx
 import { useMachine } from "@doeixd/machine/react";
+import { createCounterMachine } from "./counterMachine";
 
 function Counter() {
-  const [machine, dispatch] = useMachine(() => createCounterMachine());
+  const [machine, actions] = useMachine(() => createCounterMachine({ count: 0 }));
 
   return (
     <div>
       <p>Count: {machine.context.count}</p>
-      <button onClick={() => dispatch({ type: "increment", args: [] })}>
-        Increment
-      </button>
+      {/* Call transitions directly from the stable actions object */}
+      <button onClick={() => actions.increment()}>Increment</button>
+      <button onClick={() => actions.add(5)}>Add 5</button>
+    </div>
+  );
+}
+```
+
+#### `useMachineSelector` - For Performance
+
+To prevent unnecessary re-renders in components that only care about a small part of a large machine's state, use `useMachineSelector`. It subscribes a component to a specific slice of the state, and only triggers a re-render when that slice changes.
+
+```tsx
+function UserNameDisplay({ machine }) {
+  // This component will NOT re-render if other parts of the machine's
+  // context (e.g., user settings) change.
+  const userName = useMachineSelector(machine, (m) => m.context.user.name);
+
+  return <p>User: {userName}</p>;
+}
+```
+
+#### `createMachineContext` - For Sharing State
+
+To avoid passing your machine and actions through many layers of props ("prop-drilling"), `createMachineContext` provides a typed Context `Provider` and consumer hooks to share state across your component tree.
+
+```tsx
+import { createMachineContext, useMachine } from "@doeixd/machine/react";
+
+// 1. Create the context
+const { Provider, useSelector, useMachineActions } = createMachineContext<AuthMachine>();
+
+// 2. Provide the machine in your root component
+function App() {
+  const [machine, actions] = useMachine(() => createAuthMachine());
+  return (
+    <Provider machine={machine} actions={actions}>
+      <Header />
+    </Provider>
+  );
+}
+
+// 3. Consume it in any child component
+function Header() {
+  const status = useSelector(m => m.context.status);
+  const actions = useMachineActions();
+
+  return (
+    <header>
+      {status === 'loggedIn' ? (
+        <button onClick={() => actions.logout()}>Logout</button>
+      ) : (
+        <button onClick={() => actions.login('user', 'pass')}>Login</button>
+      )}
+    </header>
+  );
+}
+```
+
+#### `useEnsemble` - For Advanced Integration
+
+For maximum testability and portability, `useEnsemble` decouples your pure, framework-agnostic state logic from React's state management. Your machine logic becomes fully portable, and React's `useState` simply acts as the "state store" for the ensemble.
+
+```tsx
+import { useEnsemble } from "@doeixd/machine/react";
+import { fetchFactories } from "./fetchFactories"; // Pure, framework-agnostic logic
+
+function DataFetcher() {
+  const ensemble = useEnsemble(
+    { status: 'idle', data: null }, // Initial context
+    fetchFactories, // Your pure machine factories
+    (ctx) => ctx.status // Discriminant function
+  );
+
+  return (
+    <div>
+      <p>Status: {ensemble.context.status}</p>
+      {ensemble.context.status === 'idle' && (
+        <button onClick={() => ensemble.actions.fetch('/api/data')}>
+          Fetch
+        </button>
+      )}
     </div>
   );
 }
 ```
 
+#### Which Hook Should I Use?
+
+| Hook | Best For | Key Feature |
+| :--- | :--- | :--- |
+| **`useMachine`** | **Local component state** | The simplest way to get started. Ergonomic `[machine, actions]` API. |
+| **`useMachineSelector`** | **Performance optimization** | Prevents re-renders by subscribing to slices of state. |
+| **`createMachineContext`** | **Sharing state / DI** | Avoids prop-drilling a machine through the component tree. |
+| **`useEnsemble`** | **Complex or shared state** | Decouples business logic from React for maximum portability and testability. |
+
 ### Solid.js Integration
 
 Comprehensive Solid.js integration with signals, stores, and fine-grained reactivity:
@@ -884,6 +1464,269 @@ pipeTransitions(
 );
 ```
 
+## 📊 Statechart Extraction & Visualization
+
+**NEW**: Generate formal statechart definitions from your TypeScript machines for visualization and documentation.
+
+### Overview
+
+The statechart extraction system performs build-time static analysis to generate [XState](https://xstate.js.org/)-compatible JSON from your type-safe machines. This enables:
+
+- 🎨 **Visualization** in [Stately Viz](https://stately.ai/viz) and other tools
+- 📖 **Documentation** with auto-generated state diagrams
+- ✅ **Formal verification** using XState tooling
+- 🔄 **Team communication** via visual state charts
+
+### Quick Example
+
+**1. Annotate your machines with metadata:**
+
+```typescript
+import { MachineBase } from '@doeixd/machine';
+import { transitionTo, describe, action, guarded } from '@doeixd/machine/primitives';
+
+class LoggedOut extends MachineBase<{ status: 'loggedOut' }> {
+  login = describe(
+    "Start the login process",
+    action(
+      { name: "logAttempt", description: "Track login attempts" },
+      transitionTo(LoggingIn, (username: string) => new LoggingIn({ username }))
+    )
+  );
+}
+
+class LoggingIn extends MachineBase<{ status: 'loggingIn'; username: string }> {
+  success = transitionTo(LoggedIn, (token: string) => new LoggedIn({ token }));
+  failure = transitionTo(LoggedOut, () => new LoggedOut());
+}
+
+class LoggedIn extends MachineBase<{ status: 'loggedIn'; token: string }> {
+  logout = describe(
+    "Log out and clear session",
+    action(
+      { name: "clearSession" },
+      transitionTo(LoggedOut, () => new LoggedOut())
+    )
+  );
+
+  deleteAccount = guarded(
+    { name: "isAdmin", description: "Only admins can delete accounts" },
+    transitionTo(LoggedOut, () => new LoggedOut())
+  );
+}
+```
+
+**2. Create extraction config (`.statechart.config.ts`):**
+
+```typescript
+import type { ExtractionConfig } from '@doeixd/machine';
+
+export default {
+  machines: [{
+    input: 'src/auth.ts',
+    classes: ['LoggedOut', 'LoggingIn', 'LoggedIn'],
+    output: 'statecharts/auth.json',
+    id: 'auth',
+    initialState: 'LoggedOut'
+  }],
+  verbose: true
+} satisfies ExtractionConfig;
+```
+
+**3. Run extraction:**
+
+```bash
+npm run extract
+```
+
+**4. Generated output (`statecharts/auth.json`):**
+
+```json
+{
+  "id": "auth",
+  "initial": "LoggedOut",
+  "states": {
+    "LoggedOut": {
+      "on": {
+        "login": {
+          "target": "LoggingIn",
+          "description": "Start the login process",
+          "actions": ["logAttempt"]
+        }
+      }
+    },
+    "LoggingIn": {
+      "on": {
+        "success": { "target": "LoggedIn" },
+        "failure": { "target": "LoggedOut" }
+      }
+    },
+    "LoggedIn": {
+      "on": {
+        "logout": {
+          "target": "LoggedOut",
+          "description": "Log out and clear session",
+          "actions": ["clearSession"]
+        },
+        "deleteAccount": {
+          "target": "LoggedOut",
+          "cond": "isAdmin"
+        }
+      }
+    }
+  }
+}
+```
+
+**5. Visualize in [Stately Viz](https://stately.ai/viz):**
+
+Paste the JSON into Stately Viz to see your state machine as an interactive diagram!
+
+### Metadata Primitives
+
+The extraction system recognizes these annotation primitives:
+
+| Primitive | Purpose | Extracted As |
+|-----------|---------|--------------|
+| `transitionTo(Target, impl)` | Declare target state | `"target": "TargetClass"` |
+| `describe(text, transition)` | Add description | `"description": "..."` |
+| `guarded(guard, transition)` | Add guard condition | `"cond": "guardName"` |
+| `action(action, transition)` | Add side effect | `"actions": ["actionName"]` |
+| `invoke(service, impl)` | Async service | `"invoke": [...]` |
+
+**All primitives are identity functions** - they have **zero runtime overhead**. They exist purely for:
+1. Type-level documentation
+2. Build-time extraction
+3. IDE autocomplete
+
+### CLI Usage
+
+```bash
+# Extract from config
+npx tsx scripts/extract-statechart.ts --config .statechart.config.ts
+
+# Extract single machine
+npx tsx scripts/extract-statechart.ts \
+  --input src/machine.ts \
+  --id myMachine \
+  --classes State1,State2 \
+  --initial State1
+
+# Watch mode
+npx tsx scripts/extract-statechart.ts --config .statechart.config.ts --watch
+
+# With validation
+npx tsx scripts/extract-statechart.ts --config .statechart.config.ts --validate
+```
+
+### npm Scripts
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "extract": "tsx scripts/extract-statechart.ts --config .statechart.config.ts",
+    "extract:watch": "tsx scripts/extract-statechart.ts --config .statechart.config.ts --watch"
+  }
+}
+```
+
+### How It Works
+
+The extraction system uses **AST-based static analysis**:
+
+1. **Parse TypeScript source** using ts-morph (TypeScript Compiler API)
+2. **Find DSL primitive calls** in class property initializers
+3. **Extract literal arguments** from the Abstract Syntax Tree
+4. **Resolve class name identifiers** to target states
+5. **Generate XState-compatible JSON** with full metadata
+
+**Why AST-based?** TypeScript's type system resolves generic parameters in branded types (`WithMeta<F, M>`) as constraints rather than concrete values. AST parsing reads the actual source code, bypassing type system limitations. This is the same approach used by XState's extraction tooling.
+
+### Static Extraction API (Build-Time)
+
+```typescript
+import { extractMachine, extractMachines } from '@doeixd/machine';
+import { Project } from 'ts-morph';
+
+// Extract single machine
+const project = new Project();
+project.addSourceFilesAtPaths('src/**/*.ts');
+
+const chart = extractMachine({
+  input: 'src/auth.ts',
+  classes: ['LoggedOut', 'LoggedIn'],
+  id: 'auth',
+  initialState: 'LoggedOut'
+}, project);
+
+console.log(JSON.stringify(chart, null, 2));
+
+// Extract multiple machines
+const charts = extractMachines({
+  machines: [
+    { input: 'src/auth.ts', classes: [...], id: 'auth', initialState: 'LoggedOut' },
+    { input: 'src/fetch.ts', classes: [...], id: 'fetch', initialState: 'Idle' }
+  ],
+  verbose: true
+});
+```
+
+### Runtime Extraction API
+
+Extract statecharts from **running machine instances** without requiring source code access:
+
+```typescript
+import { generateStatechart, extractFromInstance } from '@doeixd/machine';
+
+// Create machine instances (annotated with DSL primitives)
+const loggedOutMachine = new LoggedOut({ status: 'loggedOut' });
+const loggedInMachine = new LoggedIn({ status: 'loggedIn', token: 'abc' });
+
+// Generate complete statechart from multiple states
+const chart = generateStatechart({
+  LoggedOut: loggedOutMachine,
+  LoggedIn: loggedInMachine
+}, {
+  id: 'auth',
+  initial: 'LoggedOut'
+});
+
+// Or extract from a single instance
+const singleChart = extractFromInstance(loggedOutMachine, {
+  id: 'auth',
+  stateName: 'LoggedOut'
+});
+```
+
+**Use cases:**
+- 🐛 Debug production machines without source access
+- 🌐 Extract statecharts in browser DevTools
+- 🧪 Generate diagrams from test instances
+- 📦 Work with dynamically created machines
+
+The DSL primitives (`transitionTo`, `describe`, etc.) attach metadata at runtime via non-enumerable Symbols with zero performance overhead.
+
+### Full Documentation
+
+For comprehensive documentation including:
+- Type-level metadata DSL reference
+- Configuration options
+- Limitations and gotchas
+- Troubleshooting guide
+- Advanced usage patterns
+
+See **[docs/statechart-extraction.md](./docs/statechart-extraction.md)**
+
+### Examples
+
+Complete annotated examples in the `examples/` directory:
+- [`examples/authMachine.ts`](./examples/authMachine.ts) - Authentication flow with guards and actions
+- [`examples/fetchMachine.ts`](./examples/fetchMachine.ts) - Data fetching with invoke services
+- [`examples/formMachine.ts`](./examples/formMachine.ts) - Multi-step wizard
+- [`examples/trafficLightMachine.ts`](./examples/trafficLightMachine.ts) - Simple cyclic machine
+
 ## Philosophy & Design Principles
 
 ### 1. Type-State Programming First
@@ -899,13 +1742,7 @@ This isn't just a feature—it's the fundamental way you should think about stat
 
 ### 2. Minimal Primitives
 
-The core library provides only the essential building blocks:
-- `Machine<C>` and `AsyncMachine<C>` types
-- `createMachine()` and `createAsyncMachine()` functions
-- `runMachine()` for async runtime
-- Basic composition utilities
-
-Everything else is built on top of these primitives. We give you the foundation; you build what you need.
+The core library provides one true primitive: the pure, immutable Machine. Everything else is built on this foundation. To handle real-world complexity, we provide optional factories (createRunner, createEnsemble) that compose this primitive into different operational patterns. This keeps the core minimal while providing powerful, opt-in capabilities for ergonomics and framework integration.
 
 ### 3. TypeScript as the Compiler
 
@@ -1061,6 +1898,108 @@ runAsync<C, T>(flow: (m: Machine<C>) => AsyncGenerator<...>, initial: Machine<C>
 stepAsync<C>(machine: Machine<C>): AsyncGenerator<...>
 ```
 
+### Multi Module (Stateful Controllers & Framework Integration)
+
+**Import:** `import { ... } from "@doeixd/machine/multi"`
+
+#### Types
+
+```typescript
+// Stateful controller for a single machine
+type Runner<M extends Machine<any>> = {
+  readonly state: M;
+  readonly context: Context<M>;
+  readonly actions: BoundTransitions<M>;
+  setState(newState: M): void;
+};
+
+// Mapped type: all transition methods pre-bound to update a Runner
+type BoundTransitions<M extends Machine<any>> = {
+  [K in TransitionNames<M>]: (...args: TransitionArgs<M, K>) => ReturnType<M[K]>;
+};
+
+// External state storage interface for Ensemble
+interface StateStore<C extends object> {
+  getContext: () => C;
+  setContext: (newContext: C) => void;
+}
+
+// Orchestration engine for global state
+type Ensemble<AllMachines extends Machine<any>, C extends object> = {
+  readonly context: C;
+  readonly state: AllMachines;
+  readonly actions: AllTransitions<AllMachines>;
+};
+```
+
+#### Functions
+
+```typescript
+// Create a stateful wrapper for local state management
+createRunner<M extends Machine<any>>(
+  initialMachine: M,
+  onChange?: (newState: M) => void
+): Runner<M>
+
+// Create an ensemble for framework-agnostic global state orchestration
+createEnsemble<
+  C extends object,
+  F extends Record<string, (context: C) => Machine<C>>
+>(
+  store: StateStore<C>,
+  factories: F,
+  getDiscriminant: (context: C) => keyof F  // Accessor function - refactor-safe
+): Ensemble<ReturnType<F[keyof F]>, C>
+
+// Execute a generator workflow with a Runner
+runWithRunner<M extends Machine<any>, T>(
+  flow: (runner: Runner<M>) => Generator<any, T, any>,
+  initialMachine: M
+): T
+
+// Execute a generator workflow with an Ensemble
+runWithEnsemble<AllMachines extends Machine<any>, C extends object, T>(
+  flow: (ensemble: Ensemble<AllMachines, C>) => Generator<any, T, any>,
+  ensemble: Ensemble<AllMachines, C>
+): T
+
+// Create a mutable machine (EXPERIMENTAL - use with caution)
+createMutableMachine<
+  C extends object,
+  F extends Record<string, (context: C) => Machine<C>>
+>(
+  sharedContext: C,
+  factories: F,
+  getDiscriminant: (context: C) => keyof F  // Accessor function - refactor-safe
+): MutableMachine<C, ReturnType<F[keyof F]>>
+```
+
+#### Additional Types (Multi Module)
+
+```typescript
+// Mutable machine combining context and transitions (EXPERIMENTAL)
+type MutableMachine<C extends object, AllMachines extends Machine<any>> = C &
+  AllTransitions<AllMachines>;
+
+// Base class for MultiMachine OOP approach
+abstract class MultiMachineBase<C extends object> {
+  protected store: StateStore<C>;
+  protected get context(): C;
+  protected setContext(newContext: C): void;
+}
+```
+
+#### Additional Functions (Multi Module)
+
+```typescript
+// Create a class-based MultiMachine instance
+createMultiMachine<C extends object, T extends MultiMachineBase<C>>(
+  MachineClass: new (store: StateStore<C>) => T,
+  store: StateStore<C>,
+  getDiscriminant?: (context: C) => string  // Optional accessor function - refactor-safe
+): C & T
+```
+
 ## License
 
 MIT