@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/shared/vitest/README.md

@@ -0,0 +1,12 @@
+[API](../../../README.md) / [@xmachines/shared](../README.md) / vitest
+
+# vitest
+
+## Interfaces
+
+- [XmBrowserConfigOptions](interfaces/XmBrowserConfigOptions.md)
+
+## Functions
+
+- [defineXmBrowserConfig](functions/defineXmBrowserConfig.md)
+- [defineXmVitestConfig](functions/defineXmVitestConfig.md)

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md

@@ -0,0 +1,42 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vitest](../README.md) / defineXmBrowserConfig
+
+# Function: defineXmBrowserConfig()
+
+```ts
+function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
+```
+
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L167)
+
+Create a Vitest browser-mode config with XMachines workspace defaults.
+
+Composes [defineXmVitestConfig](defineXmVitestConfig.md) (so alias resolution, setup-file
+normalization/injection, and the required deep excludes all apply) and
+bakes in the browser boilerplate shared by every browser test project:
+
+- `cacheDir` from `xmCacheDir(importMetaUrl, test.name)` and
+  `resolve` from `xmResolve(importMetaUrl)` (standalone configs only).
+- `optimizeDeps` from `xmOptimizeDeps(options.optimizeDeps)`.
+- `test.include: ["test/browser/**/*.browser.test.ts"]` and
+  `test.exclude: ["**/node_modules/**", "**/dist/**"]` defaults.
+- `test.fileParallelism: false`.
+- Headless Playwright Chromium via `test.browser`.
+
+Everything in `overrides` wins over these defaults: `test.include`,
+`test.exclude`, and `test.setupFiles` replace the defaults when provided,
+and `test.browser` entries (e.g. an `api` port) are merged on top of the
+Playwright defaults. Plugins stay per-package arguments (`plugins: [vue()]`).
+
+## Parameters
+
+| Parameter       | Type                                                                | Description                                                                                                                                          |
+| --------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `importMetaUrl` | `string`                                                            | Pass `import.meta.url` from the calling config file.                                                                                                 |
+| `overrides`     | `UserConfig`                                                        | Package/project-specific Vitest config overrides. `overrides.test.name` is required — it names the project and keys the shared Vite cache directory. |
+| `options`       | [`XmBrowserConfigOptions`](../interfaces/XmBrowserConfigOptions.md) | Browser-specific knobs, see [XmBrowserConfigOptions](../interfaces/XmBrowserConfigOptions.md).                                                       |
+
+## Returns
+
+`UserConfig`
+
+Merged Vitest configuration object.

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md

@@ -0,0 +1,34 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vitest](../README.md) / defineXmVitestConfig
+
+# Function: defineXmVitestConfig()
+
+```ts
+function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
+```
+
+Defined in: [vitest.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L64)
+
+Create a Vitest config with XMachines workspace defaults.
+
+What this applies automatically:
+
+- `resolve.alias` from `xmAliases(importMetaUrl)` so `@xmachines/*` imports
+  resolve to source in local/dev test runs.
+- `config/vitest.setup.ts` when missing.
+- `config/vitest.node.setup.ts` for non-browser projects when missing.
+
+Setup injection is additive and preserves caller-provided ordering after
+required shared setup files.
+
+## Parameters
+
+| Parameter       | Type         | Description                                          |
+| --------------- | ------------ | ---------------------------------------------------- |
+| `importMetaUrl` | `string`     | Pass `import.meta.url` from the calling config file. |
+| `overrides`     | `UserConfig` | Package/project-specific Vitest config overrides.    |
+
+## Returns
+
+`UserConfig`
+
+Merged Vitest configuration object.

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -0,0 +1,16 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vitest](../README.md) / XmBrowserConfigOptions
+
+# Interface: XmBrowserConfigOptions
+
+Defined in: [vitest.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L117)
+
+Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
+Vitest config overrides.
+
+## Properties
+
+| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
+| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L125) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L132) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:138](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vitest.ts#L138) |

package/api/README.md

@@ -4,22 +4,21 @@
 
 - [@xmachines/play](@xmachines/play/README.md)
 - [@xmachines/play-actor](@xmachines/play-actor/README.md)
-- [@xmachines/play-catalog](@xmachines/play-catalog/README.md)
+- [@xmachines/play-dom](@xmachines/play-dom/README.md)
+- [@xmachines/play-dom-router](@xmachines/play-dom-router/README.md)
 - [@xmachines/play-react](@xmachines/play-react/README.md)
 - [@xmachines/play-react-router](@xmachines/play-react-router/README.md)
-- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
 - [@xmachines/play-router](@xmachines/play-router/README.md)
-- [@xmachines/play-router-demo](@xmachines/play-router-demo/README.md)
 - [@xmachines/play-signals](@xmachines/play-signals/README.md)
 - [@xmachines/play-solid](@xmachines/play-solid/README.md)
 - [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md)
-- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-svelte](@xmachines/play-svelte/README.md)
+- [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md)
+- [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md)
 - [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md)
-- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-router](@xmachines/play-tanstack-router/README.md)
 - [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md)
-- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
 - [@xmachines/play-vue](@xmachines/play-vue/README.md)
 - [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md)
-- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
 - [@xmachines/play-xstate](@xmachines/play-xstate/README.md)
 - [@xmachines/shared](@xmachines/shared/README.md)

package/api/llms.txt

@@ -1,26 +1,75 @@
-# 
+# XMachines JavaScript/TypeScript API Docs
 
-> Documentation for XMachines
+> Stream-first, deterministic state machine runtime, rendering, and router adapter packages for JavaScript and TypeScript.
+
+- Core actor, routing, rendering, and catalog packages
+- Framework adapters for React, Solid, Vue, and router integrations
+- Generated API reference tuned for package discovery and implementation guidance
+
+## Start Here
+
+- Defining players from machines: start with [@xmachines/play-xstate](@xmachines/play-xstate/README.md).
+- Understanding actor contracts: read [@xmachines/play-actor](@xmachines/play-actor/README.md) for [Viewable](@xmachines/play-actor/interfaces/Viewable.md) and [Routable](@xmachines/play-actor/interfaces/Routable.md).
+- [Viewable](@xmachines/play-actor/interfaces/Viewable.md) is the rendering contract: actors expose `currentView` plus a component catalog so rendering packages can resolve UI without owning application state.
+- [Routable](@xmachines/play-actor/interfaces/Routable.md) is the routing contract: actors expose `currentRoute` plus route-oriented event handling, while adapters translate browser or router changes into actor events.
+- Rendering actor-driven UI: use [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), or [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- Synchronizing URLs with actor state: use [@xmachines/play-router](@xmachines/play-router/README.md) plus a framework-specific router adapter.
+
+## Package Roles
+
+- `Core runtime`: [@xmachines/play](@xmachines/play/README.md), [@xmachines/play-actor](@xmachines/play-actor/README.md), [@xmachines/play-signals](@xmachines/play-signals/README.md), [@xmachines/play-router](@xmachines/play-router/README.md), and [@xmachines/play-xstate](@xmachines/play-xstate/README.md). Catalog and component registry are provided by `@xmachines/json-render-core` and the framework rendering packages.
+- `Rendering`: [@xmachines/play-react](@xmachines/play-react/README.md), [@xmachines/play-solid](@xmachines/play-solid/README.md), [@xmachines/play-svelte](@xmachines/play-svelte/README.md), and [@xmachines/play-vue](@xmachines/play-vue/README.md).
+- `Router adapters`: [@xmachines/play-react-router](@xmachines/play-react-router/README.md), [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md), [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md), [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md), [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md), [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md), and [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md), all built on top of [Routable](@xmachines/play-actor/interfaces/Routable.md) actors and shared route metadata.
+- `Shared tooling`: [@xmachines/shared](@xmachines/shared/README.md) for shared config and workspace-level support files.
 
 ## API
-- [@xmachines/play](@xmachines/play/README.md): @xmachines/play module
-- [@xmachines/play-actor](@xmachines/play-actor/README.md): @xmachines/play-actor module
-- [@xmachines/play-catalog](@xmachines/play-catalog/README.md): @xmachines/play-catalog module
-- [@xmachines/play-react](@xmachines/play-react/README.md): @xmachines/play-react module
-- [@xmachines/play-react-router](@xmachines/play-react-router/README.md): @xmachines/play-react-router module
-- [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md): @xmachines/play-react-router-demo module
-- [@xmachines/play-router](@xmachines/play-router/README.md): @xmachines/play-router module
-- [@xmachines/play-router-demo](@xmachines/play-router-demo/README.md): @xmachines/play-router-demo module
-- [@xmachines/play-signals](@xmachines/play-signals/README.md): @xmachines/play-signals module
-- [@xmachines/play-solid](@xmachines/play-solid/README.md): @xmachines/play-solid module
-- [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md): @xmachines/play-solid-router module
-- [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md): @xmachines/play-solid-router-demo module
-- [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md): @xmachines/play-tanstack-react-router module
-- [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md): @xmachines/play-tanstack-react-router-demo module
-- [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md): @xmachines/play-tanstack-solid-router module
-- [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md): @xmachines/play-tanstack-solid-router-demo module
-- [@xmachines/play-vue](@xmachines/play-vue/README.md): @xmachines/play-vue module
-- [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md): @xmachines/play-vue-router module
-- [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md): @xmachines/play-vue-router-demo module
-- [@xmachines/play-xstate](@xmachines/play-xstate/README.md): @xmachines/play-xstate module
-- [@xmachines/shared](@xmachines/shared/README.md): @xmachines/shared module
+- [@xmachines/play](@xmachines/play/README.md): Core Play types and runtime contracts
+- [@xmachines/play-actor](@xmachines/play-actor/README.md): Abstract actor base class plus Routable and Viewable capabilities
+- [@xmachines/play-dom](@xmachines/play-dom/README.md): Vanilla DOM renderer for Viewable actors
+- [@xmachines/play-dom-router](@xmachines/play-dom-router/README.md): Vanilla DOM browser history, router, and actor↔URL synchronization
+- [@xmachines/play-signals](@xmachines/play-signals/README.md): Signal primitives used by Play actors and adapters
+- [@xmachines/play-router](@xmachines/play-router/README.md): Route extraction, route maps, and shared routing infrastructure
+- [@xmachines/play-tanstack-router](@xmachines/play-tanstack-router/README.md): Shared framework-agnostic TanStack Router bridge base
+- [@xmachines/play-xstate](@xmachines/play-xstate/README.md): XState-backed player and actor integration
+- [@xmachines/play-react](@xmachines/play-react/README.md): React renderer for Viewable actors
+- [@xmachines/play-solid](@xmachines/play-solid/README.md): Solid renderer for Viewable actors
+- [@xmachines/play-vue](@xmachines/play-vue/README.md): Vue renderer for Viewable actors
+- [@xmachines/play-svelte](@xmachines/play-svelte/README.md): Svelte renderer for Viewable actors
+- [@xmachines/play-react-router](@xmachines/play-react-router/README.md): React Router bridge and provider for actor-driven navigation
+- [@xmachines/play-tanstack-react-router](@xmachines/play-tanstack-react-router/README.md): TanStack React Router bridge and provider
+- [@xmachines/play-solid-router](@xmachines/play-solid-router/README.md): Solid Router bridge and provider
+- [@xmachines/play-tanstack-solid-router](@xmachines/play-tanstack-solid-router/README.md): TanStack Solid Router bridge and provider
+- [@xmachines/play-vue-router](@xmachines/play-vue-router/README.md): Vue Router bridge and provider
+- [@xmachines/play-sveltekit-router](@xmachines/play-sveltekit-router/README.md): SvelteKit router adapter for actor-driven navigation
+- [@xmachines/play-svelte-spa-router](@xmachines/play-svelte-spa-router/README.md): Svelte SPA router adapter for actor-driven navigation
+- [@xmachines/shared](@xmachines/shared/README.md): Shared TypeScript, oxlint, and formatting configuration
+
+## Notes For LLMs
+
+- Prefer the core packages before the demo apps; demos are intentionally excluded from this file.
+- For implementation questions, usually read in this order: [@xmachines/play-actor](@xmachines/play-actor/README.md) -> [@xmachines/play-xstate](@xmachines/play-xstate/README.md) -> [@xmachines/play-router](@xmachines/play-router/README.md) -> framework renderer/adapter.
+- [Routable](@xmachines/play-actor/interfaces/Routable.md) is the key abstraction for URL synchronization: router adapters observe and update actor route state but do not own navigation policy.
+- Router adapter packages are passive infrastructure; business logic stays in the actor and machine layers.
+- Rendering packages consume the [Viewable](@xmachines/play-actor/interfaces/Viewable.md) contract and component catalogs rather than owning application state.
+
+## Quick Reference
+
+```javascript
+import { definePlayer } from '@xmachines/play-xstate';
+import { createRouteMapFromTree, extractMachineRoutes, extractRouteParams } from '@xmachines/play-router';
+import { defineRegistry } from '@xmachines/json-render-react';
+import { PlayRenderer } from '@xmachines/play-react';
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
+const currentView = actor.currentView.get();
+const currentRoute = actor.currentRoute.get();
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+const stateId = routeMap.getStateIdByPath(currentRoute ?? '/');
+
+const { registry } = defineRegistry(catalog, { components, actions });
+<PlayRenderer actor={actor} registry={registry} actions={{ login: 'auth.login' }} />
+```

package/contributing/README.md

@@ -0,0 +1,10 @@
+# XMachines Development
+
+Reference documentation for contributors and maintainers of the `@xmachines/xmachines-js` monorepo.
+
+## Contents
+
+- **[Development](development.md)** — Monorepo setup, build system, adding packages, code conventions
+- **[Configuration](configuration.md)** — TypeScript, linting, formatting, Vitest, CI/CD, and release configuration
+- **[Testing](testing.md)** — Vitest setup, node vs browser modes, test patterns, coverage requirements
+- **[Deployment](deployment.md)** — npm publishing, semantic-release process, GitLab CI pipeline