@ape-egg/vibe 4.0.1 → 4.1.3

package/runtime/affected.js

@@ -12,10 +12,6 @@ import {
 } from "./utils.js";
 import { beginTracking, endTracking, unsubscribe } from "./tracking.js";
 
-// Drop the subscribers of a stale binding-cache list. A cache rebuild means
-// the parsed source or element changed — the old binding objects are dead,
-// but their anchors may still be connected (a reparse of a live element), so
-// disconnect-pruning alone would leave them serving stale patches.
 const unsubscribeBindings = (list) => {
   if (!list) return;
   for (let i = 0; i < list.length; i++) {
@@ -23,12 +19,6 @@ const unsubscribeBindings = (list) => {
   }
 };
 
-// The @[...] bindings in a tree node are static: the parsed template string and
-// the element's component scope don't change between renders. Re-running the
-// regex + resolveThisPath on every affected-walk was a large per-frame cost in
-// hot iterations (combat at 60fps re-extracts every binding of every row). Cache
-// the extracted + scope-resolved bindings on the node, keyed by the parsed source
-// and element so a re-parse or element swap recomputes.
 const textBindingsOf = (tree) => {
   if (tree._tbSrc === tree.parsed && tree._tbEl === tree.element) return tree._tb;
   unsubscribeBindings(tree._tb);
@@ -45,8 +35,6 @@ const textBindingsOf = (tree) => {
       tokens: tokensOf(resolvedInner),
     });
   }
-  // Back-ref so dispatch can expand one dirty binding to its whole text
-  // span (a text node hydrates all-or-nothing).
   for (let i = 0; i < out.length; i++) out[i]._group = out;
   tree._tb = out;
   tree._tbSrc = tree.parsed;
@@ -75,9 +63,6 @@ const attrBindingsOf = (tree) => {
   return out;
 };
 
