prestruct 1.0.0 → 1.2.0

package/init/scripts/hooks.js

@@ -0,0 +1,93 @@
+// engine/scripts/hooks.js - general postBuild hook contract (prestruct#41,
+// port of the freestruct tag reference; prestruct#21's shape). Replaces the
+// npm-script chain ("prestruct build && node scripts/whatever.mjs") with a
+// first-class seam:
+//
+//   // ssr.config.js
+//   hooks: { postBuild: ['node scripts/inject-faq-schema.mjs'] }
+//   runHooks: true,   // opt-in: nothing executes without it
+//
+// Security posture (why the gate): postBuild entries are shell commands
+// sourced from the config file. A malicious or typo'd config must not gain
+// a silent execution path, so nothing runs unless runHooks is explicitly
+// true - logged loudly either way. The build pipeline runs the hooks
+// itself, so `prestruct build` can no longer skip them the way it skipped
+// the npm-script chain.
+//
+// Values ride FUNCTION replacers, never string-form replace strings: an
+// output path carrying $& or $1..9 is replacement SYNTAX in string form
+// and would corrupt the command about to run (the same never-corrupt rule
+// the injection pipeline enforces on head values).
+//
+// This module NEVER exits: it returns the failure list; bin/cli.mjs turns
+// the collection into the build exit.
+
+import { execSync } from 'child_process'
+
+/** Build a fresh env for hook children: same facts as the placeholders, so
+ * a hook script does not do string surgery to learn where the build landed. */
+function hookEnv({ siteUrl, outputDir }) {
+  return {
+    ...process.env,
+    PRESTRUCT_SITE_URL: siteUrl,
+    PRESTRUCT_OUTPUT_DIR: outputDir,
+  }
+}
+
+function substitutePlaceholders(command, { siteUrl, outputDir }) {
+  return command
+    .replace(/\$\{?SITE_URL\}?/g, function () { return siteUrl })
+    .replace(/\$\{?OUTPUT_DIR\}?/g, function () { return outputDir })
+}
+
+/**
+ * Run config.hooks.postBuild (string | string[]): each entry spawned with
+ * stdio inherited and a 30-second timeout (the family reference posture:
+ * a hung hook may cost the build its runtime, never the deploy); a hook
+ * that genuinely needs longer can background its own work. PRESTRUCT_SITE_URL
+ * and PRESTRUCT_OUTPUT_DIR are in the env, placeholders substituted via
+ * function replacers. Returns the list of failed entries (empty = clean).
+ */
+export function runPostBuildHooks(config, { siteUrl, outputDir } = {}) {
+  const raw = config?.hooks?.postBuild
+  if (raw === undefined || raw === null) return []
+  const commands = Array.isArray(raw) ? raw : [raw]
+  if (commands.length === 0) return []
+
+  const url = siteUrl ?? config.siteUrl ?? ''
+  const out = outputDir ?? 'dist'
+  const failures = []
+  let gated = false
+
+  for (const entry of commands) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+      console.log('[prestruct] hooks.postBuild entry is not a non-empty string command - skipped')
+      continue
+    }
+    const command = substitutePlaceholders(entry, { siteUrl: url, outputDir: out })
+
+    if (config.runHooks !== true) {
+      console.log('[prestruct] PostBuild hook (not run - set runHooks: true to enable): '
+        + command.slice(0, 100))
+      gated = true
+      continue
+    }
+
+    console.log('[prestruct] PostBuild hook: running ' + command.slice(0, 76) + '...')
+    try {
+      execSync(command, { stdio: 'inherit', timeout: 30 * 1000, env: hookEnv({ siteUrl: url, outputDir: out }) })
+      console.log('[prestruct] PostBuild hook: done')
+    } catch (e) {
+      console.log('[prestruct] PostBuild hook: FAILED (exit ' + (e.status ?? e.message) + ')')
+      // Timeout kills surface as a signal, not an exit code - record it so a
+      // hung hook is distinguishable from a clean nonzero exit.
+      failures.push({ command: entry, status: e.status, signal: e.signal })
+    }
+  }
+
+  if (gated && failures.length === 0) {
+    console.log('[prestruct] hooks.postBuild is configured but no hook ran '
+      + '(opt-in gate: set runHooks: true in ssr.config.js)')
+  }
+  return failures
+}

