@ape-egg/vibe 4.0.0 → 4.1.1

package/runtime/pre-compiled-manifest.js

@@ -1,28 +1,17 @@
-/**
- * Pre-compiled Manifest - Manifest support for pre-compiled Vibe pages
- *
- * Handles detection, loading, and restoration of pre-compiled page manifests.
- */
-
-// Build manifest with restoration data (captures markers before hydration)
 export const buildHyperspeedManifest = (parsedTree) => {
-  // Helper to split text content by @[...] markers into array
   const splitByMarkers = (text) => {
     const regex = /@\[[^\]]+\]/g;
     const parts = [];
     let lastIndex = 0;
 
     text.replace(regex, (match, index) => {
-      // Add text before marker
       if (index > lastIndex) {
         parts.push(text.slice(lastIndex, index));
       }
-      // Add marker
       parts.push(match);
       lastIndex = index + match.length;
     });
 
-    // Add remaining text
     if (lastIndex < text.length) {
       parts.push(text.slice(lastIndex));
     }
@@ -37,12 +26,10 @@ export const buildHyperspeedManifest = (parsedTree) => {
       children: {},
     };
 
-    // Copy type for iterations/conditionals
     if (node.type) {
       result.type = node.type;
     }
 
-    // Check if parsed string contains bindings - split into array
     if (typeof node.parsed === "string" && node.parsed.includes("@[")) {
       const parsedArray = splitByMarkers(node.parsed);
       if (parsedArray) {
@@ -52,7 +39,6 @@ export const buildHyperspeedManifest = (parsedTree) => {
       }
     }
 
-    // Check for attribute bindings
     if (node.attributes && typeof node.attributes === "object") {
       const attrBindings = {};
       for (const [key, value] of Object.entries(node.attributes)) {
@@ -68,7 +54,6 @@ export const buildHyperspeedManifest = (parsedTree) => {
       }
     }
 
-    // For iterations, extract template as HTML string
     if (node.type === "iteration" && node.meta?.template?.element) {
       const templateElement = node.meta.template.element;
       if (templateElement && templateElement.innerHTML) {
@@ -79,7 +64,6 @@ export const buildHyperspeedManifest = (parsedTree) => {
       }
     }
 
-    // For conditionals, extract branch templates as HTML strings
     if (node.type === "conditional" && node.meta?.branches) {
       const trueBranch = node.meta.branches.true?.element;
       const falseBranch = node.meta.branches.false?.element;
@@ -97,7 +81,6 @@ export const buildHyperspeedManifest = (parsedTree) => {
       }
     }
 
-    // Recursively process children (skip runtime-only nodes)
     if (node.children && typeof node.children === "object") {
       for (const [key, childNode] of Object.entries(node.children)) {
         result.children[key] = walkNode(childNode);
@@ -107,7 +90,6 @@ export const buildHyperspeedManifest = (parsedTree) => {
     return result;
   };
 
-  // Wrap in body structure (parsedTree is already the body's children)
   return {
     element: null,
     parsed: [],
@@ -115,37 +97,18 @@ export const buildHyperspeedManifest = (parsedTree) => {
       body: {
         element: null,
         parsed: [],
-        children: walkNode(parsedTree).children, // Use children directly
+        children: walkNode(parsedTree).children,
       },
     },
   };
 };
 
-// Manifest detection - per-page manifest
-// Each compiled page has its own manifest: /vibe-hyperspeed/{page-path}.manifest.js
 let hyperspeedData = null;
 let hyperspeedDetectionAttempted = false;
 
-/**
- * Build the ordered list of manifest URLs to try for a page, most-likely first.
- *
- * `pathname` is window.location.pathname; `route` is the optional route template
- * the page declares (window.__ROUTE__, e.g. "/brawlers/:index"). When the route
- * marks a segment dynamic with `:param`, the compiler has collapsed that segment
- * to `$` in the manifest path — so we point straight at the tokenized manifest
- * instead of probing literal paths (`/brawlers/0.html.manifest.js`) that are
- * guaranteed to 404. Without the route hint the original literal-first strategies
- * apply unchanged. The result is de-duplicated (subdirectory pages otherwise
- * produce the same candidate twice).
- *
- * @param {string} pathname
- * @param {string|null|undefined} route
- * @returns {string[]}
- */
 export const buildManifestCandidatePaths = (pathname, route) => {
   let pagePath = pathname;
 
-  // Normalize path: handle directory URLs and missing extensions
   if (pagePath.endsWith("/")) {
     pagePath = pagePath + "index.html";
   } else if (!pagePath.includes(".")) {
@@ -164,23 +127,12 @@ export const buildManifestCandidatePaths = (pathname, route) => {
 
   const possiblePaths = [];
 
-  // Route-aware fast path: a `:segment` in the declared route is a dynamic param
-  // the compiler tokenized to `$`. Tokenize exactly those positions (params can
-  // sit mid-path, e.g. /a/:id/b) and try that manifest first — a direct hit, no
-  // 404 probing. Skipped entirely when no route is declared.
   const routeSegments = route ? route.split("/").filter((s) => s) : null;
   const isCatchAll =
     routeSegments &&
     routeSegments[routeSegments.length - 1]?.startsWith(":") &&
     routeSegments[routeSegments.length - 1]?.endsWith("*");
   if (isCatchAll) {
-    // A trailing `:name*` catch-all (pages/x/$$name.html) swallows every
-    // remaining URL segment — zero or more — so tokenizing by position is
-    // meaningless past the static prefix. The compiler collapses the whole
-    // `$$name.html` file to the same `$` token as a single `$param`, giving
-    // ONE manifest for every depth: <static-prefix>/$.html.manifest.js.
-    // Built from the raw pathname: with zero extra segments the .html
-    // normalization above has already mutated the prefix's last segment.
     const rawSegments = pathname.split("/").filter((s) => s);
     const prefix = rawSegments
       .slice(0, routeSegments.length - 1)
@@ -195,22 +147,16 @@ export const buildManifestCandidatePaths = (pathname, route) => {
     possiblePaths.push(`/vibe-hyperspeed/${tokenized.join("/")}.manifest.js`);
   }
 
-  // Strategy 1: vibe-hyperspeed at the same level as parent directory
-  // /compiled/playground/test.html -> /compiled/vibe-hyperspeed/playground/test.html.manifest.js
   if (dirSegments.length >= 1) {
-    const subPath = dirSegments.slice(1).join("/"); // Everything after first dir
-    const baseDir = "/" + dirSegments[0]; // First directory segment
+    const subPath = dirSegments.slice(1).join("/");
+    const baseDir = "/" + dirSegments[0];
     possiblePaths.push(
       `${baseDir}/vibe-hyperspeed/${subPath ? subPath + "/" : ""}${fileName}.manifest.js`,
     );
   }
 
-  // Strategy 2: vibe-hyperspeed at web root (original behavior)
-  // /compiled/playground/test.html -> /vibe-hyperspeed/compiled/playground/test.html.manifest.js
   possiblePaths.push(`/vibe-hyperspeed${pagePath}.manifest.js`);
 
-  // Strategy 3: vibe-hyperspeed relative to immediate parent
-  // /playground/test.html -> /vibe-hyperspeed/playground/test.html.manifest.js
   if (dirSegments.length > 0) {
     const relativePath = dirSegments.join("/");
     possiblePaths.push(
@@ -218,11 +164,6 @@ export const buildManifestCandidatePaths = (pathname, route) => {
     );
   }
 
-  // Strategy 4: dynamic routes without a declared route. The compiler collapses a
-  // `$param` segment to a single `$` token (the-arena/$id.html ->
-  // the-arena/$.html.manifest.js), so a concrete URL only matches once its
-  // trailing segment is tokenized. Tried after the literal strategies, so static
-  // pages still win on an exact hit.
   const dot = fileName.indexOf(".");
   const tokenized = dot >= 0 ? "$" + fileName.slice(dot) : "$";
   if (tokenized !== fileName) {
@@ -230,37 +171,16 @@ export const buildManifestCandidatePaths = (pathname, route) => {
     possiblePaths.push(`/vibe-hyperspeed${dirPrefix}/${tokenized}.manifest.js`);
   }
 
-  // Subdirectory pages make strategies 2 and 3 collapse to the same URL — probe
-  // each candidate once.
   return [...new Set(possiblePaths)];
 };
 
-/**
- * Detect page-specific manifest (async, cached after first call)
- * Returns { manifest, path } or null
- */
 const detectHyperspeed = async () => {
   if (hyperspeedDetectionAttempted) return hyperspeedData;
   hyperspeedDetectionAttempted = true;
 
-  // Runtime-mode pages still have [vibe-fouc] / .vibe-fouc on their vibe root
-  // at this point — the compiler strips it at build time, and the runtime only
-  // clears it after hydration (PHASE_READY). Vibe can latch to any element, so
-  // search the whole document. If any fouc marker is still here, we're in
-  // runtime mode and no hyperspeed manifest will exist — skip the network
-  // fetches and avoid the 404 devtools noise.
   const skipNetwork = !!document.querySelector("[vibe-fouc], .vibe-fouc");
 
   try {
-    // window.__MANIFEST__ is an explicit manifest URL stamped into the page by
-    // the build/dev server. The compiled SPA shell needs it: the shell is
-    // served for EVERY route, so pathname-derived candidates point at manifests
-    // that don't exist (deep links probed 404s and never found the shell's own
-    // manifest). When present it is the single, authoritative candidate.
-    //
-    // window.__ROUTE__ is the page's route template (e.g. "/brawlers/:index"),
-    // injected by the compiler/dev server for dynamic pages. It lets us resolve
-    // the tokenized `$` manifest directly instead of probing literal 404s.
     const hinted = typeof window !== "undefined" ? window.__MANIFEST__ : null;
     const possiblePaths = hinted
       ? [hinted]
@@ -272,12 +192,7 @@ const detectHyperspeed = async () => {
     if (possiblePaths.length === 0) return null;
 
     if (!skipNetwork) {
-      // Fully-runtime dynamic import. Hidden behind `new Function` so any
-      // bundler's static-analysis can't read into it — there's nothing we
-      // could or should tell it about these manifest paths, which are decided
-      // at runtime by searching a list.
       const dynamicImport = new Function('p', 'return import(p)');
-      // Try each possible path
       for (const manifestPath of possiblePaths) {
         try {
           const module = await dynamicImport(manifestPath);
@@ -287,43 +202,21 @@ const detectHyperspeed = async () => {
           };
           return hyperspeedData;
         } catch (e) {
-          // Try next path
           continue;
         }
       }
     }
 
-    // When skipping network, yield a macrotask so module-graph timing matches
-    // the old behavior where `await import()` on a missing manifest resolved
-    // via a network 404 (macrotask), not a microtask. Without this yield, the
-    // vibe module-graph resolves too fast and the post-boot microtask fires
-    // before sibling `<script type="module">` tags (e.g. component scripts)
-    // have had a chance to register their state.
     if (skipNetwork) {
       await new Promise((resolve) => setTimeout(resolve, 0));
     }
 
-    // No manifest found
     return null;
   } catch {
-    // No manifest for this page - runtime-only mode
     return null;
   }
 };
 
-/**
- * Restore DOM from pre-rendered values to @[...] markers using pre-compiled manifest
- * This enables FOUC-free loading while maintaining runtime reactivity
- *
- * Flow:
- * 1. Page loads with pre-rendered values: <strong>John Doe</strong> (visible, no FOUC)
- * 2. Restoration: Replace with markers: <strong>@[firstName] @[lastName]</strong>
- * 3. Runtime processes normally: Finds markers, makes reactive
- *
- * @param {Element} rootElement - The DOM element to restore (e.g., <body>)
- * @param {Object} subtree - The matching subtree from manifest (e.g., manifest.children.body)
- * @param {Object} fullManifest - The full manifest (unused now, kept for compatibility)
- */
 export const restoreMarkersFromManifest = (
   rootElement,
   subtree,
@@ -332,68 +225,46 @@ export const restoreMarkersFromManifest = (
   const walkTree = (tree, element) => {
     if (!tree || !element) return;
 
-    // Check for compiled restoration data
     const restoration = tree.compiled?.restoration;
 
     if (restoration) {
-      // Restore text content with markers if parsed contains bindings
       if (restoration.parsed && Array.isArray(restoration.parsed)) {
         const hasBindings = restoration.parsed.some(
           (item) => typeof item === "string" && item.includes("@["),
         );
 
         if (hasBindings) {
-          // Reconstruct original content with markers
           let originalContent = restoration.parsed.join("");
 
-          // Transform component-scoped bindings back to this. format
-          // Compiler transforms @[this.count] → @[_c0.count] for stamping
-          // Runtime expects @[this.count], so transform back
           originalContent = originalContent.replace(/@\[_c\d+\./g, "@[this.");
 
-          // For text nodes, update parent's innerHTML
-          // For elements with children, update only text nodes
           if (
             element.childNodes.length === 1 &&
             element.childNodes[0].nodeType === 3
           ) {
-            // Single text node - replace it
             element.childNodes[0].textContent = originalContent;
           } else if (element.childNodes.length === 0) {
-            // No children - set textContent
             element.textContent = originalContent;
           }
-          // If element has multiple children, they'll be handled recursively
         }
       }
 
-      // Restore attribute bindings for reactivity
-      // Two cases:
-      // 1. Boolean-like attributes with falsy values were removed - restore them
-      // 2. Value attributes were stamped - replace stamped values with markers
       if (restoration.attributes) {
         for (let [attrName, attrValue] of Object.entries(
           restoration.attributes,
         )) {
-          // Transform component-scoped bindings back to this. format
-          // Compiler transforms @[this.count] → @[_c0.count], runtime expects @[this.count]
           attrValue = attrValue.replace(/@\[_c\d+\./g, "@[this.");
 
-          // Always set the attribute to restore the marker
-          // - If missing (boolean-like, falsy): adds it back
-          // - If present (value attr, stamped): replaces stamped value with marker
           element.setAttribute(attrName, attrValue);
         }
       }
 
-      // Restore name bindings (sparse array indexed by attribute position)
       if (restoration.nameBindings && Array.isArray(restoration.nameBindings)) {
         const attrs = Array.from(element.attributes);
 
         for (let i = 0; i < restoration.nameBindings.length; i++) {
           const marker = restoration.nameBindings[i];
           if (marker && attrs[i]) {
-            // Replace the stamped attribute name with the marker
             const stampedName = attrs[i].name;
             const attrValue = attrs[i].value;
 
@@ -403,17 +274,11 @@ export const restoreMarkersFromManifest = (
         }
       }
 
-      // After restoration, delete compiled.restoration (runtime will parse DOM fresh)
       if (tree.compiled) {
         delete tree.compiled.restoration;
       }
     }
 
-    // IMPORTANT: Restore text nodes BEFORE processing conditionals/iterations
-    // Text nodes use childNodes indices which become invalid after DOM modifications
-    // Ascending index order, same invariant the directive restoration below
-    // relies on: each text node is returned to its pre-stamp state before a
-    // later index is consulted, so every index stays valid as we go.
     if (tree.children) {
       const texts = Object.keys(tree.children)
         .filter((key) => key.startsWith("text_"))
@@ -431,23 +296,16 @@ export const restoreMarkersFromManifest = (
           );
 
           if (hasBindings) {
-            // Transform component-scoped bindings back to this. format
             const originalContent = restoration.parsed
               .join("")
               .replace(/@\[_c\d+\./g, "@[this.");
 
             const node = element.childNodes[index];
-            if (node && node.nodeType === Node.TEXT_NODE) {
+            if (index === 0 && Object.keys(tree.children).length === 1) {
+              element.textContent = originalContent;
+            } else if (node && node.nodeType === Node.TEXT_NODE) {
               node.textContent = originalContent;
             } else {
-              // The stamp ELIDED this text node: every binding in it rendered
-              // to an empty string, and an empty text node has no HTML
-              // serialization, so the compiled page carries no node here at all
-              // (`<out>@[removed.join(',')]</out>` with an empty array stamps to
-              // `<out></out>`). Recreate it at its recorded index — otherwise
-              // the marker never returns and the binding is dead for the page's
-              // lifetime, and every later sibling index at this level is off by
-              // one, so their restorations silently miss too.
               element.insertBefore(
                 document.createTextNode(originalContent),
                 node ?? null,
@@ -462,13 +320,6 @@ export const restoreMarkersFromManifest = (
       }
     }
 
-    // Restore iterations/conditionals at THIS level by their childNodes index.
-    // The manifest key encodes the start comment's pre-stamp position
-    // (`conditional_13` = element.childNodes[13]); processing in ascending
-    // order keeps every index valid, because each restoration returns its
-    // region to the exact pre-stamp node count before the next index is
-    // consulted. Locating by index — not by expression text — is what
-    // disambiguates sibling directives that share the same expression.
     if (tree.children) {
       const directives = Object.keys(tree.children)
         .filter((key) => {
@@ -483,8 +334,6 @@ export const restoreMarkersFromManifest = (
         const childTree = tree.children[key];
         const restoration = childTree.compiled?.restoration;
 
-        // Always delete the directive node from the tree — the runtime
-        // re-creates it when it parses the restored DOM.
         delete tree.children[key];
 
         if (!restoration?.template) continue;
@@ -494,8 +343,6 @@ export const restoreMarkersFromManifest = (
           continue;
         }
 
-        // Find the matching end marker at this sibling level, depth-counted
-        // so nested same-kind directives inside the region don't end it early.
         const isIteration = childTree.type === "iteration";
         const openPrefix = isIteration ? "each " : "if ";
         const closeMarker = isIteration ? "/each" : "/if";
@@ -516,9 +363,6 @@ export const restoreMarkersFromManifest = (
         }
         if (!endComment) continue;
 
-        // Drop the stamped content (including the <!-- else --> marker and
-        // any stamped-row comments) and re-insert the pre-stamp template —
-        // node-for-node identical to what the manifest was built against.
         let current = startComment.nextSibling;
         while (current && current !== endComment) {
           const next = current.nextSibling;
@@ -532,12 +376,10 @@ export const restoreMarkersFromManifest = (
       }
     }
 
-    // Recursively restore children (skip conditional/iteration children as they were already handled)
     if (tree.children) {
       for (const key in tree.children) {
         const childTree = tree.children[key];
 
-        // Skip conditionals and iterations (already processed/deleted above)
         if (
           childTree.type === "conditional" ||
           childTree.type === "iteration"
@@ -545,14 +387,10 @@ export const restoreMarkersFromManifest = (
           continue;
         }
 
-        // Skip text nodes - already handled before conditional/iteration processing
         if (key.startsWith("text_")) {
           continue;
         }
 
-        // Find corresponding child element by tag name and index
-        // Keys like "layout_1" mean the node at childNodes index 1 (includes text nodes)
-        // Tag names can contain digits (h1, h2, etc.) so use [a-z0-9-]+
         const match = key.match(/^([a-z0-9-]+)_(\d+)$/);
         if (match) {
           const tagName = match[1].toUpperCase();
@@ -575,7 +413,6 @@ export const restoreMarkersFromManifest = (
   walkTree(subtree, rootElement);
 };
 
-// Top-level await to detect before module exports
 hyperspeedData = await detectHyperspeed();
 
 export const hyperspeedManifest = hyperspeedData?.manifest || null;

package/runtime/raw-html.js

@@ -1,8 +1,3 @@
-// Marker for trusted raw-HTML output. `$.unsafe(str)` wraps a string so the
-// hydrate path knows to set innerHTML instead of escaping via textContent.
-// toString() returns the raw string so any non-pure use (the marker spliced
-// into surrounding text) degrades to escaped literal text automatically — the
-// browser escapes it when it lands in a text node.
 export class RawHtml {
   constructor(html) {
     this.html = html == null ? '' : String(html);