ansimax 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,108 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] — Phase 2 complete: animated, eased & conic gradients
+
+Minor release closing the **gradient engine roadmap (Phase 2)** with three
+long-awaited capabilities. All additions are fully backwards-compatible —
+existing `gradient()` calls work identically.
+
+### Added — Easing curves
+
+`gradient()` now accepts an `easing` option to control how colors are
+distributed along the text. Five built-in curves plus custom functions:
+
+```ts
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'ease-in' });
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'ease-out' });
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'ease-in-out' });
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'cubic-bezier' });
+
+// Or pass a custom EasingFn (t → eased t, both in [0,1])
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: (t) => t * t * t });
+```
+
+- `linear` — even distribution (default, identical to pre-1.2.0 behavior)
+- `ease-in` — concentrates colors at the end (quadratic)
+- `ease-out` — concentrates colors at the start (quadratic)
+- `ease-in-out` — slow at both ends, fast in middle
+- `cubic-bezier` — CSS-style `ease` curve (Newton-Raphson approximated)
+- Out-of-range custom easings are clamped to `[0, 1]` automatically
+
+### Added — Phase offset (flowing colors)
+
+`gradient()` now accepts a `phase` parameter `[0, 1)` that shifts the
+gradient along the text. Combined with an animation loop, this produces
+a flowing color effect:
+
+```ts
+gradient('hello', ['#ff0000', '#0000ff'], { phase: 0.5 });
+// negative values wrap forward; NaN/Infinity falls back to 0
+```
+
+### Added — `animateGradient()` API
+
+High-level API for animated gradients with proper lifecycle management:
+
+```ts
+import { animateGradient } from 'ansimax';
+
+const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
+  duration: 2000,
+  fps: 30,
+  direction: 'forward',  // or 'reverse'
+  infinite: true,
+});
+
+// Later
+ctrl.stop();
+// Or via AbortController
+const abort = new AbortController();
+animateGradient('hi', stops, { signal: abort.signal });
+abort.abort();
+```
+
+Returns an `AnimateGradientController` with `.stop()` and `.done` (Promise).
+Supports `AbortSignal`, custom render via `onFrame`, fps cap at 60,
+and direction reversal.
+
+### Added — Conic gradients
+
+`gradientRect()` now supports `style: 'conic'` for radial sweeps around
+the center point:
+
+```ts
+import { gradientRect } from 'ansimax';
+
+console.log(gradientRect({
+  width: 30, height: 15,
+  colors: ['#ff0000', '#00ff00', '#0000ff', '#ff0000'],
+  style: 'conic',
+  startAngle: 0,  // rotation in degrees
+  dither: 'bayer',
+}));
+```
+
+- `startAngle` (degrees) rotates the sweep
+- Non-finite `startAngle` falls back to `0`
+- Compatible with all existing options (`dither`, `braille`, `width`, `height`)
+
+### Added — New exports
+
+- `animateGradient` — function
+- `AnimateGradientOptions` / `AnimateGradientController` — types
+- `EasingName` — union type of built-in curve names
+- `EasingFn` — `(t: number) => number` curve type
+
+### Notes
+
+- All 1848 + 30 new tests pass.
+- Backwards-compatible: existing `gradient()` calls work identically.
+- No new runtime dependencies.
+- Phase 2 of the [roadmap](README.md#%EF%B8%8F-roadmap) is now **fully complete**.
+
+---
+
 ## [1.1.2] — maturity & robustness
 
 Patch release focused on maturity: better error semantics, defensive
@@ -321,4 +423,4 @@ Hierarchical text renderer inspired by Rich's `Tree`.
 - TypeScript types exported.
 - Adaptive color rendering (NO_COLOR / FORCE_COLOR / TTY detection).
 - AbortSignal support across all blocking APIs.
-- 750+ tests, 85%+ coverage.
+- 750+ tests, 85%+ coverage.

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.1.2-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.0-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)
@@ -202,6 +202,53 @@ console.log(gradient('fuego a océano', ['#ff6b6b', '#feca57', '#48dbfb']));
 console.log(rainbow('preset rainbow integrado'));
 ```
 
+### Gradientes animados (v1.2.0)
+
+```ts
+import { animateGradient, sleep } from 'ansimax';
+
+// Animación de flujo de color — corre hasta llamar stop()
+const ctrl = animateGradient('Cargando...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
+  duration: 2000,    // ms por ciclo
+  fps: 30,
+  direction: 'forward',  // o 'reverse'
+});
+
+await sleep(3000);
+ctrl.stop();
+```
+
+### Curvas de interpolación (v1.2.0)
+
+```ts
+import { gradient } from 'ansimax';
+
+// Cinco easings built-in + soporte para funciones personalizadas
+gradient('hola mundo', stops, { easing: 'linear' });
+gradient('hola mundo', stops, { easing: 'ease-in' });
+gradient('hola mundo', stops, { easing: 'ease-out' });
+gradient('hola mundo', stops, { easing: 'ease-in-out' });
+gradient('hola mundo', stops, { easing: 'cubic-bezier' });
+
+// O tu propia función de easing (t → t suavizado, ambos en [0,1])
+gradient('hola mundo', stops, { easing: (t) => t * t * t });
+```
+
+### Gradientes cónicos (v1.2.0)
+
+```ts
+import { gradientRect } from 'ansimax';
+
+// Barrido radial alrededor del centro — rueda arcoíris
+console.log(gradientRect({
+  width: 30, height: 15,
+  colors: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff00ff', '#ff0000'],
+  style: 'conic',
+  startAngle: 0,   // ángulo de rotación en grados
+  dither: 'bayer',
+}));
+```
+
 ### ASCII Art
 
 <img src="media/ascii_art.png" alt="ASCII art" />
@@ -277,7 +324,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.1.2'));
+console.log(components.badge('VERSION', 'v1.2.0'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -487,9 +534,9 @@ El roadmap apunta intencionalmente — y busca superar — gaps que ni siquiera
 - [x] Gradientes a ángulo arbitrario
 - [x] Dithering Bayer 4×4 para transiciones tonales suaves
 - [x] UX single-stop (comportamiento estilo CSS)
-- [ ] **Gradientes animados** (flujo de color en el tiempo, loops infinitos)
-- [ ] **Curvas de interpolación** (linear / ease-in / ease-out / cubic-bezier)
-- [ ] **Gradientes cónicos** (barrido radial)
+- [x] **Gradientes animados** — flujo de color en el tiempo con `animateGradient()` (v1.2.0)
+- [x] **Curvas de interpolación** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / personalizado (v1.2.0)
+- [x] **Gradientes cónicos** — barrido radial con `style: 'conic'` (v1.2.0)
 
 ### 🟡 Fase 3 — Motor ASCII
 - [x] Fuentes de bloque (`big`, `small`)
@@ -679,6 +726,24 @@ ansimax/
 
 ## 📝 Changelog
 
+### 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:
+
+- 🌊 **`animateGradient()`** — flujo de color en el tiempo con ciclo de vida apropiado (Promise, signal, fps, direction)
+- 📐 **Curvas de interpolación** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / funciones personalizadas
+- ⭕ **Gradientes cónicos** — `gradientRect({ style: 'conic', startAngle })` para barridos radiales
+
+```ts
+import { animateGradient } from 'ansimax';
+
+const ctrl = animateGradient('Cargando...', ['#ff79c6', '#bd93f9', '#8be9fd']);
+await sleep(3000);
+ctrl.stop();
+```
+
+Totalmente retrocompatible — todo programa 1.1.x corre idénticamente.
+
 ### v1.1.2 — Madurez y robustez
 
 Release patch enfocado en refinamientos de calidad — sin cambios en la API.
@@ -795,4 +860,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.1.2-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.0-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)
@@ -202,6 +202,53 @@ console.log(gradient('fire to ocean', ['#ff6b6b', '#feca57', '#48dbfb']));
 console.log(rainbow('built-in rainbow preset'));
 ```
 
