@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

package/api/@xmachines/play-xstate/type-aliases/GuardArray.md

@@ -6,7 +6,7 @@
 type GuardArray<TContext, TEvent> = Guard<TContext, TEvent>[] | string[];
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/guards/types.ts#L23)
+Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/guards/types.ts#L23)
 
 Array of guard predicates or guard names
 

package/api/@xmachines/play-xstate/type-aliases/PlayerFactory.md

@@ -6,7 +6,7 @@
 type PlayerFactory<TMachine> = (input?, options?) => PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/types.ts#L57)
+Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/types.ts#L57)
 
 Factory function returned by definePlayer()
 

package/api/@xmachines/play-xstate/type-aliases/RouteMachineConfig.md

@@ -6,7 +6,7 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L52)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L48)
 
 Minimal structural constraint for machine configs accepted by
 `formatPlayRouteTransitions`.
@@ -32,7 +32,7 @@ through the transform, so the return value remains directly usable by
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L53)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L49)
 
 ---
 
@@ -42,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:5
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L55)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
 
 ---
 
@@ -52,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:5
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L54)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L50)

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L21)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
 
 Minimal structural shape of a single XState state node as read by
 `formatPlayRouteTransitions` when crawling the machine config.
@@ -29,7 +29,7 @@ the index signature.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L23)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
 
 Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
@@ -41,7 +41,7 @@ Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` targ
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L25)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
 
 State metadata — `meta.route` marks the state as routable.
 
@@ -61,6 +61,6 @@ URL path template (e.g. `"/profile/:username"`, `"/settings/:section?"`).
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-xstate/src/routing/format-play-route-transitions.ts#L22)
 
 Nested child states, recursively crawled for additional route declarations.

package/api/@xmachines/shared/functions/defineXmVitestConfig.md

@@ -3,10 +3,10 @@
 # Function: defineXmVitestConfig()
 
 ```ts
