@xmachines/docs 5.0.2 → 6.1.0

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

@@ -3,282 +3,195 @@
 # Variable: authCatalog
 
 ```ts
-const authCatalog: Catalog<
-	{
-		catalog: SchemaType<
-			"object",
-			{
-				actions: SchemaType<
-					"map",
-					{
-						description: SchemaType<"string", unknown>;
-						params: SchemaType<"zod", unknown>;
-					}
-				>;
-				components: SchemaType<
-					"map",
-					{
-						description: SchemaType<"string", unknown>;
-						example: SchemaType<"any", unknown>;
-						props: SchemaType<"zod", unknown>;
-						slots: SchemaType<"array", SchemaType<"string", unknown>>;
-					}
-				>;
-			}
-		>;
-		spec: SchemaType<
-			"object",
-			{
-				elements: SchemaType<
-					"record",
-					SchemaType<
-						"object",
-						{
-							children: SchemaType<"array", SchemaType<"string", unknown>>;
-							props: SchemaType<"propsOf", string>;
-							repeat: {
-								inner?: unknown;
-								kind: "any";
-								optional: true;
-							};
-							type: SchemaType<"ref", string>;
-							visible: {
-								inner?: unknown;
-								kind: "any";
-								optional: true;
-							};
-						}
-					>
-				>;
-				root: SchemaType<"string", unknown>;
-			}
-		>;
-	},
-	{
-		actions: {
-			addTask: {
-				description: "Add a task (sends task.add to the machine)";
-				params: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			completeTask: {
-				description: "Mark a task done (sends task.complete to the machine)";
-				params: ZodObject<
-					{
-						id: ZodString;
-					},
-					$strip
-				>;
-			};
-			login: {
-				description: "Login with username";
-				params: ZodObject<
-					{
-						username: ZodString;
-					},
-					$strip
-				>;
-			};
-			logout: {
-				description: "Logout and return to home";
-			};
-			removeTask: {
-				description: "Remove a task (sends task.remove to the machine)";
-				params: ZodObject<
-					{
-						id: ZodString;
-					},
-					$strip
-				>;
-			};
-			resetForm: {
-				description: "Reset a demo form to its defaults (confirm-gated in the spec)";
-				params: ZodObject<
-					{
-						form: ZodString;
-					},
-					$strip
-				>;
-			};
-			route: {
-				description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
-				params: ZodObject<
-					{
-						params: ZodOptional<ZodRecord<ZodString, ZodString>>;
-						to: ZodString;
-					},
-					$strip
-				>;
-			};
-			submitForm: {
-				description: "Submit a demo form; rejects when the form did not pass validation";
-				params: ZodObject<
-					{
-						form: ZodString;
-						valid: ZodOptional<ZodNullable<ZodBoolean>>;
-					},
-					$strip
-				>;
-			};
-		};
-		components: {
-			About: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Button: {
-				props: ZodObject<
-					{
-						disabled: ZodOptional<ZodBoolean>;
-						label: ZodString;
-						testId: ZodOptional<ZodString>;
-						variant: ZodOptional<
-							ZodEnum<{
-								danger: "danger";
-								primary: "primary";
-								secondary: "secondary";
-							}>
-						>;
-					},
-					$strip
-				>;
-			};
-			Contact: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Dashboard: {
-				props: ZodObject<
-					{
-						username: ZodString;
-						welcome: ZodBoolean;
-					},
-					$strip
-				>;
-			};
-			Field: {
-				props: ZodObject<
-					{
-						checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
-						formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
-						inputType: ZodOptional<
-							ZodEnum<{
-								email: "email";
-								text: "text";
-								textarea: "textarea";
-							}>
-						>;
-						label: ZodString;
-						placeholder: ZodOptional<ZodString>;
-						testId: ZodOptional<ZodString>;
-						value: ZodOptional<ZodString>;
-					},
-					$strip
-				>;
-			};
-			Home: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Login: {
-				props: ZodObject<
-					{
-						title: ZodString;
-						username: ZodOptional<ZodString>;
-					},
-					$strip
-				>;
-			};
-			NavBar: {
-				props: ZodObject<
-					{
-						isAuthenticated: ZodBoolean;
-						username: ZodNullable<ZodString>;
-					},
-					$strip
-				>;
-			};
-			Navigation: {
-				props: ZodObject<
-					{
-						currentPath: ZodString;
-						isAuthenticated: ZodBoolean;
-					},
-					$strip
-				>;
-			};
-			Overview: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Panel: {
-				props: ZodObject<
-					{
-						note: ZodOptional<
-							ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean, ZodNull]>
-						>;
-						testId: ZodOptional<ZodString>;
-						title: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>;
-						tone: ZodOptional<
-							ZodEnum<{
-								danger: "danger";
-								default: "default";
-								muted: "muted";
-								success: "success";
-							}>
-						>;
-					},
-					$strip
-				>;
-			};
-			Profile: {
-				props: ZodObject<
-					{
-						username: ZodString;
-					},
-					$strip
-				>;
-			};
-			Settings: {
-				props: ZodObject<
-					{
-						section: ZodOptional<ZodString>;
-						username: ZodString;
-					},
-					$strip
-				>;
-			};
-			Stats: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-		};
-	}
->;
+const authCatalog: Catalog<{
+  catalog: SchemaType<"object", {
+     actions: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        params: SchemaType<"zod", unknown>;
+     }>;
+     components: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        example: SchemaType<"any", unknown>;
+        props: SchemaType<"zod", unknown>;
+        slots: SchemaType<"array", SchemaType<"string", unknown>>;
+     }>;
+  }>;
+  spec: SchemaType<"object", {
+     elements: SchemaType<"record", SchemaType<"object", {
+        children: SchemaType<"array", SchemaType<"string", unknown>>;
+        props: SchemaType<"propsOf", string>;
+        repeat: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+        slots: {
+           inner?: SchemaType<"array", SchemaType<..., ...>>;
+           kind: "record";
+           optional: true;
+        };
+        type: SchemaType<"ref", string>;
+        visible: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+     }>>;
+     root: SchemaType<"string", unknown>;
+  }>;
+}, {
+  actions: {
+     addTask: {
+        description: "Add a task (sends task.add to the machine)";
+        params: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+     completeTask: {
+        description: "Mark a task done (sends task.complete to the machine)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     login: {
+        description: "Login with username";
+        params: ZodObject<{
+           username: ZodString;
+        }, $strip>;
+     };
+     logout: {
+        description: "Logout and return to home";
+     };
+     removeTask: {
+        description: "Remove a task (sends task.remove to the machine)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     resetForm: {
+        description: "Reset a demo form to its defaults (confirm-gated in the spec)";
+        params: ZodObject<{
+           form: ZodString;
+        }, $strip>;
+     };
+     route: {
+        description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
+        params: ZodObject<{
+           params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+           to: ZodString;
+        }, $strip>;
+     };
+     submitForm: {
+        description: "Submit a demo form; rejects when the form did not pass validation";
+        params: ZodObject<{
+           form: ZodString;
+           valid: ZodOptional<ZodNullable<ZodBoolean>>;
+        }, $strip>;
+     };
+  };
+  components: {
+     About: {
+        props: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+     Button: {
+        props: ZodObject<{
+           disabled: ZodOptional<ZodBoolean>;
+           label: ZodString;
+           testId: ZodOptional<ZodString>;
+           variant: ZodOptional<ZodEnum<{
+              danger: "danger";
+              primary: "primary";
+              secondary: "secondary";
+           }>>;
+        }, $strip>;
+     };
+     Contact: {
+        props: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+     Dashboard: {
+        props: ZodObject<{
+           username: ZodString;
+           welcome: ZodBoolean;
+        }, $strip>;
+     };
+     Field: {
+        props: ZodObject<{
+           checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+           formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+           inputType: ZodOptional<ZodEnum<{
+              email: "email";
+              text: "text";
+              textarea: "textarea";
+           }>>;
+           label: ZodString;
+           placeholder: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           value: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     Home: {
+        props: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+     Login: {
+        props: ZodObject<{
+           title: ZodString;
+           username: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     NavBar: {
+        props: ZodObject<{
+           isAuthenticated: ZodBoolean;
+           username: ZodNullable<ZodString>;
+        }, $strip>;
+     };
+     Navigation: {
+        props: ZodObject<{
+           currentPath: ZodString;
+           isAuthenticated: ZodBoolean;
+        }, $strip>;
+     };
+     Overview: {
+        props: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+     Panel: {
+        props: ZodObject<{
+           note: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean, ZodNull]>>;
+           testId: ZodOptional<ZodString>;
+           title: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+        }, $strip>;
+     };
+     Profile: {
+        props: ZodObject<{
+           username: ZodString;
+        }, $strip>;
+     };
+     Settings: {
+        props: ZodObject<{
+           section: ZodOptional<ZodString>;
+           username: ZodString;
+        }, $strip>;
+     };
+     Stats: {
+        props: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+  };
+}>;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/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/v6.1.0/packages/play-vue/examples/demo/src/catalog.ts#L5)

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

@@ -6,6 +6,6 @@
 const demoComponents: ComponentsMap<typeof authCatalog>;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/components/demo-components.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-vue/examples/demo/src/components/demo-components.ts#L22)
+Defined in: [packages/play-vue/examples/demo/src/components/demo-components.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-vue/examples/demo/src/components/demo-components.ts#L22)
 
 demoComponents — the full catalog component map, shared with the router demos.

package/examples/README.md

@@ -60,7 +60,7 @@ The conceptual examples in this directory are TypeScript snippets. To run them:
 
 ```bash
 # Install dependencies (from the monorepo root)
-pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom xstate
+pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core xstate
 
 # Run with tsx
 pnpm dlx tsx my-example.ts
@@ -80,7 +80,7 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 | -------------------------------------------------------------------------- | ----------------------------------------------------------- |
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)        | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)          | `PlayActor`                                                 |
-| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)            | `Viewable`, `PlaySpec`, `typedSpec`                         |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)            | `Viewable`, `PlaySpec`, `ViewMeta`, `typedSpec`             |
 | [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)            | The atom primitives, `watchAtom`                            |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)        | `RouterBridgeBase`, `RouteMap`, `Routable`                  |
 | [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) | `extractMachineRoutes`, `getRoutableRoutes`                 |

package/examples/multi-router-integration.md

@@ -492,7 +492,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 > extraction reads that value.
 >
 > These branches decide the CALLS of a navigation, and never the availability of the API.
-> [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries `urlpattern-polyfill` as an ordinary dependency and it
+> [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) carries `urlpattern-polyfill` as an ordinary dependency and it
 > uses the native `URLPattern` when the runtime has one, so you install no polyfill and
 > you load none. A BAD pattern is a question of the route map: `RouteMap` compiles each
 > parameterized route in its constructor and throws an `InvalidRoutePatternError` there.

package/examples/routing-patterns.md

@@ -117,7 +117,7 @@ on: {
 }
 ```
 
-`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state that must re-enter its own domain.
+`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state whose route must also re-enter the domain of the transition. See [Re-entry on a navigation](../guides/routing.md#re-entry-on-a-navigation).
 
 ### `play.route` Events — Navigation
 

package/examples/traffic-light.md

@@ -121,7 +121,7 @@ on: {
 
 - Every routable state must have both `id` (the `#id` navigation target) and `meta.route` (the URL template).
 - The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
-- `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state that must re-enter its own domain.
+- `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state whose route must also re-enter the domain of the transition. See [Re-entry on a navigation](../guides/routing.md#re-entry-on-a-navigation).
 
 ## The `actor.currentRoute` atom
 

package/guides/README.md

@@ -10,10 +10,11 @@ User-facing guides for the XMachines Play architecture.
 
 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 Routing](routing.md)** — The URLPattern grammar that a `meta.route` path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
-- **[Understanding Atoms](atoms.md)** — The atom primitives (`createAtom`, `createWritableAtom`, `watchAtom`), why XMachines uses them instead of observables, and the architectural invariants they enforce
+- **[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
+- **[The Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
+- **[Routing](routing.md)** — The URLPattern grammar that a `meta.route` path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
+- **[Views](views.md)** — Which state supplies the view, the read-only `/context` projection, the `viewKey` that decides when a renderer keeps the UI, and the four invariants that every renderer follows
+- **[Atoms](atoms.md)** — The atom primitives (`createAtom`, `createWritableAtom`, `watchAtom`), why XMachines uses them instead of observables, and the architectural invariants they enforce
 
 ## Tooling
 

package/guides/actor-model.md

@@ -1,4 +1,4 @@
-# Understanding the Actor Model and the Actor/Infrastructure Split
+# The Actor Model in XMachines
 
 XMachines is built around one central design principle: **business logic must never depend on infrastructure**. This page explains what that means, why the split is enforced the way it is, and what concrete responsibilities belong to each side of the boundary.
 
@@ -50,7 +50,7 @@ beside an old derivation, and the composition order of the capabilities decides
 
 A derivation that fails reports through the `onError` option of the actor and keeps its
 last good value. It throws never, because it runs inside the write and a throw would break
-the transition for every other observer. See [Understanding Atoms](atoms.md).
+the transition for every other observer. See [Atoms](atoms.md).
 
 The actor also owns:
 
@@ -190,8 +190,8 @@ The Play RFC captures the actor/infrastructure split in a single statement:
 
 ## See also
 
-- [Understanding Atoms](atoms.md) — how the actor communicates with infrastructure
-- [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
+- [Atoms](atoms.md) — how the actor communicates with infrastructure
+- [State Machines](state-machines.md) — how the machine definition drives actor behavior
 - [Getting Started](getting-started.md) — hands-on walkthrough creating and starting an actor
 - [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
 - [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)