@ape-egg/vibe 2.1.22 → 3.0.0

package/README.md

@@ -1,6 +1,14 @@
 # Vibe
 
-**Version 2.0.2 (Beta)** — A runtime-first reactive framework with optional compilation.
+**Version 3.0.0** — Runtime-first reactivity for plain HTML. Drop a script tag into any page and get reactive bindings, control flow, and URL-loaded components — no build step required. Compile later if you want; the compiler is a separate, optional package (`@ape-egg/vibe-compiler`).
+
+## Security model & CSP
+
+Vibe escapes by default: `@[expr]` renders as text, never markup. The one deliberate exception is `@[$.unsafe(trustedHtml)]`, which sets `innerHTML` and is for trusted input only.
+
+What you must know before adopting: **Vibe's engine evaluates binding expressions with `new Function` and uses inline `on*` attributes as its event model.** A site running Vibe therefore needs a Content-Security-Policy that allows `'unsafe-eval'` and inline event handlers — i.e. it cannot deploy a strict CSP. Vibe itself is not an XSS vector, but strict CSP is a browser-level safety net against *other* injection bugs anywhere on a page, and Vibe requires that net loosened.
+
+If you ship to an environment that mandates strict CSP (banks, healthcare, government, security-reviewed enterprise), Vibe is currently the wrong tool. For everything else — personal sites, games, dashboards, internal tools, most product work — this is the same posture as running Vue's in-browser template compiler or Alpine.js, and it is a documented trade-off, not an accident.
 
 No virtual DOM. No build step required. Just modern JavaScript. When you need production optimizations, add the optional Rust-based compiler.
 
