@xmachines/docs

Documentation, guides, RFCs, and generated API reference for XMachines.

Part of the XMachines Play monorepo.

Overview

@xmachines/docs is the documentation package for the XMachines Play monorepo. It ships five categories of content:

| Location | Contents | | --------------- | ---------------------------------------------------------------- | | rfc/ | Request-for-Comment specs that define the XMachines architecture | | guides/ | Concept guides, tutorials, and getting-started docs | | contributing/ | Operational docs for contributors and maintainers | | examples/ | Runnable code examples and demo application references | | api/ | TypeDoc-generated API reference for all public packages |

Installation

pnpm add @xmachines/docs

Usage

Import the package URL

The package default export is its own module URL — useful for resolving doc assets at runtime:

import docsUrl from "@xmachines/docs";
// docsUrl is the resolved URL of the docs package entry point

Access documentation files directly

All documentation directories are exposed as package exports:

// Access RFC files
import playRfc from "@xmachines/docs/rfc/play.md";

// Access guide files
import gettingStarted from "@xmachines/docs/guides/getting-started.md";

// Access example files
import basicExample from "@xmachines/docs/examples/basic-state-machine.md";

// Access API reference
import apiDocs from "@xmachines/docs/api/README.md";

Contents

RFCs

Architectural specifications that define the XMachines system:

| File | Title | Description | | ---------------------------------- | ------- | -------------------------------------------------------------------- | | rfc/play.md | Play | Universal Player Architecture — core protocol, roles, and invariants | | rfc/streams.md | Streams | WHATWG Streams as integration boundary | | rfc/broker.md | Broker | Event broker specification | | rfc/git.md | Git | Git-compatible ID and history model | | rfc/run.md | Run | Runtime execution model | | rfc/browser.md | Browser | Browser environment adapter | | rfc/node.md | Node | Node.js environment adapter | | rfc/cli.md | CLI | Command-line interface specification | | rfc/rest.md | REST | REST adapter specification | | rfc/mcp.md | MCP | Model Context Protocol adapter |

Guides

Concept guides and tutorials for working with XMachines:

Learning:

• Getting Started — setup().createMachine() → definePlayer() → actor.start() → TC39 Signals
• Understanding State Machines — meta.route, meta.view, and why machines replace boolean flags
• Understanding the Actor Model — Actor/infrastructure split, AbstractActor, and the reset invariant
• Understanding TC39 Signals — Signal primitives and the five architectural invariants they enforce

Tooling:

• Inspecting a Running Actor — PlayerOptions.inspect, the Stately inspector, late attachment, and browser-free transports

Contributing & Operations

Reference documentation for contributors and maintainers:

• Architecture — Package layers, data flows, key abstractions, TypeScript build graph
• Development — Monorepo setup, build system, adding packages, code conventions
• Configuration — TypeScript, linting, formatting, Vitest, CI/CD, and release configuration
• Testing — Vitest setup, node vs browser modes, test patterns, coverage requirements
• Deployment — npm publishing, semantic-release process, GitLab CI pipeline

Examples

Practical code examples demonstrating XMachines patterns:

• Basic State Machine — setup().createMachine() + definePlayer() + TC39 Signals
• Traffic Light — Multi-state machine with meta.route and formatPlayRouteTransitions
• Form Validation — Typed context mutations with setup.assign, guards, and $bindState
• Routing Patterns — meta.route, play.route events, always auth guards
• Multi-Router Integration — All 8 router adapters

API Reference

TypeDoc-generated API reference for all public packages — see api/README.md.

Packages documented:

• @xmachines/play — Core protocols (PlayEvent, PlayError)
• @xmachines/play-actor — AbstractActor, Routable, Viewable
• @xmachines/play-signals — TC39 Signals polyfill, watchSignal
• @xmachines/play-router — extractMachineRoutes, RouterBridgeBase
• @xmachines/play-xstate — definePlayer, formatPlayRouteTransitions, PlayerActor
• @xmachines/play-dom, play-react, play-solid, play-svelte, play-vue — View renderers
• @xmachines/play-dom-router, play-tanstack-router, play-react-router, play-tanstack-react-router, play-solid-router, play-tanstack-solid-router, play-vue-router, play-svelte-spa-router, play-sveltekit-router — Router adapters

Testing

Run the docs package tests in isolation:

# From the monorepo root
pnpm --filter @xmachines/docs test

# Or from within the package directory
pnpm test

Regenerating API Docs

The api/ directory is auto-generated by TypeDoc and must not be edited directly. Regenerate it from the monorepo root:

pnpm run docs

License

MIT — see LICENSE.