@koehler8/cms 1.0.0-beta.19 → 1.0.0-beta.21

package/package.json

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

package/src/components/NotFound.vue

@@ -0,0 +1,100 @@
+<template>
+  <section class="not-found" aria-labelledby="not-found-heading">
+    <p class="not-found__eyebrow" aria-hidden="true">404</p>
+    <h1 id="not-found-heading" class="not-found__title">{{ heading }}</h1>
+    <p class="not-found__body">{{ body }}</p>
+    <a class="not-found__home" :href="homeHref">{{ homeLabel }}</a>
+  </section>
+</template>
+
+<script setup>
+import { computed, inject } from 'vue';
+
+const pageContent = inject('pageContent', null);
+const siteData = inject('siteData', null);
+
+const config = computed(() => {
+  const fromShared = siteData?.value?.shared?.content?.notFound;
+  const fromPage = pageContent?.value?.notFound;
+  return { ...(fromShared || {}), ...(fromPage || {}) };
+});
+
+const heading = computed(() => config.value.heading || 'Page not found');
+const body = computed(
+  () => config.value.body || "We couldn't find the page you're looking for.",
+);
+const homeLabel = computed(() => config.value.homeLabel || 'Return home');
+const homeHref = computed(() => config.value.homeHref || '/');
+</script>
+
+<style scoped>
+.not-found {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 60vh;
+  padding: clamp(2rem, 6vw, 4rem) clamp(1rem, 4vw, 2rem);
+  text-align: center;
+  color: var(--brand-text, #1f2a44);
+  background: var(--brand-surface, transparent);
+  font-family: var(--ui-font-body, system-ui, -apple-system, sans-serif);
+}
+
+.not-found__eyebrow {
+  margin: 0 0 0.25rem;
+  font-size: clamp(2.5rem, 8vw, 4rem);
+  font-weight: 700;
+  line-height: 1;
+  letter-spacing: 0.02em;
+  color: var(--brand-text-muted, rgba(31, 42, 68, 0.55));
+}
+
+.not-found__title {
+  margin: 0 0 0.75rem;
+  font-size: clamp(1.5rem, 4vw, 2.25rem);
+  font-weight: 700;
+  line-height: 1.2;
+}
+
+.not-found__body {
+  margin: 0 0 1.5rem;
+  max-width: 32rem;
+  font-size: 1rem;
+  line-height: 1.6;
+  color: var(--brand-text-muted, rgba(31, 42, 68, 0.7));
+}
+
+.not-found__home {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 2.75rem;
+  padding: 0.7rem 1.5rem;
+  font-size: 1rem;
+  font-weight: 600;
+  text-decoration: none;
+  color: var(--brand-primary-cta-text, #ffffff);
+  background: var(--brand-primary-cta, var(--brand-primary, #1f2a44));
+  border-radius: var(--brand-button-radius, 10px);
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.not-found__home:hover {
+  transform: translateY(-1px);
+}
+
+.not-found__home:focus-visible {
+  outline: 2px solid var(--brand-primary, #1f2a44);
+  outline-offset: 3px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .not-found__home {
+    transition: none;
+  }
+  .not-found__home:hover {
+    transform: none;
+  }
+}
+</style>

package/src/composables/usePageConfig.js

@@ -50,6 +50,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
         content: data.content || {},
         meta: data.meta || {},
         draft: data.draft,
+        jsonld: data.jsonld,
       };
     };
 
@@ -72,9 +73,34 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
             content: data.content || {},
             meta: data.meta || {},
             draft: data.draft,
+            jsonld: data.jsonld,
           };
         }
       }
+
+      // No page matches the requested path. If it's anything other than
+      // the home path "/" — or the explicit /404 SSG route — treat it as
+      // a not-found page (instead of silently returning home content with
+      // HTTP 200, which is what the framework used to do).
+      //
+      // Sites can override the rendered 404 by authoring pages/404.json
+      // with their own components[]; otherwise the synthesized sentinel
+      // renders the bundled NotFound component.
+      if (requestedPath !== '/') {
+        const customNotFound = resolveById('404');
+        if (customNotFound) {
+          return { ...customNotFound, isNotFound: true };
+        }
+        return {
+          id: '__not_found__',
+          path: requestedPath,
+          components: [{ name: 'NotFound', enabled: true }],
+          content: {},
+          meta: {},
+          draft: undefined,
+          isNotFound: true,
+        };
+      }
     }
 
     const homeFallback = resolveById('home');
