@ape-egg/vibe 2.0.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",

package/runtime/cleanup.js

@@ -1,5 +1,10 @@
 import { debugLog } from './debug.js';
-import { PHASE_READY, FOUC_CLASS_OR_ATTR, DEHYDRATE_CLASS_OR_ATTR } from './constants.js';
+import {
+  PHASE_READY,
+  FOUC_CLASS_OR_ATTR,
+  DEHYDRATE_CLASS_OR_ATTR,
+  NON_REACTIVE_ELEMENTS,
+} from './constants.js';
 
 /**
  * Check if all Vibe processing is complete and cleanup can run
@@ -14,12 +19,16 @@ export const shouldCleanup = (rootElement) => {
     return false;
   }
 
-  // 2. Check for unhydrated bindings (literal @[...] in DOM, excluding dehydrated elements)
+  // 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) {
-      // Check if this text node is inside a dehydrated element
       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
         }

package/runtime/component-cache.js

@@ -0,0 +1,94 @@
+// 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();
+};
+
+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());
+  }
+
+  let entry = templates.get(src);
+  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();
+    return;
+  }
+  const base = path.split('?')[0];
+  for (const key of templates.keys()) {
+    if (key.split('?')[0] === base) templates.delete(key);
+  }
+};

package/runtime/component.js

@@ -1,12 +1,14 @@
 import { debugLog } from './debug.js';
 import {
   PHASE_FETCH,
+  PHASE_FETCH_CACHED,
   DEHYDRATE_CLASS_OR_ATTR,
   BINDING_REGEX,
   THIS_PROP_REGEX,
   STATE_THIS_PROP_REGEX,
 } from './constants.js';
 import { evalInScope } from './utils.js';
+import { fetchComponentTemplate, isComponentCached } from './component-cache.js';
 
 // Deterministic component counter
 let componentCounter = 0;
@@ -98,9 +100,131 @@ 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;'
+    );
+    content = content.replace(
+      /import\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?/g,
+      'const $1 = (await import($2)).default;'
+    );
+    content = content.replace(
+      /import\s+\{([^}]+)\}\s+from\s+(['"][^'"]+['"])\s*;?/g,
+      'const {$1} = await import($2);'
+    );
+    content = content.replace(
+      /import\s+\*\s+as\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?/g,
+      'const $1 = await import($2);'
+    );
+    content = content.replace(
+      /import\s+(['"][^'"]+['"])\s*;?/g,
+      'await import($1);'
+    );
+  }
+
+  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.
+export const executeCompiledComponentScripts = () => {
+  const scripts = document.querySelectorAll('script[type="vibe-module"]');
+  if (!scripts.length) return null;
+
+  // Build-time tagging already assigned _cN ids to wrappers; advance the
+  // runtime counter past them so freshly generated ids never collide.
+  document.querySelectorAll('[data-vibe-component-id]').forEach((el) => {
+    const m = el.getAttribute('data-vibe-component-id')?.match(/^_c(\d+)$/);
+    if (m) componentCounter = Math.max(componentCounter, Number(m[1]) + 1);
+  });
+
+  const asyncTasks = [];
+  const claimed = new Set();
+
+  for (const script of scripts) {
+    // 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() || '';
+    if (!rawContent) continue;
+
+    // The build tagged each component wrapper with its deterministic id —
+    // the same id the stamped bindings reference. First script in a wrapper
+    // claims it; additional scripts get fresh ids (mirrors the per-script
+    // ids of the fetch path).
+    const wrapper = script.closest('[data-vibe-component-id]');
+    let componentId = wrapper?.getAttribute('data-vibe-component-id');
+    if (!componentId || claimed.has(componentId)) componentId = generateComponentId();
+    claimed.add(componentId);
+
+    const { content, hasImports } = transformScriptContent(rawContent);
+
+    const componentFn = (state) => {
+      if (!window.__vibeComponents) window.__vibeComponents = {};
+      window.__vibeComponents[componentId] = state;
+      if (window.$) window.$[componentId] = state;
+      return componentId;
+    };
+
+    runComponentCleanups(componentId);
+    const scopedDollar = createScopedDollar(componentId);
+
+    try {
+      if (hasImports) {
+        const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+        asyncTasks.push(new AsyncFunction('$', 'component', content)(scopedDollar, componentFn));
+      } else {
+        new Function('$', 'component', content)(scopedDollar, componentFn);
+      }
+    } catch (e) {
+      console.warn('[vibe] Failed to execute component script:', e);
+    }
+  }
+
+  return asyncTasks.length ? Promise.all(asyncTasks) : null;
+};
+
 // Track pending fetches to cancel them if element is removed
 const pendingFetches = new WeakMap(); // element → AbortController
 
+// 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);
@@ -273,7 +397,7 @@ const renderPropsAndSlot = (temp, props, slotHtml) => {
 // or trigger a full re-mount (new componentIds).
 export const renderComponentTemplate = (rawHtml, props = {}, slotHtml = '', options = {}) => {
   const { componentIds = [] } = options;
-  const temp = document.createElement('div');
+  const temp = createDetached('div');
   temp.innerHTML = rawHtml;
 
   const idsToReuse = [...componentIds];
@@ -310,15 +434,19 @@ 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 fetch(src, { signal: controller.signal })
-    .then((r) => r.text())
+  return fetchComponentTemplate(src, controller.signal)
     .then((html) => {
       // Parse HTML in temporary container to process component scripts
-      const temp = document.createElement('div');
+      const temp = createDetached('div');
       temp.innerHTML = html;
 
       // Process any <script type="module"> elements
@@ -343,43 +471,10 @@ const processSingle = (el, debug) => {
       let firstComponentId = null;
 
       for (const script of moduleScripts) {
-        let scriptContent = script.textContent?.trim() || '';
-        if (!scriptContent) continue;
-
-        // Strip `import component from '...'` — Vibe injects the contextual
-        // component() function as a parameter (it needs access to the temp DOM)
-        scriptContent = scriptContent.replace(
-          /import\s+component\s+from\s+['"][^'"]+['"];?\s*/g,
-          ''
-        );
-
-        // Check for remaining imports that need rewriting
-        const hasImports = /import\s/.test(scriptContent);
-
-        if (hasImports) {
-          // Rewrite remaining imports to dynamic await import()
-          // Order matters: combined → default → named → namespace → side-effect (most specific first)
-          scriptContent = scriptContent.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;'
-          );
-          scriptContent = scriptContent.replace(
-            /import\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?/g,
-            'const $1 = (await import($2)).default;'
-          );
-          scriptContent = scriptContent.replace(
-            /import\s+\{([^}]+)\}\s+from\s+(['"][^'"]+['"])\s*;?/g,
-            'const {$1} = await import($2);'
-          );
-          scriptContent = scriptContent.replace(
-            /import\s+\*\s+as\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?/g,
-            'const $1 = await import($2);'
-          );
-          scriptContent = scriptContent.replace(
-            /import\s+(['"][^'"]+['"])\s*;?/g,
-            'await import($1);'
-          );
-        }
+        const rawContent = script.textContent?.trim() || '';
+        if (!rawContent) continue;
+
+        const { content: scriptContent, hasImports } = transformScriptContent(rawContent);
 
         // Reuse component ID from HMR if available, otherwise generate new
         const reuseIds = el._vibeReuseComponentIds;
@@ -454,9 +549,7 @@ const processSingle = (el, debug) => {
         if (el.parentNode) {
           // Create clean wrapper element (preserve tag type: component or div.component)
           const newWrapper =
-            el.tagName === 'DIV'
-              ? document.createElement('div')
-              : document.createElement('component');
+            el.tagName === 'DIV' ? createDetached('div') : createDetached('component');
 
           if (el.tagName === 'DIV') {
             newWrapper.className = 'component';
@@ -476,7 +569,7 @@ const processSingle = (el, debug) => {
           // 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.__vibeIterProps._pN]` to resolve to undefined
+          // causing every `@[window.__vibeiterprops._pN]` to resolve to undefined
           // on the next hydrate.
           if (el._vibeIterPropIds) {
             newWrapper._vibeIterPropIds = el._vibeIterPropIds;
@@ -502,7 +595,7 @@ const processSingle = (el, debug) => {
           // each row update.
           el._vibeReplacedBy = newWrapper;
           el.replaceWith(newWrapper);
-          debugLog(PHASE_FETCH, src, debug);
+          debugLog(fromCache ? PHASE_FETCH_CACHED : PHASE_FETCH, src, debug);
 
           // MutationObserver handles parsing and hydrating the new content.
           // Branch nodes are registered in the manifest by mountBranch,

package/runtime/conditionals.js

@@ -263,18 +263,25 @@ const unmountBranch = (node, manifest) => {
     }
   }
 
-  // Collect componentIds from the subtree BEFORE detaching so we can check
+  // The conditional owns everything between its comments. That's more than
+  // activeInstance.nodes: nested directives at the branch's top level (each
+  // rows, deeper if branches) insert their rendered output between their own
+  // comments after the branch mounts, so it never appears in the original
+  // clonedNodes list. Sweep the live range (same pattern as iteration
+  // teardown), collecting componentIds BEFORE detaching so we can check
   // after removal whether any live DOM still holds them.
+  const { startComment, endComment } = node.meta;
   const ids = new Set();
-  activeInstance.nodes.forEach((domNode) => collectComponentIds(domNode, ids));
-
-  // Remove all nodes from DOM and deregister from branch registry
-  activeInstance.nodes.forEach((domNode) => {
-    branchNodeRegistry.delete(domNode);
-    if (domNode.parentNode) {
-      domNode.parentNode.removeChild(domNode);
+  let current = startComment.nextSibling;
+  while (current && current !== endComment) {
+    const next = current.nextSibling;
+    collectComponentIds(current, ids);
+    branchNodeRegistry.delete(current);
+    if (current.parentNode) {
+      current.parentNode.removeChild(current);
     }
-  });
+    current = next;
+  }
 
   // CLEANUP OF CURRENT STATE
   releaseOrphanedComponentState(ids);

package/runtime/constants.js

@@ -15,7 +15,8 @@ export const PHASE_PARSE = 'Parsed'; // Reads DOM structure (parse.js)
 export const PHASE_HYDRATE = 'Hydrated'; // Replaces @[...] with values (hydrate.js)
 export const PHASE_ITERATE = 'Iterated'; // Renders <!-- each --> blocks (iterate.js)
 export const PHASE_CONDITION = 'Evaluated'; // Renders <!-- if --> blocks (conditionals.js)
-export const PHASE_FETCH = 'Fetched'; // Loads <component> content (component.js)
+export const PHASE_FETCH = 'Fetched'; // Loads <component> content over the network (component.js)
+export const PHASE_FETCH_CACHED = 'Fet(ca)ched'; // Loads <component> content from the runtime template cache — a Fetch served from memory (component.js)
 export const PHASE_UPDATE = 'Proxy'; // State changes trigger re-hydration (index.js)
 export const PHASE_MUTATE = 'Mutation'; // DOM mutations detected by observer (index.js)
 export const PHASE_HYPERSPEED = 'Hyperspeed'; // Restores @[...] markers from pre-compiled manifest (pre-compiled-manifest.js)

package/runtime/debug.js

@@ -12,6 +12,7 @@ const PHASE_COLORS = {
   Iterated: 'oklch(0.58 0.11 142)', // comment green (baseline)
   Evaluated: 'oklch(0.58 0.11 142)', // comment green (baseline)
   Fetched: 'oklch(0.59 0.12 307)', // muted purple
+  'Fet(ca)ched': 'oklch(0.59 0.12 307)', // same muted purple — a Fetch served from the runtime cache
   Mutation: 'oklch(0.60 0.11 240)', // muted blue
   Proxy: 'oklch(0.60 0.11 240)', // muted blue
   Hyperspeed: 'oklch(0.60 0.11 180)', // muted cyan
@@ -39,7 +40,7 @@ const COLORS = {
 export const debugLog = (phase, message, debug = false, indent = 0, element = null) => {
   if (!debug) return;
 
-  const phaseBracket = `[${phase}] `.padEnd(13, ' '); // Pad to 13 chars (longest is "[Manifested] ")
+  const phaseBracket = `[${phase}] `.padEnd(14, ' '); // Pad to 14 chars (longest is "[Fet(ca)ched] ")
   const indentStr = indent > 0 ? '  '.repeat(indent) + '├─ ' : '';
   const phaseColor = PHASE_COLORS[phase] || 'oklch(0.55 0.02 250)';
 

package/runtime/hydrate.js

@@ -92,9 +92,18 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           const expr = isPureBinding[1];
           const value = evalInScope(expr, effectiveState, element);
           if (element[attrName] !== value) element[attrName] = value;
-          if (value !== undefined && value !== null) {
-            const str = String(value);
-            if (element.getAttribute(attrName) !== str) element.setAttribute(attrName, str);
+          if (attrName === 'value') {
+            if (value !== undefined && value !== null) {
+              const str = String(value);
+              if (element.getAttribute(attrName) !== str) element.setAttribute(attrName, str);
+            }
+          } else if (value) {
+            // checked/selected are boolean — the truthful attribute form is
+            // presence (empty) when truthy, absence when falsy. Stringifying
+            // would leave checked="false", which is "checked" to CSS and HTML.
+            if (element.getAttribute(attrName) !== '') element.setAttribute(attrName, '');
+          } else if (element.hasAttribute(attrName)) {
+            element.removeAttribute(attrName);
           }
         } else if (!isValueAttr && isPureBinding) {
           // Boolean-like attributes: add or remove based on truthiness.

package/runtime/index.js

@@ -23,7 +23,8 @@ import {
   PHASE_READY,
   DEHYDRATE_CLASS_OR_ATTR,
 } from './constants.js';
-import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate } from './component.js';
+import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate, executeCompiledComponentScripts } from './component.js';
+import { configureComponentCache, clearComponentCache } from './component-cache.js';
 import { debugLog } from './debug.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
 import { reconcile } from './reconcile.js';
@@ -331,6 +332,9 @@ const main = (s, config = {}, stringSelector = '') => {
   const verbose = !!config?.verbose;
   globalThis.__vibeDebug = debug;
 
+  // Enable/disable the component template cache from config (`{ noCache }`).
+  configureComponentCache(config);
+
   // Expose the global `$scope` resolver used by loop-scoped `on*` handlers.
   installScopeResolver();
 
@@ -676,6 +680,17 @@ const main = (s, config = {}, stringSelector = '') => {
     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
@@ -706,6 +721,18 @@ const main = (s, config = {}, stringSelector = '') => {
   // 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);
@@ -1125,7 +1152,7 @@ const main = (s, config = {}, stringSelector = '') => {
 
   // Check if cleanup should run
   const checkCleanup = () => {
-    if (cleanupExecuted || isCompiling) return;
+    if (cleanupExecuted || isCompiling || !compiledScriptsDone) return;
 
     // Check for pending mutations first
     const pendingMutations = observer ? observer.takeRecords() : [];
@@ -1157,6 +1184,15 @@ const main = (s, config = {}, stringSelector = '') => {
   // 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;
+      checkCleanup();
+    });
+  }
+
   // Process component elements after initialization - MutationObserver will handle hydration
   componentProcessingStarted = true;