@ape-egg/vibe 2.1.22 → 3.0.0

package/runtime/component.js

@@ -1,4 +1,5 @@
 import { debugLog } from './debug.js';
+import { shouldCleanup } from './cleanup.js';
 import {
   PHASE_FETCH,
   PHASE_FETCH_CACHED,
@@ -6,12 +7,33 @@ import {
   BINDING_REGEX,
   THIS_PROP_REGEX,
   STATE_THIS_PROP_REGEX,
+  CONDITIONAL_START_REGEX,
+  ITERATION_START_REGEX,
 } from './constants.js';
 import { evalInScope } from './utils.js';
+import { bumpIterPropGeneration } from './iteration-utils.js';
 import { fetchComponentTemplate, isComponentCached } from './component-cache.js';
+import { notifyChanged } from './state.js';
+import {
+  liveNode,
+  activeOutgoingRoots,
+  markOutgoing,
+  releaseOutgoing,
+  stageIncoming,
+  commitStaged,
+  abandonStaged,
+  isComponentWrapper,
+} from './staging.js';
+
+export { activeOutgoingRoots, isComponentWrapper };
 
 // Deterministic component counter
-let componentCounter = 0;
+// Runtime-minted ids live in their own range, far above every build-tagged
+// id (SPA units get 1000 ids each — 1M covers a thousand pages). Without the
+// floor, a long session's runtime counter could grow into a not-yet-mounted
+// fragment's build range and claim its state. advanceComponentCounterPastIds
+// still bumps past anything larger it encounters in the document.
+let componentCounter = 1000000;
 
 /**
  * Generate unique component ID
@@ -40,7 +62,7 @@ export const releaseOrphanedComponentState = (collectedIds) => {
   if (!collectedIds || collectedIds.size === 0) return;
   for (const id of collectedIds) {
     if (document.querySelector(`[data-vibe-component-id="${id}"]`)) continue;
-    delete window.__vibeComponents?.[id];
+    delete window.__vibe?.components?.[id];
     // CLEANUP OF CURRENT STATE
     delete window.$[id];
     runComponentCleanups(id);
@@ -53,10 +75,20 @@ export const releaseOrphanedComponentState = (collectedIds) => {
 // unmounting the component fires the callbacks so the previous evaluation's
 // listeners don't accumulate alongside fresh registrations.
 export const runComponentCleanups = (componentId) => {
-  const cleanups = window.__vibeComponentCleanups?.[componentId];
+  const cleanups = window.__vibe?.cleanups?.[componentId];
   if (!cleanups) return;
-  for (let i = 0; i < cleanups.length; i++) cleanups[i]();
-  delete window.__vibeComponentCleanups[componentId];
+  // Deregister BEFORE running: a throwing callback must neither re-throw on
+  // every later cleanup of this id nor take the remaining callbacks down
+  // with it — and never escape into the script chain, whose links have no
+  // rejection path. User callbacks fail loudly, the engine keeps going.
+  delete window.__vibe.cleanups[componentId];
+  for (let i = 0; i < cleanups.length; i++) {
+    try {
+      cleanups[i]();
+    } catch (e) {
+      console.error('[vibe] Error in unmount cleanup:', e);
+    }
+  }
 };
 
 // Per-script `$` Proxy. Bare `$` references in a component's <script> resolve
@@ -80,8 +112,8 @@ const createScopedDollar = (componentId) => {
           // leaking them past its lifetime. At page level the root's `on`
           // resolves the same event name to pagehide instead.
           if (event === 'unmount') {
-            if (!window.__vibeComponentCleanups) window.__vibeComponentCleanups = {};
-            const slot = window.__vibeComponentCleanups[componentId] || (window.__vibeComponentCleanups[componentId] = []);
+            const cleanupsReg = ((window.__vibe ??= {}).cleanups ??= {});
+            const slot = cleanupsReg[componentId] || (cleanupsReg[componentId] = []);
             slot.push(callback);
             return () => {
               const i = slot.indexOf(callback);
@@ -89,8 +121,8 @@ const createScopedDollar = (componentId) => {
             };
           }
           const unsub = target.on(event, callback);
-          if (!window.__vibeComponentCleanups) window.__vibeComponentCleanups = {};
-          const slot = window.__vibeComponentCleanups[componentId] || (window.__vibeComponentCleanups[componentId] = []);
+          const cleanupsReg = ((window.__vibe ??= {}).cleanups ??= {});
+          const slot = cleanupsReg[componentId] || (cleanupsReg[componentId] = []);
           slot.push(unsub);
           return unsub;
         };
@@ -172,8 +204,16 @@ const transformScriptContent = (rawContent) => {
 //
 // Returns a Promise when any script is async (has imports) — the caller
 // gates `ready` on it — or null when everything ran synchronously.
+//
+// Collection is span-aware, not a blind document query: manifest adoption has
+// already swapped every directive's stamped content back to its pre-stamp
+// template (declaration form), so at sweep time ALL content between
+// `<!-- if -->`/`<!-- each -->` markers is unrendered template. Those scripts
+// run when their branch/row mounts (mountBranch / renderIteration call back
+// into this pipeline); only directive-free scripts are the boot pass's own.
 export const executeCompiledComponentScripts = () => {
-  const scripts = document.querySelectorAll('script[type="vibe-module"]');
+  const scripts = [];
+  collectMountedModuleScripts(document.body ? [document.body] : [], scripts);
   if (!scripts.length) return null;
   advanceComponentCounterPastIds(document);
   return runVibeModuleScripts(scripts);
@@ -188,16 +228,43 @@ export const executeCompiledComponentScripts = () => {
 // conditional restores its markup but its `<!-- each _cN.x -->` reads state that
 // was released on unmount (the AccountProgression overlay rendering blank on
 // second open).
-export const executeCompiledComponentScriptsIn = (nodes) => {
+//
+// `silent` routes fresh-id registrations through $.register (no global flush)
+// — correct ONLY when the subtree's own hydration runs after these scripts
+// against live `$` (the fetched-mount path). Branch/row mounts render against
+// a flush snapshot that predates the registration, so they rely on the
+// registration's own flush to fill `_cN` bindings in — they must stay loud.
+export const executeCompiledComponentScriptsIn = (nodes, { silent = false } = {}) => {
   const scripts = [];
-  for (const node of nodes) {
-    if (node.nodeType !== 1) continue;
-    if (node.matches?.('script[type="vibe-module"]')) scripts.push(node);
-    node.querySelectorAll?.('script[type="vibe-module"]').forEach((s) => scripts.push(s));
-  }
+  collectMountedModuleScripts(nodes, scripts);
   if (!scripts.length) return null;
   advanceComponentCounterPastIds(document);
-  return runVibeModuleScripts(scripts);
+  return runVibeModuleScripts(scripts, silent);
+};
+
+// Collect the vibe-module scripts a fresh mount actually OWNS. Content between
+// nested `<!-- if -->`/`<!-- each -->` markers in a just-cloned subtree is an
+// unrendered template — its scripts belong to the nested directive and run when
+// THAT directive mounts its branch/rows (mountBranch and renderIteration each
+// call back into this pass). Running them here would execute component copies
+// this mount never shows: the compiler inlines a slotted component once per
+// conditional branch, so a mount that owns both branch templates would register
+// ghost state buckets whose `$.on` hooks shadow the mounted copy's writes
+// forever. Directive spans are sibling-scoped, so each child list scans with
+// its own depth counter (same walk as reconcile's opaque-region skip).
+const collectMountedModuleScripts = (nodes, out) => {
+  let depth = 0;
+  for (const node of nodes) {
+    if (node.nodeType === 8) {
+      const text = node.textContent.trim();
+      if (CONDITIONAL_START_REGEX.test(text) || ITERATION_START_REGEX.test(text)) depth++;
+      else if (text === '/if' || text === '/each') depth--;
+      continue;
+    }
+    if (depth > 0 || node.nodeType !== 1) continue;
+    if (node.matches?.('script[type="vibe-module"]')) out.push(node);
+    else collectMountedModuleScripts(node.childNodes, out);
+  }
 };
 
 // Build-time tagging already assigned _cN ids to wrappers; advance the runtime
@@ -209,48 +276,131 @@ const advanceComponentCounterPastIds = (root) => {
   });
 };
 
-const runVibeModuleScripts = (scripts) => {
+// Shared registration: the component registry always, plus the live `$` when
+// booted. `silent` prefers $.register — a fresh id lands without its own
+// global flush; the MOUNT commits all its registrations in one notifyChanged
+// batch when its scripts settle. Re-registrations (HMR) still flush
+// immediately, and pre-boot placeholders keep the plain reactive write.
+const registerComponentState = (componentId, state, silent) => {
+  ((window.__vibe ??= {}).components ??= {})[componentId] = state;
+  if (window.$) {
+    if (silent && window.$._register) window.$._register(componentId, state);
+    else window.$[componentId] = state;
+  }
+};
+
+// Native `<script type="module">` semantics: module scripts evaluate strictly
+// in document order — script N+1 never starts before script N finished,
+// imports included. A sync script may therefore rely on globals an earlier
+// script's import produced (the game's Layout imports boot.js; chrome
+// components read its globals at their top level). Eval'd vibe-module scripts
+// lose that for free — an async function returns at its first `await`, so the
+// executor's loop would start every script "concurrently" and sync scripts
+// would run before earlier imports landed. One global chain restores the
+// contract across ALL execution sites (boot batch, mounted subtrees, fetched
+// components): while a script is pending, later scripts — sync ones too —
+// queue behind it. An idle chain runs sync scripts synchronously, so
+// boot timing is unchanged until the first async script appears.
+let scriptChain = null;
+
+const enqueueScriptExecution = (run) => {
+  if (scriptChain) {
+    const link = scriptChain.then(run);
+    const tail = link.then(() => {
+      if (scriptChain === tail) scriptChain = null;
+    });
+    scriptChain = tail;
+    return link;
+  }
+  const result = run();
+  if (!result) return null;
+  const tail = result.then(() => {
+    if (scriptChain === tail) scriptChain = null;
+  });
+  scriptChain = tail;
+  return result;
+};
+
+// Cleanups, scoping and evaluation for one script — the unit the chain
+// executes. Never throws and never rejects: a crashed script is warned and
+// released, later scripts still run (a failed native module doesn't stop
+// subsequent script elements either).
+const executeScriptUnit = (componentId, content, hasImports, scopedDollar, componentFn) => () => {
+  runComponentCleanups(componentId);
+  try {
+    if (hasImports) {
+      const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+      return new AsyncFunction('$', 'component', content)(scopedDollar, componentFn).catch((e) => {
+        console.warn('[vibe] Failed to execute component script:', e);
+      });
+    }
+    new Function('$', 'component', content)(scopedDollar, componentFn);
+  } catch (e) {
+    console.warn('[vibe] Failed to execute component script:', e);
+  }
+};
+
+// The wrapper's own setup script: the first vibe-module script in the wrapper's
+// subtree not owned by a nested component wrapper. Only THIS script may claim
+// the wrapper's build-tagged id — the id the stamped bindings reference — and
+// the rule must be deterministic across batches, not "first in this batch": a
+// later partial batch (a nested branch mount re-running one auxiliary script)
+// claiming the component's id would tear down the component's live `$.on` hooks
+// through executeScriptUnit's pre-run cleanup and never re-register them.
+const wrapperSetupScript = (wrapper) => {
+  for (const s of wrapper.querySelectorAll('script[type="vibe-module"]')) {
+    if (s.closest('[data-vibe-component-id]') === wrapper) return s;
+  }
+  return null;
+};
+
+const runVibeModuleScripts = (scripts, silent = false) => {
   const asyncTasks = [];
-  const claimed = new Set();
+  const registeredIds = [];
 
   for (const script of scripts) {
+    // One script node, one execution — native `<script>` semantics. Remounts
+    // clone fresh nodes from the restoration template (clones don't carry the
+    // marker), so they run; the same DOM node reached by overlapping passes
+    // (boot's document sweep after a pre-boot branch mount already ran it)
+    // does not run twice.
+    if (script.__vibeExecuted) continue;
+
     // Parity with the fetch path: dehydrated components never execute
     if (script.closest(`[${DEHYDRATE_CLASS_OR_ATTR}], .${DEHYDRATE_CLASS_OR_ATTR}`)) continue;
 
     const rawContent = script.textContent?.trim() || '';
     if (!rawContent) continue;
+    script.__vibeExecuted = true;
 
-    // The build tagged each component wrapper with its deterministic id —
-    // the same id the stamped bindings reference. First script in a wrapper
-    // claims it; additional scripts get fresh ids (mirrors the per-script
-    // ids of the fetch path).
     const wrapper = script.closest('[data-vibe-component-id]');
-    let componentId = wrapper?.getAttribute('data-vibe-component-id');
-    if (!componentId || claimed.has(componentId)) componentId = generateComponentId();
-    claimed.add(componentId);
+    const componentId =
+      wrapper && wrapperSetupScript(wrapper) === script
+        ? wrapper.getAttribute('data-vibe-component-id')
+        : generateComponentId();
 
     const { content, hasImports } = transformScriptContent(rawContent);
 
     const componentFn = (state) => {
-      if (!window.__vibeComponents) window.__vibeComponents = {};
-      window.__vibeComponents[componentId] = state;
-      if (window.$) window.$[componentId] = state;
+      registerComponentState(componentId, state, silent);
+      registeredIds.push(componentId);
       return componentId;
     };
 
-    runComponentCleanups(componentId);
-    const scopedDollar = createScopedDollar(componentId);
+    const task = enqueueScriptExecution(
+      executeScriptUnit(componentId, content, hasImports, createScopedDollar(componentId), componentFn),
+    );
+    if (task) asyncTasks.push(task);
+  }
 
-    try {
-      if (hasImports) {
-        const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
-        asyncTasks.push(new AsyncFunction('$', 'component', content)(scopedDollar, componentFn));
-      } else {
-        new Function('$', 'component', content)(scopedDollar, componentFn);
-      }
-    } catch (e) {
-      console.warn('[vibe] Failed to execute component script:', e);
+  // Silent mode: one grouped commit once every script has registered, so
+  // whole-`$` observers see all fresh keys with a single flush.
+  if (silent) {
+    if (asyncTasks.length) {
+      return Promise.all(asyncTasks).then(() => notifyChanged(registeredIds));
     }
+    notifyChanged(registeredIds);
+    return null;
   }
 
   return asyncTasks.length ? Promise.all(asyncTasks) : null;
@@ -278,21 +428,10 @@ export const abortComponentFetch = (element) => {
   }
 };
 
-// A fetched-component host: `<component>` or `<div class="component">`.
-export const isComponentWrapper = (el) =>
-  el.nodeName === 'COMPONENT' ||
-  (el.nodeName === 'DIV' && el.classList?.contains('component'));
-
 // The live element a reactive src binding acts on. The manifest tree keeps the
-// ORIGINAL element, but every (re)mount replaces the wrapper (finalize's
-// replaceWith), leaving a `_vibeReplacedBy` link behind. Follow the chain and
-// compress it so intermediate detached wrappers stay collectable.
-export const liveComponentWrapper = (element) => {
-  let live = element;
-  while (live._vibeReplacedBy) live = live._vibeReplacedBy;
-  if (live !== element) element._vibeReplacedBy = live;
-  return live;
-};
+// ORIGINAL element, but every (re)mount replaces the wrapper — staging.js's
+// chain resolver is the one implementation.
+export const liveComponentWrapper = liveNode;
 
 // (Re)mount a component for a reactive src binding (`src="@[page.src]"`).
 // Three phases of a wrapper's life, one entry point:
@@ -305,6 +444,7 @@ export const liveComponentWrapper = (element) => {
 //   the removal pass when replaceWith drops the old wrapper.
 export const remountComponent = (el, src, debug = false) => {
   const wasFetching = pendingFetches.has(el);
+  const hadSrcAttr = el.hasAttribute('src');
   // Compare against the LATEST requested src: with a fetch in flight the src
   // attribute holds it (rapid navigation A→B→A must abort B, not no-op on A);
   // mounted and idle, the finalize-stashed value does.
@@ -314,9 +454,33 @@ export const remountComponent = (el, src, debug = false) => {
   if (src === current) return;
   abortComponentFetch(el);
   el.setAttribute('src', src);
-  // Pre-fetch element: the boot/observer processComponent pass that hasn't
-  // reached it yet will pick up the new value — nothing to redo.
-  if (el._vibeMountedSrc === undefined && !wasFetching) return;
+  // Pre-fetch element awaiting its initial processing pass: that pass reads
+  // the new value — nothing to redo. A declaration-form wrapper (bound src
+  // that resolved to nothing, carried on data-vibe-src with no src
+  // attribute) was invisible to that pass, so hydration owns its first
+  // fetch too — the observer doesn't watch attributes.
+  if (el._vibeMountedSrc === undefined && !wasFetching && hadSrcAttr) return;
+  // The mounted content is now OUTGOING: it will be replaced wholesale when
+  // the new src lands, so re-rendering it against post-navigation state is
+  // pure waste — and is what made outgoing pages visually collapse the
+  // moment route state flipped. Both engines skip beneath a flagged wrapper
+  // (the wrapper's own src/key bindings stay live so a rapid next navigation
+  // still re-triggers). The flag dies with the wrapper at swap.
+  markOutgoing(el);
+  processSingle(el, debug);
+};
+
+// Key-change remount (`key="@[page.path]"`): mount the CURRENT src fresh even
+// though it is unchanged. Only a mounted, idle wrapper has anything to redo —
+// with a fetch pending the incoming mount is already fresh (a src change in
+// the same flush started it), and an unmounted wrapper's first mount is owned
+// by the normal processing pass.
+export const forceRemount = (el, debug = false) => {
+  if (pendingFetches.has(el) || el._vibeMountedSrc === undefined) return;
+  el.setAttribute('src', el._vibeMountedSrc);
+  // Same outgoing freeze as remountComponent — a keyed remount replaces the
+  // mounted content just the same.
+  markOutgoing(el);
   processSingle(el, debug);
 };
 
@@ -380,8 +544,15 @@ const tagScriptSiblings = (script, componentId) => {
     if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
       break;
     }
-    sibling.setAttribute('data-vibe-component-id', componentId);
-    rewriteThisBindings(sibling, componentId);
+    // A sibling already carrying an id is a build-tagged compiled wrapper
+    // that owns its scope — its `this.` bindings were rewritten to that id
+    // at compile time. Overwriting it re-scopes the wrapper to THIS script's
+    // id and orphans every `@[_cN.x]` binding inside it (the game's
+    // top-level create-teamplay modal losing its state).
+    if (!sibling.hasAttribute('data-vibe-component-id')) {
+      sibling.setAttribute('data-vibe-component-id', componentId);
+      rewriteThisBindings(sibling, componentId);
+    }
     sibling = sibling.nextElementSibling;
   }
 };
@@ -542,8 +713,11 @@ const processSingle = (el, debug) => {
   let props = el._vibeRemountProps;
   if (!props) {
     props = {};
+    // `src` and `key` are the wrapper's own contract (what to mount / when to
+    // remount), and data-vibe-* attributes are runtime transport — none of
+    // them are authored props for the component.
     Array.from(el.attributes).forEach((attr) => {
-      if (attr.name !== 'src') {
+      if (attr.name !== 'src' && attr.name !== 'key' && !attr.name.startsWith('data-vibe-')) {
         props[attr.name] = attr.value;
       }
     });
@@ -560,6 +734,13 @@ const processSingle = (el, debug) => {
 
   return fetchComponentTemplate(src, controller.signal)
     .then((html) => {
+      // Superseded before the template arrived: the cache path resolves
+      // regardless of the abort signal (aborting a cache hit is meaningless
+      // network-wise), so the supersede check lives here. A newer remount
+      // owns the wrapper — running this mount's scripts or finalize would
+      // land the stale fragment and discard the new one.
+      if (controller.signal.aborted) return;
+
       // Parse HTML in temporary container to process component scripts
       const temp = createDetached('div');
       temp.innerHTML = html;
@@ -601,9 +782,10 @@ const processSingle = (el, debug) => {
         // Sibling tagging is handled below (before script.remove()) so it works
         // for both sync and async scripts.
         const componentFn = (state) => {
-          if (!window.__vibeComponents) window.__vibeComponents = {};
-          window.__vibeComponents[componentId] = state;
-          if (window.$) window.$[componentId] = state;
+          // Fetched-mount registration is silent: the fetched subtree's
+          // hydration runs after replaceWith against live `$`, so a fresh id
+          // needs no flush (see registerComponentState / $.register).
+          registerComponentState(componentId, state, true);
           if (!registeredComponentIds.includes(componentId)) {
             registeredComponentIds.push(componentId);
           }
@@ -614,34 +796,17 @@ const processSingle = (el, debug) => {
           return componentId;
         };
 
-        // Re-running the script for a reused componentId (HMR remount) must
-        // tear down listeners from the previous evaluation before the fresh
-        // script registers new ones. Without this, every cycle stacks another
-        // listener on top of the stale closures and a single reactive tick
-        // fires N callbacks instead of one.
-        runComponentCleanups(componentId);
-
-        // Provide a per-script `$` whose `.on(...)` registers cleanups under
-        // this componentId. Bare `$` in the script body resolves to this
-        // Proxy (the function parameter shadows the global), so listener
-        // registrations are auto-tracked across `await` boundaries via the
-        // closure — no opt-in required.
-        const scopedDollar = createScopedDollar(componentId);
-
-        // Execute script with component() function in scope
-        try {
-          if (hasImports) {
-            // Async execution for scripts with imports
-            const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
-            asyncTasks.push(new AsyncFunction('$', 'component', scriptContent)(scopedDollar, componentFn));
-          } else {
-            // Synchronous execution for scripts without imports (preserves boot timing)
-            const executeFn = new Function('$', 'component', scriptContent);
-            executeFn(scopedDollar, componentFn);
-          }
-        } catch (e) {
-          console.warn('[vibe] Failed to execute component script:', e);
-        }
+        // Execute through the global script chain (see enqueueScriptExecution):
+        // cleanups for a reused componentId (HMR remount) tear down the prior
+        // evaluation's listeners right before the fresh run, the scoped `$`
+        // tracks this script's `.on(...)` registrations, and document-order
+        // execution holds even against scripts from other batches (a fetched
+        // component's script never runs while the shell's boot import is
+        // still in flight).
+        const task = enqueueScriptExecution(
+          executeScriptUnit(componentId, scriptContent, hasImports, createScopedDollar(componentId), componentFn),
+        );
+        if (task) asyncTasks.push(task);
 
         // Tag siblings + rewrite this. bindings using shared helper. Runs
         // BEFORE script.remove() so nextElementSibling is valid.
@@ -651,8 +816,27 @@ const processSingle = (el, debug) => {
         script.remove();
       }
 
+      // Evict everything this mount's scripts registered — state buckets AND
+      // their $.on listeners/unmount side effects. The scripts already RAN
+      // (execution precedes finalize), so skipping the cleanups here leaks
+      // live global listeners for DOM that never mounts.
+      const releaseRegisteredIds = () => {
+        for (const id of registeredComponentIds) {
+          delete window.__vibe?.components?.[id];
+          if (window.$) delete window.$[id];
+          runComponentCleanups(id);
+        }
+      };
+
       // Finalize: props, slots, DOM replacement
       const finalize = () => {
+        // Superseded DURING script execution (an async import held this mount
+        // while a newer remount aborted it): the newer fetch owns the wrapper.
+        if (controller.signal.aborted) {
+          releaseRegisteredIds();
+          return;
+        }
+
         // Delegate prop substitution + slot inlining to shared helper.
         const transformedHtml = renderPropsAndSlot(temp, props, children);
 
@@ -697,11 +881,17 @@ const processSingle = (el, debug) => {
           // attribute — the DOM alone carries the knowledge across swaps.
           const srcBinding = el._vibeSrcBinding ?? el.getAttribute('data-vibe-src');
           if (srcBinding) newWrapper.setAttribute('data-vibe-src', srcBinding);
+          // The key binding and its last resolved value ride along the same
+          // way, so a later key change still finds what to compare against
+          // on the replacement wrapper.
+          const keyBinding = el._vibeKeyBinding ?? el.getAttribute('data-vibe-key');
+          if (keyBinding) newWrapper.setAttribute('data-vibe-key', keyBinding);
+          if (el._vibeMountedKey !== undefined) newWrapper._vibeMountedKey = el._vibeMountedKey;
           // Transfer iteration-prop registry ownership from the soon-to-be-
           // detached `<component src>` to the new wrapper. The detached element
           // would otherwise trigger releaseOrphanedIterationProps and free the
           // registry slots that the inlined template's bindings still reference,
-          // causing every `@[window.__vibeiterprops._pN]` to resolve to undefined
+          // causing every `@[window.__vibe.iterProps._pN]` to resolve to undefined
           // on the next hydrate.
           if (el._vibeIterPropIds) {
             newWrapper._vibeIterPropIds = el._vibeIterPropIds;
@@ -715,6 +905,7 @@ const processSingle = (el, debug) => {
           if (el.hasAttribute('data-vibe-iter-prop')) {
             newWrapper.setAttribute('data-vibe-iter-prop', '');
             el.removeAttribute('data-vibe-iter-prop');
+            bumpIterPropGeneration();
           }
           // Transfer the original prop expressions too, so the iteration's
           // update path can re-evaluate them against the row's new scope and
@@ -732,21 +923,85 @@ const processSingle = (el, debug) => {
           // renderAllConditionals/Iterations populated runtime data) is what
           // iterate.js's update path uses to re-evaluate inlined bindings on
           // each row update.
+          // The observer hydrates the inserted subtree in its NEXT batch —
+          // until then, selectors keyed on hydrated attributes (a name-bound
+          // <page @[page.name]> → page[pvp] rules) don't match and the
+          // content paints unstyled. Cover the gap with the same fouc
+          // contract pages use: hidden at insertion, revealed by the batch
+          // that parsed and hydrated this subtree.
+          newWrapper.setAttribute('vibe-fouc', '');
           el._vibeReplacedBy = newWrapper;
-          el.replaceWith(newWrapper);
+          if (el._vibeOutgoing) {
+            // REMOUNT (route/key change): stage, don't swap — staging.js owns
+            // the transition (display:none sibling now, one-paint commit in
+            // tryReveal below).
+            stageIncoming(el, newWrapper);
+          } else {
+            el.replaceWith(newWrapper);
+          }
           debugLog(fromCache ? PHASE_FETCH_CACHED : PHASE_FETCH, src, debug);
 
+          // The mount's own script registrations commit as one batch — the
+          // subtree hydrates via the observer against live `$`, so the only
+          // consumers needing a flush are whole-`$` observers elsewhere.
+          notifyChanged(registeredComponentIds);
+
+          // Build-inlined child components (compiled SPA fragments) arrive
+          // with tagged wrapper ids and vibe-module scripts — the compiled-
+          // document form. A fetched mount is the fourth delivery mode after
+          // boot, conditional branches, and iteration rows: run those
+          // scripts now so each child's component({...}) state registers
+          // under its build-tagged id and the _cN bindings hydrate. Silent:
+          // their registrations commit as one grouped notify when the
+          // scripts settle — per-script flushes would re-walk the page N
+          // times (the 26-script game fragments spent ~150ms/navigation on
+          // exactly that). The settle promise also gates the reveal below:
+          // a slow module import delays registration, and until it lands the
+          // subtree's `this.`-derived bindings hydrate to junk (NaN widths —
+          // the game's "Making potion" bar painting full/empty mid-mount).
+          const scriptsSettled = Promise.resolve(
+            executeCompiledComponentScriptsIn([newWrapper], { silent: true }),
+          );
+
           // MutationObserver handles parsing and hydrating the new content.
           // Branch nodes are registered in the manifest by mountBranch,
           // so the observer can find parents even inside conditional branches.
+          // Hydration can span multiple batches (nested fetched components,
+          // async scripts) with paints in between — reveal only when the
+          // wrapper's scripts have settled AND the subtree carries no raw
+          // bindings (same predicate the page-level ready uses). The grouped
+          // registration notify queues its correction flush BEFORE the settle
+          // callback runs, so the recheck sees post-correction DOM in the
+          // same microtask drain — the first painted frame is the true one.
+          // A wrapper unmounted mid-hydration releases the hook.
+          let scriptsDone = false;
+          const tryReveal = () => {
+            if (!newWrapper.isConnected) {
+              abandonStaged(newWrapper);
+              newWrapper.removeAttribute('vibe-fouc');
+              unfouc();
+              return;
+            }
+            if (!scriptsDone || !shouldCleanup(newWrapper)) return;
+            // Atomic visual commit: old page out, parked styling-context
+            // bindings applied, new page revealed — one synchronous block,
+            // one paint. Until this moment the outgoing page was still the
+            // one on screen, fully styled.
+            commitStaged(newWrapper);
+            newWrapper.removeAttribute('vibe-fouc');
+            unfouc();
+          };
+          const unfouc = window.$.on('afterDomMutation', tryReveal);
+          scriptsSettled.then(() => {
+            scriptsDone = true;
+            tryReveal();
+          });
         } else {
           // Element was detached before finalize ran (conditional unmounted
           // during fetch, parent removed, etc). Release any state component()
           // calls registered — otherwise it leaks on `$` forever.
-          for (const id of registeredComponentIds) {
-            delete window.__vibeComponents?.[id];
-            if (window.$) delete window.$[id];
-          }
+          releaseOutgoing(el);
+          releaseRegisteredIds();
         }
       };
 
@@ -761,12 +1016,19 @@ const processSingle = (el, debug) => {
       // Clean up pending fetch tracker — ownership-guarded (see finalize)
       if (pendingFetches.get(el) === controller) pendingFetches.delete(el);
 
-      // If fetch was aborted (element removed or re-mounted), silently skip
+      // Aborted fetch: a removal-abort (wrapper left the DOM mid-remount)
+      // has no commit left to release its outgoing freeze — free the root
+      // here or the detached page subtree stays pinned in
+      // activeOutgoingRoots for the session. A supersede-abort (newer
+      // remount on the same, still-connected wrapper) keeps it: the new
+      // fetch owns the freeze.
       if (error.name === 'AbortError') {
+        if (!el.isConnected) releaseOutgoing(el);
         return;
       }
 
       console.error('[vibe] Failed to load:', src, error);
+      releaseOutgoing(el);
       if (el.parentNode) {
         el.remove();
       }