@koehler8/cms 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 1.2.0
+
+### Added
+
+- **`initialStateTrims` — let a site prune the hydration payload it alone can
+  reason about.** `trimConfigToPage` reduces `config.pages` to the page being
+  prerendered, but it cannot touch `config.shared`: deciding which shared
+  content a given ROUTE needs requires the site's own notion of what that route
+  resolves to, which the framework has no access to.
+
+  That gap gets expensive for content-heavy sites. On a 767-page publication it
+  measured at 65.42 MB of `__INITIAL_STATE__` — **75.6% of all built HTML** —
+  because every page carried every item's body in every locale, while rendering
+  exactly one. With a hook registered: 11.01 MB (-83.2%), and gzipped HTML
+  23.22 MB -> 7.23 MB (-68.9%). Worst-hit locale pages dropped ~60-73% of their
+  wire weight.
+
+  A site registers a synchronous function through the new plugin option; the
+  framework calls it once per prerendered route, after the page trim, and
+  stamps `sharedPartial: true` if the hook changed anything. `usePageConfig`
+  treats that marker exactly like `pagesPartial`, so whatever the hook prunes
+  is restored by the post-hydration reload before it can be navigated to.
+
+  Registration happens at module-eval time in the generated entry, which is the
+  only seam that works: extension setups run on the client only and are
+  unreachable during SSG. Hooks that throw, return a non-object, or drop
+  `site` / `shared` / `pages` wholesale degrade to a no-op — framework
+  components on pages the hook never reasons about read those directly, and
+  losing one is a hydration mismatch on every page's chrome.
+
+  `sharedPartial` gets its own reload clause rather than riding on
+  `pagesPartial`, because `trimConfigToPage` only sets that flag when a route
+  resolves unambiguously to a page id while the site trim fires either way.
+
+  Purely additive. With no `initialStateTrims` configured the generated entry
+  is **byte-identical** — asserted directly in `tests/vite-plugin.spec.js`,
+  because every site installs this version from npm before opting in.
+
+- **`site.robots.extraSitemaps[]` — advertise a feed as a discovery surface.**
+  Google and Bing both accept an RSS/Atom feed as a sitemap format, so a
+  publication with a nightly-updating feed has a real second discovery channel
+  and no supported way to declare it. This appends one `Sitemap:` line per
+  entry after the primary, de-duplicated and trimmed.
+
+  It has to be a config option for exactly the reason `allowAiCrawlers` did:
+  `public/robots.txt` is regenerated from config on every build, so a site that
+  hand-edited an extra `Sitemap:` line had it silently reverted on the next
+  `build:ssg` — and silently, because nothing fails when a discovery hint
+  disappears. Skipped entirely when `site.draft === true`: a pre-launch site
+  emits `Disallow: /` and should not be advertising anything.
+
+  Purely additive. A site that does not set it produces a byte-identical
+  `robots.txt`.
+
+### Changed
+
+- **The partial-embed config reload now waits for idle.** `pagesPartial`
+  triggered `syncPage({ soft: true })` on the critical path of every page load,
+  solely so a later in-SPA navigation could resolve other pages — on one site,
+  eagerly fetching a 157 KB per-locale chunk at 1.375 pages/session, for a
+  navigation most visitors never make.
+
+  The two reload triggers are not equivalent and are no longer treated the
+  same. A saved-locale switch is user-visible — the reader is looking at the
+  wrong language until it resolves — and stays eager. A partial embed is not:
+  the page has already rendered identically from the embed. That one moves to
+  `requestIdleCallback` (with a timeout fallback for Safari before 16.4).
+
+  `lastLocaleKey` is still cleared eagerly, so a navigation that beats the idle
+  callback triggers the full load itself through the route watcher; the idle
+  pass then finds the config current and re-applies it harmlessly.
+
 ## 1.1.0
 
 ### Fixed

package/README.md

@@ -85,6 +85,64 @@ fails the build if any page comes out blank.)
 | `locales` | all 15 supported | Array of locale codes to enable |
 | `themes` | `[]` | Theme package names to register |
 | `extensions` | `[]` | Extension package names to register |
