@adea-ai/ui 0.128.1 → 0.128.3

package/src/lib/theme-defaults.generated.ts

@@ -0,0 +1,319 @@
+/*
+ * GENERATED by scripts/build-theme-defaults.ts from @adea-ai/themes. Do not edit.
+ * Run `bun run theme:defaults` after the catalogue changes;
+ * tests/theme-defaults.test.ts fails when this file is stale.
+ */
+import type { AccentPreset } from '@adea-ai/themes'
+import type { ThemeEditorPalette, ThemeVariant } from './themes'
+
+/** Every catalogue theme id and its appearance, in catalogue order. */
+export const THEME_INDEX: readonly (readonly [id: string, appearance: 'light' | 'dark'])[] = [
+  ['adea-dark', 'dark'],
+  ['adea-dark-colorblind', 'dark'],
+  ['adea-dark-high-contrast', 'dark'],
+  ['adea-light', 'light'],
+  ['adea-light-colorblind', 'light'],
+  ['adea-light-high-contrast', 'light'],
+  ['aardvark-blue', 'dark'],
+  ['aardvark-ink', 'dark'],
+  ['ayu', 'dark'],
+  ['ayu-light', 'light'],
+  ['ayu-mirage', 'dark'],
+  ['catppuccin-frappe', 'dark'],
+  ['catppuccin-latte', 'light'],
+  ['catppuccin-macchiato', 'dark'],
+  ['catppuccin-mocha', 'dark'],
+  ['dracula', 'dark'],
+  ['everforest-dark', 'dark'],
+  ['everforest-light', 'light'],
+  ['gruvbox-dark', 'dark'],
+  ['gruvbox-light', 'light'],
+  ['kanagawa', 'dark'],
+  ['monokai', 'dark'],
+  ['nord', 'dark'],
+  ['nord-light', 'light'],
+  ['one-dark', 'dark'],
+  ['rosepine', 'dark'],
+  ['rosepine-dawn', 'light'],
+  ['rosepine-moon', 'dark'],
+  ['solarized-dark', 'dark'],
+  ['solarized-light', 'light'],
+  ['tokyonight-day', 'light'],
+  ['tokyonight-night', 'dark'],
+  ['tokyonight-storm', 'dark'],
+  ['vesper', 'dark'],
+]
+
+/** The default light and dark themes, complete. */
+export const DEFAULT_VARIANTS: Readonly<Record<'adea-light' | 'adea-dark', ThemeVariant>> = {
+  'adea-light': {
+    id: 'adea-light',
+    family: 'adea',
+    familyLabel: 'Adea',
+    label: 'Light',
+    appearance: 'light',
+    description:
+      "The default light theme: GitHub's own white canvas carrying the dark theme's hues, transposed to survive on paper, with the family violet accent.",
+    colors: {
+      background: 'oklch(1 0 0)',
+      foreground: 'oklch(0.2542 0.0111 254.04)',
+      card: 'oklch(0.965 0 0)',
+      cardForeground: 'oklch(0.2542 0.0111 254.04)',
+      popover: 'oklch(0.935 0 0)',
+      popoverForeground: 'oklch(0.2542 0.0111 254.04)',
+      primary: 'oklch(0.5143 0.1668 301.69)',
+      primaryForeground: 'oklch(1 0 0)',
+      secondary: 'oklch(0.965 0 0)',
+      secondaryForeground: 'oklch(0.2542 0.0111 254.04)',
+      muted: 'oklch(0.965 0 0)',
+      mutedForeground: 'oklch(0.4929 0.0076 254.04)',
+      accent: 'oklch(0.9 0 0)',
+      accentForeground: 'oklch(0.2542 0.0111 254.04)',
+      destructive: 'oklch(0.5165 0.1626 25.78)',
+      destructiveForeground: 'oklch(1 0 0)',
+      destructiveSubtle: 'oklch(0.9323 0.0228 25.78)',
+      destructiveAction: 'oklch(0.5165 0.1626 25.78)',
+      destructiveActionForeground: 'oklch(1 0 0)',
+      success: 'oklch(0.4771 0.1809 145.62)',
+      successForeground: 'oklch(1 0 0)',
+      successSubtle: 'oklch(0.9268 0.0253 145.62)',
+      warning: 'oklch(0.5016 0.1401 79.91)',
+      warningForeground: 'oklch(1 0 0)',
+      warningSubtle: 'oklch(0.9302 0.0196 79.91)',
+      info: 'oklch(0.5375 0.1155 202.14)',
+      infoForeground: 'oklch(1 0 0)',
+      infoSubtle: 'oklch(0.9353 0.0162 202.14)',
+      border: 'oklch(0.85 0 0)',
+      input: 'oklch(0.85 0 0)',
+      ring: 'oklch(0.5143 0.1668 301.69)',
+      sidebar: 'oklch(0.965 0 0)',
+      sidebarForeground: 'oklch(0.2542 0.0111 254.04)',
+      sidebarAccent: 'oklch(0.9 0 0)',
+      sidebarBorder: 'oklch(0.85 0 0)',
+      sidebarMutedForeground: 'oklch(0.4929 0.0076 254.04)',
+    },
+    terminal: {
+      background: 'oklch(1 0 0)',
+      foreground: 'oklch(0.2542 0.0111 254.04)',
+      cursor: 'oklch(0.5399 0.1906 257.48)',
+      selection: 'oklch(0.2542 0.0111 254.04)',
+      black: 'oklch(0.2785 0.0132 253.04)',
+      red: 'oklch(0.5165 0.1626 25.78)',
+      green: 'oklch(0.4771 0.1809 145.62)',
+      yellow: 'oklch(0.5016 0.1401 79.91)',
+      blue: 'oklch(0.4973 0.1518 253.31)',
+      magenta: 'oklch(0.5143 0.1668 301.69)',
+      cyan: 'oklch(0.5375 0.1155 202.14)',
+      white: 'oklch(0.5651 0.0189 250.97)',
+      brightBlack: 'oklch(0.4849 0.0196 251.02)',
+      brightRed: 'oklch(0.5834 0.1134 25.81)',
+      brightGreen: 'oklch(0.5537 0.188 145.48)',
+      brightYellow: 'oklch(0.5724 0.1386 85.24)',
+      brightBlue: 'oklch(0.5677 0.1153 246.66)',
+      brightMagenta: 'oklch(0.5825 0.1275 305.86)',
+      brightCyan: 'oklch(0.5856 0.1107 201.78)',
+      brightWhite: 'oklch(0.6658 0.0181 250.92)',
+    },
+    editor: {
+      keyword: 'oklch(0.5143 0.1668 301.69)',
+      string: 'oklch(0.4771 0.1809 145.62)',
+      number: 'oklch(0.5016 0.1401 79.91)',
+      comment: 'oklch(0.4849 0.0196 251.02)',
+      function: 'oklch(0.4973 0.1518 253.31)',
+      variable: 'oklch(0.2785 0.0132 253.04)',
+      type: 'oklch(0.5375 0.1155 202.14)',
+      tag: 'oklch(0.5165 0.1626 25.78)',
+      attribute: 'oklch(0.5016 0.1401 79.91)',
+      operator: 'oklch(0.2785 0.0132 253.04)',
+      heading: 'oklch(0.5143 0.1668 301.69)',
+      link: 'oklch(0.4973 0.1518 253.31)',
+      diffAdd: 'oklch(0.4771 0.1809 145.62)',
+      diffDelete: 'oklch(0.5165 0.1626 25.78)',
+      diffHunk: 'oklch(0.5375 0.1155 202.14)',
+      searchMatch: 'oklch(0.5016 0.1401 79.91)',
+    },
+    chart: [
+      'oklch(0.4973 0.1518 253.31)',
+      'oklch(0.5143 0.1668 301.69)',
+      'oklch(0.5375 0.1155 202.14)',
+      'oklch(0.4771 0.1809 145.62)',
+      'oklch(0.5016 0.1401 79.91)',
+      'oklch(0.5165 0.1626 25.78)',
+    ],
+    provenance: { source: 'Adea', url: 'https://github.com/adea-ai/themes', license: 'Apache-2.0' },
+  },
+  'adea-dark': {
+    id: 'adea-dark',
+    family: 'adea',
+    familyLabel: 'Adea',
+    label: 'Dark',
+    appearance: 'dark',
+    description:
+      'The default dark theme: GitHub Dark Default with the canvas re-greyed to a violet-leaning neutral and the family violet accent, kept as a composition so the default can diverge from it one slot at a time.',
+    colors: {
+      background: 'oklch(0.1756 0.0063 300.91)',
+      foreground: 'oklch(0.942 0.0054 297.72)',
+      card: 'oklch(0.2106 0.0076 300.91)',
+      cardForeground: 'oklch(0.942 0.0054 297.72)',
+      popover: 'oklch(0.2406 0.0088 300.91)',
+      popoverForeground: 'oklch(0.942 0.0054 297.72)',
+      primary: 'oklch(0.7323 0.1668 301.69)',
+      primaryForeground: 'oklch(0.1756 0.0063 300.91)',
+      secondary: 'oklch(0.2106 0.0076 300.91)',
+      secondaryForeground: 'oklch(0.942 0.0054 297.72)',
+      muted: 'oklch(0.2106 0.0076 300.91)',
+      mutedForeground: 'oklch(0.6967 0.0057 298.74)',
+      accent: 'oklch(0.2756 0.0101 300.91)',
+      accentForeground: 'oklch(0.942 0.0054 297.72)',
+      destructive: 'oklch(0.7345 0.1626 25.78)',
+      destructiveForeground: 'oklch(0.1756 0.0063 300.91)',
+      destructiveSubtle: 'oklch(0.2538 0.0282 312.79)',
+      destructiveAction: 'oklch(0.7345 0.1626 25.78)',
+      destructiveActionForeground: 'oklch(0.1756 0.0063 300.91)',
+      success: 'oklch(0.6951 0.1809 145.62)',
+      successForeground: 'oklch(0.1756 0.0063 300.91)',
+      successSubtle: 'oklch(0.2483 0.0307 279.17)',
+      warning: 'oklch(0.7196 0.1401 79.91)',
+      warningForeground: 'oklch(0.1756 0.0063 300.91)',
+      warningSubtle: 'oklch(0.2518 0.025 320.37)',
+      info: 'oklch(0.7555 0.1155 202.14)',
+      infoForeground: 'oklch(0.1756 0.0063 300.91)',
+      infoSubtle: 'oklch(0.2568 0.0216 287.08)',
+      border: 'oklch(0.3256 0.0057 300.91)',
+      input: 'oklch(0.3256 0.0057 300.91)',
+      ring: 'oklch(0.7323 0.1668 301.69)',
+      sidebar: 'oklch(0.2106 0.0076 300.91)',
+      sidebarForeground: 'oklch(0.942 0.0054 297.72)',
+      sidebarAccent: 'oklch(0.2756 0.0101 300.91)',
+      sidebarBorder: 'oklch(0.3256 0.0057 300.91)',
+      sidebarMutedForeground: 'oklch(0.6967 0.0057 298.74)',
+    },
+    terminal: {
+      background: 'oklch(0.1756 0.0063 300.91)',
+      foreground: 'oklch(0.942 0.0054 297.72)',
+      cursor: 'oklch(0.6182 0.1935 258.33)',
+      selection: 'oklch(0.9425 0.0111 243.66)',
+      black: 'oklch(0.4243 0.0101 301.11)',
+      red: 'oklch(0.7345 0.1626 25.78)',
+      green: 'oklch(0.6951 0.1809 145.62)',
+      yellow: 'oklch(0.7196 0.1401 79.91)',
+      blue: 'oklch(0.7153 0.1518 253.31)',
+      magenta: 'oklch(0.7323 0.1668 301.69)',
+      cyan: 'oklch(0.7555 0.1155 202.14)',
+      white: 'oklch(0.786 0.0087 301.32)',
+      brightBlack: 'oklch(0.5627 0.0094 301.22)',
+      brightRed: 'oklch(0.8014 0.1134 25.81)',
+      brightGreen: 'oklch(0.7717 0.188 145.48)',
+      brightYellow: 'oklch(0.7904 0.1386 85.24)',
+      brightBlue: 'oklch(0.7857 0.1153 246.66)',
+      brightMagenta: 'oklch(0.8005 0.1275 305.86)',
+      brightCyan: 'oklch(0.8036 0.1107 201.78)',
+      brightWhite: 'oklch(1 0 0)',
+    },
+    editor: {
+      keyword: 'oklch(0.7323 0.1668 301.69)',
+      string: 'oklch(0.6951 0.1809 145.62)',
+      number: 'oklch(0.7196 0.1401 79.91)',
+      comment: 'oklch(0.5627 0.0094 301.22)',
+      function: 'oklch(0.7153 0.1518 253.31)',
+      variable: 'oklch(0.786 0.0087 301.32)',
+      type: 'oklch(0.7555 0.1155 202.14)',
+      tag: 'oklch(0.7345 0.1626 25.78)',
+      attribute: 'oklch(0.7196 0.1401 79.91)',
+      operator: 'oklch(0.786 0.0087 301.32)',
+      heading: 'oklch(0.7323 0.1668 301.69)',
+      link: 'oklch(0.7153 0.1518 253.31)',
+      diffAdd: 'oklch(0.6951 0.1809 145.62)',
+      diffDelete: 'oklch(0.7345 0.1626 25.78)',
+      diffHunk: 'oklch(0.7555 0.1155 202.14)',
+      searchMatch: 'oklch(0.7196 0.1401 79.91)',
+    },
+    chart: [
+      'oklch(0.7153 0.1518 253.31)',
+      'oklch(0.7323 0.1668 301.69)',
+      'oklch(0.7555 0.1155 202.14)',
+      'oklch(0.6951 0.1809 145.62)',
+      'oklch(0.7196 0.1401 79.91)',
+      'oklch(0.7345 0.1626 25.78)',
+    ],
+    provenance: { source: 'Adea', url: 'https://github.com/adea-ai/themes', license: 'Apache-2.0' },
+  },
+}
+
+/** The accents the default light/dark pair offers beside the presets. */
+export const DEFAULT_THEME_ACCENTS: readonly AccentPreset[] = [
+  {
+    id: 'ansi-blue',
+    label: 'Blue',
+    description: "The theme's own blue colour.",
+    light: 'oklch(0.4973 0.1518 253.31)',
+    dark: 'oklch(0.7153 0.1518 253.31)',
+  },
+  {
+    id: 'ansi-magenta',
+    label: 'Magenta',
+    description: "The theme's own magenta colour.",
+    light: 'oklch(0.5143 0.1668 301.69)',
+    dark: 'oklch(0.7323 0.1668 301.69)',
+  },
+  {
+    id: 'ansi-cyan',
+    label: 'Cyan',
+    description: "The theme's own cyan colour.",
+    light: 'oklch(0.5375 0.1155 202.14)',
+    dark: 'oklch(0.7555 0.1155 202.14)',
+  },
+  {
+    id: 'ansi-green',
+    label: 'Green',
+    description: "The theme's own green colour.",
+    light: 'oklch(0.4771 0.1809 145.62)',
+    dark: 'oklch(0.6951 0.1809 145.62)',
+  },
+]
+
+/** Each default's measured `--primary-subtle` expression. */
+export const DEFAULT_PRIMARY_SUBTLE: Readonly<Record<string, string>> = {
+  'adea-light': 'color-mix(in oklch, var(--primary) 10%, transparent)',
+  'adea-dark': 'color-mix(in oklch, var(--primary) 16%, transparent)',
+}
+
+/** Each default's `--editor-*` ramp held to 4.5:1 on its canvas (`editorRoles: 'floor'`). */
+export const DEFAULT_FLOOR_EDITOR: Readonly<Record<string, ThemeEditorPalette>> = {
+  'adea-light': {
+    keyword: '#7a49b5',
+    string: '#00711f',
+    number: '#825c00',
+    comment: '#57606a',
+    function: '#0662b5',
+    variable: '#24292f',
+    type: '#007d85',
+    tag: '#b23533',
+    attribute: '#825c00',
+    operator: '#24292f',
+    heading: '#7a49b5',
+    link: '#0662b5',
+    diffAdd: '#00711f',
+    diffDelete: '#b23533',
+    diffHunk: '#007d85',
+    searchMatch: '#825c00',
+  },
+  'adea-dark': {
+    keyword: '#bc8cff',
+    string: '#3fb950',
+    number: '#d29922',
+    comment: '#7d7b81',
+    function: '#58a6ff',
+    variable: '#bab8be',
+    type: '#39c5cf',
+    tag: '#ff7b72',
+    attribute: '#d29922',
+    operator: '#bab8be',
+    heading: '#bc8cff',
+    link: '#58a6ff',
+    diffAdd: '#3fb950',
+    diffDelete: '#ff7b72',
+    diffHunk: '#39c5cf',
+    searchMatch: '#d29922',
+  },
+}

