@koehler8/cms 1.0.0-beta.10

package/src/themes/themeLoader.js

@@ -0,0 +1,156 @@
+import baseManifest from '../../themes/base/theme.config.js';
+const cssModules = import.meta.glob('../../themes/**/theme.css', { eager: true });
+import { validateThemeManifest } from './themeValidator.js';
+
+const manifestModules = import.meta.glob(
+  [
+    '../../themes/**/theme.config.js',
+    '../../themes/**/theme.config.mjs',
+    '../../themes/**/theme.config.json',
+  ],
+  { eager: true }
+);
+
+const catalog = {};
+
+const normalizeSlug = (slug) =>
+  typeof slug === 'string' && slug.trim().length > 0 ? slug.trim().toLowerCase() : null;
+
+const cssMap = Object.keys(cssModules).reduce((acc, key) => {
+  const slugMatch = key.match(/\/themes\/([^/]+)\/theme\.css$/);
+  if (slugMatch) {
+    acc[slugMatch[1]] = key;
+  }
+  return acc;
+}, {});
+
+const addToCatalog = (manifest, sourceId, cssPath) => {
+  if (!manifest || typeof manifest !== 'object') return;
+  const normalized = normalizeSlug(manifest.slug);
+  try {
+    validateThemeManifest(manifest);
+  } catch (error) {
+    const message = error?.message || 'Unknown theme validation error';
+    throw new Error(`[theme-loader] ${message} (source: ${sourceId})`);
+  }
+  if (!normalized) {
+    throw new Error(`[theme-loader] Theme manifest missing slug (source: ${sourceId})`);
+  }
+  if (catalog[normalized]) {
+    console.warn(
+      `[theme-loader] Duplicate theme slug "${normalized}" detected. Source ${sourceId} skipped.`
+    );
+    return;
+  }
+
+  catalog[normalized] = {
+    ...manifest,
+    slug: normalized,
+    assets: {
+      ...manifest.assets,
+      css: manifest.assets?.css || cssPath || undefined,
+    },
+  };
+};
+
+// Auto-discover bundled themes (i.e. base)
+Object.entries(manifestModules).forEach(([path, module]) => {
+  const manifest = module?.default ?? module;
+  const slug = normalizeSlug(manifest?.slug);
+  const bundledCssPath = slug ? cssMap[slug] : undefined;
+  addToCatalog(manifest, path, bundledCssPath ? bundledCssPath.replace('../../', '') : undefined);
+});
+
+if (!catalog.base) {
+  addToCatalog(baseManifest, 'themes/base/theme.config.js', undefined);
+}
+
+/**
+ * Register an external theme package.
+ *
+ * Called by the Vite plugin for each theme passed via the `themes` option.
+ * Must be called before the first render (during app initialisation).
+ *
+ * Two patterns for shipping theme CSS:
+ *
+ *   1. **Side-effect import (preferred).** The theme's `index.js` imports
+ *      its `theme.css` for side effects:
+ *
+ *        import manifest from './theme.config.js';
+ *        import './theme.css';
+ *        export default { manifest };
+ *
+ *      Vite bundles `theme.css` into the main entry chunk and emits a
+ *      synchronous `<link rel="stylesheet">` in `<head>`, so theme rules
+ *      apply during the initial paint. Combined with the SSR-rendered
+ *      `data-site-theme` attribute (set in `applySiteTheme`), this
+ *      eliminates the FOUC that JS-injected theme CSS used to cause.
+ *
+ *   2. **Inline string (legacy).** The theme's `index.js` imports the CSS
+ *      with `?inline` and exports it as a `css` string:
+ *
+ *        import manifest from './theme.config.js';
+ *        import css from './theme.css?inline';
+ *        export default { manifest, css };
+ *
+ *      The CSS is injected via a runtime `<style>` tag (handled below).
+ *      This works but applies after Vue hydrates, so dark themes will
+ *      flash a light first paint unless the site provides critical CSS.
+ *
+ * Existing themes (cms-theme-neon, -frog, -aurora, -southpark, -swamp)
+ * still use pattern 2 and are supported indefinitely; new themes should
+ * prefer pattern 1.
+ *
+ * @param {object} themeModule - Default export from a @koehler8/cms-theme-* package
+ *   Expected shape: { manifest, css? } or just the manifest object directly.
+ */
+export function registerTheme(themeModule) {
+  if (!themeModule || typeof themeModule !== 'object') {
+    throw new Error('[theme-loader] registerTheme() requires a theme module object');
+  }
+
+  const manifest = themeModule.manifest || themeModule;
+  const cssContent = themeModule.css;
+  const sourceId = `external:${manifest?.slug || 'unknown'}`;
+
+  addToCatalog(manifest, sourceId, undefined);
+
+  // Legacy pattern 2: theme shipped inline CSS, inject it into the document head.
+  // For pattern 1 themes, `cssContent` is undefined and this block is skipped —
+  // the CSS is already loaded via Vite's bundling.
+  if (cssContent && typeof cssContent === 'string' && typeof document !== 'undefined') {
+    const slug = normalizeSlug(manifest.slug);
+    const existingStyle = document.getElementById(`theme-css-${slug}`);
+    if (!existingStyle) {
+      const style = document.createElement('style');
+      style.id = `theme-css-${slug}`;
+      style.textContent = cssContent;
+      document.head.appendChild(style);
+    }
+  }
+}
+
+export function getThemeCatalog() {
+  return catalog;
+}
+
+export function getThemeManifest(themeKey) {
+  if (typeof themeKey !== 'string') return null;
+  return catalog[themeKey.trim().toLowerCase()] || null;
+}
+
+export function resolveThemeManifest(themeKey) {
+  return (
+    getThemeManifest(themeKey) ||
+    catalog.base ||
+    Object.values(catalog)[0] ||
+    null
+  );
+}
+
+export function listThemeMetadata() {
+  return Object.values(catalog).map((manifest) => ({
+    slug: manifest.slug,
+    meta: manifest.meta,
+  }));
+}

