@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,379 @@
+[Documentation](../../README.md) / @xmachines/shared
+
+# @xmachines/shared
+
+**Shared TypeScript, linting, and formatting configurations for XMachines monorepo**
+
+Centralized config enabling composite build system with project references.
+
+## Overview
+
+`@xmachines/shared` provides shared configuration files for all XMachines packages, establishing consistent TypeScript compilation, linting rules, formatting, and Vitest setup across the monorepo.
+
+**Enhancement:** Added TypeScript composite build system with project references enabling correct build order, incremental compilation, and IDE source navigation via declaration maps.
+
+## Installation
+
+This package is automatically available to all workspace packages via npm workspaces.
+
+## Contents
+
+Configuration files in `config/` directory:
+
+- **`config/tsconfig.json`** - TypeScript compiler settings with composite project support
+- **`config/oxlint.json`** - Linting rules and plugins
+- **`config/oxfmt.json`** - Code formatting preferences
+- **`config/vitest.ts`** - Shared Vitest config helper (`defineXmVitestConfig`)
+- **`config/vitest.setup.ts`** - Shared cross-runtime Vitest setup (polyfills, jest-dom matchers)
+- **`config/vitest.node.setup.ts`** - Node-only Vitest setup (Node runtime/version preflight)
+- **`config/vite-aliases.ts`** - Workspace alias mapping for `@xmachines/*`
+
+## Usage
+
+### TypeScript Configuration
+
+**Recommended (short alias):**
+
+```json
+{
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	}
+}
+```
+
+**Alternative (full path):**
+
+```json
+{
+	"extends": "@xmachines/shared/config/tsconfig.json",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	}
+}
+```
+
+> **Note:** Both import styles work. The short alias is recommended for cleaner config files.
+
+### Oxlint Configuration
+
+**Recommended:**
+
+```json
+{
+	"extends": ["@xmachines/shared/oxlint"]
+}
+```
+
+### Oxfmt Configuration
+
+**Recommended:**
+
+```json
+{
+	"extends": ["@xmachines/shared/oxfmt"]
+}
+```
+
+### Vite Alias Configuration
+
+Use the shared alias helper in Vite and Vitest configs so workspace packages resolve to source files without requiring `dist/` builds:
+
+```ts
+import { defineConfig } from "vite";
+import { xmAliases } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+	resolve: {
+		alias: xmAliases(import.meta.url),
+	},
+});
+```
+
+This is especially important after `npm run clean`, where package `exports` targeting `dist/` are temporarily unavailable until rebuild.
+
+### Vitest Configuration
+
+Use the shared helper so package configs inherit common aliasing and runtime setup:
+
+```ts
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		environment: "node",
+		include: ["test/**/*.test.ts"],
+		exclude: ["node_modules/**"],
+	},
+});
+```
+
+**Browser project example:**
+
+```ts
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+import { playwright } from "@vitest/browser-playwright";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		name: "my-demo-browser",
+		browser: {
+			enabled: true,
+			provider: playwright(),
+			headless: true,
+			instances: [{ browser: "chromium" }],
+		},
+		include: ["test/browser/**/*.browser.test.ts"],
+		exclude: ["node_modules/**"],
+	},
+});
+```
+
+What the shared Vitest layer provides automatically:
+
+- `resolve.alias` for all `@xmachines/*` packages via `xmAliases(...)`
+- Shared setup injection (`config/vitest.setup.ts`) unless already present
+- Node setup injection (`config/vitest.node.setup.ts`) for non-browser projects
+- Runtime preflight:
+    - Node.js runtime/version check (`>=22`) in node setup
+- DOM matcher extension via `@testing-library/jest-dom/vitest`
+
+### Vitest Setup Injection Rules
+
+`defineXmVitestConfig(...)` applies setup files predictably:
+
+1. It normalizes `test.setupFiles` into an array.
+2. It injects `config/vitest.setup.ts` if missing.
+3. It injects `config/vitest.node.setup.ts` only when `test.browser.enabled !== true`.
+4. It avoids duplicates by checking filenames (suffix match).
+5. Injected setup files run before user-provided setup files.
+
+This gives a safe default for Node package tests while keeping browser projects compatible.
+
+### Vitest Exports
+
+`@xmachines/shared` exports these Vitest entry points:
+
+- `@xmachines/shared/vitest` → `config/vitest.ts`
+- `@xmachines/shared/vitest-setup` → `config/vitest.setup.ts`
+- `@xmachines/shared/vitest-node-setup` → `config/vitest.node.setup.ts`
+- `@xmachines/shared/vitest-urlpattern-setup` → `config/vitest.urlpattern.setup.ts`
+
+Use `@xmachines/shared/vitest` for package config files; direct setup exports are for advanced customization only.
+
+`vitest-urlpattern-setup` must be added explicitly to `setupFiles` in packages that exercise URLPattern-based route matching (e.g. `play-router` and its adapter packages). It mirrors what consumers must do in production on Node < 24 or older browsers.
+
+## Configuration Details
+
+### TypeScript (`config/tsconfig.json`)
+
+- **Target:** ESNext (Node.js 22+)
+- **Module:** NodeNext (ESM with `.js` extensions required)
+- **Strict:** Full strict mode enabled
+- **Output:** Colocated `.d.ts` files with source maps
+- **Composite:** Enabled for project references ()
+
+**Important:** You must use `.js` extensions in imports:
+
+```typescript
+import { foo } from "./bar.js"; // ✅ Correct
+import { foo } from "./bar"; // ❌ Wrong
+```
+
+### Oxlint (`config/oxlint.json`)
+
+- **Plugins:** TypeScript, Unicorn, Import
+- **Categories:** Correctness (error), Suspicious (warn), Performance (warn)
+- **Key Rules:**
+    - Circular dependency detection (`import/no-cycle`)
+    - Unused variables (allow `_` prefix)
+    - TypeScript-specific checks
+
+### Oxfmt (`config/oxfmt.json`)
+
+- **Line Width:** 100 characters
+- **Indentation:** Tabs (4 spaces)
+- **Style:** Double quotes, semicolons, trailing commas
+- **Final Newline:** Always insert
+
+### Vitest (`config/vitest.ts`, `config/vitest.setup.ts`, `config/vitest.node.setup.ts`, `config/vitest.urlpattern.setup.ts`)
+
+- **Helper API:** `defineXmVitestConfig(importMetaUrl, overrides)` merges shared defaults with package-specific Vitest config
+- **Auto-aliasing:** `resolve.alias` is wired to `xmAliases(importMetaUrl)` so workspace packages resolve to source
+- **Cross-runtime setup (`config/vitest.setup.ts`):**
+    - extends `expect` with `@testing-library/jest-dom/vitest`
+- **URLPattern setup (`config/vitest.urlpattern.setup.ts`):**
+    - loads `urlpattern-polyfill` — opt-in per package via `setupFiles: ["@xmachines/shared/vitest-urlpattern-setup"]`
+    - required for packages exercising URLPattern-based route matching (play-router and adapters)
+    - mirrors what consumers must do in production on Node < 24 or older browsers
+- **Node-only setup (`config/vitest.node.setup.ts`):**
+    - asserts Node runtime (`process.release.name === "node"`)
+    - enforces Node version `>=22`
+- **Browser behavior:** Browser projects do not receive node-only setup injection
+- **Override model:** Package-level config still controls test environment, includes/excludes, plugins, coverage, and browser provider
+
+### Vite Aliases (`config/vite-aliases.ts`)
+
+- **Helper API:** `xmAliases(importMetaUrl)` returns a complete `resolve.alias` map for all `@xmachines/*` workspace packages
+- **Root discovery:** Walks upward from `import.meta.url` until it finds the workspace root (`package.json` with `workspaces`)
+- **Source-first resolution:** Maps package imports to `packages/*/src/index.ts` for fast local dev without prebuild
+- **Extra aliases:** Includes `@xmachines/play-router-shared` and `@xmachines/play-router-shared/index.css` for demo shared assets
+- **Primary use cases:** `vite.config.ts`, `vitest` browser configs, and any local tooling relying on Vite resolver semantics
+
+### Vite Alias Troubleshooting
+
+- **`[xmAliases] Could not find workspace root`**
+    - Ensure `xmAliases` receives `import.meta.url` from the calling config file.
+    - Ensure the config file lives somewhere under the monorepo root.
+- **Workspace package import resolves to missing `dist/` files**
+    - Ensure config includes `resolve.alias: xmAliases(import.meta.url)`.
+    - Re-run after cleaning caches when lockfile/deps changed.
+
+### Vitest Troubleshooting
+
+- **`URLPattern is unavailable after setup`**
+    - Ensure `test.setupFiles` is not replacing shared setup unexpectedly.
+    - Ensure config is created via `defineXmVitestConfig(...)`.
+- **`Node runtime is required for this Vitest configuration`**
+    - This indicates node-only setup loaded in a browser project.
+    - Set `test.browser.enabled: true` in that project config.
+- **Workspace import resolution failures (e.g. `@xmachines/play-signals`)**
+    - Confirm config uses `defineXmVitestConfig(import.meta.url, ...)` so aliases are injected.
+
+## TypeScript Composite Build System
+
+This package introduced TypeScript project references for proper build-order management in the monorepo.
+
+### What This Means
+
+- **Root `tsconfig.json`** coordinates all packages via `references` array
+- **Each package** has `composite: true` enabling incremental builds
+- **Packages with dependencies** declare `references` to their deps
+- **TypeScript builds in correct order automatically** (no manual sequencing needed)
+
+### Building
+
+```bash
+npm run build          # Root-level tsc --build handles everything
+npm run build -w <pkg> # Automatically builds dependencies first
+```
+
+The root build command uses `tsc --build` which:
+
+- Understands the dependency graph
+- Builds packages in correct order
+- Only rebuilds changed packages (incremental)
+- Produces `.d.ts.map` files for IDE navigation
+
+### Declaration Maps
+
+The base config enables **declaration maps** (`declarationMap: true`) for better IDE experience in composite projects.
+
+When TypeScript compiles with `declarationMap: true`, it produces `.d.ts.map` files that map type definitions back to source. This enables:
+
+- **Go to Definition** jumps to `.ts` source files (not compiled `.d.ts`)
+- **Rename refactoring** works across package boundaries
+- **Error messages** reference source locations
+
+**Cost:** Slightly larger `dist/` output (~10% more)  
+**Benefit:** Dramatically better IDE experience
+
+### Project References
+
+Packages with internal dependencies should declare `references` in their `tsconfig.json`:
+
+```json
+{
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"references": [{ "path": "../dependency-package" }]
+}
+```
+
+The root `tsconfig.json` maintains the full package reference graph, enabling TypeScript to:
+
+- Build packages in correct dependency order
+- Support incremental builds (only rebuild what changed)
+- Enable cross-package type checking and navigation
+
+### Adding New Packages
+
+When creating a new package:
+
+1. **Add to root tsconfig.json references:**
+
+    ```json
+    {
+    	"references": [{ "path": "./packages/your-new-package" }]
+    }
+    ```
+
+2. **Enable composite in package tsconfig.json:**
+
+    ```json
+    {
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": {
+    		"composite": true,
+    		"rootDir": "./src",
+    		"outDir": "./dist"
+    	}
+    }
+    ```
+
+3. **Declare dependencies (if any):**
+    ```json
+    {
+    	"references": [{ "path": "../dependency-package" }]
+    }
+    ```
+
+### IDE Benefits
+
+With `declarationMap: true` in the base config:
+
+- **Go to Definition** jumps to source files (not compiled `.d.ts`)
+- **Real-time errors** across package boundaries
+- **Refactoring works** across the entire monorepo
+
+No build required for IDE features - TypeScript understands the source graph directly.
+
+See `AGENTS.md` (section: TypeScript Composite Build System) for complete composite build documentation.
+
+## Adding New Configurations
+
+To add a new shared configuration (e.g., for Jest, Vitest, etc.):
+
+1. Create `config/<tool>.json` (or `.js`, `.ts` as appropriate)
+2. Add exports to `package.json` exports field:
+    ```json
+    {
+    	"exports": {
+    		"./<tool>": "./config/<tool>.json",
+    		"./config/<tool>.json": "./config/<tool>.json"
+    	}
+    }
+    ```
+3. Document in this README with usage examples
+4. Note whether the tool supports package exports or requires relative paths
+
+## License
+
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.
+
+## Functions
+
+- [defineXmVitestConfig](functions/defineXmVitestConfig.md)
+- [xmAliases](functions/xmAliases.md)

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

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/shared](../README.md) / defineXmVitestConfig
+
+# Function: defineXmVitestConfig()
+
+```ts
+function defineXmVitestConfig(importMetaUrl, overrides): object;
+```
+
+Defined in: [src/index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/shared/src/index.ts#L10)
+
+Create a Vitest config with XMachines workspace defaults.
+
+This wrapper exposes the helper at the package top-level so API docs
+render it under `@xmachines/shared` instead of nested module pages.
+
+## Parameters
+
+| Parameter       | Type                            |
+| --------------- | ------------------------------- |
+| `importMetaUrl` | `string`                        |
+| `overrides`     | `Record`\<`string`, `unknown`\> |
+
+## Returns
+
+`object`
+
+| Name   | Type  | Defined in                                                                                                                                             |
+| ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `test` | `any` | [config/vitest.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/shared/config/vitest.ts#L82) |

package/api/@xmachines/shared/functions/xmAliases.md

@@ -0,0 +1,24 @@
+[Documentation](../../../README.md) / [@xmachines/shared](../README.md) / xmAliases
+
+# Function: xmAliases()
+
+```ts
+function xmAliases(importMetaUrl): Record<string, string>;
+```
+
+Defined in: [src/index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/shared/src/index.ts#L20)
+
+Build Vite/Vitest alias entries for all `@xmachines/*` workspace packages.
+
+This wrapper exposes the helper at the package top-level so API docs
+render it under `@xmachines/shared` instead of nested module pages.
+
+## Parameters
+
+| Parameter       | Type     |
+| --------------- | -------- |
+| `importMetaUrl` | `string` |
+
+## Returns
+
+`Record`\<`string`, `string`\>

package/api/README.md

@@ -0,0 +1,25 @@
+# Documentation
+
+## Packages
+
+- [@xmachines/play](@xmachines/play/README.md)
+- [@xmachines/play-actor](@xmachines/play-actor/README.md)
+- [@xmachines/play-catalog](@xmachines/play-catalog/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-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-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

@@ -0,0 +1,26 @@
+# 
+
+> Documentation for XMachines
+
+## 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

package/examples/README.md

@@ -0,0 +1,63 @@
+# XMachines Examples
+
+Practical code examples demonstrating common XMachines patterns and use cases.
+
+## Learning Path
+
+### Level 1: Basic Concepts
+
+Start with fundamental state machine concepts:
+
+- **[Basic State Machine](basic-state-machine.md)** - Simple two-state toggle machine
+- **[Traffic Light](traffic-light.md)** - Multi-state machine with cyclic transitions
+- **[Form Validation](form-validation.md)** - Validation with guards and conditional logic
+
+### Level 2: Routing Patterns
+
+Learn how state machines control navigation:
+
+- **[Routing Patterns](routing-patterns.md)** - State-driven routing and navigation guards
+- **[Multi-Router Integration](multi-router-integration.md)** - Framework-agnostic routing architecture
+
+### Level 3: Full Applications
+
+See complete working implementations demonstrating all architectural invariants:
+
+## Demo Applications
+
+Complete working applications demonstrating all 5 architectural invariants:
+
+- **[React + TanStack Router Demo](../../packages/play-tanstack-react-router/examples/demo-app/)** - Canonical reference implementation showing all 5 invariants, comprehensive routing, authentication guards, and browser tests
+- **[Vue Router Demo](../../packages/play-vue-router/examples/demo/)** - Vue Composition API integration with same auth patterns
+- **[SolidJS Router Demo](../../packages/play-solidjs-router/examples/demo/)** - Solid signals integration demonstrating framework independence
+
+## Running Examples
+
+All examples are written in TypeScript and can be run in:
+
+**Node.js:**
+
+```bash
+npm install @xmachines/play
+npx tsx example.ts
+```
+
+**Browser:**
+Include via bundler (Vite, Webpack) or use browser platform package.
+
+**Deno:**
+
+```bash
+deno run --allow-net example.ts
+```
+
+## Related Documentation
+
+- **[Getting Started Guide](/docs/guides/getting-started)** - First steps with XMachines
+- **[API Reference](/docs/api)** - Complete API documentation
+- **[Core Concepts](/docs/api/guides/core-concepts)** - Architecture and design patterns
+
+---
+
+**Contributing Examples:**
+Have a useful example to share? See [Development Docs](/development) for contribution guidelines.

package/examples/basic-state-machine.md

@@ -0,0 +1,70 @@
+# Basic State Machine
+
+Learn how to create a simple state machine with two states.
+
+## Use Case
+
+This example demonstrates a toggle switch or on/off button - the foundation for understanding state transitions in XMachines. It's the simplest possible state machine with just two states and one event type.
+
+## Complete Code
+
+```typescript
+import { createMachine } from "xstate";
+
+// Define states
+type ToggleState = "off" | "on";
+
+// Define events
+type ToggleEvent = { type: "TOGGLE" };
+
+// Create machine
+const toggleMachine = createMachine<ToggleState, ToggleEvent>({
+	id: "toggle",
+	initial: "off",
+	states: {
+		off: {
+			on: {
+				TOGGLE: "on",
+			},
+		},
+		on: {
+			on: {
+				TOGGLE: "off",
+			},
+		},
+	},
+});
+
+// Usage
+let state = toggleMachine.initialState;
+console.log(state); // 'off'
+
+state = toggleMachine.transition(state, { type: "TOGGLE" });
+console.log(state); // 'on'
+
+state = toggleMachine.transition(state, { type: "TOGGLE" });
+console.log(state); // 'off'
+```
+
+## Code Explanation
+
+1. **Define TypeScript types** - Create union types for states (`'off' | 'on'`) and events (`{ type: 'TOGGLE' }`) to get type safety throughout your application.
+
+2. **Create machine with initial state** - Use `createMachine` with an `initial` property to specify which state the machine starts in.
+
+3. **Define state transitions** - In the `states` config, each state has an `on` object mapping event types to target states.
+
+4. **Use the machine** - Call `transition(currentState, event)` to compute the next state based on the current state and incoming event.
+
+## Key Concepts
+
+- **State**: The current mode or condition of the machine (`'off'` or `'on'`)
+- **Event**: A trigger that causes a state change (`{ type: 'TOGGLE' }`)
+- **Transition**: A rule defining how the machine moves from one state to another
+- **Type Safety**: TypeScript ensures you only use valid states and events, catching errors at compile time
+
+## Next Steps
+
+- **[Traffic Light Example](traffic-light.md)** - See how to handle multiple states with cyclic transitions
+- **[Form Validation Example](form-validation.md)** - Learn about guards and conditional transitions
+- **[API Documentation](/docs/api/xmachines/play/readme)** - Explore the complete API reference