prestruct 0.0.0-stage → 0.9.0

package/init/scripts/validate-config.js

@@ -0,0 +1,117 @@
+/**
+ * scripts/validate-config.js
+ * ==========================
+ * Validates ssr.config.js shape and emits structured diagnostics.
+ *
+ * Shared by prerender.js and inject-brand.js. The contract:
+ *   - Returns { ok, errors } where errors are consumable strings, one line each
+ *   - Never throws, never exits -- callers decide policy (prerender exits 0
+ *     on CF Pages unless PRESTRUCT_STRICT=1 is set; see prerender.js)
+ */
+
+const PLATFORMS = ['cloudflare', 'vercel', 'netlify']
+const CHANGEFREQS = ['daily', 'weekly', 'monthly', 'yearly']
+
+// Identity helper: `import { defineConfig } from 'prestruct'` for type-aware
+// ssr.config.js files. No preprocessing -- config is passed through.
+/**
+ * Identity helper: `import { defineConfig } from 'prestruct'` for type-aware
+ * ssr.config.js files. Passes the config straight through.
+ *
+ * @template T
+ * @param {T} config - the config object
+ * @returns {T} the same config object
+ */
+export function defineConfig(config) {
+  return config
+}
+
+/**
+ * Validate the ssr.config.js shape and emit structured diagnostics.
+ * Shape checks: siteUrl form, route paths (leading slash, traversal guard),
+ * priority/changefreq values, meta objects, duplicate paths, empty lists,
+ * platform and appLayoutPath know-values. Never throws, never exits.
+ *
+ * @param {object} config - full ssr.config.js export
+ * @returns {{ok: boolean, errors: string[]}} diagnostics consumable by callers
+ */
+export function validateConfig(config) {
+  const errors = []
+  if (!config || typeof config !== 'object') {
+    return { ok: false, errors: ['config must export a default object'] }
+  }
+
+  // Required: siteUrl (origin or full URL, no trailing slash enforced upstream)
+  if (typeof config.siteUrl !== 'string' || !/^https?:\/\//.test(config.siteUrl.trim())) {
+    errors.push('siteUrl is required and must start with http:// or https://')
+  }
+
+  // routes: array of route objects; duplicate paths are an error because two
+  // routes with the same path would collide in the cache key AND write the
+  // same dist file twice with different meta (silent SEO corruption).
+  if (!Array.isArray(config.routes)) {
+    errors.push('routes must be an array (or omitted entirely)')
+  } else if (!config.routes.length) {
+    // Hammer finding (2026-10): an explicitly EMPTY routes array validated as
+    // "valid (0 routes)" -- the build would prerender nothing while reporting
+    // a green configured site. Zero routes is a misconfiguration (route lists
+    // WITHOUT the home route are fine: vite still ships index.html).
+    errors.push('routes is empty -- configure at least one route to prerender')
+  } else {
+    config.routes.forEach((route, i) => {
+      if (!route || typeof route !== 'object') {
+        errors.push(`routes[${i}]: must be an object`)
+        return
+      }
+      if (typeof route.path !== 'string' || !route.path.startsWith('/')) {
+        errors.push(`routes[${i}].path: missing or does not start with "/"`)
+      }
+      // Path traversal guard: prerender writes dist/<path>/index.html. A
+      // '..' or backslash segment escapes dist/ (and on POSIX could land
+      // outside the project root entirely). Route paths are URL paths --
+      // they never need either.
+      if (typeof route.path === 'string' && (route.path.includes('..') || route.path.includes('\\'))) {
+        errors.push(`routes[${i}].path: "${route.path}" contains ".." or backslash -- route paths cannot escape dist/`)
+      }
+      if (route.priority !== undefined && !/^(0?\.\d+|1(\.0+)?)$/.test(String(route.priority))) {
+        errors.push(`routes[${i}].priority: "${route.priority}" is not a number between 0 and 1`)
+      }
+      if (route.changefreq !== undefined && !CHANGEFREQS.includes(route.changefreq)) {
+        errors.push(`routes[${i}].changefreq: "${route.changefreq}" not in ${CHANGEFREQS.join(', ')}`)
+      }
+      if (route.meta !== undefined && (typeof route.meta !== 'object' || route.meta === null)) {
+        errors.push(`routes[${i}].meta: must be an object like { title, description }`)
+      }
+    })
+    const seen = new Set()
+    config.routes.forEach((route, i) => {
+      if (route && typeof route === 'object' && typeof route.path === 'string') {
+        if (seen.has(route.path)) {
+          errors.push(`routes[${i}].path: duplicate path "${route.path}" (first seen earlier) -- every path must be unique`)
+        }
+        seen.add(route.path)
+      }
+    })
+  }
+
+  // Optional known-value fields
+  if (config.platform !== undefined && !PLATFORMS.includes(config.platform)) {
+    errors.push(`platform: "${config.platform}" not in ${PLATFORMS.join(', ')}`)
+  }
+  if (config.appLayoutPath !== undefined && (typeof config.appLayoutPath !== 'string' || !config.appLayoutPath.startsWith('/'))) {
+    errors.push('appLayoutPath: must be a Vite-rooted path starting with "/"')
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+// Structured one-liner format callers print for each diagnostic
+/**
+ * Format diagnostics as the printed one-liners (`[prestruct] config: <msg>`).
+ *
+ * @param {string[]} errors - raw diagnostic messages
+ * @returns {string[]} prefixed one-liner strings
+ */
+export function formatDiagnostics(errors) {
+  return errors.map(e => `[prestruct] config: ${e}`)
+}

package/init/src/App.jsx

@@ -0,0 +1,21 @@
+/**
+ * src/App.jsx
+ * ===========
+ * TEMPLATE FILE -- wire your AppLayout here, keep BrowserRouter in this file only.
+ *
+ * BrowserRouter must NOT be imported in AppLayout.jsx or any file it imports.
+ * If it is, ssrLoadModule will initialize BrowserRouter against window.location
+ * (which defaults to '/' in Node), and every route will prerender as the
+ * homepage with no error message. See AGENTS.md for the full explanation.
+ */
+
+import { BrowserRouter } from 'react-router-dom'
+import AppLayout from './AppLayout.jsx'
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <AppLayout />
+    </BrowserRouter>
+  )
+}

