mnfst-render 0.4.0 → 0.4.2

package/manifest.render.mjs

@@ -6,6 +6,7 @@ import { readFileSync, readSync, mkdirSync, writeFileSync, existsSync, rmSync, s
 import { spawnSync } from 'node:child_process';
 import { join, resolve, dirname, relative, basename, sep } from 'node:path';
 import { createServer } from 'node:http';
+import { cpus } from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
@@ -23,37 +24,6 @@ async function importFromProject(moduleName) {
   }
 }
 
-/**
- * localechange reloads localized sources asynchronously; waitForNetworkIdle can finish before
- * Alpine.store('data') updates. Without this, x-for / $modify('items') lists often snapshot empty.
- */
-async function waitForAlpineDataStoresSettled(page, timeoutMs = 12000) {
-  const interval = 100;
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const ok = await page
-      .evaluate(() => {
-        try {
-          const Alpine = window.Alpine;
-          if (!Alpine?.store) return true;
-          const d = Alpine.store('data');
-          if (!d) return true;
-          if (d._localeChanging) return false;
-          for (const k of Object.keys(d)) {
-            if (!k.startsWith('_') || !k.endsWith('_state')) continue;
-            const s = d[k];
-            if (s && typeof s === 'object' && s.loading) return false;
-          }
-          return true;
-        } catch {
-          return true;
-        }
-      })
-      .catch(() => true);
-    if (ok) return;
-    await new Promise((r) => setTimeout(r, interval));
-  }
-}
 
 async function flushAlpineEffects(page) {
   await page
@@ -96,86 +66,72 @@ function logicalPathToVisibilityNormalizedPath(pathSeg, locales) {
 }
 
 /**
- * After locale + route sync: run component swapping explicitly, then wait until Alpine data stores
- * are settled. We call ManifestComponentsSwapping.processAll() directly because swapping only
- * subscribes to manifest:route-change if window.ManifestRouting already exists at initialize() time;
- * when the router loads after components, that listener is never registered and no second
- * manifest:components-processed fires.
+ * Set locale, dispatch route/locale events, call component swapping, then wait for
+ * manifest:render-ready — the authoritative signal from the data plugin that all tracked
+ * sources have settled for the active locale.
+ *
+ * Falls back to a timeout if the data plugin is absent or predates manifest:render-ready,
+ * so this is backward-compatible with any Manifest project.
  */
-async function waitForManifestPrerenderPipeline(page, { allLocales, currentLocale, timeoutMs }) {
+async function waitForManifestRenderReady(page, { allLocales, currentLocale, timeoutMs }) {
   const result = await page
     .evaluate(
       async ({ localeList, loc, ms }) => {
-        const sleep = (n) => new Promise((r) => setTimeout(r, n));
-        const deadline = Date.now() + ms;
-
-        const checkData = () => {
-          try {
-            const Alpine = window.Alpine;
-            if (!Alpine?.store) return true;
-            const d = Alpine.store('data');
-            if (!d) return true;
-            if (d._localeChanging) return false;
-            for (const k of Object.keys(d)) {
-              if (!k.startsWith('_') || !k.endsWith('_state')) continue;
-              const s = d[k];
-              if (s && typeof s === 'object' && s.loading) return false;
-            }
-            return true;
-          } catch {
-            return true;
-          }
-        };
-
         try {
           const locales = Array.isArray(localeList) ? localeList : [];
+
+          // 1. Align locale state before dispatching any events.
           if (loc && typeof loc === 'string') {
-            try {
-              document.documentElement.lang = loc;
-            } catch {
-              /* no-op */
-            }
+            try { document.documentElement.lang = loc; } catch { /* no-op */ }
           }
-          const store = typeof Alpine !== 'undefined' && Alpine.store ? Alpine.store('locale') : null;
-          if (store) {
-            if (!Array.isArray(store.available) || store.available.length === 0) {
-              store.available = locales.slice();
+          const localeStore = typeof Alpine !== 'undefined' && Alpine.store
+            ? Alpine.store('locale') : null;
+          if (localeStore) {
+            if (!Array.isArray(localeStore.available) || localeStore.available.length === 0) {
+              localeStore.available = locales.slice();
             } else {
-              store.available = Array.from(new Set([...store.available, ...locales]));
-            }
-            if (loc && typeof loc === 'string') {
-              store.current = loc;
+              localeStore.available = Array.from(new Set([...localeStore.available, ...locales]));
             }
+            if (loc && typeof loc === 'string') localeStore.current = loc;
           }
 
-          if (loc && typeof loc === 'string') {
-            window.dispatchEvent(new CustomEvent('localechange', { detail: { locale: loc } }));
-          }
-
-          const rawRoute = window.ManifestRoutingNavigation?.getCurrentRoute?.() ?? window.location.pathname;
+          // 2. Compute normalised route path (strips locale prefix, matches router logic).
+          const rawRoute = window.ManifestRoutingNavigation?.getCurrentRoute?.()
+            ?? window.location.pathname;
           const clean = String(rawRoute || '/').replace(/^\/+|\/+$/g, '');
           const parts = clean ? clean.split('/') : [];
           const logical =
             parts.length > 0 && locales.includes(parts[0])
               ? '/' + parts.slice(1).join('/')
-              : clean
-                ? '/' + clean
-                : '/';
+              : clean ? '/' + clean : '/';
           const to = logical === '//' ? '/' : logical;
           const normalizedPath =
             typeof to === 'string' && to !== '/' ? to.replace(/^\/|\/$/g, '') : '/';
 
-          window.dispatchEvent(
-            new CustomEvent('manifest:route-change', {
-              detail: {
-                from: to,
-                to,
-                normalizedPath,
-              },
-            })
-          );
+          // 3. Register the manifest:render-ready listener BEFORE dispatching events so we
+          //    never miss a fast-settling response. Falls back to timeout for older data plugins.
+          const renderReadyPromise = new Promise((resolve) => {
+            const onReady = (e) => resolve({ ok: true, locale: e.detail?.locale });
+            window.addEventListener('manifest:render-ready', onReady, { once: true });
+            setTimeout(() => {
+              window.removeEventListener('manifest:render-ready', onReady);
+              resolve({ ok: false, reason: 'timeout' });
+            }, ms);
+          });
+
+          // 4. Dispatch locale change — triggers localized source reloads in the data plugin.
+          if (loc && typeof loc === 'string') {
+            window.dispatchEvent(new CustomEvent('localechange', { detail: { locale: loc } }));
+          }
+
+          // 5. Dispatch route change — ensures router visibility and head content are current.
+          window.dispatchEvent(new CustomEvent('manifest:route-change', {
+            detail: { from: to, to, normalizedPath },
+          }));
           window.dispatchEvent(new PopStateEvent('popstate'));
 
+          // 6. Run component swapping explicitly so components tied to this route render
+          //    and trigger any $x accesses that start on-demand data loads.
           if (window.ManifestComponentsSwapping?.processAll) {
             try {
               await window.ManifestComponentsSwapping.processAll(normalizedPath);
@@ -184,33 +140,18 @@ async function waitForManifestPrerenderPipeline(page, { allLocales, currentLocal
             }
           }
 
-          while (Date.now() < deadline) {
-            if (checkData()) {
-              return { ok: true };
-            }
-            await sleep(50);
-          }
-          return {
-            ok: false,
-            reason: 'timeout',
-            dataOk: checkData(),
-            hadSwapping: !!window.ManifestComponentsSwapping?.processAll,
-          };
+          // 7. Await the authoritative signal (or timeout fallback).
+          return await renderReadyPromise;
         } catch (err) {
           return { ok: false, reason: 'error', message: String(err?.message || err) };
         }
       },
-      {
-        localeList: allLocales,
-        loc: currentLocale,
-        ms: timeoutMs,
-      }
+      { localeList: allLocales, loc: currentLocale, ms: timeoutMs }
     )
     .catch((e) => ({ ok: false, reason: 'evaluate', message: String(e) }));
 
   if (!result?.ok) {
-    const parts = [`prerender: pipeline wait incomplete (${result?.reason ?? 'unknown'})`];
-    if (result?.dataOk === false) parts.push('data still loading');
+    const parts = [`prerender: render-ready wait incomplete (${result?.reason ?? 'unknown'})`];
     if (result?.message) parts.push(result.message);
     process.stdout.write(`${parts.join('; ')}\n`);
   }
@@ -289,7 +230,14 @@ function resolveConfig() {
     redirects: Array.isArray(pre.redirects) ? pre.redirects : [],
     wait: cli.wait ?? pre.wait ?? null,
     waitAfterIdle: Math.max(0, cli.waitAfterIdle ?? pre.waitAfterIdle ?? 0),
-    concurrency: Math.max(1, cli.concurrency ?? pre.concurrency ?? 6),
+    concurrency: Math.max(1, cli.concurrency ?? pre.concurrency ?? Math.max(4, cpus().length - 1)),
+    /** Default: generate locale variant pages via Node.js text substitution rather than Puppeteer.
+     *  Set manifest.prerender.localeSubstitution=false to always use Puppeteer for every locale. */
+    localeSubstitution: pre.localeSubstitution !== false,
+    /** Locales to always render with Puppeteer even when localeSubstitution is enabled (e.g. RTL). */
+    localeSubstitutionExclude: Array.isArray(pre.localeSubstitutionExclude)
+      ? pre.localeSubstitutionExclude.map(String)
+      : [],
     dryRun: !!cli.dryRun,
     debugPrerender: !!(cli.debugPrerender ?? pre.debugPrerender),
     pipelineTimeout: Math.max(3000, Number(pre.pipelineTimeout) || 25000),
@@ -1168,6 +1116,185 @@ function hasOtherOgMeta(html) {
   return /<meta[^>]*property="og:(?!locale(?::alternate)?")[^"]*"[^>]*>/i.test(html);
 }
 
+// --- Locale text substitution (Node.js post-processing — no Puppeteer for locale variants) ------
+
+/**
+ * Load the key→value content data for every locale from every CSV that has locale columns.
+ * Returns Map<locale, { key: value }>.
+ */
+function loadAllLocaleContentData(manifest, rootDir, locales) {
+  const data = manifest?.data;
+  if (!data || typeof data !== 'object') return new Map();
+
+  const csvFiles = [];
+  const seen = new Set();
+  const addCsv = (ref) => {
+    if (typeof ref !== 'string' || !ref.endsWith('.csv')) return;
+    const p = join(rootDir, ref.startsWith('/') ? ref.slice(1) : ref);
+    if (!seen.has(p)) { seen.add(p); csvFiles.push(p); }
+  };
+
+  for (const [, value] of Object.entries(data)) {
+    if (typeof value === 'string') { addCsv(value); continue; }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      if (value.locales) {
+        const refs = Array.isArray(value.locales) ? value.locales : [value.locales];
+        refs.forEach(addCsv);
+      }
+    }
+  }
+
+  const result = new Map();
+  for (const locale of locales) {
+    const merged = {};
+    for (const csvPath of csvFiles) {
+      Object.assign(merged, parseCsvToKeyValue(csvPath, locale));
+    }
+    result.set(locale, merged);
+  }
+  return result;
+}
+
+/**
+ * Build [[defaultValue, targetValue], ...] replacement pairs sorted longest-first.
+ * Skips empty strings and identical pairs to reduce noise.
+ */
+function buildSubstitutionPairs(defaultLocaleData, targetLocaleData) {
+  const pairs = [];
+  for (const [key, rawDefault] of Object.entries(defaultLocaleData)) {
+    const rawTarget = targetLocaleData[key];
+    if (rawTarget == null || rawDefault == null) continue;
+    const from = String(rawDefault).trim();
+    const to = String(rawTarget).trim();
+    if (!from || from === to) continue;
+    pairs.push([from, to]);
+  }
+  pairs.sort((a, b) => b[0].length - a[0].length);
+  return pairs;
+}
+
+/**
+ * Apply locale text substitution to rendered HTML.
+ * Replaces content in text nodes (between > and <) and in key attributes:
+ * content, alt, title, placeholder, aria-label.
+ */
+function applyLocaleSubstitution(html, pairs) {
+  if (!pairs || !pairs.length) return html;
+
+  // 1. Text nodes: walk content between '>' and '<'
+  let out = '';
+  let pos = 0;
+  while (pos < html.length) {
+    const gtPos = html.indexOf('>', pos);
+    if (gtPos === -1) { out += html.slice(pos); break; }
+    const ltPos = html.indexOf('<', gtPos + 1);
+    if (ltPos === -1) { out += html.slice(pos); break; }
+    out += html.slice(pos, gtPos + 1);
+    let text = html.slice(gtPos + 1, ltPos);
+    if (text.trim()) {
+      for (const [from, to] of pairs) {
+        if (text.includes(from)) text = text.split(from).join(to);
+      }
+    }
+    out += text;
+    pos = ltPos;
+  }
+
+  // 2. Selected attributes that carry visible text
+  out = out.replace(
+    /(\s(?:content|alt|title|placeholder|aria-label)=["'])([^"']*)(['"])/g,
+    (match, prefix, val, suffix) => {
+      let v = val;
+      for (const [from, to] of pairs) {
+        if (v.includes(from)) v = v.split(from).join(to);
+      }
+      return `${prefix}${v}${suffix}`;
+    }
+  );
+
+  return out;
+}
+
+/**
+ * Generate a locale variant's HTML entirely in Node.js from a cached base-path DOM snapshot.
+ * Applies text substitution then the full Node.js post-processing pipeline.
+ * Returns { html, utilityBlocks }.
+ */
+function generateLocaleVariantHtml({
+  rawHtml, pathSeg, targetLocale, locales, defaultLocale,
+  config, manifest, routerBasePath, tailwindBuilt, bundleUtilities,
+  substitutionPairs,
+}) {
+  let html = rawHtml;
+
+  // Update lang attribute before resolveHeadXBindings so it sees the right locale
+  html = html.replace(/(<html\b[^>]*)\s+lang=["'][^"']*["']/i, `$1 lang="${targetLocale}"`);
+  if (!/<html\b[^>]*\slang=/i.test(html)) {
+    html = html.replace(/(<html\b)/i, `$1 lang="${targetLocale}"`);
+  }
+
+  // Apply locale text substitution
+  html = applyLocaleSubstitution(html, substitutionPairs);
+
+  // Standard Node.js post-processing (same sequence as processPath)
+  html = stripDevOnlyContent(html);
+  html = stripInjectedPluginScripts(html);
+  if (tailwindBuilt) html = stripRuntimeTailwindArtifacts(html);
+
+  const pageUtilityBlocks = [];
+  if (bundleUtilities) {
+    const extracted = extractUtilityStyleBlocks(html);
+    html = extracted.html;
+    for (const b of extracted.blocks) pageUtilityBlocks.push(b);
+  }
+
+  if (tailwindBuilt) {
+    html = injectBeforeHeadClose(
+      html,
+      `<link rel="stylesheet" href="${buildRootAssetPath(routerBasePath, 'prerender.tailwind.css')}">`
+    );
+  }
+
+  html = stripDuplicatedLoopDirectives(html);
+  html = stripPrerenderedXDataDirectives(html);
+
+  const content = loadContentForPrerender(manifest, config.root, targetLocale);
+  html = resolveHeadXBindings(html, { manifest, content });
+
+  html = stripPrerenderDynamicBindings(html);
+  html = stripPrerenderBakedRadioCheckedForXModel(html);
+  html = stripRedundantImgSrcBindings(html);
+  html = stripEmptyInlineMaskStyles(html);
+  html = stripResolvedXIconDirectives(html);
+  html = stripPrerenderHydrateMarkers(html);
+
+  const fileSegments = pathToFileSegments(pathSeg ? '/' + pathSeg : '/');
+  html = rewriteHtmlAssetPaths(html, fileSegments.length);
+
+  const liveBase = config.liveUrl.replace(/\/$/, '');
+  const canonicalHreflang = buildCanonicalAndHreflang(pathSeg, locales, defaultLocale, liveBase);
+  const ogLocale = buildOgLocale(pathSeg, locales, defaultLocale);
+  const injectOgLocale = ogLocale && hasOtherOgMeta(html);
+  if (injectOgLocale) html = stripOgLocaleFromHead(html);
+
+  const routeEx = config.localeRouteExclude || [];
+  const routeMeta = routeEx.length > 0
+    ? `<meta name="manifest:locale-route-exclude" content="${JSON.stringify(routeEx).replace(/"/g, '&quot;')}">\n`
+    : '';
+  const baseMeta = routerBasePath !== null
+    ? `<meta name="manifest:router-base" content="${String(routerBasePath).replace(/"/g, '&quot;')}">\n`
+    : '';
+  const routeDepth = fileSegments.length;
+
+  html = html.replace(
+    '</head>',
+    `${canonicalHreflang}${injectOgLocale ? ogLocale : ''}${routeMeta}${baseMeta}<meta name="manifest:prerendered" content="1">\n<meta name="manifest:router-base-depth" content="${routeDepth}">\n</head>`
+  );
+  html = markPrerenderedManifestComponents(html);
+
+  return { html, utilityBlocks: pageUtilityBlocks };
+}
+
 // --- Resolve $x bindings in <head> (data-head meta/link are injected with :attr="$x.path" but never evaluated) ---
 
 function loadContentForPrerender(manifest, rootDir, locale) {
@@ -1546,18 +1673,83 @@ async function runPrerender(config) {
   const pathTotal = pathList.length;
   const failedPaths = [];
   const debugRows = [];
-  process.stdout.write(`Prerendering ${pathTotal} path(s)...\n`);
+
+  // --- Two-phase rendering: Puppeteer for base paths, Node.js substitution for locale variants ---
+  // Categorise paths: locale-prefixed paths (en/about, fr/about, ...) are "locale variants"
+  // and can be generated from the corresponding base path's DOM snapshot + text substitution.
+  // This eliminates Puppeteer for every locale × route combination beyond the base routes.
+  const localeSubstEnabled = config.localeSubstitution;
+  const localeSubstExclude = new Set(config.localeSubstitutionExclude || []);
+  const puppeteerPaths = [];
+  const localeVariantPaths = []; // { pathSeg, basePathSeg, targetLocale }
+
+  // Two-pass categorisation: locale substitution only applies when the locale-neutral base path
+  // (e.g. 'about' for 'fr/about') is itself in the path list and will be Puppeteer-rendered.
+  //
+  // Paths whose data is inherently locale-specific (e.g. 'en/articles/slug', 'fr/articles/slug'
+  // discovered from per-locale data sources) have no locale-neutral counterpart and must be
+  // rendered by Puppeteer directly — their content differs per locale and substitution cannot
+  // produce correct output. This mirrors the framework's own data model: locale-neutral paths
+  // use a shared structure with CSV text overlay; locale-prefixed paths carry per-locale content.
+
+  // Pass 1: collect all locale-neutral path segments (no locale prefix in the first segment).
+  const localeNeutralPathSet = new Set();
+  for (const seg of pathList) {
+    if (!seg || seg === NOT_FOUND_PATH) continue;
+    if (!localeSet.has(seg.split('/')[0])) localeNeutralPathSet.add(seg);
+  }
+
+  // Pass 2: categorise.
+  for (const seg of pathList) {
+    if (!localeSubstEnabled || seg === NOT_FOUND_PATH || !seg) {
+      puppeteerPaths.push(seg);
+      continue;
+    }
+    const fp = seg.split('/')[0];
+    if (!localeSet.has(fp) || localeSubstExclude.has(fp)) {
+      puppeteerPaths.push(seg);
+      continue;
+    }
+    const basePathSeg = seg.slice(fp.length + 1) || '';
+    if (localeNeutralPathSet.has(basePathSeg)) {
+      // Locale-neutral base exists and will be Puppeteer-rendered → safe to substitute.
+      localeVariantPaths.push({ pathSeg: seg, basePathSeg, targetLocale: fp });
+    } else {
+      // No locale-neutral base — this path has per-locale content; Puppeteer required.
+      puppeteerPaths.push(seg);
+    }
+  }
+
+  // Preload locale data for text substitution (all CSV sources with locale columns)
+  const allLocaleData = loadAllLocaleContentData(manifest, config.root, locales);
+  const substitutionMaps = new Map(); // locale → [[from, to], ...]
+  for (const locale of locales) {
+    if (locale === defaultLocale) {
+      substitutionMaps.set(locale, []); // default locale: no text substitution needed
+    } else {
+      substitutionMaps.set(locale, buildSubstitutionPairs(
+        allLocaleData.get(defaultLocale) || {},
+        allLocaleData.get(locale) || {}
+      ));
+    }
+  }
+
+  // baseHtmlCache: base path segment → raw DOM HTML captured before any Node.js transforms
+  const baseHtmlCache = new Map();
+  const puppeteerTotal = puppeteerPaths.length;
+
+  process.stdout.write(`Prerendering ${pathTotal} path(s) (${puppeteerTotal} via Puppeteer, ${localeVariantPaths.length} via substitution)...\n`);
 
   function pushDebug(row) {
     if (!config.debugPrerender) return;
     debugRows.push(row);
   }
 
-  async function processPath(pathSeg, pathIndex) {
+  async function processPath(pathSeg, pathIndex, { onRawHtml } = {}) {
     const is404 = pathSeg === NOT_FOUND_PATH;
     const pathname = is404 ? `/${NOT_FOUND_PATH}` : (pathSeg ? `/${pathSeg}` : '/');
     const displayPath = pathSeg === '' ? '/' : pathname;
-    process.stdout.write(`  [ ${pathIndex + 1}/${pathTotal} ] ${displayPath}\n`);
+    process.stdout.write(`  [ ${pathIndex + 1}/${puppeteerTotal} ] ${displayPath}\n`);
     const url = `${config.localUrl}${pathname}`;
     const fileSegments = is404 ? [] : pathToFileSegments(pathSeg ? `/${pathSeg}` : '/');
     const outDir = is404 ? config.output : join(config.output, ...fileSegments);
@@ -1646,16 +1838,16 @@ async function runPrerender(config) {
         });
       }).catch(() => { });
 
-      // Locale + route sync, then wait for manifest:components-processed (swapping) and settled data stores
-      // before snapshot. Listener is installed inside the page before dispatch (see waitForManifestPrerenderPipeline).
-      await waitForManifestPrerenderPipeline(page, {
+      // Set locale, dispatch route/locale events, call component swapping, then wait for
+      // manifest:render-ready — the single authoritative signal that all data sources have
+      // settled for this locale/route. Falls back to timeout for older data plugins.
+      await waitForManifestRenderReady(page, {
         allLocales: locales,
         currentLocale,
         timeoutMs: config.pipelineTimeout,
       });
 
-      await page.waitForNetworkIdle({ idleTime: 800, timeout: 12000 }).catch(() => { });
-      await waitForAlpineDataStoresSettled(page, 10000);
+      // Flush any remaining Alpine microtask effects after the render-ready signal.
       await flushAlpineEffects(page);
 
       if (config.debugPrerender) {
@@ -2066,6 +2258,8 @@ async function runPrerender(config) {
       });
 
       let html = await page.evaluate(() => document.documentElement.outerHTML);
+      // Cache raw DOM snapshot for locale variant generation (before any Node.js transforms).
+      if (typeof onRawHtml === 'function') onRawHtml(pathSeg, html);
       if (config.debugPrerender) {
         const post = await page.evaluate(() => {
           const templates = document.querySelectorAll('template[x-for]').length;
@@ -2143,22 +2337,65 @@ async function runPrerender(config) {
     }
   }
 
+  // Phase 1: Puppeteer — render base paths, cache raw DOM for substitution
   try {
     let index = 0;
     async function worker() {
       while (true) {
         const i = index++;
-        if (i >= pathList.length) return;
-        await processPath(pathList[i], i);
+        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);
+          },
+        });
       }
     }
     await Promise.all(
-      Array.from({ length: Math.min(concurrency, pathList.length) }, () => worker())
+      Array.from({ length: Math.min(concurrency, puppeteerPaths.length || 1) }, () => worker())
     );
   } finally {
     await browser.close();
   }
 
+  // Phase 2: Node.js — generate locale variants via text substitution
+  if (localeVariantPaths.length > 0) {
+    process.stdout.write(`  Generating ${localeVariantPaths.length} locale variant(s) via text substitution...\n`);
+    let substIndex = 0;
+    for (const { pathSeg, basePathSeg, targetLocale } of localeVariantPaths) {
+      substIndex++;
+      const rawHtml = baseHtmlCache.get(basePathSeg);
+      if (!rawHtml) {
+        // Base path was expected to be Puppeteer-rendered but is absent — its render likely failed.
+        failedPaths.push({ path: '/' + pathSeg, message: `base path "${basePathSeg || '/'}" missing from cache (did its Puppeteer render fail?)` });
+        process.stderr.write(`prerender: skipped /${pathSeg} — base "${basePathSeg || '/'}" not in cache\n`);
+        continue;
+      }
+
+      const displayPath = '/' + pathSeg;
+      process.stdout.write(`  [subst ${substIndex}/${localeVariantPaths.length}] ${displayPath}\n`);
+
+      try {
+        const pairs = substitutionMaps.get(targetLocale) || [];
+        const { html, utilityBlocks: pageBlocks } = generateLocaleVariantHtml({
+          rawHtml, pathSeg, targetLocale, locales, defaultLocale,
+          config, manifest, routerBasePath, tailwindBuilt, bundleUtilities,
+          substitutionPairs: pairs,
+        });
+        for (const b of pageBlocks) utilityBlocks.push(b);
+
+        const fileSegments = pathToFileSegments(pathSeg ? '/' + pathSeg : '/');
+        const outDir = join(config.output, ...fileSegments);
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(join(outDir, 'index.html'), html, 'utf8');
+      } catch (err) {
+        failedPaths.push({ path: displayPath, message: err?.message ?? String(err) });
+        process.stderr.write(`prerender: substitution failed ${displayPath}: ${failedPaths[failedPaths.length - 1].message}\n`);
+      }
+    }
+  }
+
   if (failedPaths.length > 0) {
     const sample = failedPaths.slice(0, 5).map((f) => `${f.path}: ${f.message}`).join(' | ');
     throw new Error(`prerender failed for ${failedPaths.length}/${pathTotal} paths. Sample: ${sample}`);

package/package.json

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