@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -1,38 +1,46 @@
-[Documentation](../../README.md) / @xmachines/shared
+[API](../../README.md) / @xmachines/shared
 
-# @xmachines/shared
+# `@xmachines/shared`
 
-**Shared TypeScript, linting, and formatting configurations for XMachines monorepo**
+Shared configurations for XMachines packages — TypeScript, linting, formatting, and Vitest setup used across the monorepo.
 
-Centralized config enabling composite build system with project references.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 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)

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

@@ -0,0 +1,38 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmAliases
+
+# Function: xmAliases()
+
+```ts
+function xmAliases(importMetaUrl): Record<string, string>;
+```
+
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L221)
+
+Vite resolve.alias entries for all @xmachines/* workspace packages.
+
+Maps every package to its TypeScript source entry so that `pnpm run dev`
+works without a prior `pnpm run build`. Required because `pnpm run clean`
+removes all dist/ directories — including transitive dependencies —
+leaving Vite unable to resolve package.json `exports` that point to dist/.
+
+The map is derived from the workspace layout at config-load time (see
+`buildAliases`), so adding a new package needs no edit here. A few
+special-case subpath aliases are maintained explicitly on top.
+
+Usage in a demo vite.config.ts:
+
+import { xmAliases } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+resolve: { alias: xmAliases(import.meta.url) },
+});
+
+## Parameters
+
+| Parameter       | Type     | Description                                                                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `importMetaUrl` | `string` | Pass `import.meta.url` from the calling config file. Used to locate the workspace root (the directory containing `packages/`). |
+
+## Returns
+
+`Record`\<`string`, `string`\>

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

@@ -0,0 +1,27 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmCacheDir
+
+# Function: xmCacheDir()
+
+```ts
+function xmCacheDir(importMetaUrl, name): string;
+```
+
+Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L333)
+
+Returns the shared Vite `cacheDir` for this workspace package.
+
+All browser test projects use a single cache under `<workspace-root>/node_modules/.vite/`
+keyed by the project name. This means the dep optimizer runs once per project
+across the whole workspace rather than once per local `node_modules/.vite/` directory,
+and a lockfile change only triggers one rebuild per project — not one per local cache.
+
+## Parameters
+
+| Parameter       | Type     | Description                                          |
+| --------------- | -------- | ---------------------------------------------------- |
+| `importMetaUrl` | `string` | Pass `import.meta.url` from the calling config file. |
+| `name`          | `string` | Unique project name (matches `test.name`).           |
+
+## Returns
+
+`string`

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

@@ -0,0 +1,35 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmOptimizeDeps
+
+# Function: xmOptimizeDeps()
+
+```ts
+function xmOptimizeDeps(include?): DepOptimizationOptions;
+```
+
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L291)
+
+Returns the standard Vite `optimizeDeps` config for browser test projects.
+
+Tells Vite's dep optimizer which packages to pre-bundle at startup rather than
+discovering them lazily at runtime. Without this, adding or changing dependencies
+(e.g. a lockfile change) causes Vite to re-optimize mid-run, producing the
+"Re-optimizing dependencies because lockfile has changed" warnings that slow down
+and occasionally destabilise browser test runs.
+
+Every entry has to be a dependency the calling package declares. pnpm gives each
+package its own `node_modules`, so a specifier the project does not declare cannot
+be resolved from its root — and the optimizer only warns: `Failed to resolve
+dependency: <name>, present in client 'optimizeDeps.include'` on stderr, with the
+run carrying on. That reads as a failure inside a passing job, and it hides the
+same message when it is real. So nothing is pre-bundled by default: pass the
+packages this project actually depends on.
+
+## Parameters
+
+| Parameter | Type       | Default value | Description                                                    |
+| --------- | ---------- | ------------- | -------------------------------------------------------------- |
+| `include` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
+
+## Returns
+
+`DepOptimizationOptions`

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

@@ -0,0 +1,42 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmResolve
+
+# Function: xmResolve()
+
+```ts
+function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
+```
+
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L258)
+
+Full Vite `resolve` config for @xmachines/* workspace packages.
+
+Combines `xmAliases` with `conditions: ["source"]` so Vite resolves every
+`@xmachines/*` package to its TypeScript source via the `"source"` export
+condition — without requiring a prior `pnpm run build`.
+
+`preserveSymlinks` defaults to `false`: under pnpm every dependency is a
+symlink into the content-addressed store, and preserving symlink paths
+prevents Vite from deduplicating packages and from resolving nested
+dependencies of pre-bundled modules (vitest's own browser-mode chunks fail
+to load). Callers can still override it explicitly.
+
+Use this instead of manually setting `resolve.alias: xmAliases(...)`:
+
+```ts
+import { xmResolve } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+	resolve: xmResolve(import.meta.url),
+});
+```
+
+## Parameters
+
+| Parameter       | Type                                     | Description                                          |
+| --------------- | ---------------------------------------- | ---------------------------------------------------- |
+| `importMetaUrl` | `string`                                 | Pass `import.meta.url` from the calling config file. |
+| `extra?`        | `Partial`\<`ResolveOptions` & `object`\> | -                                                    |
+
+## Returns
+
+`ResolveOptions` & `object`

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

@@ -0,0 +1,33 @@
+[API](../../../../README.md) / [@xmachines/shared](../../README.md) / [vite-aliases](../README.md) / xmSvelteRunes
+
+# Function: xmSvelteRunes()
+
+```ts
+function xmSvelteRunes(): object;
+```
+
+Defined in: [vite-aliases.ts:312](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L312)
+
+Svelte plugin options that enforce runes mode for workspace sources only.
+
+Forcing `compilerOptions.runes` globally also applies to third-party
+`.svelte` files pulled in through Vite dependency optimization — e.g.
+`@testing-library/svelte-core`'s `wrapper-scaffold-legacy.svelte`, which is
+intentionally written in legacy syntax and fails to compile in runes mode.
+Scoping the flag with `dynamicCompileOptions` keeps the strictness for our
+own components while letting node_modules compile in their intended mode.
+
+Usage:
+
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { xmSvelteRunes } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({ plugins: [svelte(xmSvelteRunes())] });
+
+## Returns
+
+`object`
+
+| Name                      | Type                                                    | Defined in                                                                                                                  |
+| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:313](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/shared/config/vite-aliases.ts#L313) |