@ape-egg/vibe 2.1.22 → 3.0.0

package/runtime/index.js

@@ -1,12 +1,12 @@
-import state from './state.js';
+import state, { silentSet } from './state.js';
 import parse from './parse.js';
-import createManifest from './manifest.js';
+import createManifest, { setManifestEntry, manifestPathOf, removeManifestSubtree } from './manifest.js';
 import hydrate from './hydrate.js';
 import affected from './affected.js';
 import { deepMerge, hash, setRootState } from './utils.js';
 import { unsafe } from './raw-html.js';
 import { renderAllIterations, setRenderAllConditionals, releaseOrphanedIterationProps } from './iterate.js';
-import { renderAllConditionals, branchNodeRegistry, managedNodes } from './conditionals.js';
+import { renderAllConditionals, branchNodeRegistry, managedNodes , settleConditionals} from './conditionals.js';
 import { installScopeResolver } from './loop-scope.js';
 import {
   NON_REACTIVE_ELEMENTS,
@@ -26,6 +26,8 @@ import {
 import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate, executeCompiledComponentScripts } from './component.js';
 import { configureComponentCache, clearComponentCache } from './component-cache.js';
 import { debugLog } from './debug.js';
+import { pruneDisconnected, beginFlush } from './tracking.js';
+import dispatchFlush from './dispatch.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
 import { reconcile } from './reconcile.js';
 import {
@@ -136,7 +138,7 @@ const ensureNode = (tree, path) => {
 
 // Recursively add parsed tree nodes to manifest (like createManifest does)
 const addToManifest = (tree, manifest, dotPath) => {
-  manifest[dotPath] = tree.element;
+  setManifestEntry(manifest, dotPath, tree.element);
 
   if (tree.children && Object.keys(tree.children).length > 0) {
     Object.keys(tree.children).forEach((childKey) => {
@@ -372,7 +374,7 @@ let previousState = {};
 const main = (s, config = {}, stringSelector = '') => {
   const debug = !!config?.debug;
   const verbose = !!config?.verbose;
-  globalThis.__vibeDebug = debug;
+  ((globalThis.__vibe ??= {}).debug = debug);
 
   // Enable/disable the component template cache from config (`{ noCache }`).
   configureComponentCache(config);
@@ -382,7 +384,7 @@ const main = (s, config = {}, stringSelector = '') => {
 
   // Detect if running in compiler's headless browser
   // When true: skip cleanup to preserve [vibe] attribute in compiled HTML
-  const isCompiling = typeof window !== 'undefined' && window.__vibeCompiling === true;
+  const isCompiling = typeof window !== 'undefined' && window.__vibe?.compiling === true;
 
   // Reset previous state for each new instance
   previousState = {};
@@ -571,6 +573,12 @@ const main = (s, config = {}, stringSelector = '') => {
     unmount: [],
   };
 
+  // The ready phase happens once. A listener registered after it fires
+  // immediately (parity with the late-safe $.ready promise) — late
+  // registration is the SPA norm, where fragment scripts run on mount,
+  // long after the shell booted.
+  let readyFired = false;
+
   // Page-scope 'unmount': the visitor actually leaving — pagehide (navigation
   // away, tab close). Deliberately NOT visibilitychange: a tab switch is not
   // an unmount, the visitor comes back. Inside a component script the same
@@ -608,6 +616,47 @@ const main = (s, config = {}, stringSelector = '') => {
 
   // Observer callback will be defined below (already declared above before processComponent)
 
+  // Pause the observer around an engine patch phase (its DOM writes are the
+  // engine's own), then replay anything that queued while paused and resolve
+  // fresh <component src> mounts. Shared by the walk flush and the
+  // subscription dispatch flush.
+  const patchWithObserverPaused = (patch) => {
+    // Capture pending mutations before disconnecting (takeRecords clears the queue)
+    let pendingMutations = [];
+    if (observer) {
+      pendingMutations = observer.takeRecords();
+      observer.disconnect();
+    }
+
+    patch();
+
+    if (observer) {
+      observer.observe(rootElement, {
+        attributes: false,
+        characterData: false,
+        childList: true,
+        subtree: true,
+      });
+
+      // Process mutations that were pending before we disconnected
+      if (pendingMutations.length > 0 && processMutations) {
+        processMutations(pendingMutations);
+      }
+    }
+
+    // The patch may have mounted new DOM while the observer was disconnected.
+    // Scan for unresolved <component src=""> elements that need fetching.
+    if (componentProcessingStarted) {
+      const componentConfig = {
+        ...config,
+        _forceSync: true,
+        _observer: observer,
+        _processMutations: processMutations,
+      };
+      processComponent(rootElement, null, componentConfig);
+    }
+  };
+
   const $ = state(s, (changedProps) => {
     // Selective extraction: only extract changed props, preserve references for unchanged.
     // This ensures affected() correctly skips iterations whose arrays didn't change,
@@ -627,52 +676,17 @@ const main = (s, config = {}, stringSelector = '') => {
       }
     }
 
-    // Find what changed (compare previousState vs currentState)
-    const affectedElements = affected(parsedTree, previousState, currentState);
-
-    if (affectedElements.length > 0) {
+    // THE update path: the flush is served from the subscription reverse
+    // index — a write notifies exactly its subscribers, O(change). The walk
+    // (`affected()`) exists only as the MOUNT path now: first hydration,
+    // processMutations, fresh branches and rows, where it registers new
+    // subscribers via their first evaluation.
+    const dirty = beginFlush(changedProps);
+    if (dirty.size > 0) {
       debugLog(PHASE_UPDATE, 'state changed', debug);
-
-      // Capture pending mutations before disconnecting (takeRecords clears the queue)
-      let pendingMutations = [];
-      if (observer) {
-        pendingMutations = observer.takeRecords();
-        observer.disconnect();
-      }
-
-      // Run core loop on the full tree (hydrate will use affected list)
-      // isNewNode = false because this is a state update, not a DOM mutation
-      hydrate(affectedElements, currentState, manifest, previousState);
-
-      // After hydrate, check for conditional/iteration changes
-      const conditionalCount = renderAllConditionals(parsedTree, currentState, manifest);
-      const iterationCount = renderAllIterations(parsedTree, currentState, manifest);
-
-      if (observer) {
-        observer.observe(rootElement, {
-          attributes: false,
-          characterData: false,
-          childList: true,
-          subtree: true,
-        });
-
-        // Process mutations that were pending before we disconnected
-        if (pendingMutations.length > 0 && processMutations) {
-          processMutations(pendingMutations);
-        }
-      }
-
-      // Conditionals/iterations may have mounted new DOM while observer was disconnected.
-      // Scan for unresolved <component src=""> elements that need fetching.
-      if (componentProcessingStarted) {
-        const componentConfig = {
-          ...config,
-          _forceSync: true,
-          _observer: observer,
-          _processMutations: processMutations,
-        };
-        processComponent(rootElement, null, componentConfig);
-      }
+      patchWithObserverPaused(() => {
+        dispatchFlush(dirty, currentState, previousState, manifest);
+      });
     }
 
     // Store previous state for hooks (currentState is already plain, no need to clone)
@@ -687,8 +701,49 @@ const main = (s, config = {}, stringSelector = '') => {
   // — the Proxy invariant rejects overriding non-configurable + non-writable
   // data properties. Enumerable stays false so `on` doesn't leak into state
   // snapshots or Object.keys($).
+  // Late ready — a `$.on('ready')` AFTER boot (a fetched fragment's script,
+  // an SPA mount's app-boot module) defers until the registering mount
+  // SETTLES: content inserted, attributes hydrated, staging committed, fouc
+  // gates released. That makes `$.on('ready')` ≡ `await $.ready` genuinely
+  // true — DOM-touching ready work (querySelector, scroll-spy) sees the
+  // mounted subtree in both forms. With nothing in flight the microtask
+  // flush fires on the same tick `await $.ready` would resume on.
+  const lateReady = [];
+  let lateReadyWatch = null;
+  // Settlement is judged against the MANAGED root, same as boot ready —
+  // content outside a config.target root is never scanned, so its literal
+  // @[...] text must not starve the late-ready queue.
+  const mountsSettled = () =>
+    !document.querySelector('[vibe-staged], [vibe-fouc]') && shouldCleanup(rootElement);
+  const flushLateReady = () => {
+    if (lateReady.length === 0 || !mountsSettled()) return;
+    if (lateReadyWatch) {
+      lateReadyWatch();
+      lateReadyWatch = null;
+    }
+    for (const cb of lateReady.splice(0)) {
+      try {
+        cb();
+      } catch (error) {
+        console.error('[vibe] Error in ready hook:', error);
+      }
+    }
+  };
+  const queueLateReady = (callback) => {
+    lateReady.push(callback);
+    lateReadyWatch ??= $.on('afterDomMutation', flushLateReady);
+    Promise.resolve().then(flushLateReady);
+    return () => {
+      const i = lateReady.indexOf(callback);
+      if (i >= 0) lateReady.splice(i, 1);
+    };
+  };
+
   Object.defineProperty($, 'on', {
     value: (event, callback) => {
+      if (event === 'ready' && readyFired) {
+        return queueLateReady(callback);
+      }
       if (hooks[event]) {
         hooks[event].push(callback);
       }
@@ -714,6 +769,37 @@ const main = (s, config = {}, stringSelector = '') => {
     enumerable: false,
   });
 
+  // Register a component's state bucket under its id (the fetched-mount path).
+  // A FRESH id is a key nothing in the live tree can bind yet — its subtree
+  // enters the reactive tree only after this write — so the write lands
+  // silently (raw target, no global flush) and previousState is deliberately
+  // NOT seeded: the mount's grouped notify must see undefined → state as a
+  // real diff (see the inline comment below — the load-bearing invariant).
+  // Re-registering an EXISTING id (an HMR re-run) is a real value change for
+  // live bindings and flushes normally.
+  Object.defineProperty($, '_register', {
+    value: (componentId, componentState) => {
+      if (componentId in $) {
+        $[componentId] = componentState;
+        return componentId;
+      }
+      // Raw write only — previousState is deliberately NOT seeded. The mount
+      // commits all its registrations in one notifyChanged batch when its
+      // scripts settle, and that flush must see each fresh id as a real
+      // change (undefined -> state): the subtree may have hydrated BEFORE the
+      // script ran (scripts execute in module order behind earlier imports),
+      // so this correction flush is what renders bindings, conditionals and
+      // iterations that read the component's state. A seeded previousState
+      // made the diff vacuous whenever the script filled its state object
+      // before calling component() — the game's fill-then-register pages
+      // stayed frozen at their pre-registration (empty) render.
+      silentSet($, componentId, componentState);
+      return componentId;
+    },
+    enumerable: false,
+    configurable: true,
+  });
+
   // Mark a trusted string as raw HTML. A binding that is the sole content of
   // its element — `<p>@[$.unsafe(desc)]</p>` — sets innerHTML from the string
   // instead of escaping it via textContent. Trusted input only (no sanitizing,
@@ -729,7 +815,7 @@ const main = (s, config = {}, stringSelector = '') => {
   // processed HTML string the plugin's HMR handler can hand to $.reconcile.
   // Scripts are NOT executed — callers use this only when they've verified
   // script contents haven't changed (so registered state is still valid).
-  Object.defineProperty($, 'renderComponent', {
+  Object.defineProperty($, '_renderComponent', {
     value: renderComponentTemplate,
     enumerable: false,
   });
@@ -852,7 +938,7 @@ const main = (s, config = {}, stringSelector = '') => {
     // Early exit if no mutations to process (common case)
     if (mutations.length === 0) return;
 
-    const manifestSizeBefore = Object.keys(manifest).length;
+    const manifestSizeBefore = debug ? Object.keys(manifest).length : 0;
     let hadChanges = false;
     let parsedParents = null; // Lazy init - only create Set when needed
     let addedElements = 0;
@@ -886,8 +972,14 @@ const main = (s, config = {}, stringSelector = '') => {
         // conditional's tracked reference to point to the replacement node.
         const branchRef = branchNodeRegistry.get(node);
         if (branchRef) {
-          // Find the replacement: an added node in the same mutation at the same parent
-          const replacement = Array.from(addedNodesList).find(n => n.parentNode === target);
+          // Find the replacement: an added node in the same mutation at the same
+          // parent. A STAGED remount splits add and remove into different
+          // batches (the incoming wrapper is inserted early, the outgoing one
+          // removed at commit) — the wrapper's replacement back-pointer covers
+          // that case.
+          const replacement =
+            Array.from(addedNodesList).find(n => n.parentNode === target) ||
+            (node._vibeReplacedBy?.isConnected ? node._vibeReplacedBy : null);
           if (replacement) {
             branchRef.nodes[branchRef.index] = replacement;
             branchNodeRegistry.set(replacement, branchRef);
@@ -895,13 +987,16 @@ const main = (s, config = {}, stringSelector = '') => {
           branchNodeRegistry.delete(node);
         }
 
-        const entry = Object.entries(manifest).find(([_, element]) => element === node);
+        const dotAnnotation = manifestPathOf(manifest, node);
 
         // Skip nodes that aren't tracked (e.g., iteration-generated nodes or nodes outside reactive scope)
-        if (!entry) return;
+        if (dotAnnotation === null) return;
 
-        const [dotAnnotation] = entry;
-        delete manifest[dotAnnotation];
+        // Prune the node's ENTIRE manifest scope — root entry plus every
+        // descendant and branch-alias path under it. Deleting just the root
+        // entry leaked the rest, pinning each swapped-out page's detached
+        // DOM forever (the SPA navigation leak).
+        removeManifestSubtree(manifest, dotAnnotation);
 
         const dotPath = dotAnnotation.split('.');
         const name = dotPath.pop();
@@ -955,7 +1050,7 @@ const main = (s, config = {}, stringSelector = '') => {
           });
         }
 
-        const entry = Object.entries(manifest).find(([_, element]) => element === target);
+        const dotAnnotation = manifestPathOf(manifest, target);
 
         // Parse the newly added node
         const parsedNode = parse(node);
@@ -969,8 +1064,7 @@ const main = (s, config = {}, stringSelector = '') => {
         // (If not — e.g. mutations inside an iteration instance whose rows aren't in the
         // global manifest — we still hydrate the node below; we just skip tree/manifest
         // registration since there's no tree branch to attach to.)
-        if (entry) {
-          const [dotAnnotation] = entry;
+        if (dotAnnotation !== null) {
           // navigateTree walks `children` only; when the parent lives in a
           // conditional branch's slot-projected content its manifest path isn't
           // navigable that way (see findNodeByElement). Fall back to an identity
@@ -1040,9 +1134,14 @@ const main = (s, config = {}, stringSelector = '') => {
 
     // CLEANUP OF CURRENT STATE
     releaseOrphanedComponentState(removedComponentIds);
+    let hadRemovals = false;
     mutations.forEach(({ removedNodes: removedNodesList }) => {
+      if (removedNodesList.length > 0) hadRemovals = true;
       releaseOrphanedIterationProps(removedNodesList);
     });
+    // Subscribers anchored in the removed subtrees are dead — drop them from
+    // the reverse index (observed removals: page swaps, reconcile, app code).
+    if (hadRemovals) pruneDisconnected();
 
     // Fire hooks once after all mutations are processed (not per-node)
     if (hadChanges) {
@@ -1095,8 +1194,10 @@ const main = (s, config = {}, stringSelector = '') => {
           debugLog(PHASE_MUTATE, '', debug, 0, topmostParent || addedElementsList[0]);
         }
 
-        // Log parsed elements after mutation
-        const manifestSizeAfter = Object.keys(manifest).length;
+        // Log parsed elements after mutation — debug-only: the entries
+        // snapshot allocates the full manifest per batch, so skip it entirely
+        // when nothing will be printed.
+        const manifestSizeAfter = debug ? Object.keys(manifest).length : manifestSizeBefore;
         const totalNodes = manifestSizeAfter - manifestSizeBefore;
 
         if (totalNodes > 0) {
@@ -1213,6 +1314,7 @@ const main = (s, config = {}, stringSelector = '') => {
   // Track cleanup state
   let componentProcessingStarted = false;
   let cleanupExecuted = false;
+  let bootSettleDone = false;
 
   // Check if cleanup should run
   const checkCleanup = () => {
@@ -1229,10 +1331,24 @@ const main = (s, config = {}, stringSelector = '') => {
 
     // Check if all processing is complete
     if (shouldCleanup(rootElement)) {
+      // One-shot settle before ready: directives whose expressions read
+      // globals provided by component scripts (window helpers) carry no
+      // reactive dependency for those globals, so a directive that rendered
+      // before the defining script settled — boot renders race async imports,
+      // runtime fetch mounts land after initial hydration — would stay empty
+      // forever. All scripts and mounts have settled here; re-render once
+      // against the fully-scripted world. Idempotent: rendered iterations
+      // early-return, value-unchanged conditionals are a no-op.
+      if (!bootSettleDone) {
+        bootSettleDone = true;
+        renderAllIterations(parsedTree, extractPlainValue($), manifest);
+        settleConditionals(parsedTree, $, manifest);
+      }
       cleanup(rootElement, debug);
       cleanupExecuted = true;
 
       // Fire ready hook after cleanup completes
+      readyFired = true;
       hooks.ready.forEach((callback) => {
         try {
           callback();
@@ -1253,6 +1369,14 @@ const main = (s, config = {}, stringSelector = '') => {
   if (compiledScriptsPending) {
     compiledScriptsPending.then(() => {
       compiledScriptsDone = true;
+      // The initial conditional pass ran before these module scripts settled
+      // — native MPA ordering had page modules evaluate BEFORE vibe booted,
+      // so a gate on a module-provided global (`<!-- if window.isDev -->`)
+      // saw the booted world. A gate like that carries no reactive
+      // dependency to re-check it later, so settle conditionals once against
+      // the post-module world before ready fires. Value-unchanged branches
+      // are a no-op.
+      settleConditionals(parsedTree, $, manifest);
       checkCleanup();
     });
   }
@@ -1281,7 +1405,7 @@ const main = (s, config = {}, stringSelector = '') => {
   // Use pre-compiled manifest if available (has compiledBatchFn), otherwise runtime-generated
   if (typeof window !== 'undefined') {
     const manifestToExport = hyperspeedTree || hyperspeedManifestData;
-    window.__vibeManifest = manifestToExport;
+    (window.__vibe ??= {}).manifest = manifestToExport;
   }
 
   return $;