@xmachines/docs 1.0.0-beta.10

package/examples/traffic-light.md

@@ -0,0 +1,99 @@
+# Traffic Light State Machine
+
+Multi-state machine with automatic transitions demonstrating cyclic state flows.
+
+## Use Case
+
+This example models a traffic light with a red → green → yellow → red cycle. It demonstrates how to handle multiple states with cyclic transitions, making it useful for:
+
+- Traffic light controllers
+- Multi-step workflows with repeating cycles
+- Game state loops (menu → playing → game over → menu)
+- Carousel or slideshow controls
+
+## Complete Code
+
+```typescript
+import { createMachine } from "xstate";
+
+// Define states
+type TrafficState = "red" | "yellow" | "green";
+
+// Define events
+type TrafficEvent = { type: "TIMER" };
+
+// Create machine
+const trafficMachine = createMachine<TrafficState, TrafficEvent>({
+	id: "traffic",
+	initial: "red",
+	states: {
+		red: {
+			on: {
+				TIMER: "green",
+			},
+		},
+		green: {
+			on: {
+				TIMER: "yellow",
+			},
+		},
+		yellow: {
+			on: {
+				TIMER: "red",
+			},
+		},
+	},
+});
+
+// Usage with timer
+let state = trafficMachine.initialState;
+console.log(state); // 'red'
+
+// Simulate automatic transitions
+setInterval(() => {
+	state = trafficMachine.transition(state, { type: "TIMER" });
+	console.log(`Light changed to: ${state}`);
+}, 3000); // Change every 3 seconds
+```
+
+## Code Explanation
+
+1. **Multiple states** - Defines three distinct states (`'red'`, `'yellow'`, `'green'`) instead of just two, showing how state machines scale beyond binary toggles.
+
+2. **Cyclic transitions** - Each state transitions to the next state in the cycle when receiving a `TIMER` event, creating a continuous loop.
+
+3. **Timer integration** - Uses `setInterval` to automatically trigger state transitions, demonstrating how external timing mechanisms integrate with state machines.
+
+4. **Deterministic behavior** - No matter how many cycles complete, the state is always predictable based on the number of `TIMER` events received.
+
+## Key Concepts
+
+- **Multi-state machines**: Not limited to two states - model complex workflows with many states
+- **Cyclic transitions**: States can form loops, returning to previous states in a predictable pattern
+- **External triggers**: State machines react to external events like timers, user actions, or network responses
+- **Deterministic**: Same sequence of events always produces the same sequence of states
+
+## Variations
+
+**Different timing per state:**
+
+```typescript
+const timings = { red: 5000, green: 4000, yellow: 2000 };
+let state = trafficMachine.initialState;
+
+function scheduleNext() {
+	setTimeout(() => {
+		state = trafficMachine.transition(state, { type: "TIMER" });
+		console.log(`Light: ${state}`);
+		scheduleNext();
+	}, timings[state]);
+}
+
+scheduleNext();
+```
+
+## Next Steps
+
+- **[Form Validation Example](form-validation.md)** - Learn about guards and conditional transitions
+- **[Basic State Machine](basic-state-machine.md)** - Return to foundational concepts
+- **[API Documentation](/docs/api/xmachines/play/readme)** - Explore advanced features like actions and context

package/guides/README.md