+### Animated Gradients (v1.2.0)
+
+```ts
+import { animateGradient, sleep } from 'ansimax';
+
+// Color flow animation — runs until you call stop()
+const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
+  duration: 2000,    // ms per cycle
+  fps: 30,
+  direction: 'forward',  // or 'reverse'
+});
+
+await sleep(3000);
+ctrl.stop();
+```
+
+### Easing Curves (v1.2.0)
+
+```ts
+import { gradient } from 'ansimax';
+
+// Five built-in easings + custom function support
+gradient('hello world', stops, { easing: 'linear' });
+gradient('hello world', stops, { easing: 'ease-in' });
+gradient('hello world', stops, { easing: 'ease-out' });
+gradient('hello world', stops, { easing: 'ease-in-out' });
+gradient('hello world', stops, { easing: 'cubic-bezier' });
+
+// Or pass your own easing function (t → eased t, both in [0,1])
+gradient('hello world', stops, { easing: (t) => t * t * t });
+```
+
+### Conic Gradients (v1.2.0)
+
+```ts
+import { gradientRect } from 'ansimax';
+
+// Radial sweep around center — rainbow wheel
+console.log(gradientRect({
+  width: 30, height: 15,
+  colors: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff00ff', '#ff0000'],
+  style: 'conic',
+  startAngle: 0,   // rotation angle in degrees
+  dither: 'bayer',
+}));
+```
+
 ### ASCII Art
 
 <img src="media/ascii_art.png" alt="ASCII art" />
