Theme System

interface Theme {
  /** Theme display name */
  name: string;

  /** Theme category */
  type: 'light' | 'dark' | 'ansi' | 'custom';

  /** Primary accent color */
  primary?: string;

  /** Secondary accent color */
  secondary?: string;

  /** Background color */
  background?: string;

  /** Foreground/text color */
  foreground?: string;

  /** Additional color palette */
  colors?: {
    error?: string;
    warning?: string;
    success?: string;
    info?: string;
    muted?: string;
    highlight?: string;
  };

  /** Syntax highlighting colors */
  syntax?: {
    keyword?: string;
    string?: string;
    number?: string;
    comment?: string;
    function?: string;
    variable?: string;
  };
}

const DARK_THEMES = [
  'ayu-dark',           // Modern dark theme with blue accents
  'atom-one-dark',      // Popular editor theme
  'dracula',            // High-contrast purple theme
  'default',            // Default dark theme
  'github-dark',        // GitHub's dark theme
  'shades-of-purple'    // Purple-focused theme
] as const;

const LIGHT_THEMES = [
  'ayu-light',          // Clean light theme
  'default-light',      // Default light theme
  'github-light',       // GitHub's light theme
  'googlecode',         // Google Code style
  'xcode'               // Xcode-inspired theme
] as const;

const ANSI_THEMES = [
  'ansi',               // Standard ANSI colors
  'ansi-light'          // Light ANSI variant
] as const;

const SPECIAL_THEMES = [
  'no-color'            // Activated when NO_COLOR env var is set
] as const;

interface ThemeManager {
  /**
   * Get list of all available theme names
   * @returns Array of theme names
   */
  getAvailableThemes(): string[];

  /**
   * Set the active theme
   * @param name - Theme name to activate
   * @throws Error if theme doesn't exist
   */
  setActiveTheme(name: string): void;

  /**
   * Get the currently active theme
   * @returns Current theme object
   */
  getActiveTheme(): Theme;

  /**
   * Load custom themes from configuration
   * @param themes - Custom theme definitions
   */
  loadCustomThemes(themes: Record<string, Theme>): void;

  /**
   * Get theme by name
   * @param name - Theme name
   * @returns Theme object or null if not found
   */
  getTheme(name: string): Theme | null;

  /**
   * Check if theme exists
   * @param name - Theme name to check
   * @returns True if theme exists
   */
  hasTheme(name: string): boolean;
}

/** Global theme manager instance */
const themeManager: ThemeManager;

/**
 * Interactive theme selection interface
 * @returns Promise resolving to selected theme name
 */
function selectTheme(): Promise<string>;

/**
 * Set theme from command line or configuration
 * @param themeName - Name of theme to apply
 * @param scope - Settings scope to save in
 */
function applyTheme(
  themeName: string,
  scope: SettingScope
): Promise<void>;

interface CustomTheme extends Theme {
  /** Theme type must be 'custom' */
  type: 'custom';

  /** Base theme to inherit from (optional) */
  extends?: string;
}

{
  "ui": {
    "customThemes": {
      "my-dark-theme": {
        "name": "My Dark Theme",
        "type": "custom",
        "primary": "#00d4ff",
        "secondary": "#ff6b6b",
        "background": "#1a1a1a",
        "foreground": "#e6e6e6",
        "colors": {
          "error": "#ff5555",
          "warning": "#f1fa8c",
          "success": "#50fa7b",
          "info": "#8be9fd"
        }
      },
      "corporate": {
        "name": "Corporate Theme",
        "type": "custom",
        "extends": "github-light",
        "primary": "#0366d6",
        "secondary": "#28a745"
      }
    }
  }
}

/**
 * Resolve theme inheritance chain
 * @param theme - Theme with potential inheritance
 * @param baseThemes - Available base themes
 * @returns Fully resolved theme
 */
function resolveThemeInheritance(
  theme: CustomTheme,
  baseThemes: Record<string, Theme>
): Theme;

interface UISettings {
  /** Active theme name */
  theme?: string;

  /** Custom theme definitions */
  customThemes?: Record<string, CustomTheme>;

  /** Theme-related UI options */
  hideWindowTitle?: boolean;
  showLineNumbers?: boolean;
  showCitations?: boolean;
}

/**
 * Detect appropriate theme based on environment
 * @returns Recommended theme name
 */
function detectEnvironmentTheme(): string;

// Environment detection logic
const environmentThemes = {
  /** NO_COLOR environment variable set */
  NO_COLOR: 'no-color',

  /** Cloud Shell environment */
  CLOUD_SHELL: 'ansi',

  /** Terminal with limited color support */
  LIMITED_COLORS: 'ansi-light'
};

