ansimax 1.1.1 → 1.2.0

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.1-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)
@@ -50,14 +50,14 @@ npm install ansimax
 ```
 
 ```ts
-import { color, gradient, ascii, loader } from 'ansimax';
+import { color, gradient, ascii, loader, sleep } from 'ansimax';
 
 console.log(ascii.banner('hello', {
   colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
 }));
 
 const stop = loader.spin('Building project', { color: '#bd93f9' });
-await someAsyncWork();
+await sleep(1500);
 stop('Build complete', true);
 ```
 
@@ -123,14 +123,14 @@ yarn add ansimax
 ## ⚡ 30-second example
 
 ```ts
-import { color, gradient, loader, ascii } from 'ansimax';
+import { color, gradient, loader, ascii, sleep } from 'ansimax';
 
 console.log(ascii.banner('deploy', {
   colorFn: (t) => gradient(t, ['#ff6b6b', '#feca57', '#48dbfb']),
 }));
 
 const stop = loader.spin('Building project', { color: '#bd93f9' });
-await someAsyncWork();
+await sleep(1500);             // simulate async work
 stop('Build complete', true);  // ✓ + success color
 
 console.log(color.green('✓') + ' Ready in ' + color.bold('1.4s'));
@@ -187,12 +187,66 @@ console.log(themes.primary('cyberpunk primary'));
 <img src="media/colors.png" alt="Colors and gradients" />
 
 ```ts
-import { color, gradient } from 'ansimax';
+import { color, gradient, rainbow } from 'ansimax';
 
-color.red('red');   color.green('green');  color.blue('blue');
-color.bold(text);   color.italic(text);    color.underline(text);
-gradient('fire to ocean', ['#ff6b6b', '#feca57', '#48dbfb']);
-color.rainbow('built-in rainbow preset');
+// Basic colors
+console.log(color.red('red'), color.green('green'), color.blue('blue'));
+
+// Style modifiers
+console.log(color.bold('bold'), color.italic('italic'), color.underline('underlined'));
+
+// Multi-stop gradient
+console.log(gradient('fire to ocean', ['#ff6b6b', '#feca57', '#48dbfb']));
+
+// Built-in rainbow preset
+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
@@ -202,13 +256,13 @@ color.rainbow('built-in rainbow preset');
 ```ts
 import { ascii, gradient } from 'ansimax';
 
-ascii.banner('HELLO', {
+console.log(ascii.banner('HELLO', {
   font: 'big',
   align: 'center',
   colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9']),
-});
+}));
 
-ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' });
+console.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));
 ```
 
 ### Trees
@@ -235,7 +289,7 @@ console.log(project.render({
 <img src="media/pixel_art.png" alt="Pixel art" />
 
 ```ts
-import { images, createCanvas, gradientRect } from 'ansimax';
+import { images, createCanvas, gradientRect, SPRITES } from 'ansimax';
 
 // Built-in sprite
 console.log(images.sprite('heart'));
