@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,486 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / AbstractActor
+
+# Abstract Interface: AbstractActor\<TLogic\>
+
+Defined in: packages/play-actor/dist/abstract-actor.d.ts:173
+
+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)
+
+```typescript
+class SimpleActor extends AbstractActor<AnyActorLogic> {
+  state = new Signal.State({...});
+  send(event) { ... }
+}
+```
+
+Routable actor
+
+```typescript
+class RoutableActor extends AbstractActor<AnyActorLogic> implements Routable {
+  state = new Signal.State({...});
+  currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+  send(event) { ... }
+}
+```
+
+Full-featured actor (routing + view)
+
+```typescript
+class PlayerActor extends AbstractActor<AnyActorLogic> implements Routable, Viewable {
+  state = new Signal.State({...});
+  currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+  currentView = new Signal.State(null);
+  catalog = {};
+  send(event) { ... }
+}
+```
+
+## See
+
+- [RFC Play v1 Section 5.3](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol)
+- [Routable](../../play-actor/interfaces/Routable.md) for routing capability
+- [Viewable](../../play-actor/interfaces/Viewable.md) for view rendering capability
+
+## Extends
+
+- `Actor`\<`TLogic`\>
+
+## Type Parameters
+
+| Type Parameter                     | Description                                                                                                                                                                                                                                                                                     |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TLogic` _extends_ `AnyActorLogic` | XState actor logic type (maintains type safety) 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. |
+
+## Properties
+
+| Property                                    | Modifier   | Type                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Inherited from    | Defined in                                                    |
+| ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`    | `public`   | `AnyActorRef`                                                                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor._parent`   | node_modules/xstate/dist/declarations/src/createActor.d.ts:33 |
+| <a id="property-clock"></a> `clock`         | `public`   | `Clock`                                                                                           | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Actor.clock`     | node_modules/xstate/dist/declarations/src/createActor.d.ts:25 |
+| <a id="property-id"></a> `id`               | `public`   | `string`                                                                                          | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `Actor.id`        | node_modules/xstate/dist/declarations/src/createActor.d.ts:28 |
+| <a id="property-logic"></a> `logic`         | `public`   | `TLogic`                                                                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.logic`     | node_modules/xstate/dist/declarations/src/createActor.d.ts:18 |
+| <a id="property-options"></a> `options`     | `public`   | `Readonly`\<`ActorOptions`\<`TLogic`\>\>                                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.options`   | node_modules/xstate/dist/declarations/src/createActor.d.ts:26 |
+| <a id="property-ref"></a> `ref`             | `public`   | `ActorRef`\<`SnapshotFrom`\<`TLogic`\>, `EventFromLogic`\<`TLogic`\>, `EmittedFrom`\<`TLogic`\>\> | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.ref`       | node_modules/xstate/dist/declarations/src/createActor.d.ts:34 |
+| <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                          | The globally unique process ID for this invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `Actor.sessionId` | node_modules/xstate/dist/declarations/src/createActor.d.ts:38 |
+| <a id="property-src"></a> `src`             | `public`   | `string` \| `AnyActorLogic`                                                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.src`       | node_modules/xstate/dist/declarations/src/createActor.d.ts:42 |
+| <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/dist/abstract-actor.d.ts:193              |
+| <a id="property-system"></a> `system`       | `public`   | `AnyActorSystem`                                                                                  | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `Actor.system`    | node_modules/xstate/dist/declarations/src/createActor.d.ts:40 |
+| <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `Actor.systemId`  | node_modules/xstate/dist/declarations/src/createActor.d.ts:36 |
+
+## Methods
+
+### \[observable\]()
+
+```ts
+observable: InteropSubscribable<SnapshotFrom<TLogic>>;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:153
+
+#### Returns
+
+`InteropSubscribable`\<`SnapshotFrom`\<`TLogic`\>\>
+
+#### Inherited from
+
+```ts
+Actor.[observable]
+```
+
+---
+
+### getPersistedSnapshot()
+
+```ts
+getPersistedSnapshot(): Snapshot<unknown>;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:152
+
+Obtain the internal state of the actor, which can be persisted.
+
+#### Returns
+
+`Snapshot`\<`unknown`\>
+
+#### Remarks
+
+The internal state can be persisted from any actor, not only machines.
+
+Note that the persisted state is not the same as the snapshot from
+[Actor.getSnapshot](../../play-actor/classes/AbstractActor.md#getsnapshot). Persisted state represents the internal state of
+the actor, while snapshots represent the actor's last emitted value.
+
+Can be restored with [ActorOptions.state](#)
+
+#### See
+
+https://stately.ai/docs/persistence
+
+#### Inherited from
+
+```ts
+Actor.getPersistedSnapshot;
+```
+
+---
+
+### getSnapshot()
+
+```ts
+getSnapshot(): SnapshotFrom<TLogic>;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:168
+
+Read an actor’s snapshot synchronously.
+
+#### Returns
+
+`SnapshotFrom`\<`TLogic`\>
+
+#### Remarks
+
+The snapshot represent an actor's last emitted value.
+
+When an actor receives an event, its internal state may change. An actor
+may emit a snapshot when a state transition occurs.
+
+Note that some actors, such as callback actors generated with
+`fromCallback`, will not emit snapshots.
+
+#### See
+
+- [Actor.subscribe](../../play-actor/classes/AbstractActor.md#subscribe) to subscribe to an actor’s snapshot values.
+- [Actor.getPersistedSnapshot](../../play-actor/classes/AbstractActor.md#getpersistedsnapshot) to persist the internal state of an actor (which is more than just a snapshot).
+
+#### Inherited from
+
+```ts
+Actor.getSnapshot;
+```
+
+---
+
+### on()
+
+```ts
+on<TType>(type, handler): Subscription;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:115
+
+#### Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `TType` _extends_ `any` |
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `type`    | `TType`               |
+| `handler` | (`emitted`) => `void` |
+
+#### Returns
+
+`Subscription`
+
+#### Inherited from
+
+```ts
+Actor.on;
+```
+
+---
+
+### send()
+
+```ts
+abstract send(event): void;
+```
+
+Defined in: packages/play-actor/dist/abstract-actor.d.ts:216
+
+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.
+
+#### Parameters
+
+| Parameter | Type                                       | Description                                                                                                                                  |
+| --------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `event`   | `object` & `Record`\<`string`, `unknown`\> | Event object with type property (e.g., PlayEvent, PlayRouteEvent) Invariant: Actor Authority - Only Actor decides whether an event is valid. |
+
+#### 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
+Actor.send;
+```
+
+---
+
+### start()
+
+```ts
+start(): this;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:119
+
+Starts the Actor from the initial state
+
+#### Returns
+
+`this`
+
+#### Inherited from
+
+```ts
+Actor.start;
+```
+
+---
+
+### stop()
+
+```ts
+stop(): this;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:123
+
+Stops the Actor and unsubscribe all listeners.
+
+#### Returns
+
+`this`
+
+#### Inherited from
+
+```ts
+Actor.stop;
+```
+
+---
+
+### subscribe()
+
+#### Call Signature
+
+```ts
+subscribe(observer): Subscription;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:113
+
+Subscribe an observer to an actor’s snapshot values.
+
+##### Parameters
+
+| Parameter  | Type                                     | Description                                                                                                                                  |
+| ---------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observer` | `Observer`\<`SnapshotFrom`\<`TLogic`\>\> | Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot |
+
+##### Returns
+
+`Subscription`
+
+##### Remarks
+
+The observer will receive the actor’s snapshot value when it is emitted.
+The observer can be:
+
+- A plain function that receives the latest snapshot, or
+- An observer object whose `.next(snapshot)` method receives the latest
+  snapshot
+
+##### Examples
+
+```ts
+// Observer as a plain function
+const subscription = actor.subscribe((snapshot) => {
+	console.log(snapshot);
+});
+```
+
+```ts
+// Observer as an object
+const subscription = actor.subscribe({
+	next(snapshot) {
+		console.log(snapshot);
+	},
+	error(err) {
+		// ...
+	},
+	complete() {
+		// ...
+	},
+});
+```
+
+The return value of `actor.subscribe(observer)` is a subscription object
+that has an `.unsubscribe()` method. You can call
+`subscription.unsubscribe()` to unsubscribe the observer:
+
+```ts
+const subscription = actor.subscribe((snapshot) => {
+	// ...
+});
+
+// Unsubscribe the observer
+subscription.unsubscribe();
+```
+
+When the actor is stopped, all of its observers will automatically be
+unsubscribed.
+
+##### Inherited from
+
+```ts
+Actor.subscribe;
+```
+
+#### Call Signature
+
+```ts
+subscribe(
+   nextListener?,
+   errorListener?,
+   completeListener?): Subscription;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:114
+
+Subscribe an observer to an actor’s snapshot values.
+
+##### Parameters
+
+| Parameter           | Type                   |
+| ------------------- | ---------------------- |
+| `nextListener?`     | (`snapshot`) => `void` |
+| `errorListener?`    | (`error`) => `void`    |
+| `completeListener?` | () => `void`           |
+
+##### Returns
+
+`Subscription`
+
+##### Remarks
+
+The observer will receive the actor’s snapshot value when it is emitted.
+The observer can be:
+
+- A plain function that receives the latest snapshot, or
+- An observer object whose `.next(snapshot)` method receives the latest
+  snapshot
+
+##### Examples
+
+```ts
+// Observer as a plain function
+const subscription = actor.subscribe((snapshot) => {
+	console.log(snapshot);
+});
+```
+
+```ts
+// Observer as an object
+const subscription = actor.subscribe({
+	next(snapshot) {
+		console.log(snapshot);
+	},
+	error(err) {
+		// ...
+	},
+	complete() {
+		// ...
+	},
+});
+```
+
+The return value of `actor.subscribe(observer)` is a subscription object
+that has an `.unsubscribe()` method. You can call
+`subscription.unsubscribe()` to unsubscribe the observer:
+
+```ts
+const subscription = actor.subscribe((snapshot) => {
+	// ...
+});
+
+// Unsubscribe the observer
+subscription.unsubscribe();
+```
+
+When the actor is stopped, all of its observers will automatically be
+unsubscribed.
+
+##### Inherited from
+
+```ts
+Actor.subscribe;
+```
+
+---
+
+### toJSON()
+
+```ts
+toJSON(): object;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:135
+
+#### Returns
+
+`object`
+
+| Name           | Type     | Defined in                                                     |
+| -------------- | -------- | -------------------------------------------------------------- |
+| `id`           | `string` | node_modules/xstate/dist/declarations/src/createActor.d.ts:137 |
+| `xstate$$type` | `number` | node_modules/xstate/dist/declarations/src/createActor.d.ts:136 |
+
+#### Inherited from
+
+```ts
+Actor.toJSON;
+```

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

@@ -0,0 +1,119 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: packages/play-router/dist/types.d.ts:182
+
+Enhanced routing event with parameter and query support
+
+Unified routing event used throughout the Play architecture. Supports parameter-aware
+navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
+user navigation intent that the Actor evaluates through guards. Infrastructure proposes
+via `play.route` events, Actor decides via state machine transitions.
+
+**Browser Navigation Flow:**
+
+1. Browser fires `popstate`
+2. Router adapter resolves URL to route target
+3. Adapter sends `PlayRouteEvent` to Actor
+4. Actor validates transition via state machine guards
+
+## Param
+
+Event discriminator (always "play.route")
+
+## Param
+
+Target state ID with # prefix (e.g., '#home', '#profile')
+
+## Param
+
+Merged path + query parameters (path parameters win conflicts)
+
+## Param
+
+Query parameters only (isolated from path params)
+
+## Param
+
+Full URLPattern match result for debugging/observability (optional)
+
+## Examples
+
+Combining base and routing events
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+type AppEvent = PlayEvent | PlayRouteEvent;
+```
+
+Basic navigation to a route
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#home",
+};
+actor.send(event);
+```
+
+Navigation with route parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#profile",
+	params: { userId: "123" },
+};
+actor.send(event);
+// Resolves to route: /profile/123
+```
+
+Navigation with query parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#settings",
+	params: { section: "profile" }, // Merged: path + query
+	query: { tab: "security" }, // Query-only
+};
+actor.send(event);
+// Resolves to route: /settings/profile?tab=security
+```
+
+## See
+
+[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+
+## Remarks
+
+Use `play.route` when you need parameter-aware navigation with the `route: {}`
+config pattern on your state machine nodes. The `match` field exposes the full
+URLPatternResult for advanced use cases (debugging, pattern analysis).
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+| Property                               | Modifier   | Type                           | Defined in                               |
+| -------------------------------------- | ---------- | ------------------------------ | ---------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | packages/play-router/dist/types.d.ts:187 |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | packages/play-router/dist/types.d.ts:185 |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | packages/play-router/dist/types.d.ts:186 |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | packages/play-router/dist/types.d.ts:184 |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | packages/play-router/dist/types.d.ts:183 |

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

@@ -0,0 +1,14 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterProviderProps
+
+# Interface: PlayRouterProviderProps
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L14)
+
+## Properties
+
+| Property                                  | Type                                                      | Defined in                                                                                                                                                                                                           |
+| ----------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | [`RoutableActor`](../type-aliases/RoutableActor.md)       | [packages/play-solid-router/src/play-router-provider.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L15) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                              | [packages/play-solid-router/src/play-router-provider.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L18) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                      | [packages/play-solid-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L16) |
+| <a id="property-router"></a> `router`     | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | [packages/play-solid-router/src/play-router-provider.tsx:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L17) |

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

@@ -0,0 +1,14 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouteMapping
+
+# Interface: RouteMapping
+
+Defined in: [packages/play-solid-router/src/types.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/types.ts#L8)
+
+Mapping between state ID and URL path for SolidJS Router
+
+## 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/00a28432ed57807112288436d1ae4387d9f06919/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/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/types.ts#L13) |