@ciderpress/ui 1.0.0-rc.3 → 1.0.0-rc.4

package/src/theme/components/nav/layout.tsx

@@ -1,10 +1,10 @@
-import type { SiteEditConfig, SiteReportConfig } from '@ciderpress/config'
 import { useFrontmatter, useSite } from '@rspress/core/runtime'
 import { Layout as OriginalLayout } from '@rspress/core/theme-original'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 import { useEffect } from 'react'
 
+import type { CiderpressSiteBlock } from '../../hooks/use-ciderpress'
 import { useCiderpress } from '../../hooks/use-ciderpress'
 import { useNavItems } from '../../hooks/use-nav-items'
 import { readSocialLinks } from '../../lib/read-social-links'
@@ -120,6 +120,30 @@ export function Layout(): React.ReactElement {
     </ContentFooterPortal>
   )
 
+  // Rspress's SSG-MD pipeline renders the React tree through
+  // `react-render-to-markdown` to produce the `.md` files served to
+  // `<LlmsCopyButton />`. If we render our chrome (header, docs bar,
+  // footer slot wrappers) during that pass, the topbar logo, search,
+  // and nav items all get serialized as markdown and end up at the
+  // top of the copied content. Short-circuit to just the article body
+  // via `<OriginalLayout />` (Rspress's stock layout already returns a
+  // Fragment-only output for SSG-MD). The visible HTML SSG path
+  // (`SSG_MD` undefined) still gets the full chrome.
+  if (import.meta.env.SSG_MD) {
+    return (
+      <OriginalLayout
+        top={null}
+        beforeNavMenu={null}
+        afterNavMenu={null}
+        beforeSidebar={null}
+        afterSidebar={null}
+        beforeDoc={null}
+        afterDoc={null}
+        bottom={null}
+      />
+    )
+  }
+
   return (
     <>
       <CiderpressHeader
@@ -169,16 +193,17 @@ function readNavItems(site: unknown): readonly CiderpressNavMenuItem[] {
 
 /**
  * Build the list of `MetaAction`s to render under each doc page,
- * derived from `site.edit` and `site.report`. Returns an empty array
- * when neither is configured.
+ * derived from the serialised `site.edit` / `site.report` blocks
+ * (originally configured via top-level `editLink` / `reportLink`).
+ * Returns an empty array when neither is configured.
  *
  * @private
  * @param params - Site edit/report config plus current page path
  * @returns Ordered list of meta actions
  */
 function collectMetaActions(params: {
-  readonly edit: SiteEditConfig | undefined
-  readonly report: SiteReportConfig | undefined
+  readonly edit: CiderpressSiteBlock['edit']
+  readonly report: CiderpressSiteBlock['report']
   readonly pagePath: string
 }): readonly MetaAction[] {
   const { edit, report, pagePath } = params
@@ -204,9 +229,17 @@ function collectMetaActions(params: {
 }
 
 /**
+ * Construct the per-page "edit this page" URL from a serialised
+ * `editLink` block. The `buildSiteBlock` helper guarantees `repo` is
+ * present whenever the block itself is — callers should already have
+ * skipped the action when the block was `undefined`.
+ *
  * @private
+ * @param edit - Site edit block (non-undefined when called)
+ * @param pagePath - Current page's source path (with leading slash)
+ * @returns Fully-qualified URL string
  */
-function buildEditUrl(edit: SiteEditConfig, pagePath: string): string {
+function buildEditUrl(edit: NonNullable<CiderpressSiteBlock['edit']>, pagePath: string): string {
   if (edit.repo.startsWith('http')) {
     return edit.repo
   }
@@ -219,9 +252,14 @@ function buildEditUrl(edit: SiteEditConfig, pagePath: string): string {
 }
 
 /**
+ * Construct the "report an issue" URL from a serialised `reportLink`
+ * block. Same `repo`-presence contract as {@link buildEditUrl}.
+ *
  * @private
+ * @param report - Site report block (non-undefined when called)
+ * @returns Fully-qualified URL string
  */
-function buildReportUrl(report: SiteReportConfig): string {
+function buildReportUrl(report: NonNullable<CiderpressSiteBlock['report']>): string {
   if (report.repo.startsWith('http')) {
     return report.repo
   }

package/src/theme/components/nav/nav-logo.tsx

@@ -153,7 +153,11 @@ function readLogoConfig(mod: unknown): string | LogoFn | undefined {
     asRecord.default !== null && asRecord.default !== undefined
       ? (asRecord.default as Partial<CiderpressConfig>)
       : (mod as Partial<CiderpressConfig>)
-  const { logo } = candidate
+  const brand = candidate.brand
+  if (brand === undefined) {
+    return undefined
+  }
+  const { logo } = brand
   if (typeof logo === 'string') {
     return logo
   }

package/src/theme/components/shared/card-icon.tsx

@@ -0,0 +1,37 @@
+import { match } from 'massaman/match'
+import type React from 'react'
+
+import { Icon } from './icon'
+import type { ResolvedCardIcon } from './resolve-card-icon'
+
+interface CardIconProps {
+  readonly resolved: ResolvedCardIcon
+  readonly className?: string
+}
+
+/**
+ * Card-surface icon renderer. Branches on the discriminated
+ * `ResolvedCardIcon`:
+ *
+ * - `kind: 'iconify'` → `<Icon icon={id} />` wrapped in a colour swatch.
+ * - `kind: 'image'`   → `<img src alt>` painted at the same chip size
+ *   without colour tinting (the image carries its own art direction).
+ *
+ * @param props - Resolved icon + optional className applied to the swatch wrapper
+ * @returns Branded icon element
+ */
+export function CardIcon(props: CardIconProps): React.ReactElement {
+  const wrapperClass = props.className ?? 'cp-card__icon'
+  return match(props.resolved)
+    .with({ kind: 'iconify' }, (r) => (
+      <span className={`${wrapperClass} ${wrapperClass}--${r.color}`}>
+        <Icon icon={r.id} />
+      </span>
+    ))
+    .with({ kind: 'image' }, (r) => (
+      <span className={`${wrapperClass} ${wrapperClass}--image`}>
+        <img src={r.src} alt={r.alt} className={`${wrapperClass}-img`} />
+      </span>
+    ))
+    .exhaustive()
+}

package/src/theme/components/shared/ciderpress-logo.tsx

@@ -1,5 +1,9 @@
 import { BRAND_COLORS, DEFAULT_THEME_NAME } from '@ciderpress/theme'
-import type React from 'react'
+// Value import (not `import type`) — Rslib emits the classic JSX runtime
+// (`React.createElement(...)`), so the `React` binding must survive
+// compilation. With a type-only import, the bundle throws `React is not
+// defined` at runtime.
+import React from 'react'
 
 const FONT_STACK = "'SF Mono', 'Fira Code', 'JetBrains Mono', Consolas, monospace"
 /**

package/src/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/src/theme/components/shared/section-card.tsx

@@ -2,14 +2,15 @@ import { match, P } from 'massaman/match'
 import type React from 'react'
 
 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 +26,11 @@ export function SectionCard({
   description,
   icon = 'pixelarticons:file',
 }: SectionCardProps): React.ReactElement {
-  const resolved = resolveCardIcon(icon) ?? { id: 'pixelarticons:file', color: 'purple' }
+  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,9 +38,7 @@ 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>
       </div>
       {descEl}

package/src/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/src/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)

package/src/theme/components/workspaces/card.tsx

@@ -2,7 +2,8 @@ import { match, P } from 'massaman/match'
 import type React from 'react'
 
 import { Card } from '../shared/card'
-import { Icon } from '../shared/icon'
+import { CardIcon } from '../shared/card-icon'
+import type { CardIconInput } from '../shared/resolve-card-icon'
 import { resolveCardIcon } from '../shared/resolve-card-icon'
 import { TechTag } from '../shared/tech-tag'
 
@@ -16,9 +17,10 @@ export interface WorkspaceCardProps {
    */
   readonly href: string
   /**
-   * Icon config — Iconify identifier string or `{ id, color }` object.
+   * Icon config — Iconify identifier string, `{ id, color }` object, or
+   * `{ kind: 'image', src, alt }` for a static image asset.
    */
-  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly icon?: CardIconInput
   /**
    * Scope prefix shown above the name (e.g. "apps/").
    */
@@ -67,13 +69,9 @@ export function WorkspaceCard({
   const resolved = resolveCardIcon(icon)
 
   const iconEl = match(resolved)
-    .with(P.nonNullable, (r) => <Icon icon={r.id} />)
+    .with(P.nonNullable, (r) => <CardIcon resolved={r} className="cp-card__icon" />)
     .otherwise(() => null)
 
-  const iconColor = match(resolved)
-    .with(P.nonNullable, (r) => r.color)
-    .otherwise(() => 'purple')
-
   const scopeEl = match(scope)
     .with(
       P.when((s): s is string => s !== undefined && s.length > 0),
@@ -117,7 +115,7 @@ export function WorkspaceCard({
     <Card href={href} className="cp-workspace-card">
       <div className="cp-workspace-card__header">
         <div className="cp-workspace-card__identity">
-          <span className={`cp-card__icon cp-card__icon--${iconColor}`}>{iconEl}</span>
+          {iconEl}
           <div className="cp-workspace-card__title">
             {scopeEl}
             <span

package/src/theme/hooks/use-ciderpress.ts

@@ -1,17 +1,17 @@
-import type { FooterConfig, HomeConfig, SiteConfig } from '@ciderpress/config'
+import type { FooterConfig, HomeConfig, SerializedIcon } from '@ciderpress/config'
 import { useSite } from '@rspress/core/runtime'
 
 export interface CiderpressSidebarItem {
   readonly text?: string
   readonly link?: string
-  readonly icon?: string
+  readonly icon?: SerializedIcon
   readonly items?: readonly CiderpressSidebarItem[]
 }
 
 export interface CiderpressSidebarLink {
   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'
 }
@@ -19,7 +19,7 @@ export interface CiderpressSidebarLink {
 export interface WorkspaceCardData {
   readonly title: string
   readonly href: string
-  readonly icon: string | { readonly id: string; readonly color: string } | undefined
+  readonly icon: SerializedIcon | undefined
   readonly scope: string | undefined
   readonly description: string | undefined
   readonly tags: readonly string[]
@@ -33,6 +33,61 @@ export interface WorkspaceGroupData {
   readonly cards: readonly WorkspaceCardData[]
 }
 
+/**
+ * Serialised view of the unified `CiderpressConfig` that the runtime
+ * theme components still read through. The `site` field is rebuilt in
+ * `packages/ui/src/config.ts` (`buildSiteBlock`) from the new top-level
+ * `editLink` / `reportLink` / `topbar` / `sidebar` / `footer` / `version`
+ * config — kept under the legacy `site.*` name so theme components don't
+ * need to be rewired to look up each field individually.
+ */
+export interface CiderpressSiteBlock {
+  readonly version: string | undefined
+  readonly edit:
+    | {
+        readonly repo: string
+        readonly branch?: string
+        readonly directory?: string
+        readonly label?: string
+      }
+    | undefined
+  readonly report:
+    | {
+        readonly repo: string
+        readonly branch?: string
+        readonly directory?: string
+        readonly label?: string
+      }
+    | undefined
+  readonly topbarCta: { readonly text: string; readonly href: string } | undefined
+  readonly sidebarPromo:
+    | {
+        readonly title: string
+        readonly body: string
+        readonly cta: { readonly text: string; readonly href: string }
+      }
+    | undefined
+  readonly announcement:
+    | {
+        readonly id?: string
+        readonly lead?: string
+        readonly message: string
+        readonly cta?: { readonly href: string; readonly label: string }
+        readonly persistent?: boolean
+      }
+    | undefined
+  readonly footer:
+    | {
+        readonly columns?: readonly {
+          readonly heading: string
+          readonly links: readonly { readonly text: string; readonly href: string }[]
+        }[]
+        readonly tagline?: string
+        readonly brandMark?: string
+      }
+    | undefined
+}
+
 interface CiderpressThemeConfig {
   readonly sidebar: Record<string, readonly CiderpressSidebarItem[]>
   readonly sidebarAbove: readonly CiderpressSidebarLink[] | undefined
@@ -41,7 +96,7 @@ interface CiderpressThemeConfig {
   readonly standaloneScopePaths: readonly string[] | undefined
   readonly home: HomeConfig | undefined
   readonly ciderpressFooter: FooterConfig | undefined
-  readonly site: SiteConfig | undefined
+  readonly site: CiderpressSiteBlock | undefined
 }
 
 /**

package/src/theme/lib/read-social-links.ts

@@ -2,8 +2,9 @@ import type { CiderpressSocialLink } from '../components/nav/ciderpress-nav-soci
 
 /**
  * Pull social-link entries (GitHub, npm, etc) from Rspress's `site`
- * shape. Lives on `site.themeConfig.socialLinks` after Rspress
- * normalisation but isn't surfaced on the public typings.
+ * shape. Lives on `site.themeConfig.socialLinks` after the
+ * `packages/ui/src/config.ts` serialiser writes the unified `socials`
+ * config into the runtime theme config.
  *
  * @param site - Rspress site data (typically the result of `useSite().site`)
  * @returns Array of social-link entries (empty array when not configured)
@@ -22,6 +23,6 @@ export function readSocialLinks(site: unknown): readonly CiderpressSocialLink[]
       typeof item === 'object' &&
       item !== null &&
       typeof (item as { icon?: unknown }).icon === 'string' &&
-      typeof (item as { content?: unknown }).content === 'string'
+      typeof (item as { url?: unknown }).url === 'string'
   )
 }

package/src/theme/lib/theme-favicon.ts

@@ -107,7 +107,7 @@ function buildIconDataUri(brand: string, shadow: string, surface: string): strin
 /**
  * Locate the existing `<link rel="icon">` element, creating one if the
  * document head doesn't have one yet (a defensive fallback — Rspress
- * normally renders one from `config.icon`).
+ * normally renders one from `brand.favicon`).
  *
  * @private
  * @returns Mutable link element

package/src/theme/lib/with-mount-base.ts

@@ -0,0 +1,31 @@
+import { withBase } from '@rspress/core/runtime'
+
+/**
+ * Prefix `value` with the configured Rspress `base` only when it's an
+ * absolute path that would otherwise escape the mount. Pass-through for
+ * data URIs, fully-qualified URLs, hash anchors, and relative paths —
+ * applying `withBase()` to those produces broken results (the kitchen-
+ * sink data-URI logo regression that the examples e2e caught).
+ *
+ * Use this wrapper at every render site that takes a user-supplied asset
+ * URL from the ciderpress config (`logo`, `heroDemo.src`, brand chips
+ * etc.), instead of calling `withBase()` directly.
+ *
+ * @param value - Asset URL or path from user config (may be `undefined`)
+ * @returns The base-prefixed URL when applicable, otherwise `value` as-is
+ */
+export function withMountBase(value: string | undefined): string {
+  if (value === undefined) {
+    return ''
+  }
+  if (!value.startsWith('/')) {
+    return value
+  }
+  // Data URIs (`data:image/svg+xml;...`) and protocol-relative or
+  // explicit-protocol URLs are absolute in their own namespace — never
+  // prefix.
+  if (value.startsWith('//') || /^[a-z][a-z0-9+\-.]*:/i.test(value)) {
+    return value
+  }
+  return withBase(value)
+}