@@ -277,7 +324,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.1.2'));
+console.log(components.badge('VERSION', 'v1.2.0'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -487,9 +534,9 @@ The roadmap intentionally targets — and aims to surpass — gaps that even mat
 - [x] Arbitrary-angle gradients
 - [x] Bayer 4×4 dithering for smooth tonal transitions
 - [x] Single-stop UX (CSS-style behavior)
-- [ ] **Animated gradients** (color flow over time, infinite loops)
-- [ ] **Gradient interpolation curves** (linear / ease-in / ease-out / cubic-bezier)
-- [ ] **Conic gradients** (radial sweep)
+- [x] **Animated gradients** — color flow over time with `animateGradient()` (v1.2.0)
+- [x] **Gradient interpolation curves** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / custom (v1.2.0)
+- [x] **Conic gradients** — radial sweep with `style: 'conic'` (v1.2.0)
 
 ### 🟡 Phase 3 — ASCII engine
 - [x] Block fonts (`big`, `small`)
@@ -679,6 +726,24 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.0 — Phase 2 complete: animated, eased & conic gradients
+
+Minor release closing the gradient engine roadmap with three powerful features:
+
+- 🌊 **`animateGradient()`** — color flow over time with proper lifecycle (Promise, signal, fps, direction)
+- 📐 **Easing curves** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / custom functions
+- ⭕ **Conic gradients** — `gradientRect({ style: 'conic', startAngle })` for radial sweeps
+
+```ts
+import { animateGradient } from 'ansimax';
+
+const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd']);
+await sleep(3000);
+ctrl.stop();
+```
+
+Fully backwards-compatible — every 1.1.x program runs identically.
+
 ### v1.1.2 — Maturity & robustness
 
 Patch release focused on quality refinements — no API changes.
@@ -795,4 +860,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

@@ -538,13 +538,84 @@ declare const colorLevel: () => ColorLevel;
 /** Clear adaptive escape caches. Call after a color level change. */
 declare const clearColorCache: () => void;
 declare const compose: (...fns: ColorFn[]) => ColorFn;
+/**
+ * Built-in easing curves. Each takes a t in [0, 1] and returns an eased t
+ * in [0, 1]. Used for non-linear gradient progression.
+ */
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'cubic-bezier';
+type EasingFn = (t: number) => number;
 declare const stripAnsi: (str: string) => string;
 interface GradientOptions {
     /** Skip ANSI escapes in the input instead of overwriting them. */
     preserveAnsi?: boolean;
+    /**
+     * Interpolation curve. Default `'linear'`.
+     * - `'linear'` — even color distribution
+     * - `'ease-in'` — slow start, fast end (concentrates colors at the right)
+     * - `'ease-out'` — fast start, slow end (concentrates colors at the left)
+     * - `'ease-in-out'` — slow at both ends, fast in middle
+     * - `'cubic-bezier'` — CSS-style ease (smooth S-curve)
+     * - Or pass a custom `EasingFn` that maps `[0,1] → [0,1]`.
+     */
+    easing?: EasingName | EasingFn;
+    /**
+     * Phase offset in `[0, 1)` — shifts the gradient along the text.
+     * Use with an animation loop to produce a flowing color effect:
+     * `gradient(text, colors, { phase: (Date.now() / 100) % 1 })`
+     */
+    phase?: number;
 }
 declare const gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
 declare const rainbow: ColorFn;
+interface AnimateGradientOptions {
+    /** Total animation duration in ms. Default `2000`. */
+    duration?: number;
+    /** Frames per second. Default `30`. Capped to `60`. */
+    fps?: number;
+    /** Loop infinitely. Default `true`. Use `signal` to stop. */
+    infinite?: boolean;
+    /** Cycle count when `infinite: false`. Default `1`. */
+    cycles?: number;
+    /** Direction: `'forward'` (default) shifts colors right; `'reverse'` shifts left. */
+    direction?: 'forward' | 'reverse';
+    /** Easing curve for the gradient itself (not the time progression). */
+    easing?: EasingName | EasingFn;
+    /** Preserve embedded ANSI escapes. Default `false`. */
+    preserveAnsi?: boolean;
+    /** Abort signal — stops the animation cleanly. */
+    signal?: AbortSignal;
+    /**
+     * Callback fired on every frame with the new colored string.
+     * If omitted, frames are written to stdout via cursor-up redraw.
+     */
+    onFrame?: (frame: string, phase: number) => void;
+}
+/**
+ * Render a gradient that "flows" through the text over time. Returns a
+ * controller with a `.stop()` method. When `infinite: true` (default),
+ * the animation continues until `.stop()` is called or `signal` aborts.
+ *
+ * @example
+ * ```ts
+ * const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd']);
+ * await sleep(3000);
+ * ctrl.stop();
+ * ```
+ *
+ * @example with custom render callback
+ * ```ts
+ * animateGradient('hi', ['#f00', '#0f0'], {
+ *   onFrame: (frame) => myCustomRender(frame),
+ * });
+ * ```
+ */
+interface AnimateGradientController {
+    /** Stops the animation. Safe to call multiple times. */
+    stop: () => void;
+    /** Promise that resolves when animation finishes (stop / abort / cycle limit). */
+    done: Promise<void>;
+}
+declare const animateGradient: (text: string, stops: string[], opts?: AnimateGradientOptions) => AnimateGradientController;
 declare const PRESET_DEFS: {
     readonly sunset: readonly ["#ff6b6b", "#feca57", "#48dbfb"];
     readonly ocean: readonly ["#0575e6", "#021b79"];
@@ -1408,9 +1479,14 @@ interface GradientRectOptions {
     height?: number;
     colors?: string[];
     /** Built-in style. Use `angle` for arbitrary directions. */
-    style?: 'horizontal' | 'vertical' | 'diagonal' | 'radial';
+    style?: 'horizontal' | 'vertical' | 'diagonal' | 'radial' | 'conic';
     /** Custom angle in degrees (0=right, 90=down). Overrides `style`. */
     angle?: number;
+    /**
+     * Starting angle (degrees) for conic gradients. Default `0` (= right of center).
+     * Rotates the radial sweep around the center point.
+     */
+    startAngle?: number;
     /** Dithering algorithm. 'bayer' improves perceived smoothness. */
     dither?: 'none' | 'bayer';
     /** Render in braille mode for 2× horizontal × 4× vertical resolution. */
@@ -1625,4 +1701,4 @@ declare const ansimax: {
     configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-export { type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EraseMode, FG, FRAME_MS, type FadeOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions, type ResizeListener, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions$1 as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, filterTree, findInTree, flipHorizontal, flipVertical, frames, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, hasFont, hexToRgb, hideCursor, images, isHexColor, isNoColor, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, pauseListeners, presetNames, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, rgbTo256, rgbToHex, rotate90, safeJson, screen, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$1 as stripAnsi, stripAnsi$2 as stripAnsiCodes, stripAnsi as stripAnsiColors, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
+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 };

package/dist/index.d.ts

@@ -538,13 +538,84 @@ declare const colorLevel: () => ColorLevel;
 /** Clear adaptive escape caches. Call after a color level change. */
 declare const clearColorCache: () => void;
 declare const compose: (...fns: ColorFn[]) => ColorFn;
+/**
+ * Built-in easing curves. Each takes a t in [0, 1] and returns an eased t
+ * in [0, 1]. Used for non-linear gradient progression.
+ */
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'cubic-bezier';
+type EasingFn = (t: number) => number;
 declare const stripAnsi: (str: string) => string;
 interface GradientOptions {
     /** Skip ANSI escapes in the input instead of overwriting them. */
     preserveAnsi?: boolean;
+    /**
+     * Interpolation curve. Default `'linear'`.
+     * - `'linear'` — even color distribution
+     * - `'ease-in'` — slow start, fast end (concentrates colors at the right)
+     * - `'ease-out'` — fast start, slow end (concentrates colors at the left)
+     * - `'ease-in-out'` — slow at both ends, fast in middle
+     * - `'cubic-bezier'` — CSS-style ease (smooth S-curve)
+     * - Or pass a custom `EasingFn` that maps `[0,1] → [0,1]`.
+     */
+    easing?: EasingName | EasingFn;
+    /**
+     * Phase offset in `[0, 1)` — shifts the gradient along the text.
+     * Use with an animation loop to produce a flowing color effect:
+     * `gradient(text, colors, { phase: (Date.now() / 100) % 1 })`
+     */
+    phase?: number;
 }
 declare const gradient: (text: unknown, stops: string[] | null | undefined, opts?: GradientOptions) => string;
 declare const rainbow: ColorFn;
+interface AnimateGradientOptions {
+    /** Total animation duration in ms. Default `2000`. */
+    duration?: number;
+    /** Frames per second. Default `30`. Capped to `60`. */
+    fps?: number;
+    /** Loop infinitely. Default `true`. Use `signal` to stop. */
+    infinite?: boolean;
+    /** Cycle count when `infinite: false`. Default `1`. */
+    cycles?: number;
+    /** Direction: `'forward'` (default) shifts colors right; `'reverse'` shifts left. */
+    direction?: 'forward' | 'reverse';
+    /** Easing curve for the gradient itself (not the time progression). */
+    easing?: EasingName | EasingFn;
+    /** Preserve embedded ANSI escapes. Default `false`. */
+    preserveAnsi?: boolean;
+    /** Abort signal — stops the animation cleanly. */
+    signal?: AbortSignal;
+    /**
+     * Callback fired on every frame with the new colored string.
+     * If omitted, frames are written to stdout via cursor-up redraw.
+     */
+    onFrame?: (frame: string, phase: number) => void;
+}
+/**
+ * Render a gradient that "flows" through the text over time. Returns a
+ * controller with a `.stop()` method. When `infinite: true` (default),
+ * the animation continues until `.stop()` is called or `signal` aborts.
+ *
+ * @example
+ * ```ts
+ * const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd']);
+ * await sleep(3000);
+ * ctrl.stop();
+ * ```
+ *
+ * @example with custom render callback
+ * ```ts
+ * animateGradient('hi', ['#f00', '#0f0'], {
+ *   onFrame: (frame) => myCustomRender(frame),
+ * });
+ * ```
+ */
+interface AnimateGradientController {
+    /** Stops the animation. Safe to call multiple times. */
+    stop: () => void;
+    /** Promise that resolves when animation finishes (stop / abort / cycle limit). */
+    done: Promise<void>;
+}
+declare const animateGradient: (text: string, stops: string[], opts?: AnimateGradientOptions) => AnimateGradientController;
 declare const PRESET_DEFS: {
     readonly sunset: readonly ["#ff6b6b", "#feca57", "#48dbfb"];
     readonly ocean: readonly ["#0575e6", "#021b79"];
@@ -1408,9 +1479,14 @@ interface GradientRectOptions {
     height?: number;
     colors?: string[];
     /** Built-in style. Use `angle` for arbitrary directions. */
-    style?: 'horizontal' | 'vertical' | 'diagonal' | 'radial';
+    style?: 'horizontal' | 'vertical' | 'diagonal' | 'radial' | 'conic';
     /** Custom angle in degrees (0=right, 90=down). Overrides `style`. */
     angle?: number;
+    /**
+     * Starting angle (degrees) for conic gradients. Default `0` (= right of center).
+     * Rotates the radial sweep around the center point.
+     */
+    startAngle?: number;
     /** Dithering algorithm. 'bayer' improves perceived smoothness. */
     dither?: 'none' | 'bayer';
     /** Render in braille mode for 2× horizontal × 4× vertical resolution. */
@@ -1625,4 +1701,4 @@ declare const ansimax: {
     configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-export { type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EraseMode, FG, FRAME_MS, type FadeOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions, type ResizeListener, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions$1 as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, filterTree, findInTree, flipHorizontal, flipVertical, frames, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, hasFont, hexToRgb, hideCursor, images, isHexColor, isNoColor, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, pauseListeners, presetNames, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, rgbTo256, rgbToHex, rotate90, safeJson, screen, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$1 as stripAnsi, stripAnsi$2 as stripAnsiCodes, stripAnsi as stripAnsiColors, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
+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 };

package/dist/index.js

@@ -46,6 +46,7 @@ __export(index_exports, {
   ST: () => ST,
   STYLE: () => STYLE,
   animate: () => animate,
+  animateGradient: () => animateGradient,
   ascii: () => ascii,
   bell: () => bell,
   bg256: () => bg256,
@@ -1114,6 +1115,37 @@ var compose = (...fns) => (text) => {
   if (opens === "") return s;
   return opens + s + reset();
 };
+var _cubicBezier = (t, x1 = 0.25, y1 = 0.1, x2 = 0.25, y2 = 1) => {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  let s = t;
+  for (let i = 0; i < 8; i++) {
+    const s22 = s * s;
+    const s32 = s22 * s;
+    const oneMinusS = 1 - s;
+    const oneMinusS2 = oneMinusS * oneMinusS;
+    const fx = 3 * oneMinusS2 * s * x1 + 3 * oneMinusS * s22 * x2 + s32 - t;
+    const dfx = 3 * oneMinusS2 * x1 + 6 * oneMinusS * s * (x2 - x1) + 3 * s22 * (1 - x2);
+    if (Math.abs(dfx) < 1e-6) break;
+    s -= fx / dfx;
+    s = Math.min(1, Math.max(0, s));
+  }
+  const s2 = s * s;
+  const s3 = s2 * s;
+  return 3 * (1 - s) * (1 - s) * s * y1 + 3 * (1 - s) * s2 * y2 + s3;
+};
+var EASINGS = {
+  "linear": (t) => t,
+  "ease-in": (t) => t * t,
+  "ease-out": (t) => 1 - (1 - t) * (1 - t),
+  "ease-in-out": (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+  "cubic-bezier": (t) => _cubicBezier(t)
+};
+var resolveEasing = (e) => {
+  if (typeof e === "function") return e;
+  if (typeof e === "string" && EASINGS[e]) return EASINGS[e];
+  return EASINGS.linear;
+};
 var stripAnsi3 = stripAnsi;
 var gradient = (text, stops, opts = {}) => {
   const s = coerceText(text);
@@ -1125,13 +1157,15 @@ var gradient = (text, stops, opts = {}) => {
     const c = colors[0];
     return adaptiveFg(c.r, c.g, c.b) + s + reset();
   }
-  const { preserveAnsi = false } = opts;
+  const { preserveAnsi = false, easing, phase = 0 } = opts;
+  const easingFn = resolveEasing(easing);
+  const phaseN = Number.isFinite(phase) ? (phase % 1 + 1) % 1 : 0;
   if (!preserveAnsi || !s.includes("\x1B")) {
-    return _gradientPlain(s, colors);
+    return _gradientPlain(s, colors, easingFn, phaseN);
   }
-  return _gradientAnsiAware(s, colors);
+  return _gradientAnsiAware(s, colors, easingFn, phaseN);
 };
-var _gradientPlain = (text, colors) => {
+var _gradientPlain = (text, colors, easingFn, phase) => {
   const chars = [...text];
   const visible = chars.filter((c) => c !== " ").length;
   if (visible === 0) return text;
@@ -1144,7 +1178,10 @@ var _gradientPlain = (text, colors) => {
       out += ch;
       continue;
     }
-    const t = visible === 1 ? 0 : colorIdx / visibleMinus;
+    let t = visible === 1 ? 0 : colorIdx / visibleMinus;
+    t = (t + phase) % 1;
+    t = easingFn(t);
+    t = Math.min(1, Math.max(0, t));
     const scaled = t * (colorCount - 1);
     const lo = Math.floor(scaled);
     const hi = Math.min(lo + 1, colorCount - 1);
@@ -1155,7 +1192,7 @@ var _gradientPlain = (text, colors) => {
   return out;
 };
 var ANSI_TOKEN = /\x1b\[[0-9;?]*[a-zA-Z]/y;
-var _gradientAnsiAware = (text, colors) => {
+var _gradientAnsiAware = (text, colors, easingFn, phase) => {
   const visible = stripAnsi3(text).split("").filter((c) => c !== " ").length;
   if (visible === 0) return text;
   let out = "";
@@ -1181,7 +1218,10 @@ var _gradientAnsiAware = (text, colors) => {
     if (ch === " ") {
       out += ch;
     } else {
-      const t = visible === 1 ? 0 : colorIdx / visibleMinus;
+      let t = visible === 1 ? 0 : colorIdx / visibleMinus;
+      t = (t + phase) % 1;
+      t = easingFn(t);
+      t = Math.min(1, Math.max(0, t));
       const scaled = t * (colorCount - 1);
       const lo = Math.floor(scaled);
       const hi = Math.min(lo + 1, colorCount - 1);
@@ -1195,6 +1235,76 @@ var _gradientAnsiAware = (text, colors) => {
 };
 var RAINBOW = ["#ff0000", "#ff7f00", "#ffff00", "#00ff00", "#0000ff", "#8b00ff"];
 var rainbow = (text) => gradient(text, RAINBOW);
+var animateGradient = (text, stops, opts = {}) => {
+  const {
+    duration = 2e3,
+    fps = 30,
+    infinite = true,
+    cycles = 1,
+    direction = "forward",
+    easing,
+    preserveAnsi = false,
+    signal,
+    onFrame
+  } = opts;
+  const safeFps = Math.min(60, Math.max(1, Number.isFinite(fps) ? fps : 30));
+  const safeDuration2 = Math.max(100, Number.isFinite(duration) ? duration : 2e3);
+  const safeCycles = Math.max(1, Number.isFinite(cycles) ? cycles : 1);
+  const frameInterval2 = 1e3 / safeFps;
+  let stopped = false;
+  let timer = null;
+  let resolveDone = (
+    /* istanbul ignore next */
+    () => {
+    }
+  );
+  const done = new Promise((res) => {
+    resolveDone = res;
+  });
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer != null) {
+      clearInterval(timer);
+      timer = null;
+    }
+    resolveDone();
+  };
+  if (signal) {
+    if (signal.aborted) {
+      stop();
+      return { stop, done };
+    }
+    signal.addEventListener("abort", stop, { once: true });
+  }
+  const startTime = Date.now();
+  const renderFrame = () => {
+    if (stopped) return;
+    const elapsed = Date.now() - startTime;
+    let phase = elapsed / safeDuration2 % 1;
+    if (direction === "reverse") phase = 1 - phase;
+    const frame = gradient(text, stops, { preserveAnsi, easing, phase });
+    if (onFrame) {
+      onFrame(frame, phase);
+    } else {
+      try {
+        process.stdout.write("\r" + frame);
+      } catch {
+      }
+    }
+    if (!infinite) {
+      const completedCycles = Math.floor(elapsed / safeDuration2);
+      if (completedCycles >= safeCycles) {
+        stop();
+      }
+    }
+  };
+  renderFrame();
+  if (!stopped) {
+    timer = setInterval(renderFrame, frameInterval2);
+  }
+  return { stop, done };
+};
 var PRESET_DEFS = {
   sunset: ["#ff6b6b", "#feca57", "#48dbfb"],
   ocean: ["#0575e6", "#021b79"],
@@ -4833,6 +4943,7 @@ var gradientRect = (opts = {}) => {
     colors = ["#ff0000", "#0000ff"],
     style = "horizontal",
     angle,
+    startAngle = 0,
     dither = "none",
     braille = false
   } = opts;
@@ -4871,7 +4982,15 @@ var gradientRect = (opts = {}) => {
       } else if (style === "horizontal") t = col / (safeW - 1);
       else if (style === "vertical") t = row / (safeH - 1);
       else if (style === "diagonal") t = (col + row) / (safeW + safeH - 2);
-      else {
+      else if (style === "conic") {
+        const cx = safeW / 2, cy = safeH / 2;
+        const dx = col - cx;
+        const dy = row - cy;
+        const startRad = (Number.isFinite(startAngle) ? startAngle : 0) * Math.PI / 180;
+        let angleRad = Math.atan2(dy, dx) - startRad;
+        angleRad = (angleRad % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);
+        t = angleRad / (2 * Math.PI);
+      } else {
         const cx = safeW / 2, cy = safeH / 2;
         const dx = (col - cx) / cx;
         const dy = (row - cy) / cy;
@@ -5323,6 +5442,7 @@ var index_default = ansimax;
   ST,
   STYLE,
   animate,
+  animateGradient,
   ascii,
   bell,
   bg256,

package/dist/index.mjs

@@ -942,6 +942,37 @@ var compose = (...fns) => (text) => {
   if (opens === "") return s;
   return opens + s + reset();
 };
+var _cubicBezier = (t, x1 = 0.25, y1 = 0.1, x2 = 0.25, y2 = 1) => {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  let s = t;
+  for (let i = 0; i < 8; i++) {
+    const s22 = s * s;
+    const s32 = s22 * s;
+    const oneMinusS = 1 - s;
+    const oneMinusS2 = oneMinusS * oneMinusS;
+    const fx = 3 * oneMinusS2 * s * x1 + 3 * oneMinusS * s22 * x2 + s32 - t;
+    const dfx = 3 * oneMinusS2 * x1 + 6 * oneMinusS * s * (x2 - x1) + 3 * s22 * (1 - x2);
+    if (Math.abs(dfx) < 1e-6) break;
+    s -= fx / dfx;
+    s = Math.min(1, Math.max(0, s));
+  }
+  const s2 = s * s;
+  const s3 = s2 * s;
+  return 3 * (1 - s) * (1 - s) * s * y1 + 3 * (1 - s) * s2 * y2 + s3;
+};
+var EASINGS = {
+  "linear": (t) => t,
+  "ease-in": (t) => t * t,
+  "ease-out": (t) => 1 - (1 - t) * (1 - t),
+  "ease-in-out": (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+  "cubic-bezier": (t) => _cubicBezier(t)
+};
+var resolveEasing = (e) => {
+  if (typeof e === "function") return e;
+  if (typeof e === "string" && EASINGS[e]) return EASINGS[e];
+  return EASINGS.linear;
+};
 var stripAnsi3 = stripAnsi;
 var gradient = (text, stops, opts = {}) => {
   const s = coerceText(text);
@@ -953,13 +984,15 @@ var gradient = (text, stops, opts = {}) => {
     const c = colors[0];
     return adaptiveFg(c.r, c.g, c.b) + s + reset();
   }
-  const { preserveAnsi = false } = opts;
+  const { preserveAnsi = false, easing, phase = 0 } = opts;
+  const easingFn = resolveEasing(easing);
+  const phaseN = Number.isFinite(phase) ? (phase % 1 + 1) % 1 : 0;
   if (!preserveAnsi || !s.includes("\x1B")) {
-    return _gradientPlain(s, colors);
+    return _gradientPlain(s, colors, easingFn, phaseN);
   }
-  return _gradientAnsiAware(s, colors);
+  return _gradientAnsiAware(s, colors, easingFn, phaseN);
 };
-var _gradientPlain = (text, colors) => {
+var _gradientPlain = (text, colors, easingFn, phase) => {
   const chars = [...text];
   const visible = chars.filter((c) => c !== " ").length;
   if (visible === 0) return text;
@@ -972,7 +1005,10 @@ var _gradientPlain = (text, colors) => {
       out += ch;
       continue;
     }
-    const t = visible === 1 ? 0 : colorIdx / visibleMinus;
+    let t = visible === 1 ? 0 : colorIdx / visibleMinus;
+    t = (t + phase) % 1;
+    t = easingFn(t);
+    t = Math.min(1, Math.max(0, t));
     const scaled = t * (colorCount - 1);
     const lo = Math.floor(scaled);
     const hi = Math.min(lo + 1, colorCount - 1);
@@ -983,7 +1019,7 @@ var _gradientPlain = (text, colors) => {
   return out;
 };
 var ANSI_TOKEN = /\x1b\[[0-9;?]*[a-zA-Z]/y;
-var _gradientAnsiAware = (text, colors) => {
+var _gradientAnsiAware = (text, colors, easingFn, phase) => {
   const visible = stripAnsi3(text).split("").filter((c) => c !== " ").length;
   if (visible === 0) return text;
   let out = "";
@@ -1009,7 +1045,10 @@ var _gradientAnsiAware = (text, colors) => {
     if (ch === " ") {
       out += ch;
     } else {
-      const t = visible === 1 ? 0 : colorIdx / visibleMinus;
+      let t = visible === 1 ? 0 : colorIdx / visibleMinus;
+      t = (t + phase) % 1;
+      t = easingFn(t);
+      t = Math.min(1, Math.max(0, t));
       const scaled = t * (colorCount - 1);
       const lo = Math.floor(scaled);
       const hi = Math.min(lo + 1, colorCount - 1);
@@ -1023,6 +1062,76 @@ var _gradientAnsiAware = (text, colors) => {
 };
 var RAINBOW = ["#ff0000", "#ff7f00", "#ffff00", "#00ff00", "#0000ff", "#8b00ff"];
 var rainbow = (text) => gradient(text, RAINBOW);
+var animateGradient = (text, stops, opts = {}) => {
+  const {
+    duration = 2e3,
+    fps = 30,
+    infinite = true,
+    cycles = 1,
+    direction = "forward",
+    easing,
+    preserveAnsi = false,
+    signal,
+    onFrame
+  } = opts;
+  const safeFps = Math.min(60, Math.max(1, Number.isFinite(fps) ? fps : 30));
+  const safeDuration2 = Math.max(100, Number.isFinite(duration) ? duration : 2e3);
+  const safeCycles = Math.max(1, Number.isFinite(cycles) ? cycles : 1);
+  const frameInterval2 = 1e3 / safeFps;
+  let stopped = false;
+  let timer = null;
+  let resolveDone = (
+    /* istanbul ignore next */
+    () => {
+    }
+  );
+  const done = new Promise((res) => {
+    resolveDone = res;
+  });
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer != null) {
+      clearInterval(timer);
+      timer = null;
+    }
+    resolveDone();
+  };
+  if (signal) {
+    if (signal.aborted) {
+      stop();
+      return { stop, done };
+    }
+    signal.addEventListener("abort", stop, { once: true });
+  }
+  const startTime = Date.now();
+  const renderFrame = () => {
+    if (stopped) return;
+    const elapsed = Date.now() - startTime;
+    let phase = elapsed / safeDuration2 % 1;
+    if (direction === "reverse") phase = 1 - phase;
+    const frame = gradient(text, stops, { preserveAnsi, easing, phase });
+    if (onFrame) {
+      onFrame(frame, phase);
+    } else {
+      try {
+        process.stdout.write("\r" + frame);
+      } catch {
+      }
+    }
+    if (!infinite) {
+      const completedCycles = Math.floor(elapsed / safeDuration2);
+      if (completedCycles >= safeCycles) {
+        stop();
+      }
+    }
+  };
+  renderFrame();
+  if (!stopped) {
+    timer = setInterval(renderFrame, frameInterval2);
+  }
+  return { stop, done };
+};
 var PRESET_DEFS = {
   sunset: ["#ff6b6b", "#feca57", "#48dbfb"],
   ocean: ["#0575e6", "#021b79"],
@@ -4661,6 +4770,7 @@ var gradientRect = (opts = {}) => {
     colors = ["#ff0000", "#0000ff"],
     style = "horizontal",
     angle,
+    startAngle = 0,
     dither = "none",
     braille = false
   } = opts;
@@ -4699,7 +4809,15 @@ var gradientRect = (opts = {}) => {
       } else if (style === "horizontal") t = col / (safeW - 1);
       else if (style === "vertical") t = row / (safeH - 1);
       else if (style === "diagonal") t = (col + row) / (safeW + safeH - 2);
-      else {
+      else if (style === "conic") {
+        const cx = safeW / 2, cy = safeH / 2;
+        const dx = col - cx;
+        const dy = row - cy;
+        const startRad = (Number.isFinite(startAngle) ? startAngle : 0) * Math.PI / 180;
+        let angleRad = Math.atan2(dy, dx) - startRad;
+        angleRad = (angleRad % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);
+        t = angleRad / (2 * Math.PI);
+      } else {
         const cx = safeW / 2, cy = safeH / 2;
         const dx = (col - cx) / cx;
         const dy = (row - cy) / cy;
@@ -5150,6 +5268,7 @@ export {
   ST,
   STYLE,
   animate,
+  animateGradient,
   ascii,
   bell,
   bg256,

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.1.2'),
+    components.badge('VERSION', 'v1.2.0'),
     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.1.2'),
+  components.badge('VERSION', 'v1.2.0'),
   components.badge('BUILD', 'passing'),
   components.badge('LICENSE', 'Apache 2.0'));
 console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ansimax",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "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",