@xmachines/docs 6.0.0 → 7.0.0

package/examples/@xmachines/play-vue-demo/functions/createAuthActionHandlers.md

@@ -6,7 +6,7 @@
 function createAuthActionHandlers(actor): object;
 ```
 
-Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L48)
+Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L48)
 
 Build the demo action handler map for one actor.
 
@@ -25,11 +25,11 @@ framework's `defineRegistry` accepts; spread the result into its `actions`.
 
 | Name             | Type                                                    | Defined in                                                                                                                                                               |
 | ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L65) |
-| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L72) |
-| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L50) |
-| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L54) |
-| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L81) |
-| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L99) |
-| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L55) |
-| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L92) |
+| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L65) |
+| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L72) |
+| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L50) |
+| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L54) |
+| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L81) |
+| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L99) |
+| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L55) |
+| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L92) |

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/v6.0.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/v7.0.0/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/v6.0.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/v7.0.0/packages/play-vue/examples/demo/src/env.d.ts#L5)

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

@@ -194,4 +194,4 @@ const authCatalog: Catalog<{
 }>;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.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/v7.0.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/v6.0.0/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/v7.0.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/@xmachines/play-vue-router-demo/README.md

@@ -38,14 +38,14 @@ Use this order to understand how the demo is wired:
 6. `PlayRouterProvider` waits for `router.isReady()` so direct URL loads are handled correctly.
 7. Browser tests in `test/browser/` validate startup and auth route transitions.
 
-```ts
+```ts fragment
 // src/main.ts (shape)
 const app = createApp(App);
 app.use(router);
 app.mount("#app");
 ```
 
-```ts
+```ts fragment
 // src/router.ts (shape)
 export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", component: RouteHost }];
 ```
@@ -69,7 +69,7 @@ const renderShell = (currentActor, currentRouter) =>
 </template>
 ```
 
-```ts
+```ts fragment
 // src/runtime.ts (shape)
 export const actor = createPlayer();
 actor.start();

package/examples/README.md

@@ -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/form-validation.md

@@ -15,8 +15,9 @@ This example mirrors the `authMachine` login pattern: a form state with a local
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
 
 // Context shape
 interface LoginContext {
@@ -155,8 +156,11 @@ const loginMachine = loginSetup.createMachine(
 	}),
 );
 
-// 3. Factory and actor
-const createPlayer = definePlayer({ machine: loginMachine });
+// 3. Factory and actor — withView derives the meta.view spec that a renderer reads
+const createPlayer = definePlayer({
+	machine: loginMachine,
+	actor: compose(PlayerActor, withView),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -190,9 +194,9 @@ actor.stop();
 | `{ $bindState: "/username" }` | Two-way   | Prop reads and writes the state store key `/username`       |
 | `{ $state: "/username" }`     | Read-only | Reads the current value from the state store at `/username` |
 
-The `state:` key in `meta.view` sets the initial values for the local store. When the user types in the form field, the renderer keeps the store in sync. On submit, action params read the final value via `$state`.
+The `state:` key in `meta.view` sets the initial values for the local store. When the user types in the form field, the component writes the value to the store. On submit, action params read the final value via `$state`.
 
-```typescript
+```typescript fragment
 // In the machine meta.view — the renderer handles the rest:
 view: {
   root: "root",
@@ -231,6 +235,10 @@ import { createRenderer, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
+
+// The started actor of the complete code above
+declare const actor: ViewActor & { stop(): void };
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -257,10 +265,9 @@ const Login: ComponentFn<AppCatalog, "Login"> = ({ props, on, ctx }) => {
 	const section = document.createElement("section");
 	const input = document.createElement("input");
 	input.value = props.username ?? "";
-	// Keep the local state store in sync as the user types
-	input.addEventListener("input", () => {
-		ctx.store.update((s) => ({ ...s, username: input.value }));
-	});
+	// Write each keystroke to the store path that $bindState binds to the prop
+	const username = ctx.bound<string>("username");
+	input.addEventListener("input", () => username.set(input.value));
 	const button = document.createElement("button");
 	button.textContent = "Log In";
 	const submit = on("submit"); // bound to the spec's on.submit binding
@@ -283,9 +290,6 @@ const Dashboard: ComponentFn<AppCatalog, "Dashboard"> = ({ props, on }) => {
 // createRenderer builds the factory once — call mount() when the actor is ready
 const mount = createRenderer(catalog, { Home, Login, Dashboard });
 
-const actor = createPlayer();
-actor.start();
-
 const disconnect = mount(actor, document.getElementById("app")!);
 
 // Call teardown() when the app ends before the page does, for example when the component
@@ -302,7 +306,7 @@ function teardown(): void {
 
 - `actions` in `defineCatalog` must include every action name referenced in `meta.view` `on:` bindings. TypeScript enforces this via `CatalogHasActions`.
 - `on("submit").emit()` resolves `params` from the current state store at call time — the `$state: "/username"` in the spec is read at that moment, not at render time.
-- `ctx.store.update(fn)` is the standard write path for two-way binding. The spec's `$bindState` directive only wires the read direction (prop ← store); the write direction (store ← input) must be implemented in the component.
+- `ctx.bound("username").set(value)` writes to the store path that `$bindState` binds to the prop. The `$bindState` directive gives the prop its value from the store. The component writes the input back to the store.
 
 ## Next Steps