@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-tanstack-solid-router/type-aliases/TanStackRouterInstance.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / TanStackRouterInstance
+
+# Type Alias: TanStackRouterInstance
+
+```ts
+type TanStackRouterInstance = ConstructorParameters<typeof SolidRouterBridge>[0];
+```
+
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L8)

package/api/@xmachines/play-tanstack-solid-router/type-aliases/TanStackRouterLike.md

@@ -0,0 +1,78 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / TanStackRouterLike
+
+# Type Alias: TanStackRouterLike
+
+```ts
+type TanStackRouterLike = object;
+```
+
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L28)
+
+## Properties
+
+### history
+
+```ts
+history: object;
+```
+
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L31)
+
+#### subscribe()
+
+```ts
+subscribe(handler): () => void;
+```
+
+##### Parameters
+
+| Parameter | Type                |
+| --------- | ------------------- |
+| `handler` | (`event`) => `void` |
+
+##### Returns
+
+() => `void`
+
+---
+
+### state?
+
+```ts
+optional state?: object;
+```
+
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L30)
+
+#### location?
+
+```ts
+optional location?: object;
+```
+
+##### location.pathname?
+
+```ts
+optional pathname?: string;
+```
+
+## Methods
+
+### navigate()
+
+```ts
+navigate(args): void;
+```
+
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L29)
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `args`    | \{ `to`: `string`; \} |
+| `args.to` | `string`              |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-tanstack-solid-router-demo/README.md

@@ -0,0 +1,126 @@
+[Documentation](../../README.md) / @xmachines/play-tanstack-solid-router-demo
+
+# TanStack Solid Router Demo
+
+Solid + `@tanstack/solid-router` demonstration of the Play architecture with TanStack router integration.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with TanStack Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Object-based routing and deep location observation using TanStack's Solid primitives
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From this directory (`packages/play-tanstack-solid-router/examples/demo`):
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` bootstraps the demo app and mounts `<App />`.
+2. `src/App.tsx` sets up actor lifecycle, route mapping, and TanStack Solid router integration.
+3. Shared machine/catalog logic comes from the common demo module to keep business logic framework-agnostic.
+4. Router infrastructure stays passive: it forwards navigation intent to the actor via the `PlayRouterProvider` and reflects actor-approved route changes back to TanStack.
+5. `Shell` (inside `src/App.tsx`) renders actor-projected state (`PlayRenderer`) and emits actor events.
+6. `test/library-pattern.test.ts` plus `test/browser/` verify invariants and browser routing behavior.
+
+```tsx
+// src/main.tsx (shape)
+render(() => <App />, document.getElementById("root")!);
+```
+
+```tsx
+// src/App.tsx (shape)
+const routeTree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMap(authMachine);
+
+return (
+	<PlayRouterProvider
+		actor={actor}
+		router={router}
+		routeMap={routeMap}
+		renderer={(currentActor, currentRouter) => (
+			<Shell actor={currentActor} router={currentRouter} />
+		)}
+	/>
+);
+```
+
+```tsx
+// src/components/Login.tsx (shape)
+<button onClick={() => actor.send({ type: "auth.login", username, password })}>Login</button>
+```
+
+## Key Files
+
+- `src/App.tsx` - Wires actor lifecycle, route map, TanStack router setup, and provider/renderer integration.
+- `src/main.tsx` - Vite bootstrap for the Solid TanStack demo.
+- `src/components/` - Demo views that dispatch machine events.
+- `test/library-pattern.test.ts` - Invariant and architecture checks for package behavior.
+- `test/browser/startup.browser.test.ts` - Browser startup and wiring checks.
+- `test/browser/auth-flow.browser.test.ts` - Browser auth + route-flow checks.
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user clicks a link, TanStack Router updates the location object. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards and applies state transitions.
+2. **Passive Infrastructure:** The router does not execute route loaders or guards for business logic. The actor dictates whether navigation is permitted.
+3. **Signal-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.subscribe` to effortlessly observe location changes and signal updates.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and trigger state updates
+5. Re-arm with `watch()`/`watch(...signals)`
+
+In Solid, this is largely abstracted by `createEffect` within the bridge adapter. Cleanup remains explicit: the provider executes `bridge.disconnect()` on unmount (`onCleanup`) to prevent ghost subscriptions, ensuring safe component teardown and hot module replacement.
+
+## Adapter Boundaries
+
+The TanStack Solid adapter wraps TanStack's `router.navigate({ to })` and `router.subscribe` methods while delegating core synchronization policy to `RouterBridgeBase`. This keeps complex double-dispatch logic normalized across all frameworks.
+
+## Available Scripts
+
+```bash
+npm run dev           # Start Vite dev server (default: http://localhost:5173)
+npm run build         # Build production assets
+npm run preview       # Preview production build locally
+npm run test          # Run unit/integration tests via Vitest
+npm run test:browser  # Run browser-mode tests via vitest.browser.config.ts
+```
+
+## Verification
+
+Use these checks from this directory:
+
+```bash
+npm run test
+npm run test:browser
+```
+
+Manual sanity check:
+
+1. Start with `npm run dev`.
+2. Open `http://localhost:5173`.
+3. Verify login/logout transitions and URL updates remain actor-driven, including protected route redirection.
+
+## Learn More
+
+- [TanStack Solid Router package README](../play-tanstack-solid-router/README.md)
+- [Solid Router demo README](../play-solid-router-demo/README.md)
+- [TanStack React Router demo README](../play-tanstack-react-router-demo/README.md)

