ansimax 1.3.2 → 1.3.4

package/dist/index.d.ts

@@ -95,203 +95,36 @@ declare const getConfigValue: <K extends keyof AnsimaxConfig>(key: K) => Require
  *   });
  */
 declare const withConfig: <T>(overrides: AnsimaxConfig, fn: () => T | Promise<T>) => T | Promise<T>;
-
-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;
-}
-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 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;
-}
-/**
- * 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
+ * Set a single config key without wrapping in an object. Convenience
+ * shortcut equivalent to `configure({ [key]: value })`.
+ *
+ * @example
+ * ```ts
+ * import { setConfigValue } from 'ansimax';
+ *
+ * setConfigValue('theme', 'dracula');
+ * setConfigValue('animationSpeed', 'fast');
+ * ```
  */
-declare const sleep: (ms: number, opts?: SleepOptions) => Promise<void>;
+declare const setConfigValue: <K extends keyof AnsimaxConfig>(key: K, value: AnsimaxConfig[K]) => 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.
+ * Alias for `onConfigChange` — matches the naming convention used by
+ * `themes.onChange` and other observers in the codebase. Returns an
+ * unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * import { subscribeConfig } from 'ansimax';
+ *
+ * const unsubscribe = subscribeConfig((newCfg, oldCfg) => {
+ *   console.log('Config changed:', newCfg);
+ * });
+ *
+ * // Later: unsubscribe();
+ * ```
  */
-declare const sleepFrame: (ms?: number, opts?: SleepOptions) => Promise<void>;
+declare const subscribeConfig: (listener: ConfigChangeListener) => (() => void);
 
 interface RGB {
     r: number;
@@ -326,7 +159,7 @@ declare const lerpColor: (a: RGB, b: RGB, t: number) => RGB;
  */
 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;
+declare const stripAnsi$2: (str: string) => string;
 /**
  * Width of a single character (or grapheme) in terminal cells.
  *  - 0 for combining marks, ZWJ, VS, BOM
@@ -524,6 +357,286 @@ declare const safeJson: (value: unknown, indent?: number) => string;
  *   padBoth('hi', 5) → ' hi  '
  */
 declare const padBoth: (str: string, width: number, ch?: string) => string;
+/**
+ * Interpolate a sequence of N colors between two endpoint hex colors.
+ * Useful for procedurally generating gradient stops without calling the
+ * full gradient pipeline.
+ *
+ * @param start - Start hex color (e.g. `'#ff0000'`).
+ * @param end   - End hex color (e.g. `'#0000ff'`).
+ * @param count - Number of stops (>= 2; clamped if smaller).
+ * @returns Array of hex strings, including both endpoints.
+ *
+ * @example
+ * ```ts
+ * import { gradientStops } from 'ansimax';
+ *
+ * const stops = gradientStops('#ff0000', '#0000ff', 5);
+ * // → ['#ff0000', '#bf003f', '#7f007f', '#3f00bf', '#0000ff']
+ * ```
+ */
+declare const gradientStops: (start: string, end: string, count: number) => string[];
+/**
+ * Escape a string for safe use inside a regular expression literal.
+ * Escapes all 12 regex meta-characters: `. * + ? ^ $ { } ( ) | [ ] \`.
+ *
+ * @example
+ * ```ts
+ * import { escapeForRegex } from 'ansimax';
+ *
+ * const userInput = 'hello.world+code';
+ * const re = new RegExp(escapeForRegex(userInput));
+ * // Matches the literal string, not as a regex pattern
+ * ```
+ */
+declare const escapeForRegex: (str: string) => string;
+/**
+ * Measure a pre-rendered string block's dimensions: width (max visible
+ * width of any line) and height (line count). ANSI escapes are ignored.
+ *
+ * @example
+ * ```ts
+ * import { measureBlock } from 'ansimax';
+ *
+ * const box = ascii.box('Hello world!');
+ * const { width, height } = measureBlock(box);
+ * // → { width: 15, height: 3 }
+ * ```
+ */
+declare const measureBlock: (block: string) => {
+    width: number;
+    height: number;
+};
+
+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$1: (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;
+}
+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 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;
+}
+/**
+ * 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>;
+/**
+ * Wrap a label in an OSC 8 hyperlink escape sequence. Terminals that
+ * support hyperlinks (VS Code, iTerm2, WezTerm, Kitty, etc.) render it
+ * as clickable. Terminals without support just show the label text.
+ *
+ * @param url   - Target URL (https://, mailto:, file://, etc.)
+ * @param label - Visible text. Defaults to the URL itself.
+ * @returns String with OSC 8 wrappers around the label.
+ *
+ * @example
+ * ```ts
+ * import { hyperlink } from 'ansimax';
+ *
+ * console.log(`Visit ${hyperlink('https://github.com/Brashkie/ansimax', 'the repo')}`);
+ * console.log(`Email: ${hyperlink('mailto:hi@example.com')}`);
+ * ```
+ */
+declare const hyperlink: (url: string, label?: string) => string;
+/**
+ * Returns the escape sequence to clear the entire current line and move
+ * the cursor back to column 1. Equivalent to `screen.clearLine() + '\r'`.
+ *
+ * @example
+ * ```ts
+ * import { clearLine } from 'ansimax';
+ *
+ * for (let i = 0; i <= 100; i++) {
+ *   process.stdout.write(clearLine() + `Progress: ${i}%`);
+ *   await sleep(30);
+ * }
+ * ```
+ */
+declare const clearLine: () => string;
 
 type ColorFn = (text: string) => string;
 
@@ -921,6 +1034,40 @@ interface ParallelOptions {
  */
 type AnimFn = (text: string, opts?: Record<string, unknown>) => Promise<void>;
 type ChainStep = AnimFn | [AnimFn] | [AnimFn, Record<string, unknown>];
+interface ShakeOptions extends AnimationHooks {
+    /** Number of shake cycles. Default `5`. */
+    times?: number;
+    /** Pixels of horizontal displacement per frame. Default `2`. */
+    intensity?: number;
+    /** Milliseconds between frames. Default `50`. */
+    interval?: number;
+    /** Emit newline at end. Default `true`. */
+    newline?: boolean;
+    signal?: AbortSignal;
+    reducedMotion?: boolean;
+}
+interface CountUpOptions extends AnimationHooks {
+    /** Total animation duration in ms. Default `1500`. */
+    duration?: number;
+    /** Frame count — more = smoother but slower. Default `60`. */
+    steps?: number;
+    /** Decimal places to show. Default `0`. */
+    decimals?: number;
+    /**
+     * Format the displayed value. Default: `(n) => n.toString()`.
+     * Use this to add prefixes/suffixes, commas, etc.
+     */
+    format?: (value: number) => string;
+    /**
+     * Easing function — input/output both in [0, 1]. Default linear.
+     * Try `(t) => t * t` for accelerate, `(t) => 1 - (1-t)**2` for decelerate.
+     */
+    easing?: (t: number) => number;
+    /** Emit newline at end. Default `true`. */
+    newline?: boolean;
+    signal?: AbortSignal;
+    reducedMotion?: boolean;
+}
 declare const animate: {
     typewriter: (text: string, opts?: TypewriterOptions) => Promise<void>;
     fadeIn: (text: string, opts?: FadeOptions) => Promise<void>;
@@ -940,6 +1087,8 @@ declare const animate: {
     delay: (ms: number) => (opts?: {
         signal?: AbortSignal;
     }) => Promise<void>;
+    shake: (text: string, opts?: ShakeOptions) => Promise<void>;
+    countUp: (from: number, to: number, opts?: CountUpOptions) => Promise<void>;
 };
 
 interface RGBA {
@@ -1279,6 +1428,20 @@ interface BoxOptions {
     borderStyle?: BoxStyle;
     /** Fix inner content width. Lines are padded/truncated to fit. */
     width?: number | null;
+    /**
+     * Optional title shown in the top border, e.g. `─ Title ─────`.
+     * When set, the box expands to fit the title if content is narrower.
+     *
+     * @since 1.3.3
+     */
+    title?: string | null;
+    /**
+     * Title alignment in the top border: `'left'` | `'center'` (default) | `'right'`.
+     * Only applies when `title` is set.
+     *
+     * @since 1.3.3
+     */
+    titleAlign?: 'left' | 'center' | 'right';
 }
 interface BannerOptions {
     font?: FontName | string;
@@ -1294,6 +1457,13 @@ interface DividerOptions {
     width?: number | null;
     label?: string | null;
     style?: BoxStyle;
+    /**
+     * Label alignment: `'left'` | `'center'` (default) | `'right'`.
+     * Only applies when `label` is set.
+     *
+     * @since 1.3.3
+     */
+    align?: 'left' | 'center' | 'right';
 }
 interface LogoOptions {
     gradient?: ColorFn | null;
@@ -2299,9 +2469,16 @@ interface FrameOptions {
      */
     bottomChar?: string;
     /**
-     * Optional title shown centered in the top edge.
+     * Optional title shown in the top edge.
      */
     title?: string;
+    /**
+     * Title alignment: `'left'` | `'center'` (default) | `'right'`.
+     * Only applies when `title` is set.
+     *
+     * @since 1.3.3
+     */
+    titleAlign?: 'left' | 'center' | 'right';
 }
 /**
  * Add decorative top/bottom rule lines around a block (lighter than `ascii.box`
@@ -2339,11 +2516,71 @@ interface FrameOptions {
  * ```
  */
 declare const frame: (block: string, opts?: FrameOptions) => string;
