@ape-egg/vibe 1.7.2 → 1.9.0

package/runtime/iterate.js

@@ -2,16 +2,125 @@ 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 } from './utils.js';
-
-// Fast path for iteration rendering (opt-in via window.__VIBE_FAST_ITERATION__)
-// See: _vibe-compiled-iteration-batch.js for implementation details
-// This is a preview of what Vibe Compiled (Phase 2) will do automatically
-import * as fastPath from './_vibe-compiled-iteration-batch.js';
+import { resolveThisPath, evalInScope } from './utils.js';
+import { managedNodes } from './conditionals.js';
+import { BINDING_REGEX } from './constants.js';
 
 // Pre-compiled iteration optimization (production)
 import * as compiled from './pre-compiled-iterations.js';
 
+// Runtime batch-render helpers for full-replacement of simple templates.
+// 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 -->.
+const batchParseTemplate = document.createElement('template');
+
+// innerHTML serialization encodes <, >, &, ", ' inside attribute values.
+// Decode them back before wrapping @[expr] in ${...} for the template literal.
+const decodeEntities = (s) => s
+  .replace(/&lt;/g, '<')
+  .replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"')
+  .replace(/&#39;/g, "'")
+  .replace(/&amp;/g, '&');
+
+const hasNestedStructures = (tree) => {
+  if (!tree || !tree.children) return false;
+  for (const key in tree.children) {
+    const child = tree.children[key];
+    if (!child) continue;
+    if (child.type === 'iteration' || child.type === 'conditional') return true;
+    if (hasNestedStructures(child)) return true;
+  }
+  return false;
+};
+
+const canUseBatchRender = (template) =>
+  !hasNestedStructures(template) && template.element.children.length <= 1;
+
+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) + '}');
+
+  return new Function(
+    'arr',
+    ...stateKeys,
+    `
+      let html = '';
+      const len = arr.length;
+      for (let ${indexAlias} = 0; ${indexAlias} < len; ${indexAlias}++) {
+        const ${itemAlias} = arr[${indexAlias}];
+        html += \`${code}\`;
+      }
+      return html;
+    `,
+  );
+};
+
+// 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 literal value. Component[src] attributes intentionally
+// bypass hydrate (parse.js) so they reach processComponent as bindings — but
+// bindings that depend on iteration-local vars (item, index) can't resolve later
+// when processComponent 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) => {
+  for (let n = 0; n < nodes.length; n++) {
+    const node = nodes[n];
+    if (node.nodeType !== 1) continue;
+    const components = node.matches?.('component[src], div.component[src]')
+      ? [node, ...node.querySelectorAll('component[src], div.component[src]')]
+      : [...node.querySelectorAll('component[src], div.component[src]')];
+    for (let i = 0; i < components.length; i++) {
+      const el = components[i];
+      const attrs = el.attributes;
+      for (let j = 0; j < attrs.length; j++) {
+        const attr = attrs[j];
+        if (attr.name === 'src') continue;
+        const match = attr.value.match(/^@\[(.+)\]$/);
+        if (!match) continue;
+        try {
+          const value = evalInScope(match[1], scopedState, el);
+          if (value !== undefined) {
+            el.setAttribute(attr.name, String(value));
+          }
+        } catch {
+          // Leave binding raw — processComponent will handle it as a binding
+        }
+      }
+    }
+  }
+};
+
+const renderBatch = (iterationNode, array, state, parent, endComment) => {
+  const { itemAlias, indexAlias, template } = iterationNode.meta;
+
+  if (!iterationNode.runtime.batchFn) {
+    const stateKeys = Object.keys(state);
+    iterationNode.runtime.batchFn = compileBatchFn(template, itemAlias, indexAlias, stateKeys);
+    iterationNode.runtime.stateKeys = stateKeys;
+  }
+
+  const { batchFn, stateKeys } = iterationNode.runtime;
+  const stateValues = stateKeys.map((k) => state[k]);
+  const html = batchFn(array, ...stateValues);
+
+  batchParseTemplate.innerHTML = html;
+  const frag = batchParseTemplate.content;
+  const kids = frag.children;
+
+  const arrayLen = array.length;
+  const instances = new Array(arrayLen);
+  for (let i = 0; i < arrayLen; i++) {
+    instances[i] = { element: kids[i], item: array[i], index: i };
+  }
+
+  parent.insertBefore(frag, endComment);
+  iterationNode.runtime.instances = instances;
+};
+
 /**
  * Find a comment node with matching text content in the given nodes.
  */
