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

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

@@ -1,4 +1,5 @@
-import type { HomeGridConfig } from '@ciderpress/config'
+import type { HomeShowcaseConfig } from '@ciderpress/config'
+import { useFrontmatter } from '@rspress/core/runtime'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
@@ -7,15 +8,29 @@ import type { WorkspaceGroupData } from '../../hooks/use-ciderpress'
 import { WorkspaceCard } from '../workspaces/card'
 import { WorkspaceGrid } from '../workspaces/grid'
 
+interface FrontmatterWorkspacesHeading {
+  readonly label?: string
+  readonly title?: string
+  readonly subtitle?: string
+}
+
 /**
  * Smart orchestrator that reads workspace data from themeConfig
  * and renders workspace groups with the correct card component per type.
  *
+ * Optionally renders a top-level heading above the workspace groups
+ * when `home.showcase.heading` is configured. The sync engine writes
+ * it into frontmatter as `workspacesHeading`.
+ *
  * @returns React element with workspace groups or null
  */
 export function HomeWorkspaces(): React.ReactElement | null {
   const { workspaces, home } = useCiderpress()
-  const gridConfig = home && home.workspaces
+  const gridConfig = home && home.showcase
+  const { frontmatter } = useFrontmatter()
+  const heading = (frontmatter as Record<string, unknown>).workspacesHeading as
+    | FrontmatterWorkspacesHeading
+    | undefined
 
   return match(workspaces)
     .with(
@@ -23,6 +38,27 @@ export function HomeWorkspaces(): React.ReactElement | null {
       (groups) => (
         <div className="cp-workspace-section">
           <hr className="cp-divider" />
+          {match(heading)
+            .with(undefined, () => null)
+            .otherwise((h) => (
+              <div className="cp-feature-section-head">
+                {match(h.label)
+                  .with(undefined, () => null)
+                  .otherwise((e) => (
+                    <div className="cp-feature-section-head__eyebrow">{e}</div>
+                  ))}
+                {match(h.title)
+                  .with(undefined, () => null)
+                  .otherwise((t) => (
+                    <h2 className="cp-feature-section-head__title">{t}</h2>
+                  ))}
+                {match(h.subtitle)
+                  .with(undefined, () => null)
+                  .otherwise((s) => (
+                    <p className="cp-feature-section-head__sub">{s}</p>
+                  ))}
+              </div>
+            ))}
           {groups.map((group) => renderGroup(group, gridConfig))}
         </div>
       )
@@ -40,7 +76,7 @@ export function HomeWorkspaces(): React.ReactElement | null {
  */
 function renderGroup(
   group: WorkspaceGroupData,
-  gridConfig: HomeGridConfig | undefined
+  gridConfig: HomeShowcaseConfig | undefined
 ): React.ReactElement {
   const titleLines = gridConfig && gridConfig.truncate && gridConfig.truncate.title
   const descLines = gridConfig && gridConfig.truncate && gridConfig.truncate.description

package/dist/theme/components/nav/branch-tag.tsx

@@ -1,7 +1,7 @@
-import type { SiteConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
+import type { CiderpressSiteBlock } from '../../hooks/use-ciderpress'
 import { useCiderpress } from '../../hooks/use-ciderpress'
 
 import './branch-tag.css'
@@ -12,7 +12,7 @@ declare const __CIDERPRESS_GIT_BRANCH__: string | undefined
 /**
  * Git branch tag — pill-shaped badge rendered via the `beforeNavMenu`
  * layout slot. Hidden when on default branches (`main` or `master`) or
- * when no `site.edit.repo` is configured. Uses the pixelarticons:git-branch
+ * when no `editLink.repo` is configured. Uses the pixelarticons:git-branch
  * icon.
  *
  * @returns React element, or `null` when on a default branch / unconfigured.
@@ -61,7 +61,7 @@ function resolveBranch(): string {
 }
 
 /**
- * Build a GitHub `/tree/<branch>` URL from the configured `site.edit.repo`.
+ * Build a GitHub `/tree/<branch>` URL from the configured `editLink.repo`.
  *
  * Accepts either a full URL (used as-is) or an `org/repo` slug
  * (prefixed with `https://github.com/`). Returns `null` when `repo` is
@@ -83,14 +83,14 @@ function buildBranchHref(params: {
 }
 
 /**
- * Pull the configured edit-repo slug off the site config, expressed
- * with explicit null checks rather than optional chaining.
+ * Pull the configured edit-repo slug off the serialised site block,
+ * expressed with explicit null checks rather than optional chaining.
  *
  * @private
- * @param site - The ciderpress site config (may be undefined).
+ * @param site - The runtime site block (may be undefined).
  * @returns The configured `edit.repo` value or `undefined`.
  */
-function resolveRepo(site: SiteConfig | undefined): string | undefined {
+function resolveRepo(site: CiderpressSiteBlock | undefined): string | undefined {
   if (site === undefined) {
     return undefined
   }

package/dist/theme/components/nav/ciderpress-header.css

@@ -76,7 +76,8 @@
   text-decoration: none;
 }
 
-.cp-header-logo > svg {
+.cp-header-logo > svg,
+.cp-header-logo > img {
   height: var(--cp-header-logo-height, 28px);
   width: auto;
 }

package/dist/theme/components/nav/ciderpress-header.tsx

@@ -2,19 +2,29 @@ import { clsx } from 'clsx'
 import type React from 'react'
 
 import { RouteLink } from '../../lib/route-link.tsx'
-import { CiderpressLogo } from '../shared/ciderpress-logo'
 import { CiderpressNavHamburger } from './ciderpress-nav-hamburger'
 import { CiderpressNavMenu } from './ciderpress-nav-menu'
 import type { CiderpressNavMenuItem } from './ciderpress-nav-menu'
 import { CiderpressNavSearch } from './ciderpress-nav-search'
 import { CiderpressNavSocialLinks } from './ciderpress-nav-social-links'
 import type { CiderpressSocialLink } from './ciderpress-nav-social-links'
+import { HeaderIcon } from './header-icon'
+import { HeaderLogo } from './header-logo'
 import { NavDivider } from './nav-divider'
 import { TopbarCTA } from './topbar-cta'
 import { VariantToggle } from './variant-toggle'
 
 import './ciderpress-header.css'
 
+/**
+ * Build-time flag: `true` when the active theme declares more than one
+ * variant AND `data-cp-variants` won't collapse the `<VariantToggle />`
+ * to `display: none`. Drives whether the trailing-cluster divider is
+ * rendered — when the toggle is hidden and neither socials nor CTA
+ * follow, the divider has nothing to separate and is omitted.
+ */
+declare const __CIDERPRESS_HAS_VARIANT_TOGGLE__: boolean
+
 /**
  * Props for the ciderpress site header.
  */
@@ -57,6 +67,18 @@ export interface CiderpressHeaderProps {
  * @returns Sticky header element
  */
 export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactElement {
+  // Dividers only render when they actually separate two visible
+  // clusters — orphan dividers (nothing on the right) are visually
+  // noisy. `<VariantToggle />` is hidden by CSS for single-variant
+  // themes; the build-time flag captures that decision so the React
+  // tree matches the painted output. The search/menu inner divider is
+  // unconditional — both clusters always render some chrome, and
+  // gating on `navItems.length` would flip after hydration (Rspress's
+  // nav data isn't populated at SSG) and produce a hydration warning.
+  const hasSocials = props.socialLinks.length > 0
+  const hasCta = props.topbarCta !== undefined
+  const hasTrailingCluster = __CIDERPRESS_HAS_VARIANT_TOGGLE__ || hasSocials || hasCta
+
   // Landing / home pages live inside a constrained max-width container;
   // doc pages stretch full-width (sidebar + article). The header mirrors
   // the content shell so it never floats outside the page rhythm.
@@ -78,7 +100,8 @@ export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactEleme
           topbarCta={props.topbarCta}
         />
         <RouteLink href="/" className="cp-header-logo" aria-label="Home">
-          <CiderpressLogo />
+          <HeaderIcon />
+          <HeaderLogo />
         </RouteLink>
 
         {/* Right cluster wrapper. Grows from a zero basis so its width
@@ -96,7 +119,7 @@ export function CiderpressHeader(props: CiderpressHeaderProps): React.ReactEleme
           <CiderpressNavMenu items={props.navItems} />
         </div>
 
-        <NavDivider />
+        {hasTrailingCluster && <NavDivider />}
         <VariantToggle />
         <CiderpressNavSocialLinks links={props.socialLinks} />
         {props.topbarCta !== undefined && (

package/dist/theme/components/nav/ciderpress-nav-social-links.tsx

@@ -6,13 +6,15 @@ import { Icon } from '../shared/icon.tsx'
 import './ciderpress-nav-social-links.css'
 
 /**
- * Single social-link entry — matches the shape of `socialLinks` in
- * `ciderpress.config.ts`.
+ * Single social-link entry — matches the serialised `socials` shape
+ * written into `themeConfig.socialLinks` by `packages/ui/src/config.ts`.
+ *
+ * The Rspress `mode` / `content` discriminator was killed in the
+ * `rc.4` API overhaul; every link is now a plain anchor.
  */
 export interface CiderpressSocialLink {
   readonly icon: string
-  readonly mode: string
-  readonly content: string
+  readonly url: string
   readonly label?: string
 }
 
@@ -39,7 +41,7 @@ const ICON_MAP: Readonly<Record<string, string>> = Object.freeze({
  * Renders the configured social links as a cluster of icon buttons in
  * the topbar. Returns `null` when no links are configured.
  *
- * @param props - List of social links from `site.socialLinks`
+ * @param props - List of social links from `site.socials`
  * @returns Cluster of icon links, or `null`
  */
 export function CiderpressNavSocialLinks(
@@ -50,7 +52,7 @@ export function CiderpressNavSocialLinks(
   }
 
   const safeLinks = props.links
-    .map((link) => ({ link, href: safeUrl(link.content) }))
+    .map((link) => ({ link, href: safeUrl(link.url) }))
     .filter((entry): entry is { readonly link: CiderpressSocialLink; readonly href: string } => {
       if (entry.href === null) {
         return false
@@ -66,7 +68,7 @@ export function CiderpressNavSocialLinks(
     <div className="cp-nav-social">
       {safeLinks.map(({ link, href }) => (
         <a
-          key={link.content}
+          key={link.url}
           href={href}
           target="_blank"
           rel="noopener noreferrer"

package/dist/theme/components/nav/floating-branch-indicator.tsx

@@ -1,7 +1,7 @@
-import type { SiteConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
+import type { CiderpressSiteBlock } from '../../hooks/use-ciderpress'
 import { useCiderpress } from '../../hooks/use-ciderpress'
 
 import './floating-branch-indicator.css'
@@ -15,7 +15,7 @@ declare const __CIDERPRESS_GIT_BRANCH__: string | undefined
  * the branch name. Click anywhere on the pill opens the branch on GitHub.
  *
  * Hidden when on default branches (`main` / `master`), when the
- * build-time branch global is undefined, or when `site.edit.repo` is
+ * build-time branch global is undefined, or when `editLink.repo` is
  * not configured.
  *
  * @returns React element or null when hidden
@@ -69,7 +69,7 @@ function resolveBranch(): string {
 }
 
 /**
- * Build a GitHub `/tree/<branch>` URL from the configured `site.edit.repo`.
+ * Build a GitHub `/tree/<branch>` URL from the configured `editLink.repo`.
  *
  * Accepts either a full URL (used as-is) or an `org/repo` slug
  * (prefixed with `https://github.com/`). Returns `null` when `repo` is
@@ -91,14 +91,14 @@ function buildBranchHref(params: {
 }
 
 /**
- * Pull the configured edit-repo slug off the site config, expressed
- * with explicit null checks rather than optional chaining.
+ * Pull the configured edit-repo slug off the serialised site block,
+ * expressed with explicit null checks rather than optional chaining.
  *
  * @private
- * @param site - The ciderpress site config (may be undefined).
+ * @param site - The runtime site block (may be undefined).
  * @returns The configured `edit.repo` value or `undefined`.
  */
-function resolveRepo(site: SiteConfig | undefined): string | undefined {
+function resolveRepo(site: CiderpressSiteBlock | undefined): string | undefined {
   if (site === undefined) {
     return undefined
   }

package/dist/theme/components/nav/header-icon.css

@@ -0,0 +1,24 @@
+/**
+ * Small brand chip rendered immediately before `<HeaderLogo />` inside
+ * `cp-header-logo`. Sized to match `--cp-header-icon-size` (default
+ * 28px — same as the logo height token) so the two slots line up
+ * vertically by default. Themes can override either token to break
+ * the lockstep.
+ */
+
+.cp-header-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  height: var(--cp-header-icon-size, var(--cp-header-logo-height, 28px));
+  width: var(--cp-header-icon-size, var(--cp-header-logo-height, 28px));
+  margin-right: var(--cp-header-icon-gap, 8px);
+  color: var(--cp-header-icon-color, currentColor);
+}
+
+.cp-header-icon > svg,
+.cp-header-icon__img {
+  height: 100%;
+  width: 100%;
+  display: block;
+}

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),
+    },
+  }
+}