package/init/src/AppIslands.jsx

@@ -0,0 +1,39 @@
+/**
+ * src/AppIslands.jsx
+ * ==================
+ * TEMPLATE FILE -- register your island components here.
+ *
+ * Each entry maps a data-pre-island name to a React component.
+ * The name must match exactly what you put in the HTML attribute.
+ *
+ * Island components:
+ *   - Run only in the browser, never during SSR prerender.
+ *   - Receive no props. Read data from localStorage, fetch, or a global store.
+ *   - Replace any fallback content inside the <pre-island> element.
+ *
+ * Usage in your page JSX:
+ *
+ *   // eager (default) -- mounts immediately after hydration
+ *   <pre-island data-pre-island="recently-viewed" />
+ *
+ *   // visible -- mounts when scrolled into viewport
+ *   <pre-island data-pre-island="cart-widget" data-pre-load="visible">
+ *     <span className="island-loading">Loading cart...</span>
+ *   </pre-island>
+ *
+ *   // idle -- mounts during browser idle time
+ *   <pre-island data-pre-island="promo-banner" data-pre-load="idle" />
+ *
+ * Add your components below and uncomment the import lines.
+ * Remove unused examples before shipping.
+ */
+
+// import RecentlyViewed from './islands/RecentlyViewed.jsx'
+// import CartWidget     from './islands/CartWidget.jsx'
+// import PromoBanner    from './islands/PromoBanner.jsx'
+
+export const islands = {
+  // 'recently-viewed': RecentlyViewed,
+  // 'cart-widget':     CartWidget,
+  // 'promo-banner':    PromoBanner,
+}

package/init/src/AppLayout.jsx

