ansimax 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -1,146 +1,606 @@
-type ColorMode = 'basic' | '256' | 'truecolor';
-type AnimationSpeed = 'slow' | 'normal' | 'fast';
+/** Color rendering capability. 'none' suppresses all color output. */
+type ColorMode = 'none' | 'basic' | '256' | 'truecolor' | 'auto';
+/** Animation pacing multiplier preset. */
+type AnimationSpeed = 'slow' | 'normal' | 'fast' | 'instant';
 interface AnsimaxConfig {
+    /** Color rendering mode. 'auto' (default) defers to terminal detection. */
     colorMode?: ColorMode;
+    /** Animation speed preset. */
     animationSpeed?: AnimationSpeed;
-    asciiFont?: 'big' | 'small';
+    /** Default ASCII font name. Accepts built-in ('big', 'small') or custom names. */
+    asciiFont?: string;
+    /** UI locale. Currently informational; reserved for future i18n. */
     locale?: string;
+    /** Active theme name. Setting this calls themes.tryUse(name). */
     theme?: string;
+    /** Disable all motion (overrides animationSpeed). Useful for accessibility. */
+    reducedMotion?: boolean;
+}
+type ConfigChangeListener = (config: Required<AnsimaxConfig>) => void;
+type ConfigKey = keyof AnsimaxConfig;
+type ConfigKeyListener<K extends ConfigKey> = (newValue: Required<AnsimaxConfig>[K], oldValue: Required<AnsimaxConfig>[K]) => void;
+declare const DEFAULTS: Readonly<Required<AnsimaxConfig>>;
+/**
+ * Subscribe to ANY configuration change.
+ *
+ * @param listener Called with the new config whenever it changes
+ * @returns Unsubscribe function
+ *
+ * @example
+ *   const off = onConfigChange((c) => console.log('Theme:', c.theme));
+ *   // Later: off();
+ */
+declare const onConfigChange: (listener: ConfigChangeListener) => (() => void);
+/**
+ * Subscribe to changes of a SPECIFIC key. Listener fires only when that
+ * key's value actually changes (not on every config update).
+ *
+ * @example
+ *   const off = onConfigKeyChange('theme', (newT, oldT) => updateUI(newT));
+ */
+declare const onConfigKeyChange: <K extends ConfigKey>(key: K, listener: ConfigKeyListener<K>) => (() => void);
+/**
+ * Pause listener notifications until resume() is called. Useful for
+ * batch updates where you don't want intermediate states to fire
+ * subscribers.
+ *
+ * @example
+ *   pauseListeners();
+ *   configure({ theme: 'matrix' });
+ *   configure({ colorMode: 'none' });
+ *   resumeListeners(); // fires once with final config
+ */
+declare const pauseListeners: () => void;
+declare const resumeListeners: () => void;
+interface ConfigureOptions {
+    /**
+     * Strict mode rejects unknown keys with RangeError instead of
+     * silently ignoring them. Useful for catching typos in config files.
+     * Default: false.
+     */
+    strict?: boolean;
 }
-declare const configure: (opts?: AnsimaxConfig) => void;
+/**
+ * Update one or more configuration values. Validates inputs strictly —
+ * invalid colorMode or animationSpeed throws a RangeError, wrong types
+ * throw a TypeError. Partial updates merge with current state.
+ *
+ * Triggers subscribed listeners ONLY if values actually changed.
+ *
+ * @example
+ *   configure({ colorMode: 'none', theme: 'matrix' });
+ *   configure({ theme: 'nord' }, { strict: true });
+ */
+declare const configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
+/** Get a snapshot of the current configuration. */
 declare const getConfig: () => Required<AnsimaxConfig>;
+/** Numeric multiplier for animation timings. Returns 0 in reducedMotion. */
 declare const getSpeedMultiplier: () => number;
+/**
+ * Reset configuration to defaults. Triggers listeners if state differs
+ * from defaults. Side effects are applied (NO_COLOR cleared, theme
+ * reverts to 'dracula', etc.).
+ */
+declare const resetConfig: () => void;
+/** Read a single config field by name (typed). */
+declare const getConfigValue: <K extends keyof AnsimaxConfig>(key: K) => Required<AnsimaxConfig>[K];
+/**
+ * Temporarily override config for the duration of `fn`, then restore
+ * the previous state. Listeners fire for both the override and the
+ * restore.
+ *
+ * @example
+ *   await withConfig({ reducedMotion: true }, async () => {
+ *     await runAccessibilityChecks();
+ *   });
+ */
+declare const withConfig: <T>(overrides: AnsimaxConfig, fn: () => T | Promise<T>) => T | Promise<T>;
 
