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

package/src/theme/components/nav/header-icon.tsx

@@ -0,0 +1,119 @@
+/* oxlint-disable no-ternary -- raw-copied file; relaxed rules per packages/ui/CLAUDE.md */
+import type { CiderpressConfig, IconConfig, IconImage } from '@ciderpress/config'
+// oxlint-disable-next-line import/no-unresolved -- alias provided by createRspressConfig's resolve.alias
+import userConfigModule from '@ciderpress/internal/user-config'
+import { match } from 'massaman/match'
+import type React from 'react'
+
+import { Icon } from '../shared/icon'
+
+import './header-icon.css'
+
+/**
+ * Small brand chip rendered before `<HeaderLogo />` inside `cp-header-logo`.
+ *
+ * Reads `userConfig.brand.icon` from the bundled user config and routes:
+ * - Iconify id (`"devicon:react"`) → `<Icon>` component.
+ * - `{ id, color }` → `<Icon>` with inline color.
+ * - `{ src, alt }` → `<img>` with the user's asset.
+ * - missing → null (slot collapses, `<HeaderLogo />` stretches).
+ *
+ * Pairs with `<HeaderLogo />` for the canonical two-slot brand identity
+ * (icon chip + wordmark logo). Sites with only one of the two get the
+ * lone element rendered.
+ *
+ * @returns Branded icon chip ready to drop inside `cp-header-logo`, or null
+ */
+export function HeaderIcon(): React.ReactElement | null {
+  const icon = readIconConfig(userConfigModule)
+  if (icon === undefined) {
+    return null
+  }
+  return match(resolveTopbar(icon))
+    .with({ kind: 'iconify' }, (r) => (
+      <span className="cp-header-icon">
+        <Icon icon={r.id} style={inlineColor(r.color)} />
+      </span>
+    ))
+    .with({ kind: 'image' }, (r) => (
+      <span className="cp-header-icon">
+        <img src={r.src} alt={r.alt} className="cp-header-icon__img" />
+      </span>
+    ))
+    .exhaustive()
+}
+
+export { HeaderIcon as default }
+
+type TopbarIcon =
+  | { readonly kind: 'iconify'; readonly id: string; readonly color: string | undefined }
+  | { readonly kind: 'image'; readonly src: string; readonly alt: string }
+
+/**
+ * Extract the `brand.icon` field from the bundled user config module.
+ *
+ * @private
+ * @param mod - Module imported from `@ciderpress/internal/user-config`
+ * @returns The `brand.icon` value or `undefined` when none is configured
+ */
+function readIconConfig(mod: unknown): IconConfig | undefined {
+  if (mod === null || mod === undefined) {
+    return undefined
+  }
+  const asRecord = mod as Record<string, unknown>
+  const candidate =
+    asRecord.default !== null && asRecord.default !== undefined
+      ? (asRecord.default as Partial<CiderpressConfig>)
+      : (mod as Partial<CiderpressConfig>)
+  const brand = candidate.brand
+  if (brand === undefined) {
+    return undefined
+  }
+  return brand.icon
+}
+
+/**
+ * Discriminate `IconConfig` into a render-ready shape. Iconify strings get
+ * `color: undefined` (driven by ambient CSS); image objects supply alt
+ * defaulted to empty string per the underlying type.
+ *
+ * @private
+ * @param icon - Validated `IconConfig` value
+ * @returns Discriminated render shape
+ */
+function resolveTopbar(icon: IconConfig): TopbarIcon {
+  if (typeof icon === 'string') {
+    return { kind: 'iconify', id: icon, color: undefined }
+  }
+  if (isImageIcon(icon)) {
+    return { kind: 'image', src: icon.src, alt: icon.alt ?? '' }
+  }
+  return { kind: 'iconify', id: icon.id, color: icon.color }
+}
+
+/**
+ * Build an inline-style object that sets the chip's `color` when the user
+ * supplied an explicit palette colour. Iconify renders fills via
+ * `currentColor` for monochrome icons, so this is enough to retint them.
+ *
+ * @private
+ * @param color - Optional palette colour token
+ * @returns Inline style object or undefined
+ */
+function inlineColor(color: string | undefined): React.CSSProperties | undefined {
+  if (color === undefined) {
+    return undefined
+  }
+  return { color }
+}
+
+/**
+ * Type guard for the image-form `IconConfig` object.
+ *
+ * @private
+ * @param icon - Non-string icon config value
+ * @returns True when the object carries `src` (image form)
+ */
+function isImageIcon(icon: Exclude<IconConfig, string>): icon is IconImage {
+  return 'src' in icon && typeof icon.src === 'string'
+}

