@adea-ai/ui 0.60.4 → 0.61.0

package/src/components/appearance.ts

@@ -1,1112 +0,0 @@
-/*
- * Copyright (c) 2026 Wing
- * Licensed under the MIT License.
- *
- * Appearance domain model substantially translated from Zeron
- * crates/theme/src/lib.rs and crates/ui/src/appearance.rs, revision
- * 30a9a9537c5ec96226c87f4bf349b6f77c5dfb59: color math with WCAG contrast,
- * accent role derivation, independent light/dark theme selection, the
- * system/light/dark mode resolver, surface preference resolution, the theme
- * registry with deterministic built-in fallback, and its validation rules.
- * Modified for TypeScript, Adea's token layer, custom accent validation,
- * the translucent surface capability, and the user reduced-transparency
- * policy Zeron lacks. See NOTICE and docs/research/dev-view-donor-audit.md.
- *
- * This module is the declared token layer for the built-in theme palette
- * data: the color string literals below are the theme itself, exactly like
- * the declarations in `styles/theme.css` (see
- * `scripts/check-theme-colors.mjs`).
- */
-
-/**
- * The versioned client appearance preference (Dev Runtime spec,
- * "Appearance and App Library"). Stored as one JSON document; the legacy
- * single `theme` key migrates into it without deleting the old value.
- */
-export type AppearancePreferencesV2 = Readonly<{
-  version: 2
-  mode: AppearanceMode
-  lightThemeId: string
-  darkThemeId: string
-  /** `'theme'`, a built-in preset id, or a validated `#rrggbb` color. */
-  accent: 'theme' | string
-  surface: 'opaque' | 'frosted' | 'translucent'
-  reduceTransparency: boolean
-}>
-
-export type AppearanceMode = 'system' | 'light' | 'dark'
-export type ResolvedAppearance = 'light' | 'dark'
-export type SurfacePreference = 'opaque' | 'frosted' | 'translucent'
-
-export const APPEARANCE_STORAGE_KEY = 'appearance'
-/** The pre-#425 key. Migration reads it and never deletes it. */
-export const LEGACY_THEME_STORAGE_KEY = 'theme'
-/**
- * Recovery envelope for unread preference documents (Dev Runtime spec,
- * "Compatibility, migrations, and waivers": a failed migration retains the
- * original record; it never silently rewrites or deletes the input). A
- * malformed or future-version document is quarantined here — before any
- * write can touch the main key — so saving valid preferences later can never
- * destroy the user's unread data.
- */
-export const APPEARANCE_RECOVERY_STORAGE_KEY = 'appearance.recovery'
-
-export type AppearanceRecoveryEnvelope = Readonly<{
-  schemaVersion: 1
-  reason: 'corrupt_json' | 'unsupported_record'
-  capturedAt: string
-  raw: string
-}>
-
-export const DARK_QUERY = '(prefers-color-scheme: dark)'
-export const REDUCED_TRANSPARENCY_QUERY = '(prefers-reduced-transparency: reduce)'
-
-export const defaultAppearancePreferences: AppearancePreferencesV2 = Object.freeze({
-  version: 2,
-  mode: 'system',
-  lightThemeId: 'adea-light',
-  darkThemeId: 'adea-dark',
-  accent: 'theme',
-  surface: 'opaque',
-  reduceTransparency: false,
-})
-
-/**
- * Combine the user's choice with the OS state. A pinned mode ignores the OS;
- * `system` follows it. (Zeron `resolve`.)
- */
-export function resolveAppearanceMode(
-  mode: AppearanceMode,
-  system: ResolvedAppearance
-): ResolvedAppearance {
-  if (mode === 'system') return system
-  return mode
-}
-
-/*
- * Color math — Zeron `Color`, translated. Values are `#rgb`, `#rgba`,
- * `#rrggbb`, or `#rrggbbaa` strings.
- */
-
-export type RgbColor = Readonly<{ r: number; g: number; b: number; a: number }>
-
-export class ColorParseError extends Error {
-  constructor() {
-    super('expected a CSS hex color (#rgb, #rgba, #rrggbb, or #rrggbbaa)')
-    this.name = 'ColorParseError'
-  }
-}
-
-const NIBBLES: Record<string, number> = {
-  '0': 0,
-  '1': 1,
-  '2': 2,
-  '3': 3,
-  '4': 4,
-  '5': 5,
-  '6': 6,
-  '7': 7,
-  '8': 8,
-  '9': 9,
-  a: 10,
-  b: 11,
-  c: 12,
-  d: 13,
-  e: 14,
-  f: 15,
-  A: 10,
-  B: 11,
-  C: 12,
-  D: 13,
-  E: 14,
-  F: 15,
-}
-
-function expandNibble(nibble: number): number {
-  return (nibble << 4) | nibble
-}
-
-function parseByte(high: number, low: number): number {
-  return (high << 4) | low
-}
-
-/** Parse a hex color. Returns `undefined` for anything unsupported. */
-export function parseColor(value: string): RgbColor | undefined {
-  const trimmed = value.trim()
-  if (!trimmed.startsWith('#')) return undefined
-  const bytes = trimmed.slice(1)
-  if (bytes.length === 3 || bytes.length === 4) {
-    const nibbles: number[] = []
-    for (const character of bytes) {
-      const nibble = NIBBLES[character]
-      if (nibble === undefined) return undefined
-      nibbles.push(nibble)
-    }
-    return {
-      r: expandNibble(nibbles[0]!),
-      g: expandNibble(nibbles[1]!),
-      b: expandNibble(nibbles[2]!),
-      a: nibbles.length === 4 ? expandNibble(nibbles[3]!) : 255,
-    }
-  }
-  if (bytes.length === 6 || bytes.length === 8) {
-    const nibbles: number[] = []
-    for (const character of bytes) {
-      const nibble = NIBBLES[character]
-      if (nibble === undefined) return undefined
-      nibbles.push(nibble)
-    }
-    const pair = (index: number) => parseByte(nibbles[index]!, nibbles[index + 1]!)
-    return {
-      r: pair(0),
-      g: pair(2),
-      b: pair(4),
-      a: nibbles.length === 8 ? pair(6) : 255,
-    }
-  }
-  return undefined
-}
-
-function toHexByte(value: number): string {
-  return value.toString(16).padStart(2, '0')
-}
-
-export function colorToHex(color: RgbColor): string {
-  if (color.a === 255) return `#${toHexByte(color.r)}${toHexByte(color.g)}${toHexByte(color.b)}`
-  return `#${toHexByte(color.r)}${toHexByte(color.g)}${toHexByte(color.b)}${toHexByte(color.a)}`
-}
-
-function blendOver(foreground: RgbColor, background: RgbColor): RgbColor {
-  const alpha = foreground.a / 255
-  const blend = (front: number, back: number) => Math.round(front * alpha + back * (1 - alpha))
-  return {
-    r: blend(foreground.r, background.r),
-    g: blend(foreground.g, background.g),
-    b: blend(foreground.b, background.b),
-    a: 255,
-  }
-}
-
-function mixColors(left: RgbColor, right: RgbColor, amount: number): RgbColor {
-  const clamped = Math.min(1, Math.max(0, amount))
-  const mix = (a: number, b: number) => Math.round(a + (b - a) * clamped)
-  return { r: mix(left.r, right.r), g: mix(left.g, right.g), b: mix(left.b, right.b), a: 255 }
-}
-
-function linearChannel(channel: number): number {
-  const value = channel / 255
-  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4
-}
-
-function relativeLuminance(color: RgbColor): number {
-  return (
-    0.2126 * linearChannel(color.r) +
-    0.7152 * linearChannel(color.g) +
-    0.0722 * linearChannel(color.b)
-  )
-}
-
-/** WCAG contrast ratio between two colors. Alpha composites over the background first. */
-export function contrastRatio(
-  foreground: RgbColor | string,
-  background: RgbColor | string
-): number {
-  const front = typeof foreground === 'string' ? parseColor(foreground) : foreground
-  const back = typeof background === 'string' ? parseColor(background) : background
-  if (!front || !back) return 0
-  const opaqueFront = front.a === 255 ? front : blendOver(front, back)
-  const a = relativeLuminance(opaqueFront)
-  const b = relativeLuminance(back)
-  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
-}
-
-function bestOnColor(color: RgbColor): RgbColor {
-  return contrastRatio(WHITE, color) >= contrastRatio(BLACK, color) ? WHITE : BLACK
-}
-
-const WHITE: RgbColor = { r: 255, g: 255, b: 255, a: 255 }
-const BLACK: RgbColor = { r: 0, g: 0, b: 0, a: 255 }
-
-/** Move toward black or white until the requested contrast is met. (Zeron `ensure_contrast`.) */
-function ensureContrast(color: RgbColor, background: RgbColor, minimum: number): RgbColor {
-  if (contrastRatio(color, background) >= minimum) return color
-  const target =
-    contrastRatio(BLACK, background) >= contrastRatio(WHITE, background) ? BLACK : WHITE
-  for (let step = 1; step <= 20; step++) {
-    const candidate = mixColors(color, target, step / 20)
-    if (contrastRatio(candidate, background) >= minimum) return candidate
-  }
-  return target
-}
-
-/*
- * Accent — Zeron `AccentPreset`/`AccentSelection`/`AccentRoles` with Adea's
- * custom-color validation. Presets carry per-appearance values; a custom
- * color is normalized to the 3:1 interaction minimum instead of rejected
- * outright, and unparseable values fall back to the theme default.
- */
-
-export type AccentPreset = Readonly<{
-  id: string
-  label: string
-  dark: string
-  light: string
-}>
-
-export const accentPresets: readonly AccentPreset[] = Object.freeze([
-  { id: 'violet', label: 'Violet', dark: '#a78bfa', light: '#6d28d9' },
-  { id: 'blue', label: 'Blue', dark: '#60a5fa', light: '#2563eb' },
-  { id: 'green', label: 'Green', dark: '#4ade80', light: '#15803d' },
-  { id: 'amber', label: 'Amber', dark: '#fbbf24', light: '#b45309' },
-  { id: 'cyan', label: 'Cyan', dark: '#22d3ee', light: '#0e7490' },
-  { id: 'pink', label: 'Pink', dark: '#f472b6', light: '#be185d' },
-])
-
-/**
- * Normalize a custom accent color against a variant background: unparseable
- * input is rejected (`undefined`), and any accepted color is raised to the
- * 3:1 interaction minimum so an accent can never ship unreadable.
- */
-export function normalizeAccentValue(value: string, background: string): string | undefined {
-  const parsed = parseColor(value)
-  if (!parsed) return undefined
-  const backdrop = parseColor(background) ?? WHITE
-  return colorToHex(ensureContrast(parsed, backdrop, 3))
-}
-
-export function accentPresetById(id: string): AccentPreset | undefined {
-  return accentPresets.find((preset) => preset.id === id)
-}
-
-export type AccentRoles = Readonly<{
-  /** Interactive primary. */
-  primary: string
-  /** Text drawn on `primary`-filled controls; ≥ 4.5:1 against it. */
-  onPrimary: string
-  /** Hover/press emphasis derived from the primary. */
-  strong: string
-  /** Focus ring color. */
-  ring: string
-  /** False when the selection is the variant's own accent and no role should be overridden. */
-  overrides: boolean
-}>
-
-/**
- * Derive the accent roles for a selection against a variant. `'theme'` keeps
- * the variant's own accent; presets and custom colors are normalized to the
- * 3:1 interaction minimum (Zeron `AccentRoles::derive`, thresholds preserved).
- */
-export function deriveAccentRoles(selection: string, variant: ThemeVariant): AccentRoles {
-  const background = variant.colors.background
-  let primary = variant.colors.primary
-  let overrides = false
-  if (selection !== 'theme') {
-    const preset = accentPresetById(selection)
-    const requested = preset
-      ? parseColor(variant.appearance === 'dark' ? preset.dark : preset.light)
-      : parseColor(selection)
-    if (requested) {
-      primary = colorToHex(ensureContrast(requested, parseColor(background)!, 3))
-      overrides = true
-    }
-  }
-  const primaryRgb = parseColor(primary)!
-  const onPrimary = colorToHex(bestOnColor(primaryRgb))
-  let strong = primary
-  if (contrastRatio(onPrimary, strong) < 4.5) {
-    strong = colorToHex(ensureContrast(primaryRgb, parseColor(onPrimary)!, 4.5))
-  }
-  return { primary, onPrimary, strong, ring: strong, overrides }
-}
-
-/*
- * Surface — Zeron `SurfacePreference.resolve` extended with Adea's
- * translucent capability gate and the reduced-transparency policy: the OS
- * setting or the user preference forces an accessible opaque fallback, and a
- * translucent request on a host without native translucency renders the
- * tokenized frosted surface instead of pretending to OS vibrancy.
- */
-export type EffectiveSurface = 'opaque' | 'frosted' | 'translucent'
-
-export function resolveSurface(
-  preference: SurfacePreference,
-  environment: Readonly<{
-    osReducedTransparency: boolean
-    userReducedTransparency: boolean
-    nativeTranslucency: boolean
-  }>
-): EffectiveSurface {
-  if (environment.osReducedTransparency || environment.userReducedTransparency) return 'opaque'
-  if (preference === 'translucent' && !environment.nativeTranslucency) return 'frosted'
-  return preference
-}
-
-/*
- * Theme registry — Zeron `ThemeVariant`/`ThemeRegistry`, narrowed to Adea's
- * semantic roles. Every runtime component consumes the CSS custom properties
- * declared here; terminal ANSI and editor roles come from the same manifest
- * so a theme switch updates them live without remounting a terminal or
- * editor.
- */
-
-export type ThemeTerminalPalette = Readonly<{
-  background: string
-  foreground: string
-  cursor: string
-  selection: string
-  /** The 16 xterm ANSI slots, in protocol order. */
-  ansi: readonly string[]
-}>
-
-export type ThemeEditorRoles = Readonly<{
-  keyword: string
-  string: string
-  number: string
-  comment: string
-  function: string
-  variable: string
-  type: string
-  tag: string
-  attribute: string
-  operator: string
-  heading: string
-  link: string
-  diffAdd: string
-  diffDelete: string
-  diffHunk: string
-  searchMatch: string
-}>
-
-export type ThemeChartRoles = Readonly<{
-  chart1: string
-  chart2: string
-  chart3: string
-  chart4: string
-  chart5: string
-  chart6: string
-}>
-
-export type ThemeColors = Readonly<{
-  background: string
-  foreground: string
-  card: string
-  cardForeground: string
-  popover: string
-  popoverForeground: string
-  primary: string
-  primaryForeground: string
-  secondary: string
-  secondaryForeground: string
-  muted: string
-  mutedForeground: string
-  accent: string
-  accentForeground: string
-  destructive: string
-  success: string
-  border: string
-  input: string
-  ring: string
-}>
-
-export type ThemeVariant = Readonly<{
-  id: string
-  familyId: string
-  familyName: string
-  name: string
-  appearance: ResolvedAppearance
-  colors: ThemeColors
-  terminal: ThemeTerminalPalette
-  editor: ThemeEditorRoles
-  charts: ThemeChartRoles
-}>
-
-/**
- * The independent per-appearance theme selection (Zeron `ThemeSelection`,
- * carrying the V2 preference's field names).
- */
-export type ThemeSelection = Readonly<{ lightThemeId: string; darkThemeId: string }>
-
-export function themeSelectionVariantId(
-  selection: ThemeSelection,
-  appearance: ResolvedAppearance
-): string {
-  return appearance === 'dark' ? selection.darkThemeId : selection.lightThemeId
-}
-
-export type ValidationIssue = Readonly<{
-  variantId: string
-  severity: 'error' | 'warning'
-  message: string
-}>
-
-/**
- * Registry validation, ported from Zeron `ThemeRegistry::validate`: core text
- * and muted text must reach 4.5:1, the accent 3:1, on-accent 4.5:1, the
- * terminal foreground 4.5:1, and every chromatic ANSI slot 3:1 (slots 0 and 8
- * are structural black/dim colors). Provenance completeness is a Zeron
- * library concept; M12 ships only built-ins, so the structural check here is
- * id/non-empty-color integrity.
- */
-export function validateThemeRegistry(registry: readonly ThemeVariant[]): ValidationIssue[] {
-  const issues: ValidationIssue[] = []
-  const seen = new Set<string>()
-  for (const variant of registry) {
-    if (variant.id.trim().length === 0 || seen.has(variant.id)) {
-      issues.push({
-        variantId: variant.id,
-        severity: 'error',
-        message: 'variant id must be unique',
-      })
-    }
-    seen.add(variant.id)
-    const check = (role: string, foreground: string, background: string, minimum: number) => {
-      const actual = contrastRatio(foreground, background)
-      if (actual < minimum) {
-        issues.push({
-          variantId: variant.id,
-          severity: 'error',
-          message: `${role} contrast is ${actual.toFixed(2)}:1; expected ${minimum.toFixed(1)}:1`,
-        })
-      }
-    }
-    check('text', variant.colors.foreground, variant.colors.background, 4.5)
-    check('muted text', variant.colors.mutedForeground, variant.colors.background, 4.5)
-    check('primary', variant.colors.primary, variant.colors.background, 3)
-    check('on-primary', variant.colors.primaryForeground, variant.colors.primary, 4.5)
-    check('terminal foreground', variant.terminal.foreground, variant.terminal.background, 4.5)
-    for (const [index, color] of variant.terminal.ansi.entries()) {
-      if (index % 8 === 0) continue
-      const actual = contrastRatio(color, variant.terminal.background)
-      if (actual < 3) {
-        issues.push({
-          variantId: variant.id,
-          severity: 'warning',
-          message: `terminal ANSI slot ${index} is below 3:1`,
-        })
-      }
-    }
-    check('editor comment', variant.editor.comment, variant.colors.background, 4.5)
-    check('diff delete', variant.editor.diffDelete, variant.colors.background, 3)
-    check('diff add', variant.editor.diffAdd, variant.colors.background, 3)
-  }
-  return issues
-}
-
-/**
- * Resolve the variant for a selection, falling back deterministically to the
- * default variant of the same appearance when the stored id is missing or
- * broken — a corrupt preference degrades the palette, never the UI.
- * (Zeron `ThemeRegistry::resolve`.)
- */
-export function resolveThemeVariant(
-  registry: readonly ThemeVariant[],
-  selection: ThemeSelection,
-  appearance: ResolvedAppearance
-): ThemeVariant {
-  const wanted = themeSelectionVariantId(selection, appearance)
-  const found = registry.find((variant) => variant.id === wanted)
-  if (found) return found
-  const fallbackId =
-    appearance === 'dark'
-      ? defaultAppearancePreferences.darkThemeId
-      : defaultAppearancePreferences.lightThemeId
-  const fallback = registry.find((variant) => variant.id === fallbackId)
-  if (fallback) return fallback
-  const sameAppearance = registry.find((variant) => variant.appearance === appearance)
-  if (sameAppearance) return sameAppearance
-  return registry[0]!
-}
-
-/*
- * Built-in registry — Adea's curated M12 set. `adea-light`/`adea-dark` mirror
- * the token declarations in `styles/theme.css` (which stay authoritative for
- * the defaults so first paint never shifts); `slate` is a cool quiet pair and
- * `contrast` an AA-emphasized pair. Terminal/editor/charts ship one curated
- * template per appearance so every variant keeps ANSI/syntax/diff legibility.
- */
-
-const lightTerminal: ThemeTerminalPalette = Object.freeze({
-  background: '#ffffff',
-  foreground: '#1b1f24',
-  cursor: '#24292f',
-  selection: '#b6c7ff',
-  ansi: Object.freeze([
-    '#1b1f24',
-    '#b91c1c',
-    '#116a2e',
-    '#8a5a1b',
-    '#0b57d0',
-    '#a0186f',
-    '#0e7490',
-    '#57606a',
-    '#57606a',
-    '#c94d4d',
-    '#1f9d4f',
-    '#a9752c',
-    '#3b82f6',
-    '#c04a92',
-    '#0891b2',
-    '#24292f',
-  ]),
-})
-
-const darkTerminal: ThemeTerminalPalette = Object.freeze({
-  background: '#0d1117',
-  foreground: '#e6edf3',
-  cursor: '#e6edf3',
-  selection: '#264f78',
-  ansi: Object.freeze([
-    '#2f3742',
-    '#ff8183',
-    '#56d364',
-    '#e3b341',
-    '#6ca4f8',
-    '#db61a2',
-    '#39c5cf',
-    '#d5dde5',
-    '#57606a',
-    '#ff9494',
-    '#79dd8a',
-    '#f0c264',
-    '#8db9ff',
-    '#e87cb4',
-    '#66d3dc',
-    '#eef2f6',
-  ]),
-})
-
-const lightEditor: ThemeEditorRoles = Object.freeze({
-  keyword: '#0b57d0',
-  string: '#116a2e',
-  number: '#8a5a1b',
-  comment: '#57606a',
-  function: '#a0186f',
-  variable: '#1b1f24',
-  type: '#0e7490',
-  tag: '#b91c1c',
-  attribute: '#8a5a1b',
-  operator: '#1b1f24',
-  heading: '#1b1f24',
-  link: '#0b57d0',
-  diffAdd: '#116a2e',
-  diffDelete: '#b91c1c',
-  diffHunk: '#57606a',
-  searchMatch: '#8a5a1b',
-})
-
-const darkEditor: ThemeEditorRoles = Object.freeze({
-  keyword: '#6ca4f8',
-  string: '#56d364',
-  number: '#e3b341',
-  comment: '#8b949e',
-  function: '#db61a2',
-  variable: '#e6edf3',
-  type: '#39c5cf',
-  tag: '#ff8183',
-  attribute: '#e3b341',
-  operator: '#e6edf3',
-  heading: '#e6edf3',
-  link: '#6ca4f8',
-  diffAdd: '#56d364',
-  diffDelete: '#ff8183',
-  diffHunk: '#8b949e',
-  searchMatch: '#e3b341',
-})
-
-const lightCharts: ThemeChartRoles = Object.freeze({
-  chart1: '#0b57d0',
-  chart2: '#116a2e',
-  chart3: '#8a5a1b',
-  chart4: '#a0186f',
-  chart5: '#0e7490',
-  chart6: '#57606a',
-})
-
-const darkCharts: ThemeChartRoles = Object.freeze({
-  chart1: '#6ca4f8',
-  chart2: '#56d364',
-  chart3: '#e3b341',
-  chart4: '#db61a2',
-  chart5: '#39c5cf',
-  chart6: '#8b949e',
-})
-
-function defineVariant(
-  id: string,
-  familyId: string,
-  familyName: string,
-  name: string,
-  appearance: ResolvedAppearance,
-  colors: ThemeColors
-): ThemeVariant {
-  const light = appearance === 'light'
-  return {
-    id,
-    familyId,
-    familyName,
-    name,
-    appearance,
-    colors,
-    terminal: light ? lightTerminal : darkTerminal,
-    editor: light ? lightEditor : darkEditor,
-    charts: light ? lightCharts : darkCharts,
-  }
-}
-
-/** The `adea-light`/`adea-dark` entries mirror `styles/theme.css`. */
-export const builtinThemeRegistry: readonly ThemeVariant[] = Object.freeze([
-  defineVariant('adea-light', 'adea', 'Adea', 'Adea Light', 'light', {
-    background: '#ffffff',
-    foreground: '#252525',
-    card: '#ffffff',
-    cardForeground: '#252525',
-    popover: '#ffffff',
-    popoverForeground: '#252525',
-    primary: '#343434',
-    primaryForeground: '#fcfcfc',
-    secondary: '#f7f7f7',
-    secondaryForeground: '#343434',
-    muted: '#f7f7f7',
-    mutedForeground: '#6f6f6f',
-    accent: '#f7f7f7',
-    accentForeground: '#343434',
-    destructive: '#c53c2b',
-    success: '#1a7f37',
-    border: '#ebebeb',
-    input: '#ebebeb',
-    ring: '#a3a3a3',
-  }),
-  defineVariant('adea-dark', 'adea', 'Adea', 'Adea Dark', 'dark', {
-    background: '#252525',
-    foreground: '#fcfcfc',
-    card: '#343434',
-    cardForeground: '#fcfcfc',
-    popover: '#343434',
-    popoverForeground: '#fcfcfc',
-    primary: '#ebebeb',
-    primaryForeground: '#343434',
-    secondary: '#444444',
-    secondaryForeground: '#fcfcfc',
-    muted: '#444444',
-    mutedForeground: '#a3a3a3',
-    accent: '#444444',
-    accentForeground: '#fcfcfc',
-    destructive: '#e07060',
-    success: '#3fb950',
-    border: 'rgba(255, 255, 255, 0.16)',
-    input: 'rgba(255, 255, 255, 0.2)',
-    ring: '#7c7c7c',
-  }),
-  defineVariant('slate-light', 'slate', 'Slate', 'Slate Light', 'light', {
-    background: '#f8fafc',
-    foreground: '#0f172a',
-    card: '#ffffff',
-    cardForeground: '#0f172a',
-    popover: '#ffffff',
-    popoverForeground: '#0f172a',
-    primary: '#0f172a',
-    primaryForeground: '#f8fafc',
-    secondary: '#e2e8f0',
-    secondaryForeground: '#0f172a',
-    muted: '#e2e8f0',
-    mutedForeground: '#475569',
-    accent: '#e2e8f0',
-    accentForeground: '#0f172a',
-    destructive: '#b91c1c',
-    success: '#15803d',
-    border: '#cbd5e1',
-    input: '#cbd5e1',
-    ring: '#64748b',
-  }),
-  defineVariant('slate-dark', 'slate', 'Slate', 'Slate Dark', 'dark', {
-    background: '#0f172a',
-    foreground: '#f1f5f9',
-    card: '#1e293b',
-    cardForeground: '#f1f5f9',
-    popover: '#1e293b',
-    popoverForeground: '#f1f5f9',
-    primary: '#e2e8f0',
-    primaryForeground: '#0f172a',
-    secondary: '#334155',
-    secondaryForeground: '#f1f5f9',
-    muted: '#334155',
-    mutedForeground: '#94a3b8',
-    accent: '#334155',
-    accentForeground: '#f1f5f9',
-    destructive: '#f87171',
-    success: '#4ade80',
-    border: 'rgba(148, 163, 184, 0.2)',
-    input: 'rgba(148, 163, 184, 0.25)',
-    ring: '#64748b',
-  }),
-  defineVariant('contrast-light', 'contrast', 'High Contrast', 'High Contrast Light', 'light', {
-    background: '#ffffff',
-    foreground: '#000000',
-    card: '#ffffff',
-    cardForeground: '#000000',
-    popover: '#ffffff',
-    popoverForeground: '#000000',
-    primary: '#143d8f',
-    primaryForeground: '#ffffff',
-    secondary: '#f0f0f0',
-    secondaryForeground: '#000000',
-    muted: '#f0f0f0',
-    mutedForeground: '#333333',
-    accent: '#f0f0f0',
-    accentForeground: '#000000',
-    destructive: '#b91c1c',
-    success: '#14532d',
-    border: '#767676',
-    input: '#767676',
-    ring: '#000000',
-  }),
-  defineVariant('contrast-dark', 'contrast', 'High Contrast', 'High Contrast Dark', 'dark', {
-    background: '#000000',
-    foreground: '#ffffff',
-    card: '#0a0a0a',
-    cardForeground: '#ffffff',
-    popover: '#0a0a0a',
-    popoverForeground: '#ffffff',
-    primary: '#8ab4ff',
-    primaryForeground: '#000000',
-    secondary: '#1a1a1a',
-    secondaryForeground: '#ffffff',
-    muted: '#1a1a1a',
-    mutedForeground: '#e5e5e5',
-    accent: '#1a1a1a',
-    accentForeground: '#ffffff',
-    destructive: '#ff6b6b',
-    success: '#4ade80',
-    border: '#8f8f8f',
-    input: '#8f8f8f',
-    ring: '#ffffff',
-  }),
-])
-
-/*
- * Preference storage: normalization, legacy migration, corrupt retention.
- */
-
-function normalizeMode(value: unknown): AppearanceMode {
-  return value === 'light' || value === 'dark' || value === 'system' ? value : 'system'
-}
-
-function normalizeSurface(value: unknown): SurfacePreference {
-  return value === 'frosted' || value === 'translucent' || value === 'opaque' ? value : 'opaque'
-}
-
-function normalizeThemeId(value: unknown, fallback: string): string {
-  return typeof value === 'string' && value.trim().length > 0 ? value : fallback
-}
-
-function normalizeAccent(value: unknown): string {
-  if (value === 'theme') return 'theme'
-  if (typeof value !== 'string') return 'theme'
-  if (accentPresetById(value)) return value
-  const parsed = parseColor(value)
-  return parsed ? colorToHex(parsed) : 'theme'
-}
-
-export type NormalizedPreferences = Readonly<{
-  /** The strict v2 document, with every unknown field corrected to defaults. */
-  value: AppearancePreferencesV2
-  /**
-   * The raw stored document when it was not a valid v2 record. Retained so a
-   * future version (or a repaired write) never loses the user's data.
-   */
-  retainedRaw?: unknown
-}>
-
-/**
- * Parse a stored appearance document. Anything that is not a strict version-2
- * record falls back to the defaults and keeps the raw value for retention;
- * individual unknown values inside a v2 record are corrected field by field.
- */
-export function normalizeAppearancePreferences(raw: unknown): NormalizedPreferences {
-  if (typeof raw !== 'object' || raw === null || (raw as { version?: unknown }).version !== 2) {
-    return { value: defaultAppearancePreferences, retainedRaw: raw }
-  }
-  const record = raw as Record<string, unknown>
-  return {
-    value: {
-      version: 2,
-      mode: normalizeMode(record.mode),
-      lightThemeId: normalizeThemeId(
-        record.lightThemeId,
-        defaultAppearancePreferences.lightThemeId
-      ),
-      darkThemeId: normalizeThemeId(record.darkThemeId, defaultAppearancePreferences.darkThemeId),
-      accent: normalizeAccent(record.accent),
-      surface: normalizeSurface(record.surface),
-      reduceTransparency: record.reduceTransparency === true,
-    },
-  }
-}
-
-/** The legacy single-key preference, mapped into v2 during migration. */
-export function migrateLegacyThemeValue(
-  stored: string | null
-): AppearancePreferencesV2 | undefined {
-  if (stored !== 'light' && stored !== 'dark' && stored !== 'system') return undefined
-  return { ...defaultAppearancePreferences, mode: stored }
-}
-
-type AppearanceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
-
-/**
- * Quarantine an unread raw document into the recovery envelope. Runs at read
- * time — before any later write can overwrite the main key — and is
- * idempotent: re-reading the same unread value refreshes the capture without
- * losing it.
- */
-function retainRecoveryEnvelope(
-  storage: AppearanceStorage,
-  raw: string,
-  reason: AppearanceRecoveryEnvelope['reason']
-): void {
-  try {
-    const envelope: AppearanceRecoveryEnvelope = {
-      schemaVersion: 1,
-      reason,
-      capturedAt: new Date().toISOString(),
-      raw,
-    }
-    storage.setItem(APPEARANCE_RECOVERY_STORAGE_KEY, JSON.stringify(envelope))
-  } catch {
-    // Quarantine is best-effort; the active preference still fails closed.
-  }
-}
-
-/**
- * Read the appearance preferences: the v2 key first, then the legacy `theme`
- * key, then defaults. A malformed or future-version document is quarantined
- * into the recovery envelope and the defaults are returned; storage failures
- * degrade to defaults like every other blocked-storage consumer.
- */
-export function readAppearancePreferences(
-  storage: AppearanceStorage | undefined
-): AppearancePreferencesV2 {
-  if (!storage) return defaultAppearancePreferences
-  try {
-    const raw = storage.getItem(APPEARANCE_STORAGE_KEY)
-    if (raw !== null) {
-      let parsed: unknown
-      try {
-        parsed = JSON.parse(raw)
-      } catch {
-        retainRecoveryEnvelope(storage, raw, 'corrupt_json')
-        return defaultAppearancePreferences
-      }
-      const normalized = normalizeAppearancePreferences(parsed)
-      if (normalized.retainedRaw !== undefined) {
-        retainRecoveryEnvelope(
-          storage,
-          raw,
-          typeof parsed === 'object' && parsed !== null ? 'unsupported_record' : 'corrupt_json'
-        )
-      }
-      return normalized.value
-    }
-    return (
-      migrateLegacyThemeValue(storage.getItem(LEGACY_THEME_STORAGE_KEY)) ??
-      defaultAppearancePreferences
-    )
-  } catch {
-    return defaultAppearancePreferences
-  }
-}
-
-export function writeAppearancePreferences(
-  storage: AppearanceStorage | undefined,
-  preferences: AppearancePreferencesV2
-): void {
-  if (!storage) return
-  try {
-    storage.setItem(APPEARANCE_STORAGE_KEY, JSON.stringify(preferences))
-  } catch {
-    // Persistence is best-effort: private modes and full quotas keep the
-    // in-memory preference.
-  }
-}
-
-/*
- * Document application. Both the provider and the no-flash inline script
- * resolve preferences to the same document shape, so a pre-paint restore and
- * a live change cannot disagree.
- */
-
-export type ResolvedAppearanceState = Readonly<{
-  resolvedMode: ResolvedAppearance
-  variant: ThemeVariant
-  accent: AccentRoles
-  effectiveSurface: EffectiveSurface
-  reduceTransparencyActive: boolean
-}>
-
-/** Resolve preferences against the environment into the applied document state. */
-export function resolveAppearanceState(
-  preferences: AppearancePreferencesV2,
-  environment: Readonly<{
-    systemAppearance: ResolvedAppearance
-    osReducedTransparency: boolean
-    nativeTranslucency: boolean
-  }>,
-  registry: readonly ThemeVariant[] = builtinThemeRegistry
-): ResolvedAppearanceState {
-  const resolvedMode = resolveAppearanceMode(preferences.mode, environment.systemAppearance)
-  const variant = resolveThemeVariant(registry, preferences, resolvedMode)
-  return {
-    resolvedMode,
-    variant,
-    accent: deriveAccentRoles(preferences.accent, variant),
-    effectiveSurface: resolveSurface(preferences.surface, {
-      osReducedTransparency: environment.osReducedTransparency,
-      userReducedTransparency: preferences.reduceTransparency,
-      nativeTranslucency: environment.nativeTranslucency,
-    }),
-    reduceTransparencyActive: environment.osReducedTransparency || preferences.reduceTransparency,
-  }
-}
-
-const SURFACE_BACKGROUND_ALPHA: Record<EffectiveSurface, string> = {
-  opaque: '1',
-  frosted: '0.92',
-  translucent: '0.8',
-}
-
-/**
- * The custom properties a non-default variant owns, as a flat map. This one
- * mapping feeds both the live provider and the pre-paint no-flash script, so
- * a restored first paint and a later live switch cannot disagree. Default
- * variants return an empty map: `styles/theme.css` declares those tokens.
- */
-export function flatVariantTokens(variant: ThemeVariant): Record<string, string> {
-  if (isDefaultVariant(variant)) return {}
-  const tokens: Record<string, string> = {}
-  for (const [role, value] of Object.entries(variant.colors)) {
-    tokens[`--${kebabCase(role)}`] = value
-  }
-  const terminal = variant.terminal
-  tokens['--terminal-background'] = terminal.background
-  tokens['--terminal-foreground'] = terminal.foreground
-  tokens['--terminal-cursor'] = terminal.cursor
-  tokens['--terminal-selection'] = terminal.selection
-  const ansiNames = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']
-  for (const [index, color] of terminal.ansi.entries()) {
-    const name = ansiNames[index % 8]!
-    tokens[index < 8 ? `--terminal-ansi-${name}` : `--terminal-ansi-bright-${name}`] = color
-  }
-  for (const [role, value] of Object.entries(variant.editor)) {
-    tokens[`--editor-${kebabCase(role)}`] = value
-  }
-  for (const [index, value] of Object.values(variant.charts).entries()) {
-    tokens[`--chart-${index + 1}`] = value
-  }
-  return tokens
-}
-
-/**
- * Apply a resolved state to a document: the `dark` class and color scheme for
- * the palette, the diagnostic data attributes, the accent role overrides, and
- * the resolved variant's semantic tokens (including terminal ANSI and editor
- * roles). CSS custom properties cascade, so terminals and editors update live
- * without remounting.
- *
- * The default `adea-light`/`adea-dark` variants skip the palette override —
- * `styles/theme.css` declares those tokens already, and leaving them CSS-owned
- * keeps first paint byte-identical to the pre-#425 app.
- */
-export function applyAppearanceToDocument(
-  document: Document,
-  state: ResolvedAppearanceState
-): void {
-  const root = document.documentElement
-  const style = root.style
-
-  root.classList.toggle('dark', state.resolvedMode === 'dark')
-  style.colorScheme = state.resolvedMode
-  root.dataset.theme = state.variant.id
-  root.dataset.appearanceMode = state.resolvedMode
-  root.dataset.surface = state.effectiveSurface
-  root.dataset.accent = state.accent.overrides ? 'custom' : 'theme'
-  root.dataset.reduceTransparency = state.reduceTransparencyActive ? 'true' : 'false'
-
-  const setToken = (name: string, value: string) => style.setProperty(name, value)
-  setToken('--surface-alpha', SURFACE_BACKGROUND_ALPHA[state.effectiveSurface])
-  // `theme` keeps every interactive role CSS-owned; an override touches only
-  // the accent roles, never the surface or text palette. Returning to
-  // `theme` must also *remove* a previous override's inline properties — they
-  // beat the stylesheet, so leaving them behind made "Theme default" look like
-  // a dead button after any preset or custom accent had been used.
-  if (state.accent.overrides) {
-    setToken('--primary', state.accent.primary)
-    setToken('--primary-foreground', state.accent.onPrimary)
-    setToken('--ring', state.accent.ring)
-  } else {
-    style.removeProperty('--primary')
-    style.removeProperty('--primary-foreground')
-    style.removeProperty('--ring')
-  }
-  for (const [name, value] of Object.entries(flatVariantTokens(state.variant))) {
-    setToken(name, value)
-  }
-}
-
-/**
- * The no-flash preload script rendered in the document head. It re-resolves
- * the stored (or legacy) preference against the OS before first paint and
- * applies the same palette state the provider would, so hydration never shows
- * the wrong palette. Accent overrides land with the provider: they decorate
- * the resolved palette and cannot produce a wrong-palette flash.
- */
-export function appearanceThemeScript(): string {
-  const preload = builtinThemeRegistry.map((variant) => ({
-    id: variant.id,
-    dark: variant.appearance === 'dark',
-    tokens: flatVariantTokens(variant),
-  }))
-  const registry = JSON.stringify(preload)
-  const alpha = JSON.stringify(SURFACE_BACKGROUND_ALPHA)
-  return `(function(){try{
-var prefs=null;var raw=null;
-try{raw=localStorage.getItem('${APPEARANCE_STORAGE_KEY}')}catch(e){}
-if(raw){try{var parsed=JSON.parse(raw);if(parsed&&parsed.version===2)prefs=parsed}catch(e){}}
-var mode='system';
-if(prefs){if(prefs.mode==='light'||prefs.mode==='dark')mode=prefs.mode}
-else{try{var t=localStorage.getItem('${LEGACY_THEME_STORAGE_KEY}');if(t==='light'||t==='dark')mode=t}catch(e){}}
-var dark=mode==='dark'||(mode==='system'&&window.matchMedia('${DARK_QUERY}').matches);
-var registry=${registry};
-var wanted=dark?(prefs&&prefs.darkThemeId)||'${defaultAppearancePreferences.darkThemeId}':(prefs&&prefs.lightThemeId)||'${defaultAppearancePreferences.lightThemeId}';
-var variant=null;
-for(var i=0;i<registry.length;i++){if(registry[i].id===wanted)variant=registry[i]}
-if(!variant){for(var j=0;j<registry.length;j++){if(registry[j].dark===dark)variant=registry[j]}}
-if(!variant)variant=registry[0];
-var reduce=window.matchMedia('${REDUCED_TRANSPARENCY_QUERY}').matches||!!(prefs&&prefs.reduceTransparency);
-/* Pre-hydration the host translucency capability is unknown, so the script
-   resolves every glass request to the conservative frosted tokens; the
-   provider re-resolves with the real capability once mounted. */
-var surface=reduce?'opaque':(prefs&&prefs.surface==='frosted'||prefs&&prefs.surface==='translucent'?'frosted':'opaque');
-if(surface!=='opaque'&&surface!=='frosted')surface='opaque';
-var r=document.documentElement,s=r.style;
-r.classList.toggle('dark',dark);
-s.colorScheme=dark?'dark':'light';
-r.dataset.theme=variant.id;
-r.dataset.appearanceMode=mode;
-r.dataset.surface=surface;
-r.dataset.reduceTransparency=reduce?'true':'false';
-s.setProperty('--surface-alpha',${alpha}[surface]||'1');
-var tokens=variant.tokens||{};
-for(var name in tokens){s.setProperty(name,tokens[name])}
-}catch(e){}})();`
-}
-
-function isDefaultVariant(variant: ThemeVariant): boolean {
-  return (
-    variant.id === defaultAppearancePreferences.lightThemeId ||
-    variant.id === defaultAppearancePreferences.darkThemeId
-  )
-}
-
-function kebabCase(value: string): string {
-  return value.replaceAll(/[A-Z]/g, (character) => `-${character.toLocaleLowerCase()}`)
-}