ansimax 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -3,6 +3,155 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.7] — Bug fixes + robustness
+
+Patch release focused on edge case handling, better error messages, and
+defensive coding. No breaking changes — every 1.2.x program runs identically.
+
+### Fixed
+
+- **`ascii.fromImage()` silently accepted `width: 0`, `NaN`, `Infinity`** —
+  now returns an empty string explicitly. Previously it would clamp to 1
+  and produce a single-character-wide output, which was confusing:
+
+  ```js
+  // Before (v1.2.6 and earlier):
+  ascii.fromImage(pixels, { width: 0 });      // → 1-char-wide output 😞
+  ascii.fromImage(pixels, { width: NaN });    // → 1-char-wide output 😞
+
+  // Now (v1.2.7):
+  ascii.fromImage(pixels, { width: 0 });      // → '' (explicit)
+  ascii.fromImage(pixels, { width: NaN });    // → ''
+  ascii.fromImage(pixels, { width: -10 });    // → ''
+  ascii.fromImage(pixels, { width: 1 });      // → still works, 1-char wide
+  ```
+
+  Same validation applies to `height` when explicitly set.
+
+- **`ascii.figletText('', font)` returned `font.height - 1` empty lines**
+  instead of an empty string. Now returns `''` immediately.
+
+- **`ascii.fromImage()` could crash on non-rectangular grids** (rows of
+  different widths) because `_resizePixels` assumed all rows had the same
+  length as the first row. Now each row is sampled by its actual width,
+  with missing pixels coalesced to `null` (the standard "transparent"
+  marker).
+
+### Improved — Error codes everywhere
+
+Errors thrown by the ASCII module now carry stable `.code` properties for
+programmatic catching:
+
+| Function | Error condition | `.code` |
+|---|---|---|
+| `parseFiglet` | non-string / empty input | `ANSIMAX_INVALID_FIGLET_INPUT` |
+| `parseFiglet` | unrecognized header | `ANSIMAX_INVALID_FIGLET_HEADER` |
+| `parseFiglet` | non-positive height | `ANSIMAX_INVALID_FIGLET_HEIGHT` |
+| `ascii.registerFont` | empty name | `ANSIMAX_INVALID_FONT_NAME` |
+| `ascii.registerFont` | reserved name without `force` | `ANSIMAX_RESERVED_FONT_NAME` |
+
+Error messages also include a debug snippet for `parseFiglet` header
+errors (truncated at 60 chars), so you immediately see what was wrong.
+
+### Notes
+
+- Error message text may have changed slightly — if you were matching exact
+  strings in tests, switch to `.code` checks (which are stable forever)
+- All 1983 + 17 new tests pass
+- No new runtime dependencies — still zero
+
+---
+
+## [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

package/README.es.md

@@ -7,10 +7,10 @@
 _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.5-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.7-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)
+[![Tests](https://img.shields.io/badge/tests-1900%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
 [![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](#)
 [![Bundle](https://img.shields.io/badge/bundle-%3C100kb-brightgreen.svg?style=flat-square)](#)
 
@@ -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', {
@@ -308,13 +308,28 @@ console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }
 
 ### Imagen → ASCII (v1.2.5)
 
-```ts
+```js
 import { ascii } from 'ansimax';
-import type { PixelGrid } 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);
+}
 
-// 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');
+// Ahora usa ansimax — varias formas:
 
 // Monocromo
 console.log(ascii.fromImage(pixels, { width: 80 }));
@@ -336,7 +351,7 @@ console.log(ascii.fromImage(pixels, {
 }));
 
 // Modo rostro para retratos (mejora contraste de tonos medios)
-console.log(ascii.fromImage(retratoPixels, {
+console.log(ascii.fromImage(pixels, {
   width: 60,
   ramp: 'detailed',
   faceMode: true,
@@ -345,9 +360,9 @@ console.log(ascii.fromImage(retratoPixels, {
 
 ### Fuentes Figlet (v1.2.5)
 
-```ts
+```js
 import { readFileSync } from 'node:fs';
-import { parseFiglet, ascii } from 'ansimax';
+import { parseFiglet, ascii, gradient } from 'ansimax';
 
 // Descarga fuentes desde http://www.figlet.org/fontdb.cgi
 const font = parseFiglet(readFileSync('./standard.flf', 'utf8'));
@@ -364,7 +379,7 @@ console.log(ascii.figletText('STYLE', font, {
 
 <img src="media/trees.png" alt="Árboles" />
 
-```ts
+```js
 import { tree, color } from 'ansimax';
 
 const proyecto = tree({ label: 'mi-app', icon: '📦', color: color.bold });
@@ -383,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
@@ -409,7 +424,7 @@ c.print();
 
 <img src="media/components.png" alt="Componentes" />
 
-```ts
+```js
 import { components, color } from 'ansimax';
 
 console.log(components.table([
@@ -419,7 +434,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.5'));
+console.log(components.badge('VERSION', 'v1.2.7'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -427,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([
@@ -440,7 +455,7 @@ console.log(components.timeline([
 
 ### Loaders y Progreso
 
-```ts
+```js
 import { loader, sleep } from 'ansimax';
 
 // Spinner con éxito/fallo
@@ -469,7 +484,7 @@ await loader.tasks([
 
 ### Animaciones
 
-```ts
+```js
 import { animate, gradient, sleep } from 'ansimax';
 
 await animate.typewriter('Bienvenido al wizard de deployment...', {
@@ -491,7 +506,7 @@ await animate.parallel([
 
 <img src="media/themes.png" alt="Temas" />
 
-```ts
+```js
 import { themes, createTheme } from 'ansimax';
 
 // Temas built-in
@@ -580,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({
@@ -822,6 +837,59 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.7 — Correcciones + robustez
+
+Release patch enfocado en manejo de edge cases y mejor DX:
+
+- 🐛 **`fromImage` rechaza dimensiones inválidas explícitamente** — `width: 0`, `NaN`, `Infinity` ahora retornan `''` en vez de clampear silenciosamente
+- 🐛 **`figletText('')` retorna `''`** — antes retornaba filas vacías
+- 🛡️ **Grids no-rectangulares manejados con gracia** — filas de distinto largo ya no crashean `fromImage`
+- 🎯 **Códigos de error añadidos en todo el módulo ASCII** — `ANSIMAX_INVALID_FIGLET_HEADER`, `ANSIMAX_INVALID_FONT_NAME`, etc. para `catch` programático
+- 📝 **Mejores mensajes de error** — `parseFiglet` ahora incluye snippet del input problemático
+
+```js
+try {
+  ascii.registerFont('big', myFont);  // 'big' está reservado
+} catch (e) {
+  if (e.code === 'ANSIMAX_RESERVED_FONT_NAME') {
+    ascii.registerFont('big', myFont, { force: true });  // override
+  }
+}
+```
+
+Drop-in replacement para `1.2.6`.
+
+### 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:
@@ -833,8 +901,16 @@ Release minor que cierra el roadmap del motor ASCII con 5 features nuevas:
 - 🔠 **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';
+```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, {
@@ -859,7 +935,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']);
@@ -880,8 +956,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!'));
@@ -910,7 +986,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']);