@koehler8/cms 1.0.0-beta.6 → 1.0.0-beta.8

package/README.md

@@ -75,15 +75,25 @@ vite-ssg build    # Static site generation
 
 ## Site Configuration
 
-Site content lives in `site/config/`:
+Site content lives in `site/content/`, organized by locale:
 
-- **`site.json`** -- Site-level metadata (title, description, URL, theme, Google Analytics ID)
-- **`shared.json`** -- Content blocks shared across pages (header, footer, socials)
-- **`pages/*.json`** -- Per-page content keyed by page ID
-
-### Locale Overrides
+```
+site/content/
+  content.config.json        # { "baseLocale": "en" }
+  en/
+    site.json                # Site metadata (flat dot-notation keys, sorted)
+    shared.json              # Shared content (header, footer, socials)
+    pages/
+      home.json              # Per-page content
+      privacy.json
+  de/
+    site.json                # German overrides (only translated keys)
+    shared.json
+    pages/
+      home.json
+```
 
-Place locale-specific configs in `site/config/i18n/{locale}/` mirroring the same structure. They are deep-merged over the base config at runtime.
+All files use flat dot-notation keys in alphabetical order. The base locale (specified in `content.config.json`) is loaded first; other locale directories override only the keys they specify. Missing keys fall back to the base locale value.
 
 **Supported locales:** en, fr, es, de, ja, ko, pt, ru, tr, vi, id, zh, th, hi, fil
 
@@ -91,7 +101,7 @@ Place locale-specific configs in `site/config/i18n/{locale}/` mirroring the same
 
 Themes export a manifest with design tokens (palette, typography, surfaces, CTAs, etc.) that are applied as CSS variables at runtime.
 
-- Set `site.theme` in `site.json` to a theme slug
+- Set the `theme` key in `content/{baseLocale}/site.json` to a theme slug
 - Omit it to use the built-in `base` theme
 - External themes are npm packages registered via the `themes` plugin option
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/scripts/generate-public-assets.js

@@ -3,7 +3,7 @@
 //
 // Reads from CMS_SITE_DIR env var (e.g. /path/to/my-site/site/).
 // Assets are read from {CMS_SITE_DIR}/assets/, config from
-// {CMS_SITE_DIR}/config/site.json, output is written to
+// {CMS_SITE_DIR}/content/{baseLocale}/site.json, output is written to
 // {dirname(CMS_SITE_DIR)}/public/.
 
 import 'dotenv/config';
