mnfst-render 0.5.1 → 0.5.3

package/manifest.render.mjs

@@ -172,6 +172,7 @@ function parseArgs() {
     if (args[i] === '--wait' && args[i + 1]) { out.wait = parseInt(args[++i], 10); continue; }
     if (args[i] === '--wait-after-idle' && args[i + 1]) { out.waitAfterIdle = parseInt(args[++i], 10); continue; }
     if (args[i] === '--concurrency' && args[i + 1]) { out.concurrency = parseInt(args[++i], 10); continue; }
+    if (args[i] === '--retries' && args[i + 1]) { out.retries = parseInt(args[++i], 10); continue; }
     if (args[i] === '--dry-run') { out.dryRun = true; continue; }
     if (args[i] === '--debug-prerender') { out.debugPrerender = true; continue; }
   }
@@ -231,6 +232,7 @@ function resolveConfig() {
     wait: cli.wait ?? pre.wait ?? null,
     waitAfterIdle: 0,
     concurrency: Math.max(1, cli.concurrency ?? pre.concurrency ?? Math.max(4, cpus().length - 1)),
+    retries: Math.max(0, cli.retries ?? pre.retries ?? 2),
     localeSubstitution: true,
     localeSubstitutionExclude: [],
     /** Explicit locale-neutral paths to render in addition to those discovered automatically.
@@ -1751,8 +1753,9 @@ async function runPrerender(config) {
     browser = await puppeteer.default.launch({ headless: true });
   }
 
-  const timeout = config.wait ?? 15000;
+  const timeout = config.wait ?? 30000;
   const concurrency = config.concurrency;
+  const maxRetries = config.retries ?? 2;
   const pathTotal = pathList.length;
   const failedPaths = [];
   const debugRows = [];
@@ -1883,6 +1886,36 @@ async function runPrerender(config) {
         let nextId = 0;
         const skipTags = new Set(['MAIN', 'BODY', 'HTML']);
 
+        // Own MutationObserver registered before any other script on the page.
+        // This guarantees we process DOM additions before Alpine's observer does —
+        // critically, before Alpine's observer calls initTree on newly expanded
+        // Manifest components (preloaded or lazy) and bakes their `:class` state.
+        const installHydrateObserver = () => {
+          if (window.__manifestHydrateObserver || !document.body) return;
+          const obs = new MutationObserver((mutations) => {
+            for (const m of mutations) {
+              if (m.type !== 'childList') continue;
+              for (const node of m.addedNodes) {
+                if (node.nodeType !== 1) continue;
+                try { snapshotSubtree(node); } catch (_) {}
+              }
+            }
+          });
+          obs.observe(document.body, { childList: true, subtree: true });
+          window.__manifestHydrateObserver = obs;
+        };
+        if (typeof document !== 'undefined') {
+          if (document.body) {
+            installHydrateObserver();
+          } else {
+            document.addEventListener('DOMContentLoaded', installHydrateObserver, { once: true });
+            // Also try once readyState flips to interactive
+            document.addEventListener('readystatechange', () => {
+              if (document.readyState !== 'loading') installHydrateObserver();
+            });
+          }
+        }
+
         const snapshotElement = (el) => {
           if (!el || el.nodeType !== 1) return;
           if (el.hasAttribute('data-manifest-hyd-id')) return; // already snapshotted
@@ -1894,7 +1927,7 @@ async function runPrerender(config) {
             if (a.name === 'data-manifest-hyd-id') continue;
             attrs[a.name] = a.value;
           }
-          allSnapshots.push({ id, attrs });
+          allSnapshots.push({ id, tag: el.tagName, attrs });
         };
 
         const snapshotElementAndDescendants = (el) => {
@@ -1943,24 +1976,38 @@ async function runPrerender(config) {
           window.__manifestHydrateSnapshots = allSnapshots;
         };
 
-        // Wrap Alpine.initTree.  This MUST happen before any plugin calls initTree —
-        // otherwise preloaded components (loaded eagerly by manifest.components before
-        // Alpine starts walking the tree) get processed by the original initTree and
-        // their hydrate targets are missed.  We use a defineProperty setter on
-        // window.Alpine so the wrap happens the instant Alpine's CDN script does
-        // `window.Alpine = ...` — earlier than any event we could listen for.
+        // Wrap Alpine.start so the snapshot runs INSIDE the start call, before
+        // Alpine has a chance to walk and mutate the tree.  alpine:init as an
+        // external hook proved unreliable — in some configurations it fires after
+        // Alpine has already processed some elements.  Alpine.start is the single
+        // synchronous entry point for the initial walk, so wrapping it guarantees
+        // we capture source state before any directive has been applied.
+        //
+        // We also wrap Alpine.initTree for lazy-loaded components that appear in
+        // the DOM after Alpine.start() has completed (fetched by the components
+        // plugin in response to new <x-*> placeholders).
+        //
+        // Both wraps are installed via a defineProperty setter on window.Alpine
+        // so they land the instant Alpine's CDN script does `window.Alpine = ...`.
         const wrap = (alpine) => {
           if (!alpine || alpine.__manifestRenderWrapped) return;
-          if (typeof alpine.initTree !== 'function') return;
           alpine.__manifestRenderWrapped = true;
-          const original = alpine.initTree.bind(alpine);
-          alpine.initTree = function (root) {
-            try { snapshotSubtree(root || document.body); } catch (_) { /* graceful */ }
-            return original.apply(this, arguments);
-          };
+          if (typeof alpine.start === 'function') {
+            const originalStart = alpine.start.bind(alpine);
+            alpine.start = function () {
+              try { snapshotSubtree(document.body); } catch (_) { /* graceful */ }
+              return originalStart.apply(this, arguments);
+            };
+          }
+          if (typeof alpine.initTree === 'function') {
+            const originalInit = alpine.initTree.bind(alpine);
+            alpine.initTree = function (root) {
+              try { snapshotSubtree(root || document.body); } catch (_) { /* graceful */ }
+              return originalInit.apply(this, arguments);
+            };
+          }
         };
 
