@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.50

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

@@ -1,38 +1,46 @@
 [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                                 |
+| `@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,333 +53,112 @@ Configuration files in `config/` directory:
 }
 ```
 
-**Alternative (full path):**
+For test-specific TypeScript settings (no emit, 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
 
-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
+## Key TypeScript Settings
 
-The base config enables **declaration maps** (`declarationMap: true`) for better IDE experience in composite projects.
+The base `config/tsconfig.json` configures:
 
-When TypeScript compiles with `declarationMap: true`, it produces `.d.ts.map` files that map type definitions back to source. This enables:
+- **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
 
-- **Go to Definition** jumps to `.ts` source files (not compiled `.d.ts`)
-- **Rename refactoring** works across package boundaries
-- **Error messages** reference source locations
+## Testing
 
-**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`:
+```bash
+# Run tests for this package
+npm test -w packages/shared
 
-```json
-{
-	"extends": "@xmachines/shared/tsconfig",
-	"compilerOptions": {
-		"composite": true,
-		"rootDir": "./src",
-		"outDir": "./dist"
-	},
-	"references": [{ "path": "../dependency-package" }]
-}
+# Or from the package directory
+npm test
 ```
 
-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>.
+MIT — see [LICENSE](LICENSE).
 
 ## Modules
 

package/api/@xmachines/shared/vite-aliases/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/shared/config/vite-aliases.ts#L24)
+Defined in: [vite-aliases.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/shared/config/vite-aliases.ts#L24)
 
 Vite resolve.alias entries for all @xmachines/\* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:196](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/shared/config/vite-aliases.ts#L196)
+Defined in: [vite-aliases.ts:196](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/shared/config/vite-aliases.ts#L196)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(extra?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/shared/config/vite-aliases.ts#L179)
+Defined in: [vite-aliases.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/shared/config/vite-aliases.ts#L179)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/shared/config/vite-aliases.ts#L151)
+Defined in: [vite-aliases.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/shared/config/vite-aliases.ts#L151)
 
 Full Vite `resolve` config for @xmachines/\* workspace packages.
 

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

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/shared/config/vitest.ts#L55)
+Defined in: [vitest.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/shared/config/vitest.ts#L55)
 
 Create a Vitest config with XMachines workspace defaults.
 

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