@ape-egg/vibe 1.9.0 → 1.9.5

package/runtime/component.js

@@ -1,5 +1,11 @@
 import { debugLog } from './debug.js';
-import { PHASE_FETCH, DEHYDRATE_CLASS_OR_ATTR, BINDING_REGEX } 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
@@ -35,9 +41,49 @@ export const releaseOrphanedComponentState = (collectedIds) => {
     delete window.__vibeComponents?.[id];
     // CLEANUP OF CURRENT STATE
     delete window.$[id];
+    runComponentCleanups(id);
   }
 };
 
+// Listener registry: maps componentId → array of unsubscribe callbacks
+// returned from `$.on(...)` calls inside the component's `<script>`.
+// Re-running a script for the same id (HMR remount with reused ids) or
+// unmounting the component fires the callbacks so the previous evaluation's
+// listeners don't accumulate alongside fresh registrations.
+export const runComponentCleanups = (componentId) => {
+  const cleanups = window.__vibeComponentCleanups?.[componentId];
+  if (!cleanups) return;
+  for (let i = 0; i < cleanups.length; i++) cleanups[i]();
+  delete window.__vibeComponentCleanups[componentId];
+};
+
+// Per-script `$` Proxy. Bare `$` references in a component's <script> resolve
+// to this Proxy (the function parameter shadows the global), so every
+// `$.on(...)` registration is automatically attributed to `componentId` via
+// the closure — no global flag, async-safe across `await` boundaries because
+// the closure binds the id, not a shared variable.
+const createScopedDollar = (componentId) => {
+  const dollar = window.$;
+  if (!dollar) return dollar;
+  return new Proxy(dollar, {
+    get(target, prop, receiver) {
+      if (prop === 'on') {
+        return (event, callback) => {
+          const unsub = target.on(event, callback);
+          if (!window.__vibeComponentCleanups) window.__vibeComponentCleanups = {};
+          const slot = window.__vibeComponentCleanups[componentId] || (window.__vibeComponentCleanups[componentId] = []);
+          slot.push(unsub);
+          return unsub;
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+    set(target, prop, value, receiver) {
+      return Reflect.set(target, prop, value, receiver);
+    },
+  });
+};
+
 // 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()) => {
@@ -79,6 +125,168 @@ 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;
+
+  // HTML's parser lowercases attribute names, so a consumer-written
+  // `<component dndDisabled>` arrives here with propName `dnddisabled` while
+  // the component template author wrote `dndDisabled`. Match identifiers and
+  // bindings case-insensitively so both sides line up. Word-boundary
+  // lookbehind/lookahead still hold (they're case-agnostic), so
+  // `dnddisabled` won't bleed into `dndDisabledAlt`.
+  Object.entries(props).forEach(([propName, propValue]) => {
+    const bindingMatch = propValue.match(/^@\[(.+)\]$/);
+    const exactPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'gi');
+    const idRegex = new RegExp(
+      `(?<![a-zA-Z0-9_$\\.])${escapeRegex(propName)}(?![a-zA-Z0-9_$])`,
+      'gi'
+    );
+
+    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_$])`, 'gi');
+      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_$])`, 'gi');
+      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
@@ -119,6 +327,21 @@ const processSingle = (el, debug) => {
       // Process each script — collect async tasks if any have imports
       const asyncTasks = [];
 
+      // Track every componentId registered during this fetch. If the host
+      // element is detached before finalize runs (e.g. a conditional unmounted
+      // mid-fetch, or the user navigated away), we release these state
+      // buckets — otherwise component({...}) leaks state to `$` for DOM that
+      // never reaches the document.
+      const registeredComponentIds = [];
+
+      // First componentId encountered — applied to the wrapper itself so
+      // directives living between top-level sibling roots (e.g. a comment
+      // marker for `<!-- if this.X -->`) can resolve component scope via
+      // closest('[data-vibe-component-id]'). Without this, multi-root
+      // templates have scope-less wrappers and top-level `this.` references
+      // fall through to global state.
+      let firstComponentId = null;
+
       for (const script of moduleScripts) {
         let scriptContent = script.textContent?.trim() || '';
         if (!scriptContent) continue;
@@ -135,7 +358,11 @@ const processSingle = (el, debug) => {
 
         if (hasImports) {
           // Rewrite remaining imports to dynamic await import()
-          // Order matters: default → named → namespace → side-effect (most specific first)
+          // Order matters: combined → default → named → namespace → side-effect (most specific first)
+          scriptContent = scriptContent.replace(
+            /import\s+(\w+)\s*,\s*\{([^}]+)\}\s+from\s+(['"][^'"]+['"])\s*;?/g,
+            'const __m_$1 = await import($3); const $1 = __m_$1.default; const {$2} = __m_$1;'
+          );
           scriptContent = scriptContent.replace(
             /import\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?/g,
             'const $1 = (await import($2)).default;'
@@ -158,6 +385,8 @@ const processSingle = (el, debug) => {
         const reuseIds = el._vibeReuseComponentIds;
         const componentId = reuseIds && reuseIds.length ? reuseIds.shift() : generateComponentId();
 
+        if (firstComponentId === null) firstComponentId = componentId;
+
         // 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.
@@ -165,66 +394,43 @@ const processSingle = (el, debug) => {
           if (!window.__vibeComponents) window.__vibeComponents = {};
           window.__vibeComponents[componentId] = state;
           if (window.$) window.$[componentId] = state;
+          if (!registeredComponentIds.includes(componentId)) {
+            registeredComponentIds.push(componentId);
+          }
         };
 
+        // Re-running the script for a reused componentId (HMR remount) must
+        // tear down listeners from the previous evaluation before the fresh
+        // script registers new ones. Without this, every cycle stacks another
+        // listener on top of the stale closures and a single reactive tick
+        // fires N callbacks instead of one.
+        runComponentCleanups(componentId);
+
+        // Provide a per-script `$` whose `.on(...)` registers cleanups under
+        // this componentId. Bare `$` in the script body resolves to this
+        // Proxy (the function parameter shadows the global), so listener
+        // registrations are auto-tracked across `await` boundaries via the
+        // closure — no opt-in required.
+        const scopedDollar = createScopedDollar(componentId);
+
         // Execute script with component() function in scope
         try {
           if (hasImports) {
             // Async execution for scripts with imports
             const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
-            asyncTasks.push(new AsyncFunction('component', scriptContent)(componentFn));
+            asyncTasks.push(new AsyncFunction('$', 'component', scriptContent)(scopedDollar, componentFn));
           } else {
             // Synchronous execution for scripts without imports (preserves boot timing)
-            const executeFn = new Function('component', scriptContent);
-            executeFn(componentFn);
+            const executeFn = new Function('$', 'component', scriptContent);
+            executeFn(scopedDollar, componentFn);
           }
         } catch (e) {
           console.warn('[vibe] Failed to execute component script:', e);
         }
 
-        // 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 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(bindingRegex, `@[${componentId}.$1]`);
-            }
-          });
-
-          // 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(bindingRegex, `@[${componentId}.$1]`);
-            }
-            if (attr.value.includes('$.this.')) {
-              attr.value = attr.value.replace(writeRegex, `$.${componentId}.$1`);
-            }
-          });
-
-          // Recurse into children
-          Array.from(element.children).forEach((child) => {
-            rewriteThisBindings(child);
-          });
-        };
-
-        // 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;
-        }
+        // 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();
@@ -232,106 +438,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 — 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: @[propName] → @[path], identifiers inside expressions → (path)
-            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} -->`;
-              }
-            );
-            // 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: @[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> 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(\s[^>]*)?>\s*<\/slot>/g,
-            (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
-          );
-          transformedHtml = transformedHtml.replace(
-            /<slot(\s[^>]*)?\/>/g,
-            (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
-          );
-        }
+        // Delegate prop substitution + slot inlining to shared helper.
+        const transformedHtml = renderPropsAndSlot(temp, props, children);
 
         // Clean up pending fetch tracker
         pendingFetches.delete(el);
@@ -350,12 +458,58 @@ const processSingle = (el, debug) => {
           }
 
           newWrapper.innerHTML = transformedHtml;
+          if (firstComponentId !== null) {
+            newWrapper.setAttribute('data-vibe-component-id', firstComponentId);
+          }
+          // 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');
+          }
+          // Transfer the original prop expressions too, so the iteration's
+          // update path can re-evaluate them against the row's new scope and
+          // refresh the registry slots in place — letting the inlined
+          // component's bindings react without rebuilding the row's DOM.
+          if (el._vibeIterPropExprs) {
+            newWrapper._vibeIterPropExprs = el._vibeIterPropExprs;
+            el._vibeIterPropExprs = null;
+          }
+          // Back-pointer from the soon-to-be-detached `<component src>` to
+          // the new wrapper. The iteration's `instance.clonedNodes` still
+          // references the original element; follow this link to reach the
+          // live wrapper when refreshing registry slots / re-hydrating.
+          // The wrapper's `_vibeIterTree` (set later by processMutations after
+          // renderAllConditionals/Iterations populated runtime data) is what
+          // iterate.js's update path uses to re-evaluate inlined bindings on
+          // each row update.
+          el._vibeReplacedBy = newWrapper;
           el.replaceWith(newWrapper);
           debugLog(PHASE_FETCH, src, debug);
 
           // MutationObserver handles parsing and hydrating the new content.
           // Branch nodes are registered in the manifest by mountBranch,
           // so the observer can find parents even inside conditional branches.
+        } else {
+          // Element was detached before finalize ran (conditional unmounted
+          // during fetch, parent removed, etc). Release any state component()
+          // calls registered — otherwise it leaks on `$` forever.
+          for (const id of registeredComponentIds) {
+            delete window.__vibeComponents?.[id];
+            if (window.$) delete window.$[id];
+          }
         }
       };
 

package/runtime/conditionals.js

@@ -1,7 +1,7 @@
 import parse from './parse.js';
 import affected from './affected.js';
 import hydrate from './hydrate.js';
-import { createScopedState, renderAllIterations, initializeBlock } from './iterate.js';
+import { createScopedState, renderAllIterations, initializeBlock, resolveIterationComponentProps } from './iterate.js';
 import { evalInScope } from './utils.js';
 import { collectComponentIds, releaseOrphanedComponentState } from './component.js';
 
@@ -98,6 +98,16 @@ export const renderAllConditionals = (tree, state, manifest, parentScope = {}) =
 export const renderConditional = (node, state, manifest, parentScope = {}) => {
   const { expression, startComment, endComment, branches } = node.meta;
 
+  // Mark conditionals that live inside an iteration row so update-time branch
+  // flips can route `<component src>` props through the iteration-prop
+  // registry. Skipping this for top-level conditionals keeps their props as
+  // live `@[stateKey]` bindings — which is what global state-change reactivity
+  // depends on (the registry path snapshots a value and doesn't react to
+  // global state changes on its own).
+  if (Object.keys(parentScope).length > 0) {
+    node.runtime.inIteration = true;
+  }
+
   // Check if already rendered (using marker on comment node)
   // @ts-ignore - adding custom property to comment node
   if (startComment.__vibeRendered) {
@@ -158,12 +168,29 @@ const mountBranch = (node, branchData, state, manifest, parentScope) => {
   const scopedState =
     Object.keys(parentScope).length > 0 ? createScopedState(state, parentScope) : state;
 
-  // Initialize block (clone, parse, hydrate)
+  // Initialize block (clone, parse, hydrate). Pass the enclosing loop aliases so
+  // the re-parse rewrites loop-scoped handlers in this branch — including ones
+  // nested deeper in further conditionals, which the parser reaches by carrying
+  // the alias set down. `scopeAliases` is set at parse time and persists, so this
+  // works on both the initial-render and update (hydrate) mount paths.
+  const aliasSet = node.meta.scopeAliases?.length ? new Set(node.meta.scopeAliases) : undefined;
   const {
     element: firstElement,
     tree: branchTree,
     clonedNodes,
-  } = initializeBlock(templateContent, scopedState);
+  } = initializeBlock(templateContent, scopedState, null, null, aliasSet);
+
+  // For conditionals living inside an iteration, route any `<component src>`
+  // props through the iteration-prop registry against the active scopedState
+  // (which carries the iteration's local vars). Without this, processSingle
+  // would inline `@[item.x]` bindings into the component template, where
+  // `item` isn't reachable in global scope and props resolve to undefined.
+  // Skipped for top-level conditionals because their props reference live
+  // global-state bindings — going through the registry would snapshot the
+  // value and break reactivity.
+  if (node.runtime.inIteration) {
+    resolveIterationComponentProps(clonedNodes, scopedState);
+  }
 
   // Insert cloned nodes into DOM and register in branch registry
   clonedNodes.forEach((clonedNode, i) => {
@@ -172,6 +199,21 @@ const mountBranch = (node, branchData, state, manifest, parentScope) => {
     if (clonedNode.nodeType === 1) managedNodes.add(clonedNode);
   });
 
+  // Branch content is mounted outside the enclosing iteration instance's
+  // clonedNodes, so it doesn't inherit the instance's `__vibeScope` stamp by DOM
+  // ancestry. When this conditional lives inside a loop, stamp `scopedState` —
+  // the same scope that hydrates the branch's `@[alias.x]` bindings — onto the
+  // branch's root elements so loop-scoped `$scope(this,'alias')` handlers resolve.
+  // Gate on `scopeAliases` (set at parse time, persists) rather than the runtime
+  // parentScope/inIteration, because the update path (hydrate -> updateConditional)
+  // and deeper-nested conditionals mount with an empty parentScope yet still flow
+  // the iteration's scoped state in as `state`.
+  if (node.meta.scopeAliases?.length) {
+    for (let i = 0; i < clonedNodes.length; i++) {
+      if (clonedNodes[i].nodeType === 1) clonedNodes[i].__vibeScope = scopedState;
+    }
+  }
+
   // Integrate branch tree into the conditional node's children and manifest.
   // This makes branch content visible to the main update loop (hydrate,
   // renderAllConditionals, renderAllIterations) and to MutationObserver

package/runtime/constants.js

@@ -210,11 +210,18 @@ 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 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 parsing iteration comment syntax. Supported forms:
+//   <!-- each items as item -->
+//   <!-- each items as item, index -->
+//   <!-- each items as item (item.id) -->                // explicit key
+//   <!-- each items as item (item.id), index -->         // key + index
+// Capture groups: arrayPath, itemAlias, keyExpr (optional), indexAlias (optional).
+// The array expression can be any JS: a state path, a window global, a method
+// call, or an inline literal. The optional key expression is evaluated per
+// item against scoped state to produce a stable identity for diffing — this
+// keeps survivors stable when earlier items are removed (otherwise the
+// fallback hash key embeds the index and triggers bulk re-render).
+export const ITERATION_REGEX = /^each\s+(.+)\s+as\s+(\w+)(?:\s*\(\s*([^)]+?)\s*\))?(?:\s*,\s*(\w+))?\s*$/;
 
 // Regex for detecting start of iteration comment
 export const ITERATION_START_REGEX = /^each\s+/;
@@ -224,3 +231,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;