prestruct 1.1.0 → 1.2.0

package/init/scripts/proxy.js

@@ -64,7 +64,22 @@ let TARGET_URL     = null
 let BOT_LIST       = []
 let SECRET_SHA256  = null
 
-export const PORT = parseInt(process.env.PORT || '3000', 10)
+export const PORT = normalizePort(process.env.PORT)
+
+// Port guard (walk 2026-10): a junk PORT env ("", "3000x", "port") made
+// parseInt() produce NaN and server.listen(NaN) died at startup with a
+// runtime error far from its cause. Validate and fall back loudly.
+export function normalizePort(raw) {
+  // Number(), not parseInt(): parseInt("3000x") silently returns 3000, so a
+  // junk PORT env with a valid prefix ("3000abc") passed validation and the
+  // server bound an unintended port instead of falling back loudly.
+  const n = Number(raw ?? 3000)
+  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+    console.warn(`[proxy] PORT "${raw}" is not a valid port -- falling back to 3000`)
+    return 3000
+  }
+  return n
+}
 
 // -- Secret compare (constant time) -------------------------------------------
 // Only honoured when a secret is configured and matches. Hash both sides to a
@@ -96,7 +111,6 @@ export function isBot(ua) {
 // the module was imported from.
 const CACHE_DIR    = path.resolve(process.env.PRESTRUCT_CACHE_DIR || '.prestruct_cache')
 const CACHE_TTL    = 1000 * 60 * 60 * 24   // 24 hours -- adjust if needed
-const MAX_CACHE_SIZE = 500 * 1024 * 1024    // 500MB max cache size
 
 if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true })
 
