ansimax 1.2.6 → 1.2.7

package/CHANGELOG.md

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

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.6-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)](#)
 
@@ -434,7 +434,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.6'));
+console.log(components.badge('VERSION', 'v1.2.7'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -837,6 +837,28 @@ 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:

package/README.md

@@ -7,10 +7,10 @@
 _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.6-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)](#)
 
@@ -434,7 +434,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.2.6'));
+console.log(components.badge('VERSION', 'v1.2.7'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -837,6 +837,28 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.7 — Bug fixes + robustness
+
+Patch release focused on edge case handling and better DX:
+
+- 🐛 **`fromImage` rejects invalid dimensions explicitly** — `width: 0`, `NaN`, `Infinity` now return `''` instead of clamping silently
+- 🐛 **`figletText('')` returns `''`** — previously returned empty rows
+- 🛡️ **Non-rectangular grids handled gracefully** — rows of different widths no longer crash `fromImage`
+- 🎯 **Error codes added throughout ASCII module** — `ANSIMAX_INVALID_FIGLET_HEADER`, `ANSIMAX_INVALID_FONT_NAME`, etc. for programmatic catch
+- 📝 **Better error messages** — `parseFiglet` now includes a snippet of the problematic input
+
+```js
+try {
+  ascii.registerFont('big', myFont);  // 'big' is reserved
+} catch (e) {
+  if (e.code === 'ANSIMAX_RESERVED_FONT_NAME') {
+    ascii.registerFont('big', myFont, { force: true });  // override
+  }
+}
+```
+
+Drop-in replacement for `1.2.6`.
+
 ### v1.2.6 — ASCII module improvements
 
 Patch release with ASCII engine improvements:

package/dist/index.js

@@ -2346,12 +2346,16 @@ var validateFont = (name, fontMap) => {
 };
 var registerFont = (name, fontMap, opts = {}) => {
   if (typeof name !== "string" || !name.length) {
-    throw new TypeError("ascii.registerFont: name must be a non-empty string");
+    const err = new TypeError("ascii.registerFont: name must be a non-empty string");
+    err.code = "ANSIMAX_INVALID_FONT_NAME";
+    throw err;
   }
   if (RESERVED_FONT_NAMES.has(name) && !opts.force) {
-    throw new Error(
+    const err = new Error(
       `Font name "${name}" is reserved. Pass { force: true } to override.`
     );
+    err.code = "ANSIMAX_RESERVED_FONT_NAME";
+    throw err;
   }
   const safeMap = ensureFontMap(fontMap, name);
   validateFont(name, safeMap);
@@ -2604,10 +2608,15 @@ var _resizePixels = (pixels, targetW, targetH) => {
   for (let y = 0; y < targetH; y++) {
     const sy = Math.min(srcH - 1, Math.floor(y / targetH * srcH));
     const srcRow = pixels[sy];
+    const actualRowW = Array.isArray(srcRow) ? srcRow.length : 0;
     const newRow = new Array(targetW);
     for (let x = 0; x < targetW; x++) {
-      const sx = Math.min(srcW - 1, Math.floor(x / targetW * srcW));
-      newRow[x] = srcRow[sx];
+      if (actualRowW === 0) {
+        newRow[x] = null;
+        continue;
+      }
+      const sx = Math.min(actualRowW - 1, Math.floor(x / targetW * actualRowW));
+      newRow[x] = srcRow[sx] ?? null;
     }
     out.push(newRow);
   }
@@ -2646,8 +2655,12 @@ var fromImage = (pixels, opts = {}) => {
   if (!Array.isArray(pixels) || pixels.length === 0) return "";
   const firstRow = pixels[0];
   if (!Array.isArray(firstRow) || firstRow.length === 0) return "";
+  const requestedW = opts.width ?? 80;
+  if (!Number.isFinite(requestedW) || requestedW <= 0) return "";
+  if (opts.height !== void 0) {
+    if (!Number.isFinite(opts.height) || opts.height <= 0) return "";
+  }
   const {
-    width = 80,
     ramp = "standard",
     invert = false,
     dither = "none",
@@ -2662,7 +2675,7 @@ var fromImage = (pixels, opts = {}) => {
   } = opts;
   const srcH = pixels.length;
   const srcW = pixels[0].length;
-  const safeW = Math.max(1, Math.floor(width));
+  const safeW = Math.max(1, Math.floor(requestedW));
   const computedH = Math.max(1, Math.round(srcH / srcW * safeW * 0.5));
   const safeH = opts.height != null ? Math.max(1, Math.floor(opts.height)) : computedH;
   const resized = _resizePixels(pixels, safeW, safeH);
@@ -2721,7 +2734,9 @@ var fromImage = (pixels, opts = {}) => {
 };
 var parseFiglet = (flfContent) => {
   if (typeof flfContent !== "string" || flfContent.length === 0) {
-    throw new TypeError("parseFiglet: input must be a non-empty string");
+    const err = new TypeError("parseFiglet: input must be a non-empty string");
+    err.code = "ANSIMAX_INVALID_FIGLET_INPUT";
+    throw err;
   }
   const lines = flfContent.split(/\r?\n/);
   if (lines.length === 0) {
@@ -2730,13 +2745,20 @@ var parseFiglet = (flfContent) => {
   const header = lines[0];
   const m = /^flf2.\s*(\S)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(\d+)/.exec(header);
   if (!m) {
-    throw new TypeError('parseFiglet: invalid FIGfont header (expected "flf2a$..." line)');
+    const snippet = header.length > 60 ? header.slice(0, 60) + "\u2026" : header;
+    const err = new TypeError(
+      `parseFiglet: invalid FIGfont header. Expected "flf2a$..." prefix, got: "${snippet}"`
+    );
+    err.code = "ANSIMAX_INVALID_FIGLET_HEADER";
+    throw err;
   }
   const hardblank = m[1];
   const height = parseInt(m[2], 10);
   const commentLines = parseInt(m[6], 10);
   if (!Number.isFinite(height) || height <= 0) {
-    throw new TypeError(`parseFiglet: invalid height ${m[2]}`);
+    const err = new TypeError(`parseFiglet: invalid height ${m[2]} (must be positive integer)`);
+    err.code = "ANSIMAX_INVALID_FIGLET_HEIGHT";
+    throw err;
   }
   let cursor2 = 1 + Math.max(0, commentLines);
   const glyphs = /* @__PURE__ */ new Map();
@@ -2759,6 +2781,7 @@ var parseFiglet = (flfContent) => {
 };
 var figletText = (text, font, opts = {}) => {
   if (typeof text !== "string") return "";
+  if (text.length === 0) return "";
   if (!font || !font.glyphs || font.height <= 0) return "";
   const {
     trim = true,

package/dist/index.mjs

@@ -2166,12 +2166,16 @@ var validateFont = (name, fontMap) => {
 };
 var registerFont = (name, fontMap, opts = {}) => {
   if (typeof name !== "string" || !name.length) {
-    throw new TypeError("ascii.registerFont: name must be a non-empty string");
+    const err = new TypeError("ascii.registerFont: name must be a non-empty string");
+    err.code = "ANSIMAX_INVALID_FONT_NAME";
+    throw err;
   }
   if (RESERVED_FONT_NAMES.has(name) && !opts.force) {
-    throw new Error(
+    const err = new Error(
       `Font name "${name}" is reserved. Pass { force: true } to override.`
     );
+    err.code = "ANSIMAX_RESERVED_FONT_NAME";
+    throw err;
   }
   const safeMap = ensureFontMap(fontMap, name);
   validateFont(name, safeMap);
@@ -2424,10 +2428,15 @@ var _resizePixels = (pixels, targetW, targetH) => {
   for (let y = 0; y < targetH; y++) {
     const sy = Math.min(srcH - 1, Math.floor(y / targetH * srcH));
     const srcRow = pixels[sy];
+    const actualRowW = Array.isArray(srcRow) ? srcRow.length : 0;
     const newRow = new Array(targetW);
     for (let x = 0; x < targetW; x++) {
-      const sx = Math.min(srcW - 1, Math.floor(x / targetW * srcW));
-      newRow[x] = srcRow[sx];
+      if (actualRowW === 0) {
+        newRow[x] = null;
+        continue;
+      }
+      const sx = Math.min(actualRowW - 1, Math.floor(x / targetW * actualRowW));
+      newRow[x] = srcRow[sx] ?? null;
     }
     out.push(newRow);
   }
@@ -2466,8 +2475,12 @@ var fromImage = (pixels, opts = {}) => {
   if (!Array.isArray(pixels) || pixels.length === 0) return "";
   const firstRow = pixels[0];
   if (!Array.isArray(firstRow) || firstRow.length === 0) return "";
+  const requestedW = opts.width ?? 80;
+  if (!Number.isFinite(requestedW) || requestedW <= 0) return "";
+  if (opts.height !== void 0) {
+    if (!Number.isFinite(opts.height) || opts.height <= 0) return "";
+  }
   const {
-    width = 80,
     ramp = "standard",
     invert = false,
     dither = "none",
@@ -2482,7 +2495,7 @@ var fromImage = (pixels, opts = {}) => {
   } = opts;
   const srcH = pixels.length;
   const srcW = pixels[0].length;
-  const safeW = Math.max(1, Math.floor(width));
+  const safeW = Math.max(1, Math.floor(requestedW));
   const computedH = Math.max(1, Math.round(srcH / srcW * safeW * 0.5));
   const safeH = opts.height != null ? Math.max(1, Math.floor(opts.height)) : computedH;
   const resized = _resizePixels(pixels, safeW, safeH);
@@ -2541,7 +2554,9 @@ var fromImage = (pixels, opts = {}) => {
 };
 var parseFiglet = (flfContent) => {
   if (typeof flfContent !== "string" || flfContent.length === 0) {
-    throw new TypeError("parseFiglet: input must be a non-empty string");
+    const err = new TypeError("parseFiglet: input must be a non-empty string");
+    err.code = "ANSIMAX_INVALID_FIGLET_INPUT";
+    throw err;
   }
   const lines = flfContent.split(/\r?\n/);
   if (lines.length === 0) {
@@ -2550,13 +2565,20 @@ var parseFiglet = (flfContent) => {
   const header = lines[0];
   const m = /^flf2.\s*(\S)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(\d+)/.exec(header);
   if (!m) {
-    throw new TypeError('parseFiglet: invalid FIGfont header (expected "flf2a$..." line)');
+    const snippet = header.length > 60 ? header.slice(0, 60) + "\u2026" : header;
+    const err = new TypeError(
+      `parseFiglet: invalid FIGfont header. Expected "flf2a$..." prefix, got: "${snippet}"`
+    );
+    err.code = "ANSIMAX_INVALID_FIGLET_HEADER";
+    throw err;
   }
   const hardblank = m[1];
   const height = parseInt(m[2], 10);
   const commentLines = parseInt(m[6], 10);
   if (!Number.isFinite(height) || height <= 0) {
-    throw new TypeError(`parseFiglet: invalid height ${m[2]}`);
+    const err = new TypeError(`parseFiglet: invalid height ${m[2]} (must be positive integer)`);
+    err.code = "ANSIMAX_INVALID_FIGLET_HEIGHT";
+    throw err;
   }
   let cursor2 = 1 + Math.max(0, commentLines);
   const glyphs = /* @__PURE__ */ new Map();
@@ -2579,6 +2601,7 @@ var parseFiglet = (flfContent) => {
 };
 var figletText = (text, font, opts = {}) => {
   if (typeof text !== "string") return "";
+  if (text.length === 0) return "";
   if (!font || !font.glyphs || font.height <= 0) return "";
   const {
     trim = true,

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.6'),
+    components.badge('VERSION', 'v1.2.7'),
     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.6'),
+  components.badge('VERSION', 'v1.2.7'),
   components.badge('BUILD', 'passing'),
   components.badge('LICENSE', 'Apache 2.0'));
 console.log();

package/package.json

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