package/src/lib/theme-defaults.ts

@@ -0,0 +1,79 @@
+/**
+ * What a provider knows about the catalogue without loading it.
+ *
+ * The catalogue (`@adea-ai/themes`, 34 themes) is the heavy part of the theme
+ * system. Most hosts start on the default pair, paint a catalogue theme from a
+ * stylesheet, and open a picker rarely, so this module holds the few facts needed
+ * to start without it: the default ids, every catalogue id with its appearance (to
+ * recognise a stored preference), and the default pair as complete variants.
+ *
+ * It imports no catalogue code and no catalogue data. The facts themselves are in
+ * `theme-defaults.generated.ts`, copied from the catalogue by
+ * `scripts/build-theme-defaults.ts` and checked against it by
+ * `tests/theme-defaults.test.ts`.
+ */
+import type { ThemeAppearance, ThemeVariant } from './themes'
+import { DEFAULT_VARIANTS, THEME_INDEX } from './theme-defaults.generated'
+
+export {
+  DEFAULT_FLOOR_EDITOR,
+  DEFAULT_PRIMARY_SUBTLE,
+  DEFAULT_THEME_ACCENTS,
+  DEFAULT_VARIANTS,
+  THEME_INDEX,
+} from './theme-defaults.generated'
+
+export const defaultLightThemeId = 'adea-light'
+export const defaultDarkThemeId = 'adea-dark'
+
+/** The appearance of a catalogue theme id, or `undefined` for an id the catalogue lacks. */
+export function catalogueThemeAppearance(id: string): ThemeAppearance | undefined {
+  return THEME_INDEX.find(([candidate]) => candidate === id)?.[1]
+}
+
+/** Whether the catalogue holds a theme with this id (loaded or not). */
+export function isCatalogueThemeId(id: string): boolean {
+  return catalogueThemeAppearance(id) !== undefined
+}
+
+/** Whether an id is one of the two default themes, whose data ships with the provider. */
+export function isDefaultThemeId(id: string): id is keyof typeof DEFAULT_VARIANTS {
+  return id === defaultLightThemeId || id === defaultDarkThemeId
+}
+
+/** The default variant of an appearance. */
+export function defaultVariantFor(appearance: ThemeAppearance): ThemeVariant {
+  return DEFAULT_VARIANTS[appearance === 'dark' ? defaultDarkThemeId : defaultLightThemeId]
+}
+
+/**
+ * The variant a stored id means, or the default of the same appearance.
+ *
+ * An id the registry does not hold — an imported theme that was deleted, a
+ * catalogue entry that was renamed — must still paint *something of the appearance
+ * being shown*. Falling back to whichever variant happens to be first in the
+ * registry painted a dark palette under a light `color-scheme` for a light id, so
+ * the fallback is the appearance's own default, then any variant of that
+ * appearance, then the registry's first entry only when it holds nothing else.
+ *
+ * `registry` is the builtin catalogue plus whatever extras the host supplies; the
+ * stored id is never rewritten, only resolved, so a host that keeps an unknown id
+ * keeps resolving it if the theme comes back.
+ *
+ * The fallback order is translated from Zeron's `ThemeRegistry::resolve` (MIT,
+ * Copyright (c) 2026 Wing); see NOTICE.
+ */
+export function resolveVariant(
+  registry: readonly ThemeVariant[],
+  id: string,
+  appearance: ThemeAppearance
+): ThemeVariant {
+  const found = registry.find((variant) => variant.id === id)
+  if (found) return found
+  const defaultId = appearance === 'dark' ? defaultDarkThemeId : defaultLightThemeId
+  return (
+    registry.find((variant) => variant.id === defaultId) ??
+    registry.find((variant) => variant.appearance === appearance) ??
+    registry[0]!
+  )
+}

