@bygghammar/cms-platform 0.57.1 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.59.0
+
+- Added `site/routes/public-page`, `site/routes/preview-page` and
+  `site/routes/section-preview`: the catch-all public page route engine, the
+  page-builder preview (draft store, editor handshake, block selection) and the
+  standalone content-section preview are now package-owned. Sites keep thin
+  route wrappers supplying data sources, chrome and copy.
+- Drift guard manifest now covers the three route wrappers.
+
+## 0.58.0
+
+- Utilities sweep: the public-page context loader (`site/page-context`), the
+  deployment origin resolver (`site/public-origin`), the self-hosted font bundle
+  (`site/font-bundle`) and the version screen's build/release metadata
+  (`admin/version-core`) are now package-owned factories. Sites pass their own
+  data sources, compiled origin and font assets.
+- New drift guard: `config/package-owned-modules` lists every module a site must
+  keep as a thin wrapper, so a site test fails the build if platform behaviour is
+  reimplemented locally.
+
 ## 0.57.0
 
 - Server-function inputs are now platform contracts: `server/schemas` ships the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.57.1",
+  "version": "0.59.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": [
@@ -172,6 +172,11 @@
     "./backoffice/ResetPasswordView": "./src/backoffice/ResetPasswordView.tsx",
     "./backoffice/routes/pages": "./src/backoffice/routes/pages.tsx",
     "./config/define-site": "./src/config/define-site.ts",
+    "./site/page-context": "./src/site/page-context.ts",
+    "./site/public-origin": "./src/site/public-origin.ts",
+    "./site/font-bundle": "./src/site/font-bundle.ts",
+    "./admin/version-core": "./src/admin/version-core.ts",
+    "./config/package-owned-modules": "./src/config/package-owned-modules.ts",
     "./server/schema-drift": "./src/server/schema-drift.ts",
     "./server/media-focus-core": "./src/server/media-focus-core.ts",
     "./server/media-meta-core": "./src/server/media-meta-core.ts",
@@ -207,7 +212,10 @@
     "./site/SiteHeader": "./src/site/SiteHeader.tsx",
     "./site/SiteFooter": "./src/site/SiteFooter.tsx",
     "./server/schemas": "./src/server/schemas.ts",
-    "./server/page-seo-save-core": "./src/server/page-seo-save-core.ts"
+    "./server/page-seo-save-core": "./src/server/page-seo-save-core.ts",
+    "./site/routes/public-page": "./src/site/routes/public-page.tsx",
+    "./site/routes/preview-page": "./src/site/routes/preview-page.tsx",
+    "./site/routes/section-preview": "./src/site/routes/section-preview.tsx"
   },
   "dependencies": {
     "fflate": "^0.8.3"
@@ -285,4 +293,4 @@
     "cms-platform-migrations": "scripts/sync-migrations.mjs",
     "create-cms-site": "./scripts/create-cms-site.mjs"
   }
-}
+}

package/src/admin/version-core.ts

