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

package/api/@xmachines/play-solid/functions/useStateBinding.md

@@ -1,25 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useStateBinding
-
-# Function: useStateBinding()
-
-```ts
-function useStateBinding<T>(path): [Accessor<T | undefined>, (value) => void];
-```
-
-Defined in: `@json-render/solid`
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-## Returns
-
-\[`Accessor`\<`T` \| `undefined`\>, (`value`) => `void`\]

package/api/@xmachines/play-vue/functions/useStateBinding.md

@@ -1,32 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-vue](../README.md) / useStateBinding
-
-# Function: useStateBinding()
-
-```ts
-function useStateBinding<T>(path): [ComputedRef<T | undefined>, (value) => void];
-```
-
-Defined in: `@json-render/vue`
-
-Composable to get and set a value from the state model by path.
-
-This is the path-based variant for use in arbitrary composables. For
-registry components that receive `bindings` from the renderer, prefer
-`useBoundProp` which reads the already-resolved prop value and writes back
-to the bound path.
-
-## Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `T`            |
-
-## Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-## Returns
-
-\[`ComputedRef`\<`T` \| `undefined`\>, (`value`) => `void`\]

package/examples/@xmachines/play-actor-shared/README.md

@@ -1,155 +0,0 @@
-[Documentation](../../README.md) / @xmachines/play-actor-shared
-
-# play-actor Shared Demo Package
-
-Shared auth machine, catalog, and browser test fixtures consumed by all `@xmachines` renderer and router adapter demos.
-
-## What This Demonstrates
-
-- A single `authMachine` reused across every framework demo without modification
-- Framework-agnostic `authCatalog` defining typed component prop shapes and action param schemas
-- Shared browser test suite (`renderer-demo-browser-suite.ts`) importable by any renderer demo
-- State machine invariants: public routes, protected routes with auth guards, and nested sub-states
-
-## 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-actor-shared
-```
-
-## Step-by-Step Code Flow
-
-Use this order to understand the package structure:
-
-1. `src/auth-machine.ts` defines the `authMachine` using XState `setup()` with `formatPlayRouteTransitions` — all states include `meta.route` and `meta.view` for router and renderer integration.
-2. `src/catalog.ts` defines `authCatalog` using `defineCatalog` from `@json-render/core` — typed component prop schemas (via Zod) and action param schemas for `login`, `logout`, and all `route*` actions.
-3. `src/index.ts` re-exports `authMachine`, `authCatalog`, and all associated TypeScript types (`AuthActor`, `AuthContext`, `AuthEvents`, `AuthSnapshot`, `AuthCatalog`).
-4. `test/shared-package.test.ts` verifies machine invariants: starts at home, unauthenticated; `auth.login` transitions to `dashboard.overview`; `auth.logout` returns to `home`.
-5. `test/renderer-demo-browser-suite.ts` exports `defineNoRouterDemoBrowserSuite` — a portable browser test helper used by renderer demos that mount `<App />` and assert DOM state.
-
-```ts
-// src/auth-machine.ts (shape)
-export const authMachine = authSetup.createMachine(
-	formatPlayRouteTransitions({
-		id: "auth",
-		initial: "home",
-		on: {
-			"auth.login": { target: ".dashboard", guard: ({ context }) => !context.isAuthenticated },
-			"auth.logout": { target: ".home", guard: ({ context }) => context.isAuthenticated },
-		},
-		states: {
-			home: { meta: { route: "/", view: { component: "Home", spec: { ... } } } },
-			login: { meta: { route: "/login", view: { component: "Login", spec: { ... } } } },
-			dashboard: {
-				meta: { route: "/dashboard" },
-				initial: "overview",
-				always: { guard: ({ context }) => !context.isAuthenticated, target: "login" },
-				states: {
-					overview: { meta: { route: "overview", view: { component: "Overview", spec: { ... } } } },
-					stats: { meta: { route: "stats", view: { component: "Stats", spec: { ... } } } },
-				},
-			},
-			profile: { meta: { route: "/profile/:username", view: { component: "Profile", spec: { ... } } } },
-			settings: { meta: { route: "/settings/:section?", view: { component: "Settings", spec: { ... } } } },
-		},
-	}),
-);
-```
-
-```ts
-// src/catalog.ts (shape)
-export const authCatalog = defineCatalog(schema, {
-	components: {
-		Home: { props: z.object({ title: z.string() }) },
-		Login: { props: z.object({ title: z.string() }) },
-		Dashboard: { props: z.object({ welcome: z.boolean(), username: z.string() }) },
-		Profile: { props: z.object({ username: z.string() }) },
-		// ... more components
-	},
-	actions: {
-		login: { params: z.object({ username: z.string() }), description: "Login with username" },
-		logout: { description: "Logout and return to home" },
-		// ... more actions
-	},
-});
-```
-
-## Key Files
-
-- `src/auth-machine.ts` - XState auth machine with route metadata, guards, and nested dashboard states
-- `src/catalog.ts` - `authCatalog` with typed component and action schemas
-- `src/index.ts` - public re-exports: `authMachine`, `authCatalog`, all types
-- `src/index.css` - shared demo stylesheet imported by all renderer demos
-- `test/shared-package.test.ts` - machine invariant tests (start state, login, logout)
-- `test/renderer-demo-browser-suite.ts` - portable browser test helper for renderer demos
-
-## State Machine & Architecture Details
-
-The auth machine embodies XMachines architectural invariants:
-
-1. **Actor Authority:** All navigation uses `play.route` events — the machine evaluates each route transition against its current state and guard conditions. Framework adapters never bypass this.
-2. **Passive Infrastructure:** `meta.route` on each state is metadata for the router adapter to read, not a command. The actor drives the URL, not the other way around.
-3. **Signal-Only Reactivity:** The machine exposes `actor.currentView` and `actor.currentRoute` as TC39 Signals. Framework renderers and router adapters observe these signals — they never poll or subscribe to snapshots directly.
-
-## Watcher Lifecycle and Cleanup Contract
-
-The shared machine itself does not manage watchers — that responsibility belongs to each framework adapter. However, the machine's signal-based architecture requires adapters to follow the canonical lifecycle:
-
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project framework-local state
-5. Re-arm with `watch()`/`watch(...signals)`
-
-The `test/renderer-demo-browser-suite.ts` exports `defineNoRouterDemoBrowserSuite`, which each renderer demo uses to assert startup rendering and debug panel state without coupling to framework internals.
-
-## Adapter Boundaries
-
-This package is pure shared infrastructure: no framework imports, no DOM dependencies. It defines the contract (machine + catalog) that all framework adapters implement against. The `AuthActor` type exported here is the preferred import for components across all framework demos — it decouples component implementations from the concrete machine type.
-
-## Available Scripts
-
-These commands are defined in `package.json`:
-
-| Command                                                | Description                      |
-| ------------------------------------------------------ | -------------------------------- |
-| `npm run test -w @xmachines/play-actor-shared`         | Run Vitest test suite            |
-| `npm run test:browser -w @xmachines/play-actor-shared` | Run browser-focused Vitest suite |
-| `npm run build -w @xmachines/play-actor-shared`        | Build TypeScript declarations    |
-
-## Verification
-
-Use these checks to validate the shared package invariants:
-
-```bash
-npm run test -w @xmachines/play-actor-shared
-```
-
-Expected result: machine exports, start state, login, and logout invariants all pass.
-
-## Learn More
-
-- [play-actor package README](../../README.md)
-
-## Interfaces
-
-- [AuthContext](interfaces/AuthContext.md)
-
-## Type Aliases
-
-- [AuthActor](type-aliases/AuthActor.md)
-- [AuthCatalog](type-aliases/AuthCatalog.md)
-- [AuthEvents](type-aliases/AuthEvents.md)
-- [AuthInput](type-aliases/AuthInput.md)
-- [AuthSnapshot](type-aliases/AuthSnapshot.md)
-- [CatalogProps](type-aliases/CatalogProps.md)
-- [InferProps](type-aliases/InferProps.md)
-
-## Variables
-
-- [authCatalog](variables/authCatalog.md)
-- [authMachine](variables/authMachine.md)
-- [authSetup](variables/authSetup.md)

package/examples/@xmachines/play-actor-shared/interfaces/AuthContext.md

@@ -1,14 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthContext
-
-# Interface: AuthContext
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L27)
-
-## Properties
-
-| Property                                                | Type                           | Defined in                                                                                                                                                                                 |
-| ------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-isauthenticated"></a> `isAuthenticated` | `boolean`                      | [packages/play-actor/examples/shared/src/auth-machine.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L28) |
-| <a id="property-params"></a> `params`                   | `Record`\<`string`, `string`\> | [packages/play-actor/examples/shared/src/auth-machine.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L30) |
-| <a id="property-query"></a> `query`                     | `Record`\<`string`, `string`\> | [packages/play-actor/examples/shared/src/auth-machine.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L31) |
-| <a id="property-username"></a> `username`               | `string` \| `null`             | [packages/play-actor/examples/shared/src/auth-machine.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L29) |

package/examples/@xmachines/play-actor-shared/type-aliases/AuthActor.md

@@ -1,27 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthActor
-
-# Type Alias: AuthActor
-
-```ts
-type AuthActor = PlayerActor<typeof authMachine>;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:293](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L293)
-
-The actor type for the auth machine.
-
-Import this in components and router adapters instead of `typeof authMachine`.
-Components declare their dependency on the capability contract (AuthContext +
-AuthEvents + routing/view signals) without coupling to the concrete machine
-implementation.
-
-## Example
-
-```ts
-import type { AuthActor } from "@xmachines/play-actor-shared";
-
-function HeaderNav({ actor }: { actor: AuthActor }) {
-	const snap = actor.getSnapshot();
-	snap.context.username; // typed as string | null — no cast needed
-}
-```

