@pilotiq/pilotiq 0.1.0

package/src/theme/presets.ts

@@ -0,0 +1,135 @@
+import { colors } from './colors.js'
+import type { PresetDefinition, StylePreset, ThemeFonts, RadiusPreset, SpacingPreset } from './types.js'
+
+// Pure white for surfaces that sit ABOVE the sidebar (`--background`, `--card`,
+// `--popover`). The sidebar tracks `--muted` (one step darker than white) so
+// the sidebar reads as a recessed surface against the bright content area.
+const WHITE = 'oklch(1 0 0)'
+
+// ─── Shadcn neutral default ────────────────────────────────
+// Exact mapping of `https://ui.shadcn.com/themes` neutral defaults onto our
+// color tokens. Both Vega (the seeded default) and the six placeholder
+// presets share this baseline; differentiation between styles comes later.
+
+// Note: --primary, --ring, --sidebar-primary*, and --chart-1..5 are
+// intentionally omitted here — the theme-color and chart-color resolver
+// layers in `resolve.ts` always apply (defaulting to the `'base'` sentinel),
+// so anything we'd put for those tokens here would be unconditionally
+// overridden. Keeping them out makes the override chain easier to reason
+// about.
+const shadcnNeutral: PresetDefinition = {
+  light: {
+    '--background':                   WHITE,
+    '--foreground':                   colors.neutral[950],
+    '--card':                         WHITE,
+    '--card-foreground':              colors.neutral[950],
+    '--popover':                      WHITE,
+    '--popover-foreground':           colors.neutral[950],
+    '--secondary':                    colors.neutral[100],
+    '--secondary-foreground':         colors.neutral[900],
+    '--muted':                        colors.neutral[100],
+    '--muted-foreground':             colors.neutral[500],
+    '--accent':                       colors.neutral[100],
+    '--accent-foreground':            colors.neutral[900],
+    '--destructive':                  colors.red[600],
+    // shadcn ships destructive-foreground identical to destructive in light
+    // mode — preserves the same red token for both fg and bg surfaces.
+    '--destructive-foreground':       colors.red[600],
+    '--border':                       colors.neutral[200],
+    '--input':                        colors.neutral[200],
+    '--sidebar':                      'var(--muted)',
+    '--sidebar-foreground':           colors.neutral[950],
+    '--sidebar-accent':               colors.neutral[200],
+    '--sidebar-accent-foreground':    colors.neutral[900],
+    '--sidebar-border':               colors.neutral[200],
+  },
+  dark: {
+    '--background':                   colors.neutral[950],
+    '--foreground':                   colors.neutral[50],
+    '--card':                         colors.neutral[950],
+    '--card-foreground':              colors.neutral[50],
+    '--popover':                      colors.neutral[950],
+    '--popover-foreground':           colors.neutral[50],
+    '--secondary':                    colors.neutral[800],
+    '--secondary-foreground':         colors.neutral[50],
+    '--muted':                        colors.neutral[800],
+    '--muted-foreground':             colors.neutral[400],
+    '--accent':                       colors.neutral[800],
+    '--accent-foreground':            colors.neutral[50],
+    '--destructive':                  colors.red[900],
+    '--destructive-foreground':       colors.red[500],
+    '--border':                       colors.neutral[800],
+    '--input':                        colors.neutral[800],
+    '--sidebar':                      'var(--muted)',
+    '--sidebar-foreground':           colors.neutral[50],
+    '--sidebar-accent':               colors.neutral[700],
+    '--sidebar-accent-foreground':    colors.neutral[50],
+    '--sidebar-border':               colors.neutral[700],
+  },
+}
+
+// All seven styles share the shadcn baseline for now. Per-style personality
+// (radius, token relationships) lands in a follow-up pass.
+export const presets: Record<StylePreset, PresetDefinition> = {
+  vega: shadcnNeutral,
+  nova: shadcnNeutral,
+  maia: shadcnNeutral,
+  lyra: shadcnNeutral,
+  mira: shadcnNeutral,
+  luma: shadcnNeutral,
+  sera: shadcnNeutral,
+}
+
+/**
+ * Per-style default font pairing. Picking a Style updates the Heading + Font
+ * pickers automatically (unless the user has explicitly overridden them via
+ * `Pilotiq.theme({ fonts: {...} })` or the editor).
+ *
+ * Currently confirmed:
+ *  - vega → Inter
+ *  - nova → Geist
+ *
+ * Placeholder for the others (Inter); replace once the design system
+ * specifies a font per style.
+ */
+export const PRESET_FONTS: Record<StylePreset, Required<ThemeFonts>> = {
+  vega: { heading: 'Inter',            body: 'Inter'           },
+  nova: { heading: 'Geist',            body: 'Geist'           },
+  maia: { heading: 'Figtree',          body: 'Figtree'         },
+  lyra: { heading: 'JetBrains Mono',   body: 'JetBrains Mono'  },
+  mira: { heading: 'Inter',            body: 'Inter'           },
+  luma: { heading: 'Inter',            body: 'Inter'           },
+  sera: { heading: 'Playfair Display', body: 'Noto Sans'       },
+}
+
+/**
+ * Per-style default radius. The picker's "Default" option resolves through
+ * this map: with Style = Maia + Radius = Default, the actual rendered radius
+ * is `large` (1rem). Picking an explicit radius (e.g. "Small") still
+ * overrides this default.
+ */
+export const PRESET_RADIUS: Record<StylePreset, RadiusPreset> = {
+  vega: 'medium',
+  nova: 'medium',
+  maia: 'large',
+  lyra: 'none',
+  mira: 'medium',
+  luma: 'xlarge',
+  sera: 'none',
+}
+
+/**
+ * Per-style default spacing density. The picker's "Default" option resolves
+ * through this map. Mirrors shadcn/ui/create's per-preset density behavior:
+ * Vega / Nova / Maia / Luma / Sera lean comfortable; Lyra stays at default;
+ * Mira goes compact.
+ */
+export const PRESET_SPACING: Record<StylePreset, SpacingPreset> = {
+  vega: 'comfortable',
+  nova: 'compact',
+  maia: 'comfortable',
+  lyra: 'default',
+  mira: 'compact',
+  luma: 'comfortable',
+  sera: 'comfortable',
+}