@@ -0,0 +1,29 @@
+# XMachines Guides
+
+Entry points for current XMachines Play architecture and package documentation.
+
+## Start Here
+
+- [Root README](../../README.md) - Monorepo overview and architecture invariants
+- [Examples Index](../examples/README.md) - Runnable and conceptual usage patterns
+
+## Router Adapter Guides
+
+Use these READMEs for the current RouterBridge-first integrations:
+
+- [@xmachines/play-router](../../packages/play-router/README.md) - Route extraction, route maps, and `RouterBridgeBase`
+- [@xmachines/play-tanstack-react-router](../../packages/play-tanstack-react-router/README.md) - TanStack React adapter
+- [@xmachines/play-react-router](../../packages/play-react-router/README.md) - `react-router` v7 data-router adapter
+- [@xmachines/play-tanstack-solid-router](../../packages/play-tanstack-solid-router/README.md) - TanStack Solid adapter
+- [@xmachines/play-solid-router](../../packages/play-solid-router/README.md) - SolidJS Router adapter
+- [@xmachines/play-vue-router](../../packages/play-vue-router/README.md) - Vue Router adapter
+
+## Core Runtime Guides
+
+- [@xmachines/play-xstate](../../packages/play-xstate/README.md) - `definePlayer`, routing transitions, and actor lifecycle
+- [@xmachines/play-react](../../packages/play-react/README.md) - React rendering from actor-driven view state
+- [@xmachines/play-catalog](../../packages/play-catalog/README.md) - Catalog and schema contracts
+
+## API Reference
+
+- [/docs/api](/docs/api) - Generated API docs for all public packages

package/guides/getting-started.md

@@ -0,0 +1,223 @@
+# Getting Started
+
+Welcome to XMachines! This guide will help you understand what XMachines is and get you up and running with your first state machine.
+
+## What is XMachines?
+
+XMachines is a TypeScript implementation of the Universal Player Architecture—a state machine library that strictly separates business logic from infrastructure. It enables logic-driven applications where state machines control routing, views, and navigation through standardized TC39 Signals.
+
+At its core, XMachines is built on the actor model, following the principle that **business logic must be the single source of truth** for navigation, state, and UI structure. Infrastructure reflects actor state—it never decides.
+
+Unlike traditional frameworks where your logic adapts to the framework, XMachines inverts this relationship. Your state machines own the application behavior, and the infrastructure (routers, view renderers, React components) passively observes and reflects the current state through signals. This results in complete runtime agnosticism—your logic has zero framework dependencies.
+
+## Why XMachines?
+
+**Type Safety with TypeScript**
+
+- Full type inference from state machine catalog through to components
+- Catch navigation errors and state bugs at compile time
+- Zod validation for UI schemas and state structures
+
+**Predictable State Management**
+
+- State machines make application behavior explicit and testable
+- Actor model ensures clear message passing patterns
+- Guard enforcement prevents invalid state transitions
+
+**Platform Flexibility**
+
+- Runtime-agnostic core packages work in browser, Node, or Deno
+- Choose only the packages you need for your platform
+- Framework integrations (React, TanStack Router) are optional adapters
+
+**Modular Architecture**
+
+- 8 focused packages that work together seamlessly
+- `@xmachines/play` foundation works with any infrastructure
+- Mix and match adapters based on your stack
+
+## Quick Start
+
+### Installation
+
+First, install XMachines packages. See the complete [Installation →](installation.md) guide for all package managers and environments.
+
+```bash
+npm install @xmachines/play @xmachines/play-xstate
+```
+
+### Import and Create Your First Machine
+
+```typescript
+import { createMachine } from "@xmachines/play-xstate";
+
+// Define a simple traffic light machine
+const trafficLightMachine = createMachine({
+	id: "trafficLight",
+	initial: "red",
+	states: {
+		red: {
+			on: { TIMER: "green" },
+		},
+		green: {
+			on: { TIMER: "yellow" },
+		},
+		yellow: {
+			on: { TIMER: "red" },
+		},
+	},
+});
+```
+
+### Create an Actor and Transition States
+
+```typescript
+import { createActor } from "@xmachines/play-actor";
+
+// Instantiate the machine as an actor
+const actor = createActor(trafficLightMachine);
+
+// Start the actor
+actor.start();
+
+// Check initial state
+console.log(actor.getSnapshot().value); // "red"
+
+// Send events to transition states
+actor.send({ type: "TIMER" });
+console.log(actor.getSnapshot().value); // "green"
+
+actor.send({ type: "TIMER" });
+console.log(actor.getSnapshot().value); // "yellow"
+```
+
+### Observe State Changes with Signals
+
+```typescript
+import { signal, computed } from "@xmachines/play-signals";
+
+// Create a signal to track actor state
+const currentState = signal(actor.getSnapshot().value);
+
+// Subscribe to actor changes
+actor.subscribe((snapshot) => {
+	currentState.value = snapshot.value;
+});
+
+// Create computed values
+const canProceed = computed(() => currentState.value === "green");
+
+console.log(canProceed.value); // true when light is green
+```
+
+## Your First Machine: Toggle Example
+
+Here's a complete working example that demonstrates the core concepts:
+
+```typescript
+import { createMachine } from "@xmachines/play-xstate";
+import { createActor } from "@xmachines/play-actor";
+import { signal } from "@xmachines/play-signals";
+
+// Define the machine configuration
+const toggleMachine = createMachine(
+	{
+		id: "toggle",
+		initial: "inactive",
+		context: {
+			count: 0,
+		},
+		states: {
+			inactive: {
+				on: {
+					TOGGLE: {
+						target: "active",
+						actions: "incrementCount",
+					},
+				},
+			},
+			active: {
+				on: {
+					TOGGLE: {
+						target: "inactive",
+						actions: "incrementCount",
+					},
+				},
+			},
+		},
+	},
+	{
+		actions: {
+			incrementCount: ({ context }) => ({
+				count: context.count + 1,
+			}),
+		},
+	},
+);
+
+// Create and start the actor
+const toggleActor = createActor(toggleMachine);
+toggleActor.start();
+
+// Bind to a signal for reactive updates
+const state = signal(toggleActor.getSnapshot());
+
+toggleActor.subscribe((snapshot) => {
+	state.value = snapshot;
+});
+
+// Use the machine
+toggleActor.send({ type: "TOGGLE" });
+console.log(state.value.value); // "active"
+console.log(state.value.context.count); // 1
+
+toggleActor.send({ type: "TOGGLE" });
+console.log(state.value.value); // "inactive"
+console.log(state.value.context.count); // 2
+```
+
+### Understanding the Parts
+
+**States**: Discrete modes your application can be in (`inactive`, `active`)
+
+**Events**: Messages that trigger transitions (`TOGGLE`)
+
+**Transitions**: Rules that define which events move between which states (`on: { TOGGLE: 'active' }`)
+
+**Context**: Extended state data that persists across transitions (`count: 0`)
+
+**Actions**: Side effects or context updates executed during transitions (`incrementCount`)
+
+**Actor**: Runtime instance of a machine that processes events and emits state changes
+
+**Signals**: Reactive primitives (TC39 Signals) that enable infrastructure to observe state changes without coupling
+
+## Next Steps
+
+Now that you understand the basics, explore these resources:
+
+**Core Documentation**
+
+- [Core Concepts](/docs/api/guides/core-concepts) - Deep dive into architecture and patterns
+- [Package Overview](/docs/api/guides/package-overview) - Choose the right packages for your needs
+- [API Reference](/docs/api/xmachines/play/readme) - Detailed API documentation
+
+**Platform Guides**
+
+- [React Integration](/docs/api/xmachines/play-react/readme) - Use XMachines with React
+- [Router Integration](/docs/api/xmachines/play-tanstack-react-router/readme) - Logic-driven routing with TanStack Router
+- [UI Schemas](/docs/api/xmachines/play-ui/readme) - Define UI structure from state
+
+**Examples**
+
+- [Examples Directory](/examples) - More code examples and usage patterns
+- Working dashboard demo (coming soon)
+
+**Architecture**
+
+- [RFC Specification](/rfc) - Complete architectural specification
+- [Architecture Docs](/architecture) - System design and technical decisions
+
+---
+
+**Ready to install?** → [Installation Guide](installation.md)

package/guides/installation.md

