feat(theming): brand-asset overrides and a cached, settings-aware HTML shell

Phase 5 of docs/website/THEMING_AND_NAV.md: uploaded logo/hero/favicon
overrides on top of the BRAND_* env defaults, delivered through an HTML
shell that is no longer built once at boot.

- utils/htmlShell.js owns the shell lifecycle: rendered lazily, cached per
  process, invalidated on a brand_assets/theme_visual write with a 5-minute
  TTL so other workers converge. A settings-read failure renders the
  env-only shell and caches that, so a DB outage is not a failing query per
  page view, and with no rows the output is byte-identical to what app.js
  served before.
- POST /admin/settings/brand-asset/:slot uploads one asset and writes the
  row in the same call, so an upload never leaves an unreferenced file. It
  reuses the shared multer allowlist and only tightens it per slot: favicons
  are PNG-only and capped at 512 KB, logos at 1 MB, heroes at 8 MB. Refused
  files are unlinked before the response.
- utils/brandAssets.js constrains a stored asset to a same-origin path under
  /uploads, /brand or /assets — these are the only settings values written
  straight into the page as a URL. Strict on write, forgiving on read.
- The shell also carries the resolved theme as a <style id="theme-boot">
  block, removing the first-paint flash phases 3-4 deferred; SiteContext
  drops that block once a successful settings fetch has been applied.
- BrandLogo renders beside the MoonDot on all six shells and renders nothing
  when no logo is set, which is the shipped default.

Co-Authored-By: Claude <noreply@anthropic.com>

client/src/api/client.js

