@ape-egg/vibe 1.8.0 → 1.9.0

package/runtime/component.js

@@ -1,5 +1,5 @@
 import { debugLog } from './debug.js';
-import { PHASE_FETCH, DEHYDRATE_CLASS_OR_ATTR } from './constants.js';
+import { PHASE_FETCH, DEHYDRATE_CLASS_OR_ATTR, BINDING_REGEX } from './constants.js';
 import { evalInScope } from './utils.js';
 
 // Deterministic component counter
@@ -16,6 +16,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
 
@@ -89,7 +125,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 +154,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,22 +182,27 @@ 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
+        // Rewrite this.property to componentId.property in siblings.
+        // Handles both reads (@[this.x]) and writes ($.this.x in event handlers)
+        // so component() state is fully accessible from the component's own template.
         const rewriteThisBindings = (element) => {
-          const thisRegex = /@\[this\.(\w+)\]/g;
+          const bindingRegex = /@\[this\.(\w+)\]/g;
+          const writeRegex = /\$\.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]`);
+              node.textContent = node.textContent.replace(bindingRegex, `@[${componentId}.$1]`);
             }
           });
 
-          // Rewrite in attributes
+          // Rewrite in attributes — both @[this.x] bindings and $.this.x in event handlers
           Array.from(element.attributes || []).forEach((attr) => {
             if (attr.value.includes('@[this.')) {
-              attr.value = attr.value.replace(thisRegex, `@[${componentId}.$1]`);
+              attr.value = attr.value.replace(bindingRegex, `@[${componentId}.$1]`);
+            }
+            if (attr.value.includes('$.this.')) {
+              attr.value = attr.value.replace(writeRegex, `$.${componentId}.$1`);
             }
           });
 
@@ -184,11 +212,16 @@ const processSingle = (el, debug) => {
           });
         };
 
+        // Tag siblings with componentId and rewrite this. bindings.
+        // This runs BEFORE script.remove() so nextElementSibling is valid.
+        // For async scripts, componentFn runs later (after removal) and can't
+        // find siblings — so we tag here instead.
         let sibling = script.nextElementSibling;
         while (sibling) {
           if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
             break;
           }
+          sibling.setAttribute('data-vibe-component-id', componentId);
           rewriteThisBindings(sibling);
           sibling = sibling.nextElementSibling;
         }
@@ -202,26 +235,102 @@ const processSingle = (el, debug) => {
         // Get transformed HTML from temp container (scripts removed)
         let transformedHtml = temp.innerHTML;
 
-        // Replace props
+        // Replace props — both exact @[propName] bindings and identifiers
+        // appearing inside larger expressions like @[Math.floor(propName / 100)]
+        // or conditional/iteration comment expressions like <!-- if propName -->.
+        // Matches any <!-- if ... -->, <!-- else if ... -->, or <!-- each ... -->
+        // so prop identifiers resolve there the same way they do inside @[...].
+        const DIRECTIVE_COMMENT_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
+        // Event handler attributes (onclick, oninput, onchange, …). Prop
+        // identifiers inside these are JS expressions that read/write state —
+        // substituting them gives components natural two-way binding:
+        // child writes `$.value = x`, parent passed `value="@[email]"`,
+        // substitution turns it into `$.email = x`.
+        const EVENT_ATTR_REGEX = /\bon(\w+)="([^"]*)"/g;
+
         Object.entries(props).forEach(([propName, propValue]) => {
           const bindingMatch = propValue.match(/^@\[(.+)\]$/);
+          const exactPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
+          // Word-boundary identifier match for substitution inside expressions.
+          // The lookbehind also excludes `.` so property accesses like `_c0.email`
+          // aren't double-substituted when the prop name is `email` — only
+          // standalone identifiers match, not property tails.
+          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) {
-            // Reactive prop: replace @[propName] with @[path]
+            // Reactive prop: @[propName] → @[path], identifiers inside expressions → (path)
             const path = bindingMatch[1];
-            const propPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
-            transformedHtml = transformedHtml.replace(propPattern, `@[${path}]`);
+            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} -->`;
+              }
+            );
+            // Event handlers: rewrite `$.propName` → `$.path` for two-way
+            // binding. Only targets state access (`$.xxx`) so DOM properties
+            // like `this.value` stay untouched.
+            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 {
-            // Static prop: replace @[propName] with literal value
-            const propPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
-            transformedHtml = transformedHtml.replace(propPattern, propValue);
+            // Static prop: @[propName] → literal value (raw),
+            // identifiers inside expressions → JS literal.
+            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} -->`;
+              }
+            );
+            // Event handlers: rewrite `$.propName` → `$.literal` for static props
+            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}"`;
+            });
           }
         });
 