package/api/@xmachines/play-vue/README.md

@@ -0,0 +1,292 @@
+[Documentation](../../README.md) / @xmachines/play-vue
+
+# @xmachines/play-vue
+
+**Vue renderer consuming signals and UI schema with provider pattern**
+
+Signal-driven Vue rendering layer observing actor state with zero Vue state for business logic.
+
+## Overview
+
+`@xmachines/play-vue` provides `PlayRenderer` for building Vue 3 UIs that passively observe actor signals. This package enables framework-swappable architecture where Vue is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+
+- **Signal-Only Reactivity (INV-05):** No refs/reactive for business logic, TC39 signals only
+- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
+
+**Key Principle:** Vue state is never used for business logic. Signals are the source of truth.
+
+Renderer receives actor via props (provider pattern), not children.
+
+## Installation
+
+```bash
+npm install vue@^3.5.0
+npm install @xmachines/play-vue
+```
+
+## Current Exports
+
+- `PlayRenderer` (Vue component)
+- `PlayRendererProps` (TypeScript interface)
+
+**Peer dependencies:**
+
+- `vue` ^3.5.0 — Vue 3 runtime
+
+## Quick Start
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { definePlayer } from "@xmachines/play-xstate";
+import { defineCatalog } from "@xmachines/play-catalog";
+import { PlayRenderer } from "@xmachines/play-vue";
+import { z } from "zod";
+import LoginForm from "./components/LoginForm.vue";
+import Dashboard from "./components/Dashboard.vue";
+
+// 1. Define catalog (business logic layer)
+const catalog = defineCatalog({
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({
+		userId: z.string(),
+		username: z.string(),
+	}),
+});
+
+// 2. Define component map (view layer)
+const components = {
+	LoginForm,
+	Dashboard,
+};
+
+// 3. Create player actor (business logic runtime)
+const createPlayer = definePlayer({ machine: authMachine, catalog });
+const actor = createPlayer();
+actor.start();
+</script>
+
+<template>
+	<!-- 4. Render UI (actor via props) -->
+	<PlayRenderer :actor="actor" :components="components">
+		<template #fallback>
+			<div>Loading...</div>
+		</template>
+	</PlayRenderer>
+</template>
+```
+
+## API Reference
+
+### PlayRenderer
+
+Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+
+```typescript
+interface PlayRendererProps {
+	actor: AbstractActor<any>;
+	components: Record<string, Component>;
+}
+```
+
+**Props:**
+
+- `actor` - Actor instance with `currentView` signal
+- `components` - Map of component names to Vue components
+
+**Slots:**
+
+- `fallback` - Slot shown when `currentView` is null
+
+**Behavior:**
+
+1. Subscribes to `actor.currentView` signal using a `Signal.subtle.Watcher` inside a Vue component
+2. Looks up component from `components` map using `view.component` string
+3. Renders component with props from `view.props` + `send` function via Vue's dynamic `<component :is="..."/>`
+
+**Example Component (LoginForm.vue):**
+
+```vue
+<script setup lang="ts">
+import type { AbstractActor } from "@xmachines/play-actor";
+import { ref } from "vue";
+
+const props = defineProps<{
+	error?: string;
+	send: AbstractActor<any>["send"];
+}>();
+
+const username = ref("");
+
+function handleSubmit() {
+	props.send({
+		type: "auth.login",
+		username: username.value,
+	});
+}
+</script>
+
+<template>
+	<form @submit.prevent="handleSubmit">
+		<p v-if="error" style="color: red">{{ error }}</p>
+		<input v-model="username" required placeholder="Username" />
+		<button type="submit">Log In</button>
+	</form>
+</template>
+```
+
+## Examples
+
+### Provider Pattern
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { PlayVueRouterProvider } from "@xmachines/play-vue-router";
+import { PlayRenderer } from "@xmachines/play-vue";
+import { provide } from "vue";
+import Header from "./components/Header.vue";
+import Footer from "./components/Footer.vue";
+
+// Provide actor to nested components like Header
+provide("actor", actor);
+</script>
+
+<template>
+	<PlayVueRouterProvider :actor="actor" :router="router" :routeMap="routeMap">
+		<template #default="{ currentActor, currentRouter }">
+			<div>
+				<Header />
+				<PlayRenderer :actor="currentActor" :components="components" />
+				<Footer />
+			</div>
+		</template>
+	</PlayVueRouterProvider>
+</template>
+```
+
+```vue
+<!-- Header.vue -->
+<script setup lang="ts">
+import { inject, ref, onMounted, onUnmounted } from "vue";
+import type { AbstractActor } from "@xmachines/play-actor";
+
+const actor = inject<AbstractActor<any>>("actor")!;
+const route = ref<string | null>(null);
+
+let watcher: any;
+
+onMounted(() => {
+	let pending = false;
+	watcher = new Signal.subtle.Watcher(() => {
+		if (!pending) {
+			pending = true;
+			queueMicrotask(() => {
+				pending = false;
+				for (const s of watcher.getPending()) s.get();
+				route.value = actor.currentRoute.get();
+				watcher.watch(actor.currentRoute);
+			});
+		}
+	});
+	route.value = actor.currentRoute.get();
+	watcher.watch(actor.currentRoute);
+});
+
+onUnmounted(() => {
+	if (watcher) watcher.unwatch(actor.currentRoute);
+});
+</script>
+
+<template>
+	<header>
+		<nav>Current: {{ route }}</nav>
+	</header>
+</template>
+```
+
+## Architecture
+
+This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+
+1. **No Business Logic in Vue:**
+    - No ref/reactive for business state
+    - No watch/watchEffect for business side effects
+    - Vue only triggers renders, doesn't control state
+
+2. **Signals as Source of Truth:**
+    - `actor.currentView.get()` provides UI structure
+    - `actor.currentRoute.get()` provides navigation state
+    - Components observe signals via explicit watcher patterns
+
+3. **Event Forwarding:**
+    - Components receive `send` function via props
+    - User actions send events to actor (e.g., `{ type: "auth.login" }`)
+    - Actor guards validate and process events
+
+4. **Microtask Batching:**
+    - `Signal.subtle.Watcher` coalesces rapid signal changes
+    - Prevents Vue thrashing from multiple signal updates
+    - Single Vue render per microtask batch
+
+5. **Explicit Disposal Contract:**
+    - Component teardown calls watcher `unwatch` in `onUnmounted`
+    - Do not rely on GC-only cleanup
+
+**Pattern:**
+
+- Renderer receives actor via props (provider pattern)
+- Enables composition with navigation, headers, footers
+- Supports multiple renderers in same app
+
+**Architectural Invariants:**
+
+- **Signal-Only Reactivity (INV-05):** No Vue state for business logic
+- **Passive Infrastructure (INV-04):** Components reflect, never decide
+
+## Canonical Watcher Lifecycle
+
+If you write your own custom integration, use the same watcher flow as `PlayRenderer`:
+
+1. `notify` callback runs
+2. Schedule work with `queueMicrotask`
+3. Drain `watcher.getPending()`
+4. Read actor signals and update Vue-local ref state
+5. Re-arm with `watch(...)` or `watch()`
+
+Watcher notify is one-shot. Re-arm is required for continuous observation.
+
+## Benefits
+
+- **Framework Swappable:** Business logic has zero Vue imports
+- **Type Safety:** Props validated against catalog schemas
+- **Simple Testing:** Test actors without Vue renderer
+- **Performance:** Microtask batching reduces unnecessary renders
+- **Composability:** Renderer prop enables complex layouts
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter providing actors
+- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
+- **[@xmachines/play-vue-router](../play-vue-router/README.md)** - Vue Router integration
+- **[@xmachines/play-actor](../play-actor/README.md)** - Actor base
+- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
+
+## License
+
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.
+
+@xmachines/play-vue - Vue renderer for XMachines Play architecture
+
+## Interfaces
+
+- [PlayRendererProps](interfaces/PlayRendererProps.md)
+
+## Variables
+
+- [PlayRenderer](variables/PlayRenderer.md)

package/api/@xmachines/play-vue/interfaces/PlayRendererProps.md

@@ -0,0 +1,14 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / PlayRendererProps
+
+# Interface: PlayRendererProps
+
+Defined in: [types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue/src/types.ts#L17)
+
+Props for PlayRenderer component
+
+## Properties
+
+| Property                                      | Type                                                                                                                                    | Description                                                           | Defined in                                                                                                                                   |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`           | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability) | [types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue/src/types.ts#L19) |
+| <a id="property-components"></a> `components` | `Record`\<`string`, `Component`\>                                                                                                       | Map of component names to Vue components                              | [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue/src/types.ts#L22) |

package/api/@xmachines/play-vue/variables/PlayRenderer.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / PlayRenderer
+
+# Variable: PlayRenderer
+
+```ts
+const PlayRenderer: DefineComponent<{}, {}, unknown>;
+```
+
+Defined in: [vue-shim.d.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-vue/src/vue-shim.d.ts#L3)