@xmachines/docs 1.0.0-beta.33 → 1.0.0-beta.35

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

@@ -8,7 +8,7 @@ Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play arch
 
 - Shared auth machine reused without framework-specific business logic
 - `connectRouter` pathname URL ↔ actor sync via `@xmachines/play-sveltekit-router`
-- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Shell-driven rendering via `PlayUIProvider` + `PlayRenderer` with actor-authoritative navigation
 - Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
 - Non-browser invariant tests plus browser E2E coverage
 
@@ -30,8 +30,8 @@ Use this order to understand the implementation:
 1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
 2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
 3. `connectRouter` synchronizes browser pathname changes with the actor via `play.route` events and reflects actor-approved routes back to the pathname URL.
-4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
+4. `src/App.svelte` imports the singleton `actor` and `registryResult` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
@@ -52,20 +52,18 @@ export function cleanupDemo(): void {
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
-	import { actor, registry } from "./lib/router.js";
+	import { Shell } from "@xmachines/play-svelte-demo";
+	import { actor, registryResult } from "./lib/router.js";
 </script>
 
-<Shell {actor} {registry} />
+<Shell {actor} {registryResult} />
 ```
 
 ```svelte
-<!-- Shell.svelte — sending events (shape) -->
-<PlayRenderer
-	actor={props.actor}
-	registry={props.registry}
-	actions={{ login: "auth.login", logout: "auth.logout" }}
-/>
+<!-- Shell.svelte — rendering (shape) -->
+<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
 ## Key Files
@@ -126,5 +124,5 @@ Expected result: library-pattern invariant tests pass and the browser demo suite
 
 ## Learn More
 
-- [SvelteKit Router package README](../../README.md)
-- [Svelte package README](../../../play-svelte/README.md)
+- [SvelteKit Router](../../README.md)
+- [Svelte](../../../play-svelte)

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

@@ -125,6 +125,6 @@ Expected result: invariant test suite and the browser shared-demo suite both pas
 
 ## Learn More
 
-- [TanStack React Router package README](../../README.md)
-- [React package README](../../../play-react/README.md)
-- [TanStack Solid Router demo README](../../../play-tanstack-solid-router/examples/demo/README.md)
+- [TanStack React Router](../../README.md)
+- [React](../../../play-react)
+- [TanStack Solid Router](../../../play-tanstack-solid-router/examples/demo)

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

@@ -119,7 +119,7 @@ Expected result: library-pattern invariant tests and the browser shared-demo sui
 
 ## Learn More
 
-- [TanStack Solid Router package README](../../README.md)
-- [SolidJS package README](../../../play-solid/README.md)
-- [Solid Router demo README](../../../play-solid-router/examples/demo/README.md)
-- [TanStack React Router demo README](../../../play-tanstack-react-router/examples/demo/README.md)
+- [TanStack Solid Router](../../README.md)
+- [SolidJS](../../../play-solid)
+- [Solid Router](../../../play-solid-router/examples/demo)
+- [TanStack React Router](../../../play-tanstack-react-router/examples/demo)

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

@@ -29,15 +29,16 @@ Use this order to understand the implementation:
 
 1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, and mounts the Vue app.
 2. The actor is provided to all components via `app.provide("actor", actor)`.
-3. `src/App.vue` injects the actor and builds the component registry with `defineRegistry(authCatalog, { components, actions })`.
-4. `<PlayRenderer :actor="actor" :registry="registry" :actions="..." />` observes actor view signals and renders the active view component.
-5. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
-6. Browser tests in `test/browser/` validate startup and interaction behavior.
+3. `src/App.vue` injects the actor and builds the typed `registryResult` with `defineRegistry(authCatalog, { components, actions })` inside `computed` — real async action handlers dispatching to `actor.send()`.
+4. `<PlayUIProvider :actor="actor" :registryResult="registryResult"><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
+5. A `NavBar` SFC observes `actor` signals directly for nav visibility.
+6. `<DebugPanel :actor="actor" />` shows live state, auth status, and current route.
+7. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
+8. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```ts
 // src/main.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine });
-const actor = createPlayer();
+const actor = definePlayer({ machine: authMachine })();
 actor.start();
 
 const app = createApp(App);
@@ -48,46 +49,63 @@ app.mount("#app");
 ```vue
 <!-- src/App.vue (shape) -->
 <script setup lang="ts">
-const actor = inject<AuthActor>("actor")!;
-
-const { registry } = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-	},
-	actions: { login: async () => {}, logout: async () => {} },
-});
+const typedActor = assertNonNullable(inject<AuthActor>("actor"), "actor");
+
+const registryResult = computed(() =>
+	defineRegistry(authCatalog, {
+		components: {
+			Home: HomeSFC,
+			About: AboutSFC,
+			Contact: ContactSFC,
+			Login: LoginSFC,
+			Dashboard: DashboardSFC,
+			Overview: OverviewSFC,
+			Stats: StatsSFC,
+			Profile: ProfileSFC,
+			Settings: SettingsSFC,
+			Navigation: NavigationSFC,
+			NavBar: NavBarViewSFC,
+		},
+		actions: {
+			login: async (args) =>
+				typedActor.send({
+					type: "auth.login",
+					username: assertNonNullable(args, "args").username,
+				}),
+			logout: async () => typedActor.send({ type: "auth.logout" }),
+			route: async (args) => {
+				const { to, params } = assertNonNullable(args, "args");
+				typedActor.send({
+					type: "play.route",
+					to,
+					...(params != null && { params }),
+				});
+			},
+		},
+	}),
+);
 </script>
 
 <template>
-	<PlayRenderer
-		:actor="actor"
-		:registry="registry"
-		:actions="{ login: 'auth.login', logout: 'auth.logout' }"
-	/>
+	<div class="demo-app" data-demo-shell>
+		<header class="demo-header">
+			<h1 class="demo-title">XMachines Play Vue Demo</h1>
+			<NavBar :actor="typedActor" />
+		</header>
+		<main class="demo-content" data-demo-content>
+			<PlayUIProvider :actor="typedActor" :registryResult="registryResult">
+				<PlayRenderer />
+			</PlayUIProvider>
+		</main>
+		<DebugPanel :actor="typedActor" />
+	</div>
 </template>
 ```
 
-```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 Vue app mount with actor injection
-- `src/App.vue` - registry construction and `PlayRenderer` composition
+- `src/App.vue` - registry construction and `PlayUIProvider` + `PlayRenderer` composition
 - `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
@@ -141,5 +159,14 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Learn More
 
-- [Vue package README](../../README.md)
-- [Vue Router demo README](../../../play-vue-router/examples/demo/README.md)
+- [Vue](../../README.md)
+- [Vue Router](../../../play-vue-router/examples/demo)
+
+## Type Aliases
+
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+
+## Variables
+
+- [App](variables/App.md)
+- [authCatalog](variables/authCatalog.md)

package/examples/@xmachines/play-vue-demo/type-aliases/AuthCatalog.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / AuthCatalog
+
+# Type Alias: AuthCatalog
+
+```ts
+type AuthCatalog = typeof authCatalog;
+```
+
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/play-vue/examples/demo/src/catalog.ts#L6)

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / App
+
+# Variable: App
+
+```ts
+const App: DefineComponent<{}, {}, unknown>;
+```
+
+Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.35/packages/play-vue/examples/demo/src/env.d.ts#L5)

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

@@ -0,0 +1,172 @@
+[Documentation](../../../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.0.0-beta.35/packages/play-vue/examples/demo/src/catalog.ts#L5)

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

@@ -27,21 +27,17 @@ Then open `http://localhost:3001`.
 
 Use this order to understand how the demo is wired:
 
-1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, creates the Vue app, provides the actor, installs Vue Router, and mounts.
-2. `src/router.ts` installs a single catch-all route; `PlayRenderer` selects the actual view from actor state.
-3. `src/App.vue` calls `createRouteMap(authMachine)` and renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` renderer function.
-4. The renderer function creates the shared `Shell` component with actor, router, and registry as props.
-5. `PlayRouterProvider` waits for `router.isReady()` so direct URL loads are handled correctly.
-6. Browser tests in `test/browser/` validate startup and auth route transitions.
+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 createPlayer = definePlayer({ machine: authMachine });
-const actor = createPlayer();
-actor.start();
-
 const app = createApp(App);
-app.provide("actor", actor);
 app.use(router);
 app.mount("#app");
 ```
@@ -54,11 +50,10 @@ export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", compo
 ```vue
 <!-- src/App.vue (shape) -->
 <script setup lang="ts">
-const actor = inject<AuthActor>("actor")!;
-const routeMap = createRouteMap(authMachine);
+import { actor, routeMap, registryResult } from "./runtime.js";
 
 const renderShell = (currentActor, currentRouter) =>
-	h(SharedShell, { actor: currentActor, router: currentRouter, registry });
+	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult });
 </script>
 
 <template>
@@ -71,19 +66,21 @@ const renderShell = (currentActor, currentRouter) =>
 </template>
 ```
 
-```vue
-<!-- src/components/Login.vue (shape) -->
-<script setup lang="ts">
-const actor = inject("actor")!;
-const login = () => actor.send({ type: "auth.login", username: "demo" });
-</script>
+```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` - actor creation/start and Vue app mount with actor injection
+- `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` - `createRouteMap`, `PlayRouterProvider` wiring, and renderer composition
+- `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
 
@@ -136,5 +133,5 @@ Expected result: reactivity integration tests and the browser shared-demo suite
 
 ## Learn More
 
-- [Vue Router package README](../../README.md)
-- [Vue package README](../../../play-vue/README.md)
+- [Vue Router](../../README.md)
+- [Vue](../../../play-vue)

package/examples/README.md

@@ -34,6 +34,7 @@ Complete working implementations of actor-authoritative routing with all archite
 - [@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)
+
 <!-- typedoc:renderer-demos:end -->
 
 ### Router Demos
@@ -48,6 +49,7 @@ Complete working implementations of actor-authoritative routing with all archite
 - [@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

package/examples/form-validation.md

@@ -90,12 +90,9 @@ const loginMachine = loginSetup.createMachine(
 				meta: {
 					route: "/",
 					view: {
-						component: "Home",
-						spec: {
-							root: "root",
-							elements: {
-								root: { type: "Home", props: { title: "Welcome" }, children: [] },
-							},
+						root: "root",
+						elements: {
+							root: { type: "Home", props: { title: "Welcome" }, children: [] },
 						},
 					},
 				},
@@ -106,26 +103,23 @@ const loginMachine = loginSetup.createMachine(
 				meta: {
 					route: "/login",
 					view: {
-						component: "Login",
-						spec: {
-							root: "root",
-							// Local state store — initial value shown in the form field
-							state: { username: "" },
-							elements: {
-								root: {
-									type: "Login",
-									props: {
-										title: "Sign In",
-										// $bindState wires the prop to the local state store (two-way)
-										username: { $bindState: "/username" },
-									},
-									children: [],
-									on: {
-										// emit("submit") → resolves username from $state, calls login action
-										submit: {
-											action: "login",
-											params: { username: { $state: "/username" } },
-										},
+						root: "root",
+						// Local state store — initial value shown in the form field
+						state: { username: "" },
+						elements: {
+							root: {
+								type: "Login",
+								props: {
+									title: "Sign In",
+									// $bindState wires the prop to the local state store (two-way)
+									username: { $bindState: "/username" },
+								},
+								children: [],
+								on: {
+									// emit("submit") → resolves username from $state, calls login action
+									submit: {
+										action: "login",
+										params: { username: { $state: "/username" } },
 									},
 								},
 							},
@@ -139,17 +133,14 @@ const loginMachine = loginSetup.createMachine(
 				meta: {
 					route: "/dashboard",
 					view: {
-						component: "Dashboard",
-						spec: {
-							root: "root",
-							elements: {
-								root: {
-									type: "Dashboard",
-									props: { title: "Dashboard" },
-									children: [],
-									on: {
-										logout: { action: "logout" },
-									},
+						root: "root",
+						elements: {
+							root: {
+								type: "Dashboard",
+								props: { title: "Dashboard" },
+								children: [],
+								on: {
+									logout: { action: "logout" },
 								},
 							},
 						},
@@ -193,18 +184,18 @@ actor.stop();
 
 ## `$bindState` and `$state` Pattern
 
-`meta.view.spec` uses the `@json-render/core` spec format. Two special directives wire the component to a local per-state state store:
+`meta.view` uses the `@json-render/core` spec format (`PlaySpec`). Two special directives wire the component to a local per-state state store:
 
 | Directive                     | Direction | Usage                                                       |
 | ----------------------------- | --------- | ----------------------------------------------------------- |
 | `{ $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:` object in the spec 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 renderer keeps the store in sync. On submit, action params read the final value via `$state`.
 
 ```typescript
-// In the machine spec — the renderer handles the rest:
-spec: {
+// In the machine meta.view — the renderer handles the rest:
+view: {
   root: "root",
   state: { username: "" },         // initial store value
   elements: {
@@ -307,7 +298,7 @@ window.addEventListener("beforeunload", () => {
 
 **Key points:**
 
-- `actions` in `defineCatalog` must include every action name referenced in `meta.view` spec `on:` bindings. TypeScript enforces this via `CatalogHasActions`.
+- `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.
 

package/guides/README.md

@@ -9,6 +9,14 @@ Entry points for the current XMachines Play architecture.
 - **[Installation](installation.md)** — Core packages, framework-specific additions, TypeScript config, ESM setup
 - **[Getting Started](getting-started.md)** — `setup().createMachine()` → `definePlayer()` → `actor.start()` → TC39 Signals
 
+## Concepts
+
+Background reading that explains the _why_ behind XMachines design decisions. Read these when you want to understand the architecture, not just use the API.
+
+- **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags, scattered guards, and component-level routing logic
+- **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, what `AbstractActor` enforces, why the machine has zero framework imports, and how the reset invariant works
+- **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the five architectural invariants they enforce
+
 ## Examples
 
 - **[Examples Index](../examples/README.md)** — Conceptual patterns and complete runnable demo applications