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

package/bin/cms-generate-image-variants.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Wrapper that runs the framework's generate-image-variants.js from the
+// consuming site repo's CWD. Accepts --site-dir <path> to locate site assets;
+// defaults to ./site.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+let siteDir = './site';
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--site-dir' && args[i + 1]) {
+    siteDir = args[i + 1];
+    i++;
+  }
+}
+
+const resolvedSiteDir = path.resolve(process.cwd(), siteDir);
+process.env.CMS_SITE_DIR = resolvedSiteDir;
+
+const { generateVariants } = await import(
+  path.resolve(__dirname, '..', 'scripts', 'generate-image-variants.js')
+);
+
+try {
+  await generateVariants({ siteDir: resolvedSiteDir });
+} catch (err) {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.20",
+  "version": "1.0.0-beta.22",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,15 @@
   "bugs": {
     "url": "https://github.com/koehler8/cms/issues"
   },
-  "keywords": ["vue", "cms", "vite", "ssg", "theming", "extensions", "config-driven"],
+  "keywords": [
+    "vue",
+    "cms",
+    "vite",
+    "ssg",
+    "theming",
+    "extensions",
+    "config-driven"
+  ],
   "scripts": {
     "postinstall": "node scripts/patch-lru-cache-tla.js",
     "test": "vitest run",
@@ -46,6 +54,7 @@
   },
   "bin": {
     "cms-generate-public-assets": "./bin/cms-generate-public-assets.js",
+    "cms-generate-image-variants": "./bin/cms-generate-image-variants.js",
     "cms-validate-themes": "./bin/cms-validate-themes.js",
     "cms-validate-extensions": "./bin/cms-validate-extensions.js",
     "cms-create-theme": "./bin/cms-create-theme.js",
@@ -77,7 +86,8 @@
     "canvas": "^3.2.0",
     "dotenv": "^17.2.3",
     "pinia": "^3.0.1",
-    "png-to-ico": "^3.0.1"
+    "png-to-ico": "^3.0.1",
+    "sharp": "^0.33.5"
   },
   "devDependencies": {
     "@vue/test-utils": "^2.4.6",

package/scripts/generate-image-variants.js

@@ -0,0 +1,251 @@
+/**
+ * Generate responsive image variants from `{siteDir}/assets/img/_source/**`
+ * into `{siteDir}/assets/img/`.
+ *
+ * For each source image (jpg/jpeg/png/webp/avif/tiff), produces:
+ *   {name}-{width}.avif
+ *   {name}-{width}.webp
+ *   {name}-{width}.jpg
+ * across the configured widths. Subdirectory layout is preserved.
+ *
+ * Skips variants whose mtime is newer than the source's mtime — re-running
+ * the script after a `git pull` only regenerates the images that changed.
+ *
+ * Configuration is read from `{siteDir}/content/{baseLocale}/site.json`'s
+ * optional `imageVariants` block; defaults are sensible for marketing sites.
+ *
+ * Usage from a consuming site:
+ *   CMS_SITE_DIR=./site node node_modules/@koehler8/cms/scripts/generate-image-variants.js
+ *
+ * Or via the CLI wrapper:
+ *   npx cms-generate-image-variants --site-dir ./site
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+
+import { inflateFlatConfig } from '../src/utils/inflateFlatConfig.js';
+
+// ---- Configuration ----
+
+const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 2560];
+const DEFAULT_FORMATS = ['avif', 'webp', 'jpg'];
+const DEFAULT_QUALITY = { avif: 60, webp: 75, jpg: 80 };
+const SOURCE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.webp', '.avif', '.tiff', '.tif']);
+
+const FORMAT_OUTPUT_EXT = {
+  avif: 'avif',
+  webp: 'webp',
+  jpg: 'jpg',
+  jpeg: 'jpg',
+  png: 'png',
+};
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function resolveSiteConfig(siteDir) {
+  const contentDir = path.join(siteDir, 'content');
+  const contentConfig = readJsonIfExists(path.join(contentDir, 'content.config.json')) || {};
+  const baseLocale = contentConfig.baseLocale || 'en';
+  const sitePath = path.join(contentDir, baseLocale, 'site.json');
+  const raw = readJsonIfExists(sitePath) || {};
+  return inflateFlatConfig(raw);
+}
+
+function normalizeWidths(input) {
+  if (!Array.isArray(input)) return [...DEFAULT_WIDTHS];
+  const filtered = input
+    .map((v) => Number.parseInt(v, 10))
+    .filter((v) => Number.isFinite(v) && v > 0);
+  if (!filtered.length) return [...DEFAULT_WIDTHS];
+  return [...new Set(filtered)].sort((a, b) => a - b);
+}
+
+function normalizeFormats(input) {
+  if (!Array.isArray(input)) return [...DEFAULT_FORMATS];
+  const filtered = input
+    .map((v) => (typeof v === 'string' ? v.trim().toLowerCase() : ''))
+    .filter((v) => v && FORMAT_OUTPUT_EXT[v]);
+  if (!filtered.length) return [...DEFAULT_FORMATS];
+  return [...new Set(filtered)];
+}
+
+function normalizeQuality(input) {
+  const merged = { ...DEFAULT_QUALITY };
+  if (input && typeof input === 'object') {
+    for (const [k, v] of Object.entries(input)) {
+      const n = Number.parseInt(v, 10);
+      if (Number.isFinite(n) && n >= 1 && n <= 100) merged[k] = n;
+    }
+  }
+  return merged;
+}
+
+// Resolve `imageVariants` config block, with safe defaults.
+export function resolveImageVariantConfig(siteConfig) {
+  const block = (siteConfig?.imageVariants && typeof siteConfig.imageVariants === 'object')
+    ? siteConfig.imageVariants
+    : {};
+  return {
+    widths: normalizeWidths(block.widths),
+    formats: normalizeFormats(block.formats),
+    quality: normalizeQuality(block.quality),
+  };
+}
+
+// ---- File walking ----
+
+function* walkSourceImages(sourceDir) {
+  if (!fs.existsSync(sourceDir)) return;
+  const stack = [sourceDir];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!SOURCE_EXTENSIONS.has(ext)) continue;
+      yield full;
+    }
+  }
+}
+
+// Build the list of (sourcePath, outputs[]) jobs without doing IO yet.
+export function planVariantJobs({ siteDir, config }) {
+  const imgDir = path.join(siteDir, 'assets', 'img');
+  const sourceDir = path.join(imgDir, '_source');
+  const jobs = [];
+  if (!fs.existsSync(sourceDir)) return jobs;
+
+  for (const sourcePath of walkSourceImages(sourceDir)) {
+    const relFromSource = path.relative(sourceDir, sourcePath);
+    const parsed = path.parse(relFromSource);
+    const subdir = parsed.dir;
+    const baseName = parsed.name;
+
+    const outputs = [];
+    for (const width of config.widths) {
+      for (const format of config.formats) {
+        const ext = FORMAT_OUTPUT_EXT[format];
+        if (!ext) continue;
+        const outName = `${baseName}-${width}.${ext}`;
+        const outPath = path.join(imgDir, subdir, outName);
+        outputs.push({ width, format, outPath });
+      }
+    }
+    jobs.push({ sourcePath, outputs });
+  }
+  return jobs;
+}
+
+// Apply a per-output sharp transform pipeline.
+async function renderOutput(sourcePath, output, config) {
+  const { width, format, outPath } = output;
+  await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+
+  let pipeline = sharp(sourcePath, { failOn: 'truncated' }).rotate();
+  pipeline = pipeline.resize({ width, withoutEnlargement: true });
+  switch (format) {
+    case 'avif':
+      pipeline = pipeline.avif({ quality: config.quality.avif });
+      break;
+    case 'webp':
+      pipeline = pipeline.webp({ quality: config.quality.webp });
+      break;
+    case 'jpg':
+    case 'jpeg':
+      pipeline = pipeline.jpeg({ quality: config.quality.jpg, mozjpeg: true });
+      break;
+    case 'png':
+      pipeline = pipeline.png();
+      break;
+    default:
+      throw new Error(`unsupported format: ${format}`);
+  }
+  await pipeline.toFile(outPath);
+}
+
+function isUpToDate(sourcePath, outPath) {
+  if (!fs.existsSync(outPath)) return false;
+  try {
+    const src = fs.statSync(sourcePath).mtimeMs;
+    const dst = fs.statSync(outPath).mtimeMs;
+    return dst >= src;
+  } catch {
+    return false;
+  }
+}
+
+// ---- Main ----
+
+export async function generateVariants({ siteDir, log = console.log, warn = console.warn } = {}) {
+  if (!siteDir || !fs.existsSync(siteDir)) {
+    throw new Error(`siteDir does not exist: ${siteDir}`);
+  }
+  const siteConfig = resolveSiteConfig(siteDir);
+  const config = resolveImageVariantConfig(siteConfig);
+  const jobs = planVariantJobs({ siteDir, config });
+  if (jobs.length === 0) {
+    log(`[cms-image-variants] no sources found under ${path.join(siteDir, 'assets', 'img', '_source')}`);
+    return { generated: 0, skipped: 0, sources: 0 };
+  }
+
+  let generated = 0;
+  let skipped = 0;
+  for (const { sourcePath, outputs } of jobs) {
+    for (const output of outputs) {
+      if (isUpToDate(sourcePath, output.outPath)) {
+        skipped += 1;
+        continue;
+      }
+      try {
+        await renderOutput(sourcePath, output, config);
+        generated += 1;
+      } catch (err) {
+        warn(`[cms-image-variants] failed ${path.relative(siteDir, output.outPath)}: ${err.message}`);
+      }
+    }
+  }
+  log(
+    `[cms-image-variants] sources: ${jobs.length}, generated: ${generated}, skipped (up-to-date): ${skipped}`,
+  );
+  return { generated, skipped, sources: jobs.length };
+}
+
+// Allow invocation as `node scripts/generate-image-variants.js` (used by the
+// bin wrapper). Reads CMS_SITE_DIR like generate-public-assets does.
+const isMain = (() => {
+  try {
+    const __filename = new URL(import.meta.url).pathname;
+    return process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  const siteDir = process.env.CMS_SITE_DIR
+    ? path.resolve(process.env.CMS_SITE_DIR)
+    : null;
+  if (!siteDir) {
+    console.error('❌ CMS_SITE_DIR environment variable is required.');
+    console.error('   Example: CMS_SITE_DIR=./site npx cms-generate-image-variants');
+    process.exit(1);
+  }
+  generateVariants({ siteDir }).catch((err) => {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  });
+}

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,6 +73,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
             content: data.content || {},
             meta: data.meta || {},
             draft: data.draft,
+            jsonld: data.jsonld,
           };
         }
       }
@@ -113,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

@@ -3,8 +3,21 @@ 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 { 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: '',
   terms: 'Terms of Service',
@@ -162,6 +175,22 @@ export function usePageMeta({ siteData, currentPage, locale }) {
       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' });
@@ -169,10 +198,38 @@ 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,
+    });
+
+    // 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,
+    });
+    if (breadcrumb && !isDraft.value && !isNotFound.value) {
+      script.push({
+        type: 'application/ld+json',
+        innerHTML: JSON.stringify(breadcrumb),
+        key: 'jsonld-BreadcrumbList',
+      });
+    }
+
     return {
       title: pageMetaTitle.value,
       meta,
       link,
+      script,
     };
   });
 

package/src/utils/breadcrumbs.js

@@ -0,0 +1,118 @@
+/**
+ * Build a JSON-LD `BreadcrumbList` for the current page from URL path
+ * segments and the inflated pages map. Drives Google's breadcrumb display
+ * in search results without authors having to hand-author the schema.
+ *
+ * Returns `null` when breadcrumbs aren't applicable (home, draft, 404,
+ * single-segment path with no resolvable hierarchy, missing site.url, or
+ * per-page opt-out via `currentPage.meta.breadcrumbs === false`).
+ *
+ * Label resolution priority for each path prefix `/seg1/seg2/...`:
+ *   1. A page in the inflated config whose `path` matches → its
+ *      `meta.title`, falling back to a slug-derived title-case label.
+ *   2. Otherwise → the last segment formatted (`my-post-title` →
+ *      `My Post Title`).
+ *
+ * The first entry is always `Home` linked at the canonical home URL. The
+ * last entry is the current page; its `item` URL is included (Google
+ * accepts both forms; including is more interoperable).
+ */
+
+import { buildCanonicalUrl } from './canonicalUrl.js';
+
+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 titleCaseSlug(slug) {
+  if (typeof slug !== 'string') return '';
+  return slug
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function findPageByPath(pages, targetPath) {
+  if (!pages || typeof pages !== 'object') return null;
+  const norm = normalizePath(targetPath);
+  for (const data of Object.values(pages)) {
+    if (!data || typeof data !== 'object') continue;
+    if (normalizePath(data.path) === norm) return data;
+  }
+  return null;
+}
+
+function resolveLabel(pages, prefixPath, lastSegment) {
+  const page = findPageByPath(pages, prefixPath);
+  const explicitTitle = page?.meta?.title;
+  if (typeof explicitTitle === 'string' && explicitTitle.trim()) {
+    return explicitTitle.trim();
+  }
+  return titleCaseSlug(lastSegment) || lastSegment || '';
+}
+
+export function buildBreadcrumbList({
+  siteUrl,
+  currentPage,
+  pages,
+  baseLocale,
+  locale,
+} = {}) {
+  if (!currentPage || typeof currentPage !== 'object') return null;
+  if (currentPage.isNotFound) return null;
+  if (currentPage.draft === true) return null;
+  if (currentPage.meta && currentPage.meta.breadcrumbs === false) return null;
+
+  const host = (typeof siteUrl === 'string' ? siteUrl : '').trim().replace(/\/+$/, '');
+  if (!host) return null;
+
+  const targetPath = normalizePath(currentPage.path);
+  if (targetPath === '/' || targetPath === '') return null;
+
+  const segments = targetPath.split('/').filter(Boolean);
+  if (segments.length === 0) return null;
+
+  const homeHref = buildCanonicalUrl({
+    siteUrl: host,
+    locale,
+    baseLocale,
+    path: '/',
+  });
+
+  const items = [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: 'Home',
+      item: homeHref,
+    },
+  ];
+
+  for (let i = 0; i < segments.length; i++) {
+    const prefixPath = `/${segments.slice(0, i + 1).join('/')}`;
+    const href = buildCanonicalUrl({
+      siteUrl: host,
+      locale,
+      baseLocale,
+      path: prefixPath,
+    });
+    items.push({
+      '@type': 'ListItem',
+      position: items.length + 1,
+      name: resolveLabel(pages, prefixPath, segments[i]),
+      item: href,
+    });
+  }
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items,
+  };
+}

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/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

@@ -5,12 +5,13 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <!--
       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.
+      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 = {
@@ -832,6 +852,7 @@ export const assetUrlMap = resolver.assetUrlMap;
               siteUrl: metadata.siteUrl,
               siteGoogleId: metadata.siteGoogleId,
               siteSameAsJson: metadata.siteSameAsJson,
+              manifestThemeColor: metadata.manifestThemeColor,
             });
 
             html = html.replace(