-        // Replace <slot></slot> with children
+        // Replace <slot> with children wrapped in <slot> boundary.
+        // Allow attributes on the slot (e.g. data-vibe-component-id added by
+        // sibling tagging when a <slot> happens to be a direct sibling of the
+        // component's <script>).
         if (children) {
-          transformedHtml = transformedHtml.replace(/<slot><\/slot>/g, children);
-          transformedHtml = transformedHtml.replace(/<slot\s*\/>/g, 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>`
+          );
         }
 
         // Clean up pending fetch tracker
@@ -286,7 +395,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 +408,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+/;

package/runtime/index.js

@@ -21,9 +21,10 @@ import {
   PHASE_READY,
   DEHYDRATE_CLASS_OR_ATTR,
 } from './constants.js';
-import { processComponent, abortComponentFetch } from './component.js';
+import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState } from './component.js';
 import { debugLog } from './debug.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
+import { reconcile } from './reconcile.js';
 import {
   buildHyperspeedManifest,
   hyperspeedManifest,
@@ -617,6 +618,22 @@ const main = (s, config = {}, stringSelector = '') => {
     enumerable: false,
   });
 
+  // Promise that resolves after the ready hook fires and all ready callbacks
+  // have run. Lets late subscribers await readiness without missing the event:
+  // `await $.ready`. Non-enumerable so it won't leak into state snapshots.
+  let resolveReady;
+  Object.defineProperty($, 'ready', {
+    value: new Promise((resolve) => { resolveReady = resolve; }),
+    enumerable: false,
+  });
+
+  // Reconcile a managed subtree against new source HTML. Opt-in entry point;
+  // dormant unless called (so hot paths and benchmarks are unaffected).
+  Object.defineProperty($, 'reconcile', {
+    value: reconcile,
+    enumerable: false,
+  });
+
   // Initial hydration - pass plain values so iteration can do reference comparison
   const initialState = extractPlainValue($);
   const affectedElements = affected(parsedTree, initialState, initialState);
@@ -696,6 +713,14 @@ const main = (s, config = {}, stringSelector = '') => {
     let evaluatedCount = 0;
     let addedElementsList = []; // Track all added elements for verbose output
 
+    // Collect data-vibe-component-id values across ALL removed subtrees in this
+    // batch before doing any per-node work, so we can evict their state after
+    // the DOM mutations have been applied.
+    const removedComponentIds = new Set();
+    mutations.forEach(({ removedNodes: removedNodesList }) => {
+      removedNodesList.forEach((node) => collectComponentIds(node, removedComponentIds));
+    });
+
     mutations.forEach(({ addedNodes: addedNodesList, removedNodes: removedNodesList, target }) => {
       removedNodesList.forEach((node) => {
         // If this is a component element with pending fetch, abort it
@@ -761,29 +786,20 @@ const main = (s, config = {}, stringSelector = '') => {
           return;
         }
 
-        const entry = Object.entries(manifest).find(([_, element]) => element === target);
-
-        // If parent isn't tracked, this node is outside the reactive scope
-        if (!entry) return;
-
-        const [dotAnnotation] = entry;
-        const picked = navigateTree(parsedTree, dotAnnotation);
-
-        // If we can't navigate to the parent in the tree, skip
-        if (!picked) return;
-
-        // If parent has no element reference, re-parse from the actual DOM element
-        if (!picked.element) {
-          picked.element = target;
+        // Capture raw slot content of nested <component src> elements BEFORE parse runs.
+        // Parse creates conditional nodes from <!-- if --> comments, and renderConditional
+        // later removes the template nodes between the comments. Without capturing slot
+        // content first, conditionals inside a component's slot content lose their branch
+        // templates, breaking reactive updates.
+        if (node.nodeType === 1) {
+          node.querySelectorAll('component[src], div.component[src]').forEach((el) => {
+            if (el._vibeSlotContent === undefined) el._vibeSlotContent = el.innerHTML;
+          });
         }
 
-        // Parse the newly added node (use monotonically increasing counter for deterministic key)
-        // Initialize counter if it doesn't exist
-        if (!picked._nextChildIndex) {
-          picked._nextChildIndex = Object.keys(picked.children).length;
-        }
-        const name = `${node.nodeName.toLowerCase()}_${picked._nextChildIndex}`;
-        picked._nextChildIndex++; // Always increment, never decrement
+        const entry = Object.entries(manifest).find(([_, element]) => element === target);
+
+        // Parse the newly added node
         const parsedNode = parse(node);
 
         // Accumulate skipped stats
@@ -791,19 +807,42 @@ const main = (s, config = {}, stringSelector = '') => {
           totalSkipped += parsedNode.stats.skipped;
         }
 
-        // Update parent's parsed HTML (only once per parent)
-        if (!parsedParents) parsedParents = new Set();
-        if (!parsedParents.has(picked)) {
-          const { parsed } = parse(picked.element);
-          picked.parsed = parsed;
-          parsedParents.add(picked);
-        }
+        // If parent is tracked in the manifest, register this new node in the parsed tree.
+        // (If not — e.g. mutations inside an iteration instance whose rows aren't in the
+        // global manifest — we still hydrate the node below; we just skip tree/manifest
+        // registration since there's no tree branch to attach to.)
+        if (entry) {
+          const [dotAnnotation] = entry;
+          const picked = navigateTree(parsedTree, dotAnnotation);
+
+          if (picked) {
+            if (!picked.element) {
+              picked.element = target;
+            }
+
+            // Parse the newly added node (use monotonically increasing counter for deterministic key)
+            // Initialize counter if it doesn't exist
+            if (!picked._nextChildIndex) {
+              picked._nextChildIndex = Object.keys(picked.children).length;
+            }
+            const name = `${node.nodeName.toLowerCase()}_${picked._nextChildIndex}`;
+            picked._nextChildIndex++; // Always increment, never decrement
+
+            // Update parent's parsed HTML (only once per parent)
+            if (!parsedParents) parsedParents = new Set();
+            if (!parsedParents.has(picked)) {
+              const { parsed } = parse(picked.element);
+              picked.parsed = parsed;
+              parsedParents.add(picked);
+            }
 
-        // Add the parsed node to parent's children
-        picked.children[name] = parsedNode;
+            // Add the parsed node to parent's children
+            picked.children[name] = parsedNode;
 
-        // Recursively add node and all descendants to manifest
-        addToManifest(parsedNode, manifest, `${dotAnnotation}.${name}`);
+            // Recursively add node and all descendants to manifest
+            addToManifest(parsedNode, manifest, `${dotAnnotation}.${name}`);
+          }
+        }
 
         // Run core loop for the new node (parse already done, hydrate → conditionals → iterate)
         const counts = processCoreLoop(node, parsedNode, $, manifest, true, debug);
@@ -823,6 +862,9 @@ const main = (s, config = {}, stringSelector = '') => {
       });
     });
 
+    // CLEANUP OF CURRENT STATE
+    releaseOrphanedComponentState(removedComponentIds);
+
     // Fire hooks once after all mutations are processed (not per-node)
     if (hadChanges) {
       if (addedElements > 0 || addedNodes > 0 || removedElements > 0 || removedNodes > 0) {
@@ -1019,6 +1061,8 @@ const main = (s, config = {}, stringSelector = '') => {
           console.error('[vibe] Error in ready hook:', error);
         }
       });
+      // Resolve $.ready promise after all ready callbacks have run
+      resolveReady();
     }
   };