@xmachines/docs 1.0.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @xmachines/docs
+
+This package contains the generated Typedoc documentation for the `xmachines-js` monorepo.
+
+The documentation is automatically built and published from the source code.
+
+## Usage
+
+You can browse the documentation online at [https://xmachin.es/docs](https://xmachin.es/docs) (once published).
+
+To build the documentation locally:
+
+1. Clone the `xmachines-js` monorepo.
+2. Run `npm install` in the root directory.
+3. Run `npm run docs` to generate the documentation into `packages/docs/api`.

package/api/@xmachines/play/README.md

@@ -0,0 +1,130 @@
+[Documentation](../../README.md) / @xmachines/play
+
+# @xmachines/play
+
+**Protocol layer defining Actor ↔ Infrastructure event contracts for XMachines Play Architecture.**
+
+`@xmachines/play` is intentionally small. It provides the base event contract used across adapters and actor implementations while keeping framework/runtime concerns out of business logic.
+
+## Overview
+
+This package exports protocol types only (no runtime behavior). It exists to preserve strict separation between:
+
+- **Actors** (business authority)
+- **Infrastructure adapters** (routers/renderers that observe and forward)
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package supports:
+
+- **Actor Authority (INV-01):** infrastructure proposes intents, actor decides validity
+- **Strict Separation (INV-02):** protocol types are framework-agnostic
+- **Passive Infrastructure (INV-04):** adapters reflect actor decisions
+
+## Installation
+
+```bash
+npm install @xmachines/play
+```
+
+## API Surface
+
+This package exports:
+
+- `PlayEvent<TPayload>`
+
+`PlayEvent` is the minimal event shape:
+
+```ts
+type PlayEvent<TPayload extends Record<string, any> = Record<string, any>> = {
+	readonly type: string;
+} & TPayload;
+```
+
+## Usage
+
+### Base event usage
+
+```ts
+import type { PlayEvent } from "@xmachines/play";
+
+type LoginEvent = PlayEvent<{ userId: string }>;
+
+const event: LoginEvent = {
+	type: "auth.login",
+	userId: "user-123",
+};
+```
+
+## Architecture Notes
+
+- Keep `@xmachines/play` as the base protocol boundary.
+- Keep actor implementation details in adapter packages such as `@xmachines/play-xstate`.
+
+## Related Packages
+
+- [@xmachines/play-actor](../play-actor/README.md)
+- [@xmachines/play-xstate](../play-xstate/README.md)
+
+## License
+
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.
+
+@xmachines/play - Core Protocol Layer
+
+Defines architectural contracts enabling Actor ↔ Infrastructure communication
+without direct dependencies. Per RFC section 5.2, these protocols establish
+the foundation for loose coupling between business logic and runtime adapters.
+
+## Exports
+
+**PlayEvent<TPayload>** - Generic event type for Actor communication
+
+- Any object with a `type: string` property
+- Generic `TPayload` parameter for type-safe event shapes (optional)
+- Defaults to `Record<string, unknown>` for maximum flexibility
+- Framework-agnostic (not tied to XState or any specific library)
+
+**Usage:**
+
+```typescript
+// Flexible (default):
+const event: PlayEvent = { type: "auth.login", userId: "123" };
+
+// Type-safe (with generic):
+type LoginEvent = PlayEvent<{ userId: string }>;
+const event: LoginEvent = { type: "auth.login", userId: "123" };
+```
+
+**Common Event Patterns:**
+
+- Domain events: `{ type: 'auth.login', userId: '123' }`
+- Custom events: `{ type: 'form.submit', data: {...} }`
+
+**Routing Events** are provided by @xmachines/play-router:
+
+- PlayRouteEvent: Enhanced routing with parameters and state ID targeting
+- RouterBridge: Protocol for router adapters to connect with actors
+
+**Browser Navigation:** Browser back/forward buttons are handled by router adapters
+via the `popstate` event. When users press back/forward, the router detects the URL
+change and sends a PlayRouteEvent to the actor for validation.
+
+```typescript
+import type { PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
+```
+
+## Architectural Invariants
+
+These protocols enforce the following invariants:
+
+1. **Actor Authority**: Infrastructure proposes intents, Actor decides validity
+2. **Strict Separation**: No direct dependencies between layers
+3. **Passive Infrastructure**: Infrastructure observes Actor signals, never controls
+4. **Signal-Only Reactivity**: All state changes flow through TC39 Signals
+5. **State-Driven Reset**: Navigation follows state machine transition rules
+
+## Type Aliases
+
+- [PlayEvent](type-aliases/PlayEvent.md)

package/api/@xmachines/play/type-aliases/PlayEvent.md

@@ -0,0 +1,81 @@
+[Documentation](../../../README.md) / [@xmachines/play](../README.md) / PlayEvent
+
+# Type Alias: PlayEvent\<TPayload\>
+
+```ts
+type PlayEvent<TPayload> = object & TPayload;
+```
+
+Defined in: [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play/src/types.ts#L69)
+
+Generic event type for Play Architecture
+
+PlayEvent represents the minimal event contract for Actor communication: any object
+with a `type` string property. Infrastructure forwards events to the Actor, and the
+Actor's state machine guards determine validity.
+
+**Type Parameter:** The generic `TPayload` allows specifying the shape of additional
+event fields beyond `type`. It defaults to `Record<string, unknown>` for maximum flexibility.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** where
+infrastructure reflects user actions as events without making decisions. The Actor's
+state machine guards determine whether each event is valid from the current state.
+
+**Framework Agnostic:** This type is intentionally generic and not tied to any
+specific state machine framework. It matches the common event shape used by XState,
+Robot, and other state machine libraries.
+
+**Common Event Types:**
+
+- Domain events: `{ type: 'auth.login', userId: '123' }`
+- Custom events: `{ type: 'form.submit', data: {...} }`
+
+## Type Declaration
+
+| Name   | Type     | Defined in                                                                                                                               |
+| ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` | `string` | [types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play/src/types.ts#L70) |
+
+## Type Parameters
+
+| Type Parameter                                       | Default type                    | Description                                                             |
+| ---------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
+| `TPayload` _extends_ `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> | Additional fields beyond `type` (defaults to `Record<string, unknown>`) |
+
+## Examples
+
+Using without type parameter (flexible)
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+
+// Accepts any event with type: string
+const loginEvent: PlayEvent = {
+	type: "auth.login",
+	userId: "user123",
+	timestamp: Date.now(),
+};
+actor.send(loginEvent);
+```
+
+Using with type parameter (type-safe)
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+
+// Type-safe event with known shape
+type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
+
+const loginEvent: LoginEvent = {
+	type: "auth.login",
+	userId: "user123",
+	timestamp: Date.now(),
+};
+
+// TypeScript error: missing required field
+const invalid: LoginEvent = { type: "auth.login" }; // Error!
+```
+
+## See
+
+[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)

package/api/@xmachines/play-actor/README.md

@@ -0,0 +1,247 @@
+[Documentation](../../README.md) / @xmachines/play-actor
+
+# @xmachines/play-actor
+
+**Abstract Actor base class with signal protocol for XMachines Play Architecture**
+
+Foundation for all actor implementations, enforcing XState compatibility and reactive signal contracts.
+
+## Overview
+
+`@xmachines/play-actor` provides `AbstractActor`, a base class that extends XState's `Actor` while enforcing the Play Architecture's signal protocol. It maintains XState ecosystem compatibility (inspection tools, devtools) while exposing reactive signals for infrastructure layer communication.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+
+- **Actor Authority (INV-01):** Actor is sole source of truth for state transitions
+- **Signal-Only Reactivity (INV-05):** Infrastructure observes via TC39 Signals, never directly queries
+- **Passive Infrastructure (INV-04):** Infrastructure reflects, never decides
+
+**Note:** This is an abstract base class. Concrete implementations are provided by adapters (see [@xmachines/play-xstate](../play-xstate/README.md)).
+
+## Installation
+
+```bash
+npm install xstate@^5.0.0
+npm install @xmachines/play-actor
+```
+
+## Current Exports
+
+- `AbstractActor`
+- `Routable` (type)
+- `Viewable` (type)
+
+**Peer dependencies:**
+
+- `xstate` ^5.0.0 — State machine runtime (XState compatibility)
+- `@xmachines/play-signals` - TC39 Signals primitives
+- `@xmachines/play` - Protocol types (PlayEvent, etc.)
+
+## Quick Start
+
+**Usage:** This is an abstract base class — use concrete implementations:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+
+// definePlayer returns PlayerActor (extends AbstractActor)
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+actor.start();
+
+// Signal protocol properties (from AbstractActor)
+console.log(actor.state.get()); // Current snapshot
+console.log(actor.currentRoute.get()); // Derived route
+console.log(actor.currentView.get()); // Derived view structure
+```
+
+## API Reference
+
+### AbstractActor<TLogic>
+
+Abstract base class defining signal protocol:
+
+**Abstract Properties (must implement):**
+
+- `state: Signal.State<unknown>` - Reactive snapshot of current state
+
+**Optional capability interfaces:**
+
+Implement `Routable` to add routing support:
+
+- `currentRoute: Signal.Computed<string | null>` - Derived navigation path
+
+Implement `Viewable` to add view rendering support:
+
+- `currentView: Signal.State<ViewMetadata | null>` - Current UI structure (updated at state entry)
+- `catalog: Record<string, unknown>` - Component catalog
+
+**Inherited from XState Actor:**
+
+- `send(event): void` - Send event to actor
+- `start(): void` - Start the actor
+- `stop(): void` - Stop the actor
+- `getSnapshot()` - Get current XState snapshot (typed as `SnapshotFrom<TLogic>`)
+
+**Example implementation pattern:**
+
+```typescript
+import { AbstractActor, type Routable, type Viewable, type ViewMetadata } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+import type { AnyActorLogic, AnyMachineSnapshot } from "xstate";
+
+class PlayerActor<TLogic extends AnyActorLogic>
+    extends AbstractActor<TLogic>
+    implements Routable, Viewable
+{
+    // Required: reactive state snapshot
+    state = new Signal.State<AnyMachineSnapshot>(this.getSnapshot() as AnyMachineSnapshot);
+
+    // Routable: derived navigation path
+    currentRoute = new Signal.Computed(() => {
+        return deriveRoute(this.state.get());
+    });
+
+    // Viewable: current UI structure — Signal.State, updated at state entry (not computed)
+    currentView = new Signal.State<ViewMetadata | null>(null);
+
+    // Viewable: component catalog
+    catalog: Record<string, unknown>;
+
+    constructor(logic: TLogic, catalog: Record<string, unknown>) {
+        super(logic);
+        this.catalog = catalog;
+
+        // Subscribe to XState transitions and update signals
+        this.subscribe((snapshot) => {
+            this.state.set(snapshot as AnyMachineSnapshot);
+            // Update currentView based on snapshot meta...
+        });
+    }
+}
+}
+```
+
+## Examples
+
+### Infrastructure Observing Signals
+
+```typescript
+import { AbstractActor } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+
+function syncUrlToActor(actor: AbstractActor<any>) {
+	// Infrastructure passively observes actor's route signal
+	const watcher = new Signal.subtle.Watcher(() => {
+		queueMicrotask(() => {
+			const pending = watcher.getPending();
+			if (pending.length > 0) {
+				const route = actor.currentRoute.get();
+				if (route !== null) {
+					// Update browser URL (Passive Infrastructure)
+					window.history.replaceState(null, "", route);
+				}
+				watcher.watch(...pending); // Re-watch
+			}
+		});
+	});
+
+	watcher.watch(actor.currentRoute);
+	actor.currentRoute.get(); // Initial read
+
+	return () => watcher.unwatch(actor.currentRoute);
+}
+```
+
+### Browser Navigation Sending Events
+
+```typescript
+import { AbstractActor } from "@xmachines/play-actor";
+
+function connectBrowserNavigation(actor: AbstractActor<any>) {
+	const handlePopstate = () => {
+		const path = window.location.pathname;
+
+		// Browser event sent to actor (Actor Authority)
+		// Actor guards decide if navigation is valid
+		actor.send({ type: "play.route", to: path });
+	};
+
+	window.addEventListener("popstate", handlePopstate);
+
+	return () => {
+		window.removeEventListener("popstate", handlePopstate);
+	};
+}
+```
+
+## Architecture
+
+This base class enforces three architectural invariants:
+
+1. **Actor Authority (INV-01):**
+    - Actor decides all state transitions via guards
+    - Infrastructure sends events, actor validates and processes
+    - Actor's decision is final — no override by infrastructure
+
+2. **Signal-Only Reactivity (INV-05):**
+    - All reactive state exposed via TC39 Signals
+    - Infrastructure uses `Signal.subtle.Watcher` to observe
+    - No direct queries (`getSnapshot()` for internal use only)
+
+3. **Passive Infrastructure (INV-04):**
+    - Infrastructure reflects actor state (via signals)
+    - Infrastructure never decides transitions
+    - Browser/router events sent as commands to actor
+
+## XState Compatibility
+
+`AbstractActor` extends XState's `Actor<TLogic>` to maintain:
+
+- **Type Safety:** Generic `TLogic extends AnyActorLogic` parameter
+- **Inspection API:** XState Inspector can attach to actors
+- **DevTools Integration:** Standard XState devtools work
+- **Ecosystem Tools:** Works with XState visualization, testing libraries
+
+**Snapshot Format:** Standard XState snapshots (state + context) remain unchanged — signals are accessible via actor properties, not snapshots.
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate/README.md)** - Concrete PlayerActor implementation
+- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
+- **[@xmachines/play](../play/README.md)** - Protocol types (PlayEvent, RouterBridge)
+
+## License
+
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.
+
+@xmachines/play-actor - Abstract Actor base class for Play Architecture
+
+This package provides AbstractActor, a minimal base class that extends XState Actor
+while enforcing the Play Architecture's signal protocol (RFC section 5.3).
+
+The core protocol is minimal (state + send). Optional capabilities are provided
+via interfaces:
+
+- Routable: For actors that support routing
+- Viewable: For actors that support view rendering
+
+Maintains XState ecosystem compatibility (inspection, devtools) while exposing
+reactive signals for Infrastructure layer communication.
+
+## See
+
+[RFC Play v1 Section 5.3](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md#53-actor-protocol)
+
+## Classes
+
+- [AbstractActor](classes/AbstractActor.md)
+
+## Interfaces
+
+- [Routable](interfaces/Routable.md)
+- [Viewable](interfaces/Viewable.md)
+- [ViewMetadata](interfaces/ViewMetadata.md)