@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

package/api/@xmachines/play-solid-router/interfaces/AbstractActor.md

@@ -2,63 +2,13 @@
 
 # Abstract Interface: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-actor/src/abstract-actor.ts#L231)
+Defined in: [packages/play-actor/src/abstract-actor.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-actor/src/abstract-actor.ts#L141)
 
 Abstract base class for Play Architecture actors.
 
-Extends XState Actor to maintain ecosystem compatibility (inspection, devtools)
-while enforcing minimal signal protocol for Actor ↔ Infrastructure communication.
-
-The core protocol contains only:
-
-- state: Reactive state snapshot
-- send: Event dispatch method
-
-Optional capabilities (routing, view rendering) are provided via interfaces:
-
-- Implement Routable for routing support
-- Implement Viewable for view rendering support
-
-Concrete implementations created by @xmachines/play-xstate adapter.
-
-## Examples
-
-Simple actor (no routing, no view) - single type param, backward compat
-
-```typescript
-class SimpleActor extends AbstractActor<AnyActorLogic> {
-  state = new Signal.State({...});
-  send(event) { ... }
-}
-```
-
-Typed event actor - two type params
-
-```typescript
-type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
-class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
-  state = new Signal.State({...});
-  send(event: AuthEvent) { ... }
-}
-```
-
-Full-featured actor (routing + view)
-
-```typescript
-class PlayerActor extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>
-  implements Routable, Viewable {
-  state = new Signal.State({...});
-  currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-  currentView = new Signal.State(null);
-  send(event) { ... }
-}
-```
-
-## See
-
-- [Play RFC](../../../../rfc/play.md)
-- [Routable](../../play-actor/interfaces/Routable.md) for routing capability
-- [Viewable](../../play-actor/interfaces/Viewable.md) for view rendering capability
+Provides signal-driven state observation that integrates with XState ecosystem
+tooling (devtools, inspection) while exposing reactive signals for
+Infrastructure layer communication.
 
 ## Extends
 
@@ -66,26 +16,26 @@ class PlayerActor extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>
 
 ## Type Parameters
 
-| Type Parameter                                                                           | Default type                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | XState actor logic type (maintains type safety)                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | Event type union that this actor's send() accepts. Defaults to `EventObject` (`{ type: string }`) for backward compatibility. Use `EventFromLogic<TMachine>` from xstate to infer the exact event union from a state machine (e.g., in `PlayerActor`). Invariant: Actor Authority - Actor is the sole source of truth for state transitions. Invariant: Signal-Only Reactivity - Infrastructure observes via TC39 Signals. Invariant: Passive Infrastructure - Infrastructure reflects, never decides. |
+| Type Parameter                                                                           | Default type                                                      | Description                                     |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
+| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | -                                                                 | XState actor logic type                         |
+| `TEvent` _extends_ [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)     | [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject) | Event type constraint (defaults to EventObject) |
 
 ## Properties
 
-| Property                                    | Modifier   | Type                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Inherited from    | Defined in                                                                                                                                                       |
-| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-_parent"></a> `_parent?`    | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor._parent`   | -                                                                                                                                                                |
-| <a id="property-clock"></a> `clock`         | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                                                                                                                                                                              | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Actor.clock`     | -                                                                                                                                                                |
-| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `Actor.id`        | -                                                                                                                                                                |
-| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.logic`     | -                                                                                                                                                                |
-| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                      | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.options`   | -                                                                                                                                                                |
-| <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.ref`       | -                                                                                                                                                                |
-| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `Actor.sessionId` | -                                                                                                                                                                |
-| <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.src`       | -                                                                                                                                                                |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Typed as `Signal.State<unknown>` at the abstract level; concrete implementations narrow this to the actual snapshot type (e.g., `Signal.State<AnyMachineSnapshot>` in `@xmachines/play-xstate`'s `PlayerActor`). Infrastructure observes this signal to react to state changes without directly coupling to the Actor's internal state machine implementation. **Example** `// Infrastructure observes state signal const watcher = new Signal.subtle.Watcher(() => { console.log('Actor state changed:', actor.state.get()); }); watcher.watch(actor.state);` | -                 | [packages/play-actor/src/abstract-actor.ts:254](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-actor/src/abstract-actor.ts#L254) |
-| <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `Actor.system`    | -                                                                                                                                                                |
-| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.systemId`  | -                                                                                                                                                                |
+| Property                                    | Modifier   | Type                                                                                                                                                                                                                                                                                                               | Description                                                                                                                                                                             | Inherited from    | Defined in                                                                                                                                                       |
+| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`    | `public`   | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                  | -                                                                                                                                                                                       | `Actor._parent`   | -                                                                                                                                                                |
+| <a id="property-clock"></a> `clock`         | `public`   | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                                                                                                                                                                              | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                | `Actor.clock`     | -                                                                                                                                                                |
+| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The unique identifier for this actor relative to its parent.                                                                                                                            | `Actor.id`        | -                                                                                                                                                                |
+| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                                                                                                                                                                                                                                           | -                                                                                                                                                                                       | `Actor.logic`     | -                                                                                                                                                                |
+| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                      | -                                                                                                                                                                                       | `Actor.options`   | -                                                                                                                                                                |
+| <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                       | `Actor.ref`       | -                                                                                                                                                                |
+| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                     | `Actor.sessionId` | -                                                                                                                                                                |
+| <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                       | `Actor.src`       | -                                                                                                                                                                |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation. | -                 | [packages/play-actor/src/abstract-actor.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-actor/src/abstract-actor.ts#L151) |
+| <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                 | `Actor.system`    | -                                                                                                                                                                |
+| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                       | `Actor.systemId`  | -                                                                                                                                                                |
 
 ## Methods
 
@@ -95,6 +45,8 @@ class PlayerActor extends AbstractActor<AnyActorLogic, EventFromLogic<TMachine>>
 observable: InteropSubscribable<SnapshotFrom<TLogic>>;
 ```
 
+Defined in: `xstate`
+
 #### Returns
 
 [`InteropSubscribable`](https://www.jsdocs.io/package/xstate#InteropSubscribable)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>\>
@@ -113,6 +65,8 @@ Actor.[observable]
 getPersistedSnapshot(): Snapshot<unknown>;
 ```
 
+Defined in: `xstate`
+
 Obtain the internal state of the actor, which can be persisted.
 
 #### Returns
@@ -147,6 +101,8 @@ Actor.getPersistedSnapshot;
 getSnapshot(): SnapshotFrom<TLogic>;
 ```
 
+Defined in: `xstate`
+
 Read an actor’s snapshot synchronously.
 
 #### Returns
@@ -182,6 +138,8 @@ Actor.getSnapshot;
 on<TType>(type, handler): Subscription;
 ```
 
+Defined in: `xstate`
+
 #### Type Parameters
 
 | Type Parameter          |
@@ -213,6 +171,8 @@ Actor.on;
 select<TSelected>(selector, equalityFn?): Readable<TSelected>;
 ```
 
+Defined in: `xstate`
+
 #### Type Parameters
 
 | Type Parameter |
@@ -244,37 +204,22 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:278](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-actor/src/abstract-actor.ts#L278)
+Defined in: [packages/play-actor/src/abstract-actor.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-actor/src/abstract-actor.ts#L158)
 
-Send event to Actor
+Send event to Actor.
 
-Infrastructure forwards user intents (navigation, domain events, custom events)
-as events to the Actor. The Actor's state machine guards determine whether
-each event is valid from the current state.
+Constrained to TEvent for type safety in concrete implementations.
 
 #### Parameters
 
-| Parameter | Type     | Description                                                                                                                                  |
-| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `event`   | `TEvent` | Event object with type property (e.g., PlayEvent, PlayRouteEvent) Invariant: Actor Authority - Only Actor decides whether an event is valid. |
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `TEvent` |
 
 #### Returns
 
 `void`
 
-#### Example
-
-```typescript
-// Infrastructure forwards user intent
-actor.send({ type: "auth.login", userId: "123" });
-// Actor's guards determine if event is allowed
-```
-
-#### Remarks
-
-Accepts any event object with a type property. Core events (PlayEvent) are in
-@xmachines/play, routing events (PlayRouteEvent) are in @xmachines/play-router.
-
 #### Overrides
 
 ```ts
@@ -289,6 +234,8 @@ Actor.send;
 start(): this;
 ```
 
+Defined in: `xstate`
+
 Starts the Actor from the initial state
 
 #### Returns
@@ -309,6 +256,8 @@ Actor.start;
 stop(): this;
 ```
 
+Defined in: `xstate`
+
 Stops the Actor and unsubscribe all listeners.
 
 #### Returns
@@ -331,6 +280,8 @@ Actor.stop;
 subscribe(observer): Subscription;
 ```
 
+Defined in: `xstate`
+
 Subscribe an observer to an actor’s snapshot values.
 
 ##### Parameters
@@ -407,6 +358,8 @@ subscribe(
    completeListener?): Subscription;
 ```
 
+Defined in: `xstate`
+
 Subscribe an observer to an actor’s snapshot values.
 
 ##### Parameters
@@ -484,6 +437,8 @@ Actor.subscribe;
 toJSON(): object;
 ```
 
+Defined in: `xstate`
+
 #### Returns
 
 `object`

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [packages/play-router/src/types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L216)
+Defined in: [packages/play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -30,7 +30,7 @@ Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
@@ -85,7 +85,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);
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                                       |
 | -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [packages/play-router/src/types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L221) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [packages/play-router/src/types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L219) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [packages/play-router/src/types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L220) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [packages/play-router/src/types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L218) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [packages/play-router/src/types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L217) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [packages/play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [packages/play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [packages/play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [packages/play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [packages/play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L224) |

package/api/@xmachines/play-solid-router/interfaces/PlayRouterProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L16)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L33)
 
 ## Type Parameters
 
@@ -14,7 +14,7 @@ Defined in: [packages/play-solid-router/src/play-router-provider.tsx:16](https:/
 
 | Property                                  | Type                                                      | Description                                                                 | Defined in                                                                                                                                                                                 |
 | ----------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `actor`       | `TActor`                                                  | -                                                                           | [packages/play-solid-router/src/play-router-provider.tsx:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L17) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                              | Renderer callback receives the same concrete actor type that was passed in. | [packages/play-solid-router/src/play-router-provider.tsx:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L21) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                      | -                                                                           | [packages/play-solid-router/src/play-router-provider.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L18) |
-| <a id="property-router"></a> `router`     | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | -                                                                           | [packages/play-solid-router/src/play-router-provider.tsx:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L19) |
+| <a id="property-actor"></a> `actor`       | `TActor`                                                  | -                                                                           | [packages/play-solid-router/src/play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L34) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                              | Renderer callback receives the same concrete actor type that was passed in. | [packages/play-solid-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L38) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                      | -                                                                           | [packages/play-solid-router/src/play-router-provider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L35) |
+| <a id="property-router"></a> `router`     | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | -                                                                           | [packages/play-solid-router/src/play-router-provider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L36) |

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

@@ -2,13 +2,26 @@
 
 # Interface: RouteMapping
 
-Defined in: [packages/play-solid-router/src/types.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/types.ts#L8)
+Defined in: [packages/play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L57)
 
-Mapping between state ID and URL path for SolidJS Router
+A single state ID ↔ path mapping entry.
+
+Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`BaseRouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
+const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                              | Defined in                                                                                                                                                 |
-| --------------------------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | SolidJS Router path pattern **Example** `'/', '/profile/:userId', '/settings/:section?'` | [packages/play-solid-router/src/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/types.ts#L19) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | XMachines state ID with # prefix **Example** `'#home', '#profile'`                       | [packages/play-solid-router/src/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/types.ts#L13) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                                       |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [packages/play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [packages/play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [packages/play-router/src/types.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L264)
+Defined in: [packages/play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [packages/play-router/src/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L280)
+Defined in: [packages/play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [packages/play-router/src/types.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L296)
+Defined in: [packages/play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

@@ -6,6 +6,6 @@
 type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L8)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L9)
 
 Minimum actor shape accepted by PlayRouterProvider.

package/api/@xmachines/play-solid-router/type-aliases/SolidRouterHooks.md

@@ -6,46 +6,49 @@
 type SolidRouterHooks = object;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L10)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L27)
 
-## Properties
-
-### location
+The three Solid Router hook results that `PlayRouterProvider` and `SolidRouterBridge`
+require. Pass these directly from your component's hook calls:
 
-```ts
-location: object;
+```tsx
+const navigate = useNavigate(); // → SolidRouterHooks.navigate
+const location = useLocation(); // → SolidRouterHooks.location
+const params = useParams(); // → SolidRouterHooks.params
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L12)
-
-#### pathname
+- `navigate` — used to push URL changes when the actor's `currentRoute` changes.
+- `location` — `pathname` and `search` are read at `connect()` time for deep-link sync.
+  Subsequent pathname changes drive router→actor sync via `createEffect`.
+- `params` — Solid's pre-parsed path parameters for the current route segment. Used
+  directly in `extractParams()` to avoid re-parsing with URLPattern.
 
-```ts
-pathname: string;
-```
+## Properties
 
-#### search
+### location
 
 ```ts
-search: string;
+location: Location;
 ```
 
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L29)
+
 ---
 
 ### navigate
 
 ```ts
-navigate: ((path) => void) | ((path, ...args) => unknown);
+navigate: Navigator;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L11)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L28)
 
 ---
 
 ### params
 
 ```ts
