@ape-egg/vibe 1.9.1 → 1.9.5

package/runtime/iterate.js

@@ -2,9 +2,16 @@ import parse from './parse.js';
 import affected from './affected.js';
 import hydrate from './hydrate.js';
 import { resolvePath, getItemKey, computeDiff } from './iteration-utils.js';
-import { resolveThisPath, evalInScope } from './utils.js';
+import { resolveThisPath, evalInScope, findComponentIdForElement } from './utils.js';
 import { managedNodes } from './conditionals.js';
-import { BINDING_REGEX } from './constants.js';
+import { stampInstanceScopes } from './loop-scope.js';
+import {
+  BINDING_REGEX,
+  PURE_BINDING_REGEX,
+  VALUE_ATTRS,
+  DOM_PROPERTIES,
+  THIS_PROP_REGEX,
+} from './constants.js';
 
 // Pre-compiled iteration optimization (production)
 import * as compiled from './pre-compiled-iterations.js';
@@ -13,6 +20,12 @@ import * as compiled from './pre-compiled-iterations.js';
 // Build an HTML string via template-literal compilation, then parse once —
 // avoids per-item clone/parse/hydrate in the hot path.
 // Only used for templates without nested <!-- each --> / <!-- if -->.
+//
+// Invariant: batch produces identical DOM to the clone+hydrate path for any
+// input. New binding forms must be supported in both paths simultaneously,
+// with equivalence tests under tests/e2e/batch-vs-clone-equivalence.spec.js
+// — the test harness flips a force-clone flag and compares region-by-region,
+// so silent divergence between the two paths fails loudly.
 const batchParseTemplate = document.createElement('template');
 
 // innerHTML serialization encodes <, >, &, ", ' inside attribute values.
@@ -43,20 +56,198 @@ const hasNestedStructures = (tree) => {
 const hasComponentSrc = (templateEl) =>
   !!templateEl.querySelector?.('component[src], div.component[src]');
 
+// `__vibeForceClonePath` is a debug/test escape hatch — set it on globalThis to
+// route every iteration through the clone+hydrate path, even templates that
+// would otherwise qualify for batch. Used by the batch-vs-clone-equivalence
+// test harness so the same templates can be rendered through both paths and
+// compared. Not part of the public API.
 const canUseBatchRender = (template) =>
+  !globalThis.__vibeForceClonePath &&
   !hasNestedStructures(template) &&
   template.element.children.length <= 1 &&
   !hasComponentSrc(template.element);
 
-const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
-  const templateHtml = template.element.innerHTML.trim();
-  const escaped = templateHtml.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
-  const code = escaped.replace(BINDING_REGEX, (_, expr) => '${' + decodeEntities(expr) + '}');
+// Patterns used by compileBatchFn to recognize bindings in attribute-name and
+// attribute-value positions. The inner alternation mirrors BINDING_INNER from
+// constants.js — it has to allow nested brackets and quoted strings inside the
+// expression so things like `items[0]` or `x.replace(',', '')` round-trip
+// safely. Kept inline rather than re-exported because they live entirely
+// within this compile-time string transformation.
+const BATCH_BINDING_INNER = String.raw`(?:[^\[\]'"]|\[[^\]]*\]|'[^']*'|"[^"]*")+`;
+// Note: lookahead allows `=` because innerHTML serializes a bare attribute
+// name (no value) as `name=""`, so a name-binding written `<icon @[attrName]>`
+// arrives here as `@[attrname]=""`. The leading `\s` keeps this from matching
+// attribute-value bindings like `attr="@[x]"` (preceded by `"`, not whitespace).
+const BATCH_NAME_BINDING_REGEX = new RegExp(
+  String.raw`(\s)@\[(${BATCH_BINDING_INNER})\](?:="")?(?=[\s/>])`,
+  'g',
+);
+const BATCH_ATTR_BINDING_REGEX = new RegExp(
+  String.raw`(\s)([\w-]+)="@\[(${BATCH_BINDING_INNER})\]"`,
+  'g',
+);
+
+// Whether a hydrate'd attribute is a "value-style" string attr (kept verbatim)
+// rather than a boolean-coerced attr (added/removed by truthiness). Mirrors
+// the predicate hydrate.js uses, so batch and clone classify identically.
+const isValueStyleAttr = (attrName) =>
+  VALUE_ATTRS.includes(attrName) ||
+  attrName.startsWith('data-') ||
+  attrName.startsWith('aria-') ||
+  attrName.startsWith('on');
+
+// Compile the iteration template into a single function that emits the full
+// HTML for any input array. The function produced here must match the DOM
+// shape of the clone+hydrate path for any binding form — gaps documented in
+// the prior iteration of `do-this-job.md` were closed here:
+//
+//   1. `this.X` rewriting: pre-rewritten at compile time using the iteration's
+//      anchor element to resolve the owning componentId. No per-item cost.
+//   2. Boolean-coerced attributes: emitted as conditional template literal
+//      expressions so the attribute is absent when the binding evaluates falsy
+//      and present (with empty string value, matching hydrate.js) when truthy.
+//   3. DOM properties (value/checked/selected): emitted as attributes for
+//      runtime DOM accuracy AND collected into `domPropertyWrites` so
+//      renderBatch can run a small post-stamp loop that sets the actual DOM
+//      property on each instance — the attribute alone isn't enough.
+//   4. Name bindings (`<el @[expr]>`): emitted as conditional template literal
+//      expressions that produce ` resolvedName=""` when truthy and nothing
+//      when falsy.
+//
+// Anything the clone path renders correctly, the function returned here has
+// to render identically. New binding forms must update both paths in lockstep
+// or the equivalence harness in tests/e2e/batch-vs-clone-equivalence.spec.js
+// will catch the divergence.
+const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, anchorEl) => {
+  // Walk a clone of the template DOM so we can stash a transient
+  // `data-vibe-batch` marker on every element with DOM-property bindings
+  // without polluting the cached template that subsequent renders read.
+  const tplClone = template.element.cloneNode(true);
+  const componentId = anchorEl ? findComponentIdForElement(anchorEl) : null;
+  const domPropertyWrites = [];
+
+  const allEls = tplClone.querySelectorAll('*');
+  for (let n = 0; n < allEls.length; n++) {
+    const el = allEls[n];
+    const indexes = [];
+    const attrs = [...el.attributes];
+    for (let a = 0; a < attrs.length; a++) {
+      const attr = attrs[a];
+      if (!DOM_PROPERTIES.includes(attr.name)) continue;
+      const m = attr.value.match(PURE_BINDING_REGEX);
+      if (!m) continue;
+      let expr = m[1];
+      if (componentId) expr = expr.replace(THIS_PROP_REGEX, `$['${componentId}'].$1`);
+      indexes.push(domPropertyWrites.length);
+      domPropertyWrites.push({ prop: attr.name, expr });
+    }
+    if (indexes.length > 0) {
+      el.setAttribute('data-vibe-batch', indexes.join(','));
+    }
+  }
+
+  let templateHtml = tplClone.innerHTML.trim();
+
+  // Rewrite `this.X` only inside @[…] expressions so literal occurrences in
+  // text content (e.g. a code example explaining `this.foo`) aren't mangled.
+  // Mirrors evalInScope's behavior in the clone path.
+  if (componentId) {
+    BINDING_REGEX.lastIndex = 0;
+    templateHtml = templateHtml.replace(BINDING_REGEX, (_, expr) =>
+      '@[' + expr.replace(THIS_PROP_REGEX, `$['${componentId}'].$1`) + ']',
+    );
+  }
 
-  return new Function(
+  const escaped = templateHtml
+    .replace(/\\/g, '\\\\')
+    .replace(/`/g, '\\`')
+    .replace(/\$\{/g, '\\${');
+
+  let code = escaped;
+
+  // Name bindings: `<el @[expr]>` — emit ` resolvedName=""` when truthy, else
+  // emit nothing. The lookahead `(?=[\s/>])` distinguishes name-position
+  // bindings from attribute-value-position bindings (which are followed by `=`).
+  //
+  // HTML parses attribute names lowercase, so a binding like
+  // `<icon @[attrName]>` arrives here as `@[attrname]` and a dotted form like
+  // `<icon @[obj.iconName]>` arrives as `@[obj.iconname]`. We recover the
+  // proper case in two places:
+  //   - Single identifier → resolve against `stateKeys` at compile time and
+  //     emit a direct identifier reference.
+  //   - Dotted path → split off the first segment (resolved at compile time
+  //     against `stateKeys` + iteration aliases), then emit a runtime call to
+  //     `_walkCi` (injected into the function body below) for the remaining
+  //     segments. Mirrors `resolveCaseInsensitivePath` from utils.js.
+  // Bracket / call expressions pass through unchanged — they need a real
+  // evaluator and aren't worth special-casing here.
+  let needsCiWalker = false;
+  code = code.replace(BATCH_NAME_BINDING_REGEX, (_, _ws, expr) => {
+    let decExpr = decodeEntities(expr);
+    if (decExpr.includes('[') || decExpr.includes('(')) {
+      return '${(' + decExpr + ') ? \' \' + (' + decExpr + ') + \'=""\' : \'\'}';
+    }
+    const dot = decExpr.indexOf('.');
+    if (dot === -1) {
+      const ci = stateKeys.find((k) => k.toLowerCase() === decExpr.toLowerCase());
+      if (ci) decExpr = ci;
+      return '${(' + decExpr + ') ? \' \' + (' + decExpr + ') + \'=""\' : \'\'}';
+    }
+    const head = decExpr.slice(0, dot);
+    const tail = decExpr.slice(dot + 1).split('.');
+    const knownNames = [itemAlias, indexAlias, ...stateKeys];
+    const ciHead = knownNames.find((k) => k.toLowerCase() === head.toLowerCase()) || head;
+    const tailJSON = JSON.stringify(tail);
+    needsCiWalker = true;
+    return (
+      '${(()=>{const _v=_walkCi(' + ciHead + ',' + tailJSON +
+      ');return _v?\' \'+_v+\'=""\':\'\';})()}'
+    );
+  });
+
+  // Pure-binding attributes (`attr="@[expr]"`) — classify by attribute name:
+  //   DOM property  → emit attribute (post-stamp also writes the property)
+  //   value-style   → emit attribute as-is
+  //   boolean-coerced → emit conditional ` attr=""` so the attribute is
+  //                     absent when expr is falsy
+  code = code.replace(BATCH_ATTR_BINDING_REGEX, (_, _ws, attrName, expr) => {
+    const decExpr = decodeEntities(expr);
+    if (DOM_PROPERTIES.includes(attrName) || isValueStyleAttr(attrName)) {
+      return ' ' + attrName + '="${' + decExpr + '}"';
+    }
+    return '${(' + decExpr + ') ? \' ' + attrName + '=""\' : \'\'}';
+  });
+
+  // Remaining @[…] markers — text content and partial-binding attribute
+  // values like `href="/items/@[id]/edit"`.
+  code = code.replace(BINDING_REGEX, (_, expr) => '${' + decodeEntities(expr) + '}');
+
+  // `$` is supplied as the last parameter so component-scoped expressions like
+  // `$['_c0'].chosen` (produced by the this.X rewrite above) can resolve
+  // against the live state. Mirrors evalInScope, which also exposes `$`.
+  // `_walkCi` is only emitted when at least one dotted-path name binding was
+  // rewritten above — keeps the function body free of dead code for the
+  // common no-name-binding case.
+  const ciWalkerSrc = needsCiWalker
+    ? `const _walkCi = (cur, segs) => {
+        for (let i = 0; i < segs.length; i++) {
+          if (cur == null) return undefined;
+          const s = segs[i];
+          if (Reflect.has(Object(cur), s)) { cur = cur[s]; continue; }
+          if (typeof cur !== 'object') return undefined;
+          const k = Object.keys(cur).find((k) => k.toLowerCase() === s.toLowerCase());
+          if (!k) return undefined;
+          cur = cur[k];
+        }
+        return cur;
+      };`
+    : '';
+  const fn = new Function(
     'arr',
     ...stateKeys,
+    '$',
     `
+      ${ciWalkerSrc}
       let html = '';
       const len = arr.length;
       for (let ${indexAlias} = 0; ${indexAlias} < len; ${indexAlias}++) {
@@ -66,6 +257,8 @@ const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
       return html;
     `,
   );
+
+  return { fn, domPropertyWrites };
 };
 
 // Registry for non-primitive iteration prop snapshots. Lives on `window` (not
@@ -98,12 +291,13 @@ export const releaseOrphanedIterationProps = (nodes) => {
 };
 
 // For <component src> elements inside an iteration instance, evaluate any
-// `@[expr]` attribute bindings against the iteration's scoped state and replace
-// them with the resolved value. Primitives stringify into the attribute as
-// before. Non-primitives (objects, arrays) snapshot into the registry and the
-// attribute becomes a binding into that slot — preserving live object/array
-// access for the child component's template (`@[prop.x]`,
-// `<!-- each prop as item -->`, etc.).
+// `@[expr]` attribute bindings against the iteration's scoped state and route
+// every resolved value through the global iteration-prop registry. The prop
+// attribute becomes `@[window.__vibeIterProps._pN]` — a live binding into the
+// registry slot — for both primitives and objects. The original expression is
+// stashed on the element so the iteration's update path can re-evaluate it
+// against the new scope and refresh the slot, propagating the change into the
+// inlined component's bindings without rebuilding the row's DOM.
 //
 // Component[src] attributes intentionally bypass hydrate (parse.js) so they
 // reach processComponent as bindings — but bindings that depend on
@@ -111,7 +305,7 @@ export const releaseOrphanedIterationProps = (nodes) => {
 // inlines the component, since by then iteration scope is gone. Only called
 // from iteration code paths; conditionals don't need this because their branch
 // content is registered in the global manifest and reacts to state updates.
-const resolveIterationComponentProps = (nodes, scopedState) => {
+export const resolveIterationComponentProps = (nodes, scopedState) => {
   for (let n = 0; n < nodes.length; n++) {
     const node = nodes[n];
     if (node.nodeType !== 1) continue;
@@ -126,19 +320,17 @@ const resolveIterationComponentProps = (nodes, scopedState) => {
         if (attr.name === 'src') continue;
         const match = attr.value.match(/^@\[(.+)\]$/);
         if (!match) continue;
+        const expr = match[1];
         try {
-          const value = evalInScope(match[1], scopedState, el);
+          const value = evalInScope(expr, scopedState, el);
           if (value === undefined) continue;
-          if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
-            el.setAttribute(attr.name, String(value));
-          } else {
-            const registry = ensureIterPropsRegistry();
-            const id = `_p${__vibeIterPropCounter++}`;
-            registry[id] = value;
-            el.setAttribute(attr.name, `@[window.__vibeIterProps.${id}]`);
-            el.setAttribute('data-vibe-iter-prop', '');
-            (el._vibeIterPropIds = el._vibeIterPropIds || []).push(id);
-          }
+          const registry = ensureIterPropsRegistry();
+          const id = `_p${__vibeIterPropCounter++}`;
+          registry[id] = value;
+          el.setAttribute(attr.name, `@[window.__vibeIterProps.${id}]`);
+          el.setAttribute('data-vibe-iter-prop', '');
+          (el._vibeIterPropIds = el._vibeIterPropIds || []).push(id);
+          (el._vibeIterPropExprs = el._vibeIterPropExprs || []).push({ id, attrName: attr.name, expr });
         } catch {
           // Leave binding raw — processComponent will handle it as a binding
         }
@@ -147,18 +339,160 @@ const resolveIterationComponentProps = (nodes, scopedState) => {
   }
 };
 
-const renderBatch = (iterationNode, array, state, parent, endComment) => {
+// Resolve a clonedNodes entry to its live counterpart. processComponent's
+// `el.replaceWith(newWrapper)` detaches the original `<component src>` and
+// installs a `<component>` post-process wrapper in its place — but the
+// iteration's `instance.clonedNodes` still points at the original. The
+// `_vibeReplacedBy` chain (set in component.js right before the swap) gives
+// us a single pointer to the live wrapper.
+const liveCloneNode = (node) => {
+  let cur = node;
+  while (cur && cur._vibeReplacedBy) cur = cur._vibeReplacedBy;
+  return cur;
+};
+
+// Walk a row's clones for any element tagged as iteration-prop owner —
+// pre-process `<component src>` (still has the src attribute) and post-process
+// `<component>` wrappers both carry `_vibeIterPropExprs`. For each tracked
+// expression, re-evaluate against the row's new scoped state and write into
+// the registry slot the inlined bindings already reference. Idempotent: same
+// scoped state → same value → no-op write.
+const refreshIterationComponentProps = (clonedNodes, scopedState) => {
+  for (let n = 0; n < clonedNodes.length; n++) {
+    const node = liveCloneNode(clonedNodes[n]);
+    if (!node || node.nodeType !== 1) continue;
+    const wrappers = [];
+    if (node._vibeIterPropExprs) wrappers.push(node);
+    const found = node.querySelectorAll?.('[data-vibe-iter-prop]');
+    if (found) for (let i = 0; i < found.length; i++) wrappers.push(found[i]);
+    for (let w = 0; w < wrappers.length; w++) {
+      const el = wrappers[w];
+      const exprs = el._vibeIterPropExprs;
+      if (!exprs) continue;
+      const registry = ensureIterPropsRegistry();
+      for (let e = 0; e < exprs.length; e++) {
+        try {
+          const value = evalInScope(exprs[e].expr, scopedState, el);
+          registry[exprs[e].id] = value;
+        } catch {
+          // Leave previous registry value in place — same fail-safe as
+          // resolveIterationComponentProps's mount-time path.
+        }
+      }
+    }
+  }
+};
+
+// Walk an inlined component's parsed tree and force `updateIteration` on any
+// iteration node whose arrayPath resolves through the iteration-prop registry
+// (`window.__vibeIterProps._pN`). The registry slot was just refreshed in
+// place by `refreshIterationComponentProps`, so `affected()` can't notice
+// the change — both old/new evaluations of the path read the same updated
+// value. `updateIteration` is the only place equipped to diff against
+// `iterationNode.runtime.instances` (which still hold the previously rendered
+// items) and emit ADD / REMOVE / UPDATE / MOVE ops to bring the inlined DOM
+// in sync. Without this, an `<inner-component>` whose template iterates over
+// an array prop stays frozen on its initial-render items when the prop's
+// contents change.
+const REGISTRY_PATH_REGEX = /__vibeIterProps\._p\d+/;
+const forceRegistryBackedIterationUpdates = (tree, state, manifest, parentScope) => {
+  if (!tree) return;
+  if (tree.type === 'iteration') {
+    const arrPath = tree.meta?.arrayPath;
+    if (arrPath && REGISTRY_PATH_REGEX.test(arrPath)) {
+      updateIteration(tree, state, state, manifest, parentScope);
+    }
+  }
+  if (tree.children) {
+    for (const k in tree.children) {
+      forceRegistryBackedIterationUpdates(tree.children[k], state, manifest, parentScope);
+    }
+  }
+};
+
+// After registry slots are refreshed, re-hydrate the bindings inside each
+// inlined component wrapper so the new values reach the DOM. Each post-process
+// wrapper carries a `_vibeIterTree` snapshot captured at inline time (in
+// component.js) — that tree retains the original `@[...]` binding text even
+// after the wrapper's live DOM has been hydrated, so subsequent affected→
+// hydrate passes work the same way they would on initial render.
+const hydrateInlinedIterationComponents = (clonedNodes, oldState, newState, manifest) => {
+  for (let n = 0; n < clonedNodes.length; n++) {
+    const node = liveCloneNode(clonedNodes[n]);
+    if (!node || node.nodeType !== 1) continue;
+    const wrappers = [];
+    if (node._vibeIterTree) wrappers.push(node);
+    const found = node.querySelectorAll?.('[data-vibe-iter-prop]');
+    if (found) for (let i = 0; i < found.length; i++) {
+      if (found[i]._vibeIterTree) wrappers.push(found[i]);
+    }
+    for (let w = 0; w < wrappers.length; w++) {
+      const wrapper = wrappers[w];
+      const tree = wrapper._vibeIterTree;
+      const affectedList = affected(tree, oldState, newState);
+      if (affectedList.length > 0) {
+        hydrate(affectedList, newState, manifest, oldState);
+      }
+      // Bindings into the iteration-prop registry are visited above, but
+      // iteration nodes whose arrayPath resolves through the registry need
+      // explicit driving: the refreshed slot is a side effect that
+      // `affected()` can't see. Walk the tree and update them directly.
+      forceRegistryBackedIterationUpdates(tree, newState, manifest, {});
+    }
+  }
+};
+
+// Apply DOM-property writes that compileBatchFn collected. Each batch row
+// gets a built tiny scope (item + index + every state key) which is then
+// passed to evalInScope — same evaluator the clone path uses, so identifier
+// resolution rules (this.X already pre-rewritten, undefined-tolerant lookups)
+// stay aligned. The transient `data-vibe-batch` marker is removed once its
+// expressions have been applied so it doesn't leak into the live DOM.
+const applyDomPropertyWrites = (instances, array, state, itemAlias, indexAlias, domPropertyWrites) => {
+  for (let i = 0; i < instances.length; i++) {
+    const root = instances[i].element;
+    if (!root || root.nodeType !== 1) continue;
+    const localState = { ...state, [itemAlias]: array[i], [indexAlias]: i };
+    const tagged = [];
+    if (root.matches?.('[data-vibe-batch]')) tagged.push(root);
+    const found = root.querySelectorAll?.('[data-vibe-batch]');
+    if (found) for (let f = 0; f < found.length; f++) tagged.push(found[f]);
+    for (let t = 0; t < tagged.length; t++) {
+      const el = tagged[t];
+      const indexes = el.getAttribute('data-vibe-batch').split(',');
+      for (let k = 0; k < indexes.length; k++) {
+        const { prop, expr } = domPropertyWrites[indexes[k] | 0];
+        const value = evalInScope(expr, localState, el);
+        if (el[prop] !== value) el[prop] = value;
+        if (value === undefined || value === null) {
+          if (el.hasAttribute(prop)) el.removeAttribute(prop);
+        } else {
+          const str = String(value);
+          if (el.getAttribute(prop) !== str) el.setAttribute(prop, str);
+        }
+      }
+      el.removeAttribute('data-vibe-batch');
+    }
+  }
+};
+
+const renderBatch = (iterationNode, array, state, parent, endComment, parentScope = {}) => {
   const { itemAlias, indexAlias, template } = iterationNode.meta;
 
   if (!iterationNode.runtime.batchFn) {
     const stateKeys = Object.keys(state);
-    iterationNode.runtime.batchFn = compileBatchFn(template, itemAlias, indexAlias, stateKeys);
+    const compiled = compileBatchFn(template, itemAlias, indexAlias, stateKeys, parent);
+    iterationNode.runtime.batchFn = compiled.fn;
+    iterationNode.runtime.domPropertyWrites = compiled.domPropertyWrites;
     iterationNode.runtime.stateKeys = stateKeys;
   }
 
-  const { batchFn, stateKeys } = iterationNode.runtime;
+  const { batchFn, stateKeys, domPropertyWrites } = iterationNode.runtime;
   const stateValues = stateKeys.map((k) => state[k]);
-  const html = batchFn(array, ...stateValues);
+  const html = batchFn(array, ...stateValues, state);
+  // Remember the rendered output so a later update can skip re-rendering when an
+  // unrelated state change produces identical HTML (see updateIteration).
+  iterationNode.runtime.lastBatchHtml = html;
 
   batchParseTemplate.innerHTML = html;
   const frag = batchParseTemplate.content;
@@ -172,6 +506,13 @@ const renderBatch = (iterationNode, array, state, parent, endComment) => {
 
   parent.insertBefore(frag, endComment);
   iterationNode.runtime.instances = instances;
+
+  if (domPropertyWrites.length > 0) {
+    applyDomPropertyWrites(instances, array, state, itemAlias, indexAlias, domPropertyWrites);
+  }
+
+  // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
+  stampInstanceScopes(iterationNode, parentScope);
 };
 
 /**
@@ -293,9 +634,13 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
  * @param {NodeList} templateNodes - Template nodes to clone
  * @param {Object} scopedState - Scoped state (with localVars/parentScope already applied)
  * @param {Object} cachedTree - Optional cached parsed tree from template
+ * @param {string|null} componentId - Component the row belongs to, when the
+ *   iteration sits inside a component. Stashed on the parseContainer so
+ *   `findComponentIdForElement` can resolve `this.X` during the hydrate pass
+ *   that runs while clones are still detached.
  * @returns {Object} { element, tree, clonedNodes }
  */
-export const initializeBlock = (templateNodes, scopedState, cachedTree = null) => {
+export const initializeBlock = (templateNodes, scopedState, cachedTree = null, componentId = null, aliasSet = undefined) => {
   let tree;
   let clonedNodes = [];
   let firstElement = null;
@@ -310,6 +655,7 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null) =
 
   // Create a container for parsing (to capture all nodes including comment nodes like <!-- if -->)
   const parseContainer = document.createElement('div');
+  if (componentId) parseContainer._vibeComponentId = componentId;
 
   // Clone template nodes into container
   for (let i = 0; i < templateNodes.length; i++) {
@@ -336,8 +682,10 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null) =
     // Fast path: map cached tree structure onto cloned DOM (no regex, no DOM walking)
     tree = cloneTreeWithElements(cachedTree, parseContainer);
   } else {
-    // Full parse: walk DOM, extract bindings, build tree from scratch
-    tree = parse(parseContainer);
+    // Full parse: walk DOM, extract bindings, build tree from scratch. Pass this
+    // loop's aliases so loop-scoped `on*` handlers (and nested ones, via the
+    // parser's child-alias accumulation) rewrite to `$scope(this,'alias')`.
+    tree = parse(parseContainer, undefined, aliasSet);
   }
 
   // Extract the cloned nodes from the container (these are the same nodes the tree references)
@@ -458,19 +806,19 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
     return;
   }
 
-  // Fallback check: If markers are lost (e.g., comment nodes replaced by component loading),
-  // check actual DOM state between comments for hydrated nodes
-  let currentNode = startComment.nextSibling;
-  while (currentNode && currentNode !== endComment) {
-    if (currentNode.nodeType === 1) {
-      // Element node
-      const html = currentNode.outerHTML || '';
-      // If node doesn't have any @[...] syntax, it's been hydrated
-      if (!html.includes('@[')) {
-        return; // Already rendered
+  // Recovery for lost comment markers: a <component src> item re-processes its node
+  // out of managedNodes, dropping startComment.__vibeRendered. templateRemoved lives
+  // on runtime (not the DOM), so it survives — a true value means a prior render
+  // already cleared the template, so if content is still present between the
+  // comments, it's rendered; don't rebuild. Falls through only if content was lost.
+  if (iterationNode.runtime.templateRemoved) {
+    let currentNode = startComment.nextSibling;
+    while (currentNode && currentNode !== endComment) {
+      if (currentNode.nodeType === 1) {
+        return; // Already rendered — content still present
       }
+      currentNode = currentNode.nextSibling;
     }
-    currentNode = currentNode.nextSibling;
   }
 
   // Remove template nodes from DOM on first render
@@ -513,6 +861,10 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
   const instances = [];
   const templateNodes = template.element.childNodes;
   const frag = document.createDocumentFragment();
+  // Resolve the iteration's owning component once — `this.X` bindings inside
+  // row content resolve against this id while the cloned subtree is still
+  // detached during hydrate (see findComponentIdForElement's detached fallback).
+  const componentId = findComponentIdForElement(startComment.parentElement);
 
   for (let i = 0; i < array.length; i++) {
     const item = array[i];
@@ -520,7 +872,7 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
     const scopedState = createScopedState(state, localVars, parentScope);
 
     // Clone, parse, hydrate
-    const { element, tree, clonedNodes } = initializeBlock(templateNodes, scopedState, template);
+    const { element, tree, clonedNodes } = initializeBlock(templateNodes, scopedState, template, componentId, new Set(iterationNode.meta.scopeAliases));
 
     // Pre-resolve <component src> binding props against iteration scope (see helper comment)
     resolveIterationComponentProps(clonedNodes, scopedState);
@@ -545,6 +897,9 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
   parent.insertBefore(frag, endComment);
   iterationNode.runtime.instances = instances;
 
+  // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
+  stampInstanceScopes(iterationNode, parentScope);
+
   // Mark comment as rendered (survives re-parsing since comment nodes persist in DOM)
   // Also store runtime data on the DOM node so it persists across re-parses
   // @ts-ignore - adding custom property to comment node
@@ -553,6 +908,34 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
   startComment.__vibeIterationRuntime = iterationNode.runtime;
 };
 
+// Evaluate the iteration's optional key expression for one item.
+// Returns undefined when no keyExpr is declared, falling back to the default
+// heuristic in getItemKey.
+const evalKeyForItem = (iterationNode, item, index, state, parentScope) => {
+  const { keyExpr, itemAlias, indexAlias } = iterationNode.meta;
+  if (!keyExpr) return undefined;
+  const localVars = { [itemAlias]: item, [indexAlias]: index };
+  const scopedState = createScopedState(state, localVars, parentScope);
+  try {
+    return evalInScope(keyExpr, scopedState, iterationNode.meta.startComment.parentElement);
+  } catch {
+    return undefined;
+  }
+};
+
+// One-shot warning when an unkeyed iteration produces index-coupled keys —
+// i.e. the fallback `hash_..._<index>` path. Only emits in debug mode and only
+// once per iteration block, so console doesn't drown.
+const warnIndexCoupledKey = (iterationNode) => {
+  if (iterationNode.runtime.warnedIndexCoupled) return;
+  if (!globalThis.__vibeDebug) return;
+  iterationNode.runtime.warnedIndexCoupled = true;
+  const arrayPath = iterationNode.meta.arrayPath;
+  console.warn(
+    `[vibe] iteration over '${arrayPath}' is using index-coupled keys. Removing earlier items will trigger a full re-render. Add an explicit key: <!-- each ${arrayPath} as item (item.id) -->`,
+  );
+};
+
 // Update an iteration block when array changes
 export const updateIteration = (iterationNode, newState, oldState, manifest, parentScope = {}) => {
   if (!iterationNode.runtime.instances || !iterationNode.runtime.templateRemoved) return;
@@ -565,11 +948,19 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
   const newArray = evalInScope(resolvedExpr, newState, startComment.parentElement) ?? resolvePath(newState, resolvedExpr) ?? [];
 
   // Use instances (what's actually rendered) as ground truth for old array
-  // when oldState disagrees with the rendered count.
+  // when oldState disagrees with the rendered count, OR when stateOldArray
+  // and newArray are the same reference. The latter happens for
+  // registry-backed iterations: when the iteration's arrayPath resolves to
+  // `window.__vibeIterProps._pN`, refreshIterationComponentProps updates the
+  // slot in place, so both reads return the same NEW array. Without this
+  // fallback the diff would compare the new array against itself and report
+  // no changes — leaving the inlined iteration frozen on previously rendered
+  // items.
   const instances = iterationNode.runtime.instances;
-  const oldArray = instances.length === stateOldArray.length
-    ? stateOldArray
-    : instances.map(inst => inst.item);
+  const oldArray =
+    stateOldArray !== newArray && instances.length === stateOldArray.length
+      ? stateOldArray
+      : instances.map((inst) => inst.item);
 
   // Compiled path: Use pre-compiled batch function when available
   if (compiled.canUseCompiled(iterationNode)) {
@@ -596,8 +987,42 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
     return;
   }
 
-  const oldKeys = oldArray.map((item, i) => getItemKey(item, i));
-  const newKeys = newArray.map((item, i) => getItemKey(item, i));
+  // Treeless rows (batch-rendered) can't be patched in place — they have no
+  // parsed tree for updateInstance to walk. When affected pushes them as
+  // iteration-affected (see the same predicate in affected.js), do a full
+  // re-batch so row bindings reflect current state. Clone-rendered iterations
+  // skip this — they take the diff path below.
+  const hasTreelessInstances = instances.length > 0 && !instances[0].tree;
+  if (hasTreelessInstances && oldState !== newState) {
+    // affected.js conservatively flags a treeless (batch-rendered) iteration on
+    // ANY state change, since it can't walk per-row trees to see which bindings
+    // actually depend on what changed. Before tearing down and recreating every
+    // row, re-run the batch: if it yields identical HTML, the rows don't depend
+    // on what changed, so keep the existing DOM nodes — preserving their event
+    // listeners (e.g. tooltip mouseleave) and any in-progress drag. Skip the
+    // shortcut when the template has DOM-property writes (value/checked/etc.),
+    // which aren't reflected in the HTML string.
+    const rt = iterationNode.runtime;
+    if (rt.batchFn && rt.lastBatchHtml !== undefined && (!rt.domPropertyWrites || rt.domPropertyWrites.length === 0)) {
+      const stateValues = rt.stateKeys.map((k) => newState[k]);
+      const newHtml = rt.batchFn(newArray, ...stateValues, newState);
+      if (newHtml === rt.lastBatchHtml) return;
+    }
+    bulkReplace(iterationNode, newArray, newState, manifest, parentScope);
+    return;
+  }
+
+  const oldKeys = oldArray.map((item, i) =>
+    getItemKey(item, i, evalKeyForItem(iterationNode, item, i, oldState, parentScope)),
+  );
+  const newKeys = newArray.map((item, i) =>
+    getItemKey(item, i, evalKeyForItem(iterationNode, item, i, newState, parentScope)),
+  );
+
+  // Detect index-coupled fallback keys (debug-mode warning only).
+  if (!iterationNode.meta.keyExpr && newKeys.some(k => k.startsWith('hash_') || k.startsWith('val_'))) {
+    warnIndexCoupledKey(iterationNode);
+  }
 
   // O(n) check: if no keys are shared, do bulk replacement instead of O(n²) LCS
   const oldKeySet = new Set(oldKeys);
@@ -609,6 +1034,11 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
   // Standard diff-based updates (arrays share some common items)
   const operations = computeDiff(oldKeys, newKeys, oldArray, newArray);
 
+  // Apply array-shape operations and capture which instances were
+  // bindings-refreshed by an op (ADD built a fresh tree with newState;
+  // UPDATE patched bindings in place). Captured by reference, not index,
+  // because indices shift during the loop.
+  const refreshedByOps = new WeakSet();
   operations.forEach((op) => {
     switch (op.type) {
       case 'REMOVE':
@@ -616,19 +1046,32 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
         break;
       case 'ADD':
         addInstance(iterationNode, op.item, op.index, newState, manifest, parentScope);
+        refreshedByOps.add(iterationNode.runtime.instances[op.index]);
         break;
       case 'MOVE':
         moveInstance(iterationNode, op.from, op.to);
         break;
       case 'UPDATE':
-        updateInstance(iterationNode, op.index, op.item, newState, manifest, parentScope);
+        updateInstance(iterationNode, op.index, op.item, oldState, newState, manifest, parentScope);
+        refreshedByOps.add(iterationNode.runtime.instances[op.index]);
         break;
     }
   });
 
-  iterationNode.runtime.instances.forEach((inst, i) => {
-    inst.index = i;
-  });
+  // Refresh every row the ops didn't touch: moved rows (index changed,
+  // bindings stale) and untouched rows whose outer-scope bindings depend
+  // on state that changed in this update cycle. Each row goes through
+  // updateInstance exactly once — via an op or here.
+  const retained = iterationNode.runtime.instances;
+  for (let i = 0; i < retained.length; i++) {
+    retained[i].index = i;
+    if (refreshedByOps.has(retained[i])) continue;
+    updateInstance(iterationNode, i, retained[i].item, oldState, newState, manifest, parentScope);
+  }
+
+  // Re-stamp after the diff settles: moved/updated instances now carry their
+  // current item + index, so `$scope` handlers resolve correctly post-reorder.
+  stampInstanceScopes(iterationNode, parentScope);
 };
 
 // Bulk replacement: clear all DOM and re-render from scratch
@@ -653,7 +1096,7 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
   // For simple templates (no nested iterations/conditionals, single root element),
   // use batch string rendering: one string concatenation loop + one innerHTML parse
   if (canUseBatchRender(template)) {
-    renderBatch(iterationNode, newArray, state, parent, endComment);
+    renderBatch(iterationNode, newArray, state, parent, endComment, parentScope);
     const instances = iterationNode.runtime.instances;
     for (let i = 0; i < instances.length; i++) {
       if (instances[i].element?.nodeType === 1) managedNodes.add(instances[i].element);
@@ -677,6 +1120,9 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
   }
   parent.insertBefore(frag, endComment);
   iterationNode.runtime.instances = instances;
+
+  // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
+  stampInstanceScopes(iterationNode, parentScope);
 };
 
 // Find an instance's canonical in-DOM anchor (the first of its cloned nodes
@@ -746,10 +1192,11 @@ const detachInstanceDom = (iterationNode, index, parent) => {
 // Pure function — no DOM insertion, no side effects on iteration state.
 // Callers decide where the clones go (iteration parent, DocumentFragment).
 const buildInstance = (iterationNode, item, index, state, parentScope) => {
-  const { itemAlias, indexAlias, template } = iterationNode.meta;
+  const { itemAlias, indexAlias, template, startComment } = iterationNode.meta;
   const localVars = { [itemAlias]: item, [indexAlias]: index };
   const scopedState = createScopedState(state, localVars, parentScope);
-  const built = initializeBlock([...template.element.childNodes], scopedState, template);
+  const componentId = findComponentIdForElement(startComment.parentElement);
+  const built = initializeBlock([...template.element.childNodes], scopedState, template, componentId, new Set(iterationNode.meta.scopeAliases));
   resolveIterationComponentProps(built.clonedNodes, scopedState);
   return { ...built, scopedState, localVars };
 };
@@ -811,13 +1258,15 @@ const moveInstance = (iterationNode, fromIndex, toIndex) => {
   }
 };
 
-const updateInstance = (iterationNode, index, newItem, state, manifest, parentScope = {}) => {
-  if (index < 0 || index >= iterationNode.runtime.instances.length) return;
+// Detach-and-rebuild fallback. Used when the row's parsed tree isn't
+// available (compiled iterations), or when the row template's top-level
+// shape itself depends on the item (a `<!-- if -->` directly under the
+// iteration with the item in its expression — flipping branches needs a
+// rebuild because the active root element type changes).
+const updateInstanceRebuild = (iterationNode, index, newItem, state, manifest, parentScope) => {
   const parent = iterationNode.meta.startComment.parentNode;
   const instance = iterationNode.runtime.instances[index];
 
-  // Build fresh first, then detach old — keeps the old DOM as a stable
-  // anchor reference until we know how the new nodes are shaped.
   const built = buildInstance(iterationNode, newItem, index, state, parentScope);
   detachInstanceDom(iterationNode, index, parent);
   const insertBefore = resolveInsertBefore(iterationNode, index + 1, parent);
@@ -828,6 +1277,46 @@ const updateInstance = (iterationNode, index, newItem, state, manifest, parentSc
   instance.tree = built.tree;
   instance.item = newItem;
   instance.clonedNodes = built.clonedNodes;
+  instance.scopedState = built.scopedState;
+};
+
+// In-place refresh of a single row: rebuild scoped states from oldState +
+// newState (and possibly a new item), run affected→hydrate against the row's
+// parsed tree. Same pipeline as top-level state changes; the row's DOM nodes
+// survive, only changed bindings update.
+//
+// Called from two sites in updateIteration:
+//   1. UPDATE diff op — newItem differs from instance.item
+//   2. Post-diff outer-state propagation — newItem === instance.item
+// Both flow through here so iteration updates have one code path, not two.
+// Compiled / batch instances have no row tree to walk and fall back to a
+// full rebuild via updateInstanceRebuild.
+const updateInstance = (iterationNode, index, newItem, oldState, newState, manifest, parentScope = {}) => {
+  if (index < 0 || index >= iterationNode.runtime.instances.length) return;
+  const instance = iterationNode.runtime.instances[index];
+
+  if (!instance.tree) {
+    updateInstanceRebuild(iterationNode, index, newItem, newState, manifest, parentScope);
+    return;
+  }
+
+  const { itemAlias, indexAlias } = iterationNode.meta;
+  const oldLocalVars = { [itemAlias]: instance.item, [indexAlias]: index };
+  const newLocalVars = { [itemAlias]: newItem, [indexAlias]: index };
+  const oldScopedState = createScopedState(oldState, oldLocalVars, parentScope);
+  const newScopedState = createScopedState(newState, newLocalVars, parentScope);
+
+  refreshIterationComponentProps(instance.clonedNodes, newScopedState);
+
+  const affectedList = affected(instance.tree, oldScopedState, newScopedState);
+  if (affectedList.length > 0) {
+    hydrate(affectedList, newScopedState, manifest, oldScopedState);
+  }
+
+  hydrateInlinedIterationComponents(instance.clonedNodes, oldScopedState, newScopedState, manifest);
+
+  instance.item = newItem;
+  instance.scopedState = newScopedState;
 };
 
 export default {