@ape-egg/vibe 1.7.2 → 1.9.0

package/runtime/reconcile.js

@@ -0,0 +1,621 @@
+import { ITERATION_START_REGEX, CONDITIONAL_START_REGEX } from './constants.js';
+
+// Reconcile a live, Vibe-managed subtree against new source HTML, applying
+// the minimal mutation needed to align them. Vibe-owned regions (iterations,
+// conditionals, components) are treated as opaque — their internals are
+// state-driven and owned by iterate.js / conditionals.js / component.js.
+//
+// Walking strategy: tag-aligned, two-pointer. For each pair we either
+//   - match (recurse into element children, or update text/attrs in place),
+//   - skip (Vibe-owned region; jump both pointers past it),
+//   - insert (source has a node live doesn't), or
+//   - remove (live has a node source doesn't).
+// DOM identity survives wherever a match is found.
+
+const COMMENT = 8;
+const ELEMENT = 1;
+const TEXT = 3;
+
+const isIterationStart = (n) =>
+  n.nodeType === COMMENT && ITERATION_START_REGEX.test(n.textContent.trim());
+const isConditionalStart = (n) =>
+  n.nodeType === COMMENT && CONDITIONAL_START_REGEX.test(n.textContent.trim());
+const isRegionEnd = (n) => {
+  if (n.nodeType !== COMMENT) return false;
+  const t = n.textContent.trim();
+  return t === '/each' || t === '/if';
+};
+const isComponentWrapper = (n) =>
+  n.nodeType === ELEMENT &&
+  (n.tagName === 'COMPONENT' || (n.tagName === 'DIV' && n.classList?.contains('component')));
+
+// <slot> element pairs are opaque: the slot's children are owned by the
+// CALLER of the component, not the template being reconciled. So if source
+// is a component template (empty <slot></slot>) and live is the processed
+// wrapper (populated <slot>), recursing in would destroy the slot content.
+// Slot content is updated by the page-update path's component-pair handler,
+// which recurses INTO the slot (bypassing the slot element itself).
+const isSlotElement = (n) =>
+  n.nodeType === ELEMENT &&
+  (n.tagName === 'SLOT' || (n.tagName === 'DIV' && n.classList?.contains('slot')));
+
+// Two nodes "look matchable" — same nodeType, same tag for elements. Used
+// by the realignment lookahead below.
+const nodesMatch = (a, b) => {
+  if (!a || !b) return false;
+  if (a.nodeType !== b.nodeType) return false;
+  if (a.nodeType === ELEMENT) return a.tagName === b.tagName;
+  return true;
+};
+
+// At a mismatch, scan ahead within a small window on both sides to find a
+// near-match. Returns { dl, ds } where dl live nodes need to be removed and
+// ds source nodes need to be inserted before the realignment. Avoids the
+// cascading wholesale-replace failure mode where a single extra node on one
+// side destroys everything that follows.
+const REALIGN_WINDOW = 4;
+const findRealignment = (liveNodes, li, sourceNodes, si) => {
+  for (let total = 1; total <= 2 * REALIGN_WINDOW; total++) {
+    for (let dl = 0; dl <= Math.min(total, REALIGN_WINDOW); dl++) {
+      const ds = total - dl;
+      if (ds < 0 || ds > REALIGN_WINDOW) continue;
+      if (dl === 0 && ds === 0) continue;
+      if (nodesMatch(liveNodes[li + dl], sourceNodes[si + ds])) {
+        return { dl, ds };
+      }
+    }
+  }
+  return null;
+};
+
+// Trim leading/trailing whitespace-only text nodes. Mirrors vibe's
+// component.js, which calls .trim() on slot content before inlining — so
+// the live <slot> has no edge whitespace, but DOMParser preserves it on
+// the source side. Used when recursing into component slots.
+const trimWsEdges = (nodes) => {
+  let start = 0;
+  let end = nodes.length;
+  while (start < end && nodes[start].nodeType === TEXT && !nodes[start].textContent.trim()) start++;
+  while (end > start && nodes[end - 1].nodeType === TEXT && !nodes[end - 1].textContent.trim()) end--;
+  return nodes.slice(start, end);
+};
+
+// Find the <slot> in `el` that holds the source's slot content. Vibe wraps
+// slot content in a <slot> element after inlining; with nested components
+// (e.g. Layout uses Authorization as a wrapping component, and Layout's own
+// <slot> ends up inside Authorization's slot), there can be many <slot>s in
+// the wrapper. The right one is the slot whose first element child has the
+// same tag as the source's first element child (that's the user's content).
+const firstElementChildOf = (parent) => {
+  for (const n of parent.children || []) return n;
+  return null;
+};
+const firstElementOfNodes = (nodes) => {
+  for (const n of nodes) if (n.nodeType === ELEMENT) return n;
+  return null;
+};
+const findOwnSlot = (el, srcChildren) => {
+  const srcFirst = firstElementOfNodes(srcChildren);
+  if (!srcFirst) return null;
+  for (const slot of el.querySelectorAll('slot')) {
+    const liveFirst = firstElementChildOf(slot);
+    if (liveFirst?.tagName === srcFirst.tagName) return slot;
+  }
+  return null;
+};
+
+const hasBinding = (s) => /@\[.+?\]/.test(s);
+
+// Per-text-node cache of the last source text we saw (containing @[...]).
+// Used to surgically update STATIC portions of bound text — e.g. editing
+// "Level @[lvl]" to "Level: @[lvl]" — by extracting the binding's resolved
+// value from live using the OLD statics and re-applying with NEW statics.
+//
+// Caveat: the very first reconcile populates the cache without applying
+// anything, so a freshly-loaded page needs ONE wasted save to seed the
+// cache. Subsequent edits propagate.
+const boundSourceCache = new WeakMap();
+
+const updateBoundText = (live, newSrc, parent, log) => {
+  const oldSrc = boundSourceCache.get(live);
+  boundSourceCache.set(live, newSrc);
+  if (oldSrc === undefined || oldSrc === newSrc) return;
+
+  // Bindings must match in count + order to safely propagate static changes.
+  // (If the user added or reordered bindings, we can't infer where values go.)
+  const oldBindings = oldSrc.match(/@\[[^\]]+\]/g) || [];
+  const newBindings = newSrc.match(/@\[[^\]]+\]/g) || [];
+  if (oldBindings.length !== newBindings.length) return;
+  for (let i = 0; i < oldBindings.length; i++) {
+    if (oldBindings[i] !== newBindings[i]) return;
+  }
+
+  // Split each source by binding markers → static segments around each binding.
+  const oldStatic = oldSrc.split(/@\[[^\]]+\]/);
+  const newStatic = newSrc.split(/@\[[^\]]+\]/);
+
+  // Extract resolved values from live by stripping the old statics.
+  const liveText = live.textContent;
+  const values = [];
+  let pos = 0;
+  for (let i = 0; i < oldStatic.length - 1; i++) {
+    const before = oldStatic[i];
+    const after = oldStatic[i + 1];
+    if (liveText.slice(pos, pos + before.length) !== before) return;
+    pos += before.length;
+    let endPos;
+    if (i === oldStatic.length - 2) {
+      endPos = liveText.length - after.length;
+      if (endPos < pos || liveText.slice(endPos) !== after) return;
+    } else {
+      endPos = liveText.indexOf(after, pos);
+      if (endPos < 0) return;
+    }
+    values.push(liveText.slice(pos, endPos));
+    pos = endPos;
+  }
+
+  let result = newStatic[0];
+  for (let i = 0; i < values.length; i++) {
+    result += values[i] + newStatic[i + 1];
+  }
+  if (result === liveText) return;
+
+  live.textContent = result;
+  log.text++;
+  log.changes.push(`bound text in ${describe(parent)}: ${JSON.stringify(result.slice(0, 60))}`);
+};
+
+// Find the matching closing comment (`<!-- /each -->` or `<!-- /if -->`) for
+// a region starting at startIdx. Tracks depth so nested regions are handled.
+// `endLimit` bounds the search (defaults to nodes.length).
+const findRegionEnd = (nodes, startIdx, endLimit) => {
+  const limit = endLimit ?? nodes.length;
+  let depth = 1;
+  for (let i = startIdx + 1; i < limit; i++) {
+    const n = nodes[i];
+    if (isIterationStart(n) || isConditionalStart(n)) depth++;
+    else if (isRegionEnd(n)) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return limit - 1;
+};
+
+// Find the depth-0 `<!-- else -->` marker between an `<!-- if -->` and its
+// `<!-- /if -->`. Returns -1 if there's no else branch.
+const findElseMarker = (nodes, startIdx, endIdx) => {
+  let depth = 0;
+  for (let i = startIdx; i < endIdx; i++) {
+    const n = nodes[i];
+    if (n.nodeType !== COMMENT) continue;
+    const t = n.textContent.trim();
+    if (t.startsWith('if ') || t.startsWith('each ')) depth++;
+    else if (t === '/if' || t === '/each') depth--;
+    else if (depth === 0 && t === 'else') return i;
+  }
+  return -1;
+};
+
+// Framework-managed markers that reconcile must not strip on source absence.
+// `vibe-fouc` can appear as either an attribute or a class token (per
+// vibe.css and runtime/cleanup.js) — both forms are protected below.
+const PRESERVED_ATTRS = new Set(['vibe-fouc']);
+const PRESERVED_CLASSES = new Set(['vibe-fouc']);
+const isPreservedAttr = (name) => name.startsWith('data-vibe-') || PRESERVED_ATTRS.has(name);
+
+// Merge a source `class` value with any preserved tokens already on live, so
+// framework-managed tokens (e.g. .vibe-fouc) survive reconciliation.
+const mergeClass = (srcValue, live) => {
+  const tokens = new Set(srcValue.split(/\s+/).filter(Boolean));
+  for (const t of live.classList) {
+    if (PRESERVED_CLASSES.has(t)) tokens.add(t);
+  }
+  return [...tokens].join(' ');
+};
+
+// A description string for an element, for log readability.
+const describe = (el) => {
+  if (!el || el.nodeType !== ELEMENT) return String(el?.nodeName || el);
+  const id = el.id ? '#' + el.id : '';
+  const cls = el.classList?.length ? '.' + [...el.classList].join('.') : '';
+  return el.tagName.toLowerCase() + id + cls;
+};
+
+const reconcileAttributes = (live, src, log) => {
+  // Detect vibe name-bindings: source attribute NAMES containing @[...]
+  // (e.g. <page @[pageName]>). Vibe resolves these to dynamic attribute
+  // names at runtime, so the live element has whatever name `@[pageName]`
+  // evaluated to (e.g. `brawlers`). We can't add the literal `@[pagename]`
+  // attribute, and we can't reliably tell which live attribute maps to the
+  // binding — so when any name binding is present, skip the strip phase
+  // entirely. Vibe owns this element's attribute set.
+  let hasNameBinding = false;
+  for (const attr of src.attributes) {
+    if (attr.name.includes('@[')) { hasNameBinding = true; continue; }
+    // Source-bound attribute? hydrate owns its value — don't overwrite.
+    if (hasBinding(attr.value)) continue;
+    const next = attr.name === 'class' ? mergeClass(attr.value, live) : attr.value;
+    if (live.getAttribute(attr.name) !== next) {
+      live.setAttribute(attr.name, next);
+      log.attr++;
+      log.changes.push(`attr ${describe(live)} [${attr.name}=${JSON.stringify(next)}]`);
+    }
+  }
+  if (hasNameBinding) return;
+  for (const attr of [...live.attributes]) {
+    if (src.hasAttribute(attr.name)) continue;
+    if (isPreservedAttr(attr.name)) continue;
+    // data-X → X mirror: if source declares `data-foo`, don't strip live's
+    // `foo`. App code commonly mirrors data-* attrs into their canonical
+    // form (e.g. <img data-src="..."> with a runtime sync that sets `src`).
+    // Stripping `src` here would briefly blank the image until the next sync.
+    if (src.hasAttribute('data-' + attr.name)) continue;
+    // Source omitted `class` entirely — keep only preserved tokens (or drop).
+    if (attr.name === 'class') {
+      const kept = [...live.classList].filter((t) => PRESERVED_CLASSES.has(t));
+      if (kept.length) live.setAttribute('class', kept.join(' '));
+      else live.removeAttribute('class');
+      log.attr++;
+      log.changes.push(`attr ${describe(live)} [class trimmed]`);
+      continue;
+    }
+    live.removeAttribute(attr.name);
+    log.attr++;
+    log.changes.push(`attr ${describe(live)} [-${attr.name}]`);
+  }
+};
+
+// Reconcile a slice of liveParent's children (liveNodes[liStart..liEnd))
+// against srcNodes[siStart..sEnd). Mutations target liveParent. liveNodes
+// is a stable snapshot of liveParent.childNodes captured before mutation;
+// indices into it remain valid even after live nodes get removed/replaced.
+//
+// `insideIteration` propagates through recursion. When true, component
+// wrappers are left untouched: iterate.js owns re-rendering via state
+// changes, and pre-resolves `@[item.x]` props to literals before processing
+// — so the live/source prop shapes intentionally differ. Trying to re-mount
+// would insert a fresh <component src> outside iteration scope, losing
+// `item`/`index` and rendering `undefined`.
+const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart, sEnd, log, insideIteration = false) => {
+  let li = liStart;
+  let si = siStart;
+
+  while (li < liEnd || si < sEnd) {
+    const live = li < liEnd ? liveNodes[li] : null;
+    const src = si < sEnd ? srcNodes[si] : null;
+
+    if (!live) {
+      liveParent.appendChild(srcNodes[si].cloneNode(true));
+      log.insert++;
+      log.changes.push(`insert ${describe(srcNodes[si])} into ${describe(liveParent)}`);
+      si++;
+      continue;
+    }
+    if (!src) {
+      log.remove++;
+      log.changes.push(`remove ${describe(live)} from ${describe(liveParent)}`);
+      live.remove();
+      li++;
+      continue;
+    }
+
+    // <script> elements are side-effecting (execute on insertion) and vibe's
+    // component pipeline strips them after running. So source typically still
+    // has them while live doesn't. Skip orphan scripts on either side rather
+    // than insert/remove — preserves correctness without re-executing or
+    // accumulating dead scripts on each reconcile.
+    const srcIsScript = src?.nodeType === ELEMENT && src.tagName === 'SCRIPT';
+    const liveIsScript = live?.nodeType === ELEMENT && live.tagName === 'SCRIPT';
+    if (srcIsScript && !liveIsScript) { si++; continue; }
+    if (liveIsScript && !srcIsScript) { li++; continue; }
+
+    const liveIsRegion = isIterationStart(live) || isConditionalStart(live);
+    const srcIsRegion = isIterationStart(src) || isConditionalStart(src);
+
+    // Both pointers at a Vibe-owned region — recurse based on kind.
+    if (liveIsRegion && srcIsRegion) {
+      const liveEnd = findRegionEnd(liveNodes, li, liEnd);
+      const srcEnd = findRegionEnd(srcNodes, si, sEnd);
+      if (isConditionalStart(live) && isConditionalStart(src)) {
+        reconcileConditionalRegion(liveParent, liveNodes, li, liveEnd, srcNodes, si, srcEnd, log, insideIteration);
+      } else if (isIterationStart(live) && isIterationStart(src)) {
+        reconcileIterationRegion(liveParent, liveNodes, li, liveEnd, srcNodes, si, srcEnd, log);
+      }
+      // Mismatched region kinds (if vs each) → opaque, skip both.
+      li = liveEnd + 1;
+      si = srcEnd + 1;
+      continue;
+    }
+    // Source removed a region that's still live — drop the live region.
+    if (liveIsRegion) {
+      const end = findRegionEnd(liveNodes, li, liEnd);
+      for (let k = li; k <= end; k++) {
+        log.remove++;
+        liveNodes[k].remove();
+      }
+      log.changes.push(`remove vibe region from ${describe(liveParent)}`);
+      li = end + 1;
+      continue;
+    }
+    // Source added a new region — insert it wholesale; MutationObserver
+    // will pick up the new comments + children and process them.
+    if (srcIsRegion) {
+      const end = findRegionEnd(srcNodes, si, sEnd);
+      for (let k = si; k <= end; k++) {
+        liveParent.insertBefore(srcNodes[k].cloneNode(true), live);
+        log.insert++;
+      }
+      log.changes.push(`insert vibe region into ${describe(liveParent)}`);
+      si = end + 1;
+      continue;
+    }
+
+    // Component wrappers: the wrapper itself + its inlined template are
+    // opaque (state-driven, owned by component.js + the surrounding hydrate).
+    // But the SLOT content is user-authored static HTML — recurse into it so
+    // edits to a page's slot content (e.g. inside Layout's <slot>) reconcile
+    // surgically just like top-level static content.
+    //
+    // First, check for PROP changes. If the HMR spy in vite-plugin-vibe has
+    // stashed the original authored attrs on live._vibeProps, compare them to
+    // the source's attrs. Any diff means the callsite re-authored a prop —
+    // re-mount by replacing the wrapper with a fresh <component src> so
+    // component.js re-fetches and re-inlines with the new values.
+    if (isComponentWrapper(live) && isComponentWrapper(src)) {
+      // Inside an iteration instance, iterate.js owns re-mounting: props are
+      // pre-resolved against iteration scope before processComponent runs, so
+      // source `hp="@[item.x]"` intentionally doesn't match live `hp="50"`.
+      // Skip the prop-diff + slot recursion entirely; iteration re-renders
+      // the instance when its state changes.
+      if (insideIteration) {
+        li++;
+        si++;
+        continue;
+      }
+      if (live._vibeProps && src.hasAttribute('src')) {
+        // vibe-fouc is transient and may appear as either an attribute or a
+        // class token (see runtime/cleanup.js#FOUC_CLASS_OR_ATTR) — normalize
+        // both out so a FOUC flip never reads as a prop change.
+        const srcProps = {};
+        for (const a of src.attributes) {
+          if (a.name === 'vibe-fouc') continue;
+          if (a.name === 'class') {
+            const kept = a.value.split(/\s+/).filter((t) => t && t !== 'vibe-fouc');
+            if (kept.length) srcProps.class = kept.join(' ');
+            continue;
+          }
+          srcProps[a.name] = a.value;
+        }
+        const liveProps = live._vibeProps;
+        const liveKeys = Object.keys(liveProps);
+        const srcKeys = Object.keys(srcProps);
+        const diff =
+          liveKeys.length !== srcKeys.length ||
+          liveKeys.some((k) => liveProps[k] !== srcProps[k]) ||
+          srcKeys.some((k) => !(k in liveProps));
+
+        if (diff) {
+          const fresh = document.createElement(src.tagName);
+          if (src.tagName === 'DIV') fresh.className = 'component';
+          for (const [name, value] of Object.entries(srcProps)) {
+            fresh.setAttribute(name, value);
+          }
+          fresh.setAttribute('vibe-fouc', '');
+          const slotHtml = src.innerHTML.trim();
+          fresh._vibeSlotContent = slotHtml;
+          // Plugin mirror: _vibeSlotContent is deleted synchronously by
+          // vibe's processSingle, so the spy falls back to innerHTML (empty)
+          // on the next mount cycle. Without this, the next re-mount would
+          // read an empty slot. See vite-plugin-vibe for the symmetric read.
+          fresh._vibePluginSlot = slotHtml;
+          live.replaceWith(fresh);
+          log.replace++;
+          log.changes.push(
+            `re-mount ${describe(live)} (prop change) live=${JSON.stringify(liveProps)} src=${JSON.stringify(srcProps)}`,
+          );
+          li++;
+          si++;
+          continue;
+        }
+      }
+
+      const srcChildren = trimWsEdges([...src.childNodes]);
+      const liveSlot = findOwnSlot(live, srcChildren);
+      if (liveSlot) reconcileChildren(liveSlot, srcChildren, log, insideIteration);
+      li++;
+      si++;
+      continue;
+    }
+
+    // <slot> elements are opaque (slot content is caller-owned).
+    if (isSlotElement(live) && isSlotElement(src)) {
+      li++;
+      si++;
+      continue;
+    }
+
+    // Text nodes — update only if source is static. Bound text uses the
+    // per-node source cache to surgically re-apply changed STATICS while
+    // preserving the binding's resolved value (see updateBoundText above).
+    if (live.nodeType === TEXT && src.nodeType === TEXT) {
+      if (hasBinding(src.textContent)) {
+        updateBoundText(live, src.textContent, liveParent, log);
+      } else if (live.textContent !== src.textContent) {
+        live.textContent = src.textContent;
+        log.text++;
+        const preview = src.textContent.trim().slice(0, 60);
+        log.changes.push(`text in ${describe(liveParent)}: ${JSON.stringify(preview)}`);
+      }
+      li++;
+      si++;
+      continue;
+    }
+
+    // Plain comment nodes (non-region) — update text if changed.
+    if (live.nodeType === COMMENT && src.nodeType === COMMENT) {
+      if (live.textContent !== src.textContent) {
+        live.textContent = src.textContent;
+        log.text++;
+      }
+      li++;
+      si++;
+      continue;
+    }
+
+    // Element pair, same tag → reconcile in place. Identity preserved.
+    if (live.nodeType === ELEMENT && src.nodeType === ELEMENT &&
+        live.tagName === src.tagName) {
+      reconcileAttributes(live, src, log);
+      reconcileChildren(live, [...src.childNodes], log, insideIteration);
+      li++;
+      si++;
+      continue;
+    }
+
+    // Before falling through to wholesale replace, try a small lookahead
+    // realignment — handles cases where one side has an inserted/removed
+    // node that would otherwise cascade into a chain of bad replaces.
+    const align = findRealignment(liveNodes, li, srcNodes, si);
+    if (align && li + align.dl < liEnd && si + align.ds < sEnd) {
+      for (let i = 0; i < align.dl; i++) {
+        const n = liveNodes[li + i];
+        if (n.nodeType === ELEMENT && n.tagName === 'SCRIPT') continue; // see orphan-script note above
+        log.remove++;
+        log.changes.push(`remove (extra) ${describe(n)} from ${describe(liveParent)}`);
+        n.remove();
+      }
+      const anchor = liveNodes[li + align.dl];
+      for (let i = 0; i < align.ds; i++) {
+        const n = srcNodes[si + i];
+        if (n.nodeType === ELEMENT && n.tagName === 'SCRIPT') continue;
+        log.insert++;
+        log.changes.push(`insert (new) ${describe(n)} into ${describe(liveParent)}`);
+        liveParent.insertBefore(n.cloneNode(true), anchor);
+      }
+      li += align.dl;
+      si += align.ds;
+      continue;
+    }
+
+    // Truly mismatched (no realignment possible) — replace.
+    log.replace++;
+    log.changes.push(`replace ${describe(live)} → ${describe(src)} in ${describe(liveParent)}`);
+    live.replaceWith(src.cloneNode(true));
+    li++;
+    si++;
+  }
+};
+
+const reconcileChildren = (liveParent, sourceNodes, log, insideIteration = false) => {
+  const liveNodes = [...liveParent.childNodes];
+  reconcileRange(liveParent, liveNodes, 0, liveNodes.length, sourceNodes, 0, sourceNodes.length, log, insideIteration);
+};
+
+// Walk a conditional region: live has one active branch; source has the
+// if-branch and (optionally) the else-branch separated by `<!-- else -->`.
+// Choose the source branch whose first element tag matches live's first
+// element tag, then recurse range-vs-range. If neither matches, leave the
+// region alone (opaque) — vibe will refresh it on next state change.
+const reconcileConditionalRegion = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart, sEnd, log, insideIteration = false) => {
+  // Source branches.
+  const elseIdx = findElseMarker(srcNodes, siStart + 1, sEnd);
+  const ifStart = siStart + 1;
+  const ifEnd = elseIdx === -1 ? sEnd : elseIdx;
+  const elseStart = elseIdx === -1 ? sEnd : elseIdx + 1;
+  const elseEnd = sEnd;
+
+  // First element on each side decides which branch is live.
+  let liveFirstEl = null;
+  for (let i = liStart + 1; i < liEnd; i++) {
+    if (liveNodes[i].nodeType === ELEMENT) { liveFirstEl = liveNodes[i]; break; }
+  }
+  if (!liveFirstEl) return; // empty branch; nothing to walk
+
+  let chosenStart = -1;
+  let chosenEnd = -1;
+  for (let i = ifStart; i < ifEnd; i++) {
+    if (srcNodes[i].nodeType === ELEMENT) {
+      if (srcNodes[i].tagName === liveFirstEl.tagName) {
+        chosenStart = ifStart; chosenEnd = ifEnd;
+      }
+      break;
+    }
+  }
+  if (chosenStart === -1) {
+    for (let i = elseStart; i < elseEnd; i++) {
+      if (srcNodes[i].nodeType === ELEMENT) {
+        if (srcNodes[i].tagName === liveFirstEl.tagName) {
+          chosenStart = elseStart; chosenEnd = elseEnd;
+        }
+        break;
+      }
+    }
+  }
+  if (chosenStart === -1) return; // no matching branch; leave opaque
+
+  reconcileRange(
+    liveParent, liveNodes,
+    liStart + 1, liEnd,
+    srcNodes, chosenStart, chosenEnd,
+    log,
+    insideIteration,
+  );
+};
+
+// Walk an iteration region: live has N rendered instances of the source's
+// template. For each live top-level ELEMENT (rendered instance root), walk
+// it against the corresponding template element (modulo template length).
+// Static text/attr changes propagate to all instances; bound text/attrs
+// are left to vibe (it owns those values via state).
+//
+// Caveat: if the iteration's array state changes after this update, vibe
+// re-renders from its stored template (which we don't update), reverting
+// our changes. The user can save again to re-propagate; perfect propagation
+// would require updating vibe's iteration template metadata directly.
+const reconcileIterationRegion = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart, sEnd, log) => {
+  // Per-instance attr/children walk so static text/attr tweaks propagate
+  // without a full re-render. Component callsites inside the template are
+  // NOT reconciled here — iterate.js caches the template at mount time, and
+  // the callsite's live wrapper has iteration-resolved props that never
+  // match the authored source. Re-authored component props inside an
+  // iteration need a page refresh to take effect (known HMR limitation).
+  const tplEls = [];
+  for (let i = siStart + 1; i < sEnd; i++) {
+    if (srcNodes[i].nodeType === ELEMENT) tplEls.push(srcNodes[i]);
+  }
+  if (!tplEls.length) return;
+
+  let instanceIdx = 0;
+  for (let i = liStart + 1; i < liEnd; i++) {
+    const liveEl = liveNodes[i];
+    if (liveEl.nodeType !== ELEMENT) continue;
+    const tplEl = tplEls[instanceIdx % tplEls.length];
+    instanceIdx++;
+    if (liveEl.tagName !== tplEl.tagName) continue; // shape changed; skip
+    reconcileAttributes(liveEl, tplEl, log);
+    reconcileChildren(liveEl, [...tplEl.childNodes], log, true);
+  }
+};
+
+// Public entry point. Parses `source` (HTML string or DOM element) into an
+// inert <template>, then walks `target`'s children against it.
+//
+// Returns a Promise that resolves to a mutation summary object once vibe's
+// MutationObserver has settled. The summary is `{ text, attr, insert,
+// remove, replace, changes }` — counts plus a human-readable list of what
+// was changed (useful for HMR debug logging).
+export const reconcile = (target, source) => {
+  const live = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!live) return Promise.resolve({ text: 0, attr: 0, insert: 0, remove: 0, replace: 0, changes: [] });
+
+  const log = { text: 0, attr: 0, insert: 0, remove: 0, replace: 0, changes: [] };
+  const tpl = document.createElement('template');
+  tpl.innerHTML = typeof source === 'string' ? source : source.outerHTML;
+  reconcileChildren(live, [...tpl.content.childNodes], log);
+
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve(log)));
+  });
+};

package/runtime/state.js

@@ -1,11 +1,29 @@
 // Track which objects are already proxied to avoid double-wrapping
 const proxyCache = new WeakMap();
 
+// Batching: collect mutations and flush once per microtask
+let pendingFlush = false;
+let flushCallback = null;
+const changedProps = new Set();
+
+const scheduleFlush = () => {
+  if (!pendingFlush) {
+    pendingFlush = true;
+    queueMicrotask(() => {
+      pendingFlush = false;
+      const props = [...changedProps];
+      changedProps.clear();
+      if (flushCallback) flushCallback(props);
+    });
+  }
+};
+
 // Deep proxy: recursively wrap nested objects and arrays
 const createDeepProxy = (target, rerender, rootState = null, rootProp = null) => {
   // For root level, rootState is the target itself
   if (rootState === null) {
     rootState = target;
+    flushCallback = (props) => rerender(props);
   }
 
   // Check cache first
@@ -19,13 +37,11 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
 
       // Only trigger rerender if value actually changed
       if (oldValue !== value) {
-        // Perform the mutation
         const ref = Reflect.set(obj, prop, value);
 
-        // Trigger rerender with changed state
-        // If we're nested, use the root prop; otherwise use the prop itself
-        const changedProp = rootProp || prop;
-        rerender({ [changedProp]: rootState[changedProp] }, null);
+        // Track which root-level property changed (for selective extraction)
+        changedProps.add(rootProp || prop);
+        scheduleFlush();
 
         return ref;
       }
@@ -37,8 +53,11 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
     get(target, prop) {
       const value = Reflect.get(target, prop);
 
-      // Don't proxy non-objects, functions, or null
-      if (value === null || typeof value !== 'object' || typeof value === 'function') {
+      // Don't proxy non-objects, functions, null, or Promises.
+      // Promises aren't reactive state; wrapping them would also violate
+      // the Proxy invariant when exposed as non-writable/non-configurable
+      // properties (e.g. $.ready).
+      if (value === null || typeof value !== 'object' || typeof value === 'function' || value instanceof Promise) {
         return value;
       }