package/src/theme/radius.ts

@@ -0,0 +1,18 @@
+import type { RadiusPreset } from './types.js'
+
+/**
+ * Maps radius preset names to CSS values.
+ *
+ * `'default'` is a sentinel synonym for `'medium'` (10px) — both render the
+ * same radius. The picker shows it as the first option and as the "no
+ * explicit choice" label so users see "Default" rather than a specific size
+ * when they haven't overridden anything.
+ */
+export const radiusMap: Record<RadiusPreset, string> = {
+  default: '0.625rem',
+  none:    '0px',
+  small:   '0.25rem',
+  medium:  '0.625rem',
+  large:   '1rem',
+  xlarge:  '1.5rem',
+}

package/src/theme/resolve.test.ts

@@ -0,0 +1,238 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveTheme } from './resolve.js'
+import { baseColors } from './base-colors.js'
+import { colors } from './colors.js'
+import { PRESET_FONTS, PRESET_RADIUS, PRESET_SPACING } from './presets.js'
+import { radiusMap } from './radius.js'
+import { spacingMap } from './spacing.js'
+
+describe('resolveTheme', () => {
+  // ─── Preset layering ─────────────────────────────────────
+
+  describe('preset', () => {
+    it('defaults to vega when not specified', () => {
+      const empty = resolveTheme({})
+      const explicit = resolveTheme({ preset: 'vega' })
+      assert.deepEqual(empty.light, explicit.light)
+      assert.deepEqual(empty.dark, explicit.dark)
+    })
+
+    it('falls back to vega for unknown preset values (defensive)', () => {
+      // Cast to bypass type — defensive code in resolve.ts handles bad input
+      // from deserialized DB rows.
+      const bogus = resolveTheme({ preset: 'definitely-not-a-preset' as never })
+      const vega  = resolveTheme({ preset: 'vega' })
+      assert.deepEqual(bogus.light, vega.light)
+    })
+  })
+
+  // ─── Base color defaulting (the recent regression) ───────
+
+  describe('base color', () => {
+    it('default state matches explicit baseColor: neutral', () => {
+      // Regression guard: previously, empty config skipped the baseColor
+      // overlay entirely, leaving the preset's hardcoded WHITE surfaces.
+      // Picking "Neutral" applied neutral[50] surfaces. The two paths
+      // produced different output — this asserts they now agree.
+      const fromDefault  = resolveTheme({})
+      const fromExplicit = resolveTheme({ baseColor: 'neutral' })
+      assert.deepEqual(fromDefault.light, fromExplicit.light)
+      assert.deepEqual(fromDefault.dark,  fromExplicit.dark)
+    })
+
+    it('applies stone tokens when baseColor: stone', () => {
+      const stone = resolveTheme({ baseColor: 'stone' })
+      // baseColors.stone uses stone[50] for --background (light mode).
+      assert.equal(stone.light['--background'], baseColors.stone.light['--background'])
+      // And stone[800] for --muted (dark mode).
+      assert.equal(stone.dark['--muted'], baseColors.stone.dark['--muted'])
+    })
+
+    it('does not leak stone tokens when baseColor is neutral', () => {
+      const neutral = resolveTheme({ baseColor: 'neutral' })
+      assert.notEqual(neutral.light['--background'], baseColors.stone.light['--background'])
+    })
+  })
+
+  // ─── Theme color resolution ──────────────────────────────
+
+  describe('theme color', () => {
+    it("'base' sentinel uses the resolved base color scale", () => {
+      // With baseColor: 'stone' and themeColor: 'base', --primary should be
+      // stone[900] in light (the strongest in-scale contrast). The 'base'
+      // path uses isBase=true, which picks scale[900] for light --primary.
+      const stoneBase = resolveTheme({ baseColor: 'stone', themeColor: 'base' })
+      assert.equal(stoneBase.light['--primary'], colors.stone[900])
+      assert.equal(stoneBase.dark['--primary'],  colors.stone[50])
+    })
+
+    it("'base' sentinel falls back to neutral when no baseColor set", () => {
+      const fallback = resolveTheme({ themeColor: 'base' })
+      assert.equal(fallback.light['--primary'], colors.neutral[900])
+    })
+
+    it('hue values override --primary with that hue', () => {
+      const blue = resolveTheme({ themeColor: 'blue' })
+      // Non-base hue uses scale[600] in BOTH light and dark for brand
+      // consistency across modes.
+      assert.equal(blue.light['--primary'], colors.blue[600])
+      assert.equal(blue.dark['--primary'],  colors.blue[600])
+    })
+
+    it('defaults to base sentinel when not specified', () => {
+      const noTheme = resolveTheme({ baseColor: 'stone' })
+      const explicitBase = resolveTheme({ baseColor: 'stone', themeColor: 'base' })
+      assert.equal(noTheme.light['--primary'], explicitBase.light['--primary'])
+    })
+  })
+
+  // ─── Chart color resolution ──────────────────────────────
+
+  describe('chart color', () => {
+    it("'base' sentinel uses the resolved base color scale for --chart-1..5", () => {
+      const stoneChart = resolveTheme({ baseColor: 'stone', chartColor: 'base' })
+      // All five chart vars should be defined and pull from the stone scale.
+      for (const i of [1, 2, 3, 4, 5]) {
+        const value = stoneChart.light[`--chart-${i}`]
+        assert.ok(value, `--chart-${i} should be set`)
+        // Chart vars derived from a single-hue ramp should appear in the
+        // stone scale's value set.
+        const stoneValues = Object.values(colors.stone)
+        assert.ok(stoneValues.includes(value!), `--chart-${i} (${value}) should come from the stone scale`)
+      }
+    })
+
+    it('hue value overrides chart palette', () => {
+      const a = resolveTheme({ chartColor: 'blue' })
+      const b = resolveTheme({ chartColor: 'red' })
+      assert.notEqual(a.light['--chart-1'], b.light['--chart-1'])
+    })
+  })
+
+  // ─── Radius resolution ───────────────────────────────────
+
+  describe('radius', () => {
+    it("'default' falls through to PRESET_RADIUS[preset]", () => {
+      // Maia's default radius is 'large' per PRESET_RADIUS.
+      const maia = resolveTheme({ preset: 'maia', radius: 'default' })
+      assert.equal(maia.radius, radiusMap[PRESET_RADIUS.maia])
+      assert.equal(maia.radius, radiusMap.large)
+    })
+
+    it('undefined radius falls through to PRESET_RADIUS[preset]', () => {
+      // Same path as 'default' — both resolve through PRESET_RADIUS.
+      const luma = resolveTheme({ preset: 'luma' })
+      assert.equal(luma.radius, radiusMap[PRESET_RADIUS.luma])
+      assert.equal(luma.radius, radiusMap.xlarge)
+    })
+
+    it('explicit radius wins over preset default', () => {
+      // Maia's preset radius is 'large', but explicit 'small' should win.
+      const maia = resolveTheme({ preset: 'maia', radius: 'small' })
+      assert.equal(maia.radius, radiusMap.small)
+    })
+  })
+
+  // ─── Spacing resolution ──────────────────────────────────
+
+  describe('spacing', () => {
+    it("'default' falls through to PRESET_SPACING[preset]", () => {
+      // Mira's default spacing is 'compact'.
+      const mira = resolveTheme({ preset: 'mira', spacing: 'default' })
+      assert.equal(mira.spacing, spacingMap[PRESET_SPACING.mira])
+      assert.equal(mira.spacing, spacingMap.compact)
+    })
+
+    it('undefined spacing falls through to PRESET_SPACING[preset]', () => {
+      const vega = resolveTheme({ preset: 'vega' })
+      assert.equal(vega.spacing, spacingMap[PRESET_SPACING.vega])
+      assert.equal(vega.spacing, spacingMap.comfortable)
+    })
+
+    it('explicit spacing wins over preset default', () => {
+      // Mira's preset spacing is 'compact', but explicit 'comfortable' wins.
+      const mira = resolveTheme({ preset: 'mira', spacing: 'comfortable' })
+      assert.equal(mira.spacing, spacingMap.comfortable)
+    })
+  })
+
+  // ─── Font resolution ─────────────────────────────────────
+
+  describe('fonts', () => {
+    it('falls through to PRESET_FONTS[preset] when not set', () => {
+      const sera = resolveTheme({ preset: 'sera' })
+      assert.equal(sera.fonts?.heading, PRESET_FONTS.sera.heading)
+      assert.equal(sera.fonts?.body,    PRESET_FONTS.sera.body)
+      assert.equal(sera.fonts?.heading, 'Playfair Display')
+      assert.equal(sera.fonts?.body,    'Noto Sans')
+    })
+
+    it('field-level fallback — body override does not drop heading default', () => {
+      // Regression guard: if resolveTheme used object-level `??`, supplying
+      // only `fonts.body` would drop the heading default. Field-level merge
+      // keeps both pieces independently overridable.
+      const sera = resolveTheme({ preset: 'sera', fonts: { body: 'Inter' } })
+      assert.equal(sera.fonts?.body,    'Inter')
+      assert.equal(sera.fonts?.heading, 'Playfair Display') // preset default
+    })
+
+    it('emits fontFamily with quoted-name fallback chain', () => {
+      const vega = resolveTheme({ preset: 'vega' })
+      assert.match(vega.fontFamily?.heading ?? '', /^'Inter', system-ui, sans-serif$/)
+      assert.match(vega.fontFamily?.body ?? '',    /^'Inter', system-ui, sans-serif$/)
+    })
+  })
+
+  // ─── cssVariables escape hatch ───────────────────────────
+
+  describe('cssVariables override', () => {
+    it('overrides preset, base, theme, and chart layers', () => {
+      const result = resolveTheme({
+        preset:    'vega',
+        baseColor: 'stone',
+        themeColor: 'blue',
+        chartColor: 'red',
+        cssVariables: {
+          light: { '--primary': 'oklch(0.5 0.2 200)', '--background': 'rebeccapurple' },
+          dark:  { '--primary': 'oklch(0.6 0.2 200)' },
+        },
+      })
+      // Wins over themeColor (blue would have been set first).
+      assert.equal(result.light['--primary'], 'oklch(0.5 0.2 200)')
+      // Wins over baseColor stone's --background.
+      assert.equal(result.light['--background'], 'rebeccapurple')
+      // Dark override applied independently.
+      assert.equal(result.dark['--primary'], 'oklch(0.6 0.2 200)')
+    })
+
+    it('does not leak light overrides into dark or vice versa', () => {
+      const result = resolveTheme({
+        cssVariables: { light: { '--custom': 'x' } },
+      })
+      assert.equal(result.light['--custom'], 'x')
+      assert.equal(result.dark['--custom'],  undefined)
+    })
+  })
+
+  // ─── Misc result shape ───────────────────────────────────
+
+  describe('result shape', () => {
+    it('defaults iconLibrary to lucide', () => {
+      assert.equal(resolveTheme({}).iconLibrary, 'lucide')
+    })
+
+    it('respects iconLibrary when set', () => {
+      assert.equal(resolveTheme({ iconLibrary: 'phosphor' }).iconLibrary, 'phosphor')
+    })
+
+    it('always emits radius and spacing as concrete CSS strings', () => {
+      const r = resolveTheme({})
+      assert.equal(typeof r.radius,  'string')
+      assert.equal(typeof r.spacing, 'string')
+      assert.match(r.radius,  /rem$|px$/)
+      assert.match(r.spacing, /rem$/)
+    })
+  })
+})

