@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/examples/@xmachines/play-vue-demo/variables/authCatalog.md

@@ -0,0 +1,172 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / authCatalog
+
+# Variable: authCatalog
+
+```ts
+const authCatalog: Catalog<
+	{
+		catalog: SchemaType<
+			"object",
+			{
+				actions: SchemaType<
+					"map",
+					{
+						description: SchemaType<"string", unknown>;
+						params: SchemaType<"zod", unknown>;
+					}
+				>;
+				components: SchemaType<
+					"map",
+					{
+						description: SchemaType<"string", unknown>;
+						example: SchemaType<"any", unknown>;
+						props: SchemaType<"zod", unknown>;
+						slots: SchemaType<"array", SchemaType<"string", unknown>>;
+					}
+				>;
+			}
+		>;
+		spec: SchemaType<
+			"object",
+			{
+				elements: SchemaType<
+					"record",
+					SchemaType<
+						"object",
+						{
+							children: SchemaType<"array", SchemaType<"string", unknown>>;
+							props: SchemaType<"propsOf", string>;
+							type: SchemaType<"ref", string>;
+							visible: SchemaType<"any", unknown>;
+						}
+					>
+				>;
+				root: SchemaType<"string", unknown>;
+			}
+		>;
+	},
+	{
+		actions: {
+			login: {
+				description: "Login with username";
+				params: ZodObject<
+					{
+						username: ZodString;
+					},
+					$strip
+				>;
+			};
+			logout: {
+				description: "Logout and return to home";
+			};
+			route: {
+				description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
+				params: ZodObject<
+					{
+						params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+						to: ZodString;
+					},
+					$strip
+				>;
+			};
+		};
+		components: {
+			About: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Contact: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Dashboard: {
+				props: ZodObject<
+					{
+						username: ZodString;
+						welcome: ZodBoolean;
+					},
+					$strip
+				>;
+			};
+			Home: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Login: {
+				props: ZodObject<
+					{
+						title: ZodString;
+						username: ZodOptional<ZodString>;
+					},
+					$strip
+				>;
+			};
+			NavBar: {
+				props: ZodObject<
+					{
+						isAuthenticated: ZodBoolean;
+						username: ZodNullable<ZodString>;
+					},
+					$strip
+				>;
+			};
+			Navigation: {
+				props: ZodObject<
+					{
+						currentPath: ZodString;
+						isAuthenticated: ZodBoolean;
+					},
+					$strip
+				>;
+			};
+			Overview: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+			Profile: {
+				props: ZodObject<
+					{
+						username: ZodString;
+					},
+					$strip
+				>;
+			};
+			Settings: {
+				props: ZodObject<
+					{
+						section: ZodOptional<ZodString>;
+						username: ZodString;
+					},
+					$strip
+				>;
+			};
+			Stats: {
+				props: ZodObject<
+					{
+						title: ZodString;
+					},
+					$strip
+				>;
+			};
+		};
+	}
+>;
+```
+
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-vue/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-vue-router-demo/README.md

