vapor-chamber 1.3.0 → 1.7.0

package/README.md

@@ -3,12 +3,12 @@
 </p>
 
 <p align="center">
-  A lightweight command bus designed for <a href="https://github.com/vuejs/vue-vapor">Vue Vapor</a>. ~6.2KB. Vue 3.6 Vapor aligned. Optional DevTools integration.
+  A command bus built for <a href="https://github.com/vuejs/vue-vapor">Vue Vapor</a> — a ~4 KB brotli dispatch core with opt-in batteries, each 0 KB until imported. Vue 3.6 Vapor aligned. LGPL-2.1.
 </p>
 
 ## What is Vapor Chamber?
 
-Vapor Chamber is a **command bus for Vue 3.6+ Vapor mode**. It gives every user action a single handler, a composable plugin pipeline, and signal-native reactive state — replacing scattered event listeners and prop-drilling with one predictable, testable flow.
+Vapor Chamber is a **command bus for Vue 3.6+ Vapor mode**. Every user action gets a single handler, a composable plugin pipeline, and signal-native reactive state — replacing scattered event listeners and prop-drilling with one predictable, testable flow.
 
 ```ts
 import { createCommandBus, useCommand } from 'vapor-chamber';
@@ -23,12 +23,37 @@ bus.use(validator({ cartAdd: (cmd) => cmd.target.id ? null : 'Missing ID' }));
 const { dispatch, loading, lastError } = useCommand('cartAdd');
 ```
 
-- **~6.7 KB brotli (full IIFE) / ~5.7 KB brotli (ESM tree-shaken)** — zero runtime dependencies
-- **Framework-agnostic core** — the bus itself has no Vue import
-- **Vue 3.6.0-beta.12 aligned** — signals, `onScopeDispose`, `getCurrentScope`, alien-signals internals
-- **Full plugin pipeline** — logger, validator, debounce, throttle, retry, persist, sync, and more
-- **Transport layer** — HTTP bridge, WebSocket bridge, SSE bridge
-- **SSR-safe** — per-request bus isolation, no shared singletons
+**What's in the can** — a small core, and batteries you only pay for if you import them:
+
+| | |
+|---|---|
+| **Core** (the bus) | dispatch/query/emit, plugin pipeline, wildcard listeners — framework-agnostic, no Vue import; `createCommandBus` tree-shakes to ~3.6 KB brotli (measured sizes: [docs/BUNDLE-SIZES.md](docs/BUNDLE-SIZES.md)) |
+| **Vue composables** | `useCommand`, `useCommandState`, shared state, Vapor-mode (`defineVaporCommand`) and full Vapor wrappers |
+| **Plugins** (opt-in) | logger, validator, history (undo/redo), debounce, throttle, retry, persist, cross-tab sync, serialize, idempotent, auth guard |
+| **Transports** (opt-in) | HTTP bridge, WebSocket, SSE, Laravel Echo/Reverb |
+| **Extras** (opt-in, own subpath each) | SSR dehydrate/rehydrate, form bus, HTTP client, schema validation, transitions bridge, devtools, Vite HMR, testing utilities |
+
+- **Vue 3.6.0-beta.16 aligned** — signals, `onScopeDispose`, `getCurrentScope`, alien-signals internals; tracked per beta (see CHANGELOG)
+- **One runtime dependency** (`alien-signals`); `sideEffects: false` — unimported modules tree-shake to zero
+- **IIFE builds for no-bundler pages** — full ~10 KB / core & elements ~7 KB brotli (exact, always-current per-export table: [docs/BUNDLE-SIZES.md](docs/BUNDLE-SIZES.md), generated by `npm run size:doc`)
+- **SSR support** — dehydrate on the server, replay on the client (see `vapor-chamber/ssr`; the shared-bus helper is per-process — concurrent SSR servers should pass a per-request bus explicitly)
+
+## Install
+
+```bash
+npm install vapor-chamber        # npm registry (releases may lag the repo)
+
+# or install straight from the repo — the authoritative source while Vue 3.6
+# is in beta (a `prepare` script builds it on install):
+npm install github:lucianofedericopereira/vapor-chamber
+```
+
+Requires Node ≥20.19. Vue is an **optional** peer dep (≥3.5 for composables, ≥3.6.0-beta.16 for the full Vapor surface) — the core bus runs without Vue entirely.
+
+**Using Astro?** See [examples/exo-astro](examples/exo-astro) — a declarative directive set
+(`v-scope`, `v-command`, `v-bind-text`, `v-show`) over the vapor-chamber bus for coordinating
+independent Astro page sections, with `onMissing: 'buffer'` (+ `bufferTTL`) so sections can
+dispatch before their handlers hydrate.
 
 ---
 
@@ -130,7 +155,7 @@ vapor-chamber is built in layers. The **core** is framework-agnostic, has zero d
 | Plugins | `plugins-io.ts` | 88% | ✅ Stable |
 | Transport | `http.ts` | 80% | ✅ Stable |
 | Transport | `transports.ts` | 91% | ✅ Stable |
