@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/contributing/configuration.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Configuration
 
 This document describes every configuration file, environment variable, and per-package override used by the `xmachines-js` monorepo.
@@ -133,7 +131,6 @@ The root config extends the shared base (`@xmachines/shared/oxlint`) and adds wo
 export default defineConfig({
 	extends: [sharedConfig],
 	ignorePatterns: [
-		".planning",
 		".opencode",
 		"node_modules",
 		"dist",
@@ -185,7 +182,6 @@ export default defineConfig({
 	...sharedConfig,
 	ignorePatterns: [
 		...(sharedConfig.ignorePatterns ?? []),
-		".planning",
 		".opencode",
 		".agents",
 		".githuman",
@@ -295,7 +291,7 @@ Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 - **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`.
 - **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: true` and `conditions: ["source"]`.
 - **`xmCacheDir(import.meta.url, name)`** — returns a shared Vite cache path under `node_modules/.vite/<name>` to prevent redundant dep optimizer runs across projects.
-- **`xmOptimizeDeps(extra?)`** — returns a standard `optimizeDeps.include` list; pass framework-specific extras to pre-bundle them at startup.
+- **`xmOptimizeDeps(include?)`** — returns an `optimizeDeps.include` list holding exactly the specifiers passed in. Nothing is pre-bundled by default, and every entry has to be a package the calling project declares: pnpm gives each package its own `node_modules`, so Vite cannot resolve an undeclared specifier — it warns on stderr and carries on, which reads as a failure in a passing job.
 
 ### Release — `release.config.mjs`
 
@@ -306,11 +302,15 @@ Defines the release branches and plugin chain used by the GitLab CI semantic-rel
 
 **Release branches:**
 
-| Branch   | Channel   | Pre-release |
-| -------- | --------- | ----------- |
-| `main`   | (default) | No          |
-| `pre/rc` | `pre/rc`  | `rc`        |
-| `beta`   | `beta`    | `true`      |
+| Branch  | Channel   | Pre-release |
+| ------- | --------- | ----------- |
+| `main`  | (default) | No          |
+| `rc`    | `rc`      | `rc`        |
+| `beta`  | `beta`    | `true`      |
+| `alpha` | `alpha`   | `alpha`     |
+| `pre`   | `pre`     | `pre`       |
+
+Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — which the release needs, since `CI_JOB_TOKEN` can push neither the release commit nor the tag — is an _unprotected_ group variable and so reaches every one of these refs. If it is ever made protected, each of these branches has to be protected too, or the release fails in verify-conditions with `EGITNOPERMISSION` rather than at the registry.
 
 **Tag format:** `v${version}`
 

package/contributing/deployment.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Deployment
 
 This document describes how `@xmachines/xmachines-js` packages are built, versioned, and published to npm. All releases are automated through [semantic-release](https://semantic-release.gitbook.io/) running inside a GitLab CI pipeline. No manual `npm publish` commands are required for normal releases.
@@ -10,11 +8,11 @@ This document describes how `@xmachines/xmachines-js` packages are built, versio
 
 All `@xmachines/*` packages are published to the **public npm registry** (`registry.npmjs.org`). Every package uses `"publishConfig": { "access": "public" }` so scoped packages are accessible without an npm org subscription. See the [Published Packages](#published-packages) table for the full list.
 
-| Target          | Config File                                                            | Purpose                                                |
-| --------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ |
-| npm registry    | `.releaserc.json` (per-package `@semantic-release/npm` plugin entries) | Publish all public packages                            |
-| GitLab Releases | `.releaserc.json` (`@semantic-release/gitlab` plugin)                  | Attach tarball artifacts to the GitLab release tag     |
-| GitLab CI       | `.gitlab-ci.yml`                                                       | Trigger builds, tests, and releases on push / MR / tag |
+| Target          | Config File                                                               | Purpose                                                |
+| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------ |
+| npm registry    | `release.config.mjs` (npm plugin entries derived from the workspace scan) | Publish all public packages                            |
+| GitLab Releases | `release.config.mjs` (`@semantic-release/gitlab` plugin)                  | Attach tarball artifacts to the GitLab release tag     |
+| GitLab CI       | `.gitlab-ci.yml`                                                          | Trigger builds, tests, and releases on push / MR / tag |
 
 The root `package.json` is marked `"private": true` and is **never published** to npm.
 
@@ -22,7 +20,7 @@ The root `package.json` is marked `"private": true` and is **never published** t
 
 ## Published Packages
 
-The following packages are published on every release (derived from `.releaserc.json`):
+The following packages are published on every release (derived from the workspace scan in `release.config.mjs` — every non-private package that is not a demo):
 
 | Package                                                                                           | Directory                             |
 | ------------------------------------------------------------------------------------------------- | ------------------------------------- |
@@ -59,21 +57,23 @@ Each published package includes only the directories listed in its `files` field
 
 Pipeline runs are triggered by `.gitlab-ci.yml` under the following conditions:
 
-| Trigger                                       | Pipeline runs                                 |
-| --------------------------------------------- | --------------------------------------------- |
-| Push to `main` / `master` / `beta` / `pre/rc` | Full pipeline including release               |
-| Merge request                                 | Full pipeline (release job skipped or manual) |
-| Tag push (`$CI_COMMIT_TAG`)                   | Full pipeline                                 |
+| Trigger                                          | Pipeline runs                                      |
+| ------------------------------------------------ | -------------------------------------------------- |
+| Push to `main` / `rc` / `beta` / `alpha` / `pre` | Full pipeline; the release job waits to be started |
+| Merge request                                    | Full pipeline, no release job                      |
+| Web / API / trigger / parent pipeline            | Full pipeline                                      |
+
+No rule admits a tag pipeline, so pushing a tag runs nothing.
 
-The pipeline includes two reusable CI components:
+The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml` — which is the version to trust, rather than a number repeated here:
 
-- **`to-be-continuous/node/gitlab-ci-node@5.1.2`** — handles install, lint, build, test, and audit
-- **`to-be-continuous/semantic-release/gitlab-ci-semrel@4.1.0`** — runs `semantic-release` on eligible branches
+- **`to-be-continuous/node/gitlab-ci-node`** — handles install, lint, build, test, and audit
+- **`to-be-continuous/semantic-release/gitlab-ci-semrel`** — runs `semantic-release` on eligible branches
 
 The `node-build` job runs with:
 
 ```bash
-pnpm run build           # tsc --build (TypeScript composite build)
+pnpm run build           # vite build (JavaScript) && tsc --build (declarations)
 pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
 ```
 
@@ -116,7 +116,7 @@ node scripts/release-pack-smoke.mjs
 
 `scripts/release-pack-smoke.mjs`:
 
-1. Reads `.releaserc.json` to find all `@semantic-release/npm` plugin entries where `npmPublish` is not `false`.
+1. Reads `release.config.mjs` to find all `@semantic-release/npm` plugin entries where `npmPublish` is not `false`.
 2. For each publishable package: runs `npm pack --json` in the package directory.
 3. Creates a temporary directory, runs `npm init -y`, and installs the local tarball with `--ignore-scripts`.
 4. Asserts the install succeeds — any missing files, broken exports, or pack-time errors surface here.
@@ -130,13 +130,17 @@ This smoke test runs **before** the actual publish so packaging problems are cau
 
 ### Branch Model
 
-Releases are driven by commit history on protected branches:
+Releases are driven by commit history on the release branches:
+
+| Branch  | Channel          | Tag format       | Behaviour                     |
+| ------- | ---------------- | ---------------- | ----------------------------- |
+| `main`  | stable (default) | `v1.2.3`         | Full production release       |
+| `rc`    | `rc`             | `v1.2.3-rc.N`    | Release candidate pre-release |
+| `beta`  | `beta`           | `v1.2.3-beta.N`  | Beta pre-release              |
+| `alpha` | `alpha`          | `v1.2.3-alpha.N` | Alpha pre-release             |
+| `pre`   | `pre`            | `v1.2.3-pre.N`   | Pre-release                   |
 
-| Branch   | Channel          | Tag format      | Behaviour                     |
-| -------- | ---------------- | --------------- | ----------------------------- |
-| `main`   | stable (default) | `v1.2.3`        | Full production release       |
-| `beta`   | `beta`           | `v1.2.3-beta.N` | Beta pre-release              |
-| `pre/rc` | `pre/rc`         | `v1.2.3-rc.N`   | Release candidate pre-release |
+The channel becomes the npm dist-tag verbatim, which is why none of them contains a slash: npm reads a slash in a version selector as a GitHub shorthand, so such a tag cannot be installed.
 
 Tag format is `v${version}` (e.g., `v1.0.0-beta.46`).
 
@@ -158,7 +162,7 @@ Step by step:
 1. **Enable corepack** — activates the pinned pnpm version.
 2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
 3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
-4. **Build** — runs `tsc --build` to produce compiled `dist/` output in all packages.
+4. **Build** — runs `vite build && tsc --build` to produce compiled `dist/` output — JavaScript then declarations — in all packages.
 5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
 6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
 
@@ -169,10 +173,11 @@ Each publishable package is published in sequence via individual `@semantic-rele
 - `pkgRoot` — the package directory relative to the workspace root
 - `tarballDir` — `dist/releases/` where the packed `.tgz` is saved
 
-Example (from `.releaserc.json`):
+Example (from `release.config.mjs`, where these entries are generated rather than
+hand-written):
 
-```json
-["@semantic-release/npm", { "pkgRoot": "packages/play", "tarballDir": "dist/releases" }]
+```js
+["@semantic-release/npm", { pkgRoot: "packages/play", tarballDir: "dist/releases" }];
 ```
 
 ### Post-Release Phase
@@ -217,14 +222,14 @@ This means packages always depend on the exact same version of sibling packages
 | Variable                    | Source                                  | Purpose                                                                         |
 | --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
 | `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates `semantic-release` to npm registry via OIDC token exchange        |
-| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI protected variable            | Authenticates `@semantic-release/gitlab` for release creation and git push back |
+| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (unprotected)  | Authenticates `@semantic-release/gitlab` for release creation and git push back |
 | `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                  |
 
 **No static npm token is committed to the repository.** The `NPM_ID_TOKEN` is a short-lived OIDC token generated for each CI job with audience `npm:registry.npmjs.org`.
 
 To publish packages, a maintainer must:
 
-1. Have push access to a release-eligible branch (`main`, `beta`, `pre/rc`).
+1. Have push access to a release-eligible branch (`main`, `rc`, `beta`, `alpha`, `pre`). Only `main` is protected; see the branch model above for what changes if `GITLAB_TOKEN` is ever made a protected variable.
 2. Ensure the GitLab project CI/CD variables include the required tokens.
 
 ---
@@ -267,6 +272,22 @@ There is no automated rollback mechanism. To revert a release:
 
 ---
 
+## Recovering a Failed Release
+
+If the job dies partway (e.g. one package's trusted publisher isn't set up), some packages are published, the git tag is created, and the rest are missing. To finish the release:
+
+1. **Delete the release tag.** semantic-release creates the tag _before_ publishing, so a re-run while it exists is a no-op ([semantic-release#3178](https://github.com/semantic-release/semantic-release/issues/3178)):
+    ```bash
+    glab api --method DELETE "projects/xmachin-es%2Fxmachines-js/repository/tags/vX.Y.Z"
+    ```
+2. **Re-run the `semantic-release` job.**
+
+The config detects a staged-but-untagged version (a recovery re-run) and automatically demotes any package already on npm at that version to pack-only — re-packing it for the release assets but **not** re-publishing it — so the re-run publishes only what's missing, with no manual input. `SEMREL_SKIP_STEPS` (a regex matched against release step IDs) remains available as a manual override to force-skip specific steps.
+
+> First fix the underlying cause before re-running — e.g. configure the missing trusted publisher — otherwise the same packages fail again.
+
+---
+
 ## Local Release Dry-Run (Manual)
 
 To preview what semantic-release would do without publishing:

package/contributing/development.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Development
 
 This guide covers everything you need to set up a local development environment, understand the build system, and contribute code to the XMachines JS monorepo.
@@ -9,8 +7,10 @@ This guide covers everything you need to set up a local development environment,
 - [Local Setup](#local-setup)
 - [Monorepo Structure](#monorepo-structure)
 - [Build Commands](#build-commands)
+- [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)
 
@@ -42,14 +42,16 @@ pnpm install --frozen-lockfile
 pnpm run build
 ```
 
-The root-level `tsc --build` command uses TypeScript project references to build all packages in the correct dependency order automatically. You never need to sequence builds manually.
+The root build is two commands: `vite build` emits every package's JavaScript, then `tsc --build` emits the declarations through TypeScript project references, in dependency order. You never need to sequence builds manually.
 
-To build a single package (and its upstream dependencies):
+To build a single package:
 
 ```bash
 pnpm --filter @xmachines/<package-name> run build
 ```
 
+That runs the same two commands scoped to one package, so it produces the same `dist/` the root build would — JavaScript and declarations. It needs no other package's `dist/` to exist first: cross-package imports resolve to `src/` through the `source` export condition.
+
 ### Dev Container (Optional)
 
 A fully configured dev container is provided at `.devcontainer/`. It includes Docker-outside-of-Docker, Claude Code, and OpenCode.
@@ -82,7 +84,7 @@ packages/
 ├── play/                        # Core protocol (PlayEvent, PlayError)
 ├── play-signals/                # TC39 Signals polyfill wrapper
 ├── play-actor/                  # Abstract actor base (AbstractActor, Routable, Viewable)
-├── play-xstate/                 # XState v6 adapter (definePlayer, PlayerActor)
+├── play-xstate/                 # XState v5 adapter (definePlayer, PlayerActor)
 ├── play-router/                 # Route extraction and RouterBridgeBase
 ├── play-dom/                    # Vanilla DOM renderer
 ├── play-dom-router/             # DOM router adapter
@@ -132,8 +134,7 @@ All commands are run from the **repository root** unless otherwise noted.
 | `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                            |
 | `pnpm run test:browser`                    | Run Playwright browser tests                                          |
 | `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                  |
-| `pnpm run coverage:report`                 | Run tests and write an HTML coverage report                           |
-| `pnpm run coverage:summary`                | Run tests and write a JSON summary report                             |
+| `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                             |
 | `pnpm run test:build`                      | Type-check test files without running them (`tsconfig.test.json`)     |
 | `pnpm run lint`                            | Lint all packages with oxlint                                         |
 | `pnpm run lint:fix`                        | Auto-fix lint issues                                                  |
@@ -143,6 +144,45 @@ All commands are run from the **repository root** unless otherwise noted.
 
 ---
 
+## Updating Dependencies
+
+Every dependency is declared with the same range in every manifest that uses it, and a test fails if two disagree — `pnpm update` should move a package everywhere at once, not leave one package a minor behind.
+
+```bash
+pnpm update -r            # move within the declared ranges
+pnpm update -r --latest   # move the ranges themselves
+```
+
+`pnpm update -r` alone will not move a `0.x` dependency past its current minor: a caret on a `0.x` version means `>=0.58.0 <0.59.0`, because minors are where a pre-1.0 package is allowed to break. `oxfmt` sat six minors behind that way while `pnpm outdated` reported it on every pipeline. Use `--latest` for those, and read what changed.
+
+Two dependencies are pinned on purpose and must not be swept up:
+
+| Dependency   | Constraint                           | Why                                                                                                 |
+| ------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `playwright` | exact, equal to `PLAYWRIGHT_VERSION` | The browsers are baked into the CI image; the browser job fails on any mismatch                     |
+| `typescript` | `^5.9.3 \|\| ^6.0.3`                 | TypeScript 7 ships no programmatic compiler API, which TypeDoc and `@vue/compiler-sfc` both require |
+
+New versions also wait out pnpm's `minimumReleaseAge` (24 hours) before they can be installed at all.
+
+### Peer ranges are wider than what CI installs
+
+`peerDependencies` and `devDependencies` say different things about the same package, so the one-range rule does not apply across them and the test exempts peers.
+
+A peer range is a contract with the consumer: _bring your own React, anything in this range works_. It is deliberately wide, because the application owns that dependency — narrowing it forces consumers to upgrade in lockstep, or leaves two copies of a framework in their bundle. A dev range is what this repository installs to compile and test, and is concrete because CI needs one resolution.
+
+So `react: ^18.0.0 || ^19.0.0` as a peer alongside `react: ^19.2.5` as a dev dependency is the correct pairing, not drift.
+
+What that costs is worth stating plainly: **CI only ever exercises the dev version.** Two peers currently claim support across a major boundary that nothing here tests:
+
+| Package               | Peer range             | Tested against |
+| --------------------- | ---------------------- | -------------- |
+| `react` / `react-dom` | `^18.0.0 \|\| ^19.0.0` | 19.x           |
+| `vue-router`          | `^4.0.0 \|\| ^5.0.0`   | 5.x            |
+
+React 18 and vue-router 4 are supported by intent — nothing known depends on 19-only or 5-only behaviour — but neither is installed by any job, so a regression there would surface as a consumer's bug report rather than a red pipeline. Narrowing either range to what is tested would be a breaking change for consumers and needs a major release; adding a floor-install job would close the gap instead. Until one of those happens, treat the lower major as untested.
+
+---
+
 ## TypeScript Composite Build System
 
 The monorepo uses **TypeScript project references** for correct build-order management. No manual sequencing or separate build scripts are needed.
@@ -151,7 +191,7 @@ The monorepo uses **TypeScript project references** for correct build-order mana
 
 - The **root `tsconfig.json`** coordinates all packages via a `references` array — it compiles nothing itself
 - Each package has `composite: true` in its own `tsconfig.json`, enabling incremental and referenced builds
-- Packages declare `references` to their `@xmachines/*` dependencies so `tsc --build` resolves order automatically
+- The root `references` array is what orders the build; a package's own `tsc --build` needs no reference graph, because cross-package imports resolve to `src/` through the `source` export condition
 - With `declarationMap: true` in the base config, **Go to Definition** in your IDE navigates to `.ts` source files rather than compiled `.d.ts` files
 
 ### Build Layers
@@ -361,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:
@@ -375,13 +439,15 @@ refactor/route-map-extraction
 
 Release branches are managed by the project maintainers:
 
-| Branch   | Purpose                   |
-| -------- | ------------------------- |
-| `main`   | Stable releases           |
-| `beta`   | Pre-release beta channel  |
-| `pre/rc` | Release candidate channel |
+| Branch  | Purpose                   |
+| ------- | ------------------------- |
+| `main`  | Stable releases           |
+| `rc`    | Release candidate channel |
+| `beta`  | Pre-release beta channel  |
+| `alpha` | Pre-release alpha channel |
+| `pre`   | Pre-release channel       |
 
-**Do not** manually version packages or create release branches — releases are automated via semantic-release triggered by CI.
+**Do not** manually version packages or create release branches — semantic-release owns the version, and a release is cut by starting its manual CI job.
 
 ---
 
@@ -389,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.
 
 ```
@@ -445,19 +513,20 @@ 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
 
 The GitLab CI pipeline runs automatically on merge requests, pushes to `main`, and git tags.
 
-| Job                | Command                               | Artifacts                              |
-| ------------------ | ------------------------------------- | -------------------------------------- |
-| Build              | `pnpm run build`                      | —                                      |
-| Test with coverage | `vitest run --coverage`               | JUnit XML, Cobertura coverage report   |
-| Lint               | `oxlint .`                            | —                                      |
-| Audit              | `pnpm audit --audit-level=high`       | —                                      |
-| Semantic release   | (automated on `main`/`beta`/`pre/rc`) | CHANGELOG, npm publish, GitLab release |
+| Job                | Command                                          | Artifacts                              |
+| ------------------ | ------------------------------------------------ | -------------------------------------- |
+| Build              | `pnpm run build`                                 | —                                      |
+| Test with coverage | `vitest run --coverage`                          | JUnit XML, Cobertura coverage report   |
+| Lint               | `oxlint .`                                       | —                                      |
+| Audit              | `pnpm audit --audit-level=high`                  | —                                      |
+| Semantic release   | (manual job on `main`/`rc`/`beta`/`alpha`/`pre`) | CHANGELOG, npm publish, GitLab release |
 
 ---
 

package/contributing/testing.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Testing
 
 This document describes the test framework, conventions, and CI integration for the XMachines JS monorepo.
@@ -62,10 +60,20 @@ pnpm run test:coverage
 Produces coverage output in `text`, `html`, and `json-summary` formats.
 
 ```bash
-pnpm run coverage:report   # HTML report
-pnpm run coverage:summary  # JSON summary only
+pnpm run test:browser:coverage   # browser suite, with coverage
 ```
 
+Root-level coverage thresholds (regression gate):
+
+| Metric     | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Statements | 80%       |
+| Branches   | 75%       |
+
+Individual packages may enforce higher per-package thresholds in their own `vitest.config.ts`.
+
 ### Verify TypeScript test graph compiles
 
 ```bash
@@ -256,23 +264,32 @@ class MockActor extends AbstractActor<AnyActorLogic> implements Routable {
 }
 ```
 
-**Factory functions for lightweight inline mocks:**
+**Factory functions for lightweight inline mocks — use `stubOf`, never a double-cast:**
 
 ```typescript
+import { stubOf } from "@xmachines/shared/test-support";
+
 function createMockActor(initialView: PlaySpec | null = null) {
-	return {
+	return stubOf<AbstractActor<AnyActorLogic> & Viewable>({
 		currentView: new Signal.State<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
 		stop: vi.fn(),
 		getSnapshot: vi.fn(),
 		subscribe: vi.fn(),
-		state: new Signal.State({} as unknown),
+		state: new Signal.State<unknown>({}),
 		currentRoute: new Signal.Computed(() => null),
-	} as unknown as AbstractActor<AnyActorLogic> & Viewable;
+	});
 }
 ```
 
+`stubOf` keeps every declared member type-checked against the target type (a
+`send` with the wrong signature is a compile error) while allowing the rest to
+be absent — the one unsound assertion lives inside the helper, not at call
+sites. `X as unknown as T` is banned in this repo; if `stubOf` cannot express
+the case, `unsafeCast<T>(value)` from the same module is the deliberate,
+greppable escape hatch.
+
 ### Async and signal patterns
 
 **Flushing the microtask queue (required for Signal propagation):**
@@ -309,14 +326,16 @@ watcher.unwatch(actor.currentRoute); // Always clean up
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
 
 ```typescript
-const bad: PlaySpec = typedSpec<MyCtx>({
+const bad: PlaySpec = typedSpec({
 	root: "root",
-	// @ts-expect-error "typo" is not a key of MyCtx — typedSpec enforces this
-	contextProps: ["typo"],
 	elements: {},
+	// @ts-expect-error "stat" is not a PlaySpec field — typedSpec flags it on an
+	// inline literal (excess-property checking does not reach aliased or spread
+	// objects; use `satisfies PlaySpec` at the literal for those)
+	stat: {},
 });
 // At runtime the object exists; only the compile-time error is being tested
-expect(bad.contextProps).toEqual(["typo"]);
+expect(bad.root).toBe("root");
 ```
 
 For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `src/`:
@@ -335,8 +354,11 @@ These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.j
 ### Error testing
 
 ```typescript
-// Synchronous throws
-expect(() => actor.send(null as unknown as PlayEvent)).toThrow(InvalidEventError);
+import { unsafeCast } from "@xmachines/shared/test-support";
+
+// Synchronous throws — feed a runtime guard an invalid value through
+// unsafeCast, the named escape hatch (never `null as unknown as PlayEvent`).
+expect(() => actor.send(unsafeCast<PlayEvent>(null))).toThrow(InvalidEventError);
 
 // Error with message pattern
 expect(() => extractMachineRoutes(dupMachine)).toThrow(/Duplicate route paths detected/);

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,7 +6,7 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
 NavBar — App-shell navigation factory. Mounts a reactive nav into
 `container`, observes actor.state via watchSignal, and updates button

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -6,7 +6,7 @@
 function initShell(actor, appElement): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
 
 Shell — DOM shell layout factory. Renders demo chrome (header + main +
 debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.

package/examples/@xmachines/play-dom-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-dom-demo/variables/About.md

@@ -6,7 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/About.ts#L8)
 
 About — Public information page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

package/examples/@xmachines/play-dom-demo/variables/Contact.md

@@ -6,7 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
 
 Contact — Public contact page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Contact'>). Renders static content from props.

package/examples/@xmachines/play-dom-demo/variables/Dashboard.md

@@ -6,7 +6,7 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
 
 Dashboard — Protected authenticated home. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Dashboard'>). Renders welcome message; logout

package/examples/@xmachines/play-dom-demo/variables/Home.md

@@ -6,7 +6,7 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Home.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Home.ts#L9)
 
 Home — Public landing page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Home'>). Renders static welcome content from

package/examples/@xmachines/play-dom-demo/variables/Login.md

@@ -6,7 +6,7 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Login.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Login.ts#L9)
 
 Login — Authentication form. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Login'>). Binds username input to ctx.store via

package/examples/@xmachines/play-dom-demo/variables/NavBarView.md

@@ -6,7 +6,7 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
 
 NavBarView — Catalog-typed NavBar component for DOM renderer.
 

package/examples/@xmachines/play-dom-demo/variables/Navigation.md

@@ -6,7 +6,7 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
 
 Navigation — Navigation status display. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Navigation'>). Renders current path and auth

package/examples/@xmachines/play-dom-demo/variables/Overview.md

@@ -6,7 +6,7 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
 
 Overview — Dashboard overview child route. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Overview'>). Relative route resolves to