-type FrameCallback = (frame: string, index: number) => string;
-interface PlayOptions {
-    interval?: number;
-    repeat?: number;
-    clearOnFinish?: boolean;
-    onFrame?: FrameCallback | null;
-    signal?: AbortSignal;
-}
-interface LiveOptions {
-    fps?: number;
-    autoStart?: boolean;
+declare const ESC = "\u001B";
+declare const CSI = "\u001B[";
+/** OSC sequence introducer (Operating System Command). */
+declare const OSC = "\u001B]";
+/** String terminator used to close OSC sequences. */
+declare const ST = "\u001B\\";
+/** BEL — alternative OSC terminator (older terminals). */
+declare const BEL = "\u0007";
+type AnsiCode = number;
+/** Default fallback dimensions when stdout is not a TTY. */
+declare const DEFAULT_TERM_COLS = 80;
+declare const DEFAULT_TERM_ROWS = 24;
+declare const cursor: {
+    readonly up: (n?: number) => string;
+    readonly down: (n?: number) => string;
+    readonly right: (n?: number) => string;
+    readonly left: (n?: number) => string;
+    readonly to: (x: number, y: number) => string;
+    /** Move cursor to absolute column n (1-based). */
+    readonly column: (n: number) => string;
+    /** Save cursor (CSI s — DEC private). */
+    readonly save: () => string;
+    /** Restore cursor (CSI u). */
+    readonly restore: () => string;
+    /** Save cursor (ESC 7 — VT100 standard). */
+    readonly saveCompat: () => string;
+    /** Restore cursor (ESC 8). */
+    readonly restoreCompat: () => string;
+    readonly hide: () => string;
+    readonly show: () => string;
+    /** Query cursor position. Terminal responds with CSI <row>;<col>R. */
+    readonly position: () => string;
+    /** Move cursor to next line (CR + line down). */
+    readonly nextLine: (n?: number) => string;
+    /** Move cursor to previous line. */
+    readonly prevLine: (n?: number) => string;
+};
+/**
+ * Hide cursor and register an exit handler that restores it on crash/SIGINT.
+ * Use this instead of writing `cursor.hide()` directly when you care about
+ * leaving the user's shell in a clean state.
+ */
+declare const hideCursor: () => boolean;
+declare const showCursor: () => boolean;
+type EraseMode = 'down' | 'up' | 'all';
+declare const screen: {
+    readonly clear: () => string;
+    /** Alias for clear() — covers `screen.clearAll()` callers. */
+    readonly clearAll: () => string;
+    readonly clearLine: () => string;
+    readonly clearRight: () => string;
+    readonly clearLeft: () => string;
+    readonly clearDown: () => string;
+    readonly clearUp: () => string;
+    readonly eraseDisplay: (mode?: EraseMode) => string;
+    readonly scrollUp: (n?: number) => string;
+    readonly scrollDown: (n?: number) => string;
+};
+declare const FG: {
+    readonly black: 30;
+    readonly red: 31;
+    readonly green: 32;
+    readonly yellow: 33;
+    readonly blue: 34;
+    readonly magenta: 35;
+    readonly cyan: 36;
+    readonly white: 37;
+    readonly brightBlack: 90;
+    readonly brightRed: 91;
+    readonly brightGreen: 92;
+    readonly brightYellow: 93;
+    readonly brightBlue: 94;
+    readonly brightMagenta: 95;
+    readonly brightCyan: 96;
+    readonly brightWhite: 97;
+};
+declare const BG: {
+    readonly black: 40;
+    readonly red: 41;
+    readonly green: 42;
+    readonly yellow: 43;
+    readonly blue: 44;
+    readonly magenta: 45;
+    readonly cyan: 46;
+    readonly white: 47;
+    readonly brightBlack: 100;
+    readonly brightRed: 101;
+    readonly brightGreen: 102;
+    readonly brightYellow: 103;
+    readonly brightBlue: 104;
+    readonly brightMagenta: 105;
+    readonly brightCyan: 106;
+    readonly brightWhite: 107;
+};
+declare const STYLE: {
+    readonly reset: 0;
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly italic: 3;
+    readonly underline: 4;
+    readonly blink: 5;
+    readonly inverse: 7;
+    readonly hidden: 8;
+    readonly strikethrough: 9;
+};
+declare const sgr: (...codes: AnsiCode[]) => string;
+declare const reset: () => string;
+declare const fgRgb: (r: number, g: number, b: number) => string;
+declare const bgRgb: (r: number, g: number, b: number) => string;
+declare const fg256: (n: number) => string;
+declare const bg256: (n: number) => string;
+/**
+ * Set the terminal window title (OSC 2). Most terminals support this.
+ * Returns the escape sequence; caller is responsible for writing it.
+ */
+declare const setTitle: (text: string) => string;
+/**
+ * Make `text` a clickable hyperlink to `url` (OSC 8).
+ * Supported by iTerm2, Terminal.app (macOS 13+), WezTerm, Kitty, modern xterm.
+ * Falls back gracefully (just prints text) on terminals that don't support it.
+ */
+declare const link: (text: string, url: string) => string;
+/** Ring the terminal bell. Most modern terminals visualize, not audio. */
+declare const bell: () => string;
+type ColorSupport = 'none' | 'basic' | '256' | 'truecolor';
+type ColorLevel = 0 | 1 | 2 | 3;
+declare const supportsColor: () => ColorSupport;
+declare const supportsColorLevel: () => ColorLevel;
+/**
+ * Reset the cached capability — call after changing FORCE_COLOR /
+ * NO_COLOR env vars at runtime, or before a test that needs to
+ * exercise different code paths.
+ */
+declare const resetColorSupportCache: () => void;
+/** Returns terminal width in columns. Falls back to DEFAULT_TERM_COLS. */
+declare const getTerminalWidth: () => number;
+/** Returns terminal height in rows. Falls back to DEFAULT_TERM_ROWS. */
+declare const getTerminalHeight: () => number;
+declare const stripAnsi$2: (str: string) => string;
+/** Sync write to stdout. Returns false if stdout is missing or full. */
+declare const write: (str: string) => boolean;
+/** Sync write to stderr. Useful for CLI errors and logs. */
+declare const writeErr: (str: string) => boolean;
+declare const writeln: (str?: string) => boolean;
+declare const writelnErr: (str?: string) => boolean;
+/**
+ * Async write with backpressure handling.
+ *  - Resolves immediately when the buffer accepted the data
+ *  - Waits for `'drain'` when full
+ *  - Resolves on `'error'` instead of hanging forever
+ *  - No-ops gracefully if stdout is missing
+ *  - Optional timeout (ms) — resolves anyway after timeout to prevent
+ *    infinite hangs on broken streams
+ */
+interface WriteAsyncOptions {
+    /** Max time (ms) to wait for drain. Default: 5000. 0 disables. */
+    timeout?: number;
 }
-interface LiveController {
-    start: () => void;
-    stop: () => void;
-    update: (frame: string) => void;
+declare const writeAsync: (str: string, opts?: WriteAsyncOptions) => Promise<void>;
+interface OutputBuffer {
+    /** Append a string to the buffer. */
+    push(str: string): OutputBuffer;
+    /** Append a string with a trailing newline. */
+    pushln(str?: string): OutputBuffer;
+    /** Append `str` only when `cond` is truthy. Useful for conditional escapes. */
+    pushIf(cond: unknown, str: string): OutputBuffer;
+    /** Get the buffered content without flushing. */
+    toString(): string;
+    /** Number of characters currently buffered. */
+    length(): number;
+    /** Clear the buffer without writing. */
+    reset(): OutputBuffer;
+    /** Flush to stdout synchronously. Returns false on backpressure. */
+    flush(): boolean;
+    /** Flush to stdout asynchronously. Awaits drain on backpressure. */
+    flushAsync(opts?: WriteAsyncOptions): Promise<void>;
 }
-declare const frames: {
-    play: (frames: string[], opts?: PlayOptions) => Promise<void>;
-    generate: (count: number, fn: (i: number, total: number) => string) => string[];
-    live: (opts?: LiveOptions) => LiveController;
-    morph: (frameA: string, frameB: string, steps?: number, charset?: string) => string[];
-    presets: {
-        loadingBar: (opts?: {
-            width?: number;
-            char?: string;
-            empty?: string;
-            label?: string;
-        }) => string[];
-        ball: (opts?: {
-            width?: number;
-            char?: string;
-        }) => string[];
-        breathe: (text: string, opts?: {
-            steps?: number;
-        }) => string[];
-        typeDelete: (text: string, opts?: {
-            cursor?: string;
-        }) => string[];
-    };
-};
-
-type SpinnerType = 'dots' | 'dots2' | 'line' | 'arrow' | 'bounce' | 'star' | 'pong' | 'aesthetic' | 'blocks' | 'moon' | 'clock';
-declare const SPINNERS: Record<SpinnerType, string[]>;
-interface SpinOptions {
-    type?: SpinnerType;
-    interval?: number;
-    color?: string | null;
-    prefix?: string;
-    suffix?: string;
-    persist?: boolean;
+declare const createOutputBuffer: () => OutputBuffer;
+/** Recommended frame interval (ms) for animations. ~60 fps. */
+declare const FRAME_MS = 16;
+interface SleepOptions {
+    /** Optional AbortSignal — sleep resolves immediately when aborted. */
     signal?: AbortSignal;
-    reducedMotion?: boolean;
 }
-interface ProgressOptions {
-    width?: number;
-    char?: string;
-    emptyChar?: string;
-    showPercentage?: boolean;
-    color?: string | null;
-    label?: string;
+/**
+ * Pause for `ms` milliseconds. Cancellable via AbortSignal.
+ * - Negative or NaN ms is clamped to 0
+ * - Resolves silently on abort (no rejection)
+ * - Cleans up timer + listener on every path
+ */
+declare const sleep: (ms: number, opts?: SleepOptions) => Promise<void>;
+/**
+ * Like sleep, but rounds the wait time up to the next frame boundary.
+ * Useful inside animation loops to throttle output to a reasonable framerate.
+ */
+declare const sleepFrame: (ms?: number, opts?: SleepOptions) => Promise<void>;
+
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
 }
-interface Task {
-    text: string;
-    fn: () => Promise<unknown>;
+declare const clamp: (n: number, min: number, max: number) => number;
+declare const lerp: (a: number, b: number, t: number) => number;
+/** Returns true when a string is a valid 3- or 6-digit hex color. */
+declare const isHexColor: (hex: string) => boolean;
+/**
+ * Parses a hex color string to RGB. Throws on invalid input.
+ * Use isHexColor() first if you need fail-soft behaviour.
+ */
+declare const hexToRgb: (hex: string) => RGB;
+/** Converts R, G, B values to a hex string. Values are clamped to 0–255. */
+declare const rgbToHex: (r: number, g: number, b: number) => string;
+/** Linearly interpolates between two RGB colors. t is clamped to [0, 1]. */
+declare const lerpColor: (a: RGB, b: RGB, t: number) => RGB;
+/**
+ * Multi-stop gradient interpolation. Given a list of color stops and t in [0, 1],
+ * returns the interpolated RGB. Equivalent to a CSS `linear-gradient` sampler.
+ *
+ * Defensive: empty colors throws (no sensible default), single color returns
+ * that color regardless of t, t outside [0,1] is clamped automatically.
+ *
+ * @example
+ * gradientColor([red, yellow, green], 0.5) → yellow
+ * gradientColor([red, blue], 0.0) → red
+ * gradientColor([red, blue], -1)  → red (t clamped to 0)
+ * gradientColor([red, blue], 99)  → blue (t clamped to 1)
+ */
+declare const gradientColor: (colors: RGB[], t: number) => RGB;
+declare const rgbTo256: (r: number, g: number, b: number) => number;
+declare const stripAnsi$1: (str: string) => string;
+/**
+ * Width of a single character (or grapheme) in terminal cells.
+ *  - 0 for combining marks, ZWJ, VS, BOM
+ *  - 2 for wide CJK / emoji presentation
+ *  - 1 for everything else
+ */
+declare const charWidth: (char: string) => number;
+/**
+ * Iterate grapheme clusters in a string. A grapheme is a user-perceived
+ * character — e.g. '👨‍👩‍👧‍👦' is one grapheme even though it's 7 codepoints.
+ *
+ * Uses Intl.Segmenter when available, otherwise falls back to Unicode
+ * codepoint iteration via [...str].
+ */
+declare const graphemes: (str: string) => Generator<string, void, unknown>;
+/**
+ * Visible terminal width of a string.
+ *
+ * Strips ANSI escapes first, then sums grapheme cluster widths using
+ * the Unicode-aware `charWidth()`. This is the function every layout
+ * helper (padding, centering, table columns) should use.
+ */
+declare const visibleLen: (str: string) => number;
+declare const sliceAnsi: (str: string, start: number, end?: number) => string;
+/**
+ * Truncates a string with ANSI escapes to a max visible width.
+ * Preserves color codes that started before the cut and emits a final reset.
+ * Now Unicode-aware (handles CJK, emoji, graphemes correctly).
+ */
+declare const truncateAnsi: (str: string, width: number, ellipsis?: string) => string;
+declare const padEnd: (str: string, width: number, ch?: string) => string;
+declare const padStart: (str: string, width: number, ch?: string) => string;
+declare const center: (str: string, width: number, ch?: string) => string;
+/** Repeats a string until its visible length reaches the target width. */
+declare const repeatVisible: (str: string, width: number) => string;
+/**
+ * Current terminal size. Reads from process.stdout each call so callers
+ * always get up-to-date dimensions after a resize.
+ *
+ * Falls back to 80×24 (classic VT100 default) if stdout doesn't expose
+ * dimensions. Negative or non-number values are also handled.
+ */
+declare const termSize: () => {
+    cols: number;
+    rows: number;
+};
+type ResizeListener = (size: {
+    cols: number;
+    rows: number;
+}) => void;
+interface OnResizeOptions {
+    /**
+     * Throttle interval in ms. Coalesces rapid resize events (which can
+     * fire dozens per second during active drag-resize). Default: 50ms.
+     * Pass 0 to disable throttling.
+     */
+    throttle?: number;
 }
-interface TaskResult {
-    success: boolean;
-    result?: unknown;
-    error?: Error;
+/**
+ * Subscribe to terminal resize events. Returns a function that unsubscribes.
+ * Useful for dashboards and live UIs that need responsive re-layout.
+ *
+ * By default coalesces rapid resize events at ~20fps (50ms throttle) to
+ * avoid flooding the redraw path.
+ *
+ * @example
+ * const off = onResize(({ cols, rows }) => redraw(cols, rows));
+ * // Later: off();
+ */
+declare const onResize: (listener: ResizeListener, opts?: OnResizeOptions) => (() => void);
+/**
+ * ANSI-aware word wrap. Tokens are split by whitespace, but ANSI escape
+ * sequences within tokens are preserved verbatim. Visible width is
+ * computed Unicode-correctly. Tokens longer than `width` are soft-broken
+ * into chunks that respect ANSI boundaries.
+ */
+declare const wrapAnsi: (text: string, width: number) => string[];
+/**
+ * Backwards-compat alias. Newer code should use `wrapAnsi`.
+ * Identical behavior — wrapAnsi is the same algorithm but ANSI-aware.
+ */
+declare const wordWrap: (text: string, width: number) => string[];
+interface DebounceOptions {
+    /**
+     * Maximum time (ms) to wait before forcing invocation, even if calls
+     * keep arriving. Useful for resize handlers — without maxWait, an
+     * actively-resized window never fires its handler.
+     */
+    maxWait?: number;
 }
-interface TaskOptions {
-    type?: SpinnerType;
-    spinColor?: string;
-    parallel?: boolean;
+/**
+ * Debounce a function: delay invocation until `ms` have passed since the
+ * last call. Optional `maxWait` guarantees invocation within that window
+ * even if calls keep coming.
+ */
+declare const debounce: <T extends (...args: never[]) => unknown>(fn: T, ms: number, opts?: DebounceOptions) => T & {
+    cancel(): void;
+    flush(): void;
+};
+/**
+ * Throttle a function: invoke at most once per `ms` window. The first
+ * call fires immediately; subsequent calls inside the window are
+ * coalesced and the last one fires when the window expires.
+ */
+declare const throttle: <T extends (...args: never[]) => unknown>(fn: T, ms: number) => T & {
+    cancel(): void;
+};
+/**
+ * Schedules a callback for the next animation frame (~16ms).
+ * Inspired by browser `requestAnimationFrame` — useful for coalescing
+ * multiple render requests into a single paint.
+ *
+ * Returns a handle that can be passed to `cancelTerminalFrame()`.
+ */
+type FrameHandle = ReturnType<typeof setTimeout>;
+declare const requestTerminalFrame: (cb: () => void) => FrameHandle;
+declare const cancelTerminalFrame: (handle: FrameHandle) => void;
+/**
+ * Coalesce sync work to the next event loop turn (microtask + I/O).
+ * Falls back to setTimeout(0) in environments without setImmediate.
+ */
+declare const nextTick: (cb: () => void) => void;
+interface MemoizeOptions<A extends unknown[]> {
+    /** Max cached entries before FIFO eviction. Default: 100. */
+    max?: number;
+    /**
+     * Key extractor — given the args, returns the cache key.
+     * Use to memoize multi-arg fns: `keyFn: (a, b) => a + ':' + b`.
+     * Default: first arg.
+     */
+    keyFn?: (...args: A) => unknown;
 }
-declare const loader: {
-    spin: (text?: string, opts?: SpinOptions) => ((message?: string, success?: boolean) => void);
-    dots: (text?: string, opts?: {
-        interval?: number;
-        max?: number;
-        signal?: AbortSignal;
-    }) => (() => void);
-    progress: (percent: number, label?: string, opts?: ProgressOptions) => void;
-    progressAnimate: (steps: number, label?: string, opts?: ProgressOptions & {
-        delay?: number;
-        signal?: AbortSignal;
-    }) => Promise<void>;
-    tasks: (taskList: Task[], opts?: TaskOptions) => Promise<TaskResult[]>;
-    custom: (frames: string[], text?: string, opts?: {
-        interval?: number;
-        signal?: AbortSignal;
-    }) => (() => void);
-    countdown: (seconds: number, opts?: {
-        label?: string;
-        color?: string;
-        signal?: AbortSignal;
-    }) => Promise<void>;
-    spinners: Record<SpinnerType, string[]>;
+/**
+ * Memoize a function with bounded FIFO cache.
+ *
+ * Single-arg simple form (passes the arg as cache key):
+ *   memoize((n: number) => expensive(n))
+ *
+ * Multi-arg with key extractor:
+ *   memoize((a, b, c) => f(a,b,c), { keyFn: (a, b, c) => `${a}:${b}:${c}` })
+ *
+ * Returns the memoized fn with `clear()` and `size()` methods.
+ */
+declare const memoize: <A extends unknown[], V>(fn: (...args: A) => V, optsOrMax?: number | MemoizeOptions<A>) => ((...args: A) => V) & {
+    clear(): void;
+    size(): number;
 };
+type DiffType = 'added' | 'removed' | 'changed';
+interface LineDiff {
+    /** Index of the line that changed. */
+    index: number;
+    /** New content of that line (empty string for 'removed'). */
+    line: string;
+    /** What kind of change this line represents. */
+    type: DiffType;
+}
+/**
+ * Compute line-level differences between two multi-line frames.
+ * Returns only the lines that changed, with their indices and type.
+ *
+ * Useful for damage-tracked redraws: instead of clearing and re-rendering
+ * the full frame, redraw only the changed lines.
+ */
+declare const diffLines: (oldFrame: string, newFrame: string) => LineDiff[];
+/**
+ * Wraps a function so it only invokes the underlying fn ONCE.
+ * Subsequent calls return the cached first result. Useful for one-time
+ * setup / lazy initialization that must not run twice.
+ */
+declare const once: <T extends (...args: never[]) => unknown>(fn: T) => T;
+/**
+ * Escape a string for safe use inside a regex literal. Escapes
+ * `.`, `*`, `+`, `?`, `^`, `$`, `(`, `)`, `[`, `]`, `{`, `}`, `|`,
+ * `\`, `/`.
+ *
+ * @example
+ *   new RegExp(escapeRegex('a.b+c')); // matches "a.b+c" literally
+ */
+declare const escapeRegex: (str: string) => string;
+/**
+ * JSON.stringify replacement that handles BigInt and circular refs.
+ * BigInt is serialized as its string form. Circular references emit
+ * `"[Circular]"` placeholder instead of throwing.
+ *
+ * @example
+ *   safeJson({ n: 1n, ref: obj });  // never throws
+ */
+declare const safeJson: (value: unknown, indent?: number) => string;
+/**
+ * Pad a string equally on both sides until it reaches `width`.
+ * If the padding can't be split evenly, the right side gets the extra char.
+ *
+ * @example
+ *   padBoth('hi', 6) → '  hi  '
+ *   padBoth('hi', 5) → ' hi  '
+ */
+declare const padBoth: (str: string, width: number, ch?: string) => string;
 
 type ColorFn = (text: string) => string;
+
 /** Override color suppression at runtime. Pass true to suppress, false to force on. */
 declare const setNoColor: (v: boolean) => void;
-/** Reset to auto-detect mode (reads NO_COLOR + isTTY at call time). */
+/** Reset to auto-detect mode. */
 declare const resetNoColor: () => void;
 /** Returns true when colors should be suppressed. */
 declare const isNoColor: () => boolean;
+/** Numeric color support level (0-3). */
+declare const colorLevel: () => ColorLevel;
+/** Clear adaptive escape caches. Call after a color level change. */
+declare const clearColorCache: () => void;
 declare const compose: (...fns: ColorFn[]) => ColorFn;
-declare const gradient: (text: string, stops: string[]) => string;
+declare const stripAnsi: (str: string) => string;
+interface GradientOptions {
+    /** Skip ANSI escapes in the input instead of overwriting them. */
+    preserveAnsi?: boolean;
+}
+declare const gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
 declare const rainbow: ColorFn;
-declare const presets: {
-    sunset: (t: string) => string;
-    ocean: (t: string) => string;
-    fire: (t: string) => string;
-    neon: (t: string) => string;
-    forest: (t: string) => string;
-    aurora: (t: string) => string;
-    candy: (t: string) => string;
-    gold: (t: string) => string;
+declare const PRESET_DEFS: {
+    readonly sunset: readonly ["#ff6b6b", "#feca57", "#48dbfb"];
+    readonly ocean: readonly ["#0575e6", "#021b79"];
+    readonly fire: readonly ["#f7971e", "#ffd200", "#ff0000"];
+    readonly neon: readonly ["#f953c6", "#b91d73"];
+    readonly forest: readonly ["#134e5e", "#71b280"];
+    readonly aurora: readonly ["#00c6ff", "#0072ff", "#7e57c2"];
+    readonly candy: readonly ["#fd79a8", "#a29bfe", "#74b9ff"];
+    readonly gold: readonly ["#f7971e", "#ffd200"];
 };
+type PresetName = keyof typeof PRESET_DEFS;
+/** All available built-in gradient preset names. */
+declare const presetNames: readonly PresetName[];
+/**
+ * Register a custom gradient preset accessible via `color.<name>(text)`.
+ * Throws if `name` collides with an existing color method.
+ *
+ * @example
+ *   registerPreset('mango', ['#ff5e3a', '#ff9500']);
+ *   color.mango('hello');
+ */
+declare const registerPreset: (name: string, stops: string[]) => void;
+/** List all registered presets (built-in + custom). */
+declare const listPresets: () => string[];
+declare const presets: Record<string, ColorFn>;
+interface ColorChain {
+    black: () => ColorChain;
+    red: () => ColorChain;
+    green: () => ColorChain;
+    yellow: () => ColorChain;
+    blue: () => ColorChain;
+    magenta: () => ColorChain;
+    cyan: () => ColorChain;
+    white: () => ColorChain;
+    gray: () => ColorChain;
+    brightRed: () => ColorChain;
+    brightGreen: () => ColorChain;
+    brightYellow: () => ColorChain;
+    brightBlue: () => ColorChain;
+    bold: () => ColorChain;
+    dim: () => ColorChain;
+    italic: () => ColorChain;
+    underline: () => ColorChain;
+    inverse: () => ColorChain;
+    strikethrough: () => ColorChain;
+    rgb: (r: number, g: number, b: number) => ColorChain;
+    hex: (h: string) => ColorChain;
+    bgRgb: (r: number, g: number, b: number) => ColorChain;
+    bgHex: (h: string) => ColorChain;
+    apply: (text: unknown) => string;
+    /** Returns the composed function for reuse. */
+    fn: () => ColorFn;
+}
+/** Start a new color chain. */
+declare const chain: () => ColorChain;
 declare const color: {
-    sunset: (t: string) => string;
-    ocean: (t: string) => string;
-    fire: (t: string) => string;
-    neon: (t: string) => string;
-    forest: (t: string) => string;
-    aurora: (t: string) => string;
-    candy: (t: string) => string;
-    gold: (t: string) => string;
     black: ColorFn;
     red: ColorFn;
     green: ColorFn;
@@ -159,7 +619,7 @@ declare const color: {
     brightWhite: ColorFn;
     gray: ColorFn;
     grey: ColorFn;
-    orange: (t: string) => string;
+    orange: (t: unknown) => string;
     purple: ColorFn;
     bgBlack: ColorFn;
     bgRed: ColorFn;
@@ -169,69 +629,48 @@ declare const color: {
     bgMagenta: ColorFn;
     bgCyan: ColorFn;
     bgWhite: ColorFn;
-    bold: (t: string) => string;
-    dim: (t: string) => string;
-    italic: (t: string) => string;
-    underline: (t: string) => string;
-    blink: (t: string) => string;
-    inverse: (t: string) => string;
-    strikethrough: (t: string) => string;
-    hidden: (t: string) => string;
+    bold: (t: unknown) => string;
+    dim: (t: unknown) => string;
+    italic: (t: unknown) => string;
+    underline: (t: unknown) => string;
+    blink: (t: unknown) => string;
+    inverse: (t: unknown) => string;
+    strikethrough: (t: unknown) => string;
+    hidden: (t: unknown) => string;
     rgb: (r: number, g: number, b: number) => ColorFn;
     bgRgb: (r: number, g: number, b: number) => ColorFn;
     hex: (h: string) => ColorFn;
     bgHex: (h: string) => ColorFn;
     color256: (n: number) => ColorFn;
     bgColor256: (n: number) => ColorFn;
-    gradient: (text: string, stops: string[]) => string;
+    gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
     rainbow: ColorFn;
+    chain: () => ColorChain;
 };
 
-interface RGB {
-    r: number;
-    g: number;
-    b: number;
-}
-declare const clamp: (n: number, min: number, max: number) => number;
-declare const lerp: (a: number, b: number, t: number) => number;
-/** Returns true when a string is a valid 3- or 6-digit hex color. */
-declare const isHexColor: (hex: string) => boolean;
 /**
- * Parses a hex color string to RGB. Throws on invalid input.
- * Use isHexColor() first if you need fail-soft behaviour.
- */
-declare const hexToRgb: (hex: string) => RGB;
-/** Converts R, G, B values to a hex string. Values are clamped to 0–255. */
-declare const rgbToHex: (r: number, g: number, b: number) => string;
-/** Linearly interpolates between two RGB colors. t is clamped to [0, 1]. */
-declare const lerpColor: (a: RGB, b: RGB, t: number) => RGB;
-declare const rgbTo256: (r: number, g: number, b: number) => number;
-declare const stripAnsi: (str: string) => string;
-declare const visibleLen: (str: string) => number;
-/**
- * Truncates a string with ANSI escapes to a max visible width.
- * Preserves color codes that started before the cut and emits a final reset.
+ * True when colors AND TTY are both available.
+ * Public predicate — useful for callers that want to gate features.
  */
-declare const truncateAnsi: (str: string, width: number, ellipsis?: string) => string;
-declare const padEnd: (str: string, width: number, ch?: string) => string;
-declare const padStart: (str: string, width: number, ch?: string) => string;
-declare const center: (str: string, width: number, ch?: string) => string;
-/** Repeats a string until its visible length reaches the target width. */
-declare const repeatVisible: (str: string, width: number) => string;
-declare const termSize: () => {
-    cols: number;
-    rows: number;
-};
-declare const wordWrap: (text: string, width: number) => string[];
-
-interface TypewriterOptions {
+declare const canAnimate: () => boolean;
+/** For tests — reset the cursor counter back to zero. */
+declare const resetCursorRefCount: () => void;
+interface AnimationHooks {
+    /** Called after each frame is written. Receives 0-based frame index. */
+    onFrame?: (frame: number) => void;
+    /** Called when the animation completes naturally. */
+    onDone?: () => void;
+    /** Called when the signal aborts the animation. */
+    onAbort?: () => void;
+}
+interface TypewriterOptions extends AnimationHooks {
     speed?: number;
     newline?: boolean;
     colorFn?: ColorFn | null;
     signal?: AbortSignal;
     reducedMotion?: boolean;
 }
-interface FadeOptions {
+interface FadeOptions extends AnimationHooks {
     duration?: number;
     steps?: number;
     newline?: boolean;
@@ -239,14 +678,14 @@ interface FadeOptions {
     signal?: AbortSignal;
     reducedMotion?: boolean;
 }
-interface SlideOptions {
+interface SlideOptions extends AnimationHooks {
     direction?: 'left' | 'right';
     duration?: number;
     newline?: boolean;
     signal?: AbortSignal;
     reducedMotion?: boolean;
 }
-interface PulseOptions {
+interface PulseOptions extends AnimationHooks {
     times?: number;
     interval?: number;
     color1?: string | RGB;
@@ -255,7 +694,7 @@ interface PulseOptions {
     signal?: AbortSignal;
     reducedMotion?: boolean;
 }
-interface WaveOptions {
+interface WaveOptions extends AnimationHooks {
     duration?: number;
     steps?: number;
     colors?: string[];
@@ -263,20 +702,48 @@ interface WaveOptions {
     signal?: AbortSignal;
     reducedMotion?: boolean;
 }
-interface GlitchOptions {
+interface GlitchOptions extends AnimationHooks {
     duration?: number;
     intensity?: number;
     newline?: boolean;
     signal?: AbortSignal;
     reducedMotion?: boolean;
 }
-interface RevealOptions {
+interface RevealOptions extends AnimationHooks {
     duration?: number;
     charset?: string;
     newline?: boolean;
     signal?: AbortSignal;
     reducedMotion?: boolean;
+    /**
+     * Number of "scramble" frames before the text resolves. Default scales
+     * with text length (longer text → more frames for visible reveal).
+     */
+    steps?: number;
 }
+/**
+ * A parallel step receives the parent signal. Steps that ignore it
+ * (zero-arg thunks) still work via the optional parameter.
+ */
+type ParallelStep = (opts?: {
+    signal?: AbortSignal;
+}) => Promise<void>;
+interface ParallelOptions {
+    signal?: AbortSignal;
+    /**
+     * Maximum time (ms) to wait for all steps to settle. After timeout,
+     * remaining steps are abandoned and parallel() resolves. Useful for
+     * preventing animations from blocking indefinitely on stuck steps.
+     */
+    timeout?: number;
+}
+/**
+ * Apply multiple animations to the SAME text in order.
+ * Each entry is `[fn, options]` or just `fn`.
+ * Errors in any step propagate after cursor cleanup.
+ */
+type AnimFn = (text: string, opts?: Record<string, unknown>) => Promise<void>;
+type ChainStep = AnimFn | [AnimFn] | [AnimFn, Record<string, unknown>];
 declare const animate: {
     typewriter: (text: string, opts?: TypewriterOptions) => Promise<void>;
     fadeIn: (text: string, opts?: FadeOptions) => Promise<void>;
@@ -286,8 +753,49 @@ declare const animate: {
     wave: (text: string, opts?: WaveOptions) => Promise<void>;
     glitch: (text: string, opts?: GlitchOptions) => Promise<void>;
     reveal: (text: string, opts?: RevealOptions) => Promise<void>;
+    sequence: (steps: Array<() => Promise<void>>, opts?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    chain: (text: string, steps: ChainStep[], opts?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    parallel: (steps: ParallelStep[], opts?: ParallelOptions) => Promise<void>;
+    delay: (ms: number) => (opts?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
 };
 
+/** A glyph is an array of equal-length strings (one per row). */
+type Glyph = string[];
+/** Maps a character to its glyph. Every font must define ' ' or '?'. */
+type FontMap = Record<string, Glyph>;
+/** Built-in font name. */
+type FontName = 'big' | 'small';
+/** For tests — clear the render cache. */
+declare const clearRenderCache: () => void;
+/** For tests/debugging — current cache size. */
+declare const getRenderCacheSize: () => number;
+interface RegisterFontOptions {
+    /** Allow overwriting reserved built-in fonts (big, small). Default: false. */
+    force?: boolean;
+}
+/**
+ * Register a custom font at runtime.
+ * Validates that the font is internally consistent before accepting it.
+ * Throws TypeError for invalid types, Error for structural issues.
+ *
+ * @example
+ *   ascii.registerFont('mini', {
+ *     ' ': ['  ', '  '],
+ *     A: ['▄▀', '▀▀'],
+ *     '?': ['?·', ' ·'],
+ *   });
+ */
+declare const registerFont: (name: string, fontMap: FontMap, opts?: RegisterFontOptions) => void;
+/** List all registered font names. */
+declare const listFonts: () => string[];
+/** Check if a font is registered (built-in or custom). */
+declare const hasFont: (name: string) => boolean;
 type BoxStyle = 'single' | 'double' | 'rounded' | 'heavy' | 'dashed' | 'ascii';
 interface BoxChars {
     tl: string;
@@ -301,12 +809,17 @@ declare const BOX_STYLES: Record<BoxStyle, BoxChars>;
 interface BoxOptions {
     padding?: number;
     borderStyle?: BoxStyle;
+    /** Fix inner content width. Lines are padded/truncated to fit. */
     width?: number | null;
 }
 interface BannerOptions {
-    font?: 'big' | 'small';
+    font?: FontName | string;
     colorFn?: ColorFn | null;
+    /** Apply colorFn per-character instead of per-line (true gradients). */
+    perCharColor?: boolean;
     align?: 'left' | 'center';
+    /** Spaces between glyphs (default: 1). */
+    letterSpacing?: number;
 }
 interface DividerOptions {
     char?: string;
@@ -317,31 +830,254 @@ interface DividerOptions {
 interface LogoOptions {
     gradient?: ColorFn | null;
     boxStyle?: BoxStyle;
+    /** Center the rendered ASCII inside the box (default: true). */
+    centered?: boolean;
+}
+interface Dimensions {
+    width: number;
+    height: number;
+}
+interface StreamOptions {
+    /** Font name to use. Default: 'big'. */
+    font?: FontName | string;
+    /** Spaces between glyphs. Default: 1. */
+    letterSpacing?: number;
+    /** Stream granularity: 'row' yields one line at a time, 'char' yields one char. */
+    granularity?: 'row' | 'char';
+    /** Abort signal — stops yielding when triggered. */
+    signal?: AbortSignal;
 }
 declare const ascii: {
     big: (text: string) => string;
     small: (text: string) => string;
     figlet: (text: string, opts?: {
-        font?: "big" | "small";
+        font?: FontName | string;
+        letterSpacing?: number;
     }) => string;
     banner: (text: string, opts?: BannerOptions) => string;
     box: (text: string, opts?: BoxOptions) => string;
     divider: (opts?: DividerOptions) => string;
     logo: (text: string, opts?: LogoOptions) => string;
+    stream: (text: string, opts?: StreamOptions) => AsyncGenerator<string, void, unknown>;
+    measure: (text: string, font?: FontName | string, letterSpacing?: number) => Dimensions;
+    stageRender: (text: string, font: FontName | string, letterSpacing?: number) => string;
+    stageAlign: (rendered: string, align: "left" | "center") => string;
+    stageColorize: (rendered: string, colorFn: ColorFn | null, perCharColor: boolean) => string;
+    registerFont: (name: string, fontMap: FontMap, opts?: RegisterFontOptions) => void;
+    listFonts: () => string[];
+    hasFont: (name: string) => boolean;
+    clearRenderCache: () => void;
+    getRenderCacheSize: () => number;
     boxStyles: Array<keyof typeof BOX_STYLES>;
 };
 
+/** For tests — reset the cursor counter. */
+declare const resetLoaderCursorCount: () => void;
+type SpinnerType = 'dots' | 'dots2' | 'line' | 'arrow' | 'bounce' | 'star' | 'pong' | 'aesthetic' | 'blocks' | 'moon' | 'clock';
+declare const SPINNERS: Record<SpinnerType, string[]>;
+interface SpinOptions {
+    type?: SpinnerType;
+    interval?: number;
+    color?: string | null;
+    prefix?: string;
+    suffix?: string;
+    persist?: boolean;
+    signal?: AbortSignal;
+    reducedMotion?: boolean;
+}
+interface ProgressOptions {
+    width?: number;
+    char?: string;
+    emptyChar?: string;
+    showPercentage?: boolean;
+    color?: string | null;
+    label?: string;
+}
+interface Task {
+    text: string;
+    fn: () => Promise<unknown>;
+    /** Optional sub-tasks executed inside this task's lifecycle. */
+    subtasks?: Task[];
+}
+interface TaskResult {
+    success: boolean;
+    result?: unknown;
+    error?: Error;
+    /** Results for subtasks, in order of execution. */
+    subtasks?: TaskResult[];
+}
+type StopFn = (finalText?: string, success?: boolean) => void;
+interface ProgressAnimateOptions extends ProgressOptions {
+    delay?: number;
+    signal?: AbortSignal;
+}
+interface TasksOptions {
+    type?: SpinnerType;
+    spinColor?: string;
+    successColor?: string;
+    errorColor?: string;
+    interval?: number;
+    signal?: AbortSignal;
+    /** Indent prefix for nested subtasks. Default 2 spaces per level. */
+    indent?: string;
+    /**
+     * Run top-level tasks in parallel instead of sequentially.
+     * Subtasks within each parent still run sequentially. Default: false.
+     */
+    parallel?: boolean;
+}
+interface DotsOptions {
+    interval?: number;
+    max?: number;
+    color?: string;
+    signal?: AbortSignal;
+}
+interface CustomOptions {
+    interval?: number;
+    color?: string;
+    signal?: AbortSignal;
+}
+interface CountdownOptions {
+    label?: string;
+    color?: string;
+    signal?: AbortSignal;
+}
+interface MultiLoaderItem {
+    /** Update the displayed text. */
+    update(text: string): void;
+    /** Mark as success and remove. */
+    succeed(text?: string): void;
+    /** Mark as failed and remove. */
+    fail(text?: string): void;
+    /** Just remove without success/fail. */
+    stop(): void;
+    /** Current displayed text. */
+    text: string;
+}
+interface MultiLoader {
+    /** Add a spinner; returns a controller for that line. */
+    add(text: string, opts?: {
+        color?: string;
+        type?: SpinnerType;
+    }): MultiLoaderItem;
+    /** Stop all and remove. */
+    clear(): void;
+    /** Number of active items. */
+    count(): number;
+}
+declare const loader: {
+    spin: (text?: string, opts?: SpinOptions) => StopFn;
+    progress: (percent: number, label?: string, opts?: ProgressOptions) => void;
+    progressAnimate: (steps: number, label?: string, opts?: ProgressAnimateOptions) => Promise<void>;
+    tasks: (taskList: Task[], opts?: TasksOptions) => Promise<TaskResult[]>;
+    dots: (text?: string, opts?: DotsOptions) => (() => void);
+    custom: (frames: string[], text?: string, opts?: CustomOptions) => (() => void);
+    countdown: (seconds: number, opts?: CountdownOptions) => Promise<void>;
+    multi: (opts?: {
+        interval?: number;
+    }) => MultiLoader;
+    /** Alias for SPINNERS — the built-in spinner frame definitions. */
+    spinners: Record<SpinnerType, string[]>;
+};
+
+type FrameCallback = (frame: string, index: number) => string;
+interface PlayOptions {
+    /** Milliseconds between frames. Ignored if `fps` is provided. */
+    interval?: number;
+    /** Frames per second. Takes precedence over `interval`. Capped at 60 fps. */
+    fps?: number;
+    /** Number of full loops. 0 means infinite. Default: 1. */
+    repeat?: number;
+    /** Clear all rendered lines when playback finishes. */
+    clearOnFinish?: boolean;
+    /** Transform each frame before writing. Errors are swallowed. */
+    onFrame?: FrameCallback | null;
+    /** Called when playback completes naturally (not aborted). */
+    onFinish?: () => void;
+    /** Cancel playback mid-run. */
+    signal?: AbortSignal;
+}
+/** Returned by `play()` — controls a running animation. */
+interface PlayController {
+    /** Pause playback. Idempotent. */
+    pause: () => void;
+    /** Resume playback after pause. Idempotent. */
+    resume: () => void;
+    /** Jump to a specific frame index (modulo frame count). */
+    seek: (frameIndex: number) => void;
+    /** Cancel playback immediately. */
+    stop: () => void;
+    /** True while the animation is actively running. */
+    isPlaying: () => boolean;
+    /** Promise that resolves when playback finishes (or is stopped). */
+    done: Promise<void>;
+}
+interface LiveOptions {
+    /** Frames per second for the render tick. Default: 12. Capped at 60. */
+    fps?: number;
+    /** Start the render loop immediately. Default: true. */
+    autoStart?: boolean;
+    /** Auto-stop the render loop when this signal aborts. */
+    signal?: AbortSignal;
+}
+interface LiveController {
+    start: () => void;
+    /** Stop the loop. Pass `{ clear: true }` to wipe the last rendered frame. */
+    stop: (opts?: {
+        clear?: boolean;
+    }) => void;
+    update: (frame: string) => void;
+    /** True while the render tick is active. */
+    isRunning: () => boolean;
+}
+/** For tests — reset cursor ref count. */
+declare const resetFramesCursorCount: () => void;
+interface LoadingBarOptions {
+    width?: number;
+    char?: string;
+    empty?: string;
+    label?: string;
+}
+interface BallOptions {
+    width?: number;
+    char?: string;
+}
+interface BreatheOptions {
+    steps?: number;
+}
+interface TypeDeleteOptions {
+    cursor?: string;
+}
+declare const frames: {
+    play: (frames: string[], opts?: PlayOptions) => PlayController;
+    generate: (count: number, fn: (i: number, total: number) => string) => string[];
+    live: (opts?: LiveOptions) => LiveController;
+    morph: (frameA: string, frameB: string, steps?: number, charset?: string) => string[];
+    presets: {
+        loadingBar: (opts?: LoadingBarOptions) => string[];
+        ball: (opts?: BallOptions) => string[];
+        breathe: (text: string, opts?: BreatheOptions) => string[];
+        typeDelete: (text: string, opts?: TypeDeleteOptions) => string[];
+    };
+};
+
 type TableBorderStyle = 'single' | 'double' | 'rounded' | 'heavy';
 interface TableOptions {
     header?: boolean;
     borderStyle?: TableBorderStyle;
     padding?: number;
+    /** Truncate cell content if it exceeds the column max. Default: null (auto-size). */
+    maxColWidth?: number | null;
 }
 interface BadgeOptions {
     labelBg?: number;
     valueBg?: number;
     labelFg?: number;
     valueFg?: number;
+    /** Inner padding (spaces) around the text. Default: 1. */
+    padding?: number;
+    /** Wrap the badge in a box-drawing border. Default: false. */
+    border?: boolean;
 }
 interface ProgressBarOptions {
     width?: number;
@@ -350,8 +1086,17 @@ interface ProgressBarOptions {
     showPercentage?: boolean;
     label?: string;
     color?: number | null;
+    /** Optional gradient stops applied to the filled portion. Overrides `color`. */
+    gradient?: string[] | null;
 }
+declare const box: (text: string, opts?: BoxOptions) => string;
 type StatusType = 'success' | 'error' | 'warn' | 'info' | 'wait';
+interface StatusOptions {
+    /** Override the default icon (or pass `null`/empty string for no icon). */
+    icon?: string | null;
+    /** Override the default color. */
+    color?: number;
+}
 interface SectionOptions {
     char?: string;
     width?: number | null;
@@ -361,6 +1106,8 @@ interface ColumnsOptions {
     cols?: number;
     gap?: number;
     width?: number | null;
+    /** Truncate items wider than the column. Default: 'truncate'. Use 'wrap' to flow into multiple lines. */
+    overflow?: 'truncate' | 'wrap';
 }
 interface TimelineEvent {
     label: string;
@@ -373,6 +1120,8 @@ interface TimelineOptions {
     color?: number;
     doneColor?: number;
     pendingColor?: number;
+    /** Pad time column to this visible width for alignment. Default: max time width across events. */
+    timeColumnWidth?: number | null;
 }
 interface MenuInput {
     isTTY?: boolean;
@@ -399,11 +1148,147 @@ declare const components: {
     table: (rows: string[][], opts?: TableOptions) => string;
     badge: (label: string, value: string, opts?: BadgeOptions) => string;
     progressBar: (percent: number, opts?: ProgressBarOptions) => string;
-    status: (type: StatusType, message: string) => string;
+    status: (type: StatusType, message: string, opts?: StatusOptions) => string;
     section: (title: string, opts?: SectionOptions) => string;
     columns: (items: string[], opts?: ColumnsOptions) => string;
     timeline: (events: TimelineEvent[], opts?: TimelineOptions) => string;
     menu: (items: string[], opts?: MenuOptions) => Promise<MenuResult>;
+    box: (text: string, opts?: BoxOptions) => string;
+};
+
+type TreeStyle = 'normal' | 'rounded' | 'heavy' | 'ascii';
+/**
+ * Plain-data representation of a tree node.
+ * Use when you have data and want to render it (e.g. JSON, filesystem walk).
+ */
+interface TreeData {
+    /** Display label. Multi-line strings render with aligned continuation. */
+    label: string;
+    /** Optional colorizer applied to this node's label. */
+    color?: ColorFn;
+    /** Optional icon prefix (e.g. '📁', '📄'). Rendered before label. */
+    icon?: string;
+    /** Override visual style for the subtree starting at this node. */
+    style?: TreeStyle;
+    /** Hide first N children, show "[+N hidden]" instead. */
+    collapse?: number;
+    /** Child nodes. */
+    children?: TreeData[];
+}
+/**
+ * Builder-style node returned by `tree(label)`.
+ * Mirrors Rich's API: `tree('root').add('child').add('grandchild')`.
+ */
+interface TreeNode extends TreeData {
+    /**
+     * Add a child node. Accepts a label string OR a partial TreeData object
+     * for icons/colors. Returns the *child* (so `.add().add()` walks deeper).
+     */
+    add(child: string | Partial<TreeData>): TreeNode;
+    /** Add a child and return the parent (for fluent sibling adds). */
+    addLeaf(child: string | Partial<TreeData>): TreeNode;
+    /** Render to string using the tree's own root style. */
+    render(opts?: RenderOptions$1): string;
+}
+interface RenderOptions$1 {
+    /** Visual style. Default: 'normal'. */
+    style?: TreeStyle;
+    /**
+     * Per-depth color palette. Node at depth N uses palette[N % palette.length].
+     * Per-node `color` overrides this. Empty palette is treated as "no palette".
+     */
+    palette?: ColorFn[];
+    /**
+     * Apply guide-line color (the ├──, │, └── chars).
+     * Default: undefined (no color).
+     */
+    guideColor?: ColorFn;
+    /** Maximum depth to render. Deeper nodes show "[+N more]". Default: Infinity. */
+    maxDepth?: number;
+    /** Indent the entire tree by N spaces. Default: 0. */
+    indent?: number;
+}
+/**
+ * Start a new tree with a root label. Returns a builder.
+ *
+ * @example
+ *   const t = tree('Project');
+ *   t.add('src').add('index.ts');
+ *   t.add('package.json');
+ *   console.log(t.render());
+ */
+declare const tree: (root: string | Partial<TreeData>) => TreeNode;
+/**
+ * Render a tree from plain data. Pure — no side effects.
+ *
+ * @example
+ *   renderTree({
+ *     label: 'src',
+ *     children: [
+ *       { label: 'index.ts' },
+ *       { label: 'utils', children: [{ label: 'helpers.ts' }] },
+ *     ],
+ *   });
+ */
+declare const renderTree: (root: TreeData, opts?: RenderOptions$1) => string;
+declare const renderTreeStream: (root: TreeData, opts?: RenderOptions$1) => Generator<string, void, unknown>;
+interface TreeDimensions {
+    width: number;
+    height: number;
+}
+declare const measureTree: (root: TreeData, opts?: RenderOptions$1) => TreeDimensions;
+interface WalkVisitor {
+    (node: TreeData, depth: number, isLast: boolean): void;
+}
+/**
+ * Depth-first walk over the tree, calling `visitor` for each node.
+ * Detects cycles to prevent infinite recursion.
+ */
+declare const walkTree: (root: TreeData, visitor: WalkVisitor) => void;
+/**
+ * Find the first node matching a predicate (depth-first). Returns null if none.
+ *
+ * @example
+ *   const found = findInTree(tree, (n) => n.label === 'package.json');
+ */
+declare const findInTree: (root: TreeData, predicate: (node: TreeData, depth: number) => boolean) => TreeData | null;
+/**
+ * Count nodes in the tree (including root).
+ * @example countNodes(tree) → number of nodes total
+ */
+declare const countNodes: (root: TreeData) => number;
+/**
+ * Transform every node's label via `fn`. Returns a NEW tree (input untouched).
+ *
+ * @example
+ *   const uppered = mapTree(tree, (n) => ({ ...n, label: n.label.toUpperCase() }));
+ */
+declare const mapTree: (root: TreeData, fn: (node: TreeData, depth: number) => TreeData) => TreeData;
+/**
+ * Filter tree to keep only nodes matching `predicate`. Returns NEW tree
+ * (or `null` if root itself fails the predicate).
+ *
+ * Note: a parent that fails the predicate but has matching descendants
+ * is kept (otherwise descendants would be orphaned). Set `prune: true`
+ * to drop those parents entirely (losing their descendants too).
+ */
+declare const filterTree: (root: TreeData, predicate: (node: TreeData, depth: number) => boolean, opts?: {
+    prune?: boolean;
+}) => TreeData | null;
+declare const trees: {
+    tree: (root: string | Partial<TreeData>) => TreeNode;
+    render: (root: TreeData, opts?: RenderOptions$1) => string;
+    renderStream: (root: TreeData, opts?: RenderOptions$1) => Generator<string, void, unknown>;
+    measure: (root: TreeData, opts?: RenderOptions$1) => TreeDimensions;
+    walk: (root: TreeData, visitor: WalkVisitor) => void;
+    find: (root: TreeData, predicate: (node: TreeData, depth: number) => boolean) => TreeData | null;
+    count: (root: TreeData) => number;
+    map: (root: TreeData, fn: (node: TreeData, depth: number) => TreeData) => TreeData;
+    filter: (root: TreeData, predicate: (node: TreeData, depth: number) => boolean, opts?: {
+        prune?: boolean;
+    }) => TreeData | null;
+    /** Map of available styles (read-only). */
+    styles: TreeStyle[];
 };
 
 interface Theme {
@@ -411,6 +1296,8 @@ interface Theme {
     primary: string;
     secondary: string;
     accent: string;
+    /** Alias-friendly success color (defaults to accent if missing). */
+    success?: string;
     warning: string;
     error: string;
     info: string;
@@ -420,122 +1307,163 @@ interface Theme {
     text: string;
     gradient: string[];
 }
-declare const themes: {
+/** Names of style methods on a ThemeInstance — used by `style()`. */
+type ThemeStyleName = 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'error' | 'info' | 'muted' | 'text';
+type ThemeChangeListener = (newTheme: Theme, oldTheme: Theme) => void;
+interface ThemeInstance {
+    /** List all registered theme names (built-in + custom). */
     list: () => string[];
+    /** Look up a theme definition. Returns null if missing. */
     get: (name: string) => Theme | null;
-    use(name: string): /*elided*/ any;
+    /** Switch active theme. Throws if name doesn't exist. */
+    use: (name: string) => ThemeInstance;
+    /**
+     * Try to switch active theme. Returns true on success, false if missing.
+     * Useful when names come from runtime config that may have typos.
+     */
+    tryUse: (name: string) => boolean;
+    /** Get the currently active theme definition. */
     current: () => Theme;
-    primary: (text: string) => string;
-    secondary: (text: string) => string;
-    accent: (text: string) => string;
-    warning: (text: string) => string;
-    error: (text: string) => string;
-    info: (text: string) => string;
-    muted: (text: string) => string;
-    text: (text: string) => string;
-    bold: (text: string) => string;
-    gradient: (text: string) => string;
+    /** Register a custom theme. Validates input strictly. */
     register: (name: string, def: Theme) => void;
-    preview: () => void;
-};
+    /** Remove a registered theme. Throws if removing the active one. */
+    unregister: (name: string) => void;
+    /**
+     * Subscribe to theme changes. Returns an unsubscribe function.
+     * Listener errors are caught — they don't break others.
+     */
+    onChange: (listener: ThemeChangeListener) => () => void;
+    primary: ColorFn;
+    secondary: ColorFn;
+    accent: ColorFn;
+    /** Semantic success color (falls back to `accent` if not defined). */
+    success: ColorFn;
+    warning: ColorFn;
+    error: ColorFn;
+    info: ColorFn;
+    muted: ColorFn;
+    text: ColorFn;
+    bgPrimary: ColorFn;
+    bgSecondary: ColorFn;
+    bgAccent: ColorFn;
+    bgSuccess: ColorFn;
+    bgWarning: ColorFn;
+    bgError: ColorFn;
+    bgInfo: ColorFn;
+    bgMuted: ColorFn;
+    bgSurface: ColorFn;
+    bold: ColorFn;
+    /**
+     * Dynamic accessor — get a color fn by name. Useful when the field
+     * comes from config: `theme.style(level)(message)`.
+     * Returns identity fn (passthrough) for unknown names.
+     */
+    style: (name: ThemeStyleName) => ColorFn;
+    gradient: (text: string, custom?: string[]) => string;
+    banner: (text: string, opts?: BannerOpts) => string;
+    preview: () => string;
+}
+/**
+ * Banner options — same as `ascii.banner` minus `colorFn` (we provide it).
+ * Defined explicitly to avoid fragile `Omit<Parameters<...>>` derivation.
+ */
+interface BannerOpts {
+    font?: 'big' | 'small' | string;
+    align?: 'left' | 'center';
+    perCharColor?: boolean;
+    letterSpacing?: number;
+}
+declare const createTheme: (initial?: string) => ThemeInstance;
+/** Clear the global singleton's color cache. */
+declare const clearThemeColorCache: () => void;
+declare const themes: ThemeInstance;
 
-type Pixel = RGB | null;
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    /** 0..1 alpha. 1 = opaque, 0 = transparent. */
+    a: number;
+}
+/** A pixel can be opaque RGB, semi-transparent RGBA, or null (fully transparent). */
+type Pixel = RGB | RGBA | null;
 type PixelGrid = Pixel[][];
-declare const renderPixelArt: (pixels: PixelGrid, opts?: {
+/** Clear the ANSI escape caches. Useful for tests or after large palette changes. */
+declare const clearAnsiCache: () => void;
+interface RenderOptions {
     scale?: number;
     halfBlock?: boolean;
-}) => string;
+    /** Use braille (2×4 sub-char resolution). Overrides halfBlock. */
+    braille?: boolean;
+}
+declare const renderPixelArt: (pixels: PixelGrid, opts?: RenderOptions) => string;
 declare const SPRITES: Record<string, {
     pixels: PixelGrid;
 }>;
-declare const gradientRect: (opts?: {
+declare const flipHorizontal: (pixels: PixelGrid) => PixelGrid;
+declare const flipVertical: (pixels: PixelGrid) => PixelGrid;
+declare const rotate90: (pixels: PixelGrid) => PixelGrid;
+interface GradientRectOptions {
     width?: number;
     height?: number;
     colors?: string[];
-    style?: "horizontal" | "vertical" | "diagonal" | "radial";
-}) => string;
+    /** Built-in style. Use `angle` for arbitrary directions. */
+    style?: 'horizontal' | 'vertical' | 'diagonal' | 'radial';
+    /** Custom angle in degrees (0=right, 90=down). Overrides `style`. */
+    angle?: number;
+    /** Dithering algorithm. 'bayer' improves perceived smoothness. */
+    dither?: 'none' | 'bayer';
+    /** Render in braille mode for 2× horizontal × 4× vertical resolution. */
+    braille?: boolean;
+}
+declare const gradientRect: (opts?: GradientRectOptions) => string;
+interface CanvasRenderOptions extends RenderOptions {
+    /** Render only the dirty region instead of the whole canvas. Default: false. */
+    dirtyOnly?: boolean;
+}
 interface Canvas {
     set: (x: number, y: number, color: Pixel) => void;
     get: (x: number, y: number) => Pixel;
     fill: (color: Pixel) => void;
-    drawRect: (x: number, y: number, w: number, h: number, color: RGB, fill?: boolean) => void;
-    drawCircle: (cx: number, cy: number, radius: number, color: RGB, fill?: boolean) => void;
-    render: (opts?: {
-        scale?: number;
-        halfBlock?: boolean;
-    }) => string;
-    print: (opts?: {
-        scale?: number;
-        halfBlock?: boolean;
-    }) => void;
+    drawRect: (x: number, y: number, w: number, h: number, color: Pixel, fill?: boolean) => void;
+    drawCircle: (cx: number, cy: number, radius: number, color: Pixel, fill?: boolean) => void;
+    /** Composite a sprite at (x, y) with optional alpha blending. */
+    drawSprite: (x: number, y: number, sprite: PixelGrid) => void;
+    render: (opts?: CanvasRenderOptions) => string;
+    print: (opts?: CanvasRenderOptions) => void;
+    /** Resize the canvas, preserving content within the new bounds. */
+    resize: (newWidth: number, newHeight: number, fillColor?: Pixel) => void;
+    /** Mark all pixels as dirty (forces full redraw on next dirtyOnly render). */
+    markDirty: () => void;
+    /** Clear the dirty region tracker (after a full render). */
+    clearDirty: () => void;
     width: number;
     height: number;
+    /** Deep copy of the current pixel grid. Mutations don't affect the canvas. */
     pixels: PixelGrid;
 }
 declare const createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
 declare const images: {
-    render: (pixels: PixelGrid, opts?: {
-        scale?: number;
-        halfBlock?: boolean;
-    }) => string;
+    render: (pixels: PixelGrid, opts?: RenderOptions) => string;
     sprites: Record<string, {
         pixels: PixelGrid;
     }>;
     flipHorizontal: (pixels: PixelGrid) => PixelGrid;
     flipVertical: (pixels: PixelGrid) => PixelGrid;
     rotate90: (pixels: PixelGrid) => PixelGrid;
-    sprite(name: string, opts?: {
-        scale?: number;
-        halfBlock?: boolean;
-    }): string;
-    gradientRect: (opts?: {
-        width?: number;
-        height?: number;
-        colors?: string[];
-        style?: "horizontal" | "vertical" | "diagonal" | "radial";
-    }) => string;
+    sprite(name: string, opts?: RenderOptions): string;
+    gradientRect: (opts?: GradientRectOptions) => string;
     createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
+    colors: {
+        hex: (h: unknown) => RGB | null;
+        lerp: (a: RGB, b: RGB, t: number) => RGB;
+        blend: (fg: Pixel, bg: RGB) => RGB;
+    };
+    clearAnsiCache: () => void;
 };
 
-declare const cursor: {
-    readonly up: (n?: number) => string;
-    readonly down: (n?: number) => string;
-    readonly right: (n?: number) => string;
-    readonly left: (n?: number) => string;
-    readonly to: (x: number, y: number) => string;
-    readonly save: () => string;
-    readonly restore: () => string;
-    readonly hide: () => string;
-    readonly show: () => string;
-};
-declare const screen: {
-    readonly clear: () => string;
-    readonly clearLine: () => string;
-    readonly clearRight: () => string;
-    readonly clearDown: () => string;
-    readonly scrollUp: (n?: number) => string;
-    readonly scrollDown: (n?: number) => string;
-};
-declare const sgr: (...codes: number[]) => string;
-declare const reset: () => string;
-declare const fgRgb: (r: number, g: number, b: number) => string;
-declare const bgRgb: (r: number, g: number, b: number) => string;
-type ColorSupport = 'none' | 'basic' | '256' | 'truecolor';
-declare const supportsColor: () => ColorSupport;
-declare const sleep: (ms: number) => Promise<void>;
-declare const write: (str: string) => boolean;
-declare const writeln: (str?: string) => boolean;
-
 declare const ansimax: {
     color: {
-        sunset: (t: string) => string;
-        ocean: (t: string) => string;
-        fire: (t: string) => string;
-        neon: (t: string) => string;
-        forest: (t: string) => string;
-        aurora: (t: string) => string;
-        candy: (t: string) => string;
-        gold: (t: string) => string;
         black: ColorFn;
         red: ColorFn;
         green: ColorFn;
@@ -554,7 +1482,7 @@ declare const ansimax: {
         brightWhite: ColorFn;
         gray: ColorFn;
         grey: ColorFn;
-        orange: (t: string) => string;
+        orange: (t: unknown) => string;
         purple: ColorFn;
         bgBlack: ColorFn;
         bgRed: ColorFn;
@@ -564,22 +1492,23 @@ declare const ansimax: {
         bgMagenta: ColorFn;
         bgCyan: ColorFn;
         bgWhite: ColorFn;
-        bold: (t: string) => string;
-        dim: (t: string) => string;
-        italic: (t: string) => string;
-        underline: (t: string) => string;
-        blink: (t: string) => string;
-        inverse: (t: string) => string;
-        strikethrough: (t: string) => string;
-        hidden: (t: string) => string;
+        bold: (t: unknown) => string;
+        dim: (t: unknown) => string;
+        italic: (t: unknown) => string;
+        underline: (t: unknown) => string;
+        blink: (t: unknown) => string;
+        inverse: (t: unknown) => string;
+        strikethrough: (t: unknown) => string;
+        hidden: (t: unknown) => string;
         rgb: (r: number, g: number, b: number) => ColorFn;
         bgRgb: (r: number, g: number, b: number) => ColorFn;
         hex: (h: string) => ColorFn;
         bgHex: (h: string) => ColorFn;
         color256: (n: number) => ColorFn;
         bgColor256: (n: number) => ColorFn;
-        gradient: (text: string, stops: string[]) => string;
+        gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
         rainbow: ColorFn;
+        chain: () => ColorChain;
     };
     animate: {
         typewriter: (text: string, opts?: TypewriterOptions) => Promise<void>;
@@ -590,119 +1519,110 @@ declare const ansimax: {
         wave: (text: string, opts?: WaveOptions) => Promise<void>;
         glitch: (text: string, opts?: GlitchOptions) => Promise<void>;
         reveal: (text: string, opts?: RevealOptions) => Promise<void>;
+        sequence: (steps: Array<() => Promise<void>>, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<void>;
+        chain: (text: string, steps: (((text: string, opts?: Record<string, unknown>) => Promise<void>) | [(text: string, opts?: Record<string, unknown>) => Promise<void>] | [(text: string, opts?: Record<string, unknown>) => Promise<void>, Record<string, unknown>])[], opts?: {
+            signal?: AbortSignal;
+        }) => Promise<void>;
+        parallel: (steps: ParallelStep[], opts?: ParallelOptions) => Promise<void>;
+        delay: (ms: number) => (opts?: {
+            signal?: AbortSignal;
+        }) => Promise<void>;
     };
     ascii: {
         big: (text: string) => string;
         small: (text: string) => string;
         figlet: (text: string, opts?: {
-            font?: "big" | "small";
+            font?: FontName | string;
+            letterSpacing?: number;
         }) => string;
         banner: (text: string, opts?: BannerOptions) => string;
         box: (text: string, opts?: BoxOptions) => string;
         divider: (opts?: DividerOptions) => string;
         logo: (text: string, opts?: LogoOptions) => string;
+        stream: (text: string, opts?: StreamOptions) => AsyncGenerator<string, void, unknown>;
+        measure: (text: string, font?: FontName | string, letterSpacing?: number) => Dimensions;
+        stageRender: (text: string, font: FontName | string, letterSpacing?: number) => string;
+        stageAlign: (rendered: string, align: "left" | "center") => string;
+        stageColorize: (rendered: string, colorFn: ColorFn | null, perCharColor: boolean) => string;
+        registerFont: (name: string, fontMap: FontMap, opts?: RegisterFontOptions) => void;
+        listFonts: () => string[];
+        hasFont: (name: string) => boolean;
+        clearRenderCache: () => void;
+        getRenderCacheSize: () => number;
         boxStyles: Array<BoxStyle>;
     };
     loader: {
-        spin: (text?: string, opts?: SpinOptions) => ((message?: string, success?: boolean) => void);
-        dots: (text?: string, opts?: {
-            interval?: number;
-            max?: number;
-            signal?: AbortSignal;
-        }) => (() => void);
+        spin: (text?: string, opts?: SpinOptions) => StopFn;
         progress: (percent: number, label?: string, opts?: ProgressOptions) => void;
-        progressAnimate: (steps: number, label?: string, opts?: ProgressOptions & {
-            delay?: number;
-            signal?: AbortSignal;
-        }) => Promise<void>;
-        tasks: (taskList: Task[], opts?: TaskOptions) => Promise<TaskResult[]>;
-        custom: (frames: string[], text?: string, opts?: {
+        progressAnimate: (steps: number, label?: string, opts?: ProgressAnimateOptions) => Promise<void>;
+        tasks: (taskList: Task[], opts?: TasksOptions) => Promise<TaskResult[]>;
+        dots: (text?: string, opts?: DotsOptions) => (() => void);
+        custom: (frames: string[], text?: string, opts?: CustomOptions) => (() => void);
+        countdown: (seconds: number, opts?: CountdownOptions) => Promise<void>;
+        multi: (opts?: {
             interval?: number;
-            signal?: AbortSignal;
-        }) => (() => void);
-        countdown: (seconds: number, opts?: {
-            label?: string;
-            color?: string;
-            signal?: AbortSignal;
-        }) => Promise<void>;
+        }) => MultiLoader;
         spinners: Record<SpinnerType, string[]>;
     };
     frames: {
-        play: (frames: string[], opts?: PlayOptions) => Promise<void>;
+        play: (frames: string[], opts?: PlayOptions) => PlayController;
         generate: (count: number, fn: (i: number, total: number) => string) => string[];
         live: (opts?: LiveOptions) => LiveController;
         morph: (frameA: string, frameB: string, steps?: number, charset?: string) => string[];
         presets: {
-            loadingBar: (opts?: {
-                width?: number;
-                char?: string;
-                empty?: string;
-                label?: string;
-            }) => string[];
-            ball: (opts?: {
-                width?: number;
-                char?: string;
-            }) => string[];
-            breathe: (text: string, opts?: {
-                steps?: number;
-            }) => string[];
-            typeDelete: (text: string, opts?: {
-                cursor?: string;
-            }) => string[];
+            loadingBar: (opts?: LoadingBarOptions) => string[];
+            ball: (opts?: BallOptions) => string[];
+            breathe: (text: string, opts?: BreatheOptions) => string[];
+            typeDelete: (text: string, opts?: TypeDeleteOptions) => string[];
         };
     };
     components: {
         table: (rows: string[][], opts?: TableOptions) => string;
         badge: (label: string, value: string, opts?: BadgeOptions) => string;
         progressBar: (percent: number, opts?: ProgressBarOptions) => string;
-        status: (type: StatusType, message: string) => string;
+        status: (type: StatusType, message: string, opts?: StatusOptions) => string;
         section: (title: string, opts?: SectionOptions) => string;
         columns: (items: string[], opts?: ColumnsOptions) => string;
         timeline: (events: TimelineEvent[], opts?: TimelineOptions) => string;
         menu: (items: string[], opts?: MenuOptions) => Promise<MenuResult>;
+        box: (text: string, opts?: BoxOptions) => string;
     };
-    themes: {
-        list: () => string[];
-        get: (name: string) => Theme | null;
-        use(name: string): /*elided*/ any;
-        current: () => Theme;
-        primary: (text: string) => string;
-        secondary: (text: string) => string;
-        accent: (text: string) => string;
-        warning: (text: string) => string;
-        error: (text: string) => string;
-        info: (text: string) => string;
-        muted: (text: string) => string;
-        text: (text: string) => string;
-        bold: (text: string) => string;
-        gradient: (text: string) => string;
-        register: (name: string, def: Theme) => void;
-        preview: () => void;
+    trees: {
+        tree: (root: string | Partial<TreeData>) => TreeNode;
+        render: (root: TreeData, opts?: RenderOptions$1) => string;
+        renderStream: (root: TreeData, opts?: RenderOptions$1) => Generator<string, void, unknown>;
+        measure: (root: TreeData, opts?: RenderOptions$1) => TreeDimensions;
+        walk: (root: TreeData, visitor: WalkVisitor) => void;
+        find: (root: TreeData, predicate: (node: TreeData, depth: number) => boolean) => TreeData | null;
+        count: (root: TreeData) => number;
+        map: (root: TreeData, fn: (node: TreeData, depth: number) => TreeData) => TreeData;
+        filter: (root: TreeData, predicate: (node: TreeData, depth: number) => boolean, opts?: {
+            prune?: boolean;
+        }) => TreeData | null;
+        styles: TreeStyle[];
     };
+    themes: ThemeInstance;
     images: {
-        render: (pixels: (RGB | null)[][], opts?: {
-            scale?: number;
-            halfBlock?: boolean;
-        }) => string;
+        render: (pixels: PixelGrid, opts?: RenderOptions) => string;
         sprites: Record<string, {
-            pixels: (RGB | null)[][];
+            pixels: PixelGrid;
         }>;
-        flipHorizontal: (pixels: (RGB | null)[][]) => (RGB | null)[][];
-        flipVertical: (pixels: (RGB | null)[][]) => (RGB | null)[][];
-        rotate90: (pixels: (RGB | null)[][]) => (RGB | null)[][];
-        sprite(name: string, opts?: {
-            scale?: number;
-            halfBlock?: boolean;
-        }): string;
-        gradientRect: (opts?: {
-            width?: number;
-            height?: number;
-            colors?: string[];
-            style?: "horizontal" | "vertical" | "diagonal" | "radial";
-        }) => string;
-        createCanvas: (width: number, height: number, fillColor?: RGB | null) => Canvas;
+        flipHorizontal: (pixels: PixelGrid) => PixelGrid;
+        flipVertical: (pixels: PixelGrid) => PixelGrid;
+        rotate90: (pixels: PixelGrid) => PixelGrid;
+        sprite(name: string, opts?: RenderOptions): string;
+        gradientRect: (opts?: GradientRectOptions) => string;
+        createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
+        colors: {
+            hex: (h: unknown) => RGB | null;
+            lerp: (a: RGB, b: RGB, t: number) => RGB;
+            blend: (fg: Pixel, bg: RGB) => RGB;
+        };
+        clearAnsiCache: () => void;
     };
-    configure: (opts?: AnsimaxConfig) => void;
+    configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-export { type AnimationSpeed, type AnsimaxConfig, type BadgeOptions, type BannerOptions, type BoxOptions, type BoxStyle, type Canvas, type ColorFn, type ColorMode, type ColumnsOptions, type DividerOptions, type FadeOptions, type GlitchOptions, type LiveController, type LogoOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type PlayOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RevealOptions, SPINNERS, SPRITES, type SectionOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusType, type TableOptions, type Task, type TaskResult, type Theme, type TimelineEvent, type TimelineOptions, type TypewriterOptions, type WaveOptions, animate, ascii, bgRgb, center, clamp, color, presets as colorPresets, components, compose, configure, createCanvas, cursor, ansimax as default, fgRgb, frames, getConfig, getSpeedMultiplier, gradient, gradientRect, hexToRgb, images, isHexColor, isNoColor, lerp, lerpColor, loader, padEnd, padStart, rainbow, renderPixelArt, repeatVisible, reset, resetNoColor, rgbTo256, rgbToHex, screen, setNoColor, sgr, sleep, stripAnsi, supportsColor, termSize, themes, truncateAnsi, visibleLen, wordWrap, write, writeln };
+export { type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EraseMode, FG, FRAME_MS, type FadeOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions, type ResizeListener, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions$1 as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, filterTree, findInTree, flipHorizontal, flipVertical, frames, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, hasFont, hexToRgb, hideCursor, images, isHexColor, isNoColor, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, pauseListeners, presetNames, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, rgbTo256, rgbToHex, rotate90, safeJson, screen, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$1 as stripAnsi, stripAnsi$2 as stripAnsiCodes, stripAnsi as stripAnsiColors, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };