@koehler8/cms 1.0.0-beta.8 → 1.0.0

package/src/utils/socialMeta.js

@@ -0,0 +1,100 @@
+/**
+ * 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,
+  locale,
+  availableLocales,
+} = {}) {
+  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' });
+
+  // og:locale mirrors the page's rendered language; alternates list the other
+  // locales the framework actually pre-renders (same set as hreflang). Bare
+  // language codes are emitted as-is — the framework's locale ids don't carry
+  // territories.
+  const currentLocale = typeof locale === 'string' ? locale.trim() : '';
+  if (currentLocale) {
+    meta.push({ property: 'og:locale', content: currentLocale, key: 'og:locale' });
+    const others = (Array.isArray(availableLocales) ? availableLocales : [])
+      .map((l) => (typeof l === 'string' ? l.trim() : ''))
+      .filter((l) => l && l !== currentLocale);
+    others.forEach((l) => {
+      meta.push({ property: 'og:locale:alternate', content: l, key: `og:locale:alternate:${l}` });
+    });
+  }
+
+  return meta;
+}

package/src/utils/ssgRoutes.js

@@ -0,0 +1,40 @@
+// Route sharding for `cms-ssg-build` — the opt-in durable memory bound for the
+// SSG pre-render. vite-ssg renders every route in one Node process and leaves a
+// fixed retained cost per route, so peak heap scales with total routes;
+// `cms-ssg-build` runs the render in N separate processes, each handling a slice
+// of the routes, so peak heap is bounded by slice size instead. This module is
+// the pure partition function so the slicing rules are unit-testable without a
+// build. See SSG-MEMORY-PLAN.md.
+
+// Routes every shard renders regardless of its slice. `/404` must be present in
+// each shard's output dir so that shard's `onFinished` can copy 404/index.html
+// → 404.html.
+export const ALWAYS_SHARDED_ROUTES = ['/404'];
+
+/**
+ * Return shard `k` of `N` from the full SSG route list.
+ *
+ * `shardSpec` is a `"k/N"` string (e.g. `"2/5"`). Shard k = the always-present
+ * routes + every Nth remaining route offset by k, so the N shards partition the
+ * non-always routes exactly once each (no route rendered twice, none dropped).
+ *
+ * Returns the full list unchanged when `shardSpec` is absent or malformed —
+ * this is the normal `vite-ssg build` path and must stay byte-identical.
+ */
+export function applyRouteShard(allRoutes, shardSpec) {
+  if (!Array.isArray(allRoutes)) return allRoutes;
+  const match = typeof shardSpec === 'string' ? shardSpec.trim().match(/^(\d+)\/(\d+)$/) : null;
+  if (!match) return allRoutes;
+
+  const k = Number(match[1]);
+  const n = Number(match[2]);
+  if (!(n > 0) || k < 0 || k >= n) return allRoutes;
+
+  const always = new Set(ALWAYS_SHARDED_ROUTES);
+  const alwaysRoutes = allRoutes.filter((route) => always.has(route));
+  const shardRoutes = allRoutes
+    .filter((route) => !always.has(route))
+    .filter((_, i) => i % n === k);
+
+  return Array.from(new Set([...alwaysRoutes, ...shardRoutes]));
+}

package/src/utils/trackingContext.js

