@xmachines/docs 5.0.1 → 6.0.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.1/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.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/v5.0.1/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.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/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

package/examples/form-validation.md

@@ -288,11 +288,14 @@ actor.start();
 
 const disconnect = mount(actor, document.getElementById("app")!);
 
-// Cleanup
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	actor.stop();
-});
+}
 ```
 
 **Key points:**

package/examples/multi-router-integration.md

@@ -300,13 +300,16 @@ const registryResult = defineRegistry(authCatalog, {
 const mount = createPlayUI(registryResult);
 const disconnectRenderer = mount(actor, document.getElementById("app")!);
 
-// Cleanup
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	router.destroy();
 	disconnectRenderer();
 	actor.stop();
-});
+}
 ```
 
 ### SvelteKit (`@xmachines/play-sveltekit-router`)

package/examples/routing-patterns.md

@@ -256,11 +256,14 @@ const router = createRouter({ routeTree: authMachine, history });
 // - browser URL changes → play.route event sent to actor
 const disconnect = connectRouter({ actor, router, routeMap });
 
-// Cleanup on unload
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	router.destroy();
-});
+}
 ```
 
 ## React Router Setup

package/guides/atoms.md

@@ -121,6 +121,16 @@ const subscription = actor.currentRoute.subscribe((route) => {
 subscription.unsubscribe();
 ```
 
+The subscription is a plain object. To hold it with `using`, publish it with `asDisposable` of [`@xmachines/core/utils`](../api/@xmachines/core/README.md), and name `unsubscribe` as the release:
+
+```typescript
+{
+	const plain = actor.currentRoute.subscribe((route) => render(route));
+	using subscription = asDisposable(plain, () => plain.unsubscribe());
+	render(actor.currentRoute.get());
+}
+```
+
 Two consequences follow from the synchronous delivery, and both matter:
 
 - Several writes in one tick call the observer several times. Nothing coalesces them.
@@ -157,9 +167,8 @@ Use [`watchAtom()`](../api/@xmachines/play-atom/functions/watchAtom.md) in frame
 
 ## The release, and `using`
 
-`watchAtom()` returns a `Cleanup` from [`@xmachines/play`](../api/@xmachines/play/README.md): a
-function, and a `Disposable`. One value therefore serves two forms, and the same holds for
-the mount of [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md) and for `history.subscribe()` of
+`watchAtom()` returns a plain function. The same holds for the mount of
+[`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md) and for `history.subscribe()` of
 [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md).
 
 Keep the explicit call where the release outlives the scope that made it — a field that a
@@ -170,12 +179,15 @@ const stop = watchAtom(actor.currentRoute, render);
 onUnmount(() => stop());
 ```
 
-Write `using` where the release belongs to one scope. The scope releases it, an exception
-releases it too, and the code carries no teardown:
+Where the release belongs to one scope, publish it with `asDisposable` of
+[`@xmachines/core/utils`](../api/@xmachines/core/README.md), and write `using`. The scope releases
+it, an exception releases it too, and the code carries no teardown:
 
 ```typescript
+import { asDisposable } from "@xmachines/core/utils";
+
 {
-	using stop = watchAtom(actor.currentRoute, render);
+	using stop = asDisposable(watchAtom(actor.currentRoute, render));
 	render(actor.currentRoute.get());
 	// stop() runs here, and it runs even when render() throws
 }
@@ -184,17 +196,17 @@ releases it too, and the code carries no teardown:
 A scope releases from the last declaration to the first, so a release that depends on an
 earlier one is safe.
 
-Every release here is synchronous, so `Cleanup` is a `Disposable` and not an
+Every release here is synchronous, so `asDisposable` makes a `Disposable` and not an
 `AsyncDisposable`. That is the permissive choice: a `Disposable` serves `using` AND
 `await using`, while an `AsyncDisposable` raises a TypeError under a plain `using` and
-forces every holder into an async function. `asCleanup` therefore refuses a release that
-returns a value, and a promise above all — a promise handed to it would go on the floor,
-released and unawaitable.
+forces every holder into an async function. `asDisposable` therefore refuses a release that
+returns a value, a promise above all: the scope would ignore the promise, and nothing could
+await the work.
 
 `using` needs Node 24 or a browser with Explicit Resource Management. The publishable
 packages build at `target: "esnext"` and pass the syntax through untouched, so your bundler
-decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
-`Symbol.dispose` still calls it as a plain function.
+decides how to emit it. A caller that does not write `using` needs neither, and it needs no
+[`@xmachines/core/utils`](../api/@xmachines/core/README.md).
 
 ---