-| Vue | `chamber.ts` | 76% | ✅ Stable |
+| Vue | `chamber.ts` | ~95% stmts / ~87% branch | ✅ Stable |
 | Extras | `form.ts` | 99% | ✅ Stable |
 | Extras | `schema.ts` | 92% | ✅ Stable |
 | Vue 3.6 | `chamber-vapor.ts` | ✅ | ✅ Stable (unit-tested without Vue 3.6 runtime) |
@@ -149,6 +174,7 @@ Sub-path exports avoid pulling in optional modules:
 'vapor-chamber/observable'    → Symbol.observable interop — RxJS / xstream / callbag adapter
 'vapor-chamber/standard-schema'→ Standard Schema v1 validator plugin (Zod / Valibot / ArkType compatible)
 'vapor-chamber/alien-signals' → connector to use alien-signals as the underlying reactive primitive (non-Vue contexts)
+'vapor-chamber/reactive'      → opt-in DEEP reactivity: deepSignal + useDeepCommandState (nested-mutation tracking; the core signal() is shallow+fast by default)
 'vapor-chamber/iife'          → IIFE bundle (full)
 'vapor-chamber/iife-core'     → IIFE bundle (no Vapor custom-element, no Suspense paths)
 'vapor-chamber/iife-elements' → IIFE bundle (core + Vapor custom-element)
@@ -161,9 +187,9 @@ audience, not by feature checklist.
 
 | Variant   | Audience                                     | File                                  | Min   | Brotli | Gzip   |
 |-----------|----------------------------------------------|---------------------------------------|-------|--------|--------|
-| core      | Sprinkled JS on server-rendered pages (Blade, Rails, Django, .NET MVC, WordPress). You dispatch user actions to a backend over HTTP. | `vapor-chamber-core.iife.js`     | 23 KB | 6.1 KB | 6.8 KB |
-| elements  | Embeddable widgets (chat bubbles, checkout buttons, third-party drop-ins). You ship a `<vc-widget>` custom element. | `vapor-chamber-elements.iife.js` | 24 KB | 6.4 KB | 7.2 KB |
-| full      | SPAs that grew big enough to want everything (realtime, undo/redo, persistence, full Vapor surface). | `vapor-chamber.iife.js`              | 32 KB | 8.7 KB | 9.8 KB |
+| core      | Sprinkled JS on server-rendered pages (Blade, Rails, Django, .NET MVC, WordPress). You dispatch user actions to a backend over HTTP. | `vapor-chamber-core.iife.js`     | 24.4 KB | 7.0 KB  | 7.8 KB  |
+| elements  | Embeddable widgets (chat bubbles, checkout buttons, third-party drop-ins). You ship a `<vc-widget>` custom element. | `vapor-chamber-elements.iife.js` | 25.9 KB | 7.4 KB  | 8.3 KB  |
+| full      | SPAs that grew big enough to want everything (realtime, undo/redo, persistence, full Vapor surface). | `vapor-chamber.iife.js`              | 35.4 KB | 10.2 KB | 11.3 KB |
 
 **What's in each variant**
 
@@ -203,15 +229,28 @@ audience, not by feature checklist.
 <vc-cart sku="ABC-123"></vc-cart>
 ```
 
-(Sizes measured against v1.2.0; min = `*.iife.min.js`. Brotli @ q=11, gzip @ -9.
-Modern CDNs serve brotli to every supported browser, so brotli is the number
-that hits the wire.) The build is driven by `scripts/build.mjs` (Vite programmatic
-API) — single source, multiple outputs.
+Sizes above are **minified brotli** (q=11) / gzip (-9); brotli is what hits the wire on
+modern CDNs. The dispatch core alone (`createCommandBus`, tree-shaken) is **~3.6 KB brotli**.
+These figures — and the per-export ESM sizes — are regenerated and **CI-verified fresh** in
+**[docs/BUNDLE-SIZES.md](docs/BUNDLE-SIZES.md)** (the always-current source of truth, via
+`npm run size:doc`); `npm run size:check` fails CI on any regression past the budget. The build
+is `scripts/build.mjs` (Vite 8 / rolldown).
+
+**Size by version** (IIFE brotli — `full` / `core` / `elements`):
+
+| Version | full | core | elements | Notes |
+|---------|-----:|-----:|---------:|-------|
+| v1.2.0 | 8.7 | 6.1 | 6.4 | audience-split baseline |
+| v1.6.0 (beta.15) | 10.4 | 7.1 | 7.5 | +realtime / undo-redo / `onMissing:'buffer'` / Echo |
+| v1.7.0 (unreleased, beta.16) | **10.2** | **7.0** | **7.4** | Vite 8 / rolldown minifier — **smaller, no regression** |
+
+The v1.2 → v1.6 growth tracked added capabilities (see CHANGELOG per version); the latest move
+is a **decrease**. Verified each release against the prior baseline via `npm run size:check`.
 
 > **Variant contents are not under semver before v2.0.** While Vue 3.6 is in
 > beta, the lib reserves the right to move APIs between IIFE variants. ESM
 > consumers (the `vapor-chamber` main entry) get the full surface and are
-> unaffected. See [ROADMAP.md](./ROADMAP.md).
+> unaffected. See [ROADMAP.md](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/ROADMAP.md).
 
 ---
 
@@ -221,23 +260,24 @@ API) — single source, multiple outputs.
 npm install vapor-chamber
 ```
 
