@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-catalog/functions/defineCatalog.md

@@ -1,98 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / defineCatalog
-
-# Function: defineCatalog()
-
-```ts
-function defineCatalog<TCatalog>(schemas): TCatalog;
-```
-
-Defined in: [define-catalog.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-catalog.ts#L74)
-
-Define component catalog with Zod schemas for type-safe UI projection
-
-Creates a catalog mapping component names to their prop schemas using Zod validators.
-The catalog enables **Strict Separation (INV-02)** by defining UI vocabulary in
-framework-agnostic terms that the Actor can reference without coupling to React/Vue/etc.
-
-**Architectural Context:** Implements **Strict Separation (INV-02)** where business
-logic (state machine) has zero framework imports. The catalog serves as the contract
-between Actor (which references component names in `meta.view`) and Infrastructure
-(which renders actual framework components).
-
-## Type Parameters
-
-| Type Parameter                                                                                                            |
-| ------------------------------------------------------------------------------------------------------------------------- |
-| `TCatalog` _extends_ `Record`\<`string`, `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\> |
-
-## Parameters
-
-| Parameter | Type       | Description                                   |
-| --------- | ---------- | --------------------------------------------- |
-| `schemas` | `TCatalog` | Record mapping component names to Zod schemas |
-
-## Returns
-
-`TCatalog`
-
-Typed catalog object with schema entries (frozen in development for immutability)
-
-## Examples
-
-Basic catalog definition
-
-```typescript
-import { z } from "zod";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const catalog = defineCatalog({
-	Dashboard: z.object({ userId: z.string() }),
-	LoginForm: z.object({ error: z.string().optional() }),
-});
-
-// TypeScript infers catalog type automatically
-type CatalogType = typeof catalog;
-```
-
-Progressive catalog with multiple components
-
-```typescript
-import { z } from "zod";
-import { defineCatalog } from "@xmachines/play-catalog";
-
-const catalog = defineCatalog({
-	// Public pages
-	HomePage: z.object({}),
-	AboutPage: z.object({}),
-
-	// Auth components
-	LoginForm: z.object({
-		error: z.string().optional(),
-		returnUrl: z.string().optional(),
-	}),
-
-	// Protected pages
-	Dashboard: z.object({
-		userId: z.string(),
-		stats: z.object({
-			views: z.number(),
-			clicks: z.number(),
-		}),
-	}),
-});
-```
-
-## See
-
-- [RFC Play v1 - Invariant INV-02](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
-- [defineComponents](defineComponents.md) for binding components to catalog
-- [Catalog](../type-aliases/Catalog.md) for the catalog type definition
-
-## Remarks
-
-**Primary Purpose:** Type inference. The returned catalog object is primarily used
-for TypeScript type inference. Runtime validation happens at state entry when the
-Actor attempts to project a view through the renderer.
-
-**Immutability:** In development mode, the catalog is frozen via `Object.freeze()`
-to prevent accidental mutation. In production, freezing is skipped for performance.

package/api/@xmachines/play-catalog/functions/defineComponents.md

@@ -1,134 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / defineComponents
-
-# Function: defineComponents()
-
-```ts
-function defineComponents<TCatalog, TComponents>(
-	catalog,
-	components,
-): NoExtraKeys<TComponents, TCatalog>;
-```
-
-Defined in: [define-components.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-components.ts#L116)
-
-Define components matching catalog schema with compile-time validation
-
-Enforces bidirectional validation between catalog and component implementations:
-
-- All catalog keys must have corresponding components (no missing components)
-- No extra components outside catalog (no undefined keys)
-- TypeScript compilation fails for mismatches (build-time safety)
-
-**Architectural Context:** Implements **Strict Separation (INV-02)** by validating
-that framework components (React/Vue/etc.) exactly match the framework-agnostic
-catalog that the Actor references. This ensures the Actor can reference component
-names in `meta.view` without importing framework code.
-
-## Type Parameters
-
-| Type Parameter                                                                                                            |
-| ------------------------------------------------------------------------------------------------------------------------- |
-| `TCatalog` _extends_ `Record`\<`string`, `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\> |
-| `TComponents` _extends_ [`ComponentsFor`](../type-aliases/ComponentsFor.md)\<`TCatalog`\>                                 |
-
-## Parameters
-
-| Parameter    | Type                                                                         | Description                                             |
-| ------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------- |
-| `catalog`    | `TCatalog`                                                                   | Component catalog with Zod schemas                      |
-| `components` | [`NoExtraKeys`](../type-aliases/NoExtraKeys.md)\<`TComponents`, `TCatalog`\> | Component implementations matching catalog keys exactly |
-
-## Returns
-
-[`NoExtraKeys`](../type-aliases/NoExtraKeys.md)\<`TComponents`, `TCatalog`\>
-
-Component map validated at compile time (frozen in development)
-
-## Throws
-
-Error if runtime validation detects missing or extra keys
-
-## Examples
-
-Valid component definition
-
-```typescript
-import { defineComponents } from "@xmachines/play-catalog";
-import { catalog } from "./catalog.js";
-import { DashboardComponent, LoginFormComponent } from "./components.js";
-
-// ✅ Valid - all keys match catalog
-const components = defineComponents(catalog, {
-	Dashboard: DashboardComponent,
-	LoginForm: LoginFormComponent,
-});
-```
-
-TypeScript compile errors
-
-```typescript
-import { defineComponents } from "@xmachines/play-catalog";
-import { catalog } from "./catalog.js";
-
-// ❌ TypeScript error - missing 'LoginForm'
-const components = defineComponents(catalog, {
-	Dashboard: DashboardComponent,
-});
-
-// ❌ TypeScript error - extra 'UnknownComponent' not in catalog
-const components = defineComponents(catalog, {
-	Dashboard: DashboardComponent,
-	LoginForm: LoginFormComponent,
-	UnknownComponent: SomeComponent,
-});
-```
-
-Progressive example with Actor integration
-
-```typescript
-import { z } from "zod";
-import { defineCatalog, defineComponents } from "@xmachines/play-catalog";
-import { definePlayer } from "@xmachines/play-xstate";
-import { setup } from "xstate";
-
-// 1. Define catalog
-const catalog = defineCatalog({
-  HomePage: z.object({}),
-  Dashboard: z.object({ userId: z.string() })
-});
-
-// 2. Define components
-const components = defineComponents(catalog, {
-  HomePage: () => <div>Home</div>,
-  Dashboard: ({ userId }) => <div>Dashboard for {userId}</div>
-});
-
-// 3. Create machine referencing catalog components
-const machine = setup({}).createMachine({
-  initial: 'home',
-  states: {
-    home: {
-      meta: {
-        route: '/',
-        view: { component: 'HomePage' } // References catalog key
-      }
-    },
-    dashboard: {
-      meta: {
-        route: '/dashboard',
-        view: { component: 'Dashboard', userId: '123' }
-      }
-    }
-  }
-});
-
-// 4. Create actor with catalog
-const createPlayer = definePlayer({ machine, catalog });
-const actor = createPlayer();
-```
-
-## See
-
-- [RFC Play v1 - Invariant INV-02](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
-- [defineCatalog](defineCatalog.md) for creating the catalog schema
-- [Catalog](../type-aliases/Catalog.md) for the catalog type definition

package/api/@xmachines/play-catalog/type-aliases/Catalog.md

@@ -1,48 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / Catalog
-
-# Type Alias: Catalog\<TCatalog\>
-
-```ts
-type Catalog<TCatalog> = TCatalog;
-```
-
-Defined in: [types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/types.ts#L35)
-
-Component catalog mapping component names to Zod prop schemas
-
-Generic type that maps component name strings to their Zod schema validators.
-The catalog enables type-safe UI projection by defining the vocabulary of
-components that the Actor can reference in `meta.view` without coupling to
-framework implementations.
-
-## Type Parameters
-
-| Type Parameter                                         | Default type                      | Description                                        |
-| ------------------------------------------------------ | --------------------------------- | -------------------------------------------------- |
-| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> | `Record`\<`string`, `z.ZodType`\> | Record mapping component names to Zod schema types |
-
-## Example
-
-Basic catalog type
-
-```typescript
-import { z } from "zod";
-import { defineCatalog } from "@xmachines/play-catalog";
-import type { Catalog } from "@xmachines/play-catalog";
-
-const catalog = defineCatalog({
-	Dashboard: z.object({ userId: z.string() }),
-	LoginForm: z.object({ error: z.string().optional() }),
-});
-
-type MyCatalog = typeof catalog;
-// Inferred as: Catalog<{
-//   Dashboard: z.ZodObject<...>,
-//   LoginForm: z.ZodObject<...>
-// }>
-```
-
-## See
-
-- [defineCatalog](../functions/defineCatalog.md) for creating catalog instances
-- [InferComponentProps](InferComponentProps.md) for extracting prop types

package/api/@xmachines/play-catalog/type-aliases/ComponentsFor.md

@@ -1,20 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / ComponentsFor
-
-# Type Alias: ComponentsFor\<TCatalog\>
-
-```ts
-type ComponentsFor<TCatalog> = { [K in keyof TCatalog]: unknown };
-```
-
-Defined in: [define-components.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-components.ts#L10)
-
-Component map type enforcing catalog keys
-
-Mapped type ensures components object has exactly catalog keys - no missing, no extra.
-This provides compile-time validation that framework components match the catalog schema.
-
-## Type Parameters
-
-| Type Parameter                                         |
-| ------------------------------------------------------ |
-| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> |

package/api/@xmachines/play-catalog/type-aliases/InferComponentProps.md

@@ -1,65 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / InferComponentProps
-
-# Type Alias: InferComponentProps\<TCatalog, TKey\>
-
-```ts
-type InferComponentProps<TCatalog, TKey> = z.infer<TCatalog[TKey]>;
-```
-
-Defined in: [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/types.ts#L84)
-
-Infer component prop types from catalog entry
-
-Utility type that extracts the TypeScript type of a component's props from its
-Zod schema definition in the catalog. Enables type-safe component implementations
-that match the catalog schema.
-
-## Type Parameters
-
-| Type Parameter                                         | Description                                           |
-| ------------------------------------------------------ | ----------------------------------------------------- |
-| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> | Catalog record mapping component names to Zod schemas |
-| `TKey` _extends_ keyof `TCatalog`                      | Specific component key to extract props for           |
-
-## Returns
-
-TypeScript type inferred from the Zod schema
-
-## Example
-
-Extracting prop types for components
-
-```typescript
-import { z } from "zod";
-import { defineCatalog } from "@xmachines/play-catalog";
-import type { InferComponentProps } from "@xmachines/play-catalog";
-
-const catalog = defineCatalog({
-  Dashboard: z.object({
-    userId: z.string(),
-    stats: z.object({
-      views: z.number(),
-      clicks: z.number()
-    })
-  })
-});
-
-type DashboardProps = InferComponentProps<typeof catalog, 'Dashboard'>;
-// Inferred as: {
-//   userId: string;
-//   stats: {
-//     views: number;
-//     clicks: number;
-//   };
-// }
-
-// Use in React component
-function Dashboard({ userId, stats }: DashboardProps) {
-  return <div>{userId}: {stats.views} views</div>;
-}
-```
-
-## See
-
-- [Catalog](Catalog.md) for the catalog type definition
-- [defineCatalog](../functions/defineCatalog.md) for creating catalog instances

package/api/@xmachines/play-catalog/type-aliases/NoExtraKeys.md

@@ -1,17 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / NoExtraKeys
-
-# Type Alias: NoExtraKeys\<TComponents, TCatalog\>
-
-```ts
-type NoExtraKeys<TComponents, TCatalog> = TComponents &
-	Record<Exclude<keyof TComponents, keyof TCatalog>, never>;
-```
-
-Defined in: [define-components.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-components.ts#L14)
-
-## Type Parameters
-
-| Type Parameter                                         |
-| ------------------------------------------------------ |
-| `TComponents`                                          |
-| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> |

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

@@ -1,15 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / PlayRendererProps
-
-# Interface: PlayRendererProps
-
-Defined in: [packages/play-react/src/types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/types.ts#L18)
-
-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) | [packages/play-react/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/types.ts#L20) |
-| <a id="property-components"></a> `components` | `Record`\<`string`, `React.ElementType`\>                                                                                               | Map of component names to React components                            | [packages/play-react/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/types.ts#L23) |
-| <a id="property-fallback"></a> `fallback?`    | `ReactNode`                                                                                                                             | Optional component shown when currentView is null                     | [packages/play-react/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react/src/types.ts#L26) |

package/api/@xmachines/play-react-router/functions/PlayRouterProvider.md

@@ -1,19 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProvider
-
-# Function: PlayRouterProvider()
-
-```ts
-function PlayRouterProvider(__namedParameters): Element;
-```
-
-Defined in: [play-react-router/src/play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L20)
-
-## Parameters
-
-| Parameter           | Type                                                                  |
-| ------------------- | --------------------------------------------------------------------- |
-| `__namedParameters` | [`PlayRouterProviderProps`](../interfaces/PlayRouterProviderProps.md) |
-
-## Returns
-
-`Element`

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

@@ -1,137 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-react-router-demo
-
-# React Router Demo
-
-React Router v7 integration demo for the XMachines Play architecture.
-
-## What This Demonstrates
-
-- Shared auth machine reused without framework-specific business logic
-- `PlayRouterProvider` renderer-based integration with React Router
-- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Canonical TC39 Signals lifecycle mapped to React's rendering loop
-- Non-browser invariant tests plus browser E2E coverage
-
-## Running the Demo
-
-From the repository root:
-
-```bash
-npm install
-npm run dev -w packages/play-react-router/examples/demo
-```
-
-Then open `http://localhost:5173`.
-
-## Step-by-Step Code Flow
-
-Use this order to understand the implementation:
-
-1. `src/main.tsx` mounts `<App />`.
-2. `src/App.tsx` creates/starts the actor from shared machine + catalog.
-3. Route metadata is extracted from the machine and converted into a route map.
-4. `PlayRouterProvider` wires `createBrowserRouter` and actor navigation in both directions.
-5. `Shell` (inside `App.tsx`) renders `PlayRenderer` and actor-driven navigation UI.
-6. Browser tests in `test/browser/` validate startup and auth navigation flow.
-
-```tsx
-// src/main.tsx (shape)
-createRoot(document.getElementById("root")!).render(
-	<StrictMode>
-		<App />
-	</StrictMode>,
-);
-```
-
-```tsx
-// src/App.tsx (shape)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
-const actor = createPlayer();
-actor.start();
-
-const routeTree = extractMachineRoutes(authMachine);
-const routeMap = createRouteMapFromTree(routeTree);
-
-return (
-	<PlayRouterProvider
-		actor={actor}
-		router={router}
-		routeMap={routeMap}
-		renderer={(currentActor, currentRouter) => {
-			void currentActor;
-			return <RouterProvider router={currentRouter} />;
-		}}
-	/>
-);
-```
-
-```tsx
-// src/components/Login.tsx (shape)
-export function Login() {
-	return (
-		<button onClick={() => actor.send({ type: "auth.login", username, password })}>
-			Login
-		</button>
-	);
-}
-```
-
-## Key Files
-
-- `src/main.tsx` - React entry point that mounts `<App />`
-- `src/App.tsx` - actor lifecycle, route extraction, provider wiring, and renderer composition
-- `src/components/` - demo views bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
-- `test/browser/startup.browser.test.tsx` - startup assertion for public home + login control
-- `test/browser/auth-flow.browser.test.tsx` - end-to-end login -> dashboard -> profile -> logout flow
-
-## State Machine & Architecture Details
-
-The demo utilizes XMachines architectural invariants:
-
-1. **Actor Authority:** Navigation triggers URL changes, which the `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
-2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates whether navigation is permitted. The React application only triggers renders.
-3. **Signal-Only Reactivity:** The bridge leverages React's `useSyncExternalStore` (internally within the hooks) to react precisely when signals update, without polluting the React component tree with `useState` or `useEffect` for business logic.
-
-## Watcher Lifecycle and Cleanup Contract
-
-This demo follows the same watcher lifecycle used across `@xmachines/play-signals` and framework adapters:
-
-1. `notify`
-2. `queueMicrotask`
-3. Drain pending work with `getPending()`
-4. Read actor signals and project framework-local state
-5. Re-arm via `watch()`/`watch(...signals)`
-
-Watcher notifications are one-shot. Cleanup is explicit: bridge/provider teardown must call `disconnect`/`unwatch` paths, never rely on GC-only cleanup. The `PlayRouterProvider` handles this natively on component unmount.
-
-## Adapter Boundaries
-
-`PlayRouterProvider` and the React Router bridge stay passive infrastructure. Business validity remains actor-owned, while `RouterBridgeBase` remains the shared policy layer and the concrete React adapter stays a thin port, delegating DOM synchronization to React Router.
-
-## Available Scripts
-
-These commands are defined in `package.json`:
-
-| Command                                                            | Description                      |
-| ------------------------------------------------------------------ | -------------------------------- |
-| `npm run dev -w packages/play-react-router/examples/demo`          | Start Vite dev server            |
-| `npm run build -w packages/play-react-router/examples/demo`        | Build production bundle          |
-| `npm run preview -w packages/play-react-router/examples/demo`      | Preview built bundle             |
-| `npm run test -w packages/play-react-router/examples/demo`         | Run Vitest test suite            |
-| `npm run test:browser -w packages/play-react-router/examples/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-react-router/examples/demo
-npm run test:browser -w packages/play-react-router/examples/demo
-```
-
-Expected result: tests pass for startup and auth-flow browser scenarios.
-
-## Learn More
-
-- [React Router package README](../play-react-router/README.md)
-- [React package README](../play-react/README.md)