ferst-core 0.4.7 → 0.4.9

package/cms/theme-preview.js

@@ -0,0 +1,108 @@
+/**
+ * CMS design-tokens live preview (PDLC Phase 1 / WS4) — SPIKE artifact.
+ *
+ * Registers a Sveltia/Decap preview template for the `theme` file collection that
+ * embeds an iframe of the live site (?preview=1) and pushes the editor's CURRENT
+ * (unsaved) token values to it over postMessage — same-origin, since /admin and
+ * the site share the client domain. Re-themes live via ferst-core's site-side
+ * listener (lib/theme-preview.ts). Save is the CMS's existing git-proxy write.
+ *
+ * STATUS: unverified against the deployed Sveltia (pre-1.0; docs warn of Decap
+ * preview-template compat gaps). It is fully GUARDED — if the API isn't present or
+ * differs, it logs once and no-ops, so it can never break the CMS. The portal
+ * Theme Studio is the guaranteed token surface until the dev spike confirms this.
+ *
+ * Include from a client's public/admin/index.html AFTER the Sveltia bundle:
+ *   <script src="/ferst/theme-preview.js"></script>   (copied from ferst-core/cms)
+ */
+(function () {
+  'use strict';
+
+  var MSG = { theme: 'ferst:preview:theme', ready: 'ferst:preview:ready' };
+  // Match the CMS theme collection's fields (config.yml `theme` file).
+  var FIELDS = ['brand', 'ink', 'surface', 'corners', 'elevation', 'stroke', 'fields', 'darkDepth', 'darkChroma'];
+
+  function log(msg) {
+    try {
+      console.info('[ferst theme-preview] ' + msg);
+    } catch (_) {}
+  }
+
+  // Read the live entry into a themeSettings-shaped draft (Immutable Map API).
+  function draftFromEntry(entry) {
+    var get = function (k) {
+      try {
+        return entry && entry.getIn ? entry.getIn(['data', k]) : undefined;
+      } catch (_) {
+        return undefined;
+      }
+    };
+    var fonts = get('fonts') || {};
+    var ov = get('darkOverrides') || {};
+    var pick = function (o, k) {
+      return o && typeof o.get === 'function' ? o.get(k) : o ? o[k] : '';
+    };
+    return {
+      brand: get('brand') || '',
+      ink: get('ink') || '',
+      surface: get('surface') || '',
+      fonts: { heading: pick(fonts, 'heading') || '', body: pick(fonts, 'body') || '', display: pick(fonts, 'display') || '' },
+      corners: get('corners') || 'rounded',
+      elevation: get('elevation') || 'raised',
+      stroke: get('stroke') || 'on',
+      fields: get('fields') || 'boxed',
+      darkDepth: typeof get('darkDepth') === 'number' ? get('darkDepth') : 0.21,
+      darkChroma: typeof get('darkChroma') === 'number' ? get('darkChroma') : 0.05,
+      darkOverrides: { ground: pick(ov, 'ground') || '', text: pick(ov, 'text') || '', accent: pick(ov, 'accent') || '' },
+    };
+  }
+
+  function register(CMS, React) {
+    var Preview = function (props) {
+      // Keep one iframe of the live site in the preview pane; push the draft on
+      // every render (Sveltia re-renders as the editor types) and on ready.
+      var doc = props.document || document;
+      var frame = doc.getElementById('ferst-preview-frame');
+      if (!frame) {
+        frame = doc.createElement('iframe');
+        frame.id = 'ferst-preview-frame';
+        frame.src = '/?preview=1';
+        frame.style.cssText = 'width:100%;height:100%;min-height:80vh;border:0';
+        (doc.body || doc.documentElement).appendChild(frame);
+        (props.window || window).addEventListener('message', function (e) {
+          if (e && e.data && e.data.type === MSG.ready) postDraft();
+        });
+      }
+      function postDraft() {
+        try {
+          frame.contentWindow.postMessage({ type: MSG.theme, theme: draftFromEntry(props.entry) }, window.location.origin);
+        } catch (_) {}
+      }
+      postDraft();
+      // Render nothing of our own into React's tree — we own the iframe directly.
+      return React && React.createElement ? React.createElement('div', { style: { display: 'none' } }) : null;
+    };
+    CMS.registerPreviewTemplate('theme', Preview);
+    log('registered live preview for the theme collection');
+    void FIELDS; // documents the fields this mirrors
+  }
+
+  var tries = 0;
+  (function wait() {
+    var CMS = window.CMS;
+    var React = window.React || window.h || (CMS && CMS.React);
+    if (CMS && typeof CMS.registerPreviewTemplate === 'function') {
+      try {
+        register(CMS, React);
+      } catch (err) {
+        log('registerPreviewTemplate failed — in-pane preview disabled (use the portal Theme Studio). ' + (err && err.message));
+      }
+      return;
+    }
+    if (tries++ < 40) {
+      setTimeout(wait, 250); // CMS loads async as an ES module
+    } else {
+      log('CMS.registerPreviewTemplate not found — in-pane preview unavailable in this CMS build.');
+    }
+  })();
+})();

package/layouts/Base.astro

