@xmachines/docs 6.1.0 → 7.1.0

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-flight-demo
+
+# @xmachines/play-vue-router-flight-demo
+
+Vue Router integration demo of the shared **Flight** machine for the XMachines Play architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared Flight machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with Vue Router — the wizard steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-vue-gallery-demo`](../play-vue-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-vue-router-flight-demo run dev
+```
+
+Then open `http://localhost:3091`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `flightCatalog` + `demoComponents`.
+3. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+5. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector.
+6. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` delegate to the shared Flight router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Flight router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                 | Description                                    |
+| ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3091/) |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-flight-demo run test
+pnpm --filter @xmachines/play-vue-router-flight-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared Flight router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-todomvc-demo
+
+# @xmachines/play-vue-router-todomvc-demo
+
+Vue Router integration demo of the shared **TodoMVC** machine for the XMachines Play architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared TodoMVC machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with Vue Router — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-vue-gallery-demo`](../play-vue-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-vue-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3088`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `todoMvcCatalog` + `demoComponents`.
+3. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+5. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector.
+6. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` delegate to the shared TodoMVC router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared TodoMVC router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                  | Description                                    |
+| ------------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3088/) |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-todomvc-demo run test
+pnpm --filter @xmachines/play-vue-router-todomvc-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared TodoMVC router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-trivia-demo
+
+# @xmachines/play-vue-router-trivia-demo
+
+Vue Router integration demo of the shared **Trivia** machine for the XMachines Play architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared Trivia machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with Vue Router — the game states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-vue-gallery-demo`](../play-vue-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-vue-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3089`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `triviaCatalog` + `demoComponents`.
+3. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+5. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector.
+6. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` delegate to the shared Trivia router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                 | Description                                    |
+| ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3089/) |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-trivia-demo run test
+pnpm --filter @xmachines/play-vue-router-trivia-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared Trivia router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

package/examples/README.md

@@ -19,7 +19,13 @@ Learn how state machines control navigation:
 - **[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, and `basePath` for sharing a router with the host
 
-### Level 3: Full Applications
+### Level 3: Ported XState Examples
+
+Eight official XState examples, packaged as one renderer gallery per framework plus a router demo per adapter:
+
+- **[XState Example Ports](xstate-example-ports.md)** — What was ported, how it is packaged, and what the cross-framework matrix caught
+
+### Level 4: Full Applications
 
 Complete working implementations of actor-authoritative routing with all architectural invariants enforced.
 
@@ -31,11 +37,11 @@ Every demo below also wires the [Stately inspector](../guides/inspector.md): the
 
 <!-- typedoc:renderer-demos:start -->
 
-- [@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)
+- [@xmachines/play-dom-gallery-demo](@xmachines/play-dom-gallery-demo/README.md)
+- [@xmachines/play-react-gallery-demo](@xmachines/play-react-gallery-demo/README.md)
+- [@xmachines/play-solid-gallery-demo](@xmachines/play-solid-gallery-demo/README.md)
+- [@xmachines/play-svelte-gallery-demo](@xmachines/play-svelte-gallery-demo/README.md)
+- [@xmachines/play-vue-gallery-demo](@xmachines/play-vue-gallery-demo/README.md)
 
 <!-- typedoc:renderer-demos:end -->
 
@@ -44,13 +50,45 @@ Every demo below also wires the [Stately inspector](../guides/inspector.md): the
 <!-- typedoc:router-demos:start -->
 
 - [@xmachines/play-dom-router-demo](@xmachines/play-dom-router-demo/README.md)
+- [@xmachines/play-dom-router-donut-demo](@xmachines/play-dom-router-donut-demo/README.md)
+- [@xmachines/play-dom-router-flight-demo](@xmachines/play-dom-router-flight-demo/README.md)
+- [@xmachines/play-dom-router-todomvc-demo](@xmachines/play-dom-router-todomvc-demo/README.md)
+- [@xmachines/play-dom-router-trivia-demo](@xmachines/play-dom-router-trivia-demo/README.md)
 - [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
+- [@xmachines/play-react-router-donut-demo](@xmachines/play-react-router-donut-demo/README.md)
+- [@xmachines/play-react-router-flight-demo](@xmachines/play-react-router-flight-demo/README.md)
+- [@xmachines/play-react-router-todomvc-demo](@xmachines/play-react-router-todomvc-demo/README.md)
+- [@xmachines/play-react-router-trivia-demo](@xmachines/play-react-router-trivia-demo/README.md)
 - [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-solid-router-donut-demo](@xmachines/play-solid-router-donut-demo/README.md)
+- [@xmachines/play-solid-router-flight-demo](@xmachines/play-solid-router-flight-demo/README.md)
+- [@xmachines/play-solid-router-todomvc-demo](@xmachines/play-solid-router-todomvc-demo/README.md)
+- [@xmachines/play-solid-router-trivia-demo](@xmachines/play-solid-router-trivia-demo/README.md)
 - [@xmachines/play-svelte-spa-router-demo](@xmachines/play-svelte-spa-router-demo/README.md)
+- [@xmachines/play-svelte-spa-router-donut-demo](@xmachines/play-svelte-spa-router-donut-demo/README.md)
+- [@xmachines/play-svelte-spa-router-flight-demo](@xmachines/play-svelte-spa-router-flight-demo/README.md)
+- [@xmachines/play-svelte-spa-router-todomvc-demo](@xmachines/play-svelte-spa-router-todomvc-demo/README.md)
+- [@xmachines/play-svelte-spa-router-trivia-demo](@xmachines/play-svelte-spa-router-trivia-demo/README.md)
 - [@xmachines/play-sveltekit-router-demo](@xmachines/play-sveltekit-router-demo/README.md)
+- [@xmachines/play-sveltekit-router-donut-demo](@xmachines/play-sveltekit-router-donut-demo/README.md)
+- [@xmachines/play-sveltekit-router-flight-demo](@xmachines/play-sveltekit-router-flight-demo/README.md)
+- [@xmachines/play-sveltekit-router-todomvc-demo](@xmachines/play-sveltekit-router-todomvc-demo/README.md)
+- [@xmachines/play-sveltekit-router-trivia-demo](@xmachines/play-sveltekit-router-trivia-demo/README.md)
 - [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-react-router-donut-demo](@xmachines/play-tanstack-react-router-donut-demo/README.md)
+- [@xmachines/play-tanstack-react-router-flight-demo](@xmachines/play-tanstack-react-router-flight-demo/README.md)
+- [@xmachines/play-tanstack-react-router-todomvc-demo](@xmachines/play-tanstack-react-router-todomvc-demo/README.md)
+- [@xmachines/play-tanstack-react-router-trivia-demo](@xmachines/play-tanstack-react-router-trivia-demo/README.md)
 - [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-donut-demo](@xmachines/play-tanstack-solid-router-donut-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-flight-demo](@xmachines/play-tanstack-solid-router-flight-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-todomvc-demo](@xmachines/play-tanstack-solid-router-todomvc-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-trivia-demo](@xmachines/play-tanstack-solid-router-trivia-demo/README.md)
 - [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
+- [@xmachines/play-vue-router-donut-demo](@xmachines/play-vue-router-donut-demo/README.md)
+- [@xmachines/play-vue-router-flight-demo](@xmachines/play-vue-router-flight-demo/README.md)
+- [@xmachines/play-vue-router-todomvc-demo](@xmachines/play-vue-router-todomvc-demo/README.md)
+- [@xmachines/play-vue-router-trivia-demo](@xmachines/play-vue-router-trivia-demo/README.md)
 
 <!-- typedoc:router-demos:end -->
 

package/examples/form-validation.md

@@ -15,8 +15,9 @@ This example mirrors the `authMachine` login pattern: a form state with a local
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 
 // Context shape
 interface LoginContext {
@@ -155,8 +156,11 @@ const loginMachine = loginSetup.createMachine(
 	}),
 );
 
-// 3. Factory and actor
-const createPlayer = definePlayer({ machine: loginMachine });
+// 3. Factory and actor — withView derives the meta.view spec that a renderer reads
+const createPlayer = definePlayer({
+	machine: loginMachine,
+	actor: compose(PlayerActor, withView),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -190,9 +194,9 @@ actor.stop();
 | `{ $bindState: "/username" }` | Two-way   | Prop reads and writes the state store key `/username`       |
 | `{ $state: "/username" }`     | Read-only | Reads the current value from the state store at `/username` |
 
-The `state:` key in `meta.view` sets the initial values for the local store. When the user types in the form field, the renderer keeps the store in sync. On submit, action params read the final value via `$state`.
+The `state:` key in `meta.view` sets the initial values for the local store. When the user types in the form field, the component writes the value to the store. On submit, action params read the final value via `$state`.
 
-```typescript
+```typescript fragment
 // In the machine meta.view — the renderer handles the rest:
 view: {
   root: "root",
@@ -231,6 +235,10 @@ import { createRenderer, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
+
+// The started actor of the complete code above
+declare const actor: ViewActor & { stop(): void };
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -257,10 +265,9 @@ const Login: ComponentFn<AppCatalog, "Login"> = ({ props, on, ctx }) => {
 	const section = document.createElement("section");
 	const input = document.createElement("input");
 	input.value = props.username ?? "";
-	// Keep the local state store in sync as the user types
-	input.addEventListener("input", () => {
-		ctx.store.update((s) => ({ ...s, username: input.value }));
-	});
+	// Write each keystroke to the store path that $bindState binds to the prop
+	const username = ctx.bound<string>("username");
+	input.addEventListener("input", () => username.set(input.value));
 	const button = document.createElement("button");
 	button.textContent = "Log In";
 	const submit = on("submit"); // bound to the spec's on.submit binding
@@ -283,9 +290,6 @@ const Dashboard: ComponentFn<AppCatalog, "Dashboard"> = ({ props, on }) => {
 // createRenderer builds the factory once — call mount() when the actor is ready
 const mount = createRenderer(catalog, { Home, Login, Dashboard });
 
-const actor = createPlayer();
-actor.start();
-
 const disconnect = mount(actor, document.getElementById("app")!);
 
 // Call teardown() when the app ends before the page does, for example when the component
@@ -302,7 +306,7 @@ function teardown(): void {
 
 - `actions` in `defineCatalog` must include every action name referenced in `meta.view` `on:` bindings. TypeScript enforces this via `CatalogHasActions`.
 - `on("submit").emit()` resolves `params` from the current state store at call time — the `$state: "/username"` in the spec is read at that moment, not at render time.
-- `ctx.store.update(fn)` is the standard write path for two-way binding. The spec's `$bindState` directive only wires the read direction (prop ← store); the write direction (store ← input) must be implemented in the component.
+- `ctx.bound("username").set(value)` writes to the store path that `$bindState` binds to the prop. The `$bindState` directive gives the prop its value from the store. The component writes the input back to the store.
 
 ## Next Steps