@bygghammar/cms-platform 0.62.1 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.63.0
+
+- Site config gains `branding` (`logo`, `logoDark`, `logoAlt`,
+  `invertLogoOnLightSurface`) and it is an overridable setting, so the logo can be
+  uploaded from **Site settings → Branding** with the code value as the fallback.
+- `SiteSettingsView` renders the branding section, using the host media field
+  (library picker + upload) when available and live previews on both surfaces.
+- New `loadSiteBrandingCore(client, config)` for a public read of the resolved
+  logo, and `brandingLogoFor()` to pick artwork per surface.
+- `SiteHeader` accepts `logoDarkSrc` and `logoAlt`; a dark artwork replaces the
+  CSS inversion on light surfaces.
+
 ## 0.61.1
 
 - `site/host-indexing-response` takes the configured origin from the site instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.62.1",
+  "version": "0.64.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": [
@@ -300,4 +300,4 @@
     "cms-platform-migrations": "scripts/sync-migrations.mjs",
     "create-cms-site": "./scripts/create-cms-site.mjs"
   }
-}
+}

package/src/backoffice/DashboardView.tsx

@@ -14,6 +14,8 @@ export type DashboardCard = {
   title: string;
   body: string;
   icon: ComponentType<{ className?: string }>;
+  /** Module switch that has to be on for the card to be shown. */
+  feature?: string;
 };
 
 /** Translation sweep modes offered on the dashboard. */

package/src/backoffice/SiteSettingsView.tsx