interface ThemePickerOptions {
  /** Show theme previews */
  showPreview: boolean;

  /** Group themes by category */
  groupByType: boolean;

  /** Include custom themes */
  includeCustom: boolean;

  /** Current theme for highlighting */
  currentTheme: string;
}

/**
 * Display interactive theme picker
 * @param options - Picker configuration
 * @returns Selected theme name or null if cancelled
 */
function showThemePicker(
  options: ThemePickerOptions
): Promise<string | null>;

interface ThemePreview {
  /** Sample code with syntax highlighting */
  codeSnippet: string;

  /** UI elements preview */
  uiElements: string[];

  /** Color palette display */
  colorPalette: string;
}

/**
 * Generate theme preview
 * @param theme - Theme to preview
 * @returns Preview content
 */
function generateThemePreview(theme: Theme): ThemePreview;

interface AccessibilityTheme extends Theme {
  /** High contrast mode enabled */
  highContrast: boolean;

  /** Minimum contrast ratios */
  contrastRatios: {
    normal: number;
    large: number;
  };

  /** Screen reader optimizations */
  screenReaderOptimized: boolean;
}

/**
 * Validate theme accessibility
 * @param theme - Theme to validate
 * @returns Accessibility compliance report
 */
function validateThemeAccessibility(theme: Theme): {
  compliant: boolean;
  issues: string[];
  suggestions: string[];
};

/**
 * Adjust theme for color blindness
 * @param theme - Original theme
 * @param type - Color blindness type
 * @returns Adjusted theme
 */
function adjustThemeForColorBlindness(
  theme: Theme,
  type: 'protanopia' | 'deuteranopia' | 'tritanopia'
): Theme;

/**
 * Test theme color combinations
 * @param theme - Theme to test
 * @returns Color accessibility report
 */
function testThemeColorAccessibility(theme: Theme): {
  combinations: Array<{
    foreground: string;
    background: string;
    contrast: number;
    wcagLevel: 'AA' | 'AAA' | 'fail';
  }>;
};

/**
 * Create theme from color palette
 * @param name - Theme name
 * @param palette - Color palette
 * @param type - Theme type
 * @returns Generated theme
 */
function createThemeFromPalette(
  name: string,
  palette: {
    primary: string;
    secondary: string;
    background: string;
    foreground: string;
  },
  type: 'light' | 'dark'
): Theme;

/**
 * Generate theme variants
 * @param baseTheme - Base theme
 * @returns Theme variants (light/dark)
 */
function generateThemeVariants(baseTheme: Theme): {
  light: Theme;
  dark: Theme;
};

interface ThemeValidation {
  /** Validation success */
  valid: boolean;

  /** Validation errors */
  errors: string[];

  /** Validation warnings */
  warnings: string[];

  /** Missing required properties */
  missing: string[];
}

/**
 * Validate theme configuration
 * @param theme - Theme to validate
 * @returns Validation results
 */
function validateTheme(theme: Theme): ThemeValidation;

interface DynamicTheme extends Theme {
  /** Theme adapts to time of day */
  timeAdaptive: boolean;

  /** Theme adapts to system preference */
  systemAdaptive: boolean;

  /** Schedule for time-based switching */
  schedule?: {
    lightTheme: string;
    darkTheme: string;
    switchTimes: {
      toDark: string;    // "18:00"
      toLight: string;   // "06:00"
    };
  };
}

/**
 * Apply dynamic theme based on current conditions
 * @param dynamicTheme - Dynamic theme configuration
 * @returns Resolved theme name
 */
function resolveDynamicTheme(dynamicTheme: DynamicTheme): string;

/**
 * Export theme to file
 * @param theme - Theme to export
 * @param format - Export format
 * @returns Exported theme data
 */
function exportTheme(
  theme: Theme,
  format: 'json' | 'css' | 'scss'
): string;

/**
 * Import theme from file
 * @param data - Theme data
 * @param format - Import format
 * @returns Imported theme
 */
function importTheme(
  data: string,
  format: 'json' | 'css' | 'scss'
): Theme;

interface ThemePackage {
  /** Package metadata */
  name: string;
  version: string;
  author: string;
  description: string;

  /** Included themes */
  themes: Record<string, Theme>;

  /** Package tags */
  tags: string[];

  /** Download statistics */
  stats: {
    downloads: number;
    rating: number;
  };
}

/**
 * Browse available theme packages
 * @param query - Search query
 * @returns Available theme packages
 */
function browseThemePackages(
  query?: string
): Promise<ThemePackage[]>;

/**
 * Install theme package
 * @param packageName - Package to install
 * @param scope - Installation scope
 */
function installThemePackage(
  packageName: string,
  scope: SettingScope
): Promise<void>;