package/init/scripts/indexnow.js

@@ -0,0 +1,139 @@
+// engine/scripts/indexnow.js - IndexNow key-file emission + submission
+// (prestruct#36 port of the freestruct tag reference; prestruct owns the
+// sitemap in prerender.js, so the fit is the same: key file into dist/ =
+// the keyLocation contract, a `prestruct indexnow` verb that reads the
+// BAKED sitemap.xml (the source of truth for what is actually live, not
+// config) and POSTs the URL list. Honesty contract: submission only makes
+// sense AFTER the output is deployed live (keyLocation must resolve at
+// host/key.txt) - docs say so; the verb surfaces HTTP status codes; the
+// --dry-run flag prints the request body without touching the network.
+// This module NEVER exits: exit codes belong to bin/cli.mjs, same as audit.
+
+import fs from 'fs'
+import crypto from 'crypto'
+import path from 'path'
+
+export const INDEXNOW_API = 'https://api.indexnow.org/indexnow'
+
+/** 32 lowercase hex chars is the documented IndexNow key shape. */
+export function isValidIndexNowKey(key) {
+  return typeof key === 'string' && /^[a-f0-9]{32}$/.test(key)
+}
+
+/**
+ * Resolve the IndexNow key for a run.
+ *   indexNow.key (config, 32-hex)   wins
+ *   indexNow: true                  reads configDir/indexnow-key.txt, or
+ *                                   generates one and PERSISTS it
+ *                                   (generate-once: the same key across
+ *                                   runs keeps the keyLocation stable at
+ *                                   the search engines)
+ * Rotating? Change the config key or delete indexnow-key.txt - loudly
+ * logged. Returns { key, source } or null when IndexNow is not configured.
+ */
+export function resolveIndexNowKey(config, configDir) {
+  const cfg = config.indexNow
+  if (cfg === undefined || cfg === null || cfg === false) return null
+  if (typeof cfg === 'string' || typeof cfg === 'object') {
+    const key = typeof cfg === 'string' ? cfg : cfg.key
+    if (key !== undefined && key !== null) {
+      if (!isValidIndexNowKey(key)) return null // config diagnostics already warned
+      return { key, source: 'config' }
+    }
+  }
+  const persistPath = path.join(configDir, 'indexnow-key.txt')
+  if (fs.existsSync(persistPath)) {
+    const key = fs.readFileSync(persistPath, 'utf8').trim()
+    if (isValidIndexNowKey(key)) return { key, source: 'persisted (indexnow-key.txt)' }
+  }
+  const key = crypto.randomBytes(16).toString('hex')
+  fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(persistPath, key + '\n', 'utf8')
+  console.log('[prestruct] indexnow: generated a new key and persisted it to '
+    + persistPath
+    + ' (generate-once: commit this file so the keyLocation stays stable across runs)')
+  return { key, source: 'generated' }
+}
+
+/** Emit <key>.txt into the output dir (the keyLocation file engines probe). */
+export function emitIndexNowKeyFile(key, outputDir) {
+  const keyFile = path.join(outputDir, key + '.txt')
+  fs.writeFileSync(keyFile, key + '\n', 'utf8')
+  console.log('[prestruct] indexnow: key file written: ' + key
+    + '.txt (deploy it live - keyLocation must resolve)')
+  return keyFile
+}
+
+/** Read the baked sitemap.xml and return its URL list (null when absent/empty). */
+export function readSitemapUrls(outputDir) {
+  const sitemapPath = path.join(outputDir, 'sitemap.xml')
+  if (!fs.existsSync(sitemapPath)) return null
+  const sitemap = fs.readFileSync(sitemapPath, 'utf8')
+  const urls = (sitemap.match(/<loc>([\s\S]*?)<\/loc>/g) || [])
+    .map(function (e) { return e.replace(/<\/?loc>/g, '').trim() })
+    .filter(Boolean)
+  return urls.length > 0 ? urls : null
+}
+
+/**
+ * POST the sitemap URL list to api.indexnow.org. Returns the HTTP status so
+ * the caller can surface it (202 = accepted). dryRun skips the network and
+ * prints the request body instead - the CI-safe shape.
+ */
+export async function submitIndexNow({ config, configDir, outputDir, dryRun }) {
+  const resolved = resolveIndexNowKey(config, configDir)
+  if (!resolved) {
+    console.log('[prestruct] indexnow: not configured (set indexNow in ssr.config.js)')
+    return { ok: false, status: null, reason: 'not-configured' }
+  }
+
+  const urls = readSitemapUrls(outputDir)
+  if (!urls) {
+    console.log('[prestruct] indexnow: no sitemap.xml with <loc> entries in '
+      + outputDir + ' - run prestruct build first (indexnow reads the baked sitemap)')
+    return { ok: false, status: null, reason: 'no-sitemap' }
+  }
+
+  let host
+  try { host = new URL(config.siteUrl).host } catch {
+    console.log('[prestruct] indexnow: siteUrl is not parseable - cannot derive host')
+    return { ok: false, status: null, reason: 'bad-site-url' }
+  }
+
+  const payload = {
+    host,
+    key: resolved.key,
+    urlList: urls,
+    keyLocation: config.siteUrl.replace(/\/$/, '') + '/' + resolved.key + '.txt',
+  }
+
+  console.log('[prestruct] indexnow: submitting ' + urls.length + ' URL(s) to '
+    + INDEXNOW_API + ' (key source: ' + resolved.source + ')')
+  if (dryRun) {
+    console.log('[prestruct] indexnow: --dry-run, request body:')
+    console.log(JSON.stringify(payload, null, 2))
+    return { ok: true, status: 'dry-run', reason: 'dry-run' }
+  }
+
+  let res
+  try {
+    res = await fetch(INDEXNOW_API, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      body: JSON.stringify(payload),
+    })
+  } catch (e) {
+    console.log('[prestruct] indexnow: request failed: ' + e.message)
+    return { ok: false, status: null, reason: 'network-error' }
+  }
+
+  console.log('[prestruct] indexnow: HTTP ' + res.status
+    + (res.status === 200 || res.status === 202
+      ? ' (accepted)'
+      : ' (NOT accepted - the engines surface failures; check the key file is deployed live)'))
+  if (res.status !== 200 && res.status !== 202) {
+    const body = await res.text().catch(function () { return '' })
+    if (body) console.log('[prestruct] indexnow: response: ' + body.slice(0, 300))
+  }
+  return { ok: res.status === 200 || res.status === 202, status: res.status, reason: 'http' }
+}

