@xmachines/docs 6.1.0 → 8.0.0-next.1

package/rfc/play.md

@@ -11,7 +11,7 @@
 
 This RFC defines the **Universal Player Architecture** and its reference implementation. The architecture establishes a design pattern that strictly separates **Business Logic (The Actor)** from **Infrastructure (The Runtime Adapter and View)**.
 
-The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **atoms** to glue a specific **State Engine (XState v5)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
+The reference implementation provides a modular monorepo that satisfies the architectural constraints of **Runtime Agnosticism** and **Logic-Driven Guarding**. It leverages **atoms** to glue a specific **State Engine (XState v6)** to multiple **Runtime Adapters** (TanStack Router, React Router, Vue Router, SolidJS Router) and **View Layers** (React, Vue, SolidJS, Vanilla DOM — all via JSON-Render), while ensuring that **business logic remains the single source of truth** for navigation, state, and UI structure.
 
 ---
 
@@ -162,7 +162,6 @@ The base class requires only two abstract members: **reactive state** and **type
 **Design Rationale:** The RFC declared an abstract `AbstractActor` CLASS that extended `Actor` of `xstate`, and it declared both capability interfaces in this package. The implementation made the contract an INTERFACE, `PlayActor`, because the class carried no implementation: both of its members were abstract, and its whole effect was to force the inheritance of XState on every consumer of the contract. [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names `xstate` nowhere now. The implementation also moved each capability interface to the package that holds its shared machinery: `Routable` is in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), beside the bridge that reads it, and `Viewable` and `PlaySpec` are in [`@xmachines/play-view`](../api/@xmachines/play-view/README.md), beside the view store lifecycle. A consumer who needs no routing and no view therefore installs neither package, and [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) names the capability packages nowhere. The shape of each interface is unchanged.
 
 ```ts
-import { Actor, type AnyActorLogic, type EventObject } from "xstate";
 import type {
 	AnyAtom,
 	Atom,
@@ -215,16 +214,18 @@ export interface Viewable {
 	readonly currentView: ReadonlyAtom<PlaySpec | null>;
 }
 
-// The Base Protocol — minimal contract
-export abstract class PlayActor<
-	TLogic extends AnyActorLogic,
-	TEvent extends EventObject = EventObject,
-> extends Actor<TLogic> {
+// The Base Protocol — minimal contract. An INTERFACE, which names no state machine
+// library. The RFC declared an abstract class that extended `Actor` of XState.
+export interface ActorEvent {
+	readonly type: string;
+}
+
+export interface PlayActor<TSnapshot = unknown, TEvent extends ActorEvent = ActorEvent> {
 	// Reactive Output (Snapshot)
-	public abstract state: Atom<unknown>;
+	readonly state: Atom<TSnapshot>;
 
 	// Input Channel (typed for specific event shapes)
-	public abstract override send(event: TEvent): void;
+	send(event: TEvent): void;
 }
 ```
 
@@ -238,9 +239,9 @@ export abstract class PlayActor<
 
 #### 5.2.1 `@xmachines/play-xstate`
 
-**Role:** Concrete Logic Adapter (XState v5)
+**Role:** Concrete Logic Adapter (XState v6)
 
-Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API for creating actors from state machine definitions.
+Wraps XState v6 to satisfy the `PlayActor` contract. Provides the primary API for creating actors from state machine definitions.
 
 **Primary Exports:**
 
@@ -258,9 +259,9 @@ Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API fo
 - Compose the view of a parent state that declares `outlets` with the views of its active substates, so the state tree decides the layout
 - Manage atom lifecycle (create on start, dispose on stop)
 - Support snapshot restore for resumable sessions
-- Provide XState DevTools compatibility
+- Keep the inspection of XState: the `inspect` option of the factory goes to `createActor` without a change
 
