@koehler8/cms 1.0.0-beta.9 → 1.1.0

package/vite-plugin.js

@@ -12,8 +12,19 @@ import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import vue from '@vitejs/plugin-vue';
 
-import { SUPPORTED_LOCALES } from './src/constants/locales.js';
 import { inflateFlatConfig } from './src/utils/inflateFlatConfig.js';
+import { buildRobotsTxt } from './src/utils/robotsGenerator.js';
+import { buildSitemap, getSitemapUrl } from './src/utils/sitemapGenerator.js';
+import { buildWebAppManifest } from './src/utils/webAppManifest.js';
+import { sha256Hex } from './src/utils/sha256.js';
+import { applyRouteShard } from './src/utils/ssgRoutes.js';
+import {
+  computeVariantCacheDir,
+  resolveImageVariantConfig,
+  planVariantJobsFromFlatDir,
+  reconcileVariantCache,
+} from './scripts/image-variants/index.js';
+import { validateExtensionManifests } from './scripts/lib/extension-manifests.mjs';
 
 // ---- Helpers ----
 
@@ -22,6 +33,15 @@ function loadSplitConfig(contentLocaleDir) {
   if (!fs.existsSync(sitePath)) return null;
 
   const site = inflateFlatConfig(JSON.parse(fs.readFileSync(sitePath, 'utf-8')));
+  // The plaintext password is read at build time so the plugin can produce
+  // robots.txt / sitemap.xml without surfacing it; strip it out of the
+  // in-memory siteConfig so accidental future code paths can't pass it
+  // through to the bundle. The `transform` hook below replaces the
+  // plaintext with a SHA-256 hash before any JSON file is imported by the
+  // runtime.
+  if (site && typeof site === 'object') {
+    delete site.draftPassword;
+  }
   const sharedPath = path.join(contentLocaleDir, 'shared.json');
   const shared = fs.existsSync(sharedPath) ? inflateFlatConfig(JSON.parse(fs.readFileSync(sharedPath, 'utf-8'))) : {};
 
@@ -38,6 +58,29 @@ function loadSplitConfig(contentLocaleDir) {
   return { site, shared, pages };
 }
 
+// Replace site.json's plaintext draftPassword with a SHA-256 hash before
+// the JSON ever enters the bundle. Returns the original code untouched
+// when the file doesn't carry a password (or doesn't parse as JSON), so
+// non-CMS site.json files anywhere else in the project are unaffected.
+async function transformSiteJson(code) {
+  let parsed;
+  try {
+    parsed = JSON.parse(code);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+
+  const password = typeof parsed.draftPassword === 'string' ? parsed.draftPassword.trim() : '';
+  if (!('draftPassword' in parsed) && !password) return null;
+
+  delete parsed.draftPassword;
+  if (password) {
+    parsed.draftPasswordHash = await sha256Hex(password);
+  }
+  return JSON.stringify(parsed);
+}
+
 function normalizeRoutePath(value = '/') {
   if (typeof value !== 'string') return '/';
   const trimmed = value.trim();
@@ -83,14 +126,21 @@ function extractSiteMetadata(siteConfig) {
     url: siteUrl = '',
     googleId: siteGoogleId = '',
     sameAs: siteSameAs = [],
+    manifest: siteManifest = {},
   } = siteConfig.site || {};
 
   const siteSameAsList = Array.isArray(siteSameAs)
     ? siteSameAs.map((v) => (typeof v === 'string' ? v.trim() : '')).filter(Boolean)
     : [];
-  const siteSameAsJson = JSON.stringify(siteSameAsList);
 
-  return { siteTitle, siteDescription, siteUrl, siteGoogleId, siteSameAsJson };
+  // Mobile chrome bar / PWA splash color. Defaults match buildWebAppManifest's
+  // default so the rendered <meta name="theme-color"> matches whatever
+  // manifest.json advertises.
+  const manifestThemeColor = (typeof siteManifest.themeColor === 'string'
+    ? siteManifest.themeColor.trim()
+    : '') || '#ffffff';
+
+  return { siteTitle, siteDescription, siteUrl, siteGoogleId, siteSameAsList, manifestThemeColor };
 }
 
 const __filename = fileURLToPath(import.meta.url);
@@ -105,8 +155,12 @@ const VIRTUAL_ASSETS = 'virtual:cms-asset-resolver';
 // <link rel="stylesheet"> in <head>, so theme CSS variables apply during the
 // initial paint instead of after Vue hydrates.
 const VIRTUAL_THEME_VARS = 'virtual:cms-theme-vars.css';
+// Eager glob over `site/components/**/*.vue` so site-local Vue files can be
+// referenced by basename in pages/{pageId}.json `components[]`. Resolution
+// priority: site > extension > bundled (see useComponentResolver).
+const VIRTUAL_SITE_COMPONENTS = 'virtual:cms-site-components';
 
-const VIRTUAL_IDS = new Set([VIRTUAL_CONFIG, VIRTUAL_STYLES, VIRTUAL_ASSETS, VIRTUAL_THEME_VARS]);
+const VIRTUAL_IDS = new Set([VIRTUAL_CONFIG, VIRTUAL_STYLES, VIRTUAL_ASSETS, VIRTUAL_THEME_VARS, VIRTUAL_SITE_COMPONENTS]);
 
 // Entry file name (written to site repo root, gitignored, cleaned up in buildEnd)
 const ENTRY_FILENAME = '.cms-entry.js';
@@ -146,6 +200,7 @@ function buildEntrySource(themePackages = [], extensionPackages = []) {
 import { setConfigLoader } from '@koehler8/cms/utils/loadConfig';
 import { setSiteStyleLoader } from '@koehler8/cms/utils/siteStyles';
 import { setAssetResolver } from '@koehler8/cms/utils/assetResolver';
+import { setSiteComponents } from '@koehler8/cms/utils/componentRegistry';
 ${needsThemeRegister ? `import { registerTheme } from '@koehler8/cms/themes/themeLoader';` : ''}
 ${needsExtRegister ? `import { registerExtension } from '@koehler8/cms/extensions/extensionLoader';` : ''}
 ${themeImports}
@@ -154,11 +209,13 @@ ${extImports}
 import * as __cmsConfig from '${VIRTUAL_CONFIG}';
 import * as __cmsStyles from '${VIRTUAL_STYLES}';
 import * as __cmsAssets from '${VIRTUAL_ASSETS}';
+import * as __cmsSiteComponents from '${VIRTUAL_SITE_COMPONENTS}';
 import '${VIRTUAL_THEME_VARS}';
 
 setConfigLoader(__cmsConfig);
 setSiteStyleLoader(__cmsStyles);
 setAssetResolver(__cmsAssets);
+setSiteComponents(__cmsSiteComponents);
 
 ${themeRegistrations}
 ${extRegistrations}
@@ -195,6 +252,24 @@ function renderTemplate(template, data) {
     ? `${canonicalBase}${STATIC_OG_IMAGE_PATH}`
     : STATIC_OG_IMAGE_PATH;
 
+  // The Organization JSON-LD is built as real JSON rather than interpolated
+  // field-by-field in the template: <%= %> HTML-escaping corrupted values
+  // inside the script element (a `"` in a site title shipped to crawlers as
+  // a literal &quot;), and raw interpolation risked </script> breakout.
+  // JSON.stringify with `<` escaped is both valid JSON and script-safe.
+  const organizationJsonLd = JSON.stringify(
+    {
+      '@context': 'https://schema.org',
+      '@type': 'Organization',
+      name: data.site ?? '',
+      url: data.siteUrl ?? '',
+      logo: ABSOLUTE_LOGO,
+      sameAs: data.siteSameAsList ?? [],
+    },
+    null,
+    2,
+  ).replace(/</g, '\\u003c');
+
   const scope = {
     ...data,
     STATIC_LOGO_PATH,
@@ -202,6 +277,7 @@ function renderTemplate(template, data) {
     canonicalBase,
     ABSOLUTE_LOGO,
     ABSOLUTE_OG_IMAGE,
+    organizationJsonLd,
   };
 
   // Strip <% ... %> blocks (declarations are pre-computed above)
@@ -275,24 +351,121 @@ function discoverExtensionCjsDeps(extensionPackages, projectRoot) {
   return [...cjsDeps];
 }
 
+// Build-time extension-manifest validation lives in scripts/lib so the
+// cms-validate-extensions CLI shares the exact same implementation. Imported
+// above (a bare `export ... from` re-export would not bind the name for the
+// plugin's own use) and re-exported here for tests and API stability.
+export { validateExtensionManifests };
+
+// List every *.vue basename under a directory (recursive). Mirrors the
+// import.meta.glob discovery the runtime registries use.
+function collectVueBasenames(dir) {
+  const names = new Set();
+  if (!fs.existsSync(dir)) return names;
+  const walk = (d) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.vue')) {
+        names.add(entry.name.replace(/\.vue$/i, ''));
+      }
+    }
+  };
+  walk(dir);
+  return names;
+}
+
+// Build-time components[] validation: every name referenced by a page must
+// resolve to a bundled, site-local, or extension-manifest component — the
+// same namespace the runtime resolver searches. At runtime an unknown name
+// silently drops the section in production (the resolver's warnings are
+// DEV-gated), which is the fleet's #1 documented authoring trap; here it
+// fails the build with the page and name instead. Exported for tests.
+export function collectComponentRefProblems({ pagesByLocale = {}, bundledNames, siteNames, extensions = [] }) {
+  const bundled = bundledNames instanceof Set ? bundledNames : new Set(bundledNames || []);
+  const site = siteNames instanceof Set ? siteNames : new Set(siteNames || []);
+  const bySlug = new Map(extensions.map((e) => [e.slug, e.componentNames]));
+  const extensionNames = new Set(extensions.flatMap((e) => [...e.componentNames]));
+  const allKnown = new Set([...bundled, ...site, ...extensionNames]);
+  const lowerToCanonical = new Map([...allKnown].map((n) => [n.toLowerCase(), n]));
+
+  const problems = [];
+  for (const [locale, pages] of Object.entries(pagesByLocale)) {
+    for (const [pageId, page] of Object.entries(pages || {})) {
+      const components = Array.isArray(page?.components) ? page.components : [];
+      components.forEach((entry, index) => {
+        let name = '';
+        let source = '';
+        if (typeof entry === 'string') {
+          name = entry.trim();
+        } else if (entry && typeof entry === 'object') {
+          name = typeof entry.name === 'string' ? entry.name.trim() : '';
+          source = typeof entry.source === 'string' ? entry.source.trim() : '';
+        }
+        if (!name) return;
+        if (!source && name.includes(':')) {
+          [source, name] = [name.slice(0, name.indexOf(':')), name.slice(name.indexOf(':') + 1)];
+        }
+
+        const where = `pages/${pageId}.json (locale ${locale}) components[${index}]`;
+        if (source === 'site') {
+          if (!site.has(name)) {
+            problems.push(`- ${where}: "site:${name}" — no site/components/${name}.vue exists`);
+          }
+          return;
+        }
+        if (source) {
+          const extSet = bySlug.get(source);
+          if (!extSet) {
+            problems.push(`- ${where}: unknown extension source "${source}" (registered: ${[...bySlug.keys()].join(', ') || 'none'})`);
+          } else if (!extSet.has(name)) {
+            problems.push(`- ${where}: extension "${source}" declares no component "${name}"`);
+          }
+          return;
+        }
+        if (!allKnown.has(name)) {
+          const suggestion = lowerToCanonical.get(name.toLowerCase());
+          problems.push(
+            `- ${where}: unknown component "${name}"${suggestion ? ` (did you mean "${suggestion}"?)` : ''}`,
+          );
+        }
+      });
+    }
+  }
+  return problems;
+}
+
 export default function cmsPlugin(options = {}) {
   const {
     siteDir: siteDirOption = './site',
     frameworkRoot: frameworkRootOption = __dirname,
-    locales = SUPPORTED_LOCALES,
     themes: themePackages = [],
     extensions: extensionPackages = [],
   } = options;
+  // The previous `locales` option is no longer accepted: per-site available
+  // locales are now discovered from on-disk content directories. Passing
+  // `locales` is silently ignored (kept here as a destructure to swallow it
+  // gracefully; the `SUPPORTED_LOCALES` constant remains exported only for
+  // any consumer that imports it directly).
 
   // These are resolved relative to the project cwd at config time
   let siteDir;
   let siteRoot; // project root — parent of siteDir
   let frameworkRoot;
   let siteConfig;
+  let baseLocale = 'en';
+  let availableLocales = [];
   let pagePaths;
   let metadata;
   let tempIndexPath;
   let tempEntryPath;
+  let variantCacheDir;
+  let variantManifestPath;
+  let imageVariantWidths = [];
+  // Closure-scoped (NOT this._isDevServer): Vite 8 binds configureServer to a
+  // shared minimal context, not the object buildEnd/closeBundle see, so a
+  // property stashed on `this` in one hook is invisible in the others.
+  let isDevServer = false;
 
   const writeTempFiles = () => {
     // Write entry file (with optional external theme registrations)
@@ -306,7 +479,8 @@ export default function cmsPlugin(options = {}) {
       siteDescription: metadata.siteDescription,
       siteUrl: metadata.siteUrl,
       siteGoogleId: metadata.siteGoogleId,
-      siteSameAsJson: metadata.siteSameAsJson,
+      siteSameAsList: metadata.siteSameAsList,
+      manifestThemeColor: metadata.manifestThemeColor,
     });
 
     const processed = html.replace(
@@ -349,11 +523,61 @@ export default function cmsPlugin(options = {}) {
     mirrorDir(frameworkPublicDir, sitePublicDir);
   };
 
+  // Generate robots.txt and sitemap.xml from the inflated site config and
+  // write them to siteRoot/public/. Runs after syncPublicDir so dynamic
+  // output overwrites any framework or stale static copy. Sites pick up
+  // changes by rebuilding (the existing edit-JSON-rebuild-deploy flow).
+  // Skip the write when content is unchanged: siteRoot/public/ may be
+  // git-tracked, and a plain `vite dev` session should not churn mtimes on
+  // tracked files.
+  const writeFileIfChanged = (filePath, content) => {
+    try {
+      if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf-8') === content) return;
+    } catch { /* unreadable → fall through to write */ }
+    fs.writeFileSync(filePath, content, 'utf-8');
+  };
+
+  const writeSeoFiles = ({ removeStale = true } = {}) => {
+    const sitePublicDir = path.join(siteRoot, 'public');
+    fs.mkdirSync(sitePublicDir, { recursive: true });
+
+    const sitemapXml = buildSitemap(siteConfig, { availableLocales, baseLocale });
+    const sitemapPath = path.join(sitePublicDir, 'sitemap.xml');
+    if (sitemapXml) {
+      writeFileIfChanged(sitemapPath, sitemapXml);
+    } else if (fs.existsSync(sitemapPath)) {
+      if (removeStale) {
+        // Stale sitemap from a previous build (e.g. site.url was removed, or
+        // every page is now draft). Drop it so crawlers don't get a list of
+        // URLs that no longer apply.
+        try { fs.unlinkSync(sitemapPath); } catch { /* noop */ }
+      } else {
+        // Dev session: never delete a (possibly tracked) file over what may
+        // be a transient config typo — a build will reconcile it.
+        console.warn('[@koehler8/cms] sitemap.xml is stale (no site.url, or the whole site is draft); left in place — the next build will remove it.');
+      }
+    }
+
+    const sitemapUrl = sitemapXml ? getSitemapUrl(siteConfig) : '';
+    const robotsBody = buildRobotsTxt(siteConfig, sitemapUrl);
+    writeFileIfChanged(path.join(sitePublicDir, 'robots.txt'), robotsBody);
+
+    // Web App Manifest. The template emits <link rel="manifest"> on every
+    // page; browsers use this to enable Add-to-Home-Screen + control
+    // splash colors when the site is launched from a homescreen icon.
+    const manifest = buildWebAppManifest(siteConfig);
+    writeFileIfChanged(
+      path.join(sitePublicDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2) + '\n',
+    );
+  };
+
   const cmsCore = {
     name: '@koehler8/cms',
     enforce: 'pre',
 
-    config(userConfig, env) {
+    async config(userConfig, env) {
+      isDevServer = env?.command === 'serve';
       // Resolve absolute paths
       frameworkRoot = path.resolve(frameworkRootOption);
       siteDir = path.isAbsolute(siteDirOption)
@@ -362,6 +586,13 @@ export default function cmsPlugin(options = {}) {
       siteRoot = path.dirname(siteDir);
       tempIndexPath = path.join(siteRoot, 'index.html');
       tempEntryPath = path.join(siteRoot, ENTRY_FILENAME);
+      variantCacheDir = computeVariantCacheDir(siteRoot, siteDir);
+      variantManifestPath = path.join(variantCacheDir, '.manifest.json');
+
+      // Invalid extension manifests fail the build here, loudly, instead of
+      // being silently skipped in the visitor's browser. The returned info
+      // (slug + declared component names) feeds components[] validation below.
+      const extensionManifestInfo = await validateExtensionManifests(extensionPackages, siteRoot, frameworkRoot);
 
       // Load site config at config-resolution time (needed for SSG routes + HTML injection)
       const contentDir = path.join(siteDir, 'content');
@@ -369,14 +600,85 @@ export default function cmsPlugin(options = {}) {
       const contentConfig = fs.existsSync(contentConfigPath)
         ? JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'))
         : {};
-      const baseLocale = contentConfig.baseLocale || 'en';
+      baseLocale = contentConfig.baseLocale || 'en';
       const configDir = path.join(contentDir, baseLocale);
       siteConfig = loadSplitConfig(configDir);
       if (!siteConfig) {
         throw new Error(`[@koehler8/cms] site config not found at ${configDir}`);
       }
+      // Discover locales actually present on disk: any directory under
+      // content/ that has at least one of `site.json`, `shared.json`, or
+      // a `pages/` subdir is treated as a real locale. (Earlier the check
+      // required `site.json` specifically — too strict for sites that
+      // author per-locale page overrides without overriding the site
+      // metadata, which is the common pattern for translation-only locale
+      // dirs.)
+      const localeDirHasContent = (dir) =>
+        fs.existsSync(path.join(dir, 'site.json'))
+        || fs.existsSync(path.join(dir, 'shared.json'))
+        || fs.existsSync(path.join(dir, 'pages'));
+      availableLocales = fs.existsSync(contentDir)
+        ? fs
+            .readdirSync(contentDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .filter((name) => localeDirHasContent(path.join(contentDir, name)))
+            .sort()
+        : [];
       pagePaths = collectPagePaths(siteConfig);
       metadata = extractSiteMetadata(siteConfig);
+      imageVariantWidths = resolveImageVariantConfig(siteConfig).widths;
+
+      // Unknown components[] references fail the build. Every locale's pages
+      // are checked — locale files can define their own component lists, and
+      // translation-only locale dirs may carry pages without a site.json.
+      const pagesByLocale = { [baseLocale]: siteConfig.pages || {} };
+      for (const locale of availableLocales) {
+        if (locale === baseLocale) continue;
+        const pagesDir = path.join(contentDir, locale, 'pages');
+        if (!fs.existsSync(pagesDir)) continue;
+        const localePages = {};
+        for (const file of fs.readdirSync(pagesDir)) {
+          if (!file.endsWith('.json')) continue;
+          try {
+            localePages[file.replace('.json', '')] = inflateFlatConfig(
+              JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8')),
+            );
+          } catch {
+            /* unparseable page JSON surfaces via the real config load */
+          }
+        }
+        pagesByLocale[locale] = localePages;
+      }
+      const bundledComponentNames = collectVueBasenames(path.join(frameworkRoot, 'src', 'components'));
+      bundledComponentNames.delete('Home'); // page wrapper, not addressable from components[]
+      const componentProblems = collectComponentRefProblems({
+        pagesByLocale,
+        bundledNames: bundledComponentNames,
+        siteNames: collectVueBasenames(path.join(siteDir, 'components')),
+        extensions: extensionManifestInfo,
+      });
+      if (componentProblems.length) {
+        throw new Error(
+          `[@koehler8/cms] Unknown component reference(s) in components[] — these sections would silently render nothing:\n${componentProblems.join('\n')}`,
+        );
+      }
+
+      // Contact-form shape check: a page with contact content but no valid
+      // form action renders a disabled form. Warn (not fatal) so the
+      // operator finds out at build time, not from a visitor.
+      for (const [locale, localePages] of Object.entries(pagesByLocale)) {
+        for (const [pageId, page] of Object.entries(localePages || {})) {
+          const contact = page?.content?.contact;
+          if (!contact || typeof contact !== 'object') continue;
+          const action = contact.form?.action;
+          if (typeof action !== 'string' || !/^https?:\/\//i.test(action.trim())) {
+            console.warn(
+              `[@koehler8/cms] pages/${pageId}.json (locale ${locale}): content.contact has no valid form.action URL — the contact form will render disabled.`,
+            );
+          }
+        }
+      }
 
       const extensionsDir = path.join(frameworkRoot, 'extensions');
       const extensionSetupFiles = collectExtensionSetupFiles(extensionsDir);
@@ -388,10 +690,22 @@ export default function cmsPlugin(options = {}) {
           alias: {
             '@cms-site': siteDir,
             '@cms-framework': frameworkRoot,
+            '@cms-variant-cache': variantCacheDir,
             '@': path.join(frameworkRoot, 'src'),
             '@extensions': extensionsDir,
           },
         },
+        // Static framework-version literal for src/utils/appInfo.js — the old
+        // `package.json?raw` import shipped the framework's entire manifest
+        // (deps, exports map) as a string in every client bundle to read one
+        // field. A real VITE_APP_VERSION env var still wins.
+        define: {
+          'import.meta.env.VITE_APP_VERSION': JSON.stringify(
+            process.env.VITE_APP_VERSION
+              || JSON.parse(fs.readFileSync(path.join(frameworkRoot, 'package.json'), 'utf-8')).version
+              || '0.0.0',
+          ),
+        },
         optimizeDeps: {
           // vue and vue-router MUST NOT be pre-bundled (inlined) into
           // @koehler8/cms chunks — if they are, .vue components served raw
@@ -400,14 +714,11 @@ export default function cmsPlugin(options = {}) {
           // injected router context (renders empty).
           exclude: ['vue', 'vue-router', 'pinia', '@koehler8/cms', ...extensionPackages],
           include: [
-            // CJS deps imported directly by framework source
-            'ajv',
-            'ajv/dist/2020',
-            'ajv/dist/2020.js',
-            'ajv-formats',
             // Auto-discovered CJS deps from extension packages.
             // Extensions may depend on ESM packages that import CJS modules;
             // these must be pre-bundled for proper default-export shims.
+            // (ajv is no longer here: manifest validation moved to build
+            // time in this plugin, so the runtime never imports it.)
             ...discoverExtensionCjsDeps(extensionPackages, siteRoot),
           ],
         },
@@ -418,6 +729,14 @@ export default function cmsPlugin(options = {}) {
         publicDir: path.join(siteRoot, 'public'),
         build: {
           modulePreload: false,
+          // `cms-ssg-build` renders each route shard as a separate build into
+          // its own outDir (e.g. `.cms-ssg/dist-0`), then merges them into
+          // `dist/`. Honor the override for the CLIENT build only — vite-ssg's
+          // SSR build sets its own temp outDir and then imports the server
+          // bundle back from there, so overriding it would break that import.
+          ...(process.env.CMS_SSG_OUTDIR && !(env?.isSsrBuild || userConfig?.build?.ssr)
+            ? { outDir: process.env.CMS_SSG_OUTDIR }
+            : {}),
           rollupOptions: {
             input: tempIndexPath,
             output: {
@@ -455,12 +774,51 @@ export default function cmsPlugin(options = {}) {
         },
         ssgOptions: {
           dirStyle: 'nested',
+          // Cap vite-ssg's render pool (default is 20). The SSG pre-render
+          // leaves a fixed retained cost per route (one jsdom document survives
+          // each page inside vite-ssg's loop), so peak heap is dominated by that
+          // accumulation rather than the concurrent batch — but a smaller pool
+          // still trims the transient working set layered on top and makes peak
+          // more predictable on large multi-locale sites. This is a mitigation,
+          // not the bound; see SSG-MEMORY-PLAN.md for the durable fix.
+          concurrency: 8,
+          // After vite-ssg pre-renders every route, copy the rendered
+          // dist/404/index.html to dist/404.html — the not-found target
+          // hosts point their catch-all at. (GitHub-Pages-style hosts
+          // auto-serve it at HTTP 404; AWS Amplify does NOT — it needs the
+          // fleet's customRule `/<*>` → `/404.html` @ `404`, which Amplify
+          // implements as a 302 redirect. Measured 2026-08-16.)
+          onFinished() {
+            const distDir = path.join(siteRoot, process.env.CMS_SSG_OUTDIR || 'dist');
+            const nestedNotFound = path.join(distDir, '404', 'index.html');
+            const flatNotFound = path.join(distDir, '404.html');
+            if (fs.existsSync(nestedNotFound)) {
+              try {
+                fs.copyFileSync(nestedNotFound, flatNotFound);
+              } catch (err) {
+                console.warn(`[@koehler8/cms] failed to write 404.html: ${err.message}`);
+              }
+            }
+          },
           includedRoutes(paths) {
-            const staticRoutes = new Set(['/admin']);
+            // /404 is the not-found landing page (rendered via the
+            // catch-all + NotFound component). onFinished above copies
+            // dist/404/index.html to dist/404.html; the host's catch-all
+            // rule sends unmatched URLs there. (On AWS Amplify that rule is
+            // a 302 redirect — its `404` rule type redirects rather than
+            // rewriting, and it has no native 404.html fallback. Measured
+            // 2026-08-16; the page's noindex meta covers the SEO side.)
+            const staticRoutes = new Set(['/404']);
             pagePaths.forEach((routePath) => staticRoutes.add(routePath));
 
+            // Pre-render every page under each non-base locale prefix that
+            // actually has a content directory on disk. The base locale is
+            // served at the unprefixed path (it's already covered by
+            // staticRoutes) — emitting `/{baseLocale}/path` would create
+            // duplicate URLs that all render the same content.
+            const localePrefixes = availableLocales.filter((l) => l !== baseLocale);
             const localizedRoutes = new Set();
-            locales.forEach((locale) => {
+            localePrefixes.forEach((locale) => {
               pagePaths.forEach((routePath) => {
                 const localized =
                   routePath === '/' ? `/${locale}` : `/${locale}${routePath}`;
@@ -473,7 +831,15 @@ export default function cmsPlugin(options = {}) {
               ...Array.from(staticRoutes),
               ...Array.from(localizedRoutes),
             ];
-            return Array.from(new Set(candidates));
+            const allRoutes = Array.from(new Set(candidates));
+
+            // Opt-in durable memory bound: when `cms-ssg-build` sets
+            // CMS_SSG_SHARD=k/N in the environment, render only this shard's
+            // slice of routes so peak SSG heap is bounded by slice size, not
+            // total route count. Unset (the normal `vite-ssg build` path) →
+            // the full list, byte-identical to before. (applyRouteShard keeps
+            // /404 in every shard so each can emit its own 404.html.)
+            return applyRouteShard(allRoutes, process.env.CMS_SSG_SHARD);
           },
         },
       };
@@ -554,7 +920,17 @@ const loader = createConfigLoader(allModules);
 export const loadConfigData = loader.loadConfigData;
 export const mergeConfigTrees = loader.mergeConfigTrees;
 export const cloneConfig = loader.cloneConfig;
-export const availableLocales = loader.availableLocales;
+// availableLocales + baseLocale are emitted as build-time literals derived
+// from the same on-disk discovery the plugin uses for SSG includedRoutes
+// and sitemap generation. This guarantees the runtime sees the exact same
+// locale list as the build, regardless of glob-based heuristics.
+export const availableLocales = ${JSON.stringify(availableLocales)};
+export const baseLocale = ${JSON.stringify(baseLocale)};
+// The resolved image-variant width matrix (site.imageVariants.widths or the
+// pipeline default) — the single source of truth useResponsiveImage builds
+// srcsets from, so components can never request widths the pipeline doesn't
+// generate.
+export const imageVariantWidths = ${JSON.stringify(imageVariantWidths)};
 `;
       }
 
@@ -567,7 +943,30 @@ export const ensureSiteStylesLoaded = loader.ensureSiteStylesLoaded;
 `;
       }
 
+      if (virtualId === VIRTUAL_SITE_COMPONENTS) {
+        // Eager glob — Vite resolves each match at build time and inlines
+        // the imported components. The result is a bare object literal of
+        // the form { './path/to/Foo.vue': ModuleLike } that componentRegistry
+        // re-keys by basename.
+        return `
+const modules = import.meta.glob('@cms-site/components/**/*.vue', { eager: true });
+export default modules;
+`;
+      }
+
       if (virtualId === VIRTUAL_ASSETS) {
+        // Three globs:
+        //   shared    — framework-bundled assets
+        //   site      — site/assets/** flat-dir originals (everything the
+        //               author put on disk, including any leftover variants
+        //               from the old pipeline that haven't been cleaned up)
+        //   variants  — generated variants from node_modules/.cache/
+        //               @koehler8/cms/image-variants/{siteKey}/assets/**.
+        //               The cache mirrors the site's `assets/` layout so
+        //               normalizeAssetKey strips the same `assets/` prefix
+        //               and surfaces variants under canonical `img/...` keys.
+        // Spread order: variants first so site flat-dir wins on collision —
+        // a hand-placed file in site/assets/img/ overrides the cached variant.
         return `
 import { createAssetResolver } from '@koehler8/cms/utils/assetResolver';
 const shared = import.meta.glob('@cms-framework/src/assets/**/*', {
@@ -575,15 +974,17 @@ const shared = import.meta.glob('@cms-framework/src/assets/**/*', {
   query: '?url',
   import: 'default',
 });
-const site = import.meta.glob([
-  '@cms-site/assets/**/*',
-  '!@cms-site/assets/_source/**',
-], {
+const site = import.meta.glob('@cms-site/assets/**/*', {
   eager: true,
   query: '?url',
   import: 'default',
 });
-const resolver = createAssetResolver(shared, site);
+const variants = import.meta.glob('@cms-variant-cache/assets/**/*', {
+  eager: true,
+  query: '?url',
+  import: 'default',
+});
+const resolver = createAssetResolver(shared, { ...variants, ...site });
 export const resolveAssetUrl = resolver.resolveAssetUrl;
 export const resolveAsset = resolver.resolveAsset;
 export const resolveMedia = resolver.resolveMedia;
@@ -594,33 +995,97 @@ export const assetUrlMap = resolver.assetUrlMap;
       return null;
     },
 
+    async transform(code, id) {
+      // Strip plaintext draftPassword from any site.json under content/
+      // before it lands in the bundle. The runtime reads the resulting
+      // draftPasswordHash via siteData and verifies user input against
+      // the hash. enforce: 'pre' on this plugin runs the transform before
+      // Vite's built-in JSON plugin converts the file to a JS module.
+      if (!id) return null;
+      const idPath = id.split('?')[0];
+      if (!idPath.endsWith('/site.json')) return null;
+      if (!idPath.includes(`${path.sep}content${path.sep}`) && !idPath.includes('/content/')) {
+        return null;
+      }
+      const transformed = await transformSiteJson(code);
+      if (transformed == null) return null;
+      return { code: transformed, map: null };
+    },
+
+    async buildStart() {
+      // Generate image variants into the cache dir BEFORE the VIRTUAL_ASSETS
+      // load() block runs its import.meta.glob — that glob picks up the cache
+      // files and surfaces them as Vite-pipelined assets (hashed, emitted to
+      // dist/assets/) at build, or served straight from disk during dev.
+      //
+      // Errors here are warned, not thrown — a broken variant pipeline should
+      // not kill the entire build. Sites without source images (no img dir,
+      // empty img dir) are no-ops.
+      const siteImgDir = path.join(siteDir, 'assets', 'img');
+
+      // Strict deprecation: warn loudly if the legacy _source/ dir exists.
+      // Pipeline only reads the flat dir — sites that haven't migrated will
+      // see broken image URLs until the originals move up a level.
+      const legacySourceDir = path.join(siteImgDir, '_source');
+      if (fs.existsSync(legacySourceDir)) {
+        this.warn(
+          `[@koehler8/cms] Found legacy site/assets/img/_source/ directory.`
+          + ` Image originals live directly in site/assets/img/ and variants`
+          + ` generate at build time into node_modules/.cache/. Move the`
+          + ` originals from _source/ up into site/assets/img/, delete any`
+          + ` committed pre-generated variants ({name}-{width}.{ext} files),`
+          + ` and remove _source/. The pipeline is NOT reading from _source/`
+          + ` — image URLs will 404 until you migrate.`,
+        );
+      }
+
+      try {
+        const variantConfig = resolveImageVariantConfig(siteConfig);
+        const jobs = planVariantJobsFromFlatDir({
+          siteImgDir,
+          config: variantConfig,
+        });
+        await reconcileVariantCache({
+          jobs,
+          cacheDir: variantCacheDir,
+          manifestPath: variantManifestPath,
+          currentConfig: variantConfig,
+          log: (msg) => this.warn(`[@koehler8/cms image-variants] ${msg}`),
+        });
+      } catch (err) {
+        this.warn(`[@koehler8/cms image-variants] generation failed: ${err.message}`);
+      }
+    },
+
     configResolved(resolvedConfig) {
       // Write temp files as soon as config is resolved so vite-ssg's
       // detectEntry (which runs before Vite's build lifecycle) finds them.
       writeTempFiles();
 
       // Mirror framework's public/ into the site's public/ so fonts, maps,
-      // robots.txt, etc. end up in dist. Site-specific files (favicon.ico,
-      // logo.png, og-image.jpg written by generate-public-assets) win over
-      // any accidental collisions because we skip files that already exist.
+      // etc. end up in dist. Site-specific files (favicon.ico, logo.png,
+      // og-image.jpg written by generate-public-assets) win over any
+      // accidental collisions because we skip files that already exist.
       syncPublicDir();
+
+      // robots.txt and sitemap.xml are generated from the inflated site
+      // config (so per-site draft state regenerates on every build). Dev
+      // sessions write-if-changed only and never delete (public/ may be
+      // git-tracked; a config typo mid-session must not remove files).
+      writeSeoFiles({ removeStale: !isDevServer });
     },
 
     buildEnd() {
       // Only clean up during actual builds, not dev server
-      if (!this._isDevServer) cleanupTempFiles();
+      if (!isDevServer) cleanupTempFiles();
     },
 
     closeBundle() {
       // Only clean up during actual builds, not dev server
-      if (!this._isDevServer) cleanupTempFiles();
+      if (!isDevServer) cleanupTempFiles();
     },
 
     configureServer(server) {
-      // Mark that we're running as a dev server so buildEnd/closeBundle
-      // don't prematurely delete the temp files.
-      this._isDevServer = true;
-
       // Clean up only when the dev server actually closes
       server.httpServer?.once('close', cleanupTempFiles);
       process.once('exit', cleanupTempFiles);
@@ -656,8 +1121,59 @@ export const assetUrlMap = resolver.assetUrlMap;
       // Watch site content for HMR
       server.watcher.add(siteDir);
 
+      // Image-variant regen on source-image change. Debounced so bulk
+      // drag-and-drop adds don't trigger N pipeline runs. Writes to the
+      // cache dir don't re-trigger because we early-return on those events.
+      const siteImgDir = path.join(siteDir, 'assets', 'img');
+      let pendingVariantRegen = null;
+      const scheduleVariantRegen = () => {
+        if (pendingVariantRegen) clearTimeout(pendingVariantRegen);
+        pendingVariantRegen = setTimeout(async () => {
+          pendingVariantRegen = null;
+          try {
+            const variantConfig = resolveImageVariantConfig(siteConfig);
+            const jobs = planVariantJobsFromFlatDir({
+              siteImgDir,
+              config: variantConfig,
+            });
+            await reconcileVariantCache({
+              jobs,
+              cacheDir: variantCacheDir,
+              manifestPath: variantManifestPath,
+              currentConfig: variantConfig,
+              log: (msg) => console.log(`[@koehler8/cms image-variants] ${msg}`),
+            });
+            // Invalidate the asset-resolver virtual module so its
+            // import.meta.glob re-evaluates and the new variant URLs land
+            // in the asset map. The full-reload below picks them up.
+            const assetMod = server.moduleGraph.getModuleById(resolved(VIRTUAL_ASSETS));
+            if (assetMod) server.moduleGraph.invalidateModule(assetMod);
+            server.ws.send({ type: 'full-reload' });
+          } catch (err) {
+            console.warn(`[@koehler8/cms image-variants] regen failed: ${err.message}`);
+          }
+        }, 250);
+      };
+      const handleImageEvent = (file) => {
+        if (typeof file !== 'string') return;
+        // Ignore writes our own pipeline made into the cache dir.
+        if (variantCacheDir && file.startsWith(variantCacheDir)) return;
+        if (!file.startsWith(siteImgDir)) return;
+        scheduleVariantRegen();
+      };
+      server.watcher.on('add', handleImageEvent);
+      server.watcher.on('change', handleImageEvent);
+      server.watcher.on('unlink', handleImageEvent);
+
       // Invalidate virtual modules when site content changes
       const invalidate = (file) => {
+        // Don't double-handle image events — the dedicated handler above
+        // (debounced variant regen) owns everything under site/assets/img/
+        // and the cache dir, and fires its own full-reload once the fresh
+        // variants exist. Handling them here too caused two full reloads per
+        // image edit, the first against stale variants.
+        if (variantCacheDir && file.startsWith(variantCacheDir)) return;
+        if (siteImgDir && file.startsWith(siteImgDir)) return;
         if (!file.startsWith(siteDir)) return;
         for (const id of VIRTUAL_IDS) {
           const mod = server.moduleGraph.getModuleById(resolved(id));
@@ -683,7 +1199,8 @@ export const assetUrlMap = resolver.assetUrlMap;
               siteDescription: metadata.siteDescription,
               siteUrl: metadata.siteUrl,
               siteGoogleId: metadata.siteGoogleId,
-              siteSameAsJson: metadata.siteSameAsJson,
+              siteSameAsList: metadata.siteSameAsList,
+              manifestThemeColor: metadata.manifestThemeColor,
             });
 
             html = html.replace(