@xmachines/docs 1.0.0-beta.27 → 1.0.0-beta.29

package/examples/@xmachines/play-actor-shared/variables/authMachine.md

@@ -0,0 +1,189 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / authMachine
+
+# Variable: authMachine
+
+```ts
+const authMachine: StateMachine<AuthContext, AuthEvents, {
+}, never, never, never, never,
+  | "login"
+  | "home"
+  | "about"
+  | "contact"
+  | "profile"
+  | "settings"
+  | {
+  dashboard: "overview" | "stats";
+}, string, AuthInput, NonReducibleUnknown, EventObject, MetaObject, ToStateSchema<{
+  context: (__namedParameters) => object;
+  id: string;
+  initial: string;
+  on: {
+     auth.login: {
+        actions: ActionFunction<AuthContext, AuthEvents, AuthEvents, undefined, never, never, never, never, never>;
+        guard: (__namedParameters) => boolean;
+        target: string;
+     };
+     auth.logout: {
+        actions: ActionFunction<AuthContext, AuthEvents, AuthEvents, undefined, never, never, never, never, never>;
+        guard: (__namedParameters) => boolean;
+        target: string;
+     };
+  };
+  states: {
+     about: {
+        id: string;
+        meta: {
+           route: string;
+           view: {
+              component: string;
+              spec: {
+                 elements: {
+                    root: {
+                       children: ...[];
+                       props: {
+                          title: ...;
+                       };
+                       type: string;
+                    };
+                 };
+                 root: string;
+              };
+           };
+        };
+     };
+     contact: {
+        id: string;
+        meta: {
+           route: string;
+           view: {
+              component: string;
+              spec: {
+                 elements: {
+                    root: {
+                       children: ...[];
+                       props: {
+                          title: ...;
+                       };
+                       type: string;
+                    };
+                 };
+                 root: string;
+              };
+           };
+        };
+     };
+     dashboard: {
+        always: {
+           guard: (__namedParameters) => boolean;
+           target: string;
+        };
+        id: string;
+        initial: string;
+        meta: {
+           route: string;
+        };
+        states: {
+           overview: {
+              id: string;
+              meta: {
+                 route: string;
+                 view: {
+                    component: string;
+                    spec: PlaySpec;
+                 };
+              };
+           };
+           stats: {
+              id: string;
+              meta: {
+                 route: string;
+                 view: {
+                    component: string;
+                    spec: PlaySpec;
+                 };
+              };
+           };
+        };
+     };
+     home: {
+        id: string;
+        meta: {
+           route: string;
+           view: {
+              component: string;
+              spec: {
+                 elements: {
+                    root: {
+                       children: ...[];
+                       props: {
+                          title: ...;
+                       };
+                       type: string;
+                    };
+                 };
+                 root: string;
+              };
+           };
+        };
+     };
+     login: {
+        id: string;
+        meta: {
+           route: string;
+           view: {
+              component: string;
+              spec: {
+                 elements: {
+                    root: {
+                       children: ...[];
+                       on: {
+                          submit: ...;
+                       };
+                       props: {
+                          title: ...;
+                          username: ...;
+                       };
+                       type: string;
+                    };
+                 };
+                 root: string;
+                 state: {
+                    username: string;
+                 };
+              };
+           };
+        };
+     };
+     profile: {
+        always: {
+           guard: (__namedParameters) => boolean;
+           target: string;
+        };
+        id: string;
+        meta: {
+           route: string;
+           view: {
+              component: string;
+              spec: PlaySpec;
+           };
+        };
+     };
+     settings: {
+        always: {
+           guard: (__namedParameters) => boolean;
+           target: string;
+        };
+        id: string;
+        meta: {
+           route: string;
+           view: {
+              component: string;
+              spec: PlaySpec;
+           };
+        };
+     };
+  };
+}>>;
+```
+
+Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L49)

package/examples/@xmachines/play-actor-shared/variables/authSetup.md

@@ -0,0 +1,22 @@
+[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / authSetup
+
+# Variable: authSetup
+
+```ts
+const authSetup: SetupReturn<
+	AuthContext,
+	AuthEvents,
+	{},
+	{},
+	{},
+	{},
+	never,
+	string,
+	AuthInput,
+	NonReducibleUnknown,
+	EventObject,
+	MetaObject
+>;
+```
+
+Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L41)

package/examples/@xmachines/play-dom-demo/README.md