@@ -0,0 +1,76 @@
+/**
+ * Build metadata and platform release history for the version screen.
+ *
+ * The build constants are injected by the site's Vite config (they must be, the
+ * values only exist at build time); reading them defensively and fetching the
+ * package's published releases is identical everywhere, so it lives here.
+ */
+
+export type BuildInfo = {
+  appVersion: string;
+  buildTime: string;
+  platformVersion: string;
+  platformRange: string;
+};
+
+export type PlatformRelease = {
+  version: string;
+  publishedAt: string | null;
+  current: boolean;
+};
+
+/** Raw build constants as provided by the host build. */
+export type BuildConstants = {
+  appVersion?: unknown;
+  buildTime?: unknown;
+  platformVersion?: unknown;
+  platformRange?: unknown;
+};
+
+const text = (value: unknown, fallback: string): string =>
+  typeof value === "string" && value ? value : fallback;
+
+/** Normalize the injected build constants into a complete `BuildInfo`. */
+export function readBuildInfoFrom(constants: BuildConstants): BuildInfo {
+  return {
+    appVersion: text(constants.appVersion, "0.0.0"),
+    buildTime: text(constants.buildTime, new Date().toISOString()),
+    platformVersion: text(constants.platformVersion, "unknown"),
+    platformRange: text(constants.platformRange, "unknown"),
+  };
+}
+
+/** The npm package name of the shared CMS platform. */
+export const PLATFORM_PACKAGE = "@bygghammar/cms-platform";
+
+/**
+ * The most recent published platform releases, newest first.
+ *
+ * Network failures are not an error worth surfacing on an information screen —
+ * the screen still shows the running version from the build constants.
+ */
+export async function fetchPlatformReleases(
+  currentVersion: string,
+  limit = 3,
+): Promise<PlatformRelease[]> {
+  try {
+    const res = await fetch(
+      `https://registry.npmjs.org/${PLATFORM_PACKAGE.replace("/", "%2F")}`,
+      { headers: { accept: "application/json" } },
+    );
+    if (!res.ok) return [];
+    const json = (await res.json()) as { time?: Record<string, string> };
+    const time = json.time ?? {};
+    return Object.entries(time)
+      .filter(([v]) => v !== "created" && v !== "modified")
+      .map(([version, publishedAt]) => ({
+        version,
+        publishedAt,
+        current: version === currentVersion,
+      }))
+      .sort((a, b) => (a.publishedAt < b.publishedAt ? 1 : -1))
+      .slice(0, limit);
+  } catch {
+    return [];
+  }
+}

package/src/config/package-owned-modules.ts

@@ -0,0 +1,75 @@
+/**
+ * Drift guard manifest.
+ *
+ * Each entry names a module a site is expected to keep as a thin wrapper, and
+ * the package export it must delegate to. A site test walks this manifest and
+ * fails the build when a local file stops importing the package module — the
+ * failure mode this whole extraction exists to prevent, where a site quietly
+ * reimplements platform behaviour and then drifts away from every other site.
+ */
+
+export type OwnedModule = {
+  /** Path relative to the site's project root. */
+  site: string;
+  /** Package specifier the site file must reference. */
+  packageModule: string;
+  /** Whether the site is allowed not to have the file at all. */
+  optional?: boolean;
+};
+
+export const PACKAGE_OWNED_MODULES: OwnedModule[] = [
+  { site: "src/lib/i18n/routes.ts", packageModule: "@bygghammar/cms-platform/site/routes" },
+  {
+    site: "src/lib/i18n/page-context.ts",
+    packageModule: "@bygghammar/cms-platform/site/page-context",
+  },
+  {
+    site: "src/lib/site/public-origin.ts",
+    packageModule: "@bygghammar/cms-platform/site/public-origin",
+  },
+  { site: "src/lib/site/site-url.ts", packageModule: "@bygghammar/cms-platform/site/site-url" },
+  { site: "src/lib/fonts/bundle.ts", packageModule: "@bygghammar/cms-platform/site/font-bundle" },
+  {
+    site: "src/lib/admin/version.server.ts",
+    packageModule: "@bygghammar/cms-platform/admin/version-core",
+  },
+  {
+    site: "src/lib/backup/backup.server.ts",
+    packageModule: "@bygghammar/cms-platform/server/backup-core",
+  },
+  {
+    site: "src/components/site/SiteHeader.tsx",
+    packageModule: "@bygghammar/cms-platform/site/SiteHeader",
+  },
+  {
+    site: "src/components/site/SiteFooter.tsx",
+    packageModule: "@bygghammar/cms-platform/site/SiteFooter",
+  },
+  {
+    site: "src/components/site/PageRenderer.tsx",
+    packageModule: "@bygghammar/cms-platform/site/PageRenderer",
+  },
+  {
+    site: "src/components/site/blocks/FormBlock.tsx",
+    packageModule: "@bygghammar/cms-platform/blocks/components/FormBlock",
+  },
+  {
+    site: "src/components/site/blocks/CourseListBlock.tsx",
+    packageModule: "@bygghammar/cms-platform/blocks/components/TripListBlock",
+    optional: true,
+  },
+  { site: "src/lib/blocks/registry.tsx", packageModule: "@bygghammar/cms-platform/blocks/registry" },
+  { site: "src/lib/site/definition.ts", packageModule: "@bygghammar/cms-platform/config/define-site" },
+  {
+    site: "src/routes/$.tsx",
+    packageModule: "@bygghammar/cms-platform/site/routes/public-page",
+  },
+  {
+    site: "src/routes/preview.$key.tsx",
+    packageModule: "@bygghammar/cms-platform/site/routes/preview-page",
+  },
+  {
+    site: "src/routes/preview.section.$key.tsx",
+    packageModule: "@bygghammar/cms-platform/site/routes/section-preview",
+  },
+];

