@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/api/@xmachines/play-xstate/type-aliases/PlayerFactory.md

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactory
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactory
 
 # Type Alias: PlayerFactory\<TMachine\>
 
 ```ts
-type PlayerFactory<TMachine> = (input?) => PlayerActor<TMachine>;
+type PlayerFactory<TMachine> = (input?, options?) => PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/types.ts#L65)
+Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/types.ts#L57)
 
 Factory function returned by definePlayer()
 
@@ -14,15 +14,16 @@ Per CONTEXT.md: Factory supports creating multiple actor instances
 
 ## Type Parameters
 
-| Type Parameter                         |
-| -------------------------------------- |
-| `TMachine` _extends_ `AnyStateMachine` |
+| Type Parameter                                                                                 |
+| ---------------------------------------------------------------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
 
 ## Parameters
 
-| Parameter | Type                      |
-| --------- | ------------------------- |
-| `input?`  | `InputFrom`\<`TMachine`\> |
+| Parameter  | Type                                                                                      |
+| ---------- | ----------------------------------------------------------------------------------------- |
+| `input?`   | [`InputFrom`](https://www.jsdocs.io/package/xstate#InputFrom)\<`TMachine`\>               |
+| `options?` | [`PlayerFactoryResumeOptions`](../interfaces/PlayerFactoryResumeOptions.md)\<`TMachine`\> |
 
 ## Returns
 

package/api/@xmachines/play-xstate/type-aliases/RouteMachineConfig.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMachineConfig
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMachineConfig
 
 # Type Alias: RouteMachineConfig
 
@@ -6,7 +6,17 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L29)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L53)
+
+Minimal structural constraint for machine configs accepted by
+`formatPlayRouteTransitions`.
+
+This is intentionally loose so the function accepts both the bare `createMachine`
+config object and the stricter `setup().createMachine` config without requiring
+any type casts at the call site. The generic `T extends RouteMachineConfig`
+parameter on `formatPlayRouteTransitions` preserves the original concrete type
+through the transform, so the return value remains directly usable by
+`setup().createMachine()`.
 
 ## Indexable
 
@@ -22,7 +32,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:2
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L30)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L54)
 
 ---
 
@@ -32,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:3
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L32)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L56)
 
 ---
 
@@ -42,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:3
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L31)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L55)

package/api/@xmachines/play-xstate/type-aliases/RouteMetadata.md

@@ -0,0 +1,9 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMetadata
+
+# Type Alias: RouteMetadata
+
+```ts
+type RouteMetadata = string | RouteObject;
+```
+
+Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/types.ts#L6)

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteStateNode
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteStateNode
 
 # Type Alias: RouteStateNode
 
@@ -6,7 +6,14 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+
+Minimal structural shape of a single XState state node as read by
+`formatPlayRouteTransitions` when crawling the machine config.
+
+Only the fields the function actually inspects are typed here; all other
+state-node fields (e.g. `on`, `entry`, `after`) pass through unmodified via
+the index signature.
 
 ## Indexable
 
@@ -22,7 +29,9 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L14)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
+
+Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
 ---
 
@@ -32,14 +41,19 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:1
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L19)
+
+State metadata — `meta.route` marks the state as routable.
 
 #### route?
 
 ```ts
