@koehler8/cms 1.0.0-beta.8 → 1.0.0

package/src/composables/usePageMeta.js

@@ -1,5 +1,22 @@
 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, toJsonLdString } from '../utils/jsonLd.js';
+import { buildBreadcrumbList } from '../utils/breadcrumbs.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: '',
@@ -35,13 +52,37 @@ 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 trailingSlash = computed(() => siteData.value?.site?.trailingSlash === true);
+  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"
+    // the URL bar already identifies the page.
+    if (isDraft.value) {
+      return site ? `Draft — ${site}` : 'Draft';
+    }
     const explicitTitle = page?.meta?.title;
     if (explicitTitle) {
       return explicitTitle;
@@ -54,6 +95,9 @@ export function usePageMeta({ siteData, currentPage }) {
   });
 
   const pageMetaDescription = computed(() => {
+    if (isDraft.value || isNotFound.value) {
+      return '';
+    }
     const explicitDescription = currentPage.value?.meta?.description;
     if (explicitDescription && explicitDescription.trim()) {
       return explicitDescription.trim();
@@ -61,16 +105,145 @@ 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 || '/',
+      trailingSlash: trailingSlash.value,
+    });
+  });
+
+  // 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,
+        trailingSlash: trailingSlash.value,
+      });
+      if (href) {
+        links.push({ rel: 'alternate', hreflang: code, href, key: `hreflang-${code}` });
+      }
+    }
+    const defaultHref = buildCanonicalUrl({
+      siteUrl: siteUrl.value,
+      locale: configBaseLocale,
+      baseLocale: configBaseLocale,
+      path,
+      trailingSlash: trailingSlash.value,
+    });
+    if (defaultHref) {
+      links.push({ rel: 'alternate', hreflang: 'x-default', href: defaultHref, key: 'hreflang-x-default' });
+    }
+    return links;
+  });
+
   useHead(() => {
     const description = pageMetaDescription.value;
-    const meta = description
-      ? [{ name: 'description', content: description, key: 'description' }]
-      : [];
+    const meta = [];
+    if (description) {
+      meta.push({ name: 'description', content: description, key: 'description' });
+    }
+    // 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,
+      locale: localeValue.value || configBaseLocale,
+      availableLocales: configAvailableLocales,
+    });
+    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' });
+    }
+    for (const entry of hreflangLinks.value) {
+      link.push(entry);
+    }
+
+    const script = buildJsonLdScripts({
+      siteData: siteData.value,
+      currentPage: currentPage.value,
+      isDraft: isDraft.value,
+      isNotFound: isNotFound.value,
+    });
+
+    // Auto-generated BreadcrumbList JSON-LD. Appended after any
+    // author-supplied jsonld blocks so authors can override by emitting a
+    // hand-authored BreadcrumbList of their own (Google takes the first
+    // valid one when multiple are present).
+    const breadcrumb = buildBreadcrumbList({
+      siteUrl: siteUrl.value,
+      currentPage: currentPage.value,
+      pages: siteData.value?.pages,
+      baseLocale: configBaseLocale,
+      locale: localeValue.value,
+      trailingSlash: trailingSlash.value,
+    });
+    if (breadcrumb && !isDraft.value && !isNotFound.value) {
+      script.push({
+        type: 'application/ld+json',
+        innerHTML: toJsonLdString(breadcrumb),
+        key: 'jsonld-BreadcrumbList',
+      });
+    }
+
     return {
+      // Reflect the page's locale on <html lang> during SSR/prerender so the
+      // on-disk HTML for /{locale}/... ships the right language (the router
+      // guard only sets this client-side, after hydration). Base-locale pages
+      // fall back to the configured base locale.
+      htmlAttrs: { lang: localeValue.value || configBaseLocale || 'en' },
       title: pageMetaTitle.value,
       meta,
+      link,
+      script,
     };
   });
 
-  return { pageMetaTitle, pageMetaDescription };
+  return { pageMetaTitle, pageMetaDescription, isDraft, isNotFound, canonicalHref, hreflangLinks };
 }

package/src/composables/usePromoBackgroundStyles.js