+| `initialStateTrims` | `[]` | Module paths exporting a hydration-payload trim hook (see below) |
+
+## Hydration payload
+
+Each prerendered page embeds the config it needs as `window.__INITIAL_STATE__`
+so the first client render reproduces the prerendered DOM instead of blanking
+while the async loader runs. On a content-heavy site that blob can dominate
+page weight, so there are two levers.
+
+### `site.trimInitialState` (default: on)
+
+Embeds only the current page's entry from `config.pages` rather than every
+page's, and marks the result `pagesPartial`. After hydration the full config is
+fetched once in the background — deferred to `requestIdleCallback`, since the
+current page has already rendered identically and the full config only matters
+once the reader navigates.
+
+Set it to `false` to embed the whole config. That flag is the single, complete
+rollback for everything in this section.
+
+### `initialStateTrims`
+
+`trimConfigToPage` handles `config.pages`. It cannot touch `config.shared`,
+because knowing which shared content a *route* needs requires the site's own
+notion of what that route resolves to. A site closes that gap with a hook:
+
+```js
+// vite.config.js
+cms({ initialStateTrims: ['./site/components/payloadTrim.js'] })
+```
+
+```js
+// site/components/payloadTrim.js
+export default function payloadTrim(config, { routePath, locale, pageId }) {
+  if (!needsTrimming(config)) return config;   // same reference === no-op
+  return { ...config, shared: prune(config.shared, routePath) };
+}
+```
+
+The hook must be **synchronous and pure** — it runs once per prerendered route,
+which is thousands of times per build. Return the config unchanged (the same
+reference) to no-op; anything that is not a plain object is ignored.
+
+The framework stamps `sharedPartial: true` when a hook actually changes
+something, so a hook cannot forget the marker and ship a payload that is
+permanently short with nothing to repair it. That marker triggers the same
+post-hydration reload as `pagesPartial`, so anything pruned is restored before
+it can be navigated to.
+
+**Never drop `site`, `shared` or `pages` wholesale.** Framework components on
+pages your hook never reasons about read them directly (`useIntroGate`,
+`FooterMinimal`, `ComingSoon`, `NotFound`, `Header`), and a first client render
+without them is a hydration mismatch on every page's chrome. Returns that do
+so are discarded, as are hooks that throw.
+
+Measured on a 767-page publication whose per-locale item bodies lived in
+`shared.json`: payload 65.42 MB → 11.01 MB (−83.2%), gzipped HTML 23.22 MB →
+7.23 MB (−68.9%).
 
 ## Site Configuration
 

package/package.json

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

package/src/composables/usePageConfig.js

@@ -13,6 +13,19 @@ function normalizePath(value) {
   return normalized || '/';
 }
 
