@ape-egg/vibe 4.0.0 → 4.1.1

package/runtime/reconcile.js

@@ -1,17 +1,5 @@
 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;
@@ -29,18 +17,10 @@ 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;
@@ -48,11 +28,6 @@ const nodesMatch = (a, b) => {
   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++) {
@@ -68,10 +43,6 @@ const findRealignment = (liveNodes, li, sourceNodes, si) => {
   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;
@@ -80,12 +51,6 @@ const trimWsEdges = (nodes) => {
   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;
@@ -106,14 +71,6 @@ const findOwnSlot = (el, srcChildren) => {
 
 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) => {
@@ -121,8 +78,6 @@ const updateBoundText = (live, newSrc, parent, log) => {
   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;
@@ -130,11 +85,9 @@ const updateBoundText = (live, newSrc, parent, log) => {
     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;
@@ -166,9 +119,6 @@ const updateBoundText = (live, newSrc, parent, log) => {
   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;
@@ -183,8 +133,6 @@ const findRegionEnd = (nodes, startIdx, endLimit) => {
   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++) {
@@ -198,15 +146,10 @@ const findElseMarker = (nodes, startIdx, endIdx) => {
   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) {
@@ -215,7 +158,6 @@ const mergeClass = (srcValue, live) => {
   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 : '';
@@ -224,17 +166,9 @@ const describe = (el) => {
 };
 
 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) {
@@ -247,12 +181,7 @@ const reconcileAttributes = (live, src, log) => {
   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(' '));
@@ -267,17 +196,6 @@ const reconcileAttributes = (live, src, log) => {
   }
 };
 
-// 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;
@@ -301,11 +219,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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; }
@@ -314,7 +227,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
     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);
@@ -323,12 +235,10 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       } 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++) {
@@ -339,8 +249,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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++) {
@@ -352,32 +260,13 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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;
@@ -405,10 +294,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
           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++;
@@ -429,16 +314,12 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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);
@@ -453,7 +334,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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;
@@ -464,7 +344,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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);
@@ -474,14 +353,11 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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
+        if (n.nodeType === ELEMENT && n.tagName === 'SCRIPT') continue;
         log.remove++;
         log.changes.push(`remove (extra) ${describe(n)} from ${describe(liveParent)}`);
         n.remove();
@@ -499,7 +375,6 @@ const reconcileRange = (liveParent, liveNodes, liStart, liEnd, srcNodes, siStart
       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));
@@ -513,25 +388,18 @@ const reconcileChildren = (liveParent, sourceNodes, log, insideIteration = false
   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
+  if (!liveFirstEl) return;
 
   let chosenStart = -1;
   let chosenEnd = -1;
@@ -553,7 +421,7 @@ const reconcileConditionalRegion = (liveParent, liveNodes, liStart, liEnd, srcNo
       }
     }
   }
-  if (chosenStart === -1) return; // no matching branch; leave opaque
+  if (chosenStart === -1) return;
 
   reconcileRange(
     liveParent, liveNodes,
@@ -564,23 +432,7 @@ const reconcileConditionalRegion = (liveParent, liveNodes, liStart, liEnd, srcNo
   );
 };
 
-// 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]);
@@ -593,19 +445,12 @@ const reconcileIterationRegion = (liveParent, liveNodes, liStart, liEnd, srcNode
     if (liveEl.nodeType !== ELEMENT) continue;
     const tplEl = tplEls[instanceIdx % tplEls.length];
     instanceIdx++;
-    if (liveEl.tagName !== tplEl.tagName) continue; // shape changed; skip
+    if (liveEl.tagName !== tplEl.tagName) continue;
     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: [] });

package/runtime/staging.js

@@ -1,24 +1,3 @@
-// Navigation staging — the one-paint commit machinery behind reactive-src /
-// keyed remounts, owned in one place. A remount marks the mounted wrapper
-// OUTGOING: it keeps the screen — visible, styled, frozen — while the
-// incoming wrapper hydrates as a display:none sibling ([vibe-staged]). The
-// commit swaps the two and replays parked ancestor bindings in one
-// synchronous step: navigation paints exactly once, never an unstyled or
-// blank frame between.
-//
-// Every consumer answers its question through THIS module:
-//   isOutgoing(el)      tree walks — skip collecting under a frozen wrapper
-//   outgoingRootOf(n)   dispatch — is this subscriber inside a frozen page?
-//   parkRootFor(el)     hydrate — is a frozen page inside this element? then
-//                       park the binding (it is the styling context AROUND
-//                       the outlet — flipping it mid-stage un-styles the
-//                       visible page) and let the commit replay it
-//   stage/commit/abandon  component.js's mount finalize drives transitions
-
-// The mount pipeline replaces wrappers (finalize's replaceWith), leaving a
-// `_vibeReplacedBy` link behind. Trees and clone lists keep ORIGINAL nodes —
-// follow the chain to the live one, compressing so intermediate detached
-// wrappers stay collectable.
 export const liveNode = (node) => {
   let live = node;
   while (live && live._vibeReplacedBy) live = live._vibeReplacedBy;
@@ -26,7 +5,6 @@ export const liveNode = (node) => {
   return live;
 };
 
-// Wrappers whose mounted content is outgoing — a remount is in flight.
 export const activeOutgoingRoots = new Set();
 
 export const isOutgoing = (element) => !!(element && liveNode(element)._vibeOutgoing);
@@ -41,11 +19,6 @@ export const releaseOutgoing = (el) => {
   activeOutgoingRoots.delete(el);
 };
 
-// The outgoing root STRICTLY containing `node`, or null. The root's own
-// src/key/prop bindings stay live (a rapid next navigation must re-trigger);
-// everything beneath it is replaced wholesale at the swap, so re-rendering
-// it against post-navigation state is pure waste — and was the visible
-// mid-navigation collapse.
 export const outgoingRootOf = (node) => {
   if (!activeOutgoingRoots.size || !node) return null;
   for (const root of activeOutgoingRoots) {
@@ -54,9 +27,6 @@ export const outgoingRootOf = (node) => {
   return null;
 };
 
-// The outgoing root strictly INSIDE `element`, or null — the park direction:
-// `element` is the styling context around the outlet (the game's
-// `<page @[page.name]>`). Zero cost when nothing is staging.
 export const parkRootFor = (element) => {
   if (!activeOutgoingRoots.size || !element) return null;
   for (const root of activeOutgoingRoots) {
@@ -65,9 +35,6 @@ export const parkRootFor = (element) => {
   return null;
 };
 
-// Parked updates live on the outgoing wrapper (Map<element, Map<key, apply>>)
-// keyed by element + binding so rapid flushes during staging keep only the
-// latest value; the commit replays them in its synchronous swap step.
 export const parkBinding = (root, element, key, apply) => {
   const parked = (root._vibeParkedBindings ??= new Map());
   let perElement = parked.get(element);
@@ -84,27 +51,16 @@ const replayParked = (old) => {
   old._vibeParkedBindings = null;
 };
 
-// A fetched-component host: `<component>` or `<div class="component">`.
 export const isComponentWrapper = (el) =>
   el.nodeName === 'COMPONENT' ||
   (el.nodeName === 'DIV' && el.classList?.contains('component'));
 
-// A flush entry that (re)mounts: the wrapper's own src/key binding. These
-// process FLUSH-WIDE FIRST — they register the outgoing roots every other
-// entry's freeze-skip and parking decisions depend on. (Tree-walk order gave
-// the walk this for free within one pass; dispatch batches must hoist.)
 export const isRemountTrigger = (entry) =>
   entry.type === 'attribute' &&
   (entry.attrName === 'src' || entry.attrName === 'key') &&
   !!entry.element &&
   isComponentWrapper(entry.element);
 
-// ————— staged swap transitions (driven by component.js finalize) —————
-
-// Mount landed for an outgoing wrapper: stage the incoming wrapper, don't
-// swap. A superseded staged wrapper (rapid re-navigation) was never visible:
-// drop it immediately and inherit the ORIGINAL visible page as this mount's
-// commit target.
 export const stageIncoming = (el, newWrapper) => {
   if (el.hasAttribute('vibe-staged')) {
     newWrapper._vibeCommitOld = el._vibeCommitOld;
@@ -114,16 +70,11 @@ export const stageIncoming = (el, newWrapper) => {
   } else {
     newWrapper._vibeCommitOld = el;
     newWrapper.setAttribute('vibe-staged', '');
-    // The outgoing wrapper is no longer a mount request — with the src
-    // attribute still on it, every processComponent rescan would treat it as
-    // unresolved and mount a second copy while it holds the screen.
     el.removeAttribute('src');
     el.after(newWrapper);
   }
 };
 
-// Atomic visual commit: old page out, parked styling-context bindings
-// applied, new page revealed — one synchronous block, one paint.
 export const commitStaged = (newWrapper) => {
   const old = newWrapper._vibeCommitOld;
   if (old) {
@@ -135,14 +86,6 @@ export const commitStaged = (newWrapper) => {
   newWrapper.removeAttribute('vibe-staged');
 };
 
-// Incoming wrapper died before its commit (unmounted mid-hydration, or
-// removed by something outside the staging machinery — $.reconcile on an
-// ancestor, app code pruning the container): no swap is coming. Release the
-// frozen old page — connected, it must resume updating; detached, the Set
-// entry would pin the subtree forever — and reverse the replaced-by link so
-// chains compressed onto the dead staged wrapper resolve back to the page
-// that stayed (its src binding must act on IT again, or no later navigation
-// can ever remount).
 export const abandonStaged = (newWrapper) => {
   const old = newWrapper._vibeCommitOld;
   if (!old) return;