package/src/theme/components/nav/header-logo.css

@@ -0,0 +1,16 @@
+/**
+ * Sizing for the brand mark rendered inside `cp-header-logo` by
+ * `<HeaderLogo />`.
+ *
+ * The parent `.cp-header-logo` already sets `--cp-header-logo-height`
+ * (default 28px) and `width: auto` for inline SVGs. Apply matching
+ * rules to image marks so a user `logo: '/logo.svg'` lines up exactly
+ * with the SVG wordmark height — no extra config needed.
+ */
+
+.cp-header-logo__img,
+.cp-header-logo__mark {
+  height: var(--cp-header-logo-height, 28px);
+  width: auto;
+  display: block;
+}

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

@@ -0,0 +1,200 @@
+/* oxlint-disable no-ternary -- raw-copied file; relaxed rules per packages/ui/CLAUDE.md */
+import type { CiderpressConfig, LogoFn, LogoImage } from '@ciderpress/config'
+// oxlint-disable-next-line import/no-unresolved -- alias provided by createRspressConfig's resolve.alias
+import userConfigModule from '@ciderpress/internal/user-config'
+import { BRAND_COLORS, DEFAULT_THEME_NAME } from '@ciderpress/theme'
+import React, { useEffect, useState } from 'react'
+
+import { withMountBase } from '../../lib/with-mount-base.ts'
+
+import './header-logo.css'
+
+interface ThemeContext {
+  readonly name: string
+  readonly variant: 'light' | 'dark'
+  readonly isDark: boolean
+  readonly colors: {
+    readonly brand: string
+    readonly brandHover: string
+    readonly brandSoft: string
+    readonly bg: string
+    readonly text: string
+  }
+}
+
+const COLOR_VARS = Object.freeze({
+  brand: '--rp-c-brand',
+  brandHover: '--rp-c-brand-dark',
+  brandSoft: '--rp-c-brand-tint',
+  bg: '--rp-c-bg',
+  text: '--rp-c-text-1',
+})
+
+const DEFAULT_BRAND = BRAND_COLORS[DEFAULT_THEME_NAME]
+const FALLBACK_COLORS = Object.freeze({
+  brand: DEFAULT_BRAND.primary,
+  brandHover: DEFAULT_BRAND.hover,
+  brandSoft: DEFAULT_BRAND.soft,
+  bg: '#ffffff',
+  text: '#1f2937',
+})
+
+/**
+ * Brand mark rendered inside `<RouteLink className="cp-header-logo">`
+ * by `<CiderpressHeader />`.
+ *
+ * Reads `userConfig.brand.logo` from the bundled user config (same
+ * `@ciderpress/internal/user-config` alias `NavLogo` uses) and renders:
+ *
+ * - `string` → `<img src={...}>` pointed at the user's asset path.
+ * - `LogoFn` → call with the live theme context. `LogoImage` returns
+ *   render as `<img>`; React node returns render as-is. Re-renders
+ *   when `data-cp-theme` / `data-cp-variant` flips so theme-aware
+ *   logos retint without a reload.
+ * - missing → the framework's themed `<CiderpressLogo />` wordmark.
+ *
+ * Replaces the prior approach where the header was hardcoded to
+ * `<CiderpressLogo />` and the user's logo was forwarded only to
+ * Rspress's nav slot — which renders at 1×1 on landing pages.
+ *
+ * @returns Branded logo element ready to drop inside `cp-header-logo`
+ */
+export function HeaderLogo(): React.ReactElement | null {
+  const logoConfig = readLogoConfig(userConfigModule)
+  const [themeContext, setThemeContext] = useState<ThemeContext | null>(null)
+
+  useEffect(() => {
+    if (typeof logoConfig !== 'function') {
+      return
+    }
+    const html = globalThis.document.documentElement
+    setThemeContext(readThemeContext(html))
+
+    const observer = new MutationObserver(() => {
+      setThemeContext(readThemeContext(html))
+    })
+    observer.observe(html, {
+      attributes: true,
+      attributeFilter: ['data-cp-theme', 'data-cp-variant', 'class', 'style'],
+    })
+    return () => observer.disconnect()
+  }, [logoConfig])
+
+  if (logoConfig === undefined) {
+    // Default: the auto-generated `/logo.svg` written to the public dir
+    // by the banner module at sync time (derived from `config.title`).
+    // Sites that committed their own `public/logo.svg` already win here.
+    // The `<CiderpressLogo />` framework wordmark is opt-in via
+    // `logo: ({ theme }) => <CiderpressLogo />`.
+    return <img src={withMountBase('/logo.svg')} alt="" className="cp-header-logo__img" />
+  }
+
+  if (typeof logoConfig === 'string') {
+    return <img src={withMountBase(logoConfig)} alt="" className="cp-header-logo__img" />
+  }
+
+  if (themeContext === null) {
+    // Function-form logo: render nothing for a frame instead of flashing
+    // the ciderpress wordmark while themeContext resolves. The user's
+    // logo appears as soon as the layout effect runs.
+    return null
+  }
+
+  const result = logoConfig({ theme: themeContext })
+  if (isLogoImage(result)) {
+    return (
+      <img
+        src={withMountBase(result.src)}
+        alt={result.alt ?? ''}
+        width={result.width}
+        height={result.height}
+        className="cp-header-logo__img"
+      />
+    )
+  }
+  return <>{result as React.ReactNode}</>
+}
+
+export { HeaderLogo as default }
+
+/**
+ * Extract the `logo` field from the bundled user config module.
+ *
+ * @private
+ * @param mod - Module imported from `@ciderpress/internal/user-config`
+ * @returns The `logo` value or `undefined` when none is configured
+ */
+function readLogoConfig(mod: unknown): string | LogoFn | undefined {
+  if (mod === null || mod === undefined) {
+    return undefined
+  }
+  const asRecord = mod as Record<string, unknown>
+  const candidate =
+    asRecord.default !== null && asRecord.default !== undefined
+      ? (asRecord.default as Partial<CiderpressConfig>)
+      : (mod as Partial<CiderpressConfig>)
+  const brand = candidate.brand
+  if (brand === undefined) {
+    return undefined
+  }
+  const { logo } = brand
+  if (typeof logo === 'string') {
+    return logo
+  }
+  if (typeof logo === 'function') {
+    return logo
+  }
+  return undefined
+}
+
+/**
+ * Type guard distinguishing a `LogoImage` object from a React element.
+ *
+ * @private
+ * @param value - Return value from a `LogoFn`
+ * @returns True when `value` should be spread onto an `<img>` element
+ */
+function isLogoImage(value: unknown): value is LogoImage {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+  const obj = value as Record<string, unknown>
+  if ('$$typeof' in obj) {
+    return false
+  }
+  return typeof obj.src === 'string'
+}
+
+/**
+ * Build the live `ThemeContext` passed to a function-form `logo`.
+ *
+ * @private
+ * @param html - Document root element
+ * @returns Live theme context snapshot
+ */
+function readThemeContext(html: HTMLElement): ThemeContext {
+  const variant: 'light' | 'dark' = html.dataset.cpVariant === 'light' ? 'light' : 'dark'
+  const name = typeof html.dataset.cpTheme === 'string' ? html.dataset.cpTheme : DEFAULT_THEME_NAME
+
+  const styles = globalThis.window.getComputedStyle(html)
+  function read(cssVar: string, fallback: string): string {
+    const raw = styles.getPropertyValue(cssVar).trim()
+    if (raw.length === 0) {
+      return fallback
+    }
+    return raw
+  }
+
+  return {
+    name,
+    variant,
+    isDark: variant === 'dark',
+    colors: {
+      brand: read(COLOR_VARS.brand, FALLBACK_COLORS.brand),
+      brandHover: read(COLOR_VARS.brandHover, FALLBACK_COLORS.brandHover),
+      brandSoft: read(COLOR_VARS.brandSoft, FALLBACK_COLORS.brandSoft),
+      bg: read(COLOR_VARS.bg, FALLBACK_COLORS.bg),
+      text: read(COLOR_VARS.text, FALLBACK_COLORS.text),
+    },
+  }
+}

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