package/examples/@xmachines/play-actor-shared/type-aliases/AuthCatalog.md

@@ -1,16 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthCatalog
-
-# Type Alias: AuthCatalog
-
-```ts
-type AuthCatalog = typeof authCatalog;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L69)
-
-The type of the auth catalog — use as the `C` type param in `ComponentFn<AuthCatalog, "X">`,
-`ComponentContext<AuthCatalog, "X">`, and `defineRegistry(authCatalog, ...)`.
-
-Prefer this over `typeof authCatalog` at every call site: it's more readable,
-follows the PascalCase convention for types, and insulates components from
-the catalog's runtime representation.

package/examples/@xmachines/play-actor-shared/type-aliases/AuthEvents.md

@@ -1,17 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthEvents
-
-# Type Alias: AuthEvents
-
-```ts
-type AuthEvents =
-	| PlayRouteEvent
-	| {
-			type: "auth.login";
-			username: string;
-	  }
-	| {
-			type: "auth.logout";
-	  };
-```
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L36)

package/examples/@xmachines/play-actor-shared/type-aliases/AuthInput.md

@@ -1,9 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthInput
-
-# Type Alias: AuthInput
-
-```ts
-type AuthInput = Partial<AuthContext> | undefined;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L34)

package/examples/@xmachines/play-actor-shared/type-aliases/AuthSnapshot.md