@@ -23,14 +23,34 @@ function selectLargestEntry(srcset = '') {
 }
 
 /**
- * Build a CSS background-image declaration that respects the neon backdrop toggle
- * and reuses the responsive image metadata returned by `useResponsiveImage`.
+ * Build a hero-background style binding that pairs a `url()` fallback with an
+ * `image-set()` upgrade. Returns an OBJECT with two CSS custom properties.
+ *
+ * Why an object with custom properties instead of a single `background-image`
+ * string: Vue 3's `:style` parses a string into a normalized object keyed by
+ * property name. A string with two `background-image` declarations
+ * (`background-image: url(...); background-image: image-set(...)`) collapses
+ * to a single entry — only the last value survives. This loses the
+ * progressive-enhancement chain that's the whole point of pairing a `url()`
+ * fallback with an `image-set()` upgrade. By emitting two custom properties,
+ * Vue keeps both, and the consuming CSS rule chains them as two real
+ * declarations of `background-image` so browsers walk the cascade naturally.
+ *
+ * Consumed by Hero.vue's `.promo-surface` rule, which declares:
+ *
+ *   background-image: var(--promo-bg-fallback);
+ *   background-image: var(--promo-bg-set, var(--promo-bg-fallback));
+ *
+ * Browsers that can parse `image-set()` (and its `type()` argument) use the
+ * second declaration; browsers that can't fall through to the first.
+ *
  * @param {object} options
  * @param {{
  *   sources: import('vue').MaybeRefOrGetter<Array<{ type: string, srcset: string }>>,
  *   fallbackSrc: import('vue').MaybeRefOrGetter<string>,
  *   fallbackFormat: import('vue').MaybeRefOrGetter<string>
  * }} options.imageSet
+ * @returns {import('vue').ComputedRef<Record<string, string> | null>}
  */
 export function usePromoBackgroundStyles({ imageSet }) {
   return computed(() => {
@@ -38,30 +58,26 @@ export function usePromoBackgroundStyles({ imageSet }) {
     const fallbackFormat = (unref(imageSet?.fallbackFormat) || 'jpg').toLowerCase();
     const sources = unref(imageSet?.sources) || [];
 
-    const formatEntries = [];
+    if (!fallbackSrc) return null;
 
+    const formatEntries = [];
     sources.forEach((source) => {
       const largest = selectLargestEntry(source?.srcset);
       if (largest) {
         formatEntries.push(`url("${largest}") type("${source?.type}") 1x`);
       }
     });
-
     if (fallbackSrc) {
       const fallbackMime = fallbackFormat === 'jpg' ? 'jpeg' : fallbackFormat;
       formatEntries.push(`url("${fallbackSrc}") type("image/${fallbackMime}") 1x`);
     }
 
-    const cssImageSet = formatEntries.length ? `image-set(${formatEntries.join(', ')})` : '';
-    let style = '';
-
-    if (fallbackSrc) {
-      style += `background-image: url("${fallbackSrc}");`;
-    }
-    if (cssImageSet) {
-      style += `background-image: ${cssImageSet};`;
+    const result = {
+      '--promo-bg-fallback': `url("${fallbackSrc}")`,
+    };
+    if (formatEntries.length) {
+      result['--promo-bg-set'] = `image-set(${formatEntries.join(', ')})`;
     }
-
-    return style;
+    return result;
   });
 }

package/src/extensions/extensionLoader.js

@@ -1,6 +1,5 @@
 import { defineAsyncComponent } from 'vue';
 
-import manifestSchema from '../../extensions/manifest.schema.json' with { type: 'json' };
 import { unwrapDefault as toPlainModule } from '../utils/unwrapDefault.js';
 
 const manifestModules = import.meta.glob('../../extensions/**/extension.config.json', {
@@ -23,22 +22,30 @@ const componentModules = import.meta.glob([
   '!**/*.spec.*',
 ]);
 
-// Lazy-load ajv via dynamic import — the static `import Ajv from 'ajv/...'`
-// fails when Vite serves this file outside the dep optimizer (CJS module
-// without a default export shim).  Dynamic import always gets the shim.
-let validateManifest;
-async function getValidator() {
-  if (!validateManifest) {
-    const [{ default: Ajv }, ajvFormats] = await Promise.all([
-      import('ajv/dist/2020'),
-      import('ajv-formats'),
-    ]);
-    const addFormats = ajvFormats.default || ajvFormats;
-    const ajv = new Ajv({ allErrors: true, strict: false });
-    addFormats(ajv);
-    validateManifest = ajv.compile(manifestSchema);
+// Structural sanity check only — full JSON-Schema validation runs at build
+// time in the Vite plugin (validateExtensionManifests), which FAILS the
+// build on an invalid manifest. This runtime check exists so a malformed
+// manifest handed straight to registerExtension() can't crash the loader,
+// and it is deliberately cheap: shipping ajv to the browser to re-validate
+// build-frozen JSON was ~40 KB of bundle for zero new information. Checks
+// only the fields the loader dereferences below.
+function describeManifestProblem(manifest) {
+  if (!manifest || typeof manifest !== 'object') {
+    return 'manifest is not an object';
+  }
+  if (typeof manifest.slug !== 'string' || !manifest.slug.trim()) {
+    return 'manifest.slug must be a non-empty string';
+  }
+  if (!Array.isArray(manifest.components)) {
+    return 'manifest.components must be an array';
+  }
+  for (const component of manifest.components) {
+    if (!component || typeof component !== 'object'
+      || typeof component.name !== 'string' || !component.name.trim()) {
+      return 'every manifest.components entry needs a non-empty string "name"';
+    }
   }
-  return validateManifest;
+  return null;
 }
 
 const extensionComponentRegistry = {};
@@ -128,10 +135,11 @@ await Promise.all(
       return;
     }
 
-    const validate = await getValidator();
-    const isValid = validate(manifest);
-    if (!isValid) {
-      warn(`Manifest at ${manifestPath} failed validation.`, validate.errors);
+    const problem = describeManifestProblem(manifest);
+    if (problem) {
+      // Not DEV-gated: this fires once at boot, and a silently missing
+      // extension in production is exactly the failure mode to surface.
+      console.warn(`[extensions] Manifest at ${manifestPath} is invalid (${problem}); skipping.`);
       return;
     }
 
@@ -290,10 +298,12 @@ export async function registerExtension(extensionModule) {
     throw new Error('[extensions] registerExtension() module must include a manifest');
   }
 
-  const validate = await getValidator();
-  const isValid = validate(manifest);
-  if (!isValid) {
-    warn(`External extension "${manifest.slug}" failed validation.`, validate.errors);
+  const problem = describeManifestProblem(manifest);
+  if (problem) {
+    // Not DEV-gated: one boot-time line beats an extension vanishing
+    // silently in production. Schema-level validation already failed the
+    // build if this manifest shipped through the Vite plugin.
+    console.warn(`[extensions] External extension "${manifest?.slug || '(unknown)'}" has an invalid manifest (${problem}); skipping.`);
     return;
   }
 

package/src/main.js

@@ -5,8 +5,8 @@ import { createHead } from '@unhead/vue/client';
 import App from './App.vue';
 import { routes, resolveHistory, applyRouterGuards } from './router/index.js';
 
-import { shouldEnableAnalytics, scheduleAnalyticsLoad } from './utils/cookieConsent.js';
-import { loadConfigData } from './utils/loadConfig.js';
+import { shouldEnableAnalytics, scheduleAnalyticsLoad, configureAnalyticsConsentMode } from './utils/cookieConsent.js';
+import { loadConfigData, primeConfigSync, trimConfigToPage, resolvePageIdForRoute } from './utils/loadConfig.js';
 import { persistAttributionFromLocation } from './utils/trackingContext.js';
 import { applyThemeVariables } from './themes/themeManager.js';
 import { setActiveThemeKey } from './utils/themeColors.js';
@@ -41,14 +41,29 @@ const extractThemeKey = (siteData) => {
 
 const applySiteTheme = (themeKey, head) => {
   const normalized = normalizeThemeKey(themeKey);
-  const resolved = normalized || 'base';
+
+  // No theme configured — leave `<html>` without `data-site-theme` so
+  // none of the `:root[data-site-theme="X"]` rules in the bundled
+  // virtual:cms-theme-vars.css apply. Components fall back to their
+  // hardcoded CSS defaults. Sites that intentionally want the bundled
+  // `base` palette must opt in via `"theme": "base"` in site.json (or
+  // any locale's site.json).
+  //
+  // (The implicit auto-apply of `base` was removed in 1.0.0-beta.12.
+  // It hid configuration mistakes — sites that registered a theme but
+  // forgot to activate it silently rendered with `base` instead of the
+  // theme they intended. Surfacing the misconfiguration via "no theme
+  // applied" is more honest.)
+  if (!normalized) {
+    return;
+  }
 
   // Push the html attribute via @unhead so `data-site-theme="X"` lands
   // in the SSR-rendered HTML *before* Vue hydrates. Theme CSS selectors
   // (`:root[data-site-theme="X"]`) then apply during the very first
   // paint, eliminating the need for site-side critical-CSS overrides.
   if (head && typeof head.push === 'function') {
-    head.push({ htmlAttrs: { 'data-site-theme': resolved } });
+    head.push({ htmlAttrs: { 'data-site-theme': normalized } });
   }
 
   // Client only: also set the attribute imperatively (so runtime theme
@@ -56,8 +71,8 @@ const applySiteTheme = (themeKey, head) => {
   // for themes that ship JS-only design tokens (e.g. the bundled `base`
   // theme has no theme.css).
   if (typeof document !== 'undefined') {
-    document.documentElement.dataset.siteTheme = resolved;
-    applyThemeVariables(resolved);
+    document.documentElement.dataset.siteTheme = normalized;
+    applyThemeVariables(normalized);
   }
 };
 
@@ -120,6 +135,21 @@ export function createCmsApp() {
       };
 
       const extractCurrentRoute = () => {
+        // During SSG, vite-ssg passes the route being pre-rendered as a string
+        // on `ctx.routePath` and only pushes the router AFTER this setup fn runs
+        // — so `router.currentRoute` is still vue-router's START_LOCATION ('/')
+        // here, identically on every page. Resolve `routePath` through the router
+        // (a pure match, no navigation) to recover the real path + `params.locale`.
+        // Without this, `resolveCurrentPageId` sees '/' for every route, so the
+        // payload trim targets the wrong page — or, when '/' is ambiguous, none.
+        const routePath = ctx?.routePath;
+        if (typeof routePath === 'string' && routePath) {
+          try {
+            return router.resolve(routePath);
+          } catch {
+            return { path: routePath, params: {} };
+          }
+        }
         if (ctx?.route) {
           return ctx.route;
         }
@@ -130,6 +160,18 @@ export function createCmsApp() {
         return null;
       };
 
+      // SSG only: resolve the route being pre-rendered to its page id so the
+      // embedded config can be trimmed to that single page when the site opts
+      // 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);
+        return resolvePageIdForRoute(config, rawPath, localeParam);
+      };
+
       const loadSiteConfig = async (options = {}) => {
         const requestedLocale =
           pickLocaleParam(options.locale) ??
@@ -143,6 +185,10 @@ export function createCmsApp() {
           initialState.siteTheme = existingTheme;
           setActiveThemeKey(existingTheme);
           applySiteTheme(existingTheme, ctx.head);
+          // Expose the server-resolved config for the first synchronous client
+          // render (see usePageConfig.hydrateFromSyncCache) so the prerendered
+          // DOM isn't replaced by an empty render while the async loader runs.
+          primeConfigSync(localeKey, initialState.siteConfig);
           return initialState.siteConfig;
         }
 
@@ -159,6 +205,22 @@ export function createCmsApp() {
       if (!isClient) {
         try {
           await loadSiteConfig();
+          // Payload trim (default ON since 1.0.0; opt out with
+          // `"trimInitialState": false`): embed only the current page's config
+          // in window.__INITIAL_STATE__ rather than every page's (the
+          // full-site blob is byte-identical on every page and can dominate
+          // page weight — measured 81% of page bytes on a profiled site).
+          // The rendered HTML body is unaffected — usePageConfig resolves the
+          // SSR render from its own loadConfigData() call, not from
+          // initialState — so this only shrinks the serialized hydration blob.
+          // 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);
+            if (currentPageId) {
+              initialState.siteConfig = trimConfigToPage(initialState.siteConfig, currentPageId);
+            }
+          }
         } catch (error) {
           console.error('Failed to load site configuration during SSG build', error);
         }
@@ -168,6 +230,7 @@ export function createCmsApp() {
       let siteData;
       try {
         siteData = await loadSiteConfig();
+        configureAnalyticsConsentMode(siteData?.site?.analytics?.consentMode);
         if (shouldEnableAnalytics()) {
           const googleId = siteData?.site?.googleId;
           if (googleId) scheduleAnalyticsLoad(googleId);