@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-router/classes/BaseRouteMap.md

@@ -1,142 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / BaseRouteMap
-
-# Class: BaseRouteMap
-
-Defined in: [base-route-map.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L70)
-
-Shared bidirectional route map base class.
-
-All framework adapter `RouteMap` classes extend this — they add no logic of their
-own and inherit the full public API from here.
-
-**Lookup strategy:**
-
-- Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
-  of routes sharing the same first path segment
-- Results are cached after the first match
-
-**Pattern syntax** (`:param` / `:param?`):
-
-- `:param` — required segment, matches exactly one non-`/` segment
-- `:param?` — optional segment, matches zero or one non-`/` segment
-
-## Example
-
-```typescript
-import { BaseRouteMap } from "@xmachines/play-router";
-
-const map = new BaseRouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
-
-map.getStateIdByPath("/"); // "home"
-map.getStateIdByPath("/profile/123"); // "profile"
-map.getStateIdByPath("/settings"); // "settings"
-map.getStateIdByPath("/unknown"); // null
-
-map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("missing"); // null
-```
-
-## Extended by
-
-- [`RouteMap`](../../play-react-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-solid-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-tanstack-react-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-tanstack-solid-router/classes/RouteMap.md)
-- [`VueBaseRouteMap`](../../play-vue-router/classes/VueBaseRouteMap.md)
-
-## Constructors
-
-### Constructor
-
-```ts
-new BaseRouteMap(mappings): BaseRouteMap;
-```
-
-Defined in: [base-route-map.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L86)
-
-Build a route map from an array of state ID ↔ path mappings.
-
-Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `RegExp` and grouped into first-segment
-buckets for efficient candidate selection.
-
-#### Parameters
-
-| Parameter  | Type                                                      | Description                                                                                                       |
-| ---------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `mappings` | [`BaseRouteMapping`](../interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
-
-#### Returns
-
-`BaseRouteMap`
-
-## Methods
-
-### getPathByStateId()
-
-```ts
-getPathByStateId(stateId): string | null;
-```
-
-Defined in: [base-route-map.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L164)
-
-Look up the path pattern registered for a state ID.
-
-#### Parameters
-
-| Parameter | Type     | Description                                               |
-| --------- | -------- | --------------------------------------------------------- |
-| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
-
-#### Returns
-
-`string` \| `null`
-
-The registered path pattern, or `null` if the state ID is unknown
-
-#### Example
-
-```typescript
-map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("missing"); // null
-```
-
----
-
-### getStateIdByPath()
-
-```ts
-getStateIdByPath(path): string | null;
-```
-
-Defined in: [base-route-map.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L130)
-
-Resolve a URL path to its mapped state ID.
-
-Strips query strings and hash fragments before matching. Tries an O(1) exact
-lookup first, then falls back to bucket-indexed pattern matching. Results are
-cached after the first pattern match.
-
-#### Parameters
-
-| Parameter | Type     | Description                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------ |
-| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
-
-#### Returns
-
-`string` \| `null`
-
-The mapped state ID, or `null` if no route matches
-
-#### Example
-
-```typescript
-map.getStateIdByPath("/profile/123"); // "profile"
-map.getStateIdByPath("/unknown"); // null
-```

package/api/@xmachines/play-router/functions/connectRouter.md

@@ -1,67 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / connectRouter
-
-# Function: connectRouter()
-
-```ts
-function connectRouter(options): () => void;
-```
-
-Defined in: [connect-router.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/connect-router.ts#L58)
-
-Connect vanilla router to actor (pure browser integration).
-
-This is the LOW-LEVEL API for maximum control. No JSX, no rendering,
-just actor ↔ router synchronization.
-
-Use this when:
-
-- You want manual control over rendering
-- Using non-JSX framework (jQuery, Alpine, HTMX, etc.)
-- Building custom integration
-
-For JSX frameworks, use framework adapters instead:
-
-- @xmachines/play-react (React components)
-- Future: @xmachines/play-preact, @xmachines/play-solid, @xmachines/play-vue
-
-Architecture:
-
-- Subscribes to history changes → sends play.route to actor
-- Watches actor.currentRoute signal → updates browser URL
-- Prevents circular updates (history change triggers actor, actor triggers history)
-- Returns cleanup function
-
-Usage:
-
-```typescript
-import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-router";
-
-const history = createBrowserHistory({ window });
-const router = createRouter({ routeTree, history });
-
-// Connect router to actor
-const disconnect = connectRouter({ actor, router, routeMap });
-
-// User handles rendering (vanilla JS)
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		const view = actor.currentView.get();
-		document.getElementById("app").innerHTML = render(view);
-	});
-});
-watcher.watch(actor.currentView);
-
-// Later: cleanup
-disconnect();
-watcher.unwatch(actor.currentView);
-```
-
-## Parameters
-
-| Parameter | Type                                                            |
-| --------- | --------------------------------------------------------------- |
-| `options` | [`ConnectRouterOptions`](../interfaces/ConnectRouterOptions.md) |
-
-## Returns
-
-() => `void`

package/api/@xmachines/play-router/functions/crawlMachine.md

@@ -1,92 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / crawlMachine
-
-# Function: crawlMachine()
-
-```ts
-function crawlMachine(machine): StateVisit[];
-```
-
-Defined in: [crawl-machine.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/crawl-machine.ts#L74)
-
-Crawl state machine graph using breadth-first traversal
-
-Visits all state nodes in the machine, including deeply nested states, and returns
-complete list of visits with path and parent information. This enables systematic
-discovery of all states for route extraction and tree building.
-
-**Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
-routing information from the state machine definition rather than external configuration.
-The BFS traversal ensures all nested states are discovered, enabling the Actor to
-define the complete navigation structure through its machine definition.
-
-## Parameters
-
-| Parameter | Type              | Description                      |
-| --------- | ----------------- | -------------------------------- |
-| `machine` | `AnyStateMachine` | XState v5 state machine to crawl |
-
-## Returns
-
-[`StateVisit`](../interfaces/StateVisit.md)[]
-
-Array of state visits in breadth-first order
-
-## Examples
-
-Basic machine crawl
-
-```typescript
-import { createMachine } from "xstate";
-import { crawlMachine } from "@xmachines/play-router";
-
-const machine = createMachine({
-	initial: "home",
-	states: {
-		home: {},
-		dashboard: {
-			initial: "overview",
-			states: {
-				overview: {},
-				settings: {},
-			},
-		},
-	},
-});
-
-const visits = crawlMachine(machine);
-// Returns visits for: root, home, dashboard, dashboard.overview, dashboard.settings
-console.log(visits.map((v) => v.path.join(".")));
-// ['', 'home', 'dashboard', 'dashboard.overview', 'dashboard.settings']
-```
-
-Extract state paths and parents
-
-```typescript
-import { crawlMachine } from "@xmachines/play-router";
-
-const visits = crawlMachine(machine);
-visits.forEach((visit) => {
-	console.log({
-		path: visit.path.join(".") || "root",
-		hasParent: !!visit.parent,
-		hasChildren: Object.keys(visit.node.states).length > 0,
-	});
-});
-```
-
-## See
-
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
-- [extractRoute](extractRoute.md) for extracting route from individual states
-- [extractMachineRoutes](extractMachineRoutes.md) for complete route extraction
-- [StateVisit](../interfaces/StateVisit.md) for visit structure
-
-## Remarks
-
-**BFS Traversal:** Breadth-first search ensures systematic discovery of all states
-at each nesting level before descending deeper. This produces a predictable ordering
-useful for route tree construction and debugging.
-
-**Path Format:** Paths use array notation (`['dashboard', 'settings']`) which can be
-joined with dots for state IDs (`'dashboard.settings'`) matching XState's hierarchical
-state naming convention.

package/api/@xmachines/play-router/functions/createRouter.md

@@ -1,76 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouter
-
-# Function: createRouter()
-
-```ts
-function createRouter(options): VanillaRouter;
-```
-
-Defined in: [create-router.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-router.ts#L73)
-
-Create vanilla router for framework-agnostic routing.
-
-Architecture:
-
-- Just wraps history and routeTree
-- Does NOT embed routeMap (providers need it as prop)
-- Framework-agnostic history management only
-
-Why no routeMap:
-
-- Router doesn't know about state IDs (that's Play-specific)
-- RouteMap is the bridge between router and actor
-- Provider receives routeMap as prop to do path → state ID resolution
-
-Usage (parallel to TanStack mode):
-
-```typescript
-// Both modes: identical setup
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMap(routeTree);
-const history = createBrowserHistory({ window });
-
-// Vanilla router
-const router = createRouter({ routeTree, history });
-
-// Provider needs routeMap as prop (router doesn't have it)
-<PlayRouterProvider
-  actor={actor}
-  router={router}
-  routeMap={routeMap}  // ← Must pass separately
-  renderer={(currentActor, currentRouter) => {
-    void currentRouter;
-    return <Renderer actor={currentActor} components={components} />;
-  }}
-/>
-```
-
-Compare to TanStack mode:
-
-```typescript
-// TanStack router (external library)
-const router = TanStackCreateRouter({ routeTree, history });
-
-// Provider needs routeMap as prop (same as vanilla!)
-<PlayRouterProvider
-  actor={actor}
-  router={router}
-  routeMap={routeMap}  // ← Must pass separately
-  renderer={(currentActor, currentRouter) => {
-    void currentRouter;
-    return <Renderer actor={currentActor} components={components} />;
-  }}
-/>
-```
-
-## Parameters
-
-| Parameter           | Type                                                                                                                          |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `options`           | \{ `history`: [`BrowserHistory`](../interfaces/BrowserHistory.md); `routeTree`: [`RouteTree`](../interfaces/RouteTree.md); \} |
-| `options.history`   | [`BrowserHistory`](../interfaces/BrowserHistory.md)                                                                           |
-| `options.routeTree` | [`RouteTree`](../interfaces/RouteTree.md)                                                                                     |
-
-## Returns
-
-[`VanillaRouter`](../interfaces/VanillaRouter.md)

package/api/@xmachines/play-router/functions/extractRoute.md

@@ -1,45 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / extractRoute
-
-# Function: extractRoute()
-
-```ts
-function extractRoute(node, path, stateMap): RouteInfo | null;
-```
-
-Defined in: [extract-route.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/extract-route.ts#L26)
-
-Extract route information from state node with validation
-
-States with meta.route are "routable" - they can receive play.route events
-(when machine is wrapped with formatPlayRouteTransitions).
-
-## Parameters
-
-| Parameter  | Type                                                              | Description                                       |
-| ---------- | ----------------------------------------------------------------- | ------------------------------------------------- |
-| `node`     | `StateNode`                                                       | XState StateNode to extract route from            |
-| `path`     | `string`[]                                                        | State path segments from root                     |
-| `stateMap` | `Map`\<`string`, `StateNode`\<`MachineContext`, `EventObject`\>\> | Map of all state IDs to StateNodes for validation |
-
-## Returns
-
-[`RouteInfo`](../interfaces/RouteInfo.md) \| `null`
-
-RouteInfo if state has meta.route, null otherwise
-
-## Throws
-
-If route path is malformed (missing leading /)
-
-## Throws
-
-If route references non-existent state
-
-## Example
-
-```typescript
-const node = {
-	id: "dashboard",
-	meta: { route: "/dashboard" },
-};
-```

package/api/@xmachines/play-router/interfaces/BaseRouteMapping.md

@@ -1,27 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / BaseRouteMapping
-
-# Interface: BaseRouteMapping
-
-Defined in: [base-route-map.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L28)
-
-A single state ID ↔ path mapping entry.
-
-Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
-Adapter packages re-export a structurally compatible `RouteMapping` type under
-their own name. This type is published from `@xmachines/play-router` as
-`BaseRouteMapping` to avoid name collisions with those adapter-local types.
-
-## Example
-
-```typescript
-const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
-const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
-const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
-```
-
-## Properties
-
-| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                                        |
-| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L32) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/base-route-map.ts#L30) |

package/api/@xmachines/play-router/interfaces/BrowserHistory.md

@@ -1,172 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / BrowserHistory
-
-# Interface: BrowserHistory
-
-Defined in: [create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L1)
-
-## Properties
-
-| Property                                  | Modifier   | Type      | Description                | Defined in                                                                                                                                                                      |
-| ----------------------------------------- | ---------- | --------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-location"></a> `location` | `readonly` | `object`  | Get current location state | [create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L5) |
-| `location.hash`                           | `public`   | `string`  | -                          | [create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L8) |
-| `location.pathname`                       | `public`   | `string`  | -                          | [create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L6) |
-| `location.search`                         | `public`   | `string`  | -                          | [create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L7) |
-| `location.state`                          | `public`   | `unknown` | -                          | [create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L9) |
-
-## Methods
-
-### back()
-
-```ts
-back(): void;
-```
-
-Defined in: [create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L26)
-
-#### Returns
-
-`void`
-
----
-
-### createHref()
-
-```ts
-createHref(path): string;
-```
-
-Defined in: [create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L38)
-
-Create href from path
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-#### Returns
-
-`string`
-
----
-
-### destroy()
-
-```ts
-destroy(): void;
-```
-
-Defined in: [create-browser-history.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L43)
-
-Cleanup
-
-#### Returns
-
-`void`
-
----
-
-### forward()
-
-```ts
-forward(): void;
-```
-
-Defined in: [create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L27)
-
-#### Returns
-
-`void`
-
----
-
-### go()
-
-```ts
-go(delta): void;
-```
-
-Defined in: [create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L25)
-
-Go back/forward
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `delta`   | `number` |
-
-#### Returns
-
-`void`
-
----
-
-### push()
-
-```ts
-push(path, state?): void;
-```
-
-Defined in: [create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L15)
-
-Push new URL to history
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `path`    | `string`  |
-| `state?`  | `unknown` |
-
-#### Returns
-
-`void`
-
----
-
-### replace()
-
-```ts
-replace(path, state?): void;
-```
-
-Defined in: [create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L20)
-
-Replace current URL in history
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `path`    | `string`  |
-| `state?`  | `unknown` |
-
-#### Returns
-
-`void`
-
----
-
-### subscribe()
-
-```ts
-subscribe(listener): () => void;
-```
-
-Defined in: [create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-browser-history.ts#L33)
-
-Subscribe to history changes
-Returns unsubscribe function
-
-#### Parameters
-
-| Parameter  | Type                   |
-| ---------- | ---------------------- |
-| `listener` | (`location`) => `void` |
-
-#### Returns
-
-() => `void`