@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

package/api/@xmachines/play-react/interfaces/PlayErrorBoundaryProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayErrorBoundaryProps
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L14)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L14)
 
 Props for PlayErrorBoundary
 
@@ -10,6 +10,6 @@ Props for PlayErrorBoundary
 
 | Property                                   | Type                        | Description                                                                             | Defined in                                                                                                                                                             |
 | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children`  | `ReactNode`                 | Child components to render                                                              | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
-| <a id="property-fallback"></a> `fallback?` | `ReactNode`                 | Fallback UI to render when a child component throws. Defaults to null.                  | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
-| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void` | Optional error handler callback — forwards errors to observability tools (Sentry, etc.) | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
+| <a id="property-children"></a> `children`  | `ReactNode`                 | Child components to render                                                              | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
+| <a id="property-fallback"></a> `fallback?` | `ReactNode`                 | Fallback UI to render when a child component throws. Defaults to null.                  | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
+| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void` | Optional error handler callback — forwards errors to observability tools (Sentry, etc.) | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L20) |

package/api/@xmachines/play-react/interfaces/PlayErrorBoundaryState.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayErrorBoundaryState
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L28)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L28)
 
 Internal state shape for PlayErrorBoundary
 
@@ -10,5 +10,5 @@ Internal state shape for PlayErrorBoundary
 
 | Property                                  | Type              | Defined in                                                                                                                                                             |
 | ----------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-error"></a> `error`       | `Error` \| `null` | [packages/play-react/src/PlayErrorBoundary.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L30) |
-| <a id="property-haserror"></a> `hasError` | `boolean`         | [packages/play-react/src/PlayErrorBoundary.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayErrorBoundary.tsx#L29) |
+| <a id="property-error"></a> `error`       | `Error` \| `null` | [packages/play-react/src/PlayErrorBoundary.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L30) |
+| <a id="property-haserror"></a> `hasError` | `boolean`         | [packages/play-react/src/PlayErrorBoundary.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayErrorBoundary.tsx#L29) |

package/api/@xmachines/play-react/interfaces/PlayUIProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayUIProviderProps
 
-Defined in: [packages/play-react/src/PlayUIProvider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayUIProvider.tsx#L34)
+Defined in: [packages/play-react/src/PlayUIProvider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayUIProvider.tsx#L34)
 
 Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's own props.
 
@@ -14,13 +14,13 @@ Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's own p
 
 | Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                               | Defined in                                                                                                                                                       |
 | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                                | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L154) |
-| <a id="property-children"></a> `children`                        | `ReactNode`                                                                                                                                                                                                                                                      | Child components to render inside the provider tree                                                                                                                                                                         | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-react/src/ActorProvider.tsx:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/ActorProvider.tsx#L37)   |
-| <a id="property-fallback"></a> `fallback?`                       | `ReactNode`                                                                                                                                                                                                                                                      | Optional component shown when currentView is null or a catalog component throws                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-react/src/ActorProvider.tsx:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/ActorProvider.tsx#L33)   |
+| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                                | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L154) |
+| <a id="property-children"></a> `children`                        | `ReactNode`                                                                                                                                                                                                                                                      | Child components to render inside the provider tree                                                                                                                                                                         | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-react/src/ActorProvider.tsx:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/ActorProvider.tsx#L37)   |
+| <a id="property-fallback"></a> `fallback?`                       | `ReactNode`                                                                                                                                                                                                                                                      | Optional component shown when currentView is null or a catalog component throws                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-react/src/ActorProvider.tsx:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/ActorProvider.tsx#L33)   |
 | <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                                                                                                                                                                         | Named functions for `$computed` expressions in props                                                                                                                                                                        | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`functions`](JSONUIProviderProps.md#property-functions)                     | -                                                                                                                                                                |
 | <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | Navigation function                                                                                                                                                                                                         | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`navigate`](JSONUIProviderProps.md#property-navigate)                       | -                                                                                                                                                                |
-| <a id="property-onerror"></a> `onError?`                         | (`error`, `info`) => `void`                                                                                                                                                                                                                                      | Optional error handler callback invoked when a catalog component throws during render                                                                                                                                       | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-react/src/ActorProvider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/ActorProvider.tsx#L35)   |
-| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)                | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L167) |
-| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult)              | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L156) |
-| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                                | [packages/play-actor/src/abstract-actor.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L162) |
+| <a id="property-onerror"></a> `onError?`                         | (`error`, `info`) => `void`                                                                                                                                                                                                                                      | Optional error handler callback invoked when a catalog component throws during render                                                                                                                                       | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-react/src/ActorProvider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/ActorProvider.tsx#L35)   |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)                | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L167) |
+| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult)              | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L156) |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                                | [packages/play-actor/src/abstract-actor.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L162) |
 | <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | Custom validation functions                                                                                                                                                                                                 | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`validationFunctions`](JSONUIProviderProps.md#property-validationfunctions) | -                                                                                                                                                                |

package/api/@xmachines/play-react/interfaces/ViewContextValue.md

@@ -2,7 +2,7 @@
 
 # Interface: ViewContextValue
 
-Defined in: [packages/play-react/src/ActorProvider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/ActorProvider.tsx#L45)
+Defined in: [packages/play-react/src/ActorProvider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/ActorProvider.tsx#L45)
 
 Value provided by ViewContext (accessible via usePlayView()).
 
@@ -14,7 +14,7 @@ Value provided by ViewContext (accessible via usePlayView()).
 
 | Property                                  | Type                                                  | Description                                                                                               | Inherited from                                                                                                                                                    | Defined in                                                                                                                                                       |
 | ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L122) |
-| <a id="property-registry"></a> `registry` | `ComponentRegistry`                                   | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L124) |
-| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L120) |
-| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L126) |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L122) |
+| <a id="property-registry"></a> `registry` | `ComponentRegistry`                                   | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L124) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L120) |
+| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-actor/src/abstract-actor.ts#L126) |

package/api/@xmachines/play-react/type-aliases/PlayActor.md

@@ -6,4 +6,4 @@
 type PlayActor = AbstractActor<AnyActorLogic>;
 ```
 
