@xmachines/docs 6.1.0 → 7.0.0

package/examples/routing-patterns.md

@@ -14,7 +14,7 @@ Every routing interaction starts with a `play.route` event sent to the actor. If
 
 Add a `meta.route` URL template to any state to make it routable:
 
-```typescript
+```typescript fragment
 states: {
   home: {
     id: "home",            // required: used as the play.route target ("#home")
@@ -106,7 +106,7 @@ const authMachine = authSetup.createMachine(
 
 `formatPlayRouteTransitions` generates root-level handlers equivalent to:
 
-```typescript
+```typescript fragment
 on: {
   "play.route": [
     { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: false, actions: assign({ params, query }) },
@@ -124,6 +124,10 @@ on: {
 To navigate, send a `play.route` event with `to: "#stateId"`:
 
 ```typescript
+import type { RoutableActor } from "@xmachines/play-router";
+
+declare const actor: RoutableActor; // the started actor of "Complete Actor Usage" below
+
 // Navigate to home
 actor.send({ type: "play.route", to: "#home" });
 
@@ -151,7 +155,7 @@ actor.send({
 
 Use XState `always` transitions to protect states. If the guard fires, the machine redirects _before_ the state is fully entered:
 
-```typescript
+```typescript fragment
 dashboard: {
   id: "dashboard",
   meta: { route: "/dashboard" },
@@ -177,7 +181,7 @@ profile: {
 
 Domain events placed at the root `on:` level are handled from any state:
 
-```typescript
+```typescript fragment
 const authMachine = authSetup.createMachine(
 	formatPlayRouteTransitions({
 		// ...
@@ -207,6 +211,12 @@ const authMachine = authSetup.createMachine(
 ## Complete Actor Usage
 
 ```typescript
+import type { AnyStateMachine } from "xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+
+declare const authMachine: AnyStateMachine; // the machine of the sections above
+
 const createPlayer = definePlayer({
 	machine: authMachine,
 	actor: compose(PlayerActor, withRouting),
@@ -244,12 +254,18 @@ To sync the browser URL with `actor.currentRoute`, use [`@xmachines/play-dom-rou
 
 ```typescript
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
-import { createRouteMap } from "@xmachines/play-router/xstate";
+import { createRouteMap, extractMachineRoutes } from "@xmachines/play-router/xstate";
+import type { RoutableActor } from "@xmachines/play-router";
+import type { AnyStateMachine } from "xstate";
+
+declare const authMachine: AnyStateMachine; // the machine of the sections above
+declare const actor: RoutableActor; // the started actor of "Complete Actor Usage"
+
 // createRouteMap extracts meta.route declarations from the machine
 const routeMap = createRouteMap(authMachine);
 
 const history = createBrowserHistory({ window });
-const router = createRouter({ routeTree: authMachine, history });
+const router = createRouter({ routeTree: extractMachineRoutes(authMachine), history });
 
 // connectRouter handles all bidirectional sync:
 // - actor.currentRoute atom → browser URL (history.push)
@@ -271,14 +287,33 @@ function teardown(): void {
 For React, use [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md) or [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md):
 
 ```tsx
-import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+import type { ReactNode } from "react";
+import {
+	PlayRouterProvider,
+	createRouteMapFromTree,
+	type RoutableActor,
+	type TanStackRouterInstance,
+} from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const authMachine: AnyStateMachine; // the machine of the sections above
+declare const actor: RoutableActor; // the started actor of "Complete Actor Usage"
+declare const router: TanStackRouterInstance; // your TanStack Router instance
+declare function Shell(props: { actor: RoutableActor }): ReactNode; // your layout component
 
 const routeTree = extractMachineRoutes(authMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 
 function App() {
-	return <PlayRouterProvider actor={actor} router={router} routeMap={routeMap} />;
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor) => <Shell actor={currentActor} />}
+		/>
+	);
 }
 ```
 

package/examples/traffic-light.md

@@ -36,7 +36,7 @@ const trafficSetup = setup({
 					params?: Record<string, string>;
 					query?: Record<string, string>;
 			  },
-		input: {} as undefined,
+		input: undefined,
 	},
 });
 
@@ -106,7 +106,7 @@ actor.stop();
 
 `formatPlayRouteTransitions` crawls every state that has **both** an `id` and a `meta.route`, then generates root-level `play.route` event handlers of the form:
 
-```typescript
+```typescript fragment
 // Auto-generated by formatPlayRouteTransitions — you don't write this manually:
 on: {
   "play.route": [
@@ -129,6 +129,10 @@ on: {
 
 ```typescript
 import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+// The actor of the complete code above.
+declare const actor: Routable;
 
 const unwatch = watchAtom(actor.currentRoute, () => {
 	console.log("URL changed to:", actor.currentRoute.get());

package/guides/actor-model.md

@@ -33,7 +33,7 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 ## What the actor owns
 
-An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It implements three reactive properties:
+An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends the `Actor` class of XState and implements the [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) interface. With its capabilities, it holds three reactive properties:
 
 | Property             | Type                             | What it is                                                                                                                                               |
 | -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -116,27 +116,30 @@ The two optional capability interfaces — [`Routable`](../api/@xmachines/play-r
 An actor implements only the capabilities it actually uses:
 
 ```typescript
+import type { PlayActor } from "@xmachines/play-actor";
+import { createAtom } from "@xmachines/play-atom";
+import { compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import type { AnyStateMachine } from "xstate";
+
+type CounterEvent = { type: "increment" };
+
 // Minimal actor: the contract alone, which is reactive state and send
-class MinimalActor implements PlayActor<SomeSnapshot, SomeEvent> {
-	readonly state = createAtom<SomeSnapshot>(initial);
-	send(event: SomeEvent): void {
-		/* dispatch */
+class CounterActor implements PlayActor<{ count: number }, CounterEvent> {
+	readonly state = createAtom({ count: 0 });
+
+	send(event: CounterEvent): void {
+		if (event.type === "increment") this.state.set(({ count }) => ({ count: count + 1 }));
 	}
 }
 
-// Full actor: the contract, the routing and the view. It extends the actor class of
-// its own engine, and `PlayActor` stays out of the inheritance.
-class PlayerActor
-	extends Actor<SomeMachine>
-	implements PlayActor<SomeSnapshot, SomeEvent>, Routable, Viewable
-{
-	readonly state = createAtom(this.getSnapshot());
-	readonly currentRoute = createAtom(() => deriveRoute(this.state.get()));
-	readonly currentView = createAtom((): PlaySpec | null => deriveView(this.state.get()));
-}
+// Full actor: `PlayerActor` extends the `Actor` class of XState, and it implements
+// `PlayActor`. `withRouting` adds `Routable`, and `withView` adds `Viewable`.
+const FullActor = compose(PlayerActor<AnyStateMachine>, withRouting, withView);
 ```
 
-In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
+In practice you never write the actor class yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates the actor from your machine definition and from the class that `compose` returns.
 
 ---
 
@@ -146,7 +149,9 @@ In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
-import { myMachine } from "./machine.js";
+import { setup } from "xstate";
+
+const myMachine = setup({}).createMachine({ id: "app", initial: "idle", states: { idle: {} } });
 
 const createPlayer = definePlayer({ machine: myMachine });
 
@@ -157,11 +162,24 @@ actor.start();
 
 [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
 
-The factory accepts optional `input` (initial context overrides) and a `restore` snapshot (for resumable sessions):
+The factory accepts an optional `input` (initial context overrides) and an optional second argument `{ snapshot }` (a persisted snapshot, for resumable sessions):
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+
+const machine = setup({
+	types: {
+		input: {} as { userId: string } | undefined,
+		context: {} as { userId: string | null },
+	},
+}).createMachine({ context: ({ input }) => ({ userId: input?.userId ?? null }) });
+
+const createPlayer = definePlayer({ machine });
+
 const actor = createPlayer({ userId: "abc" }); // with input
-const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
+const snapshot = actor.getPersistedSnapshot();
+const restored = createPlayer(undefined, { snapshot }); // restored from snapshot
 ```
 
 ---

package/guides/atoms.md

@@ -48,6 +48,8 @@ In XMachines, `actor.state` is an `Atom<Snapshot>`. The actor updates it on ever
 An atom notifies nobody when the new value compares equal to the old one. The default comparison is `Object.is`, and the `compare` option replaces it:
 
 ```typescript
+import { createAtom } from "@xmachines/play-atom";
+
 const point = createAtom(
 	{ x: 0, y: 0 },
 	{ compare: (previous, next) => previous.x === next.x && previous.y === next.y },
@@ -59,13 +61,18 @@ const point = createAtom(
 `ReadonlyAtom<T>` derives a value from one or more other atoms. It recomputes only when its dependencies change, and it memoizes the result. The atom tracks each dependency for you: read another atom inside the function, and the edge exists.
 
 ```typescript
-const route = createAtom(() => {
-	const snapshot = actor.state.get();
-	return snapshot.getMeta()?.route ?? null;
-});
+import { createAtom } from "@xmachines/play-atom";
+import type { PlayerActor } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const actor: PlayerActor<AnyStateMachine>;
+
+// Whether the machine is in a state that shows the dashboard. The atom reads actor.state,
+// so it recomputes on each snapshot, and it notifies only when the answer changes.
+const onDashboard = createAtom(() => actor.state.get().matches("dashboard"));
 ```
 
-In XMachines, `actor.currentRoute` is a `ReadonlyAtom<string | null>`. Router adapters read it to know which URL to push — they do not compute the route themselves. Route derivation stays in the actor where the business logic lives.
+In XMachines, `actor.currentRoute` is such a derived `ReadonlyAtom<string | null>`. It derives the route template of the active branch from `actor.state`, and it then fills the params from the context. Router adapters read it to know which URL to push — they do not compute the route themselves. Route derivation stays in the actor where the business logic lives.
 
 > **A computed atom with a subscriber is EAGER.** `@xstate/store` builds a subscription on an effect that READS the atom, so a write to a dependency evaluates the derivation at once, inside that write. A computed atom that nobody subscribes to stays lazy, and it computes on a read. Keep a derivation cheap and free of a side effect.
 
@@ -80,11 +87,15 @@ The actor writes exactly one atom for each transition — `state` — and `curre
 A subscriber makes a computed atom eager, so the derivation runs inside the `set` of its dependency — before any observer sees anything. No subscriber can wrap that, so a derivation that something may watch must not throw:
 
 ```typescript
-const derived = createAtom((previous) => {
+import { createAtom } from "@xmachines/play-atom";
+
+const source = createAtom('{ "count": 0 }');
+
+const derived = createAtom((previous?: unknown) => {
 	try {
-		return expensiveDerivation(source.get());
+		return JSON.parse(source.get()) as unknown;
 	} catch (error) {
-		report(error);
+		console.error(error);
 		return previous ?? null; // keep the last good value
 	}
 });
@@ -97,6 +108,8 @@ const derived = createAtom((previous) => {
 `createAtom` carries two signatures, and TypeScript must prove the argument is not a function before it reaches the writable one. For a concrete type it proves that at once. For a type parameter, or a conditional type over one, it cannot, so it picks the computed signature and returns a `ReadonlyAtom` that carries no `set`.
 
 ```typescript
+import { createWritableAtom, type Atom } from "@xmachines/play-atom";
+
 class Holder<T extends { value: unknown }> {
 	public readonly state: Atom<T["value"]>;
 
@@ -114,6 +127,10 @@ Use `createAtom` everywhere else.
 Every atom carries `subscribe`. The observer runs **synchronously**, inside the `set` of the atom that changed, and it returns a subscription with `unsubscribe()`.
 
 ```typescript
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+
 const subscription = actor.currentRoute.subscribe((route) => {
 	console.log("Route is now:", route);
 });
@@ -124,6 +141,12 @@ 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
+import { asDisposable } from "@xmachines/core/utils";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+declare function render(route: string | null): void;
+
 {
 	const plain = actor.currentRoute.subscribe((route) => render(route));
 	using subscription = asDisposable(plain, () => plain.unsubscribe());
@@ -145,6 +168,11 @@ For both reasons, application code should use [`watchAtom()`](../api/@xmachines/
 [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) exports [`watchAtom(atom, onValue)`](../api/@xmachines/play-atom/functions/watchAtom.md) as a lifecycle-safe wrapper around `subscribe`. It returns a cleanup function:
 
 ```typescript
+import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+
 const stop = watchAtom(actor.currentRoute, (route) => {
 	console.log("Route is now:", route);
 });
@@ -175,6 +203,13 @@ Keep the explicit call where the release outlives the scope that made it — a f
 teardown reads, an entry in a `Set` of releases:
 
 ```typescript
+import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+declare function render(route: string | null): void;
+declare function onUnmount(teardown: () => void): void; // the hook of your framework
+
 const stop = watchAtom(actor.currentRoute, render);
 onUnmount(() => stop());
 ```
@@ -185,6 +220,11 @@ it, an exception releases it too, and the code carries no teardown:
 
 ```typescript
 import { asDisposable } from "@xmachines/core/utils";
+import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+declare function render(route: string | null): void;
 
 {
 	using stop = asDisposable(watchAtom(actor.currentRoute, render));

package/guides/getting-started.md

@@ -102,13 +102,13 @@ The test suite relies on TypeScript path aliases that resolve to source files. I
 
 #### TypeScript errors about missing types after adding a dependency
 
-Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, also add the correct `references` entry in the package's `tsconfig.base.json`.
+Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, declare it in the `package.json` of the package with a `workspace:*` range. The root `tsconfig.json` holds the build order, and `tests/tsconfig-reference-graph.test.ts` fails when that order misses the new edge.
 
 #### Lint errors about import extensions
 
 All TypeScript imports must end with `.js`, even for `.ts` source files:
 
-```typescript
+```typescript fragment
 // ✅ Correct
 import { PlayError } from "./errors.js";
 
@@ -154,9 +154,11 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 Every XMachines application needs these six packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core@0.21.0-xm.6
 ```
 
+The json-render packages are exact peers: install the version that this release names, `0.21.0-xm.6`.
+
 | Package                                                             | Role                                                                                                                                                                                                                                                                       |
 | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                                                                                           |
@@ -208,7 +210,6 @@ const appSetup = setup({
 	types: {
 		context: {} as { count: number },
 		events: {} as { type: "toggle" },
-		input: {} as undefined,
 	},
 });
 
@@ -272,6 +273,10 @@ release:
 
 ```typescript
 import { watchAtom } from "@xmachines/play-atom";
+import type { PlayerActor } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const actor: PlayerActor<AnyStateMachine>; // the actor of the example above
 
 const stop = watchAtom(actor.state, (snapshot) => {
 	console.log("the machine is now:", snapshot.value);
@@ -325,7 +330,6 @@ const appSetup = setup({
 		},
 		events: {} as
 			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
 	},
 });
 
@@ -412,16 +416,27 @@ Used with framework-integrated routers like TanStack Router. All three props (`a
 
 ```tsx
 // React + TanStack Router example
-import { useMemo, useEffect } from "react";
+import { useMemo, useEffect, type ReactNode } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // the machine of "Adding Routing"
+declare function Shell(props: { actor: typeof actor }): ReactNode; // your layout
+
 // Build OUTSIDE of JSX — must be stable references
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 const router = createRouter({ routeTree: createRootRoute() });
 
 // Actor also created outside the component (or memoized inside)
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -448,12 +463,21 @@ Used with framework-agnostic or server-rendered routers. `connectRouter` handles
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
 import { createRouteMapFromTree } from "@xmachines/play-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // the machine of "Adding Routing"
 
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
 
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -483,6 +507,10 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-re
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/play-react";
 import { z } from "zod";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -501,7 +529,9 @@ const registryResult = defineRegistry(catalog, {
 		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -548,7 +578,9 @@ function App() {
 			Login: { template: `<button @click="on('submit').emit()">Log in</button>` },
 		},
 		actions: {
-			login: async ({ username }) => actor.send({ type: "auth.login", username }),
+			login: async (params) => {
+				if (params) actor.send({ type: "auth.login", username: params.username });
+			},
 			logout: async () => actor.send({ type: "auth.logout" }),
 		},
 	});
@@ -562,6 +594,10 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-so
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/play-solid";
 import { z } from "zod";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -580,7 +616,9 @@ const registryResult = defineRegistry(catalog, {
 		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -601,6 +639,10 @@ import { createPlayUI, defineRegistry, 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";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -631,7 +673,9 @@ const Login: ComponentFn<typeof catalog, "Login"> = ({ on }) => {
 const registryResult = defineRegistry(catalog, {
 	components: { Home, Login },
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -658,7 +702,7 @@ nothing is needed — the generated transitions assign `event.query` to context
 on every navigation. A machine that handles `play.route` by hand must do that
 assignment itself:
 
-```typescript
+```typescript fragment
 on: {
   "play.route": {
     actions: assign({
@@ -675,7 +719,7 @@ on: {
 
 **Fix:** Every state with `meta.route` must declare an explicit `id`:
 
-```typescript
+```typescript fragment
 // ❌ Missing id
 home: { meta: { route: "/" } }
 
@@ -690,6 +734,12 @@ home: { id: "home", meta: { route: "/" } }
 **Fix:** Always call `actor.start()` before `actor.send()`:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start(); // required before any send()
 actor.send({ type: "toggle" });
@@ -701,7 +751,7 @@ actor.send({ type: "toggle" });
 
 **Fix:** Construct stable references outside JSX or memoize them:
 
-```typescript
+```typescript fragment
 // ✅ Built outside the component
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);