+interface GridOptions {
+    /** Number of columns. Required. */
+    columns: number;
+    /** Horizontal gap between cells. Default `1`. */
+    gapX?: number;
+    /** Vertical gap between rows. Default `0`. */
+    gapY?: number;
+    /** Horizontal alignment of content within each cell. Default `'start'`. */
+    alignX?: Alignment;
+    /** Vertical alignment of content within each cell. Default `'start'`. */
+    alignY?: Alignment;
+    /**
+     * Fix each cell to this width (in visible characters). If omitted, cells
+     * use the max width of the widest block in their column.
+     */
+    cellWidth?: number | null;
+}
+/**
+ * Arrange blocks in a grid of N columns, flowing left-to-right then
+ * top-to-bottom. Each row is auto-sized to its tallest block, and each
+ * column is auto-sized to its widest block (unless `cellWidth` is fixed).
+ *
+ * Internally uses `vsplit` for rows + `hsplit` for the column stack, so
+ * all alignment + ANSI rules behave consistently.
+ *
+ * @param blocks - Pre-rendered string blocks. Flows in reading order.
+ * @param opts   - Grid configuration. `columns` is required.
+ *
+ * @example 2×2 grid of stats cards
+ * ```js
+ * import { panels, ascii } from 'ansimax';
+ *
+ * const cards = [
+ *   ascii.box('FILES\n42',   { borderStyle: 'rounded', padding: 1 }),
+ *   ascii.box('LINES\n1247', { borderStyle: 'rounded', padding: 1 }),
+ *   ascii.box('TESTS\n38',   { borderStyle: 'rounded', padding: 1 }),
+ *   ascii.box('COV\n98%',    { borderStyle: 'rounded', padding: 1 }),
+ * ];
+ *
+ * console.log(panels.grid(cards, { columns: 2, gapX: 2, gapY: 1 }));
+ * ```
+ *
+ * @example 3-column gallery with auto-flow
+ * ```js
+ * // 7 items in 3 columns → 3 rows: [3, 3, 1]
+ * const items = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven'];
+ * console.log(panels.grid(items, { columns: 3, gapX: 4 }));
+ * ```
+ *
+ * @example uniform cell width for visual consistency
+ * ```js
+ * console.log(panels.grid(blocks, {
+ *   columns: 4,
+ *   cellWidth: 15,
+ *   alignX: 'center',
+ * }));
+ * ```
+ */
+declare const grid: (blocks: string[], opts: GridOptions) => string;
 declare const panels: {
     vsplit: (blocks: string[], opts?: VsplitOptions) => string;
     hsplit: (blocks: string[], opts?: HsplitOptions) => string;
     center: (block: string, opts: CenterOptions) => string;
     frame: (block: string, opts?: FrameOptions) => string;
+    grid: (blocks: string[], opts: GridOptions) => string;
 };
 
 /**
@@ -2401,6 +2638,23 @@ interface PrettyOptions {
      * @since 1.3.1
      */
     inlineArrayMaxLength?: number;