@@ -212,7 +220,7 @@ Multi-segment paths (`@[this.user.profile.name]`), conditionals (`<!-- if this.e
 How it works:
 
 1. `component({...})` claims the nearest unprocessed `<component>` (or `<div class="component">`) wrapper, registers state at `$[id]`, and tags the wrapper with `data-vibe-component-id`
-2. Internally it calls `ensureBoot()` (from `@ape-egg/vibe/boot`), which initializes `window.$`, parses the DOM, hydrates bindings, and starts the MutationObserver — exactly once, even if multiple `<component>` blocks call `component()`
+2. Internally it triggers the boot pipeline, which initializes `window.$`, parses the DOM, hydrates bindings, and starts the MutationObserver — exactly once, even if multiple `<component>` blocks call `component()`
 3. From there, `@[this.X]`, `onclick="this.fn()"`, and `<!-- if this.X -->` work as documented
 
 Multiple drop-in blocks on the same page each get their own state bucket. They can read each other's state via global `$['_c0'].count` if they need to coordinate, but in most drop-in cases they're independent.
@@ -247,6 +255,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.
@@ -297,9 +358,11 @@ No need for immutable update patterns or spread operators. Just mutate and Vibe
 1. **Proxy-based state** — `window.$` intercepts property changes
 2. **Deep reactivity** — Nested mutations trigger updates automatically (`$.obj.nested.prop = x`)
 3. **DOM parsing** — Finds all `@[...]` bindings on load
-4. **Surgical updates** — Only affected elements re-render
+4. **Auto-tracked subscriptions** — Every binding, conditional, and iteration records which state keys its expression read during evaluation; a write dispatches exactly its subscribers — O(what changed), no tree walk, no virtual DOM
 5. **MutationObserver** — Tracks dynamically added elements
 
+One contract follows from #4: **an expression that should react must read reactive state.** `@[items.map(format)]` re-renders when `$.items` changes because `items` was read from `$` — but if `format` is a window global that you later *reassign*, nothing re-renders, because assigning a global is not a state write. Values that change over time belong in `$`. (Helpers defined by component scripts are safe: mounts re-settle their directives once their scripts have run.)
+
 ---
 
 ## Vibe Compiler
@@ -342,6 +405,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 +441,8 @@ Add to your `package.json`:
     "nodeModulesAsIs": false,
     "componentsAsIs": false,
     "runtimeAsIs": false,
-    "iterationsAsIs": false
+    "iterationsAsIs": false,
+    "spa": false
   }
 }
 ```
@@ -389,6 +454,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 +511,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:
@@ -632,7 +739,7 @@ ISC
 - `runtime/affected.js:~122` — `shouldAffect = noMatch || ...` fallback for unmatched expressions
 - `runtime/affected.js:~248` — same fallback for name bindings
 
-Every time `matchesKey` can't prove an expression is unrelated to a state change, that binding re-hydrates. A proper AST-based dependency extraction at parse time would eliminate the fallback entirely: each binding stores its exact dependency set, and runtime just checks if any dep key changed.
+As of 3.0.0 this is solved — not by static extraction (which lies for helper calls) but by the subscription engine: every binding records the state keys it actually reads during evaluation, live at the proxy's get trap, so a write notifies exactly its subscribers. Update cost is O(change), and it costs zero authoring syntax.
 
 ### HTML lowercases attribute names — breaks name binding matching
 

package/boot.js

@@ -25,8 +25,8 @@ export const boot = () => {
   booted = true;
 
   // Merge all state: global + components
-  const globalState = window.__vibeGlobalState || {};
-  const componentStates = window.__vibeComponents || {};
+  const globalState = window.__vibe?.state || {};
+  const componentStates = window.__vibe?.components || {};
 
   const mergedState = {
     ...globalState,
@@ -34,8 +34,8 @@ export const boot = () => {
   };
 
   // Get config and targetSelector (first caller wins)
-  const config = window.__vibeConfig || {};
-  const targetSelector = window.__vibeTargetSelector || '';
+  const config = window.__vibe?.config || {};
+  const targetSelector = config.target || '';
 
   // Boot with merged state
   window.$ = main(mergedState, config, targetSelector);

package/component.js

@@ -3,7 +3,7 @@
 //   <component>
 //     <script type="module">
 //       import component from 'vibe/component.js';
-//       component({ count: 0 }, { debug: false }, 'body');
+//       component({ count: 0 }, { debug: false, target: 'body' });
 //     </script>
 //     <div>@[this.count]</div>
 //   </component>
@@ -14,28 +14,31 @@
 import { generateComponentId } from './runtime/component.js';
 import { ensureBoot } from './boot.js';
 
-const component = (state = {}, config, targetSelector) => {
+const component = (state = {}, config) => {
   // Initialize component registry
-  if (!window.__vibeComponents) {
-    window.__vibeComponents = {};
-  }
+  const ns = (window.__vibe ??= {});
+  if (!ns.components) ns.components = {};
 
-  // Find the first unprocessed INLINE component wrapper
-  // Skip <component src=""> (fetched components) - they don't need state tagging
-  // Scripts execute in DOM order, so we claim wrappers in DOM order too
-  // Supports: <component> or <div class="component">
+  // Pair this call with its wrapper. Module scripts execute in document
+  // order, so the K-th component() call belongs to the K-th wrapper whose own
+  // direct <script type="module"> calls component( — the runtime mirror of
+  // the build tagger's registers_state predicate. Wrappers without such a
+  // script (no local state, or a compiler-neutered vibe-module script that
+  // registers through boot) can never claim a call, so they're excluded —
+  // otherwise a stateless wrapper earlier in the document absorbs a later
+  // section's claim and every pairing after it is cross-wired. In compiled
+  // pages the claimed wrapper is already build-tagged: register under its id.
+  // Supports: <component> or <div class="component">; <component src> mounts
+  // register through the fetch pipeline instead.
   const allWrappers = Array.from(document.querySelectorAll('component:not([src]), div.component:not([src])'));
-
-  // Try to find unprocessed component (runtime mode)
-  let wrapper = allWrappers.find(el => !el.hasAttribute('data-vibe-component-id'));
-
-  // If not found, try to find pre-compiled component that hasn't registered state yet (compiled mode)
-  if (!wrapper) {
-    wrapper = allWrappers.find(el => {
-      const existingId = el.getAttribute('data-vibe-component-id');
-      return existingId && !window.__vibeComponents[existingId];
-    });
-  }
+  const wrapper = allWrappers.find((el) => {
+    const ownsCall = Array.from(el.children).some(
+      (child) => child.matches?.('script[type="module"]') && /component\s*\(/.test(child.textContent),
+    );
+    if (!ownsCall) return false;
+    const existingId = el.getAttribute('data-vibe-component-id');
+    return !existingId || !ns.components[existingId];
+  });
 
   if (!wrapper) {
     console.warn('[vibe] component() must be called inside <component> or <div class="component">');
@@ -50,16 +53,11 @@ const component = (state = {}, config, targetSelector) => {
   }
 
   // Register component state in shared registry
-  window.__vibeComponents[componentId] = state;
-
-  // Store config (first caller wins)
-  if (config && !window.__vibeConfig) {
-    window.__vibeConfig = config;
-  }
+  ns.components[componentId] = state;
 
-  // Store targetSelector (first caller wins)
-  if (targetSelector && !window.__vibeTargetSelector) {
-    window.__vibeTargetSelector = targetSelector;
+  // Store config (first caller wins); config.target scopes the boot.
+  if (config && !ns.config) {
+    ns.config = config;
   }
 
   // Ensure boot happens

package/hot-module-refresh.js

@@ -6,7 +6,7 @@
 //
 // SOFT DEPENDENCY: nothing in Vibe's runtime imports this, it imports nothing
 // from Vibe, and deleting it leaves a working framework. It depends solely on
-// the runtime global `window.$` (reconcile / renderComponent /
+// the runtime global `window.$` (reconcile / _renderComponent /
 // clearComponentCache), so it ships as a flat module a plain static server can
 // serve as-is — no bundler, no Vite.
 //
@@ -267,7 +267,7 @@ export const setupHotModuleRefresh = ({ debug = false, subscribe }) => {
   // Component file changed. Strategy:
   //   1. Fetch the raw template once per update; hash its <script type="module">
   //      contents. Script hash unchanged + not inside an iteration → surgical
-  //      path: $.renderComponent produces the processed HTML (props + slot
+  //      path: $._renderComponent produces the processed HTML (props + slot
   //      substituted, componentIds reused) and $.reconcile diffs it against
   //      the live wrapper's children. DOM identity, focus, and component
   //      state are preserved.
@@ -295,7 +295,7 @@ export const setupHotModuleRefresh = ({ debug = false, subscribe }) => {
       const rawUrl = path + (path.includes('?') ? '&' : '?') + '_t=' + Date.now();
       const rawHtml = await fetch(rawUrl, { cache: 'no-store' }).then((r) => r.text());
       const scriptHash = hashScripts(rawHtml);
-      const canSurgical = typeof window.$?.renderComponent === 'function'
+      const canSurgical = typeof window.$?._renderComponent === 'function'
         && typeof window.$?.reconcile === 'function';
 
       let surgical = 0;
@@ -314,7 +314,7 @@ export const setupHotModuleRefresh = ({ debug = false, subscribe }) => {
               ? el._vibePluginSlot
               : (el._vibeSlotContent || '');
             const props = el._vibeProps || {};
-            const processedHtml = window.$.renderComponent(rawHtml, props, slot, { componentIds });
+            const processedHtml = window.$._renderComponent(rawHtml, props, slot, { componentIds });
             const summary = await window.$.reconcile(el, processedHtml);
             el._vibeScriptHash = scriptHash;
             el._vibeRawSource = rawHtml;

package/index.js

@@ -31,10 +31,24 @@ const createVibeInstance = () => ({
   }
 });
 
-const vibe = (state = {}, config, targetSelector) => {
+// Shallow, key-level defaults: set only keys `target` does not have yet.
+// This is what "initial state, declared again" means once the app is live —
+// a re-mounted SPA page fragment's vibe({ ... }) seeds on first mount and
+// never clobbers live state after (vibe() state is app-lifetime; per-visit
+// state belongs in a component()).
+export const applyDefaults = (target, state) => {
+  for (const key in state) {
+    if (!(key in target)) target[key] = state[key];
+  }
+  return target;
+};
+
+const vibe = (state = {}, config) => {
   if (isBooted()) {
-    // Already booted - merge state into live proxy
-    Object.assign(window.$, state);
+    // Already booted: initial state declared late seeds missing keys only —
+    // on a fresh document load this branch never runs, so MPA behavior is
+    // byte-identical.
+    applyDefaults(window.$, state);
     return window.$;
   }
 
@@ -43,24 +57,19 @@ const vibe = (state = {}, config, targetSelector) => {
     vibeInstance = createVibeInstance();
   }
 
-  // Not booted yet - accumulate in global state registry
-  if (!window.__vibeGlobalState) {
-    window.__vibeGlobalState = {};
-  }
-  Object.assign(window.__vibeGlobalState, state);
-
-  // Store config (first caller wins)
-  if (config && !window.__vibeConfig) {
-    window.__vibeConfig = config;
-  }
+  // Not booted yet - accumulate in the reserved namespace's state registry
+  const ns = (window.__vibe ??= {});
+  if (!ns.state) ns.state = {};
+  Object.assign(ns.state, state);
 
-  // Store targetSelector (first caller wins)
-  if (targetSelector && !window.__vibeTargetSelector) {
-    window.__vibeTargetSelector = targetSelector;
+  // Store config (first caller wins). `config.target` scopes the boot to a
+  // selector (the old third positional argument, folded into config at 3.0.0).
+  if (config && !ns.config) {
+    ns.config = config;
   }
 
   // Explicit boot call (no state passed means "boot now with accumulated state")
-  if (Object.keys(state).length === 0 && Object.keys(window.__vibeGlobalState).length > 0) {
+  if (Object.keys(state).length === 0 && Object.keys(ns.state).length > 0) {
     return boot();
   }
 

package/llms.txt

@@ -88,6 +88,8 @@ $.config.theme.colors.primary = "#007bff";
 
 Vibe uses recursive proxies to detect changes at any nesting level automatically.
 
+**Reactivity model (3.0.0):** every binding, conditional, and iteration subscribes to the state keys its expression read during evaluation; a state write dispatches exactly its subscribers. Consequence: an expression only re-evaluates when reactive state it read changes. Window globals, module values, and other non-state sources are read once — reassigning them re-renders nothing. Anything that changes over time belongs in `$`. Helpers defined by component scripts are picked up automatically (mounts re-settle once their scripts have run).
+
 ## Control Flow
 
 ### Iteration
@@ -201,7 +203,7 @@ Multi-segment paths, conditionals (`<!-- if this.editing -->`), and iterations (
 
 Mechanism:
 1. `component({...})` claims the nearest unprocessed `<component>` (or `<div class="component">`) wrapper
-2. It calls `ensureBoot()` from `@ape-egg/vibe/boot`, which initializes `window.$`, parses the DOM, hydrates bindings, and starts the MutationObserver — exactly once per page, even if multiple drop-in blocks call `component()`
+2. It triggers the internal boot, which initializes `window.$`, parses the DOM, hydrates bindings, and starts the MutationObserver — exactly once per page, even if multiple drop-in blocks call `component()`
 3. `@[this.X]`, `onclick="this.fn()"`, `<!-- if this.X -->`, etc. resolve against that block's bucket
 
 Multiple drop-in blocks on the same page each get their own state and run independently. They can still read each other's state via global `$['<id>']` if coordination is needed.
@@ -214,10 +216,39 @@ This makes vibe usable as a "sprinkle of reactivity" library: paste a snippet in
 $.on('ready', () => {});                  // once, after initial parse + hydrate + components mounted
 $.on('afterUpdate', (cur, prev) => {});   // every state change (batched per microtask)
 $.on('afterDomMutation', () => {});       // after every MutationObserver batch
+$.on('unmount', () => {});                // scope-resolved teardown: in a component script, fires when
+                                          // THAT component unmounts; at page level, fires on pagehide
 ```
 
 Also: `await $.ready` resolves after boot, useful when calling code captured `window.$` before vibe finished initializing.
 
+## SPA Routing (`@ape-egg/vibe/spa`)
+
+A standalone router maintaining `$.page = { path, route, params, src }`; a reactive component src is the route outlet:
+
+```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' }, // :param = one segment
+    { route: '/docs/:rest*',     src: '/components/docs.html' },                      // trailing :name* = zero or more
+    { route: '/',                src: '/components/home.html', title: 'Home' },
+    { route: '*',                src: '/components/lost.html' },                      // no-match fallback (deep links/popstate only)
+  ];
+
+  window.$ = vibe({ page: resolve(location, routes) ?? {} });
+  setupSpa({ routes }); // returns { navigate, dispose }
+</script>
+
+<component src="@[page.src]"></component>
+```
+
+Rules: tables are pre-sorted most-specific-first, first match wins. Clicks are claimed only for same-origin, unmodified, untargeted links whose pathname matches a real route (`'*'` never claims) — everything else navigates natively, so mixed MPA/SPA output works. Route titles swap `document.title`. `resolve(location, routes)` is pure. A custom `onNavigate` makes it a pure router without Vibe.
+
+State semantics under SPA: `vibe()` state is app-lifetime, `component()` state is mount-lifetime (resets per visit). `vibe()` itself has defaults semantics once booted — it sets only keys that don't exist yet on `$`, so re-running page scripts (SPA fragment re-mounts) never clobber live state. The compiler's SPA mode (`"spa": true` in `vibe-compiler` config, or `--spa`) compiles an MPA `pages/` tree into page fragments under `/components/vibe-spa/`, a generated route table, and a composed `/index.html` shell wired to this router — deploy with one rewrite: every route → `/index.html`.
+
 ## Special Attributes
 
 ### vibe-fouc
@@ -299,15 +330,15 @@ Imported from `@ape-egg/vibe/component`. Registers a component-local state bucke
 
 ### `$.on(event, callback)`
 
-Register a lifecycle listener. Events: `'ready'`, `'afterUpdate'`, `'afterDomMutation'`. Listeners registered before boot are queued and replayed once vibe is ready.
+Register a lifecycle listener. Events: `'ready'`, `'afterUpdate'`, `'afterDomMutation'`, `'unmount'`. Listeners registered before boot are queued and replayed once vibe is ready. A `'ready'` listener registered AFTER boot (a fetched fragment's script) fires once its mount settles — same timing as `await $.ready`. `'unmount'` is scope-resolved: inside a component script it fires on that component's unmount (and before an HMR re-run); at page level it fires on pagehide.
 
 ### `$.ready`
 
 A Promise that resolves once vibe has finished initial parse + hydrate + component loading.
 
-### `$.reconcile(el, html)` and `$.renderComponent(rawHtml, props, slot, opts)` (advanced)
+### `$.reconcile(el, html)` (advanced)
 
-Subtree reconciliation primitives used by `@ape-egg/vite-plugin-vibe` for surgical HMR. `$.reconcile` diffs `el`'s children against fresh `html` while preserving DOM identity, focus, and selection; vibe-managed regions (iterations, conditionals, components, slot pairs) are treated as opaque. Treat these as plumbing — shape may evolve.
+Subtree reconciliation used by `@ape-egg/vite-plugin-vibe` for surgical HMR: diffs `el`'s children against fresh `html` while preserving DOM identity, focus, and selection; vibe-managed regions (iterations, conditionals, components, slot pairs) are treated as opaque. Treat as plumbing — shape may evolve. (Internal renders/registration live on underscore-prefixed `$` members and are not API.)
 
 ## Scoped Variables in Iterations
 
@@ -368,7 +399,7 @@ Vibe consists of these core runtime modules (in `runtime/`):
 
 - **No computed values primitive**: derived state can be done with `Object.defineProperty($, 'x', { get })` or with `afterUpdate` listeners; a first-class `computed` API isn't shipped
 - **Expression security**: `new Function()` evaluation — don't bind untrusted input
-- **HTML binding**: `@[expr]` always sets `textContent` (escape-safe). A first-class opt-in for trusted HTML is planned but not finalized
+- **HTML binding**: `@[expr]` always sets `textContent` (escape-safe). For trusted HTML, `@[$.unsafe(trustedHtml)]` sets `innerHTML` when it is the element's sole content (no sanitizing — trusted input only; injected markup is inert)
 
 ## Best Practices
 

package/package.json

@@ -1,34 +1,40 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.1.22",
+  "version": "3.0.0",
   "type": "module",
-  "description": "Runtime-first reactivity with optional compiler",
+  "description": "Runtime-first reactivity for plain HTML — no build step, no virtual DOM, no new syntax to learn",
   "main": "index.js",
   "homepage": "https://vibe.korte.kim",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kkortes/vibe.git"
+  },
   "exports": {
     ".": "./index.js",
-    "./boot": "./boot.js",
     "./component": "./component.js",
-    "./hot-module-refresh": "./hot-module-refresh.js",
-    "./runtime": "./runtime/index.js",
-    "./compiler": "./compiler/bin/vibe-compile.js"
-  },
-  "bin": {
-    "vibe": "./compiler/bin/vibe-compile.js"
+    "./spa": "./spa.js",
+    "./hot-module-refresh": "./hot-module-refresh.js"
   },
+  "files": [
+    "index.js",
+    "boot.js",
+    "component.js",
+    "spa.js",
+    "hot-module-refresh.js",
+    "runtime",
+    "vibe.css",
+    "llms.txt"
+  ],
   "keywords": [
     "reactive",
     "framework",
     "frontend",
     "ui",
+    "no-build",
     "mutation-observer",
     "proxy",
-    "minimalistic",
-    "compiler"
+    "minimalistic"
   ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "author": "kkortes",
   "license": "ISC",
   "publishConfig": {