@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackRouterLike
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackRouterLike
 
 # Type Alias: TanStackRouterLike
 
@@ -6,7 +6,11 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L42)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+
+Structural (type-only) interface for the TanStack Router surface used by
+`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
+`@tanstack/solid-router` instances satisfy it.
 
 ## Properties
 
@@ -16,7 +20,29 @@ Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https:
 history: object;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L45)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+
+#### location
+
+```ts
+location: object;
+```
+
+Current location — populated from `window.location` when `createRouter()` runs,
+before `router.load()`. Always available in the browser.
+`router.state.location` is only populated after `router.load()` and may be stale.
+
+##### location.pathname
+
+```ts
+pathname: string;
+```
+
+##### location.search?
+
+```ts
+optional search?: string;
+```
 
 #### subscribe()
 
@@ -34,29 +60,25 @@ subscribe(handler): () => void;
 
 () => `void`
 
----
+## Methods
 
-### state?
+### load()?
 
 ```ts
-optional state?: object;
+optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L44)
-
-#### location?
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
 
-```ts
-optional location?: object;
-```
+Re-runs TanStack route matching and loaders for the current location.
+Optional: the bridge calls it (fire-and-forget) after every navigation so
+matching/loaders stay in sync even without a mounted `<RouterProvider>`.
 
-##### location.pathname?
+#### Returns
 
-```ts
-optional pathname?: string;
-```
+`void` \| `Promise`\<`void`\>
 
-## Methods
+---
 
 ### navigate()
 
@@ -64,7 +86,7 @@ optional pathname?: string;
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L43)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
 
 #### Parameters
 

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

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterProvider
+
+# Variable: PlayRouterProvider
+
+```ts
+const PlayRouterProvider: <TActor>(__namedParameters) => Element;
+```
+
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L57)
+
+Connects a `PlayerActor` to TanStack React Router, keeping actor state and
+browser URL in sync bidirectionally.
+
+The bridge is created once on mount and torn down on unmount. It is also
+rebuilt if `actor`, `router`, or `routeMap` change identity — so all three
+props must be **stable references** (created outside JSX or memoized).
+Under React `<StrictMode>` the effect runs twice on mount
+(connect → disconnect → connect), which the bridge supports.
+
+## Type Parameters
+
+| Type Parameter                                               |
+| ------------------------------------------------------------ |
+| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) |
+
+## Parameters
+
+| Parameter           | Type                                                                                                                                                     |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `__namedParameters` | [`PlayRouterProviderBaseProps`](../interfaces/PlayRouterProviderBaseProps.md)\<[`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md), `TActor`\> |
+
+## Returns
+
+`Element`

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

@@ -0,0 +1,61 @@
+[API](../../README.md) / @xmachines/play-tanstack-router
+
+# @xmachines/play-tanstack-router
+
+Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-router)
+
+TanStack Router exposes the identical `navigate` / `load` / `history` surface in
+both its React and Solid flavours, so the entire bridge implementation lives here
+as `TanStackRouterBridgeBase` (extending `RouterBridgeBase` from
+[`@xmachines/play-router`](../play-router/README.md)). The framework adapter
+packages only subclass it to bind their concrete router type.
+
+This package has **no TanStack runtime dependency** — `TanStackRouterLike` is a
+structural, type-only interface covering the small router surface the bridge uses.
+
+## Who consumes it
+
+- [`@xmachines/play-tanstack-react-router`](../play-tanstack-react-router/README.md) — TanStack Router adapter (React)
+- [`@xmachines/play-tanstack-solid-router`](../play-tanstack-solid-router/README.md) — TanStack Router adapter (SolidJS)
+
+## Usage
+
+```typescript
+import { TanStackRouterBridgeBase } from "@xmachines/play-tanstack-router";
+
+export class MyTanStackBridge extends TanStackRouterBridgeBase {}
+
+const bridge = new MyTanStackBridge(router, actor, routeMap);
+bridge.connect();
+// Cleanup on unmount
+return () => bridge.disconnect();
+```
+
+## Exports
+
+- `TanStackRouterBridgeBase` — abstract bridge base class
+- `TanStackRouterLike` — structural (type-only) TanStack router surface
+- `TanStackRouteMapLike` — narrow route-map surface the bridge requires
+
+## License
+
+MIT
+
+@xmachines/play-tanstack-router
+
+Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
+Consumed by `@xmachines/play-tanstack-react-router` and
+`@xmachines/play-tanstack-solid-router`, which subclass
+`TanStackRouterBridgeBase` to bind their concrete router type.
+
+## Classes
+
+- [TanStackRouterBridgeBase](classes/TanStackRouterBridgeBase.md)
+
+## Type Aliases
+
+- [TanStackRouteMapLike](type-aliases/TanStackRouteMapLike.md)
+- [TanStackRouterLike](type-aliases/TanStackRouterLike.md)

package/api/@xmachines/play-tanstack-router/classes/TanStackRouterBridgeBase.md

@@ -0,0 +1,131 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouterBridgeBase
+
+# Class: TanStackRouterBridgeBase
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
+
+Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
+
+## Remarks
+
+Extends RouterBridgeBase to handle all common lifecycle and sync logic; adds
+the TanStack-specific navigation and subscription methods shared by the React
+and Solid adapters.
+
+Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
+back/forward browser navigation (popstate events) are also captured. The
+router.subscribe("onBeforeLoad") approach only works when TanStack's
+Transitioner component is mounted (i.e. inside a full <RouterProvider>).
+Since this bridge is used without <RouterProvider>, we must subscribe to
+the underlying history object directly — which is exactly what Transitioner
+does internally: `router.history.subscribe(router.load)`.
+
+Architectural Invariants:
+
+- INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+- Actor validates all navigation via guards before URL changes
+
+The class is concrete — it can be instantiated directly. The framework
+packages re-export or subclass it purely to bind the public adapter name
+(and, for Solid, to add the `dispose()` alias).
+
+## Example
+
+```typescript
+const bridge = new TanStackRouterBridgeBase(router, actor, routeMap);
+bridge.connect();
+return () => bridge.disconnect();
+```
+
+## Extends
+
+- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+
+## Extended by
+
+- [`TanStackSolidRouterBridge`](../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new TanStackRouterBridgeBase(
+   router,
+   actor,
+   routeMap): TanStackRouterBridgeBase;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
+
+Create a TanStack Router bridge
+
+#### Parameters
+
+| Parameter  | Type                                                                 | Description                                       |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)        | TanStack Router instance (from `createRouter`)    |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | XMachines actor instance                          |
+| `routeMap` | [`TanStackRouteMapLike`](../type-aliases/TanStackRouteMapLike.md)    | Bidirectional mapping between state IDs and paths |
+
+#### Returns
+
+`TanStackRouterBridgeBase`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:120
+
+Connect the router bridge to the Actor.
+
+Sets up the TC39 Signal watcher for actor → router direction and
+starts watching router changes (framework-specific).
+
+Ordering here is part of the bridge contract:
+
+- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
+- the actor watcher is installed before adapter router subscriptions
+- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+
+Adapters that need custom initial-sync behavior should override
+`getInitialRouterPath()` rather than reordering `connect()` steps.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:126
+
+Disconnect the router bridge from the Actor.
+
+Stops signal watching and unregisters framework-specific router listener.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)

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

@@ -0,0 +1,57 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouteMapLike
+
+# Type Alias: TanStackRouteMapLike
+
+```ts
+type TanStackRouteMapLike = object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L66)
+
+Narrow route-map surface required by `TanStackRouterBridgeBase`.
+`RouteMap` from `@xmachines/play-router` satisfies it (null returns are
+adapted to undefined internally).
+
+`getPathByStateId` may receive the stateId in either `"#stateId"` or bare
+`"stateId"` form — the bridge tries both forms automatically, so custom
+implementations keyed on a single form still resolve.
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(id): string | null | undefined;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L68)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+#### Returns
+
+`string` \| `null` \| `undefined`
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null | undefined;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L67)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+#### Returns
+
+`string` \| `null` \| `undefined`

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