@@ -6,8 +6,6 @@ import { BRAND_COLORS, DEFAULT_THEME_NAME } from '@ciderpress/theme'
 import React, { useEffect, useState } from 'react'
 import { createPortal } from 'react-dom'
 
-import { CiderpressLogo } from '../shared/ciderpress-logo'
-
 import './nav-logo.css'
 
 /**
@@ -37,7 +35,7 @@ const FALLBACK_COLORS = Object.freeze({
 })
 
 /**
- * `NavLogo` — Rspress-aware logo slot that handles all three logo configs.
+ * `NavLogo` — Rspress-aware logo slot for function-form `logo` configs.
  *
  * - Reads `userConfig.logo` from the bundled user config via the
  *   `@ciderpress/internal/user-config` alias.
@@ -52,7 +50,10 @@ const FALLBACK_COLORS = Object.freeze({
  * - `logo` is a function → call with the live `LogoContext`. If the return
  *   value is a `LogoImage`-shaped object, spread onto `<img>`. Otherwise
  *   render as a React node.
- * - `logo` is missing → render the default themed `<CiderpressLogo />`.
+ * - `logo` is missing → render `null`; Rspress paints the auto-generated
+ *   `/logo.svg` (written to the public dir by the banner module, derived
+ *   from the project title). Users who want the framework's themed wordmark
+ *   opt in via `logo: ({ theme }) => <CiderpressLogo />`.
  *
  * @returns Portaled logo element or null
  */