package/src/lib/theme-engine-light.ts

@@ -0,0 +1,117 @@
+/**
+ * The light theme engine: the catalogue questions answered from the data that ships
+ * with the provider, with no catalogue code or data (see `lib/theme-engine`).
+ */
+import type { AccentPreset } from '@adea-ai/themes'
+import { primarySubtleCss } from '@adea-ai/themes'
+import {
+  accentOverrideVariables,
+  resolveAccentRoles,
+  type AccentRoles,
+  type AccentTarget,
+} from './accent-roles'
+import { isThemeAccentId } from './theme-accents'
+import { themeCssVariablesWith } from './theme-css'
+import {
+  DEFAULT_FLOOR_EDITOR,
+  DEFAULT_PRIMARY_SUBTLE,
+  DEFAULT_THEME_ACCENTS,
+  DEFAULT_VARIANTS,
+  defaultDarkThemeId,
+  defaultLightThemeId,
+  isCatalogueThemeId,
+  isDefaultThemeId,
+} from './theme-defaults'
+import { CatalogueRequired, needsData, pairIds, type ThemeEngine } from './theme-engine'
+import type {
+  AccentVariableOptions,
+  EditorRolesMode,
+  ThemeAppearance,
+  ThemeVariant,
+} from './themes'
+
+const defaultVariantList: readonly ThemeVariant[] = [
+  DEFAULT_VARIANTS[defaultLightThemeId],
+  DEFAULT_VARIANTS[defaultDarkThemeId],
+]
+
+function lightEditor(theme: ThemeVariant, mode: EditorRolesMode) {
+  if (mode !== 'floor' || DEFAULT_VARIANTS[theme.id as keyof typeof DEFAULT_VARIANTS] !== theme)
+    return theme.editor
+  return DEFAULT_FLOOR_EDITOR[theme.id] ?? theme.editor
+}
+
+function lightPrimarySubtle(theme: Pick<ThemeVariant, 'id' | 'appearance'>): string {
+  const measured = DEFAULT_PRIMARY_SUBTLE[theme.id]
+  if (measured) return measured
+  if (isCatalogueThemeId(theme.id)) throw new CatalogueRequired(`the tint of ${theme.id}`)
+  return primarySubtleCss(theme.appearance)
+}
+
+function lightThemeAccentsFor(lightThemeId: string, darkThemeId: string): readonly AccentPreset[] {
+  const [light, dark] = pairIds(lightThemeId, darkThemeId)
+  if (needsData(light) || needsData(dark))
+    throw new CatalogueRequired(`the accents of ${light}/${dark}`)
+  return DEFAULT_THEME_ACCENTS
+}
+
+export const lightThemeEngine: ThemeEngine = {
+  builtinThemes: defaultVariantList,
+  isCatalogueVariant: (variant) =>
+    isDefaultThemeId(variant.id) && DEFAULT_VARIANTS[variant.id] === variant,
+  themeCssVariables(variant, options = {}) {
+    if (needsData(variant.id)) throw new CatalogueRequired(`the roles of ${variant.id}`)
+    return themeCssVariablesWith(
+      { primarySubtle: lightPrimarySubtle, editor: lightEditor },
+      variant,
+      options
+    )
+  },
+  themeAccentsFor: lightThemeAccentsFor,
+  accentVariables(accentId, appearance, pair, options = {}) {
+    const roles = lightAccentRoles(accentId, appearance, pair, options)
+    return roles ? accentOverrideVariables(roles) : undefined
+  },
+  accentRolesForSelection(accentId, appearance, pair, options = {}) {
+    if (accentId === 'theme') return undefined
+    const variantId = options.variantId
+    if (variantId !== undefined && needsData(variantId))
+      throw new CatalogueRequired(`the accent roles over ${variantId}`)
+    const roles = lightAccentRoles(accentId, appearance, pair, options)
+    const measured = variantId === undefined ? undefined : DEFAULT_PRIMARY_SUBTLE[variantId]
+    if (!roles || measured === undefined) return roles
+    // The theme's own tint strength is shipped for the defaults, and is the right one
+    // whenever the accent was not repaired. A repaired accent's tint is measured against
+    // the repaired primary, which only the catalogue can do.
+    const ungated = lightAccentRoles(accentId, appearance, pair, {
+      ...options,
+      floor: Number.NEGATIVE_INFINITY,
+    })
+    if (ungated?.primary !== roles.primary)
+      throw new CatalogueRequired(`the tint of a repaired accent over ${variantId}`)
+    return { ...roles, primarySubtle: measured }
+  },
+}
+
+/**
+ * The accent's roles with the appearance standing in for the theme record. The four
+ * document properties depend on the appearance alone; `primarySubtle` reads the record,
+ * so callers that return it must correct it.
+ */
+function lightAccentRoles(
+  accentId: string,
+  appearance: ThemeAppearance,
+  pair: { lightThemeId: string; darkThemeId: string },
+  options: AccentVariableOptions
+): AccentRoles | undefined {
+  if (accentId === 'theme') return undefined
+  const context: AccentTarget = {
+    target: appearance,
+    background: options.background,
+    floor: options.floor,
+    themeAccents: isThemeAccentId(accentId)
+      ? lightThemeAccentsFor(pair.lightThemeId, pair.darkThemeId)
+      : undefined,
+  }
+  return resolveAccentRoles(accentId, context)
+}

