@ape-egg/vibe 2.1.22 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [2.3.0] - 2026-07-02
+
+### Changed
+
+- **SPA shell ships without `vibe-fouc`** (compiler `spa.rs`) — `vibe-fouc` absence is the compiled-mode marker (the runtime gates hyperspeed manifest loading on it), so the shell carrying it silently ran in runtime mode and never fetched its own manifest — and broke consumers keying compiled-detection off the marker (Battle Brawlers' COMPILED badge). The shell now strips the attribute from the body-attr union instead of adding it: nothing flashes — the outlet is empty and fragments hydrate off-DOM before insertion. Test: `tests/compiler/spa/` (body-attr union asserts the absence); the compiled SPA e2e now exercises the shell's manifest-driven boot.
+- **SPA shell vibe-import fallback is browser-resolvable** (compiler `spa.rs`) — when no page imports vibe directly (the import lives in a bundled app-boot module, the game-stack shape), the shell previously emitted the bare `@ape-egg/vibe` specifier, which no browser loads without an import map. The fallback is now the conventional `/node_modules/@ape-egg/vibe/index.js` (spa.js derived from it); harvested page import styles still win when present. Test: `tests/compiler/spa-bundled-vibe/`.
+- **Defaults semantics folded into `vibe()` itself; `@ape-egg/vibe/defaults` removed** (`index.js`, `defaults.js` (deleted), compiler `spa.rs`) — `vibe(state)` called once booted now seeds missing keys only (`applyDefaults`, exported from the main entry) instead of `Object.assign`-clobbering live state. "Initial state, declared again" finally means the same thing in both lifetimes, so the separate defaults entry and the compiler SPA mode's fragment import rewrite are gone — fragment scripts are carried byte-identical with the page's own import. 2.2.0 was never published (npm is at 2.1.22), so nothing external loses the entry. Pre-boot behavior is untouched: on a fresh document load MPA behavior is byte-identical. Tests: `tests/unit/defaults.test.js` retargeted to the main entry; `tests/compiler/spa/` + `tests/compiler/spa-inline-children/` now assert imports pass through untouched; the compiled-SPA state-survival e2e proves the folded semantics end-to-end through real fragments.
+
+### Added
+
+- **Watch mode hot-reloads its config** (compiler `watcher.rs`, `config.rs`) — a running `--watch` was a spawn-time config snapshot: flipping `"spa"` (or any vibe-compiler option) in package.json did nothing until you found which process owned the output lock and restarted it by hand. The watcher now watches package.json explicitly (outside the source tree and past `skip_files`, which routinely lists it for copying) and, when the loaded config actually differs from the spawn baseline (formatting-only writes are ignored via `Config: PartialEq`), restarts itself in place: lock released, then `exec` of the same binary with the same argv — CLI flag overrides re-apply with perfect parity, and the pid is preserved so a parent process supervising the child (a dev server watching for compiler exit) never notices. Full recompile under the new config follows naturally, and the standard output-clean removes the other mode's artifacts. Test: `tests/compiler/watch-config-reload/` (spawn `--watch` under `spa: true`, flip to `false`, assert the output switches shape live).
+- **Fetched-component mounts are fouc-covered until settled** (`runtime/component.js`) — finalize inserts a fetched component's content and the observer hydrates it across LATER mutation batches, with paints in between: until hydration lands, selectors keyed on hydrated attributes (a name-bound `<page @[page.name]>` driving `page[pvp]`-scoped rules) don't match and the content flashes unstyled — ~300ms of raw skeleton on every Battle Brawlers SPA navigation. The replacement wrapper now carries `vibe-fouc` from insertion until its subtree settles (`shouldCleanup(wrapper)` — the page-ready predicate — checked per afterDomMutation; a wrapper unmounted mid-hydration releases the hook). Applies to every runtime-fetched component, not just SPA outlets; nested fetched children compose (the parent stays covered until they settle too). Test: `tests/e2e/spa-router.spec.js` ("stays fouc-covered until its subtree settles" — deterministic via a held child fetch, both modes).
+- **Late `$.on('ready')` fires immediately** (`runtime/index.js`) — the ready phase happens once; a listener registered after it now runs on the spot (same try/catch as phase-time listeners) instead of silently never firing, with parity to the already-late-safe `$.ready` promise. Late registration is the SPA norm: fragment scripts execute on mount, long after the shell booted — an app-boot module imported by a fragment registers its ready work exactly there. Test: `e2e-runtime/late-ready.html` + `tests/e2e/late-ready.spec.js` (both modes: pre-boot control listener fires at the phase, post-ready listener fires immediately).
+- **Named routes — `$.page.name`** (`spa.js`) — `resolve()` and the default `onNavigate` now carry `name`, the route slug: segments joined with dashes, params flattened to their bare name (`'/' → 'home'`, `'/pve/:id' → 'pve-id'`, `'/docs/:rest*' → 'docs-rest'`, the `'*'` fallback keeps its literal `'*'`). Stable across param values, so markup hangs page-scoped attributes and active checks on it — `<page @[page.name]>`, `page.name.startsWith('pve')` — the shape MPA route parsers already derive, so page code ports to SPA untouched. Contract is now `$.page = { path, route, params, src, name }`. Tests: `tests/unit/spa.test.js` ("route names" — root, static, multi-segment, param flattening + stability, catch-all, `'*'`), name assertions in both SPA e2e suites.
+- **Keyed outlet — `key` on fetched components** (`runtime/parse.js`, `runtime/hydrate.js`, `runtime/component.js`; compiler `spa.rs`, 2.1.1 → 2.2.0) — `key="@[expr]"` on a `<component src>` declares the mount's identity: when the resolved key changes, the component remounts even though the src is unchanged. The compiler's SPA shell now emits `<component src="@[page.src]" key="@[page.path]"></component>`, so param→param navigation on the same route (`/brawlers/0 → /brawlers/1` — same fragment src) mounts fresh, exactly like the MPA reload it replaces. Mechanics: fetched components capture the bound key alongside src (every other attribute stays a raw prop); a key change force-remounts the current src through `forceRemount` — a pending fetch is already a fresh mount (a src change in the same flush deduped for free) and an unmounted wrapper's first mount stays owned by the normal pass; finalize rides `data-vibe-key` + the last resolved key across wrapper replacements the same way `data-vibe-src` travels, so the knowledge survives arbitrarily many navigations. `src` and `key` are the wrapper's own contract and are never passed to the component as props (`data-vibe-*` transport attributes likewise excluded). Tests: `tests/e2e/spa-router.spec.js` + `tests/e2e/spa-compiled.spec.js` (param→param remount runs the fragment script again, both modes + through the real generated shell), `tests/compiler/spa/` + `tests/compiler/spa-inline-children/` (shell emits the keyed outlet).
+
+## [2.2.1] - 2026-07-02
+
+### Fixed
+
+- **`nodeModulesAsIs` copied gigabytes of build artifacts through a symlinked local package** (`compiler/src/compiler/compile.rs`, compiler 2.1.0 → 2.1.1) — the as-is copy walks `node_modules` blindly, and a dev-workspace symlink (`node_modules/@ape-egg/vibe → <local vibe repo>`) dragged the package's cargo `target/` along: a 15MB copy became **4.2GB and ~4.3s per clean compile**. `copy_dir_recursive` now honors the Cache Directory Tagging spec — any directory carrying a signed `CACHEDIR.TAG` (cargo stamps `target/` with exactly this so copy/backup tools can skip it) is skipped, with the signature header verified so the check can't false-positive on an ordinary file name. Same fixture: 16MB in 9ms. Nested `node_modules` inside packages, dotdirs like `.bin`, and everything else copy as before — the skip is opt-in by the directory's own declaration, not name-based guessing. Test: `compile.rs` (`as_is_copy_skips_cachedir_tagged_directories`). Affects every project that symlinks the local vibe package with `nodeModulesAsIs: true` (Battle Brawlers' compiled builds included).
+
+## [2.2.0] - 2026-07-02
+
+### Added
+
+- **`@ape-egg/vibe/spa` — standalone SPA router** (`spa.js` (new), exported from `package.json`) — the tier between a handrolled router and compiler SPA mode, shaped exactly like `hot-module-refresh.js`: a flat module importing nothing from the runtime, depending only on the public `window.$` surface, usable without Vibe entirely via one seam. One contract: `$.page = { path, route, params, src }`; a reactive `<component src="@[page.src]">` turns that into the route outlet. `resolve(location, routes)` is the pure core (accepts anything with a `.pathname` or a bare string; `:param` captures one segment, trailing `:name*` zero-or-more, `'*'` is a position-independent declared fallback applied only after every real route missed; tables are pre-sorted most-specific-first, first match wins; trailing slashes resolve). `setupSpa({ routes, onNavigate? })` wires one document-level click listener (claims same-origin, unmodified, untargeted clicks whose pathname matches a REAL route — `'*'` never claims, same-page hash anchors keep the native jump, everything else navigates natively, which is what makes mixed MPA/SPA output work), pushState + one fresh-object `$.page` assignment + `document.title` swap when the route carries one + scroll-to-top; `popstate` re-resolves WITH the `'*'` fallback (symmetric with deep-link entry) and doesn't scroll — the browser restores. Returns `{ navigate, dispose }`: `navigate(path)` claims like a click and falls back to a native load for unrouted paths; `dispose()` releases the listeners. The default `onNavigate` reads `window.$` at call time; passing a custom one makes the module a pure router. Tests: `tests/unit/spa.test.js` (resolve: params, catch-alls at every depth, specificity, `'*'`, no-match, location-likes), `e2e-runtime/spa-router.html` + `tests/e2e/spa-router.spec.js` (both modes: claiming without document loads, params → bindings, title swaps, global-state survival vs fresh component mounts, unmount teardown, popstate both directions, native fallthrough, hash anchors, programmatic navigate, dispose).
+- **`@ape-egg/vibe/defaults` — the root entry with defaults semantics for booted state** (`defaults.js` (new), exported from `package.json`) — `vibe()` state is app-lifetime under SPA: already booted, only keys that do not yet exist on `$` are set (`applyDefaults`, shallow and key-level — exported pure for reuse), so a re-mounted page fragment's `vibe({ ...globalState, notifications: [] })` seeds on first mount and never clobbers live state after; pre-boot it delegates to `vibe()` unchanged, so on a fresh document load defaults ≡ assign and MPA behavior is byte-identical. The documented rule this encodes: `vibe()` state = app-lifetime, `component()` state = mount-lifetime — per-visit-reset state belongs in a component (the Timer pattern). Tests: `tests/unit/defaults.test.js` (missing keys set; existing — including falsy and `undefined`-valued — never overwritten; shallow; returns target), exercised end-to-end by the compiler SPA e2e's state-survival spec.
+- **Compiler SPA mode — `"spa": true` / `--spa`** (`compiler/src/compiler/spa.rs` (new), `compile.rs`, `watcher.rs`, `config.rs`, `main.rs`, compiler 2.0.3 → 2.1.0) — compiles the SAME MPA `pages/` tree into: **page fragments** at `output/components/vibe-spa/<pages-relative-path>` (body content, head `<style>` tags prepended, page `<script type="module">` carried with ONE rewrite — the vibe import specifier redirected to the defaults entry; body module scripts get the same redirect; `componentsAsIs` composes: `true` keeps child `<component src>` tags runtime-fetched and deduped through the component cache, `false` — the default — inlines children INTO each fragment so every route is one self-contained fetch, with each inlined child carried in the compiled-document form: `ComponentTagger` runs per fragment, so wrappers get deterministic `data-vibe-component-id`s, `this.` bindings and `$.this.` handlers are rewritten to those ids, and child scripts stay `type="vibe-module"`); a **generated route table** (`$param` → `:param`, terminal `$$name` → `:name*`, terminal `index` serves its directory; titles harvested from each page's `<title>`; ordered non-catch-alls-deepest-first-statics-before-params, then catch-alls — the exact-beats-param and everything-beats-catch-all rules a full table needs on top of scanRoutes' deepest-first); and a **composed shell** at `output/index.html` — plain tier-2 runtime-Vibe code (deduped head union where `<meta>` keeps only the set common to every page — page-specific meta dropped with a verbose note — links/scripts stack first-seen; the `/` route's title; body attribute union + `vibe-fouc`, divergences noted in verbose; a generated boot script reusing the pages' own vibe import style; the `<component src="@[page.src]"></component>` outlet). SPA output has **no** `pages/` directory, **no** per-page manifests, and **no** per-page stamping — fragments are runtime-parsed on mount (per-route lazy loading falls out of the bound src for free). The shell still gets a manifest but is deliberately **unstamped**: it is served at every route path while manifests resolve by URL, and stamping would have stripped the raw outlet binding — deep links would have hydrated a dead outlet (stamp-skip is keyed in `generate_file_manifest`). The fragments mirror prunes orphans (deleted pages leave no stale fragment), `components/vibe-spa` in source is reserved (hard error), a source-root `index.html` being shadowed by the shell warns, and an unmount-hygiene warning names any page script that starts side effects (`setInterval`/`setTimeout`/`addEventListener`/`new WebSocket`) without referencing `$.on('unmount'`. Watch mode: any pages-tree change (edit/add/delete, or a component edit whose dependents are pages) re-runs the whole SPA pass — fragments, shell, route table, orphan prune, shell manifest — in ~10ms, with component-cache invalidation shared with the per-page path. Config parsing tolerates the future per-page object form (`"spa": {...}` reads as enabled instead of silently resetting the whole section). Deferred by design until the compiled branch-script double-run is fixed: the inline fragment mode (`componentsAsIs: false` semantics — fragments inlined into the shell behind route conditionals). Tests: `spa.rs` + `config.rs` + `compile.rs` Rust units (route grammar, ordering, import rewrite forms, hygiene, tolerant config, watch-cycle sync incl. orphan prune), `tests/compiler/spa/` (14 bun tests over a mini pages tree: shell composition, head dedup + meta drop, body-attr union, fragment content and rewrites, no pages dir / no page manifests, shell manifest carries the binding, warnings), `tests/e2e-spa-app/` + `tests/e2e/spa-compiled.spec.js` (a real compiled app driven in the browser: root entry, no-match entry leaves the outlet empty with no garbage fetch, claimed navigation, **defaults-merge state survival across navigation**, unmount teardown, params, popstate, scoped catch-all claiming, native fallthrough to a plain MPA document in the same output, shared child components).
+
+- **Fetched mounts execute inlined `vibe-module` scripts** (`runtime/component.js`) — a freshly fetched component's subtree is the fourth delivery mode after boot, conditional branches, and iteration rows: `processSingle`'s finalize now runs `executeCompiledComponentScriptsIn` on the mounted wrapper, so build-inlined children inside a fetched SPA fragment register their `component({...})` state under their build-tagged ids and the rewritten `_cN` bindings hydrate. A no-op everywhere else — runtime component sources and the compiler's raw components mirror never contain `vibe-module` scripts. Locked in by `tests/compiler/spa-inline-children/` (fragment carries tagged wrapper + vibe-module script + `_cN`-rewritten bindings/handlers, props and slot stamped, no child fetch) and verified in-browser: child state is live and reactive inside a fetched fragment, resets per visit (mount-lifetime), zero child network fetches.
+
+### Fixed
+
+- **An unresolved reactive component src fetched a garbage URL instead of mounting nothing** (`runtime/hydrate.js`, `runtime/component.js`) — with `<component src="@[page.src]">` and `page.src` unset (a no-match deep link: the SPA contract says the outlet stays empty, no built-in 404), hydration stringified the binding to `"undefined"` and the component pass happily fetched it — and where hydration left the raw attribute, the initial component scan fetched the literal `@[page.src]` as a URL. Root fix at both layers: hydration now resolves nullish binding values to empty and, when nothing resolves, moves the authored binding onto `data-vibe-src` — the established transport `parse.js` already reads — and drops the fetchable `src`, so the component scan and the fouc/cleanup gate both treat the outlet as settled rather than pending; `remountComponent`'s pre-fetch early-return (which trusts a pending boot pass to pick the value up) now applies only when the element actually had a `src` attribute for that pass to see — a declaration-form wrapper was invisible to it, and the observer doesn't watch attributes, so hydration owns its first fetch too. Locked in by the compiled SPA e2e: entry at an unrouted URL mounts nothing and the request log contains no `undefined`/`@[` fetches; late resolution (navigating from a no-match entry to a real route) mounts normally.
+- **A relative `--cwd` let watch mode write INTO the source tree** (`compiler/src/config.rs`, compiler 2.1.0) — every derived path (source, output, pages) joins from `working_dir`, and filesystem-watch events always carry absolute paths, so a relative `--cwd` made `strip_prefix` fail throughout the watcher; in the incremental manifest pass the un-stripped absolute path then escaped `output_dir.join(...)` entirely (an absolute join replaces the base) and the pass **stamped a source page in place and wrote a manifest beside it**. `Config::load` now canonicalizes `working_dir` up front — one root fix that makes every downstream base absolute. (The repo's own `bun dev` always passed an absolute `$OLDPWD`, which is why this never bit before.)
+
 ## [2.1.22] - 2026-07-02
 
 ### Added

package/README.md

@@ -247,6 +247,59 @@ $.on('afterDomMutation', () => {});  // after every MutationObserver batch
 
 `$.ready` is also exposed as a Promise (`await $.ready`), useful for code that captured `window.$` before boot.
 
+```javascript
+$.on('unmount', () => {});           // scope-resolved teardown: component scripts → that component
+                                     // unmounts; page level → pagehide
+```
+
+### SPA Router (`@ape-egg/vibe/spa`)
+
+A standalone client-side router built on one contract: `$.page = { path, route, params, src, name }`. Point a reactive component src at it and the outlet is your route view:
+
+```html
+<script type="module">
+  import vibe from '@ape-egg/vibe';
+  import { setupSpa, resolve } from '@ape-egg/vibe/spa';
+
+  const routes = [
+    { route: '/brawlers/:index', src: '/components/brawler.html', title: 'Brawler' },
+    { route: '/docs/:rest*',     src: '/components/docs.html' },
+    { route: '/',                src: '/components/home.html', title: 'Home' },
+    { route: '*',                src: '/components/lost.html' },
+  ];
+
+  window.$ = vibe({ page: resolve(location, routes) ?? {} });
+  setupSpa({ routes });
+</script>
+
+<component src="@[page.src]" key="@[page.path]"></component>
+```
+
+**Route grammar** (shared with the compiler's route table): literal segments, `:param` captures one segment, a trailing `:name*` captures zero or more (`/docs` matches with `rest: ''`), and `'*'` is the declared no-match fallback. Tables are pre-sorted most-specific-first; `resolve` returns the first match. `resolve(location, routes)` is pure — it accepts anything with a `.pathname` (or a bare path string) and returns `{ path, route, params, src, name, title? }` or `null`.
+
+**Route names**: `name` is the route slug — segments joined with dashes, params flattened to their bare name: `'/' → 'home'`, `'/pve/:id' → 'pve-id'`, `'/docs/:rest*' → 'docs-rest'`, the `'*'` fallback keeps its literal `'*'`. Stable across param values, so markup hangs page-scoped attributes and active checks on it: `<page @[page.name]>`, `page.name.startsWith('pve')`.
+
+**Keyed outlet**: `key` on a fetched `<component>` declares its identity — when the resolved key changes, the component remounts even if `src` is unchanged. With `key="@[page.path]"`, param→param navigation on the same route (`/brawlers/0 → /brawlers/1` — same fragment src) mounts fresh, exactly like an MPA reload on the new URL. `src` and `key` are the wrapper's own contract and are never passed to the component as props.
+
+**Link claiming**: one document-level click listener claims same-origin, unmodified, untargeted clicks whose pathname matches a **real** route — pushState + a fresh `$.page` assignment + `document.title` swap when the route carries one, scroll to top. Everything else navigates natively: other origins, modified clicks, `target`/`download` links, same-page hash anchors, and unrouted paths — which is what makes mixed MPA/SPA output work. `'*'` never claims a click; it only resolves deep-link entries and popstate. `popstate` re-resolves (including `'*'`) without scrolling — the browser restores position.
+
+**No match, no `'*'`**: `$.page.src` stays unset and the outlet mounts nothing. There is no built-in 404.
+
+`setupSpa({ routes, onNavigate? })` returns `{ navigate, dispose }`. `navigate(path)` claims like a link click (unrouted paths get a native load); `dispose()` removes the listeners. Pass a custom `onNavigate(resolved)` and the module is a pure router — parse/claim/history only, no Vibe in sight.
+
+### App-Lifetime State Defaults (built into `vibe()`)
+
+`vibe()` called once the app is booted applies **defaults semantics**: only keys that do not yet exist on `$` are set.
+
+```javascript
+import vibe from '@ape-egg/vibe';
+vibe({ ...globalState, notifications: [] }); // first mount seeds, re-mounts never clobber
+```
+
+Pre-boot, state accumulates and boot is queued as always — on a fresh document load nothing changes, MPA behavior is byte-identical. Once booted, "initial state, declared again" seeds missing keys only: under SPA a re-mounted page fragment's `vibe({...})` call re-runs on every visit, and live state (notifications, session, timers) is never reset to initial values. No separate entry, no compiler rewrite — the same import does the right thing in both lifetimes. The pure `applyDefaults(target, state)` is exported for reuse.
+
+**The rule**: `vibe()` state is app-lifetime; `component()` state is mount-lifetime (resets per visit). Per-page-reset state belongs in a component — that's the Timer pattern.
+
 ### Subtree Reconciliation (advanced)
 
 `$.reconcile(el, html)` and `$.renderComponent(rawHtml, props, slot, opts)` are public-but-advanced APIs used by the vite plugin's HMR path. Their shape may evolve; treat them as plumbing rather than application code for now.
@@ -342,6 +395,7 @@ bunx vibe compile --node-modules-as-is  # Copy node_modules as-is
 bunx vibe compile --components-as-is    # Skip component inlining
 bunx vibe compile --runtime-as-is       # Skip manifest generation
 bunx vibe compile --iterations-as-is    # Skip iteration optimization
+bunx vibe compile --spa                 # Compile the pages tree to SPA output
 ```
 
 Or via npm scripts:
@@ -377,7 +431,8 @@ Add to your `package.json`:
     "nodeModulesAsIs": false,
     "componentsAsIs": false,
     "runtimeAsIs": false,
-    "iterationsAsIs": false
+    "iterationsAsIs": false,
+    "spa": false
   }
 }
 ```
@@ -389,6 +444,7 @@ Add to your `package.json`:
 - `componentsAsIs: false` — Inline components (default) or keep separate for runtime
 - `iterationsAsIs: false` — Optimize iterations (default) or use runtime rendering
 - `runtimeAsIs: false` — Generate manifest (default) or skip for runtime-only
+- `spa: false` — Compile the pages tree to SPA output: fragments + route table + shell (see SPA Mode)
 
 **Defaults** (when no config):
 
@@ -445,6 +501,47 @@ Features:
 - **Debounced** — 300ms debounce prevents excessive compilation during rapid changes
 - **Delta output** — First compile shows full output, subsequent compiles show only changes
 
+### SPA Mode
+
+`"spa": true` (or `--spa`) compiles the same MPA `pages/` tree into a single-page app — authors change **nothing** about how pages are written:
+
+```json
+{ "vibe-compiler": { "spa": true } }
+```
+
+The pages tree becomes three things:
+
+1. **Page fragments** at `/components/vibe-spa/<pages-relative-path>` — each page's body content, with its head `<style>` tags prepended and its `<script type="module">` carried along byte-identical. No rewrites: `vibe()` itself applies defaults semantics once booted (see App-Lifetime State Defaults above), so page state gets app-lifetime behavior with the page's own import.
+2. **A generated route table** — `pages/brawlers/$index.html` → `{ route: '/brawlers/:index', src: '/components/vibe-spa/brawlers/$index.html', title: <harvested from the page's <title>> }`. `$param` → `:param`, terminal `$$name` → `:name*`, terminal `index` serves its directory path. Sorted most-specific-first.
+3. **A composed shell** at the output root `/index.html` — plain runtime-Vibe code: the deduped union of every page's head resources (`<meta>` keeps only the set common to all pages; page-specific meta is dropped with a verbose note), the `/` route's title, the union of page body attributes minus `vibe-fouc`, one generated boot script (`resolve` seeds `$.page`, `setupSpa` wires navigation — imports reuse the pages' own import style), and the keyed route outlet: `<component src="@[page.src]" key="@[page.path]"></component>` (a path change remounts the fragment even when the route — and so the src — is unchanged: param→param navigation mounts fresh, like the MPA reload it replaces).
+
+**What SPA mode skips**: per-page stamped HTML, per-page manifests, and the `pages/` output directory. Fragments are runtime-parsed on mount (per-route lazy loading falls out of the reactive src for free); the shell itself gets a manifest but is deliberately left unstamped — it is served at every route path, so its first paint is location-dependent by nature. The shell ships **without** `vibe-fouc`: its absence is the compiled-mode marker (it gates hyperspeed manifest loading), and there is nothing to flash — the outlet is empty and fragments hydrate off-DOM before insertion.
+
+**Deployment**: one rewrite — every route serves `/index.html`; `/components/**`, `/vibe-hyperspeed/**`, and assets serve as files. The vercel.json shape:
+
+```json
+{
+  "rewrites": [
+    { "source": "/((?!components/|vibe-hyperspeed/|nodemodules/|.*\\..*).*)", "destination": "/index.html" }
+  ]
+}
+```
+
+Dev-server equivalents: any "history API fallback" option (`http-server` can't rewrite; `vite preview`, `serve -s`, and Caddy `try_files` all can).
+
+**Watch mode**: `--spa --watch` re-runs the SPA pass on any pages-tree change — edited pages re-transform, added/removed pages resync the route table and prune orphan fragments, title/head edits recompose the shell, and the shell's manifest refreshes.
+
+**Current scope**: `spa: true` converts the entire pages tree (per-page selection is planned as a config-object form — parsing already tolerates it). Fragments ship as separate fetched files either way; `componentsAsIs` decides their children: `false` (the default) inlines child components into each fragment, making every route one self-contained fetch, while `true` keeps children as runtime `<component src>` fetches deduped across routes by the component cache. Compiling every fragment into the shell itself behind route conditionals (single document, zero per-route fetches) is specified but lands only once compiled branch-scripts stop double-running. Pages that wrap themselves in a Layout component remount it per navigation — exactly like an MPA reload; persistent chrome is out of scope for now. `components/vibe-spa/` in your source is reserved.
+
+### MPA → SPA Compliance Contract
+
+SPA mode assumes; this contract defines. Pages that follow it compile to MPA today and SPA tomorrow with no edits:
+
+1. **Side effects register teardown.** Anything a page script starts — `setInterval`, `addEventListener`, sockets — must be released in `$.on('unmount', …)`. Under MPA that callback fires on `pagehide`; under SPA it fires when the page fragment unmounts on navigation. The compiler emits a warning for page scripts that start side effects and never reference `$.on('unmount'`.
+2. **`vibe()` state is app-lifetime; `component()` state is mount-lifetime.** Under SPA, a page's `vibe({...})` seeds missing keys only (defaults semantics) — it never resets live state. State that must reset on every visit belongs in a `component()`.
+3. **Head resources are shell-safe.** Stylesheets and scripts linked from a page's `<head>` end up in the shared shell head (deduped union) — they must be safe to load once for the whole app. Page-specific styling goes in `<style>` tags (which travel with the fragment) or components, not head links. Page-specific `<meta>` is dropped.
+4. **No full-document assumptions.** Pages don't rely on `window.onload`-era patterns or being the entire document — a page's body becomes a fragment inside a live shell. Use absolute URLs for assets and component srcs (the fragment is served from a different path than the page was authored at).
+
 ### Component System
 
 Components are automatically inlined during compilation with full support for props and slots:

package/compiler/src/Cargo.lock

@@ -1599,7 +1599,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
 [[package]]
 name = "vibe-compiler"
-version = "2.0.3"
+version = "2.2.0"
 dependencies = [
  "clap",
  "colored",

package/compiler/src/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vibe-compiler"
-version = "2.0.3"
+version = "2.2.0"
 edition = "2021"
 description = "Vibe framework compiler - compiles Vibe source files into optimized output"
 authors = ["Kim Korte"]