@koehler8/cms 1.0.0-beta.18 → 1.0.0-beta.20

package/package.json

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

package/src/components/Home.vue

@@ -90,7 +90,7 @@ const {
   attemptUnlock,
 } = useDraftGate({ siteData, currentPage });
 
-usePageMeta({ siteData, currentPage });
+usePageMeta({ siteData, currentPage, locale: () => props.locale });
 
 const {
   isComingSoonVisible,

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

@@ -75,6 +75,30 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
           };
         }
       }
+
+      // 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');

package/src/composables/usePageMeta.js

@@ -1,6 +1,9 @@
 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 { availableLocales as configAvailableLocales, baseLocale as configBaseLocale } from '../utils/loadConfig.js';
 
 const SPECIAL_PAGE_LABELS = {
   home: '',
@@ -36,17 +39,29 @@ function inferPageLabel(page) {
     .join(' / ');
 }
 
-export function usePageMeta({ siteData, currentPage }) {
+export function usePageMeta({ siteData, currentPage, locale }) {
   const siteTitle = computed(() => siteData.value?.site?.title || '');
   const siteDescription = computed(() => siteData.value?.site?.description || '');
+  const siteUrl = computed(() => siteData.value?.site?.url || '');
+  const localeValue = computed(() => {
+    if (typeof locale === 'function') return locale() || '';
+    if (typeof locale === 'string') return locale;
+    return '';
+  });
 
   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"
@@ -66,7 +81,7 @@ export function usePageMeta({ siteData, currentPage }) {
   });
 
   const pageMetaDescription = computed(() => {
-    if (isDraft.value) {
+    if (isDraft.value || isNotFound.value) {
       return '';
     }
     const explicitDescription = currentPage.value?.meta?.description;
@@ -76,20 +91,90 @@ export function usePageMeta({ siteData, currentPage }) {
     return siteDescription.value || '';
   });
 
+  // Canonical URL — base-locale URLs have no prefix; non-base locales get
+  // /{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 || isNotFound.value) return '';
+    if (!siteUrl.value) return '';
+    return buildCanonicalUrl({
+      siteUrl: siteUrl.value,
+      locale: localeValue.value,
+      baseLocale: configBaseLocale,
+      path: currentPage.value?.path || '/',
+    });
+  });
+
+  // hreflang alternates — only emitted when a site has more than one
+  // locale's content on disk. Includes one entry per available locale plus
+  // 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 || isNotFound.value) return [];
+    if (!siteUrl.value) return [];
+    if (!Array.isArray(configAvailableLocales) || configAvailableLocales.length <= 1) return [];
+    const path = currentPage.value?.path || '/';
+    const links = [];
+    for (const code of configAvailableLocales) {
+      const href = buildCanonicalUrl({
+        siteUrl: siteUrl.value,
+        locale: code,
+        baseLocale: configBaseLocale,
+        path,
+      });
+      if (href) {
+        links.push({ rel: 'alternate', hreflang: code, href, key: `hreflang-${code}` });
+      }
+    }
+    const defaultHref = buildCanonicalUrl({
+      siteUrl: siteUrl.value,
+      locale: configBaseLocale,
+      baseLocale: configBaseLocale,
+      path,
+    });
+    if (defaultHref) {
+      links.push({ rel: 'alternate', hreflang: 'x-default', href: defaultHref, key: 'hreflang-x-default' });
+    }
+    return links;
+  });
+
   useHead(() => {
     const description = pageMetaDescription.value;
     const meta = [];
     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);
+    const link = [];
+    if (canonicalHref.value) {
+      link.push({ rel: 'canonical', href: canonicalHref.value, key: 'canonical' });
+    }
+    for (const entry of hreflangLinks.value) {
+      link.push(entry);
+    }
     return {
       title: pageMetaTitle.value,
       meta,
+      link,
     };
   });
 
-  return { pageMetaTitle, pageMetaDescription, isDraft };
+  return { pageMetaTitle, pageMetaDescription, isDraft, isNotFound, canonicalHref, hreflangLinks };
 }

package/src/router/index.js

@@ -3,7 +3,7 @@ import { h } from 'vue';
 
 import Home from '../components/Home.vue';
 
-import { SUPPORTED_LOCALES } from '../constants/locales.js';
+import { availableLocales, baseLocale } from '../utils/loadConfig.js';
 
 const LocaleLayout = {
   name: 'LocaleLayout',
@@ -12,57 +12,85 @@ const LocaleLayout = {
   },
 };
 
-export const routes = [
-  {
+// Locales that should match the `/:locale/...` route — every available
+// locale on disk EXCEPT the base. The base locale is served at the
+// unprefixed path; emitting `/{baseLocale}/path` would be a duplicate URL.
+//
+// Read at module-load time. The vite-plugin's generated entry calls
+// setConfigLoader() synchronously before importing the app, so by the
+// time this module is evaluated (inside main.js), the singletons are
+// populated.
+function computeLocalePrefixes() {
+  if (!Array.isArray(availableLocales)) return [];
+  return availableLocales.filter((l) => typeof l === 'string' && l !== baseLocale);
+}
+
+export function buildRoutes(localePrefixes = computeLocalePrefixes()) {
+  const homeRoute = {
     path: '/',
     name: 'Home',
     component: Home,
     props: { pageId: 'home', pagePath: '/' },
-  },
-  {
-    path: `/:locale(${SUPPORTED_LOCALES.join('|')})`,
-    component: LocaleLayout,
-    children: [
-      {
-        path: '',
-        name: 'HomeLocale',
-        component: Home,
-        props: (route) => ({ pageId: 'home', pagePath: '/', locale: route.params.locale }),
-      },
-      {
-        path: ':pathMatch(.*)*',
-        name: 'LocaleDynamicPage',
-        component: Home,
-        props: (route) => {
-          const pathMatch = route.params.pathMatch;
-          const slugSegments = Array.isArray(pathMatch) ? pathMatch : [pathMatch || ''];
-          const rawSlug = `/${slugSegments.filter(Boolean).join('/')}`;
-          const normalizedSlug = rawSlug.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
-          return { pagePath: normalizedSlug, locale: route.params.locale };
-        },
-      },
-    ],
-  },
-  {
+  };
+
+  const catchAllRoute = {
     path: '/:pathMatch(.*)*',
     name: 'DynamicPage',
     component: Home,
     props: (route) => ({ pagePath: route.path || '/' }),
-  },
-];
+  };
+
+  if (!localePrefixes.length) {
+    // Single-locale site: don't register the locale-prefixed route at all.
+    // `/de/about` etc. fall into the catch-all → DynamicPage with a
+    // pagePath that won't match any page → home fallback.
+    return [homeRoute, catchAllRoute];
+  }
+
+  return [
+    homeRoute,
+    {
+      path: `/:locale(${localePrefixes.join('|')})`,
+      component: LocaleLayout,
+      children: [
+        {
+          path: '',
+          name: 'HomeLocale',
+          component: Home,
+          props: (route) => ({ pageId: 'home', pagePath: '/', locale: route.params.locale }),
+        },
+        {
+          path: ':pathMatch(.*)*',
+          name: 'LocaleDynamicPage',
+          component: Home,
+          props: (route) => {
+            const pathMatch = route.params.pathMatch;
+            const slugSegments = Array.isArray(pathMatch) ? pathMatch : [pathMatch || ''];
+            const rawSlug = `/${slugSegments.filter(Boolean).join('/')}`;
+            const normalizedSlug = rawSlug.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+            return { pagePath: normalizedSlug, locale: route.params.locale };
+          },
+        },
+      ],
+    },
+    catchAllRoute,
+  ];
+}
+
+export const routes = buildRoutes();
 
 function normalizeLocale(value = '') {
   return value.toLowerCase().split('-')[0];
 }
 
