@xmachines/docs 1.0.0-beta.45 → 1.0.0-beta.48

package/guides/development.md

@@ -0,0 +1,617 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Development Guide
+
+This guide covers everything you need to contribute to the XMachines JS monorepo — from setting up your environment through the full build, test, lint, and release lifecycle.
+
+---
+
+## Prerequisites
+
+| Requirement | Version              | Notes                                                    |
+| ----------- | -------------------- | -------------------------------------------------------- |
+| Node.js     | `>= 22.0.0`          | Specified in all `package.json` `engines` fields         |
+| npm         | Bundled with Node 22 | Workspaces support required                              |
+| TypeScript  | `^5.7+`              | Installed as a dev dependency — no global install needed |
+| Git         | Any recent version   | Commit message format enforced by CI                     |
+
+No global tool installs are required beyond Node.js. All build, lint, and format tooling is installed locally via `npm ci`.
+
+---
+
+## Local Setup
+
+### 1. Clone the repository
+
+```bash
+git clone git@gitlab.com:xmachin-es/xmachines-js.git
+cd xmachines-js
+```
+
+### 2. Install dependencies
+
+Always use `npm ci` (not `npm install`) so the lockfile is respected:
+
+```bash
+npm ci
+```
+
+`postinstall` automatically runs `patch-package` to apply the patches in `patches/` — this is expected and required.
+
+### 3. Build all packages
+
+```bash
+npm run build
+```
+
+The build uses TypeScript project references (`tsc --build`) and compiles all packages in dependency order. Build outputs go to each package's `dist/` directory. The `dist/` directories are gitignored.
+
+### 4. Verify
+
+```bash
+npm test
+```
+
+All tests should pass on a clean install. If any fail, check the [Common Setup Issues](#common-setup-issues) section.
+
+---
+
+## Dev Container (Optional)
+
+A fully configured dev container is provided at `.devcontainer/`. It includes Docker-outside-of-Docker, Claude Code, and OpenCode.
+
+```bash
+npm run devcontainer:up
+```
+
+Or open the repository in VS Code and choose **Reopen in Container** when prompted.
+
+---
+
+## Monorepo Structure
+
+The repository is organized as an **npm workspaces** monorepo with all packages under `packages/`:
+
+```
+packages/
+├── shared/                      # Shared configs (tsconfig, oxlint, oxfmt, vitest)
+├── play/                        # Core protocol (PlayEvent, PlayError)
+├── play-signals/                # TC39 Signals polyfill wrapper
+├── play-actor/                  # Abstract actor base (AbstractActor, Routable, Viewable)
+├── play-xstate/                 # XState v5 adapter (definePlayer, PlayerActor)
+├── play-router/                 # Route extraction and RouterBridgeBase
+├── play-dom/                    # Vanilla DOM renderer
+├── play-dom-router/             # DOM router adapter
+├── play-react/                  # React renderer (PlayRenderer)
+├── play-react-router/           # React Router v7 adapter
+├── play-vue/                    # Vue 3 renderer
+├── play-vue-router/             # Vue Router adapter
+├── play-solid/                  # SolidJS renderer
+├── play-solid-router/           # SolidJS Router adapter
+├── play-svelte/                 # Svelte renderer
+├── play-svelte-spa-router/      # Svelte SPA Router adapter
+├── play-sveltekit-router/       # SvelteKit Router adapter
+├── play-tanstack-react-router/  # TanStack Router (React)
+├── play-tanstack-solid-router/  # TanStack Router (SolidJS)
+└── docs/                        # API docs, guides, RFCs (@xmachines/docs)
+```
+
+Many packages also contain an `examples/` subdirectory with runnable demo apps.
+
+### Package naming convention
+
+All packages use the `@xmachines/` npm scope. The package directory name matches the npm name without the scope:
+
+- `packages/play` → [`@xmachines/play`](../api/@xmachines/play/README.md)
+- `packages/play-actor` → [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)
+
+### Standard package layout
+
+```
+packages/<name>/
+├── src/              # TypeScript source files
+├── dist/             # Build output (gitignored)
+├── test/             # Test files (*.spec.ts or *.test.ts)
+├── examples/         # Runnable demo apps (optional)
+├── package.json      # Must have "type": "module"
+├── tsconfig.json     # Extends shared base config
+├── tsconfig.base.json # Local base (extends @xmachines/shared/tsconfig)
+├── vitest.config.ts  # Package test config
+└── README.md
+```
+
+---
+
+## Build System
+
+### Build commands
+
+| Command                            | Description                                                |
+| ---------------------------------- | ---------------------------------------------------------- |
+| `npm run build`                    | Build all packages in dependency order (incremental)       |
+| `npm run build -w packages/<name>` | Build a specific package (and its deps)                    |
+| `npm run test:build`               | Type-check the full test TypeScript graph without emitting |
+| `npm run clean`                    | Remove all build outputs and caches across all packages    |
+
+### TypeScript composite build
+
+This monorepo uses **TypeScript project references** (`composite: true`) for build-order management.
+
+- **`tsconfig.json`** at the root coordinates all packages via its `references` array — it does not compile anything itself
+- Each package's `tsconfig.json` sets `composite: true`, `rootDir: "./src"`, and `outDir: "./dist"`
+- TypeScript understands the full dependency graph and builds packages in the correct order automatically
+- Incremental builds: only changed packages are rebuilt
+- `declarationMap: true` is set in the base config — **Go to Definition** in your IDE jumps to source `.ts` files, not compiled `.d.ts`
+
+**Dependency layers** (from `tsconfig.json`):
+
+| Layer   | Packages                                                              |
+| ------- | --------------------------------------------------------------------- |
+| Layer 0 | `play-signals`, `play`, `docs` — no internal dependencies             |
+| Layer 1 | `play-actor` — depends on Layer 0                                     |
+| Layer 2 | `play-router`, `play-xstate`, all view renderers, all router adapters |
+| Layer 3 | Example applications                                                  |
+
+---
+
+## Adding a New Package
+
+Follow these steps when creating a new package:
+
+### 1. Create the package directory
+
+```bash
+mkdir packages/my-new-package
+```
+
+### 2. Create `package.json`
+
+Must include `"type": "module"` and follow the standard scripts pattern:
+
+```json
+{
+	"name": "@xmachines/my-new-package",
+	"version": "1.0.0-beta.46",
+	"type": "module",
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc --build",
+		"clean": "rm -rf dist *.tsbuildinfo coverage",
+		"test": "vitest",
+		"lint": "oxlint .",
+		"lint:fix": "oxlint --fix .",
+		"format": "oxfmt .",
+		"format:check": "oxfmt --check .",
+		"prepublishOnly": "npm run build"
+	},
+	"devDependencies": {
+		"@xmachines/shared": "1.0.0-beta.46",
+		"oxfmt": "^0.45.0",
+		"oxlint": "^1.60.0",
+		"vitest": "^4.1.4"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	}
+}
+```
+
+### 3. Create `tsconfig.json`
+
+```json
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"include": ["src/**/*"]
+}
+```
+
+### 4. Create `tsconfig.base.json`
+
+```json
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"skipLibCheck": true
+	}
+}
+```
+
+If the package depends on other packages in this monorepo, add `references`:
+
+```json
+{
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": { "skipLibCheck": true },
+	"references": [{ "path": "../play" }, { "path": "../play-actor" }]
+}
+```
+
+### 5. Register in root `tsconfig.json`
+
+Add an entry to the `references` array in the appropriate layer:
+
+```json
+{
+	"references": [{ "path": "./packages/my-new-package" }]
+}
+```
+
+### 6. Register in root `tsconfig.test.json`
+
+```json
+{
+	"references": [{ "path": "./packages/my-new-package/tsconfig.test.json" }]
+}
+```
+
+### 7. Create `vitest.config.ts`
+
+```typescript
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		environment: "node",
+		include: ["test/**/*.spec.ts", "test/**/*.test.ts"],
+		coverage: {
+			provider: "v8",
+			include: ["src/**/*.ts"],
+			thresholds: {
+				lines: 80,
+				functions: 80,
+				branches: 75,
+				statements: 80,
+			},
+		},
+	},
+});
+```
+
+### 8. Register in root `vitest.config.ts`
+
+Add the package's `vitest.config.ts` to the `projects` array in the root `vitest.config.ts`.
+
+---
+
+## Code Style
+
+### Rules enforced
+
+**All rules below are mandatory and enforced in CI.**
+
+#### 1. `.js` extensions on all imports
+
+Even in TypeScript source files, imports must use `.js` extensions. This is required by Node.js ESM resolution:
+
+```typescript
+// ✅ Correct
+import { foo } from "./bar.js";
+import { PlayEvent } from "@xmachines/play";
+
+// ❌ Wrong — will fail at runtime
+import { foo } from "./bar";
+```
+
+#### 2. ESM only — no CommonJS
+
+Every package has `"type": "module"` in its `package.json`. Do not use `require()`, `module.exports`, or `.cjs` files.
+
+#### 3. Strict TypeScript
+
+The base `tsconfig.json` enables the full strict suite plus additional checks:
+
+| Option                       | Value  |
+| ---------------------------- | ------ |
+| `strict`                     | `true` |
+| `noUnusedLocals`             | `true` |
+| `noUnusedParameters`         | `true` |
+| `noImplicitReturns`          | `true` |
+| `noImplicitOverride`         | `true` |
+| `exactOptionalPropertyTypes` | `true` |
+| `verbatimModuleSyntax`       | `true` |
+| `isolatedModules`            | `true` |
+
+Use `import type` for type-only imports (required by `verbatimModuleSyntax`).
+
+#### 4. No `any`
+
+`typescript/no-explicit-any` is set to `"error"` in the shared oxlint config. Use `unknown` or appropriate generic types instead.
+
+### Linting (oxlint)
+
+The project uses **oxlint** — a Rust-based linter with TypeScript, unicorn, and import plugins.
+
+```bash
+npm run lint          # Lint all packages
+npm run lint:fix      # Auto-fix lint issues across all packages
+```
+
+Root config: `oxlint.config.ts`  
+Shared base: `packages/shared/config/oxlint.config.ts`
+
+Enabled categories: `correctness: error`, `suspicious: warn`, `perf: warn`. Import cycle detection (`import/no-cycle`) is set to `"error"`.
+
+### Formatting (oxfmt)
+
+The project uses **oxfmt** — an opinionated formatter.
+
+```bash
+npm run format         # Format all files in place
+npm run format:check   # Check formatting without writing (CI mode)
+```
+
+Root config: `oxfmt.config.ts`  
+Shared base: `packages/shared/config/oxfmt.config.ts`
+
+Key settings (from shared config):
+
+| Setting         | Value                     |
+| --------------- | ------------------------- |
+| Print width     | 100                       |
+| Indentation     | Tabs (width 4)            |
+| Semicolons      | `true`                    |
+| Quotes          | Double                    |
+| Trailing commas | All                       |
+| JSON/YAML files | 2-space indent (override) |
+
+### EditorConfig
+
+An `.editorconfig` at the project root ensures consistent whitespace in editors:
+
+- All files: tabs (4-wide), LF line endings, insert final newline
+- JSON/YAML: spaces (2-wide)
+- Markdown: trailing whitespace preserved
+
+---
+
+## Testing
+
+### Test framework
+
+All packages use **Vitest 4.x** with **v8 coverage**.
+
+### Running tests
+
+| Command                    | Description                                      |
+| -------------------------- | ------------------------------------------------ |
+| `npm test`                 | Run all tests (node environment)                 |
+| `npm run test:watch`       | Interactive watch mode                           |
+| `npm run test:ui`          | Vitest browser UI for visual debugging           |
+| `npm run test:browser`     | Run browser-mode tests (Playwright/Chromium)     |
+| `npm run test:coverage`    | Run with coverage, output text/HTML/JSON-summary |
+| `npm run coverage:report`  | Coverage with HTML report                        |
+| `npm run coverage:summary` | Coverage with JSON summary                       |
+| `npm run test:build`       | Type-check all test files (no emit)              |
+
+To run tests for a single package in isolation:
+
+```bash
+npm test -w packages/play-actor
+```
+
+### Test file conventions
+
+- Place test files in `test/` within each package
+- Use `.spec.ts` or `.test.ts` extensions
+- Both are supported; `.spec.ts` is the conventional choice for unit tests
+
+### Coverage thresholds
+
+Root-level (regression gate for the full monorepo):
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 75%       |
+| Statements | 80%       |
+
+Core packages enforce higher per-package thresholds in their own `vitest.config.ts`. For example, `play-actor` requires 90% lines/functions/statements and 85% branches.
+
+### Browser tests
+
+Browser tests use Vitest's Playwright integration (Chromium). They run separately from node tests:
+
+```bash
+npm run test:browser
+```
+
+Browser test configs are named `vitest.browser.config.ts` inside each package. Not all packages have browser tests — add them only when the code has meaningful browser-specific behavior.
+
+### Shared test setup
+
+The [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md) helper ([`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md)) automatically:
+
+- Configures `@xmachines/*` path aliases so tests resolve to source files
+- Injects the shared setup file (`vitest.setup.ts`) for global test utilities
+- Injects the node setup file (`vitest.node.setup.ts`) for non-browser packages
+
+Use [`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) in every package's `vitest.config.ts` instead of bare `defineConfig`.
+
+---
+
+## Commit Conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/). Commit messages are parsed by `semantic-release` to determine version bumps and changelog entries.
+
+### Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type       | Triggers                  | When to use                                |
+| ---------- | ------------------------- | ------------------------------------------ |
+| `feat`     | Minor bump                | New user-facing feature                    |
+| `fix`      | Patch bump                | Bug fix                                    |
+| `docs`     | No bump                   | Documentation only                         |
+| `chore`    | No bump                   | Build scripts, tooling, dependencies       |
+| `refactor` | No bump                   | Code restructuring without behavior change |
+| `test`     | No bump                   | Adding or updating tests                   |
+| `perf`     | No bump (unless breaking) | Performance improvement                    |
+| `ci`       | No bump                   | CI configuration changes                   |
+
+A `BREAKING CHANGE:` footer or `!` after the type triggers a major version bump:
+
+```
+feat!: drop Node 20 support
+
+BREAKING CHANGE: Minimum Node version is now 22.
+```
+
+### Scope (optional)
+
+Use the package short-name as scope when the change is isolated to one package:
+
+```
+fix(play-actor): correct signal cleanup on dispose
+feat(play-react): add PlayRenderer suspense boundary
+```
+
+---
+
+## Documentation
+
+API documentation is generated from TypeScript source using **TypeDoc**.
+
+```bash
+npm run docs
+```
+
+This runs the full build, generates API docs into `packages/docs/api/`, then formats the output.
+
+**Important:** `packages/docs/api/` is auto-generated and committed to git. **Never edit files inside it directly.** Always regenerate via `npm run docs`.
+
+### RFC links in JSDoc
+
+RFC files live at `packages/docs/rfc/`. Use relative links in `@see` tags:
+
+```typescript
+/**
+ * @see `Play RFC`
+ */
+```
+
+TypeDoc's custom plugin (`typedoc.config.mjs`) handles rewriting these links in the generated output.
+
+---
+
+## Patches
+
+The `patches/` directory contains `patch-package` patches applied automatically during `npm ci` and `npm install` (via the `postinstall` script).
+
+Current patches are for `@json-render` packages. Do not remove or manually modify patch files — they are required for the build to succeed.
+
+To create a new patch after modifying a file in `node_modules/`:
+
+```bash
+npx patch-package <package-name>
+```
+
+---
+
+## Release Process
+
+Releases are fully automated via **semantic-release** running in GitLab CI. No manual version bumping or tagging is required.
+
+### How releases work
+
+1. Commits merged to `main` are analyzed by `@semantic-release/commit-analyzer`
+2. If releasable commits are present, semantic-release:
+    - Determines the next version from commit types
+    - Updates all workspace `package.json` versions via `scripts/set-workspace-versions.mjs`
+    - Builds all packages and regenerates API docs
+    - Publishes all publishable packages to npm
+    - Creates a GitLab release with tarball artifacts
+    - Commits `CHANGELOG.md`, updated `package.json` files, and generated docs back to the branch
+
+### Release branches
+
+| Branch   | Channel | Pre-release tag |
+| -------- | ------- | --------------- |
+| `main`   | stable  | —               |
+| `beta`   | beta    | `beta`          |
+| `pre/rc` | pre/rc  | `rc`            |
+
+### Smoke testing before release
+
+The `release-pack-smoke` CI job validates that packed tarballs install correctly:
+
+```bash
+npm run build
+node scripts/release-pack-smoke.mjs
+```
+
+This job runs automatically on `main` pushes and tags but can be triggered manually on other branches.
+
+### Published packages
+
+All packages listed in `.releaserc.json` with `npmPublish: true` (the default) are published to npm under the `@xmachines/` scope. Example packages (`examples/demo`) are packed for the GitLab release but not published to npm.
+
+---
+
+## CI Pipeline
+
+The GitLab CI pipeline (`.gitlab-ci.yml`) runs on:
+
+- Every push to `main`
+- Every merge request
+- Every git tag
+
+### Pipeline stages
+
+| Job                  | Description                                                                   |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `node-build`         | Lints, builds, and runs `test:coverage`; reports JUnit and Cobertura coverage |
+| `semantic-release`   | Automated release on `main`, `beta`, and `pre/rc` branches                    |
+| `release-pack-smoke` | Validates packed tarballs install correctly                                   |
+
+The pipeline uses the `to-be-continuous/node` component and `to-be-continuous/semantic-release` component from the GitLab CI component catalog.
+
+**Coverage gate:** The CI reports coverage in Cobertura format. The regex `/All files[^|]*\|[^|]*\s+([\d\.]+)/` extracts the aggregate coverage percentage.
+
+---
+
+## Common Setup Issues
+
+**Tests fail with `Cannot find module` errors**
+: Run `npm run build` before running tests. Some packages need their `dist/` present even in development. Alternatively, ensure [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/vite-aliases/README.md) aliases are configured in your `vitest.config.ts` — use [`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) from [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md) to get them automatically.
+
+**TypeScript errors about missing types after adding a dependency**
+: Run `npm ci` to ensure all types are installed. If adding a workspace-local dependency, also add the correct `references` entry to the package's `tsconfig.base.json`.
+
+**`patch-package` errors during install**
+: The patches in `patches/` are version-specific. If you update a `@json-render` package, the patches may need to be regenerated with `npx patch-package <pkg>`.
+
+**Lint errors on import extensions**
+: All imports must end with `.js`. This applies to relative imports even for `.ts` source files. Your editor's auto-import may omit the extension — fix it manually or configure your editor to add it automatically.
+
+**Build is slow after a `git clean`**
+: TypeScript incremental builds use `.tsbuildinfo` files. After a full clean these are gone and the initial build will be slower. This is expected.
+
+---
+
+## Related Documentation
+
+- [Architecture](ARCHITECTURE.md) — System design, component diagram, data flow
+- [Configuration](CONFIGURATION.md) — Environment variables and config files
+- [RFC docs](../rfc/) — Canonical specifications for each protocol