@ape-egg/vibe 4.0.1 → 4.1.1

package/runtime/component.js

@@ -27,60 +27,29 @@ import {
 
 export { activeOutgoingRoots, isComponentWrapper };
 
-// Deterministic component counter
-// 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
- * Uses deterministic counter: _c0, _c1, _c2, etc.
- */
 export const generateComponentId = () => {
   return `_c${componentCounter++}`;
 };
 
-// Helper to escape regex special characters
 const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-// Kept as no-ops for API compatibility — path-based tracking was replaced by
-// DOM-scan cleanup in releaseOrphanedComponentState. Manifest paths don't
-// align 1:1 with component ownership across conditional remounts, so scanning
-// the DOM subtree about to be removed is simpler and waterproof.
 export const trackComponentOwnership = () => {};
 
-// Given an iterable of DOM nodes that are about to be (or have just been)
-// removed, find every `data-vibe-component-id` inside them and, for each id
-// whose DOM is fully gone from the live document, evict its state.
-//
-// Call this AFTER the nodes have been detached from the document so the
-// `document.querySelector` check sees the post-removal state.
 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.__vibe?.components?.[id];
-    // CLEANUP OF CURRENT STATE
     delete window.$[id];
     runComponentCleanups(id);
   }
 };
 
-// Listener registry: maps componentId → array of unsubscribe callbacks
-// returned from `$.on(...)` calls inside the component's `<script>`.
-// Re-running a script for the same id (HMR remount with reused ids) or
-// 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.__vibe?.cleanups?.[componentId];
   if (!cleanups) return;
-  // 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 {
@@ -91,11 +60,6 @@ export const runComponentCleanups = (componentId) => {
   }
 };
 