-export function applyRouterGuards(router) {
+export function applyRouterGuards(router, localePrefixes = computeLocalePrefixes()) {
   router.beforeEach((to) => {
     const rawLocale = (to.params.locale || '').toString().trim();
 
     if (rawLocale) {
       const normalized = normalizeLocale(rawLocale);
 
-      if (!SUPPORTED_LOCALES.includes(normalized)) {
+      if (!localePrefixes.includes(normalized)) {
         return { path: '/', replace: true };
       }
 
@@ -87,7 +115,7 @@ export function applyRouterGuards(router) {
       const navLang = (navigator.language || navigator.userLanguage || '').toString();
       const shortLang = normalizeLocale(navLang || '');
 
-      if (to.path === '/' && SUPPORTED_LOCALES.includes(shortLang)) {
+      if (to.path === '/' && localePrefixes.includes(shortLang)) {
         return { path: `/${shortLang}`, replace: true };
       }
     }

package/src/utils/canonicalUrl.js

@@ -0,0 +1,44 @@
+/**
+ * Single source of truth for the canonical URL formula.
+ *
+ * Used by:
+ *   - usePageMeta.js (emits <link rel="canonical"> + <link rel="alternate" hreflang>)
+ *   - sitemapGenerator.js (emits <loc> + <xhtml:link rel="alternate" hreflang>)
+ *
+ * URL space rule (matches Google / Stripe / GitHub conventions):
+ *   - Base locale → ${siteUrl}${path}     e.g. https://example.com/about
+ *   - Non-base    → ${siteUrl}/${locale}${path}   e.g. https://example.com/de/about
+ *
+ * Returns '' when siteUrl is missing — sitemaps require absolute URLs and
+ * canonical links without a host are useless. Callers treat '' as "skip".
+ */
+
+function normalizePath(value) {
+  if (typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let p = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  return p || '/';
+}
+
+function normalizeLocale(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim().toLowerCase();
+  return trimmed;
+}
+
+export function buildCanonicalUrl({ siteUrl, locale, baseLocale, path } = {}) {
+  const host = typeof siteUrl === 'string' ? siteUrl.trim().replace(/\/+$/, '') : '';
+  if (!host) return '';
+
+  const normalizedPath = normalizePath(path);
+  const loc = normalizeLocale(locale);
+  const base = normalizeLocale(baseLocale);
+
+  if (!loc || loc === base) {
+    return normalizedPath === '/' ? `${host}/` : `${host}${normalizedPath}`;
+  }
+
+  return normalizedPath === '/' ? `${host}/${loc}` : `${host}/${loc}${normalizedPath}`;
+}

package/src/utils/loadConfig.js

@@ -307,13 +307,16 @@ let _loadConfigData = async () => {
 };
 
 let _availableLocales = [];
+let _baseLocale = '';
 
 export function setConfigLoader(instance) {
   if (!instance) return;
   _loadConfigData = instance.loadConfigData;
   _availableLocales = instance.availableLocales || [];
+  _baseLocale = typeof instance.baseLocale === 'string' ? instance.baseLocale : '';
 }
 
 export { _availableLocales as availableLocales };
+export { _baseLocale as baseLocale };
 
 export const loadConfigData = (...args) => _loadConfigData(...args);

package/src/utils/sitemapGenerator.js

@@ -5,12 +5,14 @@
  * sitemap. Returns '' when site.url is missing (the sitemap protocol requires
  * absolute URLs); the plugin treats empty output as "do not write the file."
  *
- * v1 emits only <loc> per page. No <lastmod>, <changefreq>, <priority>, or
- * hreflang alternates yet — a page with a path is listed once with its
- * unprefixed canonical URL. Multi-locale sites can layer hreflang in later.
+ * Single-locale sites emit only <loc> per page. Multi-locale sites add
+ * <xhtml:link rel="alternate" hreflang="..." /> annotations per page (one
+ * per available locale plus an `x-default` pointing at the base-locale
+ * URL). The single-locale output stays byte-identical to pre-hreflang.
  */
 
 import { isPathDraft, normalizeDraftPath } from './draftMode.js';
+import { buildCanonicalUrl } from './canonicalUrl.js';
 
 function escapeXml(value) {
   return String(value).replace(/[<>&'"]/g, (c) => ({
@@ -22,7 +24,7 @@ function escapeXml(value) {
   }[c]));
 }
 
-export function buildSitemap(siteConfig) {
+export function buildSitemap(siteConfig, options = {}) {
   const siteUrl = (siteConfig?.site?.url || '').trim().replace(/\/+$/, '');
   if (!siteUrl) return '';
 
@@ -33,26 +35,61 @@ export function buildSitemap(siteConfig) {
   // the runtime gate; it is not advertised to crawlers.
   if (siteConfig?.site?.draft === true) return '';
 
+  const baseLocale = typeof options.baseLocale === 'string' ? options.baseLocale.toLowerCase() : '';
+  const availableLocales = Array.isArray(options.availableLocales)
+    ? options.availableLocales.map((l) => (typeof l === 'string' ? l.toLowerCase() : '')).filter(Boolean)
+    : [];
+  const isMultiLocale = availableLocales.length > 1;
+
   const pages = siteConfig?.pages || {};
-  const urls = new Set();
+  const entries = [];
+  const seenPaths = new Set();
 
   for (const [, pageData] of Object.entries(pages)) {
     if (!pageData || typeof pageData !== 'object') continue;
-    const path = normalizeDraftPath(pageData.path) || '/';
-    if (isPathDraft(siteConfig, path, pageData)) continue;
-    const url = path === '/' ? `${siteUrl}/` : `${siteUrl}${path}`;
-    urls.add(url);
+    const pagePath = normalizeDraftPath(pageData.path) || '/';
+    if (isPathDraft(siteConfig, pagePath, pageData)) continue;
+    if (seenPaths.has(pagePath)) continue;
+    seenPaths.add(pagePath);
+
+    const baseUrl = buildCanonicalUrl({ siteUrl, baseLocale, locale: baseLocale, path: pagePath });
+    if (!baseUrl) continue;
+
+    const alternates = isMultiLocale
+      ? availableLocales.map((loc) => ({
+          hreflang: loc,
+          href: buildCanonicalUrl({ siteUrl, baseLocale, locale: loc, path: pagePath }),
+        }))
+      : [];
+    if (isMultiLocale) {
+      alternates.push({ hreflang: 'x-default', href: baseUrl });
+    }
+
+    entries.push({ loc: baseUrl, alternates });
   }
 
-  if (urls.size === 0) return '';
+  if (entries.length === 0) return '';
+
+  entries.sort((a, b) => a.loc.localeCompare(b.loc));
+
+  const urlsetAttrs = isMultiLocale
+    ? 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
+
+  const renderUrlEntry = (entry) => {
+    if (entry.alternates.length === 0) {
+      return `  <url><loc>${escapeXml(entry.loc)}</loc></url>`;
+    }
+    const altLines = entry.alternates
+      .map((a) => `    <xhtml:link rel="alternate" hreflang="${escapeXml(a.hreflang)}" href="${escapeXml(a.href)}"/>`)
+      .join('\n');
+    return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n${altLines}\n  </url>`;
+  };
 
-  const sortedUrls = Array.from(urls).sort();
-  const urlEntries = sortedUrls
-    .map((loc) => `  <url><loc>${escapeXml(loc)}</loc></url>`)
-    .join('\n');
+  const urlEntries = entries.map(renderUrlEntry).join('\n');
 
   return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset ${urlsetAttrs}>
 ${urlEntries}
 </urlset>
 `;

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/templates/index.html

@@ -2,18 +2,14 @@
 <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,
+      and hreflang are emitted by usePageMeta at SSG render time. Site-wide
+      structured-data (the JSON-LD Organization snippet below) and the
+      static <link rel="icon"> remain in this template since they don't
+      vary per page.
+    -->
     <link rel="icon" href="/favicon.ico">
     <script type="application/ld+json">
     {

package/vite-plugin.js

@@ -12,7 +12,6 @@ import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import vue from '@vitejs/plugin-vue';
 
-import { SUPPORTED_LOCALES } from './src/constants/locales.js';
 import { inflateFlatConfig } from './src/utils/inflateFlatConfig.js';
 import { buildRobotsTxt } from './src/utils/robotsGenerator.js';
 import { buildSitemap, getSitemapUrl } from './src/utils/sitemapGenerator.js';
@@ -321,16 +320,22 @@ export default function cmsPlugin(options = {}) {
   const {
     siteDir: siteDirOption = './site',
     frameworkRoot: frameworkRootOption = __dirname,
-    locales = SUPPORTED_LOCALES,
     themes: themePackages = [],
     extensions: extensionPackages = [],
   } = options;
+  // The previous `locales` option is no longer accepted: per-site available
+  // locales are now discovered from on-disk content directories. Passing
+  // `locales` is silently ignored (kept here as a destructure to swallow it
+  // gracefully; the `SUPPORTED_LOCALES` constant remains exported only for
+  // any consumer that imports it directly).
 
   // These are resolved relative to the project cwd at config time
   let siteDir;
   let siteRoot; // project root — parent of siteDir
   let frameworkRoot;
   let siteConfig;
+  let baseLocale = 'en';
+  let availableLocales = [];
   let pagePaths;
   let metadata;
   let tempIndexPath;
@@ -399,7 +404,7 @@ export default function cmsPlugin(options = {}) {
     const sitePublicDir = path.join(siteRoot, 'public');
     fs.mkdirSync(sitePublicDir, { recursive: true });
 
-    const sitemapXml = buildSitemap(siteConfig);
+    const sitemapXml = buildSitemap(siteConfig, { availableLocales, baseLocale });
     const sitemapPath = path.join(sitePublicDir, 'sitemap.xml');
     if (sitemapXml) {
       fs.writeFileSync(sitemapPath, sitemapXml, 'utf-8');
@@ -435,12 +440,24 @@ export default function cmsPlugin(options = {}) {
       const contentConfig = fs.existsSync(contentConfigPath)
         ? JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'))
         : {};
-      const baseLocale = contentConfig.baseLocale || 'en';
+      baseLocale = contentConfig.baseLocale || 'en';
       const configDir = path.join(contentDir, baseLocale);
       siteConfig = loadSplitConfig(configDir);
       if (!siteConfig) {
         throw new Error(`[@koehler8/cms] site config not found at ${configDir}`);
       }
+      // Discover locales actually present on disk: directories under
+      // content/ that contain a site.json. This becomes the authoritative
+      // list for both the SSG route fanout and the runtime locale-aware
+      // canonical/hreflang emission.
+      availableLocales = fs.existsSync(contentDir)
+        ? fs
+            .readdirSync(contentDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .filter((name) => fs.existsSync(path.join(contentDir, name, 'site.json')))
+            .sort()
+        : [];
       pagePaths = collectPagePaths(siteConfig);
       metadata = extractSiteMetadata(siteConfig);
 
@@ -521,12 +538,40 @@ 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
+            // actually has a content directory on disk. The base locale is
+            // served at the unprefixed path (it's already covered by
+            // staticRoutes) — emitting `/{baseLocale}/path` would create
+            // duplicate URLs that all render the same content.
+            const localePrefixes = availableLocales.filter((l) => l !== baseLocale);
             const localizedRoutes = new Set();
-            locales.forEach((locale) => {
+            localePrefixes.forEach((locale) => {
               pagePaths.forEach((routePath) => {
                 const localized =
                   routePath === '/' ? `/${locale}` : `/${locale}${routePath}`;
@@ -620,7 +665,12 @@ const loader = createConfigLoader(allModules);
 export const loadConfigData = loader.loadConfigData;
 export const mergeConfigTrees = loader.mergeConfigTrees;
 export const cloneConfig = loader.cloneConfig;
-export const availableLocales = loader.availableLocales;
+// availableLocales + baseLocale are emitted as build-time literals derived
+// from the same on-disk discovery the plugin uses for SSG includedRoutes
+// and sitemap generation. This guarantees the runtime sees the exact same
+// locale list as the build, regardless of glob-based heuristics.
+export const availableLocales = ${JSON.stringify(availableLocales)};
+export const baseLocale = ${JSON.stringify(baseLocale)};
 `;
       }