@adea-ai/ui 0.128.1 → 0.128.3

package/dist/r/src/components/theme/theme-state.ts

@@ -1,326 +1,17 @@
-import {
-  DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
-  normalizeAppearanceEditorFontSettings,
-  type AppearanceEditorFontSettings,
-} from '../../lib/appearance-font-settings'
-import type { AccentPreset } from '@adea-ai/themes'
-import { normalizeCustomAccent, type AccentRoles } from '../../lib/accent-roles'
-import { stepAppearanceFontSizes, type FontZoomIntent } from '../../lib/font-zoom'
-import type { ThemeSurface } from '../../lib/theme-surface'
-import {
-  accentRolesForSelection,
-  defaultDarkThemeId,
-  defaultLightThemeId,
-  resolveVariant,
-  type ThemeAppearance,
-  type ThemeVariant,
-} from '../../lib/themes'
+import { catalogueThemeEngine } from '../../lib/theme-catalogue'
+import type { AccentRoles } from '../../lib/accent-roles'
+import type { ThemeVariant } from '../../lib/themes'
+import { accentRolesForStateWith, type ThemeSelection } from './theme-state-core'
 
-/**
- * The pure half of the theme provider: what a selection is, how two selections
- * merge, and what a selection resolves to.
- *
- * Nothing here touches the document, storage or a signal, so each rule can be
- * tested by calling it. `ThemeProvider` owns the reactivity and wires these to it;
- * `theme-document.ts` owns the writes; `theme-persistence.ts` owns the store.
- */
-
-/**
- * Four independent choices, and keeping them independent is the point:
- *
- *   - **appearance** — light, dark, or follow the system.
- *   - **a theme per appearance** — so a user can run Catppuccin Mocha by night and
- *     Solarized Light by day without re-choosing when the system flips.
- *   - **an accent** — adea's six presets, or one of the accents the selected theme
- *     pair carries itself (`ansi-blue`…), which re-colour the interactive roles on
- *     top of whichever theme is active.
- *   - **fonts** — separate family and size choices for UI, content and code.
- */
-export type ThemeSelection = {
-  /** `system` follows `prefers-color-scheme` and updates when it changes. */
-  appearance: ThemeAppearance | 'system'
-  /** The variant to use when the resolved appearance is light. */
-  lightThemeId: string
-  /** The variant to use when the resolved appearance is dark. */
-  darkThemeId: string
-  /**
-   * An `accentPresets` id, a theme accent id from `themeAccents()` (`ansi-blue`…),
-   * `theme` for the variant's own primary, or a custom colour as `#rrggbb`. A theme
-   * accent the current pair does not offer falls back to the variant's own primary.
-   *
-   * A custom colour is stored lower case and is raised to the contrast floor when it
-   * is painted, never when it is stored: the selection keeps what the user chose.
-   * Anything else that is not an id is dropped at paint, not rejected here.
-   */
-  accent: string
-  /** UI-family alias for consumers of the original single-font preference. */
-  font: string
-  /** UI, content and code font settings. Omitted legacy records are migrated from `font`. */
-  fonts?: AppearanceEditorFontSettings
-  /**
-   * `comfortable` is the system's default geometry; `compact` moves the control
-   * ladder down one rung.
-   *
-   * Optional, and defaulted on read, so a preference stored before density existed
-   * keeps working and `ThemeSelection` stays assignable without it.
-   */
-  density?: ThemeDensity
-  /**
-   * The terminal either follows the interface theme (`theme`, or absent) or is pinned
-   * to another theme's terminal palette by that theme's id. The pin is written over
-   * the interface variant's own `--terminal-*` properties, so a light interface can
-   * carry a dark terminal.
-   *
-   * An id the registry does not hold paints the interface palette and stays in the
-   * selection, the same rule as an unknown theme id.
-   *
-   * Optional and not defaulted: see {@link defaultThemeSelection}.
-   */
-  terminalThemeId?: string
-  /**
-   * How opaque elevated panels are. Written to `<html>` only when the provider's
-   * `surface` prop is on or this is set; absent, a host paints no surface axis at
-   * all. Resolved against the OS and the host's capability before it is painted —
-   * see `resolveSurface` — so the value stored is a preference, never the outcome.
-   */
-  surface?: ThemeSurface
-  /**
-   * The user's own Reduce Transparency switch, which forces the `opaque` surface the
-   * same way the operating system's setting does.
-   */
-  reduceTransparency?: boolean
-}
-
-/**
- * The two density rungs.
- *
- * `comfortable` is the geometry in `theme.css`, so it is the absence of an
- * attribute rather than a value: a document that ships no `data-density` at all
- * renders correctly, which is what keeps this additive.
- */
-export type ThemeDensity = 'comfortable' | 'compact'
-
-/**
- * Deliberately lists only the fields every consumer has always had. A field added
- * to {@link ThemeSelection} later gets no default here: `JSON.stringify` drops an
- * `undefined`, so a store written by a consumer that never sets the field stays
- * byte-identical to what it was before the field existed.
- */
-export const defaultThemeSelection: ThemeSelection = {
-  appearance: 'system',
-  lightThemeId: defaultLightThemeId,
-  darkThemeId: defaultDarkThemeId,
-  accent: 'theme',
-  font: 'system',
-  fonts: DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
-  density: 'comfortable',
-}
-
-/**
- * A stored selection's density, defaulted.
- *
- * The stored value is read through here rather than trusted, because a preference
- * written before density existed has no `density` key and a hand-edited store may
- * hold anything.
- */
-export function resolvedDensity(selection: ThemeSelection): ThemeDensity {
-  return selection.density === 'compact' ? 'compact' : 'comfortable'
-}
-
-export type ThemeContextValue = {
-  /** The preference as stored. A {@link ThemeContextValue.preview} does not change it. */
-  selection: () => ThemeSelection
-  /** What the preference resolves to right now, after `system`. */
-  resolvedAppearance: () => ThemeAppearance
-  /** The variant in use. */
-  variant: () => ThemeVariant
-  /** Update part of the preference. */
-  setSelection: (patch: Partial<ThemeSelection>) => void
-  /**
-   * The built-in catalogue, so a picker does not import it separately. A plain
-   * array: {@link ThemeContextValue.allThemes} is the one that follows a host's
-   * extra themes.
-   */
-  themes: readonly ThemeVariant[]
-  /**
-   * The accents the selected light/dark pair carries, offered beside the presets.
-   * Follows the selection: a different theme pair may offer different slots.
-   */
-  themeAccents: () => readonly AccentPreset[]
-  /**
-   * The built-in catalogue followed by the provider's `themes` prop. Reactive when
-   * that prop is a function that reads signals.
-   */
-  allThemes: () => readonly ThemeVariant[]
-  /**
-   * Paint the document from `draft` laid over the stored selection, without
-   * persisting it or changing what {@link ThemeContextValue.selection} returns.
-   * `undefined` ends the preview. A {@link ThemeContextValue.setSelection} ends it
-   * too, because the committed selection is then what should be showing.
-   */
-  preview: (draft: Partial<ThemeSelection> | undefined) => void
-  /** True while a {@link ThemeContextValue.preview} draft is on the document. */
-  previewing: () => boolean
-  /**
-   * The roles `accent` paints over `variantId` (default: the variant in use), held
-   * to the provider's `accentContrastFloor`, for an element-scoped override with
-   * `paintAccentRoles` — a workspace that carries its own colour. `undefined` for
-   * `null`, for `theme`, for an id that resolves to nothing, and for a variant the
-   * registry does not hold: each means "keep the inherited accent".
-   */
-  accentRolesFor: (accent: string | null, variantId?: string) => AccentRoles | undefined
-  /**
-   * The surface the committed selection paints, after Reduce Transparency and the
-   * host's translucency capability. `opaque` when the axis is off. Follows the
-   * committed selection, not a preview, like {@link ThemeContextValue.variant}.
-   */
-  effectiveSurface: () => ThemeSurface
-  /**
-   * True while the operating system or the selection's `reduceTransparency` forces
-   * opaque surfaces. Always false when the surface axis is off, because nothing is
-   * then listening to the operating system.
-   */
-  reduceTransparencyActive: () => boolean
-  /**
-   * Step the three text sizes together, or put them back to the defaults: what the
-   * `fontZoom` prop's chords do, for a host that binds its own keys or a menu. Goes
-   * through {@link ThemeContextValue.setSelection}, so it persists and ends a preview.
-   */
-  zoomFonts: (intent: FontZoomIntent) => void
-}
-
-/** A selection with the `undefined` keys of a patch left out. */
-function definedOnly<T extends object>(value: T): Partial<T> {
-  return Object.fromEntries(
-    Object.entries(value).filter(([, entry]) => entry !== undefined)
-  ) as Partial<T>
-}
-
-/** Keep the deprecated single-font view synchronized with the UI axis. */
-export function mergeThemeSelection(
-  base: ThemeSelection,
-  patch: Partial<ThemeSelection>
-): ThemeSelection {
-  const merged = { ...base, ...patch }
-  let fonts: AppearanceEditorFontSettings
-
-  if (patch.fonts !== undefined) {
-    fonts = normalizeAppearanceEditorFontSettings(patch.fonts).settings
-  } else if (patch.font !== undefined) {
-    const currentFonts = normalizeAppearanceEditorFontSettings(base.fonts, base.font).settings
-    fonts = normalizeAppearanceEditorFontSettings({
-      ...currentFonts,
-      ui: { ...currentFonts.ui, family: patch.font },
-    }).settings
-  } else {
-    fonts = normalizeAppearanceEditorFontSettings(merged.fonts, merged.font).settings
-  }
-
-  return {
-    ...merged,
-    // One spelling for a custom colour, so equal choices compare and store equal.
-    accent: normalizeCustomAccent(merged.accent) ?? merged.accent,
-    fonts,
-    font: fonts.ui.family,
-  }
-}
-
-/**
- * The selection a provider starts from: the defaults, then whatever the store
- * returned, then `initial`.
- *
- * `initial` wins over the store on every mount. That precedence is part of the
- * contract Cortana relies on (its `initial` pins `appearance` and `font`), and it
- * is why the store's answer is only the middle layer. A store that returned
- * nothing, or threw, or answered with explicit `undefined`s, leaves the defaults
- * standing for those fields.
- */
-export function initialThemeSelection(
-  stored: Partial<ThemeSelection> | undefined,
-  initial: Partial<ThemeSelection> | undefined
-): ThemeSelection {
-  const base = mergeThemeSelection(defaultThemeSelection, definedOnly(stored ?? {}))
-  return mergeThemeSelection(base, initial ?? {})
-}
-
-/** `system` resolved against what the operating system reports. */
-export function resolveAppearance(
-  preference: ThemeSelection['appearance'],
-  system: ThemeAppearance
-): ThemeAppearance {
-  return preference === 'system' ? system : preference
-}
-
-/** The theme id the selection names for a resolved appearance. */
-export function selectedThemeId(selection: ThemeSelection, appearance: ThemeAppearance): string {
-  return appearance === 'dark' ? selection.darkThemeId : selection.lightThemeId
-}
-
-/**
- * What a selection paints: the resolved appearance and the variant for it.
- *
- * An id the registry does not hold resolves to the appearance's default rather than
- * being rewritten (see `resolveVariant`), so the selection a host stores is never
- * changed by being unresolvable.
- */
-export function resolveThemeState(
-  selection: ThemeSelection,
-  system: ThemeAppearance,
-  registry: readonly ThemeVariant[]
-): { appearance: ThemeAppearance; variant: ThemeVariant } {
-  const appearance = resolveAppearance(selection.appearance, system)
-  return {
-    appearance,
-    variant: resolveVariant(registry, selectedThemeId(selection, appearance), appearance),
-  }
-}
-
-/**
- * The variant whose terminal palette is pinned, or `undefined` when the terminal
- * follows the interface theme.
- *
- * `theme`, an absent id and an id the registry does not hold all mean the interface
- * palette: a terminal must never resolve to a blank or half-painted palette because a
- * theme was deleted after it was pinned.
- */
-export function resolveTerminalVariant(
-  terminalThemeId: string | undefined,
-  registry: readonly ThemeVariant[]
-): ThemeVariant | undefined {
-  if (terminalThemeId === undefined || terminalThemeId === 'theme') return undefined
-  return registry.find((candidate) => candidate.id === terminalThemeId)
-}
-
-/**
- * The font settings a zoom chord asks for: one pixel up or down on every axis, or
- * the defaults for `reset`.
- */
-export function zoomedFontSettings(
-  selection: ThemeSelection,
-  intent: FontZoomIntent
-): AppearanceEditorFontSettings {
-  if (intent === 'reset') return { ...DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS }
-  return stepAppearanceFontSizes(selection.fonts, intent === 'in' ? 1 : -1)
-}
-
-/**
- * The registry a provider resolves against: the catalogue, then the host's extras.
- *
- * The catalogue wins an id collision, because it is listed first and `resolveVariant`
- * takes the first match: a host's variant can add a theme but cannot shadow one.
- */
-export function mergeRegistry(
-  builtin: readonly ThemeVariant[],
-  extra: readonly ThemeVariant[] | undefined
-): readonly ThemeVariant[] {
-  return extra && extra.length > 0 ? [...builtin, ...extra] : builtin
-}
+export * from './theme-state-core'
 
 /**
- * The roles an accent paints over a variant, for {@link ThemeContextValue.accentRolesFor}.
+ * The roles an accent paints over a variant, for `ThemeContextValue.accentRolesFor`,
+ * resolved against the whole catalogue.
  *
  * Resolved against the committed selection's theme pair, so an `ansi-*` accent means
- * the same colour here as it does on `<html>`.
+ * the same colour here as it does on `<html>`. The lazy provider uses
+ * {@link accentRolesForStateWith} with the engine it has.
  */
 export function accentRolesForState(
   accent: string | null,
@@ -332,15 +23,5 @@ export function accentRolesForState(
     accentContrastFloor?: number
   }
 ): AccentRoles | undefined {
-  if (accent === null) return undefined
-  const variant =
-    variantId === undefined
-      ? state.variant
-      : state.registry.find((candidate) => candidate.id === variantId)
-  if (!variant) return undefined
-  return accentRolesForSelection(accent, variant.appearance, state.selection, {
-    background: variant.colors.background,
-    floor: state.accentContrastFloor,
-    variantId: variant.id,
-  })
+  return accentRolesForStateWith(catalogueThemeEngine, accent, variantId, state)
 }