@@ -0,0 +1,100 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouterLike
+
+# Type Alias: TanStackRouterLike
+
+```ts
+type TanStackRouterLike = object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+
+Structural (type-only) interface for the TanStack Router surface used by
+`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
+`@tanstack/solid-router` instances satisfy it.
+
+## Properties
+
+### history
+
+```ts
+history: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+
+#### location
+
+```ts
+location: object;
+```
+
+Current location — populated from `window.location` when `createRouter()` runs,
+before `router.load()`. Always available in the browser.
+`router.state.location` is only populated after `router.load()` and may be stale.
+
+##### location.pathname
+
+```ts
+pathname: string;
+```
+
+##### location.search?
+
+```ts
+optional search?: string;
+```
+
+#### subscribe()
+
+```ts
+subscribe(handler): () => void;
+```
+
+##### Parameters
+
+| Parameter | Type                |
+| --------- | ------------------- |
+| `handler` | (`event`) => `void` |
+
+##### Returns
+
+() => `void`
+
+## Methods
+
+### load()?
+
+```ts
+optional load(): void | Promise<void>;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
+
+Re-runs TanStack route matching and loaders for the current location.
+Optional: the bridge calls it (fire-and-forget) after every navigation so
+matching/loaders stay in sync even without a mounted `<RouterProvider>`.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+---
+
+### navigate()
+
+```ts
+navigate(args): void;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `args`    | \{ `to`: `string`; \} |
+| `args.to` | `string`              |
+
+#### Returns
+
+`void`