@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-vue-router/interfaces/PlayActor.md

@@ -0,0 +1,68 @@
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayActor
+
+# Interface: PlayActor
+
+Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L297)
+
+Full actor shape used by `PlayRouterProvider` components across all framework
+adapters (`play-solid-router`, `play-vue-router`, `play-react-router`, and the
+adapters built on the shared framework-router bridge bases).
+
+Extends `RoutableActor` with `currentView` — the provider renders the current
+view spec in addition to synchronizing routes, so it needs both capabilities.
+
+- Use `RoutableActor` when only routing is needed (e.g. `RouterBridgeBase` subclasses,
+  `connectRouter`).
+- Use `PlayActor` when the component also renders the current view spec
+  (e.g. `PlayRouterProvider` renderer callback parameter, `PlayRenderer`).
+
+All `AbstractActor` subclasses that implement both `Routable` and `Viewable`
+satisfy this interface structurally.
+
+## Example
+
+```typescript
+import type { PlayActor } from "@xmachines/play-router";
+
+function MyRouterProvider({ actor }: { actor: PlayActor }) {
+	// access actor.currentRoute (routing) and actor.currentView (rendering)
+}
+```
+
+## Extends
+
+- [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                                                                                                 | Defined in                                                                                                                      |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L261) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L299) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L267) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L269)
+
+Send a route navigation event to the actor.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`send`](../../play-dom-router/interfaces/RoutableActor.md#send)

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

@@ -1,8 +1,8 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouteEvent
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouteEvent
 
 # Interface: PlayRouteEvent
 
-Defined in: play-router/dist/types.d.ts:182
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L225)
 
 Enhanced routing event with parameter and query support
 
@@ -22,22 +22,32 @@ via `play.route` events, Actor decides via state machine transitions.
 
 ## Param
 
+**type**
+
 Event discriminator (always "play.route")
 
 ## Param
 
+**to**
+
 Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+**params**
+
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
+**query**
+
 Query parameters only (isolated from path params)
 
 ## Param
 
+**match**
+
 Full URLPattern match result for debugging/observability (optional)
 
 ## Examples
@@ -85,7 +95,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Merged: path + query
+	params: { section: "profile" }, // Path-only route parameter
 	query: { tab: "security" }, // Query-only
 };
 actor.send(event);
@@ -94,7 +104,7 @@ actor.send(event);
 
 ## See
 
-[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+[Play RFC](../../../../rfc/play.md)
 
 ## Remarks
 
@@ -110,10 +120,10 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                      |
-| -------------------------------------- | ---------- | ------------------------------ | ------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | play-router/dist/types.d.ts:187 |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:185 |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:186 |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | play-router/dist/types.d.ts:184 |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | play-router/dist/types.d.ts:183 |
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L226) |

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

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouteMapOptions
+
+# Interface: RouteMapOptions
+
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L9)
+
+Options for `createRouteMap` and `createRouteMapFromTree`.
+
+## Properties
+
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -1,15 +1,27 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouteMapping
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouteMapping
 
 # Interface: RouteMapping
 
-Defined in: [play-vue-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/types.ts#L10)
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L51)
 
-Mapping configuration between XMachines state IDs and Vue Router route names
+A single state ID ↔ path mapping entry.
+
+Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`RouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: RouteMapping = { stateId: "home", path: "/" };
+const paramMapping: RouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                    | Modifier   | Type     | Description                                    | Defined in                                                                                                                                                              |
-| ------------------------------------------- | ---------- | -------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pattern"></a> `pattern?`    | `readonly` | `string` | Optional URL pattern for debugging             | [play-vue-router/src/types.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/types.ts#L16) |
-| <a id="property-routename"></a> `routeName` | `readonly` | `string` | Vue Router route name                          | [play-vue-router/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/types.ts#L14) |
-| <a id="property-stateid"></a> `stateId`     | `readonly` | `string` | XMachines state ID (e.g., '#home', '#profile') | [play-vue-router/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/types.ts#L12) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L53) |

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

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouterBridge
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouterBridge
 
 # Interface: RouterBridge
 
-Defined in: play-router/dist/types.d.ts:229
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L341)
 
 RouterBridge interface for runtime infrastructure adapters
 
-Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
 the Actor. Infrastructure "bridges" to the Actor by observing its signals and
 managing its own lifecycle accordingly.
 
@@ -16,13 +16,13 @@ a unidirectional observation pattern. Infrastructure connects to observe Actor s
 
 ## Example
 
-TanStack Router bridge implementation
+Framework router bridge implementation
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
 
-class TanStackRouterBridge implements RouterBridge {
+class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
@@ -44,7 +44,7 @@ class TanStackRouterBridge implements RouterBridge {
 
 ## See
 
-[RFC Play v1 - Invariant INV-04](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
 
 ## Methods
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: play-router/dist/types.d.ts:245
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L357)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: play-router/dist/types.d.ts:260
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L373)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-vue-router/type-aliases/RoutableActor.md

@@ -1,9 +1,13 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RoutableActor
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RoutableActor
 
-# Type Alias: RoutableActor
+# ~~Type Alias: RoutableActor~~
 
 ```ts
-type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
+type RoutableActor = PlayActor;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/play-router-provider.ts#L9)
+Defined in: [play-vue-router/src/play-router-provider.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-vue-router/src/play-router-provider.ts#L10)
+
+## Deprecated
+
+Use `PlayActor` from `@xmachines/play-router`. Will be removed in the next major version.

package/api/@xmachines/play-vue-router/variables/PlayRouterProvider.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouterProvider
+[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouterProvider
 
 # Variable: PlayRouterProvider
 
@@ -7,7 +7,7 @@ const PlayRouterProvider: DefineComponent<
 	ExtractPropTypes<{
 		actor: {
 			required: true;
-			type: PropType<RoutableActor>;
+			type: PropType<PlayActor>;
 		};
 		renderer: {
 			required: true;
@@ -19,7 +19,7 @@ const PlayRouterProvider: DefineComponent<
 		};
 		router: {
 			required: true;
-			type: PropType<Router>;
+			type: PropType<RouterClassic>;
 		};
 	}>,
 	() => VNodeChild,
@@ -35,7 +35,7 @@ const PlayRouterProvider: DefineComponent<
 		ExtractPropTypes<{
 			actor: {
 				required: true;
-				type: PropType<RoutableActor>;
+				type: PropType<PlayActor>;
 			};
 			renderer: {
 				required: true;
@@ -47,7 +47,7 @@ const PlayRouterProvider: DefineComponent<
 			};
 			router: {
 				required: true;
-				type: PropType<Router>;
+				type: PropType<RouterClassic>;
 			};
 		}>,
 		{}
@@ -64,4 +64,10 @@ const PlayRouterProvider: DefineComponent<
 >;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue-router/src/play-router-provider.ts#L11)
+Defined in: [play-vue-router/src/play-router-provider.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-vue-router/src/play-router-provider.ts#L19)
+
+PlayRouterProvider — Vue convenience wrapper for VueRouterBridge.
+
+Note: Vue's `defineComponent` does not support generic type parameters.
+The renderer prop is typed with the `RoutableActor` constraint. Pass a concrete
+actor and TypeScript will structurally validate it at the call site.