@ape-egg/vibe 1.2.0 → 1.3.0

package/runtime/cleanup.js

@@ -1,5 +1,5 @@
 import { debugLog } from './debug.js';
-import { PHASE_COMPLETE } from './constants.js';
+import { PHASE_READY, FOUC_CLASS_OR_ATTR } from './constants.js';
 
 /**
  * Check if all Vibe processing is complete and cleanup can run
@@ -7,30 +7,27 @@ import { PHASE_COMPLETE } from './constants.js';
  * @returns {Boolean} - true if cleanup should run
  */
 export const shouldCleanup = (rootElement) => {
-  // 1. Check for pending <component> elements
-  const componentElements = rootElement.querySelectorAll('component');
+  // 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]');
   if (componentElements.length > 0) {
     return false;
   }
 
   // 2. Check for unhydrated bindings (literal @[...] in DOM, excluding dehydrated elements)
-  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 (parent.hasAttribute('dehydrate')) {
-            return NodeFilter.FILTER_REJECT; // Skip dehydrated content
-          }
-          parent = parent.parentElement;
+  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 (parent.hasAttribute('dehydrate')) {
+          return NodeFilter.FILTER_REJECT; // Skip dehydrated content
         }
-        return NodeFilter.FILTER_ACCEPT;
+        parent = parent.parentElement;
       }
