ansimax 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -3,6 +3,68 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [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.2-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,26 +216,37 @@ 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';
 
+const stops = ['#ff79c6', '#bd93f9', '#8be9fd'];
+
 // 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' });
+console.log(gradient('hola mundo', stops, { easing: 'linear' }));
+console.log(gradient('hola mundo', stops, { easing: 'ease-in' }));
+console.log(gradient('hola mundo', stops, { easing: 'ease-out' }));
+console.log(gradient('hola mundo', stops, { easing: 'ease-in-out' }));
+console.log(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 });
+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';
 
@@ -324,7 +335,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.2'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -726,6 +737,18 @@ ansimax/
 
 ## 📝 Changelog
 
+### 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:

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.2-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,26 +216,37 @@ 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)
 
+<img src="media/easing_curves.png" alt="Colors and gradients" />
+
 ```ts
 import { gradient } from 'ansimax';
 
+const stops = ['#ff79c6', '#bd93f9', '#8be9fd'];
+
 // 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' });
+console.log(gradient('hello world', stops, { easing: 'linear' }));
+console.log(gradient('hello world', stops, { easing: 'ease-in' }));
+console.log(gradient('hello world', stops, { easing: 'ease-out' }));
+console.log(gradient('hello world', stops, { easing: 'ease-in-out' }));
+console.log(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 });
+console.log(gradient('hello world', stops, { easing: (t) => t * t * t }));
 ```
 
 ### Conic Gradients (v1.2.0)
 
+<img src="media/conic_gradients.png" alt="Colors and gradients" />
+
 ```ts
 import { gradientRect } from 'ansimax';
 
@@ -324,7 +335,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.2'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -726,6 +737,18 @@ ansimax/
 
 ## 📝 Changelog
 
+### 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:

package/dist/index.d.mts

@@ -565,6 +565,38 @@ 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;
 declare const rainbow: ColorFn;
 interface AnimateGradientOptions {
@@ -614,6 +646,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: {

package/dist/index.d.ts

@@ -565,6 +565,38 @@ 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;
 declare const rainbow: ColorFn;
 interface AnimateGradientOptions {
@@ -614,6 +646,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: {

package/dist/index.js

@@ -1273,7 +1273,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 +1294,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 +1311,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 +4237,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 +4587,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(", ")}`
       );
     }

package/dist/index.mjs

@@ -1100,7 +1100,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 +1121,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 +1138,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 +4064,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 +4414,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(", ")}`
       );
     }

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

package/package.json

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