mnfst-render 0.5.2 → 0.5.4

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; }
   }
@@ -230,7 +231,12 @@ function resolveConfig() {
     redirects: Array.isArray(pre.redirects) ? pre.redirects : [],
     wait: cli.wait ?? pre.wait ?? null,
     waitAfterIdle: 0,
-    concurrency: Math.max(1, cli.concurrency ?? pre.concurrency ?? Math.max(4, cpus().length - 1)),
+    // Default concurrency: 2.  Chromium per-page memory overhead is large and
+    // our hydration source-attribute map adds more per page.  On big sites
+    // (>100 routes) higher concurrency crashes the browser with OOM/target
+    // closed errors.  Users can override for small projects with --concurrency.
+    concurrency: Math.max(1, cli.concurrency ?? pre.concurrency ?? 2),
+    retries: Math.max(0, cli.retries ?? pre.retries ?? 2),
     localeSubstitution: true,
     localeSubstitutionExclude: [],
     /** Explicit locale-neutral paths to render in addition to those discovered automatically.
@@ -599,14 +605,24 @@ function stripDevOnlyContent(html) {
   return out;
 }
 
-// --- Strip CDN-injected plugin scripts from snapshot so only the loader remains ---
-// When the static page loads, the loader runs once and adds plugins; avoids duplicate script execution.
+// --- Strip plugin scripts injected by the loader during prerender so only the loader tag remains ---
+// When the static page loads, the loader runs once and adds plugins; avoids
+// duplicate script execution (which would cause `const` re-declaration errors).
+// Matches both CDN-minified (.min.js) and self-hosted (.js) plugin URLs.
+// Also strips the loader-injected Alpine script (both defer and non-defer
+// forms) — at runtime the loader re-injects Alpine AFTER plugin registration,
+// and if Chromium serialized an Alpine script tag during the Puppeteer render,
+// leaving it in place would cause Alpine to execute synchronously during HTML
+// parse, before plugins have a chance to register their directives.
 function stripInjectedPluginScripts(html) {
   const pluginPattern =
-    /<script[^>]*\ssrc=["'][^"']*manifest\.(?:components|router|utilities|data|icons|localization|markdown|code|themes|toasts|tooltips|dropdowns|tabs|slides|resize|tailwind|appwrite\.(?:auth|data|presence))[^"']*\.min\.js["'][^>]*>\s*<\/script>/gi;
+    /<script[^>]*\ssrc=["'][^"']*manifest\.(?:components|router|utilities|data|icons|localization|markdown|code|themes|toasts|tooltips|dropdowns|tabs|slides|resize|colorpicker|tailwind|appwrite\.(?:auth|data|presence))[^"']*\.(?:min\.)?js["'][^>]*>\s*<\/script>/gi;
   let out = html.replace(pluginPattern, '');
+  const alpinePattern =
+    /<script[^>]*\ssrc=["'][^"']*\/alpinejs@[^"']*["'][^>]*>\s*<\/script>/gi;
+  out = out.replace(alpinePattern, '');
   const runtimePattern =
-    /<script[^>]*\ssrc=["'][^"']*(?:alpinejs\/dist\/cdn\.min\.js|papaparse@[^"']*\/papaparse\.min\.js|marked\/marked\.min\.js|highlightjs\/cdn-release@[^"']*\/highlight\.min\.js)[^"']*["'][^>]*>\s*<\/script>/gi;
+    /<script[^>]*\ssrc=["'][^"']*(?:papaparse@[^"']*\/papaparse\.min\.js|marked\/marked\.min\.js|highlightjs\/cdn-release@[^"']*\/highlight\.min\.js)[^"']*["'][^>]*>\s*<\/script>/gi;
   out = out.replace(runtimePattern, '');
   return out;
 }
@@ -840,8 +856,15 @@ function stripDuplicatedLoopDirectives(html) {
   return html;
 }
 
+// Returns true if the attribute string contains either the explicit `data-hydrate`
+// attribute (source-authored hydrate island root) or a `data-hydrate-id` (element
+// that the prerender has tagged as a runtime-restoration target).  String-level
+// strip passes use this to skip elements whose attribute state will be restored
+// from the hydration contract at runtime — leaving them untouched is the safest
+// default even though the contract would correct most damage anyway.
 function isHydrateMarkedAttrs(attrsStr) {
-  return /\sdata-prerender-hydrate(?:\s*=|[\s>])/i.test(attrsStr || '');
+  if (!attrsStr) return false;
+  return /\sdata-hydrate(?:-id)?(?:\s*=|[\s>])/i.test(attrsStr);
 }
 
 // --- Strip x-text and x-html that reference $x when static/SEO (content already in snapshot).
@@ -943,22 +966,16 @@ function stripResolvedXIconDirectives(html) {
   });
 }
 
-function stripPrerenderHydrateMarkers(html) {
-  return html.replace(/\sdata-prerender-hydrate(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?/gi, '');
-}
-
-// Remove the snapshot id attribute used by the hydrate restore phase.  These ids
-// only exist to let the post-Alpine restore step in Puppeteer find each snapshotted
-// element back; they have no purpose in the final output.
-function stripPrerenderHydrateSnapshotIds(html) {
-  return html.replace(/\sdata-manifest-hyd-id(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?/gi, '');
-}
-
 function markPrerenderedManifestComponents(html) {
   return html.replace(/<(x-[a-z][\w-]*)([^>]*)>/gi, (full, tag, attrs) => {
     const a = attrs || '';
     if (/\bdata-pre-rendered\s*=/i.test(a) || /\bdata-processed\s*=/i.test(a)) return full;
-    if (/\bdata-prerender-hydrate\b/i.test(a)) return full; // Inside data-hydrate island — skip
+    // Inside an explicit hydrate island — the runtime will restore its
+    // innerHTML to the authored source, so we must NOT tell the components
+    // processor to skip re-fetching.  Leaving the placeholder unmarked lets
+    // the runtime restoration reinstate the <x-*> tag and the components
+    // plugin processes it normally on load.
+    if (/\bdata-hydrate\b/i.test(a)) return full;
     const spacer = /\S/.test(a) ? ' ' : '';
     return `<${tag}${a}${spacer}data-pre-rendered="1">`;
   });
@@ -1341,8 +1358,6 @@ function generateLocaleVariantHtml({
   // markPrerenderedManifestComponents must run BEFORE stripPrerenderHydrateMarkers so it can
   // detect data-prerender-hydrate markers and skip components inside hydrate islands.
   html = markPrerenderedManifestComponents(html);
-  html = stripPrerenderHydrateMarkers(html);
-  html = stripPrerenderHydrateSnapshotIds(html);
 
   const fileSegments = pathToFileSegments(pathSeg ? '/' + pathSeg : '/');
   html = rewriteHtmlAssetPaths(html, fileSegments.length);
@@ -1725,34 +1740,53 @@ async function runPrerender(config) {
   const tailwindBuilt = runTailwindCliForPrerender(rootResolved, outputResolved, pre);
   const utilityBlocks = [];
 
-  let browser;
-  try {
-    const chromium = await importFromProject('@sparticuz/chromium');
-    const pptr = await importFromProject('puppeteer-core');
-    const executablePath = await chromium.default.executablePath();
-    browser = await pptr.default.launch({
-      args: chromium.default.args,
-      defaultViewport: chromium.default.defaultViewport ?? null,
-      executablePath,
-      headless: chromium.default.headless ?? true,
-      ignoreHTTPSErrors: true,
-    });
-  } catch (serverlessErr) {
-    let puppeteer;
+  // Launch a fresh browser instance.  Chromium is known to accumulate memory
+  // and handle leaks on large prerender runs (we've seen crashes around page
+  // ~230 on sites with hundreds of routes).  The launchBrowser function is
+  // used both for the initial launch AND for periodic recycling — we close
+  // the old browser and start a new one every `browserRecycleEvery` pages to
+  // bound memory growth.
+  async function launchBrowser() {
     try {
-      puppeteer = await importFromProject('puppeteer');
-    } catch {
-      console.error('prerender: missing browser runtime.');
-      console.error('Install one of the following, then rerun:');
-      console.error('  npm i -D puppeteer');
-      console.error('  npm i -D puppeteer-core @sparticuz/chromium');
-      process.exit(1);
+      const chromium = await importFromProject('@sparticuz/chromium');
+      const pptr = await importFromProject('puppeteer-core');
+      const executablePath = await chromium.default.executablePath();
+      return await pptr.default.launch({
+        args: chromium.default.args,
+        defaultViewport: chromium.default.defaultViewport ?? null,
+        executablePath,
+        headless: chromium.default.headless ?? true,
+        ignoreHTTPSErrors: true,
+      });
+    } catch (_serverlessErr) {
+      let puppeteer;
+      try {
+        puppeteer = await importFromProject('puppeteer');
+      } catch {
+        console.error('prerender: missing browser runtime.');
+        console.error('Install one of the following, then rerun:');
+        console.error('  npm i -D puppeteer');
+        console.error('  npm i -D puppeteer-core @sparticuz/chromium');
+        process.exit(1);
+      }
+      return await puppeteer.default.launch({ headless: true });
     }
-    browser = await puppeteer.default.launch({ headless: true });
   }
+  let browser = await launchBrowser();
 
-  const timeout = config.wait ?? 15000;
+  const timeout = config.wait ?? 30000;
+  // Lower default concurrency: Chromium's own memory overhead per page is
+  // substantial, and we also now maintain a per-page source-attribute Map for
+  // the hydration contract.  On large sites (>100 routes) higher concurrency
+  // spikes memory and crashes the browser.  Users can still override via
+  // --concurrency or manifest.prerender.concurrency.
   const concurrency = config.concurrency;
+  const maxRetries = config.retries ?? 2;
+  // Recycle the browser every N processed pages to bound resource growth.
+  // Configurable via manifest.prerender.browserRecycleEvery.
+  const browserRecycleEvery = Math.max(0, pre.browserRecycleEvery ?? 40);
+  let pagesSinceRecycle = 0;
+  const recycleLock = { busy: false };
   const pathTotal = pathList.length;
   const failedPaths = [];
   const debugRows = [];
@@ -1844,6 +1878,11 @@ async function runPrerender(config) {
           : defaultLocale || 'en'
         : defaultLocale || 'en';
 
+    // Refuse to newPage() against a closed browser (happens briefly during
+    // recycle); the worker loop will retry.
+    if (!browser || !browser.connected) {
+      throw new Error('browser not ready');
+    }
     const page = await browser.newPage();
     try {
       // Align <html lang> with the URL being prerendered before any app script runs.
@@ -1865,161 +1904,113 @@ async function runPrerender(config) {
         }
       }, currentLocale);
 
-      // Snapshot pristine source attributes of hydrate-target elements BEFORE Alpine
-      // touches them.  We do this by wrapping `Alpine.initTree` — Alpine calls this
-      // for the initial tree walk AND every time the components plugin lazy-loads a
-      // new <x-*> component.  Right before Alpine processes a subtree, we walk it
-      // and snapshot every hydrate target inside.  This is the exact moment the
-      // user's source HTML is sitting in the DOM with no Alpine mutations applied.
+      // Deterministic source-attribute capture via MutationObserver with
+      // `attributeOldValue`.  This runs before ANY page script and records the
+      // first (pre-mutation) value of every attribute that Alpine or a Manifest
+      // plugin ever touches.  It also records the *initial* attributes of every
+      // new element added to the DOM via childList mutations — so elements
+      // parsed from innerHTML (components, markdown rendering, etc.) are also
+      // captured the moment they appear.
+      //
+      // The observer handles all mutation surfaces at once:
+      //   - setAttribute / removeAttribute
+      //   - className setter
+      //   - classList.add / remove / toggle / replace
+      //   - style.* property assignments (which mutate the style attribute)
+      //   - Any other path that ultimately modifies an attribute
       //
-      // The snapshots are restored in a later page.evaluate call after Alpine
-      // settles.  This is true hydration: Alpine never gets to bake state into
-      // hydrate elements, so every directive (`:class`, `:style`, `x-text`, custom
-      // plugin directives, etc.) works in the prerendered MPA exactly the way it
-      // does in the live SPA — no per-binding strip logic, no cloak band-aids, no
-      // edge cases to chase.
+      // At serialize time we read the map, identify hydrate targets per the
+      // catalog, and emit a compact JSON hydration contract.  The runtime
+      // (`hydratePrerenderedPage` in manifest.js) reads the contract and
+      // restores source attributes before Alpine starts.
       await page.evaluateOnNewDocument(() => {
-        const allSnapshots = [];
-        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();
-            });
+        // element -> { attrName: originalValue (null if attribute was absent) }
+        // Keyed by reference so detached elements drop out naturally.
+        const sourceAttrs = new Map();
+        // element -> original innerHTML (only populated for elements already
+        // marked data-hydrate when we first see them — used for subtree-wide
+        // restoration of explicit hydrate islands).
+        const sourceInnerHTML = new Map();
+
+        const recordInitialAttrs = (el) => {
+          if (!el || el.nodeType !== 1 || sourceAttrs.has(el)) return;
+          const rec = {};
+          const list = el.attributes;
+          for (let i = 0; i < list.length; i++) {
+            rec[list[i].name] = list[i].value;
           }
-        }
-
-        const snapshotElement = (el) => {
-          if (!el || el.nodeType !== 1) return;
-          if (el.hasAttribute('data-manifest-hyd-id')) return; // already snapshotted
-          const id = '__manifest-hyd-' + nextId++;
-          el.setAttribute('data-manifest-hyd-id', id);
-          const attrs = {};
-          for (let i = 0; i < el.attributes.length; i++) {
-            const a = el.attributes[i];
-            if (a.name === 'data-manifest-hyd-id') continue;
-            attrs[a.name] = a.value;
+          sourceAttrs.set(el, rec);
+          if (el.hasAttribute && el.hasAttribute('data-hydrate')) {
+            try { sourceInnerHTML.set(el, el.innerHTML); } catch (_) {}
           }
-          allSnapshots.push({ id, tag: el.tagName, attrs });
         };
 
-        const snapshotElementAndDescendants = (el) => {
-          snapshotElement(el);
-          if (el && el.querySelectorAll) {
-            el.querySelectorAll('*').forEach(snapshotElement);
+        const handleMutations = (mutations) => {
+          for (const m of mutations) {
+            if (m.type === 'attributes') {
+              const el = m.target;
+              let rec = sourceAttrs.get(el);
+              if (!rec) {
+                // First time we see this element AT ALL via an attribute record:
+                // seed with every current attribute so we never lose attrs that
+                // existed before any mutation we happened to observe.
+                rec = {};
+                const list = el.attributes;
+                for (let i = 0; i < list.length; i++) {
+                  rec[list[i].name] = list[i].value;
+                }
+                // Overwrite the one being mutated with the true oldValue
+                // (which may be null if the attribute was absent pre-mutation).
+                rec[m.attributeName] = m.oldValue;
+                sourceAttrs.set(el, rec);
+              } else if (!(m.attributeName in rec)) {
+                rec[m.attributeName] = m.oldValue;
+              }
+            } else if (m.type === 'childList') {
+              for (const node of m.addedNodes) {
+                if (node.nodeType !== 1) continue;
+                recordInitialAttrs(node);
+                if (node.querySelectorAll) {
+                  node.querySelectorAll('*').forEach(recordInitialAttrs);
+                }
+              }
+            }
           }
         };
 
-        const snapshotSubtree = (root) => {
-          if (!root || root.nodeType !== 1) return;
+        const observer = new MutationObserver(handleMutations);
 
-          // 1. Direct data-hydrate roots + descendants within this subtree.
-          const hydrateRoots = [];
-          if (root.matches && root.matches('[data-hydrate]')) hydrateRoots.push(root);
-          if (root.querySelectorAll) {
-            root.querySelectorAll('[data-hydrate]').forEach((el) => hydrateRoots.push(el));
-          }
-          hydrateRoots.forEach(snapshotElementAndDescendants);
-
-          // 2. x-theme elements (color mode plugin needs runtime click handler).
-          if (root.matches && root.matches('[x-theme]')) snapshotElementAndDescendants(root);
-          if (root.querySelectorAll) {
-            root.querySelectorAll('[x-theme]').forEach(snapshotElementAndDescendants);
+        let observing = false;
+        const startObserving = () => {
+          if (observing) return true;
+          // We can observe `document` itself — MutationObserver accepts it as a
+          // target and forwards subtree mutations, so we catch <html> creation
+          // and everything under it without racing the parser.
+          try {
+            observer.observe(document, {
+              attributes: true,
+              attributeOldValue: true,
+              childList: true,
+              subtree: true,
+            });
+            observing = true;
+          } catch (_) { return false; }
+          // Seed whatever already exists.
+          if (document.documentElement) {
+            recordInitialAttrs(document.documentElement);
+            document.documentElement.querySelectorAll('*').forEach(recordInitialAttrs);
           }
-
-          // 3. Propagate from data-hydrate children to nearest LOCAL x-data ancestor
-          //    so the reactive controller, sibling event handlers (@click toggles
-          //    etc.) and all bindings inside the scope are preserved together.
-          //    Skip page-level scopes (main, body, [x-route]).
-          hydrateRoots.forEach((el) => {
-            let ancestor = el.parentElement;
-            while (ancestor && ancestor !== document.body) {
-              if (
-                ancestor.hasAttribute('x-data') &&
-                !skipTags.has(ancestor.tagName) &&
-                !ancestor.hasAttribute('x-route')
-              ) {
-                snapshotElementAndDescendants(ancestor);
-                break;
-              }
-              ancestor = ancestor.parentElement;
-            }
-          });
-
-          window.__manifestHydrateSnapshots = allSnapshots;
+          return true;
         };
+        startObserving();
 
-        // 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;
-          alpine.__manifestRenderWrapped = true;
-          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);
-            };
-          }
+        // Flush any pending mutations before the DOM is read for serialization.
+        window.__manifestFlushHydrateSources = () => {
+          try { handleMutations(observer.takeRecords()); } catch (_) {}
         };
-
-        let _Alpine;
-        try {
-          Object.defineProperty(window, 'Alpine', {
-            configurable: true,
-            enumerable: true,
-            get() { return _Alpine; },
-            set(v) { _Alpine = v; wrap(v); },
-          });
-        } catch (_) { /* defineProperty failed, fall back to event listeners */ }
-
-        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));
-        }
+        // Expose for the contract-emission phase.
+        window.__manifestSourceAttrs = sourceAttrs;
+        window.__manifestSourceInnerHTML = sourceInnerHTML;
       });
 
       pushDebug({ path: displayPath, stage: 'start' });