@@ -0,0 +1,66 @@
+/**
+ * src/AppLayout.jsx
+ * =================
+ * TEMPLATE FILE -- copy and wire to your own routes, components, and pages.
+ *
+ * Router-agnostic layout shell. No BrowserRouter here -- ever.
+ *
+ * Imported by:
+ *   App.jsx          (wrapped in BrowserRouter for the client)
+ *   prerender.js     (wrapped in StaticRouter via ssrLoadModule)
+ *
+ * CRITICAL: Nothing in this file's import graph may import BrowserRouter.
+ * If it does, ssrLoadModule will initialize BrowserRouter against window.location
+ * (which defaults to '/' in Node), overriding StaticRouter's location context.
+ * Every route will prerender as the homepage with no error message.
+ * See AGENTS.md for the full root cause analysis.
+ *
+ * SSR SAFETY: Any component in this tree that accesses window, document, or
+ * localStorage must guard with `typeof window !== 'undefined'` because SSR
+ * runs in Node where these globals don't exist.
+ */
+
+import { Routes, Route, useLocation } from 'react-router-dom'
+import { useEffect } from 'react'
+import { mountIslands } from './islands.js'
+import { islands }      from './AppIslands.jsx'
+
+// Replace these with your actual components and pages. A live-fire check
+// (2026-10): uncommenting a <Route> whose import is still commented makes
+// prerender die with "X is not defined" per route. Rule: only ever uncomment
+// a <Route> line AFTER its import line is uncommented too.
+// import Nav from './components/Nav'
+// import Footer from './components/Footer'
+// import Home from './pages/Home'
+// import About from './pages/About'
+
+function ScrollToTop() {
+  const { pathname } = useLocation()
+  useEffect(() => {
+    if (typeof window !== 'undefined') window.scrollTo({ top: 0, behavior: 'instant' })
+    // Re-scan for islands on every route change. The WeakSet in islands.js
+    // prevents double-mounting elements that are already active. The setTimeout(0)
+    // defers the scan one tick so React has committed the new page to the DOM.
+    const t = setTimeout(() => mountIslands(islands), 0)
+    return () => clearTimeout(t)
+  }, [pathname])
+  return null
+}
+
+export default function AppLayout() {
+  return (
+    <>
+      <ScrollToTop />
+      {/* <Nav /> */}
+      <main>
+        <Routes>
+          {/* Replace with your routes */}
+          {/* <Route path="/"      element={<Home />} /> */}
+          {/* <Route path="/about" element={<About />} /> */}
+          {/* <Route path="*"      element={<NotFound />} /> */}
+        </Routes>
+      </main>
+      {/* <Footer /> */}
+    </>
+  )
+}

package/init/src/hooks/usePageMeta.js