-// Per-script `$` Proxy. Bare `$` references in a component's <script> resolve
-// to this Proxy (the function parameter shadows the global), so every
-// `$.on(...)` registration is automatically attributed to `componentId` via
-// the closure — no global flag, async-safe across `await` boundaries because
-// the closure binds the id, not a shared variable.
 const createScopedDollar = (componentId) => {
   const dollar = window.$;
   if (!dollar) return dollar;
@@ -103,14 +67,6 @@ const createScopedDollar = (componentId) => {
     get(target, prop, receiver) {
       if (prop === 'on') {
         return (event, callback) => {
-          // 'unmount' is scope-resolved: in a component script it means THIS
-          // component's unmount (conditional toggle, iteration removal,
-          // reactive src swap — and before an HMR re-run of the same id).
-          // The callback rides the same per-component cleanup registry the
-          // global-event unsubscribes below ride, so a component owns
-          // arbitrary side effects (intervals, listeners, sockets) without
-          // leaking them past its lifetime. At page level the root's `on`
-          // resolves the same event name to pagehide instead.
           if (event === 'unmount') {
             const cleanupsReg = ((window.__vibe ??= {}).cleanups ??= {});
             const slot = cleanupsReg[componentId] || (cleanupsReg[componentId] = []);
@@ -135,8 +91,6 @@ const createScopedDollar = (componentId) => {
   });
 };
 
-// Walk a node subtree (element or node list) and collect all
-// `data-vibe-component-id` values found on the node and its descendants.
 export const collectComponentIds = (node, into = new Set()) => {
   if (!node) return into;
   if (node.nodeType === 1) {
@@ -149,25 +103,15 @@ export const collectComponentIds = (node, into = new Set()) => {
   return into;
 };
 
-// Prepare a component <script> body for execution through the injected
-// component() path: strip the `import component from '...'` line (the
-// function is passed in as a parameter) and rewrite any remaining static
-// imports to awaited dynamic imports. Shared by the fetch path
-// (processSingle) and the compiled-page path (executeCompiledComponentScripts).
 const transformScriptContent = (rawContent) => {
-  // Strip `import component from '...'` — Vibe injects the contextual
-  // component() function as a parameter (it needs access to the temp DOM)
   let content = rawContent.replace(
     /import\s+component\s+from\s+['"][^'"]+['"];?\s*/g,
     ''
   );
 
-  // Check for remaining imports that need rewriting
   const hasImports = /import\s/.test(content);
 
   if (hasImports) {
-    // Rewrite remaining imports to dynamic await import()
-    // Order matters: combined → default → named → namespace → side-effect (most specific first)
     content = content.replace(
       /import\s+(\w+)\s*,\s*\{([^}]+)\}\s+from\s+(['"][^'"]+['"])\s*;?/g,
       'const __m_$1 = await import($3); const $1 = __m_$1.default; const {$2} = __m_$1;'
@@ -193,24 +137,6 @@ const transformScriptContent = (rawContent) => {
   return { content, hasImports };
 };
 
-// Compiled pages inline `<component src>` content at build time, and the
-// compiler neuters each component script to type="vibe-module" so the browser
-// does NOT execute it as a native page module — native timing is wrong
-// (pre-boot: `$` is the placeholder, state registered after boot never merges
-// into the live proxy). This executes those scripts through the same
-// injected-component() path processSingle uses for fetched scripts: one
-// pipeline, identical semantics in both modes. Scripts stay in the DOM
-// (inert) so the manifest's childNodes indices keep matching the page.
-//
-// 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 = [];
   collectMountedModuleScripts(document.body ? [document.body] : [], scripts);
@@ -219,21 +145,6 @@ export const executeCompiledComponentScripts = () => {
   return runVibeModuleScripts(scripts);
 };
 
-// Same pipeline as the boot-time pass, but scoped to a freshly mounted subtree
-// (a conditional branch or iteration row) rather than the whole document. The
-// boot pass only sees component scripts that are in the page at boot; a branch
-// that mounts later — or RE-mounts after being unmounted — carries its own
-// inlined `vibe-module` scripts that must run each time so component-local state
-// (`component({...})` → `$._cN`) is re-registered. Without this, a re-opened
-// conditional restores its markup but its `<!-- each _cN.x -->` reads state that
-// was released on unmount (the AccountProgression overlay rendering blank on
-// second open).
-//
-// `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 = [];
   collectMountedModuleScripts(nodes, scripts);
@@ -242,16 +153,6 @@ export const executeCompiledComponentScriptsIn = (nodes, { silent = false } = {}
   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) {
@@ -267,8 +168,6 @@ const collectMountedModuleScripts = (nodes, out) => {
   }
 };
 
-// Build-time tagging already assigned _cN ids to wrappers; advance the runtime
-// counter past them so freshly generated ids never collide.
 const advanceComponentCounterPastIds = (root) => {
   root.querySelectorAll('[data-vibe-component-id]').forEach((el) => {
     const m = el.getAttribute('data-vibe-component-id')?.match(/^_c(\d+)$/);
@@ -276,11 +175,6 @@ const advanceComponentCounterPastIds = (root) => {
   });
 };
 
-// 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.$) {
@@ -289,18 +183,6 @@ const registerComponentState = (componentId, state, silent) => {
   }
 };
 
-// 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) => {
@@ -321,10 +203,6 @@ const enqueueScriptExecution = (run) => {
   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 {
@@ -340,13 +218,6 @@ const executeScriptUnit = (componentId, content, hasImports, scopedDollar, compo
   }
 };
 
-// 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;
@@ -359,14 +230,8 @@ const runVibeModuleScripts = (scripts, silent = false) => {
   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() || '';
@@ -393,8 +258,6 @@ const runVibeModuleScripts = (scripts, silent = false) => {
     if (task) asyncTasks.push(task);
   }
 
-  // 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));
@@ -406,20 +269,12 @@ const runVibeModuleScripts = (scripts, silent = false) => {
   return asyncTasks.length ? Promise.all(asyncTasks) : null;
 };
 
-// Track pending fetches to cancel them if element is removed
-const pendingFetches = new WeakMap(); // element → AbortController
+const pendingFetches = new WeakMap();
 
-// Component HTML is parsed (and prop/slot-transformed) while its @[...]
-// bindings are still literal text. Parsing in the live document lets the
-// browser act on those literals mid-parse — Chrome logs "The specified value
-// ... cannot be parsed" for a typed input's value="@[...]". An inert document
-// (no browsing context) parses identical DOM without a console to complain to;
-// nodes are auto-adopted into the live document on insertion.
 let inertDocument;
 const createDetached = (tagName) =>
   (inertDocument ??= document.implementation.createHTMLDocument('')).createElement(tagName);
 
-// Cancel a pending fetch for a component element
 export const abortComponentFetch = (element) => {
   const controller = pendingFetches.get(element);
   if (controller) {
@@ -428,73 +283,34 @@ export const abortComponentFetch = (element) => {
   }
 };
 
-// The live element a reactive src binding acts on. The manifest tree keeps the
-// 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:
-// - Unprocessed element (no fetch yet): write the resolved src — the pending
-//   boot/observer processComponent pass fetches it.
-// - Fetch in flight: abort it and fetch the new src.
-// - Mounted wrapper (src consumed by finalize): re-fetch and re-mount; the
-//   authored props + slot content re-apply via the remount context finalize
-//   stashed on the wrapper, and the outgoing component's state is evicted by
-//   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.
   const current = wasFetching
     ? el.getAttribute('src')
     : (el._vibeMountedSrc ?? el.getAttribute('src'));
   if (src === current) return;
   abortComponentFetch(el);
   el.setAttribute('src', src);
-  // 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);
 };
 
-// A src still carrying an @[…] binding is not a URL — it's source material
-// (an iteration or branch template the renderer hasn't consumed yet, or an
-// outlet whose scope owner hasn't resolved it). Fetching it verbatim is never
-// right: initializeBlock substitutes loop-scoped srcs, hydration remounts
-// reactive outlets, and this pass only mounts real URLs.
 const hasUnresolvedSrc = (el) => {
   BINDING_REGEX.lastIndex = 0;
   return BINDING_REGEX.test(el.getAttribute('src'));
 };
 
-// Check if an element is nested inside another unprocessed component[src]
 const isNestedInUnprocessedComponent = (el, rootElement) => {
   let parent = el.parentElement;
   while (parent && parent !== rootElement) {
@@ -509,17 +325,6 @@ const isNestedInUnprocessedComponent = (el, rootElement) => {
   return false;
 };
 
-// Rewrite `@[this.x...]` and `$.this.x...` inside element's text/attrs to use
-// componentId. Shared between script-execution path and pure-render path.
-//
-// Within `@[...]` bindings we rewrite every `this.X` reference (preserving
-// any trailing `.Y.Z` chain), so `@[this.user.name]` and `@[this.x + 1]` both
-// resolve correctly. Outside bindings — i.e. event handler attribute bodies
-// like `onclick="$.this.mode = 'edit'"` — only `$.this.X` writes are
-// rewritten; bare `this.X` in event handlers is handled later by parse.js,
-// which lowers it to `$this(this).X` — resolved at fire time by
-// this-scope.js (declared state keys hit the bucket, everything else stays
-// the native element).
 const rewriteBindingsInString = (str, componentId) =>
   str.replace(BINDING_REGEX, (match, expr) => {
     const rewritten = expr.replace(THIS_PROP_REGEX, `${componentId}.$1`);
@@ -547,20 +352,12 @@ const rewriteThisBindings = (element, componentId) => {
   });
 };
 
-// Tag siblings of a <script> with componentId and rewrite `this.` bindings.
-// Runs BEFORE script.remove() so nextElementSibling is valid. Shared by
-// processSingle (executing path) and renderComponentTemplate (pure path).
 const tagScriptSiblings = (script, componentId) => {
   let sibling = script.nextElementSibling;
   while (sibling) {
     if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
       break;
     }
-    // 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);
@@ -569,21 +366,12 @@ const tagScriptSiblings = (script, componentId) => {
   }
 };
 
-// Substitute props + inline slot content into a pre-processed temp container.
-// Returns the final processed HTML string. Shared by processSingle.finalize()
-// (runtime mount) and renderComponentTemplate (surgical HMR).
 const renderPropsAndSlot = (temp, props, slotHtml) => {
   let transformedHtml = temp.innerHTML;
 
   const DIRECTIVE_COMMENT_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
   const EVENT_ATTR_REGEX = /\bon(\w+)="([^"]*)"/g;
 
-  // HTML's parser lowercases attribute names, so a consumer-written
-  // `<component dndDisabled>` arrives here with propName `dnddisabled` while
-  // the component template author wrote `dndDisabled`. Match identifiers and
-  // bindings case-insensitively so both sides line up. Word-boundary
-  // lookbehind/lookahead still hold (they're case-agnostic), so
-  // `dnddisabled` won't bleed into `dndDisabledAlt`.
   Object.entries(props).forEach(([propName, propValue]) => {
     const bindingMatch = propValue.match(/^@\[(.+)\]$/);
     const exactPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'gi');
@@ -592,11 +380,6 @@ const renderPropsAndSlot = (temp, props, slotHtml) => {
       'gi'
     );
 
-    // Rewrite the identifier only outside string literals. A prop/alias that also
-    // appears inside a quoted string — e.g. the selector in `closest('brawler-slot')`
-    // when the prop is `slot` — must be left intact. Split on string literals
-    // (single/double/backtick, honouring escapes) and substitute only the code spans
-    // between them. Template `${…}` interpolation counts as part of the literal here.
     const stringLiteral = /(['"`])(?:\\.|(?!\1)[^\\])*\1/g;
     const substituteInExpr = (expr, replacement) => {
       let out = '';
@@ -627,11 +410,6 @@ const renderPropsAndSlot = (temp, props, slotHtml) => {
       );
       const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'gi');
       transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
-        // Substitute the bare prop identifier too (not just the `$.prop` form),
-        // mirroring the @[...] binding pass above — so `onclick="pick(item)"`
-        // resolves the live prop, not a global that throws ReferenceError. A
-        // loop-alias path (`row.sig`) becomes `(row.sig)` here; parse.js then
-        // rewrites the alias to `$scope(this,'row')`.
         const rewritten = substituteInExpr(body.replace(stateRegex, `$.${path}`), `(${path})`);
         return rewritten === body ? match : `on${evName}="${rewritten}"`;
       });
@@ -658,8 +436,6 @@ const renderPropsAndSlot = (temp, props, slotHtml) => {
       );
       const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'gi');
       transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
-        // Same bare-identifier substitution for a literal prop: `onclick="set(limit)"`
-        // with `limit="5"` becomes `set(5)`.
         const rewritten = substituteInExpr(body.replace(stateRegex, `$.${literal}`), literal);
         return rewritten === body ? match : `on${evName}="${rewritten}"`;
       });
@@ -681,12 +457,6 @@ const renderPropsAndSlot = (temp, props, slotHtml) => {
   return transformedHtml;
 };
 
-// Pure-render path for surgical HMR. Takes a component's raw template HTML
-// plus the live instance's props, slot, and existing componentIds. Returns
-// the processed HTML string that $.reconcile can diff against the live
-// wrapper's children. Scripts are NOT executed — callers are responsible
-// for deciding whether to preserve the existing state (reuse componentIds)
-// or trigger a full re-mount (new componentIds).
 export const renderComponentTemplate = (rawHtml, props = {}, slotHtml = '', options = {}) => {
   const { componentIds = [] } = options;
   const temp = createDetached('div');
@@ -703,31 +473,19 @@ export const renderComponentTemplate = (rawHtml, props = {}, slotHtml = '', opti
   return renderPropsAndSlot(temp, props, slotHtml);
 };
 
-// Process a single component element: fetch HTML, execute scripts, replace DOM
 const processSingle = (el, debug) => {
-  // Skip dehydrated components
   if (el.hasAttribute(DEHYDRATE_CLASS_OR_ATTR) || el.classList.contains(DEHYDRATE_CLASS_OR_ATTR)) {
     return Promise.resolve();
   }
 
-  // Skip if fetch already in flight for this element
   if (pendingFetches.has(el)) return Promise.resolve();
 
   const src = el.getAttribute('src');
 
-  // Use pre-hydration slot content if available (saved by index.js before
-  // hydration ran, or re-stashed by finalize for reactive-src re-mounts),
-  // otherwise fall back to current innerHTML (e.g. runtime-only usage without
-  // boot). Kept on the element — a re-mount consumes the same authored slot.
   const children = (el._vibeSlotContent !== undefined ? el._vibeSlotContent : el.innerHTML).trim();
-  // A re-mounted wrapper carries no prop attributes (finalize stripped them) —
-  // its authored props ride the remount context stashed at the previous mount.
   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' && attr.name !== 'key' && !attr.name.startsWith('data-vibe-')) {
         props[attr.name] = attr.value;
@@ -735,47 +493,24 @@ const processSingle = (el, debug) => {
     });
   }
 
-  // Capture cache state before the fetch so the debug layer can tell a real
-  // network fetch from a runtime-cache hit (the call below would make them
-  // indistinguishable — both just resolve a promise).
   const fromCache = isComponentCached(src);
 
-  // Create AbortController to cancel fetch if element is removed
   const controller = new AbortController();
   pendingFetches.set(el, controller);
 
   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;
 
-      // Process any <script type="module"> elements
       const moduleScripts = temp.querySelectorAll('script[type="module"]');
 
-      // Process each script — collect async tasks if any have imports
       const asyncTasks = [];
 
-      // Track every componentId registered during this fetch. If the host
-      // element is detached before finalize runs (e.g. a conditional unmounted
-      // mid-fetch, or the user navigated away), we release these state
-      // buckets — otherwise component({...}) leaks state to `$` for DOM that
-      // never reaches the document.
       const registeredComponentIds = [];
 
-      // First componentId encountered — applied to the wrapper itself so
-      // directives living between top-level sibling roots (e.g. a comment
-      // marker for `<!-- if this.X -->`) can resolve component scope via
-      // closest('[data-vibe-component-id]'). Without this, multi-root
-      // templates have scope-less wrappers and top-level `this.` references
-      // fall through to global state.
       let firstComponentId = null;
 
       for (const script of moduleScripts) {
@@ -784,54 +519,29 @@ const processSingle = (el, debug) => {
 
         const { content: scriptContent, hasImports } = transformScriptContent(rawContent);
 
-        // Reuse component ID from HMR if available, otherwise generate new
         const reuseIds = el._vibeReuseComponentIds;
         const componentId = reuseIds && reuseIds.length ? reuseIds.shift() : generateComponentId();
 
         if (firstComponentId === null) firstComponentId = componentId;
 
-        // Provide a component() function that registers state for this component.
-        // Sibling tagging is handled below (before script.remove()) so it works
-        // for both sync and async scripts.
         const componentFn = (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);
           }
-          // Return the id so consumers can reach their reactive state via
-          // `$[id]` — matches the public component.js contract. Without this,
-          // `const id = component(state)` is undefined for src-fetched
-          // components and `$[id]` silently resolves to nothing.
           return componentId;
         };
 
-        // 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.
         tagScriptSiblings(script, componentId);
 
-        // Remove script from temp (we executed it manually)
         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];
@@ -840,27 +550,17 @@ const processSingle = (el, debug) => {
         }
       };
 
-      // 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);
 
-        // Clean up pending fetch tracker — only if this fetch still owns the
-        // slot (a reactive-src re-mount may have aborted us and registered a
-        // newer controller for the same element).
         if (pendingFetches.get(el) === controller) pendingFetches.delete(el);
 
-        // Replace with clean component wrapper (no src, no props)
-        // Check if element still has a parent (might have been removed during fetch)
         if (el.parentNode) {
-          // Create clean wrapper element (preserve tag type: component or div.component)
           const newWrapper =
             el.tagName === 'DIV' ? createDetached('div') : createDetached('component');
 
@@ -869,127 +569,47 @@ const processSingle = (el, debug) => {
           }
 
           newWrapper.innerHTML = transformedHtml;
-          // Park binding-valued src while the wrapper still lives in the inert
-          // document — adoption into the live document is what starts image
-          // loads, so this is the last moment a raw `@[...]` src is harmless.
           parkFetchableSrc(newWrapper);
           if (firstComponentId !== null) {
             newWrapper.setAttribute('data-vibe-component-id', firstComponentId);
           }
-          // Stash the raw source so the HMR plugin can establish a baseline
-          // script hash on the very first update — without this, the first
-          // save after page load would always fall back to re-mount (since
-          // the plugin would have nothing to compare against). Vibe itself
-          // never reads this; it's purely for the plugin spy.
           newWrapper._vibeRawSource = html;
-          // Remount context for reactive src bindings (src="@[page.src]"):
-          // the mounted src (no-op detection), the authored props, and the
-          // authored slot content. Each re-mount consumes these and finalize
-          // stashes them onto the next wrapper — self-sustaining across
-          // arbitrarily many navigations.
           newWrapper._vibeMountedSrc = src;
           newWrapper._vibeRemountProps = props;
           newWrapper._vibeSlotContent = children;
-          // The authored binding travels ON the wrapper (data-vibe-src, same
-          // transport idea as data-vibe-namebind): the original tree node is
-          // pruned when this replaceWith's removal mutation is processed, and
-          // the replacement's reparse recaptures the binding from this
-          // 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.__vibe.iterProps._pN]` to resolve to undefined
-          // on the next hydrate.
           if (el._vibeIterPropIds) {
             newWrapper._vibeIterPropIds = el._vibeIterPropIds;
             el._vibeIterPropIds = null;
           }
-          // The discovery marker rides on the registry path (props with iteration
-          // aliases) AND the global-only raw-binding path (no registry slot, just
-          // `_vibeIterPropExprs = []`). Transfer it whenever present so affected.js's
-          // walkInlinedComponentTrees can find the wrapper and re-hydrate its
-          // bindings on a global-state change.
           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
-          // refresh the registry slots in place — letting the inlined
-          // component's bindings react without rebuilding the row's DOM.
           if (el._vibeIterPropExprs) {
             newWrapper._vibeIterPropExprs = el._vibeIterPropExprs;
             el._vibeIterPropExprs = null;
           }
-          // Back-pointer from the soon-to-be-detached `<component src>` to
-          // the new wrapper. The iteration's `instance.clonedNodes` still
-          // references the original element; follow this link to reach the
-          // live wrapper when refreshing registry slots / re-hydrating.
-          // The wrapper's `_vibeIterTree` (set later by processMutations after
-          // 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;
           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) {
@@ -999,10 +619,6 @@ const processSingle = (el, debug) => {
               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();
@@ -1013,31 +629,19 @@ const processSingle = (el, debug) => {
             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.
           releaseOutgoing(el);
           releaseRegisteredIds();
         }
       };
 
-      // If any scripts had async imports, wait for them before finalizing.
-      // Otherwise finalize synchronously (preserves original boot timing).
       if (asyncTasks.length > 0) {
         return Promise.all(asyncTasks).then(finalize);
       }
       finalize();
     })
     .catch((error) => {
-      // Clean up pending fetch tracker — ownership-guarded (see finalize)
       if (pendingFetches.get(el) === controller) pendingFetches.delete(el);
 
-      // 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;
@@ -1060,10 +664,6 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
     return;
   }
 
-  // Only process top-level components with a fetchable src — skip unresolved
-  // binding srcs (never fetchable), and skip those nested inside other
-  // unprocessed component[src] elements (they're slot content that will
-  // be revealed when the parent component finalizes).
   const topLevel = Array.from(allComponents).filter(
     (el) => !hasUnresolvedSrc(el) && !isNestedInUnprocessedComponent(el, rootElement)
   );
@@ -1073,10 +673,5 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
     return;
   }
 
-  // Fetch and process all top-level components in parallel.
-  // Nested components (inside finalized content) are discovered and
-  // processed by the MutationObserver → processComponent chain.
-  // onComplete is handled by checkCleanup (which fires when no
-  // component[src] elements remain).
   topLevel.forEach((el) => processSingle(el, debug));
 };