-params: Record<string, string | undefined>;
+params: Params;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-solid-router/src/play-router-provider.tsx#L13)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-solid-router/src/play-router-provider.tsx#L30)

package/api/@xmachines/play-solid-router-demo/README.md

@@ -2,7 +2,7 @@
 
 # Solid Router Demo
 
-Solid + `@solidjs/router` demonstration of the Play architecture using provider-based router integration.
+Solid + `@solidjs/router` integration demo for the XMachines Play architecture using provider-based router integration.
 
 ## What This Demonstrates
 
@@ -14,22 +14,22 @@ Solid + `@solidjs/router` demonstration of the Play architecture using provider-
 
 ## Running the Demo
 
-From this directory (`packages/play-solid-router/examples/demo`):
+From the repository root:
 
 ```bash
 npm install
-npm run dev
+npm run dev -w packages/play-solid-router/examples/demo
 ```
 
-Open `http://localhost:5173`.
+Then open `http://localhost:3002`.
 
 ## Step-by-Step Code Flow
 
 Use this order to understand the implementation:
 
-1. `src/main.tsx` bootstraps the demo and mounts the `<App />` component.
+1. `src/main.tsx` bootstraps the demo and mounts `<App />`.
 2. `src/App.tsx` wires actor lifecycle, shared machine/catalog imports, and router integration.
