@actuate-media/cms-admin 0.52.1 → 0.54.0

package/src/AdminRoot.tsx

@@ -7,6 +7,7 @@ import { Layout } from './layout/Layout.js'
 import { adminPortalContainer } from './lib/portal-container.js'
 import { useAdminRouter } from './router/index.js'
 import { cmsApi, ensureCsrfToken } from './lib/api.js'
+import { setDocumentFavicon, BRAND_UPDATED_EVENT } from './lib/favicon.js'
 import {
   registerSectionTypes,
   resetCustomSectionTypes,
@@ -743,50 +744,69 @@ function useBranding(config: any) {
 
   useEffect(() => {
     const branding = config?.admin?.branding
-    if (!branding) return
-
-    // --- Favicon ---
-    if (branding.favicon) {
-      const existing = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
-      originalFaviconRef.current = existing?.href ?? null
-
-      if (existing) {
-        existing.href = branding.favicon
-      } else {
-        const link = document.createElement('link')
-        link.rel = 'icon'
-        link.href = branding.favicon
-        document.head.appendChild(link)
-        injectedLinkRef.current = link
-      }
+
+    // Capture the originals up-front so cleanup can restore them even after the
+    // DB favicon (below) overrides whatever config set.
+    originalFaviconRef.current =
+      document.querySelector<HTMLLinkElement>('link[rel="icon"]')?.href ?? null
+    originalTitleRef.current = document.title
+
+    const applyFavicon = (href: string, type?: string | null) => {
+      const { link, created } = setDocumentFavicon(href, type)
+      if (created && !injectedLinkRef.current) injectedLinkRef.current = link
     }
 
+    // --- Static config favicon (instant, no network) ---
+    // Acts as a fast default; the DB favicon below overrides it when one is set
+    // in Settings → Appearance.
+    if (branding?.favicon) applyFavicon(branding.favicon)
+
     // --- Document title ---
-    originalTitleRef.current = document.title
-    if (branding.title) {
+    if (branding?.title) {
       document.title = branding.title
-    } else if (branding.name) {
+    } else if (branding?.name) {
       document.title = `${branding.name} Admin`
     }
 
     // --- Primary color ---
     const adminEl = document.querySelector<HTMLElement>('.actuate-admin')
-    if (branding.primaryColor && adminEl) {
+    if (branding?.primaryColor && adminEl) {
       adminEl.style.setProperty('--primary', branding.primaryColor)
       adminEl.style.setProperty('--sidebar-primary', branding.primaryColor)
     }
 
+    // --- DB favicon (Settings → Appearance) ---
+    // The uploaded favicon is the source of truth for the browser tab. Fetch it
+    // on mount and re-apply whenever the brand is saved, so the tab icon tracks
+    // the upload without a full reload. The admin request carries the session
+    // cookie, so the public/brand read bypasses any shared cache (see
+    // cache/http.ts) and is always fresh.
+    let cancelled = false
+    const applyDbFavicon = async () => {
+      try {
+        const res = await cmsApi<{ favicon?: { icon?: string | null; type?: string | null } }>(
+          '/public/brand',
+        )
+        const favicon = res.data?.favicon
+        if (!cancelled && favicon?.icon) applyFavicon(favicon.icon, favicon.type ?? undefined)
+      } catch {
+        /* brand API unavailable — keep the config/default favicon */
+      }
+    }
+    void applyDbFavicon()
+    const onBrandUpdated = () => void applyDbFavicon()
+    window.addEventListener(BRAND_UPDATED_EVENT, onBrandUpdated)
+
     return () => {
+      cancelled = true
+      window.removeEventListener(BRAND_UPDATED_EVENT, onBrandUpdated)
+
       // Restore favicon
-      if (branding.favicon) {
-        const link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
-        if (link && originalFaviconRef.current) {
-          link.href = originalFaviconRef.current
-        }
-        if (injectedLinkRef.current) {
-          injectedLinkRef.current.remove()
-          injectedLinkRef.current = null
-        }
+      const link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+      if (link && originalFaviconRef.current) link.href = originalFaviconRef.current
+      if (injectedLinkRef.current) {
+        injectedLinkRef.current.remove()
+        injectedLinkRef.current = null
       }
 
       // Restore title
@@ -795,7 +815,7 @@ function useBranding(config: any) {
       }
 
       // Remove primary color override
-      if (branding.primaryColor && adminEl) {
+      if (branding?.primaryColor && adminEl) {
         adminEl.style.removeProperty('--primary')
         adminEl.style.removeProperty('--sidebar-primary')
       }

package/src/__tests__/layout/sidebar-brand.render.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
-import { describe, expect, it, vi } from 'vitest'
-import { render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
 
 // The sidebar fetches forms unread counts on mount; stub it so these brand
 // tests stay offline and deterministic.
@@ -8,25 +8,40 @@ vi.mock('../../lib/forms-service.js', () => ({
   fetchFormsSidebarCounts: vi.fn(async () => []),
 }))
 
-// Drive the brand lockup directly: a branded install (initials derived from a
-// site title) with no uploaded logo. happy-dom's localStorage stub is
-// unreliable here, so we mock the theme hook rather than hydrating it.
+// Drive the brand lockup directly via a mutable theme state. happy-dom's
+// localStorage stub is unreliable here, so we mock the theme hook rather than
+// hydrating it. Tests mutate `themeState` before rendering.
+interface ThemeState {
+  adminBrand: {
+    primaryUrl: string | null
+    markUrl: string | null
+    darkUrl: string | null
+    initials: string
+  }
+  resolvedTheme: string
+  density: string
+}
+const DEFAULT_THEME: ThemeState = {
+  adminBrand: { primaryUrl: null, markUrl: null, darkUrl: null, initials: 'AC' },
+  resolvedTheme: 'light',
+  density: 'default',
+}
+let themeState: ThemeState = { ...DEFAULT_THEME }
+
 vi.mock('../../components/ThemeProvider.js', () => ({
-  useTheme: () => ({
-    adminBrand: { primaryUrl: null, markUrl: null, darkUrl: null, initials: 'AC' },
-    resolvedTheme: 'light',
-    density: 'default',
-  }),
+  useTheme: () => themeState,
 }))
 
 const { Sidebar } = await import('../../layout/Sidebar.js')
 
-/**
- * Brand lockup fallback behaviour. When an install is branded (a site name is
- * set, so initials exist) but no logo has been uploaded, the sidebar must show
- * the neutral logo placeholder — NOT a filled initials badge, which reads as a
- * user avatar (the real account avatar already lives top-right).
- */
+function setTheme(brand: Partial<ThemeState['adminBrand']>, resolvedTheme = 'light') {
+  themeState = {
+    ...DEFAULT_THEME,
+    resolvedTheme,
+    adminBrand: { ...DEFAULT_THEME.adminBrand, ...brand },
+  }
+}
+
 function renderSidebar(collapsed: boolean, config?: unknown) {
   return render(
     <Sidebar
@@ -39,6 +54,16 @@ function renderSidebar(collapsed: boolean, config?: unknown) {
   )
 }
 
+afterEach(() => {
+  themeState = { ...DEFAULT_THEME }
+})
+
+/**
+ * Brand lockup fallback behaviour. When an install is branded (a site name is
+ * set, so initials exist) but no logo has been uploaded, the sidebar must show
+ * the neutral logo placeholder — NOT a filled initials badge, which reads as a
+ * user avatar (the real account avatar already lives top-right).
+ */
 describe('Sidebar brand placeholder', () => {
   it('renders the logo placeholder (not an initials avatar) when branded with no logo — expanded', () => {
     renderSidebar(false, { admin: { branding: { name: 'Acme Co' } } })
@@ -56,3 +81,54 @@ describe('Sidebar brand placeholder', () => {
     expect(screen.queryByText('AC')).toBeNull()
   })
 })
+
+describe('Sidebar brand logo rendering', () => {
+  it('shows the primary logo (scaled to fit) when collapsed — never the favicon', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/logo.svg' })
+    renderSidebar(true)
+
+    const img = screen.getByRole('img', { name: 'Admin' }) as HTMLImageElement
+    expect(img.src).toContain('logo.svg')
+    // Wide logos must be width-capped so they scale down instead of overflowing.
+    expect(img.className).toContain('max-w-full')
+  })
+
+  it('caps the expanded logo width so wide logos stay responsive', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/logo.svg' })
+    renderSidebar(false)
+
+    const img = screen.getByRole('img', { name: 'Admin' }) as HTMLImageElement
+    expect(img.className).toContain('max-w-full')
+    expect(img.className).toContain('object-contain')
+  })
+
+  it('prefers the dark logo in dark mode and falls back to primary on error', () => {
+    setTheme(
+      {
+        primaryUrl: 'https://cdn.example.com/logo.svg',
+        darkUrl: 'https://cdn.example.com/dark.svg',
+      },
+      'dark',
+    )
+    renderSidebar(false)
+
+    const img = screen.getByRole('img', { name: 'Admin' }) as HTMLImageElement
+    expect(img.src).toContain('dark.svg')
+  })
+
+  it('falls through to the placeholder when the logo URL is broken (onError)', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/broken.svg' })
+    renderSidebar(false, { admin: { branding: { name: 'Acme Co' } } })
+
+    // With a brand name configured, the logo alt is the brand name.
+    const img = screen.getByRole('img', { name: 'Acme Co' }) as HTMLImageElement
+    expect(img.src).toContain('broken.svg')
+    // Simulate the asset URL failing to load.
+    fireEvent.error(img)
+
+    // The broken logo is gone; the neutral placeholder + brand name take over
+    // (no browser broken-image glyph left behind).
+    expect(screen.queryByRole('img', { name: 'Acme Co' })).toBeNull()
+    expect(screen.getByText('Acme Co')).toBeTruthy()
+  })
+})

package/src/__tests__/lib/favicon.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { setDocumentFavicon, BRAND_UPDATED_EVENT } from '../../lib/favicon.js'
+
+afterEach(() => {
+  document.head.querySelectorAll('link[rel="icon"]').forEach((l) => l.remove())
+})
+
+describe('setDocumentFavicon', () => {
+  it('creates a link[rel=icon] when the document has none', () => {
+    const { created, previousHref, link } = setDocumentFavicon(
+      'https://cdn.example.com/fav.png',
+      'image/png',
+    )
+    expect(created).toBe(true)
+    expect(previousHref).toBeNull()
+    expect(link.rel).toBe('icon')
+    const found = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+    expect(found).not.toBeNull()
+    expect(found!.href).toContain('fav.png')
+    expect(found!.type).toBe('image/png')
+  })
+
+  it('updates the existing link in place and reports the previous href', () => {
+    const existing = document.createElement('link')
+    existing.rel = 'icon'
+    existing.href = 'https://cdn.example.com/old.png'
+    document.head.appendChild(existing)
+
+    const { created, previousHref, link } = setDocumentFavicon(
+      'https://cdn.example.com/new.svg',
+      'image/svg+xml',
+    )
+    expect(created).toBe(false)
+    expect(previousHref).toContain('old.png')
+    expect(link).toBe(existing)
+    expect(existing.href).toContain('new.svg')
+    expect(existing.type).toBe('image/svg+xml')
+    // Never duplicates the icon link.
+    expect(document.querySelectorAll('link[rel="icon"]').length).toBe(1)
+  })
+
+  it('preserves the existing type when no new type is provided', () => {
+    setDocumentFavicon('https://cdn.example.com/a.png', 'image/png')
+    setDocumentFavicon('https://cdn.example.com/b.png')
+    const link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+    expect(link!.href).toContain('b.png')
+    expect(link!.type).toBe('image/png')
+  })
+
+  it('exposes a stable brand-updated event name', () => {
+    expect(BRAND_UPDATED_EVENT).toBe('actuate:brand-updated')
+  })
+})

package/src/__tests__/views/section-inspector-media.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { companionDimensionKeys } from '../../views/page-editor/SectionInspector.js'
+
+describe('companionDimensionKeys', () => {
+  it('maps a *Url field to *Width / *Height (feature, hero)', () => {
+    expect(companionDimensionKeys('imageUrl')).toEqual({
+      width: 'imageWidth',
+      height: 'imageHeight',
+    })
+    expect(companionDimensionKeys('backgroundUrl')).toEqual({
+      width: 'backgroundWidth',
+      height: 'backgroundHeight',
+    })
+  })
+
+  it('maps a gallery-row `url` field to plain width / height', () => {
+    expect(companionDimensionKeys('url')).toEqual({ width: 'width', height: 'height' })
+  })
+
+  it('falls back to <key>Width / <key>Height for other keys', () => {
+    expect(companionDimensionKeys('photo')).toEqual({ width: 'photoWidth', height: 'photoHeight' })
+  })
+})

package/src/layout/Sidebar.tsx

@@ -98,16 +98,39 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
   const initials = adminBrand.initials
   const hasInitials = Boolean(initials) && initials !== 'A'
 
-  // Prefer the dark logo on dark backgrounds when supplied.
-  const primary =
-    resolvedTheme === 'dark' && adminBrand.darkUrl ? adminBrand.darkUrl : adminBrand.primaryUrl
-  const mark = adminBrand.markUrl
+  // Track image URLs that fail to load (broken/expired/deleted asset) so the
+  // resolution falls through to the next option instead of showing the browser's
+  // broken-image icon in the sidebar header.
+  const [failedSrcs, setFailedSrcs] = useState<Set<string>>(new Set())
+  const markFailed = (src: string) =>
+    setFailedSrcs((prev) => (prev.has(src) ? prev : new Set(prev).add(src)))
+  const usable = (url: string | null | undefined): string | null =>
+    url && !failedSrcs.has(url) ? url : null
+  const onErr = (src: string) => () => markFailed(src)
+
+  // The admin brand is ALWAYS the logo — the favicon is only for the browser tab
+  // and is never used here (see resolveAdminBrand). Prefer the dark logo on dark
+  // backgrounds when supplied, falling back to the primary if the dark asset is
+  // missing or broken.
+  const darkPref = resolvedTheme === 'dark' ? adminBrand.darkUrl : null
+  const primary = usable(darkPref) ?? usable(adminBrand.primaryUrl)
+  const mark = usable(adminBrand.markUrl)
+  const cfg = usable(configLogo)
   const alt = brandName ?? 'Admin'
 
+  // Wide horizontal logos must scale down to fit the narrow rail / sidebar
+  // header instead of overflowing — height-capped, width auto, never wider than
+  // the available space.
+  const logoClass = 'h-8 w-auto max-w-full object-contain'
+
   if (collapsed) {
-    if (mark) return <img src={mark} alt={alt} className="h-8 w-8 object-contain" />
-    if (primary) return <img src={primary} alt={alt} className="h-8 w-8 object-contain" />
-    if (configLogo) return <img src={configLogo} alt={alt} className="h-8 w-8 object-contain" />
+    // Collapsed rail prefers a dedicated square mark; otherwise it shows the
+    // logo (scaled to fit) — never the favicon.
+    if (mark)
+      return <img src={mark} alt={alt} className="h-8 w-8 object-contain" onError={onErr(mark)} />
+    if (primary)
+      return <img src={primary} alt={alt} className={logoClass} onError={onErr(primary)} />
+    if (cfg) return <img src={cfg} alt={alt} className={logoClass} onError={onErr(cfg)} />
     if (hasInitials) return <LogoPlaceholder tone="sidebar" />
     return <ActuateMark className="h-8 w-8" />
   }
@@ -115,7 +138,7 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
   if (primary) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">
-        <img src={primary} alt={alt} className="h-8 w-auto shrink-0 object-contain" />
+        <img src={primary} alt={alt} className={logoClass} onError={onErr(primary)} />
         {brandName && (
           <span className="text-sidebar-foreground truncate text-sm font-medium">{brandName}</span>
         )}
@@ -123,10 +146,10 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
     )
   }
 
-  if (configLogo) {
+  if (cfg) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">
-        <img src={configLogo} alt={alt} className="h-8 w-auto shrink-0 object-contain" />
+        <img src={cfg} alt={alt} className={logoClass} onError={onErr(cfg)} />
         {brandName && (
           <span className="text-sidebar-foreground truncate text-sm font-medium">{brandName}</span>
         )}
@@ -137,7 +160,12 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
   if (mark) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">
-        <img src={mark} alt={alt} className="h-8 w-8 shrink-0 object-contain" />
+        <img
+          src={mark}
+          alt={alt}
+          className="h-8 w-8 shrink-0 object-contain"
+          onError={onErr(mark)}
+        />
         <span className="text-sidebar-foreground truncate text-sm font-medium">
           {brandName ?? alt}
         </span>

package/src/lib/favicon.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser-tab favicon helpers for the admin SPA.
+ *
+ * The admin runs as a client app, so the favicon shown in the browser tab is
+ * whatever `<link rel="icon">` the document currently has. The Settings →
+ * Appearance favicon (stored in the CMS) is the source of truth, so the admin
+ * applies it at runtime instead of relying on the host app's `<head>` wiring.
+ */
+
+/**
+ * Window event the admin dispatches after the brand (logo/favicon) is saved so
+ * live surfaces — the browser tab favicon — refresh without a full reload.
+ */
+export const BRAND_UPDATED_EVENT = 'actuate:brand-updated'
+
+export interface FaviconUpdate {
+  /** The `<link rel="icon">` element that is now active. */
+  link: HTMLLinkElement
+  /** True when we created the link (so callers can remove it on cleanup). */
+  created: boolean
+  /** The href the link had before this update — for restore on cleanup. */
+  previousHref: string | null
+}
+
+/**
+ * Point the browser tab favicon at `href`, creating the `<link rel="icon">` when
+ * the document doesn't already have one. Returns enough state for the caller to
+ * restore/remove it on cleanup. Client-only — call inside an effect.
+ */
+export function setDocumentFavicon(href: string, type?: string | null): FaviconUpdate {
+  const existing = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+  if (existing) {
+    const previousHref = existing.href || null
+    existing.href = href
+    if (type) existing.type = type
+    return { link: existing, created: false, previousHref }
+  }
+  const link = document.createElement('link')
+  link.rel = 'icon'
+  link.href = href
+  if (type) link.type = type
+  document.head.appendChild(link)
+  return { link, created: true, previousHref: null }
+}

package/src/views/page-editor/SectionInspector.tsx

@@ -148,6 +148,7 @@ export function SectionInspector({
               field={field}
               value={section.content[field.key]}
               onChange={(v) => onContentChange({ [field.key]: v })}
+              onPatch={(patch) => onContentChange(patch)}
             />
           ))}
         </fieldset>
@@ -302,11 +303,17 @@ function ContentField({
   field,
   value,
   onChange,
+  onPatch,
   id: idProp,
 }: {
   field: SectionFieldDef
   value: unknown
   onChange: (v: unknown) => void
+  /**
+   * Optional multi-key patch sink — lets media fields persist companion
+   * dimension keys (width/height) atomically with the URL.
+   */
+  onPatch?: (patch: Record<string, unknown>) => void
   /** Explicit input id (repeater rows pass a row-scoped id to stay unique). */
   id?: string
 }) {
@@ -335,7 +342,7 @@ function ContentField({
   }
 
   if (field.type === 'media') {
-    return <MediaField id={id} field={field} value={text} onChange={onChange} />
+    return <MediaField id={id} field={field} value={text} onChange={onChange} onPatch={onPatch} />
   }
 
   if (field.type === 'select') {
@@ -393,16 +400,39 @@ function ContentField({
   )
 }
 
+/**
+ * Companion content keys that hold an image field's intrinsic dimensions.
+ * Picking from the media library persists width/height alongside the URL so the
+ * public renderer can use the CLS-safe `next/image` path without waiting on
+ * read-time `/resolve` enrichment. Mirrors the keys the section renderers read:
+ *   `imageUrl` → `imageWidth` / `imageHeight`; `url` (gallery row) → `width` / `height`.
+ */
+export function companionDimensionKeys(fieldKey: string): { width: string; height: string } {
+  if (fieldKey === 'url') return { width: 'width', height: 'height' }
+  if (fieldKey.endsWith('Url')) {
+    const base = fieldKey.slice(0, -'Url'.length)
+    return { width: `${base}Width`, height: `${base}Height` }
+  }
+  return { width: `${fieldKey}Width`, height: `${fieldKey}Height` }
+}
+
 function MediaField({
   id,
   field,
   value,
   onChange,
+  onPatch,
 }: {
   id: string
   field: SectionFieldDef
   value: string
   onChange: (v: unknown) => void
+  /**
+   * When provided, picking from the library applies a multi-key patch (URL +
+   * intrinsic width/height) in one update. Falls back to `onChange` (URL only)
+   * for manual entry and when no patch sink is wired.
+   */
+  onPatch?: (patch: Record<string, unknown>) => void
 }) {
   const [open, setOpen] = useState(false)
   return (
@@ -434,8 +464,18 @@ function MediaField({
       <MediaPickerModal
         open={open}
         onClose={() => setOpen(false)}
+        onSelectItem={(item) => {
+          if (!onPatch) return
+          const { width: wKey, height: hKey } = companionDimensionKeys(field.key)
+          const patch: Record<string, unknown> = { [field.key]: item.url }
+          if (typeof item.width === 'number') patch[wKey] = item.width
+          if (typeof item.height === 'number') patch[hKey] = item.height
+          onPatch(patch)
+        }}
         onSelect={(url) => {
-          onChange(url)
+          // onSelectItem handles persistence when a patch sink is wired; only
+          // fall back to a URL-only update when it isn't.
+          if (!onPatch) onChange(url)
           setOpen(false)
         }}
         accept="image/*"
@@ -743,6 +783,7 @@ function SortableRepeaterRow({
             field={sub}
             value={row[sub.key]}
             onChange={(v) => onPatch({ [sub.key]: v })}
+            onPatch={(patch) => onPatch(patch)}
           />
         ))}
       </div>

package/src/views/settings/BrandingCard.tsx

@@ -64,10 +64,14 @@ function LogoField({
 }) {
   const inputRef = useRef<HTMLInputElement>(null)
   const [pickerOpen, setPickerOpen] = useState(false)
+  // Remember a preview URL that failed to load so a broken/expired asset shows
+  // the neutral placeholder icon instead of the browser's broken-image glyph.
+  const [thumbErrorUrl, setThumbErrorUrl] = useState<string | null>(null)
   const assetId = brand[field]
   const asset = assetId ? assets[assetId] : undefined
   const uploading = uploadingField === field
   const inputId = `brand-${field}`
+  const showPreview = Boolean(asset?.url) && asset?.url !== thumbErrorUrl
 
   const thumbnail = (
     <div
@@ -76,12 +80,13 @@ function LogoField({
       )} ${square ? 'h-12 w-12' : 'h-12 w-20'}`}
       aria-hidden={!asset}
     >
-      {asset?.url ? (
+      {showPreview ? (
         // Never stretch/crop — contain preserves aspect ratio + transparency.
         <img
-          src={asset.url}
+          src={asset!.url}
           alt={`${label} preview`}
           className="max-h-full max-w-full object-contain"
+          onError={() => setThumbErrorUrl(asset!.url)}
         />
       ) : (
         <ImageIcon size={18} className="text-muted-foreground" aria-hidden="true" />

package/src/views/settings/useAppearanceSettings.ts

@@ -20,6 +20,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import { useTheme, type AdminBrandCache } from '../../components/ThemeProvider.js'
 import { cmsApi } from '../../lib/api.js'
+import { BRAND_UPDATED_EVENT } from '../../lib/favicon.js'
 import type { SettingsSourceMetadata, ValidationIssue } from './useGeneralSettings.js'
 
 export type SaveState = 'idle' | 'saving' | 'success' | 'error'
@@ -548,6 +549,11 @@ export function useAppearanceSettings(
     }
     baselineRef.current = snapshot(appearance, brand)
     setAdminBrand(assetToCache(brand, assets, siteTitleRef.current))
+    // Notify live surfaces (browser-tab favicon) to refresh from the saved
+    // brand without a full reload.
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(BRAND_UPDATED_EVENT))
+    }
     setSaveState('success')
   }, [canEdit, issues, appearance, brand, assets, setAdminBrand])