@xmachines/docs 6.1.0 → 7.1.0

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

@@ -2,16 +2,16 @@
 
 # Interface: PlayErrorBoundaryProps
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L14)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L14)
 
 The props of PlayErrorBoundary
 
 ## Properties
 
-| Property                                               | Type                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                                     |
-| ------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children`              | `ReactNode`                       | The child components to render                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
-| <a id="property-fallback"></a> `fallback?`             | `ReactNode`                       | The fallback UI to render when a child component throws. The default is null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
-| <a id="property-onerror"></a> `onError?`               | (`error`, `info`) => `void`       | The optional error handler. It sends each error to an observability tool, such as Sentry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
-| <a id="property-resetkey"></a> `resetKey?`             | `unknown`                         | The reset key. The boundary clears its error state when this value changes, and it renders the children again. ActorProvider gives it the current view. A view transition therefore retries the render. Without the key the boundary holds the fallback for the complete life of the provider: the user sends a recovery event, the actor moves to a healthy view, and the screen keeps the fallback. **The boundary compares the value by IDENTITY (`Object.is`) by default.** Give a stable reference. An inline object literal — `resetKey={{ view }}` — is a new value on every render, so the boundary clears its caught error before each one, renders the children that threw, catches again, and calls `onError` again. Hold the value where it survives a render, and build a new one only when an input moves. [PlayErrorBoundaryProps.resetKeyEquals](#property-resetkeyequals) takes the identity rule away, and a caller that gives one needs no stable reference at all. | [packages/play-react/src/PlayErrorBoundary.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L39) |
-| <a id="property-resetkeyequals"></a> `resetKeyEquals?` | (`previous`, `next`) => `boolean` | The comparison of two reset keys. The default is `Object.is`. The boundary clears its error where this function answers `false`. A caller that builds a key of several inputs therefore compares those INPUTS, and it owes the boundary no stable reference for the key that carries them. That is what `ActorProvider` gives. A key of the three view inputs and the retry nonce holds no identity of its own across renders — React makes no promise to keep a `useMemo`, and a ref that the render writes survives a render that React throws away, which the documentation of React forbids for that reason. With a comparison of the fields, a key that carries the same inputs is the same key, whichever render built it. The state of this class is the key of the last COMMIT: React commits the state of a class with the commit, so a render that React discards writes none. The comparison therefore reads the committed key on one side every time.                      | [packages/play-react/src/PlayErrorBoundary.tsx:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L63) |
+| Property                                               | Type                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                                          |
+| ------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-children"></a> `children`              | `ReactNode`                       | The child components to render                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
+| <a id="property-fallback"></a> `fallback?`             | `ReactNode`                       | The fallback UI to render when a child component throws. The default is null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
+| <a id="property-onerror"></a> `onError?`               | (`error`, `info`) => `void`       | The optional error handler. It sends each error to an observability tool, such as Sentry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
+| <a id="property-resetkey"></a> `resetKey?`             | `unknown`                         | The reset key. The boundary clears its error state when this value changes, and it renders the children again. ActorProvider gives it the current view. A view transition therefore retries the render. Without the key the boundary holds the fallback for the complete life of the provider: the user sends a recovery event, the actor moves to a healthy view, and the screen keeps the fallback. **The boundary compares the value by IDENTITY (`Object.is`) by default.** Give a stable reference. An inline object literal — `resetKey={{ view }}` — is a new value on every render, so the boundary clears its caught error before each one, renders the children that threw, catches again, and calls `onError` again. Hold the value where it survives a render, and build a new one only when an input moves. [PlayErrorBoundaryProps.resetKeyEquals](#property-resetkeyequals) takes the identity rule away, and a caller that gives one needs no stable reference at all. | [packages/play-react/src/PlayErrorBoundary.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L39) |
+| <a id="property-resetkeyequals"></a> `resetKeyEquals?` | (`previous`, `next`) => `boolean` | The comparison of two reset keys. The default is `Object.is`. The boundary clears its error where this function answers `false`. A caller that builds a key of several inputs therefore compares those INPUTS, and it owes the boundary no stable reference for the key that carries them. That is what `ActorProvider` gives. A key of the three view inputs and the retry nonce holds no identity of its own across renders — React makes no promise to keep a `useMemo`, and a ref that the render writes survives a render that React throws away, which the documentation of React forbids for that reason. With a comparison of the fields, a key that carries the same inputs is the same key, whichever render built it. The state of this class is the key of the last COMMIT: React commits the state of a class with the commit, so a render that React discards writes none. The comparison therefore reads the committed key on one side every time.                      | [packages/play-react/src/PlayErrorBoundary.tsx:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L63) |

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

@@ -2,14 +2,14 @@
 
 # Interface: PlayErrorBoundaryState
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L71)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L71)
 
 The internal state shape of PlayErrorBoundary
 
 ## Properties
 
-| Property                                  | Type              | Description                                                               | Defined in                                                                                                                                                     |
-| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-error"></a> `error`       | `Error` \| `null` | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L73) |
-| <a id="property-haserror"></a> `hasError` | `boolean`         | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L72) |
-| <a id="property-resetkey"></a> `resetKey` | `unknown`         | The resetKey of the last render. A different prop clears the error state. | [packages/play-react/src/PlayErrorBoundary.tsx:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L75) |
+| Property                                  | Type              | Description                                                               | Defined in                                                                                                                                                          |
+| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-error"></a> `error`       | `Error` \| `null` | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L73) |
+| <a id="property-haserror"></a> `hasError` | `boolean`         | -                                                                         | [packages/play-react/src/PlayErrorBoundary.tsx:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L72) |
+| <a id="property-resetkey"></a> `resetKey` | `unknown`         | The resetKey of the last render. A different prop clears the error state. | [packages/play-react/src/PlayErrorBoundary.tsx:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayErrorBoundary.tsx#L75) |

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

@@ -2,25 +2,26 @@
 
 # Interface: PlayUIProviderProps
 
-Defined in: [packages/play-react/src/PlayUIProvider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayUIProvider.tsx#L35)
+Defined in: [packages/play-react/src/PlayUIProvider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayUIProvider.tsx#L35)
 
 The props of PlayUIProvider — every ActorProvider prop, and also the props of JSONUIProvider.
 
 ## Extends
 
-- [`ActorProviderProps`](ActorProviderProps.md).`Partial`\<`JSONUIForwardedProps`\>
+- [`ActorProviderProps`](ActorProviderProps.md)
+- `Partial`\<`JSONUIForwardedProps`\>
 
 ## Properties
 
-| Property                                                         | Type                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                               | Defined in                                                                                                                                             |
-| ---------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `actor`                              | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) | The actor instance with the currentView atom. It requires the Viewable capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                                | [packages/play-view/src/view-types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L224)         |
-| <a id="property-children"></a> `children`                        | `ReactNode`                                                    | The child components to render inside the provider tree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-react/src/ActorProvider.tsx:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/ActorProvider.tsx#L99) |
-| <a id="property-fallback"></a> `fallback?`                       | `ReactNode`                                                    | The component to show when currentView is null, or when a catalog component throws. This prop is optional                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-react/src/ActorProvider.tsx:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/ActorProvider.tsx#L61) |
-| <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`, `reset`) => `void`                           | The optional error handler. The provider calls it when a descendant throws during a render. While the error is active, the provider renders the `fallback` instead of its children. The provider clears the error on the next view emission (when `currentView` changes), so a view transition retries the render. Element-level catalog component throws are caught upstream by the per-element boundary of @json-render, and reported through `onRenderError`. This boundary is the outer net for everything else. The THIRD parameter is the reset, for a retry that the host starts — a "Retry" button of its own. It sits after `info`, and not in the second place that the four other renderers use, because `React.ErrorInfo` holds that place already and a move would break every handler that reads `info.componentStack`. The reset clears the contained error and renders again. It renders the view that the actor holds at the MOMENT OF THE CALL, so a host that keeps the callback cannot rewind the screen to the view that failed. A reset that the host calls from inside this handler does nothing, because no input changed between the two attempts, and a reset after the provider is unmounted does nothing. The five renderers hold the same three rules. **A handler that THROWS reaches no caller.** The provider contains that throw, and it writes the throw to `console.error`. This handler runs inside `componentDidCatch`, so a throw that left it would reach the boundary ABOVE this provider, and React can then unmount the complete root — which is the failure that this boundary contained. Report a failure from this handler. To ESCALATE one, raise it from a task of your own — `rethrowLater(error)` of `@xmachines/core/utils` — which reaches the global handler of the page and leaves the containment whole. The host installs `@xmachines/core` itself. The five renderers hold this one rule. | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-react/src/ActorProvider.tsx:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/ActorProvider.tsx#L97) |
-| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)  | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)                | [packages/play-view/src/view-types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L238)         |
-| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                         | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult)              | [packages/play-view/src/view-types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L226)         |
-| <a id="property-store"></a> `store?`                             | `StateStore`                                                   | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                                | [packages/play-view/src/view-types.ts:233](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L233)         |
-| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>          | Custom validation functions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`validationFunctions`](JSONUIProviderProps.md#property-validationfunctions) | -                                                                                                                                                      |
+| Property                                                         | Type                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                               | Defined in                                                                                                                                                  |
+| ---------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                              | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) | The actor instance with the currentView atom. It requires the Viewable capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                                | [packages/play-view/src/view-types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L219)         |
+| <a id="property-children"></a> `children`                        | `ReactNode`                                                    | The child components to render inside the provider tree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-react/src/ActorProvider.tsx:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/ActorProvider.tsx#L95) |
+| <a id="property-fallback"></a> `fallback?`                       | `ReactNode`                                                    | The component to show when currentView is null, or after a failure of the view. This prop is optional                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-react/src/ActorProvider.tsx:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/ActorProvider.tsx#L54) |
+| <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`, `reset`, `info`) => `void`                           | The optional error handler. The provider calls it when a descendant throws during a render. While the error is active, the provider renders the `fallback` instead of its children. The provider clears the error on the next view emission (when `currentView` changes), so a view transition retries the render. The per-element boundary of `json-render` catches a throw of a catalog component below the root, and it reports it through `onRenderError` alone. A failure of the ROOT — its component, a prop, or its `visible` condition — leaves no view, and json-render gives it to no boundary of the host. The provider contains it as a failure of the view all the same: it shows the fallback, and it calls this handler one time. `onRenderError` also receives it, with `info.kind` `"root"`. This boundary is the outer net for everything else. The SECOND parameter is the reset, for a retry that the host starts — a "Retry" button of its own. It sits in the same place as in the four other renderers, and the `React.ErrorInfo` of the boundary comes third. The reset clears the contained error and renders again. It renders the view that the actor holds at the MOMENT OF THE CALL, so a host that keeps the callback cannot rewind the screen to the view that failed. A reset that the host calls from inside this handler does nothing, because no input changed between the two attempts, and a reset after the provider is unmounted does nothing. The five renderers hold the same three rules. **A handler that THROWS reaches no caller.** The provider contains that throw, and it writes the throw to `console.error`. This handler runs inside `componentDidCatch`, so a throw that left it would reach the boundary ABOVE this provider, and React can then unmount the complete root — which is the failure that this boundary contained. Report a failure from this handler. To ESCALATE one, raise it from a task of your own — `rethrowLater(error)` of `@xmachines/core/utils` — which reaches the global handler of the page and leaves the containment whole. The host installs `@xmachines/core` itself. The five renderers hold this one rule. | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-react/src/ActorProvider.tsx:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/ActorProvider.tsx#L93) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`OnRenderError`](../type-aliases/OnRenderError.md)            | The renderer calls it with `(error, name, info)` for each failure that it reports: a catalog component that throws, a prop or a `visible` condition that fails, an action chain or a watch chain that fails, and a failure of the root. `info.kind` names the kind of the failure. A handler with the two parameters `(error, name)` stays valid. This handler replaces every onRenderError of defineRegistry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)                | [packages/play-view/src/view-types.ts:236](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L236)         |
+| <a id="property-registryresult"></a> `registryResult`            | [`DefineRegistryResult`](DefineRegistryResult.md)              | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult)              | [packages/play-view/src/view-types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L221)         |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                   | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                                | [packages/play-view/src/view-types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L228)         |
+| <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/RenderErrorInfo.md

@@ -0,0 +1,16 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / RenderErrorInfo
+
+# Interface: RenderErrorInfo
+
+Defined in: `@xmachines/json-render-core`
+
+What a renderer tells the handler about a failure.
+
+## Properties
+
+| Property                               | Type                                                    | Description                                                                                       | Defined in |
+| -------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-action"></a> `action?` | `string`                                                | The action name, for `action` and `watch`.                                                        | -          |
+| <a id="property-key"></a> `key?`       | `string`                                                | The key of the element whose code failed. For `props` and `visible`, the child, not the boundary. | -          |
+| <a id="property-kind"></a> `kind`      | [`RenderErrorKind`](../type-aliases/RenderErrorKind.md) | The place where the failure occurred.                                                             | -          |
+| <a id="property-type"></a> `type?`     | `string`                                                | The component type of that element.                                                               | -          |

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

@@ -8,10 +8,10 @@ Props for the Renderer component
 
 ## Properties
 
-| Property                                             | Type                                                          | Description                                                     | Defined in |
-| ---------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- | ---------- |
-| <a id="property-fallback"></a> `fallback?`           | `ComponentRenderer`\<`Record`\<`string`, `unknown`\>\>        | Fallback component for unknown types                            | -          |
-| <a id="property-loading"></a> `loading?`             | `boolean`                                                     | Whether the spec is currently loading/streaming                 | -          |
-| <a id="property-onrendererror"></a> `onRenderError?` | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | Callback for element render errors caught by the inner boundary | -          |
-| <a id="property-registry"></a> `registry`            | `ComponentRegistry`                                           | Component registry                                              | -          |
-| <a id="property-spec"></a> `spec`                    | `Spec` \| `null`                                              | The UI spec to render                                           | -          |
+| Property                                             | Type                                                   | Description                                                          | Defined in |
+| ---------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------- | ---------- |
+| <a id="property-fallback"></a> `fallback?`           | `ComponentRenderer`\<`Record`\<`string`, `unknown`\>\> | Fallback component for unknown types                                 | -          |
+| <a id="property-loading"></a> `loading?`             | `boolean`                                              | Whether the spec is currently loading/streaming                      | -          |
+| <a id="property-onrendererror"></a> `onRenderError?` | [`OnRenderError`](../type-aliases/OnRenderError.md)    | Callback for each failure that the renderer reports (see the README) | -          |
+| <a id="property-registry"></a> `registry`            | `ComponentRegistry`                                    | Component registry                                                   | -          |
+| <a id="property-spec"></a> `spec`                    | `Spec` \| `null`                                       | The UI spec to render                                                | -          |

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

@@ -2,7 +2,7 @@
 
 # Interface: ViewContextValue
 
-Defined in: [packages/play-react/src/ActorProvider.tsx:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/ActorProvider.tsx#L107)
+Defined in: [packages/play-react/src/ActorProvider.tsx:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/ActorProvider.tsx#L103)
 
 The value that ViewContext provides. usePlayView() reads it.
 
@@ -12,9 +12,9 @@ The value that ViewContext provides. usePlayView() reads it.
 
 ## Properties
 
-| Property                                  | Type                                                       | Description                                                                                                            | Inherited from                                                                                                                                                              | Defined in                                                                                                                                     |
-| ----------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                      | The action handlers, resolved against the live StateStore.                                                             | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`handlers`](../../play-view/index/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-view/src/view-types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L167) |
-| <a id="property-registry"></a> `registry` | `TRegistry`                                                | The component registry, from registryResult.registry.                                                                  | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`registry`](../../play-view/index/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-view/src/view-types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L169) |
-| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-view/index/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                                        | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`spec`](../../play-view/index/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-view/src/view-types.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L165) |
-| <a id="property-store"></a> `store`       | `StateStore`                                               | The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state. | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`store`](../../play-view/index/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-view/src/view-types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/view-types.ts#L173) |
+| Property                                  | Type                                                       | Description                                                                                                            | Inherited from                                                                                                                                                              | Defined in                                                                                                                                          |
+| ----------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                      | The action handlers, resolved against the live StateStore.                                                             | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`handlers`](../../play-view/index/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-view/src/view-types.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L162) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                                                | The component registry, from registryResult.registry.                                                                  | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`registry`](../../play-view/index/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-view/src/view-types.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L164) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-view/index/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                                        | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`spec`](../../play-view/index/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-view/src/view-types.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L160) |
+| <a id="property-store"></a> `store`       | `StateStore`                                               | The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state. | [`BaseViewContextValue`](../../play-view/index/interfaces/BaseViewContextValue.md).[`store`](../../play-view/index/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-view/src/view-types.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-view/src/view-types.ts#L168) |

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

@@ -6,7 +6,7 @@
 type AnyPlayActor = PlayActor;
 ```
 