package/src/themes/themeManager.js

@@ -0,0 +1,34 @@
+import { resolveThemeManifest } from './themeLoader.js';
+import { buildCssVarMap } from './buildCssVarMap.js';
+
+// buildCssVarMap was extracted to its own pure module so the build-time
+// vite plugin can call it (to emit `virtual:cms-theme-vars.css`) without
+// pulling in this file's runtime-only imports.
+
+export function applyThemeVariables(themeKey) {
+  const manifest = resolveThemeManifest(themeKey);
+  if (typeof document === 'undefined') {
+    return manifest;
+  }
+  const vars = buildCssVarMap(manifest);
+  const root = document.documentElement;
+
+  // Remove inline assignments from previous calls so normal cascade can apply.
+  Object.keys(vars).forEach((name) => root.style.removeProperty(name));
+
+  let styleTag = document.getElementById('theme-vars');
+  if (!styleTag) {
+    styleTag = document.createElement('style');
+    styleTag.id = 'theme-vars';
+    // Insert early so site/theme overrides loaded later can win via cascade.
+    const head = document.head || root;
+    head.insertBefore(styleTag, head.firstChild);
+  }
+
+  const cssBody = Object.entries(vars)
+    .map(([name, value]) => `${name}: ${value};`)
+    .join('\n  ');
+  styleTag.textContent = `:root {\n  ${cssBody}\n}`;
+
+  return manifest;
+}

package/src/themes/themeValidator.js

