@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-vue-router/variables/PlayRouterProvider.md

@@ -0,0 +1,67 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouterProvider
+
+# Variable: PlayRouterProvider
+
+```ts
+const PlayRouterProvider: DefineComponent<
+	ExtractPropTypes<{
+		actor: {
+			required: true;
+			type: PropType<RoutableActor>;
+		};
+		renderer: {
+			required: true;
+			type: PropType<(actor, router) => VNodeChild>;
+		};
+		routeMap: {
+			required: true;
+			type: PropType<RouteMap>;
+		};
+		router: {
+			required: true;
+			type: PropType<Router>;
+		};
+	}>,
+	() => VNodeChild,
+	{},
+	{},
+	{},
+	ComponentOptionsMixin,
+	ComponentOptionsMixin,
+	{},
+	string,
+	PublicProps,
+	ToResolvedProps<
+		ExtractPropTypes<{
+			actor: {
+				required: true;
+				type: PropType<RoutableActor>;
+			};
+			renderer: {
+				required: true;
+				type: PropType<(actor, router) => VNodeChild>;
+			};
+			routeMap: {
+				required: true;
+				type: PropType<RouteMap>;
+			};
+			router: {
+				required: true;
+				type: PropType<Router>;
+			};
+		}>,
+		{}
+	>,
+	{},
+	{},
+	{},
+	{},
+	string,
+	ComponentProvideOptions,
+	true,
+	{},
+	any
+>;
+```
+
+Defined in: [play-vue-router/src/play-router-provider.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/play-router-provider.ts#L11)

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

@@ -0,0 +1,133 @@
+[Documentation](../../README.md) / @xmachines/play-vue-router-demo
+
+# Vue Router Demo
+
+Vue Router integration demonstrating Play Architecture with Vue Composition API.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayVueRouterProvider` 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
+npm install
+npm run dev -w packages/play-vue-router/examples/demo
+```
+
+Visit `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand how the demo is wired:
+
+1. `src/main.ts` creates the actor via `definePlayer({ machine: authMachine, catalog })`.
+2. `src/router.ts` installs one catch-all route; `PlayRenderer` selects the actual view from actor state.
+3. `src/App.vue` uses `PlayVueRouterProvider` + `createRouteMap(authMachine)` with a renderer function to connect router navigation and actor routing events.
+4. Provider waits for `router.isReady()` so direct URL loads are handled correctly.
+5. `src/Shell.vue` renders actor-projected state (`PlayRenderer`) and sends events back to the actor.
+6. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/main.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine, catalog });
+const actor = createPlayer();
+actor.start();
+
+const app = createApp(App);
+app.provide("actor", actor);
+app.use(router);
+app.mount("#app");
+```
+
+```ts
+// src/router.ts (shape)
+export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", component: RouteHost }];
+```
+
+```ts
+// src/App.vue (renderer shape)
+const renderShell = (currentActor, currentRouter) =>
+	h(Shell, {
+		actor: currentActor,
+		router: currentRouter,
+	});
+```
+
+```vue
+<!-- src/components/Login.vue (shape) -->
+<script setup lang="ts">
+const actor = inject("actor")!;
+const login = () => actor.send({ type: "auth.login", username: "demo" });
+</script>
+```
+
+## Key Files
+
+- `src/main.ts` - actor creation/start and app mount
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - provider wiring and renderer composition
+- `src/Shell.vue` - actor-driven demo shell with nav, renderer, and debug panel
+- `src/components/` - route and page view components
+- `test/browser/startup.browser.test.ts` - startup check for home + login link rendering
+- `test/browser/auth-flow.browser.test.ts` - login -> dashboard -> profile -> logout browser flow
+- `test/reactivity.test.ts` - reactive integration assertions
+
+## 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 `PlayVueRouterProvider` 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 uses 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 `PlayVueRouterProvider` 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
+
+```bash
+npm run dev           # Start Vite dev server (default: http://localhost:5173)
+npm run build         # Build production assets
+npm run preview       # Preview production build locally
+npm run test          # Run unit/integration tests via Vitest
+npm run test:browser  # Run browser-mode tests via vitest.browser.config.ts
+```
+
+## Verification
+
+Use these checks from this directory:
+
+```bash
+npm run test
+npm run test:browser
+```
+
+Manual sanity check:
+
+1. Start with `npm run dev`.
+2. Open `http://localhost:5173`.
+3. Confirm login/logout transitions update both view and URL, and that accessing protected routes while logged out redirects properly.
+
+## Learn More
+
+- **[Vue Router Adapter README](../play-vue-router/README.md)** - Package-level API and bridge docs

package/api/@xmachines/play-xstate/README.md

@@ -0,0 +1,512 @@
+[Documentation](../../README.md) / @xmachines/play-xstate
+
+# @xmachines/play-xstate
+
+**XState v5 adapter for Play Architecture with signal-driven reactivity and routing**
+
+Transform declarative state machines into live actors with TC39 Signals and parameter-aware navigation.
+
+## Overview
+
+`@xmachines/play-xstate` provides `definePlayer()`, the primary API for binding XState v5 state machines to the Play Architecture actor base. It enables business logic to control routing and state through guard-enforced transitions with catalog binding, signal lifecycle management, and XState DevTools compatibility.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+
+- **Actor Authority (INV-01):** State machine guards decide navigation validity
+- **Strict Separation (INV-02):** Zero React/framework imports in business logic
+- **Signal-Only Reactivity (INV-05):** TC39 Signals expose all state changes
+
+**Routing:** Supports `meta.route` patterns, `play.route` events with parameters, and route extraction.
+
+## Installation
+
+```bash
+npm install xstate@^5.0.0
+npm install @xmachines/play-xstate
+```
+
+**Peer dependencies:**
+
+- `xstate` ^5.0.0 — State machine runtime
+
+> `zod` is a direct dependency of `@xmachines/play-xstate` (not a peer). You do not need to install it separately unless you use it in your own catalog schemas.
+
+## Quick Start
+
+```typescript
+import { setup } from "xstate";
+import { z } from "zod";
+import { definePlayer } from "@xmachines/play-xstate";
+import { defineCatalog } from "@xmachines/play-catalog";
+
+// 1. Define XState machine with meta.route
+const machine = setup({
+	types: {
+		context: {} as { userId: string },
+		events: {} as { type: "play.route"; to: string } | { type: "auth.login"; userId: string },
+	},
+	guards: {
+		isLoggedIn: ({ context }) => !!context.userId,
+	},
+}).createMachine({
+	id: "app",
+	initial: "login",
+	context: { userId: "" },
+	states: {
+		login: {
+			id: "login",
+			meta: {
+				route: "/login",
+				view: { component: "LoginForm" },
+			},
+			on: {
+				"auth.login": {
+					guard: "isLoggedIn",
+					target: "dashboard",
+				},
+			},
+		},
+		dashboard: {
+			id: "dashboard",
+			meta: {
+				route: "/dashboard",
+				view: { component: "Dashboard", props: { userId: "" } },
+			},
+		},
+	},
+});
+
+// 2. Define catalog with Zod schemas
+const catalog = defineCatalog({
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({ userId: z.string() }),
+});
+
+// 3. Create player factory
+const createPlayer = definePlayer({ machine, catalog });
+
+// 4. Create and start actor
+const actor = createPlayer({ userId: "" });
+actor.start();
+
+// 5. Send events (play.route with parameters)
+actor.send({ type: "play.route", to: "/login" });
+
+// 6. Observe signals
+console.log(actor.currentRoute.get()); // "/login"
+console.log(actor.currentView.get()); // { component: "LoginForm", props: {...} }
+
+// 7. Cleanup
+actor.dispose();
+```
+
+## API Reference
+
+### definePlayer()
+
+Create a player factory from XState machine and catalog:
+
+```typescript
+const createPlayer = definePlayer<TMachine, TCatalog>({
+	machine: AnyStateMachine,
+	catalog?: Catalog,
+	options?: PlayerOptions,
+}): PlayerFactory;
+```
+
+**Config:**
+
+- `machine` (required) - XState v5 state machine
+- `catalog` (optional) - UI component catalog with Zod schemas
+- `options` (optional) - Lifecycle hooks
+
+**Returns:** Factory function `(input?) => PlayerActor`
+
+**Example:**
+
+```typescript
+const createPlayer = definePlayer({
+	machine: authMachine,
+	catalog: authCatalog,
+	options: {
+		onStart: (actor) => console.log("Started:", actor.id),
+		onTransition: (actor, prev, next) => {
+			console.log("Transition:", prev.value, "→", next.value);
+		},
+	},
+});
+
+const actor1 = createPlayer({ userId: "user1" });
+const actor2 = createPlayer({ userId: "user2" });
+// Multiple independent actor instances
+```
+
+### PlayerActor
+
+Concrete actor implementing Play signal protocol:
+
+**Signal Properties:**
+
+- `state: Signal.State<AnyMachineSnapshot>` — Reactive snapshot of current state
+- `currentRoute: Signal.Computed<string | null>` — Derived navigation path
+- `currentView: Signal.State<ViewMetadata | null>` — Current UI structure (updated at state entry)
+
+**Actor Properties:**
+
+- `catalog: Catalog` — Component catalog
+
+**Constructor:**
+
+```typescript
+new PlayerActor(machine, catalog, options, input?)
+```
+
+- `input` — Typed as `InputFrom<TMachine>`. Consumers receive compile-time validation against the machine's input schema. Pass initial context values required by the machine.
+
+**Methods:**
+
+- `start()` — Start the actor (must call after creation)
+- `stop()` — Stop the actor
+- `send(event: PlayEvent)` — Send event to actor
+- `dispose()` — Convenience cleanup (calls stop())
+
+**Prop validation modes** (via `PlayerOptions.propValidation`):
+
+- `"lenient"` (default) — On catalog prop validation failure, calls `onError` hook and renders with unvalidated props
+- `"strict"` — On catalog prop validation failure, calls `onError` hook and sets `currentView` to `null` (blocks render)
+
+**Example:**
+
+```typescript
+const actor = createPlayer();
+actor.start();
+
+// Observe signals with watcher
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const route = actor.currentRoute.get();
+		console.log("Route changed:", route);
+	});
+});
+watcher.watch(actor.currentRoute);
+actor.currentRoute.get(); // Initial read
+```
+
+### Guard Composition
+
+```typescript
+import {
+	composeGuards,
+	composeGuardsOr,
+	negateGuard,
+	hasContext,
+	eventMatches,
+	stateMatches,
+} from "@xmachines/play-xstate";
+
+const machine = setup({
+	guards: {
+		isLoggedIn: hasContext("userId"),
+		isAdmin: ({ context }) => context.role === "admin",
+	},
+}).createMachine({
+	on: {
+		accessAdmin: {
+			// Array means AND - all guards must pass
+			guard: composeGuards(["isLoggedIn", "isAdmin"]),
+			target: "adminPanel",
+		},
+		accessPublic: {
+			// OR composition - any guard passes
+			guard: composeGuardsOr(["isLoggedIn", ({ event }) => event.type === "guest.access"]),
+			target: "publicArea",
+		},
+		logout: {
+			// NOT composition
+			guard: negateGuard("isLoggedIn"),
+			target: "login",
+		},
+	},
+});
+```
+
+**Helpers:**
+
+- `hasContext(path: string)` - Check if context property is truthy
+- `eventMatches(type: string)` - Check event type
+- `stateMatches(value: string)` - Check state value
+- `composeGuards(guards: Array)` - AND composition
+- `composeGuardsOr(guards: Array)` - OR composition
+- `negateGuard(guard)` - NOT composition
+
+## Examples
+
+### Guard Placement Philosophy
+
+**Guards check if you can BE in a state (state entry), not if you can TAKE an event (event handlers).**
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { defineCatalog } from "@xmachines/play-catalog";
+
+// Pattern 1: RECOMMENDED - Use formatPlayRouteTransitions utility
+const machineConfig = {
+	id: "app",
+	initial: "home",
+	context: { isAuthenticated: false },
+	states: {
+		home: {
+			id: "home",
+			meta: { route: "/", view: { component: "Home" } },
+		},
+		dashboard: {
+			id: "dashboard",
+			meta: { route: "/dashboard", view: { component: "Dashboard" } },
+			// Always-guard validates state entry
+			always: [
+				{
+					target: "login",
+					guard: ({ context }) => !context.isAuthenticated,
+				},
+			],
+		},
+		login: {
+			id: "login",
+			meta: { route: "/login", view: { component: "Login" } },
+		},
+	},
+};
+
+// formatPlayRouteTransitions handles routing infrastructure
+const machine = setup({
+	types: {
+		events: {} as { type: "play.route"; to: string } | { type: "auth.login" },
+	},
+}).createMachine(formatPlayRouteTransitions(machineConfig));
+
+const catalog = defineCatalog({
+	Home,
+	Dashboard,
+	Login,
+});
+
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+actor.start();
+
+// Navigation via play.route event
+actor.send({ type: "play.route", to: "/dashboard" });
+// Guard validates: Can I BE in dashboard state?
+// If !isAuthenticated → redirects to login
+```
+
+**Why this works:**
+
+- `formatPlayRouteTransitions` adds routing infrastructure (event.to → state mapping)
+- Always-guards handle business logic (authentication checks)
+- Clear separation: routing is infrastructure, guards are business logic
+
+**Anti-pattern (DON'T DO THIS):**
+
+```typescript
+// ❌ WRONG - Guard on event checking event properties
+on: {
+  "play.route": {
+    guard: ({ event }) => event.to === "/dashboard",
+    target: "dashboard"
+  }
+}
+```
+
+**Reference:** See `docs/examples/routing-patterns.md` for canonical `formatPlayRouteTransitions` usage with always-guards for authentication.
+
+### Lifecycle Hooks
+
+```typescript
+const createPlayer = definePlayer({
+	machine,
+	catalog,
+	options: {
+		onStart: (actor) => {
+			console.log("Actor started:", actor.id);
+		},
+		onStop: (actor) => {
+			console.log("Actor stopped:", actor.id);
+		},
+		onTransition: (actor, prev, next) => {
+			console.log("State change:", {
+				from: prev.value,
+				to: next.value,
+				timestamp: Date.now(),
+			});
+		},
+		onStateChange: (actor, state) => {
+			// Called on every state update
+			console.log("Snapshot updated:", state.value);
+		},
+		onError: (actor, error) => {
+			console.error("Actor error:", error);
+			// Log to monitoring service, show error UI, etc.
+		},
+	},
+});
+```
+
+### XState DevTools Integration
+
+```typescript
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const { inspect } = createBrowserInspector();
+
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+actor.start();
+
+// PlayerActor maintains XState Inspector compatibility
+// Inspector displays:
+// - State transitions and values
+// - Context data
+// - Events sent to actor
+// - Guard evaluation results
+
+// Signals accessible via actor properties, not snapshots
+console.log(actor.currentRoute.get()); // "/dashboard"
+```
+
+## Metadata Conventions
+
+### Route Metadata
+
+```typescript
+// meta.route marks states as routable
+states: {
+	dashboard: {
+		id: "dashboard",
+		meta: {
+			route: "/dashboard", // URL path - marks state as routable
+		},
+	},
+}
+
+// Parameters
+meta: {
+	route: "/profile/:userId", // Required parameter
+	route: "/settings/:section?", // Optional parameter
+}
+
+// Inheritance
+meta: {
+	route: "/absolute", // Starts with / → doesn't inherit parent route
+	route: "relative", // Doesn't start with / → inherits parent route
+}
+```
+
+### View Metadata
+
+```typescript
+meta: {
+	view: {
+		component: "Dashboard", // Must exist in catalog
+		props: { userId: "user123" }, // Validated against Zod schema
+		title: "Dashboard", // Additional metadata
+	},
+}
+
+// Dynamic props from context
+meta: {
+	view: {
+		component: "Dashboard",
+		props: (context) => ({
+			userId: context.userId,
+			notifications: context.unreadCount,
+		}),
+	},
+}
+```
+
+## Architecture
+
+This package implements RFC Play v1 requirements:
+
+**Architectural Invariants:**
+
+- **Actor Authority (INV-01):** Guards decide navigation validity
+- **Strict Separation (INV-02):** Zero framework imports
+- **Signal-Only Reactivity (INV-05):** All state via TC39 Signals
+
+**XState DevTools:** Maintains Inspector compatibility — snapshots remain pure XState format, signals accessible via actor properties.
+
+**Routing:**
+
+- `meta.route` property marks states as routable
+- `play.route` events support parameters (enhancement)
+- Route extraction for URL patterns
+
+**Note:** Route parameter extraction uses URLPattern API. See [@xmachines/play-tanstack-react-router browser support](../play-tanstack-react-router/README.md) for polyfill requirements.
+
+## Related Packages
+
+- **[@xmachines/play-actor](../play-actor/README.md)** - AbstractActor base class
+- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals polyfill
+- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
+- **[@xmachines/play-router](../play-router/README.md)** - Route extraction
+- **[@xmachines/play](../play/README.md)** - Protocol types (PlayEvent)
+
+## License
+
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.
+
+@xmachines/play-xstate - XState v5 adapter for Play Architecture
+
+Provides definePlayer() API for binding XState state machines to the
+actor base with catalog binding, signal lifecycle, and DevTools integration.
+
+Per RFC Play v1, this package implements the Logic Layer adapter that
+transforms declarative machine definitions into live actors with signal-driven
+reactivity.
+
+## Classes
+
+- [PlayerActor](classes/PlayerActor.md)
+
+## Interfaces
+
+- [CatalogEntry](interfaces/CatalogEntry.md)
+- [PlayerConfig](interfaces/PlayerConfig.md)
+- [PlayerOptions](interfaces/PlayerOptions.md)
+- [RouteContext](interfaces/RouteContext.md)
+
+## Type Aliases
+
+- [Catalog](type-aliases/Catalog.md)
+- [ComposedGuard](type-aliases/ComposedGuard.md)
+- [Guard](type-aliases/Guard.md)
+- [GuardArray](type-aliases/GuardArray.md)
+- [PlayerFactory](type-aliases/PlayerFactory.md)
+- [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
+- [RouteStateNode](type-aliases/RouteStateNode.md)
+- [ValidationResult](type-aliases/ValidationResult.md)
+- [ViewMergeContext](type-aliases/ViewMergeContext.md)
+
+## Functions
+
+- [buildRouteUrl](functions/buildRouteUrl.md)
+- [composeGuards](functions/composeGuards.md)
+- [composeGuardsOr](functions/composeGuardsOr.md)
+- [definePlayer](functions/definePlayer.md)
+- [deriveRoute](functions/deriveRoute.md)
+- [eventMatches](functions/eventMatches.md)
+- [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
+- [hasContext](functions/hasContext.md)
+- [isAbsoluteRoute](functions/isAbsoluteRoute.md)
+- [mergeViewProps](functions/mergeViewProps.md)
+- [negateGuard](functions/negateGuard.md)
+- [stateMatches](functions/stateMatches.md)
+- [validateComponentBinding](functions/validateComponentBinding.md)
+- [validateViewProps](functions/validateViewProps.md)