@@ -0,0 +1,78 @@
+/**
+ * src/hooks/usePageMeta.js
+ * ========================
+ * Updates route-specific head tags on client-side navigation.
+ *
+ * SSR (prerender.js) bakes correct tags into each route's HTML at build time --
+ * bots without JS and initial page loads see those tags directly.
+ * This hook keeps them in sync when the user navigates within the SPA,
+ * covering JS-enabled bots (Googlebot, social crawlers) and the browser tab.
+ *
+ * Tags updated on each navigation:
+ *   <title>
+ *   <meta name="description">
+ *   <link rel="canonical">
+ *   <meta property="og:url">
+ *   <meta property="og:title">
+ *   <meta property="og:description">
+ *   <meta name="twitter:title">
+ *   <meta name="twitter:description">
+ *
+ * Tags intentionally NOT updated (same on every page):
+ *   og:image, og:type, og:locale, og:site_name, twitter:card, twitter:image
+ *
+ * NO external dependencies -- does not import from ssr.config.js or any app file.
+ * siteUrl is passed as a prop or read from VITE_SITE_URL env.
+ *
+ * Usage (explicit siteUrl):
+ *   usePageMeta({
+ *     siteUrl:     'https://yoursite.com',
+ *     path:        '/about',
+ *     title:       'About | Your Site',
+ *     description: 'About page description.',
+ *   })
+ *
+ * Usage (env-driven, set VITE_SITE_URL in .env or vite.config.js define):
+ *   usePageMeta({ path: '/about', title: '...', description: '...' })
+ *
+ * Tip: wrap in your own hook to avoid repeating siteUrl:
+ *   // src/hooks/useMeta.js
+ *   import usePageMeta from './usePageMeta.js'
+ *   const SITE_URL = import.meta.env.VITE_SITE_URL || 'https://yoursite.com'
+ *   export default (args) => usePageMeta({ siteUrl: SITE_URL, ...args })
+ */
+
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+
+/** 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 || ''
+  const location = useLocation()
+
+  useEffect(() => {
+    // Without a base URL a computed canonical would be relative ("/about"),
+    // which is not a canonical URL -- skip rather than write a wrong tag.
+    const canonical = base ? `${base}${path === '/' ? '' : path}` : ''
+
+    const set = (selector, attr, value) => {
+      const el = document.querySelector(selector)
+      if (el && value) el.setAttribute(attr, value)
+    }
+
+    if (title)       document.title = title
+    if (description) set('meta[name="description"]',             'content', description)
+    if (canonical) {
+      set('link[rel="canonical"]',                               'href',    canonical)
+      set('meta[property="og:url"]',                            'content', canonical)
+    }
+    if (title) {
+      set('meta[property="og:title"]',                          'content', title)
+      set('meta[name="twitter:title"]',                         'content', title)
+    }
+    if (description) {
+      set('meta[property="og:description"]',                    'content', description)
+      set('meta[name="twitter:description"]',                   'content', description)
+    }
+  }, [title, description, path, base, location])
+}

package/init/src/islands.js

@@ -0,0 +1,129 @@
+/**
+ * src/islands.js
+ * ==============
+ * Engine file -- copy once, never edit.
+ *
+ * Mounts dynamic React components into <pre-island> placeholders after
+ * the main app hydrates. Each island is a hole punched through the
+ * prerendered HTML: invisible to crawlers, filled for human visitors.
+ *
+ * Usage -- call mountIslands() in AppLayout's route-change effect after each
+ * navigation. This ensures islands mount on both hard loads and SPA transitions.
+ * The WeakSet prevents double-mounting if the same element is scanned twice.
+ *
+ *   import { mountIslands } from './islands.js'
+ *   import { islands } from './AppIslands.jsx'
+ *
+ *   // Inside ScrollToTop's useEffect([pathname]):
+ *   const t = setTimeout(() => mountIslands(islands), 0)
+ *   return () => clearTimeout(t)
+ *
+ * Islands are declared in src/AppIslands.jsx as a name -> component map.
+ * Each island in the HTML is a <pre-island> custom element:
+ *
+ *   <pre-island data-pre-island="recently-viewed"></pre-island>
+ *   <pre-island data-pre-island="cart-widget" data-pre-load="visible"></pre-island>
+ *   <pre-island data-pre-island="promo-banner" data-pre-load="idle"></pre-island>
+ *
+ * Load strategies (data-pre-load):
+ *   eager   -- mount immediately. Default if omitted.
+ *   visible -- mount when the element enters the viewport (IntersectionObserver).
+ *   idle    -- mount during browser idle time (requestIdleCallback).
+ *
+ * Fallback content:
+ *   Any children inside <pre-island> are shown before the island mounts.
+ *   They are replaced when the React component renders.
+ *
+ *   <pre-island data-pre-island="cart-widget">
+ *     <span class="island-loading">Loading cart...</span>
+ *   </pre-island>
+ *
+ * SSR behavior:
+ *   <pre-island> is a custom element. React's renderToString passes it
+ *   through as plain HTML -- no guard needed. Fallback content renders
+ *   in the static HTML and is visible to crawlers. The React component
+ *   never runs at build time.
+ *
+ * Island components receive no props by default. To pass data, use
+ * data attributes and read them from the element ref inside the component,
+ * or pull from a global store / localStorage / fetch.
+ */
+
+import ReactDOM from 'react-dom/client'
+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()
+
+function mount(el, Component) {
+  if (mounted.has(el)) return
+  mounted.add(el)
+  el.innerHTML = ''
+  ReactDOM.createRoot(el).render(React.createElement(Component))
+}
+
+function observe(el, Component) {
+  if (mounted.has(el)) return
+  const io = new IntersectionObserver((entries, observer) => {
+    for (const entry of entries) {
+      if (entry.isIntersecting) {
+        observer.unobserve(el)
+        io.disconnect()  // Clean up the observer after use
+        mount(el, Component)
+      }
+    }
+  }, { rootMargin: '0px', threshold: 0.1 })
+  io.observe(el)
+}
+
+function whenIdle(el, Component) {
+  if (mounted.has(el)) return
+  if ('requestIdleCallback' in window) {
+    requestIdleCallback(() => {
+      // Guard against the element being removed from the DOM before the
+      // callback fires (e.g. user navigated away within the idle window).
+      if (el.isConnected) mount(el, Component)
+    }, { timeout: 2000 })
+  } else {
+    // requestIdleCallback not available -- fall back to a short timeout
+    setTimeout(() => { if (el.isConnected) mount(el, Component) }, 200)
+  }
+}
+
+/**
+ * mountIslands(registry)
+ *
+ * Scans the DOM for <pre-island> elements and mounts the matching
+ * React component from the registry into each one.
+ *
+ * Unregistered island names are skipped with a console warning.
+ * Safe to call with an empty registry -- nothing happens.
+ *
+ * @param {Record<string, Function>} [registry={}] - island name -> React component
+ * @returns {void}
+ */
+export function mountIslands(registry = {}) {
+  if (typeof window === 'undefined') return
+
+  const elements = document.querySelectorAll('pre-island[data-pre-island]')
+
+  for (const el of elements) {
+    const name      = el.dataset.preIsland
+    const strategy  = el.dataset.preLoad || 'eager'
+    const Component = registry[name]
+
+    if (!Component) {
+      console.warn(`[islands] no component registered for "${name}" -- skipping`)
+      continue
+    }
+
+    if (strategy === 'visible') {
+      observe(el, Component)
+    } else if (strategy === 'idle') {
+      whenIdle(el, Component)
+    } else {
+      mount(el, Component)
+    }
+  }
+}

