@actuate-media/cms-admin 0.36.1 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cms-admin",
-  "version": "0.36.1",
+  "version": "0.37.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/actuate-media/actuatecms.git",
@@ -88,7 +88,7 @@
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.0",
-    "@actuate-media/cms-core": "0.46.0",
+    "@actuate-media/cms-core": "0.47.0",
     "@actuate-media/component-blocks": "0.2.0"
   },
   "scripts": {

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

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+
+// The sidebar fetches forms unread counts on mount; stub it so these brand
+// tests stay offline and deterministic.
+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.
+vi.mock('../../components/ThemeProvider.js', () => ({
+  useTheme: () => ({
+    adminBrand: { primaryUrl: null, markUrl: null, darkUrl: null, initials: 'AC' },
+    resolvedTheme: 'light',
+    density: 'default',
+  }),
+}))
+
+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 renderSidebar(collapsed: boolean, config?: unknown) {
+  return render(
+    <Sidebar
+      collapsed={collapsed}
+      onToggleCollapse={() => {}}
+      currentPath="/"
+      onNavigate={() => {}}
+      config={config}
+    />,
+  )
+}
+
+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' } } })
+
+    // Placeholder slot is present and the brand name shows beside it.
+    expect(screen.getByText('Acme Co')).toBeTruthy()
+    // The old avatar-style initials badge must not render.
+    expect(screen.queryByText('AC')).toBeNull()
+  })
+
+  it('renders the logo placeholder slot when branded with no logo — collapsed', () => {
+    renderSidebar(true)
+
+    expect(screen.getByRole('img', { name: 'Logo placeholder' })).toBeTruthy()
+    expect(screen.queryByText('AC')).toBeNull()
+  })
+})

package/src/__tests__/views/appearance-settings.render.test.tsx

