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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.34",
+  "version": "1.0.0-beta.35",
   "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.35",
     "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:**
 

package/api/@xmachines/play-vue-router/classes/VueBaseRouteMap.md

@@ -1,141 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / VueBaseRouteMap
-
-# Class: VueBaseRouteMap
-
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-router/src/base-route-map.ts#L100)
-
-Shared bidirectional route map base class.
-
-All framework adapter `RouteMap` classes extend this — they add no logic of their
-own and inherit the full public API from here.
-
-**Lookup strategy:**
-
-- Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
-  of routes sharing the same first path segment
-- Results are cached after the first match in an LRU cache (default 500 entries,
-  configurable via the `cacheSize` constructor option)
-
-**Pattern syntax** (`:param` / `:param?`):
-
-- `:param` — required segment, matches exactly one non-`/` segment
-- `:param?` — optional segment, matches zero or one non-`/` segment
-
-## Example
-
-```typescript
-import { BaseRouteMap } from "@xmachines/play-router";
-
-const map = new BaseRouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
-
-map.getStateIdByPath("/"); // "home"
-map.getStateIdByPath("/profile/123"); // "profile"
-map.getStateIdByPath("/settings"); // "settings"
-map.getStateIdByPath("/unknown"); // null
-
-map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("missing"); // null
-```
-
-## Extended by
-
-- [`RouteMap`](RouteMap.md)
-
-## Constructors
-
-### Constructor
-
-```ts
-new VueBaseRouteMap(mappings, options?): BaseRouteMap;
-```
-
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-router/src/base-route-map.ts#L125)
-
-Build a route map from an array of state ID ↔ path mappings.
-
-Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `URLPattern` and grouped into first-segment
-buckets for efficient candidate selection.
-
-#### Parameters
-
-| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
-| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
-| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
-| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
-
-#### Returns
-
-`BaseRouteMap`
-
-## Methods
-
-### getPathByStateId()
-
-```ts
-getPathByStateId(stateId): string | null;
-```
-
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-router/src/base-route-map.ts#L209)
-
-Look up the path pattern registered for a state ID.
-
-#### Parameters
-
-| Parameter | Type     | Description                                               |
-| --------- | -------- | --------------------------------------------------------- |
-| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
-
-#### Returns
-
-`string` \| `null`
-
-The registered path pattern, or `null` if the state ID is unknown
-
-#### Example
-
-```typescript
-map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("missing"); // null
-```
-
----
-
-### getStateIdByPath()
-
-```ts
-getStateIdByPath(path): string | null;
-```
-
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-router/src/base-route-map.ts#L174)
-
-Resolve a URL path to its mapped state ID.
-
-Strips query strings and hash fragments before matching. Tries an O(1) exact
-lookup first, then falls back to bucket-indexed pattern matching. Results are
-cached after the first pattern match.
-
-#### Parameters
-
-| Parameter | Type     | Description                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------ |
-| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
-
-#### Returns
-
-`string` \| `null`
-
-The mapped state ID, or `null` if no route matches
-
-#### Example
-
-```typescript
-map.getStateIdByPath("/profile/123"); // "profile"
-map.getStateIdByPath("/unknown"); // null
-```