package/src/site/font-bundle.ts

@@ -0,0 +1,43 @@
+/**
+ * Self-hosted WOFF2 payloads, bundled into the server build.
+ *
+ * Fonts deliberately do NOT live in `public/`: files served by the framework's
+ * static-asset handler bypass every application layer, so they come back without
+ * `Cache-Control` and without `Expires`. Serving them from a real route puts them
+ * back under the deployment's caching policy in both runtimes.
+ *
+ * The site imports its own `.woff2?inline` assets (they are brand assets) and
+ * hands the resulting data URIs to this factory; decoding and caching are shared.
+ */
+
+export type FontBundle = {
+  /** Every filename this bundle can serve. */
+  filenames: string[];
+  /** Font bytes, decoded once per process. `undefined` for unknown names. */
+  fontBytes: (name: string) => Uint8Array | undefined;
+};
+
+function fromDataUri(uri: string): Uint8Array {
+  const base64 = uri.slice(uri.indexOf(",") + 1);
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** Build a font bundle from a `filename -> data URI` map. */
+export function createFontBundle(dataUris: Record<string, string>): FontBundle {
+  const decoded = new Map<string, Uint8Array>();
+  return {
+    filenames: Object.keys(dataUris),
+    fontBytes(name: string): Uint8Array | undefined {
+      const cached = decoded.get(name);
+      if (cached) return cached;
+      const uri = dataUris[name];
+      if (!uri) return undefined;
+      const bytes = fromDataUri(uri);
+      decoded.set(name, bytes);
+      return bytes;
+    },
+  };
+}

package/src/site/page-context.ts

@@ -0,0 +1,87 @@
+/**
+ * Public-page context: the single server round-trip every public route needs.
+ *
+ * A public page needs four facts before it can render its `<head>`: the CMS SEO
+ * overrides, the locale implied by the request domain, the request origin, and
+ * the locale/domain map used for cross-domain hreflang. Fetching them one by one
+ * per route is what made this glue site-local; the engine is identical for every
+ * site, so it lives here and the site supplies only its data sources.
+ */
+import { queryOptions } from "@tanstack/react-query";
+
+import type { Locale } from "../i18n/locales";
+import type { PageHead, PageSeoOverrides, SiteRoutes } from "./routes";
+
+/** One `locale -> domain` mapping row, as stored by the domains module. */
+export type PageContextDomain = { locale: string; domain: string };
+
+export type PageContext<Row = unknown> = {
+  seoRows: Row[];
+  locale: Locale;
+  origin: string;
+  domains: PageContextDomain[];
+};
+
+export type PageContextDeps<Row> = {
+  /** Raw `page_seo` rows for this site. */
+  getSeoRows: () => Promise<Row[]>;
+  /** Locale + origin derived from the incoming request. */
+  getRequestLocale: () => Promise<{ locale: Locale; origin: string }>;
+  /** Configured locale domains. */
+  getLocaleDomains: () => Promise<PageContextDomain[]>;
+  /** Convert stored rows into the routing engine's override shape. */
+  rowsToOverrides: (rows: Row[] | undefined) => PageSeoOverrides;
+  /** The site's routing engine (from `createSiteRoutes`). */
+  routes: Pick<SiteRoutes, "resolveRoute" | "pageHeadMeta">;
+  /** Locale used when nothing else is known. */
+  defaultLocale: Locale;
+  /** Query key; defaults to `["page-context"]`. */
+  queryKey?: readonly unknown[];
+  /** Cache lifetime in ms; defaults to one minute. */
+  staleTime?: number;
+};
+
+export type SitePageContext<Row> = {
+  pageContextQueryOptions: ReturnType<typeof queryOptions<PageContext<Row>>>;
+  buildPageHead: (pageKey: string, context: PageContext<Row> | undefined) => PageHead;
+  canonicalPathFor: (pageKey: string, context: PageContext<Row> | undefined) => string;
+};
+
+/** Build the page-context loader + head helpers for one site. */
+export function createPageContext<Row>(deps: PageContextDeps<Row>): SitePageContext<Row> {
+  async function fetchPageContext(): Promise<PageContext<Row>> {
+    const [seoRows, localeInfo, domains] = await Promise.all([
+      deps.getSeoRows(),
+      deps.getRequestLocale(),
+      deps.getLocaleDomains(),
+    ]);
+    return {
+      seoRows,
+      locale: localeInfo.locale,
+      origin: localeInfo.origin,
+      domains,
+    };
+  }
+
+  const options = queryOptions<PageContext<Row>>({
+    queryKey: deps.queryKey ?? ["page-context"],
+    queryFn: fetchPageContext,
+    staleTime: deps.staleTime ?? 60_000,
+  });
+
+  function buildPageHead(pageKey: string, context: PageContext<Row> | undefined): PageHead {
+    const locale = context?.locale ?? deps.defaultLocale;
+    const origin = context?.origin ?? "";
+    const overrides = deps.rowsToOverrides(context?.seoRows);
+    const domains = context?.domains ?? [];
+    return deps.routes.pageHeadMeta(pageKey, locale, origin, overrides, domains);
+  }
+
+  function canonicalPathFor(pageKey: string, context: PageContext<Row> | undefined): string {
+    const locale = context?.locale ?? deps.defaultLocale;
+    const overrides = deps.rowsToOverrides(context?.seoRows);
+    return deps.routes.resolveRoute(pageKey, locale, overrides);
+  }
+
+  return { pageContextQueryOptions: options, buildPageHead, canonicalPathFor };
+}

package/src/site/public-origin.ts

@@ -0,0 +1,47 @@
+/**
+ * The canonical public origin for a deployment.
+ *
+ * The origin is a deployment fact, not editable content: preview, staging and
+ * production are different hosts. It is read from the environment, with the
+ * origin compiled into the site's source as the fallback, and is deliberately
+ * never stored as a database override — canonical URLs, sitemaps and auth
+ * redirects must be right before any database read happens.
+ */
+import { originIsFromEnvironment, resolveSiteOrigin } from "../config/site-config";
+
+export type PublicOriginDeps = {
+  /** Origin compiled into the build; used whenever no environment value is set. */
+  codeOrigin: string;
+  /** Reads the configured origin from the environment, or `undefined`. */
+  readEnvOrigin: () => string | undefined;
+};
+
+export type PublicOrigin = {
+  /** The origin this deployment should advertise. Always returns something. */
+  publicOrigin: () => string;
+  /**
+   * The origin this deployment was EXPLICITLY configured with, or `null`.
+   *
+   * Distinct from `publicOrigin()`: a deployment with no configuration is not
+   * the live site, it is a deployment whose configuration is missing. Answering
+   * that from a constant would make every unconfigured build claim to be
+   * production — the one answer that must never be reached by default.
+   */
+  configuredPublicOrigin: () => string | null;
+  /** Whether the running origin came from the environment rather than code. */
+  publicOriginFromEnv: () => boolean;
+};
+
+/** Build the origin accessors for one deployment. */
+export function createPublicOrigin(deps: PublicOriginDeps): PublicOrigin {
+  return {
+    publicOrigin: () => resolveSiteOrigin(deps.codeOrigin, deps.readEnvOrigin()),
+    configuredPublicOrigin: () => {
+      const value = deps.readEnvOrigin();
+      if (typeof value !== "string") return null;
+      const trimmed = value.trim();
+      return trimmed ? trimmed : null;
+    },
+    publicOriginFromEnv: () => originIsFromEnvironment(deps.codeOrigin, deps.readEnvOrigin()),
+  };
+}

package/src/site/routes/preview-page.tsx

@@ -0,0 +1,240 @@
+/**
+ * Page-builder preview route (site-agnostic).
+ *
+ * The preview renders either an unsaved draft (from the local draft store or a
+ * postMessage stream from the builder) or the published version of a page, and
+ * talks back to the editor: ready handshake, block selection, scroll-to-block.
+ * All of that is platform behaviour; a site supplies its data sources, chrome
+ * and draft store only.
+ */
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useState, type ComponentType } from "react";
+
+import { LocaleProvider, isLocale, DEFAULT_LOCALE, type Locale } from "../../i18n";
+import type { BlockInstance } from "../../blocks/types";
+
+export type PreviewDraftSnapshot = {
+  blocks: BlockInstance[];
+  globals?: Record<string, BlockInstance[]>;
+  locale?: string;
+};
+
+export type PreviewPageDeps = {
+  /** Published blocks + globals for a page key. */
+  getPublishedPage: (key: string) => Promise<PreviewDraftSnapshot | null | undefined>;
+  /** Saved blocks for a global section key (preview keys prefixed `gs:`). */
+  getGlobalSection: (key: string) => Promise<{ blocks: BlockInstance[] } | null | undefined>;
+  /** Local draft store written by the builder. */
+  readDraft: (key: string) => PreviewDraftSnapshot | null;
+  subscribeDraft: (key: string, cb: (snap: PreviewDraftSnapshot) => void) => () => void;
+  /** In-memory renderer for a block tree. */
+  DraftPageRenderer: ComponentType<{
+    blocks: BlockInstance[];
+    globals: Record<string, BlockInstance[]>;
+    edit?: boolean;
+    selectedId?: string | null;
+  }>;
+  Header: ComponentType;
+  Footer: ComponentType;
+  /** Query key holding shared content sections, patched from inspector edits. */
+  sharedContentQueryKey: readonly unknown[];
+  /** Page key rendered without the header offset (usually the home page). */
+  fullBleedKey?: string;
+  /** Outline colour used for block hover/selection. */
+  outlineColorVar?: string;
+  copy?: { draft?: string; published?: string; loading?: string };
+};
+
+type DraftMsg = {
+  source: "lovable-editor";
+  type: "draft" | "scrollTo";
+  blocks: BlockInstance[];
+  globals: Record<string, BlockInstance[]>;
+  selectedId?: string | null;
+  blockId?: string;
+  locale?: string;
+  sharedContent?: Record<string, unknown>;
+};
+
+export function createPreviewPage(deps: PreviewPageDeps): ComponentType<{ pageKey: string }> {
+  const copy = {
+    draft: deps.copy?.draft ?? "Draft preview — unsaved changes",
+    published: deps.copy?.published ?? "Preview — published version",
+    loading: deps.copy?.loading ?? "Loading preview…",
+  };
+  const outline = deps.outlineColorVar ?? "var(--primary, #2ac4ea)";
+
+  return function PreviewPage({ pageKey: key }) {
+    const queryClient = useQueryClient();
+    const [blocks, setBlocks] = useState<BlockInstance[]>([]);
+    const [globals, setGlobals] = useState<Record<string, BlockInstance[]>>({});
+    const [selectedId, setSelectedId] = useState<string | null>(null);
+    const [locale, setLocale] = useState<Locale>(DEFAULT_LOCALE);
+    const [ready, setReady] = useState(false);
+    const [isDraft, setIsDraft] = useState(false);
+    const embedded = typeof window !== "undefined" && window.parent !== window;
+
+    // Bootstrap: prefer a local unsaved draft, else the saved version.
+    useEffect(() => {
+      let alive = true;
+      const local = deps.readDraft(key);
+      if (local) {
+        setBlocks(local.blocks);
+        setGlobals(local.globals ?? {});
+        if (local.locale && isLocale(local.locale)) setLocale(local.locale);
+        setIsDraft(true);
+        setReady(true);
+        return;
+      }
+      if (key.startsWith("gs:")) {
+        deps
+          .getGlobalSection(key.slice(3))
+          .then((res) => {
+            if (!alive || !res) return;
+            setBlocks((prev) => (prev.length ? prev : res.blocks));
+          })
+          .catch(() => {})
+          .finally(() => alive && setReady(true));
+        return () => {
+          alive = false;
+        };
+      }
+      deps
+        .getPublishedPage(key)
+        .then((res) => {
+          if (!alive || !res) return;
+          setBlocks((prev) => (prev.length ? prev : res.blocks));
+          setGlobals((prev) => (Object.keys(prev).length ? prev : (res.globals ?? {})));
+        })
+        .catch(() => {})
+        .finally(() => alive && setReady(true));
+      return () => {
+        alive = false;
+      };
+    }, [key]);
+
+    // Live sync with the builder in another tab.
+    useEffect(() => {
+      if (embedded) return;
+      return deps.subscribeDraft(key, (snap) => {
+        setBlocks(snap.blocks);
+        setGlobals(snap.globals ?? {});
+        if (snap.locale && isLocale(snap.locale)) setLocale(snap.locale);
+        setIsDraft(true);
+        setReady(true);
+      });
+    }, [key, embedded]);
+
+    // Locale from the URL (?locale=en) wins for standalone tabs.
+    useEffect(() => {
+      if (typeof window === "undefined") return;
+      const q = new URLSearchParams(window.location.search).get("locale");
+      if (q && isLocale(q)) setLocale(q);
+    }, []);
+
+    // Ready handshake plus draft/scroll messages from the editor.
+    useEffect(() => {
+      const send = (msg: unknown) =>
+        window.parent && window.parent !== window && window.parent.postMessage(msg, "*");
+      send({ source: "lovable-preview", type: "ready" });
+      const onMsg = (ev: MessageEvent) => {
+        const data = ev.data as DraftMsg | undefined;
+        if (!data || data.source !== "lovable-editor") return;
+        if (data.type === "scrollTo") {
+          const id = data.blockId;
+          if (!id) return;
+          requestAnimationFrame(() => {
+            document
+              .querySelector(`[data-block-id="${CSS.escape(id)}"]`)
+              ?.scrollIntoView({ behavior: "smooth", block: "start" });
+          });
+          return;
+        }
+        if (data.type !== "draft") return;
+        if (data.sharedContent && Object.keys(data.sharedContent).length) {
+          queryClient.setQueryData(
+            deps.sharedContentQueryKey,
+            (prev: Record<string, unknown> | undefined) => ({
+              ...(prev ?? {}),
+              ...data.sharedContent,
+            }),
+          );
+        }
+        setBlocks(data.blocks);
+        setGlobals(data.globals);
+        setSelectedId(data.selectedId ?? null);
+        if (data.locale && isLocale(data.locale)) setLocale(data.locale);
+        setIsDraft(true);
+        setReady(true);
+      };
+      window.addEventListener("message", onMsg);
+      return () => window.removeEventListener("message", onMsg);
+    }, [queryClient]);
+
+    // Intercept clicks and report the outermost block to the editor.
+    useEffect(() => {
+      const onClick = (e: MouseEvent) => {
+        if (window.parent === window) return;
+        const target = e.target as HTMLElement | null;
+        let el = target?.closest("[data-block-id]") as HTMLElement | null;
+        if (!el) return;
+        let outer = el.parentElement?.closest("[data-block-id]") as HTMLElement | null;
+        while (outer) {
+          el = outer;
+          outer = el.parentElement?.closest("[data-block-id]") as HTMLElement | null;
+        }
+        e.preventDefault();
+        e.stopPropagation();
+        window.parent.postMessage(
+          {
+            source: "lovable-preview",
+            type: "select",
+            blockId: el.getAttribute("data-block-id"),
+          },
+          "*",
+        );
+      };
+      document.addEventListener("click", onClick, true);
+      return () => document.removeEventListener("click", onClick, true);
+    }, []);
+
+    return (
+      <LocaleProvider locale={locale}>
+        <style>{`
+        .lovable-block { position: relative; }
+        .lovable-block::after {
+          content: ""; position: absolute; inset: 0; pointer-events: none;
+          outline: 2px dashed transparent; outline-offset: -2px;
+          transition: outline-color .15s ease; z-index: 40;
+        }
+        .lovable-block:hover::after { outline-color: ${outline}; }
+        .lovable-block[data-selected="true"]::after {
+          outline: 3px solid ${outline}; outline-offset: -3px;
+        }
+        a, button { cursor: pointer; }
+      `}</style>
+        <main className="min-h-screen bg-background text-foreground overflow-x-hidden">
+          {!embedded && (
+            <div className="fixed bottom-4 left-4 z-[100] border border-ink/15 bg-white/95 px-3 py-1.5 text-[0.65rem] uppercase tracking-[0.18em] text-ink/70 shadow-lg">
+              {isDraft ? copy.draft : copy.published}
+            </div>
+          )}
+          <deps.Header />
+          <div className={key === (deps.fullBleedKey ?? "home") ? "" : "pt-24 md:pt-32"}>
+            {ready ? (
+              <deps.DraftPageRenderer
+                blocks={blocks}
+                globals={globals}
+                edit
+                selectedId={selectedId}
+              />
+            ) : (
+              <div className="p-12 text-ink/50 text-sm">{copy.loading}</div>
+            )}
+          </div>
+          <deps.Footer />
+        </main>
+      </LocaleProvider>
+    );
+  };
+}