@@ -1,5 +1,7 @@
-const ATTR_STORAGE_KEY = 'app_attribution_v1';
-const SESSION_STORAGE_KEY = 'app_session_id';
+import { STORAGE_KEYS, readStorage, writeStorage } from './webStorage.js';
+
+const ATTRIBUTION = STORAGE_KEYS.attribution;
+const SESSION_ID = STORAGE_KEYS.sessionId;
 
 function generateSessionId() {
   if (typeof crypto !== 'undefined' && crypto.randomUUID) {
@@ -8,28 +10,22 @@ function generateSessionId() {
   return `sess_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
 }
 
-function readStoredJson(key, fallback = {}) {
-  if (typeof window === 'undefined') return { ...fallback };
+function readStoredJson(entry, fallback = {}) {
   try {
-    const raw = window.sessionStorage.getItem(key);
+    const raw = readStorage(entry.kind, entry.key, entry.legacy);
     if (!raw) return { ...fallback };
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === 'object') {
       return { ...fallback, ...parsed };
     }
   } catch (error) {
-    console.warn('[trackingContext] Failed to read storage key', key, error);
+    console.warn('[trackingContext] Failed to read storage key', entry.key, error);
   }
   return { ...fallback };
 }
 
-function writeStoredJson(key, value) {
-  if (typeof window === 'undefined') return;
-  try {
-    window.sessionStorage.setItem(key, JSON.stringify(value));
-  } catch (error) {
-    console.warn('[trackingContext] Failed to write storage key', key, error);
-  }
+function writeStoredJson(entry, value) {
+  writeStorage(entry.kind, entry.key, JSON.stringify(value));
 }
 
 function detectDeviceType(userAgent = '') {
@@ -65,7 +61,7 @@ export function persistAttributionFromLocation() {
   if (typeof window === 'undefined') return;
 
   const params = new URLSearchParams(window.location.search || '');
-  const stored = readStoredJson(ATTR_STORAGE_KEY, {});
+  const stored = readStoredJson(ATTRIBUTION, {});
 
   const next = { ...stored };
 
@@ -93,15 +89,15 @@ export function persistAttributionFromLocation() {
     next.referrer = document.referrer;
   }
 
-  writeStoredJson(ATTR_STORAGE_KEY, next);
+  writeStoredJson(ATTRIBUTION, next);
 
-  if (!window.sessionStorage.getItem(SESSION_STORAGE_KEY)) {
-    window.sessionStorage.setItem(SESSION_STORAGE_KEY, generateSessionId());
+  if (!readStorage(SESSION_ID.kind, SESSION_ID.key, SESSION_ID.legacy)) {
+    writeStorage(SESSION_ID.kind, SESSION_ID.key, generateSessionId());
   }
 }
 
 export function getAnalyticsContext(overrides = {}) {
-  const attribution = readStoredJson(ATTR_STORAGE_KEY, {
+  const attribution = readStoredJson(ATTRIBUTION, {
     utm_source: 'direct',
     utm_medium: 'none',
     utm_campaign: '',
@@ -113,12 +109,10 @@ export function getAnalyticsContext(overrides = {}) {
   let sessionId = '';
   if (typeof window !== 'undefined') {
     sessionId =
-      window.sessionStorage.getItem(SESSION_STORAGE_KEY) ||
+      readStorage(SESSION_ID.kind, SESSION_ID.key, SESSION_ID.legacy) ||
       (() => {
         const fresh = generateSessionId();
-        try {
-          window.sessionStorage.setItem(SESSION_STORAGE_KEY, fresh);
-        } catch {}
+        writeStorage(SESSION_ID.kind, SESSION_ID.key, fresh);
         return fresh;
       })();
   }

package/src/utils/webAppManifest.js

@@ -0,0 +1,85 @@
+/**
+ * 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 [
+    // purpose 'any' only: the default icon isn't padded for the maskable
+    // safe zone, and claiming 'maskable' gets it cropped (Lighthouse flags
+    // the combined 'any maskable' for exactly this).
+    { src: '/favicon-256.png', sizes: '256x256', type: 'image/png', purpose: 'any' },
+    { 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/src/utils/webStorage.js

@@ -0,0 +1,82 @@
+/**
+ * Namespaced, guarded browser-storage access for framework state.
+ *
+ * All framework keys carry the `cms_` prefix so they cannot collide with
+ * site-author or extension keys on the same origin (the bare `locale` key in
+ * particular was a likely collision). Reads fall back to the pre-1.0
+ * unprefixed key and migrate the value forward, so returning visitors keep
+ * their consent choice and locale preference across the rename; the legacy
+ * key is left in place (harmless, and keeps still-cached pre-1.0 bundles
+ * working during a deploy window).
+ *
+ * Every access is guarded: Safari private mode and blocked-storage contexts
+ * throw on touch, and a storage failure must degrade to "no stored value" —
+ * never break the page.
+ */
+
+export const STORAGE_KEYS = {
+  locale: { kind: 'local', key: 'cms_locale', legacy: 'locale' },
+  consent: { kind: 'local', key: 'cms_cookie_consent', legacy: 'cookie_consent' },
+  consentTimestamp: { kind: 'local', key: 'cms_cookie_consent_timestamp', legacy: 'cookie_consent_timestamp' },
+  sessionId: { kind: 'session', key: 'cms_session_id', legacy: 'app_session_id' },
+  attribution: { kind: 'session', key: 'cms_attribution_v1', legacy: 'app_attribution_v1' },
+};
+
+function getStore(kind) {
+  try {
+    if (typeof window === 'undefined') return null;
+    return kind === 'session' ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a value. Falls back to `legacyKey` (migrating it forward) when the
+ * namespaced key is empty. Returns null when unavailable.
+ */
+export function readStorage(kind, key, legacyKey = '') {
+  const store = getStore(kind);
+  if (!store) return null;
+  try {
+    const value = store.getItem(key);
+    if (value !== null && value !== undefined) return value;
+    if (legacyKey) {
+      const legacy = store.getItem(legacyKey);
+      if (legacy !== null && legacy !== undefined) {
+        try {
+          store.setItem(key, legacy);
+        } catch {
+          /* migration is best-effort */
+        }
+        return legacy;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Write a value. Returns false (never throws) when storage is unavailable. */
+export function writeStorage(kind, key, value) {
+  const store = getStore(kind);
+  if (!store) return false;
+  try {
+    store.setItem(key, value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Convenience wrappers for the shared locale preference. */
+export function readStoredLocale() {
+  const { kind, key, legacy } = STORAGE_KEYS.locale;
+  return readStorage(kind, key, legacy);
+}
+
+export function writeStoredLocale(value) {
+  const { kind, key } = STORAGE_KEYS.locale;
+  return writeStorage(kind, key, value);
+}

package/templates/index.html

@@ -2,35 +2,28 @@
 <html lang="">
   <head>
     <meta charset="UTF-8">
-    <title><%= site %></title>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="description" content="<%= siteDescription %>">
-    <meta property="og:title" content="<%= site %>">
-    <meta property="og:description" content="<%= siteDescription %>">
-    <meta property="og:url" content="<%= siteUrl %>">
-    <meta property="og:type" content="website">
-    <meta property="og:image" content="<%= ABSOLUTE_OG_IMAGE %>">
-    <meta name="twitter:card" content="summary_large_image">
-    <meta name="twitter:title" content="<%= site %>">
-    <meta name="twitter:description" content="<%= siteDescription %>">
-    <meta name="twitter:image" content="<%= ABSOLUTE_OG_IMAGE %>">
+    <!--
+      Per-page <title>, <meta name="description">, og:*, twitter:*, canonical,
+      hreflang, and JSON-LD blocks are emitted by usePageMeta at SSG render
+      time. Site-wide invariants (favicon, web-app manifest, the JSON-LD
+      Organization snippet, mobile-chrome theme color) live here.
+    -->
     <link rel="icon" href="/favicon.ico">
-    <script type="application/ld+json">
-    {
-      "@context": "https://schema.org",
-      "@type": "Organization",
-      "name": "<%= site %>",
-      "url": "<%= siteUrl %>",
-      "logo": "<%= ABSOLUTE_LOGO %>",
-      "sameAs": <%- siteSameAsJson %>
-    }
-    </script>
+    <link rel="manifest" href="/manifest.json">
+    <meta name="theme-color" content="<%= manifestThemeColor %>">
+    <script type="application/ld+json"><%- organizationJsonLd %></script>
   </head>
   <!-- Google Analytics is loaded dynamically after user consent -->
   <body>
-    <main>
-      <div id="app"></div>
-    </main>
+    <noscript>
+      <style>
+        /* Scroll-reveal targets stay opacity:0 until JS observes them. If JS
+           never runs, force them visible so SSG content remains accessible. */
+        .fade-up-in { opacity: 1 !important; transform: none !important; }
+      </style>
+    </noscript>
+    <div id="app"></div>
     <script type="module" src="/src/main.js"></script>
   </body>
 </html>

package/templates/scaffolds/extension/README.md

@@ -0,0 +1,53 @@
+# cms-ext-__SLUG__
+
+__DISPLAY_NAME__ extension for [`@koehler8/cms`](https://github.com/koehler8/cms).
+
+## Status
+
+Starter scaffold. Currently empty (`components: []`). Add components as the design takes shape.
+
+## Activate
+
+After scaffolding (`npx cms-create-extension __SLUG__`), wire it into your site:
+
+```jsonc
+// package.json
+"dependencies": {
+  "cms-ext-__SLUG__": "file:./extensions/__SLUG__"
+}
+```
+
+```js
+// vite.config.js
+plugins: cms({
+  siteDir: './site',
+  extensions: ['cms-ext-__SLUG__'],
+}),
+```
+
+Run `npm install`, then build/preview.
+
+## Add a component
+
+1. Create `components/Foo.vue`. Follow the standard CMS pattern:
+   - Read content via `inject('pageContent')`
+   - Use `<style scoped>`
+   - Consume theme tokens via `var(--brand-*)`
+2. Add an entry to [extension.config.json](extension.config.json) `components[]` — `name`, `label`, `description`, `module`, `configKey`.
+3. Add a lazy dynamic import to [index.js](index.js)'s `components` map keyed by the same module path.
+4. Reference the component by name in any page's `components[]` array (e.g. `"components[N]": "Foo"`).
+5. Put translations under `content.{configKey}.*` in `pages/{pageId}.json`.
+
+## When to put a component here vs `site/components/`
+
+- **`site/components/`** — one-off components specific to a single site. Auto-globbed; no extension wrapper needed. **Default.**
+- **This extension** — components destined to be shared across multiple sites (e.g. eventually published to npm).
+
+## Extracting to a standalone repo
+
+Once the extension carries enough to be worth sharing:
+
+1. Copy `extensions/__SLUG__/` to a new repo named `cms-ext-__SLUG__/`
+2. Rename `name` in `package.json` to `@koehler8/cms-ext-__SLUG__` and add the standard repo metadata (homepage, bugs, repository) following the pattern of `@koehler8/cms-ext-compliance`
+3. Publish to GitHub Packages / npm
+4. Replace the `file:` dependency in each consuming site with the published version

package/templates/scaffolds/extension/extension.config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../node_modules/@koehler8/cms/extensions/manifest.schema.json",
+  "slug": "__SLUG__",
+  "version": "0.1.0",
+  "license": "MIT",
+  "provider": {
+    "name": "__DISPLAY_NAME__ extension"
+  },
+  "components": []
+}

package/templates/scaffolds/extension/index.js

@@ -0,0 +1,37 @@
+import manifest from './extension.config.json' with { type: 'json' };
+
+// Components contributed by this extension (use lazy dynamic imports so
+// Vite splits each into its own chunk). Key by the same module path
+// declared in extension.config.json's components[].module.
+//
+// To add a new component:
+//   1. Create components/Foo.vue.
+//   2. Add a {name, label, description, module, configKey} entry to
+//      extension.config.json's components[] array.
+//   3. Add a `'./components/Foo.vue': () => import('./components/Foo.vue')`
+//      entry to the map below.
+const components = {};
+
+// Optional setup() hook — runs once during app initialization with
+// { app, router, pinia, siteData, isClient }. Use it for runtime
+// concerns the manifest doesn't cover (e.g. mounting a banner Vue app
+// to document.body, registering a Pinia store, etc.). Remove if unused.
+//
+// async function setup({ app, router, pinia, siteData, isClient }) {
+//   // ...
+// }
+
+// Optional contentDefaults — a frozen object keyed by `configKey` that
+// the resolver merges underneath each component's content. Use it to
+// ship sensible defaults so consumer sites only override what they
+// want to change. Remove if unused.
+//
+// import contentDefaults from './content.defaults.json' with { type: 'json' };
+
+export default {
+  manifest,
+  components,
+  // setup,
+  // contentDefaults,
+};
+export { manifest };

package/templates/scaffolds/extension/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "cms-ext-__SLUG__",
+  "version": "0.1.0",
+  "description": "__DISPLAY_NAME__ extension for @koehler8/cms.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./config": "./extension.config.json"
+  },
+  "files": [
+    "index.js",
+    "extension.config.json",
+    "components",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@koehler8/cms": "^1.0.0"
+  }
+}

package/templates/scaffolds/site/.env.example

@@ -0,0 +1,7 @@
+# Site token used by some extensions and the provisioning tooling (safe to
+# leave as-is for a plain content site).
+VITE_TOKEN=__SLUG__
+
+# Optional: override the framework version string reported in the client
+# bundle (defaults to the installed @koehler8/cms package version).
+# VITE_APP_VERSION=

package/templates/scaffolds/site/.nvmrc

@@ -0,0 +1 @@
+20.19.0