@crustjs/style 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,965 @@
+/**
+* An ANSI style pair consisting of an opening and closing escape sequence.
+*
+* @example
+* ```ts
+* const bold: AnsiPair = { open: "\x1b[1m", close: "\x1b[22m" };
+* ```
+*/
+interface AnsiPair {
+	readonly open: string;
+	readonly close: string;
+}
+/** Reset all attributes. */
+declare const reset: AnsiPair;
+/** Bold / increased intensity. */
+declare const bold: AnsiPair;
+/** Dim / decreased intensity. */
+declare const dim: AnsiPair;
+/** Italic. */
+declare const italic: AnsiPair;
+/** Underline. */
+declare const underline: AnsiPair;
+/** Inverse / reverse video. */
+declare const inverse: AnsiPair;
+/** Hidden / conceal. */
+declare const hidden: AnsiPair;
+/** Strikethrough / crossed out. */
+declare const strikethrough: AnsiPair;
+declare const black: AnsiPair;
+declare const red: AnsiPair;
+declare const green: AnsiPair;
+declare const yellow: AnsiPair;
+declare const blue: AnsiPair;
+declare const magenta: AnsiPair;
+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;
+/**
+* Options for {@link unorderedList}.
+*/
+interface UnorderedListOptions {
+	/**
+	* The bullet marker character.
+	*
+	* @default "•"
+	*/
+	marker?: string;
+	/**
+	* Number of spaces between the marker and item content.
+	*
+	* @default 1
+	*/
+	markerGap?: number;
+	/**
+	* Base indentation (number of leading spaces) for the entire list.
+	*
+	* @default 0
+	*/
+	indent?: number;
+}
+/**
+* Options for {@link orderedList}.
+*/
+interface OrderedListOptions {
+	/**
+	* The starting index for numbering.
+	*
+	* @default 1
+	*/
+	start?: number;
+	/**
+	* Number of spaces between the marker (e.g. `1.`) and item content.
+	*
+	* @default 1
+	*/
+	markerGap?: number;
+	/**
+	* Base indentation (number of leading spaces) for the entire list.
+	*
+	* @default 0
+	*/
+	indent?: number;
+}
+/**
+* A single task-list item with a checked/unchecked state.
+*/
+interface TaskListItem {
+	/** The text content of the item. */
+	text: string;
+	/** Whether the item is checked (complete). */
+	checked: boolean;
+}
+/**
+* Options for {@link taskList}.
+*/
+interface TaskListOptions {
+	/**
+	* The marker shown for checked items.
+	*
+	* @default "[x]"
+	*/
+	checkedMarker?: string;
+	/**
+	* The marker shown for unchecked items.
+	*
+	* @default "[ ]"
+	*/
+	uncheckedMarker?: string;
+	/**
+	* Number of spaces between the marker and item content.
+	*
+	* @default 1
+	*/
+	markerGap?: number;
+	/**
+	* Base indentation (number of leading spaces) for the entire list.
+	*
+	* @default 0
+	*/
+	indent?: number;
+}
+/**
+* Format an array of strings as an unordered (bullet) list.
+*
+* Multiline items have continuation lines indented to align under the
+* first line's content (after the marker). The marker's visible width
+* is used for alignment so ANSI-styled markers work correctly.
+*
+* @param items - The list items (may contain `\n` for multiline content).
+* @param options - Formatting options.
+* @returns The formatted list as a single string.
+*
+* @example
+* ```ts
+* unorderedList(["alpha", "beta", "gamma"]);
+* // "• alpha\n• beta\n• gamma"
+*
+* unorderedList(["first\nsecond line"], { marker: "-" });
+* // "- first\n  second line"
+* ```
+*/
+declare function unorderedList(items: string[], options?: UnorderedListOptions): string;
+/**
+* Format an array of strings as an ordered (numbered) list.
+*
+* Marker width is computed from the widest index in the sequence so that
+* items align correctly for sequences including 1 through 100+. For example,
+* a 3-item list starting at 1 uses markers `1.`, `2.`, `3.` (all width 2),
+* while a 10-item list right-pads `1.` through `9.` to match `10.` width.
+*
+* Multiline items have continuation lines indented to align under the
+* first line's content (after the marker).
+*
+* @param items - The list items (may contain `\n` for multiline content).
+* @param options - Formatting options.
+* @returns The formatted list as a single string.
+*
+* @example
+* ```ts
+* orderedList(["alpha", "beta", "gamma"]);
+* // "1. alpha\n2. beta\n3. gamma"
+*
+* orderedList(["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"]);
+* // " 1. a\n 2. b\n ... \n10. j"
+* ```
+*/
+declare function orderedList(items: string[], options?: OrderedListOptions): string;
+/**
+* Format an array of task items as a checkbox-style task list.
+*
+* Each item is prefixed with a checked or unchecked marker. Multiline
+* items have continuation lines indented to align under the first line's
+* content (after the marker).
+*
+* @param items - The task list items with `text` and `checked` fields.
+* @param options - Formatting options.
+* @returns The formatted task list as a single string.
+*
+* @example
+* ```ts
+* taskList([
+*   { text: "Buy milk", checked: true },
+*   { text: "Write tests", checked: false },
+* ]);
+* // "[x] Buy milk\n[ ] Write tests"
+* ```
+*/
+declare function taskList(items: TaskListItem[], options?: TaskListOptions): string;
+/**
+* Horizontal alignment for a table column.
+*/
+type ColumnAlignment = "left" | "right" | "center";
+/**
+* Options for {@link table}.
+*/
+interface TableOptions {
+	/**
+	* Per-column alignment. If fewer alignments than columns are provided,
+	* remaining columns default to `"left"`. If omitted, all columns are
+	* left-aligned.
+	*/
+	align?: ColumnAlignment[];
+	/**
+	* Minimum column width (in visible characters). Columns are always at
+	* least as wide as their widest cell content regardless of this setting.
+	*
+	* @default 0
+	*/
+	minColumnWidth?: number;
+	/**
+	* Padding (number of spaces) added to each side of every cell.
+	*
+	* @default 1
+	*/
+	cellPadding?: number;
+	/**
+	* The character used for the horizontal separator line.
+	*
+	* @default "-"
+	*/
+	separatorChar?: string;
+	/**
+	* The column separator character placed between cells.
+	*
+	* @default "|"
+	*/
+	borderChar?: string;
+}
+/**
+* Format tabular data as an aligned, bordered table string.
+*
+* The table includes a header row, a separator row, and data rows.
+* Column widths are computed from the visible width of all cell content
+* (ANSI escape sequences are excluded from width calculations), so styled
+* cell values align correctly.
+*
+* @param headers - The header row cells.
+* @param rows - The data rows (each row is an array of cell strings).
+* @param options - Formatting options.
+* @returns The formatted table as a single string.
+*
+* @example
+* ```ts
+* table(
+*   ["Name", "Age"],
+*   [
+*     ["Alice", "30"],
+*     ["Bob", "25"],
+*   ],
+* );
+* // "| Name  | Age |"
+* // "|-------|-----|"
+* // "| Alice | 30  |"
+* // "| Bob   | 25  |"
+* ```
+*/
+declare function table(headers: string[], rows: string[][], options?: TableOptions): string;
+/**
+* Color emission mode for the style engine.
+*
+* - `"auto"` — Emit ANSI codes when stdout is a TTY and `NO_COLOR` is not set.
+* - `"always"` — Always emit ANSI codes regardless of terminal detection.
+* - `"never"` — Never emit ANSI codes; return plain text.
+*
+* @example
+* ```ts
+* const style = createStyle({ mode: "never" });
+* style.bold("text"); // "text" (no ANSI codes)
+* ```
+*/
+type ColorMode = "auto" | "always" | "never";
+/**
+* Capability inputs for deterministic testing.
+*
+* When provided, these override the runtime environment checks.
+* This allows tests to simulate different terminal environments
+* without modifying `process.env` or `process.stdout`.
+*/
+interface CapabilityOverrides {
+	/** Override `process.stdout.isTTY`. */
+	readonly isTTY?: boolean;
+	/** Override `process.env.NO_COLOR`. */
+	readonly noColor?: string | undefined;
+}
+/**
+* Configuration options for creating a style instance.
+*
+* @example
+* ```ts
+* const style = createStyle({ mode: "always" });
+* ```
+*/
+interface StyleOptions {
+	/** Color emission mode. Defaults to `"auto"`. */
+	readonly mode?: ColorMode;
+	/** Capability overrides for deterministic testing. */
+	readonly overrides?: CapabilityOverrides;
+}
+/**
+* A style function that applies an ANSI style pair to text,
+* respecting the configured color mode.
+*/
+type StyleFn = (text: string) => string;
+/**
+* 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 {
+	/** Whether ANSI codes will be emitted by this instance. */
+	readonly enabled: 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;
+}
+/**
+* Resolve whether ANSI color codes should be emitted.
+*
+* Resolution rules:
+* - `"always"` → `true` regardless of environment.
+* - `"never"` → `false` regardless of environment.
+* - `"auto"` → `true` only when stdout is a TTY **and** the `NO_COLOR`
+*   environment variable is not set. Any non-undefined value of `NO_COLOR`
+*   (including the empty string `""`) disables color, per the
+*   [NO_COLOR convention](https://no-color.org/).
+*
+* The `overrides` parameter allows deterministic testing by injecting
+* capability inputs instead of reading from the runtime environment.
+*
+* @param mode - The color emission mode.
+* @param overrides - Optional overrides for TTY and NO_COLOR detection.
+* @returns `true` if ANSI codes should be emitted, `false` otherwise.
+*
+* @example
+* ```ts
+* resolveCapability("auto"); // true if TTY and NO_COLOR not set
+* resolveCapability("always"); // true
+* resolveCapability("never"); // false
+* resolveCapability("auto", { isTTY: true, noColor: undefined }); // true
+* resolveCapability("auto", { isTTY: true, noColor: "" }); // false
+* ```
+*/
+declare function resolveCapability(mode: ColorMode, overrides?: CapabilityOverrides): boolean;
+/** Apply black foreground color. */
+declare function black2(text: string): string;
+/** Apply red foreground color. */
+declare function red2(text: string): string;
+/** Apply green foreground color. */
+declare function green2(text: string): string;
+/** Apply yellow foreground color. */
+declare function yellow2(text: string): string;
+/** Apply blue foreground color. */
+declare function blue2(text: string): string;
+/** Apply magenta foreground color. */
+declare function magenta2(text: string): string;
+/** Apply cyan foreground color. */
+declare function cyan2(text: string): string;
+/** Apply white foreground color. */
+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;
+/** Apply bright green foreground color. */
+declare function brightGreen3(text: string): string;
+/** Apply bright yellow foreground color. */
+declare function brightYellow3(text: string): string;
+/** Apply bright blue foreground color. */
+declare function brightBlue3(text: string): string;
+/** Apply bright magenta foreground color. */
+declare function brightMagenta3(text: string): string;
+/** Apply bright cyan foreground color. */
+declare function brightCyan3(text: string): string;
+/** Apply bright white foreground color. */
+declare function brightWhite3(text: string): string;
+/** Apply black background color. */
+declare function bgBlack3(text: string): string;
+/** Apply red background color. */
+declare function bgRed3(text: string): string;
+/** Apply green background color. */
+declare function bgGreen3(text: string): string;
+/** Apply yellow background color. */
+declare function bgYellow3(text: string): string;
+/** Apply blue background color. */
+declare function bgBlue3(text: string): string;
+/** Apply magenta background color. */
+declare function bgMagenta3(text: string): string;
+/** Apply cyan background color. */
+declare function bgCyan3(text: string): string;
+/** Apply white background color. */
+declare function bgWhite3(text: string): string;
+/** Apply bright black background color. */
+declare function bgBrightBlack3(text: string): string;
+/** Apply bright red background color. */
+declare function bgBrightRed3(text: string): string;
+/** Apply bright green background color. */
+declare function bgBrightGreen3(text: string): string;
+/** Apply bright yellow background color. */
+declare function bgBrightYellow3(text: string): string;
+/** Apply bright blue background color. */
+declare function bgBrightBlue3(text: string): string;
+/** Apply bright magenta background color. */
+declare function bgBrightMagenta3(text: string): string;
+/** Apply bright cyan background color. */
+declare function bgBrightCyan3(text: string): string;
+/** Apply bright white background color. */
+declare function bgBrightWhite3(text: string): string;
+/**
+* Create a configured style instance with mode-aware styling functions.
+*
+* The returned instance provides the full set of modifier, foreground color,
+* and background color functions. In `"never"` mode (or when `"auto"` mode
+* resolves to disabled), all functions return plain text without ANSI codes.
+* In `"always"` mode (or when `"auto"` resolves to enabled), ANSI codes are
+* emitted via the nesting-safe style engine.
+*
+* @param options - Configuration options. Defaults to `{ mode: "auto" }`.
+* @returns A frozen {@link StyleInstance} with all styling functions.
+*
+* @example
+* ```ts
+* // Auto-detect terminal capabilities
+* const s = createStyle();
+* console.log(s.bold("hello"));
+*
+* // Force color output
+* const color = createStyle({ mode: "always" });
+* console.log(color.red("error"));
+*
+* // Disable all styling
+* const plain = createStyle({ mode: "never" });
+* console.log(plain.red("error")); // "error"
+*
+* // Deterministic testing
+* const test = createStyle({
+*   mode: "auto",
+*   overrides: { isTTY: true, noColor: undefined },
+* });
+* ```
+*/
+declare function createStyle(options?: StyleOptions): StyleInstance;
+/**
+* Default style instance using `"auto"` mode.
+*
+* Emits ANSI codes when stdout is a TTY and `NO_COLOR` is not set.
+* Import this for convenient access without explicit configuration.
+*
+* @example
+* ```ts
+* import { style } from "@crustjs/style";
+*
+* console.log(style.bold("hello"));
+* console.log(style.red("error"));
+* ```
+*/
+declare const style: StyleInstance;
+/**
+* Apply **bold** (increased intensity) to text.
+*
+* @example
+* ```ts
+* bold("important") // "\x1b[1mimportant\x1b[22m"
+* ```
+*/
+declare function bold2(text: string): string;
+/**
+* Apply **dim** (decreased intensity) to text.
+*
+* @example
+* ```ts
+* dim("secondary") // "\x1b[2msecondary\x1b[22m"
+* ```
+*/
+declare function dim2(text: string): string;
+/**
+* Apply *italic* to text.
+*
+* @example
+* ```ts
+* italic("emphasis") // "\x1b[3memphasis\x1b[23m"
+* ```
+*/
+declare function italic2(text: string): string;
+/**
+* Apply underline to text.
+*
+* @example
+* ```ts
+* underline("link") // "\x1b[4mlink\x1b[24m"
+* ```
+*/
+declare function underline2(text: string): string;
+/**
+* Apply inverse (reverse video) to text.
+*
+* @example
+* ```ts
+* inverse("highlighted") // "\x1b[7mhighlighted\x1b[27m"
+* ```
+*/
+declare function inverse2(text: string): string;
+/**
+* Apply hidden (conceal) to text.
+*
+* @example
+* ```ts
+* hidden("secret") // "\x1b[8msecret\x1b[28m"
+* ```
+*/
+declare function hidden2(text: string): string;
+/**
+* Apply ~~strikethrough~~ to text.
+*
+* @example
+* ```ts
+* strikethrough("removed") // "\x1b[9mremoved\x1b[29m"
+* ```
+*/
+declare function strikethrough2(text: string): string;
+/**
+* Apply an ANSI style pair to a string with nesting-safe composition.
+*
+* When the input already contains the close sequence for the applied style
+* (e.g. from a nested style call that shares the same close code), the engine
+* reopens the outer style after each inner close to prevent style bleed.
+*
+* @param text - The string to style.
+* @param style - The ANSI pair to apply.
+* @returns The styled string, or the original string if empty.
+*
+* @example
+* ```ts
+* import { applyStyle } from "./styleEngine.ts";
+* import { bold, red } from "./ansiCodes.ts";
+*
+* // Simple usage
+* applyStyle("hello", bold); // "\x1b[1mhello\x1b[22m"
+*
+* // Nesting: bold wraps a red segment — bold reopens after red's close
+* const inner = applyStyle("world", red);
+* applyStyle(`hello ${inner}!`, bold);
+* ```
+*/
+declare function applyStyle(text: string, style: AnsiPair): string;
+/**
+* Compose multiple ANSI style pairs into a single style pair.
+*
+* The composed pair opens all styles in order and closes them in reverse
+* order. Useful for creating reusable compound styles.
+*
+* @param styles - The ANSI pairs to compose.
+* @returns A single composed ANSI pair.
+*
+* @example
+* ```ts
+* import { composeStyles } from "./styleEngine.ts";
+* import { bold, red } from "./ansiCodes.ts";
+*
+* const boldRed = composeStyles(bold, red);
+* applyStyle("error", boldRed);
+* ```
+*/
+declare function composeStyles(...styles: AnsiPair[]): AnsiPair;
+/**
+* Pad a string on the left (right-align) to the given visible width.
+*
+* Uses {@link visibleWidth} to measure the string, so ANSI escape sequences
+* are excluded from the width calculation. If the string is already at or
+* beyond the target width, it is returned unchanged.
+*
+* @param text - The string to pad (may contain ANSI escapes).
+* @param width - The target visible width.
+* @param fillChar - The character used for padding (default: space).
+* @returns The padded string.
+*
+* @example
+* ```ts
+* padStart("hi", 5);          // "   hi"
+* padStart("hi", 5, ".");     // "...hi"
+* padStart("\x1b[1mhi\x1b[22m", 5); // "   \x1b[1mhi\x1b[22m"
+* ```
+*/
+declare function padStart(text: string, width: number, fillChar?: string): string;
+/**
+* Pad a string on the right (left-align) to the given visible width.
+*
+* Uses {@link visibleWidth} to measure the string, so ANSI escape sequences
+* are excluded from the width calculation. If the string is already at or
+* beyond the target width, it is returned unchanged.
+*
+* @param text - The string to pad (may contain ANSI escapes).
+* @param width - The target visible width.
+* @param fillChar - The character used for padding (default: space).
+* @returns The padded string.
+*
+* @example
+* ```ts
+* padEnd("hi", 5);          // "hi   "
+* padEnd("hi", 5, ".");     // "hi..."
+* padEnd("\x1b[1mhi\x1b[22m", 5); // "\x1b[1mhi\x1b[22m   "
+* ```
+*/
+declare function padEnd(text: string, width: number, fillChar?: string): string;
+/**
+* Center a string within the given visible width.
+*
+* Distributes padding evenly on both sides. When the remaining space is
+* odd, the extra character is placed on the right side.
+*
+* Uses {@link visibleWidth} to measure the string, so ANSI escape sequences
+* are excluded from the width calculation. If the string is already at or
+* beyond the target width, it is returned unchanged.
+*
+* @param text - The string to center (may contain ANSI escapes).
+* @param width - The target visible width.
+* @param fillChar - The character used for padding (default: space).
+* @returns The centered string.
+*
+* @example
+* ```ts
+* center("hi", 6);          // "  hi  "
+* center("hi", 7);          // "  hi   "
+* center("\x1b[1mhi\x1b[22m", 6); // "  \x1b[1mhi\x1b[22m  "
+* ```
+*/
+declare function center(text: string, width: number, fillChar?: string): string;
+/**
+* Remove all ANSI escape sequences from a string.
+*
+* Returns the plain-text content with all styling, cursor, and control
+* escape sequences stripped. Useful for computing visible text width,
+* logging plain output, or comparing styled strings by content.
+*
+* @param text - The string potentially containing ANSI escape codes.
+* @returns The string with all ANSI escapes removed.
+*
+* @example
+* ```ts
+* import { stripAnsi } from "./stripAnsi.ts";
+*
+* stripAnsi("\x1b[1mhello\x1b[22m"); // "hello"
+* stripAnsi("no escapes"); // "no escapes"
+* ```
+*/
+declare function stripAnsi(text: string): string;
+/**
+* Compute the visible (column) width of a string.
+*
+* ANSI escape sequences are stripped before measurement. Full-width
+* characters (CJK, fullwidth forms) count as 2 columns; all other
+* printable characters count as 1.
+*
+* Only measures a single line. For multiline strings, split on `\n`
+* and measure each line individually.
+*
+* @param text - The string to measure (may contain ANSI escapes).
+* @returns The visible width in terminal columns.
+*
+* @example
+* ```ts
+* import { visibleWidth } from "./width.ts";
+*
+* visibleWidth("hello");              // 5
+* visibleWidth("\x1b[1mhello\x1b[22m"); // 5
+* visibleWidth("\u4f60\u597d");        // 4 (two CJK characters)
+* ```
+*/
+declare function visibleWidth(text: string): number;
+/**
+* Options for {@link wrapText}.
+*/
+interface WrapOptions {
+	/**
+	* Whether to perform word-aware wrapping. When `true`, the wrapper
+	* breaks at the last space before the width limit rather than mid-word.
+	* If a single word exceeds the width, it is force-broken.
+	*
+	* @default true
+	*/
+	wordBreak?: boolean;
+}
+/**
+* Wrap text to a maximum visible width, preserving ANSI style continuity
+* across line breaks.
+*
+* When a line is broken, any active ANSI styles are closed at the end of the
+* current line and reopened at the start of the next line. This ensures each
+* output line is a self-contained, properly-terminated styled string.
+*
+* Existing newlines in the input are preserved — each logical line is wrapped
+* independently.
+*
+* @param text - The input text (may contain ANSI escape codes and newlines).
+* @param width - The maximum visible width per line (in terminal columns).
+* @param options - Optional wrapping behavior configuration.
+* @returns The wrapped text with style continuity preserved.
+*
+* @example
+* ```ts
+* import { wrapText } from "./wrap.ts";
+*
+* wrapText("hello world", 5);
+* // "hello\nworld"
+*
+* wrapText("\x1b[1mhello world\x1b[22m", 5);
+* // "\x1b[1mhello\x1b[22m\n\x1b[1mworld\x1b[22m"
+* ```
+*/
+declare function wrapText(text: string, width: number, options?: WrapOptions): string;
+/**
+* A style function that transforms a string for themed terminal output.
+*
+* Theme slot functions are pure string-in/string-out transformers.
+* They may apply ANSI styling, add structural markers, or return
+* the input unchanged — depending on the theme configuration and
+* color mode.
+*/
+type ThemeSlotFn = (value: string) => string;
+/**
+* Semantic theme contract for GitHub Flavored Markdown (GFM) presentation.
+*
+* Each slot corresponds to a distinct GFM construct. A markdown renderer
+* maps parsed AST nodes to these slots to produce styled terminal output.
+* The theme itself is parser-agnostic — it only defines how to style
+* already-extracted text for each construct.
+*
+* All slots are `string => string` functions. When colors are disabled,
+* slots should preserve textual structure and readability without ANSI codes.
+*
+* @example
+* ```ts
+* import { defaultTheme } from "@crustjs/style";
+*
+* // Use theme slots to style extracted markdown content
+* const styled = defaultTheme.heading1("Introduction");
+* console.log(styled); // Bold + underlined "Introduction"
+* ```
+*/
+interface MarkdownTheme {
+	/** ATX heading level 1 text. */
+	readonly heading1: ThemeSlotFn;
+	/** ATX heading level 2 text. */
+	readonly heading2: ThemeSlotFn;
+	/** ATX heading level 3 text. */
+	readonly heading3: ThemeSlotFn;
+	/** ATX heading level 4 text. */
+	readonly heading4: ThemeSlotFn;
+	/** ATX heading level 5 text. */
+	readonly heading5: ThemeSlotFn;
+	/** ATX heading level 6 text. */
+	readonly heading6: ThemeSlotFn;
+	/** Default paragraph / body text. */
+	readonly text: ThemeSlotFn;
+	/** Italic emphasis (`*text*` or `_text_`). */
+	readonly emphasis: ThemeSlotFn;
+	/** Bold / strong emphasis (`**text**` or `__text__`). */
+	readonly strong: ThemeSlotFn;
+	/** Bold + italic (`***text***`). */
+	readonly strongEmphasis: ThemeSlotFn;
+	/** Strikethrough (`~~text~~`). */
+	readonly strikethrough: ThemeSlotFn;
+	/** Inline code span (`` `code` ``). */
+	readonly inlineCode: ThemeSlotFn;
+	/** Link display text (`[text](url)`). */
+	readonly linkText: ThemeSlotFn;
+	/** Link destination URL. */
+	readonly linkUrl: ThemeSlotFn;
+	/** Autolink display text (`<https://...>`). */
+	readonly autolink: ThemeSlotFn;
+	/** Blockquote prefix/marker (e.g. `>`). */
+	readonly blockquoteMarker: ThemeSlotFn;
+	/** Blockquote body text content. */
+	readonly blockquoteText: ThemeSlotFn;
+	/** Unordered list bullet marker. */
+	readonly listMarker: ThemeSlotFn;
+	/** Ordered list number marker (e.g. `1.`). */
+	readonly orderedListMarker: ThemeSlotFn;
+	/** Task list checked marker (e.g. `[x]`). */
+	readonly taskChecked: ThemeSlotFn;
+	/** Task list unchecked marker (e.g. `[ ]`). */
+	readonly taskUnchecked: ThemeSlotFn;
+	/** Code fence delimiter (e.g. ` ``` `). */
+	readonly codeFence: ThemeSlotFn;
+	/** Code block info string / language label. */
+	readonly codeInfo: ThemeSlotFn;
+	/** Code block body text. */
+	readonly codeText: ThemeSlotFn;
+	/** Thematic break / horizontal rule. */
+	readonly thematicBreak: ThemeSlotFn;
+	/** Table header cell text. */
+	readonly tableHeader: ThemeSlotFn;
+	/** Table body cell text. */
+	readonly tableCell: ThemeSlotFn;
+	/** Table border / separator characters. */
+	readonly tableBorder: ThemeSlotFn;
+	/** Image alt text. */
+	readonly imageAltText: ThemeSlotFn;
+	/** Image URL / destination. */
+	readonly imageUrl: ThemeSlotFn;
+}
+/**
+* Partial theme override type for {@link createTheme}.
+*
+* Allows overriding any subset of theme slots while inheriting
+* defaults for the rest.
+*/
+type PartialMarkdownTheme = Partial<MarkdownTheme>;
+/**
+* Build a default {@link MarkdownTheme} from a {@link StyleInstance}.
+*
+* The returned theme uses the style instance's modifier and color functions,
+* so color emission respects the instance's configured mode (`auto` / `always`
+* / `never`). When colors are disabled the slots return the input unchanged
+* (identity functions), preserving textual structure and readability.
+*
+* @param s - The style instance to derive theme functions from.
+* @returns A frozen {@link MarkdownTheme} with readable default styles.
+*
+* @example
+* ```ts
+* import { createStyle } from "@crustjs/style";
+* import { buildDefaultTheme } from "./defaultTheme.ts";
+*
+* const theme = buildDefaultTheme(createStyle({ mode: "always" }));
+* console.log(theme.heading1("Title")); // bold + underlined
+* ```
+*/
+declare function buildDefaultMarkdownTheme(s: StyleInstance): MarkdownTheme;
+/**
+* Options for {@link createMarkdownTheme}.
+*/
+interface CreateMarkdownThemeOptions {
+	/**
+	* Style configuration options (mode and capability overrides).
+	*
+	* When provided, a new {@link StyleInstance} is created with these
+	* options and used to build the default theme base. When omitted,
+	* the default `"auto"` mode is used.
+	*/
+	readonly style?: StyleOptions;
+	/**
+	* Partial theme overrides to merge on top of the default theme.
+	*
+	* Only the slots you provide are overridden; all other slots
+	* inherit from the default theme.
+	*
+	* @example
+	* ```ts
+	* createMarkdownTheme({
+	*   overrides: {
+	*     heading1: (value) => `## ${value.toUpperCase()} ##`,
+	*   },
+	* });
+	* ```
+	*/
+	readonly overrides?: PartialMarkdownTheme;
+}
+/**
+* Create a {@link MarkdownTheme} with optional style configuration and
+* partial slot overrides.
+*
+* The factory builds a default theme using the specified style mode and
+* then applies any provided overrides on top. This enables consumers to
+* customize individual slots while inheriting defaults for the rest.
+*
+* @param options - Style configuration and/or partial theme overrides.
+* @returns A frozen {@link MarkdownTheme} instance.
+*
+* @example
+* ```ts
+* import { createMarkdownTheme } from "@crustjs/style";
+*
+* // Default theme with auto mode
+* const theme = createMarkdownTheme();
+*
+* // Force colors + custom heading
+* const custom = createMarkdownTheme({
+*   style: { mode: "always" },
+*   overrides: {
+*     heading1: (value) => `# ${value.toUpperCase()}`,
+*   },
+* });
+* ```
+*/
+declare function createMarkdownTheme(options?: CreateMarkdownThemeOptions): MarkdownTheme;
+/**
+* Default markdown theme using `"auto"` mode.
+*
+* Emits styled output when stdout is a TTY and `NO_COLOR` is not set.
+* Import this for convenient access without explicit configuration.
+*
+* @example
+* ```ts
+* import { defaultTheme } from "@crustjs/style";
+*
+* console.log(defaultTheme.heading1("Title"));
+* console.log(defaultTheme.strong("important"));
+* ```
+*/
+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 };