-optional route?: string;
+optional route?: RouteMetadata;
 ```
 
+URL path template — string form (e.g. `"/profile/:username"`) or object
+form (`{ path, title }`), matching [RouteMetadata](RouteMetadata.md).
+
 ---
 
 ### states?
@@ -48,4 +62,6 @@ optional route?: string;
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-xstate/src/routing/format-play-route-transitions.ts#L18)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-xstate/src/routing/format-play-route-transitions.ts#L27)
+
+Nested child states, recursively crawled for additional route declarations.

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

@@ -1,38 +1,46 @@
-[Documentation](../../README.md) / @xmachines/shared
+[API](../../README.md) / @xmachines/shared
 
-# @xmachines/shared
+<!-- generated-by: gsd-doc-writer -->
 
-**Shared TypeScript, linting, and formatting configurations for XMachines monorepo**
+# `@xmachines/shared`
 
-Centralized config enabling composite build system with project references.
+Shared configurations for XMachines packages — TypeScript, linting, formatting, and Vitest setup used across the monorepo.
 
-## 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.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
-This package is automatically available to all workspace packages via npm workspaces.
+This package is an internal monorepo dependency. It is **not intended for installation by external consumers**.
 
-## Contents
+Within the monorepo it is referenced by package name:
 
-Configuration files in `config/` directory:
+```json
+{
+	"dependencies": {
+		"@xmachines/shared": "*"
+	}
+}
+```
 
-- **`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/*`
+## Exports
+
+| Export                                      | File                                | Description                                                                                     |
+| ------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `@xmachines/shared/tsconfig`                | `config/tsconfig.json`              | Base TypeScript configuration for all packages                                                  |
+| `@xmachines/shared/tsconfig-test`           | `config/tsconfig.test.json`         | TypeScript configuration for test files (no emit, `allowImportingTsExtensions`, Vitest globals) |
+| `@xmachines/shared/oxlint`                  | `config/oxlint.config.ts`           | Shared oxlint configuration                                                                     |
+| `@xmachines/shared/oxfmt`                   | `config/oxfmt.config.ts`            | Shared oxfmt formatter configuration                                                            |
+| `@xmachines/shared/vite-aliases`            | `config/vite-aliases.ts`            | Vite resolve aliases for all `@xmachines/*` workspace packages                                  |
+| `@xmachines/shared/vitest`                  | `config/vitest.ts`                  | `defineXmVitestConfig` helper for per-package Vitest configs                                    |
+| `@xmachines/shared/vitest-setup`            | `config/vitest.setup.ts`            | Shared Vitest setup — extends matchers with `@testing-library/jest-dom`                         |
+| `@xmachines/shared/vitest-node-setup`       | `config/vitest.node.setup.ts`       | Node.js runtime guard — asserts `Node.js >= 22`                                                 |
+| `@xmachines/shared/vitest-urlpattern-setup` | `config/vitest.urlpattern.setup.ts` | Optional URLPattern polyfill setup for route-matching tests                                     |
 
 ## Usage
 
 ### TypeScript Configuration
 
-**Recommended (short alias):**
+Extend the base TypeScript config in any package:
 
 ```json
 {
@@ -45,335 +53,127 @@ Configuration files in `config/` directory:
 }
 ```
 
-**Alternative (full path):**
+For test-specific TypeScript settings (no emit, `allowImportingTsExtensions`, Vitest globals), extend:
 
 ```json
 {
-	"extends": "@xmachines/shared/config/tsconfig.json",
-	"compilerOptions": {
-		"composite": true,
-		"rootDir": "./src",
-		"outDir": "./dist"
-	}
+	"extends": "@xmachines/shared/tsconfig-test",
+	"include": ["src/**/*", "test/**/*"]
 }
 ```
 
-> **Note:** Both import styles work. The short alias is recommended for cleaner config files.
+### Linting (`oxlint`)
 
-### Oxlint Configuration
+Reference the shared oxlint config from a package's `oxlint.config.ts`:
 
-**Recommended:**
-
-```json
-{
-	"extends": ["@xmachines/shared/oxlint"]
-}
+```typescript
+import sharedConfig from "@xmachines/shared/oxlint";
+export default sharedConfig;
 ```
 
-### Oxfmt Configuration
-
-**Recommended:**
+The shared config enables the `typescript`, `unicorn`, and `import` plugins with:
 
-```json
-{
-	"extends": ["@xmachines/shared/oxfmt"]
-}
-```
-
-### Vite Alias Configuration
+- `correctness` rules as errors
+- `suspicious` and `perf` rules as warnings
+- `import/no-cycle` and `typescript/no-explicit-any` as errors
+- `typescript/no-unused-vars` as an error (ignoring `_`-prefixed names)
 
-Use the shared alias helper in Vite and Vitest configs so workspace packages resolve to source files without requiring `dist/` builds:
+### Formatting (`oxfmt`)
 
-```ts
-import { defineConfig } from "vite";
-import { xmAliases } from "@xmachines/shared/vite-aliases";
+Reference the shared oxfmt config from a package's `oxfmt.config.ts`:
 
-export default defineConfig({
-	resolve: {
-		alias: xmAliases(import.meta.url),
-	},
-});
+```typescript
+import sharedConfig from "@xmachines/shared/oxfmt";
+export default sharedConfig;
 ```
 
-This is especially important after `npm run clean`, where package `exports` targeting `dist/` are temporarily unavailable until rebuild.
+Key formatting rules: 4-space tab width using actual tabs, 100-character print width, double quotes, trailing commas, final newline. JSON/YAML files use 2-space indentation.
 
 ### Vitest Configuration
 
-Use the shared helper so package configs inherit common aliasing and runtime setup:
+Use `defineXmVitestConfig` for per-package Vitest configs. It automatically injects shared setup files and wires `@xmachines/*` source aliases:
 
-```ts
+```typescript
+// vitest.config.ts
 import { defineXmVitestConfig } from "@xmachines/shared/vitest";
 
 export default defineXmVitestConfig(import.meta.url, {
 	test: {
-		environment: "node",
-		include: ["test/**/*.test.ts"],
-		exclude: ["node_modules/**"],
+		globals: true,
 	},
 });
 ```
 
-**Browser project example:**
+**What `defineXmVitestConfig` applies automatically:**
 
-```ts
-import { defineXmVitestConfig } from "@xmachines/shared/vitest";
-import { playwright } from "@vitest/browser-playwright";
+- `resolve.alias` from `xmAliases(import.meta.url)` — resolves `@xmachines/*` to TypeScript source
+- `config/vitest.node.setup.ts` — Node.js runtime guard (skipped in browser mode)
+- `config/vitest.setup.ts` — `@testing-library/jest-dom` matcher extensions
+
+For packages that test URL routing, add the URLPattern polyfill setup:
 