package/src/lib/theme-engine.ts

@@ -0,0 +1,111 @@
+/**
+ * The catalogue-dependent operations a provider performs, as one seam.
+ *
+ * `ThemeProvider` needs to ask a handful of questions that only the catalogue can
+ * answer in general: the built-in variants, a variant's custom properties, the roles
+ * an accent paints over it, the accents a theme pair offers. Two engines answer them.
+ *
+ *   - {@link catalogueThemeEngine} (`lib/theme-catalogue`) is the full answer, backed by
+ *     the whole catalogue. It is what `ThemeProvider` uses and what the lazy provider
+ *     switches to once the catalogue has loaded.
+ *   - {@link lightThemeEngine} (`lib/theme-engine-light`) answers from the data that ships with the
+ *     provider (`theme-defaults`): the default light/dark pair, host variants that are
+ *     not in the catalogue, and nothing else. It imports no catalogue data, which is
+ *     the point: a host that keeps the default pair never pays for the other 32
+ *     themes. A question outside that set throws {@link CatalogueRequired}; the lazy
+ *     provider asks {@link needsCatalogue} first and loads the catalogue instead.
+ *
+ * `tests/theme-engine.test.ts` holds the two to the same answers wherever the light
+ * engine can answer.
+ */
+import type { AccentPreset } from '@adea-ai/themes'
+import type { AccentRoles } from './accent-roles'
+import { isThemeAccentId } from './theme-accents'
+import {
+  defaultDarkThemeId,
+  defaultLightThemeId,
+  isCatalogueThemeId,
+  isDefaultThemeId,
+} from './theme-defaults'
+import type {
+  AccentVariableOptions,
+  ThemeAppearance,
+  ThemeCssVariableOptions,
+  ThemeVariant,
+} from './themes'
+
+export type ThemeEngine = {
+  /** The built-in variants. A plain array, in catalogue order. */
+  readonly builtinThemes: readonly ThemeVariant[]
+  /** True for the catalogue's own variant, not a host's copy that merely shares its id. */
+  isCatalogueVariant(variant: ThemeVariant): boolean
+  /** The custom properties a variant sets. */
+  themeCssVariables(
+    variant: ThemeVariant,
+    options?: ThemeCssVariableOptions
+  ): Record<string, string>
+  /**
+   * The custom properties an accent selection overrides on the document (`--primary`, its
+   * foreground, hover and ring), or `undefined` when it overrides nothing.
+   */
+  accentVariables(
+    accentId: string,
+    appearance: ThemeAppearance,
+    pair: { lightThemeId: string; darkThemeId: string },
+    options?: AccentVariableOptions
+  ): Record<string, string> | undefined
+  /** An accent selection resolved to its full roles against a theme pair, or `undefined`. */
+  accentRolesForSelection(
+    accentId: string,
+    appearance: ThemeAppearance,
+    pair: { lightThemeId: string; darkThemeId: string },
+    options?: AccentVariableOptions
+  ): AccentRoles | undefined
+  /** The accents a light/dark pair offers beside the presets. */
+  themeAccentsFor(lightThemeId: string, darkThemeId: string): readonly AccentPreset[]
+}
+
+/** Thrown by the light engine for a question that needs the whole catalogue. */
+export class CatalogueRequired extends Error {
+  constructor(what: string) {
+    super(`${what} needs the theme catalogue, which has not been loaded`)
+    this.name = 'CatalogueRequired'
+  }
+}
+
+/** The ids an id resolves to when the catalogue lacks it, as `getTheme ?? default` does. */
+export function pairIds(lightThemeId: string, darkThemeId: string): [string, string] {
+  return [
+    isCatalogueThemeId(lightThemeId) ? lightThemeId : defaultLightThemeId,
+    isCatalogueThemeId(darkThemeId) ? darkThemeId : defaultDarkThemeId,
+  ]
+}
+
+/** A catalogue id other than the two defaults: its data is not in the light engine. */
+export const needsData = (id: string) => isCatalogueThemeId(id) && !isDefaultThemeId(id)
+
+/**
+ * Whether answering for this selection needs the catalogue.
+ *
+ * True when the variant being shown, the pinned terminal theme, or (for a
+ * theme-derived `ansi-*` accent) either theme of the pair is a catalogue theme other
+ * than the two defaults. Everything else — the default pair, a host's own variants,
+ * every preset and custom accent — the light engine answers from shipped data.
+ */
+export function needsCatalogue(
+  selection: {
+    lightThemeId: string
+    darkThemeId: string
+    accent: string
+    terminalThemeId?: string
+  },
+  appearance: ThemeAppearance
+): boolean {
+  const shown = appearance === 'dark' ? selection.darkThemeId : selection.lightThemeId
+  if (needsData(shown)) return true
+  if (selection.terminalThemeId !== undefined && needsData(selection.terminalThemeId)) return true
+  return (
+    isThemeAccentId(selection.accent) &&
+    (needsData(selection.lightThemeId) || needsData(selection.darkThemeId))
+  )
+}