@@ -251,7 +305,8 @@ console.log(gradientRect({
 const c = createCanvas(40, 10);
 c.fill({ r: 18, g: 18, b: 38 });
 c.drawCircle(20, 5, 4, { r: 255, g: 200, b: 0 }, true);
-c.drawSprite(2, 2, images.sprites.star!.pixels);
+const starSprite = SPRITES.star;
+if (starSprite) c.drawSprite(2, 2, starSprite.pixels);
 c.print();
 ```
 
@@ -262,15 +317,15 @@ c.print();
 ```ts
 import { components, color } from 'ansimax';
 
-components.table([
+console.log(components.table([
   ['Module',     'Status',                'Coverage'],
   ['colors',     color.green('● ready'),  '100%'],
   ['animations', color.green('● ready'),  '100%'],
   ['loaders',    color.green('● ready'),  '100%'],
-], { borderStyle: 'rounded' });
+], { borderStyle: 'rounded' }));
 
-components.badge('VERSION', 'v1.1.1');
-components.badge('BUILD',   'passing');
+console.log(components.badge('VERSION', 'v1.2.0'));
+console.log(components.badge('BUILD',   'passing'));
 ```
 
 ### Timeline
@@ -278,22 +333,24 @@ components.badge('BUILD',   'passing');
 <img src="media/timeline.png" alt="Timeline" />
 
 ```ts
-components.timeline([
+import { components } from 'ansimax';
+
+console.log(components.timeline([
   { label: 'Project init',   done: true,  time: '10:00' },
   { label: 'Build pipeline', done: true,  time: '10:15' },
   { label: 'Run tests',      done: false, time: '10:32' },
   { label: 'Deploy to npm',  done: false },
-]);
+]));
 ```
 
 ### Loaders & Progress
 
 ```ts
-import { loader } from 'ansimax';
+import { loader, sleep } from 'ansimax';
 
 // Spinner with success/failure
 const stop = loader.spin('Loading...', { color: '#bd93f9' });
-await work();
+await sleep(1500);
 stop('Done!', true);   // ✓ green icon
 
 // Animated progress bar
@@ -303,18 +360,22 @@ await loader.progressAnimate(100, 'Downloading', {
 
 // Hierarchical tasks with parallel execution
 await loader.tasks([
-  { text: 'Build', fn: async () => build(), subtasks: [
-    { text: 'TypeScript', fn: async () => tsc() },
-    { text: 'Bundle',     fn: async () => bundle() },
-  ]},
-  { text: 'Test',  fn: async () => test() },
+  {
+    text: 'Build',
+    fn: async () => await sleep(500),
+    subtasks: [
+      { text: 'TypeScript', fn: async () => await sleep(800) },
+      { text: 'Bundle',     fn: async () => await sleep(600) },
+    ],
+  },
+  { text: 'Test', fn: async () => await sleep(700) },
 ], { parallel: true });
 ```
 
 ### Animations
 
 ```ts
-import { animate, gradient } from 'ansimax';
+import { animate, gradient, sleep } from 'ansimax';
 
 await animate.typewriter('Welcome to the deployment wizard...', {
   speed: 30,
@@ -325,9 +386,9 @@ await animate.fadeIn('Loading complete', { duration: 600 });
 
 // Race steps against a timeout — never hang
 await animate.parallel([
-  async () => await checkNetwork(),
-  async () => await checkDatabase(),
-  async () => await checkAuth(),
+  async () => await sleep(500),   // simulated network check
+  async () => await sleep(700),   // simulated database check
+  async () => await sleep(400),   // simulated auth check
 ], { timeout: 5000 });
 ```
 
@@ -340,7 +401,7 @@ import { themes, createTheme } from 'ansimax';
 
 // Built-in themes
 themes.use('dracula');
-themes.primary('hello');
+console.log(themes.primary('hello'));
 
 // Listen for changes
 const off = themes.onChange((newTheme, oldTheme) => {
@@ -350,7 +411,27 @@ const off = themes.onChange((newTheme, oldTheme) => {
 // Multi-tenant: each instance fully isolated
 const tenantA = createTheme('nord');
 const tenantB = createTheme('matrix');
-tenantA.register('custom', myDef);  // doesn't leak to tenantB
+
+// Define a custom theme and register it ONLY in tenantA
+tenantA.register('custom', {
+  name: 'Custom',
+  primary:   '#ff5e5e',
+  secondary: '#5e5eff',
+  accent:    '#5eff5e',
+  success:   '#10b981',
+  warning:   '#fbbf24',
+  error:     '#ef4444',
+  info:      '#06b6d4',
+  muted:     '#6b7280',
+  bg:        '#1e293b',
+  surface:   '#334155',
+  text:      '#f1f5f9',
+  gradient:  ['#ff5e5e', '#5eff5e', '#5e5eff'],
+});
+
+console.log('tenantA themes include custom?', tenantA.list().includes('custom'));
+console.log('tenantB themes include custom?', tenantB.list().includes('custom'));
+//                                            ↑ false — full isolation
 ```
 
 ---
@@ -421,11 +502,11 @@ const off = onConfigKeyChange('theme', (newTheme, oldTheme) => {
 
 // Temporary override + auto-restore on completion or throw
 await withConfig({ animationSpeed: 'fast' }, async () => {
-  await runDemo();
+  // ...your fast-mode code here...
 });
 
 // Strict mode catches config typos
-configure({ unknwnKey: 'x' }, { strict: true });  // throws RangeError
+// configure({ unknwnKey: 'x' }, { strict: true });  // throws RangeError
 ```
 
 ---
@@ -453,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`)
@@ -645,6 +726,35 @@ 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.
+
+- 🛡️ **`process.setMaxListeners` defensive bump** — prevents `MaxListenersExceededWarning` in HMR / nodemon / ts-node-dev setups where ansimax modules re-register cursor-restore handlers
+- 🧪 **Uniform `TypeError` for theme validation** — `themes.register()` now consistently throws `TypeError` for structural / type errors (was a mix of `Error` and `TypeError`)
+- 🎯 **`themes.use()` throws `RangeError`** for unknown theme names (was `Error`) — better semantic match for "value out of allowed set"
+- 📝 **Cleaner barrel re-exports** — header comment now documents legacy aliases and recommends canonical names
+
+Drop-in replacement for `1.1.1`.
+
 ### v1.1.1 — Bug fixes + cleaner examples
 
 Patch release fixing two bugs from real-world v1.1.0 testing, plus a refreshed examples folder.
@@ -750,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 };