@@ -116,13 +117,11 @@ export function NavLogo(): React.ReactElement | null {
 
   const logoConfig = readLogoConfig(userConfigModule)
 
-  // String-form user logos are handled by Rspress's native <img>. NavLogo
-  // takes over for both the default case (theme-aware CiderpressLogo SVG) and
-  // function-form logos (user-defined render). The static `/logo.svg` from
-  // Rspress's <img> renders immediately on first paint; once NavLogo's
-  // portal mounts, CSS hides the static img so only the theme-aware version
-  // shows. Theme color flips via `currentColor` reading from `--rp-c-brand`.
-  if (typeof logoConfig === 'string') {
+  // String-form user logos and the missing-logo default both ride Rspress's
+  // native <img>. resolveLogo() in @ciderpress/ui/config maps the missing
+  // case to the auto-generated /logo.svg path. Only function-form logos
+  // need this portal — they re-render when the theme/variant changes.
+  if (typeof logoConfig !== 'function') {
     return null
   }
 
@@ -130,13 +129,7 @@ export function NavLogo(): React.ReactElement | null {
     return null
   }
 
-  // Raw-copied file — plain conditional, no ts-pattern (see packages/ui/CLAUDE.md).
-  const rendered =
-    typeof logoConfig === 'function' ? (
-      renderLogoFn({ fn: logoConfig, theme: themeContext })
-    ) : (
-      <CiderpressLogo />
-    )
+  const rendered = renderLogoFn({ fn: logoConfig, theme: themeContext })
 
   return createPortal(<span className="cp-nav-logo">{rendered}</span>, target)
 }
@@ -160,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 }))
 }