ansimax 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -3,6 +3,201 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.5] — Phase 3 closure: image-to-ASCII engine
+
+Minor release closing the **ASCII engine roadmap (Phase 3)** with five
+new capabilities. All additions are fully backwards-compatible — existing
+code runs identically.
+
+### Added — `ascii.fromImage(pixels, opts)` — image-to-ASCII converter
+
+Convert a `PixelGrid` (from `ansimax.images`) into ASCII art. Five
+features in one call:
+
+```ts
+import { ascii } from 'ansimax';
+
+console.log(ascii.fromImage(pixels, {
+  width: 80,
+  ramp: 'detailed',          // 'standard' | 'detailed' | 'blocks' | 'simple' | custom string
+  invert: false,
+  dither: 'floyd-steinberg', // 'none' | 'floyd-steinberg'
+  edgeDetect: 'sobel',       // 'none' | 'sobel'
+  edgeThreshold: 40,
+  color: true,               // preserve source colors
+  faceMode: false,           // histogram stretch for portraits
+}));
+```
+
+**Aspect-ratio aware**: terminal cells are ~2× as tall as wide, so the
+output height is auto-halved to maintain visual proportion (override
+with `height`).
+
+**Zero-dependency**: input is a `PixelGrid` (one Pixel per cell). Users
+of `sharp`, `jimp`, or any decoder convert their output to `PixelGrid`
+once, then call `ascii.fromImage()`.
+
+### Added — `ASCII_RAMPS` — pre-built character ramps
+
+Four curated character ramps, ordered dark → light, exported as a
+read-only object:
+
+```ts
+ASCII_RAMPS.standard   // ' .:-=+*#%@'           — balanced 10-char (default)
+ASCII_RAMPS.detailed   // 70-char Paul Bourke    — max detail
+ASCII_RAMPS.blocks     // ' ░▒▓█'                — looks like a real photo
+ASCII_RAMPS.simple     // ' .+#'                 — minimal 4-char
+```
+
+Or pass any custom string as the `ramp` option for full control.
+
+### Added — Sobel edge detection
+
+Set `edgeDetect: 'sobel'` to render edges instead of luminance. Useful
+for line-art effects or technical diagrams:
+
+```ts
+console.log(ascii.fromImage(pixels, {
+  width: 100,
+  edgeDetect: 'sobel',
+  edgeThreshold: 50,    // tune for noise/detail balance
+  ramp: 'blocks',
+}));
+```
+
+### Added — Floyd-Steinberg dithering
+
+Set `dither: 'floyd-steinberg'` for error-diffusion dithering. Produces
+smoother tonal gradients in photos. Most useful with shorter ramps:
+
+```ts
+ascii.fromImage(pixels, {
+  width: 80,
+  ramp: 'simple',
+  dither: 'floyd-steinberg',
+});
+```
+
+### Added — Face mode
+
+Set `faceMode: true` to apply histogram stretching ([10%, 90%] percentile
+remap to [0, 255]). Boosts midtone contrast where facial features live,
+producing better results on portraits:
+
+```ts
+ascii.fromImage(portraitPixels, {
+  width: 60,
+  ramp: 'detailed',
+  faceMode: true,
+});
+```
+
+### Added — Figlet (.flf) font support
+
+Parse and render with community FIGfonts (250+ available at
+[figlet.org](http://www.figlet.org/fontdb.cgi)):
+
+```ts
+import { readFileSync } from 'node:fs';
+import { parseFiglet, ascii } from 'ansimax';
+
+const fontStr = readFileSync('./standard.flf', 'utf8');
+const font = parseFiglet(fontStr);
+
+console.log(ascii.figletText('Hello!', font, {
+  trim: true,
+  colorFn: (t) => t,  // optional colorize
+}));
+```
+
+Returns a `FigletFont` object containing the parsed glyphs. Renders
+ASCII 32-126; unknown chars fall back to space.
+
+### Added — Type exports
+
+`AsciiRamp`, `FromImageOptions`, `FigletFont`, `FigletOptions` — all
+exported from the main barrel.
+
+### Notes
+
+- Phase 3 of the [roadmap](README.md#%EF%B8%8F-roadmap) is now **fully complete**.
+- Image decoding (PNG/JPEG → PixelGrid) is intentionally **not** included;
+  users pair ansimax with `sharp`/`jimp`/`pngjs` to keep zero deps.
+- 1914 + 30 new tests pass.
+- No new runtime dependencies — still zero.
+
+---
+
+## [1.2.4] — Gradient utilities + inspectability
+
+Patch release adding gradient inspection and manipulation utilities.
+No breaking changes — `createGradient()` callers from 1.2.3 continue
+to work, but now have access to metadata.
+
+### Added — `ReusableGradient` metadata
+
+`createGradient()` now returns a `ReusableGradient` — still callable
+like before, but with frozen metadata for inspection and debugging:
+
+```ts
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c'], {
+  easing: 'ease-in',
+});
+
+// All still callable
+console.log(fire('hello'));
+
+// New: read-only inspection
+fire.stops;            // → ['#ff5555', '#ffb86c', '#f1fa8c']
+fire.resolvedStops;    // → [{r:255,g:85,b:85}, {r:255,g:184,b:108}, ...]
+fire.defaultOptions;   // → { easing: 'ease-in' }
+```
+
+All three properties are frozen — attempting to mutate them throws in
+strict mode and silently fails in sloppy mode.
+
+### Added — `reverseGradient()` helper
+
+Returns a new gradient with stops in reverse order. Works with both
+plain arrays and `ReusableGradient` instances. Default options are
+preserved when reversing a `ReusableGradient`:
+
+```ts
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+const ice  = reverseGradient(fire);  // → '#f1fa8c' → '#ffb86c' → '#ff5555'
+
+console.log(fire('warm side'));
+console.log(ice('cool side'));
+
+// Also works with plain arrays
+reverseGradient(['#f00', '#0f0', '#00f']);  // → ['#00f', '#0f0', '#f00']
+```
+
+The original array / gradient is never mutated.
+
+### Added — `presets` alias (canonical name)
+
+Previously `presets` was exported only as `colorPresets`. Many users
+referenced `presets` based on docs and got `ReferenceError`. Now both
+names point to the same object:
+
+```ts
+import { presets, colorPresets } from 'ansimax';
+
+presets === colorPresets;  // → true
+```
+
+`colorPresets` remains for backwards compatibility; new code can use
+either name.
+
+### Notes
+
+- Coverage holds steady at ~98%.
+- No new runtime dependencies — still zero.
+- All 1892 + 22 new tests pass.
+
+---
+
 ## [1.2.3] — Gradient factory + performance
 
 Patch release adding a new performance-oriented API and refinements. No

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.3-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.5-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)
@@ -263,7 +263,7 @@ console.log(gradientRect({
 ### Gradientes reusables (v1.2.3)
 
 ```ts
-import { createGradient, ascii } from 'ansimax';
+import { createGradient, reverseGradient, ascii } from 'ansimax';
 
 // Pre-resuelve los stops de hex una vez — significativamente más rápido para uso repetido
 const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
@@ -275,6 +275,14 @@ console.log(fire('Tercera línea'));
 // Úsalo como colorFn para banners — misma firma de ColorFn
 console.log(ascii.banner('FIRE', { colorFn: fire }));
 
+// v1.2.4: inspecciona metadata
+console.log('Stops:', fire.stops);             // → ['#ff5555', '#ffb86c', '#f1fa8c']
+console.log('Resolved:', fire.resolvedStops);  // → [{r:255,g:85,b:85}, ...]
+
+// v1.2.4: invierte un gradiente (preserva las opciones por defecto)
+const ice = reverseGradient(fire);
+console.log(ice('Lado frío'));
+
 // Las opciones por-llamada aún funcionan — perfecto para animación
 for (let p = 0; p < 1; p += 0.05) {
   process.stdout.write('\r' + fire('fluyendo', { phase: p }));
@@ -298,6 +306,60 @@ console.log(ascii.banner('HOLA', {
 console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }));
 ```
 
+### Imagen → ASCII (v1.2.5)
+
+```ts
+import { ascii } from 'ansimax';
+import type { PixelGrid } from 'ansimax';
+
+// Obtén un PixelGrid de cualquier librería de imágenes (sharp, jimp, pngjs, etc.)
+// Cada Pixel es `{ r, g, b }` o null
+const pixels: PixelGrid = await loadImagePixels('./foto.png');
+
+// Monocromo
+console.log(ascii.fromImage(pixels, { width: 80 }));
+
+// Color + dithering Floyd-Steinberg + ramp detallado
+console.log(ascii.fromImage(pixels, {
+  width: 100,
+  color: true,
+  dither: 'floyd-steinberg',
+  ramp: 'detailed',
+}));
+
+// Modo detección de bordes (line art)
+console.log(ascii.fromImage(pixels, {
+  width: 80,
+  edgeDetect: 'sobel',
+  edgeThreshold: 50,
+  ramp: 'blocks',
+}));
+
+// Modo rostro para retratos (mejora contraste de tonos medios)
+console.log(ascii.fromImage(retratoPixels, {
+  width: 60,
+  ramp: 'detailed',
+  faceMode: true,
+}));
+```
+
+### Fuentes Figlet (v1.2.5)
+
+```ts
+import { readFileSync } from 'node:fs';
+import { parseFiglet, ascii } from 'ansimax';
+
+// Descarga fuentes desde http://www.figlet.org/fontdb.cgi
+const font = parseFiglet(readFileSync('./standard.flf', 'utf8'));
+
+console.log(ascii.figletText('¡Hola!', font));
+
+// Con color
+console.log(ascii.figletText('STYLE', font, {
+  colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
+}));
+```
+
 ### Árboles
 
 <img src="media/trees.png" alt="Árboles" />
@@ -357,7 +419,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.3'));
+console.log(components.badge('VERSION', 'v1.2.5'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -571,7 +633,7 @@ El roadmap apunta intencionalmente — y busca superar — gaps que ni siquiera
 - [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
+### ✅ Fase 3 — Motor ASCII
 - [x] Fuentes de bloque (`big`, `small`)
 - [x] Banner con gradiente + alineación + coloreado por carácter
 - [x] Dibujo de cajas (6 estilos de borde)
@@ -579,11 +641,12 @@ El roadmap apunta intencionalmente — y busca superar — gaps que ni siquiera
 - [x] Compositor de logos (gradiente + box wrapping)
 - [x] Registro de fuentes personalizadas (`registerFont`, `hasFont`, `listFonts`)
 - [x] API de stream (`ascii.stream()` con AbortSignal)
-- [ ] **Conversor Imagen → ASCII** (con detección de bordes, Sobel/Canny)
-- [ ] **Renderizado ASCII en color** (preservar colores de imagen)
-- [ ] **Dithering de imágenes** para mejor rango tonal (Floyd-Steinberg)
-- [ ] **ASCII optimizado para rostros** (modo de alto detalle para retratos)
-- [ ] **Soporte de fuentes figlet** (loader de archivos `.flf` — 250+ fuentes de comunidad)
+- [x] **Conversor Imagen → ASCII** — `ascii.fromImage()` con mapeo de luminancia (v1.2.5)
+- [x] **Renderizado ASCII en color** — preserva colores de imagen con `color: true` (v1.2.5)
+- [x] **Dithering de imágenes** — error diffusion Floyd-Steinberg (v1.2.5)
+- [x] **ASCII optimizado para rostros** — histogram stretching para retratos (v1.2.5)
+- [x] **Soporte de fuentes figlet** — parser + renderer `.flf` (`parseFiglet` + `ascii.figletText`) (v1.2.5)
+- [x] **Detección de bordes** — operador Sobel integrado en `fromImage` (v1.2.5, bonus)
 
 ### ✅ Fase 4 — Primitivas TUI
 - [x] Tablas (filas irregulares, celdas multi-línea, conscientes de ANSI)
@@ -759,6 +822,56 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.5 — Fase 3 completa: motor de imagen-a-ASCII
+
+Release minor que cierra el roadmap del motor ASCII con 5 features nuevas:
+
+- 🖼️ **`ascii.fromImage(pixels, opts)`** — Conversor Imagen → ASCII (input: `PixelGrid`)
+- 🎨 **Renderizado ASCII en color** — `color: true` preserva los colores fuente
+- 📐 **Dithering Floyd-Steinberg** — `dither: 'floyd-steinberg'` para gradientes tonales más suaves
+- 👤 **Modo optimizado para rostros** — `faceMode: true` mejora contraste de tonos medios en retratos
+- 🔠 **Soporte Figlet (.flf)** — `parseFiglet()` + `ascii.figletText()` para 250+ fuentes de comunidad
+- ⚡ **Bonus: detección de bordes Sobel** — `edgeDetect: 'sobel'` para efectos line-art
+
+```ts
+import { ascii } from 'ansimax';
+
+// Imagen a ASCII (input desde sharp/jimp/etc, sin dependencia de decoder)
+console.log(ascii.fromImage(pixels, {
+  width: 80,
+  color: true,
+  dither: 'floyd-steinberg',
+  ramp: 'detailed',
+}));
+
+// Renderizado Figlet
+const font = parseFiglet(readFileSync('./standard.flf', 'utf8'));
+console.log(ascii.figletText('¡Hola!', font));
+```
+
+Drop-in replacement para `1.2.4`.
+
+### v1.2.4 — Utilidades de gradiente + inspectabilidad
+
+Release patch añadiendo metadata de inspección y un helper `reverseGradient()`:
+
+- 🔍 **`ReusableGradient` expone `.stops`, `.resolvedStops`, `.defaultOptions`** — todos congelados, todos de solo lectura
+- 🔄 **Helper `reverseGradient()`** — invierte el orden de stops de un gradiente (funciona con arrays o `ReusableGradient`)
+- 🎯 **`presets` exportado con su nombre canónico** — junto al alias existente `colorPresets`
+
+```ts
+import { createGradient, reverseGradient } from 'ansimax';
+
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+const ice  = reverseGradient(fire);
+
+console.log(fire.stops);  // ['#ff5555', '#ffb86c', '#f1fa8c']  — read-only
+console.log(fire('cálido'));
+console.log(ice('frío'));
+```
+
+Drop-in replacement para `1.2.3`.
+
 ### v1.2.3 — Factory de gradientes + performance
 
 Release patch añadiendo una API orientada a performance:

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.3-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.5-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)
@@ -263,7 +263,7 @@ console.log(gradientRect({
 ### Reusable Gradients (v1.2.3)
 
 ```ts
-import { createGradient, ascii } from 'ansimax';
+import { createGradient, reverseGradient, ascii } from 'ansimax';
 
 // Pre-resolve hex stops once — significantly faster for repeated use
 const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
@@ -275,6 +275,14 @@ console.log(fire('Third line'));
 // Use as a colorFn for banners — same ColorFn signature
 console.log(ascii.banner('FIRE', { colorFn: fire }));
 
+// v1.2.4: inspect metadata
+console.log('Stops:', fire.stops);             // → ['#ff5555', '#ffb86c', '#f1fa8c']
+console.log('Resolved:', fire.resolvedStops);  // → [{r:255,g:85,b:85}, ...]
+
+// v1.2.4: reverse a gradient (preserves default options)
+const ice = reverseGradient(fire);
+console.log(ice('Cool side'));
+
 // Per-call options still work — perfect for animation
 for (let p = 0; p < 1; p += 0.05) {
   process.stdout.write('\r' + fire('flowing', { phase: p }));
@@ -298,6 +306,60 @@ console.log(ascii.banner('HELLO', {
 console.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));
 ```
 
+### Image → ASCII (v1.2.5)
+
+```ts
+import { ascii } from 'ansimax';
+import type { PixelGrid } from 'ansimax';
+
+// Get a PixelGrid from any image library (sharp, jimp, pngjs, etc.)
+// Each Pixel is `{ r, g, b }` or null
+const pixels: PixelGrid = await loadImagePixels('./photo.png');
+
+// Monochrome
+console.log(ascii.fromImage(pixels, { width: 80 }));
+
+// Color + Floyd-Steinberg dithering + detailed ramp
+console.log(ascii.fromImage(pixels, {
+  width: 100,
+  color: true,
+  dither: 'floyd-steinberg',
+  ramp: 'detailed',
+}));
+
+// Edge-detection mode (line art)
+console.log(ascii.fromImage(pixels, {
+  width: 80,
+  edgeDetect: 'sobel',
+  edgeThreshold: 50,
+  ramp: 'blocks',
+}));
+
+// Face mode for portraits (boosts midtone contrast)
+console.log(ascii.fromImage(portraitPixels, {
+  width: 60,
+  ramp: 'detailed',
+  faceMode: true,
+}));
+```
+
+### Figlet Fonts (v1.2.5)
+
+```ts
+import { readFileSync } from 'node:fs';
+import { parseFiglet, ascii } from 'ansimax';
+
+// Download fonts from http://www.figlet.org/fontdb.cgi
+const font = parseFiglet(readFileSync('./standard.flf', 'utf8'));
+
+console.log(ascii.figletText('Hello!', font));
+
+// With color
+console.log(ascii.figletText('STYLE', font, {
+  colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
+}));
+```
+
 ### Trees
 
 <img src="media/trees.png" alt="Trees" />
@@ -357,7 +419,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.3'));
+console.log(components.badge('VERSION', 'v1.2.5'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -571,7 +633,7 @@ The roadmap intentionally targets — and aims to surpass — gaps that even mat
 - [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
+### ✅ Phase 3 — ASCII engine
 - [x] Block fonts (`big`, `small`)
 - [x] Banner with gradient + alignment + per-char coloring
 - [x] Box drawing (6 border styles)
@@ -579,11 +641,12 @@ The roadmap intentionally targets — and aims to surpass — gaps that even mat
 - [x] Logo composer (gradient + box wrapping)
 - [x] Custom font registry (`registerFont`, `hasFont`, `listFonts`)
 - [x] Stream API (`ascii.stream()` with AbortSignal)
-- [ ] **Image → ASCII** converter (with edge detection, Sobel/Canny)
-- [ ] **Color ASCII** rendering (preserve image colors)
-- [ ] **Image dithering** for better tonal range (Floyd-Steinberg)
-- [ ] **Face-optimized ASCII** (high-detail mode for portraits)
-- [ ] **Figlet font support** (.flf file loader — 250+ community fonts)
+- [x] **Image → ASCII** converter — `ascii.fromImage()` with luminance mapping (v1.2.5)
+- [x] **Color ASCII** rendering — preserve image colors via `color: true` (v1.2.5)
+- [x] **Image dithering** — Floyd-Steinberg error diffusion (v1.2.5)
+- [x] **Face-optimized ASCII** — histogram stretching for portraits (v1.2.5)
+- [x] **Figlet font support** — `.flf` parser + renderer (`parseFiglet` + `ascii.figletText`) (v1.2.5)
+- [x] **Edge detection** — Sobel operator integrated in `fromImage` (v1.2.5, bonus)
 
 ### ✅ Phase 4 — Terminal UI primitives
 - [x] Tables (irregular rows, multi-line cells, ANSI-aware)
@@ -759,6 +822,56 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.5 — Phase 3 complete: image-to-ASCII engine
+
+Minor release closing the ASCII engine roadmap with 5 new features:
+
+- 🖼️ **`ascii.fromImage(pixels, opts)`** — Image → ASCII converter (input: `PixelGrid`)
+- 🎨 **Color ASCII rendering** — `color: true` preserves source colors
+- 📐 **Floyd-Steinberg dithering** — `dither: 'floyd-steinberg'` for smoother tonal gradients
+- 👤 **Face-optimized mode** — `faceMode: true` boosts midtone contrast for portraits
+- 🔠 **Figlet (.flf) support** — `parseFiglet()` + `ascii.figletText()` for 250+ community fonts
+- ⚡ **Bonus: Sobel edge detection** — `edgeDetect: 'sobel'` for line-art effects
+
+```ts
+import { ascii } from 'ansimax';
+
+// Image to ASCII (input from sharp/jimp/etc, no decoder dependency)
+console.log(ascii.fromImage(pixels, {
+  width: 80,
+  color: true,
+  dither: 'floyd-steinberg',
+  ramp: 'detailed',
+}));
+
+// Figlet rendering
+const font = parseFiglet(readFileSync('./standard.flf', 'utf8'));
+console.log(ascii.figletText('Hello!', font));
+```
+
+Drop-in replacement for `1.2.4`.
+
+### v1.2.4 — Gradient utilities + inspectability
+
+Patch release adding inspection metadata and a `reverseGradient()` helper:
+
+- 🔍 **`ReusableGradient` exposes `.stops`, `.resolvedStops`, `.defaultOptions`** — all frozen, all read-only
+- 🔄 **`reverseGradient()` helper** — flips a gradient's stop order (works with arrays or `ReusableGradient`)
+- 🎯 **`presets` exported as canonical name** — alongside the existing `colorPresets` alias
+
+```ts
+import { createGradient, reverseGradient } from 'ansimax';
+
+const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
+const ice  = reverseGradient(fire);
+
+console.log(fire.stops);  // ['#ff5555', '#ffb86c', '#f1fa8c']  — read-only
+console.log(fire('warm'));
+console.log(ice('cool'));
+```
+
+Drop-in replacement for `1.2.3`.
+
 ### v1.2.3 — Gradient factory + performance
 
 Patch release adding a performance-oriented API: