ansimax 1.3.3 → 1.3.5

package/dist/index.d.ts

@@ -95,6 +95,463 @@ declare const getConfigValue: <K extends keyof AnsimaxConfig>(key: K) => Require
  *   });
  */
 declare const withConfig: <T>(overrides: AnsimaxConfig, fn: () => T | Promise<T>) => T | Promise<T>;
+/**
+ * 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 setConfigValue: <K extends keyof AnsimaxConfig>(key: K, value: AnsimaxConfig[K]) => void;
+/**
+ * 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 subscribeConfig: (listener: ConfigChangeListener) => (() => void);
+
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Type guard: true when `n` is a finite number (rejects NaN, ±Infinity,
+ * non-numbers). Useful for input validation.
+ *
+ * @since 1.3.5
+ */
+declare const isFiniteNumber: (n: unknown) => n is number;
+/**
+ * Coerce any value to a safe integer. Handles non-numbers, NaN, Infinity,
+ * and floats. Consolidates the `Math.max(0, Math.floor(Number(x) || 0))`
+ * pattern that appears across the codebase.
+ *
+ * @param value    - Any value (will be coerced via `Number()`).
+ * @param fallback - Returned when `value` is non-finite. Default `0`.
+ * @param min      - Lower bound (inclusive). Default `-Infinity`.
+ * @param max      - Upper bound (inclusive). Default `Infinity`.
+ *
+ * @example
+ * ```ts
+ * safeInt('abc')                  // → 0
+ * safeInt(3.7)                    // → 3
+ * safeInt(-5, 0, 0, 100)          // → 0  (clamped to min)
+ * safeInt(NaN, 50)                // → 50 (fallback)
+ * safeInt(null, 1)                // → 1  (fallback — null is not a real number)
+ * ```
+ *
+ * @since 1.3.5
+ */
+declare const safeInt: (value: unknown, fallback?: number, min?: number, max?: number) => number;
+declare const clamp: (n: number, min: number, max: number) => number;
+declare const lerp: (a: number, b: number, t: number) => number;
+/**
+ * Clamp + round a number to the 0–255 byte range. Exported as of v1.3.5.
+ *
+ * @since 1.3.5
+ */
+declare const clampByte: (v: 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;
+interface HSL {
+    /** Hue in degrees, 0–360 (wraps; 360 ≡ 0). */
+    h: number;
+    /** Saturation in [0, 1] (0 = grayscale, 1 = pure color). */
+    s: number;
+    /** Lightness in [0, 1] (0 = black, 0.5 = pure, 1 = white). */
+    l: number;
+}
+/**
+ * Convert RGB (0–255) to HSL.
+ *
+ * @example
+ * rgbToHsl({ r: 255, g: 0, b: 0 })  // → { h: 0,   s: 1, l: 0.5 }
+ * rgbToHsl({ r: 0, g: 255, b: 0 })  // → { h: 120, s: 1, l: 0.5 }
+ *
+ * @since 1.3.5
+ */
+declare const rgbToHsl: (rgb: RGB) => HSL;
+/**
+ * Convert HSL to RGB (0–255). Hue wraps modulo 360.
+ *
+ * @example
+ * hslToRgb({ h: 0,   s: 1, l: 0.5 })  // → { r: 255, g: 0,   b: 0   }
+ * hslToRgb({ h: 240, s: 1, l: 0.5 })  // → { r: 0,   g: 0,   b: 255 }
+ *
+ * @since 1.3.5
+ */
+declare const hslToRgb: (hsl: HSL) => RGB;
+interface Oklab {
+    /** Perceptual lightness in [0, 1]. */
+    L: number;
+    /** Green↔Red axis, roughly [-0.4, 0.4]. */
+    a: number;
+    /** Blue↔Yellow axis, roughly [-0.4, 0.4]. */
+    b: number;
+}
+/**
+ * Convert RGB (0–255) to Oklab. Perceptually uniform — interpolating in
+ * this space produces smoother gradients than naive RGB.
+ *
+ * @since 1.3.5
+ */
+declare const rgbToOklab: (rgb: RGB) => Oklab;
+/**
+ * Convert Oklab back to RGB (0–255). Out-of-gamut values are clamped.
+ *
+ * @since 1.3.5
+ */
+declare const oklabToRgb: (oklab: Oklab) => RGB;
+/** Color space to interpolate in. Default `'rgb'` for backward compatibility. */
+type ColorSpace = 'rgb' | 'hsl' | 'oklab';
+/**
+ * Linearly interpolate between two RGB colors. `t` is clamped to [0, 1].
+ *
+ * **v1.3.5+**: Accepts an optional 4th argument `space` to control which
+ * color space the interpolation happens in. `'oklab'` produces the
+ * smoothest, most perceptually uniform gradients but is ~3× slower than
+ * naive RGB. `'hsl'` is useful for hue rotation.
+ *
+ * @param a     - Start color (RGB, 0–255).
+ * @param b     - End color (RGB, 0–255).
+ * @param t     - Mixing factor in [0, 1] (clamped).
+ * @param space - Interpolation space. Default `'rgb'` (backward-compat).
+ *
+ * @example
+ * ```ts
+ * lerpColor(red, blue, 0.5);                   // naive RGB midpoint
+ * lerpColor(red, blue, 0.5, 'oklab');          // perceptual midpoint
+ * lerpColor(red, blue, 0.5, 'hsl');            // through purple via hue
+ * ```
+ */
+declare const lerpColor: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
+/**
+ * Semantic alias for `lerpColor`. Reads more naturally for the "blend
+ * two colors" use case, especially with a named color space.
+ *
+ * @example
+ * ```ts
+ * mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
+ * // Accepts hex strings OR RGB objects
+ * ```
+ *
+ * @since 1.3.5
+ */
+declare const mixColors: (a: RGB | string, b: RGB | string, t: number, space?: ColorSpace) => RGB;
+/**
+ * Quantize a color to N levels per channel. Useful for palette
+ * reduction, posterization effects, or matching a constrained color
+ * palette (e.g., 16-color terminals).
+ *
+ * Mathematically: maps each channel to the nearest of `levels` evenly
+ * spaced values in [0, 255]. With `levels=2` you get pure on/off per
+ * channel (8 colors total). With `levels=4` you get a 64-color palette.
+ *
+ * @param color  - Input RGB (0–255).
+ * @param levels - Number of discrete levels per channel (≥2, default `4`).
+ *
+ * @example
+ * ```ts
+ * quantizeColor({ r: 100, g: 150, b: 200 }, 4);
+ * // → snaps each channel to nearest of [0, 85, 170, 255]
+ * ```
+ *
+ * @since 1.3.5
+ */
+declare const quantizeColor: (color: RGB, levels?: 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, space?: ColorSpace) => RGB;
+declare const rgbTo256: (r: number, g: number, b: number) => number;
+declare const stripAnsi$2: (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$1: (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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+/**
+ * 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).
+ * @param space - **v1.3.5+** Color space for interpolation:
+ *                `'rgb'` (default, fast), `'hsl'` (hue rotation),
+ *                or `'oklab'` (perceptually uniform).
+ * @returns Array of hex strings, including both endpoints.
+ *
+ * @example
+ * ```ts
+ * import { gradientStops } from 'ansimax';
+ *
+ * // Naive RGB (default)
+ * const stops = gradientStops('#ff0000', '#0000ff', 5);
+ *
+ * // Perceptually uniform (smoother visual transition)
+ * const smooth = gradientStops('#ff0000', '#0000ff', 5, 'oklab');
+ * ```
+ */
+declare const gradientStops: (start: string, end: string, count: number, space?: ColorSpace) => 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[";
@@ -234,7 +691,7 @@ declare const resetColorSupportCache: () => void;
 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;
+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. */
@@ -292,238 +749,39 @@ declare const sleep: (ms: number, opts?: SleepOptions) => Promise<void>;
  * 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;
-}
-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$1: (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;
-}
 /**
- * Subscribe to terminal resize events. Returns a function that unsubscribes.
- * Useful for dashboards and live UIs that need responsive re-layout.
+ * 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.
  *
- * By default coalesces rapid resize events at ~20fps (50ms throttle) to
- * avoid flooding the redraw path.
+ * @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
- * 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;
-}
-/**
- * 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;
-}
-/**
- * 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
- * `.`, `*`, `+`, `?`, `^`, `$`, `(`, `)`, `[`, `]`, `{`, `}`, `|`,
- * `\`, `/`.
+ * ```ts
+ * import { hyperlink } from 'ansimax';
  *
- * @example
- *   new RegExp(escapeRegex('a.b+c')); // matches "a.b+c" literally
+ * console.log(`Visit ${hyperlink('https://github.com/Brashkie/ansimax', 'the repo')}`);
+ * console.log(`Email: ${hyperlink('mailto:hi@example.com')}`);
+ * ```
  */
-declare const escapeRegex: (str: string) => string;
+declare const hyperlink: (url: string, label?: 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.
+ * Returns the escape sequence to clear the entire current line and move
+ * the cursor back to column 1. Equivalent to `screen.clearLine() + '\r'`.
  *
  * @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.
+ * ```ts
+ * import { clearLine } from 'ansimax';
  *
- * @example
- *   padBoth('hi', 6) → '  hi  '
- *   padBoth('hi', 5) → ' hi  '
+ * for (let i = 0; i <= 100; i++) {
+ *   process.stdout.write(clearLine() + `Progress: ${i}%`);
+ *   await sleep(30);
+ * }
+ * ```
  */
-declare const padBoth: (str: string, width: number, ch?: string) => string;
+declare const clearLine: () => string;
 
 type ColorFn = (text: string) => string;
 
@@ -921,6 +1179,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 +1232,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 {
@@ -1227,7 +1521,7 @@ declare const images: {
     createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
     colors: {
         hex: (h: unknown) => RGB | null;
-        lerp: (a: RGB, b: RGB, t: number) => RGB;
+        lerp: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
         blend: (fg: Pixel, bg: RGB) => RGB;
     };
     clearAnsiCache: () => void;
@@ -2557,6 +2851,41 @@ declare const json: {
     pretty: (value: unknown, opts?: PrettyOptions) => string;
 };
 
+type EasingFunction = (t: number) => number;
+/**
+ * Union of all built-in easing names in the comprehensive Robert Penner
+ * library. Provides autocompletion and prevents typos when looking up
+ * functions in `easings`.
+ *
+ * **Note**: This is the v1.3.5 extended library. The original `EasingName`
+ * from the gradient module is a smaller union (5 values) and is
+ * preserved for backward compatibility.
+ *
+ * @since 1.3.5
+ */
+type EasingLibraryName = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic' | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce';
+/**
+ * A library of named easing functions. Each maps `t ∈ [0, 1]` to an
+ * eased value, typically also in `[0, 1]` (back/elastic briefly
+ * overshoot by design).
+ *
+ * Typed as `Record<EasingLibraryName, EasingFunction>` so all 31 keys are
+ * known to TypeScript — autocompletion + no `possibly undefined` errors
+ * when accessing standard names.
+ *
+ * @since 1.3.5
+ */
+declare const easings: Record<EasingLibraryName, EasingFunction>;
+/**
+ * Resolve an easing reference to a function. Accepts a function (returned
+ * as-is), a named string in `easings` (typed `EasingName` for autocomplete,
+ * but any string is allowed at runtime with linear fallback), or
+ * `undefined`/invalid input (returns `linear`).
+ *
+ * @since 1.3.5
+ */
+declare const resolveEasingByName: (e: EasingLibraryName | string | EasingFunction | undefined | null) => EasingFunction;
+
 declare const ansimax: {
     color: {
         black: ColorFn;
@@ -2624,6 +2953,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;
@@ -2715,7 +3046,7 @@ declare const ansimax: {
         createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
         colors: {
             hex: (h: unknown) => RGB | null;
-            lerp: (a: RGB, b: RGB, t: number) => RGB;
+            lerp: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
             blend: (fg: Pixel, bg: RGB) => RGB;
         };
         clearAnsiCache: () => void;
@@ -2723,4 +3054,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 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, 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, grid, 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 ColorSpace, 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 EasingFunction, type EasingLibraryName, 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 HSL, 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 Oklab, 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, clampByte, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, easings, 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, hslToRgb, hsplit, hyperlink, images, isFiniteNumber, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureBlock, measureTree, memoize, mixColors, nextTick, oklabToRgb, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, quantizeColor, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resolveEasingByName, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rgbToHsl, rgbToOklab, rotate90, safeInt, 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 };