@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/play-svelte-spa-router/functions/connectRouter.md

@@ -6,7 +6,7 @@
 function connectRouter(options): RouterConnection;
 ```
 
-Defined in: [play-svelte-spa-router/src/connect-router.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L31)
+Defined in: [play-svelte-spa-router/src/connect-router.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L32)
 
 Connects svelte-spa-router to an actor.
 
@@ -25,7 +25,8 @@ It returns a cleanup function. The public API surface stays as it was (D-14).
 ## Example
 
 ```typescript
-import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+import { connectRouter } from "@xmachines/play-svelte-spa-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 const routeMap = createRouteMap(machine);
 const disconnect = connectRouter({ actor, routeMap });
 onDestroy(() => disconnect());

package/api/@xmachines/play-svelte-spa-router/interfaces/BasePathOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: BasePathOptions
 
-Defined in: [play-router/src/base-path.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L44)
+Defined in: [play-url/src/base-path.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L44)
 
 The base-path options that every router bridge, `connectRouter` function, and
 `PlayRouterProvider` component accepts.
@@ -26,7 +26,7 @@ connectRouter({
 
 ## Properties
 
-| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Defined in                                                                                                                            |
-| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](ConnectRouterOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [play-router/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L58) |
-| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](ConnectRouterOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-router/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L72) |
+| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Defined in                                                                                                                      |
+| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](ConnectRouterOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [play-url/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L58) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](ConnectRouterOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-url/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L72) |

package/api/@xmachines/play-svelte-spa-router/interfaces/ConnectRouterOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-svelte-spa-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L6)
+Defined in: [play-svelte-spa-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L6)
 
 @xmachines/play-svelte-spa-router
 
@@ -14,10 +14,10 @@ Svelte SPA router adapter for the XMachines Play architecture.
 
 ## Properties
 
-| Property                                               | Modifier   | Type                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Inherited from                                                                                         | Defined in                                                                                                                                                            |
-| ------------------------------------------------------ | ---------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                    | `readonly` | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                      | [play-svelte-spa-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L7)   |
-| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                                             | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [`BasePathOptions`](BasePathOptions.md).[`basePath`](BasePathOptions.md#property-basepath)             | [play-router/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L58)                                 |
-| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\>                           | The values of the `:param` segments of [BasePathOptions.basePath](#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [`BasePathOptions`](BasePathOptions.md).[`basePathParams`](BasePathOptions.md#property-basepathparams) | [play-router/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L72)                                 |
-| <a id="property-routemap"></a> `routeMap`              | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                 | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                      | [play-svelte-spa-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L8)   |
-| <a id="property-window"></a> `window?`                 | `readonly` | [`WindowLike`](WindowLike.md)                                        | The window-like object for the `hashchange` subscription. The default is the global `window`, when one exists. In an environment without a window, such as SSR or Node, the bridge skips the `hashchange` subscription. Give a mock in a test.                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                      | [play-svelte-spa-router/src/connect-router.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L15) |
+| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Inherited from                                                                                         | Defined in                                                                                                                                                            |
+| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                    | `readonly` | [`RoutableActor`](RoutableActor.md)        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                      | [play-svelte-spa-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L7)   |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [`BasePathOptions`](BasePathOptions.md).[`basePath`](BasePathOptions.md#property-basepath)             | [play-url/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L58)                                       |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [`BasePathOptions`](BasePathOptions.md).[`basePathParams`](BasePathOptions.md#property-basepathparams) | [play-url/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L72)                                       |
+| <a id="property-routemap"></a> `routeMap`              | `readonly` | [`RouteMap`](../classes/RouteMap.md)       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                      | [play-svelte-spa-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L8)   |
+| <a id="property-window"></a> `window?`                 | `readonly` | [`WindowLike`](WindowLike.md)              | The window-like object for the `hashchange` subscription. The default is the global `window`, when one exists. In an environment without a window, such as SSR or Node, the bridge skips the `hashchange` subscription. Give a mock in a test.                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                      | [play-svelte-spa-router/src/connect-router.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-svelte-spa-router/src/connect-router.ts#L15) |

package/api/@xmachines/play-svelte-spa-router/interfaces/PlayRouteEvent.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L238)
+Defined in: [play-router/src/types.ts:336](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L336)
 
 The routing event, with its parameters and its query
 
@@ -118,18 +118,13 @@ Use `play.route` when you need a navigation that knows the parameters, with the
 gives you the complete URLPatternResult, for an advanced use such as a debug or an
 analysis of the pattern.
 
-## Indexable
-
-```ts
-[key: string]: unknown
-```
-
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
-| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:243](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L243) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L241) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L242) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L240) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L239) |
+| Property                               | Modifier   | Type                                                             | Description                                                                                                                                                                                                                                                                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-data"></a> `data?`     | `readonly` | [`RouteData`](../../play-router/index/type-aliases/RouteData.md) | The extra data that the SENDER of this event supplies: a router bridge, or the code of an application. It is not what the target state declares — that is [RouteObject.data](../../play-router/index/interfaces/RouteObject.md#property-data), and a resolver there reads this field. | [play-router/src/types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L346) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                                                        | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L347) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\>                                   | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:339](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L339) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\>                                   | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L340) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                                                         | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L338) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                                                   | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:337](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L337) |