-```ts
+```ts fragment
 import type { AnyStateMachine, InputFrom } from "xstate";
 
 interface PlayerConfig<TMachine extends AnyStateMachine> {
@@ -278,8 +279,8 @@ const definePlayer = <TMachine extends AnyStateMachine>(
 // PlayerActor carries the core protocol alone. It extends the actor class of XState
 // directly, and `PlayActor` is a contract that it implements.
 class PlayerActor<TMachine extends AnyStateMachine>
-	extends Actor<AnyActorLogic>
-	implements PlayActor<SnapshotFrom<TMachine>, EventFromLogic<TMachine>>
+	extends Actor<TMachine>
+	implements PlayActor<SnapshotFrom<TMachine>, SendableEventFromLogic<TMachine>>
 {
 	public state: Atom<SnapshotFrom<TMachine>>;
 }
@@ -303,7 +304,7 @@ Provides the complete routing infrastructure: route extraction from state machin
 
 **Design Rationale:** The RFC put the whole of the routing in one package. The implementation split it at two boundaries, because a consumer paid for both halves and used one:
 
-- [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate` and `@statelyai/graph`.
+- [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) holds the machine half — `extractMachineRoutes`, `createRouteMap`, `machineToGraph`, and the queries over a route tree. That half alone needs `xstate`.
 - [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) holds the pattern LANGUAGE — one parse of the URLPattern pathname grammar, and the path that `buildPath` writes back from it. A parse is string work, so the package carries no URLPattern API and no polyfill. BOTH directions of the routing read it: the match of [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) reads the parse, and the routing capability of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) reads the same parse to build a URL, so that package installs no matching machinery.
 - [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) holds the URL LAYER — the URLPattern API with its polyfill, a base path, a location splitter, and the params of a framework router. It reads [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md) for the language and re-exports it whole. It knows no machine and no bridge.
 - [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) keeps the route map, the match of a location, `RouterBridgeBase`, the provider lifecycle, and the `Routable` capability. It names no state machine.
@@ -380,7 +381,7 @@ Each view renderer provides a `PlayRenderer` component that passively observes t
 
 **[`@xmachines/play-react`](../api/@xmachines/play-react/README.md) exports (representative):**
 
-```ts
+```ts fragment
 // Batteries-included composite — standard entry point
 // Props: actor, registryResult, store?, fallback?, onError?, onRenderError?,
 //        validationFunctions?, navigate?, functions?
@@ -438,13 +439,18 @@ The original RFC proposed an `@xmachines/play-ui` package for this purpose. The
 Defines the **UI vocabulary** — available components and their prop schemas. No framework code.
 
 ```ts
-import { defineCatalog, z } from "@xmachines/json-render-core";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { schema } from "@xmachines/json-render-react/schema";
+import { z } from "zod";
 
-export const catalog = defineCatalog({
+export const catalog = defineCatalog(schema, {
 	components: {
 		Dashboard: { props: z.object({ title: z.string() }) },
 		Metric: { props: z.object({ value: z.number(), label: z.string() }) },
 	},
+	actions: {
+		submit: { description: "Submit the form" },
+	},
 });
 ```
 
@@ -453,13 +459,21 @@ export const catalog = defineCatalog({
 Defines **Logic**. No framework code. No routing library imports.
 
 ```ts
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-
-export const machine = setup({/* types, guards, actions */}).createMachine({
+import { setup, types } from "xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+
+export const machine = setup({
+	// the schemas of the context and the events, guards, actions
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine({
+	id: "dashboard",
 	initial: "overview",
 	states: {
 		overview: {
+			id: "overview",
 			meta: {
 				route: "/dashboard",
 				view: typedSpec({
@@ -478,20 +492,27 @@ export const machine = setup({/* types, guards, actions */}).createMachine({
 	},
 });
 
-// definePlayer returns a factory function
-export const createDashboard = definePlayer({ machine });
+// definePlayer returns a factory function. The router and the renderer need both capabilities
+export const createDashboard = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 ```
 
 ### 6.3 Application (`App.tsx`)
 
 Binds Logic to a View Renderer and Router Adapter.
 
-```tsx
-import { createDashboard, machine } from "./features/dashboard/player";
-import { catalog } from "./catalog";
+```tsx fragment
+import { createRootRoute, createRouter } from "@tanstack/react-router";
+import { createDashboard, machine } from "./dashboard.player.js";
+import { catalog } from "./catalog.js";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
-import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
+import {
+	createRouteMapFromTree,
+	TanStackReactRouterBridge,
+} from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 // 1. Create the actor
 const actor = createDashboard();
@@ -516,7 +537,8 @@ const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 
 // 4. Connect router adapter (router, actor, routeMap)
-const bridge = new TanStackReactRouterBridge(tanstackRouter, actor, routeMap);
+const router = createRouter({ routeTree: createRootRoute() });
+const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
 
 // 5. Render — PlayUIProvider is the batteries-included composite; PlayRenderer is the zero-prop leaf

package/rfc/run.md

@@ -42,9 +42,12 @@ Properties:
 ### 2.3 Run Identity
 
 - Run IDs are **opaque and hash-like**
-- The algorithm is **Git OID–compatible**
-- With Git enabled: run ID **is** a commit hash
-- Without Git: the same algorithm is used
+- The algorithm is **Git's object ID**, in the **SHA-1** object format
+- A run ID is the hash of the run's **fork commit**: its parent is the machine's
+  commit, its tree holds `machine.json` and `run.json` (the run's name and input),
+  and its author time is the time of the fork (see [Git](git.md), Identity)
+- With Git enabled: run ID **is** that commit hash
+- Without Git: the same algorithm is used, so the ID is the same
 
 Run IDs never change and never require migration.
 
@@ -152,7 +155,7 @@ a run is deterministic.
 1. Events are the only mutation mechanism
 2. Snapshots are read-only externally
 3. History is immutable
-4. IDs are Git OID–compatible
+4. IDs are Git object IDs (SHA-1)
 
 ---
 

package/api/@xmachines/play-view/index/functions/createFailureLatch.md

@@ -1,20 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / createFailureLatch
-
-# Function: createFailureLatch()
-
-```ts
-function createFailureLatch(): FailureLatch;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L202)
-
-Makes a [FailureLatch](../interfaces/FailureLatch.md).
-
-The latch holds the three inputs BESIDE the flag. Clearing on each emission would be
-enough for a provider that can hook every emission, and the identity check covers the
-one that cannot: a render that runs again with nothing changed reports nothing, whether
-or not the provider noticed that it ran.
-
-## Returns
-
-[`FailureLatch`](../interfaces/FailureLatch.md)

package/api/@xmachines/play-view/index/functions/sameViewInputs.md

@@ -1,25 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / sameViewInputs
-
-# Function: sameViewInputs()
-
-```ts
-function sameViewInputs(a, b): boolean;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L45)
-
-Answers whether two sets of inputs are the SAME attempt.
-
-Identity, and not a deep compare: a provider holds the references that it rendered, and
-a new spec object is a new attempt even when it holds equal fields.
-
-## Parameters
-
-| Parameter | Type                                        |
-| --------- | ------------------------------------------- |
-| `a`       | [`ViewInputs`](../interfaces/ViewInputs.md) |
-| `b`       | [`ViewInputs`](../interfaces/ViewInputs.md) |
-
-## Returns
-
-`boolean`

package/api/@xmachines/play-view/index/interfaces/FailureLatch.md

@@ -1,60 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / FailureLatch
-
-# Interface: FailureLatch
-
-Defined in: [packages/play-view/src/failure-latch.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L174)
-
-The record of what a provider reported. See [createFailureLatch](../functions/createFailureLatch.md).
-
-## Methods
-
-### clear()
-
-```ts
-clear(): void;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L191)
-
-Forgets the record, so the next failure reports again.
-
-A caller clears it on EVERY emission of a view, the null emission included: a view,
-then null, then the same view is a real sequence of an actor, and the second failure
-of that view is a second attempt that the host must hear about. It also clears it on
-a resolution that works, and on a retry that the host starts — the host asked for
-that attempt, so it must hear the result.
-
-#### Returns
-
-`void`
-
----
-
-### shouldReport()
-
-```ts
-shouldReport(
-   actor,
-   view,
-   store
-): boolean;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:181](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L181)
-
-Answers whether a failure of these three inputs is new, and records it.
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `actor`   | `unknown` |
-| `view`    | `unknown` |
-| `store`   | `unknown` |
-
-#### Returns
-
-`boolean`
-
-`true` the first time for one set of inputs, and `false` for every repeat
-of the same set. A caller reports only when it returns `true`.

package/api/@xmachines/play-view/index/interfaces/ViewInputs.md

@@ -1,19 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / ViewInputs
-
-# Interface: ViewInputs
-
-Defined in: [packages/play-view/src/failure-latch.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L33)
-
-The three inputs that a provider resolves a store from.
-
-`ViewStoreLifecycle.resolve` takes exactly these, and every provider names all three in
-its reset rule. The type gives the rule one name, so the comparison below stands one
-time instead of once for each renderer that needs it.
-
-## Properties
-
-| Property                            | Type      | Defined in                                                                                                                                         |
-| ----------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor` | `unknown` | [packages/play-view/src/failure-latch.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L34) |
-| <a id="property-store"></a> `store` | `unknown` | [packages/play-view/src/failure-latch.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L36) |
-| <a id="property-view"></a> `view`   | `unknown` | [packages/play-view/src/failure-latch.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L35) |