+// Run a callback when the browser is next idle, falling back to a timeout on
+// engines without requestIdleCallback (Safari before 16.4). Used to move the
+// background config reload off the critical path — see hydrateFromSyncCache.
+function whenIdle(fn, timeout = 4000) {
+  if (typeof window === 'undefined') return () => {};
+  if (typeof window.requestIdleCallback === 'function') {
+    const handle = window.requestIdleCallback(fn, { timeout });
+    return () => window.cancelIdleCallback?.(handle);
+  }
+  const handle = setTimeout(fn, 1);
+  return () => clearTimeout(handle);
+}
+
 function mergeWithSharedContent(sharedContent, pageSpecificContent) {
   const base = sharedContent && typeof sharedContent === 'object' ? sharedContent : {};
   const overrides = pageSpecificContent && typeof pageSpecificContent === 'object' ? pageSpecificContent : {};
@@ -37,6 +50,8 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
   let cachedConfig = null;
   let lastLocaleKey = null;
   let activeRequest = 0;
+  // Cancels a pending idle-scheduled background reload (see hydrateFromSyncCache).
+  let cancelIdleReload = () => {};
 
   function selectPage(config) {
     const pages = config?.pages || {};
@@ -241,16 +256,43 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     //     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);
-
+    // `sharedPartial` is the site-trim marker (see utils/initialStateTrim.js).
+    // It needs the same reload and must be checked independently: a route whose
+    // page id is ambiguous gets no `pagesPartial` at all, so relying on that
+    // flag alone would leave a shared-trimmed payload permanently short with
+    // nothing to repair it.
+    let needsFullReload = Boolean(primed && (primed.pagesPartial || primed.sharedPartial));
+
+    // Only trigger (2) is user-visible: until it resolves the reader is looking
+    // at the WRONG LOCALE. Trigger (1) is not — the current page has already
+    // rendered identically from the partial embed, and the full config only
+    // matters once the reader navigates. So (2) stays eager and (1) waits for
+    // idle. That distinction is the whole point: on a site whose visitors read
+    // one page and leave, the partial-embed reload was fetching a large
+    // per-locale chunk on the critical path for a navigation most of them never
+    // make.
+    let reloadIsUrgent = false;
     if (localeForConfig === undefined) {
       const stored = (readStoredLocale() || '').trim().toLowerCase();
-      if (stored) needsFullReload = true;
+      if (stored) {
+        needsFullReload = true;
+        reloadIsUrgent = true;
+      }
     }
 
     if (needsFullReload) {
-      lastLocaleKey = null; // force syncPage to reload (localStorage-resolved for base routes)
-      syncPage({ soft: true });
+      // Set eagerly, NOT inside the idle callback. syncPage() reloads only when
+      // `!cachedConfig || lastLocaleKey !== localeKey`, and hydrateFromSyncCache
+      // just set both from the partial embed. Clearing the key here means an
+      // in-SPA navigation that beats the idle callback triggers the full load
+      // itself through the route watcher; the idle pass then finds the config
+      // already current and re-applies it harmlessly.
+      lastLocaleKey = null;
+      if (reloadIsUrgent) {
+        syncPage({ soft: true });
+      } else {
+        cancelIdleReload = whenIdle(() => { syncPage({ soft: true }); });
+      }
     }
     return true;
   }
@@ -269,7 +311,14 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
 
   watch(
     () => [getPageId(), getPagePath(), getLocale()],
-    () => { syncPage(); },
+    () => {
+      // A navigation supersedes any idle-scheduled reload: syncPage below does
+      // the full load itself, because hydrateFromSyncCache already cleared
+      // lastLocaleKey.
+      cancelIdleReload();
+      cancelIdleReload = () => {};
+      syncPage();
+    },
   );
 
   return {

package/src/main.js

@@ -7,6 +7,7 @@ import { routes, resolveHistory, applyRouterGuards } from './router/index.js';
 
 import { shouldEnableAnalytics, scheduleAnalyticsLoad, configureAnalyticsConsentMode } from './utils/cookieConsent.js';
 import { loadConfigData, primeConfigSync, trimConfigToPage, resolvePageIdForRoute } from './utils/loadConfig.js';
+import { applyInitialStateTrims } from './utils/initialStateTrim.js';
 import { persistAttributionFromLocation } from './utils/trackingContext.js';
 import { applyThemeVariables } from './themes/themeManager.js';
 import { setActiveThemeKey } from './utils/themeColors.js';
@@ -165,10 +166,10 @@ export function createCmsApp() {
       // 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);
+      const resolveCurrentPageId = (config, route) => {
+        const resolved = route === undefined ? extractCurrentRoute() : route;
+        const rawPath = typeof resolved?.path === 'string' ? resolved.path : '';
+        const localeParam = pickLocaleParam(resolved?.params?.locale);
         return resolvePageIdForRoute(config, rawPath, localeParam);
       };
 
@@ -216,10 +217,24 @@ export function createCmsApp() {
           // Safety valve: an ambiguous route→page match returns null and the
           // full config is embedded (a no-op, never a broken page).
           if (initialState.siteConfig?.site?.trimInitialState !== false) {
-            const currentPageId = resolveCurrentPageId(initialState.siteConfig);
+            const currentRoute = extractCurrentRoute();
+            const currentPageId = resolveCurrentPageId(initialState.siteConfig, currentRoute);
             if (currentPageId) {
               initialState.siteConfig = trimConfigToPage(initialState.siteConfig, currentPageId);
             }
+            // Then let the site prune `shared` — the half trimConfigToPage
+            // cannot reason about, because only the site knows what a route
+            // resolves to. Stamps `sharedPartial: true` iff a hook actually
+            // changed something; usePageConfig treats that exactly like
+            // `pagesPartial` and reloads the full config after hydration.
+            // Gated on the same trimInitialState flag so that one setting stays
+            // a single, complete rollback for the whole payload optimisation.
+            initialState.siteConfig = applyInitialStateTrims(initialState.siteConfig, {
+              route: currentRoute || null,
+              routePath: typeof currentRoute?.path === 'string' ? currentRoute.path : '',
+              locale: pickLocaleParam(currentRoute?.params?.locale),
+              pageId: currentPageId,
+            });
           }
         } catch (error) {
           console.error('Failed to load site configuration during SSG build', error);

package/src/utils/initialStateTrim.js

@@ -0,0 +1,94 @@
+// Site-supplied trimming of the serialized hydration payload.
+//
+// `trimConfigToPage` (utils/loadConfig.js) prunes `config.pages` to the page
+// being prerendered. It cannot touch `config.shared`, because deciding which
+// parts of shared content a given ROUTE needs requires knowledge the framework
+// does not have — a site's own notion of what a route resolves to.
+//
+// That gap is expensive for content-heavy sites. On one 737-page site, shared
+// content accounted for 61% of ALL built HTML bytes: every page carried every
+// item's body, in every locale, so a single story page shipped fifty times the
+// prose it rendered.
+//
+// A site registers a function here; the framework calls it once per prerendered
+// route, after the page trim, and stamps `sharedPartial: true` when the hook
+// actually changed something. usePageConfig treats that marker exactly like
+// `pagesPartial` — a background reload of the full config after hydration — so
+// anything the hook prunes is restored before it can be navigated to.
+//
+// Contract for hook authors:
+//   * SYNCHRONOUS and pure. This runs once per route (hundreds to thousands of
+//     times per build, per shard); an async hook that does I/O multiplies build
+//     time by the route count.
+//   * Return the config UNCHANGED (same reference) to no-op. Anything that is
+//     not a plain object is ignored.
+//   * Never drop `site`, `shared` or `pages` wholesale. Framework components on
+//     pages your hook never reasons about read those directly (useIntroGate,
+//     FooterMinimal, ComingSoon, NotFound, Header), and a first client render
+//     without them is a hydration mismatch on every page's chrome.
+//
+// The framework stamps the marker rather than the site, so a hook cannot forget
+// it and ship a payload that is permanently short with nothing to repair it.
+
+const hooks = [];
+
+/**
+ * Register a trim hook. Called at module-eval time from the generated entry
+ * (see vite-plugin.js `initialStateTrims`), which is what makes this reachable
+ * during SSG — extension setups run only on the client.
+ *
+ * @param {(config: object, context: {routePath: string, locale: string|undefined, pageId: string|null, route: object|null}) => object} fn
+ */
+export function registerInitialStateTrim(fn) {
+  if (typeof fn === 'function') hooks.push(fn);
+}
+
+/** Test helper — drops every registered hook. */
+export function clearInitialStateTrims() {
+  hooks.length = 0;
+}
+
+/** Test helper — how many hooks are registered. */
+export function initialStateTrimCount() {
+  return hooks.length;
+}
+
+/**
+ * Run every registered hook in registration order, threading the config
+ * through. Returns the ORIGINAL reference when nothing changed, so the caller
+ * can distinguish "trimmed" from "no-op" without the hook having to say so.
+ */
+export function applyInitialStateTrims(config, context) {
+  if (!hooks.length) return config;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return config;
+
+  let current = config;
+  let changed = false;
+
+  for (const fn of hooks) {
+    let next;
+    try {
+      next = fn(current, context);
+    } catch (error) {
+      // A payload optimisation failing is not a page failing. Deliberately NOT
+      // the '[cms-ssg] PAGE CONFIG LOAD FAILED' marker the build greps for.
+      console.warn('[@koehler8/cms] an initialStateTrim hook threw; skipping it', error);
+      continue;
+    }
+
+    if (!next || typeof next !== 'object' || Array.isArray(next)) continue;  // ignored
+    if (next === current) continue;                                          // explicit no-op
+
+    // Blast-radius guard: a hook must not be able to blank the config for a
+    // whole build. Losing any of these three is a hydration mismatch on chrome
+    // that appears on every page.
+    if (current.site && !next.site) continue;
+    if (current.shared && !next.shared) continue;
+    if (current.pages && !next.pages) continue;
+
+    current = next;
+    changed = true;
+  }
+
+  return changed ? { ...current, sharedPartial: true } : config;
+}

package/src/utils/robotsGenerator.js

@@ -32,6 +32,17 @@
  * pre-launch site shouldn't explicitly invite crawlers.
  *
  * If sitemapUrl is provided, appends a "Sitemap: <url>" line.
+ *
+ * site.robots.extraSitemaps (opt-in, default none): appends one additional
+ * "Sitemap:" line per entry, after the primary. Google and Bing both accept an
+ * RSS/Atom feed as a sitemap format, so a publication with a nightly-updating
+ * feed can advertise it as a discovery surface alongside sitemap.xml. This has
+ * to be a config option for the same reason allowAiCrawlers does: public/
+ * robots.txt is regenerated on every build, so hand edits are silently
+ * reverted on the next build:ssg. Entries are de-duplicated against each other
+ * and against the primary sitemap, trimmed, and — like allowAiCrawlers —
+ * skipped entirely when site.draft === true, since a pre-launch site should not
+ * be advertising discovery surfaces at all.
  */
 
 // No framework-default disallows: every framework route is either public
@@ -86,9 +97,23 @@ export function buildRobotsTxt(siteConfig, sitemapUrl = '') {
   }
 
   const trimmedSitemap = (sitemapUrl || '').trim();
-  if (trimmedSitemap) {
+  const sitemaps = [];
+  if (trimmedSitemap) sitemaps.push(trimmedSitemap);
+
+  if (site.draft !== true) {
+    const extras = Array.isArray(site.robots?.extraSitemaps) ? site.robots.extraSitemaps : [];
+    for (const entry of extras) {
+      if (typeof entry !== 'string') continue;
+      const url = entry.trim();
+      // A duplicate line is not an error to a crawler, but it reads as a
+      // config bug to anyone opening the file.
+      if (url && !sitemaps.includes(url)) sitemaps.push(url);
+    }
+  }
+
+  if (sitemaps.length) {
     lines.push('');
-    lines.push(`Sitemap: ${trimmedSitemap}`);
+    for (const url of sitemaps) lines.push(`Sitemap: ${url}`);
   }
 
   return `${lines.join('\n')}\n`;

package/vite-plugin.js

@@ -172,7 +172,7 @@ const ENTRY_FILENAME = '.cms-entry.js';
 // When external theme packages are provided via the `themes` option, the plugin
 // generates additional import + registerTheme() calls so themes are available
 // before the app renders.
-function buildEntrySource(themePackages = [], extensionPackages = []) {
+function buildEntrySource(themePackages = [], extensionPackages = [], trimSpecs = []) {
   const themeImports = themePackages.map(
     (pkg, i) => `import __theme${i} from '${pkg}';`
   ).join('\n');
@@ -189,8 +189,20 @@ function buildEntrySource(themePackages = [], extensionPackages = []) {
     (_, i) => `await registerExtension(__ext${i});`
   ).join('\n');
 
+  // Site-supplied hydration-payload trim hooks. Imported and registered at
+  // module-eval time, BEFORE createCmsApp() — extension setups run only on the
+  // client, so they are unreachable during SSG and cannot serve this purpose.
+  const trimImports = trimSpecs.map(
+    (spec, i) => `import __trim${i} from '${spec}';`
+  ).join('\n');
+
+  const trimRegistrations = trimSpecs.map(
+    (_, i) => `registerInitialStateTrim(__trim${i});`
+  ).join('\n');
+
   const needsThemeRegister = themePackages.length > 0;
   const needsExtRegister = extensionPackages.length > 0;
+  const needsTrimRegister = trimSpecs.length > 0;
 
   // Use dynamic import for createCmsApp so that setConfigLoader/etc run
   // BEFORE ViteSSG's auto-mount IIFE.  Static imports are hoisted and
@@ -203,8 +215,10 @@ 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';` : ''}
+${needsTrimRegister ? `import { registerInitialStateTrim } from '@koehler8/cms/utils/initialStateTrim';` : ''}
 ${themeImports}
 ${extImports}
+${trimImports}
 
 import * as __cmsConfig from '${VIRTUAL_CONFIG}';
 import * as __cmsStyles from '${VIRTUAL_STYLES}';
@@ -219,6 +233,7 @@ setSiteComponents(__cmsSiteComponents);
 
 ${themeRegistrations}
 ${extRegistrations}
+${trimRegistrations}
 
 const { createCmsApp } = await import('@koehler8/cms/app');
 export const createApp = createCmsApp();
@@ -355,7 +370,7 @@ function discoverExtensionCjsDeps(extensionPackages, projectRoot) {
 // 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 };
+export { validateExtensionManifests, buildEntrySource };
 
 // List every *.vue basename under a directory (recursive). Mirrors the
 // import.meta.glob discovery the runtime registries use.
@@ -441,6 +456,7 @@ export default function cmsPlugin(options = {}) {
     frameworkRoot: frameworkRootOption = __dirname,
     themes: themePackages = [],
     extensions: extensionPackages = [],
+    initialStateTrims: initialStateTrimOption = [],
   } = options;
   // The previous `locales` option is no longer accepted: per-site available
   // locales are now discovered from on-disk content directories. Passing
@@ -462,6 +478,9 @@ export default function cmsPlugin(options = {}) {
   let variantCacheDir;
   let variantManifestPath;
   let imageVariantWidths = [];
+  // Site-supplied initialStateTrim module specifiers, resolved at config time
+  // to something the generated entry (written into siteRoot) can import.
+  let initialStateTrims = [];
   // 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.
@@ -469,7 +488,7 @@ export default function cmsPlugin(options = {}) {
 
   const writeTempFiles = () => {
     // Write entry file (with optional external theme registrations)
-    fs.writeFileSync(tempEntryPath, buildEntrySource(themePackages, extensionPackages), 'utf-8');
+    fs.writeFileSync(tempEntryPath, buildEntrySource(themePackages, extensionPackages, initialStateTrims), 'utf-8');
 
     // Write index.html with site metadata injected and script src pointing
     // at the entry file
@@ -589,6 +608,28 @@ export default function cmsPlugin(options = {}) {
       variantCacheDir = computeVariantCacheDir(siteRoot, siteDir);
       variantManifestPath = path.join(variantCacheDir, '.manifest.json');
 
+      // Resolve initialStateTrims to specifiers the generated entry can import.
+      // A relative path that does not exist is a HARD failure at config time:
+      // this hook's failure mode is an invisibly-larger payload, so a typo must
+      // not degrade to a silent no-op.
+      initialStateTrims = (Array.isArray(initialStateTrimOption) ? initialStateTrimOption : [initialStateTrimOption])
+        .filter((spec) => typeof spec === 'string' && spec.trim())
+        .map((spec) => {
+          const trimmed = spec.trim();
+          // Bare package specifier — hand it to the bundler untouched.
+          if (!trimmed.startsWith('.') && !path.isAbsolute(trimmed)) return trimmed;
+          const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(siteRoot, trimmed);
+          if (!fs.existsSync(abs)) {
+            throw new Error(
+              `[cms] initialStateTrims: no such file: ${trimmed}\n` +
+              `  resolved to: ${abs}\n` +
+              `  (paths are resolved relative to the project root, ${siteRoot})`,
+            );
+          }
+          const rel = path.relative(siteRoot, abs).split(path.sep).join('/');
+          return rel.startsWith('.') ? rel : `./${rel}`;
+        });
+
       // 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.
@@ -1101,7 +1142,7 @@ export const assetUrlMap = resolver.assetUrlMap;
           try {
             // Ensure the temp file exists for Vite's module graph
             if (!fs.existsSync(tempEntryPath)) {
-              fs.writeFileSync(tempEntryPath, buildEntrySource(themePackages, extensionPackages), 'utf-8');
+              fs.writeFileSync(tempEntryPath, buildEntrySource(themePackages, extensionPackages, initialStateTrims), 'utf-8');
             }
             // Let Vite transform it (resolves bare specifiers, applies plugins)
             const result = await server.transformRequest(`/${ENTRY_FILENAME}`);