package/dist/r/src/components/theme/theme-toggle.tsx

@@ -3,7 +3,7 @@ import type { ComponentProps } from 'solid-js'
 import { For, splitProps } from 'solid-js'
 import { cn } from '../../lib/utils'
 import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group/toggle-group'
-import { useTheme } from './theme-provider'
+import { useTheme } from './theme-context'
 
 /**
  * ThemeToggle.

package/dist/r/src/lib/accent-presets.ts

@@ -0,0 +1,43 @@
+import { ACCENTS } from '@adea-ai/themes'
+
+/*
+ * Its own module so the theme provider's start-up path (the stored-preference reader
+ * and the boot script both need the preset ids) does not import the token manifest in
+ * `tokens.ts`, which is 20 KB of documentation data a provider never reads.
+ * `tokens.ts` re-exports both names, so every existing import keeps working.
+ */
+
+/**
+ * The accent axis.
+ *
+ * adea's accent presets, as a selection rather than a constant. `theme` is the
+ * default and means "the variant's own primary" — monochrome in adea's palette —
+ * and each named preset overrides the interactive roles through the
+ * `[data-accent]` blocks in `theme.css`.
+ *
+ * These are the same six presets `accentPresets` exports in adea's own
+ * `appearance.ts`, and the values match. A consumer's appearance picker and the
+ * workshop's theme toolbar read this one list, so the two cannot disagree about
+ * what a preset is called or what colour it is.
+ */
+export type AccentPreset = {
+  /** The `data-accent` value. `theme` is the variant's own primary. */
+  id: string
+  label: string
+  /** What the preset is for, in the gallery and in a picker. */
+  description: string
+  /** The accent as it appears in the light theme. Absent for `theme`. */
+  light?: string
+  /** The accent as it appears in the dark theme. Absent for `theme`. */
+  dark?: string
+}
+
+export const accentPresets: readonly AccentPreset[] = Object.freeze([
+  {
+    id: 'theme',
+    label: 'Theme',
+    description:
+      "The variant's own primary. Neutral in adea's palette, so the interface stays monochrome.",
+  },
+  ...ACCENTS,
+])

