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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.19",
+  "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/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

@@ -2,6 +2,7 @@ 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 = {
@@ -51,10 +52,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 +81,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 +92,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 +111,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 +145,23 @@ 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);
     const link = [];
     if (canonicalHref.value) {
       link.push({ rel: 'canonical', href: canonicalHref.value, key: 'canonical' });
@@ -155,5 +176,5 @@ export function usePageMeta({ siteData, currentPage, locale }) {
     };
   });
 
-  return { pageMetaTitle, pageMetaDescription, isDraft, canonicalHref, hreflangLinks };
+  return { pageMetaTitle, pageMetaDescription, isDraft, isNotFound, canonicalHref, hreflangLinks };
 }

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

@@ -538,8 +538,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