@xmachines/docs 1.1.0 → 2.0.0

package/examples/@xmachines/play-vue-demo/README.md

@@ -1,11 +1,11 @@
 [Examples](../../README.md) / @xmachines/play-vue-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-vue-demo
 
 Vue 3 renderer demo for [`@xmachines/play-vue`](../../../api/@xmachines/play-vue/README.md) — actor + `PlayRenderer` without a router.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic

package/examples/@xmachines/play-vue-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-vue/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-vue-demo/variables/App.md

@@ -6,4 +6,4 @@
 const App: DefineComponent<{}, {}, unknown>;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-vue/examples/demo/src/env.d.ts#L5)
+Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/env.d.ts#L5)

package/examples/@xmachines/play-vue-demo/variables/authCatalog.md

@@ -169,4 +169,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-vue/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-vue-router-demo/README.md

@@ -1,11 +1,11 @@
 [Examples](../../README.md) / @xmachines/play-vue-router-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-vue-router-demo
 
 Vue Router integration demo for the XMachines Play architecture using Vue Composition API.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic

package/examples/README.md

@@ -23,6 +23,8 @@ Learn how state machines control navigation:
 
 Complete working implementations of actor-authoritative routing with all architectural invariants enforced.
 
+Every demo below also wires the [Stately inspector](../guides/inspector.md): the debug panel's **Show Inspector** button opens the live machine — history replayed — in its own window.
+
 ## Complete Demo Applications
 
 ### Renderer Demos
@@ -107,5 +109,6 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 ## Related Documentation
 
 - **[Getting Started](../guides/getting-started.md)** — Installation, first actor, routing, and view renderer setup
+- **[Inspecting a Running Actor](../guides/inspector.md)** — Attaching the Stately inspector to a `PlayerActor`, in the browser and out of it
 - **[API Reference](../api/README.md)** — Generated API docs for all public packages
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/examples/form-validation.md