package/src/theme/resolve.ts

@@ -0,0 +1,96 @@
+import type { ThemeConfig, ThemeMeta, BaseColor } from './types.js'
+import { presets, PRESET_FONTS, PRESET_RADIUS, PRESET_SPACING } from './presets.js'
+import { baseColors } from './base-colors.js'
+import { resolveThemeColor } from './theme-colors.js'
+import { resolveChartColor } from './chart-colors.js'
+import { radiusMap } from './radius.js'
+import { spacingMap } from './spacing.js'
+
+/**
+ * Resolves a user-facing `ThemeConfig` into a serializable `ThemeMeta`.
+ *
+ * Layering order (each overrides the previous):
+ * 1. Preset (full variable set)
+ * 2. Base color (gray/neutral overrides)
+ * 3. Theme color (primary/ring overrides — `'base'` derives from base color)
+ * 4. Chart color (chart-1..5 ramp — `'base'` derives from base color)
+ * 5. Raw cssVariables escape hatch
+ */
+export function resolveTheme(config: ThemeConfig): ThemeMeta {
+  // 1. Start with preset. Validate the name once so every downstream
+  //    preset-keyed lookup (PRESET_RADIUS, PRESET_SPACING, PRESET_FONTS) is
+  //    safe — bogus names from deserialized data fall through to 'vega'
+  //    instead of crashing with "Cannot read properties of undefined".
+  const requestedName = config.preset ?? 'vega'
+  const presetName = presets[requestedName] ? requestedName : 'vega'
+  const preset = presets[presetName]
+  const light = { ...preset.light }
+  const dark  = { ...preset.dark }
+
+  // 2. Apply base color — always layered, defaulting to neutral so the
+  //    "default state" and an explicit `baseColor: 'neutral'` resolve to the
+  //    same tokens. Without this, the preset's hardcoded surface values
+  //    (e.g. WHITE for --background) would leak through whenever no base
+  //    color is selected, making the picker show "Neutral" while the actual
+  //    rendered colors didn't match a neutral selection.
+  const effectiveBase: BaseColor = config.baseColor ?? 'neutral'
+  const base = baseColors[effectiveBase]
+  Object.assign(light, base.light)
+  Object.assign(dark, base.dark)
+
+  // 3 + 4. Always apply theme + chart color (default to `'base'` sentinel).
+  // We default these so the editor's trigger ("Theme: Neutral", "Chart: Neutral")
+  // matches what the resolver actually renders. Otherwise the trigger would
+  // show "Neutral" but the preset's hardcoded primary/chart values would
+  // still leak through.
+  const themeColor = config.themeColor ?? 'base'
+  const tc = resolveThemeColor(themeColor, effectiveBase)
+  Object.assign(light, tc.light)
+  Object.assign(dark, tc.dark)
+
+  const chartColor = config.chartColor ?? 'base'
+  const cc = resolveChartColor(chartColor, effectiveBase)
+  Object.assign(light, cc.light)
+  Object.assign(dark, cc.dark)
+
+  // 5. Raw CSS variable overrides — highest priority escape hatch
+  if (config.cssVariables?.light) Object.assign(light, config.cssVariables.light)
+  if (config.cssVariables?.dark)  Object.assign(dark, config.cssVariables.dark)
+
+  // Resolve radius — `'default'` (or undefined) routes through PRESET_RADIUS
+  // so each style can pick its own baseline (e.g. Maia = large). An explicit
+  // pick (none/small/medium/large) always wins over the preset default.
+  const isExplicit = config.radius && config.radius !== 'default'
+  const radiusKey = isExplicit ? config.radius! : PRESET_RADIUS[presetName]
+  const radius = radiusMap[radiusKey]
+
+  // Resolve spacing density — same pattern as radius. Drives `--spacing`,
+  // which Tailwind v4 multiplies into every `p-*` / `gap-*` / `m-*` utility.
+  const isSpacingExplicit = config.spacing && config.spacing !== 'default'
+  const spacingKey = isSpacingExplicit ? config.spacing! : PRESET_SPACING[presetName]
+  const spacing = spacingMap[spacingKey]
+
+  // Resolve fonts — fall through to the per-style font pairing in PRESET_FONTS.
+  // Field-level fallback (not object-level ??) so `fonts: { body: '...' }`
+  // doesn't accidentally drop the heading default.
+  const presetFonts = PRESET_FONTS[presetName]
+  const fonts = {
+    body:    config.fonts?.body    ?? presetFonts.body,
+    heading: config.fonts?.heading ?? presetFonts.heading,
+  }
+  const fontFamily: { heading?: string; body?: string } = {}
+  if (fonts.heading) fontFamily.heading = `'${fonts.heading}', system-ui, sans-serif`
+  if (fonts.body)    fontFamily.body    = `'${fonts.body}', system-ui, sans-serif`
+
+  const result: ThemeMeta = {
+    light,
+    dark,
+    radius,
+    spacing,
+    iconLibrary: config.iconLibrary ?? 'lucide',
+  }
+  result.fonts = fonts
+  if (Object.keys(fontFamily).length > 0) result.fontFamily = fontFamily
+
+  return result
+}

