@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.17

package/api/@xmachines/play-xstate/interfaces/PlayerOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayerOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L28)
+Defined in: [packages/play-xstate/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L20)
 
 Player lifecycle hooks
 
@@ -16,11 +16,10 @@ Per CONTEXT.md: Rich set of hooks for observability
 
 ## Properties
 
-| Property                                               | Type                                          | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                                                     |
-| ------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-onerror"></a> `onError?`               | (`actor`, `error`) => `void`                  | Called on actor errors                                                                                                                                                                                                                                                                                                                                              | [packages/play-xstate/src/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L46) |
-| <a id="property-onstart"></a> `onStart?`               | (`actor`) => `void`                           | Called when actor starts                                                                                                                                                                                                                                                                                                                                            | [packages/play-xstate/src/types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L30) |
-| <a id="property-onstatechange"></a> `onStateChange?`   | (`actor`, `state`) => `void`                  | Called when state signal changes                                                                                                                                                                                                                                                                                                                                    | [packages/play-xstate/src/types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L43) |
-| <a id="property-onstop"></a> `onStop?`                 | (`actor`) => `void`                           | Called when actor stops                                                                                                                                                                                                                                                                                                                                             | [packages/play-xstate/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L33) |
-| <a id="property-ontransition"></a> `onTransition?`     | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition                                                                                                                                                                                                                                                                                                                                    | [packages/play-xstate/src/types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L36) |
-| <a id="property-propvalidation"></a> `propValidation?` | `"strict"` \| `"lenient"`                     | Prop validation failure mode (default: 'lenient') - 'lenient': On validation failure, call onError hook and render with unvalidated props (current behavior). Documents as explicit trade-off. - 'strict': On validation failure, call onError hook and set viewSignal to null (no render). Blocks rendering until machine transitions to a state with valid props. | [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L57) |
+| Property                                             | Type                                          | Description                      | Defined in                                                                                                                                     |
+| ---------------------------------------------------- | --------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                  | Called on actor errors           | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L38) |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                           | Called when actor starts         | [packages/play-xstate/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L22) |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                  | Called when state signal changes | [packages/play-xstate/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L35) |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                           | Called when actor stops          | [packages/play-xstate/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L25) |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition | [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L28) |

package/api/@xmachines/play-xstate/interfaces/RouteContext.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteContext
 