@@ -2253,88 +2244,154 @@ async function runPrerender(config) {
         });
       });
 
-      // Restore hydrate-target elements to their pristine source attributes
-      // (snapshotted via evaluateOnNewDocument before Alpine ran).  This is true
-      // hydration: every Alpine binding (`:class`, `:style`, `:value`, `x-text`,
-      // `x-init`, custom plugin directives, …) is preserved exactly as authored,
-      // and Alpine processes them at runtime in the prerendered MPA the same way
-      // 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.
+      // Emit the hydration contract: walk the DOM, identify every hydrate
+      // target (explicit `data-hydrate`, interactive Manifest directives,
+      // diff-semantic bindings, runtime-magic-driven bindings), tag each with
+      // `data-hydrate-id`, and collect the diff between each target's source
+      // attributes (recorded by the MutationObserver in evaluateOnNewDocument)
+      // and its current post-render attributes.  The contract is returned as a
+      // JSON-serialisable array; the runtime reads it on page load and restores
+      // source state before Alpine starts.
       //
-      // 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.
+      // For explicit `data-hydrate` roots, the entry also carries the original
+      // innerHTML so the whole subtree is restored to source, not just its
+      // attributes.
       //
-      // 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) { report.notFound++; return; }
-          let depth = 0;
-          for (let p = el.parentNode; p; p = p.parentNode) depth++;
-          items.push({ id, el, attrs, depth });
+      // The catalog here is the authoritative list of "what counts as
+      // interactive" and MUST match the docs/articles surface.
+      const hydrationContractRaw = await page.evaluate(() => {
+        // Drain any mutations not yet delivered to the observer so our source
+        // map has the latest values.
+        try { window.__manifestFlushHydrateSources && window.__manifestFlushHydrateSources(); } catch (_) {}
+
+        const sourceAttrs = window.__manifestSourceAttrs || new Map();
+        const sourceInnerHTML = window.__manifestSourceInnerHTML || new Map();
+
+        // --- CATALOG: what makes an element a hydrate target ---
+        // Interactive Manifest-registered directives that attach click/hover/
+        // observer state at runtime and therefore need the live Alpine scope.
+        const INTERACTIVE_DIRECTIVES = new Set([
+          'x-theme', 'x-dropdown', 'x-tooltip', 'x-tab', 'x-tabpanel',
+          'x-toast', 'x-carousel', 'x-resize', 'x-anchors', 'x-model',
+          'x-files', 'x-data-files',
+        ]);
+        // Runtime-only Alpine magics whose values change after the prerender
+        // snapshot (e.g. via media query, route change, auth state).  Bindings
+        // referencing these must re-evaluate in the live page.
+        const RUNTIME_MAGIC_RX = /\$(theme|locale|url|auth|search|query|toast)\b/;
+
+        const isDiffBindingAttr = (name) =>
+          name === ':class' || name === 'x-bind:class' ||
+          name === ':style' || name === 'x-bind:style';
+
+        const isEventAttr = (name) =>
+          name.charCodeAt(0) === 64 /* @ */ || name.startsWith('x-on:');
+
+        const isBindingAttr = (name) =>
+          name.charCodeAt(0) === 58 /* : */ || name.startsWith('x-bind:') || name.startsWith('x-');
+
+        const classifyElement = (el) => {
+          // Explicit data-hydrate — subtree-wide restoration.
+          if (el.hasAttribute('data-hydrate')) return 'explicit';
+
+          const list = el.attributes;
+          for (let i = 0; i < list.length; i++) {
+            const name = list[i].name;
+            const val = list[i].value;
+
+            if (INTERACTIVE_DIRECTIVES.has(name)) return 'interactive';
+            if (isEventAttr(name)) return 'event';
+            if (isDiffBindingAttr(name)) return 'diff-binding';
+            if (isBindingAttr(name) && val && RUNTIME_MAGIC_RX.test(val)) return 'runtime-magic';
+          }
+          return null;
+        };
+
+        // --- Walk: collect all hydrate targets ---
+        const targets = new Set();
+        const subtreeRoots = new Set(); // explicit roots — restore innerHTML too
+        const all = document.body ? document.body.querySelectorAll('*') : [];
+        all.forEach((el) => {
+          const kind = classifyElement(el);
+          if (!kind) return;
+          if (kind === 'explicit') {
+            subtreeRoots.add(el);
+            targets.add(el);
+            el.querySelectorAll('*').forEach((d) => targets.add(d));
+          } else {
+            targets.add(el);
+          }
         });
-        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) });
+
+        // --- Build contract entries ---
+        let nextId = 0;
+        const entries = [];
+        targets.forEach((el) => {
+          const source = sourceAttrs.get(el);
+          const attrsOut = {};
+          let dirty = false;
+
+          // Collect attributes that DIVERGED from source.  For each current
+          // attribute: if the source recorded a different value (or absent),
+          // we need to restore the source value.
+          const currentAttrs = {};
+          const list = el.attributes;
+          for (let i = 0; i < list.length; i++) {
+            currentAttrs[list[i].name] = list[i].value;
+          }
+
+          if (source) {
+            // For every attribute in source, check if current differs.
+            for (const name in source) {
+              if (name === 'data-hydrate-id') continue;
+              const src = source[name];
+              const cur = name in currentAttrs ? currentAttrs[name] : null;
+              if (src !== cur) {
+                attrsOut[name] = src; // may be null (means "remove this attribute")
+                dirty = true;
+              }
+            }
+            // For current attributes that weren't in source, remove them.
+            for (const name in currentAttrs) {
+              if (name === 'data-hydrate-id') continue;
+              if (!(name in source)) {
+                attrsOut[name] = null;
+                dirty = true;
+              }
+            }
+          }
+          // If no source recorded and it's not an explicit subtree root, the
+          // element had no mutations observed — no restoration needed.
+
+          const innerHTMLSource = sourceInnerHTML.get(el);
+          let innerHTMLEntry;
+          if (subtreeRoots.has(el) && innerHTMLSource !== undefined) {
+            if (innerHTMLSource !== el.innerHTML) {
+              innerHTMLEntry = innerHTMLSource;
+              dirty = true;
+            }
           }
+
+          if (!dirty) return;
+
+          const id = 'h' + nextId++;
+          el.setAttribute('data-hydrate-id', id);
+          const entry = { id, attrs: attrsOut };
+          if (innerHTMLEntry !== undefined) entry.html = innerHTMLEntry;
+          entries.push(entry);
         });
 