package/init/scripts/inject-brand.js

@@ -127,6 +127,35 @@ function defaultGetDeployId() {
  * never exits.
  *
  * @param {object} config - full ssr.config.js export
+/**
+ * Config-driven JSON-LD defaults (#30): Organization + WebSite, built from
+ * the same siteName/siteUrl/author keys the head already consumes. A host
+ * that never defines buildJsonLd still ships both blocks. Exported for the
+ * battery: the shape is a contract, not an implementation detail.
+ *
+ * @param {{siteUrl?: string, siteName?: string, author?: string}} config
+ * @returns {object|null} wrapped payload ({@graph}) or null when nothing
+ *   is derivable (no siteUrl AND no siteName/author).
+ */
+export function buildDefaultJsonLd({ siteUrl, siteName, author } = {}) {
+  const base = siteUrl ? siteUrl.replace(/\/$/, '') : ''
+  const nodes = []
+  if (siteName || author || base) {
+    const org = { '@type': 'Organization' }
+    if (siteName || author) org.name = siteName || author
+    if (base) org.url = base
+    nodes.push(org)
+  }
+  // WebSite is only emitted with BOTH identity facts: a name-less or
+  // URL-less WebSite node is schema-invalid, not "shorter defaults".
+  if (siteName && base) {
+    nodes.push({ '@type': 'WebSite', name: siteName, url: base })
+  }
+  if (nodes.length === 0) return null
+  return { '@context': 'https://schema.org', '@graph': nodes }
+}
+
+/**
  * @param {string} [distDir=resolve('dist')] - build output directory
  * @param {{getDeployId?: Function, projectRoot?: string}} [opts] - injection hooks
  * @returns {void}
@@ -135,7 +164,7 @@ export function injectBrand(config, distDir = resolve('dist'), { getDeployId = d
   const {
     platform = 'cloudflare',
     siteUrl, siteName, author, tagline, ogImage, keywords,
-    routes = [], buildJsonLd, proxy = {},
+    routes = [], buildJsonLd, proxy = {}, jsonLdDefaults,
   } = config
 
   // Only generate Cloudflare-specific files (_headers, _redirects)
@@ -148,24 +177,63 @@ export function injectBrand(config, distDir = resolve('dist'), { getDeployId = d
   const htmlPath = join(distDir, 'index.html')
 
   if (!existsSync(htmlPath)) {
+    // Library-safe (matches this function's contract): RETURN, never
+    // process.exit -- the CLI calls injectBrand in-process, so exiting here
+    // would kill the whole build silently with code 0, a green fail-open
+    // right where a missing shell should be a hard error. The direct-run
+    // wrapper (isMainExecute) turns the null return into exit 0 for the
+    // legacy standalone path.
     console.warn('[inject-brand] dist/index.html not found -- skipping')
-    process.exit(0)
+    return null
   }
 
   // Homepage meta as the global description fallback
   const homeRoute   = routes.find(r => r.path === '/') || {}
   const title       = generateTitle(siteName, tagline)
   const description = homeRoute.meta?.description || null
-  const canonical   = `${siteUrl}/`
+  // Trailing-slash normalization (#53): the canonical + entire og block ride
+  // this base; a consumer pasting `https://x.example.com/` used to get
+  // `https://x.example.com//` -- validated form, doubled junction.
+  // Home canonical is the BARE origin, no trailing slash (#76): the same form
+  // prerender.injectMeta and generateSitemap use for `/`, so the global head
+  // inject-brand writes agrees with every per-route surface (the 404 used to
+  // be the lone outlier carrying `siteUrl/`).
+  const canonical   = (siteUrl || '').replace(/\/$/, '')
 
   const titleSafe       = toReplaceSafe(escapeHtmlAttr(title))
   const descriptionSafe = toReplaceSafe(escapeHtmlAttr(description))
   const authorSafe      = toReplaceSafe(escapeHtmlAttr(author))
   const keywordsSafe    = toReplaceSafe(escapeHtmlAttr(keywords))
   const canonicalSafe   = toReplaceSafe(escapeHtmlAttr(canonical))
-  const ogImageSafe     = toReplaceSafe(escapeHtmlAttr(ogImage))
   const siteNameSafe    = toReplaceSafe(escapeHtmlAttr(siteName))
 
+  // og:image accepts the legacy string shorthand AND the structured object
+  // form (object contract per validate-config): { url, width, height, alt,
+  // type }. Companion properties are emitted ONLY when present and only
+  // when their value validates at this seam, so a typo'd companion can
+  // never corrupt the head (same never-corrupt rule as the escape pipeline).
+  const ogImgObject = (ogImage && typeof ogImage === 'object' && !Array.isArray(ogImage))
+    ? ogImage
+    : (ogImage ? { url: String(ogImage) } : null)
+  const ogImgUrl     = typeof ogImgObject?.url === 'string' ? ogImgObject.url : ''
+  const ogImgWidth   = /^[0-9]+$/.test(String(ogImgObject?.width  ?? '')) ? String(ogImgObject.width) : ''
+  const ogImgHeight  = /^[0-9]+$/.test(String(ogImgObject?.height ?? '')) ? String(ogImgObject.height) : ''
+  const ogImgAlt     = typeof ogImgObject?.alt === 'string' ? ogImgObject.alt : ''
+  const ogImgType    = typeof ogImgObject?.type === 'string' ? ogImgObject.type : ''
+
+  const ogImageSafe     = toReplaceSafe(escapeHtmlAttr(ogImgUrl))
+  const ogImgWidthSafe  = toReplaceSafe(escapeHtmlAttr(ogImgWidth))
+  const ogImgHeightSafe = toReplaceSafe(escapeHtmlAttr(ogImgHeight))
+  const ogImgAltSafe    = toReplaceSafe(escapeHtmlAttr(ogImgAlt))
+  const ogImgTypeSafe   = toReplaceSafe(escapeHtmlAttr(ogImgType))
+  // og:image:secure_url is emitted only for http:// sources, as the upgraded
+  // https variant. An already-https source makes the property redundant
+  // (og:image itself is the secure form) -- emitting it there just doubles
+  // the same URL in the head.
+  const ogImgSecureSafe = ogImgUrl.startsWith('http://')
+    ? toReplaceSafe(escapeHtmlAttr('https://' + ogImgUrl.slice('http://'.length)))
+    : ''
+
   let html = readFileSync(htmlPath, 'utf8')
 
   // -- Deploy ID --------------------------------------------------------------
@@ -193,7 +261,12 @@ export function injectBrand(config, distDir = resolve('dist'), { getDeployId = d
   // stripped when not (safe to run on rebuild either way). It travels on the
   // root div and is carried through prerendering by replaceRootDiv.
   if (showFooter) {
-    html = html.replace(/<div id="root"/, '<div id="root" data-deploy-id-footer')
+    // Insert after the root div's `id="root"` wherever it sits -- the old
+    // byte-exact `/<div id="root"/` missed a reflowed shell (single quotes,
+    // spaces around `=`, or an attribute before the id), silently dropping the
+    // opt-in footer attribute the config asked for with no warning. Match the
+    // same attribute-tolerant span the rest of the engine uses.
+    html = html.replace(/(<div\b[^>]*\sid\s*=\s*["']root["'])/, '$1 data-deploy-id-footer')
   } else {
     html = html.replace(/ data-deploy-id-footer/g, '')
   }
@@ -226,15 +299,30 @@ export function injectBrand(config, distDir = resolve('dist'), { getDeployId = d
     `<link rel="canonical" href="${canonicalSafe}" />`)
 
   // -- Remove previously injected OG / JSON-LD blocks (safe to run on rebuild) --
-
-  html = html.replace(/\n\s*<!-- Open Graph -->[\s\S]*?<\/script>\s*/g, '\n  ')
+  // Bounded at </head>: the old `[\s\S]*?<\/script>` lazily matched the block's
+  // own closing <script>, but when inject-brand emitted NO JSON-LD (buildJsonLd
+  // returned nothing, or jsonLdDefaults:false) there was no engine <script> to
+  // stop at -- the match ran past </head> into <body> and ate the root div and
+  // the app entry script on the SECOND run (docs promise idempotence). The
+  // injected block always sits immediately before </head>, so anchor there.
+  html = html.replace(/\n\s*<!-- Open Graph -->[\s\S]*?(?=\n\s*<\/head>)/g, '')
 
   // -- Open Graph + Twitter Card -----------------------------------------------
 