@@ -304,5 +304,5 @@ window.addEventListener("beforeunload", () => {
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
-- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, `$state`, and `contextProps`
+- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
 - **[`@xmachines/play-router`](../api/@xmachines/play-router/README.md)** — Route extraction and tree building

package/guides/README.md

@@ -13,3 +13,9 @@ Background reading that explains the _why_ behind XMachines design decisions.
 - **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags and component-level routing logic
 - **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
 - **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the architectural invariants they enforce
+
+## Tooling
+
+Working with a running actor.
+
+- **[Inspecting a Running Actor](inspector.md)** — Attaching the Stately inspector via `PlayerOptions.inspect`, reading inspection events, enabling an inspector after startup, and inspecting without a browser

package/guides/actor-model.md

@@ -91,7 +91,7 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
 
-- XState's inspection API works (`@xstate/inspect`)
+- XState's inspection API works ([`@statelyai/inspect`](https://stately.ai/docs/inspector) — see [Inspecting a Running Actor](inspector.md))
 - XState DevTools attach to actors normally
 - The full XState ecosystem (testing utilities, visualization) is compatible
 

package/guides/getting-started.md

@@ -151,10 +151,10 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 
 #### Step 1: Install the core packages
 
-Every XMachines application needs these three packages plus XState:
+Every XMachines application needs these four packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/json-render-core
 ```
 
 | Package                                                               | Role                                                                                                                                                                |
@@ -163,6 +163,7 @@ pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-sig
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                       |
 | [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                 |
+| `@xmachines/json-render-core`                                         | Spec and store types the actor layer builds on — a peer of `@xmachines/play-actor`, and of every renderer package                                                   |
 
 #### Step 2: Install a router adapter (pick one)
 
@@ -706,6 +707,7 @@ node --version
 
 ## Next Steps
 
+- **[Inspecting a Running Actor](inspector.md)** — Attaching the Stately inspector to see the machine, its transitions, and its context live
 - **[Architecture](../contributing/architecture.md)** — System design, layers, invariants, and data flow
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification
 - **[API Reference](../api/README.md)** — Auto-generated API docs for all packages

package/guides/inspector.md

@@ -0,0 +1,197 @@
+# Inspecting a Running Actor
+
+A `PlayerActor` is an XState actor, so every XState inspection tool works on it unchanged. This guide covers how to attach an inspector, what the events look like once they arrive, and the two things that are specific to XMachines: the actor _is_ the actor an inspector sees, and the observer is configured on the factory rather than on each instance.
+
+After reading this you will be able to open the [Stately inspector](https://stately.ai/docs/inspector) against a running demo or your own app, inspect an actor that has no browser around it, and wire an inspector that can be turned on after the actor has already started.
+
+- [Quick start](#quick-start) — three lines to a live inspector
+- [Where the observer attaches](#where-the-observer-attaches) — factory-level, creation-time
+- [Reading the events](#reading-the-events) — identity, `rootId`, the construction caveat
+- [Turning the inspector on later](#turning-the-inspector-on-later) — dev-tools toggles and replay
+- [Inspecting without a browser](#inspecting-without-a-browser) — WebSocket transport, Node and SSR
+- [Trying it in the demos](#trying-it-in-the-demos) — the shared demo controller
+- [Production considerations](#production-considerations) — cost and data exposure
+
+---
+
+## Quick start
+
+Install the inspect client alongside your existing XState dependency:
+
+```bash
+pnpm add -D @statelyai/inspect
+```
+
+Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md):
+
+```typescript
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import { appMachine } from "./machine.js";
+
+const { inspect } = createBrowserInspector();
+
+const createPlayer = definePlayer({
+	machine: appMachine,
+	options: { inspect },
+});
+
+const actor = createPlayer();
+actor.start();
+```
+
+`createBrowserInspector()` opens Stately's hosted inspector in a new tab and streams the actor's events to it. From there the machine draws itself, every transition animates, and the context is readable at each step.
+
+That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md) is forwarded verbatim to XState's `createActor`, so anything XState accepts there is accepted here — a function, or an observer object with a `next` method:
+
+```typescript
+// Function form — the common case
+definePlayer({ machine, options: { inspect: (event) => console.log(event.type) } });
+
+// Observer form — also forwarded as-is
+definePlayer({ machine, options: { inspect: { next: (event) => sink.write(event) } } });
+```
+
+---
+
+## Where the observer attaches
+
+Two properties of the attachment point matter in practice.
+
+**It is configured on the factory, not on the instance.** `definePlayer({ machine, options })` returns a factory; `options.inspect` belongs to that configuration, and every actor the factory creates reports to the same observer. The factory's per-call options bag carries `snapshot` for restoring persisted state and nothing else — there is no per-instance `inspect` override. When one factory produces several live actors (multi-user scenarios, SSR, tests), demultiplex the stream by root instead:
+
+```typescript
+const createPlayer = definePlayer({ machine, options: { inspect } });
+
+const alice = createPlayer({ userId: "alice" });
+const bob = createPlayer({ userId: "bob" });
+
+// Events from alice's tree, children included
+const forAlice = (event: InspectionEvent) => event.rootId === alice.sessionId;
+```
+
+**It is the only route that sees construction.** Attaching after the fact with `actor.system.inspect(fn)` works and needs no factory changes, but it only receives events from the moment it subscribes — the `@xstate.actor` registration event has already fired by then, and an inspector that never receives it has no machine to draw. Use `options.inspect` when you want the full history; use `actor.system.inspect(fn)` when you only care about what happens next.
+
+---
+
+## Reading the events
+
+Because a `PlayerActor` _is_ the XState actor rather than a wrapper around a hidden one, the events name it directly:
+
+- `event.actorRef === actor` for the player's own events — recognise a player by identity, no bookkeeping required.
+- `event.rootId === actor.sessionId` for the whole tree, including invoked and spawned children, whose `actorRef` is the child rather than the player.
+
+The event types are XState's: `@xstate.actor` when an actor registers, `@xstate.event` when an event is sent, `@xstate.snapshot` after a transition, `@xstate.action` for executed actions, and `@xstate.microstep` for intermediate steps.
+
+### The construction caveat
+
+`@xstate.actor` fires from _inside_ the actor's constructor. The `actorRef` it carries is a real `PlayerActor`, but a mid-construction one: `state`, `currentRoute`, `currentView` and `initialRoute` do not exist yet, and reading them there throws — XState itself refuses to read a snapshot in that window.
+
+```typescript
+const inspect = (event: InspectionEvent) => {
+	if (event.type === "@xstate.actor") {
+		// ❌ throws — the signals are not assigned yet
+		console.log(event.actorRef.currentRoute.get());
+	}
+	if (event.type === "@xstate.snapshot") {
+		// ✅ construction has returned; signals are live
+		console.log(event.actorRef.getSnapshot().value);
+	}
+};
+```
+
+Capture the reference during construction if you need it, and read the signals from a later event or from outside the observer entirely.
+
+---
+
+## Turning the inspector on later
+
+An inspector that is only created when the user asks for it — a dev-tools toggle, a keyboard shortcut, a debug panel button — cannot be passed to `definePlayer`, which ran at module scope long before the click. Pass a forwarding function instead, so the attachment point is fixed at factory time while the destination stays swappable:
+
+```typescript
+let current: ((event: InspectionEvent) => void) | undefined;
+
+const createPlayer = definePlayer({
+	machine: appMachine,
+	options: { inspect: (event) => current?.(event) },
+});
+
+// Later, from a click handler
+export function enableInspector() {
+	const { inspect } = createBrowserInspector();
+	current = inspect;
+}
+```
+
+This attaches at creation time (so nothing is missed structurally) while forwarding to nothing until the toggle flips.
+
+There is a catch worth knowing before you ship it: events that arrive while `current` is undefined are dropped, so an inspector enabled after startup opens on a machine with no registration event and no history — it has nothing to draw until the next transition. If late opening should show the machine as it stands, buffer the events from creation and replay the buffer when the inspector connects. The demo controller described below does exactly that, and is worth reading as a worked example.
+
+---
+
+## Inspecting without a browser
+
+`createBrowserInspector` is one transport, not the only one. `@statelyai/inspect` also exports `createWebSocketInspector`, which pairs with `createInspectorServer` from `@statelyai/inspect/server` to stream the same events over a socket — the route to an actor with no browser around it at all, such as one running in a Node process or on the server half of an SSR render:
+
+```typescript
+import { createWebSocketInspector } from "@statelyai/inspect";
+
+const { inspect } = createWebSocketInspector({ url: "ws://localhost:8080" });
+
+const createPlayer = definePlayer({ machine: appMachine, options: { inspect } });
+```
+
+Both transports consume the identical `options.inspect` observer, so switching between them touches only the line that creates the inspector. The same is true of an observer you write yourself: a `console.log`, a test spy asserting a transition sequence, or a writer that appends events to a log are all valid `inspect` values, and none of them require the inspect client at all.
+
+---
+
+## Trying it in the demos
+
+Every demo in this repository — all five renderer demos and all eight router demos — wires the inspector the same way, so any of them can be used to see the flow end to end:
+
+```bash
+pnpm --filter @xmachines/play-react-demo run dev
+```
+
+Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you log in, navigate, and log out.
+
+The demos share one controller, `createDemoInspector()` from `@xmachines/play-actor-shared`, which each demo passes straight through to `definePlayer`:
+
+```typescript
+const inspector = createDemoInspector();
+
+const actor = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+})();
+actor.start();
+
+// The debug panel's button
+<button onClick={() => inspector.show()}>Show Inspector</button>;
+```
+
+The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the current root's registration so it can never roll out of the bounded buffer, and flushes the buffer when the inspector window completes its handshake. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. See the [shared demo package README](../../play-actor/examples/shared/README.md) for the design in full.
+
+---
+
+## Production considerations
+
+**Cost.** Inspection serializes events. A `console.log` observer is cheap; a browser inspector posting every transition, and any buffering scheme layered on top, is not. Gate the inspector behind a development-only branch, and prefer letting the bundler drop it entirely:
+
+```typescript
+const options = import.meta.env.DEV ? { inspect: createBrowserInspector().inspect } : {};
+
+const createPlayer = definePlayer({ machine: appMachine, options });
+```
+
+**Data exposure.** Inspection events carry the machine's definition and its context — which in a real application may include user identifiers, tokens, or form input. The browser transport posts that data to the inspector's origin over `postMessage`, and the WebSocket transport sends it to whatever server is listening. Treat an inspector connection as a data egress path: keep it out of production builds, and when inspecting a shared environment, know where the events are going.
+
+---
+
+## Related documentation
+
+- **[`PlayerOptions`](../api/@xmachines/play-xstate/interfaces/PlayerOptions.md)** — the full options bag, `inspect` included
+- **[`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)** — the actor an inspector observes
+- **[Understanding the Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
+- **[Getting Started](getting-started.md)** — installing packages and creating your first actor
+- **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector itself, its transports and options

package/guides/state-machines.md

@@ -122,7 +122,9 @@ const appMachine = setup({/* ... */}).createMachine({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec<TContext>(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@xmachines/json-render-core` spec object describing what to render. Use `typedSpec(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to type-check the spec literal at the definition site (XState's `meta` is untyped). When the machine enters a state, `actor.currentView` is updated with the derived spec. The renderer reads it and projects it through framework components.
+
+The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
 **The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -15,7 +15,7 @@
   "author": "Mikael Karon <mikael@karon.se>",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
+    "url": "git+https://gitlab.com/xmachin-es/xmachines-js.git",
     "directory": "packages/docs"
   },
   "files": [

package/rfc/play.md

@@ -153,7 +153,16 @@ export interface Routable {
 
 // Optional capability: View rendering
 export interface PlaySpec extends Spec {
-	contextProps?: string[];
+	// The machine's whole context is projected into the derived view's state
+	// under the read-only /context subtree; specs read it via
+	// { $state: "/context/…" } in props, visible conditions, and
+	// repeat.statePath. /context never accepts writes — machine context
+	// changes only through events.
+	//
+	// Stamped by view derivation from the selected meta entry (never
+	// authored): providers key their store lifecycle on it — changed key
+	// reseeds the store, unchanged key refreshes /context in place.
+	viewKey?: string;
 }
 
 export interface Viewable {
@@ -393,7 +402,7 @@ export const machine = setup({/* types, guards, actions */}).createMachine({
 		overview: {
 			meta: {
 				route: "/dashboard",
-				view: typedSpec<DashboardCtx>({
+				view: typedSpec({
 					root: "root",
 					elements: {
 						root: {