ansimax 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -3,6 +3,116 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.3] — Gradient factory + performance
+
+Patch release adding a new performance-oriented API and refinements. No
+breaking changes — every 1.2.x program runs identically.
+
+### Added — `createGradient()` factory
+
+A pre-resolved gradient that can be applied repeatedly to different
+strings without re-parsing hex stops on every call. Significantly
+faster for animation loops, frame-based rendering, and bulk colorizing:
+
+```ts
+import { createGradient } from 'ansimax';
+
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+
+// Reuse — hex stops are pre-resolved
+console.log(fire('first line'));
+console.log(fire('second line'));
+
+// Use as colorFn for ascii.banner (matches the ColorFn signature)
+console.log(ascii.banner('FIRE', { colorFn: fire }));
+
+// Per-call options still work (especially useful for animation)
+for (let p = 0; p < 1; p += 0.05) {
+  process.stdout.write('\r' + fire('flowing', { phase: p }));
+}
+```
+
+**Performance**: hex→RGB conversion happens once at factory time. For
+loops calling `gradient()` hundreds of times per frame, this can cut
+gradient overhead by ~40–60% (depending on stop count).
+
+**API surface**:
+- `createGradient(stops, defaultOpts?)` returns `(text, opts?) => string`
+- The returned function matches the `ColorFn` shape (compatible with
+  `ascii.banner({ colorFn })`, `themes.gradient`, etc.)
+- Per-call `opts` override defaults; useful for varying `phase` per frame
+  while keeping the same colors/easing
+
+### Improved
+
+- **More JSDoc on `createGradient`** with three runnable `@example` blocks.
+- All 1880 + 12 new tests pass.
+- No new runtime dependencies — still zero.
+
+---
+
+## [1.2.2] — Quality polish
+
+Patch release focused on API ergonomics and robustness refinements. No
+breaking changes — every 1.2.x program runs identically.
+
+### Improved
+
+- **`animateGradient` controller is now thenable** — you can `await` it
+  directly instead of `await ctrl.done`:
+
+  ```ts
+  // Before (v1.2.0)
+  const ctrl = animateGradient(text, stops, { infinite: false, cycles: 1 });
+  await ctrl.done;
+
+  // After (v1.2.2) — both still work
+  await animateGradient(text, stops, { infinite: false, cycles: 1 });
+
+  // Also supports .then() / .catch() / .finally()
+  animateGradient(text, stops, opts).finally(() => cleanup());
+  ```
+
+  The `.done` property remains for backwards compatibility.
+
+- **Stable error codes for programmatic catch.** Errors thrown by the
+  theme system now carry a `.code` property with the `ANSIMAX_*` prefix
+  for stable programmatic filtering:
+
+  ```ts
+  try {
+    themes.use('not-a-real-theme');
+  } catch (e) {
+    if ((e as { code?: string }).code === 'ANSIMAX_UNKNOWN_THEME') {
+      // handle gracefully
+    }
+  }
+  ```
+
+  New codes: `ANSIMAX_INVALID_THEME`, `ANSIMAX_INVALID_THEME_NAME`,
+  `ANSIMAX_UNKNOWN_THEME`. Error messages and types
+  (`TypeError` / `RangeError`) are unchanged.
+
+- **`animateGradient` is safer in sandboxed environments.** The default
+  stdout-write path now checks `process?.stdout?.write` before calling
+  it, so the function no longer crashes in workers, Edge runtimes, or
+  embedded sandboxes that lack a writable stdout.
+
+- **Better JSDoc on the `gradient()` function.** IntelliSense now shows
+  parameter descriptions, return semantics, and three runnable
+  `@example` blocks (basic, with easing, with phase animation).
+
+- **README fix: `Easing Curves` snippet.** The v1.2.0 snippet was missing
+  the `stops` variable declaration. Now copy-paste runnable.
+
+### Notes
+
+- 1880 + 7 new tests pass.
+- No new dependencies — still zero runtime deps.
+- All API additions are non-breaking and side-effect-free for existing code.
+
+---
+
 ## [1.2.0] — Phase 2 complete: animated, eased & conic gradients
 
 Minor release closing the **gradient engine roadmap (Phase 2)** with three

package/README.es.md

@@ -7,7 +7,7 @@
 _Colores • Gradientes • Animaciones • ASCII Art • Pixel Art • Árboles • Componentes • Temas_
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-v1.2.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.3-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-1700%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -216,10 +216,17 @@ const ctrl = animateGradient('Cargando...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
 
 await sleep(3000);
 ctrl.stop();
+
+// v1.2.2: await directo (no se necesita .done)
+await animateGradient('¡Listo!', ['#50fa7b', '#bd93f9'], {
+  infinite: false, cycles: 2, duration: 800,
+});
 ```
 
 ### Curvas de interpolación (v1.2.0)
 
+<img src="media/easing_curves.png" alt="Colors and gradients" />
+
 ```ts
 import { gradient } from 'ansimax';
 
@@ -238,6 +245,8 @@ console.log(gradient('hola mundo', stops, { easing: (t) => t * t * t }));
 
 ### Gradientes cónicos (v1.2.0)
 
+<img src="media/conic_gradients.png" alt="Colors and gradients" />
+
 ```ts
 import { gradientRect } from 'ansimax';
 
@@ -251,6 +260,28 @@ console.log(gradientRect({
 }));
 ```
 
+### Gradientes reusables (v1.2.3)
+
+```ts
+import { createGradient, ascii } from 'ansimax';
+
+// Pre-resuelve los stops de hex una vez — significativamente más rápido para uso repetido
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+
+console.log(fire('Primera línea'));
+console.log(fire('Segunda línea'));
+console.log(fire('Tercera línea'));
+
+// Úsalo como colorFn para banners — misma firma de ColorFn
+console.log(ascii.banner('FIRE', { colorFn: fire }));
+
+// Las opciones por-llamada aún funcionan — perfecto para animación
+for (let p = 0; p < 1; p += 0.05) {
+  process.stdout.write('\r' + fire('fluyendo', { phase: p }));
+  await new Promise((r) => setTimeout(r, 50));
+}
+```
+
 ### ASCII Art
 
 <img src="media/ascii_art.png" alt="ASCII art" />
@@ -326,7 +357,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.0'));
+console.log(components.badge('VERSION', 'v1.2.3'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -728,6 +759,36 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.3 — Factory de gradientes + performance
+
+Release patch añadiendo una API orientada a performance:
+
+- ⚡ **Factory `createGradient()`** — pre-resuelve los stops de hex una vez para reuso, ~40-60% más rápido en loops de animación y colorizado en bulk
+- 📖 Más JSDoc con ejemplos ejecutables
+- 🎯 Coincide con la firma `ColorFn` — funciona como `colorFn` en `ascii.banner`, themes, etc.
+
+```ts
+import { createGradient } from 'ansimax';
+
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+console.log(fire('¡Colores reusados!'));
+console.log(ascii.banner('FIRE', { colorFn: fire }));
+```
+
+Drop-in replacement para `1.2.2`.
+
+### v1.2.2 — Pulido de calidad
+
+Release patch enfocado en ergonomía de API y refinamientos de robustez.
+
+- ✨ **`animateGradient` ahora es thenable** — `await animateGradient(...)` directo sin `.done`
+- 🎯 **Códigos de error estables** — los errores de tema llevan propiedad `.code` (`ANSIMAX_UNKNOWN_THEME`, etc.) para `catch` programático
+- 🛡️ **Seguridad en sandboxes** — `animateGradient` ya no crashea cuando `process.stdout` no está disponible (workers, edge runtimes)
+- 📖 **Mejor JSDoc** — `gradient()` ahora muestra IntelliSense completo con ejemplos
+- 🐛 **Fix de README** — snippet de Easing Curves ahora es ejecutable copy-paste
+
+Drop-in replacement para `1.2.0`.
+
 ### v1.2.0 — Fase 2 completa: gradientes animados, easing y cónicos
 
 Release minor que cierra el roadmap del motor de gradientes con tres features potentes:
@@ -862,4 +923,4 @@ Ansimax está licenciada bajo **Apache License, Version 2.0** — una licencia p
 
 Si Ansimax te ayuda a hacer mejores CLIs, ¡dale ⭐ en [GitHub](https://github.com/Brashkie/ansimax)!
 
-</div>
+</div>

package/README.md

@@ -7,7 +7,7 @@
 _Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-v1.2.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.3-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-1700%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -216,6 +216,11 @@ const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
 
 await sleep(3000);
 ctrl.stop();
+
+// v1.2.2: await directly (no .done needed)
+await animateGradient('Done!', ['#50fa7b', '#bd93f9'], {
+  infinite: false, cycles: 2, duration: 800,
+});
 ```
 
 ### Easing Curves (v1.2.0)
@@ -255,6 +260,28 @@ console.log(gradientRect({
 }));
 ```
 
+### Reusable Gradients (v1.2.3)
+
+```ts
+import { createGradient, ascii } from 'ansimax';
+
+// Pre-resolve hex stops once — significantly faster for repeated use
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+
+console.log(fire('First line'));
+console.log(fire('Second line'));
+console.log(fire('Third line'));
+
+// Use as a colorFn for banners — same ColorFn signature
+console.log(ascii.banner('FIRE', { colorFn: fire }));
+
+// Per-call options still work — perfect for animation
+for (let p = 0; p < 1; p += 0.05) {
+  process.stdout.write('\r' + fire('flowing', { phase: p }));
+  await new Promise((r) => setTimeout(r, 50));
+}
+```
+
 ### ASCII Art
 
 <img src="media/ascii_art.png" alt="ASCII art" />
@@ -330,7 +357,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.0'));
+console.log(components.badge('VERSION', 'v1.2.3'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -732,6 +759,36 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.3 — Gradient factory + performance
+
+Patch release adding a performance-oriented API:
+
+- ⚡ **`createGradient()` factory** — pre-resolves hex stops once for reuse, ~40-60% faster for animation loops and bulk colorizing
+- 📖 More JSDoc with runnable examples
+- 🎯 Matches the `ColorFn` signature — works as `colorFn` in `ascii.banner`, themes, etc.
+
+```ts
+import { createGradient } from 'ansimax';
+
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+console.log(fire('Reused colors!'));
+console.log(ascii.banner('FIRE', { colorFn: fire }));
+```
+
+Drop-in replacement for `1.2.2`.
+
+### v1.2.2 — Quality polish
+
+Patch release focused on API ergonomics and robustness refinements.
+
+- ✨ **`animateGradient` is now thenable** — `await animateGradient(...)` directly without `.done`
+- 🎯 **Stable error codes** — theme errors carry `.code` properties (`ANSIMAX_UNKNOWN_THEME`, etc.) for programmatic catch
+- 🛡️ **Sandbox safety** — `animateGradient` no longer crashes when `process.stdout` is unavailable (workers, edge runtimes)
+- 📖 **Better JSDoc** — `gradient()` now shows full IntelliSense with examples
+- 🐛 **README fix** — Easing Curves snippet now copy-paste runnable
+
+Drop-in replacement for `1.2.0`.
+
 ### v1.2.0 — Phase 2 complete: animated, eased & conic gradients
 
 Minor release closing the gradient engine roadmap with three powerful features:
@@ -866,4 +923,4 @@ Ansimax is licensed under the **Apache License, Version 2.0** — a permissive l
 
 If Ansimax helps you ship better CLIs, give it a ⭐ on [GitHub](https://github.com/Brashkie/ansimax)!
 
-</div>
+</div>

package/dist/index.d.mts

@@ -565,7 +565,64 @@ interface GradientOptions {
      */
     phase?: number;
 }
+/**
+ * Apply a multi-stop color gradient across the visible characters of `text`.
+ * ANSI escapes are skipped, and Unicode wide characters / graphemes are
+ * counted correctly.
+ *
+ * @param text  - The text to colorize. Non-string inputs are coerced via `String(text)`.
+ * @param stops - Array of hex colors (`#rgb` or `#rrggbb`). At least 1 required.
+ *                Invalid stops are silently dropped; an empty array returns input as-is.
+ * @param opts  - Optional configuration. See `GradientOptions`.
+ *
+ * @returns ANSI-colorized string. Returns input unchanged if `NO_COLOR` is set
+ *          or if no valid stops are provided.
+ *
+ * @example
+ * ```ts
+ * gradient('Hello world!', ['#ff0000', '#00ff00', '#0000ff']);
+ * // → ANSI-colored "Hello world!" with smooth color transition
+ * ```
+ *
+ * @example with easing curve
+ * ```ts
+ * gradient('Smooth text', ['#ff79c6', '#8be9fd'], { easing: 'ease-in-out' });
+ * ```
+ *
+ * @example animated phase shift
+ * ```ts
+ * setInterval(() => {
+ *   const phase = (Date.now() / 1000) % 1;
+ *   process.stdout.write('\r' + gradient('flowing', ['#f00', '#00f'], { phase }));
+ * }, 33);
+ * ```
+ */
 declare const gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
+/**
+ * A pre-resolved gradient that can be applied repeatedly to different
+ * strings without re-parsing hex stops. Useful for hot loops, animation
+ * frames, or any case where the same color palette colorizes many texts.
+ *
+ * The returned function accepts the same per-call options as `gradient()`
+ * (e.g. you can still override `phase` per call for animation).
+ *
+ * @example
+ * ```ts
+ * const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+ *
+ * console.log(fire('first line'));
+ * console.log(fire('second line'));
+ *
+ * // Use as colorFn for ascii.banner
+ * console.log(ascii.banner('FIRE', { colorFn: fire }));
+ *
+ * // Animate by overriding phase per frame
+ * for (let p = 0; p < 1; p += 0.05) {
+ *   console.log(fire('flowing', { phase: p }));
+ * }
+ * ```
+ */
+declare const createGradient: (stops: string[] | null | undefined, defaultOpts?: Omit<GradientOptions, "phase">) => ((text: unknown, opts?: GradientOptions) => string);
 declare const rainbow: ColorFn;
 interface AnimateGradientOptions {
     /** Total animation duration in ms. Default `2000`. */
@@ -614,6 +671,15 @@ interface AnimateGradientController {
     stop: () => void;
     /** Promise that resolves when animation finishes (stop / abort / cycle limit). */
     done: Promise<void>;
+    /**
+     * Thenable hook — lets you `await animateGradient(...)` directly.
+     * Equivalent to `await ctrl.done`.
+     */
+    then: Promise<void>['then'];
+    /** Equivalent to `ctrl.done.catch(...)`. */
+    catch: Promise<void>['catch'];
+    /** Equivalent to `ctrl.done.finally(...)`. */
+    finally: Promise<void>['finally'];
 }
 declare const animateGradient: (text: string, stops: string[], opts?: AnimateGradientOptions) => AnimateGradientController;
 declare const PRESET_DEFS: {
@@ -1701,4 +1767,4 @@ declare const ansimax: {
     configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-export { type AnimateGradientController, type AnimateGradientOptions, 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 EasingFn, type EasingName, 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, animateGradient, 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 };
+export { type AnimateGradientController, type AnimateGradientOptions, 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 EasingFn, type EasingName, 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, animateGradient, 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, createGradient, 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 };

package/dist/index.d.ts

@@ -565,7 +565,64 @@ interface GradientOptions {
      */
     phase?: number;
 }
+/**
+ * Apply a multi-stop color gradient across the visible characters of `text`.
+ * ANSI escapes are skipped, and Unicode wide characters / graphemes are
+ * counted correctly.
+ *
+ * @param text  - The text to colorize. Non-string inputs are coerced via `String(text)`.
+ * @param stops - Array of hex colors (`#rgb` or `#rrggbb`). At least 1 required.
+ *                Invalid stops are silently dropped; an empty array returns input as-is.
+ * @param opts  - Optional configuration. See `GradientOptions`.
+ *
+ * @returns ANSI-colorized string. Returns input unchanged if `NO_COLOR` is set
+ *          or if no valid stops are provided.
+ *
+ * @example
+ * ```ts
+ * gradient('Hello world!', ['#ff0000', '#00ff00', '#0000ff']);
+ * // → ANSI-colored "Hello world!" with smooth color transition
+ * ```
+ *
+ * @example with easing curve
+ * ```ts
+ * gradient('Smooth text', ['#ff79c6', '#8be9fd'], { easing: 'ease-in-out' });
+ * ```
+ *
+ * @example animated phase shift
+ * ```ts
+ * setInterval(() => {
+ *   const phase = (Date.now() / 1000) % 1;
+ *   process.stdout.write('\r' + gradient('flowing', ['#f00', '#00f'], { phase }));
+ * }, 33);
+ * ```
+ */
 declare const gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
+/**
+ * A pre-resolved gradient that can be applied repeatedly to different
+ * strings without re-parsing hex stops. Useful for hot loops, animation
+ * frames, or any case where the same color palette colorizes many texts.
+ *
+ * The returned function accepts the same per-call options as `gradient()`
+ * (e.g. you can still override `phase` per call for animation).
+ *
+ * @example
+ * ```ts
+ * const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+ *
+ * console.log(fire('first line'));
+ * console.log(fire('second line'));
+ *
+ * // Use as colorFn for ascii.banner
+ * console.log(ascii.banner('FIRE', { colorFn: fire }));
+ *
+ * // Animate by overriding phase per frame
+ * for (let p = 0; p < 1; p += 0.05) {
+ *   console.log(fire('flowing', { phase: p }));
+ * }
+ * ```
+ */
+declare const createGradient: (stops: string[] | null | undefined, defaultOpts?: Omit<GradientOptions, "phase">) => ((text: unknown, opts?: GradientOptions) => string);
 declare const rainbow: ColorFn;
 interface AnimateGradientOptions {
     /** Total animation duration in ms. Default `2000`. */
@@ -614,6 +671,15 @@ interface AnimateGradientController {
     stop: () => void;
     /** Promise that resolves when animation finishes (stop / abort / cycle limit). */
     done: Promise<void>;
+    /**
+     * Thenable hook — lets you `await animateGradient(...)` directly.
+     * Equivalent to `await ctrl.done`.
+     */
+    then: Promise<void>['then'];
+    /** Equivalent to `ctrl.done.catch(...)`. */
+    catch: Promise<void>['catch'];
+    /** Equivalent to `ctrl.done.finally(...)`. */
+    finally: Promise<void>['finally'];
 }
 declare const animateGradient: (text: string, stops: string[], opts?: AnimateGradientOptions) => AnimateGradientController;
 declare const PRESET_DEFS: {
@@ -1701,4 +1767,4 @@ declare const ansimax: {
     configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-export { type AnimateGradientController, type AnimateGradientOptions, 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 EasingFn, type EasingName, 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, animateGradient, 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 };
+export { type AnimateGradientController, type AnimateGradientOptions, 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 EasingFn, type EasingName, 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, animateGradient, 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, createGradient, 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 };

package/dist/index.js

@@ -70,6 +70,7 @@ __export(index_exports, {
   configure: () => configure,
   countNodes: () => countNodes,
   createCanvas: () => createCanvas,
+  createGradient: () => createGradient,
   createOutputBuffer: () => createOutputBuffer,
   createTheme: () => createTheme,
   cursor: () => cursor,
@@ -1165,6 +1166,28 @@ var gradient = (text, stops, opts = {}) => {
   }
   return _gradientAnsiAware(s, colors, easingFn, phaseN);
 };
+var createGradient = (stops, defaultOpts = {}) => {
+  const colors = Array.isArray(stops) ? stops.map(safeHex).filter((c) => c !== null) : [];
+  const defaultEasingFn = resolveEasing(defaultOpts.easing);
+  const defaultPreserveAnsi = defaultOpts.preserveAnsi ?? false;
+  return (text, opts = {}) => {
+    const s = coerceText(text);
+    if (!s || isNoColor()) return s;
+    if (colors.length === 0) return s;
+    if (colors.length === 1) {
+      const c = colors[0];
+      return adaptiveFg(c.r, c.g, c.b) + s + reset();
+    }
+    const easingFn = opts.easing !== void 0 ? resolveEasing(opts.easing) : defaultEasingFn;
+    const preserveAnsi = opts.preserveAnsi ?? defaultPreserveAnsi;
+    const phase = opts.phase ?? 0;
+    const phaseN = Number.isFinite(phase) ? (phase % 1 + 1) % 1 : 0;
+    if (!preserveAnsi || !s.includes("\x1B")) {
+      return _gradientPlain(s, colors, easingFn, phaseN);
+    }
+    return _gradientAnsiAware(s, colors, easingFn, phaseN);
+  };
+};
 var _gradientPlain = (text, colors, easingFn, phase) => {
   const chars = [...text];
   const visible = chars.filter((c) => c !== " ").length;
@@ -1273,7 +1296,13 @@ var animateGradient = (text, stops, opts = {}) => {
   if (signal) {
     if (signal.aborted) {
       stop();
-      return { stop, done };
+      return {
+        stop,
+        done,
+        then: done.then.bind(done),
+        catch: done.catch.bind(done),
+        finally: done.finally.bind(done)
+      };
     }
     signal.addEventListener("abort", stop, { once: true });
   }
@@ -1288,7 +1317,9 @@ var animateGradient = (text, stops, opts = {}) => {
       onFrame(frame, phase);
     } else {
       try {
-        process.stdout.write("\r" + frame);
+        if (process?.stdout?.write) {
+          process.stdout.write("\r" + frame);
+        }
       } catch {
       }
     }
@@ -1303,7 +1334,14 @@ var animateGradient = (text, stops, opts = {}) => {
   if (!stopped) {
     timer = setInterval(renderFrame, frameInterval2);
   }
-  return { stop, done };
+  return {
+    stop,
+    done,
+    // Thenable hooks — bind to done so `await ctrl` works directly
+    then: done.then.bind(done),
+    catch: done.catch.bind(done),
+    finally: done.finally.bind(done)
+  };
 };
 var PRESET_DEFS = {
   sunset: ["#ff6b6b", "#feca57", "#48dbfb"],
@@ -4222,13 +4260,18 @@ var STYLE_NAMES = [
   "muted",
   "text"
 ];
+var _themeError = (Ctor, code, message) => {
+  const err = new Ctor(message);
+  err.code = code;
+  return err;
+};
 var validateTheme = (t) => {
   if (typeof t !== "object" || t === null || Array.isArray(t)) {
-    throw new TypeError("Theme must be a non-null object.");
+    throw _themeError(TypeError, "ANSIMAX_INVALID_THEME", "Theme must be a non-null object.");
   }
   const obj = t;
   if (typeof obj.name !== "string" || obj.name.length === 0) {
-    throw new TypeError('Theme must have a non-empty "name" string.');
+    throw _themeError(TypeError, "ANSIMAX_INVALID_THEME_NAME", 'Theme must have a non-empty "name" string.');
   }
   for (const key of REQUIRED_COLOR_KEYS) {
     const value = obj[key];
@@ -4567,7 +4610,9 @@ var themes = {
   use(name) {
     const t = _globalRegistry.get(name);
     if (!t) {
-      throw new RangeError(
+      throw _themeError(
+        RangeError,
+        "ANSIMAX_UNKNOWN_THEME",
         `Theme "${name}" not found. Available themes: ${[..._globalRegistry.keys()].join(", ")}`
       );
     }
@@ -5466,6 +5511,7 @@ var index_default = ansimax;
   configure,
   countNodes,
   createCanvas,
+  createGradient,
   createOutputBuffer,
   createTheme,
   cursor,

package/dist/index.mjs

@@ -992,6 +992,28 @@ var gradient = (text, stops, opts = {}) => {
   }
   return _gradientAnsiAware(s, colors, easingFn, phaseN);
 };
+var createGradient = (stops, defaultOpts = {}) => {
+  const colors = Array.isArray(stops) ? stops.map(safeHex).filter((c) => c !== null) : [];
+  const defaultEasingFn = resolveEasing(defaultOpts.easing);
+  const defaultPreserveAnsi = defaultOpts.preserveAnsi ?? false;
+  return (text, opts = {}) => {
+    const s = coerceText(text);
+    if (!s || isNoColor()) return s;
+    if (colors.length === 0) return s;
+    if (colors.length === 1) {
+      const c = colors[0];
+      return adaptiveFg(c.r, c.g, c.b) + s + reset();
+    }
+    const easingFn = opts.easing !== void 0 ? resolveEasing(opts.easing) : defaultEasingFn;
+    const preserveAnsi = opts.preserveAnsi ?? defaultPreserveAnsi;
+    const phase = opts.phase ?? 0;
+    const phaseN = Number.isFinite(phase) ? (phase % 1 + 1) % 1 : 0;
+    if (!preserveAnsi || !s.includes("\x1B")) {
+      return _gradientPlain(s, colors, easingFn, phaseN);
+    }
+    return _gradientAnsiAware(s, colors, easingFn, phaseN);
+  };
+};
 var _gradientPlain = (text, colors, easingFn, phase) => {
   const chars = [...text];
   const visible = chars.filter((c) => c !== " ").length;
@@ -1100,7 +1122,13 @@ var animateGradient = (text, stops, opts = {}) => {
   if (signal) {
     if (signal.aborted) {
       stop();
-      return { stop, done };
+      return {
+        stop,
+        done,
+        then: done.then.bind(done),
+        catch: done.catch.bind(done),
+        finally: done.finally.bind(done)
+      };
     }
     signal.addEventListener("abort", stop, { once: true });
   }
@@ -1115,7 +1143,9 @@ var animateGradient = (text, stops, opts = {}) => {
       onFrame(frame, phase);
     } else {
       try {
-        process.stdout.write("\r" + frame);
+        if (process?.stdout?.write) {
+          process.stdout.write("\r" + frame);
+        }
       } catch {
       }
     }
@@ -1130,7 +1160,14 @@ var animateGradient = (text, stops, opts = {}) => {
   if (!stopped) {
     timer = setInterval(renderFrame, frameInterval2);
   }
-  return { stop, done };
+  return {
+    stop,
+    done,
+    // Thenable hooks — bind to done so `await ctrl` works directly
+    then: done.then.bind(done),
+    catch: done.catch.bind(done),
+    finally: done.finally.bind(done)
+  };
 };
 var PRESET_DEFS = {
   sunset: ["#ff6b6b", "#feca57", "#48dbfb"],
@@ -4049,13 +4086,18 @@ var STYLE_NAMES = [
   "muted",
   "text"
 ];
+var _themeError = (Ctor, code, message) => {
+  const err = new Ctor(message);
+  err.code = code;
+  return err;
+};
 var validateTheme = (t) => {
   if (typeof t !== "object" || t === null || Array.isArray(t)) {
-    throw new TypeError("Theme must be a non-null object.");
+    throw _themeError(TypeError, "ANSIMAX_INVALID_THEME", "Theme must be a non-null object.");
   }
   const obj = t;
   if (typeof obj.name !== "string" || obj.name.length === 0) {
-    throw new TypeError('Theme must have a non-empty "name" string.');
+    throw _themeError(TypeError, "ANSIMAX_INVALID_THEME_NAME", 'Theme must have a non-empty "name" string.');
   }
   for (const key of REQUIRED_COLOR_KEYS) {
     const value = obj[key];
@@ -4394,7 +4436,9 @@ var themes = {
   use(name) {
     const t = _globalRegistry.get(name);
     if (!t) {
-      throw new RangeError(
+      throw _themeError(
+        RangeError,
+        "ANSIMAX_UNKNOWN_THEME",
         `Theme "${name}" not found. Available themes: ${[..._globalRegistry.keys()].join(", ")}`
       );
     }
@@ -5292,6 +5336,7 @@ export {
   configure,
   countNodes,
   createCanvas,
+  createGradient,
   createOutputBuffer,
   createTheme,
   cursor,

package/examples/all-in-one.cjs

@@ -118,7 +118,7 @@ async function main() {
   console.log(components.section('🏷️  Badges & Status', { width: 60 }));
   console.log();
   console.log(' ',
-    components.badge('VERSION', 'v1.2.0'),
+    components.badge('VERSION', 'v1.2.3'),
     components.badge('BUILD', 'passing'),
     components.badge('LICENSE', 'Apache 2.0'));
   console.log();

package/examples/all-in-one.mjs

@@ -117,7 +117,7 @@ console.log();
 console.log(components.section('🏷️  Badges & Status', { width: 60 }));
 console.log();
 console.log(' ',
-  components.badge('VERSION', 'v1.2.0'),
+  components.badge('VERSION', 'v1.2.3'),
   components.badge('BUILD', 'passing'),
   components.badge('LICENSE', 'Apache 2.0'));
 console.log();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ansimax",
-  "version": "1.2.1",
-  "description": "Zero-dependency CLI rendering library: colors, gradients, animations, ASCII art, pixel art, components, and themes — all in TypeScript.",
+  "version": "1.2.3",
+  "description": "Zero-dependency CLI rendering library: colors, gradients, animations, ASCII art, pixel art, components, and themes \u2014 all in TypeScript.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",