@@ -124,31 +138,49 @@ function cacheWrite(key, html) {
 
 // Cleanup old/large cache files
 let lastCleanup = 0
-function cleanupCache() {
+
+// Eviction only ever touches cache-shaped files: a 64-hex `.html` written by
+// this proxy's cacheWrite. Walk 2026-10 finding: the old implementation
+// readdirSync'd the WHOLE cache dir and evicted the OLDEST FILES whatever
+// they were -- with the documented PRESTRUCT_CACHE_DIR override, an operator
+// mounting a shared/large directory as the cache could have their non-proxy
+// files deleted once the directory crossed the size limit. Decoys stay put.
+// The size cap is also an env knob now (PRESTRUCT_CACHE_MAX_MB, default 500)
+// so operators on small disks can turn eviction on before it matters -- and
+// so tests can exercise real eviction without 500MB of fixtures.
+const CACHE_FILE_SHAPE = /^[0-9a-f]{64}\.html$/
+export function cleanupCache({ force = false } = {}) {
   const now = Date.now()
-  // Only run cleanup once per minute max
-  if (now - lastCleanup < 60000) return
+  // Only run cleanup once per minute max (force bypasses for tests)
+  if (!force && now - lastCleanup < 60000) return
   lastCleanup = now
 
   try {
-    const files = fs.readdirSync(CACHE_DIR).map(f => {
-      const p = path.join(CACHE_DIR, f)
-      const stat = fs.statSync(p)
-      return { path: p, size: stat.size, mtime: stat.mtimeMs }
-    })
+    const maxCacheSize = Math.max(1, parseInt(process.env.PRESTRUCT_CACHE_MAX_MB || '500', 10) || 500) * 1024 * 1024
+    const files = fs.readdirSync(CACHE_DIR)
+      .filter(f => CACHE_FILE_SHAPE.test(f))
+      .map(f => {
+        const p = path.join(CACHE_DIR, f)
+        const stat = fs.statSync(p)
+        return { path: p, size: stat.size, mtime: stat.mtimeMs }
+      })
 
     // Calculate total size
     let totalSize = files.reduce((sum, f) => sum + f.size, 0)
 
     // If over limit, remove oldest files
-    if (totalSize > MAX_CACHE_SIZE) {
+    if (totalSize > maxCacheSize) {
       files.sort((a, b) => a.mtime - b.mtime)
-      while (totalSize > MAX_CACHE_SIZE * 0.8 && files.length > 0) {
+      const evicted = []
+      while (totalSize > maxCacheSize * 0.8 && files.length > 0) {
         const oldest = files.shift()
         fs.unlinkSync(oldest.path)
         totalSize -= oldest.size
+        evicted.push(oldest.path)
       }
-      console.log('[proxy] Cache cleaned up, removed', files.length, 'files')
+      // The old log printed the REMAINING count as "removed" -- misleading ops
+      // signal during incidents.
+      console.log('[proxy] Cache cleaned up, removed', evicted.length, 'files')
     }
   } catch (err) {
     console.warn('[proxy] Cache cleanup failed:', err.message)
@@ -233,8 +265,44 @@ export async function withRenderLimit(fn) {
   })
 }
 
-// -- Express app ---------------------------------------------------------------
+// -- Single-flight renders ---------------------------------------------------
+// (2026-10 walk): the concurrency limiter bounds how many renders run at once,
+// but a 50-bot burst on the same uncached URL still queued TEN sequential
+// renders of the identical page -- one full wave of 5 before the first HIT
+// could serve. renderOnce collapses a burst to one render: the first miss
+// opens a flight keyed by the cache key, every other identical miss awaits
+// the same promise and is served its bytes. Forced refreshes skip the flight
+// (their contract is bypass-the-cache, so they must not ride one) and own no
+// map entry, so a flight can never be deleted by a request that is not its
+// owner.
+const inflightRenders = new Map()
+
+/**
+ * Render a URL exactly once per burst: concurrent identical misses share the
+ * one render; forced refreshes bypass the flight entirely.
+ *
+ * @param {string} key  - sha256 cache key of the request URL
+ * @param {string} targetFullUrl - the origin URL page.goto renders
+ * @param {boolean} [forceRefresh] - true = render fresh, bypass the flight
+ * @returns {Promise<string>} rendered HTML (shared instance across joiners)
+ */
+export async function renderOnce(key, targetFullUrl, forceRefresh = false, renderFn = render) {
+  if (!forceRefresh && inflightRenders.has(key)) {
+    return inflightRenders.get(key)
+  }
+  const own = !forceRefresh
+  const promise = withRenderLimit(() => renderFn(targetFullUrl))
+  if (own) {
+    inflightRenders.set(key, promise)
+    promise.finally(function () {
+      if (inflightRenders.get(key) === promise) inflightRenders.delete(key)
+    }).catch(function () {})
+  }
+  return promise
+}
 
+// -- Express app ---------------------------------------------------------------
+// The app is a module-level singleton: one browser, one queue, one flight map.
 const app = express()
 
 // Live-fire fix (2026-10): the wildcard routes (`app.all('*')` /
@@ -250,11 +318,19 @@ export async function proxyHandler(req, res, next) {
   const ua  = req.headers['user-agent'] || ''
   const bot = isBot(ua)
 
-  // Validate and build the target URL. Reject anything that produces a non-HTTP scheme.
+  // Validate and build the target URL. Build it by concatenation (preserving
+  // any path prefix on targetUrl) and then require the resolved origin to
+  // equal the configured target origin, so a request target like
+  // `//evil.com/x` or `@evil.com/` can never swap the host. The old form
+  // relied on Node's HTTP parser rejecting `@`-prefixed targets -- correct
+  // today, but the SSRF guard should not hinge on parser behavior.
   let targetFullUrl
   try {
+    const base   = new URL(TARGET_URL)
     const parsed = new URL(`${TARGET_URL}${req.url}`)
-    if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error('Invalid protocol')
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.origin !== base.origin) {
+      throw new Error('Invalid target origin')
+    }
     targetFullUrl = parsed.toString()
   } catch {
     return res.status(400).send('Invalid request URL.')
@@ -280,7 +356,7 @@ export async function proxyHandler(req, res, next) {
   }
 
   try {
-    const html = await withRenderLimit(() => render(targetFullUrl))
+    const html = await renderOnce(key, targetFullUrl, forceRefresh)
     cacheWrite(key, html)
     res.setHeader('X-Prestruct-Cache',       'MISS')
     res.setHeader('X-Prestruct-Rendered-At', new Date().toISOString())
@@ -317,6 +393,13 @@ export function createProxyApp(config) {
   }
 
   BOT_LIST = proxyConfig.botList || []
+  if (!Array.isArray(proxyConfig.botList) || proxyConfig.botList.length === 0) {
+    // Loud config diagnostic (#52 form): a proxy with an empty bot list
+    // renders nothing -- every request, bot or not, gets the 302 and the
+    // operator sees a green process doing nothing. Config is author-owned,
+    // so this warns instead of failing.
+    console.warn('[proxy] config.proxy.botList is empty or missing -- no bot will ever be rendered (every request 302s). Set the browser token list.')
+  }
 
   const secret = process.env.PRESTRUCT_SECRET || null
   SECRET_SHA256 = secret

package/init/scripts/proxy.worker.js

@@ -38,13 +38,20 @@
  *
  * targetUrl vs siteUrl:
  *   Set PRESTRUCT_TARGET_URL in wrangler.toml [vars] to point the proxy at a
- *   different origin (WordPress, staging, localhost tunnel, etc.).
- *   Defaults to the `x-forwarded-host` of the incoming request if not set.
+ *   different origin (WordPress, staging, localhost tunnel, etc.). It is
+ *   required: an unset value fails the request with a 500 rather than falling
+ *   back to a guessed origin.
  *
  * Bot list:
  *   Maintained inline here. Sync with config.proxy.botList in ssr.config.js
  *   if you customise either. The Worker has no access to your build-time config.
  *
+ * Render load:
+ *   A per-isolate flight map collapses a burst of identical uncached misses
+ *   into one render, and a concurrency limiter (MAX_CONCURRENT) bounds how
+ *   many Browser Rendering sessions one isolate opens at once -- parity with
+ *   the VPS proxy's renderOnce + withRenderLimit.
+ *
  * Security:
  *   - Cache refresh requires the PRESTRUCT_SECRET value in x-prestruct-refresh,
  *     compared with a full-length constant-time XOR (see refreshSecretMatches).
@@ -91,6 +98,38 @@ export function cacheKey(url) {
   return `prestruct:${encodeURIComponent(url)}`
 }
 
+// Walk 2026-10 finding: KV keys are capped at 512 bytes -- a long query
+// string (tracked urls, exported search params) blows past the cap and the
+// KV put/get REJECTS, turning an already-successful render into a 500 on
+// the response path. The legacy encoding stays the key for every normal
+// URL (byte-identical existing cache entries); only oversized keys fall
+// back to SHA-256 hex (collision-proof per the shared cache-key lesson)
+// under a shape-tagged prefix. crypto.subtle is available in Workers AND any
+// Web-Crypto runtime; Node >=20 ships it as a global.
+export async function cacheKeyFor(url) {
+  const legacy = cacheKey(url)
+  if (legacy.length <= 500) return legacy
+  const bytes = new TextEncoder().encode(String(url))
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  const hex = [...new Uint8Array(digest)].map(b => b.toString(16).padStart(2, '0')).join('')
+  return `prestruct:sha256:${hex}`
+}
+
+/**
+ * TTL guard (walk 2026-10): KV's expirationTtl rejects non-numbers, values
+ * below the protocol minimum of 60s, and NaN -- and the put happens AFTER a
+ * successful, already-paid-for render, so a junk env value turned a working
+ * MISS into a 500 on the response path. Validate loudly at the seam.
+ */
+export function ttlFromEnv(raw) {
+  const n = parseInt(raw ?? '86400', 10)
+  if (!Number.isFinite(n)) {
+    console.warn(`[proxy:worker] CACHE_TTL_SECONDS "${raw}" is not a number -- falling back to 86400`)
+    return 86400
+  }
+  return Math.max(60, n) // KV minimum TTL; a shorter wish cannot be honored
+}
+
 // -- Secret compare (constant time) -------------------------------------------
 // Workers cannot import node:crypto, so there is no timingSafeEqual here.
 // The XOR form is the standard constant-time comparator available in any
@@ -109,13 +148,93 @@ export function refreshSecretMatches(secret, headerValue) {
   const len = Math.max(a.length, b.length)
   for (let i = 0; i < len; i++) {
     diff |= (a[i % a.length] || 0) ^ (b[i % b.length] || 0)
+  }  return diff === 0
+}
+
+// Single-flight render map, per isolate (module scope): a same-isolate burst
+// of identical uncached bots collapses into one render instead of one per
+// concurrent request; forced refreshes bypass it. KV is eventually
+// consistent, so this shares only within the isolate that owns the miss.
+const inflightRenders = new Map()
+
+// Render concurrency limit (parity with scripts/proxy.js): bounds how many
+// Browser Rendering sessions one isolate opens at once. Without it a bot
+// burst that misses the flight map launches unbounded sessions.
+export const MAX_CONCURRENT = 5
+let activeRenders = 0
+const renderQueue = []
+
+export async function withRenderLimit(fn) {
+  if (activeRenders < MAX_CONCURRENT) {
+    activeRenders++
+    try {
+      return await fn()
+    } finally {
+      activeRenders--
+      // Recurse into withRenderLimit (not fn directly) so the queued task
+      // re-acquires a slot; calling fn() directly skips the acquire and
+      // returns to unbounded concurrency under sustained load.
+      if (renderQueue.length > 0) {
+        const next = renderQueue.shift()
+        next()
+      }
+    }
+  }
+  return new Promise((resolve, reject) => {
+    renderQueue.push(() => { withRenderLimit(fn).then(resolve, reject) })
+  })
+}
+
+// Single-flight: the entry is set BEFORE the render is awaited, so a
+// same-isolate burst of identical misses joins the open flight instead of
+// each starting its own render. Returns { html, joined } so the caller can
+// label a joiner's response (FLIGHT) apart from the owner's (MISS). The
+// previous shape read the map before rendering and wrote it after, so the
+// flight was never observable and the FLIGHT branch was dead code.
+export async function renderOnce(key, targetFullUrl, forceRefresh, renderFn) {
+  if (!forceRefresh && inflightRenders.has(key)) {
+    const html = await inflightRenders.get(key)
+    return { html, joined: true }
+  }
+  const own = !forceRefresh
+  const promise = withRenderLimit(() => renderFn(targetFullUrl))
+  if (own) {
+    inflightRenders.set(key, promise)
+    promise.finally(function () {
+      if (inflightRenders.get(key) === promise) inflightRenders.delete(key)
+    }).catch(function () {})
+  }
+  const html = await promise
+  return { html, joined: false }
+}
+
+// Render via Browser Rendering API. The binding is imported lazily so the
+// module (and its unit tests) never require the @cloudflare/puppeteer
+// package -- only the render path does.
+async function renderViaBrowser(env, targetFullUrl) {
+  const { default: workerPuppeteer } = await import('@cloudflare/puppeteer')
+  const browser = await workerPuppeteer.launch(env.BROWSER)
+  let page
+  try {
+    page = await browser.newPage()
+    await page.setViewport({ width: 1280, height: 800 })
+    await page.setExtraHTTPHeaders({ 'X-Prestruct-Proxy': 'true' })
+    await page.goto(targetFullUrl, { waitUntil: 'networkidle0', timeout: 30000 })
+    return await page.content()
+  } finally {
+    if (page) {
+      try {
+        await page.close()
+      } catch {}
+    }
+    try {
+      await browser.close()
+    } catch {}
   }
-  return diff === 0
 }
 
 export default {
   async fetch(request, env) {
-    // Only GET
     if (request.method !== 'GET') {
       return new Response('Method not allowed.', { status: 405 })
     }
@@ -132,8 +251,11 @@ export default {
     const requestUrl = new URL(request.url)
     let targetFullUrl
     try {
+      const base   = new URL(TARGET_URL)
       const parsed = new URL(`${TARGET_URL}${requestUrl.pathname}${requestUrl.search}`)
-      if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error('Invalid protocol')
+      if (!['http:', 'https:'].includes(parsed.protocol) || parsed.origin !== base.origin) {
+        throw new Error('Invalid target origin')
+      }
       targetFullUrl = parsed.toString()
     } catch {
       return new Response('Invalid request URL.', { status: 400 })
@@ -151,8 +273,8 @@ export default {
     const refreshToken = request.headers.get('x-prestruct-refresh')
     const forceRefresh = refreshSecretMatches(SECRET, refreshToken)
 
-    const TTL = parseInt(env.CACHE_TTL_SECONDS || '86400', 10)
-    const key = cacheKey(requestUrl.pathname + requestUrl.search)
+    const TTL = ttlFromEnv(env.CACHE_TTL_SECONDS)
+    const key = await cacheKeyFor(requestUrl.pathname + requestUrl.search)
 
     // Try KV cache first (payload is the {html, cachedAt} JSON we now store)
     if (!forceRefresh) {
@@ -170,46 +292,41 @@ export default {
       }
     }
 
-    // Render via Browser Rendering API. The binding is imported lazily so the
-    // module (and its unit tests) never require the @cloudflare/puppeteer
-    // package -- only the render path does.
+    // Single-flight renders (2026-10 walk, parity with scripts/proxy.js): a
+    // same-isolate burst of identical misses collapses into one render (the
+    // flight entry is set before the render is awaited). Forced refreshes
+    // bypass the flight (their contract is bypass-the-cache). KV is eventually
+    // consistent, so no flight guarantees across isolates; this only removes
+    // the same-isolate duplication the burst case actually creates.
     let html
-    let browser
-    let page
+    let joined = false
     try {
-      const { default: workerPuppeteer } = await import('@cloudflare/puppeteer')
-      browser = await workerPuppeteer.launch(env.BROWSER)
-      page    = await browser.newPage()
-      await page.setViewport({ width: 1280, height: 800 })
-      await page.setExtraHTTPHeaders({ 'X-Prestruct-Proxy': 'true' })
-      await page.goto(targetFullUrl, { waitUntil: 'networkidle0', timeout: 30000 })
-      html = await page.content()
+      const result = await renderOnce(
+        key,
+        targetFullUrl,
+        forceRefresh,
+        (url) => renderViaBrowser(env, url),
+      )
+      html = result.html
+      joined = result.joined
     } catch (err) {
       console.error('[proxy:worker] Render failed:', err.message)
       // Fall through to live site on render failure
       return Response.redirect(targetFullUrl, 302)
-    } finally {
-      if (page) {
-        try {
-          await page.close()
-        } catch {}
-      }
-      if (browser) {
-        try {
-          await browser.close()
-        } catch {}
-      }
     }
 
     // Store in KV with TTL. JSON-encode with the render timestamp so the hit
     // path can report a real X-Prestruct-Rendered-At (the old form cached the
-    // bare HTML and reported a stale/absent date on every HIT).
-    await env.CACHE.put(key, JSON.stringify({ html, cachedAt: new Date().toISOString() }), { expirationTtl: TTL })
+    // bare HTML and reported a stale/absent date on every HIT). A joiner does
+    // not re-put: the flight owner's put already covers the key.
+    if (!joined) {
+      await env.CACHE.put(key, JSON.stringify({ html, cachedAt: new Date().toISOString() }), { expirationTtl: TTL })
+    }
 
     return new Response(html, {
       headers: {
         'Content-Type':            'text/html; charset=utf-8',
-        'X-Prestruct-Cache':       'MISS',
+        'X-Prestruct-Cache':       joined ? 'FLIGHT' : 'MISS',
         'X-Prestruct-Rendered-At': new Date().toISOString(),
       },
     })

package/init/scripts/validate-config.js

@@ -10,7 +10,11 @@
  */
 
 const PLATFORMS = ['cloudflare', 'vercel', 'netlify']
-const CHANGEFREQS = ['daily', 'weekly', 'monthly', 'yearly']
+// The full sitemap-protocol set, not the common four: 'hourly', 'always'
+// and 'never' are legal <changefreq> values, and correctly refusing nothing
+// the protocol accepts is the validator's job (a false "not in" error is
+// just a hard-to-name refusal of a host's honest config).
+const CHANGEFREQS = ['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']
 
 // Identity helper: `import { defineConfig } from 'prestruct'` for type-aware
 // ssr.config.js files. No preprocessing -- config is passed through.
@@ -26,6 +30,60 @@ export function defineConfig(config) {
   return config
 }
 
+// Known config keys (#52): the load-time diagnostics list. A key that is
+// neither known nor retired does NOTHING in the engine -- a typo'd seam
+// (`ogimg` instead of `ogImage`) must say so loudly instead of passing a
+// green build that silently loses SEO surface.
+export const KNOWN_CONFIG_KEYS = [
+  'siteUrl', 'siteName', 'author', 'tagline', 'ogImage', 'keywords',
+  'appLayoutPath', 'routes', 'notFound', 'robots', 'proxy', 'faqs',
+  'deployId', 'deployIdFooter', 'buildJsonLd', 'fetchRoutes', 'platform',
+  // The family ride-along set (2026-10 issue walk): structured-data
+  // defaults and per-route nodes, the verification/discovery head set,
+  // IndexNow, the postBuild hook seam, and the llms.txt opt-out.
+  'jsonLdDefaults',
+  'alternates', 'verification', 'feed', 'searchUrl',
+  'indexNow', 'hooks', 'runHooks', 'ogImageGeneration',
+  'llms',
+]
+
+// Retired keys: each entry names what owns the behavior now. Empty today --
+// no shipped key has ever been removed without a replacement seam. Entries:
+// { key: string, note: string }
+export const RETIRED_CONFIG_KEYS = []
+
+/**
+ * Collect unknown/retired ssr.config.js keys as warning strings (#52).
+ * Diagnostics, not gates: warnings never fail validation.
+ *
+ * @param {object} config - full ssr.config.js export
+ * @returns {string[]} one warning per unknown/retired key
+ */
+export function configKeyWarnings(config) {
+  if (!config || typeof config !== 'object') return []
+  const warnings = []
+  for (const key of Object.keys(config)) {
+    if (KNOWN_CONFIG_KEYS.includes(key)) continue
+    const retired = RETIRED_CONFIG_KEYS.find(r => r.key === key)
+    if (retired) {
+      warnings.push(`retired config key "${key}" has no effect: ${retired.note} - remove this key`)
+    } else {
+      warnings.push(`unknown config key "${key}" (typo? see the config reference)`)
+    }
+  }
+  return warnings
+}
+
+/**
+ * Format key warnings as printed one-liners (`[prestruct] config warning: ..`).
+ *
+ * @param {string[]} warnings - raw warning strings from configKeyWarnings()
+ * @returns {string[]} prefixed one-liner strings
+ */
+export function formatConfigWarnings(warnings) {
+  return warnings.map(w => `[prestruct] config warning: ${w}`)
+}
+
 /**
  * Validate the ssr.config.js shape and emit structured diagnostics.
  * Shape checks: siteUrl form, route paths (leading slash, traversal guard),
@@ -94,6 +152,37 @@ export function validateConfig(config) {
     })
   }
 
+  // ogImage: legacy string shorthand AND the structured object form
+  // (freestruct proposal #38 commentary): { url, width, height, alt, type }.
+  // The object form is what lets og:image carry its width/height/alt
+  // companions -- the properties social crawlers use to size previews.
+  // Never throws. Bad shapes surface as errors, not as silently-dropped
+  // metadata. Companion content validation lives at the injection seam
+  // (non-numeric width/height / non-string alt or type are simply not
+  // emitted, so a typo'd field can never corrupt the head)
+  if (config.ogImage !== undefined && config.ogImage !== null) {
+    const isObj = typeof config.ogImage === 'object' && !Array.isArray(config.ogImage)
+    if (isObj) {
+      if (typeof config.ogImage.url !== 'string') {
+        errors.push('ogImage: object form requires a string "url" field')
+      }
+      for (const k of ['width', 'height']) {
+        const v = config.ogImage[k]
+        if (v !== undefined && !/^[0-9]+$/.test(String(v))) {
+          errors.push(`ogImage: "${k}" should be a number (pixels), got ${JSON.stringify(v)}`)
+        }
+      }
+      for (const k of ['alt', 'type']) {
+        const v = config.ogImage[k]
+        if (v !== undefined && typeof v !== 'string') {
+          errors.push(`ogImage: "${k}" must be a string, got ${JSON.stringify(v)}`)
+        }
+      }
+    } else if (typeof config.ogImage !== 'string') {
+      errors.push('ogImage: must be a string URL or an object { url, width, height, alt, type }')
+    }
+  }
+
   // Optional known-value fields
   if (config.platform !== undefined && !PLATFORMS.includes(config.platform)) {
     errors.push(`platform: "${config.platform}" not in ${PLATFORMS.join(', ')}`)
@@ -102,6 +191,19 @@ export function validateConfig(config) {
     errors.push('appLayoutPath: must be a Vite-rooted path starting with "/"')
   }
 
+  // indexNow (#36): the key must be 32 lowercase hex, or the boolean forms
+  // (true = persisted auto-key, false = off). resolveIndexNowKey RETURNS NULL
+  // on an invalid key ("diagnostics already warned") -- so without this check
+  // a mistyped/placeholder key silently disables IndexNow with no diagnostic
+  // anywhere: the example's own placeholder is 36 chars, and uncommenting it
+  // would drop the feature green. Surface it here, where the claim is made.
+  if (config.indexNow !== undefined && config.indexNow !== null && config.indexNow !== false && config.indexNow !== true) {
+    const key = typeof config.indexNow === 'string' ? config.indexNow : config.indexNow.key
+    if (typeof key !== 'string' || !/^[a-f0-9]{32}$/.test(key)) {
+      errors.push('indexNow: must be true, a 32-char lowercase hex key string, or { key: "<32-hex>" }')
+    }
+  }
+
   return { ok: errors.length === 0, errors }
 }
 

package/init/src/hooks/usePageMeta.js

@@ -54,7 +54,9 @@ const { useLocation } = rrd
 
 /** Update the SPA head tags on every route change (see the module head doc). */
 export default function usePageMeta({ title, description, path, siteUrl }) {
-  const base = siteUrl || import.meta.env?.VITE_SITE_URL || ''
+  // Trailing-slash normalization (#53): a configured base with its trailing
+  // slash would join into `https://site//about` on every navigation
+  const base = (siteUrl || import.meta.env?.VITE_SITE_URL || '').replace(/\/$/, '')
   const location = useLocation()
 
   useEffect(() => {

package/init/src/islands.js

@@ -55,25 +55,44 @@ import React    from 'react'
 // Tracks elements that have already been mounted to prevent double createRoot
 // calls when mountIslands is called again on SPA route change.
 const mounted = new WeakSet()
+// Tracks elements that already have a live IntersectionObserver. mountIslands
+// is contractually called after EVERY navigation, and a never-intersected
+// 'visible' island survives each scan as the same element: without this set,
+// a duplicate scan stacks another observer on it (each with its own callback
+// and its own disconnect lifecycle).
+const observing = new WeakSet()
+// The live observer per watched element, so mount() can disconnect exactly
+// the observer that got it here instead of leaving the one-shot entry firing.
+const observers = new WeakMap()
 
 function mount(el, Component) {
   if (mounted.has(el)) return
   mounted.add(el)
+  // Disconnect the 'visible' island's observer exactly once, at the moment
+  // of the mount it was waiting for (instead of inside its own callback,
+  // which a duplicate observer would race with).
+  const io = observers.get(el)
+  if (io) {
+    observers.delete(el)
+    observing.delete(el)
+    io.disconnect()
+  }
   el.innerHTML = ''
   ReactDOM.createRoot(el).render(React.createElement(Component))
 }
 
 function observe(el, Component) {
   if (mounted.has(el)) return
-  const io = new IntersectionObserver((entries, observer) => {
+  if (observing.has(el)) return // already waiting on one observer
+  observing.add(el)
+  const io = new IntersectionObserver((entries) => {
     for (const entry of entries) {
       if (entry.isIntersecting) {
-        observer.unobserve(el)
-        io.disconnect()  // Clean up the observer after use
-        mount(el, Component)
+        mount(el, Component) // mount() does the disconnect now
       }
     }
   }, { rootMargin: '0px', threshold: 0.1 })
+  observers.set(el, io)
   io.observe(el)
 }
 

package/init/ssr.config.example.js

@@ -127,6 +127,43 @@ export default {
   //   ]
   // },
 
+  // === Family ride-alongs (2026-10 issue walk) ===
+  // All optional; every block is missing-only and config-gated. Full
+  // semantics: docs/guides/config.md#family-ride-alongs.
+
+  // Config-driven structured-data defaults (#30): without buildJsonLd the
+  // engine emits Organization + WebSite from siteName/siteUrl/author.
+  // jsonLdDefaults: false,   // skip the defaults
+
+  // Per-route schema: route.jsonLd (object or array) ships on that page only
+  // (FAQPage on the FAQ page, Article on the article). Feed discovery,
+  // hreflang alternates (route.alternates overrides the site-wide set),
+  // search-console verification metas, and a SearchAction on the home route:
+  // feed:    { url: 'https://example.com/feed.xml', title: 'Feed' },
+  // searchUrl: 'https://example.com/search?q={query}',
+  // alternates: [{ hreflang: 'en', href: 'https://example.com' }],
+  // verification: { 'google-site-verification': 'token-here' },
+
+  // llms.txt (AI-consumable site summary from the baked route set),
+  // generated-only (a hand-rolled file is never touched). Opt-out:
+  // llms: false,
+
+  // IndexNow (#36): a 32-char lowercase-hex key string (or true = persisted
+  // auto-key in .prestruct/). build writes <key>.txt into dist/; `prestruct
+  // indexnow --dry-run` prints the submission payload.
+  // indexNow: 'replacewithyour32lowercasehexkey',
+
+  // postBuild hooks (#41): shell commands run BY the build after prerender
+  // (npm-chain scripts can be retired). Opt-in execution gate:
+  // runHooks: true,
+  // hooks: { postBuild: ['node scripts/inject-faq-schema.mjs'] },
+
+  // Branded per-route OG images (#43): render a 1200x630 PNG per route from
+  // a 1200x630 SVG template ({{ogTitle}}/{{ogDescription}}/{{ogUrl}} slots).
+  // Rasterizer is the optional dev dep @resvg/resvg-js - without it the
+  // generation skips loudly (build stays green, audit flags the head).
+  // ogImageGeneration: { template: 'og-template.svg', font: './brand/bold.ttf' },
+
   // === 404 Page ===
   // Custom 404 page content. Prerendered with noindex meta.
   notFound: {