ansimax 1.2.4 → 1.2.5

package/CHANGELOG.md

@@ -3,6 +3,131 @@
 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.

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.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)
@@ -306,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" />
@@ -365,7 +419,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.5'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -579,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)
@@ -587,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)
@@ -767,6 +822,35 @@ 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()`:

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.4-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)
@@ -306,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" />
@@ -365,7 +419,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.4'));
+console.log(components.badge('VERSION', 'v1.2.5'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -579,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)
@@ -587,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)
@@ -767,6 +822,35 @@ 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: