@crustjs/style 0.0.1 → 0.0.3

package/README.md

@@ -21,6 +21,7 @@ import { style } from "@crustjs/style";
 console.log(style.bold("Build succeeded"));
 console.log(style.red("Error: missing argument"));
 console.log(style.dim("hint: use --help for usage"));
+console.log(style.bold.red("Critical failure"));
 ```
 
 ## Primitive Styling
@@ -57,6 +58,63 @@ console.log(applyStyle("critical error", boldRed));
 
 Nested styles are handled safely — no style bleed across boundaries.
 
+## Dynamic Colors (Truecolor)
+
+Use any RGB or hex color via 24-bit truecolor ANSI sequences:
+
+```ts
+import { rgb, bgRgb, hex, bgHex } from "@crustjs/style";
+
+// RGB values (0–255)
+console.log(rgb("ocean", 0, 128, 255));
+console.log(bgRgb("warning", 255, 128, 0));
+
+// Hex colors (#RGB or #RRGGBB)
+console.log(hex("error", "#ff0000"));
+console.log(hex("short", "#f00"));
+console.log(bgHex("highlight", "#ff8800"));
+```
+
+### Pair Factories
+
+Create reusable `AnsiPair` objects for composition:
+
+```ts
+import { rgbCode, bgRgbCode, hexCode, bgHexCode, applyStyle, composeStyles, boldCode } from "@crustjs/style";
+
+const coral = rgbCode(255, 127, 80);
+console.log(applyStyle("coral text", coral));
+
+const boldCoral = composeStyles(boldCode, hexCode("#ff7f50"));
+console.log(applyStyle("bold coral", boldCoral));
+```
+
+### Style Instance
+
+Dynamic colors on `createStyle` instances respect mode and truecolor detection:
+
+```ts
+import { createStyle } from "@crustjs/style";
+
+const s = createStyle({ mode: "always" });
+console.log(s.rgb("text", 255, 0, 0));
+console.log(s.hex("text", "#ff0000"));
+console.log(s.bgRgb("text", 0, 128, 255));
+console.log(s.bgHex("text", "#0080ff"));
+```
+
+In `"auto"` mode, dynamic colors are emitted only when the terminal supports truecolor (detected via `COLORTERM=truecolor|24bit` or `TERM` containing `truecolor`, `24bit`, or `-direct`). When truecolor is not detected, dynamic color methods return plain text while standard 16-color methods continue to work.
+
+In `"never"` mode, all dynamic color methods return plain text. In `"always"` mode, truecolor sequences are always emitted.
+
+### Terminal Compatibility
+
+Dynamic colors use truecolor (24-bit) ANSI sequences. There is no automatic fallback to 256 or 16 colors. On terminals that do not support truecolor:
+
+- Colors may be approximated to the nearest supported color
+- Colors may be silently ignored (text renders in default color)
+- No runtime errors will occur
+
 ## Color Modes
 
 Control when ANSI codes are emitted using `createStyle`:
@@ -70,6 +128,7 @@ const auto = createStyle({ mode: "auto" });
 // Always emit ANSI codes
 const color = createStyle({ mode: "always" });
 console.log(color.red("always red"));
+console.log(color.bold.red("always bold red"));
 
 // Never emit ANSI codes — returns plain text
 const plain = createStyle({ mode: "never" });
@@ -90,6 +149,12 @@ const testStyle = createStyle({
   mode: "auto",
   overrides: { isTTY: true, noColor: undefined },
 });
+
+// Include truecolor overrides for dynamic color testing
+const truecolorStyle = createStyle({
+  mode: "auto",
+  overrides: { isTTY: true, noColor: undefined, colorTerm: "truecolor" },
+});
 ```
 
 ## Text Utilities

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+declare namespace codes {
+	export { yellow, white, underline, strikethrough, reset, red, magenta, italic, inverse, hidden, green, gray, dim, cyan, brightYellow, brightWhite, brightRed, brightMagenta, brightGreen, brightCyan, brightBlue, bold, blue, black, bgYellow, bgWhite, bgRed, bgMagenta, bgGreen, bgCyan, bgBrightYellow, bgBrightWhite, bgBrightRed, bgBrightMagenta, bgBrightGreen, bgBrightCyan, bgBrightBlue, bgBrightBlack, bgBlue, bgBlack, AnsiPair };
+}
 /**
 * An ANSI style pair consisting of an opening and closing escape sequence.
 *
@@ -36,29 +39,29 @@ declare const cyan: AnsiPair;
 declare const white: AnsiPair;
 /** Bright black (gray). */
 declare const gray: AnsiPair;
