@ape-egg/vibe 1.6.1 → 1.7.1

package/compiler/src/parser/html.rs

@@ -71,6 +71,21 @@ impl HtmlParser {
         Ok(())
     }
 
+    /// Reload a single element from disk (when the file changes in watch mode)
+    pub fn reload_element(&mut self, path: &Path) -> Result<(), ParseError> {
+        if path.extension().map_or(false, |ext| ext == "html") {
+            if let Some(tag_name) = path.file_stem().and_then(|s| s.to_str()) {
+                let content = fs::read_to_string(path).map_err(|e| ParseError::ReadError {
+                    path: path.display().to_string(),
+                    source: e,
+                })?;
+                let element = Element::new(tag_name.to_string(), path.to_path_buf(), content);
+                self.cache.insert(tag_name.to_string(), element);
+            }
+        }
+        Ok(())
+    }
+
     /// Get an element by tag name
     pub fn _get_element(&self, tag_name: &str) -> Option<&Element> {
         self.cache.get(tag_name)
@@ -115,8 +130,20 @@ impl HtmlParser {
 
         // Step 2: Handle explicit <component src="..."> elements
         // If components_as_is is false, recursively inline all <component> elements
+        // Keep running until no more components are found (handles nested components in slots)
         if !components_as_is {
-            result = self.inline_component_elements(&result, external_cache);
+            let mut iterations = 0;
+            let max_iterations = 50; // Prevent infinite loops
+            loop {
+                let before = result.clone();
+                result = self.inline_component_elements(&result, external_cache);
+                iterations += 1;
+
+                // Stop if no changes or max iterations reached
+                if result == before || iterations >= max_iterations {
+                    break;
+                }
+            }
 
             // NOTE: Don't run inline_custom_elements again here - it causes infinite recursion
             // Custom elements inside components are already processed when the component was cached
@@ -228,6 +255,65 @@ impl HtmlParser {
     /// Recursively inline all <component> elements with their HTML content
     /// Inline a single component (one pass, no looping)
     /// Used during recursive component fetching to resolve nested components
+    /// Find the start position of the matching close tag, handling nesting of the same tag.
+    /// `after_open`: byte position immediately after the `>` of the opening tag.
+    fn find_matching_close(content: &str, after_open: usize, tag_name: &str) -> Option<usize> {
+        // \b ensures <component> matches but not <component-foo>
+        let open_re = regex::Regex::new(&format!(r"<{}\b", regex::escape(tag_name))).unwrap();
+        let close_re = regex::Regex::new(&format!(r"</{}>", regex::escape(tag_name))).unwrap();
+
+        let mut depth = 1i32;
+        let mut cursor = after_open;
+
+        while cursor < content.len() {
+            let slice = &content[cursor..];
+            let next_open = open_re.find(slice).map(|m| (m.start(), m.end()));
+            let next_close = close_re.find(slice).map(|m| (m.start(), m.end()));
+
+            match (next_open, next_close) {
+                (None, None) => return None,
+                (None, Some((cs, ce))) => {
+                    depth -= 1;
+                    if depth == 0 { return Some(cursor + cs); }
+                    cursor += ce;
+                }
+                (Some((os, oe)), None) => {
+                    // Check if self-closing by finding the end of this tag
+                    if let Some(end) = slice[os..].find('>') {
+                        if slice[os..os + end + 1].ends_with("/>") {
+                            cursor += os + end + 1;
+                        } else {
+                            depth += 1;
+                            cursor += oe;
+                        }
+                    } else {
+                        return None;
+                    }
+                }
+                (Some((os, oe)), Some((cs, ce))) => {
+                    if os < cs {
+                        if let Some(end) = slice[os..].find('>') {
+                            if slice[os..os + end + 1].ends_with("/>") {
+                                cursor += os + end + 1;
+                            } else {
+                                depth += 1;
+                                cursor += oe;
+                            }
+                        } else {
+                            return None;
+                        }
+                    } else {
+                        depth -= 1;
+                        if depth == 0 { return Some(cursor + cs); }
+                        cursor += ce;
+                    }
+                }
+            }
+        }
+
+        None
+    }
+
     pub fn inline_single_component(&self, content: &str, component_src: &str, component_content: &str) -> String {
         let mut result = content.to_string();
 
@@ -243,55 +329,53 @@ impl HtmlParser {
             }
         };
 
-        // Match <component src="..." attrs...>children</component>
-        // OR <div class="component" src="..." attrs...>children</div>
-        let pattern = format!(r#"(?s)<(component|div)\s+([^>]*)\bsrc="{}"\s*([^>]*)>(.*?)</(component|div)>"#, regex::escape(&normalized_src));
-        let component_re = regex::Regex::new(&pattern).unwrap();
+        // Match only the opening tag — slot content is extracted via depth-counting close search
+        // to correctly handle slot content that contains </div> or nested <component> elements.
+        let pattern = format!(r#"<(component|div)\s+([^>]*)\bsrc="{}"\s*([^>]*)>"#, regex::escape(&normalized_src));
+        let open_re = regex::Regex::new(&pattern).unwrap();
 
-        let matches: Vec<_> = component_re.captures_iter(&result).map(|cap| {
-            let full_match = cap.get(0).unwrap();
+        let matches: Vec<_> = open_re.captures_iter(&result).filter_map(|cap| {
+            let open_tag = cap.get(0).unwrap();
             let tag_name = cap.get(1).unwrap().as_str();
             let attrs_before = cap.get(2).map(|m| m.as_str()).unwrap_or("");
             let attrs_after = cap.get(3).map(|m| m.as_str()).unwrap_or("");
-            let slot_content = cap.get(4).map(|m| m.as_str().to_string());
 
             // For <div>, verify it has class="component"
             if tag_name == "div" {
                 let combined_attrs = format!("{} {}", attrs_before, attrs_after);
                 if !combined_attrs.contains("class=") || !combined_attrs.contains("component") {
-                    return None; // Not a component div, skip
+                    return None;
                 }
             }
 
-            // Combine all attributes
+            let open_end = open_tag.end();
+            let close_start = Self::find_matching_close(&result, open_end, tag_name)?;
+            let close_end = close_start + format!("</{}>", tag_name).len();
+            let slot_content = result[open_end..close_start].to_string();
+
             let attrs_str = format!("{} {}", attrs_before, attrs_after);
             let props = Self::parse_props(&attrs_str);
 
-            Some((full_match.start(), full_match.end(), props, slot_content))
-        }).flatten().collect();
+            Some((open_tag.start(), close_end, props, slot_content))
+        }).collect();
+
+        // Replace from end to start (sorted descending by start position)
+        let mut sorted = matches;
+        sorted.sort_by(|a, b| b.0.cmp(&a.0));
 
-        // Replace from end to start
-        for (start, end, props, slot_content) in matches.iter().rev() {
+        for (start, end, props, slot_content) in &sorted {
             let mut replacement = component_content.to_string();
 
-            // Replace props
             for (prop_name, prop_value) in props {
                 let prop_binding = format!("@[{}]", prop_name);
                 replacement = replacement.replace(&prop_binding, prop_value);
             }
 
-            // Replace slots
-            let slot_replacement = slot_content
-                .as_ref()
-                .filter(|s| !s.trim().is_empty())
-                .map(|s| s.as_str())
-                .unwrap_or("");
-
+            let slot_replacement = if slot_content.trim().is_empty() { "" } else { slot_content.as_str() };
             replacement = replacement.replace("<slot></slot>", slot_replacement);
             replacement = replacement.replace("<slot/>", slot_replacement);
             replacement = replacement.replace("<slot />", slot_replacement);
 
-            // Keep the <component> wrapper
             let wrapper = format!("<component>{}</component>", replacement);
             result.replace_range(*start..*end, &wrapper);
         }
@@ -302,73 +386,81 @@ impl HtmlParser {
     fn inline_component_elements(&self, content: &str, external_cache: &HashMap<String, String>) -> String {
         let mut result = content.to_string();
 
-        // Single pass - all components in cache are already fully resolved
-        // Match <component src="..." attrs...>children</component>
-        // OR <div class="component" src="..." attrs...>children</div> (after accessibility transformation)
-        // Both signatures require src attribute (wrappers without src are already processed)
-        let component_re = regex::Regex::new(
-            r#"(?s)<(component|div)\s+([^>]*)\bsrc="([^"]+)"([^>]*)>(.*?)</(component|div)>"#
+        // Match only the opening component tag — slot content is extracted via depth-counting
+        // to correctly handle slot content containing </div> or nested <component> elements.
+        let open_re = regex::Regex::new(
+            r#"<(component|div)\s+([^>]*)\bsrc="([^"]+)"([^>]*)>"#
         ).unwrap();
 
-        let matches: Vec<_> = component_re.captures_iter(&result).map(|cap| {
-            let full_match = cap.get(0).unwrap();
-            let tag_name = cap.get(1).unwrap().as_str();
-            let attrs_before = cap.get(2).map(|m| m.as_str()).unwrap_or("");
-            let src = cap.get(3).unwrap().as_str();
-            let attrs_after = cap.get(4).map(|m| m.as_str()).unwrap_or("");
-            let slot_content = cap.get(5).map(|m| m.as_str().to_string());
-
-            // For <div>, verify it has class="component" (or class="component other-classes")
-            if tag_name == "div" {
-                let combined_attrs = format!("{} {}", attrs_before, attrs_after);
-                if !combined_attrs.contains("class=") || !combined_attrs.contains("component") {
-                    return None; // Not a component div, skip
+        // Process one match at a time with re-scanning after each replacement.
+        // This is required for nested components (e.g. Layout.html wrapping inner components):
+        // collecting all byte positions at once and applying them in reverse fails because
+        // replacing an inner component changes the string length, invalidating the outer
+        // component's end byte position and causing a char boundary panic.
+        loop {
+            let matches: Vec<_> = open_re.captures_iter(&result).filter_map(|cap| {
+                let open_tag = cap.get(0).unwrap();
+                let tag_name = cap.get(1).unwrap().as_str();
+                let attrs_before = cap.get(2).map(|m| m.as_str()).unwrap_or("");
+                let src = cap.get(3).unwrap().as_str();
+                let attrs_after = cap.get(4).map(|m| m.as_str()).unwrap_or("");
+
+                // For <div>, verify it has class="component"
+                if tag_name == "div" {
+                    let combined_attrs = format!("{} {}", attrs_before, attrs_after);
+                    if !combined_attrs.contains("class=") || !combined_attrs.contains("component") {
+                        return None;
+                    }
                 }
-            }
 
-            // Combine all attributes (excluding src which we already extracted)
-            let attrs_str = format!("{} {}", attrs_before, attrs_after);
-            let props = Self::parse_props(&attrs_str);
+                let open_end = open_tag.end();
+                let close_start = Self::find_matching_close(&result, open_end, tag_name)?;
+                let close_end = close_start + format!("</{}>", tag_name).len();
+                let slot_content = result[open_end..close_start].to_string();
 
-            Some((full_match.start(), full_match.end(), src.to_string(), props, slot_content))
-        }).flatten().collect();
+                let attrs_str = format!("{} {}", attrs_before, attrs_after);
+                let props = Self::parse_props(&attrs_str);
 
-        // Replace from end to start
-        for (start, end, src, props, slot_content) in matches.iter().rev() {
-            // Normalize path
-            let normalized_src = if src.starts_with("http://") || src.starts_with("https://") {
-                src.to_string()
-            } else {
-                let without_prefix = src.trim_start_matches("./");
-                if without_prefix.starts_with('/') {
-                    without_prefix.to_string()
+                Some((open_tag.start(), close_end, src.to_string(), props, slot_content))
+            }).collect();
+
+            // Pick the rightmost match that has a cached component and apply it, then re-scan.
+            let mut sorted = matches;
+            sorted.sort_by(|a, b| b.0.cmp(&a.0));
+
+            let mut applied = false;
+            for (start, end, src, props, slot_content) in sorted {
+                let normalized_src = if src.starts_with("http://") || src.starts_with("https://") {
+                    src.to_string()
                 } else {
-                    format!("/{}", without_prefix)
-                }
-            };
-
-            // Get fully resolved component from cache
-            if let Some(mut replacement) = external_cache.get(&normalized_src).cloned() {
-                // Replace props
-                for (prop_name, prop_value) in props {
-                    let prop_binding = format!("@[{}]", prop_name);
-                    replacement = replacement.replace(&prop_binding, prop_value);
-                }
+                    let without_prefix = src.trim_start_matches("./");
+                    if without_prefix.starts_with('/') {
+                        without_prefix.to_string()
+                    } else {
+                        format!("/{}", without_prefix)
+                    }
+                };
 
-                // Replace slots
-                let slot_replacement = slot_content
-                    .as_ref()
-                    .filter(|s| !s.trim().is_empty())
-                    .map(|s| s.as_str())
-                    .unwrap_or("");
+                if let Some(mut replacement) = external_cache.get(&normalized_src).cloned() {
+                    for (prop_name, prop_value) in &props {
+                        let prop_binding = format!("@[{}]", prop_name);
+                        replacement = replacement.replace(&prop_binding, prop_value);
+                    }
 
-                replacement = replacement.replace("<slot></slot>", slot_replacement);
-                replacement = replacement.replace("<slot/>", slot_replacement);
-                replacement = replacement.replace("<slot />", slot_replacement);
+                    let slot_replacement = if slot_content.trim().is_empty() { "" } else { slot_content.as_str() };
+                    replacement = replacement.replace("<slot></slot>", slot_replacement);
+                    replacement = replacement.replace("<slot/>", slot_replacement);
+                    replacement = replacement.replace("<slot />", slot_replacement);
+
+                    let wrapper = format!("<component>{}</component>", replacement);
+                    result.replace_range(start..end, &wrapper);
+                    applied = true;
+                    break;
+                }
+            }
 
-                // Keep the <component> wrapper
-                let wrapper = format!("<component>{}</component>", replacement);
-                result.replace_range(*start..*end, &wrapper);
+            if !applied {
+                break;
             }
         }
 
@@ -440,16 +532,41 @@ fn transform_custom_tags_to_divs(content: &str, reserved_elements: &[String]) ->
         }
     }
 
+    // Sort by descending length so more specific tags (e.g. "accordion-content")
+    // are processed before shorter prefixes (e.g. "accordion"), preventing
+    // partial tag-name matches like <accordion([^>]*)> matching <accordion-content>
+    custom_tags.sort_by(|a, b| b.len().cmp(&a.len()));
+
+    // Pre-compile class attribute regex for merging existing class values
+    let class_attr_re = regex::Regex::new(r#"\bclass="([^"]*)""#).unwrap();
+
     // Transform each custom tag
-    for tag in custom_tags {
-        // Opening tag: <custom-tag attrs> -> <div class="custom-tag" attrs>
-        let open_re = regex::Regex::new(&format!(r"<{}([^>]*)>", regex::escape(&tag))).unwrap();
-        result = open_re
-            .replace_all(&result, format!("<div class=\"{}\"$1>", tag).as_str())
-            .to_string();
+    for tag in &custom_tags {
+        // Opening tag: require whitespace or end-of-tag after the tag name so that
+        // <accordion> does not accidentally match <accordion-content>
+        let open_re = regex::Regex::new(
+            &format!(r"<{}([\s][^>]*|)>", regex::escape(tag))
+        ).unwrap();
+
+        result = open_re.replace_all(&result, |caps: &regex::Captures| -> String {
+            let attrs = caps.get(1).map(|m| m.as_str()).unwrap_or("");
+
+            // If the element already has class="...", merge tag name with existing value
+            if let Some(class_cap) = class_attr_re.captures(attrs) {
+                let existing = class_cap.get(1).unwrap().as_str();
+                let merged = format!("{} {}", tag, existing);
+                let new_attrs = class_attr_re.replace(
+                    attrs,
+                    format!(r#"class="{}""#, merged.trim()).as_str(),
+                );
+                format!("<div{}>", new_attrs)
+            } else {
+                format!("<div class=\"{}\"{}>", tag, attrs)
+            }
+        }).to_string();
 
         // Closing tag: </custom-tag> -> </div>
-        let close_re = regex::Regex::new(&format!(r"</{}>", regex::escape(&tag))).unwrap();
+        let close_re = regex::Regex::new(&format!(r"</{}>", regex::escape(tag))).unwrap();
         result = close_re.replace_all(&result, "</div>").to_string();
     }
 

package/index.js

@@ -1,15 +1,41 @@
 // Universal entry point for Vibe
 // Usage: import vibe from 'vibe/index.js'; vibe({ initialState }, { debug: true }, 'body');
 
-import { ensureBoot, boot, isBooted } from './boot.js';
+import { boot, isBooted, ensureBoot } from './boot.js';
+
+// Shared instance for queueing listeners before boot
+let vibeInstance = null;
+
+const createVibeInstance = () => ({
+  _pendingListeners: { afterUpdate: [], afterDomMutation: [], ready: [] },
+  on(event, callback) {
+    // If booted, delegate to window.$
+    if (isBooted() && window.$) {
+      return window.$.on(event, callback);
+    }
+
+    // Otherwise queue for later
+    if (this._pendingListeners[event]) {
+      this._pendingListeners[event].push(callback);
+    }
+    return () => {
+      this._pendingListeners[event] = this._pendingListeners[event].filter(cb => cb !== callback);
+    };
+  }
+});
 
 const vibe = (state = {}, config, targetSelector) => {
   if (isBooted()) {
-    // Already booted - mutate live state
+    // Already booted - merge state into live proxy
     Object.assign(window.$, state);
     return window.$;
   }
 
+  // Create shared instance on first call
+  if (!vibeInstance) {
+    vibeInstance = createVibeInstance();
+  }
+
   // Not booted yet - accumulate in global state registry
   if (!window.__vibeGlobalState) {
     window.__vibeGlobalState = {};
@@ -26,15 +52,18 @@ const vibe = (state = {}, config, targetSelector) => {
     window.__vibeTargetSelector = targetSelector;
   }
 
-  // Explicit boot call (no state passed means "boot now")
+  // Explicit boot call (no state passed means "boot now with accumulated state")
   if (Object.keys(state).length === 0 && Object.keys(window.__vibeGlobalState).length > 0) {
     return boot();
   }
 
-  // Ensure boot happens in microtask
+  // Queue boot in microtask to allow all component scripts to register
   ensureBoot();
 
-  return null;
+  return vibeInstance;
 };
 
+// Export function to get pending listeners (used by boot.js)
+export const getPendingListeners = () => vibeInstance?._pendingListeners || null;
+
 export default vibe;

package/llms.txt

@@ -129,7 +129,7 @@ Conditionals can be nested inside iterations and vice versa.
 Skip reactive processing for an element and its children:
 
 ```html
-<code dehydrate>@[this] displays literally, not parsed</code>
+<code vibe-dehydrate>@[this] displays literally, not parsed</code>
 ```
 
 Use cases:

package/package.json

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

package/runtime/cleanup.js

@@ -68,13 +68,4 @@ export const cleanup = (rootElement, debug = false) => {
       debug,
     );
   }
-
-  // Dispatch ready event to signal that Vibe has completed all initial processing
-  if (typeof document !== 'undefined') {
-    document.dispatchEvent(
-      new CustomEvent('vibe:ready', {
-        detail: { rootElement, cleanName, isClass },
-      }),
-    );
-  }
 };

package/runtime/component.js

@@ -36,7 +36,9 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
   const componentElements = rootElement.querySelectorAll('component[src], div.component[src]');
 
   if (componentElements.length === 0) {
-    if (onComplete) onComplete();
+    // Defer onComplete to give user code a chance to register listeners
+    // This is important when all components are pre-compiled (no src attributes)
+    if (onComplete) queueMicrotask(() => onComplete());
     return;
   }
 
@@ -50,15 +52,18 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
       // Process next component
       processComponent(rootElement, onComplete, config);
     } else {
-      if (onComplete) onComplete();
+      // Defer onComplete to give user code a chance to register listeners
+      if (onComplete) queueMicrotask(() => onComplete());
     }
     return;
   }
 
   const src = el.getAttribute('src');
 
-  // Capture children and props before fetching
-  const children = el.innerHTML.trim();
+  // Use pre-hydration slot content if available (saved by index.js before hydration ran),
+  // otherwise fall back to current innerHTML (e.g. runtime-only usage without boot).
+  const children = (el._vibeSlotContent !== undefined ? el._vibeSlotContent : el.innerHTML).trim();
+  delete el._vibeSlotContent;
   const props = {};
   Array.from(el.attributes).forEach((attr) => {
     if (attr.name !== 'src') {
@@ -131,21 +136,21 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
           const thisRegex = /@\[this\.(\w+)\]/g;
 
           // Rewrite in text nodes
-          Array.from(element.childNodes).forEach(node => {
+          Array.from(element.childNodes).forEach((node) => {
             if (node.nodeType === Node.TEXT_NODE && node.textContent.includes('@[this.')) {
               node.textContent = node.textContent.replace(thisRegex, `@[${componentId}.$1]`);
             }
           });
 
           // Rewrite in attributes
-          Array.from(element.attributes || []).forEach(attr => {
+          Array.from(element.attributes || []).forEach((attr) => {
             if (attr.value.includes('@[this.')) {
               attr.value = attr.value.replace(thisRegex, `@[${componentId}.$1]`);
             }
           });
 
           // Recurse into children
-          Array.from(element.children).forEach(child => {
+          Array.from(element.children).forEach((child) => {
             rewriteThisBindings(child);
           });
         };
@@ -195,9 +200,10 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
       // 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'
-          ? document.createElement('div')
-          : document.createElement('component');
+        const newWrapper =
+          el.tagName === 'DIV'
+            ? document.createElement('div')
+            : document.createElement('component');
 
         if (el.tagName === 'DIV') {
           newWrapper.className = 'component';
@@ -207,16 +213,8 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
         el.replaceWith(newWrapper);
         debugLog(PHASE_FETCH, src, debug);
 
-        // Force immediate processing of the mutation (MutationObserver is async, but we need sync)
-        // Use microtask to process right after replaceWith completes
-        if (config._forceSync && config._processMutations && config._observer) {
-          Promise.resolve().then(() => {
-            const pending = config._observer.takeRecords();
-            if (pending.length > 0) {
-              config._processMutations(pending);
-            }
-          });
-        }
+        // Let MutationObserver handle the mutation naturally
+        // It will call processMutations, which will call processComponent for the next component
       }
     })
     .catch((error) => {

package/runtime/index.js

@@ -18,6 +18,7 @@ import {
   PHASE_UPDATE,
   PHASE_MUTATE,
   PHASE_HYPERSPEED,
+  PHASE_READY,
   DEHYDRATE_CLASS_OR_ATTR,
 } from './constants.js';
 import { processComponent, abortComponentFetch } from './component.js';
@@ -70,12 +71,12 @@ const shouldProcessNode = (node) => {
 // Navigate tree using dot notation (handles .children at each level)
 const navigateTree = (tree, path) => {
   if (!path) return tree;
-  return path.split('.').reduce((node, key) => node?.children?.[key], tree);
+  return path.split('.').filter(k => k).reduce((node, key) => node?.children?.[key], tree);
 };
 
 // Get or create a node in the tree at the given path
 const ensureNode = (tree, path) => {
-  const keys = path.split('.');
+  const keys = path.split('.').filter(k => k);
   return keys.reduce((node, key) => {
     if (!node.children[key]) {
       node.children[key] = { children: {} };
@@ -453,6 +454,13 @@ const main = (s, config = {}, stringSelector = '') => {
     restoreMarkersFromManifest(rootElement, cloneForRestoration, hyperspeedTree);
   }
 
+  // Save raw slot content of fetched components before hydration replaces @[...] markers.
+  // component.js captures el.innerHTML when resolving — if hydration already ran, the
+  // binding syntax is gone and the resolved component won't be reactive.
+  rootElement.querySelectorAll('component[src], div.component[src]').forEach(el => {
+    el._vibeSlotContent = el.innerHTML;
+  });
+
   // Runtime parses DOM (which now has restored markers if hyperspeed was used)
   let parsedTree = parse(rootElement);
 
@@ -497,6 +505,7 @@ const main = (s, config = {}, stringSelector = '') => {
   const hooks = {
     afterUpdate: [],
     afterDomMutation: [],
+    ready: [],
   };
 
   // Extract plain values from proxy (removes proxy wrappers)
@@ -950,6 +959,15 @@ const main = (s, config = {}, stringSelector = '') => {
     if (shouldCleanup(rootElement)) {
       cleanup(rootElement, debug);
       cleanupExecuted = true;
+
+      // Fire ready hook after cleanup completes
+      hooks.ready.forEach((callback) => {
+        try {
+          callback();
+        } catch (error) {
+          console.error('[vibe] Error in ready hook:', error);
+        }
+      });
     }
   };