-Defined in: [packages/play-xstate/src/routing/types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/types.ts#L11)
+Defined in: [packages/play-xstate/src/routing/types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/types.ts#L11)
 
 Route build context from machine context
 
@@ -16,7 +16,7 @@ Route build context from machine context
 
 | Property                                         | Type                            | Description                    | Defined in                                                                                                                                                     |
 | ------------------------------------------------ | ------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?`       | `string`                        | Base path for relative routes  | [packages/play-xstate/src/routing/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/types.ts#L13) |
-| <a id="property-hash"></a> `hash?`               | `string`                        | Hash fragment                  | [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/types.ts#L19) |
-| <a id="property-query"></a> `query?`             | `Record`\<`string`, `unknown`\> | Query parameters               | [packages/play-xstate/src/routing/types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/types.ts#L17) |
-| <a id="property-routeparams"></a> `routeParams?` | `Record`\<`string`, `unknown`\> | Route parameters to substitute | [packages/play-xstate/src/routing/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/types.ts#L15) |
+| <a id="property-basepath"></a> `basePath?`       | `string`                        | Base path for relative routes  | [packages/play-xstate/src/routing/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/types.ts#L13) |
+| <a id="property-hash"></a> `hash?`               | `string`                        | Hash fragment                  | [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/types.ts#L19) |
+| <a id="property-query"></a> `query?`             | `Record`\<`string`, `unknown`\> | Query parameters               | [packages/play-xstate/src/routing/types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/types.ts#L17) |
+| <a id="property-routeparams"></a> `routeParams?` | `Record`\<`string`, `unknown`\> | Route parameters to substitute | [packages/play-xstate/src/routing/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/types.ts#L15) |

package/api/@xmachines/play-xstate/type-aliases/ComposedGuard.md

@@ -6,7 +6,7 @@
 type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/guards/compose.ts#L14)
+Defined in: [packages/play-xstate/src/guards/compose.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/guards/compose.ts#L14)
 
 Narrowest public return type for guard composition helpers.
 

package/api/@xmachines/play-xstate/type-aliases/Guard.md

@@ -6,7 +6,7 @@
 type Guard<TContext, TEvent> = (args) => boolean;
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/guards/types.ts#L13)
+Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/guards/types.ts#L13)
 
 Standard XState guard function signature
 

package/api/@xmachines/play-xstate/type-aliases/GuardArray.md

@@ -6,7 +6,7 @@
 type GuardArray<TContext, TEvent> = Guard<TContext, TEvent>[] | string[];
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/guards/types.ts#L23)
+Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/guards/types.ts#L23)
 
 Array of guard predicates or guard names
 

package/api/@xmachines/play-xstate/type-aliases/PlayerFactory.md

@@ -6,7 +6,7 @@
 type PlayerFactory<TMachine> = (input?, options?) => PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/types.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/types.ts#L76)
+Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/types.ts#L57)
 
 Factory function returned by definePlayer()
 

package/api/@xmachines/play-xstate/type-aliases/RouteMachineConfig.md

@@ -6,7 +6,17 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L29)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L52)
+
+Minimal structural constraint for machine configs accepted by
+`formatPlayRouteTransitions`.
+
+This is intentionally loose so the function accepts both the bare `createMachine`
+config object and the stricter `setup().createMachine` config without requiring
+any type casts at the call site. The generic `T extends RouteMachineConfig`
+parameter on `formatPlayRouteTransitions` preserves the original concrete type
+through the transform, so the return value remains directly usable by
+`setup().createMachine()`.
 
 ## Indexable
 
@@ -22,7 +32,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:2
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L53)
 
 ---
 
@@ -32,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:3
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L55)
 
 ---
 
@@ -42,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:3
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L31)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L54)

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -6,7 +6,14 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L21)
+
+Minimal structural shape of a single XState state node as read by
+`formatPlayRouteTransitions` when crawling the machine config.
+
+Only the fields the function actually inspects are typed here; all other
+state-node fields (e.g. `on`, `entry`, `after`) pass through unmodified via
+the index signature.
 
 ## Indexable
 
@@ -22,7 +29,9 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L14)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L23)
+
+Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
 ---
 
@@ -32,7 +41,9 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L25)
+
+State metadata — `meta.route` marks the state as routable.
 
 #### route?
 
@@ -40,6 +51,8 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 optional route?: string;
 ```
 
+URL path template (e.g. `"/profile/:username"`, `"/settings/:section?"`).
+
 ---
 
 ### states?
@@ -48,4 +61,6 @@ optional route?: string;
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-xstate/src/routing/format-play-route-transitions.ts#L18)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+
+Nested child states, recursively crawled for additional route declarations.

package/api/@xmachines/shared/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): object;
 ```
 
-Defined in: [src/index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/shared/src/index.ts#L10)
+Defined in: [src/index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/shared/src/index.ts#L10)
 
 Create a Vitest config with XMachines workspace defaults.
 
@@ -26,4 +26,4 @@ render it under `@xmachines/shared` instead of nested module pages.
 
 | Name   | Type  | Defined in                                                                                                                   |
 | ------ | ----- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `test` | `any` | [config/vitest.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/shared/config/vitest.ts#L82) |
+| `test` | `any` | [config/vitest.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/shared/config/vitest.ts#L82) |

package/api/@xmachines/shared/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [src/index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/shared/src/index.ts#L20)
+Defined in: [src/index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/shared/src/index.ts#L20)
 
 Build Vite/Vitest alias entries for all `@xmachines/*` workspace packages.
 

package/api/README.md

@@ -32,7 +32,7 @@ Generated API documentation for the XMachines JavaScript/TypeScript packages.
 
 - [@xmachines/play](@xmachines/play/README.md)
 - [@xmachines/play-actor](@xmachines/play-actor/README.md)
-- [@xmachines/play-catalog](@xmachines/play-catalog/README.md)
+- [@xmachines/play-dom](@xmachines/play-dom/README.md)
 - [@xmachines/play-react](@xmachines/play-react/README.md)
 - [@xmachines/play-react-router](@xmachines/play-react-router/README.md)
 - [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)

package/api/llms.txt

@@ -25,7 +25,7 @@
 ## API
 - [@xmachines/play](@xmachines/play/README.md): Core Play types and runtime contracts
 - [@xmachines/play-actor](@xmachines/play-actor/README.md): Abstract actor base class plus Routable and Viewable capabilities
-- [@xmachines/play-catalog](@xmachines/play-catalog/README.md): Catalog schemas and typed component registration
+- [@xmachines/play-dom](@xmachines/play-dom/README.md): Vanilla DOM renderer for Viewable actors
 - [@xmachines/play-signals](@xmachines/play-signals/README.md): Signal primitives used by Play actors and adapters
 - [@xmachines/play-router](@xmachines/play-router/README.md): Route extraction, route maps, and shared routing infrastructure
 - [@xmachines/play-xstate](@xmachines/play-xstate/README.md): XState-backed player and actor integration
@@ -50,20 +50,26 @@
 ## Quick Reference
 
 ```javascript
-import { definePlayer } from '@xmachines/play-xstate';
+import { definePlayer, formatPlayRouteTransitions } from '@xmachines/play-xstate';
 import { extractMachineRoutes } from '@xmachines/play-router';
+import { defineRegistry } from '@json-render/react';
+import { PlayRenderer } from '@xmachines/play-react';
 
-// Define a player from a machine and catalog
-const createPlayer = definePlayer({ machine, catalog });
+// Define a player from a machine
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start();
 
 // `Viewable` actors expose renderable view metadata
-const currentView = actor.currentView.get();
+const currentView = actor.currentView.get(); // { component, spec }
 
 // `Routable` actors expose route state for adapters to observe
 const currentRoute = actor.currentRoute.get();
 
 // Extract route metadata for a framework adapter
 const routeTree = extractMachineRoutes(machine);
+
+// Wire components to catalog and render
+const { registry } = defineRegistry(catalog, { components, actions });
+<PlayRenderer actor={actor} registry={registry} actions={{ login: 'auth.login' }} />
 ```

package/examples/multi-router-integration.md

@@ -37,7 +37,8 @@ All providers use a `renderer` prop that receives the actor and returns a ReactN
 All providers require `routeMap` as an explicit prop. Routers fundamentally don't know about Play state IDs — the map bridges the gap:
 
 ```typescript
-const routeTree = createPlayRouter({ machine });
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
 const router = createRouter({ routeTree, history: createMemoryHistory() });
 
 <PlayTanStackRouterProvider
@@ -70,7 +71,8 @@ For runnable implementations of these router integration patterns, see the [Exam
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { createRouter, createMemoryHistory } from '@tanstack/react-router';
-import { createPlayRouter, PlayTanStackRouterProvider } from '@xmachines/play-tanstack-react-router';
+import { PlayTanStackRouterProvider, createRouteMapFromTree } from '@xmachines/play-tanstack-react-router';
+import { extractMachineRoutes } from '@xmachines/play-router';
 import { PlayRenderer } from '@xmachines/play-react';
 import { definePlayer } from '@xmachines/play-xstate';
 
@@ -79,7 +81,8 @@ const createPlayer = definePlayer({ machine, catalog });
 const actor = createPlayer();
 
 // 2. Create router from machine
-const routeTree = createPlayRouter({ machine });
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
 const router = createRouter({
   routeTree,
   history: createMemoryHistory()
@@ -132,7 +135,13 @@ root.render(<StrictMode><App /></StrictMode>);
 Framework-agnostic router for JSX-based frameworks.
 
 ```typescript
-import { createPlayRouter, connectRouter } from '@xmachines/play-router';
+import {
+  connectRouter,
+  createBrowserHistory,
+  createRouteMap,
+  createRouter,
+  extractMachineRoutes,
+} from '@xmachines/play-router';
 import { definePlayer } from '@xmachines/play-xstate';
 
 // 1. Create actor
@@ -140,14 +149,17 @@ const createPlayer = definePlayer({ machine, catalog });
 const actor = createPlayer();
 
 // 2. Create framework-agnostic router
-const router = createPlayRouter({ machine });
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMap(routeTree);
+const history = createBrowserHistory();
+const router = createRouter({ routeTree, history });
 
 // 3. Connect router with manual integration
-const disconnect = connectRouter(actor, {
-  onNavigate: (path) => {
-    // Update your framework's router
-    myFrameworkRouter.push(path);
-  }
+const disconnect = connectRouter(actor, router, routeMap);
+
+history.subscribe(() => {
+  // Update your framework's router from the shared history state
+  myFrameworkRouter.push(history.location.pathname);
 });
 
 // 4. Framework-specific rendering
@@ -177,7 +189,7 @@ h(resolveComponent(view.component), viewProps)
 Manual browser integration with no framework.
 
 ```typescript
-import { createPlayRouter, connectRouter } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-router";
 
 // 1. Create actor
 const actor = createPlayer();
@@ -240,14 +252,14 @@ renderView();
 
 All three modes follow the same pattern:
 
-| Concept     | TanStack Mode                      | Vanilla Mode                         | Pure Browser Mode          |
-| ----------- | ---------------------------------- | ------------------------------------ | -------------------------- |
-| Actor       | `createPlayer()`                   | `createPlayer()`                     | `createPlayer()`           |
-| Router      | `createRouter()` (TanStack)        | `createPlayRouter()`                 | `connectRouter()`          |
-| Integration | `<PlayTanStackRouterProvider>`     | Manual via `onNavigate` callback     | Manual + `window.popstate` |
-| Rendering   | `<PlayRenderer>` via renderer prop | Framework-specific (h, Dynamic, etc) | `innerHTML` or DOM API     |
-| Events      | Component `onClick` → `send()`     | Same                                 | Same                       |
-| Signals     | Observed by `useSignalEffect`      | Manual `actor.currentView.get()`     | Same                       |
+| Concept     | TanStack Mode                      | Vanilla Mode                          | Pure Browser Mode          |
+| ----------- | ---------------------------------- | ------------------------------------- | -------------------------- |
+| Actor       | `createPlayer()`                   | `createPlayer()`                      | `createPlayer()`           |
+| Router      | `createRouter()` (TanStack)        | `createRouter()` + `createRouteMap()` | `connectRouter()`          |
+| Integration | `<PlayTanStackRouterProvider>`     | Manual via `onNavigate` callback      | Manual + `window.popstate` |
+| Rendering   | `<PlayRenderer>` via renderer prop | Framework-specific (h, Dynamic, etc)  | `innerHTML` or DOM API     |
+| Events      | Component `onClick` → `send()`     | Same                                  | Same                       |
+| Signals     | Observed by `useSignalEffect`      | Manual `actor.currentView.get()`      | Same                       |
 
 The API parallelism ensures consistent patterns regardless of mode.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.17",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -46,7 +46,7 @@
     "typedoc": "typedoc"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.16",
+    "@xmachines/shared": "1.0.0-beta.17",
     "typedoc": "^0.28.18",
     "typedoc-plugin-llms-txt": "^0.1.2",
     "typedoc-plugin-markdown": "^4.11.0"