@@ -0,0 +1,145 @@
+[Documentation](../../README.md) / @xmachines/play-dom-demo
+
+# Vanilla DOM Demo
+
+Vanilla DOM renderer demo for `@xmachines/play-dom` — actor + `connectRenderer` without a router.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `connectRenderer` wiring `PlayRenderer`-equivalent DOM rendering without a framework
+- Auth machine states (home → login → dashboard) drive DOM updates via TC39 Signal watchers
+- `watchSignal` for reactive nav visibility and debug panel updates
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-dom-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` calls `definePlayer({ machine: authMachine })` and starts the actor.
+2. `initShell(actor, app)` from `src/shell.ts` builds the HTML scaffold and registers all event listeners.
+3. `makeComponents(actor)` constructs a `DomRegistry` of stateless and stateful `DomComponentRenderer` functions.
+4. `connectRenderer({ actor, registry, container })` wires the registry to the actor — view switches happen automatically when actor state changes.
+5. `watchSignal(actor.state, ...)` drives nav login/logout button visibility and the debug panel.
+6. Browser tests in `test/browser/` validate startup rendering and auth interactions.
+
+```ts
+// src/main.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const app = document.getElementById("app");
+if (app) {
+	initShell(actor, app);
+}
+```
+
+```ts
+// src/shell.ts (shape)
+const disconnectRenderer = connectRenderer({
+	actor,
+	registry,
+	container: viewContent,
+});
+
+const unwatchState = watchSignal(actor.state, () => {
+	const snapshot = actor.getSnapshot();
+	navLogin.hidden = snapshot.context.isAuthenticated;
+	navLogout.hidden = !snapshot.context.isAuthenticated;
+});
+```
+
+```ts
+// src/shell.ts — sending events (shape)
+actor.send({ type: "play.route", to: "#login" });
+actor.send({ type: "auth.login", username });
+actor.send({ type: "auth.logout" });
+```
+
+## Key Files
+
+- `src/main.ts` - actor creation and shell bootstrap
+- `src/shell.ts` - DOM scaffold, `DomRegistry` construction, `connectRenderer` wiring, and `watchSignal` for reactive nav and debug panel
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** Navigation buttons dispatch `play.route` events to the actor. The actor evaluates guards and transitions to the correct state — the DOM never decides which view to show.
+2. **Passive Infrastructure:** `connectRenderer` and `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
+3. **Signal-Only Reactivity:** `watchSignal` (from `@xmachines/play-signals`) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and project DOM state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: both `disconnectRenderer()` and `unwatchState()` must be called to avoid memory leaks. In this demo, cleanup is returned from `initShell` and called on `beforeunload`.
+
+## Adapter Boundaries
+
+`connectRenderer` (from `@xmachines/play-dom`) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                            | Description                      |
+| -------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-dom-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-dom-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-dom-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-dom-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-dom-demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+npm run test -w @xmachines/play-dom-demo
+npm run test:browser -w @xmachines/play-dom-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Play DOM package README](../../README.md)
+- [Play DOM Router demo README](../../../play-dom-router/examples/demo/README.md)
+
+## Variables
+
+- [About](variables/About.md)
+- [Contact](variables/Contact.md)
+- [Dashboard](variables/Dashboard.md)
+- [Home](variables/Home.md)
+- [Login](variables/Login.md)
+- [Navigation](variables/Navigation.md)
+- [Overview](variables/Overview.md)
+- [Profile](variables/Profile.md)
+- [Settings](variables/Settings.md)
+- [Stats](variables/Stats.md)
+
+## Functions
+
+- [initShell](functions/initShell.md)

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / initShell
+
+# Function: initShell()
+
+```ts
+function initShell(actor, appElement): () => void;
+```
+
+Defined in: [shell.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/shell.ts#L32)
+
+## Parameters
+
+| Parameter    | Type                                                             |
+| ------------ | ---------------------------------------------------------------- |
+| `actor`      | [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md) |
+| `appElement` | `HTMLElement`                                                    |
+
+## Returns
+
+() => `void`

package/examples/@xmachines/play-dom-demo/variables/About.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+const About: ComponentFn<AuthCatalog, "About">;
+```
+
+Defined in: [components/About.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/About.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Contact.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+const Contact: ComponentFn<AuthCatalog, "Contact">;
+```
+
+Defined in: [components/Contact.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Contact.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Dashboard.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
+```
+
+Defined in: [components/Dashboard.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Dashboard.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Home.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+const Home: ComponentFn<AuthCatalog, "Home">;
+```
+
+Defined in: [components/Home.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Home.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Login.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login">;
+```
+
+Defined in: [components/Login.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Login.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Navigation.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+const Navigation: ComponentFn<AuthCatalog, "Navigation">;
+```
+
+Defined in: [components/Navigation.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Navigation.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Overview.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+const Overview: ComponentFn<AuthCatalog, "Overview">;
+```
+
+Defined in: [components/Overview.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Overview.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Profile.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+const Profile: ComponentFn<AuthCatalog, "Profile">;
+```
+
+Defined in: [components/Profile.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Profile.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Settings.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+const Settings: ComponentFn<AuthCatalog, "Settings">;
+```
+
+Defined in: [components/Settings.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Settings.ts#L4)

package/examples/@xmachines/play-dom-demo/variables/Stats.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+const Stats: ComponentFn<AuthCatalog, "Stats">;
+```
+
+Defined in: [components/Stats.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/examples/demo/src/components/Stats.ts#L4)

package/{api → examples}/@xmachines/play-dom-router-demo/README.md

@@ -18,7 +18,7 @@ From the repository root:
 
 ```bash
 npm install
-npm run dev -w packages/play-dom-router/examples/demo
+npm run dev -w @xmachines/play-dom-router-demo
 ```
 
 Then open `http://localhost:5174`.
@@ -110,27 +110,27 @@ Watcher notifications are one-shot, so re-arm is mandatory. Router/shell teardow
 
 These commands are defined in `package.json`:
 
-| Command                                                          | Description                      |
-| ---------------------------------------------------------------- | -------------------------------- |
-| `npm run dev -w packages/play-dom-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-dom-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-dom-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-dom-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-dom-router/examples/demo` | Run browser-focused Vitest suite |
+| Command                                                   | Description                      |
+| --------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-dom-router-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-dom-router-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-dom-router-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-dom-router-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-dom-router-demo` | Run browser-focused Vitest suite |
 
 ## Verification
 
 Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test -w packages/play-dom-router/examples/demo
-npm run test:browser -w packages/play-dom-router/examples/demo
+npm run test -w @xmachines/play-dom-router-demo
+npm run test:browser -w @xmachines/play-dom-router-demo
 ```
 
 Expected result: tests pass, including startup rendering and the full browser auth flow in `test/browser/`.
 
 ## Learn More
 
-- [Play DOM Router package README](../play-dom-router/README.md)
-- [Play DOM demo README](../../../examples/README.md)
-- [Play Router package README](../play-router/README.md)
+- [Play DOM Router package README](../../README.md)
+- [Play DOM demo README](../../../play-dom/examples/demo/README.md)
+- [Play Router package README](../../../play-router/README.md)