@ape-egg/vibe 2.1.19 → 2.1.20

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.1.20] - 2026-06-25
+
+### Added
+
+- **`@ape-egg/vibe/hot-module-refresh` — transport-agnostic browser HMR client** (`hot-module-refresh.js` (new), exported from `package.json`) — the surgical-HMR "brain" that reconciles a code edit into the live DOM instead of reloading the page is extracted out of `vite-plugin-vibe` into a standalone flat module the vibe package now exports. It's a *soft dependency*: nothing in the runtime imports it and it imports nothing from the runtime, depending only on the public `window.$` surface (`reconcile` / `renderComponent` / `clearComponentCache`), so a plain static server can serve it as-is — no bundler, no Vite. A transport adapter wires its channel to the brain through a single seam, `setupHotModuleRefresh({ debug, subscribe })`, where `subscribe` delivers two callbacks: `componentUpdate(path)` — re-fetch a changed component template and, for each live instance, reconcile surgically when its scripts are unchanged or re-mount otherwise (runtime mode only, since compiled output inlines components into pages) — and `pageUpdate(payload)` — re-fetch the current page and reconcile the `[vibe]` root (mode-agnostic; raw and compiled pages reconcile the same way). This lets the Vite plugin and any other dev transport share one HMR implementation. Tests: `e2e-runtime/hot-module-refresh.html`, `tests/e2e/hot-module-refresh.spec.js`.
+
 ## [2.1.19] - 2026-06-25
 
 ### Fixed

package/hot-module-refresh.js