-declare const brightRed2: AnsiPair;
-declare const brightGreen2: AnsiPair;
-declare const brightYellow2: AnsiPair;
-declare const brightBlue2: AnsiPair;
-declare const brightMagenta2: AnsiPair;
-declare const brightCyan2: AnsiPair;
-declare const brightWhite2: AnsiPair;
-declare const bgBlack2: AnsiPair;
-declare const bgRed2: AnsiPair;
-declare const bgGreen2: AnsiPair;
-declare const bgYellow2: AnsiPair;
-declare const bgBlue2: AnsiPair;
-declare const bgMagenta2: AnsiPair;
-declare const bgCyan2: AnsiPair;
-declare const bgWhite2: AnsiPair;
-declare const bgBrightBlack2: AnsiPair;
-declare const bgBrightRed2: AnsiPair;
-declare const bgBrightGreen2: AnsiPair;
-declare const bgBrightYellow2: AnsiPair;
-declare const bgBrightBlue2: AnsiPair;
-declare const bgBrightMagenta2: AnsiPair;
-declare const bgBrightCyan2: AnsiPair;
-declare const bgBrightWhite2: AnsiPair;
+declare const brightRed: AnsiPair;
+declare const brightGreen: AnsiPair;
+declare const brightYellow: AnsiPair;
+declare const brightBlue: AnsiPair;
+declare const brightMagenta: AnsiPair;
+declare const brightCyan: AnsiPair;
+declare const brightWhite: AnsiPair;
+declare const bgBlack: AnsiPair;
+declare const bgRed: AnsiPair;
+declare const bgGreen: AnsiPair;
+declare const bgYellow: AnsiPair;
+declare const bgBlue: AnsiPair;
+declare const bgMagenta: AnsiPair;
+declare const bgCyan: AnsiPair;
+declare const bgWhite: AnsiPair;
+declare const bgBrightBlack: AnsiPair;
+declare const bgBrightRed: AnsiPair;
+declare const bgBrightGreen: AnsiPair;
+declare const bgBrightYellow: AnsiPair;
+declare const bgBrightBlue: AnsiPair;
+declare const bgBrightMagenta: AnsiPair;
+declare const bgBrightCyan: AnsiPair;
+declare const bgBrightWhite: AnsiPair;
 /**
 * Options for {@link unorderedList}.
 */