-3. A `routeMap` is created by extracting routes from the shared `authMachine`.
+3. A `routeMap` is created by calling `createRouteMap(authMachine)`.
 4. `PlayRouterProvider` forwards navigation intent from `@solidjs/router` to the actor, and reflects actor-approved routes back to the URL.
 5. `Shell` (inside `src/App.tsx`) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell.
 6. `test/library-pattern.test.ts` and `test/browser/` verify invariants and runtime routing behavior.
@@ -64,12 +64,11 @@ const routeMap = createRouteMap(authMachine);
 
 ## Key Files
 
-- `src/App.tsx` - Integration entry point wiring actor, provider, renderer, and shared machine/catalog imports.
-- `src/main.tsx` - Vite bootstrap for the Solid app.
-- `src/components/` - Demo views and controls that send events to the actor.
-- `test/library-pattern.test.ts` - Node/Vitest invariant checks for architecture boundaries.
-- `test/browser/startup.browser.test.ts` - Browser startup and mount coverage.
-- `test/browser/auth-flow.browser.test.ts` - Browser auth and routing behavior coverage.
+- `src/App.tsx` - actor lifecycle, route map, `PlayRouterProvider` wiring, and renderer composition
+- `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/components/` - demo view components that send events to the actor
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
 
 ## State Machine & Architecture Details
 
