@xmachines/docs 1.0.0-beta.15 → 1.0.0-beta.17

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

@@ -4,11 +4,13 @@
 
 **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.
+`@xmachines/play` is intentionally small. It provides the base event type and the base error
+class used across all adapters and actor implementations, while keeping framework and runtime
+concerns out of business logic.
 
 ## Overview
 
-This package exports protocol types only (no runtime behavior). It exists to preserve strict separation between:
+This package exports the shared Play protocol surface. It exists to preserve strict separation between:
 
 - **Actors** (business authority)
 - **Infrastructure adapters** (routers/renderers that observe and forward)
@@ -29,40 +31,73 @@ npm install @xmachines/play
 
 This package exports:
 
-- `PlayEvent<TPayload>`
+| Export      | Type  | Purpose                                           |
+| ----------- | ----- | ------------------------------------------------- |
+| `PlayEvent` | type  | Minimal event shape — `{ type: string, ...rest }` |
+| `PlayError` | class | Base class for all `@xmachines/*` typed errors    |
 
-`PlayEvent` is the minimal event shape:
+### `PlayEvent`
 
-```ts
-type PlayEvent<TPayload extends Record<string, any> = Record<string, any>> = {
-	readonly type: string;
-} & TPayload;
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+
+// Flexible (default):
+const event: PlayEvent = { type: "auth.login", userId: "123" };
+
+// Type-safe (with generic):
+type LoginEvent = PlayEvent<{ userId: string }>;
+const login: LoginEvent = { type: "auth.login", userId: "123" };
 ```
 
-## Usage
+### `PlayError`
 
-### Base event usage
+Base class for all typed runtime errors thrown by `@xmachines/*` packages.
 
