@koehler8/cms 1.0.0-beta.5

package/src/utils/siteStyles.js

@@ -0,0 +1,40 @@
+export function createSiteStyleLoader(styleModules) {
+  let loaded = false;
+  let loadPromise;
+
+  function ensureSiteStylesLoaded() {
+    if (loadPromise) return loadPromise;
+
+    const keys = Object.keys(styleModules);
+    if (!keys.length) {
+      loadPromise = Promise.resolve(false);
+      return loadPromise;
+    }
+
+    // Single site = single style module
+    const loader = styleModules[keys[0]];
+    loadPromise = Promise.resolve(loader())
+      .then(() => {
+        loaded = true;
+        return true;
+      })
+      .catch((error) => {
+        console.warn('[site-styles] Failed to load site CSS:', error);
+        return false;
+      });
+
+    return loadPromise;
+  }
+
+  return { ensureSiteStylesLoaded };
+}
+
+// ---- Runtime singleton ----
+let _ensureSiteStylesLoaded = () => Promise.resolve(false);
+
+export function setSiteStyleLoader(instance) {
+  if (!instance) return;
+  _ensureSiteStylesLoaded = instance.ensureSiteStylesLoaded;
+}
+
+export const ensureSiteStylesLoaded = (...args) => _ensureSiteStylesLoaded(...args);

package/src/utils/themeColors.js

@@ -0,0 +1,65 @@
+import { resolveThemeManifest } from '../themes/themeLoader.js';
+
+const toKebab = (value = '') =>
+  value
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+
+const HEX_FALLBACK_BY_COLOR = {
+  neon_pink: '#ff2d86',
+  crimson_red: '#d9164b',
+  sultry_purple: '#9a2eff',
+  electric_blue: '#27f3ff',
+  amber_heat: '#ffaa1d',
+  deep_violet: '#5a1b9d',
+};
+
+const normalizeKey = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+const derivePaletteMap = (manifest) => {
+  const map = {};
+  const palette = manifest?.tokens?.palette || {};
+  Object.entries(palette).forEach(([key, value]) => {
+    const kebab = normalizeKey(toKebab(key));
+    map[kebab] = value;
+  });
+  return map;
+};
+
+let activeThemeKey = 'base';
+let activePalette = derivePaletteMap(resolveThemeManifest(activeThemeKey));
+
+export function setActiveThemeKey(themeKey) {
+  const normalized =
+    typeof themeKey === 'string' && themeKey.trim() ? themeKey.trim().toLowerCase() : 'base';
+  activeThemeKey = normalized;
+  activePalette = derivePaletteMap(resolveThemeManifest(activeThemeKey));
+}
+
+export function resolveThemeColor(colorKey) {
+  if (!colorKey) return null;
+  const normalized = normalizeKey(colorKey);
+  return (
+    activePalette[normalized] ||
+    HEX_FALLBACK_BY_COLOR[colorKey.toLowerCase()] ||
+    HEX_FALLBACK_BY_COLOR[normalized] ||
+    null
+  );
+}
+
+export function resolveThemePalette(colorKeys = []) {
+  if (!Array.isArray(colorKeys)) return [];
+  return colorKeys
+    .map((key) => resolveThemeColor(key))
+    .filter((value) => Boolean(value));
+}
+
+export const DEFAULT_THEME_COLOR_ORDER = [
+  'neon_pink',
+  'sultry_purple',
+  'electric_blue',
+  'amber_heat',
+  'deep_violet',
+  'crimson_red',
+];

package/src/utils/trackingContext.js

