prestruct 0.0.0-stage → 1.0.0

package/engine/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/engine/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/engine/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/engine/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/VERSION

@@ -0,0 +1 @@
+1.0.0

package/init/ecosystem.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * ecosystem.cjs - pm2 starter config for the Prestruct render proxy
+ * =================================================================
+ * Ships with `prestruct init` (scripts/ + this file + proxy.package.json
+ * make up the VPS proxy deployment). pm2 keeps `scripts/proxy.js` alive,
+ * restarts it on crash, and caps memory: Puppeteer holds the cost of a
+ * warm Chromium (~100MB+), so a runaway instance should be killed and
+ * restarted, not OOM the box.
+ *
+ * Usage (from the proxy's own package root -- see proxy.package.json):
+ *
+ *   npm install                    # express + puppeteer (downloads Chromium)
+ *   export PRESTRUCT_SECRET=...    # must match config.proxy.secret
+ *   pm2 start ecosystem.cjs
+ *   pm2 save && pm2 startup        # survive reboots
+ *
+ * Logs / status / stop:
+ *
+ *   pm2 logs prestruct-proxy
+ *   pm2 status
+ *   pm2 stop prestruct-proxy
+ *
+ * Prefer systemd? See scripts/prestruct-proxy.service for the unit file.
+ */
+
+module.exports = {
+  apps: [
+    {
+      name: 'prestruct-proxy',
+      script: 'scripts/proxy.js',
+      cwd: __dirname,
+      exec_mode: 'fork',          // single browser pool -- never clusterify
+      instances: 1,
+      max_memory_restart: '700M', // warm Chromium headroom; tune per box
+      restart_delay: 3000,        // back off crashes instead of hot-looping
+      kill_timeout: 3000,         // let the browser drain on restart
+      env: {
+        NODE_ENV: 'production',
+        // Set PRESTRUCT_SECRET in your shell (or an EnvironmentFile with
+        // systemd) rather than committing it here.
+      },
+    },
+  ],
+}

package/init/eslint.config.js

@@ -0,0 +1,30 @@
+// eslint.config.js
+// Prestruct ESLint config
+export default [
+  {
+    files: ['**/*.js', '**/*.mjs'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: {
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'no-console': 'off',
+      'no-process-exit': 'off',
+      'prefer-const': 'error',
+      'no-var': 'error',
+    },
+  },
+  {
+    files: ['scripts/**/*.js'],
+    rules: {
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    files: ['tests/**/*.test.js'],
+    rules: {
+      'no-unused-vars': 'off',
+    },
+  },
+]

package/init/index.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+  <!--
+    Shell template. Do not add brand meta here directly.
+
+    inject-brand.js populates these tags at build time from ssr.config.js:
+      title, description, author, keywords, canonical,
+      Open Graph, Twitter Card, JSON-LD.
+
+    The placeholder values below give the inject regex something to match.
+    They are replaced before the site is deployed -- never served as-is.
+  -->
+
+  <!-- Primary SEO (populated by inject-brand.js) -->
+  <title>Site</title>
+  <meta name="description" content="" />
+  <meta name="keywords"    content="" />
+  <meta name="author"      content="" />
+  <meta name="robots"      content="index, follow" />
+  <link rel="canonical"    href="https://yoursite.com/" />
+
+  <!--
+    Favicons -- replace with your own.
+    Generate from https://favicon.io or similar.
+  -->
+  <!-- <link rel="icon" type="image/png" href="/favicon-32.png" sizes="32x32" /> -->
+  <!-- <link rel="apple-touch-icon" href="/apple-touch-icon.png" /> -->
+  <!-- <link rel="manifest" href="/site.webmanifest" /> -->
+
+  <!--
+    Fonts -- add your font imports here if needed.
+    Use <link rel="preconnect"> to warm the connection before the stylesheet.
+  -->
+</head>
+<body>
+  <div id="root"></div>
+</body>
+</html>