@@ -0,0 +1,380 @@
+const COLOR_PATTERN =
+  /^(#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})\b|rgba?\(|hsla?\(|var\(--|linear-gradient\(|radial-gradient\(|conic-gradient\(|color-mix\()/i;
+const CSS_UNIT_PATTERN = /^-?\d*\.?\d+(px|rem|em|vh|vw|%)$/i;
+
+const CTA_KEYS = ['bg', 'text', 'border', 'hoverBg', 'hoverBorder', 'shadow'];
+const CHIP_KEYS = ['bg', 'text', 'border'];
+
+const REQUIRED_BLOCKS = {
+  palette: [
+    'primary',
+    'primaryAccent',
+    'secondary',
+    'accent',
+    'accentSoft',
+    'neutral',
+    'neutralStrong',
+    'inverse',
+    'success',
+    'info',
+    'warning',
+    'critical',
+  ],
+  text: ['primary', 'muted', 'mutedStrong', 'inverse', 'accent', 'onAccent'],
+  surfaces: [
+    'base',
+    'baseAlt',
+    'raised',
+    'sunken',
+    'callout',
+    'card',
+    'cardAlt',
+    'overlay',
+    'backdrop',
+    'border',
+    'divider',
+    'input',
+    'chip',
+    'chipAccent',
+  ],
+  typography: [
+    'bodyFamily',
+    'headingFamily',
+    'monoFamily',
+    'baseSize',
+    'scale',
+    'weightRegular',
+    'weightMedium',
+    'weightBold',
+    'letterSpacingTight',
+    'letterSpacingWide',
+  ],
+  ctas: ['primary', 'secondary', 'ghost', 'link'],
+  chips: ['neutral', 'accent', 'outline'],
+  focus: ['ring', 'ringMuted', 'outline', 'shadowInset'],
+  radii: ['sm', 'md', 'lg', 'pill', 'full'],
+  elevation: ['flat', 'raised', 'overlay'],
+  utility: [
+    'divider',
+    'inputBorder',
+    'inputText',
+    'inputPlaceholder',
+    'selectionBg',
+    'selectionText',
+    'gradientHero',
+    'gradientPromo',
+    'bodyBackground',
+    'modalSurface',
+    'modalBorder',
+    'modalShadow',
+    'modalRadius',
+    'chartTrack',
+    'chartCenterText',
+    'statusHeadline',
+  ],
+};
+
+const NESTED_SURFACES = {
+  helper: ['background', 'hover', 'text', 'border', 'heading', 'body'],
+  tabs: [
+    'background',
+    'border',
+    'shadow',
+    'tabColor',
+    'activeBackground',
+    'activeColor',
+    'activeShadow',
+    'stepBackground',
+    'stepBorder',
+    'stepColor',
+    'activeStepBackground',
+    'activeStepBorder',
+    'activeStepColor',
+  ],
+  field: [
+    'background',
+    'border',
+    'shadow',
+    'addonBackground',
+    'addonBorder',
+    'addonColor',
+    'inputColor',
+    'inputPlaceholder',
+  ],
+  strip: ['background', 'border', 'text'],
+  chrome: ['background', 'text', 'shadow', 'compactShadow'],
+  backdropPrimary: ['background', 'before', 'after'],
+  backdropSecondary: ['background', 'before', 'after'],
+};
+
+const CTA_OVERRIDES = {
+  primary: { border: ensureString, hoverBorder: ensureString, shadow: ensureString },
+  secondary: { border: ensureString, hoverBorder: ensureString, shadow: ensureString },
+  ghost: { border: ensureString, hoverBorder: ensureString, shadow: ensureString },
+  link: { underline: ensureColor },
+};
+
+const CHIP_OVERRIDES = {
+  outline: { border: ensureString },
+};
+
+const SURFACE_NESTED_OVERRIDES = {
+  tabs: {
+    border: ensureString,
+    shadow: ensureString,
+    activeShadow: ensureString,
+    stepBorder: ensureString,
+    activeStepBorder: ensureString,
+  },
+  field: {
+    shadow: ensureString,
+    addonBorder: ensureString,
+  },
+  chrome: {
+    shadow: ensureString,
+    compactShadow: ensureString,
+  },
+};
+
+const UTILITY_VALIDATORS = {
+  divider: ensureColor,
+  inputBorder: ensureColor,
+  inputText: ensureColor,
+  inputPlaceholder: ensureColor,
+  selectionBg: ensureColor,
+  selectionText: ensureColor,
+  gradientHero: ensureColor,
+  gradientPromo: ensureColor,
+  bodyBackground: ensureColor,
+  modalSurface: ensureColor,
+  modalBorder: ensureColor,
+  modalShadow: ensureString,
+  modalRadius: (value, path, errors) => {
+    if (!isCssSize(value)) errors.push(`${path} must be a CSS size`);
+  },
+  chartTrack: ensureColor,
+  chartCenterText: ensureColor,
+  statusHeadline: ensureSurfaceOrColor,
+};
+
+function isString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isColor(value) {
+  if (!isString(value)) return false;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'transparent' || normalized === 'currentcolor' || normalized === 'none') {
+    return true;
+  }
+  return COLOR_PATTERN.test(normalized);
+}
+
+function isCssSize(value) {
+  if (typeof value === 'number') return true;
+  if (!isString(value)) return false;
+  const normalized = value.trim();
+  if (normalized === '0') return true;
+  return CSS_UNIT_PATTERN.test(normalized);
+}
+
+function ensureColor(value, path, errors) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => ensureColor(entry, `${path}[${index}]`, errors));
+    return;
+  }
+  if (!isColor(value)) {
+    errors.push(`${path} must be a CSS color/gradient value`);
+  }
+}
+
+function ensureSurfaceOrColor(value, path, errors) {
+  if (value && typeof value === 'object') {
+    if (!value.background) {
+      errors.push(`${path}.background is required`);
+    } else {
+      ensureColor(value.background, `${path}.background`, errors);
+    }
+    if (value.color) ensureColor(value.color, `${path}.color`, errors);
+    if (value.shadow) ensureString(value.shadow, `${path}.shadow`, errors);
+    if (value.border) ensureColor(value.border, `${path}.border`, errors);
+    if (value.valueColor) ensureColor(value.valueColor, `${path}.valueColor`, errors);
+    if (value.valueShadow) ensureString(value.valueShadow, `${path}.valueShadow`, errors);
+    return;
+  }
+  ensureColor(value, path, errors);
+}
+
+function ensureString(value, path, errors) {
+  if (!isString(value)) {
+    errors.push(`${path} must be a non-empty string`);
+  }
+}
+
+function ensureObject(value, path, errors) {
+  if (!value || typeof value !== 'object') {
+    errors.push(`${path} must be an object`);
+    return false;
+  }
+  return true;
+}
+
+function ensureKeys(obj, keys, path, errors, validator = ensureColor, overrides = {}) {
+  keys.forEach((key) => {
+    if (!(key in obj)) {
+      errors.push(`${path}.${key} is required`);
+      return;
+    }
+    const fieldValidator = overrides[key] || validator;
+    fieldValidator(obj[key], `${path}.${key}`, errors);
+  });
+}
+
+function validatePaletteBlock(tokens, errors) {
+  if (!ensureObject(tokens.palette, 'tokens.palette', errors)) return;
+  ensureKeys(tokens.palette, REQUIRED_BLOCKS.palette, 'tokens.palette', errors, ensureColor);
+}
+
+function validateTextBlock(tokens, errors) {
+  if (!ensureObject(tokens.text, 'tokens.text', errors)) return;
+  ensureKeys(tokens.text, REQUIRED_BLOCKS.text, 'tokens.text', errors, ensureColor);
+}
+
+function validateSurfaceBlock(tokens, errors) {
+  if (!ensureObject(tokens.surfaces, 'tokens.surfaces', errors)) return;
+  ensureKeys(tokens.surfaces, REQUIRED_BLOCKS.surfaces, 'tokens.surfaces', errors, ensureColor);
+  Object.entries(NESTED_SURFACES).forEach(([key, nestedKeys]) => {
+    const node = tokens.surfaces[key];
+    if (!ensureObject(node, `tokens.surfaces.${key}`, errors)) return;
+    ensureKeys(
+      node,
+      nestedKeys,
+      `tokens.surfaces.${key}`,
+      errors,
+      ensureColor,
+      SURFACE_NESTED_OVERRIDES[key] || {}
+    );
+  });
+}
+
+function validateTypography(tokens, errors) {
+  if (!ensureObject(tokens.typography, 'tokens.typography', errors)) return;
+  ensureKeys(tokens.typography, REQUIRED_BLOCKS.typography, 'tokens.typography', errors, (value, path) => {
+    if (typeof value === 'number') return;
+    if (!isString(value)) {
+      errors.push(`${path} must be a string or number`);
+    }
+  });
+}
+
+function validateCtas(tokens, errors) {
+  if (!ensureObject(tokens.ctas, 'tokens.ctas', errors)) return;
+  REQUIRED_BLOCKS.ctas.forEach((ctaKey) => {
+    const block = tokens.ctas[ctaKey];
+    if (!ensureObject(block, `tokens.ctas.${ctaKey}`, errors)) return;
+    const keys = ctaKey === 'link' ? ['text', 'hoverText', 'underline'] : CTA_KEYS;
+    ensureKeys(
+      block,
+      keys,
+      `tokens.ctas.${ctaKey}`,
+      errors,
+      ensureColor,
+      CTA_OVERRIDES[ctaKey] || {}
+    );
+  });
+}
+
+function validateChips(tokens, errors) {
+  if (!ensureObject(tokens.chips, 'tokens.chips', errors)) return;
+  REQUIRED_BLOCKS.chips.forEach((chipKey) => {
+    const block = tokens.chips[chipKey];
+    if (!ensureObject(block, `tokens.chips.${chipKey}`, errors)) return;
+    ensureKeys(
+      block,
+      CHIP_KEYS,
+      `tokens.chips.${chipKey}`,
+      errors,
+      ensureColor,
+      CHIP_OVERRIDES[chipKey] || {}
+    );
+  });
+}
+
+function validateFocus(tokens, errors) {
+  if (!ensureObject(tokens.focus, 'tokens.focus', errors)) return;
+  ensureKeys(tokens.focus, REQUIRED_BLOCKS.focus, 'tokens.focus', errors, ensureString);
+}
+
+function validateRadii(tokens, errors) {
+  if (!ensureObject(tokens.radii, 'tokens.radii', errors)) return;
+  ensureKeys(tokens.radii, REQUIRED_BLOCKS.radii, 'tokens.radii', errors, (value, path) => {
+    if (!isCssSize(value)) {
+      errors.push(`${path} must be a CSS size (px, rem, etc.)`);
+    }
+  });
+}
+
+function validateElevation(tokens, errors) {
+  if (!ensureObject(tokens.elevation, 'tokens.elevation', errors)) return;
+  ensureKeys(tokens.elevation, REQUIRED_BLOCKS.elevation, 'tokens.elevation', errors, ensureString);
+}
+
+function validateUtility(tokens, errors) {
+  if (!ensureObject(tokens.utility, 'tokens.utility', errors)) return;
+  REQUIRED_BLOCKS.utility.forEach((key) => {
+    const value = tokens.utility[key];
+    if (value === undefined || value === null || value === '') {
+      errors.push(`tokens.utility.${key} is required`);
+      return;
+    }
+    const validator = UTILITY_VALIDATORS[key] || ensureColor;
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => validator(entry, `tokens.utility.${key}[${index}]`, errors));
+      return;
+    }
+    validator(value, `tokens.utility.${key}`, errors);
+  });
+}
+
+export function validateThemeManifest(manifest, options = {}) {
+  const { throwOnError = true } = options;
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object') {
+    errors.push('Theme manifest must be an object');
+  } else {
+    if (!isString(manifest.slug)) {
+      errors.push('manifest.slug must be a non-empty string');
+    }
+    if (!ensureObject(manifest.meta, 'manifest.meta', errors)) {
+      // no-op
+    } else {
+      if (!isString(manifest.meta.name)) errors.push('manifest.meta.name is required');
+      if (!isString(manifest.meta.version)) errors.push('manifest.meta.version is required');
+    }
+    if (!ensureObject(manifest.tokens, 'manifest.tokens', errors)) {
+      // no-op
+    } else {
+      validatePaletteBlock(manifest.tokens, errors);
+      validateTextBlock(manifest.tokens, errors);
+      validateSurfaceBlock(manifest.tokens, errors);
+      validateTypography(manifest.tokens, errors);
+      validateCtas(manifest.tokens, errors);
+      validateChips(manifest.tokens, errors);
+      validateFocus(manifest.tokens, errors);
+      validateRadii(manifest.tokens, errors);
+      validateElevation(manifest.tokens, errors);
+      validateUtility(manifest.tokens, errors);
+    }
+  }
+
+  if (errors.length && throwOnError) {
+    const slug = manifest?.slug || 'unknown';
+    const error = new Error(
+      `Theme manifest "${slug}" is invalid:\n- ${errors.join('\n- ')}`
+    );
+    error.errors = errors;
+    throw error;
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/utils/analytics.js

@@ -0,0 +1,100 @@
+/**
+ * Lightweight Google Analytics helper that respects consent settings.
+ */
+import { shouldEnableAnalytics } from './cookieConsent.js';
+import { getAnalyticsContext } from './trackingContext.js';
+
+const SENSITIVE_KEYS = new Set(['wallet_address', 'account_address', 'private_key', 'seed_phrase']);
+
+function sanitizeParams(params = {}) {
+  if (!params || typeof params !== 'object') return {};
+  return Object.entries(params).reduce((acc, [key, value]) => {
+    const lowered = key.toLowerCase();
+    if (SENSITIVE_KEYS.has(lowered)) {
+      return acc;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      acc[key] = sanitizeParams(value);
+      return acc;
+    }
+    acc[key] = value;
+    return acc;
+  }, {});
+}
+
+function canTrack() {
+  if (typeof window === 'undefined') return false;
+  if (!shouldEnableAnalytics()) return false;
+  if (typeof window.gtag !== 'function') return false;
+  return true;
+}
+
+/**
+ * Send a GA4 event if analytics is ready.
+ * @param {string} name - GA4 event name.
+ * @param {Record<string, any>} [params] - Additional event parameters.
+ * @returns {boolean} True when the call was sent to gtag.
+ */
+export function trackEvent(name, params = {}) {
+  if (!name || typeof name !== 'string') {
+    if (import.meta.env.DEV) {
+      console.warn('[analytics] trackEvent requires a string name.');
+    }
+    return false;
+  }
+
+  if (!canTrack()) return false;
+
+  try {
+    const payload = sanitizeParams(params);
+    window.gtag('event', name, payload);
+    return true;
+  } catch (error) {
+    if (import.meta.env.DEV) {
+      console.warn('[analytics] Failed to send event', name, error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Set GA4 user properties.
+ * @param {Record<string, any>} properties
+ * @returns {boolean}
+ */
+export function setUserProperties(properties = {}) {
+  if (!properties || typeof properties !== 'object') return false;
+  if (!canTrack()) return false;
+  try {
+    window.gtag('set', 'user_properties', properties);
+    return true;
+  } catch (error) {
+    if (import.meta.env.DEV) {
+      console.warn('[analytics] Failed to set user_properties', error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Public helper to surface readiness in components if needed.
+ * @returns {boolean}
+ */
+export function isAnalyticsReady() {
+  return canTrack();
+}
+
+/**
+ * Alias kept for ergonomic imports in components.
+ */
+export function trackEventIfReady(name, params) {
+  return trackEvent(name, params);
+}
+
+export function trackFunnelEvent(name, params = {}) {
+  const payload = {
+    ...getAnalyticsContext(),
+    ...sanitizeParams(params),
+  };
+  return trackEvent(name, payload);
+}

package/src/utils/appInfo.js

@@ -0,0 +1,9 @@
+import packageJsonRaw from '../../package.json?raw';
+
+const packageJson = JSON.parse(packageJsonRaw);
+
+const envVersion = import.meta?.env?.VITE_APP_VERSION;
+
+export const APP_VERSION = (typeof envVersion === 'string' && envVersion.trim())
+  ? envVersion.trim()
+  : packageJson?.version || '0.0.0';