@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -1,15 +1,145 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/docs
 
-This package contains the generated Typedoc documentation for the `xmachines-js` monorepo.
+> Documentation, guides, RFCs, and generated API reference for XMachines.
+
+Part of the `XMachines Play monorepo`.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.0.0--beta.51-blue)](https://www.npmjs.com/package/@xmachines/docs)
+
+## Overview
+
+`@xmachines/docs` is the documentation package for the XMachines Play monorepo. It ships five categories of content:
 
-The documentation is automatically built and published from the source code.
+| Location        | Contents                                                         |
+| --------------- | ---------------------------------------------------------------- |
+| `rfc/`          | Request-for-Comment specs that define the XMachines architecture |
+| `guides/`       | Concept guides, tutorials, and getting-started docs              |
+| `contributing/` | Operational docs for contributors and maintainers                |
+| `examples/`     | Runnable code examples and demo application references           |
+| `api/`          | TypeDoc-generated API reference for all public packages          |
+
+## Installation
+
+```bash
+pnpm add @xmachines/docs
+```
 
 ## Usage
 
-You can browse the documentation online at [https://xmachin.es/docs](https://xmachin.es/docs) (once published).
+### Import the package URL
+
+The package default export is its own module URL — useful for resolving doc assets at runtime:
+
+```typescript
+import docsUrl from "@xmachines/docs";
+// docsUrl is the resolved URL of the docs package entry point
+```
+
+### Access documentation files directly
+
+All documentation directories are exposed as package exports:
+
+```typescript
+// Access RFC files
+import playRfc from "@xmachines/docs/rfc/play.md";
+
+// Access guide files
+import gettingStarted from "@xmachines/docs/guides/getting-started.md";
+
+// Access example files
+import basicExample from "@xmachines/docs/examples/basic-state-machine.md";
+
+// Access API reference
+import apiDocs from "@xmachines/docs/api/README.md";
+```
+
+## Contents
+
+### RFCs
+
+Architectural specifications that define the XMachines system:
+
+| File                               | Title   | Description                                                          |
+| ---------------------------------- | ------- | -------------------------------------------------------------------- |
+| [`rfc/play.md`](rfc/play.md)       | Play    | Universal Player Architecture — core protocol, roles, and invariants |
+| [`rfc/streams.md`](rfc/streams.md) | Streams | WHATWG Streams as integration boundary                               |
+| [`rfc/broker.md`](rfc/broker.md)   | Broker  | Event broker specification                                           |
+| [`rfc/git.md`](rfc/git.md)         | Git     | Git-compatible ID and history model                                  |
+| [`rfc/run.md`](rfc/run.md)         | Run     | Runtime execution model                                              |
+| [`rfc/browser.md`](rfc/browser.md) | Browser | Browser environment adapter                                          |
+| [`rfc/node.md`](rfc/node.md)       | Node    | Node.js environment adapter                                          |
+| [`rfc/cli.md`](rfc/cli.md)         | CLI     | Command-line interface specification                                 |
+| [`rfc/rest.md`](rfc/rest.md)       | REST    | REST adapter specification                                           |
+| [`rfc/mcp.md`](rfc/mcp.md)         | MCP     | Model Context Protocol adapter                                       |
+
+### Guides
+
+Concept guides and tutorials for working with XMachines:
+
+**Learning:**
+
+- **[Getting Started](guides/getting-started.md)** — `setup().createMachine()` → `definePlayer()` → `actor.start()` → TC39 Signals
+- **[Understanding State Machines](guides/state-machines.md)** — `meta.route`, `meta.view`, and why machines replace boolean flags
+- **[Understanding the Actor Model](guides/actor-model.md)** — Actor/infrastructure split, `AbstractActor`, and the reset invariant
+- **[Understanding TC39 Signals](guides/signals.md)** — Signal primitives and the five architectural invariants they enforce
+
+### Contributing & Operations
+
+Reference documentation for contributors and maintainers:
+
+- **[Architecture](contributing/architecture.md)** — Package layers, data flows, key abstractions, TypeScript build graph
+- **[Development](contributing/development.md)** — Monorepo setup, build system, adding packages, code conventions
+- **[Configuration](contributing/configuration.md)** — TypeScript, linting, formatting, Vitest, CI/CD, and release configuration
+- **[Testing](contributing/testing.md)** — Vitest setup, node vs browser modes, test patterns, coverage requirements
+- **[Deployment](contributing/deployment.md)** — npm publishing, semantic-release process, GitLab CI pipeline
+
+### Examples
+
+Practical code examples demonstrating XMachines patterns:
+
+- **[Basic State Machine](examples/basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + TC39 Signals
+- **[Traffic Light](examples/traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
+- **[Form Validation](examples/form-validation.md)** — Typed context mutations with `setup.assign`, guards, and `$bindState`
+- **[Routing Patterns](examples/routing-patterns.md)** — `meta.route`, `play.route` events, `always` auth guards
+- **[Multi-Router Integration](examples/multi-router-integration.md)** — All 8 router adapters
+
+### API Reference
+
+TypeDoc-generated API reference for all public packages — see [`api/README.md`](api/README.md).
+
+Packages documented:
+
+- [`@xmachines/play`](../play/README.md) — Core protocols (`PlayEvent`, `PlayError`)
+- [`@xmachines/play-actor`](../play-actor/README.md) — `AbstractActor`, `Routable`, `Viewable`
+- [`@xmachines/play-signals`](../play-signals/README.md) — TC39 Signals polyfill, `watchSignal`
+- [`@xmachines/play-router`](../play-router/README.md) — `extractMachineRoutes`, `RouterBridgeBase`
+- [`@xmachines/play-xstate`](../play-xstate/README.md) — `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor`
+- [`@xmachines/play-dom`](../play-dom/README.md), [`play-react`](../play-react/README.md), [`play-solid`](../play-solid/README.md), [`play-svelte`](../play-svelte/README.md), [`play-vue`](../play-vue/README.md) — View renderers
+- [`@xmachines/play-dom-router`](../play-dom-router/README.md), [`play-tanstack-router`](../play-tanstack-router/README.md), [`play-react-router`](../play-react-router/README.md), [`play-tanstack-react-router`](../play-tanstack-react-router/README.md), [`play-solid-router`](../play-solid-router/README.md), [`play-tanstack-solid-router`](../play-tanstack-solid-router/README.md), [`play-vue-router`](../play-vue-router/README.md), [`play-svelte-spa-router`](../play-svelte-spa-router/README.md), [`play-sveltekit-router`](../play-sveltekit-router/README.md) — Router adapters
+
+## Testing
+
+Run the docs package tests in isolation:
+
+```bash
+# From the monorepo root
+pnpm --filter @xmachines/docs test
+
+# Or from within the package directory
+pnpm test
+```
+
+## Regenerating API Docs
+
+The `api/` directory is auto-generated by TypeDoc and must not be edited directly. Regenerate it from the monorepo root:
+
+```bash
+pnpm run docs
+```
 
-To build the documentation locally:
+## License
 
-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`.
+MIT — see [LICENSE](LICENSE).

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

@@ -1,75 +1,188 @@
-[Documentation](../../README.md) / @xmachines/play
+[API](../../README.md) / @xmachines/play
 
-# @xmachines/play
+<!-- generated-by: gsd-doc-writer -->
 
-**Protocol layer defining Actor ↔ Infrastructure event contracts for XMachines Play Architecture.**
+# `@xmachines/play`
 
-`@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.
+> Core protocol layer for the Universal Player Architecture — defines `PlayEvent`, `PlayError`, and architectural contracts enabling loose coupling between business logic and runtime adapters.
 
-## Overview
-
-This package exports protocol types only (no runtime behavior). It exists to preserve strict separation between:
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@xmachines/play)](https://www.npmjs.com/package/@xmachines/play)
 
-- **Actors** (business authority)
-- **Infrastructure adapters** (routers/renderers that observe and forward)
+Part of the [XMachines JS monorepo](../../README.md).
 
-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
+pnpm add @xmachines/play
 ```
 
-## API Surface
+> **Node.js `>= 22.0.0` required.** All packages are ES modules (`"type": "module"`).
 
-This package exports:
+---
 
-- `PlayEvent<TPayload>`
+## Overview
 
-`PlayEvent` is the minimal event shape:
+`@xmachines/play` is the foundational package in the XMachines ecosystem. It defines the minimal set of types and utilities that all other `@xmachines/*` packages build upon:
 
-```ts
-type PlayEvent<TPayload extends Record<string, any> = Record<string, any>> = {
-	readonly type: string;
-} & TPayload;
-```
+- **`PlayEvent<TPayload>`** — the universal event contract for Actor ↔ Infrastructure communication
+- **`PlayError`** — the typed base class for all `@xmachines/*` runtime errors
+- **`NonNullableError`** — thrown when a required value is `null` or `undefined`
+- **`assertNonNullable()`** — assertion utility that narrows `T | null | undefined` to `T`
+
+These protocols implement the architectural invariants defined in the Play RFC:
+
+| #      | Invariant                  | Description                                                        |
+| ------ | -------------------------- | ------------------------------------------------------------------ |
+| INV-01 | **Actor Authority**        | The Actor is the final authority; guards decide all transitions    |
+| INV-02 | **Strict Separation**      | Business logic never imports UI frameworks or routing libraries    |
+| INV-04 | **Passive Infrastructure** | Infrastructure observes Actor signals; it never enforces guards    |
+| INV-05 | **Signal-Only Reactivity** | TC39 Signals are the exclusive cross-boundary communication medium |
+
+---
 
 ## Usage
 
-### Base event usage
+### `PlayEvent<TPayload>`
+
+The minimal event contract: any object with a `type: string` property. Framework-agnostic — works with XState, Robot, and any other state machine library.
 
-```ts
+```typescript
 import type { PlayEvent } from "@xmachines/play";
 
-type LoginEvent = PlayEvent<{ userId: string }>;
+// Flexible (accepts any additional fields):
+const event: PlayEvent = { type: "auth.login", userId: "user123" };
+
+// Type-safe (with generic payload):
+type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
 
-const event: LoginEvent = {
+const loginEvent: LoginEvent = {
 	type: "auth.login",
-	userId: "user-123",
+	userId: "user123",
+	timestamp: Date.now(),
 };
+
+// TypeScript error: missing required field
+const invalid: LoginEvent = { type: "auth.login" }; // Error!
+```
+
+### `PlayError`
+
+Base class for all `@xmachines/*` runtime errors. Every error has a stable `scope` (throwing class/module) and `code` (machine-readable identifier). Always branch on `.code` or subclass — never on `.message`.
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { NonNullableError } from "@xmachines/play/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof NonNullableError) {
+		// err.scope === "assertNonNullable"
+		// err.code  === "PLAY_NON_NULLABLE"
+		console.error(`Missing value: ${err.message}`);
+	} else if (err instanceof PlayError) {
+		// Any other @xmachines/* error
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	} else {
+		throw err;
+	}
+}
+```
+
+Extend `PlayError` in your own `@xmachines/*`-compatible packages:
+
+```typescript
+import { PlayError } from "@xmachines/play";
+
+export class MyPackageError extends PlayError {
+	constructor(message: string, options?: ErrorOptions) {
+		super("MyScope", "MY_PACKAGE_ERROR_CODE", message, options);
+		this.name = "MyPackageError";
+	}
+}
+```
+
+### `assertNonNullable(value, name?)`
+
+Assertion utility that returns `value` typed as `NonNullable<V>` or throws `NonNullableError`. Eliminates unsafe `!` non-null assertions.
+
+```typescript
+import { assertNonNullable } from "@xmachines/play";
+
+// Inject + assert in one line — no intermediate variable or `!` needed:
+const actor = assertNonNullable(inject<AuthActor>("actor"), "actor");
+
+// DOM element lookup:
+const el = assertNonNullable(document.getElementById("app"), "#app");
+```
+
+---
+
+## API Summary
+
+### Exported from `@xmachines/play`
+
+| Export                | Kind       | Description                                                      |
+| --------------------- | ---------- | ---------------------------------------------------------------- |
+| `PlayEvent<TPayload>` | `type`     | Universal event contract — `{ type: string } & TPayload`         |
+| `PlayError`           | `class`    | Base class for all `@xmachines/*` typed errors                   |
+| `NonNullableError`    | `class`    | Thrown by `assertNonNullable` when a value is `null`/`undefined` |
+| `assertNonNullable`   | `function` | Asserts non-null, returns narrowed value                         |
+
+### Exported from `@xmachines/play/errors`
+
+| Export             | Kind    | Description                                               |
+| ------------------ | ------- | --------------------------------------------------------- |
+| `PlayError`        | `class` | Re-exported base error class                              |
+| `NonNullableError` | `class` | `scope: "assertNonNullable"`, `code: "PLAY_NON_NULLABLE"` |
+
+---
+
+## Error Codes
+
+| Code                | Class              | Thrown When                                          |
+| ------------------- | ------------------ | ---------------------------------------------------- |
+| `PLAY_NON_NULLABLE` | `NonNullableError` | `assertNonNullable()` receives `null` or `undefined` |
+
+Other `@xmachines/*` packages export their own error subclasses from their respective `./errors` subpath:
+
+| Package                      | Import path                         |
+| ---------------------------- | ----------------------------------- |
+| `@xmachines/play`            | `@xmachines/play/errors`            |
+| `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
+| `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
+| `@xmachines/play-react`      | `@xmachines/play-react/errors`      |
+| `@xmachines/play-solid`      | `@xmachines/play-solid/errors`      |
+| `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
+
+---
+
+## Testing
+
+Run tests for this package in isolation:
+
+```bash
+pnpm --filter @xmachines/play test
 ```
 
-## Architecture Notes
+Or from the package directory:
 
-- Keep `@xmachines/play` as the base protocol boundary.
-- Keep actor implementation details in adapter packages such as `@xmachines/play-xstate`.
+```bash
+pnpm test
+```
 
-## Related Packages
+Tests use **Vitest** and cover the `PlayError` class construction, inheritance, `cause` support, and subclassing patterns.
 
-- [@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.
+MIT © [Mikael Karon](mailto:mikael@karon.se)
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+See [LICENSE](./LICENSE) for details.
 
 @xmachines/play - Core Protocol Layer
 
@@ -125,6 +238,15 @@ These protocols enforce the following invariants:
 4. **Signal-Only Reactivity**: All state changes flow through TC39 Signals
 5. **State-Driven Reset**: Navigation follows state machine transition rules
 
+## Classes
+
+- [NonNullableError](classes/NonNullableError.md)
+- [PlayError](classes/PlayError.md)
+
 ## Type Aliases
 
 - [PlayEvent](type-aliases/PlayEvent.md)
+
+## Functions
+
+- [assertNonNullable](functions/assertNonNullable.md)

package/api/@xmachines/play/classes/NonNullableError.md

@@ -0,0 +1,189 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / NonNullableError
+
+# Class: NonNullableError
+
+Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play/src/errors.ts#L111)
+
+Thrown by [assertNonNullable](../functions/assertNonNullable.md) when a value is `null` or `undefined`.
+
+Catch this specifically to distinguish a missing-value assertion failure from
+other runtime errors:
+
+```ts
+import { NonNullableError } from "@xmachines/play/errors";
+
+try {
+	const actor = assertNonNullable(inject<AuthActor>("actor"), "actor");
+} catch (err) {
+	if (err instanceof NonNullableError) {
+		// err.name  === "NonNullableError"
+		// err.scope === "assertNonNullable"
+		// err.code  === "PLAY_NON_NULLABLE"
+	}
+}
+```
+
+## Extends
+
+- [`PlayError`](PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new NonNullableError(message, options?): NonNullableError;
+```
+
+Defined in: [packages/play/src/errors.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play/src/errors.ts#L112)
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `message`  | `string`       |
+| `options?` | `ErrorOptions` |
+
+#### Returns
+
+`NonNullableError`
+
+#### Overrides
+
+[`PlayError`](PlayError.md).[`constructor`](PlayError.md#constructor)
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                         | Defined in                                                                                                                 |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`cause`](PlayError.md#property-cause)                     | -                                                                                                                          |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | [`PlayError`](PlayError.md).[`code`](PlayError.md#property-code)                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play/src/errors.ts#L75) |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`message`](PlayError.md#property-message)                 | -                                                                                                                          |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`name`](PlayError.md#property-name)                       | -                                                                                                                          |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | [`PlayError`](PlayError.md).[`scope`](PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play/src/errors.ts#L66) |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`stack`](PlayError.md#property-stack)                     | -                                                                                                                          |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`PlayError`](PlayError.md).[`stackTraceLimit`](PlayError.md#property-stacktracelimit) | -                                                                                                                          |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: `@types/node`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack; // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+	b();
+}
+
+function b() {
+	c();
+}
+
+function c() {
+	// Create an error without stack trace to avoid calculating the stack trace twice.
+	const { stackTraceLimit } = Error;
+	Error.stackTraceLimit = 0;
+	const error = new Error();
+	Error.stackTraceLimit = stackTraceLimit;
+
+	// Capture the stack trace above function b
+	Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+	throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`PlayError`](PlayError.md).[`captureStackTrace`](PlayError.md#capturestacktrace)
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Defined in: `typescript`
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+[`PlayError`](PlayError.md).[`isError`](PlayError.md#iserror)
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: `@types/node`
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`PlayError`](PlayError.md).[`prepareStackTrace`](PlayError.md#preparestacktrace)