@xmachines/docs 1.0.0-beta.34 → 1.0.0-beta.36

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

@@ -0,0 +1,172 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-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-svelte/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.36/packages/play-svelte/examples/demo/src/catalog.ts#L5)

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

@@ -123,5 +123,5 @@ Expected result: library-pattern invariant tests pass and the browser demo suite
 
 ## Learn More
 
-- [Svelte SPA Router package README](../../README.md)
-- [Svelte package README](../../../play-svelte/README.md)
+- [Svelte SPA Router](../../README.md)
+- [Svelte](../../../play-svelte)

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

@@ -124,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

@@ -159,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.36/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.36/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.36/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.34",
+  "version": "1.0.0-beta.36",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -49,7 +49,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.34",
+    "@xmachines/shared": "1.0.0-beta.36",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0",
     "typedoc": "^0.28.19",

package/rfc/play.md

@@ -20,24 +20,24 @@ The reference implementation provides a modular monorepo that satisfies the arch
 ### 2.1 Roles
 
 - **The Actor (Logic Engine)**
-  - Pure, environment-agnostic logic runtime
-  - Owns state, guards, errors, and route validity
-  - Emits _Virtual Routes_ as derived intent
+    - Pure, environment-agnostic logic runtime
+    - Owns state, guards, errors, and route validity
+    - Emits _Virtual Routes_ as derived intent
 
 - **The Runtime Adapter (Infrastructure Layer)**
-  - Environment-specific adapter (Browser, Native, Server, Test Runner)
-  - Reflects Actor output into the environment
-  - Forwards environment events to the Actor without interpretation
+    - Environment-specific adapter (Browser, Native, Server, Test Runner)
+    - Reflects Actor output into the environment
+    - Forwards environment events to the Actor without interpretation
 
 - **The View**
-  - Passive consumer of Actor state
-  - No business rules or routing authority
+    - Passive consumer of Actor state
+    - No business rules or routing authority
 
 ### 2.2 Communication Medium
 
 - **Signals (TC39 Proposal)**
-  - Used exclusively for Actor ↔ Adapter communication
-  - Enables synchronous, glitch-free propagation
+    - Used exclusively for Actor ↔ Adapter communication
+    - Enables synchronous, glitch-free propagation
 
 ---
 
@@ -75,9 +75,9 @@ The reference implementation provides a modular monorepo that satisfies the arch
 - Defines **Virtual Routes** as metadata on state nodes
 - Validates all incoming navigation intents
 - On invalid intent:
-  1. Transitions to an error or fallback state
-  2. Emits a corresponding Virtual Route (e.g. `/error`, `/login`)
-  3. Forces the environment to realign with Actor state
+    1. Transitions to an error or fallback state
+    2. Emits a corresponding Virtual Route (e.g. `/error`, `/login`)
+    3. Forces the environment to realign with Actor state
 
 The Actor has zero knowledge of:
 
@@ -114,9 +114,9 @@ Wraps the TC39 Signals (Stage 1) polyfill. By isolating the reactive primitive w
 **Exports:**
 
 - `Signal` — Re-exported namespace from `signal-polyfill`:
-  - `Signal.State` — Actor output snapshot
-  - `Signal.Computed` — Lazy, pull-based derivation of routes and views
-  - `Signal.subtle.Watcher` — Synchronous observation for Runtime Adapters
+    - `Signal.State` — Actor output snapshot
+    - `Signal.Computed` — Lazy, pull-based derivation of routes and views
+    - `Signal.subtle.Watcher` — Synchronous observation for Runtime Adapters
 - `watchSignal` — Convenience function: subscribes to a single signal with a one-shot watcher lifecycle and microtask batching; returns a cleanup function
 
 #### 5.1.2 `@xmachines/play`
@@ -246,9 +246,9 @@ Provides the complete routing infrastructure: route extraction from state machin
 - `RouterBridge` — Interface: `{ connect(): void; disconnect(): void }`
 - `PlayRouteEvent` — Routing event: `{ type: 'play.route'; to: string; params?; query?; match? }`
 - `RouterBridgeBase` — Abstract base class that encapsulates common bridge logic (signal watching, route synchronization, param/query extraction). Subclasses implement only three methods:
-  - `navigateRouter(path)` — Push a path into the framework router
-  - `watchRouterChanges()` — Subscribe to framework router navigation events
-  - `unwatchRouterChanges()` — Unsubscribe from framework router events
+    - `navigateRouter(path)` — Push a path into the framework router
+    - `watchRouterChanges()` — Subscribe to framework router navigation events
+    - `unwatchRouterChanges()` — Unsubscribe from framework router events
 
 **Route Extraction Exports:**