-        return report;
+        return entries;
       });
+      // Stash the contract on the route record for HTML injection later.
+      // We carry it through as a string to avoid re-stringifying multiple times.
+      const hydrationContractJSON = JSON.stringify(hydrationContractRaw || []);
       if (config.debugPrerender) {
-        pushDebug({ path: displayPath, stage: 'hydrate-restore', metrics: restoreReport });
+        pushDebug({
+          path: displayPath,
+          stage: 'hydrate-contract',
+          metrics: { entries: (hydrationContractRaw || []).length },
+        });
       }
 
       // x-for lists: keep static lists in the HTML for SEO; collapse only dynamic lists so Alpine re-renders.
@@ -2639,6 +2696,19 @@ async function runPrerender(config) {
       });
 
       let html = await page.evaluate(() => document.documentElement.outerHTML);
+      // Inject the hydration contract blob into the raw HTML *before* caching
+      // it for locale variant generation, so every locale variant inherits the
+      // same contract (locale substitution only mutates visible text, not the
+      // JSON blob).  The same injection happens again later in the Puppeteer
+      // path after Node.js post-processing, but injecting early simplifies the
+      // cache model: "raw HTML carries its own contract."
+      if (hydrationContractJSON && hydrationContractJSON !== '[]') {
+        const safe = hydrationContractJSON.replace(/<\/script/gi, '<\\/script');
+        html = html.replace(
+          '</body>',
+          `<script type="application/json" id="__manifest_hydrate__">${safe}</script>\n</body>`
+        );
+      }
       // Cache raw DOM snapshot for locale variant generation (before any Node.js transforms).
       if (typeof onRawHtml === 'function') onRawHtml(pathSeg, html);
       if (config.debugPrerender) {
@@ -2676,11 +2746,7 @@ async function runPrerender(config) {
       html = stripRedundantImgSrcBindings(html);
       html = stripEmptyInlineMaskStyles(html);
       html = stripResolvedXIconDirectives(html);
-      // markPrerenderedManifestComponents must run BEFORE stripPrerenderHydrateMarkers so it can
-      // detect data-prerender-hydrate markers and skip components inside hydrate islands.
       html = markPrerenderedManifestComponents(html);
-      html = stripPrerenderHydrateMarkers(html);
-      html = stripPrerenderHydrateSnapshotIds(html);
       html = rewriteHtmlAssetPaths(html, fileSegments.length);
       const liveBase = config.liveUrl.replace(/\/$/, '');
       const canonicalHreflang = buildCanonicalAndHreflang(is404 ? '' : pathSeg, locales, defaultLocale, liveBase);
@@ -2699,6 +2765,8 @@ async function runPrerender(config) {
         '</head>',
         `${canonicalHreflang}${injectOgLocale ? ogLocale : ''}${routeMeta}${baseMeta}${prerenderedMeta}<meta name="manifest:router-base-depth" content="${routeDepth}">\n</head>`
       );
+      // (Hydration contract was already injected into the raw HTML before
+      // the Node.js post-processing pipeline ran, so it's already present.)
       mkdirSync(outDir, { recursive: true });
       writeFileSync(outFile, html, 'utf8');
       pushDebug({
@@ -2717,30 +2785,99 @@ async function runPrerender(config) {
         process.stderr.write(`prerender: failed ${displayPath}: ${failedPaths[failedPaths.length - 1].message}\n`);
       }
     } finally {
-      await page.close();
+      try { await page.close(); } catch (_) { /* page may be gone if browser died */ }
     }
   }
 
-  // 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.
+  //
+  // Browser recycling: after every `browserRecycleEvery` successful pages,
+  // all workers pause, one worker closes the browser and launches a fresh
+  // one, then all resume.  This bounds Chromium's memory + handle growth.
   try {
     let index = 0;
+    let activeWorkers = 0;
+    const recycleGate = { resume: null, waitForZero: null };
+
+    const waitUntilZero = () => new Promise((resolve) => {
+      if (activeWorkers === 0) return resolve();
+      recycleGate.waitForZero = resolve;
+    });
+    const waitForResume = () => new Promise((resolve) => {
+      if (!recycleLock.busy) return resolve();
+      const prev = recycleGate.resume;
+      recycleGate.resume = () => { if (prev) prev(); resolve(); };
+    });
+
+    const maybeRecycleBrowser = async () => {
+      if (browserRecycleEvery <= 0) return;
+      if (pagesSinceRecycle < browserRecycleEvery) return;
+      if (recycleLock.busy) return;
+      recycleLock.busy = true;
+      try {
+        // Wait for all in-flight workers to finish their current page.
+        await waitUntilZero();
+        process.stdout.write(`prerender: recycling browser (processed ${pagesSinceRecycle} pages)\n`);
+        try { await browser.close(); } catch (_) {}
+        browser = await launchBrowser();
+        pagesSinceRecycle = 0;
+      } finally {
+        recycleLock.busy = false;
+        const r = recycleGate.resume;
+        recycleGate.resume = null;
+        if (r) r();
+      }
+    };
+
     async function worker() {
       while (true) {
+        // Pause if a recycle is underway.
+        if (recycleLock.busy) await waitForResume();
+
         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;
+          activeWorkers++;
+          try {
+            await processPath(pathSeg, i, {
+              onRawHtml: (seg, html) => {
+                if (seg !== NOT_FOUND_PATH) baseHtmlCache.set(seg || '', html);
+              },
+            });
+          } finally {
+            activeWorkers--;
+            if (activeWorkers === 0 && recycleGate.waitForZero) {
+              const z = recycleGate.waitForZero;
+              recycleGate.waitForZero = null;
+              z();
+            }
+          }
+          if (failedPaths.length === failureCountBefore) {
+            pagesSinceRecycle++;
+            break; // success
+          }
+          if (attempt >= maxRetries) { pagesSinceRecycle++; break; }
+          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));
+        }
+        // Attempt recycle after each completed path (only one worker will
+        // actually perform the recycle; others will be gated by recycleLock).
+        await maybeRecycleBrowser();
       }
     }
     await Promise.all(
       Array.from({ length: Math.min(concurrency, puppeteerPaths.length || 1) }, () => worker())
     );
   } finally {
-    await browser.close();
+    try { await browser.close(); } catch (_) {}
   }
 
   // Phase 2: Node.js — generate locale variants via text substitution

package/package.json

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