-```ts
-import type { PlayEvent } from "@xmachines/play";
+Every `PlayError` carries two structured fields:
 
-type LoginEvent = PlayEvent<{ userId: string }>;
+- **`scope`** — the class or module that threw (e.g. `"RouterBridgeBase"`)
+- **`code`** — a stable, machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
 
-const event: LoginEvent = {
-	type: "auth.login",
-	userId: "user-123",
-};
+```typescript
+import { PlayError } from "@xmachines/play";
+
+// Catching any @xmachines/* error:
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof PlayError) {
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	}
+}
 ```
 
+Package-specific subclasses are exported from each package's `./errors` subpath:
+
+```typescript
+import { RouterSyncError } from "@xmachines/play-router/errors";
+import { InvalidEventError, MissingRouteParamError } from "@xmachines/play-xstate/errors";
+import {
+	MissingCatalogError,
+	MissingComponentError,
+	RendererError,
+} from "@xmachines/play-react/errors";
+import { MissingCatalogError, MissingComponentError } from "@xmachines/play-solid/errors";
+import { VueRouterCorrectionError } from "@xmachines/play-vue-router/errors";
+```
+
+See each package's README for the full list of error classes and when they are thrown.
+
 ## Architecture Notes
 
 - Keep `@xmachines/play` as the base protocol boundary.
 - Keep actor implementation details in adapter packages such as `@xmachines/play-xstate`.
+- Never match on `.message` strings — always match on `instanceof` or `.code`.
 
 ## Related Packages
 
 - [@xmachines/play-actor](../play-actor/README.md)
 - [@xmachines/play-xstate](../play-xstate/README.md)
+- [@xmachines/play-router](../play-router/README.md)
 
 ## License
 
@@ -125,6 +160,10 @@ 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
+
+- [PlayError](classes/PlayError.md)
+
 ## Type Aliases
 
 - [PlayEvent](type-aliases/PlayEvent.md)

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

@@ -0,0 +1,240 @@
+[Documentation](../../../README.md) / [@xmachines/play](../README.md) / PlayError
+
+# Class: PlayError
+
+Defined in: [packages/play/src/errors.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play/src/errors.ts#L63)
+
+Base class for all typed runtime errors thrown by `@xmachines/*` packages.
+
+`PlayError` gives every error two structured fields:
+
+- `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
+- `code` — a stable, machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
+
+These fields let application code branch on error type without parsing `.message`
+strings, which change across releases.
+
+## Error codes
+
+Each `@xmachines/*` package exports its own typed subclasses from an
+`"./errors"` subpath:
+
+| Package                      | Import                              |
+| ---------------------------- | ----------------------------------- |
+| `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
+| `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
+| `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
+| `@xmachines/play-react`      | `@xmachines/play-react/errors`      |
+| `@xmachines/play-solid`      | `@xmachines/play-solid/errors`      |
+
+`PlayError` itself is exported from the root `@xmachines/play` and is the base
+for all of those subclasses.
+
+## Catching errors by type
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { RouterSyncError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof RouterSyncError) {
+		// err.scope === "RouterBridgeBase"
+		// err.code  === "PLAY_ROUTER_SYNC_FAILED"
+		// err.cause  — the original error that triggered the sync failure
+		reportToMonitoring(err);
+	} else if (err instanceof PlayError) {
+		// Any other @xmachines/* error
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	} else {
+		throw err; // Re-throw unknown errors
+	}
+}
+```
+
+## Extending PlayError
+
+```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";
+	}
+}
+```
+
+## Extends
+
+- `Error`
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlayError(
+   scope,
+   code,
+   message,
+   options?): PlayError;
+```
+
+Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play/src/errors.ts#L82)
+
+#### Parameters
+
+| Parameter  | Type           | Description                                                               |
+| ---------- | -------------- | ------------------------------------------------------------------------- |
+| `scope`    | `string`       | The class or module throwing this error.                                  |
+| `code`     | `string`       | Machine-readable error identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`).     |
+| `message`  | `string`       | Human-readable description. Do not match on this in code.                 |
+| `options?` | `ErrorOptions` | Standard `ErrorOptions`; pass `{ cause: originalError }` to chain errors. |
+
+#### Returns
+
+`PlayError`
+
+#### Overrides
+
+```ts
+Error.constructor;
+```
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from          | Defined in                                                                                                                         |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.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.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play/src/errors.ts#L74) |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.message`         | -                                                                                                                                  |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.name`            | -                                                                                                                                  |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play/src/errors.ts#L65) |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.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. | `Error.stackTraceLimit` | -                                                                                                                                  |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+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
+
+```ts
+Error.captureStackTrace;
+```
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+```ts
+Error.isError;
+```
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+```ts
+Error.prepareStackTrace;
+```

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

@@ -6,7 +6,7 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play/src/types.ts#L69)
+Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play/src/types.ts#L69)
 
 Generic event type for Play Architecture
 
@@ -32,9 +32,9 @@ Robot, and other state machine libraries.
 
 ## Type Declaration
 
-| Name   | Type     | Defined in                                                                                                     |
-| ------ | -------- | -------------------------------------------------------------------------------------------------------------- |
-| `type` | `string` | [types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play/src/types.ts#L70) |
+| Name   | Type     | Defined in                                                                                                                       |
+| ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play/src/types.ts#L70) |
 
 ## Type Parameters
 

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

@@ -30,6 +30,7 @@ npm install @xmachines/play-actor
 - `AbstractActor`
 - `Routable` (type)
 - `Viewable` (type)
+- `ViewMetadata` (type)
 
 **Peer dependencies:**
 
@@ -45,7 +46,7 @@ npm install @xmachines/play-actor
 import { definePlayer } from "@xmachines/play-xstate";
 
 // definePlayer returns PlayerActor (extends AbstractActor)
-const createPlayer = definePlayer({ machine, catalog });
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start();
 
@@ -73,8 +74,7 @@ Implement `Routable` to add routing support:
 
 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
+- `currentView: Signal.State<ViewMetadata | null>` - Current view spec (updated on every state transition). `ViewMetadata` has the shape `{ component: string; spec: Spec }` where `spec` is a `@json-render/core` spec object driving the renderer.
 
 **Inherited from XState Actor:**
 
@@ -86,39 +86,39 @@ Implement `Viewable` to add view rendering support:
 **Example implementation pattern:**
 
 ```typescript
-import { AbstractActor, type Routable, type Viewable, type ViewMetadata } from "@xmachines/play-actor";
+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
+	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...
-        });
-    }
-}
+	// 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 view spec — Signal.State, updated on every state transition
+	currentView = new Signal.State<ViewMetadata | null>(null);
+
+	constructor(logic: TLogic) {
+		super(logic);
+
+		// Subscribe to XState transitions and update signals
+		this.subscribe((snapshot) => {
+			this.state.set(snapshot as AnyMachineSnapshot);
+			// Derive currentView from snapshot meta and update the signal...
+		});
+	}
 }
 ```
 
@@ -242,6 +242,7 @@ reactive signals for Infrastructure layer communication.
 
 ## Interfaces
 
+- [PlaySpec](interfaces/PlaySpec.md)
 - [Routable](interfaces/Routable.md)
 - [Viewable](interfaces/Viewable.md)
 - [ViewMetadata](interfaces/ViewMetadata.md)