@koehler8/cms 1.0.0-beta.29 → 1.0.0-beta.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.29",
+  "version": "1.0.0-beta.31",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -80,8 +80,8 @@
     "vue-router": "^5.0.0"
   },
   "dependencies": {
-    "@unhead/vue": "^2.0.19",
-    "ajv": "^8.17.1",
+    "@unhead/vue": "^2.1.15",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "canvas": "^3.2.0",
     "dotenv": "^17.2.3",
@@ -90,9 +90,11 @@
     "sharp": "^0.33.5"
   },
   "devDependencies": {
-    "@vue/test-utils": "^2.4.6",
-    "happy-dom": "^20.8.9",
-    "vitest": "^4.1.4"
+    "@vue/test-utils": "^2.4.10",
+    "happy-dom": "^20.9.0",
+    "vitest": "^4.1.6",
+    "vue": "^3.5.34",
+    "vue-router": "^5.0.7"
   },
   "engines": {
     "node": ">=20.19.0",

package/src/composables/usePageConfig.js

@@ -1,5 +1,5 @@
 import { onServerPrefetch, ref, watch } from 'vue';
-import { loadConfigData, mergeConfigTrees } from '../utils/loadConfig.js';
+import { loadConfigData, mergeConfigTrees, peekConfigSync } from '../utils/loadConfig.js';
 
 function normalizePath(value) {
   if (!value || typeof value !== 'string') return '/';
@@ -122,7 +122,39 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     return null;
   }
 
-  async function syncPage() {
+  // Synchronously apply a resolved config to the reactive refs. Kept pure and
+  // synchronous so it can run during the first client render (matching the
+  // prerendered DOM) as well as after an async load. Throws if the config has
+  // no selectable page, so callers can fall back.
+  function applyConfig(config) {
+    siteData.value = config;
+    const selectedPage = selectPage(config);
+
+    if (!selectedPage) {
+      throw new Error('No pages defined in configuration.');
+    }
+
+    const sharedContent = config?.shared?.content;
+    const mergedContent = mergeWithSharedContent(sharedContent, selectedPage.content);
+    currentPage.value = {
+      ...selectedPage,
+      content: mergedContent,
+    };
+    pageContent.value = mergedContent;
+
+    if (typeof onPageLoaded === 'function') {
+      onPageLoaded({ config, page: selectedPage, content: mergedContent });
+    }
+
+    componentKeys.value = Array.isArray(selectedPage.components)
+      ? selectedPage.components.map((entry) => (entry && typeof entry === 'object' ? { ...entry } : entry))
+      : [];
+  }
+
+  // soft: when true, keep the currently-rendered components visible while the
+  // new config loads (no blank-out). Used by the post-hydration locale
+  // reconcile so a saved-locale switch doesn't reintroduce a flash.
+  async function syncPage({ soft = false } = {}) {
     const requestId = ++activeRequest;
     const currentLocale = typeof locale === 'function' ? locale() : locale;
     const localeKey = (currentLocale || '').toString().toLowerCase() || 'default';
@@ -131,7 +163,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
 
     if (requestId === activeRequest) {
       isLoading.value = true;
-      if (shouldReload) {
+      if (shouldReload && !soft) {
         componentKeys.value = [];
       }
       loadError.value = null;
@@ -145,28 +177,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
 
       if (requestId !== activeRequest) return;
 
-      siteData.value = cachedConfig;
-      const selectedPage = selectPage(cachedConfig);
-
-      if (!selectedPage) {
-        throw new Error('No pages defined in configuration.');
-      }
-
-      const sharedContent = cachedConfig?.shared?.content;
-      const mergedContent = mergeWithSharedContent(sharedContent, selectedPage.content);
-      currentPage.value = {
-        ...selectedPage,
-        content: mergedContent,
-      };
-      pageContent.value = mergedContent;
-
-      if (typeof onPageLoaded === 'function') {
-        onPageLoaded({ config: cachedConfig, page: selectedPage, content: mergedContent });
-      }
-
-      componentKeys.value = Array.isArray(selectedPage.components)
-        ? selectedPage.components.map((entry) => (entry && typeof entry === 'object' ? { ...entry } : entry))
-        : [];
+      applyConfig(cachedConfig);
     } catch (error) {
       if (requestId !== activeRequest) return;
       if (import.meta.env.DEV) {
@@ -186,11 +197,53 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     }
   }
 
+  // Client-only: populate refs synchronously from the config the server pass
+  // already resolved + serialized (primed into a sync cache by main.js before
+  // mount). This makes the first client render reproduce the prerendered DOM
+  // instead of an empty <main> while the async loader runs — the fix for the
+  // paint -> blank -> paint white-flash. Returns false on a cache miss, so the
+  // caller falls back to the async path (previous behavior).
+  function hydrateFromSyncCache() {
+    const currentLocale = typeof locale === 'function' ? locale() : locale;
+    const localeKey = (currentLocale || '').toString().toLowerCase() || 'default';
+    const localeForConfig = localeKey === 'default' ? undefined : localeKey;
+
+    const primed = peekConfigSync(localeForConfig);
+    if (!primed) return false;
+
+    try {
+      applyConfig(primed);
+    } catch {
+      return false;
+    }
+    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.
+    if (localeForConfig === undefined && typeof localStorage !== 'undefined') {
+      let stored = '';
+      try {
+        stored = (localStorage.getItem('locale') || '').trim().toLowerCase();
+      } catch {
+        stored = '';
+      }
+      if (stored) {
+        lastLocaleKey = null; // force the reconcile to reload with localStorage resolution
+        syncPage({ soft: true });
+      }
+    }
+    return true;
+  }
+
   if (import.meta.env.SSR) {
     onServerPrefetch(async () => {
       await syncPage();
     });
-  } else {
+  } else if (!hydrateFromSyncCache()) {
     syncPage();
   }
 

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 } from './utils/loadConfig.js';
+import { loadConfigData, primeConfigSync } from './utils/loadConfig.js';
 import { persistAttributionFromLocation } from './utils/trackingContext.js';
 import { applyThemeVariables } from './themes/themeManager.js';
 import { setActiveThemeKey } from './utils/themeColors.js';
@@ -158,6 +158,10 @@ export function createCmsApp() {
           initialState.siteTheme = existingTheme;
           setActiveThemeKey(existingTheme);
           applySiteTheme(existingTheme, ctx.head);
+          // Expose the server-resolved config for the first synchronous client
+          // render (see usePageConfig.hydrateFromSyncCache) so the prerendered
+          // DOM isn't replaced by an empty render while the async loader runs.
+          primeConfigSync(localeKey, initialState.siteConfig);
           return initialState.siteConfig;
         }
 

package/src/utils/loadConfig.js

@@ -309,11 +309,43 @@ let _loadConfigData = async () => {
 let _availableLocales = [];
 let _baseLocale = '';
 
+// Synchronous, client-side cache of the config the SSR/SSG pass already
+// resolved. Warmed once before mount (see main.js, from the vite-ssg-
+// serialized `initialState.siteConfig`) so the first client render can
+// populate synchronously and match the prerendered DOM — eliminating the
+// paint -> blank -> paint flash caused by config arriving asynchronously via
+// lazy dynamic-import chunks. Keyed by normalized locale; SSR never reads it.
+const _syncConfigCache = new Map();
+
+function normalizeConfigCacheKey(locale) {
+  if (typeof locale === 'string') {
+    const trimmed = locale.trim().toLowerCase();
+    if (trimmed) return trimmed;
+  }
+  return 'default';
+}
+
 export function setConfigLoader(instance) {
   if (!instance) return;
   _loadConfigData = instance.loadConfigData;
   _availableLocales = instance.availableLocales || [];
   _baseLocale = typeof instance.baseLocale === 'string' ? instance.baseLocale : '';
+  _syncConfigCache.clear();
+}
+
+// Store a resolved config for synchronous retrieval during the first client
+// render. Pass the config exactly as the server resolved it (e.g. the
+// serialized `initialState.siteConfig`) so `peekConfigSync` returns a value
+// that matches the prerendered DOM.
+export function primeConfigSync(locale, config) {
+  if (!config || typeof config !== 'object') return;
+  _syncConfigCache.set(normalizeConfigCacheKey(locale), config);
+}
+
+// Retrieve a primed config synchronously, or null on a miss. Client-only fast
+// path used by usePageConfig; a miss falls back to the async loader.
+export function peekConfigSync(locale) {
+  return _syncConfigCache.get(normalizeConfigCacheKey(locale)) || null;
 }
 
 export { _availableLocales as availableLocales };

package/templates/scaffolds/site/.env.example

@@ -0,0 +1,4 @@
+VITE_TOKEN=__SLUG__
+VITE_REGISTRY_ADDRESS=
+VITE_RPC_READ=
+VITE_REOWN_PROJECT_ID=