-Defined in: [packages/play-react/src/useActor.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/useActor.ts#L37)
+Defined in: [packages/play-react/src/useActor.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/useActor.ts#L37)
 
 The actor type of the context of this renderer.
 

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

@@ -12,10 +12,10 @@ Component render function type for React
 
 ## Type Parameters
 
-| Type Parameter                                      |
-| --------------------------------------------------- |
-| `C` _extends_ `Catalog`                             |
-| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+| Type Parameter                                                                    |
+| --------------------------------------------------------------------------------- |
+| <a id="type-parameter-c"></a> `C` _extends_ `Catalog`                             |
+| <a id="type-parameter-k"></a> `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
 
 ## Parameters
 

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

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / OnRenderError
+
+# Type Alias: OnRenderError
+
+```ts
+type OnRenderError = (error, name, info) => void;
+```
+
+Defined in: `@xmachines/json-render-core`
+
+The `onRenderError` handler of a renderer.
+
+The second argument stays as it was: the element type for a failure of an
+element, or the action name for a failed chain. `info` tells them apart. A
+handler with two parameters is still a valid handler.
+
+## Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `error`   | `unknown`                                             |
+| `name`    | `string`                                              |
+| `info`    | [`RenderErrorInfo`](../interfaces/RenderErrorInfo.md) |
+
+## Returns
+
+`void`

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

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / RenderErrorKind
+
+# Type Alias: RenderErrorKind
+
+```ts
+type RenderErrorKind = "element" | "props" | "visible" | "action" | "watch" | "root";
+```
+
+Defined in: `@xmachines/json-render-core`
+
+The place where a failure occurred.
+
+- `element`: the component threw while it rendered, in an effect or a
+  lifecycle hook, or in a callback that it calls in those phases.
+- `props`: a prop expression of an element threw (`$computed`, a directive).
+- `visible`: the `visible` condition of an element threw.
+- `action`: an `on` chain failed: a handler that throws or rejects, a
+  built-in action, a store that refuses a write, or `validateForm`.
+- `watch`: a `watch` chain failed.
+- `root`: the root (its component, props or `visible`) failed, so the
+  renderer shows nothing.

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:364](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/ActorProvider.tsx#L364)
+Defined in: [packages/play-react/src/ActorProvider.tsx:288](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/ActorProvider.tsx#L288)
 
 ActorProvider — the low-level provider that composes the actor lifecycle with your own providers.
 
@@ -20,11 +20,21 @@ compose the providers yourself.
 ## Example
 
 ```tsx
-// A custom composition:
+// A custom composition. Hand JSONUIProvider the store of the view context: without
+// it, JSONUIProvider makes an empty store of its own, which holds no /context.
+function MyProviders({ children }: { children: React.ReactNode }) {
+  const view = usePlayView();
+  return (
+    <JSONUIProvider registry={view.registry} handlers={view.handlers} store={view.store}>
+      {children}
+    </JSONUIProvider>
+  );
+}
+
 <ActorProvider actor={actor} registryResult={registryResult}>
-  <JSONUIProvider registry={registryResult.registry}>
+  <MyProviders>
     <PlayRenderer />
-  </JSONUIProvider>
+  </MyProviders>
 </ActorProvider>
 
 // Standard use: prefer PlayUIProvider

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:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayRenderer.tsx#L40)
+Defined in: [packages/play-react/src/PlayRenderer.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayRenderer.tsx#L40)
 
 The leaf component without props 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:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/src/PlayUIProvider.tsx#L106)
+Defined in: [packages/play-react/src/PlayUIProvider.tsx:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/src/PlayUIProvider.tsx#L106)
 
 PlayUIProvider — the standard entry point for an actor-driven UI.
 

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

@@ -4,7 +4,7 @@
 
 > React Router 7 and 8 adapter for the XMachines Play Universal Player Architecture. It keeps the actor state and the browser URL in step, in both directions, through the `createBrowserRouter` data API.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-6.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-react-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-7.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-react-router)
 
 ---
 
@@ -39,13 +39,16 @@ import { PlayRouterProvider } from "@xmachines/play-react-router";
 import { createRouteMap } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
-import { myMachine } from "./machine.js";
+import type { AnyStateMachine } from "xstate";
+
+// Your machine: its routable states carry `meta.route`
+declare const myMachine: AnyStateMachine;
 
 const createPlayer = definePlayer({ machine: myMachine, actor: compose(PlayerActor, withRouting) });
 const routeMap = createRouteMap(myMachine);
 
 // Minimal app shell stub — a real app renders PlayUIProvider + PlayRenderer from
-// @xmachines/play-react here (see the workspace-only @xmachines/play-react-demo Shell)
+// @xmachines/play-react here (see the workspace-only @xmachines/play-react-gallery-demo Shell)
 function App({ actor }: { actor: ReturnType<typeof createPlayer> }) {
 	return <main />; // render your UI from the actor here
 }
@@ -60,7 +63,12 @@ function createAppRuntime() {
 export default function Root() {
 	const { actor, router } = useMemo(createAppRuntime, []);
 
-	useEffect(() => () => actor.stop(), [actor]);
+	useEffect(
+		() => () => {
+			actor.stop();
+		},
+		[actor],
+	);
 
 	return (
 		<PlayRouterProvider
@@ -85,7 +93,10 @@ import { ReactRouterBridge } from "@xmachines/play-react-router";
 import { createRouteMap } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
-import { myMachine } from "./machine.js";
+import type { AnyStateMachine } from "xstate";
+
+// Your machine: its routable states carry `meta.route`
+declare const myMachine: AnyStateMachine;
 
 // The bridge needs the routing capability
 const actor = definePlayer({ machine: myMachine, actor: compose(PlayerActor, withRouting) })();
@@ -109,7 +120,13 @@ bridge.disconnect(); // stops sync and cleans up subscriptions
 A React component that manages a `ReactRouterBridge` lifecycle via `useEffect`.
 
 ```ts
-interface PlayRouterProviderProps<TActor> {
+import type { ReactNode } from "react";
+import type { createBrowserRouter } from "react-router";
+import type { RoutableActor, RouteMap } from "@xmachines/play-react-router";
+
+type BrowserRouterInstance = ReturnType<typeof createBrowserRouter>;
+
+interface PlayRouterProviderProps<TActor extends RoutableActor> {
 	/** The actor to sync with React Router. Must be a stable reference. */
 	actor: TActor;
 	/** The React Router instance returned by `createBrowserRouter`. */
@@ -119,6 +136,10 @@ interface PlayRouterProviderProps<TActor> {
 	 * Must be a stable reference — memoize with useMemo if constructed inline.
 	 */
 	routeMap: RouteMap;
+	/** Optional URL prefix that the host owns. The routes of the machine mount under it. */
+	basePath?: string;
+	/** The values of the `:param` segments of `basePath`. */
+	basePathParams?: Record<string, string | number>;
 	/** Render callback — receives the actor and router. */
 	renderer: (actor: TActor, router: BrowserRouterInstance) => ReactNode;
 }