ansimax 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -3,6 +3,221 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.6] — ASCII module improvements
+
+Patch release focused on ASCII module quality and feature additions. No
+breaking changes — every 1.2.x program runs identically.
+
+### Added — 4 new built-in ramps
+
+`ASCII_RAMPS` now includes 4 additional ramps for different aesthetic styles:
+
+```js
+import { ASCII_RAMPS, ascii } from 'ansimax';
+
+ASCII_RAMPS.binary    // ' █'         — pure 2-char ramp
+ASCII_RAMPS.dots      // ' ⠁⠃⠇⠧⠷⡷⣷⣿' — Unicode braille (sparse aesthetic)
+ASCII_RAMPS.shades    // ' ⠁⠃⠇⠧⠷⡷⣷⣿█' — combined shading
+ASCII_RAMPS.ascii64   // 64-char printable ASCII — non-Unicode terminals
+
+ascii.fromImage(pixels, { ramp: 'shades' });
+ascii.fromImage(pixels, { ramp: 'binary', bgColor: true });  // photo-like effect
+```
+
+### Added — `bgColor` option in `fromImage`
+
+Render the source pixel's color as the **background** instead of the foreground.
+Pairs especially well with `ramp: 'binary'` for a photo-like effect where each
+character cell becomes a colored block:
+
+```js
+ascii.fromImage(pixels, {
+  width: 80,
+  bgColor: true,        // colors go on background
+  ramp: 'binary',       // chars are spaces/blocks
+});
+```
+
+Implies `color: true` — no need to set both.
+
+### Added — `brightness` and `contrast` in `fromImage`
+
+Pre-adjust the image's tonal range without modifying the source pixels:
+
+```js
+ascii.fromImage(pixels, {
+  width: 80,
+  brightness: 0.2,    // [-1, 1] — positive = lighter, negative = darker
+  contrast: 0.3,      // [-1, 1] — positive = boosted, negative = flattened
+});
+```
+
+Useful for tuning hard-to-read photos without re-processing the source.
+Values are clamped to `[-1, 1]`. Default `0` (no change, identical to v1.2.5).
+
+### Added — `kerning` option in `figletText`
+
+Control horizontal spacing between FIGfont glyphs:
+
+```js
+ascii.figletText('HELLO', font, {
+  kerning: 1,    // 1-space gap between each character glyph
+});
+```
+
+Default `0` (touching glyphs, matches previous behavior).
+
+### Added — Multi-line `figletText`
+
+`figletText` now handles `\n` in input — each line renders as a separate
+FIGfont block:
+
+```js
+ascii.figletText('LINE 1\nLINE 2', font, {
+  lineSpacing: 1,   // 1 blank line between rendered lines
+});
+```
+
+Single-line text takes a fast path (no behavior change for v1.2.5 callers).
+
+### Improved
+
+- Better JSDoc on `ASCII_RAMPS` with `@example` showing every ramp
+- Brightness/contrast use standard photo-editing formulas (linear stretch around midpoint)
+- All 1958 + 25 new tests pass
+
+### Notes
+
+- No new runtime dependencies — still zero
+- Drop-in replacement for `1.2.5`
+
+---
+
+## [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.

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.4-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.6-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)
@@ -49,7 +49,7 @@ Ansimax es una **librería de renderizado todo-en-uno** para construir interface
 npm install ansimax
 ```
 
-```ts
+```js
 import { color, gradient, ascii, loader, sleep } from 'ansimax';
 
 console.log(ascii.banner('hola', {
@@ -122,7 +122,7 @@ yarn add ansimax
 
 ## ⚡ Ejemplo en 30 segundos
 
-```ts
+```js
 import { color, gradient, loader, ascii, sleep } from 'ansimax';
 
 console.log(ascii.banner('deploy', {
@@ -140,7 +140,7 @@ console.log(color.green('✓') + ' Listo en ' + color.bold('1.4s'));
 
 ## 🚀 Inicio rápido
 
-```ts
+```js
 import { configure, color, themes, gradient } from 'ansimax';
 
 // Configuración global
@@ -186,7 +186,7 @@ console.log(themes.primary('primary de cyberpunk'));
 
 <img src="media/colors.png" alt="Colores y gradientes" />
 
-```ts
+```js
 import { color, gradient, rainbow } from 'ansimax';
 
 // Colores básicos
@@ -204,7 +204,7 @@ console.log(rainbow('preset rainbow integrado'));
 
 ### Gradientes animados (v1.2.0)
 
-```ts
+```js
 import { animateGradient, sleep } from 'ansimax';
 
 // Animación de flujo de color — corre hasta llamar stop()
@@ -227,7 +227,7 @@ await animateGradient('¡Listo!', ['#50fa7b', '#bd93f9'], {
 
 <img src="media/easing_curves.png" alt="Colors and gradients" />
 
-```ts
+```js
 import { gradient } from 'ansimax';
 
 const stops = ['#ff79c6', '#bd93f9', '#8be9fd'];
@@ -247,7 +247,7 @@ console.log(gradient('hola mundo', stops, { easing: (t) => t * t * t }));
 
 <img src="media/conic_gradients.png" alt="Colors and gradients" />
 
-```ts
+```js
 import { gradientRect } from 'ansimax';
 
 // Barrido radial alrededor del centro — rueda arcoíris
@@ -262,7 +262,7 @@ console.log(gradientRect({
 
 ### Gradientes reusables (v1.2.3)
 
-```ts
+```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
 // Pre-resuelve los stops de hex una vez — significativamente más rápido para uso repetido
@@ -294,7 +294,7 @@ for (let p = 0; p < 1; p += 0.05) {
 
 <img src="media/ascii_art.png" alt="ASCII art" />
 
-```ts
+```js
 import { ascii, gradient } from 'ansimax';
 
 console.log(ascii.banner('HOLA', {
@@ -306,11 +306,80 @@ console.log(ascii.banner('HOLA', {
 console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }));
 ```
 