@@ -1,10 +1,12 @@
-import { useEffect, useState } from "react";
+import { useEffect, useState, type ReactNode } from "react";
 import { toast } from "sonner";
 import { Save, RotateCcw } from "lucide-react";
 
 import {
   DEFAULT_FEATURE_FLAGS,
+  EMPTY_BRANDING,
   EMPTY_COMPANY,
+  type SiteBranding,
   type SiteConfig,
   type SiteFeatureFlags,
   type SiteSettingOverrides,
@@ -37,6 +39,12 @@ export type SiteSettingsDeps = {
   companyValues?: Record<string, string>;
   /** Navigate to the contact details screen, where company fields are edited. */
   onOpenContactDetails?: () => void;
+  /**
+   * Site media field (library picker + upload). When omitted the branding
+   * section falls back to plain URL inputs so the screen still works.
+   */
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  MediaField?: (props: any) => ReactNode;
 };
 
 const FEATURE_LABELS: Record<keyof SiteFeatureFlags, string> = {
@@ -80,6 +88,10 @@ export function SiteSettingsView({ deps }: { deps: SiteSettingsDeps }) {
   const [company, setCompany] = useState({ ...EMPTY_COMPANY, ...config.company });
   const [features, setFeatures] = useState<SiteFeatureFlags>({ ...config.features });
   const [brand, setBrand] = useState<Record<string, string>>({ ...config.brand });
+  const [branding, setBranding] = useState<SiteBranding>({
+    ...EMPTY_BRANDING,
+    ...config.branding,
+  });
   const [busy, setBusy] = useState<string | null>(null);
 
   useEffect(() => {
@@ -87,6 +99,7 @@ export function SiteSettingsView({ deps }: { deps: SiteSettingsDeps }) {
     setCompany({ ...EMPTY_COMPANY, ...config.company });
     setFeatures({ ...config.features });
     setBrand({ ...config.brand });
+    setBranding({ ...EMPTY_BRANDING, ...config.branding });
   }, [config]);
 
   const save = async (key: string, patch: SiteSettingOverrides) => {
@@ -212,6 +225,60 @@ export function SiteSettingsView({ deps }: { deps: SiteSettingsDeps }) {
         ) : null}
       </section>
 
+
+      <section className={`mt-6 ${cardClass}`}>
+        <SectionHeader
+          title="Branding"
+          overridden={overridden("branding")}
+          onReset={() => reset("branding")}
+          busy={busy === "branding"}
+        />
+        <p className="mt-2 max-w-2xl text-sm text-ink/60">
+          The logo shown in the site header. Upload the artwork you want here; leaving a field empty
+          falls back to the logo that ships with the site in code. Use a transparent PNG or SVG.
+        </p>
+        <div className="mt-5 grid gap-6 md:grid-cols-2">
+          <BrandingLogoField
+            label="Logo (light artwork, used on dark backgrounds)"
+            value={branding.logo}
+            onChange={(logo) => setBranding({ ...branding, logo })}
+            MediaField={deps.MediaField}
+            preview="dark"
+          />
+          <BrandingLogoField
+            label="Dark logo (optional, used on light backgrounds)"
+            value={branding.logoDark}
+            onChange={(logoDark) => setBranding({ ...branding, logoDark })}
+            MediaField={deps.MediaField}
+            preview="light"
+          />
+        </div>
+        <div className="mt-5 grid gap-4 md:grid-cols-2 md:items-end">
+          <label className="block">
+            <span className={labelClass}>Logo alt text</span>
+            <input
+              className={inputClass}
+              value={branding.logoAlt}
+              placeholder={config.name}
+              onChange={(e) => setBranding({ ...branding, logoAlt: e.target.value })}
+            />
+          </label>
+          <label className="flex items-center gap-3 text-sm text-ink">
+            <input
+              type="checkbox"
+              checked={branding.invertLogoOnLightSurface}
+              onChange={(e) =>
+                setBranding({ ...branding, invertLogoOnLightSurface: e.target.checked })
+              }
+            />
+            Invert the light artwork on light backgrounds (when no dark logo is set)
+          </label>
+        </div>
+        <div className="mt-5">
+          <SaveButton busy={busy === "branding"} onClick={() => save("branding", { branding })} />
+        </div>
+      </section>
+
       <section className={`mt-6 ${cardClass}`}>
         <SectionHeader
           title="Modules"
@@ -271,6 +338,52 @@ export function SiteSettingsView({ deps }: { deps: SiteSettingsDeps }) {
   );
 }
 
+/**
+ * One logo slot: the site's media field when the host provides one, otherwise a
+ * plain URL input. Both render the same live preview on the target surface.
+ */
+function BrandingLogoField({
+  label,
+  value,
+  onChange,
+  MediaField,
+  preview,
+}: {
+  label: string;
+  value: string;
+  onChange: (next: string) => void;
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  MediaField?: (props: any) => ReactNode;
+  preview: "light" | "dark";
+}) {
+  return (
+    <div>
+      <span className={labelClass}>{label}</span>
+      {MediaField ? (
+        <MediaField value={value} onChange={onChange} label="" />
+      ) : (
+        <input
+          className={inputClass}
+          value={value}
+          placeholder="/logo.png"
+          onChange={(e) => onChange(e.target.value)}
+        />
+      )}
+      <div
+        className={`mt-3 flex h-20 items-center justify-center border border-ink/10 px-4 ${
+          preview === "dark" ? "bg-ink" : "bg-white"
+        }`}
+      >
+        {value ? (
+          <img src={value} alt="" className="max-h-12 w-auto" />
+        ) : (
+          <span className="text-xs uppercase tracking-wider text-ink/35">Code default</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
 function SectionHeader({
   title,
   overridden,

package/src/backoffice/routes/host.ts

@@ -232,6 +232,8 @@ export type BackofficeHost = {
       title: string;
       body: string;
       icon: (props: { className?: string }) => ReactNode;
+      /** Module switch that has to be on for the card to be shown. */
+      feature?: string;
     }[];
     translateTarget?: string;
     translate?: HostServerFn;

package/src/backoffice/routes/index.tsx

@@ -45,6 +45,7 @@ import { SiteSettingsView } from "../SiteSettingsView";
 import { TrackingView } from "../TrackingView";
 import { UsersView } from "../UsersView";
 import { VersionView } from "../VersionView";
+import { useFeatureGate } from "../shell/use-resolved-config";
 import { backofficeHost, backofficePaths } from "./host";
 
 export * from "./host";
@@ -162,6 +163,7 @@ export function SiteSettingsRoute() {
         onOpenContactDetails: () => {
           window.location.href = contactPath;
         },
+        MediaField: host.components.MediaField,
       }}
     />
   );
@@ -188,7 +190,7 @@ export function RedirectsRoute() {
 }
 
 /** Code & tracking injection screen. */
-export function TrackingRoute() {
+function TrackingRouteInner() {
   const { fns, locales } = backofficeHost();
   const list = useServerFn(fns.listInjections);
   const save = useServerFn(fns.saveInjection);
@@ -237,7 +239,7 @@ export function ContactDetailsRoute() {
 }
 
 /** Form defaults and retention screen. */
-export function FormSettingsRoute() {
+function FormSettingsRouteInner() {
   const host = backofficeHost();
   const { fns } = host;
   const load = useServerFn(fns.getFormDefaults);
@@ -492,7 +494,7 @@ export function SitemapRoute() {
 }
 
 /** Email sending settings plus provider credentials. */
-export function EmailSettingsRoute() {
+function EmailSettingsRouteInner() {
   const host = backofficeHost();
   const { fns } = host;
   const fetchSettings = useServerFn(fns.getEmailSettings);
@@ -558,7 +560,7 @@ export function NavigationRoute() {
 }
 
 /** Per-locale domain mapping. */
-export function DomainsRoute() {
+function DomainsRouteInner() {
   const host = backofficeHost();
   const paths = backofficePaths(host);
   const qc = useQueryClient();
@@ -584,7 +586,7 @@ export function DomainsRoute() {
 }
 
 /** Testimonials / reviews editor backed by the shared content section. */
-export function ReviewsRoute() {
+function ReviewsRouteInner() {
   const host = backofficeHost();
   const paths = backofficePaths(host);
   const qc = useQueryClient();
@@ -620,7 +622,7 @@ export function ReviewsRoute() {
 }
 
 /** Backup and restore, superadmin only. */
-export function BackupRoute() {
+function BackupRouteInner() {
   const host = backofficeHost();
   const backup = host.backup;
   if (!backup) {
@@ -648,3 +650,45 @@ export function BackupRoute() {
     />
   );
 }
+
+/** ReviewsRoute guarded by the "reviews" module switch. */
+export function ReviewsRoute() {
+  const gate = useFeatureGate("reviews", "Reviews");
+  if (gate) return <>{gate}</>;
+  return <ReviewsRouteInner />;
+}
+
+/** DomainsRoute guarded by the "domains" module switch. */
+export function DomainsRoute() {
+  const gate = useFeatureGate("domains", "Domains");
+  if (gate) return <>{gate}</>;
+  return <DomainsRouteInner />;
+}
+
+/** TrackingRoute guarded by the "tracking" module switch. */
+export function TrackingRoute() {
+  const gate = useFeatureGate("tracking", "Code & tracking");
+  if (gate) return <>{gate}</>;
+  return <TrackingRouteInner />;
+}
+
+/** EmailSettingsRoute guarded by the "email" module switch. */
+export function EmailSettingsRoute() {
+  const gate = useFeatureGate("email", "Email");
+  if (gate) return <>{gate}</>;
+  return <EmailSettingsRouteInner />;
+}
+
+/** BackupRoute guarded by the "backup" module switch. */
+export function BackupRoute() {
+  const gate = useFeatureGate("backup", "Backup");
+  if (gate) return <>{gate}</>;
+  return <BackupRouteInner />;
+}
+
+/** FormSettingsRoute guarded by the "forms" module switch. */
+export function FormSettingsRoute() {
+  const gate = useFeatureGate("forms", "Forms");
+  if (gate) return <>{gate}</>;
+  return <FormSettingsRouteInner />;
+}

package/src/backoffice/routes/media-forms.tsx

@@ -8,6 +8,7 @@
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+import { useFeatureGate } from "../shell/use-resolved-config";
 import { Link, useNavigate, useParams, useSearch } from "@tanstack/react-router";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useServerFn } from "@tanstack/react-start";
@@ -113,7 +114,7 @@ export function MediaRoute() {
 }
 
 /** Forms index: list, create, duplicate, delete and the trash bin. */
-export function FormsIndexRoute() {
+function FormsIndexRouteInner() {
   const forms = requireHostGroup("forms");
   const { fns } = backofficeHost();
   const qc = useQueryClient();
@@ -158,7 +159,7 @@ export function FormsIndexRoute() {
 }
 
 /** Form editor for a single form key. */
-export function FormEditorRoute() {
+function FormEditorRouteInner() {
   const forms = requireHostGroup("forms");
   const { fns } = backofficeHost();
   const params = useParams({ strict: false }) as { key?: string };
@@ -231,7 +232,7 @@ export function validateSubmissionSearch(search: Record<string, unknown>): Submi
 }
 
 /** Submission inbox with filters, paging, exports and delivery retries. */
-export function FormSubmissionsRoute() {
+function FormSubmissionsRouteInner() {
   const forms = requireHostGroup("forms");
   const host = backofficeHost();
   const paths = backofficePaths(host);
@@ -302,7 +303,7 @@ export function FormSubmissionsRoute() {
 }
 
 /** Delivery attempt dashboard (retry / resolve failed notifications). */
-export function FormDeliveriesRoute() {
+function FormDeliveriesRouteInner() {
   const forms = requireHostGroup("forms");
   const host = backofficeHost();
   const paths = backofficePaths(host);
@@ -358,3 +359,31 @@ export function FormDeliveriesRoute() {
     />
   );
 }
+
+/** FormsIndexRoute guarded by the "forms" module switch. */
+export function FormsIndexRoute() {
+  const gate = useFeatureGate("forms", "Forms");
+  if (gate) return <>{gate}</>;
+  return <FormsIndexRouteInner />;
+}
+
+/** FormEditorRoute guarded by the "forms" module switch. */
+export function FormEditorRoute() {
+  const gate = useFeatureGate("forms", "Forms");
+  if (gate) return <>{gate}</>;
+  return <FormEditorRouteInner />;
+}
+
+/** FormSubmissionsRoute guarded by the "forms" module switch. */
+export function FormSubmissionsRoute() {
+  const gate = useFeatureGate("forms", "Forms");
+  if (gate) return <>{gate}</>;
+  return <FormSubmissionsRouteInner />;
+}
+
+/** FormDeliveriesRoute guarded by the "forms" module switch. */
+export function FormDeliveriesRoute() {
+  const gate = useFeatureGate("forms", "Forms");
+  if (gate) return <>{gate}</>;
+  return <FormDeliveriesRouteInner />;
+}

package/src/backoffice/routes/pages.tsx

@@ -17,6 +17,7 @@ import { toast } from "sonner";
 import { PageBuilderView } from "../PageBuilderView";
 import { SectionEditorView } from "../SectionEditorView";
 import { DashboardView, type DashboardCard } from "../DashboardView";
+import { useResolvedSiteConfig } from "../shell/use-resolved-config";
 import { ResetPasswordView } from "../ResetPasswordView";
 import { backofficeHost, backofficePaths, requireHostGroup } from "./host";
 
@@ -204,13 +205,18 @@ export function SectionEditorRoute() {
 /** Backoffice dashboard for `/<backoffice>/`. */
 export function DashboardRoute() {
   const dashboard = requireHostGroup("dashboard");
+  const { config } = useResolvedSiteConfig();
   const translateFn = dashboard.translate;
   const runTranslate = useServerFn(translateFn ?? (async () => ({})));
 
   return (
     <DashboardView
       deps={{
-        cards: dashboard.cards as unknown as readonly DashboardCard[],
+        cards: (dashboard.cards as unknown as readonly DashboardCard[]).filter(
+          (c) =>
+            !c.feature ||
+            (config.features as Record<string, boolean | undefined>)[c.feature] === true,
+        ),
         renderLink: ({ to, className, children }) => (
           <Link to={to as any} className={className}>
             {children}

package/src/backoffice/shell/index.ts

@@ -7,3 +7,11 @@ export type {
 export { backofficeNav } from "./nav-model";
 export type { BackofficeNavItem, BackofficeNavKey, BackofficeNavOptions } from "./nav-model";
 export { backofficeRedirectHost, isDevelopmentHost } from "./domain-guard";
+export {
+  FeatureDisabledNotice,
+  SITE_SETTINGS_QUERY_KEY,
+  useBackofficeNav,
+  useFeatureEnabled,
+  useFeatureGate,
+  useResolvedSiteConfig,
+} from "./use-resolved-config";

package/src/backoffice/shell/use-resolved-config.tsx

@@ -0,0 +1,84 @@
+/**
+ * Live backoffice site configuration.
+ *
+ * The sidebar, the dashboard cards and the module screens must all obey the
+ * module switches saved under Site settings, not just the values compiled into
+ * `site.config.ts`. These hooks resolve the code config layered with the stored
+ * overrides through the host's `getSiteSettings` function, sharing the
+ * `["admin","site-settings"]` query key with the settings screen so a save
+ * updates the menu immediately.
+ */
+import type { ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useServerFn } from "@tanstack/react-start";
+
+import type { SiteConfig, SiteFeatureFlags } from "../../config/site-config";
+import { resolveSiteConfig } from "../../config/site-config";
+import { backofficeHost } from "../routes/host";
+import { backofficeNav, type BackofficeNavItem, type BackofficeNavOptions } from "./nav-model";
+
+/** Query key shared with the site-settings screen. */
+export const SITE_SETTINGS_QUERY_KEY = ["admin", "site-settings"] as const;
+
+/**
+ * Code config merged with the stored overrides. While loading, the code config
+ * is returned so the shell renders without a flash of empty navigation.
+ */
+export function useResolvedSiteConfig(): { config: SiteConfig; isLoading: boolean } {
+  const host = backofficeHost();
+  const load = useServerFn(host.fns.getSiteSettings);
+  const q = useQuery({
+    queryKey: SITE_SETTINGS_QUERY_KEY,
+    queryFn: () => load() as Promise<{ config?: SiteConfig; overrides?: unknown }>,
+    staleTime: 30_000,
+  });
+
+  const resolved =
+    (q.data?.config as SiteConfig | undefined) ??
+    (q.data?.overrides
+      ? resolveSiteConfig(host.siteConfig, q.data.overrides as never)
+      : host.siteConfig);
+
+  return { config: resolved, isLoading: q.isLoading };
+}
+
+/** Sidebar model built from the live (override-aware) configuration. */
+export function useBackofficeNav(options: BackofficeNavOptions = {}): BackofficeNavItem[] {
+  const { config } = useResolvedSiteConfig();
+  return backofficeNav(config, options);
+}
+
+/**
+ * Whether a module is enabled right now. `undefined` while settings load, so a
+ * caller can avoid flashing a "turned off" notice before the answer is known.
+ */
+export function useFeatureEnabled(flag: keyof SiteFeatureFlags): boolean | undefined {
+  const { config, isLoading } = useResolvedSiteConfig();
+  if (isLoading) return undefined;
+  return config.features[flag] === true;
+}
+
+/** Notice shown instead of a screen whose module is switched off. */
+export function FeatureDisabledNotice({ label }: { label?: string }) {
+  return (
+    <div className="p-8 md:p-12">
+      <h1 className="font-serif text-2xl text-ink">
+        {label ? `${label} is turned off` : "This module is turned off"}
+      </h1>
+      <p className="mt-3 max-w-md text-sm text-ink/65">
+        Turn it back on under Site settings → Modules to use this screen.
+      </p>
+    </div>
+  );
+}
+
+/**
+ * Guard for a module screen: returns a node to render instead of the screen
+ * when the module is disabled, and `null` when the screen may render.
+ */
+export function useFeatureGate(flag: keyof SiteFeatureFlags, label?: string): ReactNode | null {
+  const enabled = useFeatureEnabled(flag);
+  if (enabled === undefined) return <div className="p-8 text-sm text-ink/50">Loading…</div>;
+  if (enabled) return null;
+  return <FeatureDisabledNotice label={label} />;
+}

package/src/config/site-config.ts

@@ -64,6 +64,32 @@ export const EMPTY_COMPANY: SiteCompany = {
   phone: "",
 };
 
+
+/**
+ * Brand identity assets (logo artwork). Locale-neutral URLs; `alt` is plain
+ * text because a logo's accessible name is the brand name in every language.
+ */
+export type SiteBranding = {
+  /** Primary logo/wordmark URL. Empty string means "no logo configured". */
+  logo: string;
+  /**
+   * Optional dark-ink logo used on light surfaces. When empty, the primary
+   * artwork is CSS-inverted instead (see `invertLogoOnLightSurface`).
+   */
+  logoDark: string;
+  /** Accessible name for the logo image. Falls back to the site name. */
+  logoAlt: string;
+  /** Invert the primary artwork on light surfaces when no dark variant exists. */
+  invertLogoOnLightSurface: boolean;
+};
+
+export const EMPTY_BRANDING: SiteBranding = {
+  logo: "",
+  logoDark: "",
+  logoAlt: "",
+  invertLogoOnLightSurface: true,
+};
+
 /** Brand design tokens. Values are CSS colors written into the theme contract. */
 export type SiteBrandTokens = Record<string, string>;
 
@@ -86,6 +112,8 @@ export type SiteConfigInput = {
   /** UI language of the backoffice itself. */
   backofficeLocale?: string;
   company?: Partial<SiteCompany>;
+  /** Logo artwork defaults; the backoffice may override these. */
+  branding?: Partial<SiteBranding>;
   brand?: SiteBrandTokens;
   features?: Partial<SiteFeatureFlags>;
   /** Optional free-form per-site extras shared code never reads. */
@@ -101,6 +129,7 @@ export type SiteConfig = {
   backofficePath: string;
   backofficeLocale: string;
   company: SiteCompany;
+  branding: SiteBranding;
   brand: SiteBrandTokens;
   features: SiteFeatureFlags;
   extra: SiteExtra;
@@ -134,6 +163,7 @@ export function defineSiteConfig(input: SiteConfigInput): SiteConfig {
     backofficePath,
     backofficeLocale: input.backofficeLocale ?? "en",
     company: { ...EMPTY_COMPANY, ...(input.company ?? {}) },
+    branding: { ...EMPTY_BRANDING, ...(input.branding ?? {}) },
     brand: { ...(input.brand ?? {}) },
     features: { ...DEFAULT_FEATURE_FLAGS, ...(input.features ?? {}) },
     extra: { ...(input.extra ?? {}) },
@@ -170,6 +200,7 @@ export function originIsFromEnvironment(fallback: string, rawEnvValue?: string |
 export const OVERRIDABLE_SETTING_KEYS = [
   "name",
   "company",
+  "branding",
   "brand",
   "features",
 ] as const satisfies readonly (keyof SiteConfig)[];
@@ -180,6 +211,7 @@ export type OverridableSettingKey = (typeof OVERRIDABLE_SETTING_KEYS)[number];
 export type SiteSettingOverrides = Partial<{
   name: string;
   company: Partial<SiteCompany>;
+  branding: Partial<SiteBranding>;
   brand: SiteBrandTokens;
   features: Partial<SiteFeatureFlags>;
 }>;
@@ -201,6 +233,18 @@ export function parseSiteSettingOverrides(raw: unknown): SiteSettingOverrides {
     }
     out.company = company;
   }
+  if (isRecord(raw["branding"])) {
+    const source = raw["branding"] as Record<string, unknown>;
+    const branding: Partial<SiteBranding> = {};
+    for (const key of ["logo", "logoDark", "logoAlt"] as const) {
+      const value = source[key];
+      if (typeof value === "string") branding[key] = value;
+    }
+    if (typeof source["invertLogoOnLightSurface"] === "boolean") {
+      branding.invertLogoOnLightSurface = source["invertLogoOnLightSurface"];
+    }
+    out.branding = branding;
+  }
   if (isRecord(raw["brand"])) {
     const brand: SiteBrandTokens = {};
     for (const [key, value] of Object.entries(raw["brand"])) {
@@ -226,6 +270,7 @@ export function resolveSiteConfig(base: SiteConfig, overrides: unknown): SiteCon
     ...base,
     name: parsed.name ?? base.name,
     company: { ...base.company, ...(parsed.company ?? {}) },
+    branding: { ...base.branding, ...(parsed.branding ?? {}) },
     brand: { ...base.brand, ...(parsed.brand ?? {}) },
     features: { ...base.features, ...(parsed.features ?? {}) },
   };
@@ -259,3 +304,18 @@ export function siteConfig(): SiteConfig {
   }
   return active;
 }
+
+/**
+ * Resolve the logo to render for a surface. A dark variant wins on light
+ * surfaces; otherwise the caller inverts the primary artwork when configured.
+ */
+export function brandingLogoFor(
+  branding: SiteBranding,
+  surface: "light" | "dark",
+): { src: string; invert: boolean } {
+  if (surface === "light" && branding.logoDark) return { src: branding.logoDark, invert: false };
+  return {
+    src: branding.logo,
+    invert: surface === "light" && branding.invertLogoOnLightSurface,
+  };
+}

package/src/server/site-settings-core.ts

@@ -11,6 +11,9 @@ import { auditAs } from "./audit-core";
 import {
   OVERRIDABLE_SETTING_KEYS,
   parseSiteSettingOverrides,
+  resolveSiteConfig,
+  type SiteBranding,
+  type SiteConfig,
   type OverridableSettingKey,
   type SiteSettingOverrides,
 } from "../config/site-config";
@@ -87,3 +90,23 @@ export async function clearSiteSettingCore(
     });
   }
 }
+
+/**
+ * Public read of the resolved branding (logo artwork) for the running site.
+ *
+ * The public header needs the stored logo before any staff session exists, so
+ * this takes whatever client the host passes — typically the publishable one —
+ * and always falls back to the code defaults when nothing is stored.
+ */
+export async function loadSiteBrandingCore(
+  client: Client,
+  base: SiteConfig,
+): Promise<SiteBranding> {
+  try {
+    const overrides = await loadSiteSettingsCore(client);
+    return resolveSiteConfig(base, overrides).branding;
+  } catch {
+    // Branding must never break the header; code defaults are always valid.
+    return base.branding;
+  }
+}

package/src/site/SiteHeader.tsx

@@ -21,6 +21,10 @@ export type SiteHeaderProps = {
   brandName: LocalizedString;
   /** Logo/wordmark artwork. Light artwork is inverted on light surfaces. */
   logoSrc: string;
+  /** Optional dark-ink artwork used on light surfaces instead of inverting. */
+  logoDarkSrc?: string;
+  /** Accessible name for the logo image. Defaults to the brand name. */
+  logoAlt?: string;
   /** Set false when the logo artwork is already dark. */
   invertLogoOnLightSurface?: boolean;
   /** Primary call to action shown on desktop and at the end of the mobile panel. */
@@ -164,6 +168,8 @@ export function SiteHeader({
   nav,
   brandName,
   logoSrc,
+  logoDarkSrc,
+  logoAlt,
   invertLogoOnLightSurface = true,
   primaryCta,
   menuLabels,
@@ -201,6 +207,10 @@ export function SiteHeader({
 
   const lightText = lightTextPaths.includes(pathname) && !scrolled;
   const name = t(brandName);
+  // A dedicated dark artwork wins on light surfaces; otherwise invert the light one.
+  const onLightSurface = !lightText;
+  const logo = onLightSurface && logoDarkSrc ? logoDarkSrc : logoSrc;
+  const invertLogo = onLightSurface && !logoDarkSrc && invertLogoOnLightSurface;
   const showBackoffice = Boolean(backoffice?.signedIn);
 
   return (
@@ -213,11 +223,11 @@ export function SiteHeader({
       <div className="container-editorial flex h-16 items-center justify-between gap-4 md:h-20">
         <Link to="/" className="shrink-0 inline-flex items-center" aria-label={name}>
           <img
-            src={logoSrc}
-            alt={name}
+            src={logo}
+            alt={logoAlt?.trim() || name}
             className={[
               "h-10 w-auto md:h-12 transition-[filter] duration-500",
-              !lightText && invertLogoOnLightSurface ? "brightness-0" : "",
+              invertLogo ? "brightness-0" : "",
             ].join(" ")}
           />
         </Link>