package/dist/r/src/lib/theme-catalogue.ts

@@ -0,0 +1,26 @@
+/**
+ * The full theme engine, backed by the whole catalogue.
+ *
+ * This is the module a provider loads when it needs more than the default pair — and,
+ * for `ThemeProvider`, always. It imports `lib/themes` (which imports the catalogue)
+ * and nothing imports it statically except the eager provider, so a bundler can put
+ * it, and the catalogue behind it, in a chunk of its own for the lazy provider.
+ */
+import {
+  accentRolesForSelection,
+  accentVariables,
+  builtinThemes,
+  isCatalogueVariant,
+  themeAccentsFor,
+  themeCssVariables,
+} from './themes'
+import type { ThemeEngine } from './theme-engine'
+
+export const catalogueThemeEngine: ThemeEngine = {
+  builtinThemes,
+  isCatalogueVariant,
+  themeCssVariables,
+  accentVariables,
+  accentRolesForSelection,
+  themeAccentsFor,
+}

package/dist/r/src/lib/theme-css.ts

@@ -0,0 +1,201 @@
+/**
+ * The mapping from a variant's roles to this system's custom properties, without the
+ * catalogue.
+ *
+ * `themeCssVariables` needs two things only the catalogue can measure for a theme:
+ * the strength of its `--primary-subtle` tint and its floor-projected editor ramp.
+ * Those are the `hooks`, so this module imports no catalogue data and a host that
+ * never loads the catalogue can still paint a variant it already holds. `lib/themes`
+ * binds the hooks to the catalogue and keeps exporting the same
+ * `themeCssVariables`; `lib/theme-engine` binds them to the precomputed default pair.
+ */
+import { primaryHover } from '@adea-ai/themes'
+import { oklchToHex, parseColor } from '@adea-ai/themes/oklch'
+import type {
+  EditorRolesMode,
+  ThemeCssVariableOptions,
+  ThemeEditorPalette,
+  ThemeVariant,
+} from './themes'
+
+/** What a variant's custom properties need that depends on the catalogue. */
+export type ThemeCssHooks = {
+  /** The `--primary-subtle` expression of a variant. */
+  primarySubtle(theme: Pick<ThemeVariant, 'id' | 'appearance'>): string
+  /** The editor ramp of a variant under a projection. */
+  editor(theme: ThemeVariant, mode: EditorRolesMode): ThemeEditorPalette
+}
+
+/**
+ * The roles a variant sets, as CSS custom properties.
+ *
+ * The one place that knows the mapping from a theme's roles to this system's variable
+ * names. A provider applies this; nothing else repeats it. The `--terminal-*` and
+ * `--editor-*` ramps are presentations of the catalogue's ANSI and syntax data rather
+ * than separate roles, which is why they are built here and not in the catalogue.
+ *
+ * `options.editor` picks the `--editor-*` projection ({@link EditorRolesMode}).
+ * Absent it, the result is what it has always been; the generated `theme-variants.css`
+ * and the design-system artifact are built without it.
+ */
+export function themeCssVariablesWith(
+  hooks: ThemeCssHooks,
+  theme: ThemeVariant,
+  options: ThemeCssVariableOptions = {}
+): Record<string, string> {
+  const c = theme.colors
+  const t = theme.terminal
+  const e = hooks.editor(theme, options.editor ?? 'syntax')
+  const derived = {
+    '--background': c.background,
+    '--foreground': c.foreground,
+    '--card': c.card,
+    '--card-foreground': c.cardForeground,
+    '--popover': c.popover,
+    '--popover-foreground': c.popoverForeground,
+    '--primary': c.primary,
+    '--primary-foreground': c.primaryForeground,
+    /*
+     * The two tokens derived from the primary, and they are here rather than left to
+     * `theme.css` because they must follow `--primary` — which this function writes
+     * for *any* theme in the catalogue, not just the two defaults `theme.css` carries.
+     *
+     * `--primary-hover` is a resolved colour, not a `color-mix()`: a uniform hover
+     * step cannot be expressed as a mix (see `primaryHover`). Left out, a theme switch
+     * would keep the previous theme's hover on the new theme's primary.
+     *
+     * `--primary-subtle` is a mix over `--primary`, so it follows an accent on its
+     * own, but its *strength* is per theme: `primarySubtleCss(record)` lowers the
+     * appearance ceiling only as far as this theme needs for body text to clear 4.5:1
+     * on the tint, over every surface, for every accent it offers. It has to be
+     * written per theme for that reason — the appearance-wide value is not legible on
+     * every palette.
+     */
+    '--primary-hover': primaryHover(c.primary, theme.appearance),
+    '--primary-subtle': hooks.primarySubtle(theme),
+    '--secondary': c.secondary,
+    '--secondary-foreground': c.secondaryForeground,
+    '--muted': c.muted,
+    '--muted-foreground': c.mutedForeground,
+    '--accent': c.accent,
+    '--accent-foreground': c.accentForeground,
+    '--destructive': c.destructive,
+    '--destructive-foreground': c.destructiveForeground,
+    '--destructive-subtle': c.destructiveSubtle,
+    '--destructive-action': c.destructiveAction,
+    '--destructive-action-foreground': c.destructiveActionForeground,
+    '--success': c.success,
+    '--success-foreground': c.successForeground,
+    '--success-subtle': c.successSubtle,
+    '--warning': c.warning,
+    '--warning-foreground': c.warningForeground,
+    '--warning-subtle': c.warningSubtle,
+    '--info': c.info,
+    '--info-foreground': c.infoForeground,
+    '--info-subtle': c.infoSubtle,
+    '--border': c.border,
+    '--input': c.input,
+    '--ring': c.ring,
+    '--sidebar': c.sidebar,
+    '--sidebar-foreground': c.sidebarForeground,
+    '--sidebar-accent': c.sidebarAccent,
+    '--sidebar-border': c.sidebarBorder,
+    '--sidebar-primary': c.primary,
+    '--sidebar-primary-foreground': c.primaryForeground,
+    '--sidebar-ring': c.ring,
+    '--sidebar-muted-foreground': c.sidebarMutedForeground,
+    '--surface-sunken': c.muted,
+    '--surface-hover': c.accent,
+    '--surface-active': c.border,
+    '--chrome': c.background,
+    ...terminalVariables(t),
+    '--editor-keyword': e.keyword,
+    '--editor-string': e.string,
+    '--editor-number': e.number,
+    '--editor-comment': e.comment,
+    '--editor-function': e.function,
+    '--editor-variable': e.variable,
+    '--editor-type': e.type,
+    '--editor-tag': e.tag,
+    '--editor-attribute': e.attribute,
+    '--editor-operator': e.operator,
+    '--editor-heading': e.heading,
+    '--editor-link': e.link,
+    '--editor-diff-add': e.diffAdd,
+    '--editor-diff-delete': e.diffDelete,
+    '--editor-diff-hunk': e.diffHunk,
+    '--editor-search-match': e.searchMatch,
+    '--chart-1': theme.chart[0] ?? c.primary,
+    '--chart-2': theme.chart[1] ?? c.info,
+    '--chart-3': theme.chart[2] ?? c.success,
+    '--chart-4': theme.chart[3] ?? c.warning,
+    '--chart-5': theme.chart[4] ?? c.destructive,
+    '--chart-6': theme.chart[5] ?? c.mutedForeground,
+  }
+  return theme.tokens ? { ...derived, ...theme.tokens } : derived
+}
+
+function terminalVariables(t: ThemeVariant['terminal']): Record<string, string> {
+  return {
+    '--terminal-background': t.background,
+    '--terminal-foreground': t.foreground,
+    '--terminal-cursor': t.cursor,
+    '--terminal-selection': t.selection,
+    '--terminal-ansi-black': t.black,
+    '--terminal-ansi-red': t.red,
+    '--terminal-ansi-green': t.green,
+    '--terminal-ansi-yellow': t.yellow,
+    '--terminal-ansi-blue': t.blue,
+    '--terminal-ansi-magenta': t.magenta,
+    '--terminal-ansi-cyan': t.cyan,
+    '--terminal-ansi-white': t.white,
+    '--terminal-ansi-bright-black': t.brightBlack,
+    '--terminal-ansi-bright-red': t.brightRed,
+    '--terminal-ansi-bright-green': t.brightGreen,
+    '--terminal-ansi-bright-yellow': t.brightYellow,
+    '--terminal-ansi-bright-blue': t.brightBlue,
+    '--terminal-ansi-bright-magenta': t.brightMagenta,
+    '--terminal-ansi-bright-cyan': t.brightCyan,
+    '--terminal-ansi-bright-white': t.brightWhite,
+  }
+}
+
+/**
+ * The `--terminal-*` properties of a variant: the palette a terminal paints.
+ *
+ * What a pinned terminal theme writes over the interface variant's own. The names
+ * are the ones {@link themeCssVariablesWith} writes, and a custom variant's verbatim
+ * `tokens` still win, so they can never drift from what the interface variant would
+ * have written for the same palette. Built from the terminal palette alone: it needs
+ * neither the catalogue nor the rest of the variant's roles.
+ */
+export function terminalCssVariables(theme: ThemeVariant): Record<string, string> {
+  const properties = terminalVariables(theme.terminal)
+  if (!theme.tokens) return properties
+  for (const [name, value] of Object.entries(theme.tokens)) {
+    if (name.startsWith('--terminal-')) properties[name] = value
+  }
+  return properties
+}
+
+/**
+ * Token values with every `oklch()` colour written as `#rrggbb`.
+ *
+ * For a host whose stylesheet, tests or native shell speak hex: the catalogue's
+ * roles are `oklch()` strings, and this is the one conversion, gamut-mapped by the
+ * catalogue's own `oklchToHex`. A value that is already hex, carries alpha
+ * (`rgba()`), or is not a plain colour (`color-mix()`, `var()`) is left byte for
+ * byte, because converting would either lose the alpha or be a guess. Suitable as
+ * `ThemeProvider`'s `transformTokens`.
+ */
+export function tokensAsHex(tokens: Readonly<Record<string, string>>): Record<string, string> {
+  const converted: Record<string, string> = {}
+  for (const [name, value] of Object.entries(tokens)) {
+    const trimmed = value.trim()
+    // `parseOklch` discards alpha, so a translucent oklch() stays as written.
+    const opaque = trimmed.startsWith('oklch(') && !trimmed.includes('/')
+    const parsed = opaque ? parseColor(trimmed) : undefined
+    converted[name] = parsed ? oklchToHex(parsed) : value
+  }
+  return converted
+}