package/api/@xmachines/play-svelte-spa-router/interfaces/RoutableActor.md

@@ -0,0 +1,72 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RoutableActor
+
+# Interface: RoutableActor
+
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L392)
+
+The minimal actor interface that `RouterBridgeBase` and every framework router
+adapter require.
+
+It names `send` itself, and it therefore gives `RouterBridgeBase.actor.send` a type that
+accepts a `PlayRouteEvent` directly. That removes the unsafe cast
+`(actor.send as (e: PlayRouteEvent) => void)`.
+
+It is [Routable](../../play-router/index/interfaces/Routable.md) with `send`. The two members of the capability are declared once,
+in `Routable`, and this interface extends it. A copy of them here drifts the day that
+one of the two files changes.
+
+**It names the view NOWHERE. Routing implies no rendering.** No file of this package,
+and no file of any of the eight router adapters, ever reads `currentView`. A provider
+whose renderer callback reads the view binds its own `TActor`, and a constraint keeps
+the concrete type of the actor whole, so that callback still reads the exact spec of
+that actor.
+
+Every `PlayActor` of `@xmachines/play-actor` that also implements `Routable`, and whose
+event union holds `PlayRouteEvent`, satisfies this interface structurally. A machine
+that declares no route event does NOT satisfy it, and that refusal is correct: a bridge
+cannot navigate an actor that receives no route event.
+
+## Example
+
+```typescript
+import type { RoutableActor } from "@xmachines/play-router";
+
+class MyBridge extends RouterBridgeBase {
+	constructor(actor: RoutableActor, routeMap: RouteMap) {
+		super(actor, routeMap);
+	}
+}
+```
+
+## Extends
+
+- [`Routable`](../../play-router/index/interfaces/Routable.md)
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                         | Inherited from                                                                                                                                      | Defined in                                                                                                                      |
+| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [`Routable`](../../play-router/index/interfaces/Routable.md).[`currentRoute`](../../play-router/index/interfaces/Routable.md#property-currentroute) | [play-router/src/types.ts:354](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L354) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [`Routable`](../../play-router/index/interfaces/Routable.md).[`initialRoute`](../../play-router/index/interfaces/Routable.md#property-initialroute) | [play-router/src/types.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L355) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [play-router/src/types.ts:394](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L394)
+
+Sends a route navigation event to the actor.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-svelte-spa-router/interfaces/RouteMapOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/types.ts:567](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L567)
 
 The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L21) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                      |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/types.ts:579](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L579) |

package/api/@xmachines/play-svelte-spa-router/interfaces/RouteMapping.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L54)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L54)
 
 One entry of the map between a state ID and a path.
 
@@ -24,5 +24,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
 | --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L58) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L56) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L56) |

package/api/@xmachines/play-svelte-spa-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L359)
+Defined in: [play-router/src/types.ts:438](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L438)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
@@ -56,7 +56,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L376)
+Defined in: [play-router/src/types.ts:455](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L455)
 
 Connects the router bridge to the Actor
 
@@ -86,7 +86,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L392)
+Defined in: [play-router/src/types.ts:471](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L471)
 
 Disconnects the router bridge from the Actor
 

package/api/@xmachines/play-svelte-spa-router/interfaces/RouterConnection.md

@@ -2,13 +2,13 @@
 
 # Interface: RouterConnection()
 
-Defined in: [play-router/src/provider-lifecycle.ts:265](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L265)
+Defined in: [play-router/src/provider-lifecycle.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L275)
 
 What `connectRouter` of an adapter returns.
 
 The value is CALLABLE, so `const disconnect = connectRouter(…); disconnect();` keeps
 working exactly as it did. It also carries the mount API, because a host that gives a
-`basePath` needs the two things [MountableRouterBridge](../../play-router/interfaces/MountableRouterBridge.md) promises: the resolved
+`basePath` needs the two things [MountableRouterBridge](../../play-router/index/interfaces/MountableRouterBridge.md) promises: the resolved
 mount to read back, and a way to move it. The bridge itself lives inside
 `connectRouter`, so without this handle a host had to rebuild the actor and the bridge
 to move a mount — which throws away the LRU cache of the route map, the very thing