@@ -0,0 +1,384 @@
+// @ape-egg/vibe/hot-module-refresh
+//
+// Transport-agnostic browser HMR client — the "brain" that reconciles a code
+// edit into the live DOM instead of reloading the page. Extracted out of
+// vite-plugin-vibe so both dev modes share one implementation.
+//
+// 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 /
+// clearComponentCache), so it ships as a flat module a plain static server can
+// serve as-is — no bundler, no Vite.
+//
+// A transport adapter wires its channel to the brain through one seam:
+//
+//   setupHotModuleRefresh({ debug, subscribe })
+//   subscribe({ componentUpdate, pageUpdate })
+//
+//   • componentUpdate(path)  — a component template changed. Fetch the raw
+//       template; for every live instance, reconcile surgically when scripts
+//       are unchanged, else re-mount. Runtime-mode only — compiled output
+//       inlines components into pages, so its adapter never calls this.
+//   • pageUpdate(payload)    — the current page changed. Fetch it and reconcile
+//       the [vibe] root. Mode-agnostic: a raw page (runtime) and a compiled
+//       page (compiled) reconcile the same way.
+
+export const setupHotModuleRefresh = ({ debug = false, subscribe }) => {
+  const dbg = {
+    info: (...a) => { if (debug) console.info(...a); },
+    group: (...a) => { if (debug) console.group(...a); },
+    groupEnd: () => { if (debug) console.groupEnd(); },
+  };
+
+  // Track which live <component> wrappers correspond to which source file.
+  // Vibe's component.js replaces <component src='X'> with a fresh <component>
+  // (no src). The spy below tags the new wrapper with _vibeSrc + the slot
+  // content, so on a component-update we can find every live instance and
+  // hand the slot back to Vibe verbatim during re-mount.
+  const liveBySrc = new Map();
+
+  const isComponentSrc = (n) =>
+    n?.nodeType === 1 && n.hasAttribute?.('src') &&
+    (n.nodeName === 'COMPONENT' || (n.nodeName === 'DIV' && n.classList?.contains?.('component')));
+  const isProcessedComponent = (n) =>
+    n?.nodeType === 1 && !n.hasAttribute?.('src') &&
+    (n.nodeName === 'COMPONENT' || (n.nodeName === 'DIV' && n.classList?.contains?.('component')));
+
+  // Snapshot slot innerHTML on a <component src> BEFORE vibe strips iteration/
+  // conditional templates from its subtree. vibe's renderAllIterations removes
+  // nodes between <!-- each -->/<!-- /each --> comments synchronously after
+  // hydrate; if we wait until the component is swapped out (spy's removedNodes
+  // path) and read innerHTML then, the templates are gone and HMR re-mounts
+  // receive an empty slot. setup runs before the page's boot script calls into
+  // vibe — the initial pass captures everything present at parse time.
+  const captureSlot = (el) => {
+    if (el._vibePluginSlot === undefined) el._vibePluginSlot = el.innerHTML;
+  };
+  document.querySelectorAll('component[src], div.component[src]').forEach(captureSlot);
+
+  // Mirrors vibe/runtime/cleanup.js#shouldCleanup: a subtree is 'done' once
+  // no <component[src]> remains pending and no literal @[...] sits in a
+  // text node. Used to release vibe-fouc once Vibe finishes processing the
+  // re-mounted component subtree.
+  const waitForVibeReady = (target, timeout = 2000) => new Promise((done) => {
+    const deadline = performance.now() + timeout;
+    const tick = () => {
+      if (!target.isConnected) return done();
+      if (!target.querySelector('component[src], div.component[src]')) {
+        const walker = document.createTreeWalker(target, NodeFilter.SHOW_TEXT);
+        let pending = false;
+        let n;
+        while ((n = walker.nextNode())) {
+          if (/@\[.+?\]/.test(n.textContent)) { pending = true; break; }
+        }
+        if (!pending) return done();
+      }
+      if (performance.now() > deadline) return done();
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  });
+
+  new MutationObserver((mutations) => {
+    // First pass: capture slot content on any <component src> that gets
+    // added dynamically (conditional/iteration branches mounting nested
+    // components). Must happen before the removal/addition logic runs, so
+    // that if a subsequent mutation re-mounts or strips this element, the
+    // snapshot is already in place.
+    for (const { addedNodes } of mutations) {
+      for (const n of addedNodes) {
+        if (isComponentSrc(n)) captureSlot(n);
+        if (n?.nodeType === 1 && n.querySelectorAll) {
+          n.querySelectorAll('component[src], div.component[src]').forEach(captureSlot);
+        }
+      }
+    }
+    for (const { addedNodes, removedNodes } of mutations) {
+      let src = null;
+      let slotContent = '';
+      let hadFouc = false;
+      let props = null;
+      let scriptHash;
+      for (const n of removedNodes) {
+        if (isComponentSrc(n)) {
+          src = n.getAttribute('src');
+          // vibe's component.js deletes _vibeSlotContent synchronously after
+          // reading it, so on re-mount transitions the prop is already gone
+          // by the time we see the removal. _vibePluginSlot is our own
+          // mirror that vibe never touches — read it preferentially, fall
+          // back to vibe's prop (initial page load), then innerHTML (also
+          // initial, when source was authored inline).
+          slotContent = (
+            n._vibePluginSlot !== undefined ? n._vibePluginSlot :
+            n._vibeSlotContent !== undefined ? n._vibeSlotContent :
+            n.innerHTML
+          ).trim();
+          hadFouc = n.hasAttribute('vibe-fouc');
+          // Script hash is set by remount() on the <component src> before it
+          // hits the DOM, OR carried from a previous wrapper via this same
+          // forward path. Either way, stash it so the processed wrapper can
+          // use it as baseline for future surgical reconciles.
+          scriptHash = n._vibeScriptHash;
+          // Capture all authored attrs so reconcile can detect prop changes
+          // on the callsite and re-mount when they differ. vibe-fouc is a
+          // transient HMR marker — in either attribute or class form — and
+          // must never end up in the authored set or every FOUC flip would
+          // falsely look like a prop change.
+          props = {};
+          for (const a of n.attributes) {
+            if (a.name === 'vibe-fouc') continue;
+            if (a.name === 'class') {
+              const kept = a.value.split(/\s+/).filter((t) => t && t !== 'vibe-fouc');
+              if (kept.length) props.class = kept.join(' ');
+              continue;
+            }
+            props[a.name] = a.value;
+          }
+          break;
+        }
+      }
+      if (!src) continue;
+      for (const n of addedNodes) {
+        if (isProcessedComponent(n)) {
+          n._vibeSrc = src;
+          n._vibeSlotContent = slotContent;
+          // Brain-owned mirror so we can recover slot content after vibe's
+          // processSingle deletes _vibeSlotContent on the next re-mount.
+          n._vibePluginSlot = slotContent;
+          n._vibeProps = props;
+          if (scriptHash !== undefined) n._vibeScriptHash = scriptHash;
+          if (!liveBySrc.has(src)) liveBySrc.set(src, new Set());
+          liveBySrc.get(src).add(n);
+          if (hadFouc) {
+            n.setAttribute('vibe-fouc', '');
+            waitForVibeReady(n).then(() => n.removeAttribute('vibe-fouc'));
+          }
+          break;
+        }
+      }
+    }
+  }).observe(document.body, { childList: true, subtree: true });
+
+  // Cheap string hash (djb2). Used to detect <script type="module"> changes
+  // between HMR fetches — unchanged scripts mean registered component state
+  // is still valid, so we can reconcile in place instead of re-mounting.
+  const hashString = (s) => {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) h = (((h << 5) + h) + s.charCodeAt(i)) | 0;
+    return h;
+  };
+  const hashScripts = (rawHtml) => {
+    const temp = document.createElement('div');
+    temp.innerHTML = rawHtml;
+    const scripts = temp.querySelectorAll('script[type="module"]');
+    return hashString([...scripts].map((s) => s.textContent || '').join(''));
+  };
+
+  // Return the baseline script hash for a live wrapper. On initial mount,
+  // vibe's component.js stashes the raw fetched HTML on the wrapper as
+  // _vibeRawSource. We hash it lazily on first HMR check and cache the
+  // result. This makes the very first save after page load surgical
+  // (assuming the script body hasn't changed) rather than always falling
+  // back to re-mount.
+  const getBaselineScriptHash = (el) => {
+    if (el._vibeScriptHash !== undefined) return el._vibeScriptHash;
+    if (el._vibeRawSource) {
+      el._vibeScriptHash = hashScripts(el._vibeRawSource);
+      return el._vibeScriptHash;
+    }
+    return undefined;
+  };
+
+  // Collect data-vibe-component-id values from the live wrapper's subtree in
+  // DOM order. Script processing inside the component assigns ids in script
+  // order → DOM order (each script's sibling group follows it), so reusing
+  // ids in DOM order keeps state bindings aligned across HMR renders.
+  const collectIdsInOrder = (el) => {
+    const ids = [];
+    const seen = new Set();
+    el.querySelectorAll('[data-vibe-component-id]').forEach((node) => {
+      const id = node.getAttribute('data-vibe-component-id');
+      if (id && !seen.has(id)) { seen.add(id); ids.push(id); }
+    });
+    return ids;
+  };
+
+  // True when an element lives inside a vibe iteration region (between
+  // <!-- each ... --> and <!-- /each -->). Iterations materialize the
+  // template N times with pre-resolved props; iterate.js caches the template
+  // at mount time, so surgical changes to one instance would be clobbered on
+  // the next array mutation. Fall back to re-mount in that case.
+  const isInsideIteration = (el) => {
+    let cur = el;
+    while (cur && cur.parentNode) {
+      let depth = 0;
+      let sib = cur.previousSibling;
+      while (sib) {
+        if (sib.nodeType === 8) {
+          const t = sib.textContent.trim();
+          if (t === '/each') depth++;
+          else if (t.startsWith('each ')) {
+            if (depth === 0) return true;
+            depth--;
+          }
+        }
+        sib = sib.previousSibling;
+      }
+      cur = cur.parentNode;
+      if (!cur || cur === document.body) return false;
+    }
+    return false;
+  };
+
+  // Re-mount a single live instance by swapping its wrapper for a fresh
+  // <component src>. Vibe re-fetches, re-executes scripts, and re-inlines
+  // the template. Used for first-HMR (no baseline hash), script changes,
+  // iteration-nested instances, and as a failure fallback.
+  const remount = (el, path, scriptHash) => {
+    const oldComponentIds = collectIdsInOrder(el);
+    const fresh = document.createElement(el.tagName);
+    if (el.tagName === 'DIV') fresh.className = 'component';
+    const props = el._vibeProps || { src: path };
+    for (const [name, value] of Object.entries(props)) {
+      fresh.setAttribute(name, value);
+    }
+    fresh.setAttribute('vibe-fouc', '');
+    const slot = el._vibePluginSlot !== undefined
+      ? el._vibePluginSlot
+      : (el._vibeSlotContent || '');
+    fresh._vibeSlotContent = slot;
+    fresh._vibePluginSlot = slot;
+    fresh._vibeScriptHash = scriptHash;
+    if (oldComponentIds.length) fresh._vibeReuseComponentIds = oldComponentIds;
+    // Transfer iteration-prop registry ownership from the soon-to-be-detached
+    // wrapper to the fresh one. The detach would otherwise trigger Vibe's
+    // releaseOrphanedIterationProps and free the registry slots that the
+    // copied prop attributes (e.g. node='@[window.__vibeIterProps._pN]') still
+    // reference, leaving every binding to render undefined after the HMR swap.
+    if (el._vibeIterPropIds) {
+      fresh._vibeIterPropIds = el._vibeIterPropIds;
+      fresh.setAttribute('data-vibe-iter-prop', '');
+      el._vibeIterPropIds = null;
+      el.removeAttribute('data-vibe-iter-prop');
+    }
+    el.replaceWith(fresh);
+  };
+
+  // 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
+  //      substituted, componentIds reused) and $.reconcile diffs it against
+  //      the live wrapper's children. DOM identity, focus, and component
+  //      state are preserved.
+  //   2. First HMR for any instance (no baseline hash stored), script changes,
+  //      or iteration-scoped callsites → full re-mount (same path as before
+  //      the surgical rewrite). vibe-fouc hides the subtree until ready.
+  //
+  // Props and slot content always come from the spy's _vibeProps /
+  // _vibePluginSlot snapshot.
+  let componentUpdateCount = 0;
+  const componentUpdate = async (path) => {
+    const n = ++componentUpdateCount;
+    // Drop the runtime's cached template for this file so any component
+    // mounted *after* this edit fetches the fresh version. Already-mounted
+    // instances are refreshed surgically below; this covers future mounts.
+    window.$?.clearComponentCache?.(path);
+    const instances = liveBySrc.get(path);
+    dbg.group('[vibe-hmr] component-update #' + n, path,
+      '— instances:', instances?.size || 0);
+    try {
+      if (!instances || !instances.size) {
+        dbg.info('[vibe-hmr]   no live instances; nothing to do');
+        return;
+      }
+      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'
+        && typeof window.$?.reconcile === 'function';
+
+      let surgical = 0;
+      let remounted = 0;
+      for (const el of [...instances]) {
+        instances.delete(el);
+        if (!el.parentNode) continue;
+
+        const oldHash = getBaselineScriptHash(el);
+        const inIter = isInsideIteration(el);
+
+        if (canSurgical && oldHash !== undefined && oldHash === scriptHash && !inIter) {
+          try {
+            const componentIds = collectIdsInOrder(el);
+            const slot = el._vibePluginSlot !== undefined
+              ? el._vibePluginSlot
+              : (el._vibeSlotContent || '');
+            const props = el._vibeProps || {};
+            const processedHtml = window.$.renderComponent(rawHtml, props, slot, { componentIds });
+            const summary = await window.$.reconcile(el, processedHtml);
+            el._vibeScriptHash = scriptHash;
+            el._vibeRawSource = rawHtml;
+            if (!liveBySrc.has(path)) liveBySrc.set(path, new Set());
+            liveBySrc.get(path).add(el);
+            surgical++;
+            dbg.info('[vibe-hmr]   surgical reconcile:', summary);
+            continue;
+          } catch (err) {
+            console.warn('[vibe-hmr]   surgical failed, falling back to re-mount:', err);
+          }
+        }
+
+        remount(el, path, scriptHash);
+        remounted++;
+      }
+      dbg.info('[vibe-hmr]   surgical:', surgical, 'remounted:', remounted);
+    } catch (err) {
+      console.error('[vibe-hmr]   component-update failed:', err);
+    } finally {
+      dbg.groupEnd();
+    }
+  };
+
+  // Page file changed — fetch new HTML and hand the [vibe] root + new inner
+  // content to $.reconcile. Vibe walks live vs. source and applies the
+  // minimal mutation; iteration / conditional / component regions are
+  // opaque (their interiors are state-driven). Page-level JS state on $
+  // is preserved (no full reload).
+  let pageUpdateCount = 0;
+  const pageUpdate = async (payload) => {
+    const n = ++pageUpdateCount;
+    dbg.group('[vibe-hmr] page-update #' + n, payload?.path || '(no path)');
+    try {
+      if (!window.$ || typeof window.$.reconcile !== 'function') {
+        console.warn('[vibe-hmr]   $.reconcile not available — skipped');
+        return;
+      }
+      const url = location.href + (location.href.includes('?') ? '&' : '?') + '_t=' + Date.now();
+      const t0 = performance.now();
+      const html = await fetch(url).then((r) => r.text());
+      dbg.info('[vibe-hmr]   fetched', html.length, 'bytes in', (performance.now() - t0).toFixed(1) + 'ms');
+      const doc = new DOMParser().parseFromString(html, 'text/html');
+      const newRoot = doc.querySelector('[vibe]') || doc.body;
+      const liveRoot = document.querySelector('[vibe]') || document.body;
+      dbg.info('[vibe-hmr]   target [vibe] root:', liveRoot, 'isConnected=', liveRoot.isConnected);
+      // Note: we no longer strip <script type='module'> from source. Stripping
+      // misaligned source vs. live and caused cascading replaces. Reconcile's
+      // tag-aligned walk now matches scripts at their position; updating a
+      // script's textContent doesn't re-execute it (a known limitation —
+      // editing inline page scripts requires a real reload to take effect).
+      const summary = await window.$.reconcile(liveRoot, newRoot.innerHTML);
+      dbg.info('[vibe-hmr]   summary:', summary);
+      if (summary?.changes?.length) {
+        for (const c of summary.changes) dbg.info('[vibe-hmr]     ·', c);
+      } else {
+        dbg.info('[vibe-hmr]   no changes — source matches live');
+      }
+    } catch (err) {
+      console.error('[vibe-hmr]   page-update failed:', err);
+    } finally {
+      dbg.groupEnd();
+    }
+  };
+
+  subscribe({ componentUpdate, pageUpdate });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.1.19",
+  "version": "2.1.20",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",
@@ -9,6 +9,7 @@
     ".": "./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"
   },