ansimax 1.2.5 → 1.2.7

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);
@@ -2523,7 +2527,12 @@ var ASCII_RAMPS = {
   standard: " .:-=+*#%@",
   detailed: " .'`^\",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$",
   blocks: " \u2591\u2592\u2593\u2588",
-  simple: " .+#"
+  simple: " .+#",
+  // v1.2.6 — new ramps
+  binary: " \u2588",
+  dots: " \u2801\u2803\u2807\u2827\u2837\u2877\u28F7\u28FF",
+  shades: " \u2801\u2803\u2807\u2827\u2837\u2877\u28F7\u28FF\u2588",
+  ascii64: " `.'^,_:-+=<>i!lI?/\\|()1{}[]rcvunxzjftLCJUYXZO0Qoahkbdpqwm*WMB8&%$#@"
 };
 var _resolveRamp = (r) => {
   if (typeof r === "string" && r.length > 0) {
@@ -2599,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);
   }
@@ -2626,27 +2640,49 @@ var _enhanceForFace = (lum) => {
     })
   );
 };
+var _adjustBrightnessContrast = (lum, brightness, contrast) => {
+  const safeBrightness = Math.max(-1, Math.min(1, brightness)) * 255;
+  const safeContrast = Math.max(-1, Math.min(1, contrast));
+  const contrastFactor = 1 + safeContrast;
+  return lum.map(
+    (row) => row.map((v) => {
+      const adjusted = (v - 128) * contrastFactor + 128 + safeBrightness;
+      return Math.max(0, Math.min(255, adjusted));
+    })
+  );
+};
 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",
     edgeDetect = "none",
     edgeThreshold = 40,
     color: color2 = false,
-    faceMode = false
+    faceMode = false,
+    // v1.2.6
+    bgColor = false,
+    brightness = 0,
+    contrast = 0
   } = 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);
   let lum = _toLuminanceGrid(resized);