@@ -21,7 +21,7 @@ stale.
 RouterConnection(): void;
 ```
 
-Defined in: [play-router/src/provider-lifecycle.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L267)
+Defined in: [play-router/src/provider-lifecycle.ts:277](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L277)
 
 Stops the synchronization. The same call as [RouterConnection.disconnect](#disconnect).
 
@@ -33,8 +33,8 @@ Stops the synchronization. The same call as [RouterConnection.disconnect](#disco
 
 | Property                                              | Modifier   | Type                                         | Description                                                                       | Defined in                                                                                                                                                |
 | ----------------------------------------------------- | ---------- | -------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath`             | `readonly` | `string`                                     | The resolved prefix of the mount, or `""` when the machine owns the whole router. | [play-router/src/provider-lifecycle.ts:288](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L288) |
-| <a id="property-basepathparams"></a> `basePathParams` | `readonly` | `Readonly`\<`Record`\<`string`, `string`\>\> | The values of the `:param` segments of the mount. They travel in no event.        | [play-router/src/provider-lifecycle.ts:290](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L290) |
+| <a id="property-basepath"></a> `basePath`             | `readonly` | `string`                                     | The resolved prefix of the mount, or `""` when the machine owns the whole router. | [play-router/src/provider-lifecycle.ts:298](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L298) |
+| <a id="property-basepathparams"></a> `basePathParams` | `readonly` | `Readonly`\<`Record`\<`string`, `string`\>\> | The values of the `:param` segments of the mount. They travel in no event.        | [play-router/src/provider-lifecycle.ts:300](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L300) |
 
 ## Methods
 
