@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-xstate/classes/PlayerActor.md

@@ -0,0 +1,527 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerActor
+
+# Class: PlayerActor\<TMachine\>
+
+Defined in: [packages/play-xstate/src/player-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L120)
+
+Concrete XState actor implementing Play Architecture signal protocol
+
+Extends [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) to provide XState v5 integration
+while maintaining ecosystem compatibility (XState inspection, devtools). This actor
+wraps an internal XState actor and exposes TC39 Signal-based reactive state for
+Infrastructure observation.
+
+**Capabilities:** Implements both [@xmachines/play-actor!Routable](../../play-actor/interfaces/Routable.md) and
+[@xmachines/play-actor!Viewable](../../play-actor/interfaces/Viewable.md) interfaces, providing routing and view
+rendering support.
+
+**Architectural Context:** Implements **Actor Authority (INV-01)** by ensuring the
+XState machine's guards control all navigation decisions. Infrastructure observes
+the actor's signals (`state`, `currentRoute`, `currentView`) but cannot directly
+manipulate state—all mutations flow through the state machine's event handlers.
+
+## Examples
+
+Basic actor creation and lifecycle
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const machine = setup({}).createMachine({
+	initial: "idle",
+	states: {
+		idle: {
+			meta: { route: "/", view: { component: "HomePage" } },
+		},
+	},
+});
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
+// Observe signals
+console.log(actor.currentRoute.get()); // '/'
+console.log(actor.currentView.get()); // { component: 'HomePage' }
+```
+
+Signal lifecycle with watchers (microtask batching)
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		console.log("State changed:", actor.state.get());
+	});
+});
+
+watcher.watch(actor.state);
+actor.send({ type: "play.route", to: "#about" });
+// Watcher notification scheduled via microtask
+```
+
+## See
+
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [definePlayer](../functions/definePlayer.md) for factory creation
+- [@xmachines/play-actor!AbstractActor](../../play-actor/classes/AbstractActor.md) for signal protocol
+- [@xmachines/play-actor!Routable](../../play-actor/interfaces/Routable.md) for routing capability
+- [@xmachines/play-actor!Viewable](../../play-actor/interfaces/Viewable.md) for view rendering capability
+
+## Remarks
+
+**Routing:** This actor supports both XState's `route: {}` config pattern
+and `play.route` events with parameters. The `deriveRoute()` function checks
+`meta.route` (Stately pattern) for URL templates with parameter substitution support.
+
+**View Signal Pattern:** The `currentView` signal is a direct `Signal.State` (not
+`Signal.Computed`) to ensure proper watcher propagation in PlayRenderer. Views are
+cached and updated at state entry, not computed on every read.
+
+## Extends
+
+- [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\>
+
+## Type Parameters
+
+| Type Parameter                         | Description                  |
+| -------------------------------------- | ---------------------------- |
+| `TMachine` _extends_ `AnyStateMachine` | XState v5 state machine type |
+
+## Implements
+
+- [`Routable`](../../play-actor/interfaces/Routable.md)
+- [`Viewable`](../../play-actor/interfaces/Viewable.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlayerActor<TMachine>(
+   machine,
+   catalog,
+   options,
+input?): PlayerActor<TMachine>;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L142)
+
+#### Parameters
+
+| Parameter | Type                                                             |
+| --------- | ---------------------------------------------------------------- |
+| `machine` | `TMachine`                                                       |
+| `catalog` | [`Catalog`](../type-aliases/Catalog.md) \| `null` \| `undefined` |
+| `options` | [`PlayerOptions`](../interfaces/PlayerOptions.md)\<`TMachine`\>  |
+| `input?`  | `InputFrom`\<`TMachine`\>                                        |
+
+#### Returns
+
+`PlayerActor`\<`TMachine`\>
+
+#### Overrides
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`constructor`](../../play-actor/classes/AbstractActor.md#constructor)
+
+## Properties
+
+| Property                                          | Modifier | Type                                                                                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Overrides                                                                                                                        | Inherited from                                                                                                                           | Defined in                                                                                                                                                                               |
+| ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-_parent"></a> `_parent?`          | `public` | `AnyActorRef`                                                                                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`_parent`](../../play-actor/classes/AbstractActor.md#property-_parent)     | node_modules/xstate/dist/declarations/src/createActor.d.ts:33                                                                                                                            |
+| <a id="property-catalog"></a> `catalog`           | `public` | [`Catalog`](../type-aliases/Catalog.md)                                                                                                     | 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-xstate/src/player-actor.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L140) |
+| <a id="property-clock"></a> `clock`               | `public` | `Clock`                                                                                                                                     | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`clock`](../../play-actor/classes/AbstractActor.md#property-clock)         | node_modules/xstate/dist/declarations/src/createActor.d.ts:25                                                                                                                            |
+| <a id="property-currentroute"></a> `currentRoute` | `public` | [`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-xstate/src/player-actor.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L138) |
+| <a id="property-currentview"></a> `currentView`   | `public` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`ViewMetadata`](../../play-actor/interfaces/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-xstate/src/player-actor.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L139) |
+| <a id="property-id"></a> `id`                     | `public` | `string`                                                                                                                                    | The unique identifier for this actor relative to its parent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`id`](../../play-actor/classes/AbstractActor.md#property-id)               | node_modules/xstate/dist/declarations/src/createActor.d.ts:28                                                                                                                            |
+| <a id="property-logic"></a> `logic`               | `public` | `AnyActorLogic`                                                                                                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`logic`](../../play-actor/classes/AbstractActor.md#property-logic)         | node_modules/xstate/dist/declarations/src/createActor.d.ts:18                                                                                                                            |
+| <a id="property-options"></a> `options`           | `public` | `Readonly`\<`ActorOptions`\<`TLogic`\>\>                                                                                                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`options`](../../play-actor/classes/AbstractActor.md#property-options)     | node_modules/xstate/dist/declarations/src/createActor.d.ts:26                                                                                                                            |
+| <a id="property-ref"></a> `ref`                   | `public` | `ActorRef`\<`any`, `any`, `any`\>                                                                                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`ref`](../../play-actor/classes/AbstractActor.md#property-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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`sessionId`](../../play-actor/classes/AbstractActor.md#property-sessionid) | node_modules/xstate/dist/declarations/src/createActor.d.ts:38                                                                                                                            |
+| <a id="property-src"></a> `src`                   | `public` | `string` \| `AnyActorLogic`                                                                                                                 | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`src`](../../play-actor/classes/AbstractActor.md#property-src)             | node_modules/xstate/dist/declarations/src/createActor.d.ts:42                                                                                                                            |
+| <a id="property-state"></a> `state`               | `public` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`AnyMachineSnapshot`\>                                                    | 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);` | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`state`](../../play-actor/classes/AbstractActor.md#property-state) | -                                                                                                                                        | [packages/play-xstate/src/player-actor.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L137) |
+| <a id="property-system"></a> `system`             | `public` | `AnyActorSystem`                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`system`](../../play-actor/classes/AbstractActor.md#property-system)       | node_modules/xstate/dist/declarations/src/createActor.d.ts:40                                                                                                                            |
+| <a id="property-systemid"></a> `systemId`         | `public` | `string` \| `undefined`                                                                                                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                | [`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`systemId`](../../play-actor/classes/AbstractActor.md#property-systemid)   | node_modules/xstate/dist/declarations/src/createActor.d.ts:36                                                                                                                            |
+
+## Methods
+
+### \[observable\]()
+
+```ts
+observable: InteropSubscribable<any>;
+```
+
+Defined in: node_modules/xstate/dist/declarations/src/createActor.d.ts:153
+
+#### Returns
+
+`InteropSubscribable`\<`any`\>
+
+#### Inherited from
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`[observable]`](../../play-actor/classes/AbstractActor.md#observable)
+
+---
+
+### dispose()
+
+```ts
+dispose(): void;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:434](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L434)
+
+Convenience dispose method for cleanup
+
+Per CONTEXT.md: "Both .dispose() convenience method and manual machine.stop()"
+
+#### Returns
+
+`void`
+
+---
+
+### 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
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`getPersistedSnapshot`](../../play-actor/classes/AbstractActor.md#getpersistedsnapshot)
+
+---
+
+### getSnapshot()
+
+```ts
+getSnapshot(): SnapshotFrom<TMachine>;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:307](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L307)
+
+Get current snapshot
+
+#### Returns
+
+`SnapshotFrom`\<`TMachine`\>
+
+#### Overrides
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`getSnapshot`](../../play-actor/classes/AbstractActor.md#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
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`on`](../../play-actor/classes/AbstractActor.md#on)
+
+---
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L282)
+
+Send event to actor
+
+Forwards events to the underlying XState actor. The actor's state machine
+guards determine whether each event is valid from the current state.
+
+#### Parameters
+
+| Parameter | Type                                                | Description                           |
+| --------- | --------------------------------------------------- | ------------------------------------- |
+| `event`   | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) | Any event object with a type property |
+
+#### Returns
+
+`void`
+
+#### Example
+
+```typescript
+// Domain event
+actor.send({ type: "auth.login", userId: "123" });
+
+// Routing event
+actor.send({ type: "play.route", to: "#home" });
+```
+
+#### Overrides
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`send`](../../play-actor/classes/AbstractActor.md#send)
+
+---
+
+### start()
+
+```ts
+start(): this;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L239)
+
+Start the actor
+
+Per RESEARCH.md Pitfall 1: Always call start() after creation
+
+#### Returns
+
+`this`
+
+#### Overrides
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`start`](../../play-actor/classes/AbstractActor.md#start)
+
+---
+
+### stop()
+
+```ts
+stop(): this;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:253](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/player-actor.ts#L253)
+
+Stop the actor and cleanup
+
+#### Returns
+
+`this`
+
+#### Overrides
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`stop`](../../play-actor/classes/AbstractActor.md#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`\<`any`\> | 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
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`subscribe`](../../play-actor/classes/AbstractActor.md#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
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`subscribe`](../../play-actor/classes/AbstractActor.md#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
+
+[`AbstractActor`](../../play-actor/classes/AbstractActor.md).[`toJSON`](../../play-actor/classes/AbstractActor.md#tojson)

package/api/@xmachines/play-xstate/functions/buildRouteUrl.md

@@ -0,0 +1,43 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / buildRouteUrl
+
+# Function: buildRouteUrl()
+
+```ts
+function buildRouteUrl(routeTemplate, context?): string;
+```
+
+Defined in: [packages/play-xstate/src/routing/build-url.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/build-url.ts#L28)
+
+Build full URL from route template and context
+
+Per CONTEXT.md:
+
+- "currentRoute derivation: Full URL generation including query params, hash, base path"
+- "Parameters: String template syntax — /user/:id"
+- "Inheritance: relative paths inherit parent route"
+
+Per RESEARCH.md Pattern 3: Replace :param with context values
+
+## Parameters
+
+| Parameter       | Type                                            | Description                                |
+| --------------- | ----------------------------------------------- | ------------------------------------------ |
+| `routeTemplate` | `string`                                        | Route path with :param placeholders        |
+| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Route context with parameters, query, hash |
+
+## Returns
+
+`string`
+
+Full URL string
+
+## Example
+
+```typescript
+const url = buildRouteUrl("/user/:id", {
+	id: "123",
+	query: { tab: "profile" },
+	hash: "section-1",
+});
+// Result: '/user/123?tab=profile#section-1'
+```

package/api/@xmachines/play-xstate/functions/composeGuards.md

@@ -0,0 +1,79 @@
+[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
+
+# Function: composeGuards()
+
+```ts
+function composeGuards<TContext, TEvent>(guards): ComposedGuard;
+```
+
+Defined in: [packages/play-xstate/src/guards/compose.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/guards/compose.ts#L72)
+
+Compose guards with AND logic using XState's and() helper
+
+Combines multiple guard predicates using AND semantics—all guards must pass for
+the composition to succeed. Uses XState's built-in `and()` helper to ensure proper
+type inference and machine serialization.
+
+**Architectural Context:** Supports **Actor Authority (INV-01)** by enabling
+declarative guard composition in state machine transitions. Guards enforce business
+logic rules that determine whether navigation or actions are valid.
+
+## Type Parameters
+
+| Type Parameter | Default type | Description                |
+| -------------- | ------------ | -------------------------- |
+| `TContext`     | `any`        | State machine context type |
+| `TEvent`       | `any`        | Event type                 |
+
+## Parameters
+
+| Parameter | Type                                                                  | Description                                                  |
+| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references) |
+
+## Returns
+
+[`ComposedGuard`](../type-aliases/ComposedGuard.md)
+
+XState and() guard composition
+
+## Throws
+
+If guards array is empty
+
+## Examples
+
+AND composition with named guards
+
+```typescript
+import { setup } from "xstate";
+import { composeGuards } from "@xmachines/play-xstate";
+
+const machine = setup({
+	guards: {
+		isLoggedIn: ({ context }) => !!context.userId,
+		hasPermission: ({ context }) => context.permissions.includes("admin"),
+	},
+}).createMachine({
+	on: {
+		accessAdmin: {
+			// Both guards must pass
+			guard: composeGuards(["isLoggedIn", "hasPermission"]),
+			target: "adminPanel",
+		},
+	},
+});
+```
+
+AND composition with inline predicates
+
+```typescript
+import { composeGuards } from "@xmachines/play-xstate";
+
+guard: composeGuards([({ context }) => context.age >= 18, ({ context }) => context.verified]);
+```
+
+## See
+
+- [composeGuardsOr](composeGuardsOr.md) for OR composition
+- [negateGuard](negateGuard.md) for NOT logic