prestruct 1.1.0 → 1.2.0

package/init/scripts/prerender.js

@@ -18,9 +18,13 @@
  * 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)
+ *   assertXmlSafe(value, field)     -- XML escape + control-char loud-fail
+ *   generateSitemap(routes, siteUrl, routeMtimes?)
  *   generate404(shell, config, siteUrl)
  *   readCache() / writeCache(cache) / cleanCache()
+ *   rewriteRrdNamedImports(source)  -- react-router named-import interop rewrite
+ *   esmTwinSource(id, opts)         -- react-router CJS -> ESM twin redirect (#68)
+ *   loadStaticRouter(importer?)     -- StaticRouter across the v6/v7 peer range
  *   prerender()                     -- full pipeline
  *
  * Output (for a 3-route app with /, /about, /contact):
@@ -40,6 +44,7 @@ import crypto from 'crypto'
 import { fileURLToPath, pathToFileURL } from 'url'
 
 import { validateConfig, formatDiagnostics } from './validate-config.js'
+import { resolveOgImageGeneration, renderRouteOgImage, imageSlug } from './ogimage.js'
 
 // Root-package re-export: `import { defineConfig } from 'prestruct'`
 // (binding stays out of this file's scope to avoid an unused-import)
@@ -112,8 +117,6 @@ export function escapeHtml(s) {
 // 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
@@ -124,13 +127,19 @@ export function escapeHtml(s) {
  * @param {string} shell - dist/index.html contents
  * @returns {string} stable hash signature
  */
-export function cacheSignature(route, siteUrl, shell) {
+export function cacheSignature(route, siteUrl, shell, extras = null) {
   return crypto.createHash('sha256').update(JSON.stringify({
     path: route.path,
     siteUrl,
     meta: route.meta ?? null,
     ogImage: route.ogImage ?? null,
     shell,
+    // Config-gated head additions (the 2026-10 ride-along set): a host that
+    // flips feed / hreflang / verification / searchUrl on between builds
+    // must re-render the routes that carry them. The QC sweep caught the
+    // signature covering only the shell-side inputs, so newly enabled
+    // extras rode a valid-cache hit and never reached the shipped head.
+    extras: extras ?? null,
   })).digest('hex')
 }
 
@@ -144,24 +153,92 @@ export function cacheSignature(route, siteUrl, shell) {
  * @param {string} shell - current dist/index.html contents
  * @returns {boolean} true when the cache may be reused
  */
-export function cacheEntryValid(entry, route, siteUrl, shell) {
+export function cacheEntryValid(entry, route, siteUrl, shell, extras = null) {
   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)
+  return entry.sig === cacheSignature(route, siteUrl, shell, extras)
+}
+
+/**
+ * Build the config-gated render inputs that BOTH the cache signature and
+ * injectMeta consume. Extracted so the cache-signature contract is pinnable
+ * offline (the QC-sweep lesson: a config-gated head addition that changes the
+ * baked HTML must participate in the signature, or flipping it on rides a
+ * valid-cache hit and never reaches the shipped head).
+ *
+ * `ogImageGeneration` is reduced to a stable identity descriptor
+ * (templatePath + dimensions + font presence), never the resolved block --
+ * that carries the template TEXT and font BYTES, and a Buffer does not
+ * JSON-round-trip. The descriptor changes exactly when the generated image
+ * (and therefore the per-route og:image the page ships) would change.
+ *
+ * @param {object} cfg - ssr.config.js export
+ * @param {?object} ogImageGeneration - resolved block from resolveOgImageGeneration
+ * @returns {object} extras fed to cacheSignature + injectMeta
+ */
+export function buildHeadExtras(cfg, ogImageGeneration) {
+  return {
+    feed: cfg.feed ?? null,
+    alternates: cfg.alternates ?? null,
+    verification: cfg.verification ?? null,
+    searchUrl: cfg.searchUrl ?? null,
+    // Enabling/retargeting per-route OG generation rewrites every route's
+    // og:image/twitter:image to the generated PNG -- a rendered input.
+    ogImageGeneration: ogImageGeneration
+      ? {
+          templatePath: ogImageGeneration.templatePath,
+          width: ogImageGeneration.width,
+          height: ogImageGeneration.height,
+          font: Boolean(ogImageGeneration.fontBytes),
+        }
+      : null,
+  }
 }
 
-// -- Root-div injection (W8 fix) -----------------------------------------------
+// -- Root-div injection (W8 fix + re-entrancy fix, 2026-10) ---------------------
 // 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.
+// Content-tolerant too, and NOT optional: prerender's own output lands in
+// dist/index.html -- the root div ships RENDERED. A bare re-run (CI debug
+// rerun, cache-money builds without a fresh vite step) reads that rendered
+// shell, and the old empty-only matcher threw "<div id="root"></div> not
+// found" FATAL on every route. Re-rendering an already-rendered shell is now
+// the same operation as rendering a pristine one, and idempotent.
+
+/**
+ * Locate the shell's root <div id="root"> element and return [start, end)
+ * offsets spanning the WHOLE element -- open tag through its matching close.
+ * Nested divs inside a previously rendered shell are depth-counted; a lazy
+ * matching scan would stop at the first nested </div> and swap the wrong
+ * span. A <div ... /> self-closing token neither opens nor closes a level.
+ */
+function findRootDivSpan(shell) {
+  // Attribute-tolerant: quote style, whitespace around `=`, and a stray
+  // attribute before id (inject-brand adds data-deploy-id-footer) all match.
+  // The old byte-exact `/<div id="root"[^>]*>/` failed hard on any reflow a
+  // minifier or prettier pass introduced.
+  const open = /<div\b[^>]*\sid\s*=\s*("root"|'root'|root)[^>]*>/.exec(shell)
+  if (!open) return null
+  let depth = 1
+  const TOKEN = /<div\b[^>]*>|<\/div>/g
+  TOKEN.lastIndex = open.index + open[0].length
+  let t
+  while ((t = TOKEN.exec(shell)) !== null) {
+    if (t[0] === '</div>') depth -= 1
+    else if (t[0].endsWith('/>')) continue
+    else depth += 1
+    if (depth === 0) return [open.index, TOKEN.lastIndex]
+  }
+  return null
+}
 
 /**
  * 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.
+ * carrying the prerendered markup.
  *
  * @param {string} shell - dist/index.html contents
  * @param {string} appHtml - renderToString output for the route
@@ -169,20 +246,30 @@ export function cacheEntryValid(entry, route, siteUrl, shell) {
  * @throws when the shell has no root div
  */
 export function replaceRootDiv(shell, appHtml) {
-  const match = shell.match(/<div id="root"([^>]*)><\/div>/)
-  if (!match) {
+  const span = findRootDivSpan(shell)
+  if (!span) {
     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>`
-  )
+  const closeIdx = shell.indexOf('>', span[0]) + 1
+  // Carry the open tag through UNCHANGED except for the render stamp: drop any
+  // stamp a previous pass wrote (so re-entry cannot stack duplicate stamps),
+  // then append one. Preserving the original open tag verbatim is what makes
+  // this attribute-tolerant -- the earlier form sliced attrs at the fixed
+  // `<div id="root"`.length offset, so a reflowed shell (`class="app"
+  // id="root"`, `id = "root"`, single quotes) shipped CORRUPT markup: a
+  // duplicated id, half an attribute name as garbage, or dropped attrs.
+  const base = shell
+    .slice(span[0], closeIdx)
+    .replace(/\s+data-server-rendered\s*=\s*("true"|'true'|true)/, '')
+    .replace(/>$/, '')
+    .replace(/\s+$/, '')
+  const open = base + ' data-server-rendered="true">'
+  // appHtml MUST NOT be $-expanded: it is okay for route content to contain
+  // "$1"/"$&"-shaped text (prices, code samples, quotes) and a replacement
+  // string would expand those into capture references, mangling the SSR
+  // output. Same lesson as the $120 meta-description bug.
+  // (Slice-assembly instead: no replace() in the swap at all.)
+  return shell.slice(0, span[0]) + open + appHtml + '</div>' + shell.slice(span[1])
 }
 
 // -- Meta injection ------------------------------------------------------------
@@ -199,27 +286,195 @@ export function replaceRootDiv(shell, appHtml) {
  * @param {?string} globalOgImage - config-level ogImage fallback
  * @returns {string} updated html
  */
-export function injectMeta(html, meta, routePath, siteUrl, globalOgImage) {
+// llms.txt (#49 family): one H1, a blockquote tagline, then a Docs section
+// listing every indexable route's title, absolute URL and description - the
+// AI-consumable site summary in the llmstxt.org shape. The prerender pass
+// already carries every route's meta, so this costs no new scanning.
+// Generated-only: an existing llms.txt (hand-rolled or SSG-written) is
+// never touched, same contract as sitemap.xml. Opt-out: `llms: false`.
+/**
+ * One line of plain text, whatever it was given: newlines split list
+ * entries silently, control characters ride in as garbage. Bad bytes
+ * drop, whitespace collapses.
+ */
+function oneline(value) {
+  return String(value)
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '')
+    .replace(/[\r\n]+/g, ' ')
+    .trim()
+}
+
+/**
+ * Write llms.txt into dist. Routes only: the prerendered route set (the
+ * same gate sitemap honors). @returns {string|null} the written path.
+ */
+export function generateLlms(routes, config, distDir) {
+  if (config && config.llms === false) return null
+  const target = path.join(distDir, 'llms.txt')
+  if (fs.existsSync(target)) {
+    console.log('[prerender] llms.txt exists - leaving it untouched')
+    return null
+  }
+  const base = ((config && config.siteUrl) || '').replace(/\/$/, '')
+  const lines = []
+  lines.push('# ' + oneline((config && config.siteName) || 'Site'))
+  const tagline = config && config.tagline
+  if (tagline) lines.push('', '> ' + oneline(tagline))
+  lines.push('', '## Docs', '')
+  let count = 0
+  for (const r of (routes || [])) {
+    if (!r || typeof r.path !== 'string') continue
+    const title = oneline((r.meta && r.meta.title) || r.path)
+    const desc = (r.meta && r.meta.description) ? ': ' + oneline(r.meta.description) : ''
+    lines.push('- [' + title + '](' + base + (r.path === '/' ? '/' : r.path) + ')' + desc)
+    count++
+  }
+  fs.writeFileSync(target, lines.join('\n') + '\n', 'utf-8')
+  console.log('[prerender] llms.txt: emitted for ' + count + ' route(s)')
+  return target
+}
+
+export function injectMeta(html, meta, routePath, siteUrl, globalOgImage, extras = null) {
   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}`))
+  // og:image per-route override, string shorthand OR object form (object
+  // contract mirrors inject-brand's): object resolution takes `.url` so a
+  // structured global or route value lands as a URL, never as the string
+  // "[object Object]" corrupting every head silently.
+  const globalImgUrl = (typeof globalOgImage === 'object' && globalOgImage !== null) ? globalOgImage.url : globalOgImage
+  const routeImgUrl  = (typeof meta.ogImage   === 'object' && meta.ogImage   !== null) ? meta.ogImage.url   : meta.ogImage
+  const ogImage = escapeReplacement(escapeHtml(String(routeImgUrl || globalImgUrl || '')))
+  // Per-route og:image OBJECT companions (#audit B4): a route that overrides
+  // og:image with a structured object owns its width/height/alt/type too. The
+  // companions are reconciled below (the route's replace the site-wide ones
+  // inject-brand baked; absent ones are stripped so a stale global never
+  // describes a different raster). String-form overrides keep the global
+  // companions, which still describe the same site-wide image.
+  const routeOgObject = (meta.ogImage && typeof meta.ogImage === 'object' && !Array.isArray(meta.ogImage)) ? meta.ogImage : null
+  // Trailing-slash normalization (#53): a `siteUrl` written with its trailing
+  // slash would otherwise join into `https://site//about` on every page's
+  // canonical + og:url.robots.txt already strips; this is the same contract
+  // at the injection seam.
+  const url     = escapeReplacement(escapeHtml(`${(siteUrl || '').replace(/\/$/, '')}${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`)
+    html = html.replace(/(<meta\s+property="og:title"\s+content=")[^"\r\n]*(")/,      `$1${title}$2`)
+    html = html.replace(/(<meta\s+name="twitter:title"\s+content=")[^"\r\n]*(")/,     `$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+name="description"\s+content=")[^"\r\n]*(")/,       `$1${desc}$2`)
+    html = html.replace(/(<meta\s+property="og:description"\s+content=")[^"\r\n]*(")/, `$1${desc}$2`)
+    html = html.replace(/(<meta\s+name="twitter:description"\s+content=")[^"\r\n]*(")/, `$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`)
+  html = html.replace(/(<meta\s+property="og:url"\s+content=")[^"\r\n]*(")/,          `$1${url}$2`)
+  html = html.replace(/(<link\s+rel="canonical"\s+href=")[^"\r\n]*(")/,               `$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`)
+    html = html.replace(/(<meta\s+property="og:image"\s+content=")[^"\r\n]*(")/,      `$1${ogImage}$2`)
+    html = html.replace(/(<meta\s+name="twitter:image"\s+content=")[^"\r\n]*(")/,     `$1${ogImage}$2`)
+  }
+
+  // Reconcile og:image companion tags against the route's object override.
+  // Only runs for the object form; a string override leaves the global
+  // companions in place (they describe the same site-wide image). All stale
+  // companions are stripped first (so the global width/height/alt/type/
+  // secure_url can never describe a different raster), then the route's own
+  // companions are re-emitted.
+  if (routeOgObject) {
+    html = html.replace(/\n?\s*<meta\s+property="og:image:(?:secure_url|type|width|height|alt)"\s+content="[^"\r\n]*"\s*\/?>/g, '')
+    const companions = []
+    if (typeof routeImgUrl === 'string' && routeImgUrl.startsWith('http://')) {
+      companions.push(['og:image:secure_url', 'https://' + routeImgUrl.slice('http://'.length)])
+    }
+    if (typeof routeOgObject.type === 'string' && routeOgObject.type) companions.push(['og:image:type', routeOgObject.type])
+    if (/^[0-9]+$/.test(String(routeOgObject.width  ?? ''))) companions.push(['og:image:width',  String(routeOgObject.width)])
+    if (/^[0-9]+$/.test(String(routeOgObject.height ?? ''))) companions.push(['og:image:height', String(routeOgObject.height)])
+    if (typeof routeOgObject.alt === 'string' && routeOgObject.alt) companions.push(['og:image:alt', routeOgObject.alt])
+    for (const [prop, value] of companions) {
+      const tag = `    <meta property="${prop}" content="${escapeReplacement(escapeHtml(value))}" />`
+      html = html.replace(/(<meta\s+property="og:image"\s+content="[^"\r\n]*"\s*\/>)/, `$1\n${tag}`)
+    }
+  }
+
+  // -- Grouped head additions (missing-only, config-gated: a host that opts
+  // out renders identical HTML to before). These ride a FUNCTION replacer
+  // (`</head>` swapped for tail + `</head>`), and a function replacer does
+  // NOT process `$`-syntax in its return value. So the values here need only
+  // escapeHtml (markup class); applying escapeReplacement too would ship the
+  // doubled `$$` literally (a feed URL `.../feed$1.xml` -> `.../feed$$1.xml`).
+  let tail = ''
+  const headAdd = (line) => { tail += '\n  ' + line }
+
+  // Feed autodiscovery: feed readers only learn a feed exists from <head>.
+  const feed = extras && extras.feed
+  if (feed && typeof feed.url === 'string' && feed.url) {
+    const fType  = feed.type  || 'application/rss+xml'
+    const fTitle = feed.title ? ` title="${escapeHtml(feed.title)}"` : ''
+    headAdd(`<link rel="alternate" type="${escapeHtml(fType)}"${fTitle} href="${escapeHtml(feed.url)}" />`)
+  }
+
+  // hreflang alternates: site-wide set, per-route override (swap semantics).
+  const alternates = (meta && meta.alternates) || (extras && extras.alternates)
+  if (Array.isArray(alternates)) {
+    for (const a of alternates) {
+      if (!a || typeof a.href !== 'string' || !a.href || typeof a.hreflang !== 'string' || !a.hreflang) continue
+      headAdd(`<link rel="alternate" hreflang="${escapeHtml(a.hreflang)}" href="${escapeHtml(a.href)}" />`)
+    }
+  }
+
+  // Verification metas (site verifiers for search consoles, tooling): keys
+  // must be plain meta-name shapes, values escaped. A $ or quote inside a
+  // key would otherwise become markup or replacement syntax.
+  const verification = extras && extras.verification
+  if (verification && typeof verification === 'object' && !Array.isArray(verification)) {
+    for (const [vName, vValue] of Object.entries(verification)) {
+      if (typeof vValue !== 'string' || vValue === '') continue
+      if (!/^[A-Za-z0-9._-]+$/.test(vName)) continue
+      headAdd(`<meta name="${escapeHtml(vName)}" content="${escapeHtml(vValue)}" />`)
+    }
+  }
+
+  // Per-route JSON-LD (#35): route-scoped schema nodes ship on the pages
+  // that carry them (FAQPage belongs on the FAQ page, not site-wide). The
+  // home route may also wrap the site's query interface (SearchAction) when
+  // the host configures a searchUrl with a {query} slot.
+  const routeNodes = []
+  const searchUrl = extras && routePath === '/' && typeof extras.searchUrl === 'string' ? extras.searchUrl : null
+  if (searchUrl && searchUrl.includes('{query}')) {
+    routeNodes.push({
+      '@context': 'https://schema.org',
+      '@type': 'WebSite',
+      url: `${(siteUrl || '').replace(/\/$/, '')}/`,
+      potentialAction: {
+        '@type': 'SearchAction',
+        target: { '@type': 'EntryPoint', urlTemplate: searchUrl },
+        'query-input': 'required name=query',
+      },
+    })
+  }
+  const routeJsonLd = meta && meta.jsonLd
+  if (Array.isArray(routeJsonLd)) {
+    for (const n of routeJsonLd) {
+      if (n && typeof n === 'object' && !Array.isArray(n)) routeNodes.push(n)
+    }
+  } else if (routeJsonLd && typeof routeJsonLd === 'object') {
+    routeNodes.push(routeJsonLd)
+  }
+  if (routeNodes.length > 0) {
+    const payload = routeNodes.length === 1
+      ? routeNodes[0]
+      : { '@context': 'https://schema.org', '@graph': routeNodes }
+    // Rebuild idempotence: strip any previously injected route block first.
+    html = html.replace(/\n\s*<!-- JSON-LD \(route\) -->[\s\S]*?<\/script>(?=[\s\S]*?<\/head>)/, '')
+    const script = '<script type="application/ld+json">'
+      + JSON.stringify(payload, null, 2).replace(/</g, '\\u003c')
+      + '</script>'
+    headAdd('<!-- JSON-LD (route) -->')
+    headAdd(script)
+  }
+
+  if (tail) {
+    html = html.replace('</head>', function () { return tail + '\n  </head>' })
   }
 
   return html
@@ -317,9 +572,9 @@ export function generateRobots(config) {
   const sitemapLine = cfgSitemap && siteUrl ? ['', `Sitemap: ${siteUrl}/sitemap.xml`] : []
 
   // { aeo: true | {} } -> search bots allowed, training crawls blocked by
-  // default. { aeo: { aiBots: 'allow' } } flips training to Allow. aeo with
-  // an explicit body: the body is appended after the preset groups (letting
-  // owners add extra paths) only via body; the preset itself ignores body.
+  // default. { aeo: { aiBots: 'allow' } } flips training to Allow. Under aeo
+  // the preset owns the whole file: an accompanying `body` is NOT emitted
+  // (the preset branch returns before the custom-body path below).
   const aeo       = !cfgBool && cfg && cfg.aeo
   const aeoCli    = aeo ? (aeo.aiBots === 'allow' ? 'allow' : 'block') : null
 
@@ -357,26 +612,78 @@ export function escapeXml(unsafe) {
     .replace(/'/g, '&apos;')
 }
 
+/**
+ * XML-safety loud-fail (freestruct xmllike.js adoption): sitemap fields are
+ * user-config data (paths, supplied meta), so escape what escaping can fix
+ * and REFUSE what it cannot. Control characters cannot appear in XML at all
+ * -- no replacement exists, and writing them anyway ships a corrupt sitemap
+ * that reads green. A value that still produces invalid XML is a build
+ * error, not a silently poisoned artifact.
+ *
+ * @param {unknown} value - raw sitemap field value
+ * @param {string} field - field name for the diagnostic
+ * @returns {string} XML-safe value (escapeXml over a verified-clean text)
+ * @throws {Error} when the value carries a control character
+ */
+export function assertXmlSafe(value, field) {
+  const text = String(value ?? '')
+  const bad = text.match(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/)
+  if (bad) {
+    throw new Error(
+      `XML safety: value for ${field} contains control character U+${bad[0].charCodeAt(0).toString(16).padStart(4, '0')}`
+      + ' which cannot be escaped - refusing to write invalid XML'
+    )
+  }
+  return escapeXml(text)
+}
+
 /**
  * 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
+ * @param {Map<string, Date>} [routeMtimes] - per-route dist file mtimes, the
+ *   honest <lastmod> source (content-change dates); entries missing from
+ *   the map fall back to now
  * @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('')
+export function generateSitemap(routes, siteUrl, routeMtimes = new Map()) {
+  const base = (siteUrl || '').replace(/\/$/, '') // #53: never join onto a doubled slash
+  const urls = routes.map(r => {
+    // Honest lastmod (freestruct xmllike adoption): a universal build stamp
+    // moves every <lastmod> on every build, so freshness signals churn even
+    // when one page of a 300-page site changed. Each route carries its dist
+    // file's mtime -- written once per content change (writeRouteFile skips
+    // byte-identical rewrites) -- and unknown routes fall back to now.
+    const mtime = routeMtimes.get(r.path) || new Date()
+    const loc = assertXmlSafe(`${base}${r.path === '/' ? '' : r.path}`, 'sitemap loc')
+    return `\n  <url>\n    <loc>${loc}</loc>\n    <lastmod>${assertXmlSafe(mtime.toISOString().split('T')[0], 'sitemap lastmod')}</lastmod>\n    <changefreq>${assertXmlSafe(r.changefreq || 'monthly', 'sitemap changefreq')}</changefreq>\n    <priority>${assertXmlSafe(r.priority || '0.5', 'sitemap priority')}</priority>\n  </url>`
+  }).join('')
   return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}\n</urlset>`
 }
 
+/**
+ * Write one route file, honestly. Byte-identical content skips the write so
+ * the file KEEPS its mtime -- the date the content last changed, which is
+ * the sitemap's per-route <lastmod> source. Fresh content gets a fresh
+ * stat. Cache hits previously rewrote identical HTML every build, which
+ * silently turned every lastmod into a build stamp.
+ *
+ * @param {string} distPath - final file path
+ * @param {string} html - route HTML to write
+ * @param {Map<string, Date>} routeMtimes - lastmod map, mutated with the
+ *   route's content-change date
+ * @param {string} routePath - route registry key in the map
+ */
+function writeRouteFile(distPath, html, routeMtimes, routePath) {
+  fs.mkdirSync(path.dirname(distPath), { recursive: true })
+  let prev = null
+  try { prev = fs.readFileSync(distPath, 'utf8') } catch (e) { prev = null }
+  if (prev !== html) fs.writeFileSync(distPath, html, 'utf-8')
+  routeMtimes.set(routePath, fs.existsSync(distPath) ? fs.statSync(distPath).mtime : new Date())
+}
+
 // -- 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.
@@ -400,9 +707,22 @@ export function generate404(shell, config, siteUrl) {
   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
+  // CTA href scheme guard (#walk 2026-10): escapeXml fixes the markup
+  // breaking class (" in the attribute) but nothing can make a
+  // javascript:/data: URL into a safe destination -- it would ship as a
+  // WORKING script href on the one page whose whole contract is zero JS.
+  // Allow only real anchors (relative, absolute http(s), mailto:, tel:
+  // and a plain hash); anything else falls back to '/'. Config is
+  // author-owned, so this is hardening, not a trust boundary.
+  const rawHref        = notFoundConfig.primaryCta?.href   || '/'
+  const primaryHref    = /^(\/|https?:\/\/|mailto:|tel:|#)/i.test(String(rawHref))
+    ? escapeXml(rawHref)
+    : escapeXml('/')
+  // siteName is NOT escaped here: it flows into injectMeta's title, which
+  // escapes it (escapeHtml + escapeReplacement) exactly once. Pre-escaping
+  // it here double-escaped the 404 title ("Tom & Jerry's" shipped as
+  // "Tom &amp;amp; Jerry&amp;apos;s").
+  const siteName       = config.siteName || 'Site'
 
   const bodyLines = [
     '<div id="root-404">',
@@ -417,42 +737,47 @@ export function generate404(shell, config, siteUrl) {
     '</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
+  // Root-div swap rides findRootDivSpan (re-entrancy fix): slice assembly
+  // keeps $-shaped config text literal with no replacement string in sight.
+  const span = findRootDivSpan(shell)
+  if (!span) {
+    throw new Error('<div id="root"></div> not found in shell -- check index.html')
+  }
+  let html = shell.slice(0, span[0]) + bodyLines.join('\n') + shell.slice(span[1])
+  // #42 (the root fix behind the replacer tragedy #33/#34): the four text
+  // tags ride the SAME injection pipeline as every page -- injectMeta owns
+  // title/description/og:title/twitter:title with its single-line,
+  // class-excluding regexes and the shared escape pipeline. No 404-specific
+  // replacer remains for any future head tag to trip over.
+  html = injectMeta(html, {
+    title: `Page Not Found | ${siteName}`,
+    description: 'The page you were looking for does not exist.',
+  }, '/', siteUrl, config && config.ogImage)
+  // The 404 canonical + og:url are the HOME origin, and injectMeta above
+  // already wrote them: passing '/' as the route path makes it emit exactly
+  // the home URL (the bare origin, no trailing slash -- the same form
+  // index.html, the sitemap home loc and usePageMeta use). The old explicit
+  // override here appended a trailing slash (#76), so the 404 was the one
+  // surface that disagreed with every other home-canonical writer; removing
+  // it leaves a single derivation.
+  // noindex -- 404 pages should not appear in search results. Strip any
+  // author's robots meta first (the shell may carry one), then anchor the
+  // noindex directive to `</head>` so it never depends on an optional
+  // neighbour tag: the old form anchored on `<meta name="author">`, which a
+  // shell lacking that tag (author not configured) silently skipped -- a
+  // 404 with NO noindex, invisible to a reader but still indexable.
   html = html.replace(
-    /<meta\s+name="robots"\s+content="[^"]*"\s*\/?>/s,
+    /<meta\s+name="robots"\s+content="[^"\r\n]*"\s*\/?>/,
     ''
   )
-  html = html.replace(
-    '<meta name="author"',
-    '<meta name="robots" content="noindex, nofollow, noarchive, nosnippet, noimageindex" />\n  <meta name="author"'
-  )
+  html = html.replace('</head>', '<meta name="robots" content="noindex, nofollow, noarchive, nosnippet, noimageindex" />\n  </head>')
   // 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, '')
+  html = html.replace(/<script type="module"[^>\r\n]*><\/script>/, '')
+  html = html.replace(/<link[^>\r\n]*rel="modulepreload"[^>\r\n]*>/g, '')
 
   return html
 }
@@ -498,13 +823,116 @@ 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 ?? []) {
+  //
+  // Junk tolerance (#walk 2026-10): a non-object entry (null route, a bare
+  // string from a CMS mapping bug) used to crash the Map build with
+  // `Cannot read properties of undefined (reading 'path')` -- an obscure
+  // mid-build TypeError far from its cause. validate-config already flags
+  // these as diagnostics, but a non-STRICT build still reaches here, so
+  // the downstream posture is skip-LOUD per entry (never die silently,
+  // never take down the other valid routes with one bad row).
+  const out = new Map()
+  let junk = 0
+  const addRoute = (r, origin) => {
+    if (!r || typeof r !== 'object' || typeof r.path !== 'string') {
+      console.error(`[prerender] ${origin}: skipped non-route entry (expected { path, ... }, got ${r === null ? 'null' : typeof r}${typeof r === 'string' ? ": ''" + r.slice(0, 40) + "''" : ''})`)
+      junk++
+      return
+    }
     if (!out.has(r.path)) out.set(r.path, r)
   }
+  for (const r of (staticRoutes ?? [])) addRoute(r, 'routes')
+  for (const r of (fetchedRoutes ?? [])) addRoute(r, 'fetchRoutes()')
+  if (junk > 0) console.error(`[prerender] ${junk} junk route entr(y|ies) skipped -- fix ssr.config.js (or the fetchRoutes() hook)`)
   return [...out.values()]
 }
 
+// react-router-dom v7 named-import interop (#29): v7 ships CJS, and vite's
+// SSR graph externalizes node_modules entirely, so a HOST layout's
+// `import { useLocation } from 'react-router-dom'` dies at link time
+// ("Named export 'useLocation' not found") before any engine hook can
+// intercede. Fix at import-analysis: a pre-transform rewrites the layout's
+// named-import statement into the namespace-interop shape the scaffold
+// itself uses (v6 ESM namespace or v7 CJS default), matching both majors.
+/**
+ * Rewrite `import { A, B } from 'react-router-dom'` statements into the
+ * dual-major namespace interop form. Exported so the battery can pin the
+ * rewrite offline against both import spoken forms.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function rewriteRrdNamedImports(source) {
+  let n = 0
+  return source.replace(
+    /import\s+(?:([A-Za-z_$][\w$]*)\s*,\s*)?\{([^}]+)\}\s+from\s+(['"])react-router-dom\3/g,
+    (_m, defaultName, names, q) => {
+      const bindings = names.split(',').map(function (s) { return s.trim() }).filter(Boolean).join(', ')
+      const ns = `rrdInteropNs_${++n}`
+      const resolved = `${ns}.default ?? ${ns}`
+      // Default+named form (`import rrd, { useLocation }`) is rewritten too:
+      // the old regex required `{` immediately after `import `, so that shape
+      // passed through untouched and still died at link time on v7 CJS.
+      const defaultBinding = defaultName ? ` const ${defaultName} = ${resolved};` : ''
+      return `import * as ${ns} from ${q}react-router-dom${q};${defaultBinding} const { ${bindings} } = ${resolved}`
+    },
+  )
+}
+
+// Applied as a vite pre-plugin so the rewrite lands before import analysis.
+const rrdInteropPlugin = {
+  name: 'prestruct-rrd-cjs-interop',
+  enforce: 'pre',
+  transform(code, id) {
+    if (id.includes('node_modules')) return null // never touch the externals
+    if (!code.includes('react-router-dom')) return null
+    const out = rewriteRrdNamedImports(code)
+    return out === code ? null : { code: out, map: null }
+  },
+}
+
+// react-router ESM-twin redirect (prestruct#68): when a host sets
+// `ssr.noExternal` (the documented way to keep the router in-process for the
+// old consumer shim), Vite INLINES the package's CJS node entry
+// (`dist/index.js` on v7, `dist/server.js`/`dist/main.js` on v6) into the SSR
+// registry. The registry evaluates that CJS source as ESM -- `module`/
+// `exports` are undefined -- so the load dies with `module is not defined`
+// (v7) or `exports is not defined` (v6), 0/n pages rendered. Every router
+// entry ships a sibling `.mjs` ESM twin; serving the twin's content for the
+// CJS file URL keeps the registry a real ESM module. Externalized trees never
+// hit this hook (Node loads the file itself), so the redirect is a no-op
+// there -- it only rescues the inlined case, leaving the default shape alone.
+/**
+ * Redirect react-router(-dom) CJS dist loads to their sibling `.mjs` ESM twin
+ * during the SSR pass. Returns null (honest pass-through) when the id is not a
+ * router CJS file or no twin exists.
+ *
+ * @param {string} id - module id Vite is loading
+ * @param {?{ssr?: boolean}} opts - Vite load options
+ * @returns {?string} ESM source, or null to pass through
+ */
+export function esmTwinSource(id, opts) {
+  if (!opts || opts.ssr !== true) return null
+  const clean = id.split('?')[0]
+  if (!/[\\/]node_modules[\\/]react-router(-dom)?[\\/]/.test(clean)) return null
+  if (!clean.endsWith('.js')) return null
+  const esm = clean.replace(/\.js$/, '.mjs')
+  try {
+    if (!fs.existsSync(esm)) return null
+    return fs.readFileSync(esm, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const rrdEsmTwinPlugin = {
+  name: 'prestruct-rrd-esm-twin',
+  enforce: 'pre',
+  load(id, opts) {
+    return esmTwinSource(id, opts)
+  },
+}
+
 // 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
@@ -518,12 +946,15 @@ export function mergeRoutes(staticRoutes = [], fetchedRoutes) {
  * @throws when neither entry provides StaticRouter
  */
 export async function loadStaticRouter(importer = (m) => import(m)) {
-  let StaticRouter
+  let mod
   try {
-    ;({ StaticRouter } = await importer('react-router-dom/server.js'))
+    mod = await importer('react-router-dom/server.js')
   } catch {
-    ;({ StaticRouter } = await importer('react-router-dom'))
+    mod = await importer('react-router-dom')
   }
+  // Named export first; the namespace-interop `default` carries it when a CJS
+  // entry resolved without named bindings.
+  const StaticRouter = mod && (mod.StaticRouter || (mod.default && mod.default.StaticRouter))
   if (!StaticRouter) {
     throw new Error('[prerender] Could not load StaticRouter from react-router-dom -- is it installed?')
   }
@@ -570,16 +1001,22 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
   const { createServer }   = await import('vite')
   const { renderToString } = await import('react-dom/server')
   const React              = (await import('react')).default
-  const StaticRouter = await loadStaticRouter()
+
+  // Pre-server load: the fail-before-server path (vite missing, no config) and
+  // the externalized default both land here. On react-router 6 this IS the
+  // registry's instance (require()-shaped CJS), so it is also the correct one
+  // to render with.
+  let 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({
+  const vite = await createServer({
     root: p.root,
     server: { middlewareMode: true },
     appType: 'custom',
+    plugins: [rrdInteropPlugin, rrdEsmTwinPlugin],
     customLogger: {
       info:           () => {},
       warn:           (msg) => { if (!msg.includes('ExperimentalWarning')) process.stderr.write('[prerender:warn] ' + msg + '\n') },
@@ -594,6 +1031,22 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
   try {
     const { default: AppLayout } = await vite.ssrLoadModule(appLayoutPath)
 
+    // The seam (prestruct#68): a host that sets `ssr.noExternal` (the old
+    // consumer-shim requirement) makes Vite INLINE react-router instead of
+    // externalizing it, so the registry holds its OWN instance while the
+    // pre-server `loadStaticRouter()` above holds Node's. On react-router 7
+    // (real ESM) those are two module instances with two sets of React
+    // contexts, and every route dies with "useLocation() may be used only in
+    // the context of a <Router> component". Re-load StaticRouter through the
+    // registry so the wrapper and the tree share one instance. The plain
+    // import stays as the fallback when the registry cannot serve it.
+    try {
+      const registryStaticRouter = await loadStaticRouter((m) => vite.ssrLoadModule(m))
+      if (registryStaticRouter) StaticRouter = registryStaticRouter
+    } catch (err) {
+      console.warn(`[prerender] registry StaticRouter unavailable (${err.message}) -- using the module-scope import`)
+    }
+
     // Validate dist/index.html exists (vite build may have failed)
     const indexPath = path.join(p.dist, 'index.html')
     if (!fs.existsSync(indexPath)) {
@@ -603,8 +1056,42 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
 
     const shell     = fs.readFileSync(indexPath, 'utf-8')
     let succeeded   = 0
+    let cacheHits   = 0
     const failures  = []
     const cache     = readCache({ cacheFile: p.cacheFile })
+    // Honest per-route sitemap dates: consumed by generateSitemap's <lastmod>.
+    const routeMtimes = new Map()
+    // Per-route OG image generation (#43): resolved once per run, rendered
+    // for EVERY route in the set before the render loop -- a cache-hit route
+    // must still ship its (new-template) PNG, or a vite-cleared dist would
+    // carry head tags pointing at a missing file. Routes with their own
+    // og:image override keep theirs (missing-only).
+    const ogImageGeneration = resolveOgImageGeneration(cfg, p.root)
+    // The config-gated head additions that rendered HTML depends on: carried
+    // into the incremental cache signature (QC sweep: flipping these on
+    // between builds used to ride a valid-cache hit and never reach the
+    // shipped head). Route-level alternates/jsonLd are already covered
+    // via route.meta in the base signature.
+    const headExtras = buildHeadExtras(cfg, ogImageGeneration)
+    const routeOgOverrides = new Map()
+    if (ogImageGeneration) {
+      // Slug collision guard: imageSlug flattens '/' to '-', so '/blog/post-1'
+      // and '/blog-post-1' both map to 'blog-post-1.png'. Without this, the
+      // second render silently OVERWRITES the first's PNG while both pages
+      // point at the same file -- two routes, one image, no error. Surface it
+      // loudly (author picks distinct paths, or an og:image override).
+      const slugSeen = new Map()
+      for (const route of ROUTES) {
+        if (route && route.meta && route.meta.ogImage) continue
+        const slug = imageSlug(route.path)
+        if (slugSeen.has(slug) && slugSeen.get(slug) !== route.path) {
+          console.warn(`[prerender] og image slug collision: "${route.path}" and "${slugSeen.get(slug)}" both map to og/${slug}.png -- the generated image is shared; set a distinct og:image on one route`)
+        }
+        slugSeen.set(slug, route.path)
+        const generated = renderRouteOgImage(ogImageGeneration, route, siteUrl, p.dist)
+        if (generated) routeOgOverrides.set(route.path, `${siteUrl.replace(/\/$/, '')}${generated.src}`)
+      }
+    }
 
     console.log(`[prerender] Cache: ${Object.keys(cache).length} routes cached${force ? ' (forcing rebuild)' : ''}`)
 
@@ -626,10 +1113,11 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
       // 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)) {
+      if (!force && cacheEntryValid(cache[route.path], route, siteUrl, shell, headExtras)) {
         fs.mkdirSync(path.dirname(distPath), { recursive: true })
-        fs.writeFileSync(distPath, cache[route.path].html, 'utf-8')
+        writeRouteFile(distPath, cache[route.path].html, routeMtimes, route.path)
         console.log(`[prerender] cached ${route.path}`)
+        cacheHits++
         succeeded++
         continue
       }
@@ -646,13 +1134,15 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
 
         // Attribute-tolerant root-div injection (carries inject-brand attrs)
         let html = replaceRootDiv(shell, appHtml)
-        html = injectMeta(html, route.meta || {}, route.path, siteUrl, cfg.ogImage)
+        // Per-route branded og:image when generated (#43); global otherwise.
+        const routeOg = routeOgOverrides.get(route.path) || cfg.ogImage
+        html = injectMeta(html, route.meta || {}, route.path, siteUrl, routeOg, headExtras)
 
         // Save to cache with a signature over exactly these rendered inputs
-        cache[route.path] = { html, time: Date.now(), sig: cacheSignature(route, siteUrl, shell) }
+        cache[route.path] = { html, time: Date.now(), sig: cacheSignature(route, siteUrl, shell, headExtras) }
 
         fs.mkdirSync(path.dirname(distPath), { recursive: true })
-        fs.writeFileSync(distPath, html, 'utf-8')
+        writeRouteFile(distPath, html, routeMtimes, route.path)
 
         console.log(`[prerender] ok ${route.path}`)
         succeeded++
@@ -669,8 +1159,11 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
     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')
+    // sitemap.xml -- overwrites the static one in public/, honest lastmods
+    fs.writeFileSync(path.join(p.dist, 'sitemap.xml'), generateSitemap(ROUTES, siteUrl, routeMtimes), 'utf-8')
+
+    // llms.txt -- generated-only after the sitemap (same baked route set)
+    generateLlms(ROUTES, cfg, p.dist)
     console.log('[prerender] ok /sitemap.xml')
 
     // robots.txt -- opt-in only (config.robots): without it the author-owned
@@ -691,7 +1184,7 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
     const stats = {
       routeCount: ROUTES.length,
       succeeded,
-      cached: Object.keys(cache).length,
+      cached: cacheHits,
       force,
       routes: ROUTES.map(r => ({ path: r.path, cached: Boolean(cache[r.path]) })),
     }
@@ -704,7 +1197,7 @@ export async function prerender(cfg = config, { force = false, root } = {}) {
     // 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 }
+    return { total: ROUTES.length, succeeded, cached: cacheHits, failed: failures.length, failures }
 
   } finally {
     await vite.close()