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

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

@@ -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/icon.tsx

@@ -1,41 +1,125 @@
-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 nine
+ * `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'),
+  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]
 }