@@ -0,0 +1,142 @@
+const ATTR_STORAGE_KEY = 'app_attribution_v1';
+const SESSION_STORAGE_KEY = 'app_session_id';
+
+function generateSessionId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `sess_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+}
+
+function readStoredJson(key, fallback = {}) {
+  if (typeof window === 'undefined') return { ...fallback };
+  try {
+    const raw = window.sessionStorage.getItem(key);
+    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);
+  }
+  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 detectDeviceType(userAgent = '') {
+  const ua = userAgent.toLowerCase();
+  if (!ua) {
+    if (typeof navigator !== 'undefined' && navigator.userAgent) {
+      return detectDeviceType(navigator.userAgent);
+    }
+    return 'unknown';
+  }
+  if (/tablet|ipad|playbook|silk/.test(ua)) return 'tablet';
+  if (/mobile|iphone|ipod|android|blackberry|iemobile|opera mini/.test(ua)) return 'mobile';
+  return 'desktop';
+}
+
+function getViewportBucket() {
+  if (typeof window === 'undefined') return 'unknown';
+  const width = window.innerWidth || 0;
+  if (width >= 1440) return 'xl';
+  if (width >= 1024) return 'lg';
+  if (width >= 768) return 'md';
+  if (width > 0) return 'sm';
+  return 'unknown';
+}
+
+function normalizeAttributionValue(value, fallback = 'unknown') {
+  if (!value || typeof value !== 'string') return fallback;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : fallback;
+}
+
+export function persistAttributionFromLocation() {
+  if (typeof window === 'undefined') return;
+
+  const params = new URLSearchParams(window.location.search || '');
+  const stored = readStoredJson(ATTR_STORAGE_KEY, {});
+
+  const next = { ...stored };
+
+  const utmSource = normalizeAttributionValue(params.get('utm_source'), stored.utm_source || 'direct');
+  const utmMedium = normalizeAttributionValue(params.get('utm_medium'), stored.utm_medium || 'none');
+  const utmCampaign = normalizeAttributionValue(params.get('utm_campaign'), stored.utm_campaign || '');
+  const utmTerm = normalizeAttributionValue(params.get('utm_term'), stored.utm_term || '');
+  const utmContent = normalizeAttributionValue(params.get('utm_content'), stored.utm_content || '');
+
+  next.utm_source = utmSource;
+  next.utm_medium = utmMedium;
+  next.utm_campaign = utmCampaign;
+  next.utm_term = utmTerm;
+  next.utm_content = utmContent;
+
+  if (!next.first_touch_timestamp) {
+    next.first_touch_timestamp = Date.now();
+  }
+
+  if (!next.landing_path && window.location.pathname) {
+    next.landing_path = window.location.pathname;
+  }
+
+  if (!next.referrer && document.referrer) {
+    next.referrer = document.referrer;
+  }
+
+  writeStoredJson(ATTR_STORAGE_KEY, next);
+
+  if (!window.sessionStorage.getItem(SESSION_STORAGE_KEY)) {
+    window.sessionStorage.setItem(SESSION_STORAGE_KEY, generateSessionId());
+  }
+}
+
+export function getAnalyticsContext(overrides = {}) {
+  const attribution = readStoredJson(ATTR_STORAGE_KEY, {
+    utm_source: 'direct',
+    utm_medium: 'none',
+    utm_campaign: '',
+    utm_term: '',
+    utm_content: '',
+    landing_path: typeof window !== 'undefined' ? window.location.pathname : '',
+  });
+
+  let sessionId = '';
+  if (typeof window !== 'undefined') {
+    sessionId =
+      window.sessionStorage.getItem(SESSION_STORAGE_KEY) ||
+      (() => {
+        const fresh = generateSessionId();
+        try {
+          window.sessionStorage.setItem(SESSION_STORAGE_KEY, fresh);
+        } catch {}
+        return fresh;
+      })();
+  }
+
+  const base = {
+    utm_source: attribution.utm_source || 'direct',
+    utm_medium: attribution.utm_medium || 'none',
+    utm_campaign: attribution.utm_campaign || '',
+    utm_term: attribution.utm_term || '',
+    utm_content: attribution.utm_content || '',
+    landing_path: attribution.landing_path || '',
+    referrer: attribution.referrer || '',
+    device_type: detectDeviceType(),
+    viewport: getViewportBucket(),
+    locale: (typeof document !== 'undefined' && document.documentElement?.lang) || '',
+    session_id: sessionId,
+    timestamp: Date.now(),
+  };
+
+  return { ...base, ...overrides };
+}

package/src/utils/unwrapDefault.js

@@ -0,0 +1,14 @@
+/**
+ * Unwrap an ESM module's default export.
+ * Returns `module.default` when a default export exists, otherwise the module itself.
+ * Returns `undefined` for falsy inputs.
+ * @param {*} module
+ * @returns {*}
+ */
+export function unwrapDefault(module) {
+  if (!module) return undefined;
+  if (typeof module === 'object' && 'default' in module) {
+    return module.default;
+  }
+  return module;
+}

package/src/utils/useScrollReveal.js

@@ -0,0 +1,48 @@
+let observer;
+
+function ensureObserver() {
+  if (observer || typeof window === 'undefined' || typeof IntersectionObserver === 'undefined') {
+    return observer;
+  }
+
+  observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.setAttribute('data-observed', 'true');
+          observer?.unobserve(entry.target);
+        }
+      });
+    },
+    {
+      threshold: 0.2,
+      rootMargin: '0px 0px -5% 0px',
+    }
+  );
+
+  return observer;
+}
+
+export function registerScrollReveal(elements) {
+  if (!elements) return;
+  let targets = [];
+  if (Array.isArray(elements)) {
+    targets = elements;
+  } else if (typeof elements[Symbol.iterator] === 'function' && typeof elements !== 'string') {
+    targets = Array.from(elements);
+  } else {
+    targets = [elements];
+  }
+
+  const io = ensureObserver();
+  if (!io) {
+    targets.forEach((el) => el && el.setAttribute('data-observed', 'true'));
+    return;
+  }
+
+  targets.forEach((el) => {
+    if (!el || el.dataset.observed === 'true') return;
+    el.setAttribute('data-observed', 'false');
+    io.observe(el);
+  });
+}

package/templates/index.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<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 %>">
+    <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>
+  </head>
+  <!-- Google Analytics is loaded dynamically after user consent -->
+  <body>
+    <main>
+      <div id="app"></div>
+    </main>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/themes/base/README.md

@@ -0,0 +1,23 @@
+# Core Base Theme
+- **Slug**: `base` (fallback when `site.theme` is omitted)
+- **Version**: 1.0.0
+- **Author**: Chris Koehler (source: internal)
+- **Assets**: `theme.config.js` only; no additional CSS beyond shared `base.css`/`layout.css`
+
+## Install
+- Leave `site.theme` empty to use this palette by default, or set `site.theme` to `"base"` explicitly in `sites/<site>/config/<site>.json`.
+- Reload the dev server after changing the config so Vite rehydrates with the selected theme metadata.
+
+## Visual Direction
+- Neutral/light marketing canvas with deep-blue headers, soft indigo gradients, and subtle glass borders.
+- CTA treatments lean on a cool blue gradient; secondary/ghost buttons stay minimal for operations dashboards and legal pages.
+- Suited for general-purpose launches where you want the shared UI utilities to feel native without brand-heavy art.
+
+## Token Highlights
+- Balanced light surfaces (`card`, `callout`, `tabs`, `field`) tuned for dark headers/footers and sticky chrome.
+- Consistent Inter/Clash typography stack baked into the manifest; no external CSS imports.
+- Gradient helpers (`gradientHero`, `gradientPromo`) pair with the default hero/promo layouts without requiring per-component overrides.
+
+## Compatibility Notes
+- Ideal baseline for new sites before a bespoke palette is approved.
+- Because there is no theme-specific CSS, any layout/animation customizations should live in your site’s optional `style.css` or a custom theme package.

package/themes/base/theme.config.js

@@ -0,0 +1,214 @@
+const sharedPrimary = '#4f6cf0';
+const sharedPrimaryDeep = '#243a80';
+const sharedSecondary = '#5c6ac4';
+const sharedAccent = '#f18f3b';
+const sharedNeutral = '#f5f7ff';
+const sharedNeutralAlt = '#edf1ff';
+const sharedText = '#1f2a44';
+
+export default {
+  slug: 'base',
+  meta: {
+    name: 'Core Base',
+    version: '1.0.0',
+    author: 'Chris Koehler',
+    source: 'internal',
+  },
+  tokens: {
+    palette: {
+      primary: sharedPrimary,
+      primaryAccent: sharedPrimaryDeep,
+      secondary: sharedSecondary,
+      accent: sharedAccent,
+      accentSoft: 'rgba(241, 143, 59, 0.22)',
+      neutral: sharedNeutral,
+      neutralStrong: sharedText,
+      neutralSoft: 'rgba(31, 42, 68, 0.85)',
+      inverse: '#ffffff',
+      success: '#239c65',
+      info: sharedPrimary,
+      warning: '#f2b05e',
+      critical: '#d04f4f',
+      criticalSoft: 'rgba(208, 79, 79, 0.18)',
+    },
+    text: {
+      primary: sharedText,
+      muted: '#54627b',
+      mutedStrong: 'rgba(31, 42, 68, 0.8)',
+      inverse: '#ffffff',
+      accent: sharedPrimary,
+      onAccent: '#ffffff',
+    },
+    surfaces: {
+      base: sharedNeutral,
+      baseAlt: sharedNeutralAlt,
+      raised: '#ffffff',
+      sunken: '#e8ecff',
+      callout: 'rgba(79, 108, 240, 0.08)',
+      card: '#ffffff',
+      cardAlt: 'rgba(255, 255, 255, 0.92)',
+      overlay: 'rgba(5, 6, 11, 0.88)',
+      backdrop: 'rgba(5, 6, 11, 0.65)',
+      border: 'rgba(79, 108, 240, 0.18)',
+      divider: 'rgba(79, 108, 240, 0.12)',
+      input: '#ffffff',
+      chip: 'rgba(79, 108, 240, 0.1)',
+      chipAccent: 'rgba(79, 108, 240, 0.16)',
+      helper: {
+        background: 'rgba(79, 108, 240, 0.08)',
+        hover: 'rgba(79, 108, 240, 0.12)',
+        text: sharedText,
+        border: 'rgba(79, 108, 240, 0.18)',
+        heading: sharedText,
+        body: 'rgba(31, 42, 68, 0.8)',
+      },
+      tabs: {
+        background: '#ffffff',
+        border: 'rgba(79, 108, 240, 0.18)',
+        shadow: '0 16px 32px rgba(15, 23, 42, 0.08)',
+        tabColor: '#54627b',
+        activeBackground: sharedPrimary,
+        activeColor: '#ffffff',
+        activeShadow: '0 16px 36px rgba(15, 23, 42, 0.12)',
+        stepBackground: 'rgba(79, 108, 240, 0.12)',
+        stepBorder: 'rgba(79, 108, 240, 0.35)',
+        stepColor: sharedPrimary,
+        activeStepBackground: sharedPrimary,
+        activeStepBorder: sharedPrimaryDeep,
+        activeStepColor: '#ffffff',
+      },
+      field: {
+        background: '#ffffff',
+        border: 'rgba(79, 108, 240, 0.25)',
+        shadow: '0 12px 24px rgba(10, 15, 30, 0.08)',
+        addonBackground: 'rgba(79, 108, 240, 0.08)',
+        addonBorder: 'rgba(79, 108, 240, 0.18)',
+        addonColor: sharedPrimary,
+        inputColor: sharedText,
+        inputPlaceholder: 'rgba(84, 98, 123, 0.64)',
+      },
+      strip: {
+        background: '#ffffff',
+        border: 'rgba(79, 108, 240, 0.18)',
+        text: sharedText,
+      },
+      chrome: {
+        background: '#05060b',
+        text: '#f0eaf3',
+        shadow: '0 18px 45px rgba(2, 3, 11, 0.6)',
+        compactShadow: '0 12px 32px rgba(2, 3, 11, 0.72)',
+      },
+      backdropPrimary: {
+        background: 'linear-gradient(135deg, #4f6cf0 0%, #243a80 100%)',
+        before: 'rgba(79, 108, 240, 0.12)',
+        after: 'rgba(36, 58, 128, 0.18)',
+      },
+      backdropSecondary: {
+        background: 'linear-gradient(135deg, #5c6ac4 0%, #4f6cf0 100%)',
+        before: 'rgba(92, 106, 196, 0.2)',
+        after: 'rgba(79, 108, 240, 0.2)',
+      },
+    },
+    typography: {
+      bodyFamily: '"Inter", "Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, sans-serif',
+      headingFamily:
+        '"Clash Display", "Inter", "Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, sans-serif',
+      monoFamily: '"JetBrains Mono", "SFMono-Regular", Menlo, Consolas, monospace',
+      baseSize: '16px',
+      scale: 1.125,
+      weightRegular: 400,
+      weightMedium: 500,
+      weightBold: 600,
+      letterSpacingTight: '-0.015em',
+      letterSpacingWide: '0.08em',
+    },
+    ctas: {
+      primary: {
+        bg: 'linear-gradient(135deg, #4f6cf0 0%, #243a80 100%)',
+        text: '#ffffff',
+        border: '1px solid rgba(255, 255, 255, 0.18)',
+        hoverBg: 'linear-gradient(135deg, #5c6ac4 0%, #243a80 100%)',
+        hoverBorder: '1px solid rgba(255, 255, 255, 0.22)',
+        shadow: '0 16px 32px rgba(32, 46, 104, 0.35)',
+      },
+      secondary: {
+        bg: '#ffffff',
+        text: sharedPrimary,
+        border: '1px solid rgba(79, 108, 240, 0.35)',
+        hoverBg: 'rgba(79, 108, 240, 0.08)',
+        hoverBorder: '1px solid rgba(79, 108, 240, 0.55)',
+        shadow: '0 8px 18px rgba(21, 32, 66, 0.18)',
+      },
+      ghost: {
+        bg: 'transparent',
+        text: sharedPrimary,
+        border: '1px solid rgba(79, 108, 240, 0.35)',
+        hoverBg: 'rgba(79, 108, 240, 0.08)',
+        hoverBorder: '1px solid rgba(79, 108, 240, 0.55)',
+        shadow: 'none',
+      },
+      link: {
+        text: sharedPrimary,
+        hoverText: sharedSecondary,
+        underline: 'rgba(79, 108, 240, 0.35)',
+      },
+    },
+    chips: {
+      neutral: {
+        bg: 'rgba(79, 108, 240, 0.1)',
+        text: sharedPrimaryDeep,
+        border: 'rgba(79, 108, 240, 0.18)',
+      },
+      accent: {
+        bg: 'rgba(92, 106, 196, 0.14)',
+        text: '#ffffff',
+        border: 'rgba(92, 106, 196, 0.4)',
+      },
+      outline: {
+        bg: 'transparent',
+        text: sharedPrimary,
+        border: '1px solid rgba(79, 108, 240, 0.35)',
+      },
+    },
+    focus: {
+      ring: '0 0 0 2px rgba(79, 108, 240, 0.35)',
+      ringMuted: '0 0 0 1px rgba(79, 108, 240, 0.22)',
+      outline: 'rgba(79, 108, 240, 0.6)',
+      shadowInset: 'inset 0 0 0 1px rgba(79, 108, 240, 0.25)',
+    },
+    radii: {
+      sm: '8px',
+      md: '14px',
+      lg: '24px',
+      pill: '999px',
+      full: '50%',
+    },
+    elevation: {
+      flat: '0 0 1px rgba(10, 15, 30, 0.12)',
+      raised: '0 18px 40px rgba(15, 23, 42, 0.12)',
+      overlay: '0 24px 48px rgba(15, 23, 42, 0.18)',
+    },
+    utility: {
+      divider: 'rgba(79, 108, 240, 0.12)',
+      inputBorder: 'rgba(79, 108, 240, 0.25)',
+      inputText: sharedText,
+      inputPlaceholder: 'rgba(84, 98, 123, 0.64)',
+      selectionBg: 'rgba(79, 108, 240, 0.25)',
+      selectionText: '#ffffff',
+      gradientHero: 'linear-gradient(135deg, #4f6cf0 0%, #243a80 100%)',
+      gradientPromo: 'linear-gradient(135deg, #5c6ac4 0%, #4f6cf0 100%)',
+      bodyBackground: [
+        'radial-gradient(circle at 18% 20%, rgba(79, 108, 240, 0.08), transparent 55%)',
+        'radial-gradient(circle at 80% 10%, rgba(241, 143, 59, 0.08), transparent 60%)',
+        'linear-gradient(180deg, #f8f9ff 0%, #eef1ff 100%)',
+      ],
+      modalSurface: 'rgba(255, 255, 255, 0.97)',
+      modalBorder: 'rgba(79, 108, 240, 0.18)',
+      modalShadow: '0 24px 48px rgba(15, 23, 42, 0.18)',
+      modalRadius: '24px',
+      chartTrack: 'rgba(236, 241, 255, 0.85)',
+      chartCenterText: sharedText,
+      statusHeadline: 'linear-gradient(120deg, rgba(79, 108, 240, 0.12), rgba(28, 42, 96, 0.14))',
+    },
+  },
+};