-  // Only include image tags if ogImage is provided
-  const imageMeta = ogImage ? `
+  // Only include image tags if an og:image url resolves (string shorthand or
+  // object form). Companion properties ride below the pair so inject-brand
+  // output stays one copy-pasted block.
+  const imageCompanions = [
+    ogImgSecureSafe ? `    <meta property="og:image:secure_url" content="${ogImgSecureSafe}" />` : '',
+    ogImgTypeSafe   ? `    <meta property="og:image:type"      content="${ogImgTypeSafe}" />` : '',
+    ogImgWidthSafe  ? `    <meta property="og:image:width"     content="${ogImgWidthSafe}" />` : '',
+    ogImgHeightSafe ? `    <meta property="og:image:height"    content="${ogImgHeightSafe}" />` : '',
+    ogImgAltSafe    ? `    <meta property="og:image:alt"       content="${ogImgAltSafe}" />` : '',
+  ].filter(Boolean).join('\n')
+
+  const imageMeta = ogImgUrl ? `
     <meta property="og:image"        content="${ogImageSafe}" />
-    <meta name="twitter:image"       content="${ogImageSafe}" />` : ''
+    <meta name="twitter:image"       content="${ogImageSafe}" />${imageCompanions ? '\n' + imageCompanions : ''}` : ''
 
   const ogTags = `
     <!-- Open Graph -->
@@ -273,6 +361,20 @@ export function injectBrand(config, distDir = resolve('dist'), { getDeployId = d
     ${JSON.stringify(payload, null, 2).replace(/</g, '\\u003c')}
     </script>`
     }
