@koehler8/cms 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # 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
+
+- **A site-authored `pages/404.json` is no longer indexable.** The framework
+  flagged the not-found page via `selectPage`'s fallback branch only, which
+  runs when *no* page matches the requested path. But the authored page
+  necessarily carries `path: "/404"` so the plugin can pre-render it and copy
+  the output to `404.html` — which also makes it an ordinary route. A direct
+  hit on `/404` matched the path loop first and returned a page nothing
+  downstream recognized as a 404: `usePageMeta` emitted a canonical and skipped
+  the `noindex`, and `sitemapGenerator` listed the URL. Sites that followed the
+  documented advice to author a 404 for custom chrome got an indexable,
+  sitemapped `/404` for their trouble.
+
+  Detection now lives in `src/utils/notFound.js` and is shared by the runtime
+  and the build, so they cannot disagree. The page is matched by its reserved
+  `404` id *or* by resolving to `/404`, is flagged at every resolution point,
+  and is excluded from the sitemap. Authoring `pages/404.json` now does what
+  the docs always said it did: custom chrome *and* correct 404 semantics.
+
+- **The bundled `Header` has a mobile navigation menu.** `content.header.navItems[]`
+  was `display: none` below 720px with nothing to open it, so phone visitors
+  got no primary navigation at all — the header's own comment told sites to
+  override the nav slot, which means forking the component. The links now
+  collapse into a disclosure panel behind a 44×44 toggle: `aria-expanded` /
+  `aria-controls` wired up, ESC closes and restores focus to the toggle,
+  focus-out and outside clicks dismiss it, in-SPA navigation and crossing the
+  breakpoint close it. Overriding the nav slot still suppresses the bundled
+  toggle entirely, so sites with their own responsive header are unaffected.
+
 ## 1.0.0
 
 First stable release. The changes below are the three implementation batches

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.0.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/components/Header.vue

@@ -8,7 +8,12 @@
       class="site-header__section ui-header__section"
       :class="{ 'ui-header__section--compact': isHeaderCompact }"
     >
-      <nav class="site-header__nav" aria-label="Primary">
+      <nav
+        class="site-header__nav"
+        aria-label="Primary"
+        @keydown.esc="closeNavMenu($event, 'escape')"
+        @focusout="onNavFocusOut"
+      >
         <div class="container">
           <div class="site-header__inner">
             <a href="/" ref="logoLinkRef" class="site-header__logo logo-flash-trigger" :aria-label="`${siteName || 'Home'} – home`">
@@ -33,18 +38,59 @@
             Nav slot. Defaults to a horizontal <ul> of links built from
             `content.header.navItems[]` (each entry: { text, href, target? }).
             No items, no nav.
+
+            Below 720px the row collapses into a disclosure menu behind the
+            toggle button below. Before this existed the list was simply
+            display:none on narrow viewports, which left phone visitors with
+            no primary navigation at all.
           -->
           <slot name="nav" :items="navItems">
-            <ul v-if="navItems.length" class="site-header__nav-list">
+            <ul
+              v-if="navItems.length"
+              id="site-header-nav-menu"
+              ref="navMenuRef"
+              class="site-header__nav-list"
+              :class="{ 'site-header__nav-list--open': isNavOpen }"
+            >
               <li v-for="(item, idx) in navItems" :key="`${item.href || item.text}-${idx}`">
                 <a
                   :href="item.href"
                   :target="item.target || null"
                   :rel="item.target === '_blank' ? 'noopener noreferrer' : null"
+                  @click="closeNavMenu(null, 'selection')"
                 >{{ item.text }}</a>
               </li>
             </ul>
           </slot>