+  if (brightness !== 0 || contrast !== 0) {
+    lum = _adjustBrightnessContrast(lum, brightness, contrast);
+  }
   if (faceMode) lum = _enhanceForFace(lum);
   let edgeGrid = null;
   if (edgeDetect === "sobel") {
@@ -2657,7 +2693,7 @@ var fromImage = (pixels, opts = {}) => {
   if (dither === "floyd-steinberg" && !edgeGrid) {
     lum = _floydSteinberg(lum, rampLen);
   }
-  const useColor = color2 && !isNoColor();
+  const useColor = (color2 || bgColor) && !isNoColor();
   const lines = [];
   for (let y = 0; y < safeH; y++) {
     const lumRow = lum[y];
@@ -2679,7 +2715,11 @@ var fromImage = (pixels, opts = {}) => {
       if (useColor) {
         const p = pxRow[x];
         if (p) {
-          line += fgRgb(p.r, p.g, p.b) + ch;
+          if (bgColor) {
+            line += bgRgb(p.r, p.g, p.b) + ch;
+          } else {
+            line += fgRgb(p.r, p.g, p.b) + ch;
+          }
         } else {
           line += ch;
         }
@@ -2694,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) {
@@ -2703,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();
@@ -2732,8 +2781,32 @@ 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, colorFn = null } = opts;
+  const {
+    trim = true,
+    colorFn = null,
+    // v1.2.6
+    kerning = 0,
+    lineSpacing = 0
+  } = opts;
+  const safeKerning = Math.max(0, Math.floor(kerning));
+  const safeLineSpacing = Math.max(0, Math.floor(lineSpacing));
+  if (text.includes("\n")) {
+    const linesOfText = text.split("\n");
+    const renderedBlocks = linesOfText.map(
+      (line) => _renderFigletLine(line, font, safeKerning, trim)
+    );
+    const spacer = safeLineSpacing > 0 ? "\n".repeat(safeLineSpacing + 1) : "\n";
+    let multiResult = renderedBlocks.join(spacer);
+    if (colorFn) multiResult = colorFn(multiResult);
+    return multiResult;
+  }
+  let result = _renderFigletLine(text, font, safeKerning, trim);
+  if (colorFn) result = colorFn(result);
+  return result;
+};
+var _renderFigletLine = (text, font, kerning, trim) => {
   const glyphsForText = [];
   for (const ch of text) {
     const code = ch.codePointAt(0) ?? 32;
@@ -2745,23 +2818,26 @@ var figletText = (text, font, opts = {}) => {
       glyphsForText.push(fallback ?? new Array(font.height).fill(""));
     }
   }
+  const kerningSpacer = kerning > 0 ? " ".repeat(kerning) : "";
   const hardblankRe = new RegExp(_escapeRe(font.hardblank), "g");
   const rows = [];
   for (let r = 0; r < font.height; r++) {
     let row = "";
-    for (const g of glyphsForText) {
+    for (let i = 0; i < glyphsForText.length; i++) {
+      const g = glyphsForText[i];
       row += g[r] ?? "";
+      if (i < glyphsForText.length - 1 && kerningSpacer) {
+        row += kerningSpacer;
+      }
     }
     row = row.replace(hardblankRe, " ");
     rows.push(row);
   }
-  let result = rows.join("\n");
   if (trim) {
     const trimmed = rows.filter((row) => row.trim().length > 0);
-    result = trimmed.length > 0 ? trimmed.join("\n") : rows.join("\n");
+    return trimmed.length > 0 ? trimmed.join("\n") : rows.join("\n");
   }
-  if (colorFn) result = colorFn(result);
-  return result;
+  return rows.join("\n");
 };
 var _escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 var ascii = {

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);
@@ -2343,7 +2347,12 @@ var ASCII_RAMPS = {
   standard: " .:-=+*#%@",
   detailed: " .'`^\",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$",
   blocks: " \u2591\u2592\u2593\u2588",
-  simple: " .+#"
+  simple: " .+#",
+  // v1.2.6 — new ramps
+  binary: " \u2588",
+  dots: " \u2801\u2803\u2807\u2827\u2837\u2877\u28F7\u28FF",
+  shades: " \u2801\u2803\u2807\u2827\u2837\u2877\u28F7\u28FF\u2588",
+  ascii64: " `.'^,_:-+=<>i!lI?/\\|()1{}[]rcvunxzjftLCJUYXZO0Qoahkbdpqwm*WMB8&%$#@"
 };
 var _resolveRamp = (r) => {
   if (typeof r === "string" && r.length > 0) {
@@ -2419,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);
   }
@@ -2446,27 +2460,49 @@ var _enhanceForFace = (lum) => {
     })
   );
 };
+var _adjustBrightnessContrast = (lum, brightness, contrast) => {
+  const safeBrightness = Math.max(-1, Math.min(1, brightness)) * 255;
+  const safeContrast = Math.max(-1, Math.min(1, contrast));
+  const contrastFactor = 1 + safeContrast;
+  return lum.map(
+    (row) => row.map((v) => {
+      const adjusted = (v - 128) * contrastFactor + 128 + safeBrightness;
+      return Math.max(0, Math.min(255, adjusted));
+    })
+  );
+};
 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",
     edgeDetect = "none",
     edgeThreshold = 40,
     color: color2 = false,
-    faceMode = false
+    faceMode = false,
+    // v1.2.6
+    bgColor = false,
+    brightness = 0,
+    contrast = 0
   } = 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);
   let lum = _toLuminanceGrid(resized);
