prestruct 0.0.0-stage → 1.0.0

package/engine/scripts/prerender.js

@@ -0,0 +1,726 @@
+/**
+ * scripts/prerender.js
+ * ====================
+ * Canonical engine source (engine/scripts/prerender.js). Deployed copies at
+ * scripts/prerender.js in init/ and example/ are generated byte-identically by
+ * scripts/sync-engine.mjs -- edit the engine, never the copies.
+ *
+ * Runs after `vite build && node scripts/inject-brand.js` via `npm run build`.
+ * Uses Vite's ssrLoadModule to render each route to static HTML.
+ *
+ * Why ssrLoadModule instead of `vite build --ssr`:
+ *   ssrLoadModule resolves all imports through Vite's unified module registry.
+ *   This guarantees a single instance of react-router-dom -- StaticRouter and
+ *   Routes share the same context, so location propagates correctly.
+ *   A compiled SSR bundle would silently render every route as '/' with no error.
+ *   See AGENTS.md for the full root cause analysis.
+ *
+ * Module surface (importable for tests; CLI logic only runs when executed):
+ *   replaceRootDiv(shell, appHtml)  -- root-div injector, attribute-tolerant
+ *   injectMeta(html, meta, routePath, siteUrl, ogImage)
+ *   generateSitemap(routes, siteUrl)
+ *   generate404(shell, config, siteUrl)
+ *   readCache() / writeCache(cache) / cleanCache()
+ *   prerender()                     -- full pipeline
+ *
+ * Output (for a 3-route app with /, /about, /contact):
+ *   dist/index.html           -> /
+ *   dist/about/index.html     -> /about
+ *   dist/contact/index.html   -> /contact
+ *   dist/404.html             -> served by CF Pages for unmatched routes (HTTP 404)
+ *   dist/sitemap.xml          -> replaces the static one from public/
+ *
+ * Failure policy: exits 0 on fatal error so CF Pages deploy continues as SPA.
+ * Set PRESTRUCT_STRICT=1 to make config-validation failures exit 1 (local CI use).
+ */
+
+import fs   from 'fs'
+import path from 'path'
+import crypto from 'crypto'
+import { fileURLToPath, pathToFileURL } from 'url'
+
+import { validateConfig, formatDiagnostics } from './validate-config.js'
+
+// Root-package re-export: `import { defineConfig } from 'prestruct'`
+// (binding stays out of this file's scope to avoid an unused-import)
+export { defineConfig } from './validate-config.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ROOT      = path.resolve(__dirname, '..')
+
+// Rooted-path derivation: the npm CLI passes the USER PROJECT's root;
+// deployed template copies call without opts and get their own project root.
+/**
+ * Resolve the engine's working paths from an explicit root.
+ *
+ * @param {string} [root=ROOT] - host project root (defaults to the engine package)
+ * @returns {{root: string, dist: string, cacheDir: string, cacheFile: string}} paths
+ */
+export function enginePaths(root = ROOT) {
+  return {
+    root,
+    dist: path.join(root, 'dist'),
+    cacheDir: path.join(root, '.prestruct', 'cache'),
+    cacheFile: path.join(root, '.prestruct', 'cache', 'routes.json'),
+  }
+}
+
+// -- Replacement safety --------------------------------------------------------
+// Prevent regex backreference expansion ($1, $2, ...) when dynamic values are
+// used in replacement strings.
+
+/**
+ * Neutralize replacement-pattern characters ($&, $1, ...) so a string can
+ * safely be used as the replacement side of String.prototype.replace().
+ *
+ * @param {string} s - arbitrary generated content
+ * @returns {string} replacement-safe text
+ */
+export function escapeReplacement(s) {
+  return String(s || '').replace(/\$/g, '$$$$')
+}
+
+// HTML attribute/text escaping for values landed in the baked HTML by
+// injectMeta and generate404. Route meta titles/descriptions/OG images are
+// operator config today, but CSM-fed configs interpolate third-party data --
+// a `"` in a description silently breaks the attribute, and a `</title>` in a
+// title injects markup into every baked page. Escape BEFORE $-escaping: the
+// latter only handles replace() semantics.
+/**
+ * Escape HTML-significant characters (& < > " ') for text and attribute contexts.
+ *
+ * @param {string} s - raw meta/OG value
+ * @returns {string} escaped value
+ */
+export function escapeHtml(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+// -- Cache-entry validity (stale-cache fix) ---------------------------------
+// The old skip was path-keyed only: `if (!force && cache[route.path])` -- a
+// changed shell (new vite asset hashes, meta edits, deploy-id) or changed
+// route meta did NOT invalidate, and the loop happily rewrote yesterday's
+// HTML over today's build. Real fix: every cache entry carries a
+// signature over every rendered input -- the shell, the siteUrl, and the
+// route's own meta/ogImage -- and a hit only counts when the signature
+// matches. Entries written before signatures exist (no `sig` field) count
+// as stale and get rerendered once, then upgraded in place.
+//
+// The helper is exported (not inlined in the loop) so the battery can pin
+// the stale-path without running the whole vite pipeline.
+// The helper is exported (not inlined in the loop) so the battery can pin
+// the stale path without running the whole vite pipeline.
+/**
+ * Compute the cache signature for a route render. Covers every input whose
+ * change invalidates the cached HTML: route meta, siteUrl, and the shell.
+ *
+ * @param {{path: string, meta?: object}} route - route definition
+ * @param {string} siteUrl - configured site origin
+ * @param {string} shell - dist/index.html contents
+ * @returns {string} stable hash signature
+ */
+export function cacheSignature(route, siteUrl, shell) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    path: route.path,
+    siteUrl,
+    meta: route.meta ?? null,
+    ogImage: route.ogImage ?? null,
+    shell,
+  })).digest('hex')
+}
+
+/**
+ * Whether a cached entry may be reused for a route. Legacy entries (no
+ * signature) always miss to render once and upgrade.
+ *
+ * @param {{sig?: string}} entry - cached entry or undefined
+ * @param {{path: string, meta?: object}} route - current route definition
+ * @param {string} siteUrl - configured site origin
+ * @param {string} shell - current dist/index.html contents
+ * @returns {boolean} true when the cache may be reused
+ */
+export function cacheEntryValid(entry, route, siteUrl, shell) {
+  if (!entry || typeof entry !== 'object' || typeof entry.html !== 'string') return false
+  // Legacy entries predate signatures: treat as stale once, rerender, and
+  // the write below upgrades them in place.
+  if (!entry.sig) return false
+  return entry.sig === cacheSignature(route, siteUrl, shell)
+}
+
+// -- Root-div injection (W8 fix) -----------------------------------------------
+// Attribute-tolerant: inject-brand.js may add its own attrs to the root div
+// (e.g. data-deploy-id-footer when config.deployIdFooter is true). This
+// matcher therefore matches <div id="root">, <div id="root" ...attrs>, and
+// carries existing attrs into the SSR output so they survive prerendering.
+
+/**
+ * Swap the shell's root div for one stamped with data-server-rendered and
+ * carrying the prerendered markup. Uses a function replacer so $-shaped
+ * content in appHtml stays literal.
+ *
+ * @param {string} shell - dist/index.html contents
+ * @param {string} appHtml - renderToString output for the route
+ * @returns {string} full HTML document for the route
+ * @throws when the shell has no root div
+ */
+export function replaceRootDiv(shell, appHtml) {
+  const match = shell.match(/<div id="root"([^>]*)><\/div>/)
+  if (!match) {
+    throw new Error('<div id="root"></div> not found in shell -- check index.html')
+  }
+  const existing = match[1].replace(/\s+$/, '')
+  const attrs = existing ? `${existing} data-server-rendered="true"` : ' data-server-rendered="true"'
+  // appHtml MUST be $-escaped: it is okay for route content to contain
+  // "$1"/"$&"-shaped text (prices, code samples, quotes) and the second
+  // argument to replace() would expand those into capture references,
+  // mangling the SSR output. Same lesson as the $120 meta-description bug.
+  return shell.replace(
+    /<div id="root"[^>]*><\/div>/,
+    () => `<div id="root"${attrs}>${appHtml}</div>`
+  )
+}
+
+// -- Meta injection ------------------------------------------------------------
+
+/**
+ * Stamp per-route title/description/canonical/OG onto prerendered HTML.
+ * Derives the canonical URL from siteUrl + routePath (no trailing slash for
+ * the home route) and falls back to the global ogImage.
+ *
+ * @param {string} html - prerendered document
+ * @param {{title?: string, description?: string, ogImage?: string}} meta - route meta
+ * @param {string} routePath - '/'-prefixed route path
+ * @param {string} siteUrl - configured site origin (no trailing slash)
+ * @param {?string} globalOgImage - config-level ogImage fallback
+ * @returns {string} updated html
+ */
+export function injectMeta(html, meta, routePath, siteUrl, globalOgImage) {
+  const title   = escapeReplacement(escapeHtml(meta.title))
+  const desc    = escapeReplacement(escapeHtml(meta.description))
+  const ogImage = escapeReplacement(escapeHtml(meta.ogImage || globalOgImage || ''))
+  const url     = escapeReplacement(escapeHtml(`${siteUrl}${routePath === '/' ? '' : routePath}`))
+
+  if (title) {
+    html = html.replace(/<title>[^<]*<\/title>/,                                     `<title>${title}</title>`)
+    html = html.replace(/(<meta\s+property="og:title"\s+content=")[^"]*(")/s,        `$1${title}$2`)
+    html = html.replace(/(<meta\s+name="twitter:title"\s+content=")[^"]*(")/s,       `$1${title}$2`)
+  }
+  if (desc) {
+    html = html.replace(/(<meta\s+name="description"\s+content=")[^"]*(")/s,         `$1${desc}$2`)
+    html = html.replace(/(<meta\s+property="og:description"\s+content=")[^"]*(")/s,  `$1${desc}$2`)
+    html = html.replace(/(<meta\s+name="twitter:description"\s+content=")[^"]*(")/s, `$1${desc}$2`)
+  }
+  html = html.replace(/(<meta\s+property="og:url"\s+content=")[^"]*(")/s,            `$1${url}$2`)
+  html = html.replace(/(<link\s+rel="canonical"\s+href=")[^"]*(")/s,                 `$1${url}$2`)
+  if (ogImage) {
+    html = html.replace(/(<meta\s+property="og:image"\s+content=")[^"]*(")/s,        `$1${ogImage}$2`)
+    html = html.replace(/(<meta\s+name="twitter:image"\s+content=")[^"]*(")/s,       `$1${ogImage}$2`)
+  }
+
+  return html
+}
+
+// -- Incremental cache ---------------------------------------------------------
+
+/**
+ * Read the incremental cache map from disk (empty object when absent/corrupt).
+ *
+ * @param {{cacheFile?: string}} [opts] - explicit cache file path override
+ * @returns {Record<string, {html: string, time: number, sig?: string}>} cache map
+ */
+export function readCache({ cacheFile = enginePaths().cacheFile } = {}) {
+  try {
+    if (fs.existsSync(cacheFile)) {
+      return JSON.parse(fs.readFileSync(cacheFile, 'utf8'))
+    }
+  } catch {}
+  return {}
+}
+
+/**
+ * Persist the incremental cache map (creating the cache dir as needed).
+ *
+ * @param {Record<string, object>} cache - route-keyed cached entries
+ * @param {{cacheDir?: string, cacheFile?: string}} [opts] - path overrides
+ * @returns {void}
+ */
+export function writeCache(cache, { cacheDir = enginePaths().cacheDir, cacheFile = enginePaths().cacheFile } = {}) {
+  fs.mkdirSync(cacheDir, { recursive: true })
+  fs.writeFileSync(cacheFile, JSON.stringify(cache, null, 2))
+}
+
+/**
+ * Reset the incremental cache. Contract: reset-to-empty (writes `{}`), never
+ * deletion -- a custom cacheFile's directory is created if missing so the
+ * file never dangles, and the next build treats the empty map as fresh.
+ *
+ * @param {{cacheFile?: string}} [opts] - explicit cache file path override
+ * @returns {void}
+ */
+export function cleanCache({ cacheFile = enginePaths().cacheFile } = {}) {
+  // Directory is derived from the file path so a custom cacheFile can never
+  // point at a directory that was not created.
+  fs.mkdirSync(path.dirname(cacheFile), { recursive: true })
+  fs.writeFileSync(cacheFile, '{}')
+  console.log('[prerender] Cache cleared')
+}
+
+// -- Sitemap -------------------------------------------------------------------
+
+/**
+ * Generate robots.txt when config.robots is opted in; otherwise null so the
+ * author's own public/robots.txt is left untouched. The Sitemap: line points
+ * at the freshly written sitemap.
+ *
+ * @param {object} config - full ssr.config.js export
+ * @returns {?string} robots.txt contents, or null when not opted in
+ */
+export function generateRobots(config) {
+  const cfg = config?.robots || null
+  // No config.robots = existing public/robots.txt stays authorable; we never
+  // touch dist/robots.txt in that case.
+  if (!cfg) return null
+
+  const cfgBool    = cfg === true
+  const cfgBody    = typeof cfg === 'string' ? cfg : (cfg.body || '')
+  const cfgSitemap = cfgBool || (cfg && typeof cfg === 'object' ? cfg.sitemap !== false : true)
+  const siteUrl    = (config.siteUrl || '').replace(/\/$/, '')
+
+  if (cfgBool) {
+    const lines = [
+      'User-agent: *',
+      'Allow: /',
+    ]
+    if (cfgSitemap && siteUrl) {
+      lines.push('', `Sitemap: ${siteUrl}/sitemap.xml`)
+    }
+    return lines.join('\n') + '\n'
+  }
+
+  // Custom body; sitemap pointer appended unless { sitemap: false }
+  return cfgSitemap && siteUrl
+    ? `${cfgBody.trimEnd()}\n\nSitemap: ${siteUrl}/sitemap.xml\n`
+    : `${cfgBody.trimEnd()}\n`
+}
+
+/**
+ * Escape XML-significant characters for sitemap/RSS payloads.
+ *
+ * @param {string} unsafe - raw value
+ * @returns {string} XML-safe value
+ */
+export function escapeXml(unsafe) {
+  if (!unsafe) return ''
+  return String(unsafe)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/**
+ * Build sitemap.xml from the merged route list, XML-escaped, no trailing
+ * slash on the home URL.
+ *
+ * @param {Array<{path: string}>} routes - merged route definitions
+ * @param {string} siteUrl - configured site origin
+ * @returns {string} sitemap.xml contents
+ */
+export function generateSitemap(routes, siteUrl) {
+  const now  = new Date().toISOString().split('T')[0]
+  const urls = routes.map(r => `
+  <url>
+    <loc>${escapeXml(siteUrl)}${r.path === '/' ? '' : escapeXml(r.path)}</loc>
+    <lastmod>${now}</lastmod>
+    <changefreq>${escapeXml(r.changefreq || 'monthly')}</changefreq>
+    <priority>${escapeXml(r.priority || '0.5')}</priority>
+  </url>`).join('')
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}\n</urlset>`
+}
+
+// -- 404 page ------------------------------------------------------------------
+// Uses id="root-404" (not "root") so main.jsx does NOT trigger hydrateRoot.
+// The React bundle script tag is stripped -- no JS loads at all on 404 pages.
+// See AGENTS.md for the full explanation.
+
+/**
+ * Render the static 404 page: id="root-404" (never hydrated), noindex,
+ * stripped React bundle tag, build tag stamp.
+ *
+ * @param {string} shell - dist/index.html contents
+ * @param {object} config - full ssr.config.js export
+ * @param {string} siteUrl - configured site origin
+ * @returns {string} 404.html contents
+ */
+export function generate404(shell, config, siteUrl) {
+  const notFoundConfig = config.notFound || {}
+  // User-supplied notFound values: html-escaped before they land in markup
+  // (a <script> in a heading would ship working JS otherwise) AND
+  // $$-escaped where they appear in replacement strings ("$&" in a heading
+  // would otherwise pull the matched tag text into the output).
+  const heading        = escapeXml(notFoundConfig.heading        || 'Page not found.')
+  const body           = escapeXml(notFoundConfig.body           || "That page doesn't exist -- or it moved.")
+  const primaryLabel   = escapeXml(notFoundConfig.primaryCta?.label  || 'Go home')
+  const primaryHref    = escapeXml(notFoundConfig.primaryCta?.href   || '/')
+  const siteName       = escapeXml(config.siteName || 'Site')
+  const v              = escapeReplacement
+
+  const bodyLines = [
+    '<div id="root-404">',
+    '  <div style="min-height:100vh;display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:4rem 2rem">',
+    `    <h1 style="font-size:2.5rem;font-weight:800;margin-bottom:1rem">${heading}</h1>`,
+    `    <p style="max-width:480px;font-size:1.05rem;line-height:1.7;margin-bottom:2rem">${body}</p>`,
+    // Theme-neutral CTA (#19): the filled `background:#000;color:#fff` button
+    // went invisible on dark themes (black fill on near-black pages). Text and
+    // outline now follow currentColor, so the CTA reads on any host theme.
+    `    <a href="${primaryHref}" style="display:inline-flex;align-items:center;padding:0.75rem 1.75rem;color:inherit;font-weight:700;font-size:0.9rem;letter-spacing:0.05em;text-transform:uppercase;border:2px solid currentColor;border-radius:6px;text-decoration:none">${primaryLabel}</a>`,
+    '  </div>',
+    '</div>',
+  ]
+
+  // Function replacer: bodyLines carry user text; string-form replacement
+  // would expand $-sequences (same trap as replaceRootDiv).
+  let html = shell.replace(/<div id="root"[^>]*><\/div>/, () => bodyLines.join('\n'))
+  html = html.replace(/<title>[^<]*<\/title>/,               () => `<title>Page Not Found | ${siteName}</title>`)
+  html = html.replace(
+    /(<meta\s+name="description"\s+content=")[^"]*(")/s,
+    () => `$1The page you were looking for does not exist.$2`
+  )
+  html = html.replace(
+    /(<meta\s+property="og:title"\s+content=")[^"]*(")/s,
+    () => `$1Page Not Found | ${siteName}$2`
+  )
+  html = html.replace(
+    /(<meta\s+name="twitter:title"\s+content=")[^"]*(")/s,
+    () => `$1Page Not Found | ${siteName}$2`
+  )
+  html = html.replace(
+    /(<link\s+rel="canonical"\s+href=")[^"]*(")/s,
+    () => `$1${v(siteUrl)}/$2`
+  )
+  // noindex -- 404 pages should not appear in search results
+  html = html.replace(
+    /<meta\s+name="robots"\s+content="[^"]*"\s*\/?>/s,
+    ''
+  )
+  html = html.replace(
+    '<meta name="author"',
+    '<meta name="robots" content="noindex, nofollow, noarchive, nosnippet, noimageindex" />\n  <meta name="author"'
+  )
+  // Strip the React bundle -- 404 is pure static HTML, no React needed.
+  // modulepreload must go too: vite emits one `<link rel=modulepreload>` per
+  // imported chunk next to the entry script, and a modulepreload link makes
+  // the browser PREFETCH the 160KB vendor bundle on a page whose whole
+  // contract is zero JS loads (caught by the 2026-10 perf/page-weight audit).
+  html = html.replace(/<script type="module"[^>]*><\/script>/, '')
+  html = html.replace(/<link[^>]*rel="modulepreload"[^>]*>/g, '')
+
+  return html
+}
+
+// -- Main pipeline -------------------------------------------------------------
+
+async function loadConfig() {
+  try {
+    config = (await import('../ssr.config.js')).default
+  } catch (err) {
+    console.error('[prerender] Could not load ssr.config.js:', err.message)
+    return null
+  }
+  const { ok, errors } = validateConfig(config)
+  if (!ok) {
+    formatDiagnostics(errors).forEach(line => console.error(line))
+    if (process.env.PRESTRUCT_STRICT === '1') {
+      console.error('[prerender] PRESTRUCT_STRICT=1 -- failing build on config diagnostics')
+      process.exit(1)
+    }
+  }
+  const { siteUrl } = config
+  if (!siteUrl) return null
+  return config
+}
+
+let config = null
+
+// CSS-route merge: the fetchRoutes() hook merges its CMS-driven routes with
+// the static ones. Dedupe by path -- the STATIC entry takes precedence, per
+// the documented merge contract. Pure function so tests can assert the
+// dedupe rules without spinning the whole pipeline.
+/**
+ * Merge static + fetchRoutes() CMS routes: dedupe by path with the static
+ * entry winning collisions; fetched routes are appended in order. A nullish
+ * fetched list degrades to the static list unchanged.
+ *
+ * @param {Array<{path: string}>} [staticRoutes=[]] - config routes
+ * @param {?Array<{path: string}>} [fetchedRoutes] - hook result
+ * @returns {Array<{path: string}>} merged route list
+ */
+export function mergeRoutes(staticRoutes = [], fetchedRoutes) {
+  // Static routes keep both precedence (path collisions) and position
+  // (static first, CMS routes appended). A hook that resolves to nothing
+  // (null/undefined) degrades to the static list unchanged.
+  const out = new Map((staticRoutes ?? []).map(r => [r.path, r]))
+  for (const r of fetchedRoutes ?? []) {
+    if (!out.has(r.path)) out.set(r.path, r)
+  }
+  return [...out.values()]
+}
+
+// StaticRouter loader: react-router-dom's exports map differs by version.
+// v6 exposes the SSR entry as a './server.js' subpath; v7 re-exports
+// StaticRouter from the package root. `importer` is injectable so the v7
+// fallback (and the both-fail case) is testable offline.
+/**
+ * Load StaticRouter across the react-router-dom peer range: v6 exposes the
+ * SSR entry as './server.js'; v7 re-exports it from the package root.
+ *
+ * @param {(m: string) => Promise<any>} [importer] - injectable importer (tests)
+ * @returns {Promise<Function>} the StaticRouter component
+ * @throws when neither entry provides StaticRouter
+ */
+export async function loadStaticRouter(importer = (m) => import(m)) {
+  let StaticRouter
+  try {
+    ;({ StaticRouter } = await importer('react-router-dom/server.js'))
+  } catch {
+    ;({ StaticRouter } = await importer('react-router-dom'))
+  }
+  if (!StaticRouter) {
+    throw new Error('[prerender] Could not load StaticRouter from react-router-dom -- is it installed?')
+  }
+  return StaticRouter
+}
+
+/**
+ * Run the full build-time prerender: ssrLoadModule the host's AppLayout,
+ * render each route through StaticRouter, stamp route meta, and write
+ * dist/<route>/index.html, 404.html, sitemap.xml, robots.txt, and the
+ * cache-stats snapshot. Library-safe: returns a summary, never process.exit.
+ *
+ * @param {object} [cfg=config] - full ssr.config.js export
+ * @param {{force?: boolean, root?: string}} [opts] - force rerender; host root
+ * @returns {?{total: number, succeeded: number, failed: number, cached: number, failures: Array}} render summary
+ *          (null when skipped: no config, no dist shell, or zero routes)
+ */
+export async function prerender(cfg = config, { force = false, root } = {}) {
+  const p = enginePaths(root || ROOT)
+  console.log('\n[prerender] Starting static HTML generation...')
+
+  const { siteUrl,
+    routes: staticRoutes = [],
+    appLayoutPath = '/src/AppLayout.jsx',
+  } = cfg
+
+  // fetchRoutes() hook: documented in docs/guides/api.md and the config
+  // example. Runs at build time only (never in the browser). Merged with
+  // the static routes; static wins on path collisions.
+  let fetched = []
+  if (typeof cfg.fetchRoutes === 'function') {
+    fetched = (await cfg.fetchRoutes()) || []
+  }
+  const ROUTES = mergeRoutes(staticRoutes, fetched)
+
+  if (!ROUTES.length) {
+    console.warn('[prerender] No routes defined in ssr.config.js -- skipping')
+    // Library-safety: never process.exit from a callable function -- callers
+    // (tests, host CLI) would lose control of their own process. The CLI's
+    // wrapper reports exit 0 naturally when this returns.
+    return
+  }
+
+  const { createServer }   = await import('vite')
+  const { renderToString } = await import('react-dom/server')
+  const React              = (await import('react')).default
+  const StaticRouter = await loadStaticRouter()
+
+  // Vite dev server in SSR mode.
+  // ssrLoadModule resolves all imports through Vite's unified module registry,
+  // guaranteeing a single react-router-dom instance. StaticRouter's location
+  // context reaches useLocation() inside Routes correctly.
+    const vite = await createServer({
+    root: p.root,
+    server: { middlewareMode: true },
+    appType: 'custom',
+    customLogger: {
+      info:           () => {},
+      warn:           (msg) => { if (!msg.includes('ExperimentalWarning')) process.stderr.write('[prerender:warn] ' + msg + '\n') },
+      error:          (msg) => process.stderr.write('[prerender:err] '  + msg + '\n'),
+      clearScreen:    () => {},
+      hasErrorLogged: () => false,
+      hasWarned:      false,
+      warnOnce:       () => {},
+    },
+  })
+
+  try {
+    const { default: AppLayout } = await vite.ssrLoadModule(appLayoutPath)
+
+    // Validate dist/index.html exists (vite build may have failed)
+    const indexPath = path.join(p.dist, 'index.html')
+    if (!fs.existsSync(indexPath)) {
+      console.error('[prerender] dist/index.html not found -- run vite build first')
+      return
+    }
+
+    const shell     = fs.readFileSync(indexPath, 'utf-8')
+    let succeeded   = 0
+    const failures  = []
+    const cache     = readCache({ cacheFile: p.cacheFile })
+
+    console.log(`[prerender] Cache: ${Object.keys(cache).length} routes cached${force ? ' (forcing rebuild)' : ''}`)
+
+    for (const route of ROUTES) {
+      // Defense in depth for the validator's path rules: at this point write
+      // happens for real -- anything that could escape dist/ is refused, not
+      // path-joined. Validation diagnostics already flagged it; the loop
+      // still skips silently-uncaught otherwise.
+      if (route.path.includes('..') || route.path.includes('\\')) {
+        console.error(`[prerender] FAIL ${route.path}: refusing path outside dist/ (contains ".." or backslash)`)
+        continue
+      }
+
+      const distPath = route.path === '/'
+        ? path.join(p.dist, 'index.html')
+        : path.join(p.dist, route.path.slice(1), 'index.html')
+
+      // Incremental: skip ONLY on a valid cache entry -- the old bare
+      // path-keyed check rewrote stale HTML over fresh builds whenever the
+      // shell or route meta changed. cacheEntryValid sees signatures over
+      // every rendered input; legacy entries (no sig) render once.
+      if (!force && cacheEntryValid(cache[route.path], route, siteUrl, shell)) {
+        fs.mkdirSync(path.dirname(distPath), { recursive: true })
+        fs.writeFileSync(distPath, cache[route.path].html, 'utf-8')
+        console.log(`[prerender] cached ${route.path}`)
+        succeeded++
+        continue
+      }
+
+      // Render fresh
+      try {
+        const appHtml = renderToString(
+          React.createElement(
+            StaticRouter,
+            { location: route.path },
+            React.createElement(AppLayout)
+          )
+        )
+
+        // Attribute-tolerant root-div injection (carries inject-brand attrs)
+        let html = replaceRootDiv(shell, appHtml)
+        html = injectMeta(html, route.meta || {}, route.path, siteUrl, cfg.ogImage)
+
+        // Save to cache with a signature over exactly these rendered inputs
+        cache[route.path] = { html, time: Date.now(), sig: cacheSignature(route, siteUrl, shell) }
+
+        fs.mkdirSync(path.dirname(distPath), { recursive: true })
+        fs.writeFileSync(distPath, html, 'utf-8')
+
+        console.log(`[prerender] ok ${route.path}`)
+        succeeded++
+      } catch (err) {
+        console.error(`[prerender] FAIL ${route.path}: ${err.message}`)
+        failures.push({ path: route.path, message: err.message })
+      }
+    }
+
+    // Save cache
+    writeCache(cache, { cacheDir: p.cacheDir, cacheFile: p.cacheFile })
+
+    // 404.html -- CF Pages serves this for all unmatched routes with HTTP 404
+    fs.writeFileSync(path.join(p.dist, '404.html'), generate404(shell, cfg || config, siteUrl), 'utf-8')
+    console.log('[prerender] ok /404.html')
+
+    // sitemap.xml -- overwrites the static one in public/ with today's date
+    fs.writeFileSync(path.join(p.dist, 'sitemap.xml'), generateSitemap(ROUTES, siteUrl), 'utf-8')
+    console.log('[prerender] ok /sitemap.xml')
+
+    // robots.txt -- opt-in only (config.robots): without it the author-owned
+    // public/robots.txt (if any) is untouched. Generated after sitemap so the
+    // Sitemap: line points at a file that was just (re-)written.
+    const robots = generateRobots(cfg || config)
+    if (robots !== null) {
+      fs.writeFileSync(path.join(p.dist, 'robots.txt'), robots, 'utf-8')
+      console.log('[prerender] ok /robots.txt')
+    }
+
+    // Cache stats -- static-sites-safe monitor: a JSON snapshot beside dist/
+    // (Intentionally not a runtime endpoint; static hosts serve files, not
+    // processes. Follows the PRD "static-sites-safe option preferred" note.)
+    const stats = {
+      generatedAt: new Date().toISOString(),
+      routeCount: ROUTES.length,
+      succeeded,
+      cached: Object.keys(cache).length,
+      force,
+      routes: ROUTES.map(r => ({ path: r.path, cached: Boolean(cache[r.path]) })),
+    }
+    fs.mkdirSync(path.join(p.dist, '.prestruct'), { recursive: true })
+    fs.writeFileSync(path.join(p.dist, '.prestruct', 'status.json'), JSON.stringify(stats, null, 2), 'utf-8')
+
+    console.log(`[prerender] Done. ${succeeded}/${ROUTES.length} pages rendered.\n`)
+
+    // Structured result -- callers (CLI, tests) need the failure count to
+    // decide the exit code. Live-fire (2026-10): every prerendering route
+    // is a silent-empty-page site; prerender used to end on a green-ok line while
+    // the routes errorred out. Return, never process.exit: library-safety.
+    return { total: ROUTES.length, succeeded, cached: ROUTES.length - succeeded, failed: failures.length, failures }
+
+  } finally {
+    await vite.close()
+  }
+}
+
+// -- CLI entry -----------------------------------------------------------------
+// Only runs when executed directly (node scripts/prerender.js) -- never on
+// import. prerender() itself does not load ssr.config.js; the CLI wrapper does.
+
+/**
+ * True when this module was executed directly (node scripts/prerender.js);
+ * library importers never trigger the CLI wrapper.
+ *
+ * @returns {boolean}
+ */
+export function isMainExecute() {
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1] || '').href
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  config = await loadConfig()
+  if (!config) process.exit(0)
+  const args = process.argv.slice(2)
+  if (args.includes('--clean')) {
+    cleanCache()
+    process.exit(0)
+  }
+  const result = await prerender(config, { force: args.includes('--force') })
+  // A partially-rendered build ships empty HTML for the failed routes and
+  // (pre-SPA-fallback-removal) nothing at all on deep paths. That deploy is
+  // broken, not degraded -- make the failure real so CI and CF Pages builds
+  // surface it instead of "(0/2 pages rendered)" riding through green.
+  if (result && result.failed > 0) {
+    console.error(`[prerender] FATAL: ${result.failed}/${result.total} route(s) failed to prerender:`)
+    for (const f of result.failures) console.error(`[prerender]   ${f.path}: ${f.message}`)
+    process.exit(1)
+  }
+}
+
+if (isMainExecute()) {
+  main().catch(err => {
+    // Fail loudly. Historically this exited 0 "so the SPA keeps deploying" --
+    // but the SPA fallback redirect rule is removed once prerendering is in
+    // place (AGENTS.md: _redirects), so a silent pass-through ships a site
+    // where deep routes 404 in production. A failed build must fail the build.
+    console.error('[prerender] Fatal:', err)
+    process.exit(1)
+  })
+}