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

package/dist/theme/components/footer/site-footer.tsx

@@ -1,14 +1,15 @@
+import type { CopyrightConfig, FooterConfig } from '@ciderpress/config'
 import { useSite } from '@rspress/core/runtime'
-import { match } from 'massaman/match'
+import { match, P } from 'massaman/match'
 import type React from 'react'
 
 import { useCiderpress } from '../../hooks/use-ciderpress'
 import { readSocialLinks } from '../../lib/read-social-links'
 import { RouteLink } from '../../lib/route-link.tsx'
 import { safeUrl } from '../../lib/safe-url.ts'
+import { withMountBase } from '../../lib/with-mount-base.ts'
 import { CiderpressNavSocialLinks } from '../nav/ciderpress-nav-social-links'
 import { ThemeSwitcher } from '../nav/theme-switcher'
-import { CiderpressMark } from '../shared/ciderpress-mark'
 
 import './site-footer.css'
 
@@ -35,14 +36,17 @@ export function SiteFooter(): React.ReactElement | null {
   const { message, copyright, socials } = ciderpressFooter ?? {}
   const { columns, tagline, brandMark } = siteFooter ?? {}
 
-  const hasRspressContent = message !== undefined || copyright !== undefined || socials === true
+  const copyrightText = resolveCopyright(copyright, rspressSite.title)
+  const shouldRenderSocials = socials === true && socialLinks.length > 0
+
+  const hasFooterContent = message !== undefined || copyrightText !== null || shouldRenderSocials
   const hasSiteContent = columns !== undefined || tagline !== undefined
   // The footer also hosts the theme switcher when it's enabled — so a
-  // config with `theme.switcher: true` but no other footer content
+  // config with `theme.themeSwitcher: true` but no other footer content
   // still needs the footer shell rendered.
   const hasSwitcher = __CIDERPRESS_THEME_SWITCHER__
 
-  if (!hasRspressContent && !hasSiteContent && !hasSwitcher) {
+  if (!hasFooterContent && !hasSiteContent && !hasSwitcher) {
     return null
   }
 
@@ -56,7 +60,16 @@ export function SiteFooter(): React.ReactElement | null {
             <div className="cp-site-footer__brand-mark">
               {match(brandMark)
                 .with(undefined, () => (
-                  <CiderpressMark className="cp-site-footer__brand-icon" title="" />
+                  // Default to the project's `/icon.svg` (auto-generated
+                  // from `config.title` at sync time, or overridden by
+                  // shipping a `public/icon.svg`). This was previously
+                  // the hardcoded `<CiderpressMark />` apple, which
+                  // leaked ciderpress branding into every footer.
+                  <img
+                    src={withMountBase('/icon.svg')}
+                    alt=""
+                    className="cp-site-footer__brand-icon"
+                  />
                 ))
                 .otherwise((mark) => mark)}
             </div>
@@ -65,7 +78,7 @@ export function SiteFooter(): React.ReactElement | null {
               .otherwise((msg) => (
                 <p className="cp-site-footer__message">{msg}</p>
               ))}
-            {match(socials === true && socialLinks.length > 0)
+            {match(shouldRenderSocials)
               .with(true, () => (
                 <div className="cp-site-footer__socials">
                   <CiderpressNavSocialLinks links={socialLinks} />
@@ -95,8 +108,8 @@ export function SiteFooter(): React.ReactElement | null {
       </div>
       <div className="cp-site-footer__bottom">
         <div className="cp-site-footer__bottom-inner">
-          {match(copyright)
-            .with(undefined, () => null)
+          {match(copyrightText)
+            .with(null, () => null)
             .otherwise((cr) => (
               <span className="cp-site-footer__copyright">{cr}</span>
             ))}
@@ -113,3 +126,49 @@ export function SiteFooter(): React.ReactElement | null {
     </footer>
   )
 }
+
+/**
+ * Resolve the `footer.copyright` config union into a string for rendering.
+ *
+ * Accepts the new public shape: `true` for auto-generation from the site
+ * title + current year, a verbatim string, or a `CopyrightConfig` object
+ * with `company` / `dba` / `year`. `undefined` returns `null` so the
+ * caller can skip the render.
+ *
+ * @private
+ * @param copyright - The footer copyright config value
+ * @param siteTitle - The Rspress site title to use as fallback owner name
+ * @returns The formatted copyright string, or `null` when nothing should render
+ */
+function resolveCopyright(
+  copyright: FooterConfig['copyright'],
+  siteTitle: string | undefined
+): string | null {
+  return match(copyright)
+    .with(undefined, () => null)
+    .with(true, () => formatCopyright({}, siteTitle))
+    .with(P.string, (s) => s)
+    .otherwise((cfg) => formatCopyright(cfg, siteTitle))
+}
+
+/**
+ * Build a copyright string from a partial `CopyrightConfig`. Falls back to
+ * the site title for the owner name and the current year for the date.
+ *
+ * @private
+ * @param cfg - Copyright config object (may be empty)
+ * @param siteTitle - Fallback owner name
+ * @returns Formatted copyright string
+ */
+function formatCopyright(cfg: CopyrightConfig, siteTitle: string | undefined): string {
+  const currentYear = new Date().getFullYear()
+  const yearPart = match(cfg.year)
+    .with(undefined, () => String(currentYear))
+    .with(P.number, (n) => String(n))
+    .otherwise(({ from }) => `${from}–${currentYear}`)
+  const owner = cfg.dba ?? cfg.company ?? siteTitle ?? ''
+  const ownerPart = match(owner.length === 0)
+    .with(true, () => '')
+    .otherwise(() => ` ${owner}`)
+  return `© ${yearPart}${ownerPart}`
+}

package/dist/theme/components/home/feature-card.tsx

@@ -3,14 +3,15 @@ import type React from 'react'
 
 import './feature-card.css'
 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'
 
 export interface FeatureCardProps {
   readonly title: string
   readonly description: string
   readonly href?: string
-  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly icon?: CardIconInput
   readonly span?: 2 | 3 | 4 | 6
   readonly titleLines?: number
   readonly descriptionLines?: number
@@ -23,7 +24,7 @@ export interface FeatureItem {
   readonly title: string
   readonly details: string
   readonly link?: string
-  readonly icon?: string | { readonly id: string; readonly color: string }
+  readonly icon?: CardIconInput
   readonly span?: 2 | 3 | 4 | 6
 }
 
@@ -46,11 +47,7 @@ export function FeatureCard({
   const resolved = resolveCardIcon(icon)
 
   const iconEl = match(resolved)
-    .with(P.nonNullable, (r) => (
-      <span className={`cp-card__icon cp-card__icon--${r.color}`}>
-        <Icon icon={r.id} />
-      </span>
-    ))
+    .with(P.nonNullable, (r) => <CardIcon resolved={r} className="cp-card__icon" />)
     .otherwise(() => null)
 
   const linkTail = match(href)

package/dist/theme/components/home/feature.tsx

@@ -1,4 +1,4 @@
-import type { HomeGridConfig } from '@ciderpress/config'
+import type { HomeFeaturesConfig } from '@ciderpress/config'
 import { useFrontmatter } from '@rspress/core/runtime'
 import { match, P } from 'massaman/match'
 import type React from 'react'
@@ -7,6 +7,17 @@ import { useCiderpress } from '../../hooks/use-ciderpress'
 import { FeatureCard } from './feature-card'
 import type { FeatureItem } from './feature-card'
 
+interface FrontmatterFeaturesHeading {
+  readonly label?: string
+  readonly title?: string
+  readonly subtitle?: string
+}
+
+const DEFAULT_HEADING_EYEBROW = 'Features'
+const DEFAULT_HEADING_TITLE = 'Built for the way you ship.'
+const DEFAULT_HEADING_SUBTITLE =
+  "Everything you need, nothing you don't. Configured in TypeScript, validated at boot."
+
 /**
  * Custom HomeFeature override for ciderpress.
  * Uses useFrontmatter() hook to read features and renders with FeatureCard/FeatureGrid styling.
@@ -21,9 +32,21 @@ export function HomeFeature(): React.ReactElement | null {
   // Rspress types frontmatter as its own FrontMatterMeta shape which does not
   // include ciderpress-specific `features`. The double cast is necessary because
   // no shared Zod schema exists for frontmatter validation at runtime.
-  const features = (frontmatter as Record<string, unknown>).features as
-    | readonly FeatureItem[]
-    | undefined
+  const fm = frontmatter as Record<string, unknown>
+  const features = fm.features as readonly FeatureItem[] | undefined
+  const heading = fm.featuresHeading as FrontmatterFeaturesHeading | undefined
+  // Frontmatter is unvalidated user content — a `featuresHeading.title: {}`
+  // would otherwise render as `[object Object]` in the H2. Treat any
+  // non-string value as missing and fall through to the framework default.
+  const headingEyebrow = match(heading && heading.label)
+    .with(P.string, (s) => s)
+    .otherwise(() => DEFAULT_HEADING_EYEBROW)
+  const headingTitle = match(heading && heading.title)
+    .with(P.string, (s) => s)
+    .otherwise(() => DEFAULT_HEADING_TITLE)
+  const headingSubtitle = match(heading && heading.subtitle)
+    .with(P.string, (s) => s)
+    .otherwise(() => DEFAULT_HEADING_SUBTITLE)
 
   return match(features)
     .with(
@@ -31,12 +54,9 @@ export function HomeFeature(): React.ReactElement | null {
       (items) => (
         <div className="cp-feature-section">
           <div className="cp-feature-section-head">
-            <div className="cp-feature-section-head__eyebrow">Features</div>
-            <h2 className="cp-feature-section-head__title">Built for the way you ship.</h2>
-            <p className="cp-feature-section-head__sub">
-              Everything you need, nothing you don&apos;t. Configured in TypeScript, validated at
-              boot.
-            </p>
+            <div className="cp-feature-section-head__eyebrow">{headingEyebrow}</div>
+            <h2 className="cp-feature-section-head__title">{headingTitle}</h2>
+            <p className="cp-feature-section-head__sub">{headingSubtitle}</p>
           </div>
           <div className="cp-feature-grid">
             {items.map((f, i) => renderFeature(f, i, gridConfig))}
@@ -60,7 +80,7 @@ export function HomeFeature(): React.ReactElement | null {
 function renderFeature(
   feature: FeatureItem,
   index: number,
-  gridConfig: HomeGridConfig | undefined
+  gridConfig: HomeFeaturesConfig | undefined
 ): React.ReactElement {
   const titleLines = gridConfig && gridConfig.truncate && gridConfig.truncate.title
   const descLines = gridConfig && gridConfig.truncate && gridConfig.truncate.description

package/dist/theme/components/home/hero-demo-custom.tsx

@@ -0,0 +1,116 @@
+import type { HomeHeroDemoConfig, HomeHeroDemoLine, HomeHeroDemoTerminal } from '@ciderpress/config'
+import { match } from 'massaman/match'
+import type React from 'react'
+
+import { withMountBase } from '../../lib/with-mount-base.ts'
+
+import './hero-demo.css'
+
+interface CustomHeroDemoProps {
+  readonly config: HomeHeroDemoConfig
+}
+
+/**
+ * Custom replacement for `<HeroDemo />`. Driven by `home.hero.demo` from
+ * `ciderpress.config.ts`:
+ *
+ * - **Image form** (`{ src, alt, width?, height? }`) — renders an
+ *   `<img>` inside the framework's framed `cp-hero-demo` container
+ *   (rounded corners + brand-soft glow shadow preserved).
+ * - **Terminal form** (`{ windowTitle?, command, lines }`) — keeps the
+ *   fake-macOS chrome but paints the user's command + output lines.
+ *
+ * The discriminator is structural: image objects carry `src`, terminal
+ * objects carry `lines`.
+ *
+ * @param props - Validated `HomeHeroDemoConfig`
+ * @returns Custom hero demo element
+ */
+export function CustomHeroDemo(props: CustomHeroDemoProps): React.ReactElement {
+  return match(props.config)
+    .when(
+      (c): c is HomeHeroDemoTerminal => 'lines' in c,
+      (c) => <CustomTerminal config={c} />
+    )
+    .otherwise((c) => (
+      <div className="cp-hero-demo cp-hero-demo--image">
+        <img
+          src={withMountBase(c.src)}
+          alt={c.alt ?? ''}
+          width={c.width}
+          height={c.height}
+          className="cp-hero-demo__img"
+        />
+      </div>
+    ))
+}
+
+interface CustomTerminalProps {
+  readonly config: HomeHeroDemoTerminal
+}
+
+/**
+ * Render the terminal-form hero demo with user-supplied command + lines.
+ *
+ * @private
+ * @param props - Validated terminal config
+ * @returns Terminal-shell hero demo element
+ */
+function CustomTerminal(props: CustomTerminalProps): React.ReactElement {
+  const { windowTitle, command, lines } = props.config
+  return (
+    <div className="cp-hero-demo">
+      <div className="cp-hero-demo__bar">
+        <span className="cp-hero-demo__dot" />
+        <span className="cp-hero-demo__dot" />
+        <span className="cp-hero-demo__dot" />
+        {match(windowTitle)
+          .with(undefined, () => null)
+          .otherwise((t) => (
+            <span className="cp-hero-demo__title">{t}</span>
+          ))}
+      </div>
+      <pre className="cp-hero-demo__body">
+        <span className="cp-hero-demo__prompt">$ </span>
+        {command}
+        {'\n\n'}
+        {lines.map((line, i) => (
+          <TerminalLine key={`${line.kind}-${i}`} line={line} />
+        ))}
+      </pre>
+    </div>
+  )
+}
+
+interface TerminalLineProps {
+  readonly line: HomeHeroDemoLine
+}
+
+/**
+ * Render a single line of the structured terminal hero demo. Each
+ * kind gets a coloured prefix glyph mirroring the framework default.
+ *
+ * @private
+ * @param props - Single line entry
+ * @returns Glyph-prefixed line followed by a newline
+ */
+function TerminalLine(props: TerminalLineProps): React.ReactElement {
+  const className = match(props.line.kind)
+    .with('ok', () => 'cp-hero-demo__ok')
+    .with('info', () => 'cp-hero-demo__info')
+    .with('cmt', () => 'cp-hero-demo__cmt')
+    .with('err', () => 'cp-hero-demo__err')
+    .exhaustive()
+  const glyph = match(props.line.kind)
+    .with('ok', () => ' ✓')
+    .with('info', () => ' ▸')
+    .with('cmt', () => ' ↻')
+    .with('err', () => ' ✗')
+    .exhaustive()
+  return (
+    <>
+      <span className={className}>{glyph}</span> {props.line.text}
+      {'\n'}
+    </>
+  )
+}

package/dist/theme/components/home/hero-demo.css

@@ -64,3 +64,30 @@
 .cp-hero-demo__file {
   color: var(--cp-c-tint-amber-bright-fg);
 }
+
+/* Image-form hero demo — the frame chrome (rounded corners + brand-soft
+   glow shadow) stays; the `<img>` simply fills the surface. The hero
+   slot already constrains aspect ratio. */
+.cp-hero-demo--image {
+  padding: 0;
+}
+
+.cp-hero-demo__img {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: inherit;
+}
+
+/* Custom Split visual `<pre>` shares the `.cp-split__code` surface with
+   the default `ConfigPreview` block — same padding, font, scrolling. */
+.cp-split__code {
+  margin: 0;
+  padding: var(--cp-s-20) var(--cp-s-24);
+  font-family: var(--cp-font-family-mono);
+  font-size: var(--cp-fs-code);
+  line-height: var(--cp-lh-code);
+  white-space: pre;
+  overflow-x: auto;
+  color: var(--cp-c-text-1);
+}

package/dist/theme/components/home/layout.tsx

@@ -1,6 +1,13 @@
+import type {
+  ButtonConfig,
+  HomeHeroDemoConfig,
+  HomeSectionId,
+  HomeSplitConfig,
+} from '@ciderpress/config'
+import { DEFAULT_HOME_LAYOUT } from '@ciderpress/config'
 import { useFrontmatter } from '@rspress/core/runtime'
-import { match } from 'massaman/match'
-import type React from 'react'
+import { match, P } from 'massaman/match'
+import React from 'react'
 
 import { SiteFooter } from '../footer/site-footer'
 import { CTA } from './cta'
@@ -8,8 +15,10 @@ import { HomeFeature } from './feature'
 import { Hero } from './hero'
 import type { HeroAction } from './hero'
 import { HeroDemo } from './hero-demo'
+import { CustomHeroDemo } from './hero-demo-custom'
 import { PageRail } from './page-rail'
 import { HomeSplit } from './split'
+import { CustomSplitVisual } from './split-visual-custom'
 import { TrustStrip } from './trust-strip'
 import { HomeWorkspaces } from './workspaces'
 
@@ -24,11 +33,11 @@ interface FrontmatterHero {
   readonly name?: string
   readonly text?: string
   readonly tagline?: string
-  readonly actions?: readonly HeroAction[]
-  readonly eyebrow?: string
+  readonly actions?: readonly ButtonConfig[]
+  readonly label?: string
 }
 
-interface FrontmatterTrust {
+interface FrontmatterProof {
   readonly lead?: string
   readonly names?: readonly string[]
 }
@@ -36,7 +45,7 @@ interface FrontmatterTrust {
 interface FrontmatterCTA {
   readonly title?: string
   readonly subtitle?: string
-  readonly actions?: readonly HeroAction[]
+  readonly actions?: readonly ButtonConfig[]
 }
 
 /**
@@ -52,25 +61,48 @@ interface FrontmatterCTA {
  */
 export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
   const { frontmatter } = useFrontmatter()
+
+  // SSG-MD short-circuit: the React tree is walked by
+  // `react-render-to-markdown` to produce `.md` files served to
+  // `<LlmsCopyButton />`. Rendering the home shell would dump hero
+  // text, demo blocks, and footer columns into every copied page.
+  // Return an empty fragment for SSG-MD — the home page has no
+  // canonical markdown body. The `useFrontmatter` hook above runs in
+  // both passes so hook order stays consistent.
+  if (import.meta.env.SSG_MD) {
+    return <></>
+  }
+
   const fm = frontmatter as Record<string, unknown>
 
   const hero = fm.hero as FrontmatterHero | undefined
-  const trust = fm.trust as FrontmatterTrust | undefined
+  const proof = fm.proof as FrontmatterProof | undefined
   const cta = fm.cta as FrontmatterCTA | undefined
+  // heroDemo / split frontmatter:
+  //   undefined → render the framework default
+  //   false     → suppress entirely
+  //   object    → render the user-supplied custom variant
+  const heroDemoFm = fm.heroDemo as false | HomeHeroDemoConfig | undefined
+  const splitFm = fm.split as false | HomeSplitConfig | undefined
+
+  const heroDemoEl = match(heroDemoFm)
+    .with(false, () => null)
+    .with(undefined, () => <HeroDemo />)
+    .otherwise((d) => <CustomHeroDemo config={d} />)
 
   const heroSection = match(hero)
     .with(undefined, () => null)
     .otherwise((h) => (
       <Hero
-        eyebrow={h.eyebrow}
+        eyebrow={h.label}
         title={renderTitle(h.text ?? h.name ?? '')}
         tagline={h.tagline}
-        actions={h.actions}
-        demo={<HeroDemo />}
+        actions={mapButtonsToHeroActions(h.actions)}
+        demo={heroDemoEl}
       />
     ))
 
-  const trustSection = match(trust)
+  const proofSection = match(proof)
     .with(undefined, () => null)
     .otherwise((t) => {
       const names = t.names ?? []
@@ -84,18 +116,18 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
     .otherwise((c) =>
       match(c.title === undefined)
         .with(true, () => null)
-        .otherwise(() => <CTA title={c.title ?? ''} subtitle={c.subtitle} actions={c.actions} />)
+        .otherwise(() => (
+          <CTA
+            title={c.title ?? ''}
+            subtitle={c.subtitle}
+            actions={mapButtonsToHeroActions(c.actions)}
+          />
+        ))
     )
 
-  return (
-    <PageRail>
-      {props.beforeHero}
-      {heroSection}
-      {props.afterHero}
-      {trustSection}
-      {props.beforeFeatures}
-      <HomeFeature />
-      {props.afterFeatures}
+  const splitSection = match(splitFm)
+    .with(false, () => null)
+    .with(undefined, () => (
       <HomeSplit
         eyebrow="Configuration"
         title="One file. Validated. Type-safe."
@@ -109,8 +141,57 @@ export function HomeLayout(props: HomeLayoutProps): React.ReactElement {
         action={{ theme: 'brand', text: 'Read the docs', link: '/getting-started/quick-start' }}
         visual={<ConfigPreview />}
       />
-      <HomeWorkspaces />
-      {ctaSection}
+    ))
+    .with(P.nonNullable, (s) => (
+      <HomeSplit
+        eyebrow={s.label}
+        title={s.title}
+        body={s.body}
+        bullets={s.bullets ?? []}
+        action={match(s.cta)
+          .with(undefined, () => undefined)
+          .otherwise((c) => ({ theme: 'brand' as const, text: c.text, link: c.href }))}
+        visual={match(s.visual)
+          .with(undefined, () => null)
+          .otherwise((v) => (
+            <CustomSplitVisual code={v.code} language={v.language} />
+          ))}
+      />
+    ))
+    .exhaustive()
+
+  // Section render order. `home.layout` (when provided) controls both
+  // order and visibility — sections omitted from the array are not
+  // rendered. The framework default (`DEFAULT_HOME_LAYOUT`) preserves
+  // the historical fixed order. Unknown ids are ignored at render time
+  // (the schema rejects them at config-load anyway).
+  const layout = (fm.layout as readonly HomeSectionId[] | undefined) ?? DEFAULT_HOME_LAYOUT
+  const sectionsById: Readonly<Record<HomeSectionId, React.ReactNode>> = {
+    hero: (
+      <>
+        {props.beforeHero}
+        {heroSection}
+        {props.afterHero}
+      </>
+    ),
+    proof: proofSection,
+    features: (
+      <>
+        {props.beforeFeatures}
+        <HomeFeature />
+        {props.afterFeatures}
+      </>
+    ),
+    split: splitSection,
+    showcase: <HomeWorkspaces />,
+    cta: ctaSection,
+  }
+
+  return (
+    <PageRail>
+      {layout.map((id) => (
+        <React.Fragment key={id}>{sectionsById[id]}</React.Fragment>
+      ))}
       <SiteFooter />
     </PageRail>
   )
@@ -134,16 +215,16 @@ function ConfigPreview(): React.ReactElement {
       {'  title: '}
       <span className="tok-str">'Acme Docs'</span>
       {',\n'}
-      {'  sections: [\n'}
+      {'  pages: [\n'}
       {'    { title: '}
       <span className="tok-str">'Guides'</span>
       {', include: '}
       <span className="tok-str">'docs/guides/*.md'</span>
       {' },\n'}
       {'  ],\n'}
-      {'  theme: { name: '}
+      {'  theme: { themes: ['}
       <span className="tok-str">'mulled'</span>
-      {' },\n'}
+      {'] },\n'}
       {'})'}
     </pre>
   )
@@ -181,3 +262,45 @@ function renderTitle(raw: string): React.ReactNode {
         })
     })
 }
+
+/**
+ * Map the unified `ButtonConfig[]` shape (used by the new `home.hero`
+ * / `home.cta` configs) into the legacy `HeroAction[]` shape still
+ * consumed by `<Hero />` and `<CTA />`. `'primary'` → `'brand'`,
+ * `'secondary' | 'ghost'` → `'alt'`, `undefined` → `undefined`.
+ *
+ * @private
+ * @param actions - Optional list of unified button configs from frontmatter
+ * @returns Hero-action array consumed by the existing component API
+ */
+function mapButtonsToHeroActions(
+  actions: readonly ButtonConfig[] | undefined
+): readonly HeroAction[] | undefined {
+  if (actions === undefined) {
+    return undefined
+  }
+  return actions.map((action) => ({
+    text: action.text,
+    link: action.href,
+    theme: mapButtonVariantToHeroTheme(action.variant),
+  }))
+}
+
+/**
+ * Project the new `'primary' | 'secondary' | 'ghost'` variant token
+ * back into the legacy `'brand' | 'alt'` token that `<Hero />` accepts.
+ *
+ * @private
+ * @param variant - Optional variant from the unified button config
+ * @returns `'brand'`, `'alt'`, or `undefined`
+ */
+function mapButtonVariantToHeroTheme(
+  variant: ButtonConfig['variant']
+): 'brand' | 'alt' | undefined {
+  return match(variant)
+    .with(undefined, () => undefined)
+    .with('primary', () => 'brand' as const)
+    .with('secondary', () => 'alt' as const)
+    .with('ghost', () => 'alt' as const)
+    .exhaustive()
+}

package/dist/theme/components/home/split-visual-custom.tsx

@@ -0,0 +1,26 @@
+import type React from 'react'
+
+interface CustomSplitVisualProps {
+  readonly code: string
+  readonly language?: string
+}
+
+/**
+ * Custom Split visual — renders a user-supplied code snippet inside the
+ * same `<pre>` shell as the default `ConfigPreview`. Language hint is
+ * surfaced as a `data-language` attribute so themes can hook into it
+ * for syntax-highlighter overlays. No client-side highlighting is
+ * performed in the framework (keeps the bundle slim); the rendered
+ * `<pre>` matches the default surface so themes that style the
+ * default block also style the custom one.
+ *
+ * @param props - Code snippet + optional language hint
+ * @returns Pre-formatted code block
+ */
+export function CustomSplitVisual(props: CustomSplitVisualProps): React.ReactElement {
+  return (
+    <pre data-language={props.language ?? 'ts'} className="cp-split__code">
+      {props.code}
+    </pre>
+  )
+}