prestruct 1.0.0 → 1.2.0

package/engine/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/engine/src/hooks/usePageMeta.js

@@ -43,11 +43,20 @@
  */
 
 import { useEffect } from 'react'
-import { useLocation } from 'react-router-dom'
+import * as rrdNS from 'react-router-dom'
+// Neither plain named imports nor a bare namespace destructure survive
+// both majors: v7 ships CJS (vite SSR rejects named imports; node interop
+// gives a namespace whose only reliable export is `default` -- the exports
+// object), while v6 is ESM with possibly no default. Destructure from
+// whichever carries the exports.
+const rrd = rrdNS.default ?? rrdNS
+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/engine/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/engine/ssr.config.example.js

@@ -0,0 +1,196 @@
+/**
+ * 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
+  //
+  // AEO preset -- per-bot crawl policy from the 2026 vendor docs:
+  // robots: { aeo: true },                  // search AI bots Allow, training crawls Disallow
+  // robots: { aeo: { aiBots: 'allow' } },   // same, but also allow training crawls
+  // Search group: OAI-SearchBot, PerplexityBot, Claude-SearchBot, Applebot,
+  // Googlebot, Bingbot. Training group: GPTBot, ClaudeBot, Google-Extended,
+  // Applebot-Extended, CCBot. Search access and training/data-use are separate
+  // choices; the Sitemap line is appended as usual.
+
+  // === 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',
+  //       },
+  //     },
+  //   ]
+  // },
+
+  // === 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: {
+    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/VERSION

@@ -1 +1 @@
-1.0.0
+1.2.0

package/init/ecosystem.cjs

@@ -11,7 +11,7 @@
  * 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
+ *   export PRESTRUCT_SECRET=...    # env-var secret the proxy reads (never a config key)
  *   pm2 start ecosystem.cjs
  *   pm2 save && pm2 startup        # survive reboots
  *