@@ -97,31 +96,29 @@ Solid Router integration remains passive infrastructure. `RouterBridgeBase` stay
 
 ## Available Scripts
 
-```bash
-npm run dev           # Start Vite dev server (default: http://localhost:5173)
-npm run build         # Build production assets
-npm run preview       # Preview production build locally
-npm run test          # Run unit/integration tests via Vitest
-npm run test:browser  # Run browser-mode tests via vitest.browser.config.ts
-```
+These commands are defined in `package.json`:
+
+| Command                                                            | Description                      |
+| ------------------------------------------------------------------ | -------------------------------- |
+| `npm run dev -w packages/play-solid-router/examples/demo`          | Start Vite dev server            |
+| `npm run build -w packages/play-solid-router/examples/demo`        | Build production bundle          |
+| `npm run preview -w packages/play-solid-router/examples/demo`      | Preview built bundle             |
+| `npm run test -w packages/play-solid-router/examples/demo`         | Run Vitest test suite            |
+| `npm run test:browser -w packages/play-solid-router/examples/demo` | Run browser-focused Vitest suite |
 
 ## Verification
 
-Use these checks from this directory:
+Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test
-npm run test:browser
+npm run test -w packages/play-solid-router/examples/demo
+npm run test:browser -w packages/play-solid-router/examples/demo
 ```
 
-Manual sanity check:
-
-1. Start the app with `npm run dev`.
-2. Open `http://localhost:5173`.
-3. Confirm login/logout transitions update both view and URL, and that accessing protected routes while logged out redirects properly.
+Expected result: library-pattern invariant tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.
 
 ## Learn More
 
 - [Solid Router package README](../play-solid-router/README.md)
+- [SolidJS package README](../play-solid/README.md)
 - [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)
-- [TanStack React Router demo README](../play-tanstack-react-router-demo/README.md)