@@ -138,32 +247,43 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null) =
   let clonedNodes = [];
   let firstElement = null;
 
-  // TEMPORARY: Disable fast path to test if it's causing duplication
-  let canUseFastPath = false;
+  // Use cached tree when available: cloneTreeWithElements maps the existing parsed structure
+  // onto cloned DOM nodes, avoiding a full parse() call per iteration item.
+  // Only fall back to parse() when no cached tree exists (first parse of a new template).
+  // cloneTreeWithElements has a mapping bug with compiled mode's tree structure.
+  // Keep disabled until the root cause is fixed — the other optimizations
+  // (bulk replacement, evalInScope caching, DocumentFragment) cover the hot paths.
+  const useCachedTree = false;
 
   // Create a container for parsing (to capture all nodes including comment nodes like <!-- if -->)
   const parseContainer = document.createElement('div');
 
-  if (canUseFastPath) {
-    // Fast path: clone template nodes and map to cached tree structure
-    for (let i = 0; i < templateNodes.length; i++) {
-      const cloned = templateNodes[i].cloneNode(true);
-      parseContainer.appendChild(cloned);
-      if (!firstElement && cloned.nodeType === 1) {
-        firstElement = cloned;
-      }
+  // Clone template nodes into container
+  for (let i = 0; i < templateNodes.length; i++) {
+    const cloned = templateNodes[i].cloneNode(true);
+    parseContainer.appendChild(cloned);
+    if (!firstElement && cloned.nodeType === 1) {
+      firstElement = cloned;
     }
+  }
+
+  // Preserve raw slot content of nested <component src> elements before renderAllConditionals /
+  // renderAllIterations runs on this branch/iteration instance — those paths strip <!-- if -->
+  // and <!-- each --> templates from the live DOM, so by the time processComponent reads
+  // el.innerHTML (next microtask, when MutationObserver fires) the inactive branch templates
+  // would be gone. cloneNode(true) does not copy expando JS properties, so we must (re)capture
+  // _vibeSlotContent on every clone.
+  const components = parseContainer.querySelectorAll('component[src], div.component[src]');
+  for (let i = 0; i < components.length; i++) {
+    const el = components[i];
+    if (el._vibeSlotContent === undefined) el._vibeSlotContent = el.innerHTML;
+  }
+
+  if (useCachedTree) {
+    // Fast path: map cached tree structure onto cloned DOM (no regex, no DOM walking)
     tree = cloneTreeWithElements(cachedTree, parseContainer);
   } else {
-    // Slow path: clone and parse from scratch
-    for (let i = 0; i < templateNodes.length; i++) {
-      const cloned = templateNodes[i].cloneNode(true);
-      parseContainer.appendChild(cloned);
-      if (!firstElement && cloned.nodeType === 1) {
-        firstElement = cloned;
-      }
-    }
-    // Parse the entire container (includes all nodes + conditionals)
+    // Full parse: walk DOM, extract bindings, build tree from scratch
     tree = parse(parseContainer);
   }
 
@@ -194,24 +314,22 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null) =
 
 // Create a proxied state with scoped variables (item, index, array)
 export const createScopedState = (globalState, localVars, parentScope = {}) => {
+  // Pre-compute the combined key list once at creation time.
+  // Avoids rebuilding 3 arrays + Set on every Object.keys() call.
+  const cachedKeys = [...new Set([
+    ...Object.keys(localVars),
+    ...Object.keys(parentScope),
+    ...Reflect.ownKeys(globalState),
+  ])];
+
   return new Proxy(globalState, {
     get(target, prop) {
-      // 1. Check local scope first (item, index, array)
-      if (prop in localVars) {
-        return localVars[prop];
-      }
-
-      // 2. Check parent scope (for nested iterations)
-      if (prop in parentScope) {
-        return parentScope[prop];
-      }
-
-      // 3. Fall back to global state
+      if (prop in localVars) return localVars[prop];
+      if (prop in parentScope) return parentScope[prop];
       return Reflect.get(target, prop);
     },
 
     set(target, prop, value) {
-      // Only allow setting global state, not local vars
       if (prop in localVars) {
         console.warn(`Cannot modify iteration variable '${prop}'`);
         return false;
@@ -223,21 +341,13 @@ export const createScopedState = (globalState, localVars, parentScope = {}) => {
       return Reflect.set(target, prop, value);
     },
 
-    ownKeys(target) {
-      // Return all keys: local vars, parent scope, and global state
-      const localKeys = Object.keys(localVars);
-      const parentKeys = Object.keys(parentScope);
-      const globalKeys = Reflect.ownKeys(target);
-      return [...new Set([...localKeys, ...parentKeys, ...globalKeys])];
-    },
+    ownKeys() { return cachedKeys; },
 
     has(target, prop) {
-      // Check if property exists in local scope, parent scope, or global state
       return prop in localVars || prop in parentScope || Reflect.has(target, prop);
     },
 
     getOwnPropertyDescriptor(target, prop) {
-      // Provide property descriptor for local vars and parent scope
       if (prop in localVars) {
         return { configurable: true, enumerable: true, value: localVars[prop] };
       }
@@ -323,10 +433,12 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
 
   const parent = startComment.parentNode;
 
-  // Handle this.property for component-scoped arrays
-  const resolvedArrayPath = resolveThisPath(arrayPath, startComment.parentElement);
-
-  const array = resolvePath(state, resolvedArrayPath);
+  // Evaluate the array expression — supports state paths (items),
+  // window globals (window.fights), method calls (items.filter(...)),
+  // and inline literals (['a', 'b']). Falls back to resolvePath for
+  // simple paths that evalInScope might miss in scoped contexts.
+  const resolvedExpr = resolveThisPath(arrayPath, startComment.parentElement);
+  const array = evalInScope(resolvedExpr, state, startComment.parentElement) ?? resolvePath(state, resolvedExpr);
   if (!Array.isArray(array) || array.length === 0) {
     iterationNode.runtime.instances = [];
     return;
@@ -344,15 +456,10 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
     // Fall through to runtime path if compiled failed
   }
 
-  // Fast path: opt-in via window.__VIBE_FAST_ITERATION__ (preview of Vibe Compiled)
-  if (window.__VIBE_FAST_ITERATION__ && fastPath.canUseFastPath(template)) {
-    fastPath.renderFast(iterationNode, array, state, parent, endComment);
-    return;
-  }
-
   // Standard path: clone and hydrate each item (handles nested iterations/conditionals)
   const instances = [];
-  const templateNodes = [...template.element.childNodes];
+  const templateNodes = template.element.childNodes;
+  const frag = document.createDocumentFragment();
 
   for (let i = 0; i < array.length; i++) {
     const item = array[i];
@@ -362,8 +469,14 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
     // Clone, parse, hydrate
     const { element, tree, clonedNodes } = initializeBlock(templateNodes, scopedState, template);
 
-    // Insert cloned nodes
-    clonedNodes.forEach((node) => parent.insertBefore(node, endComment));
+    // Pre-resolve <component src> binding props against iteration scope (see helper comment)
+    resolveIterationComponentProps(clonedNodes, scopedState);
+
+    // Collect nodes in DocumentFragment (single DOM insertion at end)
+    for (let j = 0; j < clonedNodes.length; j++) {
+      frag.appendChild(clonedNodes[j]);
+      if (clonedNodes[j].nodeType === 1) managedNodes.add(clonedNodes[j]);
+    }
 
     // Recursively render nested iterations and conditionals
     if (tree) {
@@ -375,6 +488,8 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
     instances.push({ element, tree, item, index: i, clonedNodes, scopedState });
   }
 
+  // Single DOM insertion for all items
+  parent.insertBefore(frag, endComment);
   iterationNode.runtime.instances = instances;
 
   // Mark comment as rendered (survives re-parsing since comment nodes persist in DOM)
@@ -391,11 +506,17 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
 
   const { arrayPath, template, startComment, endComment } = iterationNode.meta;
 
-  // Handle this.property for component-scoped arrays
-  const resolvedArrayPath = resolveThisPath(arrayPath, startComment.parentElement);
+  const resolvedExpr = resolveThisPath(arrayPath, startComment.parentElement);
 
-  const oldArray = resolvePath(oldState, resolvedArrayPath) || [];
-  const newArray = resolvePath(newState, resolvedArrayPath) || [];
+  const stateOldArray = evalInScope(resolvedExpr, oldState, startComment.parentElement) ?? resolvePath(oldState, resolvedExpr) ?? [];
+  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.
+  const instances = iterationNode.runtime.instances;
+  const oldArray = instances.length === stateOldArray.length
+    ? stateOldArray
+    : instances.map(inst => inst.item);
 
   // Compiled path: Use pre-compiled batch function when available
   if (compiled.canUseCompiled(iterationNode)) {
@@ -415,20 +536,24 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
     // Fall through to runtime path if compiled failed
   }
 
-  // Fast path: opt-in via window.__VIBE_FAST_ITERATION__ (preview of Vibe Compiled)
-  // Use for bulk operations (large arrays or empty→full transitions)
-  if (
-    window.__VIBE_FAST_ITERATION__ &&
-    fastPath.canUseFastPath(template) &&
-    (isEmptyToFull || isFullToEmpty || isLargeArray)
-  ) {
-    fastPath.updateFast(iterationNode, newArray, newState, startComment, endComment);
+  // Bulk path: skip O(n²) LCS when arrays share no common items
+  // Handles empty→full, full→empty, and full replacement (no shared keys)
+  if (oldArray.length === 0 || newArray.length === 0) {
+    bulkReplace(iterationNode, newArray, newState, manifest, parentScope);
     return;
   }
 
-  // Standard diff-based updates
   const oldKeys = oldArray.map((item, i) => getItemKey(item, i));
   const newKeys = newArray.map((item, i) => getItemKey(item, i));
+
+  // O(n) check: if no keys are shared, do bulk replacement instead of O(n²) LCS
+  const oldKeySet = new Set(oldKeys);
+  if (!newKeys.some(k => oldKeySet.has(k))) {
+    bulkReplace(iterationNode, newArray, newState, manifest, parentScope);
+    return;
+  }
+
+  // Standard diff-based updates (arrays share some common items)
   const operations = computeDiff(oldKeys, newKeys, oldArray, newArray);
 
   operations.forEach((op) => {
@@ -453,106 +578,203 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
   });
 };
 
-// Add a new instance at the specified index
-const addInstance = (iterationNode, item, index, state, manifest, parentScope) => {
-  const { itemAlias, indexAlias, template, startComment, endComment } = iterationNode.meta;
+// Bulk replacement: clear all DOM and re-render from scratch
+// Used when arrays share no common keys (avoids O(n²) LCS)
+const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
+  const { template, startComment, endComment } = iterationNode.meta;
+  const parent = startComment.parentNode;
 
-  const localVars = { [itemAlias]: item, [indexAlias]: index };
-  const scopedState = createScopedState(state, localVars, parentScope);
-  const templateNodes = [...template.element.childNodes];
+  // Clear all existing DOM between comments using Range (single operation)
+  if (iterationNode.runtime.instances.length > 0) {
+    const range = document.createRange();
+    range.setStartAfter(startComment);
+    range.setEndBefore(endComment);
+    range.deleteContents();
+  }
 
-  const { element, tree, clonedNodes } = initializeBlock(templateNodes, scopedState, template);
+  if (newArray.length === 0) {
+    iterationNode.runtime.instances = [];
+    return;
+  }
+
+  // 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);
+    const instances = iterationNode.runtime.instances;
+    for (let i = 0; i < instances.length; i++) {
+      if (instances[i].element?.nodeType === 1) managedNodes.add(instances[i].element);
+    }
+    return;
+  }
+
+  // Complex templates: build each instance, batch-append into a DocumentFragment,
+  // finalize (mark managed + render nested), then commit to the DOM in one
+  // parent.insertBefore call.
+  const instances = [];
+  const frag = document.createDocumentFragment();
+  for (let i = 0; i < newArray.length; i++) {
+    const built = buildInstance(iterationNode, newArray[i], i, state, parentScope);
+    for (let j = 0; j < built.clonedNodes.length; j++) frag.appendChild(built.clonedNodes[j]);
+    finalizeInstance(built, manifest, parentScope);
+    instances.push({
+      element: built.element, tree: built.tree, item: newArray[i], index: i,
+      clonedNodes: built.clonedNodes, scopedState: built.scopedState,
+    });
+  }
+  parent.insertBefore(frag, endComment);
+  iterationNode.runtime.instances = instances;
+};
+
+// Find an instance's canonical in-DOM anchor (the first of its cloned nodes
+// that still lives directly under the iteration's parent). Nested primitives
+// inside the iteration template — <!-- if -->, <!-- each -->, <component> —
+// can move/replace cloned nodes between iteration renders (inactive branches
+// get hoisted into template containers; component[src] wrappers get swapped
+// for processed wrappers). Any of those mutations make `clonedNodes[0]` a
+// stale reference to a node no longer under the iteration parent. Callers use
+// this anchor instead of trusting `clonedNodes[0]` directly, so that
+// insert-before / move operations always resolve against the iteration's real
+// DOM slot.
+const findInstanceAnchor = (instance, iterationParent) => {
+  const nodes = instance.clonedNodes || (instance.element ? [instance.element] : []);
+  for (let i = 0; i < nodes.length; i++) {
+    if (nodes[i]?.parentNode === iterationParent) return nodes[i];
+  }
+  return null;
+};
+
+// Resolve the reference node for `parent.insertBefore(..., ref)` at a given
+// logical iteration index. Walks later instances until it finds one with a
+// live anchor under the iteration parent; falls back to `endComment` when no
+// later instance has any node currently mounted in the iteration.
+const resolveInsertBefore = (iterationNode, index, parent) => {
+  const { instances } = iterationNode.runtime;
+  for (let i = index; i < instances.length; i++) {
+    const anchor = findInstanceAnchor(instances[i], parent);
+    if (anchor) return anchor;
+  }
+  return iterationNode.meta.endComment;
+};
+
+// Detach every DOM node belonging to a logical instance, including content
+// mounted by nested primitives (conditional branches, nested each rows,
+// fetched component wrappers) that isn't tracked in `instance.clonedNodes`.
+// Walks iteration-parent siblings from this instance's anchor up to the next
+// instance's anchor / endComment, so anything in between — clones, mounted
+// branches, swapped-in component wrappers — all gets detached. Also sweeps
+// any clonedNodes that were hoisted out of the iteration parent (e.g. into a
+// sibling conditional's template container).
+const detachInstanceDom = (iterationNode, index, parent) => {
+  const instance = iterationNode.runtime.instances[index];
+  const { endComment } = iterationNode.meta;
+  const anchor = findInstanceAnchor(instance, parent);
+  const nextAnchor = resolveInsertBefore(iterationNode, index + 1, parent);
+
+  if (anchor) {
+    let cur = anchor;
+    // endComment caps the walk even if nextAnchor ordering is ever
+    // corrupted — iteration DOM is bounded by startComment / endComment.
+    while (cur && cur !== nextAnchor && cur !== endComment) {
+      const nextSibling = cur.nextSibling;
+      parent.removeChild(cur);
+      cur = nextSibling;
+    }
+  }
 
-  // Find insertion point
-  const insertBefore =
-    index < iterationNode.runtime.instances.length
-      ? iterationNode.runtime.instances[index].clonedNodes?.[0] ||
-        iterationNode.runtime.instances[index].element
-      : endComment;
+  const nodes = instance.clonedNodes || (instance.element ? [instance.element] : []);
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (n && n.parentNode && n.parentNode !== parent) n.parentNode.removeChild(n);
+  }
+};
 
-  // Insert cloned nodes
-  clonedNodes.forEach((node) => startComment.parentNode.insertBefore(node, insertBefore));
+// Build a fresh instance's DOM + tree + scope from the iteration template.
+// 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 localVars = { [itemAlias]: item, [indexAlias]: index };
+  const scopedState = createScopedState(state, localVars, parentScope);
+  const built = initializeBlock([...template.element.childNodes], scopedState, template);
+  resolveIterationComponentProps(built.clonedNodes, scopedState);
+  return { ...built, scopedState, localVars };
+};
 
-  // Recursively render nested iterations and conditionals
+// After a built instance's clones are placed in the DOM (directly or via a
+// fragment), mark element clones as managed so the page-level MutationObserver
+// skips them in processMutations, then fire nested iteration/conditional
+// renders. Without the managed mark those clones would be re-parsed + hydrated
+// on top of the internal render, duplicating every nested branch.
+const finalizeInstance = (built, manifest, parentScope) => {
+  const { clonedNodes, tree, scopedState, localVars } = built;
+  for (let i = 0; i < clonedNodes.length; i++) {
+    if (clonedNodes[i].nodeType === 1) managedNodes.add(clonedNodes[i]);
+  }
   if (tree) {
     const nestedScope = { ...parentScope, ...localVars };
     renderAllIterations(tree, scopedState, manifest, nestedScope);
     _renderAllConditionals(tree, scopedState, manifest, nestedScope);
   }
+};
 
-  iterationNode.runtime.instances.splice(index, 0, { element, tree, item, index, clonedNodes });
+const addInstance = (iterationNode, item, index, state, manifest, parentScope) => {
+  const parent = iterationNode.meta.startComment.parentNode;
+  const built = buildInstance(iterationNode, item, index, state, parentScope);
+  const insertBefore = resolveInsertBefore(iterationNode, index, parent);
+  for (let i = 0; i < built.clonedNodes.length; i++) parent.insertBefore(built.clonedNodes[i], insertBefore);
+  finalizeInstance(built, manifest, parentScope);
+  iterationNode.runtime.instances.splice(index, 0, {
+    element: built.element, tree: built.tree, item, index, clonedNodes: built.clonedNodes,
+  });
 };
 
-// Remove an instance at the specified index
 const removeInstance = (iterationNode, index) => {
   if (index < 0 || index >= iterationNode.runtime.instances.length) return;
-
-  const instance = iterationNode.runtime.instances[index];
-
-  // Remove all cloned nodes from DOM
-  (instance.clonedNodes || [instance.element]).forEach((node) =>
-    node?.parentNode?.removeChild(node),
-  );
-
+  const parent = iterationNode.meta.startComment.parentNode;
+  if (parent) detachInstanceDom(iterationNode, index, parent);
   iterationNode.runtime.instances.splice(index, 1);
 };
 
-// Move an instance from one position to another
 const moveInstance = (iterationNode, fromIndex, toIndex) => {
   if (fromIndex === toIndex) return;
-  if (fromIndex < 0 || fromIndex >= iterationNode.runtime.instances.length) return;
-  if (toIndex < 0 || toIndex >= iterationNode.runtime.instances.length) return;
+  const { instances } = iterationNode.runtime;
+  if (fromIndex < 0 || fromIndex >= instances.length) return;
+  if (toIndex < 0 || toIndex >= instances.length) return;
+  const parent = iterationNode.meta.startComment.parentNode;
 
-  const instance = iterationNode.runtime.instances[fromIndex];
-  const nodes = instance.clonedNodes || [instance.element];
-  const parent = nodes[0]?.parentNode;
+  const instance = instances[fromIndex];
+  instances.splice(fromIndex, 1);
+  instances.splice(toIndex, 0, instance);
 
-  iterationNode.runtime.instances.splice(fromIndex, 1);
-  iterationNode.runtime.instances.splice(toIndex, 0, instance);
-
-  // Find new insertion point
-  const nextInstance = iterationNode.runtime.instances[toIndex + 1];
-  const insertBefore = nextInstance
-    ? nextInstance.clonedNodes?.[0] || nextInstance.element
-    : iterationNode.meta.endComment;
-
-  // Move all nodes
-  nodes.forEach((node) => parent.insertBefore(node, insertBefore));
+  const insertBefore = resolveInsertBefore(iterationNode, toIndex + 1, parent);
+  const nodes = instance.clonedNodes || [instance.element];
+  // Re-insert only nodes currently under the iteration parent — those hoisted
+  // into nested-conditional template containers stay there so we don't
+  // double-count branch content.
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (n?.parentNode === parent) parent.insertBefore(n, insertBefore);
+  }
 };
 
-// Update an instance with new item data
 const updateInstance = (iterationNode, index, newItem, state, manifest, parentScope = {}) => {
   if (index < 0 || index >= iterationNode.runtime.instances.length) return;
-
-  const { itemAlias, indexAlias, template } = iterationNode.meta;
+  const parent = iterationNode.meta.startComment.parentNode;
   const instance = iterationNode.runtime.instances[index];
 
-  const localVars = { [itemAlias]: newItem, [indexAlias]: index };
-  const scopedState = createScopedState(state, localVars, parentScope);
-  const templateNodes = [...template.element.childNodes];
-
-  const { element, tree, clonedNodes } = initializeBlock(templateNodes, scopedState, template);
-
-  // Remove old nodes, insert new ones in same position
-  const oldNodes = instance.clonedNodes || [instance.element];
-  const insertBefore = oldNodes[oldNodes.length - 1]?.nextSibling;
-  const parent = oldNodes[0]?.parentNode;
-
-  oldNodes.forEach((node) => node?.parentNode?.removeChild(node));
-  clonedNodes.forEach((node) => parent.insertBefore(node, insertBefore));
-
-  // Recursively render nested iterations and conditionals
-  if (tree) {
-    const nestedScope = { ...parentScope, ...localVars };
-    renderAllIterations(tree, scopedState, manifest, nestedScope);
-    _renderAllConditionals(tree, scopedState, manifest, nestedScope);
-  }
+  // 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);
+  for (let i = 0; i < built.clonedNodes.length; i++) parent.insertBefore(built.clonedNodes[i], insertBefore);
+  finalizeInstance(built, manifest, parentScope);
 
-  // Update instance
-  instance.element = element;
-  instance.tree = tree;
+  instance.element = built.element;
+  instance.tree = built.tree;
   instance.item = newItem;
-  instance.clonedNodes = clonedNodes;
+  instance.clonedNodes = built.clonedNodes;
 };
 
 export default {

package/runtime/iteration-utils.js

@@ -2,9 +2,13 @@
 import { ITERATION_START_REGEX, CONDITIONAL_START_REGEX } from './constants.js';
 
 // Resolve nested paths in state (e.g., "user.items" -> state.user.items)
+// Supports bracket notation: "teams[0].combatants" -> state.teams[0].combatants
 export const resolvePath = (obj, path) => {
   if (!path || !obj) return undefined;
-  return path.split('.').reduce((acc, part) => acc?.[part], obj);
+  // Split on dots and brackets: "a[0].b[1].c" → ["a", "0", "b", "1", "c"]
+  const parts = path.match(/[^.\[\]]+/g);
+  if (!parts) return undefined;
+  return parts.reduce((acc, part) => acc?.[part], obj);
 };
 
 // Clone template element preserving structure