@@ -1,11 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / AuthSnapshot
-
-# Type Alias: AuthSnapshot
-
-```ts
-type AuthSnapshot = SnapshotFrom<typeof authMachine>;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/auth-machine.ts:273](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/auth-machine.ts#L273)
-
-Snapshot type for the auth machine — use for typed `matches()` calls.

package/examples/@xmachines/play-actor-shared/type-aliases/CatalogProps.md

@@ -1,187 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / CatalogProps
-
-# Type Alias: CatalogProps
-
-```ts
-type CatalogProps = object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L48)
-
-## Properties
-
-### About
-
-```ts
-About: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L50)
-
-#### title
-
-```ts
-title: string;
-```
-
----
-
-### Contact
-
-```ts
-Contact: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L51)
-
-#### title
-
-```ts
-title: string;
-```
-
----
-
-### Dashboard
-
-```ts
-Dashboard: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L53)
-
-#### username
-
-```ts
-username: string;
-```
-
-#### welcome
-
-```ts
-welcome: boolean;
-```
-
----
-
-### Home
-
-```ts
-Home: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L49)
-
-#### title
-
-```ts
-title: string;
-```
-
----
-
-### Login
-
-```ts
-Login: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L52)
-
-#### title
-
-```ts
-title: string;
-```
-
----
-
-### Navigation
-
-```ts
-Navigation: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L56)
-
-#### currentPath
-
-```ts
-currentPath: string;
-```
-
-#### isAuthenticated
-
-```ts
-isAuthenticated: boolean;
-```
-
----
-
-### Overview
-
-```ts
-Overview: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L57)
-
-#### title
-
-```ts
-title: string;
-```
-
----
-
-### Profile
-
-```ts
-Profile: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L54)
-
-#### username
-
-```ts
-username: string;
-```
-
----
-
-### Settings
-
-```ts
-Settings: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L55)
-
-#### section?
-
-```ts
-optional section?: string;
-```
-
-#### username
-
-```ts
-username: string;
-```
-
----
-
-### Stats
-
-```ts
-Stats: object;
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L58)
-
-#### title
-
-```ts
-title: string;
-```

package/examples/@xmachines/play-actor-shared/type-aliases/InferProps.md

@@ -1,17 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor-shared](../README.md) / InferProps
-
-# Type Alias: InferProps\<K\>
-
-```ts
-type InferProps<K> = CatalogProps[K];
-```
-
-Defined in: [packages/play-actor/examples/shared/src/catalog.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/examples/shared/src/catalog.ts#L74)
-
-Infer props for a named component from the catalog type
-
-## Type Parameters
-
-| Type Parameter                                        |
-| ----------------------------------------------------- |
-| `K` _extends_ keyof [`CatalogProps`](CatalogProps.md) |