+          <button
+            v-if="navItems.length && !hasNavSlot"
+            ref="navToggleRef"
+            class="site-header__nav-toggle"
+            type="button"
+            aria-controls="site-header-nav-menu"
+            :aria-expanded="isNavOpen ? 'true' : 'false'"
+            :aria-label="isNavOpen ? 'Close menu' : 'Open menu'"
+            @click="toggleNavMenu"
+          >
+            <svg viewBox="0 0 24 24" aria-hidden="true" width="22" height="22">
+              <path
+                v-if="isNavOpen"
+                d="M6 6l12 12M18 6L6 18"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="1.8"
+                stroke-linecap="round"
+              />
+              <path
+                v-else
+                d="M4 7h16M4 12h16M4 17h16"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="1.8"
+                stroke-linecap="round"
+              />
+            </svg>
+          </button>
           <div v-if="hasHeaderActions || showLocaleLinks || hasActionsSlot" class="site-header__actions">
             <!-- Site-provided extra actions, rendered before the locale dropdown. -->
             <slot name="actions" />
@@ -125,8 +171,12 @@ import { readStoredLocale, writeStoredLocale } from '../utils/webStorage.js';
 
   const slots = useSlots();
   const hasActionsSlot = computed(() => Boolean(slots.actions));
+  // A site overriding the nav slot owns its own responsive behaviour, so the
+  // bundled toggle must not render alongside it.
+  const hasNavSlot = computed(() => Boolean(slots.nav));
 
 const isLangOpen = ref(false);
+const isNavOpen = ref(false);
 const isHeaderCompact = ref(false);
 const currentLocale = ref('');
 const availableLocales = computed(() => siteLocales.map((code) => code.trim()).filter(Boolean));
@@ -189,6 +239,8 @@ const localeEmojis = {
 };
   const langButtonRef = ref(null);
   const langMenuRef = ref(null);
+  const navToggleRef = ref(null);
+  const navMenuRef = ref(null);
   const localeWrapperRef = ref(null);
   const localeMenuStyle = ref({ animationDuration: '500ms' });
   const logoLinkRef = ref(null);
@@ -228,9 +280,21 @@ const updateLocaleMenuPosition = () => {
     if (isLangOpen.value) {
       updateLocaleMenuPosition();
     }
+    // Above the breakpoint the toggle is display:none. Leaving isNavOpen true
+    // would strand aria-expanded="true" on a button no longer in the a11y tree.
+    if (isNavOpen.value && typeof window !== 'undefined' && window.innerWidth >= 720) {
+      isNavOpen.value = false;
+    }
   };
 
   const onDocumentClick = (e) => {
+    const navBtn = navToggleRef.value;
+    const navMenu = navMenuRef.value;
+    if (isNavOpen.value && !navBtn?.contains(e.target) && !navMenu?.contains(e.target)) {
+      isNavOpen.value = false;
+      trackEvent('header_nav_menu_toggle', { state: 'close', trigger: 'outside_click' });
+    }
+
     const btn = langButtonRef.value;
     const menu = langMenuRef.value;
     if (btn && btn.contains(e.target)) return; // toggle handled by button
@@ -266,6 +330,41 @@ const updateLocaleMenuPosition = () => {
     }
   };
 
+  const toggleNavMenu = () => {
+    isNavOpen.value = !isNavOpen.value;
+    trackEvent('header_nav_menu_toggle', {
+      state: isNavOpen.value ? 'open' : 'close',
+      trigger: 'click',
+    });
+  };
+
+  // Mirrors closeLocaleMenu: ESC restores focus to the toggle so keyboard
+  // dismissal doesn't strand focus inside a hidden menu (WCAG 2.4.3, 1.4.13).
+  const closeNavMenu = (event, trigger = 'escape') => {
+    if (!isNavOpen.value) return;
+    if (event) {
+      event.preventDefault?.();
+      event.stopPropagation?.();
+    }
+    isNavOpen.value = false;
+    trackEvent('header_nav_menu_toggle', { state: 'close', trigger });
+    if (trigger === 'escape') {
+      nextTick(() => navToggleRef.value?.focus());
+    }
+  };
+
+  // Closes the menu when focus leaves both the menu and its toggle. Scoped to
+  // those two elements rather than the whole <nav> so tabbing from a menu link
+  // to the locale button (also inside <nav>) still dismisses it.
+  const onNavFocusOut = (event) => {
+    if (!isNavOpen.value) return;
+    const next = event.relatedTarget;
+    if (!next) return;
+    if (navMenuRef.value?.contains(next)) return;
+    if (navToggleRef.value?.contains(next)) return;
+    closeNavMenu(null, 'focusout');
+  };
+
   // Closes the menu when keyboard focus leaves the wrapper entirely.
   // Without this, Tab would walk past the dropdown but leave it visible
   // and clickable — also fails 1.4.13's "dismissable" requirement.