@@ -279,6 +282,8 @@ interface TableOptions {
 * ```
 */
 declare function table(headers: string[], rows: string[][], options?: TableOptions): string;
+declare const styleMethodPairs: Omit<typeof codes, "reset">;
+type StyleMethodName = keyof typeof styleMethodPairs;
 /**
 * Color emission mode for the style engine.
 *
@@ -307,6 +312,18 @@ interface CapabilityOverrides {
 	readonly noColor?: string | undefined;
 }
 /**
+* Truecolor capability overrides for deterministic testing.
+*
+* These override environment variable checks used by
+* {@link resolveTrueColor} to detect 24-bit color support.
+*/
+interface TrueColorOverrides {
+	/** Override `process.env.COLORTERM`. */
+	readonly colorTerm?: string | undefined;
+	/** Override `process.env.TERM`. */
+	readonly term?: string | undefined;
+}
+/**
 * Configuration options for creating a style instance.
 *
 * @example
@@ -318,7 +335,7 @@ interface StyleOptions {
 	/** Color emission mode. Defaults to `"auto"`. */
 	readonly mode?: ColorMode;
 	/** Capability overrides for deterministic testing. */
-	readonly overrides?: CapabilityOverrides;
+	readonly overrides?: CapabilityOverrides & TrueColorOverrides;
 }
 /**
 * A style function that applies an ANSI style pair to text,
@@ -326,56 +343,47 @@ interface StyleOptions {
 */
 type StyleFn = (text: string) => string;
 /**
+* Shared style method surface used by style instances and chainable style
+* functions.
+*/
+type StyleMethodMap = { readonly [K in StyleMethodName2] : ChainableStyleFn };
+/**
+* A callable style function that also exposes all style methods for chaining.
+*
+* @example
+* ```ts
+* style.bold.red("error");
+* ```
+*/
+interface ChainableStyleFn extends StyleMethodMap {
+	(text: string): string;
+}
+/**
+* Style method name used by the chain builder implementation.
+*/
+type StyleMethodName2 = StyleMethodName;
+/**
 * A configured style instance with mode-aware styling functions.
 *
 * In `"never"` mode, all functions return plain text without ANSI codes.
 * In `"always"` mode, ANSI codes are always emitted.
 * In `"auto"` mode, behavior depends on terminal capability detection.
 */
-interface StyleInstance {
+interface StyleInstance extends StyleMethodMap {
 	/** Whether ANSI codes will be emitted by this instance. */
 	readonly enabled: boolean;
+	/** Whether truecolor (24-bit) sequences will be emitted by this instance. */
+	readonly trueColorEnabled: boolean;
 	/** Apply an arbitrary ANSI pair to text, respecting the color mode. */
 	readonly apply: (text: string, pair: AnsiPair) => string;
-	readonly bold: StyleFn;
-	readonly dim: StyleFn;
-	readonly italic: StyleFn;
-	readonly underline: StyleFn;
-	readonly inverse: StyleFn;
-	readonly hidden: StyleFn;
-	readonly strikethrough: StyleFn;
-	readonly black: StyleFn;
-	readonly red: StyleFn;
-	readonly green: StyleFn;
-	readonly yellow: StyleFn;
-	readonly blue: StyleFn;
-	readonly magenta: StyleFn;
-	readonly cyan: StyleFn;
-	readonly white: StyleFn;
-	readonly gray: StyleFn;
-	readonly brightRed: StyleFn;
-	readonly brightGreen: StyleFn;
-	readonly brightYellow: StyleFn;
-	readonly brightBlue: StyleFn;
-	readonly brightMagenta: StyleFn;
-	readonly brightCyan: StyleFn;
-	readonly brightWhite: StyleFn;
-	readonly bgBlack: StyleFn;
-	readonly bgRed: StyleFn;
-	readonly bgGreen: StyleFn;
-	readonly bgYellow: StyleFn;
-	readonly bgBlue: StyleFn;
-	readonly bgMagenta: StyleFn;
-	readonly bgCyan: StyleFn;
-	readonly bgWhite: StyleFn;
-	readonly bgBrightBlack: StyleFn;
-	readonly bgBrightRed: StyleFn;
-	readonly bgBrightGreen: StyleFn;
-	readonly bgBrightYellow: StyleFn;
-	readonly bgBrightBlue: StyleFn;
-	readonly bgBrightMagenta: StyleFn;
-	readonly bgBrightCyan: StyleFn;
-	readonly bgBrightWhite: StyleFn;
+	/** Apply a truecolor foreground RGB color to text. */
+	readonly rgb: (text: string, r: number, g: number, b: number) => string;
+	/** Apply a truecolor background RGB color to text. */
+	readonly bgRgb: (text: string, r: number, g: number, b: number) => string;
+	/** Apply a truecolor foreground hex color to text. */
+	readonly hex: (text: string, hexColor: string) => string;
+	/** Apply a truecolor background hex color to text. */
+	readonly bgHex: (text: string, hexColor: string) => string;
 }
 /**
 * Resolve whether ANSI color codes should be emitted.
@@ -405,6 +413,35 @@ interface StyleInstance {
 * ```
 */
 declare function resolveCapability(mode: ColorMode, overrides?: CapabilityOverrides): boolean;
+/**
+* Resolve whether the terminal supports truecolor (24-bit) ANSI sequences.
+*
+* Detection heuristics (checked in order):
+* 1. `COLORTERM` environment variable is `"truecolor"` or `"24bit"`.
+* 2. `TERM` environment variable contains `"24bit"`, `"truecolor"`, or `"-direct"`.
+*
+* In `"always"` mode, returns `true` unconditionally.
+* In `"never"` mode, returns `false` unconditionally.
+* In `"auto"` mode, requires base color to be enabled **and** truecolor
+* to be detected.
+*
+* @param mode - The color emission mode.
+* @param overrides - Optional overrides for deterministic testing.
+* @returns `true` if truecolor sequences should be emitted.
+*
+* @example
+* ```ts
+* resolveTrueColor("auto"); // true if TTY + truecolor env detected
+* resolveTrueColor("always"); // true
+* resolveTrueColor("never"); // false
+* resolveTrueColor("auto", {
+*   isTTY: true,
+*   noColor: undefined,
+*   colorTerm: "truecolor",
+* }); // true
+* ```
+*/
+declare function resolveTrueColor(mode: ColorMode, overrides?: CapabilityOverrides & TrueColorOverrides): boolean;
 /** Apply black foreground color. */
 declare function black2(text: string): string;
 /** Apply red foreground color. */
@@ -424,51 +461,51 @@ declare function white2(text: string): string;
 /** Apply gray (bright black) foreground color. */
 declare function gray2(text: string): string;
 /** Apply bright red foreground color. */
-declare function brightRed3(text: string): string;
+declare function brightRed2(text: string): string;
 /** Apply bright green foreground color. */
-declare function brightGreen3(text: string): string;
+declare function brightGreen2(text: string): string;
 /** Apply bright yellow foreground color. */
-declare function brightYellow3(text: string): string;
+declare function brightYellow2(text: string): string;
 /** Apply bright blue foreground color. */
-declare function brightBlue3(text: string): string;
+declare function brightBlue2(text: string): string;
 /** Apply bright magenta foreground color. */
-declare function brightMagenta3(text: string): string;
+declare function brightMagenta2(text: string): string;
 /** Apply bright cyan foreground color. */
-declare function brightCyan3(text: string): string;
+declare function brightCyan2(text: string): string;
 /** Apply bright white foreground color. */
-declare function brightWhite3(text: string): string;
+declare function brightWhite2(text: string): string;
 /** Apply black background color. */
-declare function bgBlack3(text: string): string;
+declare function bgBlack2(text: string): string;
 /** Apply red background color. */
-declare function bgRed3(text: string): string;
+declare function bgRed2(text: string): string;
 /** Apply green background color. */
-declare function bgGreen3(text: string): string;
+declare function bgGreen2(text: string): string;
 /** Apply yellow background color. */
-declare function bgYellow3(text: string): string;
+declare function bgYellow2(text: string): string;
 /** Apply blue background color. */
-declare function bgBlue3(text: string): string;
+declare function bgBlue2(text: string): string;
 /** Apply magenta background color. */
-declare function bgMagenta3(text: string): string;
+declare function bgMagenta2(text: string): string;
 /** Apply cyan background color. */
-declare function bgCyan3(text: string): string;
+declare function bgCyan2(text: string): string;
 /** Apply white background color. */
-declare function bgWhite3(text: string): string;
+declare function bgWhite2(text: string): string;
 /** Apply bright black background color. */
-declare function bgBrightBlack3(text: string): string;
+declare function bgBrightBlack2(text: string): string;
 /** Apply bright red background color. */
-declare function bgBrightRed3(text: string): string;
+declare function bgBrightRed2(text: string): string;
 /** Apply bright green background color. */
-declare function bgBrightGreen3(text: string): string;
+declare function bgBrightGreen2(text: string): string;
 /** Apply bright yellow background color. */
-declare function bgBrightYellow3(text: string): string;
+declare function bgBrightYellow2(text: string): string;
 /** Apply bright blue background color. */
-declare function bgBrightBlue3(text: string): string;
+declare function bgBrightBlue2(text: string): string;
 /** Apply bright magenta background color. */
-declare function bgBrightMagenta3(text: string): string;
+declare function bgBrightMagenta2(text: string): string;
 /** Apply bright cyan background color. */
-declare function bgBrightCyan3(text: string): string;
+declare function bgBrightCyan2(text: string): string;
 /** Apply bright white background color. */
-declare function bgBrightWhite3(text: string): string;
+declare function bgBrightWhite2(text: string): string;
 /**
 * Create a configured style instance with mode-aware styling functions.
 *
@@ -490,6 +527,7 @@ declare function bgBrightWhite3(text: string): string;
 * // Force color output
 * const color = createStyle({ mode: "always" });
 * console.log(color.red("error"));
+* console.log(color.bold.red("critical"));
 *
 * // Disable all styling
 * const plain = createStyle({ mode: "never" });
@@ -519,6 +557,150 @@ declare function createStyle(options?: StyleOptions): StyleInstance;
 */
 declare const style: StyleInstance;
 /**
+* Parse a hex color string into RGB channel values.
+*
+* Supports `#RGB` (shorthand) and `#RRGGBB` (full) formats.
+* The `#` prefix is required.
+*
+* @param hex - The hex color string.
+* @returns A tuple of `[r, g, b]` channel values (0–255).
+* @throws {TypeError} If the string is not a valid hex color.
+*
+* @example
+* ```ts
+* parseHex("#ff0000"); // [255, 0, 0]
+* parseHex("#f00");    // [255, 0, 0]
+* ```
+*/
+declare function parseHex(hex: string): [r: number, g: number, b: number];
+/**
+* Create an {@link AnsiPair} for a truecolor foreground RGB color.
+*
+* Uses the ANSI escape sequence `\x1b[38;2;R;G;Bm` with close `\x1b[39m`.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns An ANSI pair for the specified foreground color.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* const pair = rgbCode(255, 0, 0);
+* applyStyle("error", pair); // red foreground
+* ```
+*/
+declare function rgbCode(r: number, g: number, b: number): AnsiPair;
+/**
+* Create an {@link AnsiPair} for a truecolor background RGB color.
+*
+* Uses the ANSI escape sequence `\x1b[48;2;R;G;Bm` with close `\x1b[49m`.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns An ANSI pair for the specified background color.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* const pair = bgRgbCode(255, 128, 0);
+* applyStyle("warning", pair); // orange background
+* ```
+*/
+declare function bgRgbCode(r: number, g: number, b: number): AnsiPair;
+/**
+* Create an {@link AnsiPair} for a truecolor foreground hex color.
+*
+* @param hex - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns An ANSI pair for the specified foreground color.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* const pair = hexCode("#ff0000");
+* applyStyle("error", pair); // red foreground
+* ```
+*/
+declare function hexCode(hex: string): AnsiPair;
+/**
+* Create an {@link AnsiPair} for a truecolor background hex color.
+*
+* @param hex - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns An ANSI pair for the specified background color.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* const pair = bgHexCode("#ff8800");
+* applyStyle("warning", pair); // orange background
+* ```
+*/
+declare function bgHexCode(hex: string): AnsiPair;
+/**
+* Apply a truecolor foreground RGB color to text.
+*
+* @param text - The text to style.
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The styled string.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* rgb("error", 255, 0, 0);   // red text
+* rgb("ocean", 0, 128, 255); // blue text
+* ```
+*/
+declare function rgb(text: string, r: number, g: number, b: number): string;
+/**
+* Apply a truecolor background RGB color to text.
+*
+* @param text - The text to style.
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The styled string.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* bgRgb("warning", 255, 128, 0); // orange background
+* ```
+*/
+declare function bgRgb2(text: string, r: number, g: number, b: number): string;
+/**
+* Apply a truecolor foreground hex color to text.
+*
+* @param text - The text to style.
+* @param hexColor - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns The styled string.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* hex("error", "#ff0000");   // red text
+* hex("ocean", "#0080ff");   // blue text
+* hex("short", "#f00");      // red text (shorthand)
+* ```
+*/
+declare function hex(text: string, hexColor: string): string;
+/**
+* Apply a truecolor background hex color to text.
+*
+* @param text - The text to style.
+* @param hexColor - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns The styled string.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* bgHex("warning", "#ff8800"); // orange background
+* ```
+*/
+declare function bgHex2(text: string, hexColor: string): string;
+/**
 * Apply **bold** (increased intensity) to text.
 *
 * @example
@@ -962,4 +1144,4 @@ declare function createMarkdownTheme(options?: CreateMarkdownThemeOptions): Mark
 * ```
 */
 declare const defaultTheme: MarkdownTheme;
-export { yellow as yellowCode, yellow2 as yellow, wrapText, white as whiteCode, white2 as white, visibleWidth, unorderedList, underline as underlineCode, underline2 as underline, taskList, table, style, stripAnsi, strikethrough as strikethroughCode, strikethrough2 as strikethrough, resolveCapability, reset, red as redCode, red2 as red, padStart, padEnd, orderedList, magenta as magentaCode, magenta2 as magenta, italic as italicCode, italic2 as italic, inverse as inverseCode, inverse2 as inverse, hidden as hiddenCode, hidden2 as hidden, green as greenCode, green2 as green, gray as grayCode, gray2 as gray, dim as dimCode, dim2 as dim, defaultTheme, cyan as cyanCode, cyan2 as cyan, createStyle, createMarkdownTheme, composeStyles, center, buildDefaultMarkdownTheme, brightYellow2 as brightYellowCode, brightYellow3 as brightYellow, brightWhite2 as brightWhiteCode, brightWhite3 as brightWhite, brightRed2 as brightRedCode, brightRed3 as brightRed, brightMagenta2 as brightMagentaCode, brightMagenta3 as brightMagenta, brightGreen2 as brightGreenCode, brightGreen3 as brightGreen, brightCyan2 as brightCyanCode, brightCyan3 as brightCyan, brightBlue2 as brightBlueCode, brightBlue3 as brightBlue, bold as boldCode, bold2 as bold, blue as blueCode, blue2 as blue, black as blackCode, black2 as black, bgYellow2 as bgYellowCode, bgYellow3 as bgYellow, bgWhite2 as bgWhiteCode, bgWhite3 as bgWhite, bgRed2 as bgRedCode, bgRed3 as bgRed, bgMagenta2 as bgMagentaCode, bgMagenta3 as bgMagenta, bgGreen2 as bgGreenCode, bgGreen3 as bgGreen, bgCyan2 as bgCyanCode, bgCyan3 as bgCyan, bgBrightYellow2 as bgBrightYellowCode, bgBrightYellow3 as bgBrightYellow, bgBrightWhite2 as bgBrightWhiteCode, bgBrightWhite3 as bgBrightWhite, bgBrightRed2 as bgBrightRedCode, bgBrightRed3 as bgBrightRed, bgBrightMagenta2 as bgBrightMagentaCode, bgBrightMagenta3 as bgBrightMagenta, bgBrightGreen2 as bgBrightGreenCode, bgBrightGreen3 as bgBrightGreen, bgBrightCyan2 as bgBrightCyanCode, bgBrightCyan3 as bgBrightCyan, bgBrightBlue2 as bgBrightBlueCode, bgBrightBlue3 as bgBrightBlue, bgBrightBlack2 as bgBrightBlackCode, bgBrightBlack3 as bgBrightBlack, bgBlue2 as bgBlueCode, bgBlue3 as bgBlue, bgBlack2 as bgBlackCode, bgBlack3 as bgBlack, applyStyle, WrapOptions, UnorderedListOptions, ThemeSlotFn, TaskListOptions, TaskListItem, TableOptions, StyleOptions, StyleInstance, StyleFn, PartialMarkdownTheme, OrderedListOptions, MarkdownTheme, CreateMarkdownThemeOptions, ColumnAlignment, ColorMode, CapabilityOverrides, AnsiPair };
+export { yellow as yellowCode, yellow2 as yellow, wrapText, white as whiteCode, white2 as white, visibleWidth, unorderedList, underline as underlineCode, underline2 as underline, taskList, table, style, stripAnsi, strikethrough as strikethroughCode, strikethrough2 as strikethrough, rgbCode, rgb, resolveTrueColor, resolveCapability, reset, red as redCode, red2 as red, parseHex, padStart, padEnd, orderedList, magenta as magentaCode, magenta2 as magenta, italic as italicCode, italic2 as italic, inverse as inverseCode, inverse2 as inverse, hidden as hiddenCode, hidden2 as hidden, hexCode, hex, green as greenCode, green2 as green, gray as grayCode, gray2 as gray, dim as dimCode, dim2 as dim, defaultTheme, cyan as cyanCode, cyan2 as cyan, createStyle, createMarkdownTheme, composeStyles, center, buildDefaultMarkdownTheme, brightYellow as brightYellowCode, brightYellow2 as brightYellow, brightWhite as brightWhiteCode, brightWhite2 as brightWhite, brightRed as brightRedCode, brightRed2 as brightRed, brightMagenta as brightMagentaCode, brightMagenta2 as brightMagenta, brightGreen as brightGreenCode, brightGreen2 as brightGreen, brightCyan as brightCyanCode, brightCyan2 as brightCyan, brightBlue as brightBlueCode, brightBlue2 as brightBlue, bold as boldCode, bold2 as bold, blue as blueCode, blue2 as blue, black as blackCode, black2 as black, bgYellow as bgYellowCode, bgYellow2 as bgYellow, bgWhite as bgWhiteCode, bgWhite2 as bgWhite, bgRgbCode, bgRgb2 as bgRgb, bgRed as bgRedCode, bgRed2 as bgRed, bgMagenta as bgMagentaCode, bgMagenta2 as bgMagenta, bgHexCode, bgHex2 as bgHex, bgGreen as bgGreenCode, bgGreen2 as bgGreen, bgCyan as bgCyanCode, bgCyan2 as bgCyan, bgBrightYellow as bgBrightYellowCode, bgBrightYellow2 as bgBrightYellow, bgBrightWhite as bgBrightWhiteCode, bgBrightWhite2 as bgBrightWhite, bgBrightRed as bgBrightRedCode, bgBrightRed2 as bgBrightRed, bgBrightMagenta as bgBrightMagentaCode, bgBrightMagenta2 as bgBrightMagenta, bgBrightGreen as bgBrightGreenCode, bgBrightGreen2 as bgBrightGreen, bgBrightCyan as bgBrightCyanCode, bgBrightCyan2 as bgBrightCyan, bgBrightBlue as bgBrightBlueCode, bgBrightBlue2 as bgBrightBlue, bgBrightBlack as bgBrightBlackCode, bgBrightBlack2 as bgBrightBlack, bgBlue as bgBlueCode, bgBlue2 as bgBlue, bgBlack as bgBlackCode, bgBlack2 as bgBlack, applyStyle, WrapOptions, UnorderedListOptions, TrueColorOverrides, ThemeSlotFn, TaskListOptions, TaskListItem, TableOptions, StyleOptions, StyleInstance, StyleFn, PartialMarkdownTheme, OrderedListOptions, MarkdownTheme, CreateMarkdownThemeOptions, ColumnAlignment, ColorMode, CapabilityOverrides, AnsiPair };

package/dist/index.js

@@ -1,5 +1,59 @@
 // @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
 // src/ansiCodes.ts
+var exports_ansiCodes = {};
+__export(exports_ansiCodes, {
+  yellow: () => yellow,
+  white: () => white,
+  underline: () => underline,
+  strikethrough: () => strikethrough,
+  reset: () => reset,
+  red: () => red,
+  magenta: () => magenta,
+  italic: () => italic,
+  inverse: () => inverse,
+  hidden: () => hidden,
+  green: () => green,
+  gray: () => gray,
+  dim: () => dim,
+  cyan: () => cyan,
+  brightYellow: () => brightYellow,
+  brightWhite: () => brightWhite,
+  brightRed: () => brightRed,
+  brightMagenta: () => brightMagenta,
+  brightGreen: () => brightGreen,
+  brightCyan: () => brightCyan,
+  brightBlue: () => brightBlue,
+  bold: () => bold,
+  blue: () => blue,
+  black: () => black,
+  bgYellow: () => bgYellow,
+  bgWhite: () => bgWhite,
+  bgRed: () => bgRed,
+  bgMagenta: () => bgMagenta,
+  bgGreen: () => bgGreen,
+  bgCyan: () => bgCyan,
+  bgBrightYellow: () => bgBrightYellow,
+  bgBrightWhite: () => bgBrightWhite,
+  bgBrightRed: () => bgBrightRed,
+  bgBrightMagenta: () => bgBrightMagenta,
+  bgBrightGreen: () => bgBrightGreen,
+  bgBrightCyan: () => bgBrightCyan,
+  bgBrightBlue: () => bgBrightBlue,
+  bgBrightBlack: () => bgBrightBlack,
+  bgBlue: () => bgBlue,
+  bgBlack: () => bgBlack
+});
 function pair(open, close) {
   return { open: `\x1B[${open}m`, close: `\x1B[${close}m` };
 }
@@ -233,6 +287,32 @@ function resolveCapability(mode, overrides) {
   }
   return isTTY;
 }