@@ -292,6 +292,16 @@ export const api = {
     // keys and the hero draft only (the server holds the allowlist). Idempotent,
     // so the caller need not know whether a row exists.
     resetSetting: (key) => req(`/admin/settings/${encodeURIComponent(key)}`, { method: 'DELETE' }),
+    // Upload one brand asset (logo | hero | favicon) and set it as the override
+    // in the same call → { url, brand_assets }. A separate endpoint from the
+    // generic upload above because the server applies per-slot rules (favicons
+    // are PNG-only and capped small) and writes the settings row itself, so an
+    // upload never leaves a file nothing points at.
+    uploadBrandAsset: (slot, file) => {
+      const fd = new FormData()
+      fd.append('image', file)
+      return req(`/admin/settings/brand-asset/${encodeURIComponent(slot)}`, { method: 'POST', body: fd, raw: true })
+    },
     activity: (limit = 50) => req(`/admin/activity?limit=${limit}`),
     botActivity: () => req('/admin/bot-activity'),
     unbanIp: (ip) => req('/admin/bot-activity/unban', { method: 'POST', body: { ip } }),

client/src/components/BrandLogo.jsx

@@ -0,0 +1,33 @@
+import { useSite } from '../contexts/SiteContext.jsx'
+
+// The instance logo, shown beside the MoonDot wherever the site says its own
+// name (docs/website/THEMING_AND_NAV.md phase 5).
+//
+// Renders NOTHING unless this instance has a logo — `brand.logo` is the uploaded
+// override or BRAND_LOGO, and its default is the empty string. That is what
+// keeps an untouched instance byte-for-byte as today: the MoonDot stands alone
+// exactly as it does now, and the logo is an addition an operator opts into.
+//
+// It sits beside the moon rather than replacing it. The moon is the app's own
+// mark and appears on surfaces (maintenance, login) that must render before the
+// settings fetch resolves; swapping it out would leave those momentarily blank.
+//
+// Deliberately not used for the footer's "powered by Runic Gateway" emblem
+// (SiteFooter.jsx) — that badge is the project's mark, not the instance's, and
+// must not follow brand_assets (§4.11).
+export default function BrandLogo({ height = 22, alt = '', style }) {
+  const { brand, siteTitle } = useSite()
+  if (!brand.logo) return null
+  return (
+    <img
+      src={brand.logo}
+      // Decorative by default: every call site puts the site title in text right
+      // next to it, so alt text here would have a screen reader say the name
+      // twice. A caller that renders the logo alone passes its own alt.
+      alt={alt || ''}
+      aria-hidden={alt ? undefined : true}
+      title={siteTitle}
+      style={{ height, width: 'auto', maxWidth: height * 6, objectFit: 'contain', display: 'block', ...style }}
+    />
+  )
+}

client/src/components/SiteHeader.jsx

@@ -1,5 +1,6 @@
 import { Link, NavLink } from 'react-router-dom'
 import MoonDot from './MoonDot.jsx'
+import BrandLogo from './BrandLogo.jsx'
 import { useAuth } from '../contexts/AuthContext.jsx'
 import { useSite } from '../contexts/SiteContext.jsx'
 import { useShardFeatures, canSee } from '../lib/useShardFeatures.js'
@@ -68,6 +69,7 @@ export default function SiteHeader() {
           className="display"
           style={{ display: 'flex', alignItems: 'center', gap: 10, fontSize: '1.2rem', letterSpacing: '0.05em', color: 'var(--accent-bright)', textDecoration: 'none', fontWeight: 600 }}
         >
+          <BrandLogo height={22} />
           <MoonDot />
           {siteTitle}
         </Link>

client/src/contexts/SiteContext.jsx

@@ -8,11 +8,16 @@ const SiteContext = createContext(null)
 export function SiteProvider({ children }) {
   const [settings, setSettings] = useState({})
   const [loading, setLoading] = useState(true)
+  // Whether a fetch has actually SUCCEEDED, as distinct from `loading` — which
+  // also goes false when the request failed and we fell back to {}. The boot
+  // theme handoff below turns on this distinction.
+  const [settled, setSettled] = useState(false)
 
   const refresh = useCallback(async () => {
     try {
       const data = await api.publicSettings()
       setSettings(data || {})
+      setSettled(true)
     } catch {
       setSettings({})
     } finally {
@@ -33,7 +38,17 @@ export function SiteProvider({ children }) {
   const appliedTokens = useRef([])
   useEffect(() => {
     appliedTokens.current = applyThemeTokens(document.documentElement.style, settings.theme, appliedTokens.current)
-  }, [settings.theme])
+    // Take over from the shell's boot block. The server injects the same tokens
+    // into <head> so a themed instance does not paint the shipped palette for a
+    // frame first (utils/htmlShell.js); from here on this effect is the
+    // authority, and leaving the block behind would mean a later reset removed
+    // the inline properties only to reveal the stale block underneath.
+    //
+    // Gated on a SUCCESSFUL fetch, not merely a finished one: a failed request
+    // leaves us with no theme at all, and dropping the block then would strip a
+    // themed instance back to the shipped palette for no reason.
+    if (settled) document.getElementById('theme-boot')?.remove()
+  }, [settings.theme, settled])
 
   // Apply the instance accent color to the CSS variable the theme is built on,
   // so branding flows to every `var(--accent)` at runtime (no rebuild). This is

client/src/routes/admin/AdminLayout.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import { NavLink, Outlet, useNavigate, useLocation } from 'react-router-dom'
 import MoonDot from '../../components/MoonDot.jsx'
+import BrandLogo from '../../components/BrandLogo.jsx'
 import { useAuth } from '../../contexts/AuthContext.jsx'
 import { useSite } from '../../contexts/SiteContext.jsx'
 
@@ -231,6 +232,7 @@ export default function AdminLayout() {
         }}
       >
         <div style={{ padding: '22px 22px 18px', borderBottom: '1px solid var(--line-soft)', display: 'flex', alignItems: 'center', gap: 10 }}>
+          <BrandLogo height={24} />
           <MoonDot />
           <div>
             <div className="display" style={{ fontSize: '1.02rem', color: 'var(--head)', letterSpacing: '0.03em' }}>

client/src/routes/admin/AdminLogin.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import { Link, useNavigate, useLocation } from 'react-router-dom'
 import MoonDot from '../../components/MoonDot.jsx'
+import BrandLogo from '../../components/BrandLogo.jsx'
 import ProviderIcon from '../../components/ProviderIcon.jsx'
 import TrustLimitModal from '../../components/security/TrustLimitModal.jsx'
 import { useAuth } from '../../contexts/AuthContext.jsx'
@@ -181,6 +182,10 @@ export default function AdminLogin() {
       <div style={{ width: '100%', maxWidth: 400 }}>
         <div style={{ textAlign: 'center', marginBottom: 26 }}>
           <div style={{ marginBottom: 14 }}>
+            {/* Stacked above the moon rather than beside it: this layout is
+                centered text, and a flex row here would change the block's
+                height on instances with no logo. */}
+            <BrandLogo height={34} style={{ margin: '0 auto 12px' }} />
             <MoonDot size={15} glow={0.55} />
           </div>
           <h1 className="display" style={{ margin: 0, fontSize: '1.7rem', letterSpacing: '0.04em', color: 'var(--head)' }}>

client/src/routes/admin/views/AppearanceAdmin.jsx

@@ -2,10 +2,11 @@ import { useEffect, useMemo, useState } from 'react'
 import { Loading, ErrorState } from '../../../components/PageState.jsx'
 import { api } from '../../../api/client.js'
 import { useSite } from '../../../contexts/SiteContext.jsx'
+import BrandAssetsPanel from './BrandAssetsPanel.jsx'
 
-// Admin · Appearance — the theme half of docs/website/THEMING_AND_NAV.md
-// (phases 3-4). Brand asset uploads and the nav builder are phases 5 and 7 and
-// get their own screens.
+// Admin · Appearance — the theme and brand-asset halves of
+// docs/website/THEMING_AND_NAV.md (phases 3-5). The nav builder is phase 7 and
+// gets its own screen.
 //
 // Two things shape this form:
 //
@@ -66,6 +67,10 @@ export default function AppearanceAdmin() {
   // "this instance is using the shipped theme" note — an admin needs to be able
   // to tell "never themed" from "themed to look like the default".
   const [stored, setStored] = useState(false)
+  // The brand-asset overrides, read in the same settings fetch and then owned by
+  // the panel below (its uploads save on their own, so it does not share this
+  // screen's Save button).
+  const [assets, setAssets] = useState(null)
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState('')
   const [busy, setBusy] = useState(false)
@@ -88,6 +93,15 @@ export default function AppearanceAdmin() {
           parsed = null
         }
         setStored(Boolean(all.theme_visual))
+        // Same fail-safe parse as the theme: a malformed row reads as absent, so
+        // the panel shows the env defaults rather than an error.
+        let parsedAssets = null
+        try {
+          parsedAssets = all.brand_assets ? JSON.parse(all.brand_assets) : null
+        } catch {
+          parsedAssets = null
+        }
+        setAssets(parsedAssets && typeof parsedAssets === 'object' && !Array.isArray(parsedAssets) ? parsedAssets : {})
         if (parsed && typeof parsed === 'object') {
           setPreset(parsed.preset || 'runic-gateway')
           setCustom({
@@ -340,6 +354,9 @@ export default function AppearanceAdmin() {
         The accent reaches the mobile app and the Discord bot too — both theme themselves from this
         site’s public branding.
       </p>
+
+      {/* ── Brand assets ───────────────────────────────────────── */}
+      <BrandAssetsPanel initial={assets || {}} />
     </section>
   )
 }

client/src/routes/admin/views/BrandAssetsPanel.jsx

@@ -0,0 +1,213 @@
+import { useRef, useState } from 'react'
+import { api } from '../../../api/client.js'
+import { useSite } from '../../../contexts/SiteContext.jsx'
+
+// Admin · Appearance → Brand assets (docs/website/THEMING_AND_NAV.md §6.3).
+//
+// Three slots, each an override layer over the matching BRAND_* env value. An
+// empty slot is not "no image" — it is "whatever this instance was deployed
+// with", which is why every row shows what it currently resolves to rather than
+// an empty box.
+//
+// Unlike the theme form above, an upload SAVES IMMEDIATELY: the file and the
+// settings row are written by one request, because an upload that stored a file
+// and then waited for a Save press would leave litter in /uploads whenever the
+// admin changed their mind. Clearing a slot is the same deal in reverse.
+const SLOTS = [
+  {
+    id: 'logo',
+    label: 'Logo',
+    accept: 'image/png,image/jpeg,image/webp,image/avif,image/gif',
+    limit: '1 MB',
+    envVar: 'BRAND_LOGO',
+    help: 'Shown beside the moon in the site header, the admin sidebar and the player portal, and used as the link preview image when a page is shared.',
+  },
+  {
+    id: 'hero',
+    label: 'Hero image',
+    accept: 'image/png,image/jpeg,image/webp,image/avif,image/gif',
+    limit: '8 MB',
+    envVar: 'BRAND_HERO',
+    // §4.9: the hero editor's own background beats this, and an admin who does
+    // not know that files a bug against a working system.
+    help: 'The image behind the portal hero. If the hero editor has its own background image set, that wins over this one.',
+  },
+  {
+    id: 'favicon',
+    label: 'Favicon',
+    accept: 'image/png',
+    limit: '512 KB',
+    envVar: 'BRAND_FAVICON',
+    // §4.10: .ico would mean adding a type to the upload allowlist, and the
+    // stored extension coming from that allowlist is what makes uploads safe.
+    help: 'The browser tab icon. PNG only — a 32×32 or 64×64 square works everywhere.',
+  },
+]
+
+export default function BrandAssetsPanel({ initial }) {
+  const { brand, refresh: refreshSite } = useSite()
+  const [assets, setAssets] = useState(initial || {})
+  const [busySlot, setBusySlot] = useState('')
+  const [error, setError] = useState('')
+  const inputs = useRef({})
+
+  async function upload(slot, file) {
+    if (!file) return
+    setBusySlot(slot)
+    setError('')
+    try {
+      const res = await api.admin.uploadBrandAsset(slot, file)
+      setAssets(res.brand_assets || {})
+      await refreshSite()
+    } catch (err) {
+      setError(err.message || 'Could not upload that image.')
+    } finally {
+      setBusySlot('')
+      // Let the same file be picked again after a failure — a file input holds
+      // its value, so re-choosing it would fire no change event.
+      if (inputs.current[slot]) inputs.current[slot].value = ''
+    }
+  }
+
+  async function clear(slot) {
+    setBusySlot(slot)
+    setError('')
+    try {
+      const next = { ...assets }
+      delete next[slot]
+      // Clearing the last override deletes the row rather than storing `{}` —
+      // absence of the row is what selects the env defaults (§2), and a stored
+      // empty object would be a different state that means the same thing.
+      if (Object.keys(next).length) await api.admin.updateSettings({ brand_assets: next })
+      else await api.admin.resetSetting('brand_assets')
+      setAssets(next)
+      await refreshSite()
+    } catch (err) {
+      setError(err.message || 'Could not clear that asset.')
+    } finally {
+      setBusySlot('')
+    }
+  }
+
+  return (
+    <div>
+      <span className="field-label">Brand assets</span>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 14, marginTop: 8 }}>
+        {SLOTS.map((slot) => {
+          const overridden = Boolean(assets[slot.id])
+          // What the site actually uses right now: the override, or the env
+          // value the brand block already resolved for us.
+          const effective = assets[slot.id] || brand[slot.id] || ''
+          return (
+            <div
+              key={slot.id}
+              style={{
+                display: 'flex',
+                alignItems: 'flex-start',
+                gap: 14,
+                padding: 12,
+                border: '1px solid var(--line)',
+                borderRadius: 'var(--radius-input)',
+              }}
+            >
+              <div
+                style={{
+                  width: 76,
+                  height: 48,
+                  flex: '0 0 auto',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  border: '1px solid var(--line-soft)',
+                  borderRadius: 6,
+                  background: 'var(--bg-deep)',
+                  overflow: 'hidden',
+                }}
+              >
+                {effective ? (
+                  <img src={effective} alt="" style={{ maxWidth: '100%', maxHeight: '100%', objectFit: 'contain' }} />
+                ) : (
+                  <span className="sans dim" style={{ fontSize: '0.68rem' }}>
+                    none
+                  </span>
+                )}
+              </div>
+
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <div className="sans" style={{ fontSize: '0.86rem', color: 'var(--ink)' }}>
+                  {slot.label}
+                </div>
+                <div className="sans dim" style={{ fontSize: '0.74rem', lineHeight: 1.6, marginTop: 2 }}>
+                  {slot.help}
+                </div>
+                <div className="sans dim" style={{ fontSize: '0.72rem', marginTop: 6 }}>
+                  {overridden ? (
+                    <>
+                      Uploaded override — <code>{assets[slot.id]}</code>
+                    </>
+                  ) : effective ? (
+                    <>
+                      Using the deployed default from <code>{slot.envVar}</code>
+                    </>
+                  ) : (
+                    <>
+                      Not set — <code>{slot.envVar}</code> is empty, so nothing is rendered
+                    </>
+                  )}
+                </div>
+
+                <div style={{ display: 'flex', gap: 10, alignItems: 'center', marginTop: 8, flexWrap: 'wrap' }}>
+                  <input
+                    ref={(el) => {
+                      inputs.current[slot.id] = el
+                    }}
+                    type="file"
+                    accept={slot.accept}
+                    disabled={Boolean(busySlot)}
+                    onChange={(e) => upload(slot.id, e.target.files?.[0])}
+                    className="sans"
+                    style={{ fontSize: '0.74rem', maxWidth: 240 }}
+                    aria-label={`Upload a ${slot.label.toLowerCase()}`}
+                  />
+                  <span className="sans dim" style={{ fontSize: '0.7rem' }}>
+                    max {slot.limit}
+                  </span>
+                  {overridden && (
+                    <button
+                      type="button"
+                      onClick={() => clear(slot.id)}
+                      disabled={Boolean(busySlot)}
+                      className="sans"
+                      title={`Go back to ${slot.envVar}`}
+                      style={linkBtn}
+                    >
+                      {busySlot === slot.id ? 'working…' : 'clear'}
+                    </button>
+                  )}
+                </div>
+              </div>
+            </div>
+          )
+        })}
+      </div>
+      {error && (
+        <span className="sans" style={{ display: 'block', marginTop: 8, color: '#d98b84', fontSize: '0.85rem' }}>
+          {error}
+        </span>
+      )}
+      <span className="sans dim" style={{ display: 'block', marginTop: 8, fontSize: '0.76rem' }}>
+        Uploads apply as soon as they finish — there is nothing to save here. The footer’s “powered by
+        Runic Gateway” mark is the project’s badge, not this instance’s, and never changes.
+      </span>
+    </div>
+  )
+}
+
+const linkBtn = {
+  border: 'none',
+  background: 'transparent',
+  color: 'var(--accent)',
+  fontSize: '0.72rem',
+  cursor: 'pointer',
+  padding: 0,
+}

client/src/routes/player/PlayerPortalLayout.jsx

@@ -1,5 +1,6 @@
 import { NavLink, Outlet, useNavigate, useLocation } from 'react-router-dom'
 import MoonDot from '../../components/MoonDot.jsx'
+import BrandLogo from '../../components/BrandLogo.jsx'
 import { useAuth } from '../../contexts/AuthContext.jsx'
 import { useSite } from '../../contexts/SiteContext.jsx'
 
@@ -86,6 +87,7 @@ export default function PlayerPortalLayout() {
         }}
       >
         <div style={{ padding: '22px 22px 18px', borderBottom: '1px solid var(--line-soft)', display: 'flex', alignItems: 'center', gap: 10 }}>
+          <BrandLogo height={24} />
           <MoonDot />
           <div>
             <div className="display" style={{ fontSize: '1.02rem', color: 'var(--head)', letterSpacing: '0.03em' }}>

client/src/routes/player/PlayerShell.jsx

@@ -1,5 +1,6 @@
 import { Link } from 'react-router-dom'
 import MoonDot from '../../components/MoonDot.jsx'
+import BrandLogo from '../../components/BrandLogo.jsx'
 import { useSite } from '../../contexts/SiteContext.jsx'
 
 // Centered card layout shared by the player login / register pages. `subtitle`
@@ -25,6 +26,10 @@ export default function PlayerShell({ subtitle, children, footer }) {
       <div style={{ width: '100%', maxWidth: 400 }}>
         <div style={{ textAlign: 'center', marginBottom: 26 }}>
           <div style={{ marginBottom: 14 }}>
+            {/* Stacked above the moon rather than beside it: this layout is
+                centered text, and a flex row here would change the block's
+                height on instances with no logo. */}
+            <BrandLogo height={34} style={{ margin: '0 auto 12px' }} />
             <MoonDot size={15} glow={0.55} />
           </div>
           <h1 className="display" style={{ margin: 0, fontSize: '1.7rem', letterSpacing: '0.04em', color: 'var(--head)' }}>

client/src/routes/public/Maintenance.jsx

@@ -1,5 +1,6 @@
 import { Link } from 'react-router-dom'
 import MoonDot from '../../components/MoonDot.jsx'
+import BrandLogo from '../../components/BrandLogo.jsx'
 import { useSite } from '../../contexts/SiteContext.jsx'
 
 export default function Maintenance() {
@@ -28,6 +29,7 @@ export default function Maintenance() {
     >
       <div style={{ maxWidth: 640, textShadow: '0 2px 22px rgba(0,0,0,0.85)' }}>
         <div style={{ marginBottom: 26 }}>
+          <BrandLogo height={40} style={{ margin: '0 auto 16px' }} />
           <MoonDot size={18} glow={0.6} />
         </div>
         <p className="eyebrow" style={{ color: '#c2d2e6', letterSpacing: '0.24em' }}>