@ciderpress/ui 1.0.0-rc.1 → 1.0.0-rc.10

package/dist/theme/components/shared/icon.tsx

@@ -1,41 +1,126 @@
-import catppuccin from '@iconify-json/catppuccin/icons.json' with { type: 'json' }
-import devicon from '@iconify-json/devicon/icons.json' with { type: 'json' }
-import logos from '@iconify-json/logos/icons.json' with { type: 'json' }
-import materialIconTheme from '@iconify-json/material-icon-theme/icons.json' with { type: 'json' }
-import mdi from '@iconify-json/mdi/icons.json' with { type: 'json' }
-import pixelarticons from '@iconify-json/pixelarticons/icons.json' with { type: 'json' }
-import simpleIcons from '@iconify-json/simple-icons/icons.json' with { type: 'json' }
-import skillIcons from '@iconify-json/skill-icons/icons.json' with { type: 'json' }
-import vscodeIcons from '@iconify-json/vscode-icons/icons.json' with { type: 'json' }
-import { addCollection, Icon } from '@iconify/react'
-
-// Register all icon collections for offline Iconify resolution.
-// `addCollection` is called purely for its side effect of mutating
-// Iconify's internal registry. Holding the return values in a
-// throwaway `const` keeps the call list a single expression statement
-// rather than nine misleading named exports.
-// oxlint-disable-next-line no-unused-vars
-const _iconCollectionsLoaded = [
-  addCollection(cast(pixelarticons)),
-  addCollection(cast(devicon)),
-  addCollection(cast(mdi)),
-  addCollection(cast(simpleIcons)),
-  addCollection(cast(skillIcons)),
-  addCollection(cast(catppuccin)),
-  addCollection(cast(logos)),
-  addCollection(cast(vscodeIcons)),
-  addCollection(cast(materialIconTheme)),
-] as const
-
-export { Icon }
+import { addCollection, Icon as IconifyIcon } from '@iconify/react'
+import type { IconProps } from '@iconify/react'
+import type React from 'react'
+import { useEffect, useState } from 'react'
 
 /**
- * Cast an icon JSON import to the type expected by `addCollection`.
+ * Per-collection lazy loaders keyed by Iconify prefix.
+ *
+ * Each entry is a bare dynamic `import()` so the consuming site's Rsbuild
+ * build emits **one async chunk per collection** instead of folding all ten
+ * `icons.json` files into a single eager ~30MB chunk pulled on every route.
+ * Two consequences fall out of that:
+ *
+ * - **Deployability** — the largest collection (`logos`, ~8MB) stays well
+ *   under per-file host caps (Cloudflare Pages rejects files >25MB), where
+ *   the combined blob failed outright.
+ * - **Performance** — a page only downloads the collections it actually
+ *   references, not the full set on first paint.
+ *
+ * The specifiers are string literals (not computed) so the bundler can
+ * statically resolve every chunk at build time.
+ *
+ * @private
+ */
+const COLLECTION_LOADERS: Record<string, () => Promise<{ readonly default: unknown }>> = {
+  catppuccin: () => import('@iconify-json/catppuccin/icons.json'),
+  devicon: () => import('@iconify-json/devicon/icons.json'),
+  logos: () => import('@iconify-json/logos/icons.json'),
+  'material-icon-theme': () => import('@iconify-json/material-icon-theme/icons.json'),
+  mdi: () => import('@iconify-json/mdi/icons.json'),
+  pixel: () => import('@iconify-json/pixel/icons.json'),
+  pixelarticons: () => import('@iconify-json/pixelarticons/icons.json'),
+  'simple-icons': () => import('@iconify-json/simple-icons/icons.json'),
+  'skill-icons': () => import('@iconify-json/skill-icons/icons.json'),
+  'vscode-icons': () => import('@iconify-json/vscode-icons/icons.json'),
+}
+
+/**
+ * Cache of in-flight / settled collection registrations keyed by prefix.
+ * Guarantees each collection's chunk is fetched and merged into Iconify's
+ * registry exactly once, regardless of how many `<Icon>` instances on a
+ * page reference it.
+ *
+ * @private
+ */
+const collectionCache = new Map<string, Promise<void>>()
+
+/**
+ * Offline-registered Iconify icon.
+ *
+ * Renders `@iconify/react`'s `Icon` unchanged, but registers the icon's
+ * collection on demand: the first time a prefix is seen the matching
+ * `@iconify-json` chunk is dynamically imported and merged into Iconify's
+ * registry, then a re-render paints the resolved SVG. Because `IconifyIcon`
+ * reads the live registry on every render, an icon appears as soon as its
+ * collection chunk resolves.
+ *
+ * @param props - Standard `@iconify/react` icon props; `icon` is the
+ *   `prefix:name` identifier (e.g. `devicon:typescript`)
+ * @returns The Iconify icon element
+ */
+export function Icon(props: IconProps): React.ReactElement {
+  const prefix = resolvePrefix(props.icon)
+  const [, markRegistered] = useState(false)
+
+  useEffect(() => {
+    ensureCollection(prefix).then(() => markRegistered(true))
+  }, [prefix])
+
+  return <IconifyIcon {...props} />
+}
+
+/**
+ * Dynamically import and register the collection for a prefix, once.
+ *
+ * Returns the cached registration promise on repeat calls so the chunk is
+ * fetched a single time. Unknown prefixes (no bundled collection) resolve
+ * immediately — `IconifyIcon` falls back to its own resolution for those.
+ *
+ * @private
+ * @param prefix - Iconify collection prefix (e.g. `logos`)
+ * @returns Promise that settles once the collection is registered
+ */
+function ensureCollection(prefix: string): Promise<void> {
+  const cached = collectionCache.get(prefix)
+  if (cached !== undefined) {
+    return cached
+  }
+  const loader = COLLECTION_LOADERS[prefix]
+  if (loader === undefined) {
+    return Promise.resolve()
+  }
+  const registration = loader().then(registerModule)
+  collectionCache.set(prefix, registration)
+  return registration
+}
+
+/**
+ * Merge a dynamically imported `icons.json` module into Iconify's registry.
+ *
+ * @private
+ * @param mod - Module namespace whose `default` export is the collection JSON
+ */
+function registerModule(mod: { readonly default: unknown }): void {
+  addCollection(mod.default as Parameters<typeof addCollection>[0])
+}
+
+/**
+ * Extract the collection prefix from an Iconify identifier. Non-string icon
+ * inputs and identifiers without a `prefix:name` shape yield an empty string,
+ * which `ensureCollection` treats as "nothing to load".
  *
  * @private
- * @param v - Raw icon JSON import
- * @returns Value cast to the addCollection parameter type
+ * @param icon - The `icon` prop passed to `<Icon>`
+ * @returns The collection prefix, or `''` when none can be determined
  */