package/init/src/main.jsx

@@ -0,0 +1,35 @@
+/**
+ * src/main.jsx
+ * ============
+ * TEMPLATE FILE -- copy as-is or adjust StrictMode to taste.
+ *
+ * Responsibilities:
+ *   1. Hydrate the prerendered SSR HTML (hydrateRoot) or do a fresh render
+ *      (createRoot) depending on whether SSR content is present.
+ *
+ * hydrateRoot vs createRoot:
+ *   hydrateRoot attaches React's event system to existing SSR DOM without
+ *   replacing it. Use it when dist/index.html contains prerendered content
+ *   (data-server-rendered="true" on #root). Without it, the browser discards
+ *   the SSR HTML and re-renders from scratch, causing FOUC on every page load.
+ *
+ * Islands:
+ *   mountIslands() is called inside AppLayout on every route change (including
+ *   the initial render). This ensures islands are mounted whether the page was
+ *   reached by a hard load or SPA navigation. The engine tracks already-mounted
+ *   elements with a WeakSet so repeated calls are safe.
+ *
+ * Do NOT import BrowserRouter here. It belongs in App.jsx.
+ */
+
+import React    from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+
+const root = document.getElementById('root')
+
+if (root && root.dataset.serverRendered) {
+  ReactDOM.hydrateRoot(root, <React.StrictMode><App /></React.StrictMode>)
+} else if (root) {
+  ReactDOM.createRoot(root).render(<React.StrictMode><App /></React.StrictMode>)
+}

package/init/ssr.config.example.js

