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

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

@@ -1,173 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / authCatalog
-
-# 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>;
-							type: SchemaType<"ref", string>;
-							visible: SchemaType<"any", unknown>;
-						}
-					>
-				>;
-				root: SchemaType<"string", unknown>;
-			}
-		>;
-	},
-	{
-		actions: {
-			login: {
-				description: string;
-				params: ZodObject<
-					{
-						username: ZodString;
-					},
-					$strip
-				>;
-			};
-			logout: {
-				description: string;
-			};
-			routeDashboard: {
-				description: string;
-			};
-			routeHome: {
-				description: string;
-			};
-			routeLogin: {
-				description: string;
-			};
-			routeOverview: {
-				description: string;
-			};
-			routeProfile: {
-				description: string;
-			};
-			routeSettings: {
-				description: string;
-			};
-			routeStats: {
-				description: string;
-			};
-		};
-		components: {
-			About: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Contact: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Dashboard: {
-				props: ZodObject<
-					{
-						username: ZodString;
-						welcome: ZodBoolean;
-					},
-					$strip
-				>;
-			};
-			Home: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Login: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$strip
-				>;
-			};
-			Navigation: {
-				props: ZodObject<
-					{
-						currentPath: ZodString;
-						isAuthenticated: ZodBoolean;
-					},
-					$strip
-				>;
-			};
-			Overview: {
-				props: ZodObject<
-					{
-						title: ZodString;
-					},
-					$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-actor/examples/shared/src/catalog.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L14)

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

@@ -1,189 +0,0 @@
-[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

@@ -1,22 +0,0 @@
-[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-router-shared/README.md

@@ -1,111 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-router-shared
-
-# play-router Shared Demo Package
-
-Shared routing test fixtures for `@xmachines` router adapter demos — route extraction, route map resolution, and portable browser test helpers.
-
-## What This Demonstrates
-
-- `extractMachineRoutes` correctly extracts public, protected, and nested routes from `authMachine`
-- `createRouteMap` resolves concrete URLs to actor state IDs and URL params
-- `play.route` events drive the actor to the correct routed states
-- Portable `defineSharedDemoBrowserSuite` browser test helper consumed by all router demos
-
-## Running the Demo
-
-This is a shared fixture package — it has no standalone dev server. Run its tests from the repository root:
-
-```bash
-npm install
-npm run test -w @xmachines/play-router-shared
-```
-
-## Step-by-Step Code Flow
-
-Use this order to understand the package structure:
-
-1. `test/auth-machine-routing.test.ts` imports `authMachine` from `@xmachines/play-actor-shared` and verifies route extraction, route map resolution, param preservation, and `play.route`-driven actor transitions.
-2. `test/demo-browser-suite.ts` exports `defineSharedDemoBrowserSuite` — a comprehensive browser test helper that covers the full auth flow: home → about → contact → login → dashboard → settings → profile → logout.
-3. Router adapter demos import `defineSharedDemoBrowserSuite` (aliased as `defineRouterDemoBrowserSuite`) to mount their app and run the canonical flow against the shared test assertions.
-
-```ts
-// test/auth-machine-routing.test.ts (shape)
-const tree = extractMachineRoutes(authMachine);
-const routeMap = createRouteMap(extractMachineRoutes(authMachine));
-
-// URL → state ID
-expect(routeMap.resolve("/").to).toBe("#home");
-expect(routeMap.resolve("/dashboard/overview").to).toBe("#dashboard-overview");
-
-// URL → params
-expect(routeMap.resolve("/profile/alice")?.params).toEqual({ username: "alice" });
-
-// play.route events drive actor state
-actor.send({ type: "play.route", to: "#about" });
-expect(snapshot.matches("about")).toBe(true);
-```
-
-```ts
-// test/demo-browser-suite.ts (shape)
-export function defineSharedDemoBrowserSuite({ mountApp }) {
-	test("shared demo flow covers public, auth, protected, and logout routes", async () => {
-		const cleanup = await mountApp();
-		// Navigates: home → about → contact → login → dashboard → settings → profile → logout
-		// Validates: URL sync, view rendering, params, back/forward, and guard redirection
-		await cleanup?.();
-	});
-}
-
-export const defineRouterDemoBrowserSuite = defineSharedDemoBrowserSuite;
-```
-
-## Key Files
-
-- `test/auth-machine-routing.test.ts` - route extraction, route map resolution, param inheritance, and `play.route`-driven actor transitions
-- `test/demo-browser-suite.ts` - `defineSharedDemoBrowserSuite` / `defineRouterDemoBrowserSuite` portable browser test helper covering the full auth flow
-- `test/env.d.ts` - Vitest browser environment type declarations
-
-## State Machine & Architecture Details
-
-The routing tests verify XMachines architectural invariants at the routing layer:
-
-1. **Actor Authority:** `play.route` events are the only mechanism for URL-driven state transitions. The test suite verifies that actors respond correctly to these events and apply guards (e.g. protected routes redirect to login when unauthenticated).
-2. **Passive Infrastructure:** `createRouteMap` is a pure lookup structure — it maps URLs to state IDs and params but executes no business logic. The actor decides whether a resolved route is reachable from its current state.
-3. **Signal-Only Reactivity:** Route resolution is synchronous and deterministic. The browser test suite validates that URL changes produce the correct `[data-page]` DOM state, confirming that the signal-driven render loop completed.
-
-## Watcher Lifecycle and Cleanup Contract
-
-The shared test fixtures exercise teardown contracts by calling `cleanup()` at the end of each test. Each router adapter demo's `mountApp` implementation must return a cleanup function that calls `disconnectRouter()` and `actor.stop()` to satisfy this contract.
-
-## Adapter Boundaries
-
-This package has no framework imports — it only depends on `@xmachines/play-actor-shared`, `@xmachines/play-router`, and `xstate`. It defines the routing contract that all concrete router adapters must satisfy. The `defineRouterDemoBrowserSuite` export is the single source of truth for browser-level routing assertions across all adapter demos.
-
-## Available Scripts
-
-These commands are defined in `package.json`:
-
-| Command                                         | Description           |
-| ----------------------------------------------- | --------------------- |
-| `npm run test -w @xmachines/play-router-shared` | Run Vitest test suite |
-
-## Verification
-
-Use these checks to validate the shared routing invariants:
-
-```bash
-npm run test -w @xmachines/play-router-shared
-```
-
-Expected result: route extraction, URL-to-state resolution, param inheritance, and `play.route`-driven actor transition tests all pass.
-
-## Learn More
-
-- [play-router package README](../../README.md)
-- [play-actor shared README](../../../play-actor/examples/shared/README.md)
-
-## Modules
-
-- [test/auth-machine-routing.test.ts](test/auth-machine-routing.test.ts/README.md)
-- [test/demo-browser-suite.ts](test/demo-browser-suite.ts/README.md)
-- [test/env.d.ts](test/env.d.ts/README.md)

package/examples/@xmachines/play-router-shared/test/auth-machine-routing.test.ts/README.md

@@ -1,3 +0,0 @@
-[Documentation](../../../../README.md) / [@xmachines/play-router-shared](../../README.md) / test/auth-machine-routing.test.ts
-
-# test/auth-machine-routing.test.ts

package/examples/@xmachines/play-router-shared/test/demo-browser-suite.ts/README.md

@@ -1,11 +0,0 @@
-[Documentation](../../../../README.md) / [@xmachines/play-router-shared](../../README.md) / test/demo-browser-suite.ts
-
-# test/demo-browser-suite.ts
-
-## Variables
-
-- [defineRouterDemoBrowserSuite](variables/defineRouterDemoBrowserSuite.md)
-
-## Functions
-
-- [defineSharedDemoBrowserSuite](functions/defineSharedDemoBrowserSuite.md)

package/examples/@xmachines/play-router-shared/test/demo-browser-suite.ts/functions/defineSharedDemoBrowserSuite.md

@@ -1,19 +0,0 @@
-[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/demo-browser-suite.ts](../README.md) / defineSharedDemoBrowserSuite
-
-# Function: defineSharedDemoBrowserSuite()
-
-```ts
-function defineSharedDemoBrowserSuite(__namedParameters): void;
-```
-
-Defined in: [packages/play-router/examples/shared/test/demo-browser-suite.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-router/examples/shared/test/demo-browser-suite.ts#L75)
-
-## Parameters
-
-| Parameter           | Type                      |
-| ------------------- | ------------------------- |
-| `__namedParameters` | `DemoBrowserSuiteOptions` |
-
-## Returns
-
-`void`

package/examples/@xmachines/play-router-shared/test/demo-browser-suite.ts/variables/defineRouterDemoBrowserSuite.md

@@ -1,19 +0,0 @@
-[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/demo-browser-suite.ts](../README.md) / defineRouterDemoBrowserSuite
-
-# Variable: defineRouterDemoBrowserSuite
-
-```ts
-const defineRouterDemoBrowserSuite: (__namedParameters) => void = defineSharedDemoBrowserSuite;
-```
-
-Defined in: [packages/play-router/examples/shared/test/demo-browser-suite.ts:234](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-router/examples/shared/test/demo-browser-suite.ts#L234)
-
-## Parameters
-
-| Parameter           | Type                      |
-| ------------------- | ------------------------- |
-| `__namedParameters` | `DemoBrowserSuiteOptions` |
-
-## Returns
-
-`void`

package/examples/@xmachines/play-router-shared/test/env.d.ts/README.md

@@ -1,8 +0,0 @@
-[Documentation](../../../../README.md) / [@xmachines/play-router-shared](../../README.md) / test/env.d.ts
-
-# test/env.d.ts
-
-## Interfaces
-
-- [ImportMeta](interfaces/ImportMeta.md)
-- [ImportMetaEnv](interfaces/ImportMetaEnv.md)

package/examples/@xmachines/play-router-shared/test/env.d.ts/interfaces/ImportMeta.md

@@ -1,63 +0,0 @@
-[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/env.d.ts](../README.md) / ImportMeta
-
-# Interface: ImportMeta
-
-Defined in: `typescript`
-
-The type of `import.meta`.
-
-If you need to declare that a given property exists on `import.meta`,
-this type may be augmented via interface merging.
-
-## Properties
-
-| Property                                  | Modifier   | Type                                | Defined in |
-| ----------------------------------------- | ---------- | ----------------------------------- | ---------- |
-| <a id="property-dirname"></a> `dirname`   | `public`   | `string`                            | -          |
-| <a id="property-env"></a> `env`           | `readonly` | [`ImportMetaEnv`](ImportMetaEnv.md) | -          |
-| <a id="property-filename"></a> `filename` | `public`   | `string`                            | -          |
-| <a id="property-glob"></a> `glob`         | `public`   | `ImportGlobFunction`                | -          |
-| <a id="property-hot"></a> `hot?`          | `readonly` | `ViteHotContext`                    | -          |
-| <a id="property-main"></a> `main`         | `public`   | `boolean`                           | -          |
-| <a id="property-url"></a> `url`           | `public`   | `string`                            | -          |
-
-## Methods
-
-### resolve()
-
-#### Call Signature
-
-```ts
-resolve(specifier): string;
-```
-
-Defined in: `typescript`
-
-##### Parameters
-
-| Parameter   | Type     |
-| ----------- | -------- |
-| `specifier` | `string` |
-
-##### Returns
-
-`string`
-
-#### Call Signature
-
-```ts
-resolve(specifier, parent?): string;
-```
-
-Defined in: `@types/node`
-
-##### Parameters
-
-| Parameter   | Type              |
-| ----------- | ----------------- |
-| `specifier` | `string`          |
-| `parent?`   | `string` \| `URL` |
-
-##### Returns
-
-`string`

package/examples/@xmachines/play-router-shared/test/env.d.ts/interfaces/ImportMetaEnv.md

@@ -1,32 +0,0 @@
-[Documentation](../../../../../README.md) / [@xmachines/play-router-shared](../../../README.md) / [test/env.d.ts](../README.md) / ImportMetaEnv
-
-# Interface: ImportMetaEnv
-
-Defined in: `vite`
-
-Custom environment variables for the shared demo browser suite.
-
-## See
-
-packages/play-router/examples/shared/test/demo-browser-suite.ts
-
-## Extends
-
-- `Record`\<`ImportMetaEnvFallbackKey`, `any`\>
-
-## Indexable
-
-```ts
-[key: string]: any
-```
-
-## Properties
-
-| Property                                                                 | Modifier   | Type      | Description                                                                 | Defined in                                                                                                                                                                       |
-| ------------------------------------------------------------------------ | ---------- | --------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base_url"></a> `BASE_URL`                                | `public`   | `string`  | -                                                                           | -                                                                                                                                                                                |
-| <a id="property-dev"></a> `DEV`                                          | `public`   | `boolean` | -                                                                           | -                                                                                                                                                                                |
-| <a id="property-mode"></a> `MODE`                                        | `public`   | `string`  | -                                                                           | -                                                                                                                                                                                |
-| <a id="property-prod"></a> `PROD`                                        | `public`   | `boolean` | -                                                                           | -                                                                                                                                                                                |
-| <a id="property-ssr"></a> `SSR`                                          | `public`   | `boolean` | -                                                                           | -                                                                                                                                                                                |
-| <a id="property-vite_enable_screenshots"></a> `VITE_ENABLE_SCREENSHOTS?` | `readonly` | `string`  | Set to any truthy string to enable screenshot capture during browser tests. | [packages/play-router/examples/shared/test/env.d.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-router/examples/shared/test/env.d.ts#L10) |