-**Requirements:** Node.js ≥20.19.0 | Vue ≥3.5.0 (composables) or ≥3.6.0-beta.11 (full Vapor) — optional peer dep | Vite ≥7.0.0 + `@vitejs/plugin-vue` ≥5.0.0 (only required for the `vapor-chamber/vite` HMR plugin and Vapor SFC support)
+**Requirements:** Node.js ≥20.19.0 | Vue ≥3.5.0 (composables) or ≥3.6.0-beta.16 (full Vapor) — optional peer dep | Vite ≥7.0.0 + `@vitejs/plugin-vue` ≥5.0.0 (only required for the `vapor-chamber/vite` HMR plugin and Vapor SFC support)
 
 > **Beta tracking:** this lib follows Vue 3.6 while it is in beta. The Vapor
-> wrappers and the `useVaporCommand` / `useCommand` split are transitional
-> surfaces that will realign once Vue 3.6 ships stable. See [ROADMAP.md](./ROADMAP.md)
+> wrappers are transitional surfaces that will realign once Vue 3.6 ships
+> stable; the command composables are now consolidated into a single
+> Vapor-safe `useCommand`. See [ROADMAP.md](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/ROADMAP.md)
 > for what is stable today, what is transitional, and the v1.3 / v2 plan.
 >
-> **Performance & tuning:** see [docs/performance.md](./docs/performance.md)
+> **Performance & tuning:** see [docs/performance.md](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/docs/performance.md)
 > for what's optimized by default, the consumer-facing tuning knobs
 > (`persist({ coalesce: true })`, `configureUid`, `configureSignal`), variant
 > selection guide, and a benchmark snapshot.
 >
-> **Laravel integration:** see [docs/integrations/laravel.md](./docs/integrations/laravel.md)
+> **Laravel integration:** see [docs/integrations/laravel.md](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/docs/integrations/laravel.md)
 > for the full backend deliverables list (route, controller, action classes,
 > CSRF flows, Sanctum, Inertia coexistence, Filament panels, Reverb
 > realtime, queued commands). Runnable PHP companions live in
-> [examples/laravel-backend/](./examples/laravel-backend/).
+> [examples/laravel-backend/](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples/laravel-backend).
 >
 > **API reference:** generate locally with `npm run docs` (TypeDoc → `docs/api/`).
 > The generated site is `.gitignore`d so it stays fresh per release. Hosting it
@@ -484,7 +524,7 @@ Every dispatched command is auto-stamped with `meta`:
 
 ```typescript
 bus.onAfter((cmd) => {
-  console.log(cmd.meta.id);             // unique UUID per dispatch
+  console.log(cmd.meta.id);             // unique id per dispatch (counter-based; UUID via configureUid)
   console.log(cmd.meta.ts);             // Date.now() timestamp
   console.log(cmd.meta.correlationId);  // trace ID for command chains
 });
@@ -881,6 +921,26 @@ bus.use(createSseBridge({
 }));
 ```
 
+### createEchoBridge
+
+Laravel Echo / Reverb realtime — subscribe public/private/presence channels and
+route each broadcast to `bus.emit()`. You pass your own Echo instance, so the
+library never imports `laravel-echo`:
+
+```typescript
+import { createEchoBridge } from 'vapor-chamber/transports';
+
+const realtime = createEchoBridge({
+  echo, // your configured laravel-echo / Reverb instance
+  channels: [
+    { name: `user.${userId}`, type: 'private',  events: ['OrderShipped'] },
+    { name: 'lobby',          type: 'presence', events: ['MessagePosted'] },
+  ],
+});
+realtime.install(bus);   // OrderShipped → bus.emit('OrderShipped', payload)
+// realtime.teardown();  // on unmount / route change
+```
+
 ## HTTP Client
 
 `postCommand` is exposed for use outside the transport plugin when you need direct HTTP control:
@@ -980,7 +1040,7 @@ const result = await bus.dispatch('userFetch', { id: 123 });
 
 ### useCommand
 
-Dispatch commands with reactive loading/error state:
+The single command composable — reactive `loading`/`lastError` signals plus `register()`, `on()`, and `emit()` with automatic cleanup. It uses no `getCurrentInstance()`, so it is Vapor-safe: the same API works in `<script setup vapor>` and VDOM components alike.
 
 ```vue
 <script setup vapor>
@@ -995,6 +1055,30 @@ const { dispatch, loading, lastError } = useCommand();
 </template>
 ```
 