+function resolveTrueColor(mode, overrides) {
+  if (mode === "always") {
+    return true;
+  }
+  if (mode === "never") {
+    return false;
+  }
+  if (!resolveCapability(mode, overrides)) {
+    return false;
+  }
+  const hasColorTermOverride = overrides !== undefined && "colorTerm" in overrides;
+  const colorTerm = hasColorTermOverride ? overrides.colorTerm : process.env.COLORTERM;
+  const lowerColorTerm = colorTerm?.toLowerCase();
+  if (lowerColorTerm === "truecolor" || lowerColorTerm === "24bit") {
+    return true;
+  }
+  const hasTermOverride = overrides !== undefined && "term" in overrides;
+  const term = hasTermOverride ? overrides.term : process.env.TERM;
+  if (term !== undefined) {
+    const lower = term.toLowerCase();
+    if (lower.includes("24bit") || lower.includes("truecolor") || lower.endsWith("-direct")) {
+      return true;
+    }
+  }
+  return false;
+}
 // src/styleEngine.ts
 function applyStyle(text, style) {
   if (text === "") {
@@ -348,58 +428,146 @@ function bgBrightCyan2(text) {
 function bgBrightWhite2(text) {
   return applyStyle(text, bgBrightWhite);
 }
+// src/dynamicColors.ts
+function validateChannel(value, channel) {
+  if (!Number.isInteger(value) || value < 0 || value > 255) {
+    throw new RangeError(`Invalid ${channel} value: ${String(value)}. Must be an integer between 0 and 255.`);
+  }
+}
+function validateRgb(r, g, b) {
+  validateChannel(r, "red");
+  validateChannel(g, "green");
+  validateChannel(b, "blue");
+}
+var HEX_SHORT = /^#([0-9a-f]{3})$/i;
+var HEX_LONG = /^#([0-9a-f]{6})$/i;
+function parseHex(hex) {
+  const shortMatch = HEX_SHORT.exec(hex);
+  if (shortMatch) {
+    const digits = shortMatch[1];
+    const r = digits.charAt(0);
+    const g = digits.charAt(1);
+    const b = digits.charAt(2);
+    return [
+      Number.parseInt(r + r, 16),
+      Number.parseInt(g + g, 16),
+      Number.parseInt(b + b, 16)
+    ];
+  }
+  const longMatch = HEX_LONG.exec(hex);
+  if (longMatch) {
+    const digits = longMatch[1];
+    return [
+      Number.parseInt(digits.slice(0, 2), 16),
+      Number.parseInt(digits.slice(2, 4), 16),
+      Number.parseInt(digits.slice(4, 6), 16)
+    ];
+  }
+  throw new TypeError(`Invalid hex color: "${hex}". Expected format: "#RGB" or "#RRGGBB".`);
+}
+function rgbCode(r, g, b) {
+  validateRgb(r, g, b);
+  return { open: `\x1B[38;2;${r};${g};${b}m`, close: "\x1B[39m" };
+}
+function bgRgbCode(r, g, b) {
+  validateRgb(r, g, b);
+  return { open: `\x1B[48;2;${r};${g};${b}m`, close: "\x1B[49m" };
+}
+function hexCode(hex) {
+  const [r, g, b] = parseHex(hex);
+  return rgbCode(r, g, b);
+}
+function bgHexCode(hex) {
+  const [r, g, b] = parseHex(hex);
+  return bgRgbCode(r, g, b);
+}
+function rgb(text, r, g, b) {
+  return applyStyle(text, rgbCode(r, g, b));
+}
+function bgRgb(text, r, g, b) {
+  return applyStyle(text, bgRgbCode(r, g, b));
+}
+function hex(text, hexColor) {
+  return applyStyle(text, hexCode(hexColor));
+}
+function bgHex(text, hexColor) {
+  return applyStyle(text, bgHexCode(hexColor));
+}
+
+// src/styleMethodRegistry.ts
+function readStyleMethodPairs() {
+  const { reset: _reset, ...pairs } = exports_ansiCodes;
+  return pairs;
+}
+var styleMethodPairs = Object.freeze(readStyleMethodPairs());
+var styleMethodNames = Object.freeze(Object.keys(styleMethodPairs));
+function stylePairFor(name) {
+  return styleMethodPairs[name];
+}
+
 // src/createStyle.ts
-function makeStyleFn(pair2, enabled) {
-  if (enabled) {
-    return (text) => applyStyle(text, pair2);
+function applyChain(text, methodNames, enabled) {
+  if (!enabled || text === "") {
+    return text;
+  }
+  let result = text;
+  for (let i = methodNames.length - 1;i >= 0; i--) {
+    const methodName = methodNames[i];
+    if (methodName === undefined) {
+      continue;
+    }
+    result = applyStyle(result, stylePairFor(methodName));
+  }
+  return result;
+}
+function buildChainableStyleFactory(enabled) {
+  const cache = new Map;
+  function makeKey(methodNames) {
+    return methodNames.join("|");
+  }
+  function createChainableStyle(methodNames) {
+    const key = makeKey(methodNames);
+    const cached = cache.get(key);
+    if (cached) {
+      return cached;
+    }
+    const styleFn = (text) => applyChain(text, methodNames, enabled);
+    cache.set(key, styleFn);
+    for (const name of styleMethodNames) {
+      Object.defineProperty(styleFn, name, {
+        configurable: false,
+        enumerable: true,
+        get() {
+          return createChainableStyle([...methodNames, name]);
+        }
+      });
+    }
+    return Object.freeze(styleFn);
+  }
+  return createChainableStyle;
+}
+function buildStyleMethods(createChainableStyle) {
+  const methods = {};
+  for (const methodName of styleMethodNames) {
+    methods[methodName] = createChainableStyle([methodName]);
   }
-  return (text) => text;
+  return methods;
 }
 function createStyle(options) {
   const mode = options?.mode ?? "auto";
   const enabled = resolveCapability(mode, options?.overrides);
+  const trueColorEnabled = resolveTrueColor(mode, options?.overrides);
+  const createChainableStyle = buildChainableStyleFactory(enabled);
+  const methods = buildStyleMethods(createChainableStyle);
   const instance = {
     enabled,
+    trueColorEnabled,
     apply: enabled ? (text, pair2) => applyStyle(text, pair2) : (text, _pair) => text,
-    bold: makeStyleFn(bold, enabled),
-    dim: makeStyleFn(dim, enabled),
-    italic: makeStyleFn(italic, enabled),
-    underline: makeStyleFn(underline, enabled),
-    inverse: makeStyleFn(inverse, enabled),
-    hidden: makeStyleFn(hidden, enabled),
-    strikethrough: makeStyleFn(strikethrough, enabled),
-    black: makeStyleFn(black, enabled),
-    red: makeStyleFn(red, enabled),
-    green: makeStyleFn(green, enabled),
-    yellow: makeStyleFn(yellow, enabled),
-    blue: makeStyleFn(blue, enabled),
-    magenta: makeStyleFn(magenta, enabled),
-    cyan: makeStyleFn(cyan, enabled),
-    white: makeStyleFn(white, enabled),
-    gray: makeStyleFn(gray, enabled),
-    brightRed: makeStyleFn(brightRed, enabled),
-    brightGreen: makeStyleFn(brightGreen, enabled),
-    brightYellow: makeStyleFn(brightYellow, enabled),
-    brightBlue: makeStyleFn(brightBlue, enabled),
-    brightMagenta: makeStyleFn(brightMagenta, enabled),
-    brightCyan: makeStyleFn(brightCyan, enabled),
-    brightWhite: makeStyleFn(brightWhite, enabled),
-    bgBlack: makeStyleFn(bgBlack, enabled),
-    bgRed: makeStyleFn(bgRed, enabled),
-    bgGreen: makeStyleFn(bgGreen, enabled),
-    bgYellow: makeStyleFn(bgYellow, enabled),
-    bgBlue: makeStyleFn(bgBlue, enabled),
-    bgMagenta: makeStyleFn(bgMagenta, enabled),
-    bgCyan: makeStyleFn(bgCyan, enabled),
-    bgWhite: makeStyleFn(bgWhite, enabled),
-    bgBrightBlack: makeStyleFn(bgBrightBlack, enabled),
-    bgBrightRed: makeStyleFn(bgBrightRed, enabled),
-    bgBrightGreen: makeStyleFn(bgBrightGreen, enabled),
-    bgBrightYellow: makeStyleFn(bgBrightYellow, enabled),
-    bgBrightBlue: makeStyleFn(bgBrightBlue, enabled),
-    bgBrightMagenta: makeStyleFn(bgBrightMagenta, enabled),
-    bgBrightCyan: makeStyleFn(bgBrightCyan, enabled),
-    bgBrightWhite: makeStyleFn(bgBrightWhite, enabled)
+    rgb: trueColorEnabled ? (text, r, g, b) => rgb(text, r, g, b) : (text, _r, _g, _b) => text,
+    bgRgb: trueColorEnabled ? (text, r, g, b) => bgRgb(text, r, g, b) : (text, _r, _g, _b) => text,
+    hex: trueColorEnabled ? (text, hexColor) => hex(text, hexColor) : (text, _hexColor) => text,
+    bgHex: trueColorEnabled ? (text, hexColor) => bgHex(text, hexColor) : (text, _hexColor) => text,
+    ...methods
   };
   return Object.freeze(instance);
 }
@@ -636,10 +804,14 @@ export {
   stripAnsi,
   strikethrough as strikethroughCode,
   strikethrough2 as strikethrough,
+  rgbCode,
+  rgb,
+  resolveTrueColor,
   resolveCapability,
   reset,
   red as redCode,
   red2 as red,
+  parseHex,
   padStart,
   padEnd,
   orderedList,
@@ -651,6 +823,8 @@ export {
   inverse2 as inverse,
   hidden as hiddenCode,
   hidden2 as hidden,
+  hexCode,
+  hex,
   green as greenCode,
   green2 as green,
   gray as grayCode,
@@ -689,10 +863,14 @@ export {
   bgYellow2 as bgYellow,
   bgWhite as bgWhiteCode,
   bgWhite2 as bgWhite,
+  bgRgbCode,
+  bgRgb,
   bgRed as bgRedCode,
   bgRed2 as bgRed,
   bgMagenta as bgMagentaCode,
   bgMagenta2 as bgMagenta,
+  bgHexCode,
+  bgHex,
   bgGreen as bgGreenCode,
   bgGreen2 as bgGreen,
   bgCyan as bgCyanCode,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/style",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "Terminal styling foundation for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",