@ape-egg/vibe 2.3.0 → 3.0.0

package/runtime/hydrate.js

@@ -1,12 +1,201 @@
 import { updateIteration } from './iterate.js';
 import { updateConditional, managedNodes } from './conditionals.js';
-import { isComponentWrapper, liveComponentWrapper, remountComponent, forceRemount } from './component.js';
+import { liveComponentWrapper, remountComponent, forceRemount } from './component.js';
+import { isComponentWrapper, parkRootFor, parkBinding } from './staging.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
-import { evalInScope, resolveCaseInsensitivePath } from './utils.js';
+import { evalInScope, resolveCaseInsensitivePath, overlayKeysOf } from './utils.js';
 import { RawHtml } from './raw-html.js';
+import { beginTracking, endTracking } from './tracking.js';
+import { reportEvalError } from './debug.js';
+
+// Run one entry's evaluation inside a tracking window. The subscriber is
+// hosted on the walk's cached binding object (aff.binding) — stable per
+// binding across flushes, invalidated exactly when the binding cache
+// rebuilds. Entries without a binding host (hand-built lists from external
+// callers) evaluate untracked, exactly as before.
+const tracked = (aff, effectiveState, fn) => {
+  const m = aff.binding;
+  if (!m) return fn();
+  const sub = (m._sub ??= {
+    kind: aff.type ?? 'text',
+    anchor: aff.textNode ?? aff.element,
+  });
+  sub.entry = aff; // latest entry shape — dispatch rebuilds scope at fire time
+  sub.lastScope = effectiveState; // overlay source for dispatch-time rescoping
+  beginTracking(sub, overlayKeysOf(effectiveState));
+  try {
+    return fn();
+  } finally {
+    endTracking();
+  }
+};
+
+const applyNameBinding = (aff, effectiveState) => {
+  const { nameBinding, matchInner, element } = aff;
+  try {
+    // HTML lowercases attribute names, so we need case-insensitive lookup.
+    // Try exact match first, then walk the path case-insensitively if the
+    // exact lookup returned nothing — this recovers camelCase property
+    // names in dotted paths like `<icon @[fx.convertsIcon]>` (arrives at
+    // runtime as `@[fx.convertsicon]`).
+    let attrName = evalInScope(matchInner, effectiveState, element);
+
+    if (!attrName) {
+      attrName = resolveCaseInsensitivePath(effectiveState, matchInner);
+    }
+
+    // Track multiple name bindings per element (need a map of binding -> evaluated attr)
+    if (!element._vibeNameBindings) {
+      element._vibeNameBindings = new Map();
+    }
+
+    // Remove the old evaluated attribute for this specific binding
+    const oldAttrName = element._vibeNameBindings.get(nameBinding);
+    if (oldAttrName) {
+      element.removeAttribute(oldAttrName);
+    }
+
+    // Remove the binding attribute itself
+    if (element.hasAttribute(nameBinding)) {
+      element.removeAttribute(nameBinding);
+    }
+
+    // Set the new attribute (empty value for boolean-like attributes)
+    if (attrName) {
+      element.setAttribute(attrName, '');
+      element._vibeNameBindings.set(nameBinding, attrName);
+    } else {
+      element._vibeNameBindings.delete(nameBinding);
+    }
+
+    // A binding relocated into `data-vibe-namebind` (clone path) has served its
+    // transport purpose once the real attribute is set — drop it so the rendered
+    // DOM matches the batch path, which never emits it.
+    if (element.hasAttribute('data-vibe-namebind')) {
+      element.removeAttribute('data-vibe-namebind');
+    }
+  } catch (e) {
+    console.error('Error hydrating name binding:', e);
+  }
+};
+
+const applyAttributeBinding = (aff, effectiveState) => {
+  const { attrName, attrValue, element } = aff;
+  try {
+    // Check if this is a pure binding (e.g., value="@[inputValue]")
+    const isPureBinding = attrValue.match(PURE_BINDING_REGEX);
+    const isDomProperty = DOM_PROPERTIES.includes(attrName);
+    // Value attrs keep their string value; everything else is boolean-like (removed when falsy)
+    const isValueAttr =
+      VALUE_ATTRS.includes(attrName) ||
+      attrName.startsWith('data-') ||
+      attrName.startsWith('aria-') ||
+      attrName.startsWith('on');
+
+    if (isDomProperty && isPureBinding) {
+      // For DOM properties (value, checked, selected), set BOTH property AND attribute
+      // Property: Fast runtime updates, what the user sees
+      // Attribute: Truthful DOM representation, enables compiler snapshots via outerHTML
+      const expr = isPureBinding[1];
+      const value = evalInScope(expr, effectiveState, element);
+      if (element[attrName] !== value) element[attrName] = value;
+      if (attrName === 'value') {
+        if (value !== undefined && value !== null) {
+          const str = String(value);
+          if (element.getAttribute(attrName) !== str) element.setAttribute(attrName, str);
+        }
+      } else if (value) {
+        // checked/selected are boolean — the truthful attribute form is
+        // presence (empty) when truthy, absence when falsy. Stringifying
+        // would leave checked="false", which is "checked" to CSS and HTML.
+        if (element.getAttribute(attrName) !== '') element.setAttribute(attrName, '');
+      } else if (element.hasAttribute(attrName)) {
+        element.removeAttribute(attrName);
+      }
+    } else if (!isValueAttr && isPureBinding) {
+      // Boolean-like attributes: add or remove based on truthiness.
+      // Compare both presence AND value — initial hydration starts with
+      // the raw `@[...]` binding text as the attribute value, so
+      // `hasAttribute` alone isn't enough to know the canonical state is
+      // already set.
+      const expr = isPureBinding[1];
+      const value = evalInScope(expr, effectiveState, element);
+      if (value) {
+        if (element.getAttribute(attrName) !== '') {
+          element.setAttribute(attrName, '');
+        }
+      } else if (element.hasAttribute(attrName)) {
+        element.removeAttribute(attrName);
+      }
+    } else {
+      // Value attribute - replace bindings with values
+      const newValue = attrValue.replace(BINDING_REGEX, (_, expr) => {
+        return evalInScope(expr, effectiveState, element);
+      });
+      if (element.getAttribute(attrName) !== newValue) {
+        element.setAttribute(attrName, newValue);
+      }
+    }
+  } catch (e) {
+    reportEvalError(attrValue, element, e);
+  }
+};
 
 export default (affected, state, manifest = {}, oldState = {}) => {
-  affected.forEach((aff) => {
+  // Wrappers that entered a reactive-src remount DURING this pass (the src/key
+  // handlers below). affected() collected this list before the outgoing flag
+  // existed, so the outgoing subtree's entries are still in it — and this is
+  // exactly the flush where route state flips. Applying them would paint the
+  // outgoing page against the incoming route for the whole fetch+mount window
+  // (the mid-navigation CSS collapse). Tree-walk order guarantees the
+  // wrapper's own src/key entries precede its subtree's entries, so skipping
+  // by ancestry here is airtight. Null until a remount actually happens —
+  // zero cost on ordinary flushes.
+  let outgoingRoots = null;
+  const underOutgoingRoot = (aff) => {
+    if (!outgoingRoots) return false;
+    const el = aff.element ?? aff.node?.meta?.startComment?.parentElement;
+    if (!el) return false;
+    for (let i = 0; i < outgoingRoots.length; i++) {
+      const root = outgoingRoots[i];
+      if (root !== el && root.contains(el)) return true;
+    }
+    return false;
+  };
+
+  // Two passes: wrapper src/key entries (remount triggers) first, everything
+  // else second. A remount marks its wrapper outgoing and starts staging —
+  // the freeze skip below and the ancestor-binding parking both depend on
+  // that registration, and tree-walk order would otherwise process an
+  // ancestor's bindings (the `<page @[page.name]>` styling context) before
+  // the outlet entry that begins the staging they must park against.
+  const remountTriggers = [];
+  const ordinary = [];
+  for (const aff of affected) {
+    const isRemountTrigger =
+      aff.type === 'attribute' &&
+      (aff.attrName === 'src' || aff.attrName === 'key') &&
+      isComponentWrapper(aff.element);
+    (isRemountTrigger ? remountTriggers : ordinary).push(aff);
+  }
+
+  const processEntry = (aff) => {
+    if (underOutgoingRoot(aff)) return;
+
+    // Torn down mid-pass: the entry's target was connected when the walk
+    // collected it but left the document before this entry processed — an
+    // earlier entry's teardown (an iteration emptying, a branch flip)
+    // removed it. Same ordering hole as the outgoing-remount skip above.
+    // Processing it would write to dead DOM and re-register a subscriber
+    // the teardown just pruned, pinning the removed subtree. Entries that
+    // were ALREADY detached at collection (initializeBlock hydrating a
+    // fresh row inside its parse container) pass through untouched.
+    if (aff.wasConnected) {
+      const target =
+        aff.textNode ?? aff.element ?? aff.node?.meta?.startComment;
+      if (target && !target.isConnected) return;
+    }
+
     // Use scoped state if provided (from iteration instances)
     const effectiveState = aff.scopedState || state;
 
@@ -30,52 +219,14 @@ export default (affected, state, manifest = {}, oldState = {}) => {
 
     // Handle name bindings (e.g., <icon @[section.icon]>)
     if (aff.type === 'nameBinding') {
-      const { nameBinding, matchInner, element } = aff;
-      try {
-        // HTML lowercases attribute names, so we need case-insensitive lookup.
-        // Try exact match first, then walk the path case-insensitively if the
-        // exact lookup returned nothing — this recovers camelCase property
-        // names in dotted paths like `<icon @[fx.convertsIcon]>` (arrives at
-        // runtime as `@[fx.convertsicon]`).
-        let attrName = evalInScope(matchInner, effectiveState, element);
-
-        if (!attrName) {
-          attrName = resolveCaseInsensitivePath(effectiveState, matchInner);
-        }
-
-        // Track multiple name bindings per element (need a map of binding -> evaluated attr)
-        if (!element._vibeNameBindings) {
-          element._vibeNameBindings = new Map();
-        }
-
-        // Remove the old evaluated attribute for this specific binding
-        const oldAttrName = element._vibeNameBindings.get(nameBinding);
-        if (oldAttrName) {
-          element.removeAttribute(oldAttrName);
-        }
-
-        // Remove the binding attribute itself
-        if (element.hasAttribute(nameBinding)) {
-          element.removeAttribute(nameBinding);
-        }
-
-        // Set the new attribute (empty value for boolean-like attributes)
-        if (attrName) {
-          element.setAttribute(attrName, '');
-          element._vibeNameBindings.set(nameBinding, attrName);
-        } else {
-          element._vibeNameBindings.delete(nameBinding);
-        }
-
-        // A binding relocated into `data-vibe-namebind` (clone path) has served its
-        // transport purpose once the real attribute is set — drop it so the rendered
-        // DOM matches the batch path, which never emits it.
-        if (element.hasAttribute('data-vibe-namebind')) {
-          element.removeAttribute('data-vibe-namebind');
-        }
-      } catch (e) {
-        console.error('Error hydrating name binding:', e);
+      const parkRoot = parkRootFor(aff.element);
+      if (parkRoot) {
+        parkBinding(parkRoot, aff.element, 'nb:' + aff.nameBinding, () =>
+          applyNameBinding(aff, effectiveState),
+        );
+        return;
       }
+      tracked(aff, effectiveState, () => applyNameBinding(aff, effectiveState));
       return;
     }
 
@@ -98,24 +249,30 @@ export default (affected, state, manifest = {}, oldState = {}) => {
         // the mount itself is owned by the normal component pass.
         if (attrName === 'key' && isComponentWrapper(element)) {
           const live = liveComponentWrapper(element);
-          const newKey = attrValue.replace(BINDING_REGEX, (_, expr) =>
-            evalInScope(expr, effectiveState, live) ?? '',
+          const newKey = tracked(aff, effectiveState, () =>
+            attrValue.replace(BINDING_REGEX, (_, expr) =>
+              evalInScope(expr, effectiveState, live) ?? '',
+            ),
           );
           live._vibeKeyBinding = attrValue;
           const prevKey = live._vibeMountedKey;
           live._vibeMountedKey = newKey;
           if (prevKey !== undefined && newKey !== prevKey) forceRemount(live);
+          if (live._vibeOutgoing) (outgoingRoots ??= []).push(live);
           return;
         }
 
         if (attrName === 'src' && isComponentWrapper(element)) {
           const live = liveComponentWrapper(element);
-          const newSrc = attrValue.replace(BINDING_REGEX, (_, expr) =>
-            evalInScope(expr, effectiveState, live) ?? '',
+          const newSrc = tracked(aff, effectiveState, () =>
+            attrValue.replace(BINDING_REGEX, (_, expr) =>
+              evalInScope(expr, effectiveState, live) ?? '',
+            ),
           );
           live._vibeSrcBinding = attrValue;
           if (newSrc) {
             remountComponent(live, newSrc);
+            if (live._vibeOutgoing) (outgoingRoots ??= []).push(live);
           } else if (live.hasAttribute('src')) {
             // Unresolved src mounts nothing (a no-match deep link leaves
             // $.page.src unset): move the binding onto data-vibe-src — the
@@ -128,61 +285,17 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           return;
         }
 
-        // Check if this is a pure binding (e.g., value="@[inputValue]")
-        const isPureBinding = attrValue.match(PURE_BINDING_REGEX);
-        const isDomProperty = DOM_PROPERTIES.includes(attrName);
-        // Value attrs keep their string value; everything else is boolean-like (removed when falsy)
-        const isValueAttr =
-          VALUE_ATTRS.includes(attrName) ||
-          attrName.startsWith('data-') ||
-          attrName.startsWith('aria-') ||
-          attrName.startsWith('on');
-
-        if (isDomProperty && isPureBinding) {
-          // For DOM properties (value, checked, selected), set BOTH property AND attribute
-          // Property: Fast runtime updates, what the user sees
-          // Attribute: Truthful DOM representation, enables compiler snapshots via outerHTML
-          const expr = isPureBinding[1];
-          const value = evalInScope(expr, effectiveState, element);
-          if (element[attrName] !== value) element[attrName] = value;
-          if (attrName === 'value') {
-            if (value !== undefined && value !== null) {
-              const str = String(value);
-              if (element.getAttribute(attrName) !== str) element.setAttribute(attrName, str);
-            }
-          } else if (value) {
-            // checked/selected are boolean — the truthful attribute form is
-            // presence (empty) when truthy, absence when falsy. Stringifying
-            // would leave checked="false", which is "checked" to CSS and HTML.
-            if (element.getAttribute(attrName) !== '') element.setAttribute(attrName, '');
-          } else if (element.hasAttribute(attrName)) {
-            element.removeAttribute(attrName);
-          }
-        } else if (!isValueAttr && isPureBinding) {
-          // Boolean-like attributes: add or remove based on truthiness.
-          // Compare both presence AND value — initial hydration starts with
-          // the raw `@[...]` binding text as the attribute value, so
-          // `hasAttribute` alone isn't enough to know the canonical state is
-          // already set.
-          const expr = isPureBinding[1];
-          const value = evalInScope(expr, effectiveState, element);
-          if (value) {
-            if (element.getAttribute(attrName) !== '') {
-              element.setAttribute(attrName, '');
-            }
-          } else if (element.hasAttribute(attrName)) {
-            element.removeAttribute(attrName);
-          }
-        } else {
-          // Value attribute - replace bindings with values
-          const newValue = attrValue.replace(BINDING_REGEX, (_, expr) => {
-            return evalInScope(expr, effectiveState, element);
-          });
-          if (element.getAttribute(attrName) !== newValue) {
-            element.setAttribute(attrName, newValue);
-          }
+        const parkRoot = parkRootFor(element);
+        if (parkRoot) {
+          parkBinding(parkRoot, element, 'attr:' + attrName, () =>
+            applyAttributeBinding(aff, effectiveState),
+          );
+          return;
         }
-      } catch (e) {}
+        tracked(aff, effectiveState, () => applyAttributeBinding(aff, effectiveState));
+      } catch (e) {
+        reportEvalError(aff.attrValue ?? aff.matchInner, aff.element, e);
+      }
       return;
     }
 
@@ -192,7 +305,9 @@ export default (affected, state, manifest = {}, oldState = {}) => {
     // This prevents undefined store properties to throw an error
     try {
       // Evaluate the expression with state as context
-      const evaluated = evalInScope(matchInner, effectiveState, element);
+      const evaluated = tracked(aff, effectiveState, () =>
+        evalInScope(matchInner, effectiveState, element),
+      );
 
       // Raw-HTML render: `$.unsafe(str)` returns a RawHtml marker. When the
       // binding is the sole content of its element (`<p>@[$.unsafe(x)]</p>`),
@@ -212,10 +327,18 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           element._vibeRawHtmlValue = html;
         }
         element._vibeRawHtml = true;
+        // The injection consumed the entry's original text node. Re-anchor
+        // the subscriber on the ELEMENT (which survives every injection) —
+        // otherwise the dispatch engine prunes it as dead after the first
+        // render and the binding silently stops re-rendering.
+        if (aff.binding?._sub) aff.binding._sub.anchor = element;
         return;
       }
 
-      const toReplace = input.replaceAll(matchOuter, evaluated).trim();
+      // Function replacer: a string replacement would run GetSubstitution on
+      // the VALUE — `$$` collapses, `$&` re-inserts the binding text into the
+      // DOM (which the settle gates then read as an unhydrated binding).
+      const toReplace = input.replaceAll(matchOuter, () => evaluated).trim();
 
       affected.forEach((innerAff) => {
         if (innerAff.element === element) {
@@ -234,11 +357,28 @@ export default (affected, state, manifest = {}, oldState = {}) => {
       // value actually changed. Reactivity coverage is unchanged: state changes
       // that produce a new value still apply; state changes that don't are now
       // proper no-ops at the DOM layer.
-      if (textNode && textNode.nodeType === 3) {
+      if (element._vibeRawHtml && !(textNode && textNode.isConnected)) {
+        // unsafe → escaped transition: an earlier injection consumed the
+        // entry's text node, so the element itself takes the escaped text —
+        // and the entry ADOPTS the fresh node, so the NEXT escaped update
+        // writes live DOM instead of the consumed original.
+        element.textContent = toReplace;
+        element._vibeRawHtml = false;
+        element._vibeRawHtmlValue = undefined;
+        if (textNode) {
+          if (!element.firstChild) element.appendChild(document.createTextNode(''));
+          aff.textNode = element.firstChild;
+        }
+      } else if (textNode && textNode.nodeType === 3) {
         if (textNode.textContent !== toReplace) textNode.textContent = toReplace;
       } else if (element.textContent !== toReplace) {
         element.textContent = toReplace;
       }
-    } catch (e) {}
-  });
+    } catch (e) {
+      reportEvalError(matchInner ?? input, element, e);
+    }
+  };
+
+  remountTriggers.forEach(processEntry);
+  ordinary.forEach(processEntry);
 };