@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,17 +2,15 @@
 
 # `@xmachines/shared`
 
-Shared configurations for XMachines packages — TypeScript, linting, formatting, and Vitest setup used across the monorepo.
+Shared configurations for the XMachines packages: TypeScript, linting, formatting, and the Vitest setup that the monorepo uses.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Part of the [xmachines-js monorepo](../../README.md).
-
 ## Installation
 
-This package is an internal monorepo dependency. It is **not intended for installation by external consumers**.
+This package is an internal dependency of the monorepo. **An external user must not install it.**
 
-Within the monorepo it is referenced by package name:
+In the monorepo, each package refers to it by name:
 
 ```json
 {
@@ -76,7 +74,7 @@ The shared config enables the `typescript`, `unicorn`, and `import` plugins with
 - `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)
+- `typescript/no-unused-vars` as an error (it ignores a name with a `_` prefix)
 
 ### Formatting (`oxfmt`)
 
@@ -87,11 +85,11 @@ import sharedConfig from "@xmachines/shared/oxfmt";
 export default sharedConfig;
 ```
 
-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.
+The main formatting rules are a tab width of 4 with real tab characters, a print width of 100 characters, double quotes, a trailing comma, and a final newline. A JSON file and a YAML file use an indentation of 2 spaces.
 
 ### Vitest Configuration
 
-Use `defineXmVitestConfig` for per-package Vitest configs. It automatically injects shared setup files and wires `@xmachines/*` source aliases:
+Use `defineXmVitestConfig` for the Vitest config of a package. It adds the shared setup files and the `@xmachines/*` source aliases:
 
 ```typescript
 // vitest.config.ts
@@ -107,7 +105,7 @@ export default defineXmVitestConfig(import.meta.url, {
 **What `defineXmVitestConfig` applies automatically:**
 
 - `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.node.setup.ts` — the Node.js runtime guard (the browser mode skips it)
 - `config/vitest.setup.ts` — `@testing-library/jest-dom` matcher extensions
 
 For packages that test URL routing, add the URLPattern polyfill setup:
@@ -123,7 +121,7 @@ export default defineXmVitestConfig(import.meta.url, {
 
 ### Vite Aliases
 
-For Vite-based demo or app packages, resolve all `@xmachines/*` packages to TypeScript source (no prior build required):
+In a Vite demo package or app package, resolve every `@xmachines/*` package to its TypeScript source. A build first is not necessary:
 
 ```typescript
 // vite.config.ts
@@ -135,9 +133,9 @@ export default defineConfig({
 });
 ```
 
-Use `xmAliases` for alias-only setup, or `xmResolve` for the full resolve config including `conditions: ["source"]` and `preserveSymlinks: true`.
+Use `xmAliases` for the aliases alone. Use `xmResolve` for a resolve config that adds `preserveSymlinks` (`false` by default) and your other resolve options to the aliases. For example, give `conditions` yourself if you need it.
 
-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:
+In a browser test project, use `xmOptimizeDeps` to bundle the packages in advance. The optimizer then does not restart during a run. Use `xmCacheDir` to share one Vite dependency cache across the workspace:
 
 ```typescript
 import { xmResolve, xmOptimizeDeps, xmCacheDir } from "@xmachines/shared/vite-aliases";
@@ -157,7 +155,7 @@ The base `config/tsconfig.json` configures:
 - **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
+- **Custom condition:** `"source"` — `xmAliases` uses it to resolve a package to its TypeScript source in development and in a test
 
 ## Testing
 

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

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L221)
+Defined in: [vite-aliases.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vite-aliases.ts#L221)
 
 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:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L338)
+Defined in: [vite-aliases.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vite-aliases.ts#L338)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

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

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L291)
+Defined in: [vite-aliases.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vite-aliases.ts#L291)
 
 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:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L258)
+Defined in: [vite-aliases.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vite-aliases.ts#L258)
 
 Full Vite `resolve` config for @xmachines/* workspace packages.
 

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

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L317)
+Defined in: [vite-aliases.ts:317](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vite-aliases.ts#L317)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -35,4 +35,4 @@ one and change the other.
 
 | Name                      | Type                                                    | Defined in                                                                                                                  |
 | ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vite-aliases.ts#L318) |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vite-aliases.ts#L318) |

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

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/shared/config/vitest.ts#L167)
+Defined in: [vitest.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/shared/config/vitest.ts#L167)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 

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

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

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

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

package/contributing/development.md

@@ -10,6 +10,7 @@ This guide covers everything you need to set up a local development environment,
 - [Updating Dependencies](#updating-dependencies)
 - [TypeScript Composite Build System](#typescript-composite-build-system)
 - [Code Style](#code-style)
+- [Writing Style](#writing-style-asd-ste100)
 - [Branch Conventions](#branch-conventions)
 - [PR Process](#pr-process)
 
@@ -400,6 +401,30 @@ Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters
 
 ---
 
+## Writing Style: ASD-STE100
+
+Every text that a human reads follows **ASD-STE100 Simplified Technical English**: commit messages, merge request titles and descriptions, documentation under `packages/docs/`, README files, changelog entries, and code comments. The specification is at <https://asd-ste100.org/>.
+
+Simplified Technical English keeps the documentation unambiguous for readers whose first language is not English, and it keeps the localized docs site consistent between versions.
+
+The rules that apply most often:
+
+- **One idea per sentence.** Keep instruction sentences to 20 words, descriptive sentences to 25.
+- **Active voice, present tense, named actor.** Write "the bridge drops the event", not "the event is dropped".
+- **Imperative for instructions.** Write "run `pnpm test`", not "you should run the tests". This also gives the Conventional Commits subject line its correct form.
+- **One word, one meaning.** Choose one term for each concept and repeat it. Do not alternate between synonyms such as "delete", "remove", and "purge".
+- **Simple words.** Write "use", not "utilize". Write "start", not "commence". Write "about", not "regarding".
+- **Keep the articles.** Write "the actor emits the event", not "actor emits event". Do not use contractions: write "do not", not "don't".
+- **No `-ing` clusters.** Write "the actor that emits the event", not "the emitting actor".
+- **No idioms, metaphors, marketing words, jokes, or emojis.**
+- **One topic for each paragraph, six sentences at most.** Put a warning or a caution before the step that it applies to.
+
+The rules apply to prose. They do not apply to identifiers, code, test names, log output, or text that you quote from an external source.
+
+The root `AGENTS.md` carries the same rules for AI coding agents.
+
+---
+
 ## Branch Conventions
 
 Use a `<type>/` prefix that matches the conventional commit type for the work being done:
@@ -430,6 +455,8 @@ Release branches are managed by the project maintainers:
 
 ### Commit Messages
 
+All prose in a commit follows [ASD-STE100](#writing-style-asd-ste100) — the subject line and the body.
+
 This project uses **Conventional Commits** — changelogs and version bumps are generated automatically from commit history.
 
 ```
@@ -486,6 +513,7 @@ feat(play-react): add PlayRenderer suspense boundary
 - [ ] New code has tests at or above coverage thresholds
 - [ ] All new public exports have JSDoc
 - [ ] Conventional commit format used on all commits
+- [ ] Commits, MR description, and docs written in [ASD-STE100](#writing-style-asd-ste100)
 - [ ] RFC read and implementation conforms to spec
 
 ### CI Pipeline

package/guides/inspector.md

@@ -170,7 +170,7 @@ actor.start();
 <button onClick={() => inspector.show()}>Show Inspector</button>;
 ```
 
-The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the current root's registration so it can never roll out of the bounded buffer, and flushes the buffer when the inspector window completes its handshake. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. See the [shared demo package README](../../play-actor/examples/shared/README.md) for the design in full.
+The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the current root's registration so it can never roll out of the bounded buffer, and flushes the buffer when the inspector window completes its handshake. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",

package/api/@xmachines/play-vue/functions/getPlayViewContext.md

@@ -1,28 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-vue](../README.md) / getPlayViewContext
-
-# Function: getPlayViewContext()
-
-```ts
-function getPlayViewContext(): ViewContextValue;
-```
-
-Defined in: [packages/play-vue/src/actor-provider-context.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-vue/src/actor-provider-context.ts#L44)
-
-Access the current ViewContextValue from inside an ActorProvider tree.
-
-## Returns
-
-[`ViewContextValue`](../interfaces/ViewContextValue.md)
-
-## Throws
-
-If called outside an <ActorProvider> (or <PlayUIProvider>) tree
-
-## Example
-
-```typescript
-import { getPlayViewContext } from "@xmachines/play-vue";
-
-const view = getPlayViewContext();
-// view.spec, view.handlers, view.registry
-```