package/src/site/routes/public-page.tsx

@@ -0,0 +1,114 @@
+/**
+ * Public catch-all page route (site-agnostic).
+ *
+ * Every site resolves an incoming path to a CMS page key, honours stored
+ * redirects, warms the page + page-context queries and renders the page between
+ * the site chrome. Only the data sources, chrome components and copy differ per
+ * site, so the engine lives here and the site keeps a thin route wrapper.
+ */
+import { notFound, redirect } from "@tanstack/react-router";
+import type { ComponentType, ReactNode } from "react";
+
+export type ResolvedPath =
+  | { kind: "page"; pageKey: string }
+  | { kind: "redirect"; to: string; status?: number }
+  | { kind: "none" };
+
+export type PublicPageHead = {
+  meta?: Array<Record<string, string>>;
+  links?: Array<Record<string, string>>;
+};
+
+export type QueryLike = { queryKey: readonly unknown[] };
+
+export type PublicPageRouteDeps<Ctx> = {
+  /** Resolve a request path to a page key, a redirect, or nothing. */
+  resolvePath: (path: string) => Promise<ResolvedPath>;
+  /** Page-context query (SEO rows, locale, origin, domains). */
+  pageContextQueryOptions: QueryLike;
+  /** Published-page query for one page key. */
+  pageQueryOptions: (pageKey: string) => QueryLike;
+  /** Head builder from `createPageContext`. */
+  buildPageHead: (pageKey: string, context: Ctx | undefined) => PublicPageHead;
+  /** Site chrome. */
+  Header: ComponentType;
+  Footer: ComponentType;
+  /** Published-page renderer. */
+  PageRenderer: ComponentType<{ pageKey: string }>;
+  /** Localized-free copy for the fallback screens (already resolved strings). */
+  copy: { notFoundTitle: string; errorText: string };
+  /** Padding applied above the page content; defaults to the header offset. */
+  contentClassName?: string;
+};
+
+type EnsureQueryData = <T extends QueryLike>(options: T) => Promise<unknown>;
+type LoaderArgs = {
+  context: { queryClient: { ensureQueryData: EnsureQueryData } };
+  params: { _splat?: string };
+};
+
+export type PublicPageRoute<Ctx> = {
+  loader: (args: LoaderArgs) => Promise<{ pageKey: string; ctx: Ctx }>;
+  head: (args: { loaderData?: { pageKey: string; ctx: Ctx } }) => PublicPageHead;
+  PublicPage: ComponentType<{ pageKey: string }>;
+  ErrorScreen: ComponentType;
+  NotFoundScreen: ComponentType;
+};
+
+export function createPublicPageRoute<Ctx>(deps: PublicPageRouteDeps<Ctx>): PublicPageRoute<Ctx> {
+  const Shell = ({ children }: { children: ReactNode }) => (
+    <main className="min-h-screen bg-background text-foreground overflow-x-hidden">
+      <deps.Header />
+      {children}
+      <deps.Footer />
+    </main>
+  );
+
+  return {
+    async loader({ context, params }) {
+      const path = `/${params._splat ?? ""}`;
+      const res = await deps.resolvePath(path);
+      if (res.kind === "redirect") {
+        throw redirect({ href: res.to, statusCode: res.status === 302 ? 302 : 301 });
+      }
+      if (res.kind !== "page") throw notFound();
+
+      const [ctx] = await Promise.all([
+        context.queryClient.ensureQueryData(deps.pageContextQueryOptions),
+        context.queryClient.ensureQueryData(deps.pageQueryOptions(res.pageKey)),
+      ]);
+      return { pageKey: res.pageKey, ctx: ctx as Ctx };
+    },
+
+    head({ loaderData }) {
+      if (!loaderData) {
+        return {
+          meta: [{ title: deps.copy.notFoundTitle }, { name: "robots", content: "noindex" }],
+        };
+      }
+      return deps.buildPageHead(loaderData.pageKey, loaderData.ctx);
+    },
+
+    PublicPage: ({ pageKey }) => (
+      <Shell>
+        <div className={deps.contentClassName ?? "pt-24 md:pt-32"}>
+          <deps.PageRenderer pageKey={pageKey} />
+        </div>
+      </Shell>
+    ),
+
+    ErrorScreen: () => (
+      <Shell>
+        <div className="pt-40 pb-32 text-center text-ink/70">{deps.copy.errorText}</div>
+      </Shell>
+    ),
+
+    NotFoundScreen: () => (
+      <Shell>
+        <div className="pt-40 pb-32 text-center">
+          <h1 className="font-serif text-4xl text-ink">{deps.copy.notFoundTitle}</h1>
+        </div>
+      </Shell>
+    ),
+  };
+}