@@ -260,12 +260,23 @@ function renderOgImageBuffer(text, { width = 1200, height = 630, bg = '#000000',
 }
 
 function loadSiteTitle() {
-  const configPath = path.join(CMS_SITE_DIR, 'config', 'site.json');
+  const contentDir = path.join(CMS_SITE_DIR, 'content');
+  const contentConfigPath = path.join(contentDir, 'content.config.json');
+  let baseLocale = 'en';
+  try {
+    if (fs.existsSync(contentConfigPath)) {
+      const cc = JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'));
+      baseLocale = cc.baseLocale || 'en';
+    }
+  } catch { /* use default */ }
+
+  const configPath = path.join(contentDir, baseLocale, 'site.json');
   if (!fs.existsSync(configPath)) return '';
   try {
     const raw = fs.readFileSync(configPath, 'utf-8');
     const parsed = JSON.parse(raw);
-    const title = parsed?.title || parsed?.site?.title;
+    // Flat format: key is "title"; nested format: key is "site.title" or nested
+    const title = parsed?.title || parsed?.['site.title'] || parsed?.site?.title;
     if (typeof title === 'string' && title.trim()) {
       return title.trim();
     }

package/scripts/migrate-to-content-dirs.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Migration script: converts site/config/ structure to site/content/ structure.
+ *
+ * Old layout:
+ *   site/config/site.json          (nested)
+ *   site/config/shared.json        (nested)
+ *   site/config/pages/*.json       (nested)
+ *   site/config/i18n/{locale}.json (flat dot-notation)
+ *
+ * New layout:
+ *   site/content/content.config.json  ({ "baseLocale": "en" })
+ *   site/content/en/site.json         (flat dot-notation, sorted)
+ *   site/content/en/shared.json       (flat dot-notation, sorted)
+ *   site/content/en/pages/*.json      (flat dot-notation, sorted)
+ *   site/content/{locale}/site.json   (flat dot-notation, sorted, overrides only)
+ *   site/content/{locale}/shared.json
+ *   site/content/{locale}/pages/*.json
+ *
+ * Usage:
+ *   node scripts/migrate-to-content-dirs.mjs /path/to/site-repo
+ *   node scripts/migrate-to-content-dirs.mjs /path/to/site-repo --commit
+ *
+ * Without --commit, runs in dry-run mode (prints what it would do).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---- Flatten utility ----
+
+const ARRAY_INDEX_RE = /\[(\d+)]/g;
+
+function flattenObject(obj, prefix = '') {
+  const result = {};
+  if (!obj || typeof obj !== 'object') return result;
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+
+    if (Array.isArray(value)) {
+      value.forEach((item, idx) => {
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+          Object.assign(result, flattenObject(item, `${fullKey}[${idx}]`));
+        } else {
+          result[`${fullKey}[${idx}]`] = item;
+        }
+      });
+    } else if (value && typeof value === 'object') {
+      Object.assign(result, flattenObject(value, fullKey));
+    } else {
+      result[fullKey] = value;
+    }
+  }
+  return result;
+}
+
+function sortedJson(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = obj[key];
+  }
+  return JSON.stringify(sorted, null, 2) + '\n';
+}
+
+// ---- Main ----
+
+const siteRepoDir = process.argv[2];
+const commit = process.argv.includes('--commit');
+
+if (!siteRepoDir) {
+  console.error('Usage: node scripts/migrate-to-content-dirs.mjs /path/to/site-repo [--commit]');
+  process.exit(1);
+}
+
+const siteDir = path.join(siteRepoDir, 'site');
+const configDir = path.join(siteDir, 'config');
+const contentDir = path.join(siteDir, 'content');
+
+if (!fs.existsSync(configDir)) {
+  console.error(`Config directory not found: ${configDir}`);
+  process.exit(1);
+}
+
+const actions = [];
+
+function plan(action, detail) {
+  actions.push({ action, detail });
+  if (!commit) console.log(`  [dry-run] ${action}: ${detail}`);
+}
+
+// 1. Flatten and move English base files
+const enDir = path.join(contentDir, 'en');
+const enPagesDir = path.join(enDir, 'pages');
+
+// site.json
+const siteJsonPath = path.join(configDir, 'site.json');
+if (fs.existsSync(siteJsonPath)) {
+  const nested = JSON.parse(fs.readFileSync(siteJsonPath, 'utf-8'));
+  const flat = flattenObject(nested);
+  plan('write', `content/en/site.json (${Object.keys(flat).length} keys)`);
+  if (commit) {
+    fs.mkdirSync(enDir, { recursive: true });
+    fs.writeFileSync(path.join(enDir, 'site.json'), sortedJson(flat));
+  }
+}
+
+// shared.json
+const sharedJsonPath = path.join(configDir, 'shared.json');
+if (fs.existsSync(sharedJsonPath)) {
+  const nested = JSON.parse(fs.readFileSync(sharedJsonPath, 'utf-8'));
+  const flat = flattenObject(nested);
+  plan('write', `content/en/shared.json (${Object.keys(flat).length} keys)`);
+  if (commit) {
+    fs.mkdirSync(enDir, { recursive: true });
+    fs.writeFileSync(path.join(enDir, 'shared.json'), sortedJson(flat));
+  }
+}
+
+// pages/*.json
+const pagesDir = path.join(configDir, 'pages');
+if (fs.existsSync(pagesDir)) {
+  for (const file of fs.readdirSync(pagesDir)) {
+    if (!file.endsWith('.json')) continue;
+    const nested = JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8'));
+    const flat = flattenObject(nested);
+    plan('write', `content/en/pages/${file} (${Object.keys(flat).length} keys)`);
+    if (commit) {
+      fs.mkdirSync(enPagesDir, { recursive: true });
+      fs.writeFileSync(path.join(enPagesDir, file), sortedJson(flat));
+    }
+  }
+}
+
+// 2. Split i18n flat files into locale directories
+const i18nDir = path.join(configDir, 'i18n');
+if (fs.existsSync(i18nDir)) {
+  // Read page filenames from config/pages/ to know valid page scopes
+  const pageFiles = fs.existsSync(pagesDir)
+    ? fs.readdirSync(pagesDir).filter((f) => f.endsWith('.json')).map((f) => f.replace('.json', ''))
+    : [];
+
+  for (const file of fs.readdirSync(i18nDir)) {
+    if (!file.endsWith('.json')) continue;
+    const locale = file.replace('.json', '');
+    const localeDir = path.join(contentDir, locale);
+    const localePagesDir = path.join(localeDir, 'pages');
+
+    const raw = JSON.parse(fs.readFileSync(path.join(i18nDir, file), 'utf-8'));
+
+    // Buckets: site.*, shared.*, pages.{pageId}.*
+    const siteBucket = {};
+    const sharedBucket = {};
+    const pageBuckets = {};
+
+    for (const [key, value] of Object.entries(raw)) {
+      if (key.startsWith('$')) continue;
+
+      if (key.startsWith('site.')) {
+        siteBucket[key.slice('site.'.length)] = value;
+      } else if (key.startsWith('shared.')) {
+        sharedBucket[key.slice('shared.'.length)] = value;
+      } else if (key.startsWith('pages.')) {
+        const rest = key.slice('pages.'.length);
+        const dotIdx = rest.indexOf('.');
+        if (dotIdx === -1) continue;
+        const pageId = rest.slice(0, dotIdx);
+        const pageKey = rest.slice(dotIdx + 1);
+        if (!pageBuckets[pageId]) pageBuckets[pageId] = {};
+        pageBuckets[pageId][pageKey] = value;
+      }
+    }
+
+    if (Object.keys(siteBucket).length > 0) {
+      plan('write', `content/${locale}/site.json (${Object.keys(siteBucket).length} keys)`);
+      if (commit) {
+        fs.mkdirSync(localeDir, { recursive: true });
+        fs.writeFileSync(path.join(localeDir, 'site.json'), sortedJson(siteBucket));
+      }
+    }
+
+    if (Object.keys(sharedBucket).length > 0) {
+      plan('write', `content/${locale}/shared.json (${Object.keys(sharedBucket).length} keys)`);
+      if (commit) {
+        fs.mkdirSync(localeDir, { recursive: true });
+        fs.writeFileSync(path.join(localeDir, 'shared.json'), sortedJson(sharedBucket));
+      }
+    }
+
+    for (const [pageId, pageData] of Object.entries(pageBuckets)) {
+      if (Object.keys(pageData).length === 0) continue;
+      plan('write', `content/${locale}/pages/${pageId}.json (${Object.keys(pageData).length} keys)`);
+      if (commit) {
+        fs.mkdirSync(localePagesDir, { recursive: true });
+        fs.writeFileSync(path.join(localePagesDir, `${pageId}.json`), sortedJson(pageData));
+      }
+    }
+  }
+}
+
+// 3. Create content.config.json
+plan('write', 'content/content.config.json');
+if (commit) {
+  fs.mkdirSync(contentDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(contentDir, 'content.config.json'),
+    JSON.stringify({ baseLocale: 'en' }, null, 2) + '\n'
+  );
+}
+
+// 4. Remove old config directory
+if (commit) {
+  fs.rmSync(configDir, { recursive: true, force: true });
+  plan('remove', 'config/ directory');
+} else {
+  plan('remove', 'config/ directory (would be removed)');
+}
+
+console.log(`\n${commit ? 'Migration complete' : 'Dry run complete'}. ${actions.length} actions.`);
+if (!commit) {
+  console.log('Run with --commit to apply changes.');
+}

package/src/components/Header.vue

@@ -85,14 +85,14 @@ import { computed, inject, nextTick, onBeforeUnmount, onMounted, ref, watch } fr
   import { resolveAsset } from '../utils/assetResolver.js';
 import { trackEvent } from '../utils/analytics.js';
 import { getExtensionComponent } from '../extensions/extensionLoader.js';
-import SUPPORTED_LOCALES from '../constants/locales.js';
+import { availableLocales as siteLocales } from '../utils/loadConfig.js';
 
   const logoSrc = computed(() => resolveAsset('img/logo.png'));
 
 const isLangOpen = ref(false);
 const isHeaderCompact = ref(false);
 const currentLocale = ref('');
-const availableLocales = computed(() => SUPPORTED_LOCALES.map((code) => code.trim()).filter(Boolean));
+const availableLocales = computed(() => siteLocales.map((code) => code.trim()).filter(Boolean));
 const localeLabels = {
   en: 'English',
   fr: 'Français',

package/src/main.js

@@ -39,12 +39,26 @@ const extractThemeKey = (siteData) => {
   return '';
 };
 
-const applySiteTheme = (themeKey) => {
-  if (typeof document === 'undefined') return;
+const applySiteTheme = (themeKey, head) => {
   const normalized = normalizeThemeKey(themeKey);
   const resolved = normalized || 'base';
-  document.documentElement.dataset.siteTheme = resolved;
-  applyThemeVariables(resolved);
+
+  // Push the html attribute via @unhead so `data-site-theme="X"` lands
+  // in the SSR-rendered HTML *before* Vue hydrates. Theme CSS selectors
+  // (`:root[data-site-theme="X"]`) then apply during the very first
+  // paint, eliminating the need for site-side critical-CSS overrides.
+  if (head && typeof head.push === 'function') {
+    head.push({ htmlAttrs: { 'data-site-theme': resolved } });
+  }
+
+  // Client only: also set the attribute imperatively (so runtime theme
+  // switching is reflected immediately) and inline the CSS variable map
+  // for themes that ship JS-only design tokens (e.g. the bundled `base`
+  // theme has no theme.css).
+  if (typeof document !== 'undefined') {
+    document.documentElement.dataset.siteTheme = resolved;
+    applyThemeVariables(resolved);
+  }
 };
 
 export function createCmsApp() {
@@ -74,9 +88,7 @@ export function createCmsApp() {
 
       if (initialState.siteTheme) {
         setActiveThemeKey(initialState.siteTheme);
-        if (typeof document !== 'undefined') {
-          applySiteTheme(initialState.siteTheme);
-        }
+        applySiteTheme(initialState.siteTheme, ctx.head);
       }
 
       applyRouterGuards(router);
@@ -130,7 +142,7 @@ export function createCmsApp() {
             initialState.siteTheme ?? normalizeThemeKey(extractThemeKey(initialState.siteConfig));
           initialState.siteTheme = existingTheme;
           setActiveThemeKey(existingTheme);
-          applySiteTheme(existingTheme);
+          applySiteTheme(existingTheme, ctx.head);
           return initialState.siteConfig;
         }
 
@@ -140,7 +152,7 @@ export function createCmsApp() {
         initialState.siteConfigLocale = localeKey;
         initialState.siteTheme = themeKey;
         setActiveThemeKey(themeKey);
-        applySiteTheme(themeKey);
+        applySiteTheme(themeKey, ctx.head);
         return siteData;
       };
 

package/src/themes/buildCssVarMap.js

@@ -0,0 +1,246 @@
+// Pure CSS-variable derivation from a theme manifest. Lives in its own
+// file (with no Vite-specific imports) so it can be called from both
+// the runtime themeManager AND the build-time vite plugin, which uses
+// it to emit `virtual:cms-theme-vars.css` — a synchronously-linked
+// stylesheet containing every registered theme's tokens. That, combined
+// with the SSR-rendered `data-site-theme` attribute (see main.js
+// applySiteTheme), eliminates the FOUC dark-themed sites used to suffer.
+
+const toKebab = (value = '') =>
+  value
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+
+const withPx = (value) => {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'number') return `${value}px`;
+  return value;
+};
+
+const setVar = (vars, name, value) => {
+  if (value === undefined || value === null || value === '') return;
+  vars[name] = String(value);
+};
+
+const assignPrefixed = (vars, entries = {}, prefix = '') => {
+  Object.entries(entries).forEach(([key, value]) => {
+    setVar(vars, `${prefix}${key}`, value);
+  });
+};
+
+function setSurfaceVars(vars, prefix, surface = {}) {
+  if (!surface) return;
+  setVar(vars, `${prefix}-bg`, surface.background);
+  setVar(vars, `${prefix}-before`, surface.before);
+  setVar(vars, `${prefix}-after`, surface.after);
+}
+
+function coerceSurface(value, defaults = {}) {
+  if (value && typeof value === 'object') return value;
+  if (!value) return defaults;
+  return { ...defaults, background: value };
+}
+
+function coerceArray(value) {
+  if (!value) return undefined;
+  return Array.isArray(value) ? value.filter(Boolean).join(', ') : value;
+}
+
+export function buildCssVarMap(manifest) {
+  if (!manifest) return {};
+  const vars = {};
+  const tokens = manifest.tokens || {};
+  const palette = tokens.palette || {};
+  const text = tokens.text || {};
+  const surfaces = tokens.surfaces || {};
+  const helper = surfaces.helper || {};
+  const tabs = surfaces.tabs || {};
+  const field = surfaces.field || {};
+  const strip = surfaces.strip || {};
+  const chrome = surfaces.chrome || {};
+  const heroSurface = surfaces.backdropPrimary || {};
+  const promoSurface = surfaces.backdropSecondary || {};
+  const typography = tokens.typography || {};
+  const ctas = tokens.ctas || {};
+  const chips = tokens.chips || {};
+  const focus = tokens.focus || {};
+  const radii = tokens.radii || {};
+  const elevation = tokens.elevation || {};
+  const utility = tokens.utility || {};
+
+  assignPrefixed(
+    vars,
+    Object.fromEntries(
+      Object.entries(palette).map(([key, value]) => [`--brand-${toKebab(key)}`, value])
+    )
+  );
+
+  setVar(vars, '--brand-accent-electric', palette.primary || palette.accent);
+  setVar(vars, '--brand-accent-electric-soft', palette.accentSoft);
+  setVar(vars, '--brand-accent-warm', palette.accent || palette.warning);
+
+  setVar(vars, '--brand-fg-100', text.primary);
+  setVar(vars, '--brand-fg-200', text.muted);
+  setVar(vars, '--brand-fg-300', text.mutedStrong);
+  setVar(vars, '--brand-fg-050', text.inverse);
+  setVar(vars, '--brand-bg-900', surfaces.base);
+  setVar(vars, '--brand-bg-800', surfaces.baseAlt);
+  setVar(vars, '--brand-bg-700', surfaces.raised);
+  setVar(vars, '--brand-bg-600', surfaces.sunken);
+
+  Object.entries(radii).forEach(([key, value]) => {
+    setVar(vars, `--brand-radius-${toKebab(key)}`, withPx(value));
+  });
+  setVar(vars, '--brand-card-radius', withPx(radii.lg || radii.md));
+  setVar(vars, '--brand-button-radius', withPx(radii.md || radii.sm));
+
+  setVar(vars, '--brand-shadow-glow', elevation.raised);
+  setVar(vars, '--brand-shadow-glow-strong', elevation.overlay);
+  setVar(vars, '--brand-card-shadow', elevation.raised);
+  setVar(vars, '--brand-surface-card-shadow', elevation.raised);
+
+  const cardTextColor = text.card || text.primary;
+  setVar(vars, '--brand-card-soft', surfaces.card);
+  setVar(vars, '--brand-surface-card-bg', surfaces.card);
+  setVar(vars, '--brand-card-border', surfaces.border);
+  setVar(vars, '--brand-surface-card-border', surfaces.border);
+  setVar(vars, '--brand-card-text', cardTextColor);
+  setVar(vars, '--brand-surface-helper-bg', helper.background || surfaces.callout);
+  setVar(vars, '--brand-surface-helper-hover-bg', helper.hover || helper.background);
+  setVar(vars, '--brand-icon-badge-bg', surfaces.chipAccent || surfaces.chip);
+  setVar(vars, '--brand-icon-badge-color', palette.primary || text.primary);
+
+  setVar(vars, '--brand-border-highlight', surfaces.border);
+  setVar(vars, '--brand-border-glow', surfaces.border);
+
+  setVar(vars, '--brand-status-success', palette.success);
+  setVar(vars, '--brand-status-error', palette.critical);
+  setVar(vars, '--brand-status-error-soft', palette.criticalSoft);
+
+  setVar(vars, '--brand-input-bg', field.background || surfaces.input);
+  setVar(vars, '--brand-input-border', field.border || utility.inputBorder);
+  setVar(vars, '--brand-input-border-active', focus.ring);
+  setVar(vars, '--brand-input-text', field.inputColor || utility.inputText || text.primary);
+  setVar(
+    vars,
+    '--brand-input-placeholder',
+    field.inputPlaceholder || utility.inputPlaceholder || text.muted
+  );
+  setVar(vars, '--brand-focus-ring', focus.ring);
+  setVar(vars, '--brand-focus-glow', focus.shadowInset);
+
+  setVar(vars, '--brand-modal-backdrop', surfaces.backdrop);
+  setVar(vars, '--brand-modal-surface', utility.modalSurface);
+  setVar(vars, '--brand-modal-border', utility.modalBorder);
+  setVar(vars, '--brand-modal-shadow', utility.modalShadow);
+  setVar(vars, '--brand-modal-radius', withPx(utility.modalRadius));
+
+  setVar(vars, '--brand-chart-track', utility.chartTrack);
+  setVar(vars, '--brand-chart-center-text', utility.chartCenterText);
+
+  setVar(vars, '--brand-header-bg', chrome.background);
+  setVar(vars, '--brand-header-text', chrome.text);
+  setVar(vars, '--site-header-shadow', chrome.shadow);
+  setVar(vars, '--site-header-shadow-compact', chrome.compactShadow);
+
+  const primaryCta = ctas.primary || {};
+  setVar(vars, '--brand-primary-cta-gradient', primaryCta.bg);
+  setVar(vars, '--brand-primary-cta-text', primaryCta.text);
+  setVar(vars, '--brand-primary-cta-border', primaryCta.border);
+  setVar(vars, '--brand-primary-cta-shadow', primaryCta.shadow);
+  setVar(vars, '--brand-primary-cta-hover-shadow', primaryCta.shadow);
+  setVar(vars, '--brand-primary-cta-hover-translate', 'translateY(-1px)');
+  setVar(vars, '--brand-cta-text', primaryCta.text);
+
+  setVar(vars, '--helper-strip-bg', helper.background || surfaces.callout);
+  setVar(vars, '--helper-strip-border', helper.border || surfaces.border);
+  setVar(vars, '--helper-strip-color', helper.text || text.primary);
+  setVar(vars, '--helper-strip-hover-bg', helper.hover || helper.background);
+  setVar(vars, '--helper-strip-hover-color', helper.hoverColor || helper.text || text.primary);
+  setVar(vars, '--helper-strip-link-hover', helper.linkHover || palette.primary);
+  setVar(vars, '--helper-strip-heading-color', helper.heading || text.primary);
+  setVar(vars, '--helper-strip-body-color', helper.body || text.mutedStrong || text.muted);
+
+  setVar(vars, '--tabs-bg', tabs.background);
+  setVar(vars, '--tabs-border', tabs.border || surfaces.border);
+  setVar(vars, '--tabs-shadow', tabs.shadow || elevation.flat);
+  setVar(vars, '--tab-color', tabs.tabColor || text.muted);
+  setVar(vars, '--tab-active-bg', tabs.activeBackground || palette.primary);
+  setVar(vars, '--tab-active-color', tabs.activeColor || palette.inverse || '#fff');
+  setVar(vars, '--tab-active-shadow', tabs.activeShadow || elevation.raised);
+  setVar(vars, '--tab-step-bg', tabs.stepBackground || helper.background);
+  setVar(vars, '--tab-step-border', tabs.stepBorder || helper.border);
+  setVar(vars, '--tab-step-color', tabs.stepColor || palette.primary);
+  setVar(vars, '--tab-active-step-bg', tabs.activeStepBackground || palette.primary);
+  setVar(vars, '--tab-active-step-border', tabs.activeStepBorder || tabs.stepBorder);
+  setVar(vars, '--tab-active-step-color', tabs.activeStepColor || palette.inverse || '#fff');
+
+  setVar(vars, '--field-bg', field.background);
+  setVar(vars, '--field-border', field.border || utility.inputBorder);
+  setVar(vars, '--field-shadow', field.shadow || elevation.flat);
+  setVar(vars, '--field-addon-bg', field.addonBackground || helper.background);
+  setVar(vars, '--field-addon-border', field.addonBorder || helper.border);
+  setVar(vars, '--field-addon-color', field.addonColor || helper.text || text.primary);
+  setVar(vars, '--field-input-color', field.inputColor || text.primary);
+  setVar(vars, '--field-input-placeholder', field.inputPlaceholder || text.muted);
+
+  setVar(vars, '--community-strip-bg', strip.background || surfaces.card);
+  setVar(vars, '--community-strip-border', strip.border || surfaces.border);
+  setVar(vars, '--community-strip-color', strip.text || text.primary);
+
+  setVar(vars, '--ui-text-primary', text.primary);
+  setVar(vars, '--ui-text-muted', text.muted);
+  setVar(vars, '--ui-field-label', text.muted);
+  setVar(vars, '--ui-field-value', text.primary);
+  setVar(vars, '--ui-status-heading-color', text.accent || palette.primary);
+
+  setVar(vars, '--brand-countdown-digit', palette.primary);
+  setVar(vars, '--brand-countdown-label', text.muted);
+
+  const secondaryCta = ctas.secondary || {};
+  setVar(vars, '--brand-pill-gradient', primaryCta.bg);
+  setVar(vars, '--brand-pill-alt-gradient', secondaryCta.bg || primaryCta.bg);
+  setVar(vars, '--brand-pill-contrast', primaryCta.text);
+
+  setVar(vars, '--brand-chip-neutral-bg', chips.neutral?.bg);
+  setVar(vars, '--brand-chip-neutral-color', chips.neutral?.text);
+  setVar(vars, '--brand-chip-neutral-border', chips.neutral?.border);
+
+  const heroBg = coerceArray(utility.gradientHero || heroSurface.background);
+  const promoBg = coerceArray(utility.gradientPromo || promoSurface.background);
+  if (heroBg) setVar(vars, '--brand-gradient-hero', heroBg);
+  if (promoBg) setVar(vars, '--brand-gradient-promo', promoBg);
+
+  setSurfaceVars(vars, '--hero-surface', heroSurface);
+  setSurfaceVars(vars, '--promo-surface', promoSurface);
+  const bodyBackground = coerceArray(utility.bodyBackground);
+  if (bodyBackground) {
+    setVar(vars, '--theme-body-background', bodyBackground);
+  }
+
+  const statusHeadline = coerceSurface(utility.statusHeadline, {
+    color: palette.primary || text.primary,
+    shadow: elevation.raised,
+  });
+
+  setVar(vars, '--status-headline-bg', statusHeadline.background);
+  setVar(vars, '--status-headline-color', statusHeadline.color);
+  setVar(vars, '--status-headline-shadow', statusHeadline.shadow);
+
+  setVar(vars, '--status-price-value-color', palette.accent || palette.primary || text.primary);
+  setVar(vars, '--status-price-value-shadow', elevation.raised);
+
+  return vars;
+}
+
+/**
+ * Render the var map as a CSS rule body.
+ * @param {object} vars Map of CSS custom property name → value
+ */
+export function renderCssVarRule(selector, vars) {
+  const declarations = Object.entries(vars)
+    .map(([name, value]) => `  ${name}: ${value};`)
+    .join('\n');
+  return `${selector} {\n${declarations}\n}`;
+}

package/src/themes/themeLoader.js

@@ -71,6 +71,36 @@ if (!catalog.base) {
  * Called by the Vite plugin for each theme passed via the `themes` option.
  * Must be called before the first render (during app initialisation).
  *
+ * Two patterns for shipping theme CSS:
+ *
+ *   1. **Side-effect import (preferred).** The theme's `index.js` imports
+ *      its `theme.css` for side effects:
+ *
+ *        import manifest from './theme.config.js';
+ *        import './theme.css';
+ *        export default { manifest };
+ *
+ *      Vite bundles `theme.css` into the main entry chunk and emits a
+ *      synchronous `<link rel="stylesheet">` in `<head>`, so theme rules
+ *      apply during the initial paint. Combined with the SSR-rendered
+ *      `data-site-theme` attribute (set in `applySiteTheme`), this
+ *      eliminates the FOUC that JS-injected theme CSS used to cause.
+ *
+ *   2. **Inline string (legacy).** The theme's `index.js` imports the CSS
+ *      with `?inline` and exports it as a `css` string:
+ *
+ *        import manifest from './theme.config.js';
+ *        import css from './theme.css?inline';
+ *        export default { manifest, css };
+ *
+ *      The CSS is injected via a runtime `<style>` tag (handled below).
+ *      This works but applies after Vue hydrates, so dark themes will
+ *      flash a light first paint unless the site provides critical CSS.
+ *
+ * Existing themes (cms-theme-neon, -frog, -aurora, -southpark, -swamp)
+ * still use pattern 2 and are supported indefinitely; new themes should
+ * prefer pattern 1.
+ *
  * @param {object} themeModule - Default export from a @koehler8/cms-theme-* package
  *   Expected shape: { manifest, css? } or just the manifest object directly.
  */
@@ -85,7 +115,9 @@ export function registerTheme(themeModule) {
 
   addToCatalog(manifest, sourceId, undefined);
 
-  // If the theme package shipped inline CSS, inject it into the document head.
+  // Legacy pattern 2: theme shipped inline CSS, inject it into the document head.
+  // For pattern 1 themes, `cssContent` is undefined and this block is skipped —
+  // the CSS is already loaded via Vite's bundling.
   if (cssContent && typeof cssContent === 'string' && typeof document !== 'undefined') {
     const slug = normalizeSlug(manifest.slug);
     const existingStyle = document.getElementById(`theme-css-${slug}`);

package/src/themes/themeManager.js

@@ -1,232 +1,9 @@
 import { resolveThemeManifest } from './themeLoader.js';
+import { buildCssVarMap } from './buildCssVarMap.js';
 
-const toKebab = (value = '') =>
-  value
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .replace(/[\s_]+/g, '-')
-    .toLowerCase();
-
-const withPx = (value) => {
-  if (value === undefined || value === null) return undefined;
-  if (typeof value === 'number') return `${value}px`;
-  return value;
-};
-
-const setVar = (vars, name, value) => {
-  if (value === undefined || value === null || value === '') return;
-  vars[name] = String(value);
-};
-
-const assignPrefixed = (vars, entries = {}, prefix) => {
-  Object.entries(entries).forEach(([key, value]) => {
-    setVar(vars, `${prefix}${key}`, value);
-  });
-};
-
-function setSurfaceVars(vars, prefix, surface = {}) {
-  if (!surface) return;
-  setVar(vars, `${prefix}-bg`, surface.background);
-  setVar(vars, `${prefix}-before`, surface.before);
-  setVar(vars, `${prefix}-after`, surface.after);
-}
-
-function coerceSurface(value, defaults = {}) {
-  if (value && typeof value === 'object') return value;
-  if (!value) return defaults;
-  return { ...defaults, background: value };
-}
-
-function coerceArray(value) {
-  if (!value) return undefined;
-  return Array.isArray(value) ? value.filter(Boolean).join(', ') : value;
-}
-
-function buildCssVarMap(manifest) {
-  if (!manifest) return {};
-  const vars = {};
-  const tokens = manifest.tokens || {};
-  const palette = tokens.palette || {};
-  const text = tokens.text || {};
-  const surfaces = tokens.surfaces || {};
-  const helper = surfaces.helper || {};
-  const tabs = surfaces.tabs || {};
-  const field = surfaces.field || {};
-  const strip = surfaces.strip || {};
-  const chrome = surfaces.chrome || {};
-  const heroSurface = surfaces.backdropPrimary || {};
-  const promoSurface = surfaces.backdropSecondary || {};
-  const typography = tokens.typography || {};
-  const ctas = tokens.ctas || {};
-  const chips = tokens.chips || {};
-  const focus = tokens.focus || {};
-  const radii = tokens.radii || {};
-  const elevation = tokens.elevation || {};
-  const utility = tokens.utility || {};
-
-  assignPrefixed(
-    vars,
-    Object.fromEntries(
-      Object.entries(palette).map(([key, value]) => [`--brand-${toKebab(key)}`, value])
-    )
-  );
-
-  setVar(vars, '--brand-accent-electric', palette.primary || palette.accent);
-  setVar(vars, '--brand-accent-electric-soft', palette.accentSoft);
-  setVar(vars, '--brand-accent-warm', palette.accent || palette.warning);
-
-  setVar(vars, '--brand-fg-100', text.primary);
-  setVar(vars, '--brand-fg-200', text.muted);
-  setVar(vars, '--brand-fg-300', text.mutedStrong);
-  setVar(vars, '--brand-fg-050', text.inverse);
-  setVar(vars, '--brand-bg-900', surfaces.base);
-  setVar(vars, '--brand-bg-800', surfaces.baseAlt);
-  setVar(vars, '--brand-bg-700', surfaces.raised);
-  setVar(vars, '--brand-bg-600', surfaces.sunken);
-
-  Object.entries(radii).forEach(([key, value]) => {
-    setVar(vars, `--brand-radius-${toKebab(key)}`, withPx(value));
-  });
-  setVar(vars, '--brand-card-radius', withPx(radii.lg || radii.md));
-  setVar(vars, '--brand-button-radius', withPx(radii.md || radii.sm));
-
-  setVar(vars, '--brand-shadow-glow', elevation.raised);
-  setVar(vars, '--brand-shadow-glow-strong', elevation.overlay);
-  setVar(vars, '--brand-card-shadow', elevation.raised);
-  setVar(vars, '--brand-surface-card-shadow', elevation.raised);
-
-  const cardTextColor = text.card || text.primary;
-  setVar(vars, '--brand-card-soft', surfaces.card);
-  setVar(vars, '--brand-surface-card-bg', surfaces.card);
-  setVar(vars, '--brand-card-border', surfaces.border);
-  setVar(vars, '--brand-surface-card-border', surfaces.border);
-  setVar(vars, '--brand-card-text', cardTextColor);
-  setVar(vars, '--brand-surface-helper-bg', helper.background || surfaces.callout);
-  setVar(vars, '--brand-surface-helper-hover-bg', helper.hover || helper.background);
-  setVar(vars, '--brand-icon-badge-bg', surfaces.chipAccent || surfaces.chip);
-  setVar(vars, '--brand-icon-badge-color', palette.primary || text.primary);
-
-  setVar(vars, '--brand-border-highlight', surfaces.border);
-  setVar(vars, '--brand-border-glow', surfaces.border);
-
-  setVar(vars, '--brand-status-success', palette.success);
-  setVar(vars, '--brand-status-error', palette.critical);
-  setVar(vars, '--brand-status-error-soft', palette.criticalSoft);
-
-  setVar(vars, '--brand-input-bg', field.background || surfaces.input);
-  setVar(vars, '--brand-input-border', field.border || utility.inputBorder);
-  setVar(vars, '--brand-input-border-active', focus.ring);
-  setVar(vars, '--brand-input-text', field.inputColor || utility.inputText || text.primary);
-  setVar(
-    vars,
-    '--brand-input-placeholder',
-    field.inputPlaceholder || utility.inputPlaceholder || text.muted
-  );
-  setVar(vars, '--brand-focus-ring', focus.ring);
-  setVar(vars, '--brand-focus-glow', focus.shadowInset);
-
-  setVar(vars, '--brand-modal-backdrop', surfaces.backdrop);
-  setVar(vars, '--brand-modal-surface', utility.modalSurface);
-  setVar(vars, '--brand-modal-border', utility.modalBorder);
-  setVar(vars, '--brand-modal-shadow', utility.modalShadow);
-  setVar(vars, '--brand-modal-radius', withPx(utility.modalRadius));
-
-  setVar(vars, '--brand-chart-track', utility.chartTrack);
-  setVar(vars, '--brand-chart-center-text', utility.chartCenterText);
-
-  setVar(vars, '--brand-header-bg', chrome.background);
-  setVar(vars, '--brand-header-text', chrome.text);
-  setVar(vars, '--site-header-shadow', chrome.shadow);
-  setVar(vars, '--site-header-shadow-compact', chrome.compactShadow);
-
-  const primaryCta = ctas.primary || {};
-  setVar(vars, '--brand-primary-cta-gradient', primaryCta.bg);
-  setVar(vars, '--brand-primary-cta-text', primaryCta.text);
-  setVar(vars, '--brand-primary-cta-border', primaryCta.border);
-  setVar(vars, '--brand-primary-cta-shadow', primaryCta.shadow);
-  setVar(vars, '--brand-primary-cta-hover-shadow', primaryCta.shadow);
-  setVar(vars, '--brand-primary-cta-hover-translate', 'translateY(-1px)');
-  setVar(vars, '--brand-cta-text', primaryCta.text);
-
-  setVar(vars, '--helper-strip-bg', helper.background || surfaces.callout);
-  setVar(vars, '--helper-strip-border', helper.border || surfaces.border);
-  setVar(vars, '--helper-strip-color', helper.text || text.primary);
-  setVar(vars, '--helper-strip-hover-bg', helper.hover || helper.background);
-  setVar(vars, '--helper-strip-hover-color', helper.hoverColor || helper.text || text.primary);
-  setVar(vars, '--helper-strip-link-hover', helper.linkHover || palette.primary);
-  setVar(vars, '--helper-strip-heading-color', helper.heading || text.primary);
-  setVar(vars, '--helper-strip-body-color', helper.body || text.mutedStrong || text.muted);
-
-  setVar(vars, '--tabs-bg', tabs.background);
-  setVar(vars, '--tabs-border', tabs.border || surfaces.border);
-  setVar(vars, '--tabs-shadow', tabs.shadow || elevation.flat);
-  setVar(vars, '--tab-color', tabs.tabColor || text.muted);
-  setVar(vars, '--tab-active-bg', tabs.activeBackground || palette.primary);
-  setVar(vars, '--tab-active-color', tabs.activeColor || palette.inverse || '#fff');
-  setVar(vars, '--tab-active-shadow', tabs.activeShadow || elevation.raised);
-  setVar(vars, '--tab-step-bg', tabs.stepBackground || helper.background);
-  setVar(vars, '--tab-step-border', tabs.stepBorder || helper.border);
-  setVar(vars, '--tab-step-color', tabs.stepColor || palette.primary);
-  setVar(vars, '--tab-active-step-bg', tabs.activeStepBackground || palette.primary);
-  setVar(vars, '--tab-active-step-border', tabs.activeStepBorder || tabs.stepBorder);
-  setVar(vars, '--tab-active-step-color', tabs.activeStepColor || palette.inverse || '#fff');
-
-  setVar(vars, '--field-bg', field.background);
-  setVar(vars, '--field-border', field.border || utility.inputBorder);
-  setVar(vars, '--field-shadow', field.shadow || elevation.flat);
-  setVar(vars, '--field-addon-bg', field.addonBackground || helper.background);
-  setVar(vars, '--field-addon-border', field.addonBorder || helper.border);
-  setVar(vars, '--field-addon-color', field.addonColor || helper.text || text.primary);
-  setVar(vars, '--field-input-color', field.inputColor || text.primary);
-  setVar(vars, '--field-input-placeholder', field.inputPlaceholder || text.muted);
-
-  setVar(vars, '--community-strip-bg', strip.background || surfaces.card);
-  setVar(vars, '--community-strip-border', strip.border || surfaces.border);
-  setVar(vars, '--community-strip-color', strip.text || text.primary);
-
-  setVar(vars, '--ui-text-primary', text.primary);
-  setVar(vars, '--ui-text-muted', text.muted);
-  setVar(vars, '--ui-field-label', text.muted);
-  setVar(vars, '--ui-field-value', text.primary);
-  setVar(vars, '--ui-status-heading-color', text.accent || palette.primary);
-
-  setVar(vars, '--brand-countdown-digit', palette.primary);
-  setVar(vars, '--brand-countdown-label', text.muted);
-
-  const secondaryCta = ctas.secondary || {};
-  setVar(vars, '--brand-pill-gradient', primaryCta.bg);
-  setVar(vars, '--brand-pill-alt-gradient', secondaryCta.bg || primaryCta.bg);
-  setVar(vars, '--brand-pill-contrast', primaryCta.text);
-
-  setVar(vars, '--brand-chip-neutral-bg', chips.neutral?.bg);
-  setVar(vars, '--brand-chip-neutral-color', chips.neutral?.text);
-  setVar(vars, '--brand-chip-neutral-border', chips.neutral?.border);
-
-  const heroBg = coerceArray(utility.gradientHero || heroSurface.background);
-  const promoBg = coerceArray(utility.gradientPromo || promoSurface.background);
-  if (heroBg) setVar(vars, '--brand-gradient-hero', heroBg);
-  if (promoBg) setVar(vars, '--brand-gradient-promo', promoBg);
-
-  setSurfaceVars(vars, '--hero-surface', heroSurface);
-  setSurfaceVars(vars, '--promo-surface', promoSurface);
-  const bodyBackground = coerceArray(utility.bodyBackground);
-  if (bodyBackground) {
-    setVar(vars, '--theme-body-background', bodyBackground);
-  }
-
-  const statusHeadline = coerceSurface(utility.statusHeadline, {
-    color: palette.primary || text.primary,
-    shadow: elevation.raised,
-  });
-
-  setVar(vars, '--status-headline-bg', statusHeadline.background);
-  setVar(vars, '--status-headline-color', statusHeadline.color);
-  setVar(vars, '--status-headline-shadow', statusHeadline.shadow);
-
-  setVar(vars, '--status-price-value-color', palette.accent || palette.primary || text.primary);
-  setVar(vars, '--status-price-value-shadow', elevation.raised);
-
-  return vars;
-}
+// buildCssVarMap was extracted to its own pure module so the build-time
+// vite plugin can call it (to emit `virtual:cms-theme-vars.css`) without
+// pulling in this file's runtime-only imports.
 
 export function applyThemeVariables(themeKey) {
   const manifest = resolveThemeManifest(themeKey);

package/src/utils/loadConfig.js

@@ -133,44 +133,84 @@ export function mergeConfigTrees(target, source, options = {}) {
 export function createConfigLoader(allModules) {
     const toPlain = unwrapDefault;
 
-    // Find the site.json path and derive the config prefix (everything up to
-    // and including `/config/`) so subsequent lookups are scoped correctly.
-    function findSiteConfigPrefix() {
+    // Discover which locale directories exist in the content folder by
+    // extracting unique locale codes from the allModules glob keys.
+    function discoverAvailableLocales() {
+        const locales = new Set();
+        const re = /\/content\/([a-z]{2,3}(?:-[a-zA-Z]{2,4})?)\//;
+        for (const key of Object.keys(allModules)) {
+            const match = key.match(re);
+            if (match) locales.add(match[1].toLowerCase());
+        }
+        return Array.from(locales).sort();
+    }
+
+    const availableLocales = discoverAvailableLocales();
+
+    // Find the content root (path ending in `/content/`) and resolve the base
+    // locale from content.config.json.
+    function findContentRoot() {
         const keys = Object.keys(allModules);
-        const siteJsonKeys = keys.filter((key) => key.endsWith('/config/site.json'));
-        if (siteJsonKeys.length === 1) {
-            const key = siteJsonKeys[0];
-            return key.slice(0, key.length - 'site.json'.length);
+        const configKey = keys.find((key) => key.endsWith('/content/content.config.json'));
+        if (configKey) {
+            return configKey.slice(0, configKey.length - 'content.config.json'.length);
         }
         return null;
     }
 
-    async function assembleBaseConfig() {
-        const prefix = findSiteConfigPrefix();
-        if (!prefix) return null;
-
-        const siteLoader = allModules[`${prefix}site.json`];
-        if (!siteLoader) return null;
+    async function resolveBaseLocale(contentRoot) {
+        const configLoader = allModules[`${contentRoot}content.config.json`];
+        if (!configLoader) return 'en';
+        const config = toPlain(await configLoader());
+        return (config && config.baseLocale) || 'en';
+    }
 
-        const sharedLoader = allModules[`${prefix}shared.json`];
-        const [siteData, sharedData] = await Promise.all([
-            siteLoader().then(toPlain),
+    // Assemble a config from a locale directory: inflates flat-format files
+    // (site.json, shared.json, pages/*.json) and returns { site, shared, pages }.
+    // When require is true, returns null if site.json is missing (used for
+    // base config). When false, assembles whatever files exist (used for
+    // locale overrides that may only contain partial translations).
+    async function assembleSplitConfig(localePrefix, { require: requireSite = false } = {}) {
+        const siteLoader = allModules[`${localePrefix}site.json`];
+        if (!siteLoader && requireSite) return null;
+
+        const sharedLoader = allModules[`${localePrefix}shared.json`];
+        const [rawSite, rawShared] = await Promise.all([
+            siteLoader ? siteLoader().then(toPlain) : Promise.resolve({}),
             sharedLoader ? sharedLoader().then(toPlain) : Promise.resolve({}),
         ]);
+        const siteData = inflateFlatConfig(rawSite);
+        const sharedData = inflateFlatConfig(rawShared);
 
-        // Collect only the pages that belong to this site's config directory
-        const pagePrefix = `${prefix}pages/`;
+        const pagePrefix = `${localePrefix}pages/`;
         const pages = {};
         const pageLoads = [];
         for (const [path, loader] of Object.entries(allModules)) {
             if (path.startsWith(pagePrefix) && path.endsWith('.json')) {
                 const pageId = path.slice(pagePrefix.length, -5);
-                pageLoads.push(loader().then((mod) => { pages[pageId] = toPlain(mod); }));
+                pageLoads.push(
+                    loader().then((mod) => { pages[pageId] = inflateFlatConfig(toPlain(mod)); })
+                );
             }
         }
         await Promise.all(pageLoads);
 
-        return { site: siteData, shared: sharedData, pages, _configPrefix: prefix };
+        // Return null if no files were found at all for this locale
+        if (!siteLoader && !sharedLoader && Object.keys(pages).length === 0) return null;
+
+        return { site: siteData, shared: sharedData, pages };
+    }
+
+    async function assembleBaseConfig() {
+        const contentRoot = findContentRoot();
+        if (!contentRoot) return null;
+
+        const baseLocale = await resolveBaseLocale(contentRoot);
+        const basePrefix = `${contentRoot}${baseLocale}/`;
+        const config = await assembleSplitConfig(basePrefix, { require: true });
+        if (!config) return null;
+
+        return { ...config, _contentRoot: contentRoot, _baseLocale: baseLocale };
     }
 
     async function loadConfigData(options) {
@@ -202,22 +242,24 @@ export function createConfigLoader(allModules) {
 
         if (normalizedLocale === undefined) {
             const config = await getBaseConfig();
-            delete config._configPrefix;
+            delete config._contentRoot;
+            delete config._baseLocale;
             return config;
         }
 
         const baseConfig = await getBaseConfig();
 
         let mergedConfig = baseConfig;
-        // Find locale override scoped to the same config directory as the site
-        const configPrefix = baseConfig._configPrefix;
-        const localizedLoader = configPrefix
-            ? allModules[`${configPrefix}i18n/${normalizedLocale}.json`]
-            : undefined;
-        if (localizedLoader) {
-            const rawLocalized = toPlain(await localizedLoader());
-            const localizedConfig = inflateFlatConfig(rawLocalized);
-            mergedConfig = mergeConfigTrees(baseConfig, localizedConfig, { cloneTarget: true, skipEmpty: true });
+        const contentRoot = baseConfig._contentRoot;
+        const baseLocale = baseConfig._baseLocale;
+
+        // Only load locale overrides if the requested locale differs from the base
+        if (contentRoot && normalizedLocale !== baseLocale) {
+            const localePrefix = `${contentRoot}${normalizedLocale}/`;
+            const localeConfig = await assembleSplitConfig(localePrefix);
+            if (localeConfig) {
+                mergedConfig = mergeConfigTrees(baseConfig, localeConfig, { cloneTarget: true, skipEmpty: true });
+            }
         }
         if (mergedConfig && mergedConfig.pages && typeof mergedConfig.pages === 'object') {
             for (const page of Object.values(mergedConfig.pages)) {
@@ -247,11 +289,12 @@ export function createConfigLoader(allModules) {
                 });
             }
         }
-        delete mergedConfig._configPrefix;
+        delete mergedConfig._contentRoot;
+        delete mergedConfig._baseLocale;
         return mergedConfig;
     }
 
-    return { loadConfigData, mergeConfigTrees, cloneConfig };
+    return { loadConfigData, mergeConfigTrees, cloneConfig, availableLocales };
 }
 
 // ---- Runtime singleton ----
@@ -263,9 +306,14 @@ let _loadConfigData = async () => {
   throw new Error('[@koehler8/cms] loadConfigData() called before config loader was initialized');
 };
 
+let _availableLocales = [];
+
 export function setConfigLoader(instance) {
   if (!instance) return;
   _loadConfigData = instance.loadConfigData;
+  _availableLocales = instance.availableLocales || [];
 }
 
+export { _availableLocales as availableLocales };
+
 export const loadConfigData = (...args) => _loadConfigData(...args);

package/vite-plugin.js

@@ -8,28 +8,30 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+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';
 
 // ---- Helpers ----
 
-function loadSplitConfig(configDir) {
-  const sitePath = path.join(configDir, 'site.json');
+function loadSplitConfig(contentLocaleDir) {
+  const sitePath = path.join(contentLocaleDir, 'site.json');
   if (!fs.existsSync(sitePath)) return null;
 
-  const site = JSON.parse(fs.readFileSync(sitePath, 'utf-8'));
-  const sharedPath = path.join(configDir, 'shared.json');
-  const shared = fs.existsSync(sharedPath) ? JSON.parse(fs.readFileSync(sharedPath, 'utf-8')) : {};
+  const site = inflateFlatConfig(JSON.parse(fs.readFileSync(sitePath, 'utf-8')));
+  const sharedPath = path.join(contentLocaleDir, 'shared.json');
+  const shared = fs.existsSync(sharedPath) ? inflateFlatConfig(JSON.parse(fs.readFileSync(sharedPath, 'utf-8'))) : {};
 
-  const pagesDir = path.join(configDir, 'pages');
+  const pagesDir = path.join(contentLocaleDir, 'pages');
   const pages = {};
   if (fs.existsSync(pagesDir)) {
     for (const file of fs.readdirSync(pagesDir)) {
       if (!file.endsWith('.json')) continue;
       const pageId = file.replace('.json', '');
-      pages[pageId] = JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8'));
+      pages[pageId] = inflateFlatConfig(JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8')));
     }
   }
 
@@ -98,8 +100,13 @@ const __dirname = path.dirname(__filename);
 const VIRTUAL_CONFIG = 'virtual:cms-config-loader';
 const VIRTUAL_STYLES = 'virtual:cms-site-styles';
 const VIRTUAL_ASSETS = 'virtual:cms-asset-resolver';
+// Synthetic stylesheet built from each registered theme's manifest at build
+// time. Importing this from the generated entry causes Vite to emit a real
+// <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';
 
-const VIRTUAL_IDS = new Set([VIRTUAL_CONFIG, VIRTUAL_STYLES, VIRTUAL_ASSETS]);
+const VIRTUAL_IDS = new Set([VIRTUAL_CONFIG, VIRTUAL_STYLES, VIRTUAL_ASSETS, VIRTUAL_THEME_VARS]);
 
 // Entry file name (written to site repo root, gitignored, cleaned up in buildEnd)
 const ENTRY_FILENAME = '.cms-entry.js';
@@ -147,6 +154,7 @@ ${extImports}
 import * as __cmsConfig from '${VIRTUAL_CONFIG}';
 import * as __cmsStyles from '${VIRTUAL_STYLES}';
 import * as __cmsAssets from '${VIRTUAL_ASSETS}';
+import '${VIRTUAL_THEME_VARS}';
 
 setConfigLoader(__cmsConfig);
 setSiteStyleLoader(__cmsStyles);
@@ -356,7 +364,13 @@ export default function cmsPlugin(options = {}) {
       tempEntryPath = path.join(siteRoot, ENTRY_FILENAME);
 
       // Load site config at config-resolution time (needed for SSG routes + HTML injection)
-      const configDir = path.join(siteDir, 'config');
+      const contentDir = path.join(siteDir, 'content');
+      const contentConfigPath = path.join(contentDir, 'content.config.json');
+      const contentConfig = fs.existsSync(contentConfigPath)
+        ? JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'))
+        : {};
+      const 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}`);
@@ -472,18 +486,75 @@ export default function cmsPlugin(options = {}) {
       return null;
     },
 
-    load(id) {
+    async load(id) {
       if (!isResolvedVirtual(id)) return null;
       const virtualId = id.slice(1); // strip leading \0
 
+      if (virtualId === VIRTUAL_THEME_VARS) {
+        // Build a stylesheet by deriving CSS variables from each registered
+        // theme's manifest at build time. We resolve the theme package via
+        // the site's node_modules (createRequire from siteRoot) and import
+        // its pure manifest through the package's `./config` exports field
+        // (which points at theme.config.js — sidestepping any Vite-only
+        // imports the theme's index.js may have, e.g. `?inline` CSS or a
+        // side-effect `import './theme.css'`). The bundled `base` theme is
+        // always included so sites without a `themes` option still get a
+        // sync theme.
+        const { buildCssVarMap, renderCssVarRule } = await import(
+          './src/themes/buildCssVarMap.js'
+        );
+        const baseManifestModule = await import('./themes/base/theme.config.js');
+        const baseManifest = baseManifestModule.default || baseManifestModule;
+
+        const requireFromSite = createRequire(path.join(siteRoot, 'package.json'));
+
+        const blocks = [];
+        const seen = new Set();
+
+        const addManifest = (manifest, sourceLabel) => {
+          if (!manifest || typeof manifest !== 'object') return;
+          const slug = typeof manifest.slug === 'string' ? manifest.slug.trim().toLowerCase() : '';
+          if (!slug || seen.has(slug)) return;
+          seen.add(slug);
+          const vars = buildCssVarMap(manifest);
+          if (Object.keys(vars).length === 0) return;
+          const selector = `:root[data-site-theme="${slug}"]`;
+          blocks.push(`/* ${sourceLabel} */\n${renderCssVarRule(selector, vars)}`);
+        };
+
+        addManifest(baseManifest, '@koehler8/cms (base)');
+
+        for (const pkg of themePackages) {
+          let manifestPath;
+          try {
+            manifestPath = requireFromSite.resolve(`${pkg}/config`);
+          } catch (err) {
+            this.warn(`[cms-vite-plugin] Theme "${pkg}" does not expose a "./config" export pointing at theme.config.js; skipping. (${err.message})`);
+            continue;
+          }
+          let manifest;
+          try {
+            const mod = await import(pathToFileURL(manifestPath).href);
+            manifest = mod.default || mod.manifest || mod;
+          } catch (err) {
+            this.warn(`[cms-vite-plugin] Failed to load theme manifest from "${pkg}": ${err.message}`);
+            continue;
+          }
+          addManifest(manifest, pkg);
+        }
+
+        return blocks.join('\n\n') + '\n';
+      }
+
       if (virtualId === VIRTUAL_CONFIG) {
         return `
 import { createConfigLoader } from '@koehler8/cms/utils/loadConfig';
-const allModules = import.meta.glob('@cms-site/config/**/*.json');
+const allModules = import.meta.glob('@cms-site/content/**/*.json');
 const loader = createConfigLoader(allModules);
 export const loadConfigData = loader.loadConfigData;
 export const mergeConfigTrees = loader.mergeConfigTrees;
 export const cloneConfig = loader.cloneConfig;
+export const availableLocales = loader.availableLocales;
 `;
       }