+### Imagen → ASCII (v1.2.5)
+
+```js
+import { ascii } from 'ansimax';
+import sharp from 'sharp';
+
+// Obtén píxeles RGB raw de cualquier librería de imágenes — ejemplo con `sharp`.
+// Puedes usar jimp, pngjs, canvas, o cualquier decoder. Ansimax sigue sin deps.
+const { data, info } = await sharp('./foto.png')
+  .raw()
+  .toBuffer({ resolveWithObject: true });
+
+// Convierte el buffer RGB raw → PixelGrid (un array 2D de objetos { r, g, b })
+const pixels = [];
+for (let y = 0; y < info.height; y++) {
+  const row = [];
+  for (let x = 0; x < info.width; x++) {
+    const i = (y * info.width + x) * info.channels;
+    row.push({ r: data[i], g: data[i + 1], b: data[i + 2] });
+  }
+  pixels.push(row);
+}
+
+// Ahora usa ansimax — varias formas:
+
+// 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(pixels, {
+  width: 60,
+  ramp: 'detailed',
+  faceMode: true,
+}));
+```
+
+### Fuentes Figlet (v1.2.5)
+
+```js
+import { readFileSync } from 'node:fs';
+import { parseFiglet, ascii, gradient } 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" />
 
-```ts
+```js
 import { tree, color } from 'ansimax';
 
 const proyecto = tree({ label: 'mi-app', icon: '📦', color: color.bold });
@@ -329,7 +398,7 @@ console.log(proyecto.render({
 
 <img src="media/pixel_art.png" alt="Pixel art" />
 
-```ts
+```js
 import { images, createCanvas, gradientRect, SPRITES } from 'ansimax';
 
 // Sprite integrado
@@ -355,7 +424,7 @@ c.print();
 
 <img src="media/components.png" alt="Componentes" />
 
-```ts
+```js
 import { components, color } from 'ansimax';
 
 console.log(components.table([
@@ -365,7 +434,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.4'));
+console.log(components.badge('VERSION', 'v1.2.6'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -373,7 +442,7 @@ console.log(components.badge('BUILD',   'passing'));
 
 <img src="media/timeline.png" alt="Timeline" />
 
-```ts
+```js
 import { components } from 'ansimax';
 
 console.log(components.timeline([
@@ -386,7 +455,7 @@ console.log(components.timeline([
 
 ### Loaders y Progreso
 
-```ts
+```js
 import { loader, sleep } from 'ansimax';
 
 // Spinner con éxito/fallo
@@ -415,7 +484,7 @@ await loader.tasks([
 
 ### Animaciones
 
-```ts
+```js
 import { animate, gradient, sleep } from 'ansimax';
 
 await animate.typewriter('Bienvenido al wizard de deployment...', {
@@ -437,7 +506,7 @@ await animate.parallel([
 
 <img src="media/themes.png" alt="Temas" />
 
-```ts
+```js
 import { themes, createTheme } from 'ansimax';
 
 // Temas built-in
@@ -526,7 +595,7 @@ node examples/all-in-one.cjs
 
 La config global afecta cada módulo que la respeta (colores, temas, velocidad de animación, etc.):
 
-```ts
+```js
 import { configure, getConfig, withConfig, onConfigKeyChange } from 'ansimax';
 
 configure({
@@ -579,7 +648,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)
@@ -587,11 +656,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)
@@ -767,6 +837,74 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.6 — Mejoras del módulo ASCII
+
+Release patch con mejoras al motor ASCII:
+
+- 🎨 **4 ramps built-in nuevos** — `binary`, `dots`, `shades`, `ascii64`
+- 🖼️ **Opción `bgColor`** en `fromImage` — colores van al background (excelente con `ramp: 'binary'` para efecto foto)
+- 🔆 **`brightness` y `contrast`** pre-ajuste en `fromImage` — afina el rango tonal sin re-procesar
+- 📏 **Opción `kerning`** en `figletText` — controla el espacio entre glyphs
+- 📄 **`figletText` multi-línea** — input con `\n` renderiza múltiples bloques FIGfont con `lineSpacing` opcional
+
+```js
+import { ascii, ASCII_RAMPS } from 'ansimax';
+
+// Renderizado tipo-foto con bloques coloreados en background
+console.log(ascii.fromImage(pixels, {
+  width: 80,
+  bgColor: true,
+  ramp: 'binary',
+  brightness: 0.1,
+  contrast: 0.2,
+}));
+
+// Figlet multi-línea con espaciado
+console.log(ascii.figletText('TITULO\nSUBTITULO', font, {
+  kerning: 1,
+  lineSpacing: 1,
+}));
+```
+
+Drop-in replacement para `1.2.5`.
+
+### 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
+
+```js
+import { readFileSync } from 'node:fs';
+import { ascii, parseFiglet } from 'ansimax';
+
+// Construye un PixelGrid pequeño a mano (usa sharp/jimp/etc para imágenes
+// reales — ver sección Imagen → ASCII arriba)
+const pixels = [
+  [{ r: 255, g: 0, b: 0 }, { r: 0, g: 255, b: 0 }],
+  [{ r: 0, g: 0, b: 255 }, { r: 255, g: 255, b: 0 }],
+];
+
+// 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()`:
@@ -775,7 +913,7 @@ Release patch añadiendo metadata de inspección y un helper `reverseGradient()`
 - 🔄 **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
+```js
 import { createGradient, reverseGradient } from 'ansimax';
 
 const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
@@ -796,8 +934,8 @@ Release patch añadiendo una API orientada a performance:
 - 📖 Más JSDoc con ejemplos ejecutables
 - 🎯 Coincide con la firma `ColorFn` — funciona como `colorFn` en `ascii.banner`, themes, etc.
 
-```ts
-import { createGradient } from 'ansimax';
+```js
+import { createGradient, ascii } from 'ansimax';
 
 const fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);
 console.log(fire('¡Colores reusados!'));
@@ -826,7 +964,7 @@ Release minor que cierra el roadmap del motor de gradientes con tres features po
 - 📐 **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
+```js
 import { animateGradient } from 'ansimax';
 
 const ctrl = animateGradient('Cargando...', ['#ff79c6', '#bd93f9', '#8be9fd']);