-        // Setter trap: as soon as Alpine is assigned to window, wrap it.
         let _Alpine;
         try {
           Object.defineProperty(window, 'Alpine', {
@@ -1971,9 +2018,8 @@ async function runPrerender(config) {
           });
         } catch (_) { /* defineProperty failed, fall back to event listeners */ }
 
-        // Belt-and-braces: also try to wrap on alpine:init events in case some
-        // environment beats the setter.  wrap() is idempotent.
         if (typeof document !== 'undefined') {
+          // Event-based fallback in case the setter trap missed Alpine assignment.
           document.addEventListener('alpine:init', () => wrap(window.Alpine));
           document.addEventListener('alpine:initialized', () => wrap(window.Alpine));
         }
@@ -2218,22 +2264,81 @@ async function runPrerender(config) {
       // it would in the live SPA.  After restoring source attributes we re-add the
       // `data-prerender-hydrate` marker so downstream Node.js stripping passes
       // continue to skip these elements.
-      await page.evaluate(() => {
+      //
+      // Implementation note: we use `outerHTML` to swap the element rather than
+      // `setAttribute` per-attribute.  Alpine's special attribute names (`@click`,
+      // possibly others starting with `@`) are not valid DOM Names per the XML
+      // production, so `setAttribute('@click', …)` throws InvalidCharacterError.
+      // The HTML parser, on the other hand, is lenient and accepts these names.
+      // Building an HTML string and assigning it via outerHTML round-trips through
+      // the parser and produces an element with all source attributes intact.
+      // Stop Alpine from observing further DOM mutations and flush any pending
+      // effects.  Then restore each hydrate target by replacing it with a fresh
+      // element parsed from a source-attribute HTML string.  Replacing the element
+      // (rather than mutating attributes in place) detaches it from Alpine's
+      // reactive bindings entirely — the new node has no `_x_*` state, no
+      // effects, and no observers.  Alpine's MutationObserver is stopped first
+      // so it can't pick up the new node and re-process it.
+      //
+      // We process snapshots deepest-first so that when an ancestor is rebuilt,
+      // its children have already been replaced with their pristine versions and
+      // are captured (via innerHTML) into the new ancestor.
+      const restoreReport = await page.evaluate(async () => {
+        try { window.Alpine && window.Alpine.flushAndStopDeferringMutations && window.Alpine.flushAndStopDeferringMutations(); } catch (_) {}
+        try { window.Alpine && window.Alpine.stopObservingMutations && window.Alpine.stopObservingMutations(); } catch (_) {}
+        await Promise.resolve();
+        await Promise.resolve();
+
         const snapshots = window.__manifestHydrateSnapshots || [];
+        const report = { total: snapshots.length, restored: 0, notFound: 0, errors: [] };
+
+        // Resolve every snapshot to its element, then sort by depth (deepest first).
+        const items = [];
         snapshots.forEach(({ id, attrs }) => {
           const el = document.querySelector(`[data-manifest-hyd-id="${id}"]`);
-          if (!el) return;
-          // Wipe everything Alpine may have added or mutated.
-          Array.from(el.attributes).map((a) => a.name).forEach((name) => el.removeAttribute(name));
-          // Put the original source attributes back.
-          Object.entries(attrs).forEach(([name, value]) => {
-            el.setAttribute(name, value);
-          });
-          // Marker so downstream stripping (xfor processing, dynamic-binding strip,
-          // component pre-render marking, etc.) skips this element.
-          el.setAttribute('data-prerender-hydrate', '1');
+          if (!el) { report.notFound++; return; }
+          let depth = 0;
+          for (let p = el.parentNode; p; p = p.parentNode) depth++;
+          items.push({ id, el, attrs, depth });
         });
+        items.sort((a, b) => b.depth - a.depth);
+
+        const voidEls = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+        const escAttr = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+
+        items.forEach(({ id, attrs }) => {
+          // Re-resolve the element by id every iteration: ancestors that were
+          // already rebuilt will have re-parsed their children, so previous
+          // references are stale.
+          const el = document.querySelector(`[data-manifest-hyd-id="${id}"]`);
+          if (!el || !el.parentNode) { report.errors.push({ id, msg: 'lost reference' }); return; }
+          const tag = el.tagName.toLowerCase();
+          const attrString = Object.entries(attrs)
+            .map(([name, value]) => `${name}="${escAttr(value)}"`)
+            .join(' ');
+          const innerHTML = voidEls.has(tag) ? '' : el.innerHTML;
+          const newHTML = voidEls.has(tag)
+            ? `<${tag} ${attrString} data-prerender-hydrate="1">`
+            : `<${tag} ${attrString} data-prerender-hydrate="1">${innerHTML}</${tag}>`;
+          // Parse via a temporary container so we can use replaceChild (more
+          // reliable than outerHTML in nested-replace scenarios).
+          const tmp = document.createElement(el.parentNode.tagName === 'TR' ? 'tr' : 'div');
+          tmp.innerHTML = newHTML;
+          const parsed = tmp.firstElementChild;
+          if (!parsed) { report.errors.push({ id, msg: 'parse failed' }); return; }
+          try {
+            el.parentNode.replaceChild(parsed, el);
+            report.restored++;
+          } catch (e) {
+            report.errors.push({ id, tag, msg: String(e && e.message || e) });
+          }
+        });
+
+        return report;
       });
+      if (config.debugPrerender) {
+        pushDebug({ path: displayPath, stage: 'hydrate-restore', metrics: restoreReport });
+      }
 
       // x-for lists: keep static lists in the HTML for SEO; collapse only dynamic lists so Alpine re-renders.
       // Explicit: data-prerender="dynamic"|"skip". Inferred: x-for uses $search/$query,
@@ -2619,19 +2724,34 @@ async function runPrerender(config) {
     }
   }
 
-  // Phase 1: Puppeteer — render base paths, cache raw DOM for substitution
+  // Phase 1: Puppeteer — render base paths, cache raw DOM for substitution.
+  // Any failures (e.g. transient navigation timeouts) are retried up to
+  // `maxRetries` times with a short backoff before being reported as fatal.
   try {
     let index = 0;
     async function worker() {
       while (true) {
         const i = index++;
         if (i >= puppeteerPaths.length) return;
-        await processPath(puppeteerPaths[i], i, {
-          onRawHtml: (seg, html) => {
-            // Cache raw DOM snapshot for locale variant generation (NOT_FOUND_PATH excluded)
-            if (seg !== NOT_FOUND_PATH) baseHtmlCache.set(seg || '', html);
-          },
-        });
+        const pathSeg = puppeteerPaths[i];
+        let attempt = 0;
+        while (true) {
+          const failureCountBefore = failedPaths.length;
+          await processPath(pathSeg, i, {
+            onRawHtml: (seg, html) => {
+              // Cache raw DOM snapshot for locale variant generation (NOT_FOUND_PATH excluded)
+              if (seg !== NOT_FOUND_PATH) baseHtmlCache.set(seg || '', html);
+            },
+          });
+          if (failedPaths.length === failureCountBefore) break; // success
+          if (attempt >= maxRetries) break; // out of retries — leave the failure recorded
+          // Pop the failure record and retry after a short backoff.
+          failedPaths.pop();
+          attempt++;
+          const displayPath = pathSeg === '' ? '/' : (pathSeg === NOT_FOUND_PATH ? '/__prerender_404__' : '/' + pathSeg);
+          process.stderr.write(`prerender: retrying ${displayPath} (attempt ${attempt + 1}/${maxRetries + 1})\n`);
+          await new Promise((r) => setTimeout(r, 500 * attempt));
+        }
       }
     }
     await Promise.all(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnfst-render",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Render Manifest sites to static HTML for SEO",
   "type": "module",
   "bin": {