-Defined in: [packages/play-react/src/useActor.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/useActor.ts#L27)
+Defined in: [packages/play-react/src/useActor.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/useActor.ts#L27)

package/api/@xmachines/play-react/variables/ActorProvider.md

@@ -6,7 +6,7 @@
 const ActorProvider: React.FC<ActorProviderProps>;
 ```
 
-Defined in: [packages/play-react/src/ActorProvider.tsx:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/ActorProvider.tsx#L168)
+Defined in: [packages/play-react/src/ActorProvider.tsx:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/ActorProvider.tsx#L168)
 
 ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
 

package/api/@xmachines/play-react/variables/PlayRenderer.md

@@ -6,7 +6,7 @@
 const PlayRenderer: React.FC<Record<string, never>>;
 ```
 
-Defined in: [packages/play-react/src/PlayRenderer.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayRenderer.tsx#L39)
+Defined in: [packages/play-react/src/PlayRenderer.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayRenderer.tsx#L39)
 
 Zero-prop leaf component that renders the current actor view.
 

package/api/@xmachines/play-react/variables/PlayUIProvider.md

@@ -6,7 +6,7 @@
 const PlayUIProvider: React.FC<PlayUIProviderProps>;
 ```
 
-Defined in: [packages/play-react/src/PlayUIProvider.tsx:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-react/src/PlayUIProvider.tsx#L102)
+Defined in: [packages/play-react/src/PlayUIProvider.tsx:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-react/src/PlayUIProvider.tsx#L102)
 
 PlayUIProvider — batteries-included entry point for actor-driven UI rendering.
 

package/api/@xmachines/play-react-router/README.md

@@ -1,188 +1,171 @@
 [API](../../README.md) / @xmachines/play-react-router
 
-# @xmachines/play-react-router
+<!-- generated-by: gsd-doc-writer -->
 
-**React Router v7 adapter for XMachines Play using RouterBridgeBase.**
+# `@xmachines/play-react-router`
 
-## Overview
+> React Router v7 adapter for the XMachines Play Universal Player Architecture — synchronizes actor state with the browser URL bidirectionally using the `createBrowserRouter` data API.
 
-`@xmachines/play-react-router` connects `react-router` v7 data routers to Play actors.
+Part of the [XMachines Play monorepo](../../README.md).
 
-The package provides:
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-- `ReactRouterBridge` for direct adapter control
-- `PlayRouterProvider` for React lifecycle wiring
-- `RouteMap` utilities for state ID <-> URL path resolution
-
-Internally, `ReactRouterBridge` extends `RouterBridgeBase` from, so behavior matches other bridge adapters in the monorepo.
+---
 
 ## Installation
 
 ```bash
-npm install react react-router
-npm install @xmachines/play-react-router @xmachines/play-router @xmachines/play-react
+npm install @xmachines/play-react-router
 ```
 
-## Current Exports
+**Peer dependencies** — install if not already present:
 
-- `ReactRouterBridge`
-- `PlayRouterProvider` + `PlayRouterProviderProps`
-- `RouteMap`
-- `createRouteMapFromTree`
-- type re-exports: `RouterBridge`, `PlayRouteEvent`
+```bash
+npm install react@"^18 || ^19" react-router@"^7.0.0" xstate@"^5.30.0"
+```
 
-Peer dependencies:
+---
 
-- `react` `^18 || ^19`
-- `react-router` `^7.0.0`
+## Usage
 
-Use).
+### `PlayRouterProvider` — Recommended (React component)
 
-## Quick Start
+`PlayRouterProvider` connects a `PlayerActor` to React Router inside a React component tree. It creates a `ReactRouterBridge` on mount, keeps actor state and the browser URL in sync bidirectionally, and tears the bridge down cleanly on unmount.
+
+> **All three props (`actor`, `router`, `routeMap`) must be stable references.** Create them outside of JSX or memoize with `useMemo`. Recreating them inline triggers a bridge disconnect/reconnect on every render.
 
 ```tsx
-import { createBrowserRouter } from "react-router";
+import { useMemo, useEffect } from "react";
+import { createBrowserRouter, RouterProvider } from "react-router";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { ReactRouterBridge, createRouteMapFromTree } from "@xmachines/play-react-router";
+import { myMachine } from "./machine.js";
 
-const router = createBrowserRouter(routes);
-const actor = definePlayer({ machine, catalog })();
-actor.start();
+const createPlayer = definePlayer({ machine: myMachine });
+const routeMap = createRouteMap(myMachine);
 
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+function createAppRuntime() {
+	const actor = createPlayer();
+	actor.start();
+	const router = createBrowserRouter([{ path: "*", element: <App actor={actor} /> }]);
+	return { actor, router };
+}
 
-const bridge = new ReactRouterBridge(router, actor, routeMap);
-bridge.connect();
+export default function Root() {
+	const { actor, router } = useMemo(createAppRuntime, []);
+
+	useEffect(() => () => actor.stop(), [actor]);
 
-// later
-bridge.disconnect();
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(_, currentRouter) => <RouterProvider router={currentRouter} />}
+		/>
+	);
+}
 ```
 
-`ReactRouterBridge` requires the data-router API (`createBrowserRouter`).
-`BrowserRouter` is not supported because it does not expose subscribe/navigate APIs needed by the bridge.
+### `ReactRouterBridge` — Manual (imperative API)
 
-## API
+Use `ReactRouterBridge` directly when you need imperative lifecycle control outside React.
 
-### `ReactRouterBridge`
+> **Requires `createBrowserRouter`** (data router API). The legacy `<BrowserRouter>` component is not supported — it does not expose the `subscribe`/`navigate` API.
 
-```ts
-class ReactRouterBridge extends RouterBridgeBase {
-	constructor(
-		router: ReturnType<typeof createBrowserRouter>,
-		actor: AbstractActor<AnyActorLogic> & Routable,
-		routeMap: RouteMap,
-	);
-	connect(): void;
-	disconnect(): void;
-}
+```typescript
+import { createBrowserRouter } from "react-router";
+import { ReactRouterBridge, createRouteMap } from "@xmachines/play-react-router";
+import { myMachine } from "./machine.js";
+
+const router = createBrowserRouter([
+	/* routes */
+]);
+const routeMap = createRouteMap(myMachine);
+
+const bridge = new ReactRouterBridge(router, actor, routeMap);
+bridge.connect(); // starts bidirectional sync
+// ... later:
+bridge.disconnect(); // stops sync and cleans up subscriptions
 ```
 
-Responsibilities:
+---
 
-- Watch React Router location updates and sync actor via `play.route`
-- Observe actor route changes and navigate router when state changes
-- Handle initial URL sync on cold load/deep links (pathname **and** query string are forwarded)
+## API
 
 ### `PlayRouterProvider`
 
-React wrapper that creates/connects/disconnects `ReactRouterBridge` in `useEffect`:
+A React component that manages a `ReactRouterBridge` lifecycle via `useEffect`.
 
 ```ts
-interface PlayRouterProviderProps {
-	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
-	router: ReturnType<typeof createBrowserRouter>;
+interface PlayRouterProviderProps<TActor> {
+	/** The actor to sync with React Router. Must be a stable reference. */
+	actor: TActor;
+	/** The React Router instance returned by `createBrowserRouter`. */
+	router: BrowserRouterInstance;
+	/**
+	 * Bidirectional route map for state ID ↔ URL path lookups.
+	 * Must be a stable reference — memoize with useMemo if constructed inline.
+	 */
 	routeMap: RouteMap;
-	renderer: (
-		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
-		router: ReturnType<typeof createBrowserRouter>,
-	) => ReactNode;
+	/** Render callback — receives the actor and router. */
+	renderer: (actor: TActor, router: BrowserRouterInstance) => ReactNode;
 }
 ```
 
-### `RouteMap` and `createRouteMapFromTree`
-
-`RouteMap` extends `BaseRouteMap` from, inheriting bucket-indexed
-bidirectional route matching. No routing logic lives in the adapter itself.
-
-```ts
-// RouteMap is a thin subclass of BaseRouteMap — no extra methods
-class RouteMap extends BaseRouteMap {}
+### `ReactRouterBridge`
 
-// Inherited API:
-routeMap.getStateIdByPath(path: string): string | null
-routeMap.getPathByStateId(stateId: string): string | null
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements the `RouterBridge` protocol.
 
-// Factory from a machine route tree:
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap
-```
+| Method         | Description                                                             |
+| -------------- | ----------------------------------------------------------------------- |
+| `connect()`    | Subscribes to router changes and syncs actor state from the current URL |
+| `disconnect()` | Unsubscribes and stops all synchronization                              |
 
-`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+### Route map utilities (re-exported from `@xmachines/play-router`)
 
-`createRouteMapFromTree` uses `node.fullPath` (the fully resolved absolute path) for all
-route entries. This is correct for both flat routes (e.g. `"/login"`) and nested relative
-routes (e.g. `meta.route: "overview"` under `"/dashboard"` resolves to `"/dashboard/overview"`).
+| Export                         | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| `RouteMap`                     | Bidirectional state ID ↔ URL path map                         |
+| `createRouteMap(machine)`      | Build a `RouteMap` directly from an XState machine definition |
+| `createRouteMapFromTree(tree)` | Build a `RouteMap` from a `RouteTree` object                  |
+| `RouteMapOptions`              | Options type for `createRouteMap`                             |
+| `RouteMapping`                 | Type for a single `{ stateId, path }` entry                   |
+| `RouterBridge`                 | Interface that `ReactRouterBridge` satisfies                  |
+| `PlayRouteEvent`               | The `play.route` event type sent to actors on navigation      |
 
-Construct directly when you have static mappings:
+---
 
-```ts
-import { RouteMap } from "@xmachines/play-react-router";
+## Testing
 
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
+Run tests for this package in isolation:
 
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-routeMap.getStateIdByPath("/unknown"); // null
+```bash
+npm test -w packages/play-react-router
 ```
 
-Or build from a machine's route tree:
+Or from inside the package directory:
 
-```ts
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-react-router";
-
-const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
+```bash
+npm test
 ```
 
-## Examples
-
-- Routing patterns guide: `docs/examples/routing-patterns.md`
-- Multi-router integration guide: `docs/examples/multi-router-integration.md`
-
-## Architecture
-
-Bridge-first adapter flow:
+Tests use [Vitest](https://vitest.dev/). Component tests (`*.test.tsx`) run in a `jsdom` environment via `@testing-library/react`. Unit tests (`*.test.ts`) run in Node.
 
-1. Build route map from `extractMachineRoutes(machine)`.
-2. Connect `ReactRouterBridge` (or `PlayRouterProvider`).
-3. Router navigation emits path updates to actor via `play.route` events.
-4. Actor transitions (and guards) determine valid state.
-5. Actor route signal updates router URL when accepted.
+Coverage thresholds (v8 provider):
 
-This keeps infrastructure passive and preserves Actor Authority.
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 80%       |
+| Statements | 80%       |
 
-## Related Packages
-
-- [@xmachines/play-router](../play-router/README.md)
-- [@xmachines/play-xstate](../play-xstate/README.md)
-- [@xmachines/play-react](../play-react/README.md)
-
-## Learn More
-
-- [Demo](../../../examples/@xmachines/play-react-router-demo/README.md)
-- [React renderer](../play-react/README.md)
+---
 
 ## 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>.
+[MIT](./LICENSE)
 
 @xmachines/play-react-router