+  } else if (jsonLdDefaults !== false) {
+    // Config-driven defaults (#30): a host that never defines buildJsonLd
+    // used to ship zero structured data even though config already carries
+    // siteName/siteUrl/author - the exact data Organization/WebSite need.
+    // Defaults emit those two nodes; jsonLdDefaults: false opts out. The
+    // payload walks the same object/array wrapper as the host-provided form.
+    const defaults = buildDefaultJsonLd({ siteUrl, siteName, author })
+    if (defaults) {
+      jsonLdBlock = `
+    <!-- JSON-LD Structured Data -- engine defaults (set jsonLdDefaults: false in ssr.config.js to skip) -->
+    <script type="application/ld+json">
+    ${JSON.stringify(defaults, null, 2).replace(/</g, '\\u003c')}
+    </script>`
+    }
   }
 
   const jsonLdBlockSafe = toReplaceSafe(jsonLdBlock)

package/init/scripts/ogimage.js

@@ -0,0 +1,165 @@
+// engine/scripts/ogimage.js - per-route OG image generation (prestruct#43,
+// port of the freestruct tag reference; the prestruct route set + per-route
+// meta titles/descriptions already live in prerender.js, so this reads the
+// same facts). Read each route's title/description, render a branded
+// 1200x630 PNG per route from a consumer-authored SVG template, write the
+// file into dist/og/, and wire the og/twitter tags to it (missing-only:
+// a route with its own og:image override keeps theirs).
+//
+// Rasterization honesty (the pitch's own hard part): PNG cannot be made in
+// pure Node. The rasterizer is the OPTIONAL npm package @resvg/resvg-js -
+// loaded lazily with createRequire and skipped loudly when it is not
+// installed (the run never breaks, never ships a half feature). Pure-Node
+// output shape: SVG rendering is deterministic (same route meta ->
+// same bytes). Fonts: system fonts are unreliable in build sandboxes, so
+// ogImageGeneration.font loads a TTF/OTF buffer straight into the raster.
+//
+// Config shape (configDir-relative paths):
+//   ogImageGeneration:
+//     template: og-template.svg   # 1200x630 SVG with {{ogTitle}} /
+//                                 # {{ogDescription}} / {{ogUrl}}
+//     font: ./brand/brand-bold.ttf  # optional
+//     width: 1200                  # optional
+//     height: 630                  # optional
+//
+// This module NEVER exits: callers own failure semantics (prerender skips
+// loudly, the audit still grades the head).
+
+import fs from 'fs'
+import path from 'path'
+import { createRequire } from 'module'
+
+const _require = createRequire(import.meta.url)
+
+/**
+ * Local XML escape for template substitution values: same replacement set
+ * as prerender's escapeXml, kept local so this module stays dependency-free
+ * (prerender owns no ogimage concerns and importing it back would be a cycle).
+ */
+function escXml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/** Directory slug for the image filename: '/' and nested paths flatten.
+ *  Exported so the caller can detect slug collisions between routes. */
+export function imageSlug(routePath) {
+  return String(routePath).replace(/^\/+|\/+$/g, '').replace(/\//g, '-') || 'index'
+}
+
+/** Lazily resolve the optional rasterizer CLASS; null when not installed. */
+function resolveRasterizer() {
+  try {
+    const mod = _require('@resvg/resvg-js')
+    // CJS shape: { default?: Resvg, Resvg } ; ESM default handled too.
+    const ctor = mod.Resvg || mod.default || mod
+    return (typeof ctor === 'function') ? ctor : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Validate + resolve the generation block. Returns null when it is not
+ * configured; every disqualifying shape logs a loud single warning (config
+ * diagnostics already handled key-name mistakes).
+ */
+export function resolveOgImageGeneration(config, configDir) {
+  const gen = config && config.ogImageGeneration
+  if (gen === undefined || gen === null || gen === false) return null
+  if (typeof gen !== 'object' || Array.isArray(gen)) {
+    console.log('[ogimage] config warning: ogImageGeneration must be a { template, font?, width?, height? } object')
+    return null
+  }
+  if (typeof gen.template !== 'string' || gen.template === '') {
+    console.log('[ogimage] config warning: ogImageGeneration.template missing - no og image generation')
+    return null
+  }
+  const templatePath = path.resolve(configDir, gen.template)
+  if (!fs.existsSync(templatePath)) {
+    console.log('[ogimage] config warning: ogImageGeneration.template "'
+      + gen.template + '" not found at ' + templatePath + ' - no og image generation')
+    return null
+  }
+  const width = Number(gen.width ?? 1200)
+  const height = Number(gen.height ?? 630)
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    console.log('[ogimage] config warning: ogImageGeneration width/height must be positive numbers - no og image generation')
+    return null
+  }
+  const fontPath = gen.font ? path.resolve(configDir, gen.font) : null
+  if (gen.font && (!fontPath || !fs.existsSync(fontPath))) {
+    console.log('[ogimage] config warning: ogImageGeneration.font "'
+      + gen.font + '" not found at ' + fontPath + ' - the rasterizer will fall back to system fonts (unreliable in build sandboxes)')
+    return null
+  }
+  const template = fs.readFileSync(templatePath, 'utf8')
+  const fontBytes = fontPath ? fs.readFileSync(fontPath) : null
+  if (/<text/i.test(template) && !fontBytes) {
+    console.log('[ogimage] warning: template carries <text> but no font is configured - add ogImageGeneration.font so build sandboxes without system fonts do not drop titles')
+  }
+  return { template, templatePath, fontPath, fontBytes, width, height }
+}
+
+/**
+ * Render one per-route image into dist/og/ and hand back the tag-ready
+ * facts. Returns null when the rasterizer is not installed (loud skip,
+ * surfaced once per run) or the SVG fails to rasterize. The og:url is
+ * template-fillable via {{ogUrl}}; the caller derives the absolute
+ * base from config.siteUrl.
+ *
+ * @param {object} generation - resolved block from resolveOgImageGeneration
+ * @param {{path: string, meta?: {title?: string, description?: string}}} route
+ * @param {string} siteUrl - configured site origin
+ * @param {string} outputDir - dist/
+ * @returns {{src: string, width: number, height: number, alt: string}|null}
+ */
+export function renderRouteOgImage(generation, route, siteUrl, outputDir) {
+  const Resvg = resolveRasterizer()
+  if (!Resvg) {
+    if (!renderRouteOgImage._skippedLoudly) {
+      renderRouteOgImage._skippedLoudly = true
+      console.log('[ogimage] @resvg/resvg-js is not installed - generation skips loudly'
+        + ' (pure-Node cannot rasterize; install it with: npm install --save-dev @resvg/resvg-js)')
+    }
+    return null
+  }
+
+  const routePath = route && typeof route.path === 'string' ? route.path : '/'
+  const routeUrl = ((siteUrl || '').replace(/\/$/, '')) + (routePath === '/' ? '/' : routePath)
+  const displayTitle = (route.meta && route.meta.title) || routePath || 'Preview'
+  const svg = generation.template
+    .split('{{ogTitle}}').join(escXml(displayTitle))
+    .split('{{ogDescription}}').join(escXml((route.meta && route.meta.description) || ''))
+    .split('{{ogUrl}}').join(escXml(routeUrl))
+
+  const fontBuffers = generation.fontBytes ? [generation.fontBytes] : undefined
+  let png
+  try {
+    const rendered = new Resvg(svg, {
+      fitTo: { mode: 'width', value: generation.width },
+      font: fontBuffers ? { fontBuffers, loadSystemFonts: false } : { loadSystemFonts: false },
+    })
+    png = rendered.render().asPng()
+  } catch (e) {
+    console.log('[ogimage] route ' + routePath + ' failed to rasterize: ' + e.message)
+    return null
+  }
+
+  const name = imageSlug(routePath)
+  const genDir = path.join(outputDir, 'og')
+  if (!fs.existsSync(genDir)) fs.mkdirSync(genDir, { recursive: true })
+  const file = path.join(genDir, name + '.png')
+  fs.writeFileSync(file, png)
+
+  return {
+    src: '/og/' + name + '.png',
+    width: generation.width,
+    height: generation.height,
+    alt: displayTitle + ' - page preview image',
+  }
+}