@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-actor/classes/AbstractActor.md

@@ -0,0 +1,520 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / AbstractActor
+
+# Abstract Class: AbstractActor\<TLogic\>
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L179)
+
+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](../interfaces/Routable.md) for routing capability
+- [Viewable](../interfaces/Viewable.md) for view rendering capability
+
+## Extends
+
+- `Actor`\<`TLogic`\>
+
+## Extended by
+
+- [`PlayerActor`](../../play-xstate/classes/PlayerActor.md)
+
+## 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. |
+
+## Constructors
+
+### Constructor
+
+```ts
+new AbstractActor<TLogic>(logic, options?): AbstractActor<TLogic>;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:50
+
+Creates a new actor instance for the given logic with the provided options,
+if any.
+
+#### Parameters
+
+| Parameter  | Type                       | Description                       |
+| ---------- | -------------------------- | --------------------------------- |
+| `logic`    | `TLogic`                   | The logic to create an actor from |
+| `options?` | `ActorOptions`\<`TLogic`\> | Actor options                     |
+
+#### Returns
+
+`AbstractActor`\<`TLogic`\>
+
+#### Inherited from
+
+```ts
+Actor<TLogic>.constructor
+```
+
+## 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/src/abstract-actor.ts:199](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L199) |
+| <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](#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](#subscribe) to subscribe to an actor’s snapshot values.
+- [Actor.getPersistedSnapshot](#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/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L223)
+
+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-actor/interfaces/Routable.md

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / Routable
+
+# Interface: Routable
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L41)
+
+Optional capability: Routing support
+
+Actors implementing this interface can derive a route from their state.
+Router adapters observe the currentRoute signal to sync browser URLs.
+
+## Example
+
+```typescript
+class MyActor extends AbstractActor implements Routable {
+	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+}
+
+// Router requires Routable
+function connectRouter<T extends AbstractActor & Routable>(actor: T) {
+	watcher.watch(actor.currentRoute);
+}
+```
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                          | Defined in                                                                                                                                                                               |
+| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | Current route signal Computed signal derived from state machine. Infrastructure observes to sync browser URL. Invariant: Passive Infrastructure - Infrastructure reflects route, never decides. **Example** `const watcher = new Signal.subtle.Watcher(() => { const route = actor.currentRoute.get(); console.log('Route changed:', route); }); watcher.watch(actor.currentRoute);` | [packages/play-actor/src/abstract-actor.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L58) |

package/api/@xmachines/play-actor/interfaces/ViewMetadata.md

@@ -0,0 +1,17 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / ViewMetadata
+
+# Interface: ViewMetadata
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L87)
+
+View metadata for rendering
+
+Describes the component to be rendered and the props to pass to it.
+Used by PlayRenderer to dynamically render UI based on actor state.
+
+## Properties
+
+| Property                                    | Type                            | Description                                      | Defined in                                                                                                                                                                               |
+| ------------------------------------------- | ------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-component"></a> `component` | `string`                        | Name of the component to render from the catalog | [packages/play-actor/src/abstract-actor.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L89) |
+| <a id="property-props"></a> `props`         | `Record`\<`string`, `unknown`\> | Props to pass to the component                   | [packages/play-actor/src/abstract-actor.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L91) |

package/api/@xmachines/play-actor/interfaces/Viewable.md

@@ -0,0 +1,12 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / Viewable
+
+# Interface: Viewable
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L94)
+
+## Properties
+
+| Property                                        | Modifier   | Type                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                     | Defined in                                                                                                                                                                                 |
+| ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-catalog"></a> `catalog`         | `readonly` | `Record`\<`string`, `unknown`\>                                                                                 | Component catalog for view resolution Maps component names to actual component implementations. Used by renderers to resolve view.component to actual UI components.                                                                                                                                                                                                            | [packages/play-actor/src/abstract-actor.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L119) |
+| <a id="property-currentview"></a> `currentView` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`ViewMetadata`](ViewMetadata.md) \| `null`\> | Current view signal State signal containing UI structure schema from meta.view. Infrastructure renders view. Invariant: Logic-Driven UI - View structure is defined by business logic, not JSX. **Example** `const watcher = new Signal.subtle.Watcher(() => { const view = actor.currentView.get(); console.log('View changed:', view); }); watcher.watch(actor.currentView);` | [packages/play-actor/src/abstract-actor.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L111) |