@koehler8/cms 1.0.0-beta.34 → 1.0.0-beta.36

package/bin/cms-ssg-build.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin wrapper that runs the memory-bounded SSG build orchestrator from the
+// consuming site's cwd. The script does its own argument handling, spawns the
+// per-shard `vite-ssg build` processes, and prints its own status.
+// See scripts/ssg-build/index.mjs and SSG-MEMORY-PLAN.md.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+await import(path.resolve(__dirname, '..', 'scripts', 'ssg-build', 'index.mjs'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.34",
+  "version": "1.0.0-beta.36",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -54,6 +54,7 @@
   },
   "bin": {
     "cms-generate-public-assets": "./bin/cms-generate-public-assets.js",
+    "cms-ssg-build": "./bin/cms-ssg-build.js",
     "cms-migrate-image-variants": "./bin/cms-migrate-image-variants.js",
     "cms-validate-themes": "./bin/cms-validate-themes.js",
     "cms-validate-extensions": "./bin/cms-validate-extensions.js",
@@ -87,13 +88,13 @@
     "dotenv": "^17.2.3",
     "pinia": "^3.0.1",
     "png-to-ico": "^3.0.1",
-    "sharp": "^0.33.5"
+    "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@vue/test-utils": "^2.4.10",
     "happy-dom": "^20.9.0",
     "vitest": "^4.1.6",
-    "vue": "^3.5.34",
+    "vue": "^3.5.39",
     "vue-router": "^5.0.7"
   },
   "engines": {

package/scripts/ssg-build/index.mjs

@@ -0,0 +1,197 @@
+/**
+ * cms-ssg-build — memory-bounded SSG pre-render (the durable fix for the
+ * per-route heap accumulation in vite-ssg's single-process render; see
+ * SSG-MEMORY-PLAN.md).
+ *
+ * vite-ssg renders every route in one Node process and leaves a fixed retained
+ * cost per route, so peak heap scales with total routes (pages × locales) and
+ * large sites OOM. This orchestrator runs the render as N separate
+ * `vite-ssg build` processes, each handling a slice of the routes (via the
+ * framework's CMS_SSG_SHARD hook) into its own outDir, then merges the shards
+ * into dist/. Because each shard is its own process, memory is reclaimed
+ * between shards — peak heap is bounded by SLICE size, not total routes,
+ * independent of how large the site grows.
+ *
+ * Shards run sequentially by default: that gives the LOWEST peak memory (one
+ * shard live at a time), which is the whole point. Parallelism would trade that
+ * back for build speed and also races on the plugin's shared writes to the site
+ * root, so it stays opt-in/experimental.
+ *
+ * Small sites (≤ one shard) fall through to a single ordinary `vite-ssg build`,
+ * byte-identical to today.
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const CWD = process.cwd();
+const TAG = '[cms-ssg-build]';
+
+function parseArgs(argv) {
+  const opts = {
+    shardSize: 150, // routes per shard
+    concurrency: 1, // sequential by default (lowest peak memory + no shared-write race)
+    heap: 2048, // per-shard --max-old-space-size (MB); a slice fits comfortably
+    siteDir: './site',
+    passthrough: [], // forwarded verbatim to `vite-ssg build`
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--shard-size') opts.shardSize = Number(argv[++i]) || opts.shardSize;
+    else if (a === '--concurrency') opts.concurrency = Math.max(1, Number(argv[++i]) || 1);
+    else if (a === '--heap') opts.heap = Number(argv[++i]) || opts.heap;
+    else if (a === '--site-dir') opts.siteDir = argv[++i] || opts.siteDir;
+    else opts.passthrough.push(a);
+  }
+  return opts;
+}
+
+// Estimate the route count the same way the Vite plugin discovers routes
+// (base-locale pages × content locales, + /404 + /admin). Only used to choose
+// the shard count N; the framework's CMS_SSG_SHARD filter partitions whatever
+// routes actually exist, so an approximate N still yields a correct, complete
+// dist/ — it just tunes slice sizes.
+function estimateRouteCount(siteDir) {
+  const contentDir = path.join(siteDir, 'content');
+  let baseLocale = 'en';
+  try {
+    baseLocale = JSON.parse(fs.readFileSync(path.join(contentDir, 'content.config.json'), 'utf8')).baseLocale || 'en';
+  } catch { /* default en */ }
+
+  let pages = 1;
+  try {
+    pages = fs.readdirSync(path.join(contentDir, baseLocale, 'pages')).filter((f) => f.endsWith('.json')).length || 1;
+  } catch { /* single page */ }
+
+  let locales = 1;
+  try {
+    locales = fs.readdirSync(contentDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .filter((d) => {
+        const dir = path.join(contentDir, d.name);
+        return fs.existsSync(path.join(dir, 'site.json'))
+          || fs.existsSync(path.join(dir, 'shared.json'))
+          || fs.existsSync(path.join(dir, 'pages'));
+      }).length || 1;
+  } catch { /* single locale */ }
+
+  return pages * locales + 2; // + /404 + /admin
+}
+
+function resolveViteSsgBin() {
+  const local = path.join(CWD, 'node_modules', '.bin', 'vite-ssg');
+  return fs.existsSync(local) ? local : 'vite-ssg';
+}
+
+function runViteSsg({ shard, outDir, heap, passthrough }) {
+  return new Promise((resolve) => {
+    const env = { ...process.env };
+    if (shard) env.CMS_SSG_SHARD = shard;
+    if (outDir) env.CMS_SSG_OUTDIR = outDir;
+    // A shard renders a bounded slice, so a modest heap suffices — this is what
+    // lets sites drop the 8 GB stop-loss flag. Strip any inherited
+    // --max-old-space-size and set our own.
+    const base = (process.env.NODE_OPTIONS || '').replace(/--max-old-space-size=\d+/g, '').trim();
+    env.NODE_OPTIONS = `${base} --max-old-space-size=${heap}`.trim();
+
+    const child = spawn(resolveViteSsgBin(), ['build', ...passthrough], { cwd: CWD, env });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { out += d; });
+    child.on('close', (code) => resolve({ code, out }));
+    child.on('error', (err) => resolve({ code: 1, out: String(err && err.stack ? err.stack : err) }));
+  });
+}
+
+async function pool(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await worker(items[i], i);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
+// Union-merge every shard's output into dist/. Shared files (assets/, sitemap,
+// robots, manifest, favicon, 404.html) are byte-identical across shards, and
+// per-route HTML files are disjoint — so a plain overwrite-merge is a clean
+// union. The ONE exception is dist/index.html: only the shard that rendered `/`
+// produced the real home page; every other shard's client build left a
+// hydration shell there. So after merging, restore the rendered home
+// explicitly (identified by the data-server-rendered marker).
+async function mergeShards(shardDirs, finalDist) {
+  await fsp.rm(finalDist, { recursive: true, force: true });
+  await fsp.mkdir(finalDist, { recursive: true });
+  for (const dir of shardDirs) {
+    await fsp.cp(dir, finalDist, { recursive: true, force: true });
+  }
+
+  let renderedHome = null;
+  for (const dir of shardDirs) {
+    try {
+      const html = await fsp.readFile(path.join(dir, 'index.html'), 'utf8');
+      if (html.includes('data-server-rendered="true"')) { renderedHome = html; break; }
+    } catch { /* shard has no index.html */ }
+  }
+  if (renderedHome != null) {
+    await fsp.writeFile(path.join(finalDist, 'index.html'), renderedHome, 'utf8');
+  } else {
+    console.warn(`${TAG} warning: no shard produced a server-rendered home page; dist/index.html left as the client shell.`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const siteDir = path.resolve(CWD, opts.siteDir);
+  const estRoutes = estimateRouteCount(siteDir);
+  const N = Math.max(1, Math.ceil(estRoutes / opts.shardSize));
+
+  if (N <= 1) {
+    console.log(`${TAG} ~${estRoutes} routes ≤ shard size ${opts.shardSize}: running a single vite-ssg build (no sharding needed).`);
+    const r = await runViteSsg({ heap: opts.heap, passthrough: opts.passthrough });
+    process.stdout.write(r.out);
+    process.exit(r.code);
+  }
+
+  console.log(`${TAG} ~${estRoutes} routes → ${N} shards of ≤${opts.shardSize}, ${opts.heap} MB heap each, ${opts.concurrency === 1 ? 'sequential' : `${opts.concurrency}-way parallel`}. Peak heap is bounded per shard.`);
+  if (opts.concurrency > 1) {
+    console.warn(`${TAG} warning: --concurrency > 1 is experimental — parallel shards race on the plugin's shared site-root writes and raise peak memory. Sequential is recommended.`);
+  }
+
+  const tmp = path.join(CWD, '.cms-ssg');
+  await fsp.rm(tmp, { recursive: true, force: true });
+  await fsp.mkdir(tmp, { recursive: true });
+
+  const shards = Array.from({ length: N }, (_, k) => ({ k, outDir: path.join('.cms-ssg', `dist-${k}`) }));
+  const t0 = Date.now();
+  const results = await pool(shards, opts.concurrency, async (s) => {
+    const started = Date.now();
+    process.stdout.write(`${TAG} shard ${s.k + 1}/${N} rendering…\n`);
+    const r = await runViteSsg({ shard: `${s.k}/${N}`, outDir: s.outDir, heap: opts.heap, passthrough: opts.passthrough });
+    process.stdout.write(`${TAG} shard ${s.k + 1}/${N} ${r.code === 0 ? 'ok' : 'FAILED'} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
+    return { ...r, k: s.k };
+  });
+
+  const failed = results.filter((r) => r.code !== 0);
+  if (failed.length) {
+    console.error(`${TAG} ${failed.length}/${N} shard(s) failed:`);
+    for (const f of failed) {
+      console.error(`${TAG} ---- shard ${f.k} output (tail) ----`);
+      console.error(f.out.slice(-4000));
+    }
+    process.exit(1);
+  }
+
+  await mergeShards(shards.map((s) => path.join(CWD, s.outDir)), path.join(CWD, 'dist'));
+  await fsp.rm(tmp, { recursive: true, force: true });
+  console.log(`${TAG} merged ${N} shards → dist/ in ${((Date.now() - t0) / 1000).toFixed(1)}s. Done.`);
+}
+
+main().catch((err) => { console.error(TAG, err); process.exit(1); });

package/src/composables/usePageConfig.js

@@ -219,11 +219,20 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     cachedConfig = primed;
     lastLocaleKey = localeKey;
 
-    // Preserve the saved-locale auto-switch on base-locale routes: the server
-    // has no localStorage, so it rendered the base locale. If a returning
-    // visitor stored a different locale, reconcile AFTER the first paint
-    // (soft = no blank) so that paint still matches the server but the saved
-    // choice is honored.
+    // Decide whether a soft (no blank-out) background reload of the FULL config
+    // is needed after this first synchronous paint. Two independent triggers,
+    // both satisfied by the same single reload:
+    //
+    //  1. Partial embed: the server trimmed the embedded config to just this
+    //     page (site.trimInitialState), so the primed config can't resolve
+    //     OTHER pages for in-SPA navigation. Load the full config now; the
+    //     current page re-applies identically, so there's no visible change.
+    //  2. Saved-locale switch: the server has no localStorage, so a base-locale
+    //     route rendered the base locale. If a returning visitor stored a
+    //     different locale, reconcile to it. (loadConfigData reads localStorage
+    //     when no explicit locale is passed, so the same reload resolves it.)
+    let needsFullReload = Boolean(primed && primed.pagesPartial);
+
     if (localeForConfig === undefined && typeof localStorage !== 'undefined') {
       let stored = '';
       try {
@@ -231,10 +240,12 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
       } catch {
         stored = '';
       }
-      if (stored) {
-        lastLocaleKey = null; // force the reconcile to reload with localStorage resolution
-        syncPage({ soft: true });
-      }
+      if (stored) needsFullReload = true;
+    }
+
+    if (needsFullReload) {
+      lastLocaleKey = null; // force syncPage to reload (localStorage-resolved for base routes)
+      syncPage({ soft: true });
     }
     return true;
   }

package/src/main.js

@@ -6,7 +6,7 @@ import App from './App.vue';
 import { routes, resolveHistory, applyRouterGuards } from './router/index.js';
 
 import { shouldEnableAnalytics, scheduleAnalyticsLoad } from './utils/cookieConsent.js';
-import { loadConfigData, primeConfigSync } from './utils/loadConfig.js';
+import { loadConfigData, primeConfigSync, trimConfigToPage, resolvePageIdForRoute } from './utils/loadConfig.js';
 import { persistAttributionFromLocation } from './utils/trackingContext.js';
 import { applyThemeVariables } from './themes/themeManager.js';
 import { setActiveThemeKey } from './utils/themeColors.js';
@@ -145,6 +145,18 @@ export function createCmsApp() {
         return null;
       };
 
+      // SSG only: resolve the route being pre-rendered to its page id so the
+      // embedded config can be trimmed to that single page when the site opts
+      // into `site.trimInitialState`. The matching rules live in the pure,
+      // unit-tested resolvePageIdForRoute (returns null on ambiguity → keep the
+      // full config, a safe no-op).
+      const resolveCurrentPageId = (config) => {
+        const route = extractCurrentRoute();
+        const rawPath = typeof route?.path === 'string' ? route.path : '';
+        const localeParam = pickLocaleParam(route?.params?.locale);
+        return resolvePageIdForRoute(config, rawPath, localeParam);
+      };
+
       const loadSiteConfig = async (options = {}) => {
         const requestedLocale =
           pickLocaleParam(options.locale) ??
@@ -178,6 +190,18 @@ export function createCmsApp() {
       if (!isClient) {
         try {
           await loadSiteConfig();
+          // Opt-in payload trim: embed only the current page's config in
+          // window.__INITIAL_STATE__ rather than every page's (the full-site
+          // blob is byte-identical on every page and can dominate page weight).
+          // The rendered HTML body is unaffected — usePageConfig resolves the
+          // SSR render from its own loadConfigData() call, not from
+          // initialState — so this only shrinks the serialized hydration blob.
+          if (initialState.siteConfig?.site?.trimInitialState === true) {
+            const currentPageId = resolveCurrentPageId(initialState.siteConfig);
+            if (currentPageId) {
+              initialState.siteConfig = trimConfigToPage(initialState.siteConfig, currentPageId);
+            }
+          }
         } catch (error) {
           console.error('Failed to load site configuration during SSG build', error);
         }

package/src/utils/loadConfig.js

@@ -34,6 +34,49 @@ export function cloneConfig(value) {
     return value;
 }
 
+// Reduce a resolved config's `pages` map to a single page, preserving `site`
+// and `shared` (which every page needs globally). Used by the SSG pass when a
+// site opts into `site.trimInitialState` so each pre-rendered page embeds only
+// its own page config in `window.__INITIAL_STATE__` instead of the entire
+// site's pages (which is byte-identical on every page and can dominate the
+// page weight). Marks the result `pagesPartial: true` so the client knows the
+// embedded config can't resolve other pages and must lazy-load the full config
+// before in-SPA navigation (see usePageConfig.hydrateFromSyncCache). Returns
+// the config untouched when the page id is absent — a safe no-op fallback so a
+// mis-resolved route never trims away the page actually being rendered.
+export function trimConfigToPage(config, pageId) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) return config;
+    if (!config.pages || typeof config.pages !== 'object') return config;
+    if (!pageId || !Object.prototype.hasOwnProperty.call(config.pages, pageId)) return config;
+    return { ...config, pages: { [pageId]: config.pages[pageId] }, pagesPartial: true };
+}
+
+// Map a route being pre-rendered to its page id, for the SSG trim above.
+// Strips a leading `/{locale}` segment (non-base locales render at
+// `/{locale}/path`), normalizes trailing/duplicate slashes, and matches against
+// each page's `path` (defaulting a path-less page to '/'). Returns the id only
+// on an UNAMBIGUOUS single match — home, path-less, or colliding routes return
+// null so the caller keeps the full config (a safe no-op). Pure/exported so the
+// locale-strip + matching rules are unit-testable without a full SSG build.
+export function resolvePageIdForRoute(config, routePath, localeParam) {
+    if (typeof routePath !== 'string' || !routePath) return null;
+    let target = routePath;
+    if (localeParam && typeof localeParam === 'string') {
+        const prefix = `/${localeParam}`;
+        if (target === prefix) target = '/';
+        else if (target.startsWith(`${prefix}/`)) target = target.slice(prefix.length);
+    }
+    const normalize = (p) =>
+        (typeof p === 'string' ? p : '/').replace(/\/+/g, '/').replace(/\/+$/, '') || '/';
+    target = normalize(target);
+    const pages = (config && config.pages) || {};
+    const matches = Object.entries(pages).filter(([, data]) => {
+        const pagePath = data && typeof data.path === 'string' && data.path.trim() ? data.path : '/';
+        return normalize(pagePath) === target;
+    });
+    return matches.length === 1 ? matches[0][0] : null;
+}
+
 export function mergeConfigTrees(target, source, options = {}) {
     const { cloneTarget = false, skipEmpty = true } = options;
 

package/src/utils/ssgRoutes.js

@@ -0,0 +1,40 @@
+// Route sharding for `cms-ssg-build` — the opt-in durable memory bound for the
+// SSG pre-render. vite-ssg renders every route in one Node process and leaves a
+// fixed retained cost per route, so peak heap scales with total routes;
+// `cms-ssg-build` runs the render in N separate processes, each handling a slice
+// of the routes, so peak heap is bounded by slice size instead. This module is
+// the pure partition function so the slicing rules are unit-testable without a
+// build. See SSG-MEMORY-PLAN.md.
+
+// Routes every shard renders regardless of its slice. `/404` must be present in
+// each shard's output dir so that shard's `onFinished` can copy 404/index.html
+// → 404.html; `/admin` is a cheap vestigial placeholder kept alongside it.
+export const ALWAYS_SHARDED_ROUTES = ['/404', '/admin'];
+
+/**
+ * Return shard `k` of `N` from the full SSG route list.
+ *
+ * `shardSpec` is a `"k/N"` string (e.g. `"2/5"`). Shard k = the always-present
+ * routes + every Nth remaining route offset by k, so the N shards partition the
+ * non-always routes exactly once each (no route rendered twice, none dropped).
+ *
+ * Returns the full list unchanged when `shardSpec` is absent or malformed —
+ * this is the normal `vite-ssg build` path and must stay byte-identical.
+ */
+export function applyRouteShard(allRoutes, shardSpec) {
+  if (!Array.isArray(allRoutes)) return allRoutes;
+  const match = typeof shardSpec === 'string' ? shardSpec.trim().match(/^(\d+)\/(\d+)$/) : null;
+  if (!match) return allRoutes;
+
+  const k = Number(match[1]);
+  const n = Number(match[2]);
+  if (!(n > 0) || k < 0 || k >= n) return allRoutes;
+
+  const always = new Set(ALWAYS_SHARDED_ROUTES);
+  const alwaysRoutes = allRoutes.filter((route) => always.has(route));
+  const shardRoutes = allRoutes
+    .filter((route) => !always.has(route))
+    .filter((_, i) => i % n === k);
+
+  return Array.from(new Set([...alwaysRoutes, ...shardRoutes]));
+}

package/templates/scaffolds/site/package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "build:ssg": "vite-ssg build",
+    "build:ssg": "NODE_OPTIONS=--max-old-space-size=4096 vite-ssg build",
     "preview": "vite preview",
     "generate:public-assets": "cms-generate-public-assets --site-dir ./site"
   },

package/vite-plugin.js

@@ -17,6 +17,7 @@ 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,
@@ -539,6 +540,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: {
@@ -576,13 +585,21 @@ 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. AWS Amplify (and most
           // static hosts) auto-serve a top-level 404.html for any
           // unmatched URL with HTTP status 404, so this gives sites a
           // proper not-found response without per-site config.
           onFinished() {
-            const distDir = path.join(siteRoot, 'dist');
+            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)) {
@@ -622,7 +639,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 + /admin in every shard so each can emit its own 404.html.)
+            return applyRouteShard(allRoutes, process.env.CMS_SSG_SHARD);
           },
         },
       };