-function cast(v: unknown): Parameters<typeof addCollection>[0] {
-  return v as Parameters<typeof addCollection>[0]
+function resolvePrefix(icon: IconProps['icon']): string {
+  if (typeof icon !== 'string') {
+    return ''
+  }
+  const parts = icon.split(':')
+  if (parts.length < 2) {
+    return ''
+  }
+  return parts[0]
 }

package/dist/theme/components/shared/resolve-card-icon.ts

@@ -1,28 +1,69 @@
+import type { SerializedIcon } from '@ciderpress/config'
+import { match } from 'massaman/match'
+
+/**
+ * Render-ready image icon — `src` plus `alt`.
+ */
+export interface ResolvedCardImageIcon {
+  readonly kind: 'image'
+  readonly src: string
+  readonly alt: string
+}
+
 /**
- * Resolved icon with id and color.
+ * Render-ready Iconify icon — `id` plus a colour-rotation key.
  */
-export interface ResolvedCardIcon {
+export interface ResolvedCardIconifyIcon {
+  readonly kind: 'iconify'
   readonly id: string
   readonly color: string
 }
 
 /**
- * Resolve a unified icon config into id + color.
+ * Discriminated union of resolved card-icon variants. Render sites
+ * switch on `kind` to decide between an Iconify `<Icon>` and an `<img>`.
+ */
+export type ResolvedCardIcon = ResolvedCardIconifyIcon | ResolvedCardImageIcon
+
+/**
+ * Card-icon input shape — the `SerializedIcon` shape emitted by the
+ * sync engine (workspaces, sections, features), re-exported here under
+ * a local alias to keep render-site call signatures readable. Always
+ * comes from `@ciderpress/config` — there is no separate source of
+ * truth.
+ */
+export type CardIconInput = SerializedIcon | undefined
+
+/**
+ * Resolve a serialized icon value into a discriminated icon ready for
+ * render.
  *
- * String icons get the default `'purple'` color. Object icons pass through.
- * Returns `undefined` for undefined input.
+ * - `string` → `{ kind: 'iconify', id, color: 'purple' }`
+ * - `{ id, color }` → `{ kind: 'iconify', id, color }`
+ * - `{ kind: 'image', src, alt }` → pass-through
+ * - `undefined` → `undefined`
  *
- * @param icon - Icon config (string, object, or undefined)
- * @returns Resolved icon or undefined
+ * @param icon - Serialized icon value or `undefined`
+ * @returns Discriminated resolved icon, or `undefined`
  */
-export function resolveCardIcon(
-  icon: string | { readonly id: string; readonly color: string } | undefined
-): ResolvedCardIcon | undefined {
+export function resolveCardIcon(icon: CardIconInput): ResolvedCardIcon | undefined {
   if (icon === undefined) {
     return undefined
   }
   if (typeof icon === 'string') {
-    return { id: icon, color: 'purple' }
+    return { kind: 'iconify', id: icon, color: 'purple' }
   }
-  return icon
+  // Match on the discriminant value rather than `'kind' in icon` so a
+  // future variant that also carries a `kind` field (or a malformed
+  // runtime input) can't silently slip into the image branch.
+  return match(icon)
+    .with({ kind: 'image' }, (img) => ({
+      kind: 'image' as const,
+      src: img.src,
+      // Defence-in-depth: even if a downstream caller hand-builds the
+      // object and forgets `alt`, fall back to an empty string so React
+      // never sees `alt={undefined}` (which silences screen readers).
+      alt: img.alt ?? '',
+    }))
+    .otherwise((i) => ({ kind: 'iconify' as const, id: i.id, color: i.color }))
 }

package/dist/theme/components/shared/section-card.tsx

@@ -1,15 +1,19 @@
+import type { BadgeConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
+import { useCiderpress } from '../../hooks/use-ciderpress'
+import { BadgeChips } from '../sidebar/sidebar-badge'
 import { Card } from './card'
-import { Icon } from './icon'
+import { CardIcon } from './card-icon'
+import type { CardIconInput } from './resolve-card-icon'
 import { resolveCardIcon } from './resolve-card-icon'
 
 export interface SectionCardProps {
   readonly href: string
   readonly title: string
   readonly description?: string
-  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly icon?: CardIconInput
 }
 
 /**
@@ -25,7 +29,13 @@ export function SectionCard({
   description,
   icon = 'pixelarticons:file',
 }: SectionCardProps): React.ReactElement {
-  const resolved = resolveCardIcon(icon) ?? { id: 'pixelarticons:file', color: 'purple' }
+  const { pageBadges } = useCiderpress()
+  const badges = lookupBadges({ pageBadges, href })
+  const resolved = resolveCardIcon(icon) ?? {
+    kind: 'iconify' as const,
+    id: 'pixelarticons:file',
+    color: 'purple',
+  }
   const descEl = match(description)
     .with(P.nonNullable, (d) => <span className="cp-section-card__desc">{d}</span>)
     .otherwise(() => null)
@@ -33,12 +43,33 @@ export function SectionCard({
   return (
     <Card href={href} className="cp-section-card">
       <div className="cp-section-card__header">
-        <span className={`cp-section-card__icon cp-section-card__icon--${resolved.color}`}>
-          <Icon icon={resolved.id} />
-        </span>
+        <CardIcon resolved={resolved} className="cp-section-card__icon" />
         <span className="cp-section-card__title">{title}</span>
+        {badges.length > 0 && (
+          <span className="cp-section-card__badges">
+            <BadgeChips badges={badges} />
+          </span>
+        )}
       </div>
       {descEl}
     </Card>
   )
 }
+
+/**
+ * Look up a page's badges from the route→badges map by its href.
+ *
+ * @private
+ * @param params - The route→badges map (if present) and card destination.
+ * @returns The page's badges, or an empty array when none apply
+ */
+function lookupBadges(params: {
+  readonly pageBadges: Record<string, readonly BadgeConfig[]> | undefined
+  readonly href: string
+}): readonly BadgeConfig[] {
+  const { pageBadges, href } = params
+  if (pageBadges === undefined) {
+    return []
+  }
+  return pageBadges[href] ?? []
+}

package/dist/theme/components/sidebar/sidebar-badge.css

@@ -0,0 +1,50 @@
+/**
+ * Sidebar badge chips — small uppercase labels (ALPHA, WIP, …) rendered
+ * in a sidebar item's right slot via the `Tag` override.
+ */
+
+@layer ciderpress.overrides {
+  .cp-sbadge {
+    display: inline-flex;
+    align-items: center;
+    padding: 1px 5px;
+    border-radius: var(--cp-radius-pill, 9999px);
+    font-family: var(--cp-font-family-mono, inherit);
+    font-size: 9px;
+    font-weight: 600;
+    line-height: 1.4;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    white-space: nowrap;
+    vertical-align: middle;
+  }
+
+  .cp-sbadge + .cp-sbadge {
+    margin-left: 4px;
+  }
+
+  .cp-sbadge--info {
+    background: var(--cp-c-badge-info-bg);
+    color: var(--cp-c-badge-info-fg);
+  }
+
+  .cp-sbadge--success {
+    background: var(--cp-c-badge-success-bg);
+    color: var(--cp-c-badge-success-fg);
+  }
+
+  .cp-sbadge--warning {
+    background: var(--cp-c-badge-warning-bg);
+    color: var(--cp-c-badge-warning-fg);
+  }
+
+  .cp-sbadge--danger {
+    background: var(--cp-c-badge-error-bg);
+    color: var(--cp-c-badge-error-fg);
+  }
+
+  .cp-sbadge--neutral {
+    background: var(--rp-c-bg-mute);
+    color: var(--rp-c-text-2);
+  }
+}

package/dist/theme/components/sidebar/sidebar-badge.tsx

@@ -0,0 +1,153 @@
+/**
+ * Sidebar badge rendering — overrides Rspress's `Tag` component.
+ *
+ * Rspress renders `<Tag tag={...} />` inside every sidebar item. Ciderpress
+ * encodes page badges (label + variant + tooltip) into that `tag` string via
+ * `@ciderpress/config`'s `encodeBadges`. This override decodes ciderpress
+ * badges and renders styled chips; any other tag falls through to Rspress's
+ * native `Tag` so existing tag behavior (images, keyword badges) is preserved.
+ */
+
+import { decodeBadges } from '@ciderpress/config'
+import type { BadgeConfig, BadgeVariant } from '@ciderpress/config'
+import { Tag as RspressTag } from '@rspress/core/theme-original'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+/**
+ * Props mirror Rspress's `Tag` — a single (optional) tag string.
+ *
+ * @private
+ */
+interface TagProps {
+  readonly tag?: string
+}
+
+/**
+ * Sidebar tag renderer. Renders ciderpress badge chips for encoded tags,
+ * delegating everything else to Rspress's native `Tag`.
+ *
+ * @param props - The sidebar item's tag string
+ * @returns Badge chips, a native tag, or `null` when there is no tag
+ */
+export function Tag({ tag }: TagProps): React.ReactElement | null {
+  const badges = decodeTag(tag)
+  if (badges === null) {
+    return <RspressTag tag={tag} />
+  }
+  return <BadgeChips badges={badges} />
+}
+
+/**
+ * Props for {@link BadgeChips}.
+ */
+export interface BadgeChipsProps {
+  readonly badges: readonly BadgeConfig[]
+}
+
+/**
+ * Render a list of badge chips (variant color, custom-color tint, hover
+ * tooltip). Used by the sidebar `Tag` override and the breadcrumb bar.
+ *
+ * @param props - The badges to render
+ * @returns Chip elements, or `null` when there are no badges
+ */
+export function BadgeChips({ badges }: BadgeChipsProps): React.ReactElement | null {
+  if (badges.length === 0) {
+    return null
+  }
+  return (
+    <>
+      {badges.map((badge, index) => (
+        <SidebarBadge key={`${badge.text}-${String(index)}`} badge={badge} />
+      ))}
+    </>
+  )
+}
+
+/**
+ * Decode a tag string into ciderpress badges, or `null` when the tag is
+ * absent or not ciderpress-encoded.
+ *
+ * @private
+ * @param tag - Raw tag string from the sidebar item
+ * @returns Decoded badges, or `null` to signal native fallback
+ */
+function decodeTag(tag: string | undefined): readonly BadgeConfig[] | null {
+  if (tag === undefined) {
+    return null
+  }
+  return decodeBadges(tag)
+}
+
+/**
+ * A single sidebar badge chip.
+ *
+ * @private
+ */
+interface SidebarBadgeProps {
+  readonly badge: BadgeConfig
+}
+
+/**
+ * Render one badge chip with variant color (or a custom color tint) and a
+ * hover tooltip.
+ *
+ * @private
+ * @param props - The badge to render
+ * @returns A styled badge chip element
+ */
+function SidebarBadge({ badge }: SidebarBadgeProps): React.ReactElement {
+  const tooltip = resolveTooltip(badge)
+  return match(badge.color)
+    .with(P.string, (color) => (
+      <span className="cp-sbadge" style={{ color, backgroundColor: tint(color) }} title={tooltip}>
+        {badge.text}
+      </span>
+    ))
+    .otherwise(() => (
+      <span className={variantClass(badge.variant)} title={tooltip}>
+        {badge.text}
+      </span>
+    ))
+}
+
+/**
+ * Resolve the hover tooltip for a badge, defaulting to its label text.
+ *
+ * @private
+ * @param badge - The badge to resolve a tooltip for
+ * @returns The tooltip string
+ */
+function resolveTooltip(badge: BadgeConfig): string {
+  return badge.tooltip ?? badge.text
+}
+
+/**
+ * Map a badge variant to its chip class, defaulting to `neutral`.
+ *
+ * @private
+ * @param variant - The badge variant, if any
+ * @returns The full class string for the chip
+ */
+function variantClass(variant: BadgeVariant | undefined): string {
+  return match(variant)
+    .with('info', () => 'cp-sbadge cp-sbadge--info')
+    .with('success', () => 'cp-sbadge cp-sbadge--success')
+    .with('warning', () => 'cp-sbadge cp-sbadge--warning')
+    .with('danger', () => 'cp-sbadge cp-sbadge--danger')
+    .with('neutral', () => 'cp-sbadge cp-sbadge--neutral')
+    .with(undefined, () => 'cp-sbadge cp-sbadge--neutral')
+    .exhaustive()
+}
+
+/**
+ * Build a subtle background tint from a custom color.
+ *
+ * @private
+ * @param color - CSS color value
+ * @returns A `color-mix` background at low opacity
+ */
+function tint(color: string): string {
+  return `color-mix(in srgb, ${color} 14%, transparent)`
+}

package/dist/theme/components/sidebar/sidebar-links.tsx

@@ -1,3 +1,4 @@
+import type { SerializedIcon } from '@ciderpress/config'
 import { Link } from '@rspress/core/runtime'
 import { match, P } from 'massaman/match'
 import type React from 'react'
@@ -10,7 +11,7 @@ import './sidebar-links.css'
 interface SidebarLinkItem {
   readonly text: string
   readonly link: string
-  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly icon?: SerializedIcon
   readonly style?: 'brand' | 'alt' | 'ghost'
   readonly shape?: 'square' | 'rounded' | 'circle'
 }
@@ -51,7 +52,10 @@ export function SidebarLinks(props: SidebarLinksProps): React.ReactElement | nul
 function renderIcon(icon: SidebarLinkItem['icon']): React.ReactElement | null {
   return match(icon)
     .with(P.string, (id) => <Icon icon={id} className="cp-sidebar-link-icon" />)
-    .with({ id: P.string, color: P.string }, (i) => (
+    .with({ kind: 'image' }, (img) => (
+      <img src={img.src} alt={img.alt} className="cp-sidebar-link-icon cp-sidebar-link-icon--img" />
+    ))
+    .with({ id: P.string }, (i) => (
       <Icon icon={i.id} className="cp-sidebar-link-icon" style={{ color: i.color }} />
     ))
     .otherwise(() => null)

package/dist/theme/components/sidebar/sidebar-scope.tsx

@@ -14,7 +14,7 @@ import type { SidebarData } from '@rspress/core'
 import { useActiveMatcher, useLocation, useSidebar } from '@rspress/core/runtime'
 import { SidebarList } from '@rspress/core/theme-original'
 import type React from 'react'
-import { useLayoutEffect, useMemo, useState } from 'react'
+import { useEffect, useLayoutEffect, useMemo, useState } from 'react'
 
 import { useCiderpress } from '../../hooks/use-ciderpress'
 import { resolveScopedSidebar } from './sidebar-filter'
@@ -59,9 +59,32 @@ export function Sidebar(): React.ReactElement {
     setSidebarData(initializeCollapsed(filteredData, activeMatcher))
   }, [activeMatcher, filteredData])
 
+  useEffect(() => {
+    decorateOverflowTitles()
+  }, [sidebarData])
+
   return <SidebarList sidebarData={sidebarData} setSidebarData={setSidebarData} />
 }
 
+/**
+ * Add a `title` attribute to sidebar labels that overflow their column so
+ * the full text shows on hover; clear it when the label fits. Runs after
+ * render because overflow is a measured, layout-dependent property.
+ *
+ * @private
+ */
+function decorateOverflowTitles(): void {
+  const labels = [...document.querySelectorAll<HTMLElement>('.rp-sidebar-item__left > .rp-doc')]
+  labels.reduce<null>((_, label) => {
+    if (label.scrollWidth > label.clientWidth) {
+      label.setAttribute('title', label.textContent ?? '')
+    } else {
+      label.removeAttribute('title')
+    }
+    return null
+  }, null)
+}
+
 /**
  * Walk the sidebar tree and uncollapse groups that contain the active path.
  *

package/dist/theme/components/theme-provider.tsx

@@ -11,6 +11,8 @@ declare const __CIDERPRESS_DEFAULT_VARIANT__: string
 declare const __CIDERPRESS_THEME_COLORS__: string
 declare const __CIDERPRESS_THEME_DARK_COLORS__: string
 declare const __CIDERPRESS_THEME_REGISTRY__: string
+declare const __CIDERPRESS_HAS_USER_FAVICON__: boolean
+declare const __CIDERPRESS_LOADER_MIN_MS__: number
 
 interface RegistryEntry {
   readonly name: string
@@ -26,7 +28,7 @@ type ThemeColorKey = keyof ThemeColors
 
 /**
  * Parsed theme registry — built-in themes plus any user themes from
- * `config.themes`. Read from the build-time define so the client bundle
+ * `theme.themes`. Read from the build-time define so the client bundle
  * does not pull `@ciderpress/theme`'s factory + Zod into the runtime path.
  */
 const REGISTRY_ENTRIES: readonly RegistryEntry[] = parseRegistry(__CIDERPRESS_THEME_REGISTRY__)
@@ -123,9 +125,11 @@ const COLOR_VAR_MAP: Readonly<Record<ThemeColorKey, readonly string[]>> = Object
 const ALL_CSS_VARS: readonly string[] = Object.values(COLOR_VAR_MAP).flat()
 
 /**
- * Minimum time (ms) the loading overlay stays visible before fading out.
+ * Minimum time (ms) the loading overlay stays visible before fading
+ * out. Resolved at build time from `brand.loader.minDisplayMs` —
+ * defaults to 150ms in `packages/ui/src/config.ts`.
  */
-const LOADER_MIN_DISPLAY_MS = 150
+const LOADER_MIN_DISPLAY_MS = __CIDERPRESS_LOADER_MIN_MS__
 
 /**
  * Duration (ms) of the CSS fade-out transition. Must match the
@@ -199,12 +203,14 @@ export function ThemeProvider(): React.ReactElement | null {
       applyColorOverrides(html, darkColors)
     }
 
-    // Sync the document favicon with the active theme's brand colour.
-    // Browsers cache static icon assets and ignore CSS, so the only way to
-    // keep the tab mark in lockstep with the chosen theme is to swap
-    // `<link rel="icon">` to a data-URI SVG carrying the resolved
-    // `--cp-c-brand-1`.
-    syncThemeFavicon(html)
+    // Sync the document favicon with the active theme's brand colour —
+    // only when the user has NOT set their own `favicon` in config. When
+    // they have, Rspress already points `<link rel="icon">` at the
+    // user's asset, and overwriting it with the themed apple data-URI
+    // would silently restore ciderpress branding.
+    if (!__CIDERPRESS_HAS_USER_FAVICON__) {
+      syncThemeFavicon(html)
+    }
 
     // Observe `.rp-dark` class changes so Rspress's built-in dark toggle
     // stays the single source of truth for variant flips. The new variant
@@ -253,8 +259,11 @@ export function ThemeProvider(): React.ReactElement | null {
       }
       // Re-sync the favicon — brand colour is constant across variants for
       // built-in themes, but surface overrides on the dark variant can
-      // affect the chip background colour we bake into the SVG.
-      syncThemeFavicon(html)
+      // affect the chip background colour we bake into the SVG. Skipped
+      // when the user supplied their own favicon (see initial sync above).
+      if (!__CIDERPRESS_HAS_USER_FAVICON__) {
+        syncThemeFavicon(html)
+      }
     })
     observer.observe(html, { attributes: true, attributeFilter: ['class'] })
 
@@ -628,6 +637,13 @@ function dismissLoader(html: HTMLElement): () => void {
     clearDotsInterval()
   }, LOADER_MIN_DISPLAY_MS + LOADER_FADE_MS)
 
+  // The forced-dismiss fallback (covering the case where React never
+  // hydrates) lives in the inline head script — see `buildHeadScriptBody`
+  // in `packages/ui/src/config.ts`. That timer always runs, so a
+  // duplicate React-side fallback here would only fire AFTER ThemeProvider
+  // has already mounted — at which point the normal fade path above has
+  // already won.
+
   return () => {
     clearTimeout(fadeTimer)
     clearTimeout(removeTimer)