@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/contributing/development.md

@@ -0,0 +1,503 @@
+# 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.
+
+## Table of Contents
+
+- [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)
+- [Branch Conventions](#branch-conventions)
+- [PR Process](#pr-process)
+
+---
+
+## Local Setup
+
+### Prerequisites
+
+- **Node.js** `>= 22.0.0`
+- **pnpm** via corepack (`corepack enable`; version pinned by the `packageManager` field — the project uses pnpm workspaces)
+- **Git**
+
+No global tool installs are required beyond Node.js. All build, lint, and format tooling is installed locally via `pnpm install --frozen-lockfile`.
+
+### Clone and Install
+
+```bash
+git clone git@gitlab.com:xmachin-es/xmachines-js.git
+cd xmachines-js
+pnpm install --frozen-lockfile
+```
+
+> **Use `pnpm install --frozen-lockfile` (not `pnpm install`)** — it installs the exact versions from the lockfile.
+
+### Build
+
+```bash
+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.
+
+To build a single package (and its upstream dependencies):
+
+```bash
+pnpm --filter @xmachines/<package-name> run build
+```
+
+### Dev Container (Optional)
+
+A fully configured dev container is provided at `.devcontainer/`. It includes Docker-outside-of-Docker, Claude Code, and OpenCode.
+
+```bash
+pnpm run devcontainer:up
+```
+
+Or open the repository in VS Code and choose **Reopen in Container** when prompted.
+
+### Verify Your Setup
+
+```bash
+pnpm test              # Run the full test suite
+pnpm run lint          # Check for lint errors
+pnpm run format:check  # Check formatting without modifying files
+```
+
+All three should pass without errors on a freshly cloned repository.
+
+---
+
+## Monorepo Structure
+
+The repository is organized as a **pnpm 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.
+
+### 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      # Composite build config (extends tsconfig.base.json)
+├── tsconfig.base.json # Local base (extends @xmachines/shared/tsconfig)
+├── vitest.config.ts   # Package test config
+└── README.md
+```
+
+---
+
+## Build Commands
+
+All commands are run from the **repository root** unless otherwise noted.
+
+| Command                                    | Description                                                           |
+| ------------------------------------------ | --------------------------------------------------------------------- |
+| `pnpm run build`                           | TypeScript composite build — all packages in dependency order         |
+| `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                 |
+| `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages |
+| `pnpm test`                                | Run all unit/integration tests once                                   |
+| `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 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                                                  |
+| `pnpm run format`                          | Format all files with oxfmt                                           |
+| `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                |
+| `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                |
+
+---
+
+## 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.
+
+### How It Works
+
+- 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
+- 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
+
+Packages are grouped into dependency layers as defined in the root `tsconfig.json`:
+
+| Layer | Packages                                                                                                                                                                                                                                                                  | Depends on         |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| 0     | `play-signals`, `play`, `docs`                                                                                                                                                                                                                                            | External libs only |
+| 1     | `play-actor`                                                                                                                                                                                                                                                              | Layer 0            |
+| 2     | `play-router`, `play-dom-router`, `play-sveltekit-router`, `play-xstate`, `play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-svelte-spa-router`, `play-tanstack-solid-router` | Layers 0–1         |
+| 3     | `play-react-router`, example demo apps                                                                                                                                                                                                                                    | Layer 2            |
+
+#### Mermaid Diagram
+
+```mermaid
+flowchart LR
+    subgraph L0["Layer 0 — no internal deps"]
+        play-signals
+        play
+        docs
+    end
+
+    subgraph L1["Layer 1"]
+        play-actor
+    end
+
+    subgraph L2["Layer 2 — view renderers & router adapters"]
+        play-router
+        play-dom-router
+        play-sveltekit-router
+        play-xstate
+        play-react
+        play-vue
+        play-solid
+        play-svelte
+        play-dom
+        play-tanstack-react-router
+        play-vue-router
+        play-solid-router
+        play-svelte-spa-router
+        play-tanstack-solid-router
+    end
+
+    subgraph L3["Layer 3 — application layer"]
+        play-react-router
+        examples["example demo apps"]
+    end
+
+    L0 --> L1
+    L1 --> L2
+    L2 --> L3
+```
+
+### Adding a New Package
+
+1. **Create the package directory** following the standard structure:
+
+    ```
+    packages/<your-package>/
+    ├── src/
+    │   └── index.ts
+    ├── test/
+    ├── package.json      # must have "type": "module"
+    ├── tsconfig.json
+    ├── tsconfig.base.json
+    ├── vitest.config.ts
+    └── README.md
+    ```
+
+2. **`tsconfig.base.json`** — extend the shared config:
+
+    ```json
+    {
+    	"$schema": "https://json.schemastore.org/tsconfig",
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": {
+    		"skipLibCheck": true
+    	}
+    }
+    ```
+
+    If the package depends on other monorepo packages, add `references`:
+
+    ```json
+    {
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": { "skipLibCheck": true },
+    	"references": [{ "path": "../play" }, { "path": "../play-actor" }]
+    }
+    ```
+
+3. **`tsconfig.json`** — enable composite build:
+
+    ```json
+    {
+    	"$schema": "https://json.schemastore.org/tsconfig",
+    	"extends": "./tsconfig.base.json",
+    	"compilerOptions": {
+    		"composite": true,
+    		"rootDir": "./src",
+    		"outDir": "./dist"
+    	},
+    	"include": ["src/**/*"]
+    }
+    ```
+
+4. **Register in root `tsconfig.json`** — add a reference in the correct layer:
+
+    ```json
+    {
+    	"references": [{ "path": "./packages/your-package" }]
+    }
+    ```
+
+5. **Register in root `tsconfig.test.json`** and **root `vitest.config.ts`** (`projects` array).
+
+---
+
+## Code Style
+
+All style rules are **mandatory** — CI enforces them on every merge request.
+
+### Formatter — oxfmt
+
+oxfmt (Biome-based) is configured via `oxfmt.config.ts` at the root (extends `@xmachines/shared/oxfmt`).
+
+```bash
+pnpm run format          # Format all files
+pnpm run format:check    # Check without writing (CI mode)
+```
+
+Key settings (from `packages/shared/config/oxfmt.config.ts`):
+
+| Setting         | Value                                 |
+| --------------- | ------------------------------------- |
+| Print width     | 100 characters                        |
+| Indentation     | Tabs (`useTabs: true`, `tabWidth: 4`) |
+| Semicolons      | Always (`semi: true`)                 |
+| Quotes          | Double (`singleQuote: false`)         |
+| Trailing commas | All                                   |
+| JSON / YAML     | 2-space indent (override)             |
+
+### Linter — oxlint
+
+oxlint is configured via `oxlint.config.ts` at the root (extends `@xmachines/shared/oxlint`).
+
+```bash
+pnpm run lint        # Lint all packages
+pnpm run lint:fix    # Auto-fix lint issues
+```
+
+Active plugins: `typescript`, `unicorn`, `import`. Key rules:
+
+| Rule                         | Severity                       |
+| ---------------------------- | ------------------------------ |
+| `typescript/no-explicit-any` | error                          |
+| `import/no-cycle`            | error                          |
+| `typescript/no-unused-vars`  | error (prefix unused with `_`) |
+| `correctness` category       | error                          |
+| `suspicious` category        | warn                           |
+
+### Editor Config
+
+`.editorconfig` is present at the root and enforces:
+
+- Tabs for indentation in all source files
+- 2-space indent for JSON/YAML
+- LF line endings, UTF-8, insert final newline
+
+### TypeScript Strict Mode
+
+All packages extend `@xmachines/shared/tsconfig` which enables full strict mode. Mandatory constraints:
+
+| Option                       | Value  |
+| ---------------------------- | ------ |
+| `strict`                     | `true` |
+| `noUnusedLocals`             | `true` |
+| `noUnusedParameters`         | `true` |
+| `noImplicitReturns`          | `true` |
+| `noImplicitOverride`         | `true` |
+| `exactOptionalPropertyTypes` | `true` |
+| `verbatimModuleSyntax`       | `true` |
+| `isolatedModules`            | `true` |
+
+Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters with `_` to suppress errors.
+
+### Import Rules
+
+1. Always use `.js` extensions in imports, even for TypeScript source files:
+
+    ```typescript
+    // ✅ Correct
+    import { PlayError } from "./errors.js";
+
+    // ❌ Wrong — will not resolve at runtime with NodeNext module resolution
+    import { PlayError } from "./errors";
+    ```
+
+2. Use `import type` for type-only imports (required by `verbatimModuleSyntax`):
+
+    ```typescript
+    import type { RouteNode, RouteTree } from "../src/types.js";
+    ```
+
+3. Import order: Node.js built-ins (`node:` prefix) → external packages → internal `@xmachines/*` packages → relative imports
+
+---
+
+## Branch Conventions
+
+Use a `<type>/` prefix that matches the conventional commit type for the work being done:
+
+```
+feat/vue-router-adapter
+fix/signal-watcher-cleanup
+docs/play-actor-jsdoc
+chore/update-vitest-4
+refactor/route-map-extraction
+```
+
+Release branches are managed by the project maintainers:
+
+| 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 — semantic-release owns the version, and a release is cut by starting its manual CI job.
+
+---
+
+## PR Process
+
+### Commit Messages
+
+This project uses **Conventional Commits** — changelogs and version bumps are generated automatically from commit history.
+
+```
+<type>[(<scope>)][!]: <short description>
+
+[optional body]
+
+[optional footer]
+```
+
+| Type       | Triggers version bump     | When to use                              |
+| ---------- | ------------------------- | ---------------------------------------- |
+| `feat`     | Minor                     | New user-facing feature                  |
+| `fix`      | Patch                     | Bug fix                                  |
+| `docs`     | No bump                   | Documentation only                       |
+| `refactor` | No bump                   | Code restructure without behavior change |
+| `test`     | No bump                   | Adding or updating tests                 |
+| `chore`    | No bump                   | Build, tooling, or dependency changes    |
+| `perf`     | No bump (unless breaking) | Performance improvements                 |
+| `ci`       | No bump                   | CI/CD pipeline changes                   |
+
+Breaking changes: append `!` after the type (`feat!:`) or add `BREAKING CHANGE:` in the footer.
+
+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
+```
+
+### Before Submitting
+
+1. **Read the relevant RFC** in [`packages/docs/rfc/`](../rfc/) — ensure your change conforms to the spec
+2. **Run the full check suite** from the repo root:
+
+    ```bash
+    pnpm run build
+    pnpm test
+    pnpm run lint
+    pnpm run format:check
+    ```
+
+3. **Write tests** — new code must meet coverage thresholds (80% lines/functions/statements and 75% branches at the monorepo level; core packages enforce higher per-package thresholds)
+4. **Add JSDoc** — all new public exports require JSDoc with `@param`, `@returns`, and `@see` RFC links
+5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `pnpm run docs`
+
+### Merge Request Checklist
+
+- [ ] Branch is up to date with `main`
+- [ ] All tests pass (`pnpm test`)
+- [ ] Lint passes (`pnpm run lint`)
+- [ ] Formatting is correct (`pnpm run format:check`)
+- [ ] Build succeeds (`pnpm run build`)
+- [ ] New code has tests at or above coverage thresholds
+- [ ] All new public exports have JSDoc
+- [ ] Conventional commit format used on all commits
+- [ ] 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   | (manual job on `main`/`rc`/`beta`/`alpha`/`pre`) | CHANGELOG, npm publish, GitLab release |
+
+---
+
+_See [Architecture](architecture.md) for the package layering and data flow details, and [Configuration](configuration.md) for tooling configuration reference._