@ape-egg/vibe 1.2.0 → 1.3.0

package/runtime/index.js

@@ -17,12 +17,17 @@ import {
   PHASE_OBSERVE,
   PHASE_UPDATE,
   PHASE_MUTATE,
-  PHASE_COMPLETE,
+  PHASE_HYPERSPEED,
 } from './constants.js';
 import { processComponent, abortComponentFetch } from './component.js';
 import { debugLog } from './debug.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
 import { generateComponentId, executeComponentScript } from './component-state.js';
+import {
+  buildHyperspeedManifest,
+  hyperspeedManifest,
+  restoreMarkersFromManifest,
+} from './hyperspeed.js';
 
 // Wire up cross-module dependency after all modules are loaded
 setRenderAllConditionals(renderAllConditionals);
@@ -132,73 +137,239 @@ const processCoreLoop = (node, parsedNode, state, manifest, isNewNode, debug) =>
   return { hydratedCount, iteratedCount, evaluatedCount };
 };
 
+/**
+ * Deep clone a tree node (to avoid mutating hyperspeed template)
+ */
+const deepCloneNode = (node) => {
+  if (!node || typeof node !== 'object') return node;
+
+  const cloned = { ...node };
+
+  // Clone children recursively
+  if (node.children && typeof node.children === 'object') {
+    cloned.children = {};
+    for (const key in node.children) {
+      cloned.children[key] = deepCloneNode(node.children[key]);
+    }
+  }
+
+  // Clone meta if it exists
+  if (node.meta && typeof node.meta === 'object') {
+    cloned.meta = { ...node.meta };
+    if (node.meta.template) {
+      cloned.meta.template = { ...node.meta.template };
+    }
+    if (node.meta.branches) {
+      cloned.meta.branches = { ...node.meta.branches };
+    }
+  }
+
+  // Clone runtime if it exists
+  if (node.runtime && typeof node.runtime === 'object') {
+    cloned.runtime = { ...node.runtime };
+    if (Array.isArray(node.runtime.instances)) {
+      cloned.runtime.instances = [...node.runtime.instances];
+    }
+  }
+
+  return cloned;
+};
+
+/**
+ * Merge hyperspeed manifest with runtime manifest
+ * Hyperspeed provides structure/metadata, runtime populates DOM references
+ */
+const mergeManifests = (hyperspeedTree, runtimeTree) => {
+  if (!hyperspeedTree) return runtimeTree;
+  if (!runtimeTree) return hyperspeedTree;
+
+  // Start with deep clone of hyperspeed (foundation)
+  const merged = deepCloneNode(hyperspeedTree);
+
+  // Helper to recursively augment hyperspeed with runtime data
+  const augmentWithRuntime = (mergedNode, runtimeNode) => {
+    if (!runtimeNode) return;
+
+    // Populate DOM references from runtime
+    if (runtimeNode.element) {
+      mergedNode.element = runtimeNode.element;
+    }
+
+    // Populate parsed data from runtime
+    if (runtimeNode.parsed) {
+      mergedNode.parsed = runtimeNode.parsed;
+    }
+
+    // For iterations: populate all meta and runtime from runtime
+    if (mergedNode.type === 'iteration' && runtimeNode.type === 'iteration') {
+      // Copy entire meta object from runtime (all properties needed)
+      mergedNode.meta = runtimeNode.meta;
+      // Copy runtime object (instances, etc.)
+      mergedNode.runtime = runtimeNode.runtime;
+    }
+
+    // For conditionals: populate all meta from runtime
+    if (mergedNode.type === 'conditional' && runtimeNode.type === 'conditional') {
+      // Copy entire meta object from runtime (all properties needed)
+      mergedNode.meta = runtimeNode.meta;
+    }
+
+    // Augment children recursively
+    if (runtimeNode.children) {
+      if (!mergedNode.children) mergedNode.children = {};
+
+      for (const key in runtimeNode.children) {
+        const runtimeChild = runtimeNode.children[key];
+
+        // Skip iterations - let runtime control them entirely
+        // Iterations are dynamic and restoration changes DOM structure
+        if (runtimeChild.type === 'iteration') {
+          mergedNode.children[key] = runtimeChild;
+          continue;
+        }
+
+        if (mergedNode.children[key]) {
+          // Child exists in both - augment it
+          augmentWithRuntime(mergedNode.children[key], runtimeNode.children[key]);
+        } else {
+          // Child only in runtime - add it (dynamic element discovered at runtime)
+          mergedNode.children[key] = runtimeNode.children[key];
+        }
+      }
+    }
+  };
+
+  // Augment hyperspeed foundation with runtime data
+  augmentWithRuntime(merged, runtimeTree);
+
+  // Preserve stats from runtime (hyperspeed won't have stats)
+  if (runtimeTree.stats) {
+    merged.stats = runtimeTree.stats;
+  }
+
+  return merged;
+};
+
 // Store previous state for comparison (needs to be accessible by core loop)
 let previousState = {};
 
-const main = (s, attrName = 'vibe', config = {}) => {
+const main = (s, config = {}, stringSelector = '') => {
   const debug = !!config?.debug;
   const verbose = !!config?.verbose;
 
+  // Detect if running in compiler's headless browser
+  // When true: skip cleanup to preserve [vibe] attribute in compiled HTML
+  const isCompiling = typeof window !== 'undefined' && window.__vibeCompiling === true;
+
   // Reset previous state for each new instance
   previousState = {};
 
-  // Find element(s) with the specified attribute
-  const elements = document.querySelectorAll(`[${attrName}]`);
+  // Use page-specific hyperspeed manifest (detected at module load)
+  const hyperspeedTree = hyperspeedManifest;
 
-  if (elements.length === 0) {
-    console.info(`[vibe] No element found with attribute "${attrName}". Falling back to body.`);
-  } else if (elements.length > 1) {
-    console.info(
-      `[vibe] Multiple elements (${elements.length}) found with attribute "${attrName}". Hydrating the first one.`,
-    );
-  }
+  let rootElement = document.body;
 
-  const rootElement = elements[0] || document.body;
+  if (stringSelector) {
+    // Find element(s) with the specified attribute
+    const elements = document.querySelectorAll(`${stringSelector}`);
+    if (elements?.[0]) {
+      rootElement = elements[0];
+    }
+  }
 
-  debugLog(PHASE_ATTACH, `Vibe attached to`, debug, 0, rootElement);
+  debugLog(PHASE_ATTACH, `Vibe attached to`, true, 0, rootElement);
+
+  // Component tagging is now handled by component.js before boot
+  // Component state is merged into s by boot.js
+
+  // RESTORATION PHASE: If hyperspeed detected, restore @[...] markers in DOM
+  // This allows pre-rendered values to be visible (no FOUC) but makes DOM reactive
+  let hyperspeedSubtree = null;
+  if (hyperspeedTree) {
+    debugLog(PHASE_HYPERSPEED, 'Applied pre-compiled vibe-hyperspeed/**/*.manifest.js', debug);
+
+    // Find matching subtree by DOM path (not just tag name)
+    // Build path from document to rootElement
+    const buildDomPath = (element) => {
+      const path = [];
+      let current = element;
+
+      // Walk up to document itself (include html in the path)
+      while (current && current.parentNode && current !== document) {
+        const parent = current.parentNode;
+
+        // Skip document node itself
+        if (parent === document) {
+          const siblings = Array.from(document.childNodes);
+          const index = siblings.indexOf(current);
+          const tag = current.nodeName.toLowerCase();
+          path.unshift({ tag, index });
+          break;
+        }
 
-  // Process inline component scripts FIRST (before parse)
-  // This sets componentIds so parse can rewrite event handlers
-  const componentScripts = rootElement.querySelectorAll('script[type="component"]');
+        const siblings = Array.from(parent.childNodes);
+        const index = siblings.indexOf(current);
+        const tag = current.nodeName.toLowerCase();
 
-  if (componentScripts.length > 0) {
-    componentScripts.forEach((script) => {
-      // Skip if already processed (e.g., by auto.js)
-      if (script.hasAttribute('data-vibe-component-id')) return;
+        path.unshift({ tag, index });
+        current = parent;
+      }
 
-      const scriptContent = script.textContent?.trim() || '';
-      if (!scriptContent) return;
+      return path;
+    };
 
-      const componentId = generateComponentId();
+    // Walk manifest tree following DOM path
+    const findManifestNodeByPath = (manifest, path) => {
+      let current = manifest;
 
-      // Store componentId on script element BEFORE parsing
-      script.setAttribute('data-vibe-component-id', componentId);
+      for (const { tag, index } of path) {
+        if (!current || !current.children) return null;
 
-      // Tag all following sibling elements with this component ID (shallow)
-      // Stop at next component script or end of siblings
-      let sibling = script.nextElementSibling;
-      while (sibling) {
-        // Stop if we hit another component script
-        if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'component') {
-          break;
+        // Look for matching child by tag_index pattern
+        const key = `${tag}_${index}`;
+        if (current.children[key]) {
+          current = current.children[key];
+        } else {
+          // Fallback: search all children for matching tag at this level
+          let found = false;
+          for (const childKey in current.children) {
+            if (childKey.startsWith(tag + '_')) {
+              current = current.children[childKey];
+              found = true;
+              break;
+            }
+          }
+          if (!found) return null;
         }
-        // Tag only the sibling (descendants will use closest() to find it)
-        sibling.setAttribute('data-vibe-component-id', componentId);
-        sibling = sibling.nextElementSibling;
       }
 
-      // Execute component script to get state
-      const componentState = executeComponentScript(scriptContent);
+      return current;
+    };
 
-      // Add component state to initial state
-      s[componentId] = componentState;
-    });
+    const domPath = buildDomPath(rootElement);
+    hyperspeedSubtree = findManifestNodeByPath(hyperspeedTree, domPath);
+
+    if (!hyperspeedSubtree) {
+      // Fallback to root if path matching fails
+      hyperspeedSubtree = hyperspeedTree;
+    }
+
+    restoreMarkersFromManifest(rootElement, hyperspeedSubtree, hyperspeedTree);
   }
 
-  // Now parse (event handlers will be rewritten correctly)
+  // Runtime parses DOM (which now has restored markers if hyperspeed was used)
   let parsedTree = parse(rootElement);
+
+  // Merge with hyperspeed if available (hyperspeed as foundation, runtime augments)
+  if (hyperspeedSubtree) {
+    parsedTree = mergeManifests(hyperspeedSubtree, parsedTree);
+  }
+
   let manifest = createManifest(parsedTree);
 
+  // Build hyperspeed manifest (before hydration, extract markers from parsed strings)
+  const hyperspeedManifestData = buildHyperspeedManifest(parsedTree);
+
   const manifestEntries = Object.entries(manifest);
   const totalCount = manifestEntries.length;
   const elementsOnly = manifestEntries.filter(
@@ -220,7 +391,11 @@ const main = (s, attrName = 'vibe', config = {}) => {
     );
   }
   debugLog(PHASE_PARSE, segments, debug);
-  debugLog(PHASE_MANIFEST, `DOM manifest created`, debug);
+  debugLog(
+    PHASE_MANIFEST,
+    hyperspeedTree ? 'DOM manifest merged with hyperspeed' : 'DOM manifest created',
+    debug,
+  );
 
   // Lifecycle hooks that users can subscribe to
   const hooks = {
@@ -241,9 +416,7 @@ const main = (s, attrName = 'vibe', config = {}) => {
     return plain;
   };
 
-  // Observer reference and callback - defined here so state handler can access processMutations
-  let observer = null;
-  let processMutations = null;
+  // Observer callback will be defined below (already declared above before processComponent)
 
   const $ = state(s, (newState, oldState) => {
     // Extract current state (after mutation)
@@ -350,6 +523,10 @@ const main = (s, attrName = 'vibe', config = {}) => {
   // After all initial rendering, capture a clean snapshot for comparison
   previousState = extractPlainValue($);
 
+  // Observer reference and processMutations
+  let observer = null;
+  let processMutations = null;
+
   // Define observer callback as named function so we can call it manually for pending mutations
   processMutations = (mutations) => {
     // Early exit if no mutations to process (common case)
@@ -436,8 +613,13 @@ const main = (s, attrName = 'vibe', config = {}) => {
           picked.element = target;
         }
 
-        // Parse the newly added node
-        const name = `${node.nodeName.toLowerCase()}_${hash()}`;
+        // Parse the newly added node (use monotonically increasing counter for deterministic key)
+        // Initialize counter if it doesn't exist
+        if (!picked._nextChildIndex) {
+          picked._nextChildIndex = Object.keys(picked.children).length;
+        }
+        const name = `${node.nodeName.toLowerCase()}_${picked._nextChildIndex}`;
+        picked._nextChildIndex++; // Always increment, never decrement
         const parsedNode = parse(node);
 
         // Accumulate skipped stats
@@ -633,7 +815,7 @@ const main = (s, attrName = 'vibe', config = {}) => {
 
   // Check if cleanup should run
   const checkCleanup = () => {
-    if (cleanupExecuted) return;
+    if (cleanupExecuted || isCompiling) return;
 
     // Check for pending mutations first
     const pendingMutations = observer ? observer.takeRecords() : [];
@@ -646,7 +828,7 @@ const main = (s, attrName = 'vibe', config = {}) => {
 
     // Check if all processing is complete
     if (shouldCleanup(rootElement)) {
-      cleanup(rootElement, attrName, debug);
+      cleanup(rootElement, debug);
       cleanupExecuted = true;
     }
   };
@@ -674,6 +856,11 @@ const main = (s, attrName = 'vibe', config = {}) => {
     componentConfig,
   );
 
+  // Export hyperspeed manifest globally for compiler extraction
+  if (typeof window !== 'undefined') {
+    window.__vibeManifest = hyperspeedManifestData;
+  }
+
   return $;
 };
 

package/runtime/iterate.js

@@ -322,8 +322,11 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
   iterationNode.runtime.instances = instances;
 
   // Mark comment as rendered (survives re-parsing since comment nodes persist in DOM)
+  // Also store runtime data on the DOM node so it persists across re-parses
   // @ts-ignore - adding custom property to comment node
   startComment.__vibeRendered = true;
+  // @ts-ignore - adding custom property to comment node
+  startComment.__vibeIterationRuntime = iterationNode.runtime;
 };
 
 // Update an iteration block when array changes

package/runtime/parse.js

@@ -1,4 +1,3 @@
-import { hash } from './utils.js';
 import { findEndComment, findConditionalEnd } from './iteration-utils.js';
 import {
   NON_REACTIVE_ELEMENTS,
@@ -60,9 +59,9 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
           // Parse the template recursively
           const templateParsed = recursive([...templateContainer.childNodes], undefined, new Set(), stats);
 
-          // Store iteration metadata
-          const iterationKey = `iteration_${hash()}`;
-          result[iterationKey] = {
+          // Store iteration metadata (use index for deterministic keys)
+          const iterationKey = `iteration_${i}`;
+          const iterationNode = {
             type: 'iteration',
             meta: {
               arrayPath,
@@ -76,12 +75,15 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
                 children: templateParsed,
               },
             },
-            runtime: {
+            // Preserve runtime data from previous parse if it exists (stored on startComment by iterate.js)
+            // @ts-ignore - custom property added by iterate.js
+            runtime: element.__vibeIterationRuntime || {
               instances: [],
               templateRemoved: false,
             },
             children: {},
           };
+          result[iterationKey] = iterationNode;
 
           // Mark template indices as processed
           for (let j = i + 1; j < endIndex; j++) {
@@ -133,8 +135,8 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
             falseBranchParsed = recursive([...falseBranchContainer.childNodes], undefined, new Set(), stats);
           }
 
-          // Store conditional metadata
-          const conditionalKey = `conditional_${hash()}`;
+          // Store conditional metadata (use index for deterministic keys)
+          const conditionalKey = `conditional_${i}`;
           result[conditionalKey] = {
             type: 'conditional',
             meta: {
@@ -194,7 +196,13 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
     // Check for attribute bindings
     const attributes = {};
     const nameBindings = [];
-    if (element.attributes) {
+
+    // Skip hydrating attributes on fetched components - they need to be passed raw
+    const isFetchedComponent =
+      (nodeName === 'COMPONENT' || (nodeName === 'DIV' && element.classList?.contains('component'))) &&
+      element.hasAttribute('src');
+
+    if (element.attributes && !isFetchedComponent) {
       for (let j = 0; j < element.attributes.length; j++) {
         const attr = element.attributes[j];
         // Reset lastIndex before test - BINDING_REGEX has 'g' flag which persists state
@@ -227,29 +235,13 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
     }
 
     // Helper to find component ID for an element
+    // Looks for nearest ancestor with data-vibe-component-id
     function findComponentIdForElement(element) {
-      if (!element || !element.parentElement) return null;
-
-      let current = element;
-
-      while (current && current !== document.body) {
-        // Check previous siblings for script[data-vibe-component-id]
-        let sibling = current.previousElementSibling;
-        while (sibling) {
-          if (
-            sibling.tagName === 'SCRIPT' &&
-            sibling.getAttribute('type') === 'component' &&
-            sibling.hasAttribute('data-vibe-component-id')
-          ) {
-            return sibling.getAttribute('data-vibe-component-id');
-          }
-          sibling = sibling.previousElementSibling;
-        }
-
-        current = current.parentElement;
-      }
+      if (!element) return null;
 
-      return null;
+      // Find nearest component wrapper (tagged by component.js)
+      const wrapper = element.closest('[data-vibe-component-id]');
+      return wrapper ? wrapper.getAttribute('data-vibe-component-id') : null;
     }
     const hasAttributeBindings = Object.keys(attributes).length > 0;
     const hasNameBindings = nameBindings.length > 0;

package/runtime/scope.js

@@ -2,36 +2,16 @@
 
 /**
  * Find the component ID that owns this element
- * Walks up DOM to find nearest script[data-vibe-component-id]
+ * Finds nearest ancestor with data-vibe-component-id (set by component.js)
  * @param {Element} element - DOM element to find component for
  * @returns {string|null} - Component ID or null if not in component scope
  */
 export const findComponentId = (element) => {
-  let current = element;
+  if (!element || !element.closest) return null;
 
-  while (current && current !== document.body) {
-    // Check if this element has component ID
-    if (current.hasAttribute && current.hasAttribute('data-vibe-component-id')) {
-      return current.getAttribute('data-vibe-component-id');
-    }
-
-    // Check previous siblings for script[data-vibe-component-id]
-    let sibling = current.previousElementSibling;
-    while (sibling) {
-      if (
-        sibling.tagName === 'SCRIPT' &&
-        sibling.getAttribute('type') === 'component' &&
-        sibling.hasAttribute('data-vibe-component-id')
-      ) {
-        return sibling.getAttribute('data-vibe-component-id');
-      }
-      sibling = sibling.previousElementSibling;
-    }
-
-    current = current.parentElement;
-  }
-
-  return null;
+  // Find nearest component wrapper (tagged by component.js)
+  const wrapper = element.closest('[data-vibe-component-id]');
+  return wrapper ? wrapper.getAttribute('data-vibe-component-id') : null;
 };
 
 /**

package/runtime/utils.js

@@ -50,21 +50,12 @@ export const evalInScope = (expr, state, element = null) => {
 };
 
 // Helper to find component ID for an element
+// Walks up DOM tree to find nearest component wrapper
 export const findComponentIdForElement = (element) => {
-  if (!element) return null;
+  if (!element || !element.closest) return null;
 
-  // First check if element itself has the ID (tagged during parse)
-  if (element.hasAttribute('data-vibe-component-id')) {
-    return element.getAttribute('data-vibe-component-id');
-  }
-
-  // Check if any ancestor has the ID
-  const ancestor = element.closest('[data-vibe-component-id]');
-  if (ancestor) {
-    return ancestor.getAttribute('data-vibe-component-id');
-  }
-
-  return null;
+  const wrapper = element.closest('[data-vibe-component-id]');
+  return wrapper ? wrapper.getAttribute('data-vibe-component-id') : null;
 };
 
 // Helper to resolve this.property paths to componentId.property

package/vibe.css

@@ -2,10 +2,12 @@
  * Elements with [vibe] attribute are hidden until framework removes it after hydration.
  * This prevents flash of unprocessed content and disables transitions during init.
  */
-[vibe] {
+[vibe-fouc],
+.vibe-fouc {
   visibility: hidden;
 }
 
-[vibe] * {
+[vibe-fouc] *,
+.vibe-fouc * {
   transition: none !important;
 }