@ape-egg/vibe 4.0.0 → 4.1.1

package/runtime/index.js

@@ -38,22 +38,15 @@ import {
   restoreMarkersFromManifest,
 } from './pre-compiled-manifest.js';
 
-// Wire up cross-module dependency after all modules are loaded
 setRenderAllConditionals(renderAllConditionals);
 
-// Stamped at module load, not boot — a console can read __vibe.version even
-// on a page whose boot died, which is exactly when a bug report needs it.
 ((globalThis.__vibe ??= {}).version = VERSION);
 
-// Check if node should be processed by Vibe
 const shouldProcessNode = (node) => {
-  // Only process element nodes
   if (node.nodeType !== 1) return false;
 
-  // Skip nodes already managed by mountBranch or renderIteration
   if (managedNodes.has(node)) return false;
 
-  // Fast check first: skip nodes without Vibe syntax (cheapest check)
   const html = node.outerHTML;
   if (
     !html.includes('@[') &&
@@ -64,7 +57,6 @@ const shouldProcessNode = (node) => {
     return false;
   }
 
-  // Node has Vibe syntax - now check if it's in a non-reactive context
   let current = node;
   while (current && current !== document.body) {
     if (NON_REACTIVE_ELEMENTS.includes(current.nodeName)) {
@@ -82,22 +74,11 @@ const shouldProcessNode = (node) => {
   return true;
 };
 
-// Navigate tree using dot notation (handles .children at each level)
 const navigateTree = (tree, path) => {
   if (!path) return tree;
   return path.split('.').filter(k => k).reduce((node, key) => node?.children?.[key], tree);
 };
 
-// Locate the tree node whose `.element` is `target`, searching the full tree:
-// plain `children`, plus conditional branch trees (`runtime.activeInstance`)
-// and iteration instance trees (`runtime.instances`). navigateTree only walks
-// `children`, so it can't reach content projected across a <slot> boundary — a
-// conditional branch's slotted content is registered in the flat manifest by
-// path, but that path isn't navigable through `children` (the slot node's
-// children don't include the projected subtree). When a <component src> resolves
-// inside such content, navigateTree returns null and the resolved subtree would
-// be orphaned from the reactive tree. This identity search recovers the real
-// parent node so the subtree links in regardless of slot/branch projection.
 const findNodeByElement = (tree, target) => {
   if (!target) return null;
   const seen = new Set();
@@ -130,7 +111,6 @@ const findNodeByElement = (tree, target) => {
   return walk(tree);
 };
 
-// Get or create a node in the tree at the given path
 const ensureNode = (tree, path) => {
   const keys = path.split('.').filter(k => k);
   return keys.reduce((node, key) => {
@@ -141,7 +121,6 @@ const ensureNode = (tree, path) => {
   }, tree);
 };
 
-// Recursively add parsed tree nodes to manifest (like createManifest does)
 const addToManifest = (tree, manifest, dotPath) => {
   setManifestEntry(manifest, dotPath, tree.element);
 
@@ -152,16 +131,6 @@ const addToManifest = (tree, manifest, dotPath) => {
   }
 };
 
-/**
- * Core loop: processes a node through parse → hydrate → conditionals → iterate
- * @param {Node} node - DOM node to process (unused in current implementation, parsedNode is primary)
- * @param {Object} parsedNode - Parsed tree node
- * @param {Object} state - Current global state
- * @param {Object} manifest - DOM manifest
- * @param {Boolean} isNewNode - Whether this is a newly added node (affects hydration)
- * @param {Boolean} debug - Debug mode
- * @returns {Object} - Counts of hydrated/iterated/evaluated elements
- */
 const processCoreLoop = (node, parsedNode, state, manifest, isNewNode, debug) => {
   let hydratedCount = 0;
   let iteratedCount = 0;
@@ -169,13 +138,6 @@ const processCoreLoop = (node, parsedNode, state, manifest, isNewNode, debug) =>
 
   if (!parsedNode) return { hydratedCount, iteratedCount, evaluatedCount };
 
-  // 1. Parse - already done before calling core loop (in processMutations)
-
-  // 2. Hydrate (replace @[...] bindings)
-  // For new nodes, use {} so all bindings are found. But filter out iterations
-  // and conditionals — those should only go through renderAllIterations/renderAllConditionals
-  // (initial render path), not updateIteration/updateConditional (which would diff against
-  // stale oldState and produce false adds/removes).
   const oldStateForAffected = isNewNode ? {} : previousState;
   let affectedElements = affected(parsedNode, oldStateForAffected, state);
   if (isNewNode) {
@@ -186,33 +148,24 @@ const processCoreLoop = (node, parsedNode, state, manifest, isNewNode, debug) =>
     hydrate(affectedElements, state, manifest, oldStateForAffected);
   }
 
-  // 3. Conditionals (evaluate <!-- if -->)
   const conditionalCount = renderAllConditionals(parsedNode, state, manifest);
   if (conditionalCount > 0) {
     evaluatedCount = conditionalCount;
   }
 
-  // 4. Iterate (render <!-- each -->)
   const iterationCount = renderAllIterations(parsedNode, state, manifest);
   if (iterationCount > 0) {
     iteratedCount = iterationCount;
   }
 
-  // Note: Any DOM changes from steps 3-4 will trigger MutationObserver
-  // which will recursively call processMutations for nested content
-
   return { hydratedCount, iteratedCount, evaluatedCount };
 };
 
-/**
- * Deep clone a tree node (to avoid mutating hyperspeed template)
- */
 const deepCloneNode = (node) => {
   if (!node || typeof node !== 'object') return node;
 
   const cloned = { ...node };
 
-  // Clone children recursively
   if (node.children && typeof node.children === 'object') {
     cloned.children = {};
     for (const key in node.children) {
@@ -220,7 +173,6 @@ const deepCloneNode = (node) => {
     }
   }
 
-  // Clone meta if it exists
   if (node.meta && typeof node.meta === 'object') {
     cloned.meta = { ...node.meta };
     if (node.meta.template) {
@@ -231,7 +183,6 @@ const deepCloneNode = (node) => {
     }
   }
 
-  // Clone runtime if it exists
   if (node.runtime && typeof node.runtime === 'object') {
     cloned.runtime = { ...node.runtime };
     if (Array.isArray(node.runtime.instances)) {
@@ -242,121 +193,87 @@ const deepCloneNode = (node) => {
   return cloned;
 };
 
-/**
- * Merge hyperspeed manifest with runtime manifest
- * Hyperspeed provides structure/metadata, runtime populates DOM references
- */
 const mergeManifests = (hyperspeedTree, runtimeTree) => {
   if (!hyperspeedTree) return runtimeTree;
   if (!runtimeTree) return hyperspeedTree;
 
-  // hyperspeedTree is already a clone (done before restoration to avoid mutation)
   const merged = hyperspeedTree;
 
-  // Helper to recursively augment hyperspeed with runtime data
   const augmentWithRuntime = (mergedNode, runtimeNode) => {
     if (!runtimeNode) return;
 
-    // Debug: log node types
-    // Populate DOM references from runtime
     if (runtimeNode.element) {
       mergedNode.element = runtimeNode.element;
     }
 
-    // Populate parsed data from runtime
     if (runtimeNode.parsed) {
       mergedNode.parsed = runtimeNode.parsed;
     }
 
-    // Populate name bindings from runtime (detected after restoration)
     if (runtimeNode.nameBindings) {
       mergedNode.nameBindings = runtimeNode.nameBindings;
     }
 
-    // Populate attributes from runtime (detected after restoration)
     if (runtimeNode.attributes) {
       mergedNode.attributes = runtimeNode.attributes;
     }
 
-    // Populate textNode reference from runtime (for text node children)
     if (runtimeNode.textNode) {
       mergedNode.textNode = runtimeNode.textNode;
     }
 
-    // For iterations: populate all meta and runtime from runtime
     if (mergedNode.type === 'iteration' && runtimeNode.type === 'iteration') {
-      // Preserve compiled data from manifest (has compiled batch function)
       const compiledData = mergedNode.compiled;
 
-      // Copy entire meta object from runtime (all properties needed)
       mergedNode.meta = runtimeNode.meta;
-      // Copy runtime object (instances, etc.)
       mergedNode.runtime = runtimeNode.runtime;
 
-      // Restore compiled data if it was present
       if (compiledData) {
         mergedNode.compiled = compiledData;
       }
     }
 
-    // For conditionals: populate all meta and runtime from runtime
     if (mergedNode.type === 'conditional' && runtimeNode.type === 'conditional') {
-      // Copy entire meta object from runtime (all properties needed)
       mergedNode.meta = runtimeNode.meta;
-      // Copy runtime object (activeBranch, activeInstance, templateRemoved)
       mergedNode.runtime = runtimeNode.runtime;
     }
 
-    // The runtime parse of the live DOM is the ground truth for what exists.
-    // A manifest child with no runtime counterpart sits at an index the DOM
-    // no longer agrees with (a content script prepending into <body> shifts
-    // every sibling) — it can never bind an element, and hydrating its
-    // bindings would dereference null. Drop it; the runtime-discovered
-    // sibling added below carries the real element.
     if (mergedNode.children) {
       for (const key in mergedNode.children) {
         if (!runtimeNode.children?.[key]) delete mergedNode.children[key];
       }
     }
 
-    // Augment children recursively
     if (runtimeNode.children) {
       if (!mergedNode.children) mergedNode.children = {};
 
       for (const key in runtimeNode.children) {
         const runtimeChild = runtimeNode.children[key];
 
-        // For iterations: augment existing node, don't replace
         if (runtimeChild.type === 'iteration') {
           const hyperspeedChild = mergedNode.children[key];
 
           if (hyperspeedChild) {
-            // Preserve compiled data from hyperspeed
             const compiledData = hyperspeedChild.compiled;
 
-            // Update meta and runtime from runtime node
             mergedNode.children[key].meta = runtimeChild.meta;
             mergedNode.children[key].runtime = runtimeChild.runtime;
 
-            // Keep compiled data from hyperspeed (it has batchFn)
             if (compiledData) {
               mergedNode.children[key].compiled = compiledData;
             }
           } else {
-            // No hyperspeed node, just use runtime
             mergedNode.children[key] = runtimeChild;
           }
           continue;
         }
 
-        // For conditionals: use runtime node but preserve compiled data
         if (runtimeChild.type === 'conditional') {
           const hyperspeedChild = mergedNode.children[key];
           const compiledData = hyperspeedChild?.compiled;
 
           mergedNode.children[key] = runtimeChild;
 
-          // Restore compiled data if it existed
           if (compiledData) {
             mergedNode.children[key].compiled = compiledData;
           }
@@ -364,20 +281,16 @@ const mergeManifests = (hyperspeedTree, runtimeTree) => {
         }
 
         if (mergedNode.children[key]) {
-          // Child exists in both - augment it
           augmentWithRuntime(mergedNode.children[key], runtimeNode.children[key]);
         } else {
-          // Child only in runtime - add it (dynamic element discovered at runtime)
           mergedNode.children[key] = runtimeNode.children[key];
         }
       }
     }
   };
 
-  // Augment hyperspeed foundation with runtime data
   augmentWithRuntime(merged, runtimeTree);
 
-  // Preserve stats from runtime (hyperspeed won't have stats)
   if (runtimeTree.stats) {
     merged.stats = runtimeTree.stats;
   }
@@ -385,7 +298,6 @@ const mergeManifests = (hyperspeedTree, runtimeTree) => {
   return merged;
 };
 
-// Store previous state for comparison (needs to be accessible by core loop)
 let previousState = {};
 
 const main = (s, config = {}, stringSelector = '') => {
@@ -393,26 +305,19 @@ const main = (s, config = {}, stringSelector = '') => {
   const verbose = !!config?.verbose;
   ((globalThis.__vibe ??= {}).debug = debug);
 
-  // Enable/disable the component template cache from config (`{ noCache }`).
   configureComponentCache(config);
 
-  // Expose the global `$scope` resolver used by loop-scoped `on*` handlers.
   installScopeResolver();
 
-  // 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.__vibe?.compiling === true;
 
-  // Reset previous state for each new instance
   previousState = {};
 
-  // Use page-specific hyperspeed manifest (detected at module load)
   const hyperspeedTree = hyperspeedManifest;
 
   let rootElement = document.body;
 
   if (stringSelector) {
-    // Find element(s) with the specified attribute
     const elements = document.querySelectorAll(`${stringSelector}`);
     if (elements?.[0]) {
       rootElement = elements[0];
@@ -421,16 +326,10 @@ const main = (s, config = {}, stringSelector = '') => {
 
   debugLog(PHASE_ATTACH, `Vibe attached to`, debug, 0, rootElement);
 
-  // Component tagging is now handled by component.js before boot
-  // Component state is merged into s by boot.js
-
-  // RESTORATION PHASE: If hyperspeed detected, restore @[...] markers in DOM
-  // This allows pre-rendered values to be visible (no FOUC) but makes DOM reactive
   let hyperspeedSubtree = null;
   if (hyperspeedTree) {
     const manifestName = hyperspeedPath ? hyperspeedPath.split('/').pop() : 'manifest.js';
 
-    // Count compiled features
     const countCompiledIterations = (tree) => {
       let count = 0;
       if (tree.type === 'iteration' && tree.compiled?.iterations?.batchFn) count++;
@@ -444,7 +343,6 @@ const main = (s, config = {}, stringSelector = '') => {
 
     const compiledIterationCount = countCompiledIterations(hyperspeedTree);
 
-    // Log features that are enabled
     debugLog(PHASE_HYPERSPEED, `Loaded ${manifestName}, page is pre-compiled`, debug);
 
     if (compiledIterationCount > 0) {
@@ -461,17 +359,13 @@ const main = (s, config = {}, stringSelector = '') => {
       );
     }
 
-    // Find matching subtree by DOM path (not just tag name)
-    // Build path from document to rootElement
     const buildDomPath = (element) => {
       const path = [];
       let current = element;
 
-      // Walk up to document itself (include html in the path)
       while (current && current.parentNode && current !== document) {
         const parent = current.parentNode;
 
-        // Skip document node itself
         if (parent === document) {
           const siblings = Array.from(document.childNodes);
           const index = siblings.indexOf(current);
@@ -491,19 +385,16 @@ const main = (s, config = {}, stringSelector = '') => {
       return path;
     };
 
-    // Walk manifest tree following DOM path
     const findManifestNodeByPath = (manifest, path) => {
       let current = manifest;
 
       for (const { tag, index } of path) {
         if (!current || !current.children) return null;
 
-        // Look for matching child by tag_index pattern
         const key = `${tag}_${index}`;
         if (current.children[key]) {
           current = current.children[key];
         } else {
-          // Fallback: search all children for matching tag at this level
           let found = false;
           for (const childKey in current.children) {
             if (childKey.startsWith(tag + '_')) {
@@ -523,36 +414,27 @@ const main = (s, config = {}, stringSelector = '') => {
     let subtreeFromManifest = findManifestNodeByPath(hyperspeedTree, domPath);
 
     if (!subtreeFromManifest) {
-      // Fallback to root if path matching fails
       subtreeFromManifest = hyperspeedTree;
     }
 
-    // IMPORTANT: Clone BEFORE restoration because restoration mutates the tree
-    // We need TWO clones: one for restoration (gets mutated), one for merging (stays intact)
-    hyperspeedSubtree = deepCloneNode(subtreeFromManifest); // For merging
-    const cloneForRestoration = deepCloneNode(subtreeFromManifest); // For restoration
+    hyperspeedSubtree = deepCloneNode(subtreeFromManifest);
+    const cloneForRestoration = deepCloneNode(subtreeFromManifest);
 
     restoreMarkersFromManifest(rootElement, cloneForRestoration, hyperspeedTree);
   }
 
-  // Save raw slot content of fetched components before hydration replaces @[...] markers.
-  // component.js captures el.innerHTML when resolving — if hydration already ran, the
-  // binding syntax is gone and the resolved component won't be reactive.
   rootElement.querySelectorAll('component[src], div.component[src]').forEach(el => {
     el._vibeSlotContent = el.innerHTML;
   });
 
-  // Runtime parses DOM (which now has restored markers if hyperspeed was used)
   let parsedTree = parse(rootElement);
 
-  // Merge with hyperspeed if available (hyperspeed as foundation, runtime augments)
   if (hyperspeedSubtree) {
     parsedTree = mergeManifests(hyperspeedSubtree, parsedTree);
   }
 
   let manifest = createManifest(parsedTree);
 
-  // Build hyperspeed manifest (before hydration, extract markers from parsed strings)
   const hyperspeedManifestData = buildHyperspeedManifest(parsedTree);
 
   const manifestEntries = Object.entries(manifest);
@@ -582,7 +464,6 @@ const main = (s, config = {}, stringSelector = '') => {
     debug,
   );
 
-  // Lifecycle hooks that users can subscribe to
   const hooks = {
     afterUpdate: [],
     afterDomMutation: [],
@@ -590,25 +471,14 @@ 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
-  // event name resolves to that component's unmount instead (the scoped `$`
-  // proxy in component.js intercepts it before it reaches this hook).
   if (typeof window !== 'undefined') {
     window.addEventListener('pagehide', () => {
       hooks.unmount.forEach((callback) => callback());
     });
   }
 
-  // Extract plain values from proxy (removes proxy wrappers)
-  // Optimized: indexed loops, Object.keys (no prototype walk), inline primitive check
   const extractPlainValue = (obj) => {
     if (obj === null || typeof obj !== 'object') return obj;
     if (Array.isArray(obj)) {
@@ -631,14 +501,7 @@ const main = (s, config = {}, stringSelector = '') => {
     return plain;
   };
 
-  // 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();
@@ -655,14 +518,11 @@ const main = (s, config = {}, stringSelector = '') => {
         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,
@@ -675,17 +535,8 @@ const main = (s, config = {}, stringSelector = '') => {
   };
 
   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,
-    // while still detecting binding changes inside iteration instances.
     const currentState = { ...previousState };
     for (const prop of changedProps) {
-      // Distinguish "set to undefined" (key still present in $) from "deleted"
-      // (key absent from $). For deletions, removing from currentState matches
-      // the live proxy's shape — otherwise downstream consumers that pass
-      // currentState as `$` to evalInScope (e.g. iterations that re-render via
-      // bindings reading the root state) would see the deleted key as a phantom
-      // own-property with value `undefined`.
       if (prop in $) {
         currentState[prop] = extractPlainValue($[prop]);
       } else {
@@ -693,11 +544,6 @@ const main = (s, config = {}, stringSelector = '') => {
       }
     }
 
-    // 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);
@@ -706,30 +552,13 @@ const main = (s, config = {}, stringSelector = '') => {
       });
     }
 
-    // Store previous state for hooks (currentState is already plain, no need to clone)
     const prev = previousState;
     previousState = currentState;
     hooks.afterUpdate.forEach((callback) => callback(currentState, prev));
   });
 
-  // Add hook subscription method (non-enumerable so it won't be spread/cloned with state)
-  // `configurable: true` lets a component script's scoped `$` Proxy (built in
-  // component.js) legally return a wrapped `.on` that auto-registers cleanup
-  // — 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 = () => {
@@ -770,46 +599,23 @@ const main = (s, config = {}, stringSelector = '') => {
     configurable: true,
   });
 
-  // Promise that resolves after the ready hook fires and all ready callbacks
-  // have run. Lets late subscribers await readiness without missing the event:
-  // `await $.ready`. Non-enumerable so it won't leak into state snapshots.
   let resolveReady;
   Object.defineProperty($, 'ready', {
     value: new Promise((resolve) => { resolveReady = resolve; }),
     enumerable: false,
   });
 
-  // Reconcile a managed subtree against new source HTML. Opt-in entry point;
-  // dormant unless called (so hot paths and benchmarks are unaffected).
   Object.defineProperty($, 'reconcile', {
     value: reconcile,
     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;
     },
@@ -817,80 +623,35 @@ const main = (s, config = {}, stringSelector = '') => {
     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,
-  // like Svelte {@html}). Non-enumerable so it never leaks into state snapshots.
   Object.defineProperty($, 'unsafe', {
     value: unsafe,
     enumerable: false,
     configurable: true,
   });
 
-  // Pure-render path for surgical component HMR. Given raw component template
-  // HTML, callsite props, slot HTML, and existing componentIds, returns the
-  // 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', {
     value: renderComponentTemplate,
     enumerable: false,
   });
 
-  // Invalidate cached component templates. `$.clearComponentCache(path)` drops
-  // one entry, `$.clearComponentCache()` drops all. Templates are immutable in
-  // production (nothing to clear), so this exists for tooling that swaps a
-  // template under a live session — e.g. the dev server busts the changed file
-  // on hot update. Non-enumerable so it never leaks into state snapshots.
   Object.defineProperty($, 'clearComponentCache', {
     value: clearComponentCache,
     enumerable: false,
     configurable: true,
   });
 
-  // Expose the live reactive proxy to the iteration stamper so loop-scoped
-  // `on*` handlers (`$scope`) resolve the SAME object identity the app sees via
-  // `$`, instead of the plain diff-snapshot clones iterations render against
-  // (see extractPlainValue below). Non-enumerable so it never shows up in the
-  // manifest's node-path entry iteration.
   Object.defineProperty(manifest, '__live', { value: $, enumerable: false, configurable: true });
 
-  // Pair the flat manifest (dotPath -> element) with its parsed tree so removal
-  // paths can prune both views together. The page MutationObserver is
-  // disconnected while Vibe renders (iteration/conditional teardown removes DOM
-  // unobserved), so those paths must prune the manifest + tree themselves; this
-  // gives them the tree root without threading it through every call. Same
-  // non-enumerable contract as __live.
   Object.defineProperty(manifest, '__tree', { value: parsedTree, enumerable: false, configurable: true });
 
-  // Bind `$` inside every expression to this live root proxy (see setRootState
-  // in utils.js). Done before the first hydration pass so `$.unsafe` and the
-  // other reserved methods are reachable from the initial render onward.
   setRootState($);
 
-  // Publish the real proxy on `window.$` BEFORE the first hydration pass.
-  // boot.js sets `window.$ = main(...)`, but until main returns it's the
-  // pre-boot placeholder (vibeInstance with no state keys). User helpers
-  // defined on `window` that close over `$` — e.g. a global `brawlerActivity`
-  // function reading `$.combat?.duration` — would then read the placeholder
-  // during initial render and treat the whole world as empty. Assigning the
-  // live proxy here lets those closures see the right `$` from the very
-  // first conditional/binding eval.
   if (typeof window !== 'undefined') window.$ = $;
 
-  // Compiled pages: execute build-inlined component scripts (neutered to
-  // type="vibe-module" by the compiler) through the runtime's component-script
-  // pipeline — same injected component(), same scoped `$`, same import
-  // rewriting as fetched scripts. Runs after `window.$` is live so
-  // `const id = component(state); $[id].x = ...` captures the reactive proxy,
-  // and before initial hydration so synchronous scripts' state is already
-  // registered when `this.` bindings first evaluate. Async scripts gate
-  // `ready` via compiledScriptsDone below.
   let compiledScriptsDone = true;
   const compiledScriptsPending = executeCompiledComponentScripts();
   if (compiledScriptsPending) compiledScriptsDone = false;
 
-  // Initial hydration - pass plain values so iteration can do reference comparison
   const initialState = extractPlainValue($);
   const affectedElements = affected(parsedTree, initialState, initialState);
 
@@ -907,12 +668,8 @@ const main = (s, config = {}, stringSelector = '') => {
     debug,
   );
 
-  // Hydrate with proxy $ so DOM bindings work
-  // Pass initialState as oldState for iterations (won't actually update, just initial render)
   hydrate(affectedElements, $, manifest, initialState);
 
-  // Render all iterations and conditionals after initial hydration
-  // Use initialState (plain values) for iteration rendering so reference comparison works
   const iterationCount = renderAllIterations(parsedTree, initialState, manifest);
   if (iterationCount > 0)
     debugLog(
@@ -943,35 +700,28 @@ const main = (s, config = {}, stringSelector = '') => {
       debug,
     );
 
-  // After all initial rendering, capture a clean snapshot for comparison
   previousState = extractPlainValue($);
 
-  // Observer reference and processMutations
   let observer = null;
   let processMutations = null;
 
-  // Define observer callback as named function so we can call it manually for pending mutations
   processMutations = (mutations) => {
-    // Early exit if no mutations to process (common case)
     if (mutations.length === 0) return;
 
     const manifestSizeBefore = debug ? Object.keys(manifest).length : 0;
     let hadChanges = false;
-    let parsedParents = null; // Lazy init - only create Set when needed
+    let parsedParents = null;
     let addedElements = 0;
     let addedNodes = 0;
     let removedElements = 0;
     let removedNodes = 0;
-    let singleElement = null; // Track the single element when count is 1
-    let totalSkipped = 0; // Track skipped elements from parse
+    let singleElement = null;
+    let totalSkipped = 0;
     let hydratedCount = 0;
     let iteratedCount = 0;
     let evaluatedCount = 0;
-    let addedElementsList = []; // Track all added elements for verbose output
+    let addedElementsList = [];
 
-    // Collect data-vibe-component-id values across ALL removed subtrees in this
-    // batch before doing any per-node work, so we can evict their state after
-    // the DOM mutations have been applied.
     const removedComponentIds = new Set();
     mutations.forEach(({ removedNodes: removedNodesList }) => {
       removedNodesList.forEach((node) => collectComponentIds(node, removedComponentIds));
@@ -979,21 +729,12 @@ const main = (s, config = {}, stringSelector = '') => {
 
     mutations.forEach(({ addedNodes: addedNodesList, removedNodes: removedNodesList, target }) => {
       removedNodesList.forEach((node) => {
-        // If this is a component element with pending fetch, abort it
         if (node.nodeName === 'COMPONENT') {
           abortComponentFetch(node);
         }
 
-        // If this node is tracked by a conditional branch (e.g. a <component src>
-        // that was replaced by processComponent via el.replaceWith), update the
-        // 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. 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);
@@ -1006,30 +747,19 @@ const main = (s, config = {}, stringSelector = '') => {
 
         const dotAnnotation = manifestPathOf(manifest, node);
 
-        // Skip nodes that aren't tracked (e.g., iteration-generated nodes or nodes outside reactive scope)
         if (dotAnnotation === null) return;
 
-        // 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();
         const parentDotAnnotation = dotPath.join('.');
 
-        // Identity fallback mirrors the added-node path: a parent inside
-        // slot-projected branch content isn't reachable via navigateTree's
-        // `children` walk, so resolve it by element identity instead — otherwise
-        // the removed node's stale tree entry lingers alongside its replacement.
         const picked =
           navigateTree(parsedTree, parentDotAnnotation) || findNodeByElement(parsedTree, target);
 
-        // If we can't navigate to the parent, skip
         if (!picked || !picked.element) return;
 
-        // Update parent's parsed HTML (only once per parent)
         if (!parsedParents) parsedParents = new Set();
         if (!parsedParents.has(picked)) {
           const { parsed } = parse(picked.element);
@@ -1037,10 +767,8 @@ const main = (s, config = {}, stringSelector = '') => {
           parsedParents.add(picked);
         }
 
-        // Remove the node from parent's children
         delete picked.children[name];
 
-        // Count elements vs nodes separately
         if (node.nodeName.startsWith('#')) {
           removedNodes++;
         } else {
@@ -1051,16 +779,10 @@ const main = (s, config = {}, stringSelector = '') => {
       });
 
       addedNodesList.forEach((node) => {
-        // Skip nodes that aren't element nodes, are non-reactive, or lack Vibe syntax
         if (!shouldProcessNode(node)) {
           return;
         }
 
-        // Capture raw slot content of nested <component src> elements BEFORE parse runs.
-        // Parse creates conditional nodes from <!-- if --> comments, and renderConditional
-        // later removes the template nodes between the comments. Without capturing slot
-        // content first, conditionals inside a component's slot content lose their branch
-        // templates, breaking reactive updates.
         if (node.nodeType === 1) {
           node.querySelectorAll('component[src], div.component[src]').forEach((el) => {
             if (el._vibeSlotContent === undefined) el._vibeSlotContent = el.innerHTML;
@@ -1069,23 +791,13 @@ const main = (s, config = {}, stringSelector = '') => {
 
         const dotAnnotation = manifestPathOf(manifest, target);
 
-        // Parse the newly added node
         const parsedNode = parse(node);
 
-        // Accumulate skipped stats
         if (parsedNode.stats?.skipped) {
           totalSkipped += parsedNode.stats.skipped;
         }
 
-        // If parent is tracked in the manifest, register this new node in the parsed tree.
-        // (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 (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
-          // search so the resolved subtree still links into the reactive tree.
           const picked =
             navigateTree(parsedTree, dotAnnotation) || findNodeByElement(parsedTree, target);
 
@@ -1094,15 +806,12 @@ const main = (s, config = {}, stringSelector = '') => {
               picked.element = target;
             }
 
-            // Parse the newly added node (use monotonically increasing counter for deterministic key)
-            // Initialize counter if it doesn't exist
             if (!picked._nextChildIndex) {
               picked._nextChildIndex = Object.keys(picked.children).length;
             }
             const name = `${node.nodeName.toLowerCase()}_${picked._nextChildIndex}`;
-            picked._nextChildIndex++; // Always increment, never decrement
+            picked._nextChildIndex++;
 
-            // Update parent's parsed HTML (only once per parent)
             if (!parsedParents) parsedParents = new Set();
             if (!parsedParents.has(picked)) {
               const { parsed } = parse(picked.element);
@@ -1110,34 +819,21 @@ const main = (s, config = {}, stringSelector = '') => {
               parsedParents.add(picked);
             }
 
-            // Add the parsed node to parent's children
             picked.children[name] = parsedNode;
 
-            // Recursively add node and all descendants to manifest
             addToManifest(parsedNode, manifest, `${dotAnnotation}.${name}`);
           }
         }
 
-        // Run core loop for the new node (parse already done, hydrate → conditionals → iterate)
         const counts = processCoreLoop(node, parsedNode, $, manifest, true, debug);
         hydratedCount += counts.hydratedCount;
         iteratedCount += counts.iteratedCount;
         evaluatedCount += counts.evaluatedCount;
 
-        // For inlined `<component>` wrappers belonging to an iteration row
-        // (marked by component.js's resolveIterationComponentProps transfer),
-        // stash the parsed tree on the wrapper. processCoreLoop has just run
-        // hydrate + renderAllConditionals + renderAllIterations on it, so
-        // `parsedNode` carries live `runtime.activeInstance` /
-        // `runtime.instances` data — exactly what `affected.js` needs to walk
-        // into branch / row content. Iterate.js's update path consumes this
-        // tree to re-hydrate bindings inside the inlined component on each
-        // row-scope change without rebuilding the wrapper's DOM.
         if (node.nodeType === 1 && node._vibeIterPropExprs) {
           node._vibeIterTree = parsedNode;
         }
 
-        // Count elements vs nodes separately
         if (node.nodeName.startsWith('#')) {
           addedNodes++;
         } else {
@@ -1149,23 +845,18 @@ 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) {
       if (addedElements > 0 || addedNodes > 0 || removedElements > 0 || removedNodes > 0) {
         const segments = [];
 
-        // Added
         if (addedElements > 0) {
           segments.push({ text: `+${addedElements}`, color: 'green' });
           segments.push({
@@ -1179,7 +870,6 @@ const main = (s, config = {}, stringSelector = '') => {
           segments.push({ text: ` ${addedNodes === 1 ? 'node' : 'nodes'}`, colored: false });
         }
 
-        // Removed
         if (removedElements > 0) {
           if (addedElements > 0 || addedNodes > 0) segments.push({ text: ', ', colored: false });
           segments.push({ text: `-${removedElements}`, color: 'red' });
@@ -1195,25 +885,15 @@ const main = (s, config = {}, stringSelector = '') => {
           segments.push({ text: ` ${removedNodes === 1 ? 'node' : 'nodes'}`, colored: false });
         }
 
-        // Pass element reference if exactly one element was mutated (not counting nodes)
-        // const totalElementCount = addedElements + removedElements;
-        // const elementToLog = totalElementCount === 1 ? singleElement : null;
-        // debugLog(PHASE_MUTATE, segments, debug, 0, elementToLog);
         debugLog(PHASE_MUTATE, segments, debug);
 
-        // Verbose: log the added element (or topmost parent if multiple)
         if (verbose && addedElementsList.length > 0) {
-          // Find the topmost parent among added elements
           const topmostParent = addedElementsList.find((el) => {
-            // Check if this element is NOT a descendant of any other element in the list
             return !addedElementsList.some((other) => other !== el && other.contains(el));
           });
           debugLog(PHASE_MUTATE, '', debug, 0, topmostParent || addedElementsList[0]);
         }
 
-        // 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;
 
@@ -1240,7 +920,6 @@ const main = (s, config = {}, stringSelector = '') => {
 
           debugLog(PHASE_PARSE, parseSegments, debug);
 
-          // Log hydration after parse
           if (hydratedCount > 0) {
             debugLog(
               PHASE_HYDRATE,
@@ -1256,7 +935,6 @@ const main = (s, config = {}, stringSelector = '') => {
             );
           }
 
-          // Log iterations after hydration
           if (iteratedCount > 0) {
             debugLog(
               PHASE_ITERATE,
@@ -1272,7 +950,6 @@ const main = (s, config = {}, stringSelector = '') => {
             );
           }
 
-          // Log conditionals after iterations
           if (evaluatedCount > 0) {
             debugLog(
               PHASE_CONDITION,
@@ -1291,12 +968,8 @@ const main = (s, config = {}, stringSelector = '') => {
       }
     }
 
-    // Always call hooks, even if no changes detected (cleanup needs to check)
     hooks.afterDomMutation.forEach((callback) => callback());
 
-    // Check for new <component> elements after DOM mutations
-    // Process component elements if we've started (initial call happened)
-    // Note: Also process after cleanup — conditionals may reveal new components
     if (componentProcessingStarted) {
       const componentConfig = {
         ...config,
@@ -1307,7 +980,6 @@ const main = (s, config = {}, stringSelector = '') => {
       processComponent(
         rootElement,
         () => {
-          // When all components are done, run cleanup check
           checkCleanup();
         },
         componentConfig,
@@ -1328,34 +1000,21 @@ const main = (s, config = {}, stringSelector = '') => {
 
   debugLog(PHASE_OBSERVE, `MutationObserver listening to DOM changes`, debug);
 
-  // Track cleanup state
   let componentProcessingStarted = false;
   let cleanupExecuted = false;
   let bootSettleDone = false;
 
-  // Check if cleanup should run
   const checkCleanup = () => {
     if (cleanupExecuted || isCompiling || !compiledScriptsDone) return;
 
-    // Check for pending mutations first
     const pendingMutations = observer ? observer.takeRecords() : [];
 
     if (pendingMutations.length > 0) {
-      // More mutations to process
       processMutations(pendingMutations);
       return;
     }
 
-    // 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);
@@ -1364,7 +1023,6 @@ const main = (s, config = {}, stringSelector = '') => {
       cleanup(rootElement, debug);
       cleanupExecuted = true;
 
-      // Fire ready hook after cleanup completes
       readyFired = true;
       hooks.ready.forEach((callback) => {
         try {
@@ -1373,35 +1031,22 @@ const main = (s, config = {}, stringSelector = '') => {
           console.error('[vibe] Error in ready hook:', error);
         }
       });
-      // Resolve $.ready promise after all ready callbacks have run
       resolveReady();
     }
   };
 
-  // Register hook to check for cleanup readiness after each mutation batch
   hooks.afterDomMutation.push(checkCleanup);
 
-  // Async compiled component scripts (imports) finish after boot — unlock the
-  // ready gate and re-check once their state has merged into `$`.
   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();
     });
   }
 
-  // Process component elements after initialization - MutationObserver will handle hydration
   componentProcessingStarted = true;
 
-  // Pass observer and processMutations to component for sync processing
   const componentConfig = {
     ...config,
     _forceSync: true,
@@ -1412,14 +1057,11 @@ const main = (s, config = {}, stringSelector = '') => {
   processComponent(
     rootElement,
     () => {
-      // When all components are done, run cleanup check
       checkCleanup();
     },
     componentConfig,
   );
 
-  // Export hyperspeed manifest globally for compiler extraction and optimizations
-  // Use pre-compiled manifest if available (has compiledBatchFn), otherwise runtime-generated
   if (typeof window !== 'undefined') {
     const manifestToExport = hyperspeedTree || hyperspeedManifestData;
     (window.__vibe ??= {}).manifest = manifestToExport;