@@ -89,6 +115,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
         content: firstData.content || {},
         meta: firstData.meta || {},
         draft: firstData.draft,
+        jsonld: firstData.jsonld,
       };
     }
 

package/src/composables/usePageMeta.js

@@ -2,8 +2,21 @@ import { computed } from 'vue';
 import { useHead } from '@unhead/vue';
 import { isPathDraft } from '../utils/draftMode.js';
 import { buildCanonicalUrl } from '../utils/canonicalUrl.js';
+import { buildSocialMeta } from '../utils/socialMeta.js';
+import { buildJsonLdScripts } from '../utils/jsonLd.js';
 import { availableLocales as configAvailableLocales, baseLocale as configBaseLocale } from '../utils/loadConfig.js';
 
+// Site-verification meta-tag names per platform. Authors set
+// `site.siteVerification.<platform>` in site.json with the token issued by
+// the platform's webmaster console; we emit one <meta> per platform.
+const SITE_VERIFICATION_META = {
+  google: 'google-site-verification',
+  bing: 'msvalidate.01',
+  yandex: 'yandex-verification',
+  pinterest: 'p:domain_verify',
+  facebook: 'facebook-domain-verification',
+};
+
 const SPECIAL_PAGE_LABELS = {
   home: '',
   terms: 'Terms of Service',
@@ -51,10 +64,16 @@ export function usePageMeta({ siteData, currentPage, locale }) {
   const isDraft = computed(() =>
     isPathDraft(siteData.value, currentPage.value?.path, currentPage.value),
   );
+  const isNotFound = computed(() => Boolean(currentPage.value?.isNotFound));
 
   const pageMetaTitle = computed(() => {
     const page = currentPage.value;
     const site = siteTitle.value;
+    // 404 pages: generic "Page not found — Site". The page slug (which is
+    // some URL the visitor typed) shouldn't leak into <title>.
+    if (isNotFound.value) {
+      return site ? `Page not found — ${site}` : 'Page not found';
+    }
     // Draft pages emit a generic title so the page slug doesn't leak via
     // <title> in the SSG-rendered HTML on disk. The tab title remains
     // generic even after client-side unlock — for "iterate before launch"
@@ -74,7 +93,7 @@ export function usePageMeta({ siteData, currentPage, locale }) {
   });
 
   const pageMetaDescription = computed(() => {
-    if (isDraft.value) {
+    if (isDraft.value || isNotFound.value) {
       return '';
     }
     const explicitDescription = currentPage.value?.meta?.description;
@@ -85,11 +104,11 @@ export function usePageMeta({ siteData, currentPage, locale }) {
   });
 
   // Canonical URL — base-locale URLs have no prefix; non-base locales get
-  // /{locale}/path. Drafts skip canonical (gated content shouldn't advertise
-  // an authoritative URL). Sites without a configured site.url skip too —
-  // we can't build an absolute URL.
+  // /{locale}/path. Drafts and 404s skip canonical (the URL itself isn't
+  // authoritative for gated/missing content). Sites without a configured
+  // site.url skip too — we can't build an absolute URL.
   const canonicalHref = computed(() => {
-    if (isDraft.value) return '';
+    if (isDraft.value || isNotFound.value) return '';
     if (!siteUrl.value) return '';
     return buildCanonicalUrl({
       siteUrl: siteUrl.value,
@@ -104,7 +123,7 @@ export function usePageMeta({ siteData, currentPage, locale }) {
   // an `x-default` pointing at the base-locale URL (Google's preferred
   // pattern for sites without explicit geo-targeting).
   const hreflangLinks = computed(() => {
-    if (isDraft.value) return [];
+    if (isDraft.value || isNotFound.value) return [];
     if (!siteUrl.value) return [];
     if (!Array.isArray(configAvailableLocales) || configAvailableLocales.length <= 1) return [];
     const path = currentPage.value?.path || '/';
@@ -138,9 +157,39 @@ export function usePageMeta({ siteData, currentPage, locale }) {
     if (description) {
       meta.push({ name: 'description', content: description, key: 'description' });
     }
-    if (isDraft.value) {
+    // 404 pages get noindex defensively — Amplify (or whichever host)
+    // already serves them with HTTP 404, but search engines occasionally
+    // crawl 404 URLs and the meta is a stronger signal than relying on
+    // the status header alone.
+    if (isDraft.value || isNotFound.value) {
       meta.push({ name: 'robots', content: 'noindex, nofollow', key: 'robots' });
     }
+    const social = buildSocialMeta({
+      siteData: siteData.value,
+      currentPage: currentPage.value,
+      pageTitle: pageMetaTitle.value,
+      pageDescription: pageMetaDescription.value,
+      canonicalHref: canonicalHref.value,
+      isDraft: isDraft.value,
+      isNotFound: isNotFound.value,
+    });
+    for (const entry of social) meta.push(entry);
+
+    // Site-verification meta tags. These are emitted on every page (not
+    // just home) — verification platforms typically only check homepage
+    // but emitting site-wide is harmless and matches what most CMSs do.
+    const verification = siteData.value?.site?.siteVerification;
+    if (verification && typeof verification === 'object') {
+      for (const [platform, token] of Object.entries(verification)) {
+        const metaName = SITE_VERIFICATION_META[platform];
+        if (!metaName) continue;
+        if (typeof token !== 'string') continue;
+        const trimmed = token.trim();
+        if (!trimmed) continue;
+        meta.push({ name: metaName, content: trimmed, key: `verify-${platform}` });
+      }
+    }
+
     const link = [];
     if (canonicalHref.value) {
       link.push({ rel: 'canonical', href: canonicalHref.value, key: 'canonical' });
@@ -148,12 +197,21 @@ export function usePageMeta({ siteData, currentPage, locale }) {
     for (const entry of hreflangLinks.value) {
       link.push(entry);
     }
+
+    const script = buildJsonLdScripts({
+      siteData: siteData.value,
+      currentPage: currentPage.value,
+      isDraft: isDraft.value,
+      isNotFound: isNotFound.value,
+    });
+
     return {
       title: pageMetaTitle.value,
       meta,
       link,
+      script,
     };
   });
 
-  return { pageMetaTitle, pageMetaDescription, isDraft, canonicalHref, hreflangLinks };
+  return { pageMetaTitle, pageMetaDescription, isDraft, isNotFound, canonicalHref, hreflangLinks };
 }

package/src/utils/jsonLd.js

@@ -0,0 +1,58 @@
+/**
+ * Normalize per-page + site-wide JSON-LD blocks into a flat list of
+ * @unhead/vue script descriptors ready for `useHead({ script: [...] })`.
+ *
+ * Authoring conventions in `pages/{id}.json` and `site.json`:
+ *
+ *   "jsonld": { "@context": "https://schema.org", "@type": "Article", ... }
+ *
+ * or for multiple blocks on a page:
+ *
+ *   "jsonld": [
+ *     { "@type": "Article", ... },
+ *     { "@type": "BreadcrumbList", ... }
+ *   ]
+ *
+ * Page blocks ALWAYS append to site blocks (there's no "override" semantic
+ * — each schema.org block is an independent assertion, so listing both is
+ * the right behavior for a sitewide Organization + a page-specific Article).
+ *
+ * Skipped entirely on drafts and 404s; structured data on those would
+ * mislead crawlers (drafts shouldn't be indexed; 404s aren't authoritative).
+ */
+
+function normalizeBlock(block) {
+  if (!block || typeof block !== 'object' || Array.isArray(block)) return null;
+  // Inject the schema.org @context if the author omitted it. JSON-LD blocks
+  // without @context are ignored by all major consumers, so adding it
+  // defensively is the right default.
+  if (!block['@context']) {
+    return { '@context': 'https://schema.org', ...block };
+  }
+  return block;
+}
+
+function collectBlocks(input) {
+  if (!input) return [];
+  if (Array.isArray(input)) {
+    return input.map(normalizeBlock).filter(Boolean);
+  }
+  const single = normalizeBlock(input);
+  return single ? [single] : [];
+}
+
+export function buildJsonLdScripts({ siteData, currentPage, isDraft, isNotFound } = {}) {
+  if (isDraft || isNotFound) return [];
+
+  const siteBlocks = collectBlocks(siteData?.site?.jsonld);
+  const pageBlocks = collectBlocks(currentPage?.jsonld);
+
+  const all = [...siteBlocks, ...pageBlocks];
+  if (all.length === 0) return [];
+
+  return all.map((block, i) => ({
+    type: 'application/ld+json',
+    innerHTML: JSON.stringify(block),
+    key: `jsonld-${block['@type'] || 'block'}-${i}`,
+  }));
+}

package/src/utils/socialMeta.js

@@ -0,0 +1,83 @@
+/**
+ * Build per-page Open Graph + Twitter Card meta entries.
+ *
+ * Returns an array of @unhead/vue meta descriptors ready to be spread into
+ * useHead's `meta:` array. Returns [] for drafts and 404 pages — drafts
+ * shouldn't be advertised socially, and 404 cards would mislead.
+ *
+ * Title and description are passed in pre-resolved (the caller — usually
+ * usePageMeta — already computes them with the site-wide fallback chain).
+ *
+ * og:image priority:
+ *   1. page.meta.image (per-page override; e.g. an article hero)
+ *   2. site.image / site.ogImage (site-wide override authored in site.json)
+ *   3. /og-image.jpg (the static asset cms-generate-public-assets writes)
+ *
+ * Relative image paths get an absolute URL built from site.url. If
+ * site.url is missing, the relative path is emitted as-is — most social
+ * scrapers won't follow it, but that's better than emitting nothing.
+ */
+
+const STATIC_OG_IMAGE = '/og-image.jpg';
+
+function absolutize(siteUrl, pathOrUrl) {
+  if (!pathOrUrl) return '';
+  if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
+  if (!siteUrl) return pathOrUrl;
+  const path = pathOrUrl.startsWith('/') ? pathOrUrl : `/${pathOrUrl}`;
+  return `${siteUrl}${path}`;
+}
+
+export function buildSocialMeta({
+  siteData,
+  currentPage,
+  pageTitle,
+  pageDescription,
+  canonicalHref,
+  isDraft,
+  isNotFound,
+} = {}) {
+  if (isDraft || isNotFound) return [];
+
+  const site = (siteData && siteData.site) || {};
+  const page = currentPage || {};
+  const pageMeta = page.meta || {};
+
+  const siteUrl = (typeof site.url === 'string' ? site.url : '').trim().replace(/\/+$/, '');
+  const siteTitle = typeof site.title === 'string' ? site.title.trim() : '';
+
+  const rawImage =
+    pageMeta.image ||
+    site.image ||
+    site.ogImage ||
+    STATIC_OG_IMAGE;
+  const ogImage = absolutize(siteUrl, rawImage);
+
+  const ogType = pageMeta.ogType || 'website';
+  const twitterCard = pageMeta.twitterCard || 'summary_large_image';
+
+  const meta = [];
+
+  if (pageTitle) {
+    meta.push({ property: 'og:title', content: pageTitle, key: 'og:title' });
+    meta.push({ name: 'twitter:title', content: pageTitle, key: 'twitter:title' });
+  }
+  if (pageDescription) {
+    meta.push({ property: 'og:description', content: pageDescription, key: 'og:description' });
+    meta.push({ name: 'twitter:description', content: pageDescription, key: 'twitter:description' });
+  }
+  if (canonicalHref) {
+    meta.push({ property: 'og:url', content: canonicalHref, key: 'og:url' });
+  }
+  meta.push({ property: 'og:type', content: ogType, key: 'og:type' });
+  if (siteTitle) {
+    meta.push({ property: 'og:site_name', content: siteTitle, key: 'og:site_name' });
+  }
+  if (ogImage) {
+    meta.push({ property: 'og:image', content: ogImage, key: 'og:image' });
+    meta.push({ name: 'twitter:image', content: ogImage, key: 'twitter:image' });
+  }
+  meta.push({ name: 'twitter:card', content: twitterCard, key: 'twitter:card' });
+
+  return meta;
+}

package/src/utils/webAppManifest.js

@@ -0,0 +1,82 @@
+/**
+ * Build a Web App Manifest (manifest.json) from the inflated site config.
+ *
+ * Returns the manifest object — the plugin JSON-stringifies and writes it
+ * to `siteRoot/public/manifest.json`. Browsers consume the file when the
+ * page emits `<link rel="manifest" href="/manifest.json">`.
+ *
+ * Authoring conventions in `site.json`:
+ *
+ *   "manifest.name": "...",          // overrides site.title
+ *   "manifest.shortName": "...",     // overrides truncated site.title
+ *   "manifest.themeColor": "#...",   // mobile chrome / splash bar color
+ *   "manifest.backgroundColor": "#...",  // splash background
+ *   "manifest.startUrl": "/",        // landing path on launch
+ *   "manifest.display": "standalone",// browser, standalone, fullscreen, minimal-ui
+ *   "manifest.icons[0].src": "...",  // override default icon set
+ *   "manifest.icons[0].sizes": "256x256",
+ *   "manifest.icons[0].type": "image/png"
+ *
+ * Defaults are derived from existing site config and the icons that
+ * cms-generate-public-assets writes (favicon-256.png + favicon.ico).
+ */
+
+const DEFAULT_DISPLAY = 'standalone';
+const DEFAULT_BG = '#ffffff';
+const DEFAULT_THEME = '#ffffff';
+const DEFAULT_START = '/';
+
+function trim(value, fallback = '') {
+  if (typeof value !== 'string') return fallback;
+  const t = value.trim();
+  return t || fallback;
+}
+
+function defaultIcons() {
+  // Mirrors what cms-generate-public-assets writes into public/.
+  // Browsers pick the best size; the 256x256 PNG is the primary, the
+  // .ico is the legacy fallback for older Android.
+  return [
+    { src: '/favicon-256.png', sizes: '256x256', type: 'image/png', purpose: 'any maskable' },
+    { src: '/favicon.ico', sizes: '64x64 32x32 16x16', type: 'image/x-icon' },
+  ];
+}
+
+export function buildWebAppManifest(siteConfig) {
+  const site = (siteConfig && siteConfig.site) || {};
+  const m = (site.manifest && typeof site.manifest === 'object') ? site.manifest : {};
+
+  const siteTitle = trim(site.title);
+  const name = trim(m.name, siteTitle) || 'Site';
+  const shortName = trim(m.shortName, name.length <= 12 ? name : name.slice(0, 12));
+
+  const description = trim(m.description, trim(site.description));
+
+  const themeColor = trim(m.themeColor, DEFAULT_THEME);
+  const backgroundColor = trim(m.backgroundColor, DEFAULT_BG);
+  const startUrl = trim(m.startUrl, DEFAULT_START);
+  const display = trim(m.display, DEFAULT_DISPLAY);
+  const lang = trim(m.lang);
+
+  const customIcons = Array.isArray(m.icons)
+    ? m.icons
+        .filter((icon) => icon && typeof icon === 'object' && typeof icon.src === 'string')
+        .map((icon) => ({ ...icon }))
+    : null;
+  const icons = customIcons && customIcons.length ? customIcons : defaultIcons();
+
+  const manifest = {
+    name,
+    short_name: shortName,
+    start_url: startUrl,
+    display,
+    theme_color: themeColor,
+    background_color: backgroundColor,
+    icons,
+  };
+
+  if (description) manifest.description = description;
+  if (lang) manifest.lang = lang;
+
+  return manifest;
+}

package/templates/index.html

@@ -2,19 +2,16 @@
 <html lang="">
   <head>
     <meta charset="UTF-8">
-    <title><%= site %></title>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="description" content="<%= siteDescription %>">
-    <meta property="og:title" content="<%= site %>">
-    <meta property="og:description" content="<%= siteDescription %>">
-    <meta property="og:url" content="<%= siteUrl %>">
-    <meta property="og:type" content="website">
-    <meta property="og:image" content="<%= ABSOLUTE_OG_IMAGE %>">
-    <meta name="twitter:card" content="summary_large_image">
-    <meta name="twitter:title" content="<%= site %>">
-    <meta name="twitter:description" content="<%= siteDescription %>">
-    <meta name="twitter:image" content="<%= ABSOLUTE_OG_IMAGE %>">
+    <!--
+      Per-page <title>, <meta name="description">, og:*, twitter:*, canonical,
+      hreflang, and JSON-LD blocks are emitted by usePageMeta at SSG render
+      time. Site-wide invariants (favicon, web-app manifest, the JSON-LD
+      Organization snippet, mobile-chrome theme color) live here.
+    -->
     <link rel="icon" href="/favicon.ico">
+    <link rel="manifest" href="/manifest.json">
+    <meta name="theme-color" content="<%= manifestThemeColor %>">
     <script type="application/ld+json">
     {
       "@context": "https://schema.org",

package/vite-plugin.js

@@ -15,6 +15,7 @@ import vue from '@vitejs/plugin-vue';
 import { inflateFlatConfig } from './src/utils/inflateFlatConfig.js';
 import { buildRobotsTxt } from './src/utils/robotsGenerator.js';
 import { buildSitemap, getSitemapUrl } from './src/utils/sitemapGenerator.js';
+import { buildWebAppManifest } from './src/utils/webAppManifest.js';
 import { sha256Hex } from './src/utils/sha256.js';
 
 // ---- Helpers ----
@@ -117,6 +118,7 @@ function extractSiteMetadata(siteConfig) {
     url: siteUrl = '',
     googleId: siteGoogleId = '',
     sameAs: siteSameAs = [],
+    manifest: siteManifest = {},
   } = siteConfig.site || {};
 
   const siteSameAsList = Array.isArray(siteSameAs)
@@ -124,7 +126,14 @@ function extractSiteMetadata(siteConfig) {
     : [];
   const siteSameAsJson = JSON.stringify(siteSameAsList);
 
-  return { siteTitle, siteDescription, siteUrl, siteGoogleId, siteSameAsJson };
+  // Mobile chrome bar / PWA splash color. Defaults match buildWebAppManifest's
+  // default so the rendered <meta name="theme-color"> matches whatever
+  // manifest.json advertises.
+  const manifestThemeColor = (typeof siteManifest.themeColor === 'string'
+    ? siteManifest.themeColor.trim()
+    : '') || '#ffffff';
+
+  return { siteTitle, siteDescription, siteUrl, siteGoogleId, siteSameAsJson, manifestThemeColor };
 }
 
 const __filename = fileURLToPath(import.meta.url);
@@ -354,6 +363,7 @@ export default function cmsPlugin(options = {}) {
       siteUrl: metadata.siteUrl,
       siteGoogleId: metadata.siteGoogleId,
       siteSameAsJson: metadata.siteSameAsJson,
+      manifestThemeColor: metadata.manifestThemeColor,
     });
 
     const processed = html.replace(
@@ -418,6 +428,16 @@ export default function cmsPlugin(options = {}) {
     const sitemapUrl = sitemapXml ? getSitemapUrl(siteConfig) : '';
     const robotsBody = buildRobotsTxt(siteConfig, sitemapUrl);
     fs.writeFileSync(path.join(sitePublicDir, 'robots.txt'), robotsBody, 'utf-8');
+
+    // Web App Manifest. The template emits <link rel="manifest"> on every
+    // page; browsers use this to enable Add-to-Home-Screen + control
+    // splash colors when the site is launched from a homescreen icon.
+    const manifest = buildWebAppManifest(siteConfig);
+    fs.writeFileSync(
+      path.join(sitePublicDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2) + '\n',
+      'utf-8',
+    );
   };
 
   const cmsCore = {
@@ -538,8 +558,30 @@ export default function cmsPlugin(options = {}) {
         },
         ssgOptions: {
           dirStyle: 'nested',
+          // After vite-ssg pre-renders every route, copy the rendered
+          // dist/404/index.html to dist/404.html. AWS Amplify (and most
+          // static hosts) auto-serve a top-level 404.html for any
+          // unmatched URL with HTTP status 404, so this gives sites a
+          // proper not-found response without per-site config.
+          onFinished() {
+            const distDir = path.join(siteRoot, 'dist');
+            const nestedNotFound = path.join(distDir, '404', 'index.html');
+            const flatNotFound = path.join(distDir, '404.html');
+            if (fs.existsSync(nestedNotFound)) {
+              try {
+                fs.copyFileSync(nestedNotFound, flatNotFound);
+              } catch (err) {
+                console.warn(`[@koehler8/cms] failed to write 404.html: ${err.message}`);
+              }
+            }
+          },
           includedRoutes(paths) {
-            const staticRoutes = new Set(['/admin']);
+            // /admin is a vestigial placeholder; /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.
+            const staticRoutes = new Set(['/admin', '/404']);
             pagePaths.forEach((routePath) => staticRoutes.add(routePath));
 
             // Pre-render every page under each non-base locale prefix that
@@ -810,6 +852,7 @@ export const assetUrlMap = resolver.assetUrlMap;
               siteUrl: metadata.siteUrl,
               siteGoogleId: metadata.siteGoogleId,
               siteSameAsJson: metadata.siteSameAsJson,
+              manifestThemeColor: metadata.manifestThemeColor,
             });
 
             html = html.replace(