+    /**
+     * Output mode controls what kind of string is produced:
+     *
+     * - `'display'` (default) — terminal-friendly output with colors (when
+     *   enabled) and informational placeholders like `[Circular]`,
+     *   `[Function: name]`, `Symbol(x)`, `Map(2) {...}`, `Set(3) {...}`,
+     *   `Date(2026-06-13T...)`, `BigInt(123n)`. Not parseable as JSON.
+     *
+     * - `'json'` — strict, parseable JSON output. Colors are forced off,
+     *   circular references throw `TypeError`, and types not representable
+     *   in JSON (functions, symbols, undefined) are omitted from objects /
+     *   replaced with `null` in arrays. Map/Set are converted to objects/arrays.
+     *   Dates become ISO strings. BigInt becomes a number (or string if too large).
+     *
+     * @since 1.3.3
+     */
+    mode?: 'display' | 'json';
 }
 /**
  * Pretty-print a JavaScript value with colored output suitable for
@@ -2519,6 +2773,8 @@ declare const ansimax: {
         delay: (ms: number) => (opts?: {
             signal?: AbortSignal;
         }) => Promise<void>;
+        shake: (text: string, opts?: ShakeOptions) => Promise<void>;
+        countUp: (from: number, to: number, opts?: CountUpOptions) => Promise<void>;
     };
     ascii: {
         big: (text: string) => string;
@@ -2618,4 +2874,4 @@ declare const ansimax: {
     configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, 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 EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, 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$1 as RenderOptions, type ResizeListener, type ReusableGradient, 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 as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, hasFont, hexToRgb, hideCursor, hsplit, images, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, 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, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
+export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, 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 EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, 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$1 as RenderOptions, type ResizeListener, type ReusableGradient, 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 as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeForRegex, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, gradientStops, graphemes, grid, hasFont, hexToRgb, hideCursor, hsplit, hyperlink, images, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureBlock, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rotate90, safeJson, screen, setConfigValue, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$2 as stripAnsi, stripAnsi$1 as stripAnsiCodes, stripAnsi as stripAnsiColors, subscribeConfig, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };