@ape-egg/vibe 4.0.1 → 4.1.1

package/runtime/iterate.js

@@ -1,7 +1,7 @@
 import parse from './parse.js';
 import affected, { nodeSubscriberOf } from './affected.js';
 import hydrate from './hydrate.js';
-import { resolvePath, getItemKey, computeDiff, iterPropWrappersOf, bumpIterPropGeneration } from './iteration-utils.js';
+import { resolvePath, getItemKey, computeDiff, iterPropWrappersOf, bumpIterPropGeneration, markBoundValues } from './iteration-utils.js';
 import { resolveThisPath, evalInScope, findComponentIdForElement, rememberScopedKeys, overlayKeysOf } from './utils.js';
 import { recordRead, beginTracking, endTracking, pruneDisconnected, markAlways } from './tracking.js';
 import { managedNodes, extractDependencies } from './conditionals.js';
@@ -15,25 +15,12 @@ import {
   THIS_PROP_REGEX,
 } from './constants.js';
 
-// Pre-compiled iteration optimization (production)
 import * as compiled from './pre-compiled-iterations.js';
 
 import { generateComponentId, executeCompiledComponentScriptsIn } from './component.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 -->.
-//
-// 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.
-// Decode them back before wrapping @[expr] in ${...} for the template literal.
 const decodeEntities = (s) => s
   .replace(/&lt;/g, '<')
   .replace(/&gt;/g, '>')
@@ -52,27 +39,12 @@ const hasNestedStructures = (tree) => {
   return false;
 };
 
-// Batch render template-literal-interpolates `@[expr]` as `${expr}` — that
-// stringifies object/array values, which breaks `<component src>` props that
-// rely on resolveIterationComponentProps to stash non-primitives in the
-// registry. Templates carrying any `<component src>` go through the
-// clone+hydrate path instead.
 const hasComponentSrc = (templateEl) =>
   !!templateEl.querySelector?.('component[src], div.component[src]');
 
-// A compiled inlined component with its own setup script carries component-local
-// state (`component({...})` → `$._cN`). Batch render emits one shared HTML string
-// per row, which would duplicate the baked `_cN` id across rows and collapse
-// their state into one bucket. Route these through the clone path, where
-// initializeBlock isolates each row's component ids.
 const hasInlinedComponentScript = (templateEl) =>
   !!templateEl.querySelector?.('script[type="vibe-module"]');
 
-// `__vibe.forceClonePath` is a debug/test escape hatch — set it 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.__vibe?.forceClonePath &&
   !hasNestedStructures(template) &&
@@ -80,17 +52,7 @@ const canUseBatchRender = (template) =>
   !hasComponentSrc(template.element) &&
   !hasInlinedComponentScript(template.element);
 
-// 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',
@@ -100,10 +62,6 @@ const BATCH_ATTR_BINDING_REGEX = new RegExp(
   'g',
 );
 
-// Apply fn to tag spans only (`<el ...>`, quote-aware so a `>` inside an
-// attribute value doesn't end the span), leaving text spans and comments
-// untouched. Used to scope the name-binding rewrite to positions where a
-// name binding can actually occur.
 const mapTagSpans = (html, fn) => {
   let out = '';
   let i = 0;
@@ -134,58 +92,22 @@ const mapTagSpans = (html, fn) => {
   return out;
 };
 
-// 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.
-// Root-position `_cN` component references inside a binding expression —
-// string literals are consumed whole and left untouched (an `_cN` inside a
-// quoted string is content, not a reference — same discipline as
-// compileExpression's alternation in utils.js; the two renderers are
-// lockstep-equivalent by contract). Already-canonical `$['_cN']` forms and
-// property accesses stay untouched via the lookbehind.
 const CID_ROOT_REGEX =
   /('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|(?<![\w$.])_c(\d+)\b/g;
 
 export const canonicalizeComponentIds = (expr) =>
   expr.replace(CID_ROOT_REGEX, (m, literal, id) => (literal !== undefined ? literal : `$['_c${id}']`));
 
-// Name-binding emission: resolve the expression under the `_e` guard, emit
-// ` value=""` when truthy, nothing otherwise.
 const nameBindingEmit = (exprSrc) =>
   '${(()=>{const _v=_e(()=>(' + exprSrc + '));return _v?\' \'+_v+\'=""\':\'\';})()}';
 
 export 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 = [];
@@ -212,20 +134,12 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
 
   let templateHtml = tplClone.innerHTML.trim();
 
-  // A name-binding the compiler relocated into `data-vibe-namebind` (its expression has
-  // whitespace, so it can't be an HTML attribute name) — restore the `@[expr]=""` form
-  // the name-binding pass below understands. Safe in this template STRING: only the
-  // resolved value (no whitespace) ever reaches innerHTML. Mirrors the clone path, which
-  // reads the same binding from the manifest's nameBindings.
   templateHtml = templateHtml.replace(
     /\sdata-vibe-namebind="((?:@\[(?:[^[\]'"]|\[[^\]]*\]|'[^']*'|"[^"]*")+\])+)"/g,
     (_, bindings) =>
       bindings.replace(/@\[(?:[^[\]'"]|\[[^\]]*\]|'[^']*'|"[^"]*")+\]/g, (b) => ' ' + b + '=""'),
   );
 
-  // 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) =>
@@ -233,12 +147,6 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
     );
   }
 
-  // Compiler-stamped component references (`_cN.x` in SPA fragments) resolve
-  // through `$` at call time — the mirror of evalInScope's id canonicalization.
-  // Baked as bare identifiers they'd be a ReferenceError whenever the id is
-  // missing from the compile-time state-key snapshot (a fragment iteration can
-  // hydrate before its component script registers), and a state key that
-  // arrives later would never be picked up by the cached batch function.
   BINDING_REGEX.lastIndex = 0;
   templateHtml = templateHtml.replace(BINDING_REGEX, (_, expr) =>
     '@[' + canonicalizeComponentIds(expr) + ']',
@@ -251,25 +159,6 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
 
   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 `=`)
-  // — but a TEXT-position binding on its own line is also whitespace-bounded,
-  // so the pass runs only over tag spans (mapTagSpans): name bindings can only
-  // exist inside a tag.
-  //
-  // 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 = mapTagSpans(code, (tag) => tag.replace(BATCH_NAME_BINDING_REGEX, (_, _ws, expr) => {
     let decExpr = decodeEntities(expr);
@@ -291,11 +180,6 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
     return nameBindingEmit('_walkCi(' + ciHead + ',' + tailJSON + ')');
   }));
 
-  // 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)) {
@@ -304,21 +188,8 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
     return '${_e(()=>(' + decExpr + ')) ? \' ' + attrName + '=""\' : \'\'}';
   });
 
-  // Remaining @[…] markers — text content and partial-binding attribute
-  // values like `href="/items/@[id]/edit"`.
   code = code.replace(BINDING_REGEX, (_, expr) => '${_e(()=>(' + 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.
-  // Per-expression failure contract, mirroring evalInScope: an expression
-  // that can't evaluate yet (component state not registered, alias mid-swap)
-  // renders '' and the next flush corrects it — it must never throw out of
-  // the batch loop and abort every row after it. Non-throwing values pass
-  // through untouched, so template-literal coercion stays identical.
   const evalGuardSrc = "const _e = (f) => { try { return f(); } catch { return ''; } };";
   const ciWalkerSrc = needsCiWalker
     ? `const _walkCi = (cur, segs) => {
@@ -354,27 +225,11 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
   return { fn, domPropertyWrites };
 };
 
-// Registry for non-primitive iteration prop snapshots. Lives on `window` (not
-// on `$`) so it doesn't pollute user-visible state enumeration, but is still
-// reachable from binding expressions because `window` is in evalInScope's
-// known-globals list. Each entry is freed when the owning component element
-// is detached (see releaseOrphanedIterationProps).
-//
-// The name is intentionally all-lowercase. resolveIterationComponentProps
-// injects `@[window.__vibe.iterProps._pN]` into the component's bindings, and
-// prop substitution carries that accessor into the template's own bindings —
-// including name-bindings (`<icon @[props.element]>`). HTML lowercases
-// attribute names, so a camelCase accessor would arrive at hydrate as
-// `window.__vibe.iterProps` and resolve to undefined, silently dropping the
-// attribute. Keeping the global lowercase makes it survive that normalization.
 let __vibeIterPropCounter = 0;
 const ensureIterPropsRegistry = () => {
   return ((window.__vibe ??= {}).iterProps ??= {});
 };
 
-// Walk a removed subtree and free any iteration-prop registry slots stashed
-// on `<component>` elements inside it. Called from the mutation-observer
-// cleanup path after DOM detachment.
 export const releaseOrphanedIterationProps = (nodes) => {
   if (!window.__vibe?.iterProps) return;
   for (const node of nodes) {
@@ -390,22 +245,8 @@ export const releaseOrphanedIterationProps = (nodes) => {
   }
 };
 
-// Slot content projected into a <component src> is captured raw (`_vibeSlotContent`)
-// and inlined only when processComponent runs — by which point the row's iteration
-// scope is gone. Any `@[...]` in that content rooted in a loop alias (item/index/
-// outer) or `this` therefore can't resolve later: value bindings render undefined
-// and name-bindings (`<icon @[row.icon]>`) never set their attribute. Pre-resolve
-// those into registry-backed global refs here — the same snapshot mechanism the
-// component's own prop attributes use — so the inlined slot hydrates against the
-// right values and the row's update path refreshes them in place (the wrapper
-// inherits `_vibeIterPropExprs`/`data-vibe-iter-prop`, so refreshIterationComponentProps
-// re-evaluates them on each item change). Globals-only bindings are left raw; they
-// resolve through the normal reactive path against the inlined component's scope.
 const SLOT_DIRECTIVE_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
 
-// Substitute an identifier only outside string literals — the same contract as
-// component.js's prop substitution: an alias that also appears inside a quoted
-// string ('materials' containing the alias name) must be left intact.
 const STRING_LITERAL_REGEX = /(['"`])(?:\\.|(?!\1)[^\\])*\1/g;
 const substituteOutsideStrings = (expr, idRegex, replacement) => {
   let out = '';
@@ -424,9 +265,6 @@ const resolveSlotContentBindings = (el, scopedState, aliases) => {
   if (!html || (!html.includes('@[') && !html.includes('<!--'))) return;
   const registry = ensureIterPropsRegistry();
   const idByExpr = new Map();
-  // Snapshot one expression into a registry slot, reusing the slot for repeat
-  // occurrences. Returns undefined (leave raw) when evaluation fails or yields
-  // undefined — same fail-safe as resolveIterationComponentProps.
   const snapshot = (expr) => {
     let id = idByExpr.get(expr);
     if (id === undefined) {
@@ -453,25 +291,8 @@ const resolveSlotContentBindings = (el, scopedState, aliases) => {
     const id = snapshot(expr);
     return id === undefined ? whole : `@[window.__vibe.iterProps.${id}]`;
   });
-  // Directive comments in slot content — <!-- if -->, <!-- else if -->,
-  // <!-- each --> — hit the same wall as @[...] bindings: after processComponent
-  // inlines the template, the wrapper's subtree is re-processed against global
-  // state, where the loop aliases don't resolve and every branch renders empty
-  // (the battleborn rewards-window icons). Route each alias the expression
-  // reads through its own registry slot (`drop.kind === 'materials'` →
-  // `window.__vibe.iterProps._pN.kind === ...`), so the inlined directive
-  // evaluates against the row's values in any scope. Updates need no extra
-  // wiring: refreshIterationComponentProps re-snapshots the alias per row
-  // update, the rewritten expression records no state read so its subscriber
-  // re-dispatches from the tracking always-bucket on every flush, and the
-  // affected() pass over the wrapper's tree stamps that subscriber's lastScope
-  // with the row's merged scope — so a branch flip mounts with the loop
-  // aliases reachable. A registry-backed <!-- each --> is driven by
-  // forceRegistryBackedIterationUpdates like any other registry iteration.
   if (aliases?.size) {
     rewritten = rewritten.replace(SLOT_DIRECTIVE_REGEX, (whole, kw, expr) => {
-      // An each's alias clause introduces fresh names — only its array
-      // expression is rewritable.
       const asMatch = kw === 'each' && expr.match(/^([^]*?)\s+as\s+([^]*)$/);
       const original = asMatch ? asMatch[1] : expr;
       let code = original;
@@ -493,12 +314,6 @@ const resolveSlotContentBindings = (el, scopedState, aliases) => {
   }
 };
 
-// Substitute the loop-scoped `@[expr]` parts of a component's src with their
-// values from this block's scope. Only exprs whose dependencies include a loop
-// alias are resolved — everything else keeps its binding form (see the caller
-// in initializeBlock for why). An expr that evaluates to undefined stays raw
-// too, so the unresolved-src invariant keeps the wrapper unfetchable instead
-// of composing a garbage URL.
 const resolveScopedSrc = (el, scopedState, scopeKeys) => {
   const src = el.getAttribute('src');
   BINDING_REGEX.lastIndex = 0;
@@ -511,21 +326,6 @@ const resolveScopedSrc = (el, scopedState, scopeKeys) => {
   if (resolved !== src) el.setAttribute('src', resolved);
 };
 
-// For <component src> elements inside an iteration instance, evaluate any
-// `@[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.__vibe.iterProps._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
-// 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.
 export const resolveIterationComponentProps = (nodes, scopedState, aliases) => {
   for (let n = 0; n < nodes.length; n++) {
     const node = nodes[n];
@@ -542,18 +342,6 @@ export const resolveIterationComponentProps = (nodes, scopedState, aliases) => {
         const match = attr.value.match(/^@\[(.+)\]$/);
         if (!match) continue;
         const expr = match[1];
-        // The registry snapshot only exists to carry iteration-local values
-        // (item/index/outer aliases, or component-local `this.X`) past the point
-        // where processComponent inlines the component and that scope is gone.
-        // A prop whose expression references ONLY globals doesn't need it — and
-        // routing it through the snapshot would freeze it, since the slot is
-        // refreshed solely on array diffs (the Brawling-loader freeze: a prop
-        // bound to `elapsedMilliseconds` in a row whose array never changes).
-        // Leave such a binding raw so the normal reactive path tracks the
-        // global, but still tag the wrapper: `_vibeIterPropExprs` makes index.js
-        // stamp `_vibeIterTree`, which is what lets affected.js's
-        // walkInlinedComponentTrees descend in and re-hydrate the raw binding on
-        // a global-state change.
         const usesLocalScope =
           /\bthis\b/.test(expr) ||
           (aliases && extractDependencies(expr).some((d) => aliases.has(d)));
@@ -575,7 +363,6 @@ export const resolveIterationComponentProps = (nodes, scopedState, aliases) => {
           (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
         }
       }
       resolveSlotContentBindings(el, scopedState, aliases);
@@ -583,13 +370,6 @@ export const resolveIterationComponentProps = (nodes, scopedState, aliases) => {
   }
 };
 
-// Walk a row's live cloned nodes and invoke `fn` for every inlined-component
-// wrapper carrying `marker` — the resolved node itself plus any
-// `[data-vibe-iter-prop]` descendant that carries it. The prop-refresh and
-// inlined-hydrate passes are identical except for this marker and the per-wrapper
-// work, so they share this walk. (`[data-vibe-iter-prop]` always implies
-// `_vibeIterPropExprs`, set together at mount, so filtering descendants by the
-// marker matches the historical "take all, skip those without exprs" behavior.)
 const forEachIterWrapper = (clonedNodes, marker, fn) => {
   for (let n = 0; n < clonedNodes.length; n++) {
     const node = liveNode(clonedNodes[n]);
@@ -602,17 +382,6 @@ const forEachIterWrapper = (clonedNodes, marker, fn) => {
   }
 };
 
-// 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.
-// Returns the set of registry slot ids whose value actually changed this
-// refresh. A slot holding the same reference (e.g. a static ability array on a
-// combatant that only moved) is a no-op, so forceRegistryBackedIterationUpdates
-// can skip re-diffing the nested iteration it feeds — the dominant cost when a
-// row carries large static nested iterations.
 const refreshIterationComponentProps = (clonedNodes, scopedState) => {
   const changed = new Set();
   const registry = ensureIterPropsRegistry();
@@ -620,54 +389,24 @@ const refreshIterationComponentProps = (clonedNodes, scopedState) => {
     for (const { id, expr } of el._vibeIterPropExprs) {
       try {
         const value = evalInScope(expr, scopedState, el);
-        // Don't clobber a slot with undefined — mirrors the mount-time guard in
-        // resolveIterationComponentProps. forEachIterWrapper reaches every
-        // [data-vibe-iter-prop] descendant, including components owned by a
-        // DEEPER iteration (e.g. a cell component inside a nested each). Their
-        // prop expressions reference the inner each's alias, which isn't in this
-        // (outer) row's scope, so they evaluate to undefined here. Skipping keeps
-        // the value the inner iteration's own update already set with the correct
-        // scope, instead of wiping it to undefined and leaving raw @[...] bindings.
         if (value === undefined) continue;
         if (registry[id] !== value) {
           registry[id] = value;
           changed.add(id);
         }
       } catch {
-        // Leave previous registry value in place — same fail-safe as
-        // resolveIterationComponentProps's mount-time path.
       }
     }
   });
   return changed;
 };
 
-// Walk an inlined component's parsed tree and force `updateIteration` on any
-// iteration node whose arrayPath resolves through the iteration-prop registry
-// (`window.__vibe.iterProps._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.
-// Registry-backed CONDITIONALS (rewritten by resolveSlotContentBindings) need
-// no counterpart here: their evaluation records no state read, so they sit in
-// the tracking always-bucket and re-dispatch on every flush — and the
-// affected() pass below stamps their subscriber's lastScope with this row's
-// merged scope, so the dispatch flips the branch with the loop aliases in
-// reach (letting the mounting branch hydrate alias bindings whose build-time
-// snapshot was undefined, e.g. drop.item.icon before an icon exists).
 const REGISTRY_SLOT_REGEX = /__vibe\.iterProps\.(_p\d+)/;
 const forceRegistryBackedIterationUpdates = (tree, state, manifest, parentScope, changedSlots) => {
   if (!tree) return;
   if (tree.type === 'iteration') {
     const arrPath = tree.meta?.arrayPath;
     const slot = arrPath && arrPath.match(REGISTRY_SLOT_REGEX);
-    // Skip iterations whose backing slot didn't change this cycle. changedSlots
-    // is undefined only on legacy/unguarded calls — fall back to always-update.
     if (slot && (!changedSlots || changedSlots.has(slot[1]))) {
       updateIteration(tree, state, state, manifest, parentScope);
     }
@@ -679,12 +418,6 @@ const forceRegistryBackedIterationUpdates = (tree, 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, changedSlots) => {
   forEachIterWrapper(clonedNodes, '_vibeIterTree', (wrapper) => {
     const tree = wrapper._vibeIterTree;
@@ -692,20 +425,10 @@ const hydrateInlinedIterationComponents = (clonedNodes, oldState, newState, mani
     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 `affected()` can't see. Update only the
-    // iterations whose slot actually changed this cycle (changedSlots).
     forceRegistryBackedIterationUpdates(tree, newState, manifest, {}, changedSlots);
   });
 };
 
-// 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;
@@ -730,8 +453,6 @@ const applyDomPropertyWrites = (instances, array, state, itemAlias, indexAlias,
             if (el.getAttribute(prop) !== str) el.setAttribute(prop, str);
           }
         } else if (value) {
-          // checked/selected are boolean — presence/absence is the truthful
-          // attribute form, matching the clone path in hydrate.js.
           if (el.getAttribute(prop) !== '') el.setAttribute(prop, '');
         } else if (el.hasAttribute(prop)) {
           el.removeAttribute(prop);
@@ -742,14 +463,6 @@ const applyDomPropertyWrites = (instances, array, state, itemAlias, indexAlias,
   }
 };
 
-// Resolve the loop's array against the LIVE `$` proxy root (not the plain
-// diff-snapshot the pipeline renders against — see extractPlainValue in
-// index.js). The plain clones are never reference-identical to the proxy
-// elements the app sees through `$`, so a loop var that flows into an `on*`
-// handler must come from here for `item === $.arr[i]` to hold. Returns null
-// when unresolvable (no live root yet, a derivation that builds fresh objects,
-// or a nested loop whose source hangs off an outer plain item) — callers fall
-// back to the plain item, which is no worse than the pre-fix behavior.
 const resolveLiveArray = (iterationNode, manifest, parentScope = {}) => {
   const liveRoot = (manifest && manifest.__live) || globalThis.$;
   if (!liveRoot) return null;
@@ -768,11 +481,6 @@ const resolveLiveArray = (iterationNode, manifest, parentScope = {}) => {
 const liveItemAt = (liveArray, index, fallback) =>
   liveArray && index < liveArray.length ? liveArray[index] : fallback;
 
-// Refresh each instance's `liveItem` (the live `$`-proxy element handed to
-// loop-scoped `$scope` handlers, set when the instance was built) and stamp
-// scope. Re-resolving here keeps `liveItem` correct after the diff reorders or
-// updates instances. Diffing still keys off the plain `inst.item`; only the
-// handler-facing `$scope` value is live.
 const stampScopes = (iterationNode, manifest, parentScope = {}) => {
   const liveArray = resolveLiveArray(iterationNode, manifest, parentScope);
   const instances = iterationNode.runtime.instances;
@@ -797,17 +505,13 @@ const renderBatch = (iterationNode, array, state, parent, endComment, parentScop
   const { batchFn, stateKeys, domPropertyWrites } = iterationNode.runtime;
   const stateValues = stateKeys.map((k) => state[k]);
   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;
 
-  // Batch rows close over every state key (stateKeys = Object.keys(state) at
-  // compile time) — "re-render on any change" is their honest dependency
-  // set; the identical-HTML guard above absorbs the no-ops (walk parity).
   markAlways(nodeSubscriberOf(iterationNode, 'iteration'));
 
   batchParseTemplate.innerHTML = html;
   const frag = batchParseTemplate.content;
+  markBoundValues(frag, html);
   const kids = frag.children;
 
   const arrayLen = array.length;
@@ -823,13 +527,9 @@ const renderBatch = (iterationNode, array, state, parent, endComment, parentScop
     applyDomPropertyWrites(instances, array, state, itemAlias, indexAlias, domPropertyWrites);
   }
 
-  // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
   stampScopes(iterationNode, manifest, parentScope);
 };
 
-/**
- * Find a comment node with matching text content in the given nodes.
- */
 const findComment = (nodes, text) => {
   const trimmedText = text.trim();
   for (let i = 0; i < nodes.length; i++) {
@@ -841,10 +541,6 @@ const findComment = (nodes, text) => {
   return null;
 };
 
-/**
- * Clone a parsed tree, mapping element references from original to cloned DOM.
- * Walks both trees in lockstep - no map building needed since structure is identical.
- */
 const cloneTreeWithElements = (originalTree, clonedRoot) => {
   if (!originalTree) return null;
 
@@ -854,7 +550,6 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
     children: {},
   };
 
-  // Avoid spread operator for performance
   if (originalTree.attributes) {
     cloned.attributes = originalTree.attributes;
   }
@@ -866,16 +561,13 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
 
   const clonedChildNodes = clonedRoot?.childNodes;
 
-  // Clone children recursively - use index from key to find cloned element
   for (const key in originalTree.children) {
     const child = originalTree.children[key];
     if (!child || typeof child !== 'object') continue;
 
-    // Handle conditional nodes - need to update comment references
     if (child.type === 'conditional' && clonedChildNodes) {
       const { startComment, elseComment, endComment, branches } = child.meta;
 
-      // Find corresponding comments in cloned DOM
       const clonedStart = findComment(clonedChildNodes, startComment.textContent);
       const clonedElse = elseComment
         ? findComment(clonedChildNodes, elseComment.textContent)
@@ -889,7 +581,7 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
           startComment: clonedStart || startComment,
           elseComment: clonedElse,
           endComment: clonedEnd || endComment,
-          branches, // Branch templates are reused (they're cloned during mount)
+          branches,
         },
         runtime: {
           activeBranch: undefined,
@@ -901,11 +593,9 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
       continue;
     }
 
-    // Handle iteration nodes - need to update comment references and fresh runtime
     if (child.type === 'iteration' && clonedChildNodes) {
       const { startComment, endComment, template } = child.meta;
 
-      // Find corresponding comments in cloned DOM
       const clonedStart = findComment(clonedChildNodes, startComment.textContent);
       const clonedEnd = findComment(clonedChildNodes, endComment.textContent);
 
@@ -917,7 +607,7 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
           indexAlias: child.meta.indexAlias,
           startComment: clonedStart || startComment,
           endComment: clonedEnd || endComment,
-          template, // Template is reused (cloned during render)
+          template,
         },
         runtime: {
           instances: [],
@@ -928,7 +618,6 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
       continue;
     }
 
-    // Extract index from key (format: "nodename_index") - avoid regex for speed
     const underscoreIdx = key.lastIndexOf('_');
     const childIndex = underscoreIdx >= 0 ? parseInt(key.slice(underscoreIdx + 1), 10) : -1;
     const clonedChild = childIndex >= 0 && clonedChildNodes ? clonedChildNodes[childIndex] : null;
@@ -939,28 +628,6 @@ const cloneTreeWithElements = (originalTree, clonedRoot) => {
   return cloned;
 };
 
-/**
- * Initialize a block instance from template nodes.
- * Uses cached template tree when available for speed.
- *
- * @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 }
- */
-// Compiled mode bakes a fixed `data-vibe-component-id` into each inlined
-// component and stamps its `@[this.x]` bindings / `$.this.x` handlers to that
-// id. An iteration clones its template once per row, so every row would
-// otherwise share that one id — and thus one local-state bucket. (Two brawler
-// slots both resolving to `_c2.open` is why opening one ability drawer opened
-// them all.) Per row, remap every baked id in the clone to a fresh one and
-// rewrite the references to it; the caller then runs the row's component
-// scripts so each registers isolated state under its fresh id. Runtime mode has
-// no baked ids here (components are still `<component src>`), so this no-ops.
 const COMPONENT_ID = /^_c\d+$/;
 
 const isolateInlinedComponentIds = (container) => {
@@ -973,9 +640,6 @@ const isolateInlinedComponentIds = (container) => {
   }
   if (!remap.size) return false;
 
-  // `_c2` must not match inside `_c20` or a longer identifier, so anchor on a
-  // non-word/`$` boundary before and a non-digit/word after. Bindings always
-  // read the id as `_cN.prop`, so the trailing `.` satisfies the lookahead.
   const refs = [...remap].map(([oldId, newId]) => [
     new RegExp(`(?<![\\w$])${oldId}(?![\\w\\d])`, 'g'),
     newId,
@@ -1007,19 +671,11 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null, c
   let clonedNodes = [];
   let firstElement = null;
 
-  // 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 (componentId) parseContainer._vibeComponentId = componentId;
 
-  // Clone template nodes into container
   for (let i = 0; i < templateNodes.length; i++) {
     const cloned = templateNodes[i].cloneNode(true);
     parseContainer.appendChild(cloned);
@@ -1028,22 +684,6 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null, c
     }
   }
 
-  // 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.
-  //
-  // Also resolve loop-scoped src bindings here, BEFORE parse() reads the
-  // attribute: the loop locals die with this render, so a src composed from
-  // them (`src="/x/@[item.slug].html"`) must become a literal URL now. Left as
-  // a binding it registers in this block's tree, and the remount transport
-  // (_vibeSrcBinding → data-vibe-src on the finalized wrapper) re-evaluates it
-  // against GLOBAL state on reparse — clobbering the mounted row with a fetch
-  // of a garbage URL. Exprs that read no loop alias stay raw: a reactive
-  // outlet (`src="@[page.src]"`) keeps its global binding, and an alias owned
-  // by a deeper loop resolves when that loop clones its own instances.
   const components = parseContainer.querySelectorAll('component[src], div.component[src]');
   const scopeKeys = overlayKeysOf(scopedState);
   for (let i = 0; i < components.length; i++) {
@@ -1052,32 +692,22 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null, c
     if (scopeKeys) resolveScopedSrc(el, scopedState, scopeKeys);
   }
 
-  // Give this row its own component ids (compiled mode) before parse() reads the
-  // bindings, then run the row's inlined setup scripts so each registers its own
-  // local state under the fresh id — mirroring the conditional-branch path.
   if (isolateComponents && isolateInlinedComponentIds(parseContainer)) {
     executeCompiledComponentScriptsIn([...parseContainer.childNodes]);
   }
 
   if (useCachedTree) {
-    // 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. 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)
-  // Avoid Array.from for performance
   const childNodes = parseContainer.childNodes;
   clonedNodes = [];
   for (let i = 0; i < childNodes.length; i++) {
     clonedNodes.push(childNodes[i]);
   }
 
-  // If no firstElement found, use parseContainer as fallback
   if (!firstElement) {
     firstElement = parseContainer;
   }
@@ -1094,19 +724,13 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null, c
   };
 };
 
-// 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),
   ])];
 
-  // Overlay = the aliases this proxy resolves locally (localVars wins over
-  // parentScope, matching the get order below). affected's descent reuses it for
-  // a cheap plain merge instead of materializing the proxy.
   const overlay =
     Object.keys(parentScope).length === 0 ? localVars : { ...parentScope, ...localVars };
 
@@ -1114,10 +738,6 @@ export const createScopedState = (globalState, localVars, parentScope = {}) => {
     get(target, prop) {
       if (prop in localVars) return localVars[prop];
       if (prop in parentScope) return parentScope[prop];
-      // Global fallthrough is a root-key read; alias hits above are the
-      // row's own scope (owned by its iteration's diff) and never record.
-      // When the target is the live root the proxy trap records too — the
-      // window's read Set dedupes.
       recordRead(prop);
       return Reflect.get(target, prop);
     },
@@ -1154,19 +774,14 @@ export const createScopedState = (globalState, localVars, parentScope = {}) => {
   return rememberScopedKeys(proxy, cachedKeys, overlay);
 };
 
-// Render all iterations in the parsed tree
 export const renderAllIterations = (tree, state, manifest, parentScope = {}) => {
   let count = 0;
 
-  // If this is an iteration node, render it
   if (tree.type === 'iteration') {
     renderIteration(tree, state, manifest, parentScope);
     return 1;
   }
 
-  // Recursively render iterations in child nodes — except under an outgoing
-  // wrapper (reactive-src remount in flight): its subtree is frozen until
-  // the swap replaces it.
   if (tree.children && !isOutgoing(tree.element)) {
     for (const key in tree.children) {
       const child = tree.children[key];
@@ -1179,44 +794,32 @@ export const renderAllIterations = (tree, state, manifest, parentScope = {}) =>
   return count;
 };
 
-// Callback for rendering conditionals - set by conditionals.js to avoid circular import
 let _renderAllConditionals = () => {};
 export const setRenderAllConditionals = (fn) => {
   _renderAllConditionals = fn;
 };
 
-// Initial render of an iteration block
 export const renderIteration = (iterationNode, state, manifest, parentScope = {}) => {
   const { arrayPath, startComment, endComment } = iterationNode.meta;
 
-  // Already rendered - updates go through updateIteration
   if (iterationNode.runtime.instances?.length > 0) {
     return;
   }
 
-  // Check if this iteration has already been rendered
-  // We use a marker on the startComment node itself (survives re-parsing)
-  // @ts-ignore - adding custom property to comment node
   if (startComment.__vibeRendered) {
     return;
   }
 
-  // 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
+        return;
       }
       currentNode = currentNode.nextSibling;
     }
   }
 
-  // Remove template nodes from DOM on first render
   if (!iterationNode.runtime.templateRemoved) {
     let node = startComment.nextSibling;
     while (node && node !== endComment) {
@@ -1229,12 +832,7 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
 
   const parent = startComment.parentNode;
 
-  // 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);
-  // First render doubles as the iteration's subscription registration.
   const trackSub = nodeSubscriberOf(iterationNode, 'iteration');
   trackSub.lastScope = state;
   beginTracking(trackSub, overlayKeysOf(state));
@@ -1245,35 +843,22 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
     return;
   }
 
-  // Compiled path: Check for pre-compiled batch function in manifest
   if (compiled.canUseCompiled(iterationNode)) {
     const compiledMeta = compiled.getCompiledMeta(iterationNode);
     if (compiled.renderCompiled(iterationNode, array, state, compiledMeta, parent, endComment)) {
-      // Compiled rows close over every state key — "any change" is their
-      // honest dependency set (walk parity for treeless instances).
       markAlways(trackSub);
-      // Mark as rendered
       startComment.__vibeRendered = true;
       startComment.__vibeIterationRuntime = iterationNode.runtime;
       return;
     }
-    // Fall through to runtime path if compiled failed
   }
 
-  // Standard path: one shared clone+hydrate render loop (also used by bulkReplace).
   renderInstances(iterationNode, array, state, manifest, 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
   startComment.__vibeRendered = true;
-  // @ts-ignore - adding custom property to comment node
   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;
@@ -1286,9 +871,6 @@ const evalKeyForItem = (iterationNode, item, index, state, parentScope) => {
   }
 };
 
-// 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.__vibe?.debug) return;
@@ -1299,7 +881,6 @@ const warnIndexCoupledKey = (iterationNode) => {
   );
 };
 
-// Update an iteration block when array changes
 export const updateIteration = (iterationNode, newState, oldState, manifest, parentScope = {}) => {
   if (!iterationNode.runtime.instances || !iterationNode.runtime.templateRemoved) return;
 
@@ -1308,32 +889,12 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
   const resolvedExpr = resolveThisPath(arrayPath, startComment.parentElement);
 
   const stateOldArray = evalInScope(resolvedExpr, oldState, startComment.parentElement) ?? resolvePath(oldState, resolvedExpr) ?? [];
-  // New-side eval re-records the iteration's subscription (self-healing).
   const trackSub = nodeSubscriberOf(iterationNode, 'iteration');
   trackSub.lastScope = newState;
   beginTracking(trackSub, overlayKeysOf(newState));
   const newArray = evalInScope(resolvedExpr, newState, startComment.parentElement) ?? resolvePath(newState, resolvedExpr) ?? [];
   endTracking();
 
-  // Use instances (what's actually rendered) as ground truth for old array
-  // whenever the only signal of change is a registry side-effect, or when
-  // the rendered count doesn't match the freshly evaluated state. Three
-  // cases collapse to "trust the rendered snapshot":
-  //   1. oldState === newState — forceRegistryBackedIterationUpdates calls
-  //      updateIteration with the same state on both sides because the only
-  //      mutation was a registry slot rewrite. The previously rendered
-  //      items are the only honest record of what was there before.
-  //   2. stateOldArray === newArray — the iteration's arrayPath resolves
-  //      directly to a registry slot (`window.__vibe.iterProps._pN`); the
-  //      slot was swapped in place, so both reads return the same NEW
-  //      array.
-  //   3. length mismatch — oldState predates the current render.
-  // Otherwise the freshly evaluated state is a trustworthy "old".
-  //
-  // Literal-wrap expressions like `[s]` would otherwise slip through this
-  // net: they build different array refs each eval but both contain the
-  // just-rewritten registry value, so a naive diff sees no change. Case 1
-  // catches them.
   const instances = iterationNode.runtime.instances;
   const useInstancesAsOld =
     oldState === newState ||
@@ -1343,7 +904,6 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
     ? instances.map((inst) => inst.item)
     : stateOldArray;
 
-  // Compiled path: Use pre-compiled batch function when available
   if (compiled.canUseCompiled(iterationNode)) {
     const compiledMeta = compiled.getCompiledMeta(iterationNode);
     if (
@@ -1356,49 +916,25 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
         endComment,
       )
     ) {
-      // Still treeless — keep the honest any-change subscription.
       markAlways(trackSub);
       return;
     }
-    // Fall through to runtime path if compiled failed
   }
 
-  // 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;
   }
 
-  // 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) {
-    // Treeless rows stay on the any-change subscription. If bulkReplace
-    // below clone-renders trees instead, the next new-side eval re-records
-    // real deps (self-healing).
     markAlways(trackSub);
-    // 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 click on a row
-    // control. DOM-property writes (value/checked/etc.) aren't reflected in the
-    // HTML string, so they're re-applied against the kept rows — property
-    // assignment also wins over a user-dirtied checkbox, which an attribute
-    // rewrite wouldn't.
     const rt = iterationNode.runtime;
     if (rt.batchFn && rt.lastBatchHtml !== undefined) {
       const stateValues = rt.stateKeys.map((k) => newState[k]);
       const newHtml = rt.batchFn(newArray, ...stateValues, newState);
       if (newHtml === rt.lastBatchHtml) {
         if (rt.domPropertyWrites?.length) {
-          // Identical HTML implies identical row count — refresh item refs so
-          // $scope handlers and property writes read the live array.
           for (let i = 0; i < instances.length; i++) instances[i].item = newArray[i];
           applyDomPropertyWrites(
             instances,
@@ -1423,25 +959,18 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
     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);
   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);
 
-  // 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) {
@@ -1462,10 +991,6 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
     }
   });
 
-  // 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;
@@ -1473,27 +998,13 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
     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.
   stampScopes(iterationNode, manifest, parentScope);
 };
 
-// Prune removed iteration rows from the global manifest (dotPath -> element)
-// and parsed tree. Both views still reference rows that mounted globally-tracked
-// content (e.g. a <component src> registers its subtree in the manifest). Vibe
-// disconnects the page MutationObserver while it reconciles, so the removals
-// below are never observed — left unpruned, the entries pin detached subtrees
-// (memory leak) and bloat every later affected/hydrate walk (the
-// combat-fps-decays-per-reset bug). Scoped to exactly the removed nodes.
 const releaseRemovedSubtrees = (removedRoots, manifest) => {
   if (!manifest || removedRoots.length === 0) return;
   const tree = manifest.__tree;
 
-  // Reverse the manifest (dotPath -> element) once so each removed root resolves
-  // to its path. An element can be registered at more than one path (a component
-  // wrapper appears at both its own node and an inlined child slot); keep the
-  // SHORTEST so the path scopes the whole row subtree, not an inner slot.
-  // __live / __tree are non-enumerable, so for-in skips them.
   const pathOf = new Map();
   for (const key in manifest) {
     const el = manifest[key];
@@ -1502,8 +1013,8 @@ const releaseRemovedSubtrees = (removedRoots, manifest) => {
     if (existing === undefined || key.length < existing.length) pathOf.set(el, key);
   }
 
-  const removedEls = new Set(); // top-level removed roots — tree prune cascades subtrees
-  const removedPaths = new Set(); // their manifest paths — manifest prune is path-scoped
+  const removedEls = new Set();
+  const removedPaths = new Set();
   for (let i = 0; i < removedRoots.length; i++) {
     const root = removedRoots[i];
     if (!root) continue;
@@ -1513,30 +1024,15 @@ const releaseRemovedSubtrees = (removedRoots, manifest) => {
   }
   if (removedPaths.size === 0 && removedEls.size === 0) return;
 
-  // Manifest: drop every entry at or under a removed root's path. Path scope (not
-  // element identity) is what catches content hoisted out of the DOM — an inactive
-  // conditional branch template sits in a detached container yet stays registered
-  // under its row's path.
   if (removedPaths.size > 0) {
     for (const key in manifest) {
       if (pathUnderRemoved(key, removedPaths)) delete manifest[key];
     }
   }
 
-  // Parsed tree: delete each removed root's node — its whole subtree (nested
-  // conditionals/iterations and their branch templates) goes with it. Prune
-  // by CONTAINMENT, not just root identity: a row's inlined component trees
-  // are also linked under OTHER ancestors' children (the dual linkage the
-  // affected-walk dedupe documents), keyed by inner wrapper elements that are
-  // never themselves removed roots. Left in place, every later walk descends
-  // those detached trees — re-hydrating dead DOM and (since subscriptions)
-  // re-registering its subscribers after teardown pruned them, pinning the
-  // whole removed subtree forever.
   const roots = [...removedEls];
   if (tree) pruneTreeNodes(tree, removedEls, roots);
 
-  // The removed rows' subscribers (bindings, nested conditionals/iterations)
-  // are anchored to nodes that just left the document.
   pruneDisconnected();
 };
 
@@ -1547,7 +1043,6 @@ const underRemovedRoot = (el, roots) => {
   return false;
 };
 
-// True when `key` is, or is a descendant of, any path in `removedPaths`.
 const pathUnderRemoved = (key, removedPaths) => {
   if (removedPaths.has(key)) return true;
   for (let i = key.indexOf('.', 1); i !== -1; i = key.indexOf('.', i + 1)) {
@@ -1568,17 +1063,10 @@ const pruneTreeNodes = (node, removedEls, roots) => {
   }
 };
 
-// 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;
 
-  // Clear all existing DOM between comments using Range (single operation),
-  // then prune the removed subtrees from the manifest + tree. Collect the LIVE
-  // nodes in the range rather than the instances' clonedNodes: a <component src>
-  // row is replaced in place by component.js, so clonedNodes can point at the
-  // stale original wrapper, not the processed content actually being removed.
   if (iterationNode.runtime.instances.length > 0) {
     const removedRoots = [];
     for (let cur = startComment.nextSibling; cur && cur !== endComment; cur = cur.nextSibling) {
@@ -1596,8 +1084,6 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
     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, parentScope, manifest);
     const instances = iterationNode.runtime.instances;
@@ -1607,20 +1093,9 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
     return;
   }
 
-  // Complex templates: one shared clone+hydrate render loop.
   renderInstances(iterationNode, newArray, state, manifest, parentScope);
 };
 
-// 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++) {
@@ -1629,10 +1104,6 @@ const findInstanceAnchor = (instance, iterationParent) => {
   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++) {
@@ -1642,28 +1113,15 @@ const resolveInsertBefore = (iterationNode, index, parent) => {
   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);
 
-  // Return the live nodes actually removed so callers can prune them from the
-  // manifest + tree (clonedNodes can be stale once a <component src> row is
-  // replaced in place by component.js).
   const removed = [];
   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);
@@ -1683,14 +1141,6 @@ const detachInstanceDom = (iterationNode, index, parent) => {
   return removed;
 };
 
-// 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).
-// `liveItem` (resolved by the caller via resolveLiveArray, so a derived-array
-// loop evaluates the expression once per render, not once per row) is the live
-// `$`-proxy element for this index. Building scope from it gives nested
-// conditional stamps and `$scope` handlers the app-visible identity; `item`
-// (plain snapshot) is still tracked for the diff.
 const buildInstance = (iterationNode, item, index, state, parentScope, liveItem) => {
   const { itemAlias, indexAlias, template, startComment } = iterationNode.meta;
   const localVars = { [itemAlias]: liveItem, [indexAlias]: index };
@@ -1702,11 +1152,6 @@ const buildInstance = (iterationNode, item, index, state, parentScope, liveItem)
   return { ...built, scopedState, localVars, liveItem };
 };
 
-// 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++) {
@@ -1719,10 +1164,6 @@ const finalizeInstance = (built, manifest, parentScope) => {
   }
 };
 
-// Build, finalize, and commit a fresh set of instances for `array` in one
-// batched DOM insertion, replacing iterationNode.runtime.instances. The single
-// clone+hydrate render loop shared by initial render (renderIteration) and full
-// rebuild (bulkReplace) — they differ only in their preamble, not this loop.
 const renderInstances = (iterationNode, array, state, manifest, parentScope) => {
   const { startComment, endComment } = iterationNode.meta;
   const parent = startComment.parentNode;
@@ -1740,7 +1181,6 @@ const renderInstances = (iterationNode, array, state, manifest, parentScope) =>
   }
   parent.insertBefore(frag, endComment);
   iterationNode.runtime.instances = instances;
-  // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
   stampScopes(iterationNode, manifest, parentScope);
 };
 
@@ -1777,30 +1217,18 @@ const moveInstance = (iterationNode, fromIndex, toIndex) => {
 
   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);
   }
 };
 
-// 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];
 
   const liveItem = liveItemAt(resolveLiveArray(iterationNode, manifest, parentScope), index, newItem);
   const built = buildInstance(iterationNode, newItem, index, state, parentScope, liveItem);
-  // Prune the OLD row's manifest/tree entries before finalizing the rebuilt one,
-  // so the replaced subtree is released (same removal contract as removeInstance).
-  // Order matters: prune the detached old nodes before finalizeInstance registers
-  // the new ones, so the new entries are never touched.
   const removed = parent ? detachInstanceDom(iterationNode, index, parent) : [];
   releaseRemovedSubtrees(removed, manifest);
   const insertBefore = resolveInsertBefore(iterationNode, index + 1, parent);
@@ -1815,17 +1243,6 @@ const updateInstanceRebuild = (iterationNode, index, newItem, state, manifest, p
   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];
@@ -1837,11 +1254,6 @@ const updateInstance = (iterationNode, index, newItem, oldState, newState, manif
 
   const { itemAlias, indexAlias } = iterationNode.meta;
   const newLocalVars = { [itemAlias]: newItem, [indexAlias]: index };
-  // The "old" scoped state is exactly last cycle's "new" one — same global
-  // snapshot (this cycle's oldState) and same item/index — already stored on the
-  // instance. Reuse it instead of allocating a second proxy per row per frame
-  // (createScopedState is a combat hot spot). Falls back on the first update
-  // after an add, before scopedState has been recorded.
   const oldScopedState =
     instance.scopedState ||
     createScopedState(oldState, { [itemAlias]: instance.item, [indexAlias]: index }, parentScope);