@@ -51,9 +51,9 @@ describe('AppearanceTab', () => {
     render(<AppearanceTab role="ADMIN" />)
 
     await screen.findByText('Branding')
-    expect(screen.getByText('Admin Theme')).toBeTruthy()
-    expect(screen.getByText('Typography & Motion')).toBeTruthy()
-    expect(screen.getByText('Brand Preview')).toBeTruthy()
+    expect(screen.getByText('Admin theme')).toBeTruthy()
+    expect(screen.getByText('Typography & motion')).toBeTruthy()
+    expect(screen.getByText('Brand preview')).toBeTruthy()
     expect(
       (screen.getByRole('button', { name: 'Save Changes' }) as HTMLButtonElement).disabled,
     ).toBe(true)
@@ -99,7 +99,7 @@ describe('AppearanceTab', () => {
     render(<AppearanceTab role="ADMIN" />)
     await screen.findByText('Branding')
 
-    const input = screen.getByLabelText('Primary Logo') as HTMLInputElement
+    const input = screen.getByLabelText('Primary logo') as HTMLInputElement
     const file = new File(
       ['<svg viewBox="0 0 400 100" xmlns="http://www.w3.org/2000/svg"></svg>'],
       'logo.svg',

package/src/__tests__/views/login-branding.render.test.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+
+/**
+ * The login screen resolves its logo to match the admin sidebar:
+ *   1. the brand uploaded in Settings → Appearance (cached admin brand, then
+ *      the unauthenticated `/public/brand` endpoint for fresh browsers),
+ *   2. the static `config.admin.branding.logo`,
+ *   3. the bundled Actuate wordmark,
+ * and `branding.logo === null` hides the logo entirely (whitelabel opt-out).
+ *
+ * `cmsApi` is mocked because the component fetches `/public/brand` on mount.
+ */
+const cmsApiMock = vi.fn()
+vi.mock('../../lib/api.js', () => ({
+  cmsApi: (...args: unknown[]) => cmsApiMock(...args),
+}))
+
+import { Login } from '../../views/Login.js'
+
+const onLogin = vi.fn(async () => ({ success: true }))
+
+beforeEach(() => {
+  cmsApiMock.mockReset()
+  // Default: no public brand configured.
+  cmsApiMock.mockResolvedValue({ data: {}, status: 200 })
+})
+
+describe('Login — logo resolution', () => {
+  it('renders the bundled Actuate logo when nothing is branded', async () => {
+    render(<Login onLogin={onLogin} />)
+    // Bundled SVG exposes role="img" + aria-label="Actuate Media".
+    expect(screen.getByRole('img', { name: 'Actuate Media' })).toBeTruthy()
+    // No <img> logo element.
+    expect(screen.queryByRole('img', { name: 'Actuate CMS' })).toBeNull()
+    await waitFor(() => expect(cmsApiMock).toHaveBeenCalledWith('/public/brand'))
+  })
+
+  it('shows the neutral logo placeholder when branded but no logo is set', async () => {
+    render(<Login onLogin={onLogin} branding={{ name: 'Acme Co' }} />)
+    // Placeholder slot, not the bundled Actuate wordmark.
+    expect(screen.getByRole('img', { name: 'Logo placeholder' })).toBeTruthy()
+    expect(screen.queryByRole('img', { name: 'Actuate Media' })).toBeNull()
+    // The brand name still renders as the headline.
+    expect(screen.getByRole('heading', { name: 'Acme Co' })).toBeTruthy()
+  })
+
+  it('shows the placeholder for a fresh browser when /public/brand reports a branded site (initials) but no logo', async () => {
+    // No config name, no cached admin brand — only the public brand initials
+    // signal a branded install. The logo-less fallback must be the placeholder,
+    // not the Actuate wordmark.
+    cmsApiMock.mockResolvedValue({
+      data: { public: { primary: null, initials: 'AC' } },
+      status: 200,
+    })
+
+    render(<Login onLogin={onLogin} />)
+
+    await waitFor(() => {
+      expect(screen.getByRole('img', { name: 'Logo placeholder' })).toBeTruthy()
+    })
+    expect(screen.queryByRole('img', { name: 'Actuate Media' })).toBeNull()
+  })
+
+  it('uses the static config logo when no appearance brand exists', async () => {
+    render(
+      <Login onLogin={onLogin} branding={{ logo: 'https://cdn.example.com/config-logo.png' }} />,
+    )
+    const img = (await screen.findByAltText('Actuate CMS')) as HTMLImageElement
+    expect(img.getAttribute('src')).toBe('https://cdn.example.com/config-logo.png')
+  })
+
+  it('prefers the uploaded appearance logo from /public/brand over the config logo', async () => {
+    cmsApiMock.mockResolvedValue({
+      data: { public: { primary: { url: 'https://cdn.example.com/appearance-logo.svg' } } },
+      status: 200,
+    })
+
+    render(
+      <Login onLogin={onLogin} branding={{ logo: 'https://cdn.example.com/config-logo.png' }} />,
+    )
+
+    await waitFor(() => {
+      const img = screen.getByAltText('Actuate CMS') as HTMLImageElement
+      expect(img.getAttribute('src')).toBe('https://cdn.example.com/appearance-logo.svg')
+    })
+  })
+
+  it('hides the logo entirely when branding.logo is null (whitelabel) and skips the fetch', async () => {
+    render(<Login onLogin={onLogin} branding={{ logo: null }} />)
+    expect(screen.queryByRole('img', { name: 'Actuate Media' })).toBeNull()
+    expect(screen.queryByAltText('Actuate CMS')).toBeNull()
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/views/login-mfa.render.test.tsx

@@ -2,6 +2,13 @@
 import { describe, expect, it, vi } from 'vitest'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 
+// The login screen fetches `/public/brand` on mount to mirror the sidebar
+// logo. These MFA tests don't care about branding — stub the network so the
+// real `cmsApi` (which reads localStorage) doesn't run in this environment.
+vi.mock('../../lib/api.js', () => ({
+  cmsApi: vi.fn(async () => ({ data: {}, status: 200 })),
+}))
+
 import { Login } from '../../views/Login.js'
 
 /**

package/src/__tests__/views/updates-tab.render.test.tsx

@@ -0,0 +1,161 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+// The Updates tab reads `/updates/check`, saves GitHub config via
+// PUT `/updates/config`, and opens an upgrade PR via POST `/updates/apply`.
+let checkData: any
+
+const cmsApi = vi.fn(async (endpoint: string, options?: { method?: string; body?: unknown }) => {
+  const method = options?.method ?? 'GET'
+  if (endpoint === '/updates/check' && method === 'GET') return { data: checkData, status: 200 }
+  if (endpoint === '/updates/config' && method === 'PUT')
+    return { data: { success: true }, status: 200 }
+  if (endpoint === '/updates/apply' && method === 'POST')
+    return { data: { prUrl: 'https://github.com/x/y/pull/1', prNumber: 1 }, status: 200 }
+  return { data: {}, status: 200 }
+})
+
+vi.mock('../../lib/api.js', () => ({ cmsApi: (e: string, o?: unknown) => cmsApi(e, o as any) }))
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn(), loading: vi.fn() } }))
+
+const { UpdatesTab } = await import('../../views/settings/UpdatesTab.js')
+
+function upToDate(overrides: Record<string, unknown> = {}) {
+  return {
+    current: '0.46.0',
+    latest: '0.46.0',
+    updateAvailable: false,
+    canManage: true,
+    hasGithubToken: false,
+    githubRepo: '',
+    source: 'update-server',
+    ...overrides,
+  }
+}
+
+function updateAvailable(overrides: Record<string, unknown> = {}) {
+  return {
+    current: '0.45.0',
+    latest: '0.46.0',
+    updateAvailable: true,
+    severity: 'minor',
+    releaseDate: '2026-01-02',
+    changelog: [
+      {
+        version: '0.46.0',
+        date: '2026-01-02',
+        summary: 'Add Brand Voice training',
+        type: 'feature',
+      },
+    ],
+    hasMigrations: true,
+    breakingChanges: ['Removed the legacy provider API'],
+    pluginCompatibility: [
+      { name: '@actuate-media/plugin-seo', compatible: true, minVersion: '0.46.0' },
+    ],
+    updateCommand: 'npm update @actuate-media/cms-core',
+    canManage: true,
+    hasGithubToken: false,
+    githubRepo: '',
+    source: 'update-server',
+    ...overrides,
+  }
+}
+
+beforeEach(() => {
+  cmsApi.mockClear()
+  checkData = upToDate()
+})
+
+describe('UpdatesTab', () => {
+  it('shows the current version and an up-to-date banner', async () => {
+    render(<UpdatesTab role="ADMIN" />)
+    await screen.findByText("You're up to date!")
+    expect(screen.getAllByText('0.46.0').length).toBeGreaterThan(0)
+    // Admins see the GitHub integration card.
+    expect(screen.getByText('GitHub Integration')).toBeTruthy()
+  })
+
+  it('surfaces severity, real changelog, migrations and breaking changes', async () => {
+    checkData = updateAvailable()
+    render(<UpdatesTab role="ADMIN" />)
+
+    await screen.findByText('Update available')
+    expect(screen.getByText('Minor')).toBeTruthy()
+    expect(screen.getByText('Add Brand Voice training')).toBeTruthy()
+    expect(screen.getByText('Database migrations required')).toBeTruthy()
+    expect(screen.getByText('Breaking changes in this release')).toBeTruthy()
+    expect(screen.getByText('Removed the legacy provider API')).toBeTruthy()
+    // Plugin compatibility surfaced.
+    expect(screen.getByText('plugin-seo')).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Create Update PR' })).toBeTruthy()
+  })
+
+  it('flags a security release prominently', async () => {
+    checkData = updateAvailable({ severity: 'security' })
+    render(<UpdatesTab role="ADMIN" />)
+    await screen.findByText('Security update available')
+    expect(screen.getByText('Security')).toBeTruthy()
+  })
+
+  it('is permission-aware: non-admins cannot manage updates', async () => {
+    checkData = updateAvailable({ canManage: false })
+    render(<UpdatesTab role="EDITOR" />)
+
+    await screen.findByText('Update available')
+    expect(screen.queryByText('GitHub Integration')).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Create Update PR' })).toBeNull()
+    expect(screen.getByText(/Ask an administrator/i)).toBeTruthy()
+  })
+
+  it('enables Save when the repo changes and persists via PUT /updates/config', async () => {
+    render(<UpdatesTab role="ADMIN" />)
+    await screen.findByText('GitHub Integration')
+
+    const save = screen.getByRole('button', { name: 'Save Changes' }) as HTMLButtonElement
+    expect(save.disabled).toBe(true)
+
+    const repo = screen.getByLabelText('Repository') as HTMLInputElement
+    fireEvent.change(repo, { target: { value: 'actuate-media/site' } })
+    expect(save.disabled).toBe(false)
+
+    fireEvent.click(save)
+    await waitFor(() =>
+      expect(cmsApi).toHaveBeenCalledWith(
+        '/updates/config',
+        expect.objectContaining({
+          method: 'PUT',
+          body: expect.stringContaining('actuate-media/site'),
+        }),
+      ),
+    )
+  })
+
+  it('blocks Save on an invalid repository format', async () => {
+    render(<UpdatesTab role="ADMIN" />)
+    await screen.findByText('GitHub Integration')
+
+    const repo = screen.getByLabelText('Repository') as HTMLInputElement
+    fireEvent.change(repo, { target: { value: 'not a repo' } })
+
+    expect(screen.getByText(/owner\/repo format/i)).toBeTruthy()
+    const save = screen.getByRole('button', { name: 'Save Changes' }) as HTMLButtonElement
+    expect(save.disabled).toBe(true)
+  })
+
+  it('creates an update PR via POST /updates/apply', async () => {
+    checkData = updateAvailable()
+    render(<UpdatesTab role="ADMIN" />)
+    await screen.findByText('Update available')
+
+    fireEvent.click(screen.getByRole('button', { name: 'Create Update PR' }))
+    await waitFor(() =>
+      expect(cmsApi).toHaveBeenCalledWith(
+        '/updates/apply',
+        expect.objectContaining({ method: 'POST', body: expect.stringContaining('0.46.0') }),
+      ),
+    )
+    await screen.findByText('Pull Request Created')
+  })
+})

package/src/components/LogoPlaceholder.tsx

@@ -0,0 +1,55 @@
+'use client'
+
+import { ImagePlus } from 'lucide-react'
+
+/**
+ * Neutral "logo goes here" placeholder shown when no brand logo has been
+ * uploaded or configured. Deliberately reads as an empty slot — a dashed
+ * outline with a muted image icon — rather than a filled initials badge, which
+ * looks like a user avatar (the real account avatar already lives top-right).
+ *
+ * It is automatically superseded the moment a logo is set in Settings →
+ * Appearance, since every logo branch takes precedence over this fallback.
+ */
+export interface LogoPlaceholderProps {
+  /** Color treatment so the slot blends with its surface. */
+  tone: 'sidebar' | 'login'
+  /** Brand/site name rendered beside the slot (expanded sidebar only). */
+  label?: string
+}
+
+export function LogoPlaceholder({ tone, label }: LogoPlaceholderProps) {
+  if (tone === 'login') {
+    return (
+      <span
+        role="img"
+        aria-label="Logo placeholder"
+        title="Add a logo in Settings → Appearance"
+        className="mx-auto mb-4 flex h-14 w-14 items-center justify-center rounded-lg border border-dashed border-gray-300 text-gray-400"
+      >
+        <ImagePlus className="h-6 w-6" aria-hidden="true" />
+      </span>
+    )
+  }
+
+  const slot = (
+    <span
+      className="border-sidebar-border text-sidebar-foreground/50 inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-md border border-dashed"
+      role={label ? undefined : 'img'}
+      aria-hidden={label ? true : undefined}
+      aria-label={label ? undefined : 'Logo placeholder'}
+      title="Add a logo in Settings → Appearance"
+    >
+      <ImagePlus size={16} aria-hidden="true" />
+    </span>
+  )
+
+  if (!label) return slot
+
+  return (
+    <div className="flex min-w-0 items-center gap-2.5">
+      {slot}
+      <span className="text-sidebar-foreground truncate text-sm font-medium">{label}</span>
+    </div>
+  )
+}

package/src/layout/Sidebar.tsx

@@ -34,6 +34,7 @@ import {
 } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { ActuateBrandLogo } from '../assets/actuate-logo.js'
+import { LogoPlaceholder } from '../components/LogoPlaceholder.js'
 
 /**
  * Compact mark used in the collapsed sidebar — just the "C" symbol from the
@@ -76,28 +77,17 @@ const ICON_MAP: Record<string, LucideIcon> = {
   Layers: Layers,
 }
 
-/** Square site-initials badge — the final fallback before the Actuate mark. */
-function InitialsBadge({ initials, size }: { initials: string; size: 'sm' | 'lg' }) {
-  return (
-    <span
-      className={`bg-sidebar-primary text-sidebar-primary-foreground inline-flex shrink-0 items-center justify-center rounded-md font-medium ${
-        size === 'lg' ? 'h-8 w-8 text-sm' : 'h-8 w-8 text-sm'
-      }`}
-      aria-hidden="true"
-    >
-      {initials}
-    </span>
-  )
-}
-
 /**
  * Sidebar brand lockup.
  *
  * Resolution order follows the Appearance spec, sourcing from the live
  * appearance context (DB-backed brand, cached in localStorage) and falling
- * back to legacy `config.admin.branding`, then site initials, then the bundled
- * Actuate mark/wordmark for un-branded installs. Dark-mode uses the dark logo
- * when one is configured. Logos are never stretched/cropped (object-contain).
+ * back to legacy `config.admin.branding`, then a neutral logo placeholder for
+ * branded-but-logo-less installs, then the bundled Actuate mark/wordmark for
+ * un-branded installs. The placeholder replaces the old initials badge, which
+ * read as a user avatar (the real account avatar already sits top-right).
+ * Dark-mode uses the dark logo when one is configured. Logos are never
+ * stretched/cropped (object-contain).
  */
 function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean }) {
   const { adminBrand, resolvedTheme } = useTheme()
@@ -117,7 +107,7 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
     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" />
-    if (hasInitials) return <InitialsBadge initials={initials} size="sm" />
+    if (hasInitials) return <LogoPlaceholder tone="sidebar" />
     return <ActuateMark className="h-8 w-8" />
   }
 
@@ -143,14 +133,10 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
     )
   }
 
-  if (mark || hasInitials) {
+  if (mark) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">
-        {mark ? (
-          <img src={mark} alt={alt} className="h-8 w-8 shrink-0 object-contain" />
-        ) : (
-          <InitialsBadge initials={initials} size="lg" />
-        )}
+        <img src={mark} alt={alt} className="h-8 w-8 shrink-0 object-contain" />
         <span className="text-sidebar-foreground truncate text-sm font-medium">
           {brandName ?? alt}
         </span>
@@ -158,6 +144,10 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
     )
   }
 
+  if (hasInitials) {
+    return <LogoPlaceholder tone="sidebar" label={brandName ?? alt} />
+  }
+
   if (brandName) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">

package/src/views/Login.tsx

@@ -1,8 +1,11 @@
 'use client'
 
-import { useState, type FormEvent } from 'react'
+import { useState, useEffect, useRef, type FormEvent } from 'react'
 import { Eye, EyeOff, AlertTriangle, Loader2 } from 'lucide-react'
 import { ActuateBrandLogo } from '../assets/actuate-logo.js'
+import { LogoPlaceholder } from '../components/LogoPlaceholder.js'
+import { useTheme } from '../components/ThemeProvider.js'
+import { cmsApi } from '../lib/api.js'
 
 export interface CaptchaConfig {
   provider: 'recaptcha' | 'turnstile' | 'none'
@@ -227,8 +230,45 @@ export function Login({
   const [totpError, setTotpError] = useState('')
   const [verifying, setVerifying] = useState(false)
 
+  // Brand logo, sourced to match the admin sidebar (see resolution note below).
+  // `adminBrand` is the ThemeProvider cache the sidebar paints from (hydrated
+  // from localStorage on mount); `publicLogo` is fetched only when that cache
+  // is empty (a fresh browser that hasn't loaded the admin yet).
+  const { adminBrand } = useTheme()
+  const [publicLogo, setPublicLogo] = useState<string | null>(null)
+  // Site initials resolved from `/public/brand`. Used only to detect whether
+  // the install is "branded" on a fresh browser (no cache, no config name), so
+  // the logo-less fallback can pick the placeholder over the Actuate wordmark.
+  const [publicInitials, setPublicInitials] = useState<string | null>(null)
+  const publicBrandFetched = useRef(false)
+
   useCaptchaScript(captchaConfig?.provider, captchaConfig?.siteKey)
 
+  useEffect(() => {
+    // The cached admin brand (exactly what the sidebar last rendered) wins and
+    // needs no network. Only reach for the unauthenticated `/public/brand`
+    // endpoint on a fresh browser with no cache, and never when the integrator
+    // opted out of a logo entirely (`branding.logo === null`).
+    if (adminBrand.primaryUrl || branding?.logo === null) return
+    if (publicBrandFetched.current) return
+    publicBrandFetched.current = true
+
+    let cancelled = false
+    void (async () => {
+      const res = await cmsApi<{
+        public?: { primary?: { url?: string } | null; initials?: string } | null
+      }>('/public/brand')
+      if (cancelled) return
+      const url = res.data?.public?.primary?.url
+      if (url) setPublicLogo(url)
+      const initials = res.data?.public?.initials
+      if (initials) setPublicInitials(initials)
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [adminBrand.primaryUrl, branding?.logo])
+
   const canSubmit = email.trim() && password && !submitting
 
   const handleSubmit = async (e: FormEvent) => {
@@ -308,27 +348,48 @@ export function Login({
   const enabledProviders =
     oauthProviders?.filter((p) => ['google', 'github', 'microsoft'].includes(p)) ?? []
 
-  // Branding fallbacks: when an integrator doesn't pass `branding`, render the
-  // Actuate Media wordmark inline (transparent SVG, no surrounding pill needed).
-  // When `branding.logo` is explicitly `null`, render no logo at all (just the
-  // headline + tagline) so whitelabel deployments can hide it entirely.
-  const customLogo = branding?.logo
+  // Logo resolution mirrors the admin sidebar so the login screen shows the
+  // same brand mark a user sees once signed in. Precedence (best available
+  // pre-auth):
+  //   1. the logo uploaded in Settings → Appearance — read from the
+  //      ThemeProvider cache the sidebar paints from, then (fresh browsers with
+  //      no cache) the unauthenticated `/public/brand` endpoint;
+  //   2. the static `config.admin.branding.logo` URL;
+  //   3. a neutral logo placeholder when the install is branded (a site/brand
+  //      name is set) but no logo has been uploaded yet — matching the sidebar;
+  //   4. the bundled Actuate wordmark for a fully un-branded install.
+  // `branding.logo === null` still hides the logo entirely (whitelabel opt-out).
+  const configLogo = branding?.logo
+  const hideLogo = configLogo === null
+  const appearanceLogo = adminBrand.primaryUrl ?? publicLogo
+  const effectiveLogo = appearanceLogo ?? (typeof configLogo === 'string' ? configLogo : null)
   const brandName = branding?.name ?? 'Actuate CMS'
   const brandTagline = branding?.tagline ?? 'Sign in to your account'
-  const showLogo = customLogo !== null
+  const showLogo = !hideLogo
+  // "Branded" = the operator has set a brand identity. Mirrors the sidebar's
+  // `hasInitials` signal (initials are derived from the site title) plus an
+  // explicit `branding.name` and, for fresh browsers, the initials returned by
+  // `/public/brand`. Drives the placeholder vs. Actuate-wordmark fallback so a
+  // configured client install never shows Actuate branding. `'A'` is the
+  // unset-title default, so it counts as un-branded.
+  const hasInitials = (value: string | null | undefined) => Boolean(value) && value !== 'A'
+  const isBranded =
+    Boolean(branding?.name) || hasInitials(adminBrand.initials) || hasInitials(publicInitials)
 
   return (
     <div className="flex min-h-screen items-center justify-center bg-gray-50 px-4">
       <div className="w-full max-w-md">
         <div className="mb-8 text-center">
           {showLogo &&
-            (customLogo ? (
+            (effectiveLogo ? (
               <img
-                src={customLogo}
+                src={effectiveLogo}
                 alt={brandName}
                 className="mx-auto mb-4 max-h-16 w-auto object-contain"
                 draggable={false}
               />
+            ) : isBranded ? (
+              <LogoPlaceholder tone="login" />
             ) : (
               <ActuateBrandLogo className="mx-auto mb-4 h-14 w-auto" />
             ))}