@@ -0,0 +1,151 @@
+/**
+ * ssr.config.js
+ * =============
+ * Copy this file to your project root as ssr.config.js, then customize.
+ * 
+ * The platform field selects host behavior. Cloudflare (default) is the only
+ * fully supported platform today: the template ships public/_headers and
+ * public/_redirects, and inject-brand appends the proxy origin to the CSP
+ * allow-list when proxy.url is set. 'vercel' and 'netlify' pass config
+ * validation but no host-specific files are generated yet.
+ * 
+ * IMPORTANT: This file is gitignored. It's your environment-specific config.
+ * Copy ssr.config.example.js to ssr.config.js and customize for your site.
+ * 
+ * Platform options:
+ *   - cloudflare  = default (only platform with generated/templated host files)
+ *   - vercel      = accepted in config; no file generation yet
+ *   - netlify     = accepted in config; no file generation yet
+ */
+
+export default {
+  // === Platform ===
+  // platform: 'cloudflare',  // 'netlify' | 'vercel' | 'cloudflare' (default)
+
+  // === Site Identity ===
+  siteUrl:    'https://example.com',
+  siteName:   'Your Site Name',
+  author:     'Your Name',
+  tagline:   'Your tagline - keeps it short',
+  ogImage:    'https://example.com/og-image.png',
+  keywords:  'keyword1, keyword2, keyword3',
+
+  // === App ===
+  // Path to your AppLayout component (no BrowserRouter, only Routes)
+  appLayoutPath: '/src/AppLayout.jsx',
+
+  // === Deploy ID ===
+  // Inject a deploy ID meta tag for debugging (visible in page source).
+  // Set deployIdFooter: true to also show in the footer (requires client-side JS).
+  // deployId: true,        // inject <meta name="deploy-id"> (default: true)
+  // deployIdFooter: false, // show in footer (default: false)
+
+  // === Robots.txt (opt-in) ===
+  // Prestruct never touches dist/robots.txt unless you opt in -- a static
+  // public/robots.txt you author yourself is copied through untouched.
+  // robots: true,              // minimal block (all agents + Sitemap line)
+  // robots: "User-agent: *\nDisallow: /private",  // custom body; sitemap auto-appended
+  // robots: { body: "...", sitemap: false },      // custom body, no sitemap line
+
+  // === Routes ===
+  // Each route gets prerendered to static HTML at build time.
+  // Add your routes here (at least one; zero routes fails validation).
+  // Subroutes-only lists are fine -- vite still ships index.html.
+  routes: [
+    {
+      path:       '/',
+      priority:   '1.0',
+      changefreq: 'monthly',
+      meta: {
+        title:       'Your Site Name',
+        description: 'Your site description for search engines.',
+        // ogImage:     'https://example.com/og-image.png',  // route-specific OG image
+      },
+    },
+    // {
+    //   path:       '/about',
+    //   priority:   '0.8',
+    //   changefreq: 'monthly',
+    //   meta: {
+    //     title:       'About | Your Site Name',
+    //     description: 'Learn more about what we do.',
+    //   },
+    // },
+    // {
+    //   path:       '/blog',
+    //   priority:   '0.7',
+    //   changefreq: 'weekly',
+    //   meta: {
+    //     title:       'Blog | Your Site Name',
+    //     description: 'Latest updates and articles.',
+    //   },
+    // },
+  ],
+
+  // === Dynamic Routes (CMS) ===
+  // Optional async hook for routes from a headless CMS.
+  // Runs at build time only - no runtime overhead.
+  // fetchRoutes() merges with static routes above.
+  // Static routes take precedence on duplicates.
+  // async fetchRoutes() {
+  //   const posts = await fetch('https://your-cms.com/api/routes')
+  //     .then(r => r.json())
+  //   return posts.map(post => ({
+  //     path: `/blog/${post.slug}`,
+  //     priority: '0.6',
+  //     meta: {
+  //       title: post.title,
+  //       description: post.excerpt,
+  //     },
+  //   }))
+  // },
+
+  // === JSON-LD Structured Data ===
+  // Optional function returning schema.org structured data.
+  // Return a single object or array of objects.
+  // buildJsonLd() {
+  //   return [
+  //     {
+  //       '@context':           'https://schema.org',
+  //       '@type':              'WebSite',
+  //       name:                 'Your Site Name',
+  //       url:                  'https://example.com',
+  //       author: {
+  //         '@type': 'Person',
+  //         name:  'Your Name',
+  //         url:   'https://github.com/yourname',
+  //       },
+  //     },
+  //   ]
+  // },
+
+  // === 404 Page ===
+  // Custom 404 page content. Prerendered with noindex meta.
+  notFound: {
+    heading:    'Page not found',
+    body:       "That page doesn't exist.",
+    primaryCta: { label: 'Go home', href: '/' },
+  },
+
+  // === Bot Proxy (optional) ===
+  // Proxy renders dynamic routes not in the prerender list.
+  // Works with Node.js/Puppeteer (VPS) or Cloudflare Worker.
+  // proxy: {
+  //   // Your proxy server URL. Signals the build to widen the CSP
+  //   // connect-src allow-list with this origin.
+  //   url:      'https://your-proxy.example.com',
+  //   // Cache-refresh shared secret is an env var, not config:
+  //   // PRESTRUCT_SECRET (unset = refresh feature disabled entirely).
+  //   // Render a different origin than siteUrl (for local dev, staging)
+  //   targetUrl: 'https://staging.example.com',
+  //   // Bot list for proxy - customize if needed
+  //   botList: [
+  //     'Googlebot',
+  //     'Google-Extended',
+  //     'Bingbot',
+  //     'BingPreview',
+  //     'DuckDuckBot',
+  //     'Slurp',
+  //   ],
+  // },
+}

package/init/vite.config.js

@@ -0,0 +1,18 @@
+/**
+ * vite.config.js (template)
+ * =========================
+ * Canonical engine source. Generated into init/ only -- example/ owns its own
+ * vite.config.js (vendor chunking etc.), so this is NOT in the example contract.
+ *
+ * Why it matters: without @vitejs/plugin-react, JSX compiles through esbuild's
+ * classic runtime, which expects an in-scope `React` binding in every JSX file.
+ * Under ssrLoadModule that surfaces as "React is not defined" per route and
+ * prerender silently degrades to the SPA fallback. The automatic runtime fixes
+ * ssrLoadModule JSX compilation for the whole template.
+ */
+
+import react from '@vitejs/plugin-react'
+
+export default {
+  plugins: [react()],
+}

package/init/vitest.config.js

@@ -0,0 +1,14 @@
+// vitest.config.js
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.js'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      include: ['scripts/**/*.js'],
+    },
+  },
+})