@@ -0,0 +1,139 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-demo
+
+# @xmachines/play-vue-router-demo
+
+Vue Router integration demo for the XMachines Play architecture using Vue Composition API.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with Vue Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Vue Composition API mapping to TC39 Signals lifecycle
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-vue-router-demo run dev
+```
+
+Then open `http://localhost:3010`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand how the demo is wired:
+
+1. `src/main.ts` creates the Vue app, installs Vue Router, mounts, and wires HMR cleanup.
+2. `src/runtime.ts` creates the actor, starts it, builds the shared `registryResult`, and creates the `routeMap`.
+3. `src/router.ts` installs a single catch-all route; `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the shared actor, routeMap, router instance, and a `renderShell` renderer function.
+5. The renderer function creates the shared `Shell` component with actor, router, and registry as props.
+6. `PlayRouterProvider` waits for `router.isReady()` so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/main.ts (shape)
+const app = createApp(App);
+app.use(router);
+app.mount("#app");
+```
+
+```ts
+// src/router.ts (shape)
+export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", component: RouteHost }];
+```
+
+```vue
+<!-- src/App.vue (shape) -->
+<script setup lang="ts">
+import { actor, routeMap, registryResult } from "./runtime.js";
+
+const renderShell = (currentActor, currentRouter) =>
+	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult });
+</script>
+
+<template>
+	<PlayRouterProvider
+		:actor="actor"
+		:route-map="routeMap"
+		:router="router"
+		:renderer="renderShell"
+	/>
+</template>
+```
+
+```ts
+// src/runtime.ts (shape)
+export const actor = createPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+export const registryResult = defineRegistry(authCatalog, { components, actions });
+```
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (mount + router install + HMR cleanup)
+- `src/runtime.ts` - actor startup, routeMap creation, and registry construction
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and renderer composition using the shared runtime
+- `test/reactivity.test.ts` - reactive integration assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user navigates to a protected route via a link, Vue Router updates the location. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions.
+2. **Passive Infrastructure:** The router does not execute Vue route guards for business logic. The actor dictates whether navigation is permitted. The Vue application only renders the state.
+3. **Signal-Only Reactivity:** The bridge leverages Vue's `watch` and `triggerRef` internally to react precisely when signals update, without polluting the Vue component tree with reactive refs that hold business state.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and sync Vue-local render state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Notifications are one-shot, so re-arm is required. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
+
+## Adapter Boundaries
+
+Vue Router integration remains passive infrastructure. `RouterBridgeBase` owns shared synchronization policy and the Vue adapter is a thin framework port. Route extraction override strategies remain supported when teams need custom route-name mapping.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                          | Description                                    |
+| ---------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-router-demo run dev`          | Start Vite dev server (http://localhost:3010/) |
+| `pnpm --filter @xmachines/play-vue-router-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-vue-router-demo run test
+pnpm --filter @xmachines/play-vue-router-demo run test:browser
+```
+
+Expected result: reactivity integration tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.
+
+## Learn More
+
+- [Vue Router](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue](../../../api/@xmachines/play-vue/README.md)

package/examples/README.md

@@ -1,63 +1,111 @@
 # 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 all architectural invariants:
+Complete working implementations of actor-authoritative routing with all architectural invariants enforced.
 
-## Demo Applications
+## Complete Demo Applications
 
-Complete working applications demonstrating all 5 architectural invariants:
+### Renderer Demos
 
-- **[React + TanStack Router Demo](../../packages/play-tanstack-react-router/examples/demo-app/)** - Canonical reference implementation showing all 5 invariants, comprehensive routing, authentication guards, and browser tests
-- **[Vue Router Demo](../../packages/play-vue-router/examples/demo/)** - Vue Composition API integration with same auth patterns
-- **[SolidJS Router Demo](../../packages/play-solidjs-router/examples/demo/)** - Solid signals integration demonstrating framework independence
+<!-- typedoc:renderer-demos:start -->
 
-## Running Examples
+- [@xmachines/play-dom-demo](@xmachines/play-dom-demo/README.md)
+- [@xmachines/play-react-demo](@xmachines/play-react-demo/README.md)
+- [@xmachines/play-solid-demo](@xmachines/play-solid-demo/README.md)
+- [@xmachines/play-svelte-demo](@xmachines/play-svelte-demo/README.md)
+- [@xmachines/play-vue-demo](@xmachines/play-vue-demo/README.md)
 
-All examples are written in TypeScript and can be run in:
+<!-- typedoc:renderer-demos:end -->
 
-**Node.js:**
+### Router Demos
+
+<!-- typedoc:router-demos:start -->
+
+- [@xmachines/play-dom-router-demo](@xmachines/play-dom-router-demo/README.md)
+- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
+- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-svelte-spa-router-demo](@xmachines/play-svelte-spa-router-demo/README.md)
+- [@xmachines/play-sveltekit-router-demo](@xmachines/play-sveltekit-router-demo/README.md)
+- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
+- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
+
+<!-- typedoc:router-demos:end -->
+
+## 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)
+pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
 
-**Browser:**
-Include via bundler (Vite, Webpack) or use browser platform package.
+# Run with tsx
+pnpm dlx tsx my-example.ts
+```
 
-**Deno:**
+To run a complete demo application, use the workspace package name:
 
 ```bash
-deno run --allow-net example.ts
+pnpm --filter @xmachines/play-dom-router-demo run dev
 ```
 
-## Related Documentation
+## Key Packages
+
+### Core
+
+| Package                                                               | Role                                                        |
+| --------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | `AbstractActor`, `typedSpec`                                |
+| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill, `watchSignal`                        |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)   | `extractMachineRoutes`, `getRoutableRoutes`                 |
+
+### Renderers
 
-- **[Getting Started Guide](/docs/guides/getting-started)** - First steps with XMachines
-- **[API Reference](/docs/api)** - Complete API documentation
-- **[Core Concepts](/docs/api/guides/core-concepts)** - Architecture and design patterns
+| Package                                                             | Role                                               |
+| ------------------------------------------------------------------- | -------------------------------------------------- |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)       | `createPlayUI`, `createRenderer`, `defineRegistry` |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)   | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)       | `PlayRenderer`, `defineRegistry`                   |
 
----
+### Router Adapters
+
+| Package                                                                                           | Router                  |
+| ------------------------------------------------------------------------------------------------- | ----------------------- |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla browser history |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router v7         |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack Router (React) |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router          |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Router (Solid) |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router              |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | svelte-spa-router       |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit               |
+
+## Related Documentation
 
-**Contributing Examples:**
-Have a useful example to share? See [Development Docs](/development) for contribution guidelines.
+- **[Getting Started](../guides/getting-started.md)** — Installation, first actor, routing, and view renderer setup
+- **[API Reference](../api/README.md)** — Generated API docs for all public packages
+- **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/examples/basic-state-machine.md

@@ -1,70 +1,112 @@
 # 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](/docs/api/xmachines/play/readme)** - 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