-// Name bindings (`<icon @[fx.icon]>`) live as raw strings on tree.nameBindings.
-// Extract + this-resolve + tokenize them once, same cache discipline as the
-// text/attr binding caches above.
 const nameBindingsOf = (tree) => {
   if (tree._nbSrc === tree.nameBindings && tree._nbEl === tree.element) return tree._nb;
   unsubscribeBindings(tree._nb);
@@ -96,20 +81,12 @@ const nameBindingsOf = (tree) => {
   return out;
 };
 
-// Evaluate conditional expression
 const evaluateCondition = (expression, state, element = null) =>
   !!evalInScope(expression, state, element);
 
-// One subscriber per conditional/iteration tree node, hosted on the node —
-// stable across flushes, dead with the node. The start comment anchors
-// liveness (disconnect-pruning).
 export const nodeSubscriberOf = (tree, kind) =>
   (tree._sub ??= { kind, node: tree, anchor: tree.meta.startComment });
 
-// Helper function to check if a match references a specific key.
-// Fast path: exact match or property access (`user.name` matches `user`).
-// Slow path: word-boundary search for complex expressions like `Math.floor(coins / 100)`
-// where the key appears as an identifier anywhere in the expression.
 const isIdentChar = (c) =>
   (c >= "a" && c <= "z") ||
   (c >= "A" && c <= "Z") ||
@@ -117,12 +94,6 @@ const isIdentChar = (c) =>
   c === "_" ||
   c === "$";
 
-// Split an expression into its identifier tokens — every maximal run of
-// identifier characters. This is exactly the set of standalone identifiers the
-// old per-key `matchesKey` scan could match, so intersecting these tokens with
-// the state-key set is equivalent to "which state keys does this binding read"
-// for identifier-named keys, but costs O(expr length) once (cached) instead of
-// O(stateKeys) on every frame. Deduped so the per-frame change check stays tight.
 const tokensOf = (expr) => {
   const seen = new Set();
   let i = 0;
@@ -138,11 +109,6 @@ const tokensOf = (expr) => {
   return [...seen];
 };
 
-// Memoize the own-key set of a state snapshot so binding checks do O(1)
-// membership tests instead of scanning the key array. Keyed by the snapshot
-// object itself — scoped-state proxies and merged plain objects are reused
-// across every node of a single affected() descent, so the Set is built once
-// per snapshot, not once per binding.
 const keySetCache = new WeakMap();
 const keySetOf = (snapshot) => {
   let set = keySetCache.get(snapshot);
@@ -153,13 +119,6 @@ const keySetOf = (snapshot) => {
   return set;
 };
 
-// A binding is affected on update when it reads a state key whose value changed,
-// OR when it reads no known state key at all (can't prove it's unaffected, so
-// re-evaluate — hydrate self-guards the DOM write). False can only be returned
-// when every key the binding reads is present AND unchanged. A key absent from
-// the OLD snapshot is a change even when its new value is undefined — mount
-// walks diff against {}, and skipping there means the binding never reaches
-// tracked() and never registers a subscriber.
 const bindingAffected = (tokens, keySet, state, newState) => {
   let matched = false;
   for (let i = 0; i < tokens.length; i++) {
@@ -172,10 +131,6 @@ const bindingAffected = (tokens, keySet, state, newState) => {
   return !matched;
 };
 
-// Name bindings (`<icon @[fx.convertIcon]>`) arrive lowercased from HTML while
-// state keys stay camelCase, so they match keys case-insensitively. This map
-// resolves a (possibly lowercased) token back to its real key. Memoized per
-// snapshot like keySetOf.
 const nameKeyMapCache = new WeakMap();
 const nameKeyMapOf = (snapshot) => {
   let map = nameKeyMapCache.get(snapshot);
@@ -203,22 +158,8 @@ const nameBindingAffected = (tokens, keyMap, state, newState) => {
   return !matched;
 };
 
-// Identifier-followed-by-`(` — i.e. an attempted function or method call.
-// Used to flag conditional expressions whose result can't be trusted to the
-// snapshot-equality short-circuit because the called function may read live
-// `$` (or other state-holding globals) via closure rather than the state
-// snapshot affected.js passes in. False positives are acceptable: when the
-// expression contains a call, we fall back to "if any state key changed,
-// re-evaluate"; mountBranch's branchChanged guard suppresses the no-op DOM
-// churn when the value didn't actually flip.
 const CALL_EXPR_REGEX = /\b[A-Za-z_$][\w$]*\s*\(/;
 
-// Descend into any inlined `<component>` parsed trees attached to an
-// iteration row. `_vibeIterTree` is stamped on the post-process wrapper by
-// index.js (mutation-observer path) and on nested inlined components reached
-// via `[data-vibe-iter-prop]`. The trees retain the original `@[…]` binding
-// text so this affected walk can flag changes the same way it would on the
-// row's own tree.
 const walkInlinedComponentTrees = (
   clonedNodes,
   state,
@@ -248,16 +189,6 @@ const walkInlinedComponentTrees = (
   }
 };
 
-// One affected() pass can reach the same parsed tree through several linkage
-// channels — a conditional walks both its runtime-mounted branch and its
-// processMutations-linked children, an iteration row's inlined component tree
-// hangs off the wrapper's `_vibeIterTree` AND off an ancestor's children. Each
-// duplicate walk multiplies at every nesting level (measured ~1000 visits per
-// node per flush on the game's armory page). A tree object is one DOM position
-// — the first visit already collected its entries, so the rest are skipped.
-// Scoped states stay correct: a row-scoped tree is reached through its owning
-// iteration first (document order), and inlined component trees carry
-// registry-rewritten expressions that evaluate identically from any channel.
 let walkVisited = null;
 
 const recursive = (
@@ -272,7 +203,6 @@ const recursive = (
     if (walkVisited.has(tree)) return affected;
     walkVisited.add(tree);
   }
-  // Handle iteration nodes specially
   if (tree.type === "iteration") {
     const resolvedExpr = resolveThisPath(
       tree.meta.arrayPath,
@@ -282,9 +212,6 @@ const recursive = (
     const oldArray =
       evalInScope(resolvedExpr, state, tree.meta.startComment?.parentElement) ??
       resolvePath(state, resolvedExpr);
-    // The new-side eval is the iteration's subscription: whatever the
-    // arrayPath expression reads NOW is what should notify it. Old-side
-    // evals never track — they read the previous snapshot.
     const iterSub = nodeSubscriberOf(tree, "iteration");
     iterSub.lastScope = newState;
     beginTracking(iterSub, overlayKeysOf(newState));
@@ -296,27 +223,6 @@ const recursive = (
       ) ?? resolvePath(newState, resolvedExpr);
     endTracking();
 
-    // Fast path: reference comparison (arrays are typically replaced, not mutated)
-    // This avoids expensive O(n) deepEqual for large arrays.
-    //
-    // Call-expression array paths (`<!-- each filterItems(...) -->`, `.filter()`
-    // chains) build a FRESH array on every eval, so the two evals above never
-    // share a reference even when nothing relevant changed — the ref compare
-    // alone would flag every such iteration as a full array change on every
-    // flush and rewalk all its rows (the armory 900ms-per-tick hang). For call
-    // expressions only, same length + same item refs ⇒ the rendered rows are
-    // already right: fall through to the per-instance walk below, which still
-    // catches outer-state bindings inside rows. Plain paths keep pure ref
-    // semantics — `$.items = [...$.items]` after an in-place item mutation must
-    // still refresh every row (the documented reassign-to-rerender pattern).
-    //
-    // "Already right" additionally requires the RENDERED rows to correspond to
-    // the array: an iteration whose initial render evaluated before its
-    // component's script settled (a fetched compiled fragment defining the
-    // helper) bailed with zero instances — its two evals now agree ("2, 6"
-    // literals produce equal fresh arrays every flush) but nothing is on
-    // screen, and skipping here would strand it empty forever (the game's
-    // "# Teams" BoxRange). Instance count vs array length is that invariant.
     if (oldArray !== newArray) {
       const freshRefArtifact =
         CALL_EXPR_REGEX.test(resolvedExpr) &&
@@ -337,17 +243,7 @@ const recursive = (
       }
     }
 
-    // Array didn't change, but check for affected elements inside iteration instances
-    // (e.g., when tutorialProgress changes, need to update checkmarks in menu items)
     if (tree.runtime.instances) {
-      // Compiled iterations have instances without tree/scopedState — the batch function
-      // may reference global state keys (e.g., `selectedCategory` in a button binding).
-      // If any state key changed, trigger a rebuild so the batch function re-evaluates.
-      // Instances rendered without a per-row parsed tree — compiled (batch
-      // fn from the manifest) or runtime batch (fast path for simple
-      // templates) — can't be walked by the recursive descent below to
-      // detect nested outer-state bindings. Mark the whole iteration as
-      // affected so updateIteration runs and rebuilds the rows.
       const hasTreelessInstances =
         tree.runtime.instances.length > 0 &&
         !tree.runtime.instances[0].tree;
@@ -372,17 +268,6 @@ const recursive = (
 
       for (const instance of tree.runtime.instances) {
         if (instance.tree && instance.scopedState) {
-          // Build plain-object snapshots for comparison. Spreading
-          // instance.scopedState yields its local vars (item, index) plus
-          // whatever globals were captured at scope-creation time; the
-          // overlaying spread of state/newState then writes the *current*
-          // values from this update cycle. Both merged states are plain
-          // objects with up-to-date values.
-          // The merged snapshot only needs this row's aliases overlaid on the
-          // current globals (`state`/`newState` already carry every global key).
-          // Recover the small overlay recorded at scope creation and plain-merge
-          // it — spreading instance.scopedState (a Proxy) instead fires its traps
-          // over every global key, per instance, per frame (a combat hot spot).
           const overlay = scopedOverlayOf(instance.scopedState);
           const mergedOldState = overlay
             ? { ...state, ...overlay }
@@ -390,21 +275,10 @@ const recursive = (
           const mergedNewState = overlay
             ? { ...newState, ...overlay }
             : { ...instance.scopedState, ...newState };
-          // Carry the alias set onto the merged plain snapshots so tracking
-          // windows opened against them can tell alias reads from global
-          // reads (skipKeys). Without the recorded overlay (legacy scoped
-          // states) alias names subscribe as phantom keys — harmless, they
-          // never appear in changedProps.
           if (overlay) {
             rememberOverlay(mergedOldState, overlay);
             rememberOverlay(mergedNewState, overlay);
           }
-          // scopedStateForHydration must reflect the new state so hydrate's
-          // bindings inside the row see post-update values. instance.scopedState
-          // is frozen against whatever target renderIteration was called with
-          // (often the plain initialState snapshot from index.js), so reading
-          // outer-state keys through it returns stale values after later
-          // mutations. mergedNewState carries the live globals + localVars.
           recursive(
             instance.tree,
             mergedOldState,
@@ -414,16 +288,6 @@ const recursive = (
             depth + 1,
           );
 
-          // Components mounted as `<component src>` *inside* an iteration row
-          // are not children of `instance.tree` — their parsed tree lives on
-          // the post-process wrapper as `_vibeIterTree`. Without descending
-          // into it, conditionals / bindings inside the inlined component are
-          // invisible to this walk, so a global state change that should tear
-          // down a row-internal `<!-- if -->` (or flip a binding) inside the
-          // component is missed. `updateInstance` re-hydrates these trees via
-          // `hydrateInlinedIterationComponents`, but only when the iteration
-          // itself is flagged affected (array change). For pure global-state
-          // updates the array is unchanged, so we descend here instead.
           if (instance.clonedNodes) {
             walkInlinedComponentTrees(
               instance.clonedNodes,
@@ -440,16 +304,12 @@ const recursive = (
     return affected;
   }
 
-  // Handle conditional nodes specially
   if (tree.type === "conditional") {
     const oldValue = evaluateCondition(
       tree.meta.expression,
       state,
       tree.meta.startComment?.parentElement,
     );
-    // New-side eval doubles as the conditional's subscription (see the
-    // iteration note above). Helper bodies reading live `$` record through
-    // the proxy trap even though the direct reads here hit the snapshot.
     const condSub = nodeSubscriberOf(tree, "conditional");
     condSub.lastScope = newState;
     beginTracking(condSub, overlayKeysOf(newState));
@@ -460,15 +320,7 @@ const recursive = (
     );
     endTracking();
 
-    // Check if condition result changed
     if (oldValue !== newValue) {
-      // Carry the state pair the condition was evaluated against. Inside an
-      // iteration row this is the merged state (loop alias + current globals),
-      // outside it is the cycle's top-level state. hydrate hands these to
-      // updateConditional so the branch swap re-evaluates the expression in
-      // the same scope — without them, a row-internal `if` is re-evaluated
-      // against a state with no `item`, which always reads falsy and leaves
-      // rows that were initially on the else branch stuck there.
       affected.push({
         type: "conditional",
         node: tree,
@@ -477,21 +329,9 @@ const recursive = (
         oldScopedState: state,
         wasConnected: !!tree.meta.startComment?.isConnected,
       });
-      // The branch swap re-renders everything beneath — no point collecting
-      // entries for content that's about to be replaced.
       return affected;
     }
 
-    // Function-call short-circuit: when the expression contains a `(`-style
-    // call, the snapshot eval can be blind — the called helper may read live
-    // `$` via closure rather than the passed state, so `oldValue` and
-    // `newValue` both run against the *current* values and the equality check
-    // never fires. Flag as affected whenever any state key actually changed
-    // this cycle so updateConditional re-runs against live state; if the
-    // result hasn't really flipped, mountBranch's branchChanged guard absorbs
-    // the call cheaply. Skip during initial hydration (state === newState).
-    // Does NOT stop the walk: the branch is (almost always) unchanged, so the
-    // content beneath still needs its own entries collected below.
     if (state !== newState && CALL_EXPR_REGEX.test(tree.meta.expression)) {
       const stateKeys = Object.keys(state);
       const anyChanged = stateKeys.some((k) => state[k] !== newState[k]);
@@ -507,17 +347,6 @@ const recursive = (
       }
     }
 
-    // Condition didn't change: walk the live content. Runtime-mounted
-    // branches live in runtime.activeInstance.parsedTree. COMPILED
-    // pre-rendered conditionals never went through mountBranch — their live
-    // DOM is what parse put in `children` — and processMutations links
-    // later-mounted subtrees (SPA fragments, slot-projected content) into
-    // `children` too. Both channels must be walked or content under a
-    // compiled conditional is frozen at its mount-time render (the game's
-    // blank fragment pages). Children whose root isn't connected are the
-    // detached both-branch template nodes of a runtime conditional — skip
-    // those; their restoration templates are strings on meta.branches, and
-    // hydrating detached template DOM is pure waste.
     if (tree.runtime.activeInstance && tree.runtime.activeInstance.parsedTree) {
       recursive(
         tree.runtime.activeInstance.parsedTree,
@@ -544,9 +373,6 @@ const recursive = (
   const matches = textBindingsOf(tree);
 
   if (matches.length) {
-    // A text node is hydrated as a whole (every @[…] re-interpolated together),
-    // so the node is all-or-nothing: if any of its bindings is affected, push
-    // them all. Initial hydration affects everything.
     const isInitialHydration = state === newState;
     let hasAffected = isInitialHydration;
     if (!isInitialHydration) {
@@ -566,16 +392,15 @@ const recursive = (
           matchInner: m.inner,
           input: m.input,
           element: tree.element,
-          textNode: tree.textNode, // Reference to specific text node (prevents wiping children)
-          scopedState: scopedStateForHydration, // Pass scoped state from iteration context
-          binding: m, // Stable per-binding host — hydrate registers its subscriber here
+          textNode: tree.textNode,
+          scopedState: scopedStateForHydration,
+          binding: m,
           wasConnected: !!(tree.textNode ?? tree.element)?.isConnected,
         });
       }
     }
   }
 
-  // Check attribute bindings
   if (tree.attributes) {
     const isInitialHydration = state === newState;
     const keySet = isInitialHydration ? null : keySetOf(newState);
@@ -592,9 +417,9 @@ const recursive = (
             attrName,
             attrValue,
             matchOuter: m.outer,
-            matchInner: m.inner, // Keep original, evalInScope will resolve this.
+            matchInner: m.inner,
             element: tree.element,
-            scopedState: scopedStateForHydration, // Pass scoped state from iteration context
+            scopedState: scopedStateForHydration,
             binding: m,
             wasConnected: !!tree.element?.isConnected,
           });
@@ -603,7 +428,6 @@ const recursive = (
     }
   }
 
-  // Check name bindings (bindings in attribute names)
   if (tree.nameBindings) {
     const isInitialHydration = state === newState;
     const keyMap = isInitialHydration ? null : nameKeyMapOf(newState);
@@ -617,7 +441,7 @@ const recursive = (
           type: "nameBinding",
           nameBinding: m.nameBinding,
           matchOuter: m.outer,
-          matchInner: m.inner, // Keep original, evalInScope will resolve this.
+          matchInner: m.inner,
           element: tree.element,
           scopedState: scopedStateForHydration,
           binding: m,
@@ -627,9 +451,6 @@ const recursive = (
     }
   }
 
-  // Process children — except under an outgoing wrapper, whose subtree is
-  // frozen until the swap (the node's own bindings above stay live: the next
-  // navigation must still re-trigger the remount through them).
   const children = tree.children;
   if (children && !isOutgoing(tree.element)) {
     for (const key in children) {
@@ -650,10 +471,6 @@ const recursive = (
   return affected;
 };
 
-// The whole collect is a speculative context: evaluations here probe "did
-// this change?" against snapshots where scoped aliases may legitimately be
-// absent — expected throws, not author errors (debug.js reportEvalError
-// stays quiet inside).
 export default (tree, state, newState) => {
   walkVisited = new WeakSet();
   beginSpeculative();

package/runtime/cleanup.js

@@ -1,80 +1,40 @@
 import { debugLog } from './debug.js';
-import {
-  PHASE_READY,
-  FOUC_CLASS_OR_ATTR,
-  DEHYDRATE_CLASS_OR_ATTR,
-  NON_REACTIVE_ELEMENTS,
-} from './constants.js';
+import { isInert } from './inert.js';
+import { PHASE_READY, FOUC_CLASS_OR_ATTR } from './constants.js';
+
+const skipInert = (root) => ({
+  acceptNode: (node) => (isInert(node, root) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT),
+});
 
-/**
- * Check if all Vibe processing is complete and cleanup can run
- * @param {Element} rootElement - Root element to check
- * @returns {Boolean} - true if cleanup should run
- */
 export const shouldCleanup = (rootElement) => {
-  // 1. Check for pending <component> elements (only those with src - fetched components)
-  // Inline component wrappers (<component> without src) are fine to remain
-  const componentElements = rootElement.querySelectorAll('component[src], div.component[src]');
+  const componentElements = [
+    ...rootElement.querySelectorAll('component[src], div.component[src]'),
+  ].filter((el) => !isInert(el, rootElement));
   if (componentElements.length > 0) {
     return false;
   }
 
-  // 2. Check for unhydrated bindings (literal @[...] in DOM, excluding dehydrated
-  // and non-reactive elements — hydrate never touches those, so a literal inside
-  // them is final content, not pending work)
-  const walker = document.createTreeWalker(rootElement, NodeFilter.SHOW_TEXT, {
-    acceptNode(node) {
-      let parent = node.parentElement;
-      while (parent && parent !== rootElement) {
-        if (NON_REACTIVE_ELEMENTS.includes(parent.nodeName)) {
-          return NodeFilter.FILTER_REJECT;
-        }
-        if (parent.hasAttribute(DEHYDRATE_CLASS_OR_ATTR) || parent.classList?.contains(DEHYDRATE_CLASS_OR_ATTR)) {
-          return NodeFilter.FILTER_REJECT; // Skip dehydrated content
-        }
-        parent = parent.parentElement;
-      }
-      return NodeFilter.FILTER_ACCEPT;
-    },
-  });
+  const walker = document.createTreeWalker(
+    rootElement,
+    NodeFilter.SHOW_TEXT,
+    skipInert(rootElement),
+  );
 
   let node;
   while ((node = walker.nextNode())) {
-    if (/@\[.+?\]/.test(node.textContent)) {
-      return false; // Found literal binding (not in dehydrated element)
+    if (!node._vibeBoundValue && /@\[.+?\]/.test(node.textContent)) {
+      return false;
     }
   }
 
-  // 3. Check for unhydrated ATTRIBUTE bindings — style="width: @[…]%" is
-  // invalid CSS until hydrated (width computes as auto → a full-width bar),
-  // so revealing on text-settled alone paints attribute-only content wrong
-  // (the game's "Making potion" loader flashed full on every navigation).
-  // data-vibe-* attributes are runtime transport that legitimately carries
-  // raw bindings across remounts, and src/key on a component wrapper are the
-  // wrapper's own remount contract — both excluded.
-  const elementWalker = document.createTreeWalker(rootElement, NodeFilter.SHOW_ELEMENT, {
-    acceptNode(el) {
-      let parent = el;
-      while (parent && parent !== rootElement) {
-        if (NON_REACTIVE_ELEMENTS.includes(parent.nodeName)) {
-          return NodeFilter.FILTER_REJECT;
-        }
-        if (parent.hasAttribute(DEHYDRATE_CLASS_OR_ATTR) || parent.classList?.contains(DEHYDRATE_CLASS_OR_ATTR)) {
-          return NodeFilter.FILTER_REJECT;
-        }
-        parent = parent.parentElement;
-      }
-      return NodeFilter.FILTER_ACCEPT;
-    },
-  });
+  const elementWalker = document.createTreeWalker(
+    rootElement,
+    NodeFilter.SHOW_ELEMENT,
+    skipInert(rootElement),
+  );
 
   let el;
   while ((el = elementWalker.nextNode())) {
-    // A component wrapper's attributes are all its own machinery: src/key
-    // are the remount contract, data-vibe-* is transport, and every other
-    // attribute is a PROP — owned and consumed by processComponent at mount,
-    // parked raw by design on a declaration-form outlet whose src resolved
-    // to nothing. None of them are unhydrated page bindings.
     if (
       el.nodeName === 'COMPONENT' ||
       (el.nodeName === 'DIV' && el.classList?.contains('component'))
@@ -83,36 +43,27 @@ export const shouldCleanup = (rootElement) => {
     }
     for (const attr of el.attributes) {
       if (attr.name.startsWith('data-vibe-')) continue;
+      if (el._vibeBoundAttrs?.has(attr.name)) continue;
       if (/@\[.+?\]/.test(attr.value)) {
         return false;
       }
     }
   }
 
-  // 4. All processing appears complete
   return true;
 };
 
-/**
- * Perform cleanup - remove attribute or class from all matching elements
- * @param {Element} rootElement - Root element
- * @param {Boolean} debug - Debug mode
- */
 export const cleanup = (rootElement, debug = false) => {
-  // Force reflow
   rootElement.offsetHeight;
 
-  // Determine if selector is a class (starts with .) or attribute (default)
   const isClass = FOUC_CLASS_OR_ATTR.startsWith('.');
   const cleanName = FOUC_CLASS_OR_ATTR.replace(/^\./, '').replace(/^\[/, '').replace(/\]$/, '');
 
   if (isClass) {
-    // Remove class from all elements in document that have it
     const elements = document.querySelectorAll(`.${cleanName}`);
     elements.forEach((el) => el.classList.remove(cleanName));
     debugLog(PHASE_READY, `Removing .${cleanName} class from ${elements.length} ${elements.length === 1 ? 'element' : 'elements'}`, debug);
   } else {
-    // Remove attribute from all elements in document that have it
     const elements = document.querySelectorAll(`[${cleanName}]`);
     elements.forEach((el) => el.removeAttribute(cleanName));
     debugLog(

package/runtime/component-cache.js

@@ -1,39 +1,7 @@
-// Component template cache.
-//
-// Vibe loads each `<component src="...">` by fetching its HTML template. A page
-// commonly mounts the same component many times (a list of cards, a row of
-// stat bars), and an SPA re-mounts components on every navigation. Without a
-// cache, each instance — and each revisit — refetches an identical template,
-// and a burst of same-tick mounts stampedes the network with N concurrent
-// requests for one file.
-//
-// This module dedupes those fetches by `src`:
-//   - concurrent mounts in the same tick share one in-flight request, because
-//     the PROMISE (not the resolved text) is cached synchronously before the
-//     first await — so callers coalesce onto it instead of each starting their own
-//   - later mounts (including after SPA navigation) resolve from memory, with
-//     no network request at all — the one win a browser HTTP cache cannot
-//     provide, since it revalidates per request and never coalesces concurrent ones
-//
-// The cache is session-lived and content-busted, never time-busted. In
-// production a component template is immutable for the life of the page (it
-// only changes on redeploy, which is a new session anyway), so there is nothing
-// to invalidate. In development, tooling busts entries on file change via
-// `clearComponentCache(path)` — which keeps this module free of any dev/HMR
-// coupling; it never references the dev server or its events.
-//
-// Disable entirely with `vibe(state, { noCache: true })`.
-
 let enabled = true;
 
-// src -> Promise<string> (raw template HTML). Stores the in-flight promise so
-// concurrent callers coalesce; the resolved value is held by the promise, so a
-// settled entry is an instant cache hit on every later read.
 const templates = new Map();
 
-// Configure from the runtime config (`{ noCache }`). Called once at boot. When
-// caching is turned off we also drop anything already cached, so toggling at
-// runtime (e.g. between test cases) can't serve a stale hit.
 export const configureComponentCache = (config = {}) => {
   enabled = !config?.noCache;
   if (!enabled) templates.clear();
@@ -41,19 +9,8 @@ export const configureComponentCache = (config = {}) => {
 
 export const isComponentCacheEnabled = () => enabled;
 
-// True when `src` will resolve without a new network request — either a settled
-// template or an in-flight request this mount coalesces onto. Callers capture
-// this BEFORE fetchComponentTemplate so the debug layer can distinguish a real
-// network fetch from a cache hit.
 export const isComponentCached = (src) => enabled && templates.has(src);
 
-// Fetch a component template, deduped by `src`. Returns a Promise<string>.
-//
-// `signal` aborts the request when the host element is removed. It is honored
-// only on the uncached path: a shared cached fetch must NOT be aborted by one
-// element unmounting while other elements still await the same template. The
-// caller already re-checks `el.parentNode` after the fetch settles, so dropping
-// the abort on the shared path costs nothing but a tiny, redundant download.
 export const fetchComponentTemplate = (src, signal) => {
   if (!enabled) {
     return fetch(src, { signal }).then((response) => response.text());
@@ -63,25 +20,15 @@ export const fetchComponentTemplate = (src, signal) => {
   if (!entry) {
     entry = fetch(src).then(async (response) => {
       const text = await response.text();
-      // Never persist a failed response — the immediate caller still gets the
-      // body (parity with the uncached path), but the next mount may retry.
       if (!response.ok) templates.delete(src);
       return text;
     });
-    // Cache synchronously, before the first await, so same-tick concurrent
-    // mounts find this pending entry and coalesce onto it.
     templates.set(src, entry);
-    // Drop the entry if the fetch rejects, so a transient network error isn't
-    // sticky for the rest of the session.
     entry.catch(() => templates.delete(src));
   }
   return entry;
 };
 
-// Invalidate cached templates. With a `path`, drops that one entry (the query
-// string is ignored when matching, so `/components/Foo.html` also clears a
-// versioned `/components/Foo.html?v=…`); with no argument, clears everything.
-// Exposed publicly as `$.clearComponentCache` for tooling to call on change.
 export const clearComponentCache = (path) => {
   if (!path) {
     templates.clear();