+```typescript
 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/**"],
+		globals: true,
+		setupFiles: ["@xmachines/shared/vitest-urlpattern-setup"],
 	},
 });
 ```
 
-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.
+### Vite Aliases
 
-### 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:
+For Vite-based demo or app packages, resolve all `@xmachines/*` packages to TypeScript source (no prior build required):
 
 ```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
+// vite.config.ts
+import { defineConfig } from "vite";
+import { xmResolve } from "@xmachines/shared/vite-aliases";
 
-```bash
-npm run build          # Root-level tsc --build handles everything
-npm run build -w <pkg> # Automatically builds dependencies first
+export default defineConfig({
+	resolve: xmResolve(import.meta.url),
+});
 ```
 
-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
+Use `xmAliases` for alias-only setup, or `xmResolve` for the full resolve config including `conditions: ["source"]` and `preserveSymlinks: true`.
 
-### Declaration Maps
+For browser test projects, use `xmOptimizeDeps` to pre-bundle packages and avoid mid-run optimizer restarts, and `xmCacheDir` to share a single Vite dep cache across the workspace:
 
-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`:
+```typescript
+import { xmResolve, xmOptimizeDeps, xmCacheDir } from "@xmachines/shared/vite-aliases";
 
-```json
-{
-	"extends": "@xmachines/shared/tsconfig",
-	"compilerOptions": {
-		"composite": true,
-		"rootDir": "./src",
-		"outDir": "./dist"
-	},
-	"references": [{ "path": "../dependency-package" }]
-}
+export default defineConfig({
+	cacheDir: xmCacheDir(import.meta.url, "my-project"),
+	resolve: xmResolve(import.meta.url),
+	optimizeDeps: xmOptimizeDeps(["my-framework-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
+## Key TypeScript Settings
 
-When creating a new package:
+The base `config/tsconfig.json` configures:
 
-1. **Add to root tsconfig.json references:**
+- **Target:** `ESNext`, **Module:** `NodeNext` with `moduleResolution: NodeNext`
+- **Strict mode:** full strict, `noUnusedLocals`, `noUnusedParameters`, `exactOptionalPropertyTypes`, `noImplicitReturns`, `noImplicitOverride`
+- **Emit:** `declaration`, `declarationMap`, `sourceMap` enabled
+- **Interop:** `verbatimModuleSyntax`, `isolatedModules`
+- **Custom condition:** `"source"` — used by `xmAliases` to resolve packages to TypeScript source in dev/test
 
-    ```json
-    {
-    	"references": [{ "path": "./packages/your-new-package" }]
-    }
-    ```
+## Testing
 
-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.):
+```bash
+# Run tests for this package
+pnpm --filter @xmachines/shared test
 
-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
+# Or from the package directory
+pnpm test
+```
 
 ## 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>.
+MIT — see [LICENSE](LICENSE).
 
-## Functions
+## Modules
 
-- [defineXmVitestConfig](functions/defineXmVitestConfig.md)
-- [xmAliases](functions/xmAliases.md)
+- [vite-aliases](vite-aliases/README.md)
+- [vitest](vitest/README.md)

package/api/@xmachines/shared/vite-aliases/README.md

@@ -0,0 +1,11 @@
+[API](../../../README.md) / [@xmachines/shared](../README.md) / vite-aliases
+
+# vite-aliases
+
+## Functions
+
+- [xmAliases](functions/xmAliases.md)
+- [xmCacheDir](functions/xmCacheDir.md)
+- [xmOptimizeDeps](functions/xmOptimizeDeps.md)
+- [xmResolve](functions/xmResolve.md)
+- [xmSvelteRunes](functions/xmSvelteRunes.md)