package/src/site/routes/section-preview.tsx

@@ -0,0 +1,40 @@
+/**
+ * Single content-section preview (site-agnostic).
+ *
+ * The backoffice thumbnail lightbox opens one section standalone so an editor
+ * sees the real site component rather than a screenshot. The section map is the
+ * only site-specific part.
+ */
+import type { ComponentType } from "react";
+
+export type SectionPreviewDeps = {
+  /** Section key -> real site component. Missing keys render the fallback. */
+  sections: Record<string, ComponentType>;
+  copy?: { title?: string; body?: string };
+};
+
+export function createSectionPreview(
+  deps: SectionPreviewDeps,
+): ComponentType<{ sectionKey: string }> {
+  const title = deps.copy?.title ?? "No visual preview";
+  const body =
+    deps.copy?.body ?? "This section holds settings and text used elsewhere on the site.";
+
+  return function SectionPreview({ sectionKey }) {
+    const Cmp = deps.sections[sectionKey];
+    return (
+      <main className="min-h-screen bg-background text-foreground overflow-x-hidden">
+        {Cmp ? (
+          <Cmp />
+        ) : (
+          <div className="flex min-h-screen items-center justify-center p-10 text-center">
+            <div>
+              <div className="font-serif text-2xl text-ink">{title}</div>
+              <p className="mt-2 text-sm text-ink/60">{body}</p>
+            </div>
+          </div>
+        )}
+      </main>
+    );
+  };
+}