-function defineXmVitestConfig(importMetaUrl, overrides): object;
+function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [src/index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/shared/src/index.ts#L10)
+Defined in: [index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/shared/src/index.ts#L10)
 
 Create a Vitest config with XMachines workspace defaults.
 
@@ -22,8 +22,4 @@ render it under `@xmachines/shared` instead of nested module pages.
 
 ## Returns
 
-`object`
-
-| Name   | Type  | Defined in                                                                                                                   |
-| ------ | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `test` | `any` | [config/vitest.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/shared/config/vitest.ts#L82) |
+`UserConfig`

package/api/@xmachines/shared/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [src/index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/shared/src/index.ts#L20)
+Defined in: [index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/shared/src/index.ts#L20)
 
 Build Vite/Vitest alias entries for all `@xmachines/*` workspace packages.
 

package/api/README.md

@@ -7,8 +7,8 @@ Generated API documentation for the XMachines JavaScript/TypeScript packages.
 - For actor contracts, start with [@xmachines/play-actor](@xmachines/play-actor/README.md).
 - For player creation from XState machines, start with [@xmachines/play-xstate](@xmachines/play-xstate/README.md).
 - For route extraction and shared URL synchronization logic, start with [@xmachines/play-router](@xmachines/play-router/README.md).
-- For rendering, choose one of [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
-- For framework router integration, choose the matching adapter package such as [@xmachines/play-react-router](@xmachines/play-react-router/README.md) or [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md).
+- For rendering, choose one of [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- For framework router integration, choose the matching adapter package such as [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), or [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md).
 
 ## Key Concepts
 
@@ -19,8 +19,8 @@ Generated API documentation for the XMachines JavaScript/TypeScript packages.
 ## Package Roles
 
 - `Core runtime`: [@xmachines/play](@xmachines/play/README.md), [@xmachines/play-actor](@xmachines/play-actor/README.md), [@xmachines/play-signals](@xmachines/play-signals/README.md), [@xmachines/play-router](@xmachines/play-router/README.md), and [@xmachines/play-xstate](@xmachines/play-xstate/README.md)
-- `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md)
-- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), and [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md)
+- `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md)
+- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), and [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md)
 - `Shared tooling`: [@xmachines/shared](@xmachines/shared/README.md)
 
 ## Notes

package/api/llms.txt

@@ -12,14 +12,14 @@
 - Understanding actor contracts: read [@xmachines/play-actor](@xmachines/play-actor/README.md) for [Viewable](@xmachines/play-actor/interfaces/Viewable.md) and [Routable](@xmachines/play-actor/interfaces/Routable.md).
 - [Viewable](@xmachines/play-actor/interfaces/Viewable.md) is the rendering contract: actors expose `currentView` plus a component catalog so rendering packages can resolve UI without owning application state.
 - [Routable](@xmachines/play-actor/interfaces/Routable.md) is the routing contract: actors expose `currentRoute` plus route-oriented event handling, while adapters translate browser or router changes into actor events.
-- Rendering actor-driven UI: use [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- Rendering actor-driven UI: use [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
 - Synchronizing URLs with actor state: use [@xmachines/play-router](@xmachines/play-router/README.md) plus a framework-specific router adapter.
 
 ## Package Roles
 
 - `Core runtime`: [@xmachines/play](@xmachines/play/README.md), [@xmachines/play-actor](@xmachines/play-actor/README.md), [@xmachines/play-signals](@xmachines/play-signals/README.md), [@xmachines/play-router](@xmachines/play-router/README.md), and [@xmachines/play-xstate](@xmachines/play-xstate/README.md). Catalog and component registry are provided by `@json-render/core` and the framework rendering packages.
-- `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md).
-- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), and [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), all built on top of [Routable](@xmachines/play-actor/interfaces/Routable.md) actors and shared route metadata.
+- `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), and [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md), all built on top of [Routable](@xmachines/play-actor/interfaces/Routable.md) actors and shared route metadata.
 - `Shared tooling`: [@xmachines/shared](@xmachines/shared/README.md) for shared config and workspace-level support files.
 
 ## API

package/examples/README.md

@@ -1,76 +1,94 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # XMachines Examples
 
-Practical code examples demonstrating common XMachines patterns and use cases.
+Practical code examples demonstrating current XMachines Play patterns and use cases.
 
 ## Learning Path
 
 ### Level 1: Basic Concepts
 
-Start with fundamental state machine concepts:
+Start with the fundamental machine + actor pattern:
 
-- **[Basic State Machine](basic-state-machine.md)** - Simple two-state toggle machine
-- **[Traffic Light](traffic-light.md)** - Multi-state machine with cyclic transitions
-- **[Form Validation](form-validation.md)** - Validation with guards and conditional logic
+- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + TC39 Signals
+- **[Traffic Light](traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
+- **[Form Validation](form-validation.md)** — Typed context mutations with `setup.assign`, guards, and `$bindState`
 
 ### Level 2: Routing Patterns
 
 Learn how state machines control navigation:
 
-- **[Routing Patterns](routing-patterns.md)** - State-driven routing and navigation guards
-- **[Multi-Router Integration](multi-router-integration.md)** - Framework-agnostic routing architecture
+- **[Routing Patterns](routing-patterns.md)** — `meta.route`, `play.route` events, `always` auth guards, and parameter routes
+- **[Multi-Router Integration](multi-router-integration.md)** — All 8 router adapters: provider pattern vs `connectRouter` pattern
 
 ### Level 3: Full Applications
 
-See complete working implementations demonstrating the current router integrations and all architectural invariants.
-
-## Complete Examples
+Complete working implementations of actor-authoritative routing with all architectural invariants enforced.
 
-Complete working applications demonstrating actor-authoritative routing, shared auth flows, and framework-specific rendering patterns:
+## Complete Demo Applications
 
 ### Framework-Agnostic Baseline
 
-- **[Vanilla JavaScript Router Demo](../api/@xmachines/play-dom-router-demo/README.md)** - Pure browser integration with the History API and DOM rendering; the lowest-level reference implementation for the router demos
+- **[Vanilla JavaScript Router Demo](../api/@xmachines/play-dom-router-demo/README.md)** — Pure browser integration: `connectRouter` + `connectRenderer` + DOM components. The lowest-level reference implementation.
 
 ### React Integrations
 
-- **[TanStack React Router Demo](../api/@xmachines/play-tanstack-react-router-demo/README.md)** - Canonical reference implementation showing all 5 invariants, comprehensive routing, authentication guards, and browser tests
-- **[React Router Demo](../api/@xmachines/play-react-router-demo/README.md)** - React Router v7 data-router integration using the same actor and shell patterns
+- **[TanStack React Router Demo](../api/@xmachines/play-tanstack-react-router-demo/README.md)** — Canonical reference implementation with all 5 invariants, comprehensive routing, authentication guards, and browser tests.
+- **[React Router Demo](../api/@xmachines/play-react-router-demo/README.md)** — React Router v7 data-router integration using a catch-all route and `ReactRouterBridge`.
 
 ### Vue Integration
 
-- **[Vue Router Demo](../api/@xmachines/play-vue-router-demo/README.md)** - Vue Composition API integration with the same shared auth and routing patterns
+- **[Vue Router Demo](../api/@xmachines/play-vue-router-demo/README.md)** — Vue Composition API integration with `PlayRouterProvider` and the shared `authMachine`.
 
-### Solid Integrations
+### Svelte Integrations
 
-- **[Solid Router Demo](../api/@xmachines/play-solid-router-demo/README.md)** - Solid fine-grained reactivity with `@solidjs/router` and provider-based routing
-- **[TanStack Solid Router Demo](../api/@xmachines/play-tanstack-solid-router-demo/README.md)** - Solid + TanStack router integration with the same actor-authoritative flow
+- **[SvelteKit Router Demo](../api/@xmachines/play-sveltekit-router-demo/README.md)** — SvelteKit-style routing with `connectRouter` + `afterNavigate`/`goto` and Svelte 5 runes.
+- **[Svelte SPA Router Demo](../api/@xmachines/play-svelte-spa-router-demo/README.md)** — Hash-based SPA routing using `svelte-spa-router` with the same actor-authoritative flow.
 
-## Running Examples
+### SolidJS Integrations
 
-All examples are written in TypeScript and can be run in:
+- **[Solid Router Demo](../api/@xmachines/play-solid-router-demo/README.md)** — `@solidjs/router` integration with `PlayRouterProvider` and SolidJS fine-grained reactivity.
+- **[TanStack Solid Router Demo](../api/@xmachines/play-tanstack-solid-router-demo/README.md)** — TanStack Router for Solid with dynamic route creation from the machine's route tree.
 
-**Node.js:**
+## Running the Code Examples
+
+The conceptual examples in this directory are TypeScript snippets. To run them:
 
 ```bash
-npm install @xmachines/play
-npx tsx example.ts
-```
+# Install dependencies (from the monorepo root)
+npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
 
-**Browser:**
-Include via bundler (Vite, Webpack) or use browser platform package.
+# Run with tsx
+npx tsx my-example.ts
+```
 
-**Deno:**
+To run a complete demo application, `cd` into the relevant package and start its dev server:
 
 ```bash
-deno run --allow-net example.ts
+# Example: vanilla DOM router demo
+cd packages/play-dom-router/examples/demo
+npm install
+npm run dev
 ```
 
+## Key Packages
+
+| Package                   | Role                                                        |
+| ------------------------- | ----------------------------------------------------------- |
+| `@xmachines/play-xstate`  | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
+| `@xmachines/play-actor`   | `AbstractActor`, `typedSpec`                                |
+| `@xmachines/play-signals` | TC39 Signals polyfill, `watchSignal`                        |
+| `@xmachines/play-router`  | `extractMachineRoutes`, `getRoutableRoutes`                 |
+| `@xmachines/play-dom`     | `connectRenderer`, `defineRegistry` (vanilla)               |
+| `@xmachines/play-react`   | `PlayRenderer`, `defineRegistry` (React)                    |
+
 ## Related Documentation
 
-- **[Getting Started Guide](../guides/getting-started.md)** - First steps with XMachines
-- **[API Reference](../api/README.md)** - Complete API documentation
+- **[Getting Started Guide](../guides/getting-started.md)** — First steps with XMachines
+- **[Installation Guide](../guides/installation.md)** — Package installation and TypeScript setup
+- **[API Reference](../api/README.md)** — Generated API docs for all public packages
+- **[Play RFC](../rfc/play.md)** — Complete architectural specification
 
 ---
 
-**Contributing Examples:**
-Have a useful example to share? See the repository contribution guidelines.
+**Contributing Examples:** Have a useful example to share? See the repository contribution guidelines.

package/examples/basic-state-machine.md

@@ -1,70 +1,114 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # Basic State Machine
 
-Learn how to create a simple state machine with two states.
+Learn how to define a simple toggle machine using the current XState v5 + XMachines `setup().createMachine()` + `definePlayer()` pattern.
 
 ## Use Case
 
-This example demonstrates a toggle switch or on/off button - the foundation for understanding state transitions in XMachines. It's the simplest possible state machine with just two states and one event type.
+This example demonstrates a toggle switch — the foundation for understanding state machines in XMachines. It is the simplest possible machine: two states, one event type, no router, no catalog.
 
 ## Complete Code
 
 ```typescript
-import { createMachine } from "xstate";
-
-// Define states
-type ToggleState = "off" | "on";
-
-// Define events
-type ToggleEvent = { type: "TOGGLE" };
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+// 1. Declare types for context, events, and input via setup()
+const toggleSetup = setup({
+	types: {
+		context: {} as { toggleCount: number },
+		events: {} as { type: "toggle" },
+		input: {} as { toggleCount?: number } | undefined,
+	},
+});
 
-// Create machine
-const toggleMachine = createMachine<ToggleState, ToggleEvent>({
+// 2. Create the machine using setup().createMachine()
+const toggleMachine = toggleSetup.createMachine({
 	id: "toggle",
 	initial: "off",
+	context: ({ input }) => ({
+		toggleCount: input?.toggleCount ?? 0,
+	}),
 	states: {
 		off: {
 			on: {
-				TOGGLE: "on",
+				toggle: {
+					target: "on",
+					actions: toggleSetup.assign({
+						toggleCount: ({ context }) => context.toggleCount + 1,
+					}),
+				},
 			},
 		},
 		on: {
 			on: {
-				TOGGLE: "off",
+				toggle: {
+					target: "off",
+					actions: toggleSetup.assign({
+						toggleCount: ({ context }) => context.toggleCount + 1,
+					}),
+				},
 			},
 		},
 	},
 });
 
-// Usage
-let state = toggleMachine.initialState;
-console.log(state); // 'off'
+// 3. Create a player factory
+const createPlayer = definePlayer({ machine: toggleMachine });
+
+// 4. Create and start an actor
+const actor = createPlayer();
+actor.start();
+
+// 5. Read initial state via getSnapshot()
+console.log(actor.getSnapshot().value); // "off"
+console.log(actor.getSnapshot().context.toggleCount); // 0
 
-state = toggleMachine.transition(state, { type: "TOGGLE" });
-console.log(state); // 'on'
+// 6. Read state via TC39 Signal
+console.log(actor.state.get().value); // "off"
 
-state = toggleMachine.transition(state, { type: "TOGGLE" });
-console.log(state); // 'off'
+// 7. Send events
+actor.send({ type: "toggle" });
+console.log(actor.getSnapshot().value); // "on"
+console.log(actor.getSnapshot().context.toggleCount); // 1
+
+actor.send({ type: "toggle" });
+console.log(actor.getSnapshot().value); // "off"
+console.log(actor.getSnapshot().context.toggleCount); // 2
+
+// 8. Cleanup
+actor.stop();
 ```
 
 ## Code Explanation
 
-1. **Define TypeScript types** - Create union types for states (`'off' | 'on'`) and events (`{ type: 'TOGGLE' }`) to get type safety throughout your application.
+1. **`setup({ types })`** — Declares TypeScript types for `context`, `events`, and `input` before the machine is created. This is the XState v5 typed entry point. Never pass type parameters directly to `createMachine`.
+
+2. **`toggleSetup.createMachine(...)`** — Creates the state machine. Using the scoped `toggleSetup.createMachine` (instead of the bare `createMachine` from xstate) ensures that guards and actions are type-checked against the declared types.
+
+3. **`toggleSetup.assign(...)`** — Assigns context mutations using the typed setup's `assign` helper. This provides full inference from the declared context type — no manual type assertions needed.
+
+4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with TC39 Signal reactivity and Play Architecture hooks.
+
+5. **`actor.start()`** — Activates the machine. Always call `start()` before sending events.
 
-2. **Create machine with initial state** - Use `createMachine` with an `initial` property to specify which state the machine starts in.
+6. **`actor.getSnapshot()`** — Returns the current XState snapshot synchronously. `.value` is the state name; `.context` is the typed context object.
 
-3. **Define state transitions** - In the `states` config, each state has an `on` object mapping event types to target states.
+7. **`actor.state.get()`** — TC39 Signal access to the current snapshot. Useful when wiring infrastructure that observes signals (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
 
-4. **Use the machine** - Call `transition(currentState, event)` to compute the next state based on the current state and incoming event.
+8. **Event types use dot-separated lowercase** — `"toggle"` not `"TOGGLE"`. This matches the XMachines convention used throughout the codebase (e.g. `"auth.login"`, `"auth.logout"`, `"play.route"`).
 
 ## Key Concepts
 
-- **State**: The current mode or condition of the machine (`'off'` or `'on'`)
-- **Event**: A trigger that causes a state change (`{ type: 'TOGGLE' }`)
-- **Transition**: A rule defining how the machine moves from one state to another
-- **Type Safety**: TypeScript ensures you only use valid states and events, catching errors at compile time
+- **`setup({ types })`**: The XState v5 typed entry point. Declares context, event, and input shapes before machine creation.
+- **`definePlayer({ machine })`**: Creates a factory function that returns `PlayerActor` instances.
+- **`actor.state`**: A `Signal.State<Snapshot>` — TC39 Signals-based reactive handle on the machine snapshot.
+- **`actor.getSnapshot()`**: Synchronous snapshot access — use for one-time reads and TypeScript-typed context inspection.
+- **Typed `assign`**: Always call `setup.assign(...)` (not the bare `assign` from xstate) for context mutations.
 
 ## Next Steps
 
-- **[Traffic Light Example](traffic-light.md)** - See how to handle multiple states with cyclic transitions
-- **[Form Validation Example](form-validation.md)** - Learn about guards and conditional transitions
-- **[API Documentation](../api/@xmachines/play/README.md)** - Explore the complete API reference
+- **[Traffic Light Example](traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
+- **[Form Validation Example](form-validation.md)** — Typed context mutations with `setup.assign` and guards
+- **[Routing Patterns](routing-patterns.md)** — Adding `meta.route` to states and using `play.route` events