@@ -171,6 +171,15 @@ const metaDescription = description ?? identity.description;
       ferstMarkExternalLinks();
       document.addEventListener('astro:page-load', ferstMarkExternalLinks);
     </script>
+    <script>
+      // Live theme preview: only when this page is FRAMED with ?preview=1 (the
+      // portal Theme Studio or the CMS design-tokens pane), listen for draft theme
+      // settings over postMessage and re-theme live. Dynamically imported so the
+      // code never ships to normal visitors. Inert otherwise.
+      if (window.parent !== window && new URLSearchParams(location.search).has('preview')) {
+        import('../lib/theme-preview').then((m) => m.initThemePreviewListener());
+      }
+    </script>
   </head>
   <body>
     <SiteHeader

package/lib/theme-preview.ts

@@ -0,0 +1,91 @@
+/**
+ * Live theme preview (client-side). Lets an external editing surface — the portal
+ * Theme Studio, or the CMS design-tokens pane — push DRAFT theme settings into a
+ * loaded page over `postMessage`, so the whole site re-themes instantly with no
+ * rebuild. This is the "instant" preview lane of the Change-Request loop (see
+ * myai4-webdev/docs/PDLC-PREVIEW-ARCHITECTURE.md).
+ *
+ * Robust for ANY site: it re-runs the core's own `buildThemeStyle(draft)` in the
+ * browser and swaps a dedicated `<style id="ferst-preview">` — the same output the
+ * server emits at build time — instead of only setting inline `--brand/--ink/
+ * --surface` (which re-derive nothing on a not-yet-themed site). Injected late in
+ * <head>, it out-specifies the server theme block (`:root:root`), so the draft wins.
+ *
+ * Import ONLY from a component <script> (touches window/document). Gated by the
+ * caller to preview mode so it never runs for normal visitors.
+ */
+import { buildThemeStyle } from './themeTokens';
+import type { ThemeSettings } from '../content/schemas';
+
+/** postMessage protocol shared with the portal / CMS preview surfaces. */
+export const PREVIEW_MESSAGES = {
+  /** surface → page: apply this draft theme */
+  theme: 'ferst:preview:theme',
+  /** surface → page: switch light/dark */
+  mode: 'ferst:preview:mode',
+  /** page → surface: listener is live, send the current draft */
+  ready: 'ferst:preview:ready',
+} as const;
+
+const STYLE_ID = 'ferst-preview';
+
+/** Origins allowed to drive the preview (besides same-origin, i.e. the CMS pane).
+ *  The Ferst portal — both its custom domains and the bare Cloudflare Pages URLs
+ *  it's actually served from (dev has no custom domain today). */
+const PORTAL_ORIGINS = [
+  'https://portal.ferst.co.uk',
+  'https://portal-dev.ferst.co.uk',
+  'https://myai4-portal.pages.dev',
+  'https://myai4-portal-dev.pages.dev',
+];
+
+/** True for same-origin (CMS design-tokens pane) or a known Ferst portal origin. */
+export function isAllowedPreviewOrigin(origin: string): boolean {
+  try {
+    if (origin === window.location.origin) return true;
+  } catch {
+    /* no window (SSR/tests) — fall through to the allowlist */
+  }
+  return PORTAL_ORIGINS.includes(origin);
+}
+
+/** Re-theme the current document from a draft, via the core's own derivation. */
+export function applyPreviewTheme(theme: ThemeSettings): void {
+  const { css, field } = buildThemeStyle(theme);
+  const head = document.head;
+  let style = document.getElementById(STYLE_ID) as HTMLStyleElement | null;
+  if (!style) {
+    style = document.createElement('style');
+    style.id = STYLE_ID;
+    head.appendChild(style);
+  } else if (style !== head.lastElementChild) {
+    head.appendChild(style); // keep it last so it always wins over the server block
+  }
+  style.textContent = css;
+  if (field) document.documentElement.dataset.field = field;
+  else delete document.documentElement.dataset.field;
+}
+
+/** Wire the page to receive drafts from an allowed surface, and announce readiness. */
+export function initThemePreviewListener(): void {
+  window.addEventListener('message', (event: MessageEvent) => {
+    if (!isAllowedPreviewOrigin(event.origin)) return;
+    const data = event.data as { type?: string; theme?: ThemeSettings; mode?: string } | null;
+    if (!data || typeof data !== 'object') return;
+    if (data.type === PREVIEW_MESSAGES.theme && data.theme) {
+      try {
+        applyPreviewTheme(data.theme);
+      } catch {
+        /* a malformed draft must never break the preview page */
+      }
+    } else if (data.type === PREVIEW_MESSAGES.mode) {
+      document.documentElement.dataset.theme = data.mode === 'dark' ? 'dark' : 'light';
+    }
+  });
+  // Tell whoever framed us that we're listening, so it can push the current draft.
+  try {
+    window.parent?.postMessage({ type: PREVIEW_MESSAGES.ready }, '*');
+  } catch {
+    /* no parent / blocked — the surface can still push on its own timer */
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",
@@ -32,6 +32,7 @@
   ],
   "files": [
     "bin",
+    "cms",
     "components",
     "layouts",
     "content",