+  if (brightness !== 0 || contrast !== 0) {
+    lum = _adjustBrightnessContrast(lum, brightness, contrast);
+  }
   if (faceMode) lum = _enhanceForFace(lum);
   let edgeGrid = null;
   if (edgeDetect === "sobel") {
@@ -2477,7 +2513,7 @@ var fromImage = (pixels, opts = {}) => {
   if (dither === "floyd-steinberg" && !edgeGrid) {
     lum = _floydSteinberg(lum, rampLen);
   }
-  const useColor = color2 && !isNoColor();
+  const useColor = (color2 || bgColor) && !isNoColor();
   const lines = [];
   for (let y = 0; y < safeH; y++) {
     const lumRow = lum[y];
@@ -2499,7 +2535,11 @@ var fromImage = (pixels, opts = {}) => {
       if (useColor) {
         const p = pxRow[x];
         if (p) {
-          line += fgRgb(p.r, p.g, p.b) + ch;
+          if (bgColor) {
+            line += bgRgb(p.r, p.g, p.b) + ch;
+          } else {
+            line += fgRgb(p.r, p.g, p.b) + ch;
+          }
         } else {
           line += ch;
         }
@@ -2514,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) {
@@ -2523,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();
@@ -2552,8 +2601,32 @@ 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, colorFn = null } = opts;
+  const {
+    trim = true,
+    colorFn = null,
+    // v1.2.6
+    kerning = 0,
+    lineSpacing = 0
+  } = opts;
+  const safeKerning = Math.max(0, Math.floor(kerning));
+  const safeLineSpacing = Math.max(0, Math.floor(lineSpacing));
+  if (text.includes("\n")) {
+    const linesOfText = text.split("\n");
+    const renderedBlocks = linesOfText.map(
+      (line) => _renderFigletLine(line, font, safeKerning, trim)
+    );
+    const spacer = safeLineSpacing > 0 ? "\n".repeat(safeLineSpacing + 1) : "\n";
+    let multiResult = renderedBlocks.join(spacer);
+    if (colorFn) multiResult = colorFn(multiResult);
+    return multiResult;
+  }
+  let result = _renderFigletLine(text, font, safeKerning, trim);
+  if (colorFn) result = colorFn(result);
+  return result;
+};
+var _renderFigletLine = (text, font, kerning, trim) => {
   const glyphsForText = [];
   for (const ch of text) {
     const code = ch.codePointAt(0) ?? 32;
@@ -2565,23 +2638,26 @@ var figletText = (text, font, opts = {}) => {
       glyphsForText.push(fallback ?? new Array(font.height).fill(""));
     }
   }
+  const kerningSpacer = kerning > 0 ? " ".repeat(kerning) : "";
   const hardblankRe = new RegExp(_escapeRe(font.hardblank), "g");
   const rows = [];
   for (let r = 0; r < font.height; r++) {
     let row = "";
-    for (const g of glyphsForText) {
+    for (let i = 0; i < glyphsForText.length; i++) {
+      const g = glyphsForText[i];
       row += g[r] ?? "";
+      if (i < glyphsForText.length - 1 && kerningSpacer) {
+        row += kerningSpacer;
+      }
     }
     row = row.replace(hardblankRe, " ");
     rows.push(row);
   }
-  let result = rows.join("\n");
   if (trim) {
     const trimmed = rows.filter((row) => row.trim().length > 0);
-    result = trimmed.length > 0 ? trimmed.join("\n") : rows.join("\n");
+    return trimmed.length > 0 ? trimmed.join("\n") : rows.join("\n");
   }
-  if (colorFn) result = colorFn(result);
-  return result;
+  return rows.join("\n");
 };
 var _escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 var ascii = {

package/examples/05-components.ts

@@ -42,10 +42,10 @@ console.log();
 
 console.log(color.bold('━━━ Status ━━━'));
 console.log();
-console.log(components.status('Build started', { type: 'info' }));
-console.log(components.status('Linting passed', { type: 'success' }));
-console.log(components.status('5 deprecation warnings', { type: 'warning' }));
-console.log(components.status('Build failed', { type: 'error' }));
+console.log(components.status('info',    'Build started'));
+console.log(components.status('success', 'Linting passed'));
+console.log(components.status('warn',    '5 deprecation warnings'));
+console.log(components.status('error',   'Build failed'));
 console.log();
 
 console.log(color.bold('━━━ Section ━━━'));

package/examples/all-in-one.cjs

@@ -118,14 +118,14 @@ async function main() {
   console.log(components.section('🏷️  Badges & Status', { width: 60 }));
   console.log();
   console.log(' ',
-    components.badge('VERSION', 'v1.2.5'),
+    components.badge('VERSION', 'v1.2.7'),
     components.badge('BUILD', 'passing'),
     components.badge('LICENSE', 'Apache 2.0'));
   console.log();
-  console.log(components.status('Build started', { type: 'info' }));
-  console.log(components.status('Tests passed', { type: 'success' }));
-  console.log(components.status('1 deprecation', { type: 'warning' }));
-  console.log(components.status('Build failed', { type: 'error' }));
+  console.log(components.status('info',    'Build started'));
+  console.log(components.status('success', 'Tests passed'));
+  console.log(components.status('warn',    '1 deprecation'));
+  console.log(components.status('error',   'Build failed'));
   console.log();
 
   // ── 9. Loaders ────────────────────────────────────────────

package/examples/all-in-one.mjs

@@ -117,14 +117,14 @@ console.log();
 console.log(components.section('🏷️  Badges & Status', { width: 60 }));
 console.log();
 console.log(' ',
-  components.badge('VERSION', 'v1.2.5'),
+  components.badge('VERSION', 'v1.2.7'),
   components.badge('BUILD', 'passing'),
   components.badge('LICENSE', 'Apache 2.0'));
 console.log();
-console.log(components.status('Build started', { type: 'info' }));
-console.log(components.status('Tests passed', { type: 'success' }));
-console.log(components.status('1 deprecation', { type: 'warning' }));
-console.log(components.status('Build failed', { type: 'error' }));
+  console.log(components.status('info',    'Build started'));
+  console.log(components.status('success', 'Tests passed'));
+  console.log(components.status('warn',    '1 deprecation'));
+  console.log(components.status('error',   'Build failed'));
 console.log();
 
 // ── 9. Loaders ────────────────────────────────────────────

package/package.json

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