@@ -44,7 +44,7 @@ Stops the synchronization. The same call as [RouterConnection.disconnect](#disco
 dispose: void;
 ```
 
-Defined in: [play-router/src/provider-lifecycle.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L286)
+Defined in: [play-router/src/provider-lifecycle.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L296)
 
 Stops the synchronization when the scope of a `using` declaration ends.
 
@@ -73,7 +73,7 @@ The release is [RouterConnection.disconnect](#disconnect), which is idempotent.
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/provider-lifecycle.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L269)
+Defined in: [play-router/src/provider-lifecycle.ts:279](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L279)
 
 Stops the synchronization.
 
@@ -89,7 +89,7 @@ Stops the synchronization.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/provider-lifecycle.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L292)
+Defined in: [play-router/src/provider-lifecycle.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L302)
 
 Moves the mount of the live bridge, with no teardown.
 

package/api/@xmachines/play-svelte-spa-router/interfaces/WindowLike.md

@@ -2,7 +2,7 @@
 
 # Interface: WindowLike
 
-Defined in: [play-router/src/types.ts:460](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L460)
+Defined in: [play-router/src/types.ts:539](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L539)
 
 The minimal window interface of an adapter that subscribes to a DOM event, for
 example to `hashchange`. You can inject it for SSR and for a test: give a mock in
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [play-router/src/types.ts:461](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L461)
+Defined in: [play-router/src/types.ts:540](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L540)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [play-router/src/types.ts:461](https://gitlab.com/xmachin-es/xmachin
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [play-router/src/types.ts:462](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L462)
+Defined in: [play-router/src/types.ts:541](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L541)
 
 #### Parameters
 

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

@@ -4,36 +4,37 @@
 
 SvelteKit router adapter for the XMachines Universal Player Architecture. It keeps the state machine routes of a `RoutableActor` and the browser URL in step, in both directions, through the `$app/navigation` module of SvelteKit.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-sveltekit-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-sveltekit-router)
 
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-sveltekit-router
+pnpm add @xmachines/play-sveltekit-router @xmachines/play-router
 ```
 
 **Peer dependencies.** Install them separately:
 
 ```bash
-pnpm add @sveltejs/kit svelte xstate
+pnpm add @sveltejs/kit svelte
 ```
 
 | Peer dependency | Required version |
 | --------------- | ---------------- |
 | `@sveltejs/kit` | `^2.0.0`         |
 | `svelte`        | `^5.0.0`         |
-| `xstate`        | `^5.31.0`        |
 
 ## Quick Start
 
 ```typescript
 import { onDestroy } from "svelte";
-import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { connectRouter } from "@xmachines/play-sveltekit-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";
 
-// 1. Create the actor
-const createPlayer = definePlayer({ machine: myMachine });
+// 1. Create the actor — `connectRouter` needs the routing capability
+const createPlayer = definePlayer({ machine: myMachine, actor: compose(PlayerActor, withRouting) });
 const actor = createPlayer();
 actor.start();
 
@@ -60,8 +61,8 @@ This function is the primary integration point. It creates a `SvelteKitRouterBri
 
 ```typescript
 import { onDestroy } from "svelte";
-import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
-
+import { connectRouter } from "@xmachines/play-sveltekit-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // machine and actor as in the Quick Start above
 const routeMap = createRouteMap(machine);
 
@@ -92,8 +93,8 @@ onDestroy(() => disconnect());
 This class extends `RouterBridgeBase` from `@xmachines/play-router`. Use it directly when you need more control over the connection lifecycle.
 
 ```typescript
-import { SvelteKitRouterBridge, createRouteMap } from "@xmachines/play-sveltekit-router";
-
+import { SvelteKitRouterBridge } from "@xmachines/play-sveltekit-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // machine and actor as in the Quick Start above
 const routeMap = createRouteMap(machine);
 const bridge = new SvelteKitRouterBridge(actor, routeMap, location);
@@ -109,12 +110,12 @@ bridge.disconnect();
 - `watchRouterChanges` → registers an `afterNavigate` callback through an indirection cell, which prevents a direct capture of `this`
 - `unwatchRouterChanges` → sets the indirection cell to null, which releases the bridge reference before the component unmounts (SvelteKit has no API to cancel `afterNavigate`)
 
-### `createRouteMap(machine)`
+### `createRouteMap(machine)` — from `@xmachines/play-router/xstate`
 
-This factory builds a `RouteMap` from an XState machine definition. It reads each route pattern from `state.meta.route`.
+This factory builds a `RouteMap` from an XState machine definition. It reads each route pattern from `state.meta.route`. This package re-exports it never: the barrel names no state machine, so import the function from `@xmachines/play-router/xstate`.
 
 ```typescript
-import { createRouteMap } from "@xmachines/play-sveltekit-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 import { createMachine } from "xstate";
 
 const machine = createMachine({
@@ -153,7 +154,6 @@ const routeMap = new RouteMap([
 | `connectRouter`         | function | High-level factory — connects the SvelteKit router to an actor, returns a cleanup function                     |
 | `SvelteKitRouterBridge` | class    | The low-level bridge class. It extends `RouterBridgeBase`. Use it directly for full lifecycle control          |
 | `ConnectRouterOptions`  | type     | The options object for `connectRouter`                                                                         |
-| `createRouteMap`        | function | Builds a `RouteMap` from an XState machine definition                                                          |
 | `RouteMap`              | class    | Bidirectional state ID ↔ URL path mapping (re-exported from `@xmachines/play-router`)                          |
 | `RouteMapping`          | type     | Single `{ stateId, path }` entry for `RouteMap` construction                                                   |
 | `RouteMapOptions`       | type     | Options for `RouteMap` construction                                                                            |
@@ -173,20 +173,6 @@ pnpm --filter @xmachines/play-sveltekit-router-demo run dev
 
 Then open `http://localhost:5173`.
 
-## Testing
-
-Run tests for this package in isolation:
-
-```bash
-# From the monorepo root
-pnpm --filter @xmachines/play-sveltekit-router test
-
-# Or from this package directory
-pnpm test
-```
-
-Coverage thresholds: **80%** lines, functions, branches, and statements.
-
 ## License
 
 MIT — see [LICENSE](LICENSE).
@@ -202,16 +188,12 @@ MIT — see [LICENSE](LICENSE).
 - [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
 - [LocationLike](interfaces/LocationLike.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RoutableActor](interfaces/RoutableActor.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 - [RouterConnection](interfaces/RouterConnection.md)
 
-## Type Aliases
-
-- [RoutableActor](type-aliases/RoutableActor.md)
-
 ## Functions
 
 - [connectRouter](functions/connectRouter.md)
-- [createRouteMap](functions/createRouteMap.md)

package/api/@xmachines/play-sveltekit-router/classes/RouteMap.md

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L105)
+Defined in: [play-router/src/base-route-map.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L111)
 
 The shared base class of the route map for both directions.
 
@@ -17,12 +17,18 @@ of its own, and it inherits the complete public API from here.
 - The class keeps each result of a first match in an LRU cache. The default size
   is 500 entries, and the `cacheSize` constructor option changes it
 
-**The syntax of a pattern** (`:param`, `:param?`, and `*`):
+**The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+often are:
 
 - `:param` — a necessary segment. It matches exactly one segment without a `/`
 - `:param?` — an optional segment. It matches zero segments or one segment without a `/`
 - `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
+A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+too. The [routing guide](../../../../guides/routing.md) states every form, the prefix
+rule, and the one divergence from the standard: a param name of this library can hold a
+hyphen.
+
 **The forms of a stateId:** you can register a stateId, and you can look one up,
 in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
 canonical form itself. `getStateIdByPath` returns the stateId exactly as you
@@ -58,7 +64,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L133)
+Defined in: [play-router/src/base-route-map.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L139)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -87,7 +93,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L229)
+Defined in: [play-router/src/base-route-map.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L242)
 
 Returns the path pattern of a state ID.
 
@@ -123,7 +129,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
+Defined in: [play-router/src/base-route-map.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L197)
 
 Resolves a URL path to its state ID.