bQuery · JosunLP · Jun 29, 2026 · Jun 29, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -99,6 +99,8 @@ and this project adheres to Semantic Versioning.
 - **`@bquery/bquery/a11y`** — the runtime audit now stamps each `AuditFinding` with its WCAG 2.1 criterion (`wcag`), and the full rule catalog is exported as `auditRules` ([#142](https://github.com/bQuery/bQuery/issues/142)) — each rule documents its WCAG mapping, default severity, and a known limitation (what it cannot detect).
 - **`@bquery/bquery/plugin`** — new `definePlugin()` authoring helper ([#145](https://github.com/bQuery/bQuery/issues/145)): an identity helper that infers a plugin's install-options type and gives third-party authors a single, stable entry point.
 - **`@bquery/bquery/devtools`** — new stable, versioned bridge protocol for the DevTools browser extension ([#146](https://github.com/bQuery/bQuery/issues/146)): `connectDevtoolsBridge()` (over `window.postMessage`), the transport-agnostic `createBridgeServer()`, `serializeComponentTree()`, and `BRIDGE_PROTOCOL_VERSION` / `BRIDGE_SOURCE` / `BRIDGE_CAPABILITIES`. A reference Manifest V3 extension (component tree, signal/store inspection, live timeline) ships in `extension/`.
+- **`@bquery/bquery/router` + `@bquery/bquery/server`** — opt-in, bundler-agnostic file-route convention with typed `load` / `action` ([#149](https://github.com/bQuery/bQuery/issues/149)). New `createFileRoutes(manifest, options?)` turns a manifest (a bundler glob such as `import.meta.glob`, or a hand-written map) into the same `RouteDefinition`s `createRouter()` already consumes, with `parseFilePath` / `filePathToRoutePattern` (`routes/users/[id]/+page.ts` → `/users/:id`, `[...rest]` → `*`, `(group)` dropped) and specificity sorting (`sortEntriesBySpecificity`). Route modules export a typed `Load` (data into the view) and `Action` (mutation target). Loaders run on the server before render (the SSR router bridge now recognises `meta.load` alongside `meta.loader`) and on client navigation via `createRouteData(router)` / `useRouteData()`. The `server` module exposes `mountFileRoutes(app, entries, options?)` / `createFileRouteServerRoutes()` so a `<form>` (or `formAction()`) posts to a route's `action`, composing with `csrf()`. Programmatic routing stays fully supported and unchanged; no bundler is shipped. See the new [File-based Routing guide](https://bquery.js.org/guide/file-routing).
+- **Docs / Stability** — single-source [Stability Matrix](https://github.com/bQuery/bQuery/blob/main/STABILITY.md) plus a per-module stability changelog ([#150](https://github.com/bQuery/bQuery/issues/150)). A new canonical `STABILITY.md` (backed by `scripts/stability-matrix.mjs`) records each module's maturity and its status-transition history; the README "Modules at a glance" table and the docs `introduction.md` matrix are now validated against it by `bun run check:stability` (`scripts/check-stability-matrix.mjs`), so the three surfaces can no longer silently drift.
 
 ### Changed (Unreleased)
 
@@ -118,6 +120,18 @@ and this project adheres to Semantic Versioning.
 - **`@bquery/bquery/view`** — `bq-for` duplicate-key handling is resolved ([#136](https://github.com/bQuery/bQuery/issues/136)): colliding keys now fall back to a deterministic, referentially-stable composite key so duplicate rows reuse their DOM across re-renders, and the duplicate-key warning is dev-only and emitted once per offending key instead of on every reactive update.
 - **`@bquery/bquery/view`** — object-expression shorthand is resolved ([#136](https://github.com/bQuery/bQuery/issues/136)): `bq-class="{ active }"` (and `bq-style` / `bq-aria` object syntax) now behaves like JS object shorthand (`{ active: active }`) instead of silently dropping the property.
 
+### Module status (Unreleased)
+
+Canonical source: [STABILITY.md](https://github.com/bQuery/bQuery/blob/main/STABILITY.md) (enforced by `bun run check:stability`).
+
+- `view`, `forms`, `i18n`, `a11y`, `dnd`, `media`, `plugin`, `devtools`, `testing`, `storybook`: Beta (API frozen, targeting Stable in 1.15.0).
+- `concurrency`, `ssr`, `server`: Experimental (surface frozen, targeting Stable in 1.15.0).
+- `router`: Stable — file-route convention added as a strictly additive, opt-in surface ([#149](https://github.com/bQuery/bQuery/issues/149)); no status change.
+
+#### Breaking changes (Beta/Experimental, per policy)
+
+- None this cycle. The graduations above freeze each surface for one minor; no breaking changes are flagged.
+
 ## [1.14.2] - 2026-06-26
 
 ### Fixed (1.14.2)

diff --git a/README.md b/README.md
@@ -202,6 +202,9 @@ import { storyHtml, when } from '@bquery/bquery/storybook';
 
 ## Modules at a glance
 
+> Module status below is mirrored from the canonical [Stability Matrix](STABILITY.md)
+> (the single source of truth, enforced by `bun run check:stability`).
+
 | Module          | Status       | Description                                                                                                                                                                 |
 | --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Core**        | Stable       | Selectors, DOM manipulation, events, traversal, and typed utilities                                                                                                         |

diff --git a/STABILITY.md b/STABILITY.md
@@ -0,0 +1,104 @@
+# Stability Matrix
+
+**This file is the single source of truth for bQuery module maturity.** The
+[README status table](README.md#modules-at-a-glance), the docs site
+[Stability matrix](https://bquery.js.org/introduction#stability-matrix), and the
+machine-readable data in [`scripts/stability-matrix.mjs`](scripts/stability-matrix.mjs)
+are all validated against it by `bun run check:stability`, so the surfaces cannot
+silently drift apart.
+
+bQuery follows [Semantic Versioning](https://semver.org/):
+
+- **Stable** modules introduce **no breaking changes between minor releases**.
+- **Beta** modules may change, but breaking changes are flagged in the
+  [Release Notes](https://bquery.js.org/release-notes/); an upgrade path is always
+  documented.
+- **Experimental** modules may change between minors without prior deprecation.
+
+When a module changes status, update the table below **and**
+[`scripts/stability-matrix.mjs`](scripts/stability-matrix.mjs), append a line to
+its history, and run `bun run check:stability`.
+
+## Matrix
+
+| Module | Status | Targeting Stable | Notes |
+| --- | --- | --- | --- |
+| `core` | Stable | — | Selectors, DOM ops, events, typed utilities. |
+| `reactive` | Stable | — | Signals, computed, effects, async data, HTTP/WS/SSE. |
+| `security` | Stable | — | Sanitizer, Trusted Types, CSP helpers. |
+| `component` | Stable | — | Typed Web Components with scoped reactivity. |
+| `motion` | Stable | — | View transitions, FLIP, springs, timelines. |
+| `platform` | Stable | — | Storage, cache, cookies, announcers, runtime config. |
+| `router` | Stable | — | SPA routing, guards, `useRoute()`, `<bq-link>`, file-route convention. |
+| `store` | Stable | — | Signal-based state, persistence, migrations, plugins. |
+| `view` | Beta | 1.15.0 | Directive set + grammar frozen; transitions + optional compiler. |
+| `forms` | Beta | 1.15.0 | Batteries-included surface frozen; progressive-enhancement actions. |
+| `i18n` | Beta | 1.15.0 | Formatting/locale surface frozen; ICU MessageFormat; extraction tooling. |
+| `a11y` | Beta | 1.15.0 | Surface frozen; runtime audit maps each finding to a WCAG criterion. |
+| `dnd` | Beta | 1.15.0 | Surface frozen; keyboard model hardened; accessibility statement. |
+| `media` | Beta | 1.15.0 | Composable surface frozen; SSR-safe defaults documented and verified. |
+| `plugin` | Beta | 1.15.0 | Hook-bus / DI / lifecycle frozen; install/uninstall symmetry proven. |
+| `devtools` | Beta | 1.15.0 | Surface frozen; versioned bridge protocol + reference extension. |
+| `testing` | Beta | 1.15.0 | Testing-Library-parity surface frozen; runner integration documented. |
+| `storybook` | Beta | 1.15.0 | Helper surface frozen; `unsafeHtml` security contract pinned. |
+| `concurrency` | Experimental | 1.15.0 | CSP-safe module workers; client UI-scheduling primitives; surface frozen. |
+| `ssr` | Experimental | 1.15.0 | Directive parity, resumability, production hydration; surface frozen. |
+| `server` | Experimental | 1.15.0 | Sessions, CSRF, guards, auth; `ctx`/`app` contract frozen. |
+
+> "Targeting Stable" means the module's public surface is frozen for one minor
+> cycle ahead of graduation; see each module guide for its exit-criteria
+> checklist.
+
+## Per-module status history
+
+Each release records module status transitions and any flagged breaking changes
+here, so the road-to-stable is auditable. Format mirrors the
+[CHANGELOG](CHANGELOG.md) "Module status" sections.
+
+- **`router`**
+  - _Unreleased_ — Additive opt-in file-route convention (typed `load` / `action`,
+    `createFileRoutes`) bridging `router` / `ssr` / `server` ([#149]). No breaking
+    changes; `router` remains **Stable**.
+  - Stable since the early public releases (programmatic SPA routing).
+- **`view`** — Beta → _targeting Stable in 1.15.0_; directive set and expression
+  grammar frozen ([#136]).
+- **`forms`** — Beta → _targeting Stable in 1.15.0_; batteries-included surface
+  frozen, progressive-enhancement actions added ([#139], [#140]).
+- **`i18n`** — Beta → _targeting Stable in 1.15.0_; formatting/locale surface
+  frozen, ICU MessageFormat coverage documented ([#141]).
+- **`a11y`** — Beta → _targeting Stable in 1.15.0_; surface frozen, audit WCAG
+  scope documented ([#142]).
+- **`dnd`** — Beta → _targeting Stable in 1.15.0_; surface frozen, keyboard model
+  hardened ([#143]).
+- **`media`** — graduated into batteries-included tier (1.14.0); Beta →
+  _targeting Stable in 1.15.0_; composable surface frozen and verified ([#144]).
+- **`plugin`** — graduated into batteries-included tier (1.14.0); Beta →
+  _targeting Stable in 1.15.0_; install/uninstall symmetry proven ([#145]).
+- **`devtools`** — graduated into batteries-included tier (1.14.0); Beta →
+  _targeting Stable in 1.15.0_; versioned bridge protocol ([#146]).
+- **`testing`** — graduated into batteries-included tier (1.14.0); Beta →
+  _targeting Stable in 1.15.0_; runner integration documented ([#147]).
+- **`storybook`** — Beta → _targeting Stable in 1.15.0_; `unsafeHtml` contract
+  pinned ([#148]).
+- **`concurrency`** — Experimental → _targeting Stable in 1.15.0_; CSP-safe
+  module workers remove the mandatory `'unsafe-eval'` ([#133], [#134], [#135]).
+- **`ssr`** — Experimental → _targeting Stable in 1.15.0_; directive parity,
+  resumability, production hydration resolved; surface frozen.
+- **`server`** — Experimental → _targeting Stable in 1.15.0_; first-party
+  sessions/CSRF/guards/auth resolved; `ctx`/`app` contract frozen.
+
+[#133]: https://github.com/bQuery/bQuery/issues/133
+[#134]: https://github.com/bQuery/bQuery/issues/134
+[#135]: https://github.com/bQuery/bQuery/issues/135
+[#136]: https://github.com/bQuery/bQuery/issues/136
+[#139]: https://github.com/bQuery/bQuery/issues/139
+[#140]: https://github.com/bQuery/bQuery/issues/140
+[#141]: https://github.com/bQuery/bQuery/issues/141
+[#142]: https://github.com/bQuery/bQuery/issues/142
+[#143]: https://github.com/bQuery/bQuery/issues/143
+[#144]: https://github.com/bQuery/bQuery/issues/144
+[#145]: https://github.com/bQuery/bQuery/issues/145
+[#146]: https://github.com/bQuery/bQuery/issues/146
+[#147]: https://github.com/bQuery/bQuery/issues/147
+[#148]: https://github.com/bQuery/bQuery/issues/148
+[#149]: https://github.com/bQuery/bQuery/issues/149
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -34,6 +34,7 @@ const moduleItems = [
   { text: 'Security', link: '/guide/security' },
   { text: 'Platform', link: '/guide/platform' },
   { text: 'Router', link: '/guide/router' },
+  { text: 'File-based Routing', link: '/guide/file-routing' },
   { text: 'Store', link: '/guide/store' },
   { text: 'View', link: '/guide/view' },
   { text: 'Forms', link: '/guide/forms' },

diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md
@@ -33,6 +33,7 @@ bun run build
 bun test
 bun run check:full-bundle
 bun run check:ai-guidance
+bun run check:stability
 ```
 
 CI runs the equivalent steps automatically on PRs and on `main`.
@@ -45,6 +46,10 @@ CI runs the equivalent steps automatically on PRs and on `main`.
 
 `bun run check:ai-guidance` verifies that the AI guidance files (`AGENT.md`, `llms.txt`, `.cursorrules`, `.clinerules`, `.github/copilot-instructions.md`, `README.md`, `CONTRIBUTING.md`) stay in sync with `package.json` (version, engines) and with each other. If you touch any of these, run this script before opening a PR.
 
+### `check:stability`
+
+`bun run check:stability` verifies that every place bQuery advertises module maturity agrees with the canonical matrix in `scripts/stability-matrix.mjs`: the [`STABILITY.md`](https://github.com/bQuery/bQuery/blob/main/STABILITY.md) table, the README "Modules at a glance" table, and the docs `introduction.md` "Stability matrix". When a module changes status, update `scripts/stability-matrix.mjs` and append a line to its history in `STABILITY.md`; the check tells you which surfaces to reconcile so they cannot silently drift.
+
 ## Commit messages
 
 Repository commits follow **Conventional Commits**, with a module-aligned scope:
@@ -79,7 +84,7 @@ A maintainer runs `npm publish` (or the configured release action). The custom d
 
 ## See also
 
-- [Stability matrix](/introduction#stability-matrix)
+- [Stability matrix](/introduction#stability-matrix) — canonical source: [`STABILITY.md`](https://github.com/bQuery/bQuery/blob/main/STABILITY.md), validated by `check:stability`
 - [Bundle & Tree-shaking](/concepts/bundle-and-tree-shaking) — `check:full-bundle` details
 - [Contributing — Architecture](/contributing/architecture) — module-addition checklist
 - [Release Notes](/release-notes/)