blecsd 0.6.0 → 0.6.2

package/dist/blend-BZDmQFAm.d.ts

@@ -0,0 +1,1215 @@
+import { z } from 'zod';
+
+/**
+ * 256-color palette definitions and types
+ * @module terminal/colors/palette
+ */
+
+/**
+ * Branded type for 256-color palette indices (0-255).
+ * Prevents accidentally passing arbitrary numbers where color indices are expected.
+ *
+ * @example
+ * ```typescript
+ * import { Color256, isColor256 } from 'blecsd';
+ *
+ * const color: Color256 = 196 as Color256; // Red
+ * if (isColor256(userInput)) {
+ *   // Safe to use as color index
+ * }
+ * ```
+ */
+type Color256 = number & {
+    readonly __brand: 'Color256';
+};
+/**
+ * RGB color representation with values from 0-255.
+ *
+ * @example
+ * ```typescript
+ * import type { RGB } from 'blecsd';
+ *
+ * const red: RGB = { r: 255, g: 0, b: 0 };
+ * ```
+ */
+interface RGB {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+/**
+ * RGBA color with alpha channel (0-1).
+ *
+ * @example
+ * ```typescript
+ * import type { RGBA } from 'blecsd';
+ *
+ * const semiTransparentRed: RGBA = { r: 255, g: 0, b: 0, a: 0.5 };
+ * ```
+ */
+interface RGBA extends RGB {
+    readonly a: number;
+}
+/**
+ * HSL color representation.
+ * - h: Hue (0-360)
+ * - s: Saturation (0-100)
+ * - l: Lightness (0-100)
+ *
+ * @example
+ * ```typescript
+ * import type { HSL } from 'blecsd';
+ *
+ * const red: HSL = { h: 0, s: 100, l: 50 };
+ * ```
+ */
+interface HSL {
+    readonly h: number;
+    readonly s: number;
+    readonly l: number;
+}
+/**
+ * HSLA color with alpha channel.
+ */
+interface HSLA extends HSL {
+    readonly a: number;
+}
+/**
+ * Schema for validating 256-color palette indices.
+ *
+ * @example
+ * ```typescript
+ * import { Color256Schema } from 'blecsd';
+ *
+ * const result = Color256Schema.safeParse(196);
+ * if (result.success) {
+ *   console.log('Valid color:', result.data);
+ * }
+ * ```
+ */
+declare const Color256Schema: z.ZodPipe<z.ZodNumber, z.ZodTransform<Color256, number>>;
+/**
+ * Schema for RGB color objects.
+ *
+ * @example
+ * ```typescript
+ * import { RGBSchema } from 'blecsd';
+ *
+ * const result = RGBSchema.safeParse({ r: 255, g: 128, b: 0 });
+ * ```
+ */
+declare const RGBSchema: z.ZodObject<{
+    r: z.ZodNumber;
+    g: z.ZodNumber;
+    b: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Schema for RGBA color objects.
+ */
+declare const RGBASchema: z.ZodObject<{
+    r: z.ZodNumber;
+    g: z.ZodNumber;
+    b: z.ZodNumber;
+    a: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Schema for HSL color objects.
+ */
+declare const HSLSchema: z.ZodObject<{
+    h: z.ZodNumber;
+    s: z.ZodNumber;
+    l: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Schema for HSLA color objects.
+ */
+declare const HSLASchema: z.ZodObject<{
+    h: z.ZodNumber;
+    s: z.ZodNumber;
+    l: z.ZodNumber;
+    a: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Schema for hex color strings (#RGB, #RRGGBB, or #RRGGBBAA).
+ *
+ * @example
+ * ```typescript
+ * import { HexColorSchema } from 'blecsd';
+ *
+ * HexColorSchema.parse('#ff0000'); // Valid
+ * HexColorSchema.parse('#f00');    // Valid (shorthand)
+ * HexColorSchema.parse('#ff000080'); // Valid (with alpha)
+ * ```
+ */
+declare const HexColorSchema: z.ZodString;
+/**
+ * Checks if a number is a valid 256-color palette index.
+ *
+ * @param value - The value to check
+ * @returns True if value is a valid Color256
+ *
+ * @example
+ * ```typescript
+ * import { isColor256 } from 'blecsd';
+ *
+ * if (isColor256(userInput)) {
+ *   // userInput is now typed as Color256
+ * }
+ * ```
+ */
+declare function isColor256(value: unknown): value is Color256;
+/**
+ * Asserts that a number is a valid Color256 and returns it typed.
+ * Throws if invalid.
+ *
+ * @param value - The value to convert
+ * @returns The value as Color256
+ * @throws Error if value is not a valid color index
+ *
+ * @example
+ * ```typescript
+ * import { asColor256 } from 'blecsd';
+ *
+ * const color = asColor256(196); // Returns 196 as Color256
+ * asColor256(256); // Throws Error
+ * ```
+ */
+declare function asColor256(value: number): Color256;
+/**
+ * Type guard for RGB objects.
+ */
+declare function isRGB(value: unknown): value is RGB;
+/**
+ * Complete 256-color palette as RGB values.
+ * - Indices 0-15: Standard ANSI colors
+ * - Indices 16-231: 6x6x6 color cube
+ * - Indices 232-255: 24-step grayscale
+ *
+ * @example
+ * ```typescript
+ * import { PALETTE_RGB } from 'blecsd';
+ *
+ * const red = PALETTE_RGB[9]; // { r: 255, g: 0, b: 0 }
+ * const gray = PALETTE_RGB[240]; // Grayscale value
+ * ```
+ */
+declare const PALETTE_RGB: readonly RGB[];
+/**
+ * Complete 256-color palette as hex strings.
+ *
+ * @example
+ * ```typescript
+ * import { PALETTE_HEX } from 'blecsd';
+ *
+ * const red = PALETTE_HEX[9]; // '#ff0000'
+ * ```
+ */
+declare const PALETTE_HEX: readonly string[];
+/**
+ * Get the RGB value for a 256-color palette index.
+ *
+ * @param color - The palette index (0-255)
+ * @returns The RGB color value
+ *
+ * @example
+ * ```typescript
+ * import { getRGB } from 'blecsd';
+ *
+ * const rgb = getRGB(196 as Color256);
+ * console.log(rgb); // { r: 255, g: 0, b: 95 }
+ * ```
+ */
+declare function getRGB(color: Color256): RGB;
+/**
+ * Get the hex string for a 256-color palette index.
+ *
+ * @param color - The palette index (0-255)
+ * @returns The hex color string
+ *
+ * @example
+ * ```typescript
+ * import { getHex } from 'blecsd';
+ *
+ * const hex = getHex(196 as Color256);
+ * console.log(hex); // '#ff005f'
+ * ```
+ */
+declare function getHex(color: Color256): string;
+/**
+ * The 6 intensity levels used in the 256-color cube.
+ */
+declare const COLOR_CUBE_LEVELS: readonly [0, 95, 135, 175, 215, 255];
+/**
+ * Get the color cube index for given R, G, B levels (0-5 each).
+ *
+ * @param r - Red level (0-5)
+ * @param g - Green level (0-5)
+ * @param b - Blue level (0-5)
+ * @returns The palette index (16-231)
+ *
+ * @example
+ * ```typescript
+ * import { colorCubeIndex } from 'blecsd';
+ *
+ * const index = colorCubeIndex(5, 0, 1); // Bright red with slight blue
+ * ```
+ */
+declare function colorCubeIndex(r: number, g: number, b: number): Color256;
+/**
+ * Get the grayscale palette index for a given step (0-23).
+ *
+ * @param step - Grayscale step (0-23, where 0 is darkest)
+ * @returns The palette index (232-255)
+ *
+ * @example
+ * ```typescript
+ * import { grayscaleIndex } from 'blecsd';
+ *
+ * const darkGray = grayscaleIndex(5);
+ * const lightGray = grayscaleIndex(20);
+ * ```
+ */
+declare function grayscaleIndex(step: number): Color256;
+/**
+ * Check if a palette index is in the standard color range (0-15).
+ */
+declare function isStandardColor(color: Color256): boolean;
+/**
+ * Check if a palette index is in the color cube range (16-231).
+ */
+declare function isColorCube(color: Color256): boolean;
+/**
+ * Check if a palette index is in the grayscale range (232-255).
+ */
+declare function isGrayscale(color: Color256): boolean;
+/**
+ * Named constants for the 16 standard ANSI colors.
+ *
+ * @example
+ * ```typescript
+ * import { COLORS } from 'blecsd';
+ *
+ * const fg = COLORS.RED;
+ * const bg = COLORS.BLACK;
+ * ```
+ */
+declare const COLORS: {
+    readonly BLACK: Color256;
+    readonly MAROON: Color256;
+    readonly GREEN: Color256;
+    readonly OLIVE: Color256;
+    readonly NAVY: Color256;
+    readonly PURPLE: Color256;
+    readonly TEAL: Color256;
+    readonly SILVER: Color256;
+    readonly GRAY: Color256;
+    readonly RED: Color256;
+    readonly LIME: Color256;
+    readonly YELLOW: Color256;
+    readonly BLUE: Color256;
+    readonly FUCHSIA: Color256;
+    readonly CYAN: Color256;
+    readonly WHITE: Color256;
+};
+/**
+ * Alias for standard colors using common terminal names.
+ */
+declare const ANSI: {
+    readonly DARK_GRAY: Color256;
+    readonly LIGHT_GRAY: Color256;
+    readonly BRIGHT_RED: Color256;
+    readonly BRIGHT_GREEN: Color256;
+    readonly BRIGHT_YELLOW: Color256;
+    readonly BRIGHT_BLUE: Color256;
+    readonly BRIGHT_MAGENTA: Color256;
+    readonly BRIGHT_CYAN: Color256;
+    readonly MAGENTA: Color256;
+    readonly DARK_RED: Color256;
+    readonly DARK_GREEN: Color256;
+    readonly DARK_YELLOW: Color256;
+    readonly DARK_BLUE: Color256;
+    readonly DARK_MAGENTA: Color256;
+    readonly DARK_CYAN: Color256;
+    readonly BLACK: Color256;
+    readonly MAROON: Color256;
+    readonly GREEN: Color256;
+    readonly OLIVE: Color256;
+    readonly NAVY: Color256;
+    readonly PURPLE: Color256;
+    readonly TEAL: Color256;
+    readonly SILVER: Color256;
+    readonly GRAY: Color256;
+    readonly RED: Color256;
+    readonly LIME: Color256;
+    readonly YELLOW: Color256;
+    readonly BLUE: Color256;
+    readonly FUCHSIA: Color256;
+    readonly CYAN: Color256;
+    readonly WHITE: Color256;
+};
+
+/**
+ * Color format conversion functions
+ * @module terminal/colors/convert
+ */
+
+/**
+ * Converts a hex color string to RGB.
+ * Supports #RGB, #RRGGBB, and #RRGGBBAA formats.
+ *
+ * @param hex - Hex color string (e.g., '#ff0000', '#f00', '#ff000080')
+ * @returns RGB or RGBA object
+ * @throws Error if hex format is invalid
+ *
+ * @example
+ * ```typescript
+ * import { hexToRgb } from 'blecsd';
+ *
+ * hexToRgb('#ff0000'); // { r: 255, g: 0, b: 0 }
+ * hexToRgb('#f00');    // { r: 255, g: 0, b: 0 }
+ * hexToRgb('#ff000080'); // { r: 255, g: 0, b: 0, a: 0.5 }
+ * ```
+ */
+declare function hexToRgb(hex: string): RGB | RGBA;
+/**
+ * Converts an RGB color to a hex string.
+ *
+ * @param rgb - RGB color object
+ * @returns Hex color string (e.g., '#ff0000')
+ *
+ * @example
+ * ```typescript
+ * import { rgbToHex } from 'blecsd';
+ *
+ * rgbToHex({ r: 255, g: 0, b: 0 }); // '#ff0000'
+ * ```
+ */
+declare function rgbToHex(rgb: RGB): string;
+/**
+ * Converts an RGBA color to a hex string with alpha.
+ *
+ * @param rgba - RGBA color object
+ * @returns Hex color string (e.g., '#ff000080')
+ *
+ * @example
+ * ```typescript
+ * import { rgbaToHex } from 'blecsd';
+ *
+ * rgbaToHex({ r: 255, g: 0, b: 0, a: 0.5 }); // '#ff000080'
+ * ```
+ */
+declare function rgbaToHex(rgba: RGBA): string;
+/**
+ * Converts an RGB color to HSL.
+ *
+ * @param rgb - RGB color object
+ * @returns HSL color object (h: 0-360, s: 0-100, l: 0-100)
+ *
+ * @example
+ * ```typescript
+ * import { rgbToHsl } from 'blecsd';
+ *
+ * rgbToHsl({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, l: 50 }
+ * rgbToHsl({ r: 0, g: 255, b: 0 }); // { h: 120, s: 100, l: 50 }
+ * ```
+ */
+declare function rgbToHsl(rgb: RGB): HSL;
+/**
+ * Converts an HSL color to RGB.
+ *
+ * @param hsl - HSL color object (h: 0-360, s: 0-100, l: 0-100)
+ * @returns RGB color object
+ *
+ * @example
+ * ```typescript
+ * import { hslToRgb } from 'blecsd';
+ *
+ * hslToRgb({ h: 0, s: 100, l: 50 });   // { r: 255, g: 0, b: 0 }
+ * hslToRgb({ h: 120, s: 100, l: 50 }); // { r: 0, g: 255, b: 0 }
+ * ```
+ */
+declare function hslToRgb(hsl: HSL): RGB;
+/**
+ * Converts RGBA to HSLA.
+ */
+declare function rgbaToHsla(rgba: RGBA): HSLA;
+/**
+ * Converts HSLA to RGBA.
+ */
+declare function hslaToRgba(hsla: HSLA): RGBA;
+/**
+ * Finds the nearest 256-color palette index for an RGB color.
+ * Uses Euclidean distance in RGB space for matching.
+ *
+ * @param rgb - RGB color to match
+ * @returns The closest Color256 palette index
+ *
+ * @example
+ * ```typescript
+ * import { rgbToColor256 } from 'blecsd';
+ *
+ * rgbToColor256({ r: 255, g: 0, b: 0 }); // 9 (bright red)
+ * rgbToColor256({ r: 128, g: 128, b: 128 }); // 244 (gray)
+ * ```
+ */
+declare function rgbToColor256(rgb: RGB): Color256;
+/**
+ * Converts a 256-color palette index to RGB.
+ *
+ * @param color - Color256 palette index
+ * @returns RGB color object
+ *
+ * @example
+ * ```typescript
+ * import { color256ToRgb } from 'blecsd';
+ *
+ * color256ToRgb(9);   // { r: 255, g: 0, b: 0 }
+ * color256ToRgb(244); // { r: 168, g: 168, b: 168 }
+ * ```
+ */
+declare function color256ToRgb(color: Color256): RGB;
+/**
+ * Converts a hex color directly to the nearest 256-color index.
+ *
+ * @param hex - Hex color string
+ * @returns Color256 palette index
+ *
+ * @example
+ * ```typescript
+ * import { hexToColor256 } from 'blecsd';
+ *
+ * hexToColor256('#ff0000'); // 9 (bright red)
+ * ```
+ */
+declare function hexToColor256(hex: string): Color256;
+/**
+ * Converts a 256-color palette index to hex.
+ *
+ * @param color - Color256 palette index
+ * @returns Hex color string
+ *
+ * @example
+ * ```typescript
+ * import { color256ToHex } from 'blecsd';
+ *
+ * color256ToHex(9); // '#ff0000'
+ * ```
+ */
+declare function color256ToHex(color: Color256): string;
+/**
+ * Packs an RGB color into a 24-bit integer (0xRRGGBB).
+ *
+ * @param rgb - RGB color object
+ * @returns Packed 24-bit color value
+ *
+ * @example
+ * ```typescript
+ * import { rgbToTruecolor } from 'blecsd';
+ *
+ * rgbToTruecolor({ r: 255, g: 0, b: 0 }); // 0xff0000 (16711680)
+ * ```
+ */
+declare function rgbToTruecolor(rgb: RGB): number;
+/**
+ * Unpacks a 24-bit truecolor integer to RGB.
+ *
+ * @param color - Packed 24-bit color value (0xRRGGBB)
+ * @returns RGB color object
+ *
+ * @example
+ * ```typescript
+ * import { truecolorToRgb } from 'blecsd';
+ *
+ * truecolorToRgb(0xff0000); // { r: 255, g: 0, b: 0 }
+ * ```
+ */
+declare function truecolorToRgb(color: number): RGB;
+/**
+ * Converts a hex color to a 24-bit truecolor integer.
+ *
+ * @param hex - Hex color string
+ * @returns Packed 24-bit color value
+ *
+ * @example
+ * ```typescript
+ * import { hexToTruecolor } from 'blecsd';
+ *
+ * hexToTruecolor('#ff0000'); // 0xff0000
+ * ```
+ */
+declare function hexToTruecolor(hex: string): number;
+/**
+ * Converts a 24-bit truecolor integer to hex.
+ *
+ * @param color - Packed 24-bit color value
+ * @returns Hex color string
+ *
+ * @example
+ * ```typescript
+ * import { truecolorToHex } from 'blecsd';
+ *
+ * truecolorToHex(0xff0000); // '#ff0000'
+ * ```
+ */
+declare function truecolorToHex(color: number): string;
+/**
+ * Converts a truecolor value to the nearest 256-color index.
+ * Useful for downgrading colors to terminals that don't support truecolor.
+ *
+ * @param color - Packed 24-bit color value
+ * @returns Color256 palette index
+ *
+ * @example
+ * ```typescript
+ * import { truecolorToColor256 } from 'blecsd';
+ *
+ * truecolorToColor256(0xff0000); // 9 (bright red)
+ * ```
+ */
+declare function truecolorToColor256(color: number): Color256;
+/**
+ * Converts a 256-color palette index to a 24-bit truecolor value.
+ *
+ * @param color - Color256 palette index
+ * @returns Packed 24-bit color value
+ *
+ * @example
+ * ```typescript
+ * import { color256ToTruecolor } from 'blecsd';
+ *
+ * color256ToTruecolor(9); // 0xff0000
+ * ```
+ */
+declare function color256ToTruecolor(color: Color256): number;
+/**
+ * Generates the SGR parameters for a 256-color foreground.
+ * Use with ESC[38;5;${n}m
+ *
+ * @param color - Color256 palette index
+ * @returns SGR parameter string (e.g., '38;5;196')
+ *
+ * @example
+ * ```typescript
+ * import { sgrFg256 } from 'blecsd';
+ *
+ * const params = sgrFg256(196);
+ * const escape = `\x1b[${params}m`; // '\x1b[38;5;196m'
+ * ```
+ */
+declare function sgrFg256(color: Color256): string;
+/**
+ * Generates the SGR parameters for a 256-color background.
+ * Use with ESC[48;5;${n}m
+ *
+ * @param color - Color256 palette index
+ * @returns SGR parameter string (e.g., '48;5;196')
+ */
+declare function sgrBg256(color: Color256): string;
+/**
+ * Generates the SGR parameters for a truecolor foreground.
+ * Use with ESC[38;2;r;g;b m
+ *
+ * @param rgb - RGB color object or packed truecolor
+ * @returns SGR parameter string (e.g., '38;2;255;0;0')
+ *
+ * @example
+ * ```typescript
+ * import { sgrFgRgb } from 'blecsd';
+ *
+ * const params = sgrFgRgb({ r: 255, g: 0, b: 0 });
+ * const escape = `\x1b[${params}m`; // '\x1b[38;2;255;0;0m'
+ * ```
+ */
+declare function sgrFgRgb(rgb: RGB | number): string;
+/**
+ * Generates the SGR parameters for a truecolor background.
+ * Use with ESC[48;2;r;g;b m
+ *
+ * @param rgb - RGB color object or packed truecolor
+ * @returns SGR parameter string (e.g., '48;2;255;0;0')
+ */
+declare function sgrBgRgb(rgb: RGB | number): string;
+/**
+ * Converts RGB directly to the nearest color cube index (16-231).
+ * More efficient than searching the full palette when you know
+ * you want a color cube match.
+ *
+ * @param rgb - RGB color object
+ * @returns Color256 index in the color cube range
+ *
+ * @example
+ * ```typescript
+ * import { rgbToColorCube } from 'blecsd';
+ *
+ * rgbToColorCube({ r: 255, g: 0, b: 0 }); // 196
+ * ```
+ */
+declare function rgbToColorCube(rgb: RGB): Color256;
+/**
+ * Converts RGB directly to the nearest grayscale index (232-255).
+ * More efficient than searching when you want a grayscale match.
+ *
+ * @param rgb - RGB color object
+ * @returns Color256 index in the grayscale range
+ *
+ * @example
+ * ```typescript
+ * import { rgbToGrayscale256 } from 'blecsd';
+ *
+ * rgbToGrayscale256({ r: 128, g: 128, b: 128 }); // ~244
+ * ```
+ */
+declare function rgbToGrayscale256(rgb: RGB): Color256;
+/**
+ * Unified color value type that can represent any color format.
+ */
+type ColorValue = string | number | RGB | Color256;
+/**
+ * Parses any color value into RGB.
+ *
+ * @param value - Color in any supported format:
+ *   - Hex string: '#ff0000', '#f00'
+ *   - RGB object: { r: 255, g: 0, b: 0 }
+ *   - 256-color index: 9 (if 0-255)
+ *   - Truecolor integer: 0xff0000 (if > 255)
+ *
+ * @returns RGB color object
+ * @throws Error if format is not recognized
+ *
+ * @example
+ * ```typescript
+ * import { parseColor } from 'blecsd';
+ *
+ * parseColor('#ff0000');            // { r: 255, g: 0, b: 0 }
+ * parseColor({ r: 255, g: 0, b: 0 }); // { r: 255, g: 0, b: 0 }
+ * parseColor(9);                    // { r: 255, g: 0, b: 0 } (256-color)
+ * parseColor(0xff0000);             // { r: 255, g: 0, b: 0 } (truecolor)
+ * ```
+ */
+declare function parseColor(value: ColorValue): RGB;
+/**
+ * Converts any color value to the nearest 256-color index.
+ *
+ * @param value - Color in any supported format
+ * @returns Color256 palette index
+ *
+ * @example
+ * ```typescript
+ * import { toColor256 } from 'blecsd';
+ *
+ * toColor256('#ff0000');              // 9
+ * toColor256({ r: 255, g: 0, b: 0 }); // 9
+ * toColor256(0xff0000);               // 9
+ * ```
+ */
+declare function toColor256(value: ColorValue): Color256;
+/**
+ * Converts any color value to a 24-bit truecolor integer.
+ *
+ * @param value - Color in any supported format
+ * @returns Packed 24-bit color value
+ *
+ * @example
+ * ```typescript
+ * import { toTruecolor } from 'blecsd';
+ *
+ * toTruecolor('#ff0000');              // 0xff0000
+ * toTruecolor({ r: 255, g: 0, b: 0 }); // 0xff0000
+ * toTruecolor(9);                      // 0xff0000
+ * ```
+ */
+declare function toTruecolor(value: ColorValue): number;
+/**
+ * Converts any color value to a hex string.
+ *
+ * @param value - Color in any supported format
+ * @returns Hex color string
+ *
+ * @example
+ * ```typescript
+ * import { toHex } from 'blecsd';
+ *
+ * toHex({ r: 255, g: 0, b: 0 }); // '#ff0000'
+ * toHex(9);                      // '#ff0000'
+ * toHex(0xff0000);               // '#ff0000'
+ * ```
+ */
+declare function toHex(value: ColorValue): string;
+
+/**
+ * Color name mappings for terminal colors
+ * @module terminal/colors/names
+ */
+
+/**
+ * Basic terminal color names (standard ANSI).
+ */
+type BasicColorName = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white';
+/**
+ * Light/bright color variants.
+ */
+type LightColorName = 'lightblack' | 'lightred' | 'lightgreen' | 'lightyellow' | 'lightblue' | 'lightmagenta' | 'lightcyan' | 'lightwhite';
+/**
+ * Bright color aliases (alternative naming).
+ */
+type BrightColorName = 'brightblack' | 'brightred' | 'brightgreen' | 'brightyellow' | 'brightblue' | 'brightmagenta' | 'brightcyan' | 'brightwhite';
+/**
+ * Dark color variants.
+ */
+type DarkColorName = 'darkred' | 'darkgreen' | 'darkyellow' | 'darkblue' | 'darkmagenta' | 'darkcyan' | 'darkgray' | 'darkgrey';
+/**
+ * Special color names.
+ */
+type SpecialColorName = 'default' | 'transparent' | 'inherit';
+/**
+ * All supported color names.
+ */
+type ColorName = BasicColorName | LightColorName | BrightColorName | DarkColorName | SpecialColorName | 'gray' | 'grey' | 'silver' | 'maroon' | 'olive' | 'navy' | 'purple' | 'teal' | 'aqua' | 'lime' | 'fuchsia' | 'orange';
+/**
+ * Mapping of color names to 256-color palette indices.
+ */
+declare const COLOR_NAMES: Record<string, Color256>;
+/**
+ * Color aliases mapping common alternate names to canonical names.
+ */
+declare const COLOR_ALIASES: Record<string, string>;
+/**
+ * Schema for validating color names.
+ *
+ * @example
+ * ```typescript
+ * import { ColorNameSchema } from 'blecsd';
+ *
+ * const result = ColorNameSchema.safeParse('red');
+ * if (result.success) {
+ *   console.log('Valid color name');
+ * }
+ * ```
+ */
+declare const ColorNameSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/**
+ * Converts a color name to a Color256 index.
+ * Returns null if the name is not recognized or is a special value.
+ *
+ * @param name - The color name (case-insensitive)
+ * @returns Color256 index or null
+ *
+ * @example
+ * ```typescript
+ * import { nameToColor } from 'blecsd';
+ *
+ * nameToColor('red');        // 1
+ * nameToColor('brightred');  // 9
+ * nameToColor('invalid');    // null
+ * nameToColor('default');    // null (special value)
+ * ```
+ */
+declare function nameToColor(name: string): Color256 | null;
+/**
+ * Converts a Color256 index to a canonical color name.
+ * Returns null for colors without standard names.
+ *
+ * @param color - The Color256 index
+ * @returns Color name or null
+ *
+ * @example
+ * ```typescript
+ * import { colorToName } from 'blecsd';
+ *
+ * colorToName(1);   // 'red'
+ * colorToName(9);   // 'brightred'
+ * colorToName(100); // null (no standard name)
+ * ```
+ */
+declare function colorToName(color: Color256): string | null;
+/**
+ * Checks if a string is a valid color name.
+ *
+ * @param name - The string to check
+ * @returns True if valid color name
+ *
+ * @example
+ * ```typescript
+ * import { isColorName } from 'blecsd';
+ *
+ * isColorName('red');     // true
+ * isColorName('invalid'); // false
+ * ```
+ */
+declare function isColorName(name: string): name is ColorName;
+/**
+ * Checks if a color name is a special value (default, transparent, inherit).
+ *
+ * @param name - The color name
+ * @returns True if special value
+ *
+ * @example
+ * ```typescript
+ * import { isSpecialColor } from 'blecsd';
+ *
+ * isSpecialColor('default');     // true
+ * isSpecialColor('transparent'); // true
+ * isSpecialColor('red');         // false
+ * ```
+ */
+declare function isSpecialColor(name: string): name is SpecialColorName;
+/**
+ * Extended CSS/X11 color names with RGB values.
+ * These are matched to the nearest 256-color palette entry.
+ */
+declare const CSS_COLORS: Record<string, RGB>;
+/**
+ * Converts a CSS/X11 color name to the nearest Color256 index.
+ * Returns null if the name is not recognized.
+ *
+ * @param name - The CSS color name (case-insensitive)
+ * @returns Color256 index or null
+ *
+ * @example
+ * ```typescript
+ * import { cssNameToColor } from 'blecsd';
+ *
+ * cssNameToColor('coral');     // Nearest 256-color match
+ * cssNameToColor('invalid');   // null
+ * ```
+ */
+declare function cssNameToColor(name: string): Color256 | null;
+/**
+ * Gets all available color names.
+ *
+ * @returns Array of color name strings
+ *
+ * @example
+ * ```typescript
+ * import { getColorNames } from 'blecsd';
+ *
+ * const names = getColorNames();
+ * // ['black', 'red', 'green', ...]
+ * ```
+ */
+declare function getColorNames(): readonly string[];
+/**
+ * Gets all available CSS/X11 color names.
+ *
+ * @returns Array of CSS color name strings
+ */
+declare function getCssColorNames(): readonly string[];
+
+/**
+ * Color blending and mixing functions
+ * @module terminal/colors/blend
+ */
+
+/**
+ * Mixes two RGB colors together.
+ *
+ * @param c1 - First color
+ * @param c2 - Second color
+ * @param ratio - Blend ratio (0 = all c1, 1 = all c2, 0.5 = equal mix). Default 0.5
+ * @returns Blended RGB color
+ *
+ * @example
+ * ```typescript
+ * import { mix } from 'blecsd';
+ *
+ * // 50/50 mix of red and blue
+ * const purple = mix(
+ *   { r: 255, g: 0, b: 0 },
+ *   { r: 0, g: 0, b: 255 }
+ * );
+ *
+ * // 75% red, 25% blue
+ * const redPurple = mix(
+ *   { r: 255, g: 0, b: 0 },
+ *   { r: 0, g: 0, b: 255 },
+ *   0.25
+ * );
+ * ```
+ */
+declare function mix(c1: RGB, c2: RGB, ratio?: number): RGB;
+/**
+ * Blends two Color256 palette colors together.
+ *
+ * @param c1 - First palette color
+ * @param c2 - Second palette color
+ * @param ratio - Blend ratio (0 = all c1, 1 = all c2). Default 0.5
+ * @returns Nearest Color256 to the blended result
+ *
+ * @example
+ * ```typescript
+ * import { blend, COLORS } from 'blecsd';
+ *
+ * // Mix red and blue
+ * const purple = blend(COLORS.RED, COLORS.BLUE);
+ * ```
+ */
+declare function blend(c1: Color256, c2: Color256, ratio?: number): Color256;
+/**
+ * Lightens an RGB color by a percentage.
+ *
+ * @param color - The color to lighten
+ * @param amount - Amount to lighten (0-1, where 1 = white)
+ * @returns Lightened RGB color
+ *
+ * @example
+ * ```typescript
+ * import { lighten } from 'blecsd';
+ *
+ * const lightRed = lighten({ r: 255, g: 0, b: 0 }, 0.3);
+ * ```
+ */
+declare function lighten(color: RGB, amount: number): RGB;
+/**
+ * Darkens an RGB color by a percentage.
+ *
+ * @param color - The color to darken
+ * @param amount - Amount to darken (0-1, where 1 = black)
+ * @returns Darkened RGB color
+ *
+ * @example
+ * ```typescript
+ * import { darken } from 'blecsd';
+ *
+ * const darkRed = darken({ r: 255, g: 0, b: 0 }, 0.3);
+ * ```
+ */
+declare function darken(color: RGB, amount: number): RGB;
+/**
+ * Lightens a Color256 palette color.
+ *
+ * @param color - The palette color
+ * @param amount - Amount to lighten (0-1)
+ * @returns Nearest Color256 to the lightened result
+ */
+declare function lighten256(color: Color256, amount: number): Color256;
+/**
+ * Darkens a Color256 palette color.
+ *
+ * @param color - The palette color
+ * @param amount - Amount to darken (0-1)
+ * @returns Nearest Color256 to the darkened result
+ */
+declare function darken256(color: Color256, amount: number): Color256;
+/**
+ * Increases the saturation of an RGB color.
+ *
+ * @param color - The color to saturate
+ * @param amount - Amount to increase saturation (0-1)
+ * @returns Saturated RGB color
+ *
+ * @example
+ * ```typescript
+ * import { saturate } from 'blecsd';
+ *
+ * // Make a muted color more vibrant
+ * const vibrant = saturate({ r: 180, g: 150, b: 150 }, 0.5);
+ * ```
+ */
+declare function saturate(color: RGB, amount: number): RGB;
+/**
+ * Decreases the saturation of an RGB color.
+ *
+ * @param color - The color to desaturate
+ * @param amount - Amount to decrease saturation (0-1, where 1 = grayscale)
+ * @returns Desaturated RGB color
+ *
+ * @example
+ * ```typescript
+ * import { desaturate } from 'blecsd';
+ *
+ * // Make a color more muted
+ * const muted = desaturate({ r: 255, g: 0, b: 0 }, 0.5);
+ *
+ * // Full desaturation = grayscale
+ * const gray = desaturate({ r: 255, g: 0, b: 0 }, 1);
+ * ```
+ */
+declare function desaturate(color: RGB, amount: number): RGB;
+/**
+ * Converts an RGB color to grayscale.
+ *
+ * @param color - The color to convert
+ * @returns Grayscale RGB color
+ *
+ * @example
+ * ```typescript
+ * import { grayscale } from 'blecsd';
+ *
+ * const gray = grayscale({ r: 255, g: 0, b: 0 }); // { r: 77, g: 77, b: 77 }
+ * ```
+ */
+declare function grayscale(color: RGB): RGB;
+/**
+ * Blends a foreground color with alpha over a background color.
+ * Uses standard alpha compositing (Porter-Duff over operator).
+ *
+ * @param fg - Foreground color with alpha
+ * @param bg - Background color (assumed opaque)
+ * @returns Composited RGB color
+ *
+ * @example
+ * ```typescript
+ * import { blendWithAlpha } from 'blecsd';
+ *
+ * // 50% transparent red over blue
+ * const result = blendWithAlpha(
+ *   { r: 255, g: 0, b: 0, a: 0.5 },
+ *   { r: 0, g: 0, b: 255 }
+ * );
+ * // { r: 128, g: 0, b: 128 }
+ * ```
+ */
+declare function blendWithAlpha(fg: RGBA, bg: RGB): RGB;
+/**
+ * Blends two colors with alpha values together.
+ * Uses Porter-Duff source over destination.
+ *
+ * @param src - Source (foreground) color
+ * @param dst - Destination (background) color
+ * @returns Composited RGBA color
+ *
+ * @example
+ * ```typescript
+ * import { blendAlpha } from 'blecsd';
+ *
+ * const result = blendAlpha(
+ *   { r: 255, g: 0, b: 0, a: 0.5 },
+ *   { r: 0, g: 0, b: 255, a: 0.5 }
+ * );
+ * ```
+ */
+declare function blendAlpha(src: RGBA, dst: RGBA): RGBA;
+/**
+ * Rotates the hue of a color.
+ *
+ * @param color - The color to modify
+ * @param degrees - Degrees to rotate hue (0-360)
+ * @returns Color with rotated hue
+ *
+ * @example
+ * ```typescript
+ * import { rotateHue } from 'blecsd';
+ *
+ * // Red rotated 120 degrees = green
+ * const green = rotateHue({ r: 255, g: 0, b: 0 }, 120);
+ * ```
+ */
+declare function rotateHue(color: RGB, degrees: number): RGB;
+/**
+ * Gets the complementary color (hue + 180 degrees).
+ *
+ * @param color - The original color
+ * @returns Complementary RGB color
+ *
+ * @example
+ * ```typescript
+ * import { complement } from 'blecsd';
+ *
+ * const cyan = complement({ r: 255, g: 0, b: 0 }); // Complement of red
+ * ```
+ */
+declare function complement(color: RGB): RGB;
+/**
+ * Inverts a color (255 - each channel).
+ *
+ * @param color - The color to invert
+ * @returns Inverted RGB color
+ *
+ * @example
+ * ```typescript
+ * import { invert } from 'blecsd';
+ *
+ * const cyan = invert({ r: 255, g: 0, b: 0 }); // { r: 0, g: 255, b: 255 }
+ * ```
+ */
+declare function invert(color: RGB): RGB;
+/**
+ * Generates a gradient of colors between two endpoints.
+ *
+ * @param from - Starting color
+ * @param to - Ending color
+ * @param steps - Number of colors to generate (including endpoints)
+ * @returns Array of RGB colors forming the gradient
+ *
+ * @example
+ * ```typescript
+ * import { gradient } from 'blecsd';
+ *
+ * // 5-step gradient from red to blue
+ * const colors = gradient(
+ *   { r: 255, g: 0, b: 0 },
+ *   { r: 0, g: 0, b: 255 },
+ *   5
+ * );
+ * // [red, redPurple, purple, bluePurple, blue]
+ * ```
+ */
+declare function gradient(from: RGB, to: RGB, steps: number): RGB[];
+/**
+ * Generates a gradient using Color256 palette colors.
+ *
+ * @param from - Starting palette color
+ * @param to - Ending palette color
+ * @param steps - Number of colors to generate
+ * @returns Array of Color256 values forming the gradient
+ *
+ * @example
+ * ```typescript
+ * import { gradient256, COLORS } from 'blecsd';
+ *
+ * const colors = gradient256(COLORS.RED, COLORS.BLUE, 5);
+ * ```
+ */
+declare function gradient256(from: Color256, to: Color256, steps: number): Color256[];
+/**
+ * Calculates the relative luminance of a color (0-1).
+ * Used for calculating contrast ratios.
+ *
+ * @param color - The color
+ * @returns Relative luminance (0-1)
+ */
+declare function luminance(color: RGB): number;
+/**
+ * Calculates the contrast ratio between two colors.
+ * Result is between 1 (no contrast) and 21 (maximum contrast).
+ *
+ * WCAG guidelines:
+ * - 4.5:1 minimum for normal text
+ * - 3:1 minimum for large text
+ * - 7:1 enhanced for normal text
+ *
+ * @param c1 - First color
+ * @param c2 - Second color
+ * @returns Contrast ratio (1-21)
+ *
+ * @example
+ * ```typescript
+ * import { contrastRatio } from 'blecsd';
+ *
+ * const ratio = contrastRatio(
+ *   { r: 0, g: 0, b: 0 },
+ *   { r: 255, g: 255, b: 255 }
+ * ); // 21 (maximum contrast)
+ * ```
+ */
+declare function contrastRatio(c1: RGB, c2: RGB): number;
+/**
+ * Determines if two colors have sufficient contrast for accessibility.
+ *
+ * @param c1 - First color
+ * @param c2 - Second color
+ * @param threshold - Minimum contrast ratio (default: 4.5 for WCAG AA)
+ * @returns True if contrast is sufficient
+ *
+ * @example
+ * ```typescript
+ * import { isReadable } from 'blecsd';
+ *
+ * if (isReadable(textColor, backgroundColor)) {
+ *   // Text is readable
+ * }
+ * ```
+ */
+declare function isReadable(c1: RGB, c2: RGB, threshold?: number): boolean;
+
+export { nameToColor as $, desaturate as A, type BasicColorName as B, COLOR_ALIASES as C, type DarkColorName as D, getColorNames as E, getCssColorNames as F, gradient as G, type HSL as H, gradient256 as I, grayscale as J, hexToColor256 as K, type LightColorName as L, hexToRgb as M, hslToRgb as N, hslaToRgba as O, invert as P, isColor256 as Q, type RGB as R, type SpecialColorName as S, isColorName as T, isRGB as U, isReadable as V, isSpecialColor as W, lighten as X, lighten256 as Y, luminance as Z, mix as _, type BrightColorName as a, rgbToColor256 as a0, rgbToHex as a1, rgbToHsl as a2, rgbaToHex as a3, rgbaToHsla as a4, rotateHue as a5, saturate as a6, ANSI as a7, COLORS as a8, COLOR_CUBE_LEVELS as a9, PALETTE_HEX as aa, PALETTE_RGB as ab, asColor256 as ac, color256ToTruecolor as ad, colorCubeIndex as ae, getHex as af, getRGB as ag, grayscaleIndex as ah, hexToTruecolor as ai, isColorCube as aj, isGrayscale as ak, isStandardColor as al, parseColor as am, rgbToColorCube as an, rgbToGrayscale256 as ao, rgbToTruecolor as ap, sgrBg256 as aq, sgrBgRgb as ar, sgrFg256 as as, sgrFgRgb as at, toColor256 as au, toHex as av, toTruecolor as aw, truecolorToColor256 as ax, truecolorToHex as ay, truecolorToRgb as az, COLOR_NAMES as b, CSS_COLORS as c, type Color256 as d, Color256Schema as e, type ColorName as f, ColorNameSchema as g, type ColorValue as h, type HSLA as i, HSLASchema as j, HSLSchema as k, HexColorSchema as l, type RGBA as m, RGBASchema as n, RGBSchema as o, blend as p, blendAlpha as q, blendWithAlpha as r, color256ToHex as s, color256ToRgb as t, colorToName as u, complement as v, contrastRatio as w, cssNameToColor as x, darken as y, darken256 as z };