@ape-egg/vibe 2.3.0 → 3.0.1

package/README.md

@@ -1,6 +1,14 @@
 # Vibe
 
-**Version 2.0.2 (Beta)** — A runtime-first reactive framework with optional compilation.
+**Version 3.0.1** — 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.
@@ -350,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
@@ -729,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

@@ -43,7 +43,7 @@ export const applyDefaults = (target, state) => {
   return target;
 };
 
-const vibe = (state = {}, config, targetSelector) => {
+const vibe = (state = {}, config) => {
   if (isBooted()) {
     // Already booted: initial state declared late seeds missing keys only —
     // on a fresh document load this branch never runs, so MPA behavior is
@@ -57,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.
@@ -245,7 +247,7 @@ A standalone router maintaining `$.page = { path, route, params, src }`; a react
 
 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). `@ape-egg/vibe/defaults` is the vibe entry with defaults semantics — already booted, it sets only keys that don't exist yet on `$`, so re-running page scripts 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`.
+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
 
@@ -328,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
 
@@ -397,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,35 +1,40 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.3.0",
+  "version": "3.0.1",
   "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",
     "./spa": "./spa.js",
-    "./runtime": "./runtime/index.js",
-    "./compiler": "./compiler/bin/vibe-compile.js"
-  },
-  "bin": {
-    "vibe": "./compiler/bin/vibe-compile.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": {