package/src/theme/spacing.ts

@@ -0,0 +1,18 @@
+import type { SpacingPreset } from './types.js'
+
+/**
+ * Maps spacing density presets to Tailwind v4 `--spacing` values.
+ *
+ * Tailwind compiles every `p-*`, `gap-*`, `m-*` utility as
+ * `calc(var(--spacing) * N)`, so swapping this single token uniformly tightens
+ * or loosens every gap and padding in the panel — no per-component edits.
+ *
+ * `'default'` is the sentinel resolver; the picker shows it as the first
+ * option and falls through to `PRESET_SPACING[preset]`. `0.25rem` matches
+ * Tailwind's stock value, kept as `default`'s rendered fallback for parity.
+ */
+export const spacingMap: Record<SpacingPreset, string> = {
+  default:     '0.25rem',
+  compact:     '0.2rem',
+  comfortable: '0.3rem',
+}

package/src/theme/theme-colors.ts

@@ -0,0 +1,88 @@
+import { colors, HUE_NAMES, type ColorScale } from './colors.js'
+import type { BaseColor, HueColor, ThemeColor, PresetDefinition } from './types.js'
+import { parseSeedToScale } from './generate-scale.js'
+
+/**
+ * Theme (primary) color resolution.
+ *
+ * The theme color drives `--primary`, `--primary-foreground`, `--ring`, and
+ * the matching sidebar variants. Built from a `ColorScale` so adding a new
+ * hue is just adding an entry to `colors.ts`.
+ *
+ * The `'base'` sentinel means "use the current base color" — resolution
+ * pulls the matching scale from `colors[baseColor]` at call time.
+ *
+ * Custom seeds (raw hex / oklch strings outside the `HueColor` union) are
+ * parsed into a synthetic 50…950 scale via `parseSeedToScale`.
+ */
+
+/**
+ * Build the primary/ring overrides for a given color scale.
+ *
+ * `isBase` toggles between two strategies:
+ *  - **base sentinel** (e.g. Theme = "Neutral"): use the strongest contrast
+ *    *within the same scale* — primary is scale[900] in light, scale[50] in
+ *    dark. Matches shadcn's neutral theme behavior (very dark/light primary).
+ *  - **hue** (e.g. Theme = "Blue"): use scale[600] in BOTH light and dark so
+ *    the brand color stays consistent across modes (instead of lifting to
+ *    scale[400] in dark, which dilutes brand identity). Foreground stays the
+ *    near-white neutral[50] for AA contrast against the saturated mid-tone.
+ */
+function buildTheme(scale: ColorScale, isBase = false): PresetDefinition {
+  if (isBase) {
+    return {
+      light: {
+        '--primary':                      scale[900],
+        '--primary-foreground':           scale[50],
+        '--ring':                         scale[400],
+        '--sidebar-primary':              scale[900],
+        '--sidebar-primary-foreground':   scale[50],
+        '--sidebar-ring':                 scale[400],
+      },
+      dark: {
+        '--primary':                      scale[50],
+        '--primary-foreground':           scale[900],
+        '--ring':                         scale[600],
+        '--sidebar-primary':              scale[50],
+        '--sidebar-primary-foreground':   scale[900],
+        '--sidebar-ring':                 scale[600],
+      },
+    }
+  }
+  return {
+    light: {
+      '--primary':                      scale[600],
+      '--primary-foreground':           colors.neutral[50],
+      '--ring':                         scale[600],
+      '--sidebar-primary':              scale[600],
+      '--sidebar-primary-foreground':   colors.neutral[50],
+      '--sidebar-ring':                 scale[600],
+    },
+    dark: {
+      '--primary':                      scale[600],
+      '--primary-foreground':           colors.neutral[50],
+      '--ring':                         scale[600],
+      '--sidebar-primary':              scale[600],
+      '--sidebar-primary-foreground':   colors.neutral[50],
+      '--sidebar-ring':                 scale[600],
+    },
+  }
+}
+
+const themeColorMap: Record<HueColor, PresetDefinition> = Object.fromEntries(
+  HUE_NAMES.map(name => [name, buildTheme(colors[name])]),
+) as Record<HueColor, PresetDefinition>
+
+/**
+ * Resolve a theme color value to its CSS variable overrides.
+ *
+ * @param themeColor  selected value — `'base'`, a known hue, or a raw seed string
+ * @param baseColor   current base color (used to resolve `'base'` sentinel)
+ */
+export function resolveThemeColor(themeColor: ThemeColor, baseColor: BaseColor): PresetDefinition {
+  if (themeColor === 'base') return buildTheme(colors[baseColor], true)
+  if (themeColor in themeColorMap) return themeColorMap[themeColor as HueColor]
+  // Custom seed — parse and synthesize a scale.
+  const synthetic = parseSeedToScale(themeColor)
+  return synthetic ? buildTheme(synthetic) : buildTheme(colors[baseColor], true)
+}