@mdxui/terminal 2.0.0

package/dist/theme/index.d.ts

@@ -0,0 +1,1339 @@
+import { z } from 'zod';
+
+/**
+ * ANSI Escape Code Constants
+ *
+ * Standard ANSI escape sequences for terminal text styling.
+ * These codes work in all terminals that support ANSI escape codes.
+ *
+ * @module
+ */
+/**
+ * ANSI escape code constants for terminal styling.
+ *
+ * Includes:
+ * - Reset code to clear all styles
+ * - Text styling (bold, dim, italic, underline, strikethrough)
+ * - Standard 8 foreground colors (black through white)
+ * - Bright variants of all 8 foreground colors
+ * - Standard 8 background colors
+ *
+ * @example
+ * ```tsx
+ * // Apply bold cyan text
+ * console.log(`${ANSI.bold}${ANSI.cyan}Hello${ANSI.reset}`)
+ *
+ * // Use with styled helper
+ * console.log(styled('Error!', ANSI.bold, ANSI.red))
+ * ```
+ */
+declare const ANSI: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly italic: "\u001B[3m";
+    readonly underline: "\u001B[4m";
+    readonly inverse: "\u001B[7m";
+    readonly strikethrough: "\u001B[9m";
+    readonly black: "\u001B[30m";
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly blue: "\u001B[34m";
+    readonly magenta: "\u001B[35m";
+    readonly cyan: "\u001B[36m";
+    readonly white: "\u001B[37m";
+    readonly brightBlack: "\u001B[90m";
+    readonly brightRed: "\u001B[91m";
+    readonly brightGreen: "\u001B[92m";
+    readonly brightYellow: "\u001B[93m";
+    readonly brightBlue: "\u001B[94m";
+    readonly brightMagenta: "\u001B[95m";
+    readonly brightCyan: "\u001B[96m";
+    readonly brightWhite: "\u001B[97m";
+    readonly bgBlack: "\u001B[40m";
+    readonly bgRed: "\u001B[41m";
+    readonly bgGreen: "\u001B[42m";
+    readonly bgYellow: "\u001B[43m";
+    readonly bgBlue: "\u001B[44m";
+    readonly bgMagenta: "\u001B[45m";
+    readonly bgCyan: "\u001B[46m";
+    readonly bgWhite: "\u001B[47m";
+    readonly bgBrightBlack: "\u001B[100m";
+    readonly bgBrightRed: "\u001B[101m";
+    readonly bgBrightGreen: "\u001B[102m";
+    readonly bgBrightYellow: "\u001B[103m";
+    readonly bgBrightBlue: "\u001B[104m";
+    readonly bgBrightMagenta: "\u001B[105m";
+    readonly bgBrightCyan: "\u001B[106m";
+    readonly bgBrightWhite: "\u001B[107m";
+};
+
+/**
+ * Parse hex color to RGB values.
+ *
+ * Handles edge cases:
+ * - Empty string returns black (0, 0, 0)
+ * - Invalid hex returns black (0, 0, 0)
+ * - Supports with/without # prefix
+ * - Supports 3-character shorthand (#fff)
+ */
+declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Options for RGB to ANSI conversion.
+ */
+interface RgbToAnsiOptions {
+    /** If true, generates background color code; otherwise foreground */
+    background?: boolean;
+}
+/**
+ * Converts RGB color values to an ANSI 256 escape sequence.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @param opts - Optional settings for background/foreground
+ * @returns ANSI escape sequence string
+ *
+ * @example
+ * ```tsx
+ * // Coral foreground color
+ * console.log(`${rgbToAnsi(255, 127, 80)}Coral text${ANSI.reset}`)
+ *
+ * // Blue background
+ * console.log(`${rgbToAnsi(0, 0, 255, { background: true })}Blue bg${ANSI.reset}`)
+ * ```
+ */
+declare function rgbToAnsi(r: number, g: number, b: number, opts?: RgbToAnsiOptions): string;
+/**
+ * Converts a hex color string to an ANSI 256 escape sequence.
+ *
+ * Supports both 3-character (#RGB) and 6-character (#RRGGBB) hex formats.
+ * The '#' prefix is optional.
+ *
+ * @param hex - Hex color string (e.g., '#ff7f50', 'ff7f50', '#f00')
+ * @param opts - Optional settings for background/foreground
+ * @returns ANSI escape sequence string
+ *
+ * @example
+ * ```tsx
+ * // Tomato red foreground
+ * console.log(`${hexToAnsi('#ff6347')}Tomato${ANSI.reset}`)
+ *
+ * // Short-form hex with background
+ * console.log(`${hexToAnsi('#f00', { background: true })}Red bg${ANSI.reset}`)
+ * ```
+ */
+declare function hexToAnsi(hex: string, opts?: RgbToAnsiOptions): string;
+/**
+ * Generate ANSI 256-color foreground escape code.
+ *
+ * @param n - ANSI 256 color code (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If n is not a valid ANSI 256 code (0-255)
+ */
+declare function ansi256(n: number): string;
+/**
+ * Generate ANSI 256-color background escape code.
+ *
+ * @param n - ANSI 256 color code (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If n is not a valid ANSI 256 code (0-255)
+ */
+declare function ansi256Bg(n: number): string;
+/**
+ * Generate true color (24-bit) foreground escape code.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If any component is not in range 0-255
+ */
+declare function rgb(r: number, g: number, b: number): string;
+/**
+ * Generate true color (24-bit) background escape code.
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If any component is not in range 0-255
+ */
+declare function rgbBg(r: number, g: number, b: number): string;
+/**
+ * Generate true color foreground from hex color.
+ *
+ * @param color - Hex color string (#RGB, RGB, #RRGGBB, or RRGGBB)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If color is not a valid hex color format
+ */
+declare function hex(color: string): string;
+/**
+ * Generate true color background from hex color.
+ *
+ * @param color - Hex color string (#RGB, RGB, #RRGGBB, or RRGGBB)
+ * @returns ANSI escape sequence string
+ * @throws {ZodError} If color is not a valid hex color format
+ */
+declare function hexBg(color: string): string;
+
+/**
+ * Tailwind CSS to ANSI Color Mapping
+ *
+ * Converts Tailwind CSS class names to ANSI escape sequences for terminal output.
+ * Supports text colors, background colors, and font styles.
+ *
+ * @module
+ */
+/**
+ * Tailwind color hex values for all standard colors and shades.
+ */
+declare const TAILWIND_COLORS: Record<string, Record<string, string>>;
+/**
+ * Converts a single Tailwind CSS class to an ANSI 256 escape sequence.
+ *
+ * Supports:
+ * - Text colors: `text-{color}-{shade}`, `text-white`, `text-black`
+ * - Background colors: `bg-{color}-{shade}`
+ * - Font styles: `font-bold`, `italic`, `underline`, `line-through`
+ *
+ * @param className - A single Tailwind CSS class name
+ * @returns ANSI escape sequence, or empty string if class is not recognized
+ *
+ * @example
+ * ```tsx
+ * const blue = tailwindToAnsi('text-blue-500')
+ * const bold = tailwindToAnsi('font-bold')
+ * console.log(`${blue}${bold}Styled text${ANSI.reset}`)
+ * ```
+ */
+declare function tailwindToAnsi(className: string): string;
+/**
+ * Converts multiple Tailwind CSS classes to ANSI escape codes.
+ *
+ * Takes a space-separated string of Tailwind classes and returns
+ * the combined ANSI escape codes.
+ *
+ * @deprecated Use {@link tailwindToAnsi} for single classes,
+ * or use the theme system for semantic colors.
+ *
+ * @param classes - Space-separated Tailwind class names
+ * @returns Combined ANSI escape codes
+ *
+ * @example
+ * ```tsx
+ * const codes = tailwindToTerminal('text-primary font-bold')
+ * console.log(`${codes}Styled text${ANSI.reset}`)
+ * ```
+ */
+declare function tailwindToTerminal(classes: string): string;
+
+/**
+ * Theme System
+ *
+ * Terminal theme creation, composition, and management utilities.
+ * Provides dark/light mode themes with semantic color tokens.
+ *
+ * All public APIs include runtime validation via Zod schemas.
+ *
+ * @module
+ */
+/**
+ * Color tokens for a terminal theme.
+ *
+ * All values are ANSI escape sequences that can be directly concatenated
+ * with text to apply styling.
+ */
+interface TerminalThemeColors {
+    /** Primary brand/accent color for key UI elements */
+    primary: string;
+    /** Secondary color for less prominent elements */
+    secondary: string;
+    /** Accent color for highlights and special elements */
+    accent: string;
+    /** Muted/dimmed color for less important text */
+    muted: string;
+    /** Success state indicator (green) */
+    success: string;
+    /** Warning state indicator (yellow/orange) */
+    warning: string;
+    /** Error state indicator (red) */
+    error: string;
+    /** Informational state indicator (blue) */
+    info: string;
+    /** Border/divider color */
+    border: string;
+    /** Background color (usually includes background escape) */
+    background: string;
+    /** Default text/foreground color */
+    foreground: string;
+    /** Selection/highlight background */
+    selection: string;
+    /** Focus indicator color */
+    focus: string;
+}
+/**
+ * A complete terminal theme with color mode and color tokens.
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * console.log(`${theme.colors.primary}Primary text${ANSI.reset}`)
+ * ```
+ */
+interface TerminalTheme {
+    /** Color mode: 'dark' or 'light' */
+    mode: 'dark' | 'light';
+    /** Color token values */
+    colors: TerminalThemeColors;
+}
+/**
+ * Legacy theme interface for backward compatibility.
+ *
+ * @deprecated Use {@link TerminalTheme} with {@link createTerminalTheme} instead.
+ */
+interface LegacyTerminalTheme {
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+}
+interface LegacyTerminalThemeWithExtras extends LegacyTerminalTheme {
+    typography?: {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    };
+    spacing?: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    };
+}
+/**
+ * Options for creating a terminal theme.
+ */
+interface CreateTerminalThemeOptions {
+    /** Color mode: 'dark' (default) or 'light' */
+    mode?: 'dark' | 'light';
+    /** Custom color overrides */
+    colors?: Partial<TerminalThemeColors>;
+}
+/**
+ * Creates a terminal theme with dark or light mode base colors.
+ *
+ * Provides sensible defaults for all color tokens based on the selected mode,
+ * with optional overrides for individual colors.
+ *
+ * @param options - Theme creation options
+ * @returns A complete terminal theme object
+ * @throws {ZodError} If options are invalid (invalid mode or color format)
+ *
+ * @example
+ * ```tsx
+ * // Dark theme with defaults
+ * const darkTheme = createTerminalTheme({ mode: 'dark' })
+ *
+ * // Light theme with custom primary color
+ * const customTheme = createTerminalTheme({
+ *   mode: 'light',
+ *   colors: { primary: '\x1b[38;5;27m' }
+ * })
+ * ```
+ */
+declare function createTerminalTheme(options: CreateTerminalThemeOptions): TerminalTheme;
+/**
+ * Gets a color value from a theme by its key name.
+ *
+ * @param theme - The terminal theme to get the color from
+ * @param key - The color key (e.g., 'primary', 'error')
+ * @param fallback - Optional fallback if the key is not found
+ * @returns The ANSI color escape sequence
+ * @throws If key is not found and no fallback is provided
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * const errorColor = getThemeColor(theme, 'error')
+ * console.log(`${errorColor}Error message${ANSI.reset}`)
+ * ```
+ */
+declare function getThemeColor(theme: TerminalTheme, key: keyof TerminalThemeColors, fallback?: string): string;
+/**
+ * Maps a CSS custom property name to its ANSI theme color.
+ *
+ * Useful for converting web-based CSS variable references to terminal colors.
+ *
+ * @param cssVar - CSS variable name (e.g., '--primary', '--error')
+ * @param theme - The terminal theme to look up colors from
+ * @returns ANSI escape sequence, or empty string if not found
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * const primary = cssVarToAnsi('--primary', theme)
+ * const error = cssVarToAnsi('--destructive', theme) // maps to error
+ * ```
+ */
+declare function cssVarToAnsi(cssVar: string, theme: TerminalTheme): string;
+/**
+ * Applies a theme color to text with automatic reset.
+ *
+ * A convenience function that wraps text with a theme color and
+ * appends the reset code.
+ *
+ * @param text - The text to style
+ * @param theme - The terminal theme to use
+ * @param styleKey - The theme color key to apply
+ * @returns Styled text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * const theme = createTerminalTheme({ mode: 'dark' })
+ * console.log(applyThemeStyles('Error!', theme, 'error'))
+ * console.log(applyThemeStyles('Success!', theme, 'success'))
+ * ```
+ */
+declare function applyThemeStyles(text: string, theme: TerminalTheme, styleKey: keyof TerminalThemeColors): string;
+declare const defaultTheme: LegacyTerminalThemeWithExtras;
+/**
+ * Named color constants matching theme semantic colors.
+ */
+declare const colors: {
+    primary: "\u001B[36m";
+    secondary: "\u001B[34m";
+    accent: "\u001B[35m";
+    muted: "\u001B[90m";
+    success: "\u001B[32m";
+    warning: "\u001B[33m";
+    error: "\u001B[31m";
+    info: "\u001B[34m";
+};
+/**
+ * Theme tokens for semantic access.
+ */
+declare const themeTokens: {
+    readonly primary: "primary";
+    readonly secondary: "secondary";
+    readonly accent: "accent";
+    readonly muted: "muted";
+    readonly success: "success";
+    readonly warning: "warning";
+    readonly error: "error";
+    readonly info: "info";
+};
+declare const darkTheme: LegacyTerminalThemeWithExtras;
+declare const lightTheme: LegacyTerminalThemeWithExtras;
+declare const highContrastTheme: LegacyTerminalThemeWithExtras;
+declare const themePresets: {
+    default: LegacyTerminalThemeWithExtras;
+    dark: LegacyTerminalThemeWithExtras;
+    light: LegacyTerminalThemeWithExtras;
+    highContrast: LegacyTerminalThemeWithExtras;
+};
+/**
+ * Creates a legacy theme with partial overrides from defaults.
+ *
+ * @deprecated Use {@link createTerminalTheme} for new code.
+ *
+ * @param partial - Partial theme overrides
+ * @returns Complete legacy theme with overrides applied
+ * @throws {ZodError} If any color value is not a valid ANSI escape sequence
+ *
+ * @example
+ * ```tsx
+ * const theme = createTheme({
+ *   primary: ANSI.brightGreen,
+ *   error: ANSI.brightRed,
+ * })
+ * ```
+ */
+declare function createTheme(partial: Partial<LegacyTerminalThemeWithExtras>): LegacyTerminalThemeWithExtras;
+/**
+ * Extends a base theme with overrides.
+ *
+ * Performs a deep merge of the override values onto the base theme,
+ * allowing nested properties (like typography, spacing) to be
+ * partially overridden.
+ *
+ * @param base - The base theme to extend
+ * @param overrides - Values to override in the base theme
+ * @returns New theme with overrides applied
+ *
+ * @example
+ * ```tsx
+ * const customTheme = extendTheme(defaultTheme, {
+ *   primary: ANSI.brightMagenta,
+ *   typography: { headingWeight: 'bold' },
+ * })
+ * ```
+ */
+declare function extendTheme<T extends LegacyTerminalThemeWithExtras>(base: T, overrides: Partial<T> & Record<string, unknown>): T & Record<string, unknown>;
+/**
+ * Composes multiple theme objects into one.
+ *
+ * Later themes in the argument list override values from earlier themes.
+ * Useful for building up themes from multiple partial configurations.
+ *
+ * @param themes - Theme objects to compose (later overrides earlier)
+ * @returns Merged theme object
+ *
+ * @example
+ * ```tsx
+ * const theme = composeThemes(
+ *   baseTheme,
+ *   brandColorOverrides,
+ *   userPreferences
+ * )
+ * ```
+ */
+declare function composeThemes<T extends Record<string, unknown>>(...themes: T[]): T;
+/**
+ * Creates a named theme variant from a base theme.
+ *
+ * Convenience function for creating theme variants. The name parameter
+ * is currently unused but reserved for future theme registry features.
+ *
+ * @param base - The base theme to start from
+ * @param _name - Name for the variant (reserved for future use)
+ * @param overrides - Values to override in the base theme
+ * @returns New theme variant
+ *
+ * @example
+ * ```tsx
+ * const warningTheme = createThemeVariant(defaultTheme, 'warning', {
+ *   primary: ANSI.yellow,
+ *   accent: ANSI.brightYellow,
+ * })
+ * ```
+ */
+declare function createThemeVariant(base: LegacyTerminalThemeWithExtras, _name: string, overrides: Partial<LegacyTerminalThemeWithExtras>): LegacyTerminalThemeWithExtras;
+/**
+ * Detect system color scheme preference (dark/light)
+ */
+declare function detectColorScheme(): 'dark' | 'light';
+
+/**
+ * Text Styling Utilities
+ *
+ * Functions for applying ANSI styles to text with automatic reset.
+ * Includes semantic color helpers and compound style application.
+ *
+ * @module
+ */
+
+/**
+ * Applies a foreground color to text with automatic reset.
+ *
+ * Accepts either a semantic color name ('primary', 'error', etc.) or
+ * a raw ANSI escape sequence.
+ *
+ * @param colorName - Semantic color name or ANSI escape sequence
+ * @param text - The text to colorize
+ * @returns Colored text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * console.log(fg('error', 'Something went wrong'))
+ * console.log(fg('success', 'Operation completed'))
+ * console.log(fg(ANSI.brightCyan, 'Custom color'))
+ * ```
+ */
+declare function fg(colorName: keyof typeof colors | string, text: string): string;
+/**
+ * Applies a background color to text with automatic reset.
+ *
+ * Accepts either a semantic color name ('primary', 'error', etc.) or
+ * a raw ANSI escape sequence.
+ *
+ * @param colorName - Semantic color name or ANSI escape sequence
+ * @param text - The text to highlight
+ * @returns Highlighted text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * console.log(bg('error', 'ALERT'))
+ * console.log(bg('success', ' OK '))
+ * ```
+ */
+declare function bg(colorName: keyof typeof colors | string, text: string): string;
+/**
+ * Applies bold styling to text.
+ *
+ * @param text - The text to make bold
+ * @returns Bold text with ANSI codes
+ */
+declare function bold(text: string): string;
+/**
+ * Applies dim/faint styling to text.
+ *
+ * @param text - The text to dim
+ * @returns Dimmed text with ANSI codes
+ */
+declare function dim(text: string): string;
+/**
+ * Applies italic styling to text.
+ *
+ * Note: Not all terminals support italic text.
+ *
+ * @param text - The text to italicize
+ * @returns Italic text with ANSI codes
+ */
+declare function italic(text: string): string;
+/**
+ * Applies underline styling to text.
+ *
+ * @param text - The text to underline
+ * @returns Underlined text with ANSI codes
+ */
+declare function underline(text: string): string;
+/**
+ * Applies strikethrough styling to text.
+ *
+ * Note: Not all terminals support strikethrough text.
+ *
+ * @param text - The text to strike through
+ * @returns Strikethrough text with ANSI codes
+ */
+declare function strikethrough(text: string): string;
+/**
+ * Applies multiple style modifiers to text.
+ *
+ * Accepts an array of modifier names (e.g., 'bold', 'red', 'underline')
+ * and applies all of them to the text.
+ *
+ * @param text - The text to style
+ * @param modifiers - Array of modifier names
+ * @returns Styled text with ANSI codes
+ *
+ * @example
+ * ```tsx
+ * console.log(style('Important', ['bold', 'red', 'underline']))
+ * console.log(style('Info', ['cyan', 'italic']))
+ * ```
+ */
+declare function style(text: string, modifiers: string[]): string;
+/**
+ * Wraps text with ANSI escape codes and automatically appends reset.
+ *
+ * The primary utility for applying multiple ANSI styles to text.
+ * Accepts any number of ANSI escape code strings.
+ *
+ * @param text - The text to style (returns empty string if null/undefined)
+ * @param codes - ANSI escape code strings to apply
+ * @returns Styled text with reset appended
+ *
+ * @example
+ * ```tsx
+ * // Bold cyan text
+ * console.log(styled('Hello', ANSI.bold, ANSI.cyan))
+ *
+ * // Error styling
+ * console.log(styled('Error!', ANSI.bold, ANSI.red, ANSI.bgBlack))
+ * ```
+ */
+declare function styled(text: string, ...codes: string[]): string;
+
+/**
+ * Color Support Detection and Degradation
+ *
+ * Utilities for detecting terminal color capabilities and
+ * gracefully degrading colors for limited terminals.
+ *
+ * @module
+ */
+/**
+ * Level of color support in the terminal.
+ *
+ * - `'none'` - No color support (monochrome)
+ * - `'16'` - Basic 16 ANSI colors
+ * - `'256'` - Extended 256 color palette
+ * - `'truecolor'` - Full 24-bit RGB color support
+ */
+type ColorSupport = 'none' | '16' | '256' | 'truecolor';
+/**
+ * Detects the terminal's color support level.
+ *
+ * Checks environment variables in this order:
+ * 1. `NO_COLOR` - Forces no color support
+ * 2. `FORCE_COLOR` - Forces a specific color level (0-3)
+ * 3. `COLORTERM` - Checks for truecolor support
+ * 4. `TERM` - Checks terminal type for color hints
+ *
+ * @returns The detected color support level
+ *
+ * @example
+ * ```tsx
+ * const support = detectColorSupport()
+ * if (support === 'truecolor') {
+ *   // Use full RGB colors
+ * } else if (support === '256') {
+ *   // Use 256 color palette
+ * }
+ * ```
+ */
+declare function detectColorSupport(): ColorSupport;
+/**
+ * Degrades an ANSI color to work with limited terminal color support.
+ *
+ * Automatically converts colors down to simpler formats:
+ * - Truecolor to 256 colors
+ * - 256 colors to 16 basic colors
+ * - Any color to nothing if support is 'none'
+ *
+ * @param ansi - Original ANSI escape sequence
+ * @param support - Target color support level
+ * @returns Degraded ANSI escape sequence, or empty string for 'none'
+ *
+ * @example
+ * ```tsx
+ * const trueColorBlue = '\x1b[38;2;100;150;200m'
+ * const support = detectColorSupport()
+ *
+ * // Automatically degrade for the current terminal
+ * const blue = degradeColor(trueColorBlue, support)
+ * ```
+ */
+declare function degradeColor(ansi: string, support: ColorSupport): string;
+/**
+ * Adapts a color based on terminal support level.
+ *
+ * Alias for {@link degradeColor} - use this when the intent is to
+ * "adapt" colors for the current terminal rather than "degrade" them.
+ *
+ * @param color - ANSI color escape sequence
+ * @param level - Target color support level
+ * @returns Adapted color escape sequence
+ *
+ * @example
+ * ```tsx
+ * const support = detectColorSupport()
+ * const color = adaptColor(theme.primary, support)
+ * ```
+ */
+declare function adaptColor(color: string, level: ColorSupport): string;
+
+/**
+ * ANSI Stripping Utilities
+ *
+ * Functions for removing ANSI escape codes from text and
+ * calculating visible text length.
+ *
+ * @module
+ */
+/**
+ * Strips all ANSI escape codes from text.
+ *
+ * Useful for getting the visible content of styled text or
+ * calculating accurate string lengths.
+ *
+ * @param text - Text potentially containing ANSI escape codes
+ * @returns Plain text with all ANSI codes removed, or empty string for null/undefined
+ *
+ * @example
+ * ```tsx
+ * const styled = bold(fg('cyan', 'Hello'))
+ * const plain = stripAnsi(styled) // 'Hello'
+ * ```
+ */
+declare function stripAnsi(text: string): string;
+/**
+ * Calculates the visible length of text (excluding ANSI codes).
+ *
+ * Essential for terminal UI layout calculations where you need
+ * to know how many characters will actually be displayed.
+ *
+ * @param text - Text potentially containing ANSI escape codes
+ * @returns Number of visible characters
+ *
+ * @example
+ * ```tsx
+ * const styled = bold(fg('cyan', 'Hello'))
+ * const len = visibleLength(styled) // 5
+ * ```
+ */
+declare function visibleLength(text: string): number;
+
+/**
+ * Box Drawing Characters
+ *
+ * Unicode box-drawing character sets for terminal UI borders
+ * and utility functions for drawing boxes.
+ *
+ * @module
+ */
+/**
+ * Unicode box-drawing character sets for terminal UI borders.
+ *
+ * Provides three styles:
+ * - `single` - Standard single-line borders (┌─┐│└┘)
+ * - `double` - Double-line borders (╔═╗║╚╝)
+ * - `rounded` - Single-line with rounded corners (╭─╮│╰╯)
+ *
+ * Each set includes:
+ * - Corner characters (topLeft, topRight, bottomLeft, bottomRight)
+ * - Line characters (horizontal, vertical)
+ * - T-junction characters (teeLeft, teeRight, teeTop, teeBottom)
+ * - Cross character (cross)
+ *
+ * @example
+ * ```tsx
+ * const chars = boxChars.single
+ * const top = chars.topLeft + chars.horizontal.repeat(10) + chars.topRight
+ * // Outputs: ┌──────────┐
+ * ```
+ */
+declare const boxChars: {
+    readonly single: {
+        readonly topLeft: "┌";
+        readonly topRight: "┐";
+        readonly bottomLeft: "└";
+        readonly bottomRight: "┘";
+        readonly horizontal: "─";
+        readonly vertical: "│";
+        readonly teeLeft: "├";
+        readonly teeRight: "┤";
+        readonly teeTop: "┬";
+        readonly teeBottom: "┴";
+        readonly cross: "┼";
+    };
+    readonly double: {
+        readonly topLeft: "╔";
+        readonly topRight: "╗";
+        readonly bottomLeft: "╚";
+        readonly bottomRight: "╝";
+        readonly horizontal: "═";
+        readonly vertical: "║";
+        readonly teeLeft: "╠";
+        readonly teeRight: "╣";
+        readonly teeTop: "╦";
+        readonly teeBottom: "╩";
+        readonly cross: "╬";
+    };
+    readonly rounded: {
+        readonly topLeft: "╭";
+        readonly topRight: "╮";
+        readonly bottomLeft: "╰";
+        readonly bottomRight: "╯";
+        readonly horizontal: "─";
+        readonly vertical: "│";
+        readonly teeLeft: "├";
+        readonly teeRight: "┤";
+        readonly teeTop: "┬";
+        readonly teeBottom: "┴";
+        readonly cross: "┼";
+    };
+};
+/**
+ * Available box drawing styles.
+ * - `'single'` - Standard single-line borders
+ * - `'double'` - Double-line borders
+ * - `'rounded'` - Single-line with rounded corners
+ */
+type BoxStyle = keyof typeof boxChars;
+/**
+ * Draws a box with specified style and dimensions.
+ *
+ * Creates an array of strings representing each line of the box.
+ * The box is hollow (empty inside) and can be used as a container
+ * for content in terminal UIs.
+ *
+ * @param width - Total width of the box including borders
+ * @param height - Total height of the box including borders
+ * @param style - Box style ('single', 'double', or 'rounded')
+ * @returns Array of strings, one per line of the box
+ *
+ * @example
+ * ```tsx
+ * const box = drawBox(20, 5, 'rounded')
+ * box.forEach(line => console.log(line))
+ * // ╭──────────────────╮
+ * // │                  │
+ * // │                  │
+ * // │                  │
+ * // ╰──────────────────╯
+ * ```
+ */
+declare function drawBox(width: number, height: number, style?: BoxStyle): string[];
+
+/**
+ * Zod Schemas for Runtime Validation
+ *
+ * Provides Zod schemas for validating public API inputs at runtime.
+ * These schemas ensure type safety beyond TypeScript's compile-time checks.
+ *
+ * @module
+ */
+
+/**
+ * Schema for hex color strings.
+ *
+ * Accepts:
+ * - 3-character hex: #RGB or RGB
+ * - 6-character hex: #RRGGBB or RRGGBB
+ *
+ * @example
+ * ```tsx
+ * HexColorSchema.parse('#ff0000')  // Valid
+ * HexColorSchema.parse('ff0000')   // Valid
+ * HexColorSchema.parse('#f00')     // Valid
+ * HexColorSchema.parse('invalid')  // Throws ZodError
+ * ```
+ */
+declare const HexColorSchema: z.ZodString;
+/**
+ * Schema for RGB component values (0-255).
+ */
+declare const RgbComponentSchema: z.ZodNumber;
+/**
+ * Schema for RGB color object.
+ */
+declare const RgbColorSchema: z.ZodObject<{
+    r: z.ZodNumber;
+    g: z.ZodNumber;
+    b: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    b: number;
+    g: number;
+    r: number;
+}, {
+    b: number;
+    g: number;
+    r: number;
+}>;
+/**
+ * Schema for ANSI 256 color codes (0-255).
+ */
+declare const Ansi256CodeSchema: z.ZodNumber;
+/**
+ * Schema for ANSI escape sequence strings.
+ * Validates that a string is a valid ANSI escape sequence.
+ *
+ * Accepts:
+ * - Empty string (valid for 'no color')
+ * - ANSI escape sequences like \x1b[38;5;33m
+ */
+declare const AnsiEscapeSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Schema for theme color mode.
+ */
+declare const ThemeModeSchema: z.ZodEnum<["dark", "light"]>;
+/**
+ * Schema for terminal theme colors.
+ * All values are ANSI escape sequences.
+ */
+declare const TerminalThemeColorsSchema: z.ZodObject<{
+    primary: z.ZodEffects<z.ZodString, string, string>;
+    secondary: z.ZodEffects<z.ZodString, string, string>;
+    accent: z.ZodEffects<z.ZodString, string, string>;
+    muted: z.ZodEffects<z.ZodString, string, string>;
+    success: z.ZodEffects<z.ZodString, string, string>;
+    warning: z.ZodEffects<z.ZodString, string, string>;
+    error: z.ZodEffects<z.ZodString, string, string>;
+    info: z.ZodEffects<z.ZodString, string, string>;
+    border: z.ZodEffects<z.ZodString, string, string>;
+    background: z.ZodEffects<z.ZodString, string, string>;
+    foreground: z.ZodEffects<z.ZodString, string, string>;
+    selection: z.ZodEffects<z.ZodString, string, string>;
+    focus: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+}, {
+    error: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+}>;
+/**
+ * Schema for CreateTerminalThemeOptions.
+ */
+declare const CreateTerminalThemeOptionsSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<["dark", "light"]>>;
+    colors: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        secondary: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        accent: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        muted: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        success: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        warning: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        error: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        info: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        border: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        background: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        foreground: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        selection: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        focus: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        error?: string | undefined;
+        primary?: string | undefined;
+        secondary?: string | undefined;
+        accent?: string | undefined;
+        muted?: string | undefined;
+        success?: string | undefined;
+        warning?: string | undefined;
+        info?: string | undefined;
+        border?: string | undefined;
+        background?: string | undefined;
+        foreground?: string | undefined;
+        selection?: string | undefined;
+        focus?: string | undefined;
+    }, {
+        error?: string | undefined;
+        primary?: string | undefined;
+        secondary?: string | undefined;
+        accent?: string | undefined;
+        muted?: string | undefined;
+        success?: string | undefined;
+        warning?: string | undefined;
+        info?: string | undefined;
+        border?: string | undefined;
+        background?: string | undefined;
+        foreground?: string | undefined;
+        selection?: string | undefined;
+        focus?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    mode?: "light" | "dark" | undefined;
+    colors?: {
+        error?: string | undefined;
+        primary?: string | undefined;
+        secondary?: string | undefined;
+        accent?: string | undefined;
+        muted?: string | undefined;
+        success?: string | undefined;
+        warning?: string | undefined;
+        info?: string | undefined;
+        border?: string | undefined;
+        background?: string | undefined;
+        foreground?: string | undefined;
+        selection?: string | undefined;
+        focus?: string | undefined;
+    } | undefined;
+}, {
+    mode?: "light" | "dark" | undefined;
+    colors?: {
+        error?: string | undefined;
+        primary?: string | undefined;
+        secondary?: string | undefined;
+        accent?: string | undefined;
+        muted?: string | undefined;
+        success?: string | undefined;
+        warning?: string | undefined;
+        info?: string | undefined;
+        border?: string | undefined;
+        background?: string | undefined;
+        foreground?: string | undefined;
+        selection?: string | undefined;
+        focus?: string | undefined;
+    } | undefined;
+}>;
+/**
+ * Schema for legacy terminal theme.
+ */
+declare const LegacyTerminalThemeSchema: z.ZodObject<{
+    primary: z.ZodEffects<z.ZodString, string, string>;
+    secondary: z.ZodEffects<z.ZodString, string, string>;
+    accent: z.ZodEffects<z.ZodString, string, string>;
+    muted: z.ZodEffects<z.ZodString, string, string>;
+    success: z.ZodEffects<z.ZodString, string, string>;
+    warning: z.ZodEffects<z.ZodString, string, string>;
+    error: z.ZodEffects<z.ZodString, string, string>;
+    info: z.ZodEffects<z.ZodString, string, string>;
+    border: z.ZodEffects<z.ZodString, string, string>;
+    background: z.ZodEffects<z.ZodString, string, string>;
+    foreground: z.ZodEffects<z.ZodString, string, string>;
+    selection: z.ZodEffects<z.ZodString, string, string>;
+    focus: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+}, {
+    error: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+}>;
+/**
+ * Schema for legacy terminal theme with extras.
+ */
+declare const LegacyTerminalThemeWithExtrasSchema: z.ZodObject<{
+    primary: z.ZodEffects<z.ZodString, string, string>;
+    secondary: z.ZodEffects<z.ZodString, string, string>;
+    accent: z.ZodEffects<z.ZodString, string, string>;
+    muted: z.ZodEffects<z.ZodString, string, string>;
+    success: z.ZodEffects<z.ZodString, string, string>;
+    warning: z.ZodEffects<z.ZodString, string, string>;
+    error: z.ZodEffects<z.ZodString, string, string>;
+    info: z.ZodEffects<z.ZodString, string, string>;
+    border: z.ZodEffects<z.ZodString, string, string>;
+    background: z.ZodEffects<z.ZodString, string, string>;
+    foreground: z.ZodEffects<z.ZodString, string, string>;
+    selection: z.ZodEffects<z.ZodString, string, string>;
+    focus: z.ZodEffects<z.ZodString, string, string>;
+} & {
+    typography: z.ZodOptional<z.ZodObject<{
+        headingWeight: z.ZodString;
+        bodyWeight: z.ZodString;
+        codeFont: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    }, {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    }>>;
+    spacing: z.ZodOptional<z.ZodObject<{
+        xs: z.ZodNumber;
+        sm: z.ZodNumber;
+        md: z.ZodNumber;
+        lg: z.ZodNumber;
+        xl: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    }, {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+    typography?: {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    } | undefined;
+    spacing?: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    } | undefined;
+}, {
+    error: string;
+    primary: string;
+    secondary: string;
+    accent: string;
+    muted: string;
+    success: string;
+    warning: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+    selection: string;
+    focus: string;
+    typography?: {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    } | undefined;
+    spacing?: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    } | undefined;
+}>;
+/**
+ * Schema for createTheme() function input (partial legacy theme).
+ */
+declare const CreateThemeInputSchema: z.ZodObject<{
+    primary: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    secondary: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    accent: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    muted: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    success: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    warning: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    error: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    info: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    border: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    background: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    foreground: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    selection: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    focus: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    typography: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        headingWeight: z.ZodString;
+        bodyWeight: z.ZodString;
+        codeFont: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    }, {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    }>>>;
+    spacing: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        xs: z.ZodNumber;
+        sm: z.ZodNumber;
+        md: z.ZodNumber;
+        lg: z.ZodNumber;
+        xl: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    }, {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    error?: string | undefined;
+    primary?: string | undefined;
+    secondary?: string | undefined;
+    accent?: string | undefined;
+    muted?: string | undefined;
+    success?: string | undefined;
+    warning?: string | undefined;
+    info?: string | undefined;
+    border?: string | undefined;
+    background?: string | undefined;
+    foreground?: string | undefined;
+    selection?: string | undefined;
+    focus?: string | undefined;
+    typography?: {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    } | undefined;
+    spacing?: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    } | undefined;
+}, {
+    error?: string | undefined;
+    primary?: string | undefined;
+    secondary?: string | undefined;
+    accent?: string | undefined;
+    muted?: string | undefined;
+    success?: string | undefined;
+    warning?: string | undefined;
+    info?: string | undefined;
+    border?: string | undefined;
+    background?: string | undefined;
+    foreground?: string | undefined;
+    selection?: string | undefined;
+    focus?: string | undefined;
+    typography?: {
+        headingWeight: string;
+        bodyWeight: string;
+        codeFont: string;
+    } | undefined;
+    spacing?: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    } | undefined;
+}>;
+/**
+ * Schema for RGB to ANSI conversion options.
+ */
+declare const RgbToAnsiOptionsSchema: z.ZodObject<{
+    background: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    background?: boolean | undefined;
+}, {
+    background?: boolean | undefined;
+}>;
+/**
+ * Schema for color support levels.
+ */
+declare const ColorSupportSchema: z.ZodEnum<["none", "16", "256", "truecolor"]>;
+type HexColor = z.infer<typeof HexColorSchema>;
+type RgbColor = z.infer<typeof RgbColorSchema>;
+type Ansi256Code = z.infer<typeof Ansi256CodeSchema>;
+type ThemeMode = z.infer<typeof ThemeModeSchema>;
+type CreateTerminalThemeOptionsInput = z.infer<typeof CreateTerminalThemeOptionsSchema>;
+type CreateThemeInput = z.infer<typeof CreateThemeInputSchema>;
+
+export { ANSI, type Ansi256Code, Ansi256CodeSchema, AnsiEscapeSchema, type BoxStyle, type ColorSupport, ColorSupportSchema, type CreateTerminalThemeOptions, type CreateTerminalThemeOptionsInput, CreateTerminalThemeOptionsSchema, type CreateThemeInput, CreateThemeInputSchema, type HexColor, HexColorSchema, type LegacyTerminalTheme, LegacyTerminalThemeSchema, type LegacyTerminalThemeWithExtras, LegacyTerminalThemeWithExtrasSchema, type RgbColor, RgbColorSchema, RgbComponentSchema, type RgbToAnsiOptions, RgbToAnsiOptionsSchema, TAILWIND_COLORS, type TerminalTheme, type TerminalThemeColors, TerminalThemeColorsSchema, type ThemeMode, ThemeModeSchema, adaptColor, ansi256, ansi256Bg, applyThemeStyles, bg, bold, boxChars, colors, composeThemes, createTerminalTheme, createTheme, createThemeVariant, cssVarToAnsi, darkTheme, defaultTheme, degradeColor, detectColorScheme, detectColorSupport, dim, drawBox, extendTheme, fg, getThemeColor, hex, hexBg, hexToAnsi, hexToRgb, highContrastTheme, italic, lightTheme, rgb, rgbBg, rgbToAnsi, strikethrough, stripAnsi, style, styled, tailwindToAnsi, tailwindToTerminal, themePresets, themeTokens, underline, visibleLength };