@ape-egg/vibe 1.8.0 → 1.9.1

package/runtime/component.js

@@ -1,5 +1,11 @@
 import { debugLog } from './debug.js';
-import { PHASE_FETCH, DEHYDRATE_CLASS_OR_ATTR } from './constants.js';
+import {
+  PHASE_FETCH,
+  DEHYDRATE_CLASS_OR_ATTR,
+  BINDING_REGEX,
+  THIS_PROP_REGEX,
+  STATE_THIS_PROP_REGEX,
+} from './constants.js';
 import { evalInScope } from './utils.js';
 
 // Deterministic component counter
@@ -16,6 +22,42 @@ export const generateComponentId = () => {
 // Helper to escape regex special characters
 const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+// Kept as no-ops for API compatibility — path-based tracking was replaced by
+// DOM-scan cleanup in releaseOrphanedComponentState. Manifest paths don't
+// align 1:1 with component ownership across conditional remounts, so scanning
+// the DOM subtree about to be removed is simpler and waterproof.
+export const trackComponentOwnership = () => {};
+
+// Given an iterable of DOM nodes that are about to be (or have just been)
+// removed, find every `data-vibe-component-id` inside them and, for each id
+// whose DOM is fully gone from the live document, evict its state.
+//
+// Call this AFTER the nodes have been detached from the document so the
+// `document.querySelector` check sees the post-removal state.
+export const releaseOrphanedComponentState = (collectedIds) => {
+  if (!collectedIds || collectedIds.size === 0) return;
+  for (const id of collectedIds) {
+    if (document.querySelector(`[data-vibe-component-id="${id}"]`)) continue;
+    delete window.__vibeComponents?.[id];
+    // CLEANUP OF CURRENT STATE
+    delete window.$[id];
+  }
+};
+
+// Walk a node subtree (element or node list) and collect all
+// `data-vibe-component-id` values found on the node and its descendants.
+export const collectComponentIds = (node, into = new Set()) => {
+  if (!node) return into;
+  if (node.nodeType === 1) {
+    const id = node.getAttribute('data-vibe-component-id');
+    if (id) into.add(id);
+    node.querySelectorAll?.('[data-vibe-component-id]').forEach((el) => {
+      into.add(el.getAttribute('data-vibe-component-id'));
+    });
+  }
+  return into;
+};
+
 // Track pending fetches to cancel them if element is removed
 const pendingFetches = new WeakMap(); // element → AbortController
 
@@ -43,6 +85,162 @@ const isNestedInUnprocessedComponent = (el, rootElement) => {
   return false;
 };
 
+// Rewrite `@[this.x...]` and `$.this.x...` inside element's text/attrs to use
+// componentId. Shared between script-execution path and pure-render path.
+//
+// Within `@[...]` bindings we rewrite every `this.X` reference (preserving
+// any trailing `.Y.Z` chain), so `@[this.user.name]` and `@[this.x + 1]` both
+// resolve correctly. Outside bindings — i.e. event handler attribute bodies
+// like `onclick="$.this.mode = 'edit'"` — only `$.this.X` writes are
+// rewritten; bare `this.X` reads in event handlers are handled later by
+// parse.js (which preserves DOM properties like `this.value`).
+const rewriteBindingsInString = (str, componentId) =>
+  str.replace(BINDING_REGEX, (match, expr) => {
+    const rewritten = expr.replace(THIS_PROP_REGEX, `${componentId}.$1`);
+    return rewritten === expr ? match : `@[${rewritten}]`;
+  });
+
+const rewriteThisBindings = (element, componentId) => {
+  Array.from(element.childNodes).forEach((node) => {
+    if (node.nodeType === Node.TEXT_NODE && node.textContent.includes('@[this.')) {
+      node.textContent = rewriteBindingsInString(node.textContent, componentId);
+    }
+  });
+
+  Array.from(element.attributes || []).forEach((attr) => {
+    if (attr.value.includes('@[this.')) {
+      attr.value = rewriteBindingsInString(attr.value, componentId);
+    }
+    if (attr.value.includes('$.this.')) {
+      attr.value = attr.value.replace(STATE_THIS_PROP_REGEX, `$.${componentId}.$1`);
+    }
+  });
+
+  Array.from(element.children).forEach((child) => {
+    rewriteThisBindings(child, componentId);
+  });
+};
+
+// Tag siblings of a <script> with componentId and rewrite `this.` bindings.
+// Runs BEFORE script.remove() so nextElementSibling is valid. Shared by
+// processSingle (executing path) and renderComponentTemplate (pure path).
+const tagScriptSiblings = (script, componentId) => {
+  let sibling = script.nextElementSibling;
+  while (sibling) {
+    if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
+      break;
+    }
+    sibling.setAttribute('data-vibe-component-id', componentId);
+    rewriteThisBindings(sibling, componentId);
+    sibling = sibling.nextElementSibling;
+  }
+};
+
+// Substitute props + inline slot content into a pre-processed temp container.
+// Returns the final processed HTML string. Shared by processSingle.finalize()
+// (runtime mount) and renderComponentTemplate (surgical HMR).
+const renderPropsAndSlot = (temp, props, slotHtml) => {
+  let transformedHtml = temp.innerHTML;
+
+  const DIRECTIVE_COMMENT_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
+  const EVENT_ATTR_REGEX = /\bon(\w+)="([^"]*)"/g;
+
+  Object.entries(props).forEach(([propName, propValue]) => {
+    const bindingMatch = propValue.match(/^@\[(.+)\]$/);
+    const exactPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
+    const idRegex = new RegExp(
+      `(?<![a-zA-Z0-9_$\\.])${escapeRegex(propName)}(?![a-zA-Z0-9_$])`,
+      'g'
+    );
+
+    const substituteInExpr = (expr, replacement) => expr.replace(idRegex, replacement);
+
+    if (bindingMatch) {
+      const path = bindingMatch[1];
+      transformedHtml = transformedHtml.replace(exactPattern, `@[${path}]`);
+      transformedHtml = transformedHtml.replace(BINDING_REGEX, (match, expr) => {
+        const rewritten = substituteInExpr(expr, `(${path})`);
+        return rewritten === expr ? match : `@[${rewritten}]`;
+      });
+      transformedHtml = transformedHtml.replace(
+        DIRECTIVE_COMMENT_REGEX,
+        (match, kw, expr) => {
+          const replacement = kw === 'each' ? path : `(${path})`;
+          const rewritten = substituteInExpr(expr, replacement);
+          return rewritten === expr ? match : `<!-- ${kw} ${rewritten} -->`;
+        }
+      );
+      const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'g');
+      transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
+        const rewritten = body.replace(stateRegex, `$.${path}`);
+        return rewritten === body ? match : `on${evName}="${rewritten}"`;
+      });
+    } else {
+      transformedHtml = transformedHtml.replace(exactPattern, propValue);
+      const isNumeric =
+        typeof propValue === 'string' && /^-?\d+(\.\d+)?(e[+-]?\d+)?$/i.test(propValue);
+      const isBooleanAttr = propValue === '';
+      const literal = isBooleanAttr
+        ? 'true'
+        : typeof propValue === 'string' && !isNumeric
+          ? JSON.stringify(propValue)
+          : String(propValue);
+      transformedHtml = transformedHtml.replace(BINDING_REGEX, (match, expr) => {
+        const rewritten = substituteInExpr(expr, literal);
+        return rewritten === expr ? match : `@[${rewritten}]`;
+      });
+      transformedHtml = transformedHtml.replace(
+        DIRECTIVE_COMMENT_REGEX,
+        (match, kw, expr) => {
+          const rewritten = substituteInExpr(expr, literal);
+          return rewritten === expr ? match : `<!-- ${kw} ${rewritten} -->`;
+        }
+      );
+      const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'g');
+      transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
+        const rewritten = body.replace(stateRegex, `$.${literal}`);
+        return rewritten === body ? match : `on${evName}="${rewritten}"`;
+      });
+    }
+  });
+
+  const children = (slotHtml || '').trim();
+  if (children) {
+    transformedHtml = transformedHtml.replace(
+      /<slot(\s[^>]*)?>\s*<\/slot>/g,
+      (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
+    );
+    transformedHtml = transformedHtml.replace(
+      /<slot(\s[^>]*)?\/>/g,
+      (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
+    );
+  }
+
+  return transformedHtml;
+};
+
+// Pure-render path for surgical HMR. Takes a component's raw template HTML
+// plus the live instance's props, slot, and existing componentIds. Returns
+// the processed HTML string that $.reconcile can diff against the live
+// wrapper's children. Scripts are NOT executed — callers are responsible
+// for deciding whether to preserve the existing state (reuse componentIds)
+// or trigger a full re-mount (new componentIds).
+export const renderComponentTemplate = (rawHtml, props = {}, slotHtml = '', options = {}) => {
+  const { componentIds = [] } = options;
+  const temp = document.createElement('div');
+  temp.innerHTML = rawHtml;
+
+  const idsToReuse = [...componentIds];
+  const moduleScripts = temp.querySelectorAll('script[type="module"]');
+  for (const script of moduleScripts) {
+    const componentId = idsToReuse.shift() || generateComponentId();
+    tagScriptSiblings(script, componentId);
+    script.remove();
+  }
+
+  return renderPropsAndSlot(temp, props, slotHtml);
+};
+
 // Process a single component element: fetch HTML, execute scripts, replace DOM
 const processSingle = (el, debug) => {
   // Skip dehydrated components
@@ -89,7 +287,10 @@ const processSingle = (el, debug) => {
 
         // Strip `import component from '...'` — Vibe injects the contextual
         // component() function as a parameter (it needs access to the temp DOM)
-        scriptContent = scriptContent.replace(/import\s+component\s+from\s+['"][^'"]+['"];?\s*/g, '');
+        scriptContent = scriptContent.replace(
+          /import\s+component\s+from\s+['"][^'"]+['"];?\s*/g,
+          ''
+        );
 
         // Check for remaining imports that need rewriting
         const hasImports = /import\s/.test(scriptContent);
@@ -115,40 +316,24 @@ const processSingle = (el, debug) => {
           );
         }
 
-        // Generate component ID for this instance
-        const componentId = generateComponentId();
+        // Reuse component ID from HMR if available, otherwise generate new
+        const reuseIds = el._vibeReuseComponentIds;
+        const componentId = reuseIds && reuseIds.length ? reuseIds.shift() : generateComponentId();
 
-        // Provide a component() function that registers state for this component
+        // Provide a component() function that registers state for this component.
+        // Sibling tagging is handled below (before script.remove()) so it works
+        // for both sync and async scripts.
         const componentFn = (state) => {
-          // Register component state in both places:
-          // 1. __vibeComponents registry (for pre-boot components)
-          if (!window.__vibeComponents) {
-            window.__vibeComponents = {};
-          }
+          if (!window.__vibeComponents) window.__vibeComponents = {};
           window.__vibeComponents[componentId] = state;
-
-          // 2. Directly in window.$ (the reactive proxy) for post-boot components
-          if (window.$) {
-            window.$[componentId] = state;
-          }
-
-          // Tag all siblings (everything after the script in this component)
-          let sibling = script.nextElementSibling;
-          while (sibling) {
-            // Stop if we hit another module script
-            if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
-              break;
-            }
-            sibling.setAttribute('data-vibe-component-id', componentId);
-            sibling = sibling.nextElementSibling;
-          }
+          if (window.$) window.$[componentId] = state;
         };
 
         // Execute script with component() function in scope
         try {
           if (hasImports) {
             // Async execution for scripts with imports
-            const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+            const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
             asyncTasks.push(new AsyncFunction('component', scriptContent)(componentFn));
           } else {
             // Synchronous execution for scripts without imports (preserves boot timing)
@@ -159,39 +344,9 @@ const processSingle = (el, debug) => {
           console.warn('[vibe] Failed to execute component script:', e);
         }
 
-        // Rewrite this.property to componentId.property in siblings
-        // This allows the runtime to resolve component-scoped bindings
-        const rewriteThisBindings = (element) => {
-          const thisRegex = /@\[this\.(\w+)\]/g;
-
-          // Rewrite in text nodes
-          Array.from(element.childNodes).forEach((node) => {
-            if (node.nodeType === Node.TEXT_NODE && node.textContent.includes('@[this.')) {
-              node.textContent = node.textContent.replace(thisRegex, `@[${componentId}.$1]`);
-            }
-          });
-
-          // Rewrite in attributes
-          Array.from(element.attributes || []).forEach((attr) => {
-            if (attr.value.includes('@[this.')) {
-              attr.value = attr.value.replace(thisRegex, `@[${componentId}.$1]`);
-            }
-          });
-
-          // Recurse into children
-          Array.from(element.children).forEach((child) => {
-            rewriteThisBindings(child);
-          });
-        };
-
-        let sibling = script.nextElementSibling;
-        while (sibling) {
-          if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
-            break;
-          }
-          rewriteThisBindings(sibling);
-          sibling = sibling.nextElementSibling;
-        }
+        // Tag siblings + rewrite this. bindings using shared helper. Runs
+        // BEFORE script.remove() so nextElementSibling is valid.
+        tagScriptSiblings(script, componentId);
 
         // Remove script from temp (we executed it manually)
         script.remove();
@@ -199,30 +354,8 @@ const processSingle = (el, debug) => {
 
       // Finalize: props, slots, DOM replacement
       const finalize = () => {
-        // Get transformed HTML from temp container (scripts removed)
-        let transformedHtml = temp.innerHTML;
-
-        // Replace props
-        Object.entries(props).forEach(([propName, propValue]) => {
-          const bindingMatch = propValue.match(/^@\[(.+)\]$/);
-
-          if (bindingMatch) {
-            // Reactive prop: replace @[propName] with @[path]
-            const path = bindingMatch[1];
-            const propPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
-            transformedHtml = transformedHtml.replace(propPattern, `@[${path}]`);
-          } else {
-            // Static prop: replace @[propName] with literal value
-            const propPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
-            transformedHtml = transformedHtml.replace(propPattern, propValue);
-          }
-        });
-
-        // Replace <slot></slot> with children
-        if (children) {
-          transformedHtml = transformedHtml.replace(/<slot><\/slot>/g, children);
-          transformedHtml = transformedHtml.replace(/<slot\s*\/>/g, children);
-        }
+        // Delegate prop substitution + slot inlining to shared helper.
+        const transformedHtml = renderPropsAndSlot(temp, props, children);
 
         // Clean up pending fetch tracker
         pendingFetches.delete(el);
@@ -241,6 +374,24 @@ const processSingle = (el, debug) => {
           }
 
           newWrapper.innerHTML = transformedHtml;
+          // Stash the raw source so the HMR plugin can establish a baseline
+          // script hash on the very first update — without this, the first
+          // save after page load would always fall back to re-mount (since
+          // the plugin would have nothing to compare against). Vibe itself
+          // never reads this; it's purely for the plugin spy.
+          newWrapper._vibeRawSource = html;
+          // Transfer iteration-prop registry ownership from the soon-to-be-
+          // detached `<component src>` to the new wrapper. The detached element
+          // would otherwise trigger releaseOrphanedIterationProps and free the
+          // registry slots that the inlined template's bindings still reference,
+          // causing every `@[window.__vibeIterProps._pN]` to resolve to undefined
+          // on the next hydrate.
+          if (el._vibeIterPropIds) {
+            newWrapper._vibeIterPropIds = el._vibeIterPropIds;
+            newWrapper.setAttribute('data-vibe-iter-prop', '');
+            el._vibeIterPropIds = null;
+            el.removeAttribute('data-vibe-iter-prop');
+          }
           el.replaceWith(newWrapper);
           debugLog(PHASE_FETCH, src, debug);
 
@@ -286,7 +437,7 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
   // unprocessed component[src] elements (they're slot content that will
   // be revealed when the parent component finalizes).
   const topLevel = Array.from(allComponents).filter(
-    el => !isNestedInUnprocessedComponent(el, rootElement)
+    (el) => !isNestedInUnprocessedComponent(el, rootElement)
   );
 
   if (topLevel.length === 0) {
@@ -299,5 +450,5 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
   // processed by the MutationObserver → processComponent chain.
   // onComplete is handled by checkCleanup (which fires when no
   // component[src] elements remain).
-  topLevel.forEach(el => processSingle(el, debug));
+  topLevel.forEach((el) => processSingle(el, debug));
 };

package/runtime/conditionals.js

@@ -3,6 +3,7 @@ import affected from './affected.js';
 import hydrate from './hydrate.js';
 import { createScopedState, renderAllIterations, initializeBlock } from './iterate.js';
 import { evalInScope } from './utils.js';
+import { collectComponentIds, releaseOrphanedComponentState } from './component.js';
 
 // Registry of DOM nodes owned by conditional branches.
 // Maps a DOM node to { nodes: array_ref, index: number } so that
@@ -30,7 +31,9 @@ const findConditionalPath = (node, manifest) => {
 
 // Register branch tree nodes in the manifest (recursive)
 const addBranchToManifest = (tree, manifest, basePath) => {
-  if (tree.element) manifest[basePath] = tree.element;
+  if (tree.element) {
+    manifest[basePath] = tree.element;
+  }
   if (tree.children) {
     for (const key in tree.children) {
       addBranchToManifest(tree.children[key], manifest, `${basePath}.${key}`);
@@ -218,6 +221,11 @@ const unmountBranch = (node, manifest) => {
     }
   }
 
+  // Collect componentIds from the subtree BEFORE detaching so we can check
+  // after removal whether any live DOM still holds them.
+  const ids = new Set();
+  activeInstance.nodes.forEach((domNode) => collectComponentIds(domNode, ids));
+
   // Remove all nodes from DOM and deregister from branch registry
   activeInstance.nodes.forEach((domNode) => {
     branchNodeRegistry.delete(domNode);
@@ -226,6 +234,9 @@ const unmountBranch = (node, manifest) => {
     }
   });
 
+  // CLEANUP OF CURRENT STATE
+  releaseOrphanedComponentState(ids);
+
   // Clear active instance
   node.runtime.activeInstance = null;
 };

package/runtime/constants.js

@@ -210,9 +210,11 @@ export const BINDING_REGEX = new RegExp(String.raw`\@\[(${BINDING_INNER})\]`, 'g
 // Regex for detecting a pure binding (entire value is just @[expression])
 export const PURE_BINDING_REGEX = new RegExp(String.raw`^\@\[(${BINDING_INNER})\]$`);
 
-// Regex for parsing iteration comment syntax (<!-- each items as item, index -->)
-// Supports nested paths like category.items and bracket notation like teams[0].combatants
-export const ITERATION_REGEX = /^each\s+([\w.\[\]]+)\s+as\s+(\w+)(?:\s*,\s*(\w+))?\s*$/;
+// Regex for parsing iteration comment syntax (<!-- each expression as item, index -->)
+// The array expression can be any JS: a state path (items), a window global
+// (window.fights), a method call (items.filter(x => x.active)), or an inline
+// array literal (['a', 'b']). Parsed via evalInScope at render time.
+export const ITERATION_REGEX = /^each\s+(.+)\s+as\s+(\w+)(?:\s*,\s*(\w+))?\s*$/;
 
 // Regex for detecting start of iteration comment
 export const ITERATION_START_REGEX = /^each\s+/;
@@ -222,3 +224,15 @@ export const CONDITIONAL_REGEX = /^if\s+(.+)$/;
 
 // Regex for detecting start of conditional comment
 export const CONDITIONAL_START_REGEX = /^if\s+/;
+
+// Regex for rewriting component-local `this.X` references to the component's
+// state path. Captures the leading identifier only — any trailing `.Y.Z`
+// chain stays attached after replacement, so `this.user.name` becomes
+// `<componentId>.user.name`. Used in expression bodies (bindings, event
+// handlers, conditional/iteration directives).
+export const THIS_PROP_REGEX = /\bthis\.(\w+)/g;
+
+// Regex for rewriting `$.this.X` writes (proxy assignment from event handlers)
+// to the component's write path. Same prefix-only semantics as THIS_PROP_REGEX
+// — `$.this.user.name = x` becomes `$.<componentId>.user.name = x`.
+export const STATE_THIS_PROP_REGEX = /\$\.this\.(\w+)/g;

package/runtime/hydrate.js

@@ -87,17 +87,24 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           // Attribute: Truthful DOM representation, enables compiler snapshots via outerHTML
           const expr = isPureBinding[1];
           const value = evalInScope(expr, effectiveState, element);
-          element[attrName] = value;
+          if (element[attrName] !== value) element[attrName] = value;
           if (value !== undefined && value !== null) {
-            element.setAttribute(attrName, String(value));
+            const str = String(value);
+            if (element.getAttribute(attrName) !== str) element.setAttribute(attrName, str);
           }
         } else if (!isValueAttr && isPureBinding) {
-          // Boolean-like attributes: add or remove based on truthiness
+          // Boolean-like attributes: add or remove based on truthiness.
+          // Compare both presence AND value — initial hydration starts with
+          // the raw `@[...]` binding text as the attribute value, so
+          // `hasAttribute` alone isn't enough to know the canonical state is
+          // already set.
           const expr = isPureBinding[1];
           const value = evalInScope(expr, effectiveState, element);
           if (value) {
-            element.setAttribute(attrName, '');
-          } else {
+            if (element.getAttribute(attrName) !== '') {
+              element.setAttribute(attrName, '');
+            }
+          } else if (element.hasAttribute(attrName)) {
             element.removeAttribute(attrName);
           }
         } else {
@@ -105,7 +112,9 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           const newValue = attrValue.replace(BINDING_REGEX, (_, expr) => {
             return evalInScope(expr, effectiveState, element);
           });
-          element.setAttribute(attrName, newValue);
+          if (element.getAttribute(attrName) !== newValue) {
+            element.setAttribute(attrName, newValue);
+          }
         }
       } catch (e) {}
       return;
@@ -128,11 +137,19 @@ export default (affected, state, manifest = {}, oldState = {}) => {
       });
 
       // If we have a direct reference to the text node, update it specifically
-      // This prevents wiping child elements when parent has both text and element children
+      // This prevents wiping child elements when parent has both text and element children.
+      // Skip the write when the value is already correct — the browser would repaint
+      // (and any in-flight CSS transition on the row would jitter) even when no value
+      // actually changed. Reactivity coverage is unchanged: the only state changes that
+      // hit this path either produce a new value (still applied) or don't (now no-op).
+      // Skip the write when the value is already correct — the browser would
+      // repaint (and any in-flight CSS transition would jitter) even when no
+      // value actually changed. Reactivity coverage is unchanged: state changes
+      // that produce a new value still apply; state changes that don't are now
+      // proper no-ops at the DOM layer.
       if (textNode && textNode.nodeType === 3) {
-        textNode.textContent = toReplace;
-      } else {
-        // Fallback: element has no children or is just a text container
+        if (textNode.textContent !== toReplace) textNode.textContent = toReplace;
+      } else if (element.textContent !== toReplace) {
         element.textContent = toReplace;
       }
     } catch (e) {}