@@ -475,6 +574,17 @@ const updateLocaleMenuPosition = () => {
       currentLocale.value = normalized;
     }
   );
+
+  // In-SPA navigation must dismiss the mobile menu. The link click handler
+  // covers taps on the menu's own links; this covers everything else that
+  // changes the route while it's open (back button, a link elsewhere on the
+  // page, a programmatic push).
+  watch(
+    () => route.path,
+    () => {
+      isNavOpen.value = false;
+    }
+  );
 </script>
 
 <style scoped>
@@ -542,8 +652,13 @@ const updateLocaleMenuPosition = () => {
 }
 
 /* Nav menu rendered from content.header.navItems[]. Sits between the logo
-   and the actions cluster. Hidden on narrow viewports — sites that need
-   responsive nav should override the slot. */
+   and the actions cluster.
+
+   Below 720px it becomes a disclosure panel dropped beneath the header bar,
+   opened by .site-header__nav-toggle. (It used to be plain display:none here,
+   with no toggle — phone visitors got no primary navigation at all.) Sites
+   that want something else still override the nav slot, which also suppresses
+   the bundled toggle. */
 .site-header__nav-list {
   display: none;
   list-style: none;
@@ -552,10 +667,76 @@ const updateLocaleMenuPosition = () => {
   gap: clamp(0.75rem, 2vw, 1.75rem);
   align-items: center;
 }
+.site-header__nav-list--open {
+  /* Containing block is .site-header (position: sticky), so this drops the
+     panel flush under the full-width bar rather than under the inner column. */
+  display: flex;
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0;
+  padding: 0.5rem 0;
+  background: var(--brand-header-bg, #020409);
+  border-top: 1px solid var(--ui-header-divider, rgba(255, 255, 255, 0.12));
+  box-shadow: var(--site-header-shadow, 0 18px 45px rgba(0, 0, 0, 0.35));
+  max-height: calc(100dvh - 100%);
+  overflow-y: auto;
+}
+.site-header__nav-list--open a {
+  display: block;
+  /* Comfortably past the 24x24 minimum for pointer targets (WCAG 2.5.8). */
+  padding: 0.85rem clamp(1rem, 5vw, 2rem);
+}
+
+/* Toggle is mobile-only; the row speaks for itself at 720px and up. */
+.site-header__nav-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  /* 44px square — the comfortable touch target, well past WCAG 2.5.8's 24px. */
+  width: 44px;
+  height: 44px;
+  margin-left: auto;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.site-header__nav-toggle:hover {
+  background: var(--ui-header-hover, rgba(255, 255, 255, 0.08));
+}
+
 @media (min-width: 720px) {
   .site-header__nav-list {
     display: flex;
   }
+  /* Neutralize the open state above the breakpoint: resizing past it while the
+     menu is open must not leave a dropped panel on a desktop layout. */
+  .site-header__nav-list--open {
+    position: static;
+    flex-direction: row;
+    align-items: center;
+    gap: clamp(0.75rem, 2vw, 1.75rem);
+    padding: 0;
+    background: none;
+    border-top: 0;
+    box-shadow: none;
+    max-height: none;
+    overflow-y: visible;
+  }
+  .site-header__nav-list--open a {
+    display: inline;
+    padding: 0;
+  }
+  .site-header__nav-toggle {
+    display: none;
+  }
 }
 .site-header__nav-list a {
   color: var(--brand-header-text, var(--brand-fg-100, inherit));

package/src/composables/usePageConfig.js

@@ -1,6 +1,7 @@
 import { onServerPrefetch, ref, watch } from 'vue';
 import { loadConfigData, mergeConfigTrees, peekConfigSync } from '../utils/loadConfig.js';
 import { readStoredLocale } from '../utils/webStorage.js';
+import { isNotFoundPage, NOT_FOUND_PAGE_ID } from '../utils/notFound.js';
 
 function normalizePath(value) {
   if (!value || typeof value !== 'string') return '/';
@@ -12,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 : {};
@@ -36,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 || {};
@@ -44,7 +60,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     const resolveById = (id) => {
       const data = pages[id];
       if (!data) return null;
-      return {
+      const resolved = {
         id,
         path: data.path ?? '/',
         components: Array.isArray(data.components) ? [...data.components] : [],
@@ -53,6 +69,13 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
         draft: data.draft,
         jsonld: data.jsonld,
       };
+      // A site-authored pages/404.json resolves like any other route (it has a
+      // real path so the plugin can pre-render it), so the flag has to be set
+      // here rather than only on the not-found fallback below. Otherwise a
+      // direct hit on /404 yields a page usePageMeta treats as ordinary —
+      // canonical emitted, noindex omitted — and sitemapGenerator lists it.
+      if (isNotFoundPage(id, resolved.path)) resolved.isNotFound = true;
+      return resolved;
     };
 
     const currentPageId = typeof pageId === 'function' ? pageId() : pageId;
@@ -67,15 +90,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
       const requestedPath = normalizePath(currentPagePath);
       for (const [id, data] of entries) {
         if (normalizePath(data.path) === requestedPath) {
-          return {
-            id,
-            path: data.path ?? '/',
-            components: Array.isArray(data.components) ? [...data.components] : [],
-            content: data.content || {},
-            meta: data.meta || {},
-            draft: data.draft,
-            jsonld: data.jsonld,
-          };
+          return resolveById(id);
         }
       }
 
@@ -88,8 +103,10 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
       // with their own components[]; otherwise the synthesized sentinel
       // renders the bundled NotFound component.
       if (requestedPath !== '/') {
-        const customNotFound = resolveById('404');
+        const customNotFound = resolveById(NOT_FOUND_PAGE_ID);
         if (customNotFound) {
+          // resolveById already flags this; kept explicit so the guarantee is
+          // visible at the call site that depends on it.
           return { ...customNotFound, isNotFound: true };
         }
         return {
@@ -239,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;
   }
@@ -267,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/notFound.js

@@ -0,0 +1,52 @@
+/**
+ * Single source of truth for "is this page the not-found page".
+ *
+ * A site can author `pages/404.json` to give the 404 its own chrome and copy.
+ * That page necessarily carries `path: "/404"` so the plugin pre-renders it and
+ * can copy `dist/404/index.html` → `dist/404.html`. The consequence is that it
+ * is also an ordinary route: resolving by id or by path matches it directly,
+ * before `selectPage`'s not-found fallback ever runs.
+ *
+ * Without a shared check, those direct resolutions produce a page that looks
+ * ordinary to everything downstream — `usePageMeta` emits a canonical and skips
+ * the `noindex`, `sitemapGenerator` lists it, and breadcrumbs are derived for
+ * it. The result is an indexable, sitemapped /404, which is the opposite of what
+ * authoring the page was supposed to achieve.
+ *
+ * Both the runtime (usePageConfig → usePageMeta) and the build (sitemapGenerator)
+ * import from here so they cannot disagree about what counts.
+ */
+
+/** Page id the framework reserves for a site-authored not-found page. */
+export const NOT_FOUND_PAGE_ID = '404';
+
+/** Route the not-found page is pre-rendered at. */
+export const NOT_FOUND_PATH = '/404';
+
+/**
+ * Normalize a page path for comparison: leading slash, no duplicate slashes,
+ * no trailing slash. Mirrors the normalization in usePageConfig so `/404/`,
+ * `404`, and `/404` all compare equal.
+ */
+export function normalizeNotFoundPath(value) {
+  if (!value || typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  normalized = normalized.replace(/\/+/g, '/');
+  normalized = normalized.replace(/\/+$/, '');
+  return normalized || '/';
+}
+
+/**
+ * True when a page is the not-found page — either by its reserved id or by
+ * being routed at /404. Either alone is enough: a site may name the file
+ * something else but point it at /404, or vice versa.
+ *
+ * @param {string} [id] page id (the content filename without extension)
+ * @param {string} [path] the page's `path` value
+ */
+export function isNotFoundPage(id, path) {
+  if (id === NOT_FOUND_PAGE_ID) return true;
+  return normalizeNotFoundPath(path) === NOT_FOUND_PATH;
+}

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/src/utils/sitemapGenerator.js

@@ -2,7 +2,10 @@
  * Build sitemap.xml from the inflated site config.
  *
  * Pages where isPathDraft() is true are skipped — drafts must not be in the
- * sitemap. Returns '' when site.url is missing (the sitemap protocol requires
+ * sitemap. The not-found page is skipped for the same reason: it is a real
+ * pre-rendered route (so the plugin can copy it to 404.html) but it carries
+ * noindex, and listing a noindex URL is a Search Console warning.
+ * Returns '' when site.url is missing (the sitemap protocol requires
  * absolute URLs); the plugin treats empty output as "do not write the file."
  *
  * Single-locale sites emit only <loc> per page. Multi-locale sites emit one
@@ -15,6 +18,7 @@
 
 import { isPathDraft, normalizeDraftPath } from './draftMode.js';
 import { buildCanonicalUrl } from './canonicalUrl.js';
+import { isNotFoundPage } from './notFound.js';
 
 function escapeXml(value) {
   return String(value).replace(/[<>&'"]/g, (c) => ({
@@ -48,10 +52,13 @@ export function buildSitemap(siteConfig, options = {}) {
   const entries = [];
   const seenPaths = new Set();
 
-  for (const [, pageData] of Object.entries(pages)) {
+  for (const [pageId, pageData] of Object.entries(pages)) {
     if (!pageData || typeof pageData !== 'object') continue;
     const pagePath = normalizeDraftPath(pageData.path) || '/';
     if (isPathDraft(siteConfig, pagePath, pageData)) continue;
+    // The not-found page is pre-rendered as a real route so the plugin can copy
+    // it to 404.html, but it carries noindex and must never be advertised.
+    if (isNotFoundPage(pageId, pagePath)) continue;
     if (seenPaths.has(pagePath)) continue;
     seenPaths.add(pagePath);
 

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.
@@ -783,10 +824,11 @@ export default function cmsPlugin(options = {}) {
           // 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.
+          // dist/404/index.html to dist/404.html — the not-found target
+          // hosts point their catch-all at. (GitHub-Pages-style hosts
+          // auto-serve it at HTTP 404; AWS Amplify does NOT — it needs the
+          // fleet's customRule `/<*>` → `/404.html` @ `404`, which Amplify
+          // implements as a 302 redirect. Measured 2026-08-16.)
           onFinished() {
             const distDir = path.join(siteRoot, process.env.CMS_SSG_OUTDIR || 'dist');
             const nestedNotFound = path.join(distDir, '404', 'index.html');
@@ -802,8 +844,11 @@ export default function cmsPlugin(options = {}) {
           includedRoutes(paths) {
             // /404 is the not-found landing page (rendered via the
             // catch-all + NotFound component). onFinished above copies
-            // dist/404/index.html to dist/404.html so AWS Amplify serves
-            // it for unmatched URLs with HTTP 404.
+            // dist/404/index.html to dist/404.html; the host's catch-all
+            // rule sends unmatched URLs there. (On AWS Amplify that rule is
+            // a 302 redirect — its `404` rule type redirects rather than
+            // rewriting, and it has no native 404.html fallback. Measured
+            // 2026-08-16; the page's noindex meta covers the SEO side.)
             const staticRoutes = new Set(['/404']);
             pagePaths.forEach((routePath) => staticRoutes.add(routePath));
 
@@ -1097,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}`);