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

package/dist/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/dist/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/dist/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/dist/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'
@@ -59,7 +59,14 @@ export function Layout(): React.ReactElement {
     .with(true, () => configNavItems)
     .otherwise(() => scrapedNavItems)
   const socialLinks = readSocialLinks(rspressSite)
-  const { announcement, topbarCta, sidebarPromo: sidebarPromoConfig, edit, report } = site ?? {}
+  const {
+    announcement,
+    topbarCta,
+    sidebarPromo: sidebarPromoConfig,
+    edit,
+    report,
+    feedback,
+  } = site ?? {}
   const { frontmatter } = useFrontmatter()
   const fmRecord = frontmatter as Record<string, unknown>
   const isHome = fmRecord.pageType === 'home'
@@ -113,13 +120,41 @@ export function Layout(): React.ReactElement {
 
   const metaActions = collectMetaActions({ edit, report, pagePath })
 
+  const feedbackSlot = match(feedback)
+    .with({ enabled: true }, (f) => <Feedback question={f.question} />)
+    .otherwise(() => null)
+
   const afterDocSlot = (
     <ContentFooterPortal>
-      <Feedback />
+      {feedbackSlot}
       <MetaActions actions={metaActions} />
     </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
@@ -158,27 +193,80 @@ function readNavItems(site: unknown): readonly CiderpressNavMenuItem[] {
   if (!Array.isArray(candidate)) {
     return []
   }
-  return candidate.filter(
-    (item): item is CiderpressNavMenuItem =>
-      typeof item === 'object' &&
-      item !== null &&
-      typeof (item as { text?: unknown }).text === 'string' &&
-      typeof (item as { link?: unknown }).link === 'string'
-  )
+  return candidate.map(toNavItem).filter((item): item is CiderpressNavMenuItem => item !== null)
+}
+
+/**
+ * Coerce one raw Rspress nav entry into a `CiderpressNavMenuItem`,
+ * recursing into `items` for dropdown parents. Entries missing a
+ * string `text`, or that are neither a link nor a non-empty dropdown,
+ * are dropped (returned as `null`).
+ *
+ * @private
+ * @param raw - Untyped nav entry read off `site.nav`
+ * @returns Parsed nav item, or `null` when the entry is unusable
+ */
+function toNavItem(raw: unknown): CiderpressNavMenuItem | null {
+  if (typeof raw !== 'object' || raw === null) {
+    return null
+  }
+  const record = raw as {
+    readonly text?: unknown
+    readonly link?: unknown
+    readonly items?: unknown
+  }
+  if (typeof record.text !== 'string') {
+    return null
+  }
+  const link = match(record.link)
+    .with(P.string, (value) => value)
+    .otherwise(() => undefined)
+  const items = match(Array.isArray(record.items))
+    .with(true, () =>
+      (record.items as readonly unknown[])
+        .map(toNavItem)
+        .filter((child): child is CiderpressNavMenuItem => child !== null)
+    )
+    .otherwise(() => [])
+  return buildNavItem({ text: record.text, link, items })
+}
+
+/**
+ * Assemble a `CiderpressNavMenuItem` from its parsed parts, keeping
+ * only the properties that are actually present so the result matches
+ * the optional-field contract. Returns `null` for a dead entry (no
+ * link and no children).
+ *
+ * @private
+ * @param params - The parsed text, optional link, and child items
+ * @returns A nav item, or `null` when there is nothing to render
+ */
+function buildNavItem(params: {
+  readonly text: string
+  readonly link: string | undefined
+  readonly items: readonly CiderpressNavMenuItem[]
+}): CiderpressNavMenuItem | null {
+  const { text, link, items } = params
+  return match({ hasLink: link !== undefined, hasItems: items.length > 0 })
+    .with({ hasLink: true, hasItems: true }, () => ({ text, link, items }))
+    .with({ hasLink: true, hasItems: false }, () => ({ text, link }))
+    .with({ hasLink: false, hasItems: true }, () => ({ text, items }))
+    .otherwise(() => null)
 }
 
 /**
  * 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 +292,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 +315,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/dist/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/dist/theme/components/openapi/index.ts

@@ -1,5 +1,3 @@
-export { CopyMarkdownButton } from './copy-markdown-button'
-export type { CopyMarkdownButtonProps } from './copy-markdown-button'
 export { OpenAPIOperation } from './operation'
 export type { OpenAPIOperationProps } from './operation'
 export { OpenAPIOverview } from './overview'

package/dist/theme/components/openapi/openapi.css

@@ -5,20 +5,6 @@
  * Uses BEM naming: block__element--modifier.
  */
 
-/* ── Hide Rspress default LLMs copy button on OpenAPI pages ── */
-/* OpenAPI pages use a custom CopyMarkdownButton with build-time rendered markdown */
-:has(.cp-oas-operation) > .rp-llms-container,
-:has(.cp-oas-overview) > .rp-llms-container {
-  display: none;
-}
-
-/* ── Copy markdown button ─────────────────────────────────── */
-.cp-oas-copy-markdown {
-  float: right;
-  margin-top: 8px;
-  margin-bottom: 0;
-}
-
 /* ── Two-column operation layout ───────────────────────────── */
 .cp-oas-operation {
   display: grid;

package/dist/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/dist/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"
 /**