+Need the full surface? `register()`, `on()`, `emit()`, and `dispose()` are part of the same composable:
+
+```vue
+<script setup vapor>
+import { useCommand } from 'vapor-chamber';
+
+const { dispatch, register, on, emit, loading, lastError, dispose } = useCommand();
+
+// Register a handler scoped to this component
+register('cartAdd', (cmd) => addToCart(cmd.target));
+
+// Listen to patterns
+on('cart*', (cmd, result) => console.log('Cart event:', cmd.action));
+
+// Dispatch with reactive loading/error tracking
+const result = dispatch('cartAdd', product, { quantity: 1 });
+
+// Emit a domain event (no handler required, no result)
+emit('cartChanged', { count: 1 });
+
+// Auto-cleanup via onScopeDispose — or call dispose() manually
+</script>
+```
+
 ### defineVaporCommand
 
 Zero-overhead dispatch for hot paths — no reactive `loading`/`lastError` signals created.
@@ -1015,29 +1099,6 @@ dispatch({ event: 'page_view', params: { page: '/shop' } });
 </script>
 ```
 
-### useVaporCommand
-
-Full-featured composable for Vapor components — reactive `loading`/`lastError` signals plus `register()` and `on()` with automatic cleanup. Unlike `defineVaporCommand` (fire-and-forget), this tracks reactive state. Unlike `useCommand` (VDOM), this uses no `getCurrentInstance()` — safe in Vapor's scope-based lifecycle:
-
-```vue
-<script setup vapor>
-import { useVaporCommand } from 'vapor-chamber';
-
-const { dispatch, register, on, loading, lastError, dispose } = useVaporCommand();
-
-// Register a handler scoped to this component
-register('cartAdd', (cmd) => addToCart(cmd.target));
-
-// Listen to patterns
-on('cart*', (cmd, result) => console.log('Cart event:', cmd.action));
-
-// Dispatch with reactive loading/error tracking
-const result = dispatch('cartAdd', product, { quantity: 1 });
-
-// Auto-cleanup via onScopeDispose — or call dispose() manually
-</script>
-```
-
 ### useCommandState
 
 State managed by commands:
@@ -1271,16 +1332,25 @@ app.mount('#app');
 
 ## Examples
 
-See the [`examples/`](./examples) folder for complete, runnable examples:
+See [`examples/`](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples) — the [examples index](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples) lists all of them. **Runnable full-project apps:**
+
+| App | What it shows |
+|-----|---------------|
+| [`vapor-sfc`](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples/vapor-sfc) | `<script setup vapor>` SFC tree — `useCommand` / `defineVaporCommand` / `useSharedCommandState` |
+| [`vapor-island-cart`](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples/vapor-island-cart) | Light-DOM Vapor custom-element islands coordinating through one bus |
+| [`exo-astro`](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples/exo-astro) | Declarative directives for Astro — dispatch *before* hydration |
+| [`laravel-app`](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples/laravel-app) | Verified Laravel 12: Blade + core IIFE + real CSRF (419/401) |
+
+**Single-file snippets** (plus `feature-*` / `pattern-*` files — see the [index](https://github.com/lucianofedericopereira/vapor-chamber/tree/main/examples)):
 
 | Example | Description |
 |---------|-------------|
-| [`shopping-cart.ts`](./examples/shopping-cart.ts) | Cart with validation, history, and undo/redo |
-| [`form-validation.ts`](./examples/form-validation.ts) | Form validation with error handling |
-| [`async-api.ts`](./examples/async-api.ts) | Async handlers with retry plugin |
-| [`realtime-search.ts`](./examples/realtime-search.ts) | Debounced search queries |
-| [`custom-plugins.ts`](./examples/custom-plugins.ts) | Analytics, auth guard, rate limiter plugins |
-| [`vue-vapor-component.vue`](./examples/vue-vapor-component.vue) | Full Vue Vapor todo app |
+| [`shopping-cart.ts`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/examples/shopping-cart.ts) | Cart with validation, history, and undo/redo |
+| [`form-validation.ts`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/examples/form-validation.ts) | Form validation with error handling |
+| [`async-api.ts`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/examples/async-api.ts) | Async handlers with retry plugin |
+| [`realtime-search.ts`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/examples/realtime-search.ts) | Debounced search queries |
+| [`custom-plugins.ts`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/examples/custom-plugins.ts) | Analytics, auth guard, rate limiter plugins |
+| [`vue-vapor-component.vue`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/examples/vue-vapor-component.vue) | Full Vue Vapor todo app |
 
 ## API Reference
 
@@ -1332,9 +1402,8 @@ See the [`examples/`](./examples) folder for complete, runnable examples:
 
 | Composable | Description |
 |------------|-------------|
-| `useCommand()` | Dispatch with reactive loading/error state (per-call signals) |
+| `useCommand()` | Vapor-safe composable: dispatch + register/on/emit + reactive loading/error state (per-call signals), auto-cleanup on scope disposal |
 | `useSharedCommandState(options?)` | Aggregate `isAnyLoading` + `errors` ring buffer, **shared** across every subscriber on the same bus. Use for toolbars, status bars, global spinners. Saves ~2 signal nodes per subscribing component. |
-| `useVaporCommand()` | Vapor-safe composable with dispatch, register, on, loading/error, auto-cleanup |
 | `defineVaporCommand(action, handler, options?)` | Zero-overhead dispatch for hot paths |
 | `useCommandState(initial, handlers)` | State managed by commands |
 | `useCommandHistory(options?)` | Reactive undo/redo |
@@ -1409,6 +1478,8 @@ See the [`examples/`](./examples) folder for complete, runnable examples:
 | `circuitBreaker` — per-action closed/open/half-open resilience | `plugins-extra` | ✅ v1.0 | ✅ covered |
 | `rateLimit` — per-action sliding window limiter | `plugins-extra` | ✅ v1.0 | ✅ covered |
 | `metrics` — lightweight telemetry (count, duration, errorRate) | `plugins-extra` | ✅ v1.0 | ✅ covered |
+| `serialize` — per-key sequential processing (async; prevents same-key races; `scope:'cross-tab'` via Web Locks) | `plugins-extra` | ✅ v1.5 | ✅ covered |
+| `idempotent` — collapse duplicate commands (double-submit/retry); stamps `Idempotency-Key` for the HTTP bridge | `plugins-extra` | ✅ v1.5 | ✅ covered |
 
 ### Utilities — optional, tree-shaken
 
@@ -1432,12 +1503,13 @@ See the [`examples/`](./examples) folder for complete, runnable examples:
 | `createWsBridge` — WebSocket plugin + reconnect + bounded queue | `transports` | ✅ v0.6.0 | ✅ covered |
 | `WsBridge.connected` — reactive signal for connection state | `transports` | ✅ v0.6.0 | ✅ covered |
 | `createSseBridge` — server-push EventSource, accepts `BaseBus` | `transports` | ✅ v0.6.0 | ✅ covered |
+| `createEchoBridge` — Laravel Echo/Reverb realtime (public/private/presence → bus) | `transports` | ✅ v1.5.0 | ✅ covered |
 
 ### Vue composables — optional, requires Vue ≥3.5
 
 | Feature | Module | Status | Tests |
 |---------|--------|--------|-------|
-| `useCommand` — reactive loading/error | `chamber` | ✅ v0.1.0 | ✅ 76% coverage |
+| `useCommand` — reactive loading/error | `chamber` | ✅ v0.1.0 | ✅ ~95% coverage |
 | `useCommandState` | `chamber` | ✅ v0.2.0 | ✅ covered |
 | `useCommandHistory` — reactive undo/redo | `chamber` | ✅ v0.2.0 | ✅ covered |
 | `useCommandGroup` — namespace isolation | `chamber` | ✅ v0.4.1 | ✅ covered |
@@ -1447,7 +1519,7 @@ See the [`examples/`](./examples) folder for complete, runnable examples:
 | `onScopeDispose` lifecycle alignment | `chamber` | ✅ v0.4.0 | ✅ covered |
 | `isVaporAvailable()` | `chamber` | ✅ v0.4.0 | ✅ covered |
 | `createVaporChamberApp` / `getVaporInteropPlugin` / `defineVaporCommand` | `chamber-vapor` | ✅ v0.4.0 | ✅ covered |
-| `useVaporCommand` — Vapor-safe reactive composable | `chamber-vapor` | ✅ v0.6.0 | ✅ covered |
+| `useCommand` — Vapor-safe reactive composable (register/on/emit/dispose) | `chamber` | ✅ v0.6.0 | ✅ covered |
 | `tryAutoCleanup` dev warning (no scope/instance) | `chamber` | ✅ v0.6.0 | ✅ covered |
 | `waitForVueDetection()` — async Vue probe | `chamber` | ✅ v0.6.0 | ✅ covered |
 
@@ -1506,12 +1578,12 @@ See the [`examples/`](./examples) folder for complete, runnable examples:
 | `createCommandPool` — object pool for hot paths | ✅ Done (v1.0) |
 | Recursion depth guard (max 10) | ✅ Done (v1.0) |
 | Architectural whitepaper | ✅ Done (v0.6.0) |
-| `chamber.ts` branch coverage | 🔄 76% → target 85% |
+| `chamber.ts` branch coverage | ✅ ~87% branch / ~95% stmts (target met) |
 | Publish to npm as `vapor-chamber@1.0.0` | ⬜ Pending |
 
 ## Documentation
 
-See [`docs/whitepaper.md`](./docs/whitepaper.md) for design philosophy, architecture, camelCase naming rationale, Vue 3.6 Vapor alignment, SSR guide, and migration strategy.
+See [`docs/whitepaper.md`](https://github.com/lucianofedericopereira/vapor-chamber/blob/main/docs/whitepaper.md) for design philosophy, architecture, camelCase naming rationale, Vue 3.6 Vapor alignment, SSR guide, and migration strategy.
 
 ## Design Goals
 

package/ROADMAP.md

@@ -4,21 +4,45 @@ This project tracks Vue 3.6 while it is in beta. That has direct consequences
 for what's stable, what's transitional, and what will change once Vue 3.6
 ships stable. This file is the source of truth for that distinction.
 
-Last reviewed against **Vue 3.6.0-beta.12** (released 2026-05-15).
+Last reviewed against **Vue 3.6.0-beta.16** (2026-06-17).
 
 ---
 
-## Current posture: beta territory
+## Posture: feature-complete; tracking Vue to stable
 
-- **Peer dependency:** `vue: ">=3.5.0 || >=3.6.0-beta.12"`. The lib supports
+**The feature set is complete as of v1.5.0 and now locked.** v1.5.0 closed the last
+planned capabilities — `serialize`, `idempotent`, `onMissing:'buffer'` deferred
+dispatch, `createEchoBridge`, and the `vapor-chamber/reactive` companion — so the
+command bus, plugins, transports, composables, schema/LLM layer, form bus, HTTP
+client, testing utilities, and the Vapor surface are considered done. From here the
+only forward motion until Vue 3.6 ships stable is:
+
+1. **Tracking each new Vue 3.6 beta/RC** — verify the pass-through wrappers still
+   hold, fold any behavioral notes into the alignment table, bump the peer dep.
+2. **The stable-landing realignment** (see "What flips at Vue 3.6 stable" below) —
+   wrapper elimination, registry collapse.
+
+Maintenance work (correctness hardening, coverage, doc currency, perf re-measurement)
+continues; new feature work does not. A genuinely new capability request is parked
+until after 3.6 stable, when the deployment patterns that would justify it are
+observable.
+
+## Beta-territory specifics
+
+- **Peer dependency:** `vue: ">=3.5.0 || >=3.6.0-beta.16"`. The lib supports
   Vue 3.5 (composables only) and Vue 3.6 betas (full Vapor surface).
 - **Vapor APIs are still moving.** `defineVaporCustomElement`, `defineVaporComponent`,
   `defineVaporAsyncComponent` are stable in shape but their underlying behavior
-  has shifted between beta.10 and beta.12 (generics inference, emits/attrs split,
-  VDOM slots interop normalization, error recovery). The lib's wrappers are
-  pass-through, so consumers inherit each beta's improvements without code
-  changes — but the wrappers themselves exist precisely because the API is
-  not yet final.
+  keeps shifting. The APIs were introduced across **3.6.0-alpha.3–5**
+  (#13059 / #14017 / #13831), not beta.10; behavior has since moved with nearly
+  every beta (generics inference, emits/attrs split,
+  VDOM slots interop normalization, error recovery, TransitionGroup move hooks,
+  lazy lifecycle update jobs, HMR reload dedup, v-show move-hook suppression,
+  shared-definition hook retention, interop-bridge immutability). The lib's
+  wrappers are pass-through, so consumers inherit each beta's improvements without
+  code changes — but the wrappers themselves exist precisely because the API is
+  not yet final. See [the whitepaper's Vue 3.6 alignment table](./docs/whitepaper.md)
+  for the per-beta detail.
 - **The lib's value during beta** is graceful degradation (`null` returns when
   Vue's API is absent or not yet present), version probing (`isVaporAvailable`),
   and a stable surface for consumers to code against while Vue itself iterates.
@@ -33,7 +57,9 @@ Vue 3.6 stable:
   emit, meta, BusError, introspection.
 - **Transports** — HTTP, WebSocket, SSE bridges. Independent of Vue.
 - **Plugins** — logger, validator, history, debounce, throttle, authGuard,
-  optimistic, retry, persist, sync, cache, circuitBreaker, rateLimit, metrics.
+  optimistic, retry, persist, sync, cache, circuitBreaker, rateLimit, metrics,
+  serialize (per-key sequential processing, async),
+  idempotent (collapse duplicate commands + stamp Idempotency-Key).
 - **Schema / LLM layer** — bus → tool-call adapters for Anthropic / OpenAI.
 - **Form bus** — reactive form state with async validation.
 - **HTTP client** — fetch wrapper with CSRF, interceptors, dedup.
@@ -48,17 +74,20 @@ Vue 3.6 stable:
 Everything below exists primarily to bridge the 3.5→3.6 gap. None will be
 removed silently — each gets a deprecation cycle with a working escape hatch.
 
-### `useVaporCommand` and `useCommand` will converge
+### `useVaporCommand` and `useCommand` have converged — **DONE**
 
-The split exists because pre-3.6, `getCurrentInstance()`-based cleanup fails
-in Vapor components. By Vue 3.6 stable, `onScopeDispose` works in every
-component context, so `useCommand` can be Vapor-safe on its own.
+The split existed because pre-3.6, `getCurrentInstance()`-based cleanup fails
+in Vapor components. `useCommand` now uses `onScopeDispose`-only cleanup and
+no `getCurrentInstance()`, so it is Vapor-safe on its own.
 
-**Plan (v1.3 or v2):** Fold `useVaporCommand` into `useCommand`. Single
-composable, `onScopeDispose`-only cleanup. `useVaporCommand` becomes a
-deprecated re-export of `useCommand` for one minor cycle, then removed.
+**Done:** `useVaporCommand` was folded into `useCommand`. There is now a single
+command composable — `register`/`on`/`emit`/`dispose` plus reactive
+`loading`/`lastError`, Vapor-safe in `<script setup vapor>` and VDOM alike.
+`useVaporCommand` was **removed entirely** — not left as a deprecated alias.
+The project tracks pre-release Vue with a tiny userbase, so the clean removal
+was preferred over a deprecation cycle.
 
-**Removes:** ~60 lines of duplicated logic, plus the "which one do I use?"
+**Removed:** ~60 lines of duplicated logic, plus the "which one do I use?"
 question from the docs.
 
 ### Thin Vapor wrappers will become opt-in via build flag
@@ -187,8 +216,79 @@ benchmark numbers, and decision tree.
 | Version | Trigger                          | Headline                                                                 |
 |---------|----------------------------------|--------------------------------------------------------------------------|
 | v1.2.x  | Vue 3.6.0-beta.11+               | Beta-aligned: docs, build pipeline, IIFE split, regression tests, V8-aligned hot path, listener bucketing, persist coalescing |
-| v1.3.0  | First Vue 3.6 RC or stable       | Build-flag wrapper elimination; `vue36` conditional export; soft-deprecations begin; Rolldown migration if stable in Vite 8; `AbortController` extensions (request/respond, dispatchBatch, child signals, WS/SSE bridge propagation); protocol-aware `createEchoBridge` for Laravel Reverb / Echo (channels / private / presence) |
-| v2.0.0  | One minor cycle after 3.6 stable | Drop `useVaporCommand` (folded into `useCommand`); registry collapse; remove wrappers' null path |
+| v1.3.0  | Vue 3.6.0-beta.12                | SSR/Hydration alignment, AbortController extensions (request/respond, dispatchBatch, child signals, WS/SSE bridge), useSharedCommandState, TestBus snapshot/time-travel |
+| v1.4.0  | Vue 3.6.0-beta.13                | TransitionGroup fixes, interop scope IDs, SSR hydration fixes, lazy lifecycle jobs, signal.ts plain-object fallback, alien-signals class adapter, alien-signals promoted to dep |
+| v1.5.0  | Vue 3.6.0-beta.14                | Beta.14 alignment (HMR reload dedup, v-show move-hook suppression, custom-element/interop fixes); `signal()` → `shallowRef` (skips deep-Proxy on object/array state); `serialize` plugin (per-key sequential, + cross-tab via Web Locks); `vapor-chamber/reactive` deep-reactivity companion; `onMissing:'buffer'` deferred dispatch (buffer-until-registered, for lazy/island hydration); `idempotent` plugin + HTTP `Idempotency-Key` forwarding (client+wire exactly-once). **Feature set locked here.** |
+| v1.6.x  | Each subsequent 3.6 beta / RC    | **Tracking only** — alignment notes folded into the version table, peer-dep bump, perf re-measure. (beta.16 broke this expectation: it carried a breaking consolidation, so it landed as the v1.7.0 minor instead of a 1.6.x patch.) |
+| v1.7.0  | Vue 3.6.0-beta.16                | **First post-lock delivery (unreleased).** Beta.16 alignment; `v-vc:command` event modifiers; **breaking: `useVaporCommand` removed → `useCommand` is the single composable** (the v2.0 merge, *delivered early* — it never depended on the stable identity call); dispatch core to 100% line+branch+func coverage + lazy buffer allocation; honest size/coverage/perf docs. Ships as a **minor** under the beta-window version policy below. |
+| v2.0.0  | One minor cycle after 3.6 stable | Stable-landing realignment: `vue36` flavor wrapper elimination + registry collapse; remove wrappers' null path; finalize the identity decision. The `useVaporCommand`→`useCommand` merge is already **done** (shipped early in **v1.7.0** — see below). See checklist below. |
+
+**Version policy during the beta window.** While Vue 3.6 is still beta, breaking
+changes ship as **minors**, not majors — the peer dep is a moving beta and there is
+effectively no userspace to protect, so a deprecation cycle would cost more than it
+saves. **2.0.0 is reserved for the post-stable identity decision** (Vapor-first vs
+bus-first; the `vue36` flavor + registry collapse), keeping the major bump meaningful.
+Corollary — **we deliver first**: any v2.0-roadmapped item that does *not* depend on
+the stable identity call ships early in a minor as soon as it's ready (the
+`useVaporCommand`→`useCommand` merge landed this way in v1.7.0).
+
+Note: the `vue36` build-flag wrapper elimination was once tentatively slated for
+v1.5.0 — it is **blocked on Vue 3.6 RC/stable** (the dead-code branch only pays
+off once consumers have a non-beta Vue in their tree), so it lands at v2.0.0, not
+during beta. `createEchoBridge` (protocol-aware Reverb/Echo realtime — public /
+private / presence channels → bus) **shipped in v1.5.0** (it's a receive-only
+transport adapter, fully decoupled from Vue, so it wasn't blocked); see
+[docs/integrations/laravel.md](./docs/integrations/laravel.md).
+
+## Vue version-support matrix
+
+Which Vue versions each released lib line supports. The peer dep is permissive
+(`>=3.5.0 || >=3.6.0-beta.16`); this table is the *tested* support statement.
+
+| vapor-chamber | Vue 3.5 (composables only) | Vue 3.6 beta | Notes |
+|---------------|----------------------------|--------------|-------|
+| v1.2.x        | ✅                          | beta.11+     | first beta-aligned line |
+| v1.3.0        | ✅                          | beta.12      | |
+| v1.4.0        | ✅                          | beta.13      | |
+| v1.5.x        | ✅                          | beta.14      | feature-locked |
+| **v1.6.x**    | ✅                          | **beta.15 → beta.16** | current; tracking-only bumps |
+| v2.0.0        | ✅ (composables)            | **3.6 stable** | `vue36` flavor adds zero-overhead path |
+
+On Vue 3.5 you get the framework-agnostic surface (bus, plugins, transports,
+composables with `onScopeDispose` cleanup). The full Vapor surface
+(`defineVapor*`, `createVaporChamberApp`, interop plugin) requires Vue 3.6 and
+returns `null` / throws with a clear message when Vapor is absent.
+
+## What flips at Vue 3.6 stable
+
+A single checklist for the stable landing (v2.0.0). Each item is detailed in
+"What is transitional" above; this is the operational summary so the bump is
+mechanical, not archaeological:
+
+- [ ] **Peer dep** — add `^3.6.0` (stable) to the supported range.
+- [ ] **`vue36` build flavor** — ship the second build with `__VAPOR_NATIVE__ = true`;
+      wrapper bodies inline to identity, the `chamber.ts` feature-detection
+      registry (`getDefineVaporComponentFn`, `_vueOnScopeDispose`, …) tree-shakes
+      to zero. Add the `vue36` conditional export.
+- [x] **`useVaporCommand` → `useCommand`** — **done** (shipped early in v1.7.0, ahead of v2.0). The
+      two composables were folded into a single Vapor-safe `useCommand`
+      (`onScopeDispose`-only cleanup, `register`/`on`/`emit`/`dispose`).
+      `useVaporCommand` was removed clean — no deprecated re-export.
+- [ ] **`createVaporChamberApp`** — soft-deprecate (`@deprecated` JSDoc), point at
+      `import { createVaporApp } from 'vue'`.
+- [ ] **Typed Vapor surface** — once Vue's Vapor types settle at stable, give the
+      `defineVapor*` wrappers first-class inference using Vue's exported types
+      (`DefineVaporComponent`, `VaporComponent`, `VaporPublicProps`) via an isolated
+      `vapor-chamber/vapor` subpath export, so the `vue` type dependency never touches
+      the Vue-less main barrel. Until then the wrappers keep the opt-in `<T = any>`
+      generic added in v1.6.0 (no Vue-type dependency).
+- [ ] **plugin-vue 6.x** — test, then bump the optional peer-dep range.
+- [ ] **Re-measure** IIFE sizes (Rolldown/Vite 8 may shift them) and update README.
+- [ ] **Variant contents** become semver-stable (the beta-era reshuffle freedom ends).
+
+None of these is a behavior change for consumers who use the documented API —
+they're internal collapses that the deprecation cycle (landing first in a v1.x
+minor) makes safe.
 
 ## Vite + plugin-vue alignment
 

package/dist/alien-signals.d.ts

@@ -46,21 +46,6 @@ export type AlienSignalFn = <T>(initial?: T) => {
     /** Read */ (): T;
     /** Write */ (next: T): T;
 };
-/**
- * Build a `CreateSignal` adapter from alien-signals' `signal` function.
- * The returned function is what `configureSignal()` expects — it produces
- * vapor-chamber-style `{ value }` objects backed by an alien-signal.
- *
- * Use this when you want manual control. For the typical case, prefer
- * {@link configureAlienSignals} which installs the adapter directly.
- *
- * @example
- * import { signal as alienSignal } from 'alien-signals';
- * import { configureSignal } from 'vapor-chamber';
- * import { alienSignalAdapter } from 'vapor-chamber/alien-signals';
- *
- * configureSignal(alienSignalAdapter(alienSignal));
- */
 export declare function alienSignalAdapter(alienSignal: AlienSignalFn): CreateSignal;
 /**
  * Install alien-signals as the underlying reactive primitive for every

package/dist/alien-signals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alien-signals.d.ts","sourceRoot":"","sources":["../src/alien-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK;IAC9C,WAAW,CAAC,IAAI,CAAC,CAAC;IAClB,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAQ3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,aAAa,GAAG,IAAI,CAEtE"}
+{"version":3,"file":"alien-signals.d.ts","sourceRoot":"","sources":["../src/alien-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK;IAC9C,WAAW,CAAC,IAAI,CAAC,CAAC;IAClB,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;CAC3B,CAAC;AAyBF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAE3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,aAAa,GAAG,IAAI,CAEtE"}