-    }
-  );
+      return NodeFilter.FILTER_ACCEPT;
+    },
+  });
 
   let node;
   while ((node = walker.nextNode())) {
@@ -44,16 +41,40 @@ export const shouldCleanup = (rootElement) => {
 };
 
 /**
- * Perform cleanup - remove vibe attribute to reveal content
+ * Perform cleanup - remove attribute or class from all matching elements
  * @param {Element} rootElement - Root element
- * @param {String} attrName - Attribute name to remove (default: 'vibe')
  * @param {Boolean} debug - Debug mode
  */
-export const cleanup = (rootElement, attrName = 'vibe', debug = false) => {
+export const cleanup = (rootElement, debug = false) => {
   // Force reflow
   rootElement.offsetHeight;
 
-  // Remove vibe attribute
-  debugLog(PHASE_COMPLETE, `removing [${attrName}] attribute`, debug);
-  rootElement.removeAttribute(attrName);
+  // 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`, debug);
+  } else {
+    // Remove attribute from all elements in document that have it
+    const elements = document.querySelectorAll(`[${cleanName}]`);
+    elements.forEach((el) => el.removeAttribute(cleanName));
+    debugLog(
+      PHASE_READY,
+      `removing [${cleanName}] attribute from ${elements.length} elements`,
+      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-state.js

@@ -1,4 +1,4 @@
-// Shared utility for processing component state from <script type="component">
+// Shared utility for processing component state
 
 /**
  * Generate unique component ID

package/runtime/component.js

@@ -20,7 +20,10 @@ export const abortComponentFetch = (element) => {
 
 export const processComponent = (rootElement, onComplete, config = {}) => {
   const debug = !!config?.debug;
-  const componentElements = rootElement.querySelectorAll('component');
+  // Only process component elements with src attribute (fetched components)
+  // Supports: <component src="..."> and <div class="component" src="...">
+  // Ignores: <component> and <div class="component"> (inline component wrappers)
+  const componentElements = rootElement.querySelectorAll('component[src], div.component[src]');
 
   if (componentElements.length === 0) {
     if (onComplete) onComplete();
@@ -31,12 +34,6 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
   const el = componentElements[0];
   const src = el.getAttribute('src');
 
-  if (!src) {
-    el.remove();
-    // Don't recursively call - let MutationObserver handle it
-    return;
-  }
-
   // Capture children and props before fetching
   const children = el.innerHTML.trim();
   const props = {};
@@ -97,10 +94,10 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
         const bindingMatch = propValue.match(/^@\[(.+)\]$/);
 
         if (bindingMatch) {
-          // Reactive prop: replace propName as word boundary
+          // Reactive prop: replace @[propName] with @[path]
           const path = bindingMatch[1];
-          const propPattern = new RegExp(`\\b${escapeRegex(propName)}\\b`, 'g');
-          transformedHtml = transformedHtml.replace(propPattern, path);
+          const propPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
+          transformedHtml = transformedHtml.replace(propPattern, `@[${path}]`);
         } else {
           // Static prop: replace @[propName] with literal value
           const propPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
@@ -117,14 +114,24 @@ export const processComponent = (rootElement, onComplete, config = {}) => {
       // Clean up pending fetch tracker
       pendingFetches.delete(el);
 
-      // Set outerHTML - this triggers MutationObserver
+      // 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) {
-        el.outerHTML = transformedHtml;
+        // Create clean wrapper element (preserve tag type: component or div.component)
+        const newWrapper = el.tagName === 'DIV'
+          ? document.createElement('div')
+          : document.createElement('component');
+
+        if (el.tagName === 'DIV') {
+          newWrapper.className = 'component';
+        }
+
+        newWrapper.innerHTML = transformedHtml;
+        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 outerHTML completes
+        // Use microtask to process right after replaceWith completes
         if (config._forceSync && config._processMutations && config._observer) {
           Promise.resolve().then(() => {
             const pending = config._observer.takeRecords();

package/runtime/constants.js

@@ -1,12 +1,13 @@
 // Debug logger name
 export const DEBUGGER_NAME = '[vibe-debug]:';
+export const FOUC_CLASS_OR_ATTR = 'vibe-fouc'; // Class or attribute used to prevent FOUC (default: [vibe])
 
 // Lifecycle phase names for debug logging
 // ONE-OFF operations (run once during initialization)
 export const PHASE_ATTACH = 'Attached'; // Latches onto DOM element (index.js)
 export const PHASE_MANIFEST = 'Manifested'; // Creates DOM manifest (manifest.js)
 export const PHASE_OBSERVE = 'Observer'; // Starts MutationObserver (index.js)
-export const PHASE_COMPLETE = 'Cleanup'; // Removes [vibe] attribute (index.js)
+export const PHASE_READY = 'Ready'; // Removes [vibe-fouc] attribute (or .vibe-fouc class) and dispatches vibe:ready event (cleanup.js)
 
 // REPEATED operations (run during init + can repeat during runtime)
 export const PHASE_PARSE = 'Parsed'; // Reads DOM structure (parse.js)
@@ -16,9 +17,12 @@ export const PHASE_CONDITION = 'Evaluated'; // Renders <!-- if --> blocks (condi
 export const PHASE_FETCH = 'Fetched'; // Loads <component> content (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 (hyperspeed.js)
 
 // Elements that should not have reactive bindings
-export const NON_REACTIVE_ELEMENTS = ['SCRIPT', 'HEAD', 'PRE', 'COMPONENT'];
+// Note: COMPONENT is NOT in this list - inline component wrappers need to be parsed
+// Fetched components (<component src="">) are handled separately by processComponent()
+export const NON_REACTIVE_ELEMENTS = ['SCRIPT', 'HEAD', 'PRE'];
 
 // Attributes where the string value is meaningful (should NOT be removed when falsy)
 // All other attributes are treated as boolean-like (removed when falsy, present when truthy)
@@ -159,14 +163,41 @@ export const DOM_PROPERTIES = ['value', 'checked', 'selected'];
 // DOM element properties that should NOT be rewritten in event handlers
 // When parsing onclick="this.value = this.inputValue", preserve this.value (DOM) but rewrite this.inputValue (component state)
 export const DOM_ELEMENT_PROPERTIES = new Set([
-  'value', 'checked', 'selected', 'disabled', 'readOnly', 'files',
-  'tagName', 'nodeName', 'nodeType', 'classList', 'className', 'id',
-  'innerHTML', 'outerHTML', 'textContent', 'innerText',
-  'parentElement', 'parentNode', 'nextSibling', 'previousSibling',
-  'firstChild', 'lastChild', 'children', 'childNodes',
-  'offsetWidth', 'offsetHeight', 'clientWidth', 'clientHeight',
-  'scrollTop', 'scrollLeft', 'scrollWidth', 'scrollHeight',
-  'style', 'dataset', 'attributes'
+  'value',
+  'checked',
+  'selected',
+  'disabled',
+  'readOnly',
+  'files',
+  'tagName',
+  'nodeName',
+  'nodeType',
+  'classList',
+  'className',
+  'id',
+  'innerHTML',
+  'outerHTML',
+  'textContent',
+  'innerText',
+  'parentElement',
+  'parentNode',
+  'nextSibling',
+  'previousSibling',
+  'firstChild',
+  'lastChild',
+  'children',
+  'childNodes',
+  'offsetWidth',
+  'offsetHeight',
+  'clientWidth',
+  'clientHeight',
+  'scrollTop',
+  'scrollLeft',
+  'scrollWidth',
+  'scrollHeight',
+  'style',
+  'dataset',
+  'attributes',
 ]);
 
 // Regex for matching reactive bindings (@[expression])

package/runtime/debug.js

@@ -14,6 +14,7 @@ const PHASE_COLORS = {
   Fetched: 'oklch(0.59 0.12 307)', // muted purple
   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
 };
 
 // Special colors for styled segments (Tailwind 500)

package/runtime/hydrate.js

@@ -82,10 +82,15 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           attrName.startsWith('on');
 
         if (isDomProperty && isPureBinding) {
-          // For DOM properties like value, set the property directly
+          // For DOM properties (value, checked, selected), set BOTH property AND attribute
+          // Property: Fast runtime updates, what the user sees
+          // Attribute: Truthful DOM representation, enables compiler snapshots via outerHTML
           const expr = isPureBinding[1];
           const value = evalInScope(expr, effectiveState, element);
           element[attrName] = value;
+          if (value !== undefined && value !== null) {
+            element.setAttribute(attrName, String(value));
+          }
         } else if (!isValueAttr && isPureBinding) {
           // Boolean-like attributes: add or remove based on truthiness
           const expr = isPureBinding[1];