@@ -0,0 +1,323 @@
+# Installation
+
+This guide covers installing XMachines packages in your project across different package managers and environments.
+
+## Prerequisites
+
+Before installing XMachines, ensure you have:
+
+- **Node.js 22+** (or compatible runtime)
+- **Package manager**: npm, pnpm, or yarn
+- **TypeScript** (optional but recommended for full type safety)
+
+## Installing XMachines
+
+Choose your preferred package manager:
+
+### npm
+
+```bash
+npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+```
+
+### pnpm
+
+```bash
+pnpm add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+```
+
+### yarn
+
+```bash
+yarn add @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+```
+
+## Package Selection Guide
+
+XMachines consists of 8 modular packages. Choose the packages based on your needs:
+
+### Core Packages (Required)
+
+**@xmachines/play**
+
+- Foundation package with core protocols and contracts
+- Required by all other packages
+
+**@xmachines/play-actor**
+
+- Abstract actor base class extending XState Actor
+- Required for instantiating state machines
+
+**@xmachines/play-signals**
+
+- TC39 Signals polyfill for reactive updates
+- Required for reactive state observation
+
+**@xmachines/play-xstate**
+
+- XState v5 logic adapter with catalog binding
+- Required for state machine definitions
+
+**Minimal installation:**
+
+```bash
+npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+```
+
+### UI and Routing (Optional)
+
+**@xmachines/play-ui**
+
+- UI schema protocol with Zod validation
+- Install if: Building declarative UI structures from state
+
+**@xmachines/play-router**
+
+- Route tree protocol and machine crawler
+- Install if: Implementing logic-driven routing
+
+**@xmachines/play-tanstack-react-router**
+
+- TanStack Router adapter with signal observation
+- Install if: Using TanStack Router for navigation
+
+**@xmachines/play-react**
+
+- React view renderer with JSON-Render
+- Install if: Building React applications
+
+**@xmachines/play-catalog**
+
+- State machine catalog and registry patterns
+- Install if: Managing multiple machines with type inference
+
+### Complete Installation
+
+For full-featured development with React and routing:
+
+```bash
+npm install @xmachines/play @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/play-ui @xmachines/play-router @xmachines/play-tanstack-react-router @xmachines/play-react @xmachines/play-catalog
+```
+
+**See also:** [Package Overview](/docs/api/guides/package-overview) for detailed descriptions of each package.
+
+## Environment-Specific Setup
+
+### Browser (Vite, Webpack, or other bundlers)
+
+No special configuration needed. ESM imports work out of the box:
+
+```typescript
+import { createMachine } from "@xmachines/play-xstate";
+import { createActor } from "@xmachines/play-actor";
+import { signal } from "@xmachines/play-signals";
+```
+
+Most modern bundlers (Vite, Webpack 5+, Rollup) handle ESM packages automatically.
+
+### Node.js
+
+XMachines uses ESM (ECMAScript Modules) exclusively. Ensure your project is configured for ESM:
+
+**Option 1: Set `"type": "module"` in package.json**
+
+```json
+{
+	"type": "module",
+	"dependencies": {
+		"@xmachines/play": "^1.0.0"
+	}
+}
+```
+
+**Option 2: Use `.mjs` file extensions**
+
+Alternatively, name your files with `.mjs` extension:
+
+```bash
+node my-app.mjs
+```
+
+**Import example:**
+
+```typescript
+import { createMachine } from "@xmachines/play-xstate";
+import { createActor } from "@xmachines/play-actor";
+
+const machine = createMachine({
+	id: "example",
+	initial: "idle",
+	states: {
+		idle: { on: { START: "running" } },
+		running: { on: { STOP: "idle" } },
+	},
+});
+
+const actor = createActor(machine);
+actor.start();
+```
+
+### Deno
+
+XMachines works with Deno via npm specifiers:
+
+```typescript
+import { createMachine } from "npm:@xmachines/play-xstate";
+import { createActor } from "npm:@xmachines/play-actor";
+import { signal } from "npm:@xmachines/play-signals";
+```
+
+Alternatively, use a CDN like esm.sh:
+
+```typescript
+import { createMachine } from "https://esm.sh/@xmachines/play-xstate";
+```
+
+### TypeScript
+
+XMachines is written in TypeScript and includes built-in type definitions. No separate `@types` package is needed.
+
+**Recommended tsconfig.json settings:**
+
+```json
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": false,
+		"resolveJsonModule": true
+	}
+}
+```
+
+**Key settings:**
+
+- **`moduleResolution: "bundler"`** (recommended) or `"node16"` for Node.js projects
+- **`strict: true`** enables full type checking
+- **`target: "ESNext"`** leverages modern JavaScript features
+
+**Type inference:**
+
+XMachines provides full type inference from machine catalog through to components:
+
+```typescript
+import { createMachine } from "@xmachines/play-xstate";
+
+const machine = createMachine({
+	id: "typed",
+	initial: "idle",
+	context: { count: 0 },
+	states: {
+		idle: { on: { START: "running" } },
+		running: { on: { STOP: "idle" } },
+	},
+});
+
+// TypeScript infers exact state types
+type States = typeof machine.states; // "idle" | "running"
+```
+
+## Verifying Installation
+
+Test your installation with this simple script:
+
+**test.ts** (or test.js with `"type": "module"`):
+
+```typescript
+import { createMachine } from "@xmachines/play-xstate";
+import { createActor } from "@xmachines/play-actor";
+
+const machine = createMachine({
+	id: "test",
+	initial: "ready",
+	states: {
+		ready: {},
+	},
+});
+
+const actor = createActor(machine);
+actor.start();
+
+console.log("✓ XMachines installed successfully");
+console.log("Current state:", actor.getSnapshot().value);
+```
+
+**Run the test:**
+
+```bash
+# TypeScript (requires tsx or ts-node)
+npx tsx test.ts
+
+# Or compile first
+npx tsc test.ts && node test.js
+
+# JavaScript (with "type": "module")
+node test.js
+```
+
+**Expected output:**
+
+```
+✓ XMachines installed successfully
+Current state: ready
+```
+
+## Troubleshooting
+
+### Module Not Found
+
+**Error:** `Cannot find module '@xmachines/play-xstate'`
+
+**Solutions:**
+
+- Verify package is installed: `npm list @xmachines/play-xstate`
+- Re-install dependencies: `npm install`
+- Check `node_modules/@xmachines/` directory exists
+
+### ESM Import Errors
+
+**Error:** `SyntaxError: Cannot use import statement outside a module`
+
+**Solutions:**
+
+- Add `"type": "module"` to package.json
+- Or rename files to `.mjs` extension
+- Or use dynamic import: `const { createMachine } = await import('@xmachines/play-xstate')`
+
+### Type Errors
+
+**Error:** `Could not find a declaration file for module '@xmachines/play-xstate'`
+
+**Solutions:**
+
+- Types are built-in; no `@types` package needed
+- Check TypeScript version (4.5+ required)
+- Verify `moduleResolution` in tsconfig.json is set correctly
+- Try `npm install` again to ensure types are properly linked
+
+### Version Mismatches
+
+**Error:** Type incompatibilities between packages
+
+**Solution:**
+Install all XMachines packages with matching major versions:
+
+```bash
+npm install @xmachines/play@latest @xmachines/play-xstate@latest @xmachines/play-actor@latest @xmachines/play-signals@latest
+```
+
+## Next Steps
+
+Now that XMachines is installed, you're ready to build your first state machine:
+
+- **[Getting Started →](getting-started.md)** - Build your first state machine
+- **[Core Concepts](/docs/api/guides/core-concepts)** - Understand the architecture
+- **[Package Overview](/docs/api/guides/package-overview)** - Deep dive into each package
+- **[Examples](/examples)** - See XMachines in action
+
+---
+
+**Need help?** Check the [Architecture Documentation](/architecture) or [API Reference](/docs/api) for detailed information.

package/index.d.ts

@@ -0,0 +1,3 @@
+declare const url: string;
+
+export default url;

package/index.js

@@ -0,0 +1,4 @@
+/**
+ * Public URL for the docs package entry.
+ */
+export default import.meta.url;