ansimax 1.1.0 → 1.1.2

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.1.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.1.2-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)
@@ -20,6 +20,27 @@ _Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • C
 
 ---
 
+<div align="center">
+
+### 🎬 Preview
+
+<table>
+  <tr>
+    <td align="center">
+      <strong>Animations</strong><br/>
+      <img src="media/animations.gif" alt="Ansimax animations demo" width="420"/>
+    </td>
+    <td align="center">
+      <strong>Loaders</strong><br/>
+      <img src="media/loaders.gif" alt="Ansimax loaders demo" width="420"/>
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
 ## 🌟 What is Ansimax?
 
 Ansimax is a **batteries-included rendering library** for building beautiful terminal UIs in Node.js. One package replaces a stack of 8+ dependencies — colors, gradients, ASCII art, spinners, progress bars, tables, menus, trees, themes, pixel art — combined into a single coherent TypeScript API with **zero runtime dependencies**.
@@ -29,14 +50,14 @@ npm install ansimax
 ```
 
 ```ts
-import { color, gradient, ascii, loader } from 'ansimax';
+import { color, gradient, ascii, loader, sleep } from 'ansimax';
 
 console.log(ascii.banner('hello', {
   colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
 }));
 
 const stop = loader.spin('Building project', { color: '#bd93f9' });
-await someAsyncWork();
+await sleep(1500);
 stop('Build complete', true);
 ```
 
@@ -102,14 +123,14 @@ yarn add ansimax
 ## ⚡ 30-second example
 
 ```ts
-import { color, gradient, loader, ascii } from 'ansimax';
+import { color, gradient, loader, ascii, sleep } from 'ansimax';
 
 console.log(ascii.banner('deploy', {
   colorFn: (t) => gradient(t, ['#ff6b6b', '#feca57', '#48dbfb']),
 }));
 
 const stop = loader.spin('Building project', { color: '#bd93f9' });
-await someAsyncWork();
+await sleep(1500);             // simulate async work
 stop('Build complete', true);  // ✓ + success color
 
 console.log(color.green('✓') + ' Ready in ' + color.bold('1.4s'));
@@ -166,12 +187,19 @@ console.log(themes.primary('cyberpunk primary'));
 <img src="media/colors.png" alt="Colors and gradients" />
 
 ```ts
-import { color, gradient } from 'ansimax';
+import { color, gradient, rainbow } from 'ansimax';
+
+// Basic colors
+console.log(color.red('red'), color.green('green'), color.blue('blue'));
 
-color.red('red');   color.green('green');  color.blue('blue');
-color.bold(text);   color.italic(text);    color.underline(text);
-gradient('fire to ocean', ['#ff6b6b', '#feca57', '#48dbfb']);
-color.rainbow('built-in rainbow preset');
+// Style modifiers
+console.log(color.bold('bold'), color.italic('italic'), color.underline('underlined'));
+
+// Multi-stop gradient
+console.log(gradient('fire to ocean', ['#ff6b6b', '#feca57', '#48dbfb']));
+
+// Built-in rainbow preset
+console.log(rainbow('built-in rainbow preset'));
 ```
 
 ### ASCII Art
@@ -181,13 +209,13 @@ color.rainbow('built-in rainbow preset');
 ```ts
 import { ascii, gradient } from 'ansimax';
 
-ascii.banner('HELLO', {
+console.log(ascii.banner('HELLO', {
   font: 'big',
   align: 'center',
   colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9']),
-});
+}));
 
-ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' });
+console.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));
 ```
 
 ### Trees
@@ -214,7 +242,7 @@ console.log(project.render({
 <img src="media/pixel_art.png" alt="Pixel art" />
 
 ```ts
-import { images, createCanvas, gradientRect } from 'ansimax';
+import { images, createCanvas, gradientRect, SPRITES } from 'ansimax';
 
 // Built-in sprite
 console.log(images.sprite('heart'));
@@ -230,7 +258,8 @@ console.log(gradientRect({
 const c = createCanvas(40, 10);
 c.fill({ r: 18, g: 18, b: 38 });
 c.drawCircle(20, 5, 4, { r: 255, g: 200, b: 0 }, true);
-c.drawSprite(2, 2, images.sprites.star!.pixels);
+const starSprite = SPRITES.star;
+if (starSprite) c.drawSprite(2, 2, starSprite.pixels);
 c.print();
 ```
 
@@ -241,15 +270,15 @@ c.print();
 ```ts
 import { components, color } from 'ansimax';
 
-components.table([
+console.log(components.table([
   ['Module',     'Status',                'Coverage'],
   ['colors',     color.green('● ready'),  '100%'],
   ['animations', color.green('● ready'),  '100%'],
   ['loaders',    color.green('● ready'),  '100%'],
-], { borderStyle: 'rounded' });
+], { borderStyle: 'rounded' }));
 
-components.badge('VERSION', 'v1.1.0');
-components.badge('BUILD',   'passing');
+console.log(components.badge('VERSION', 'v1.1.2'));
+console.log(components.badge('BUILD',   'passing'));
 ```
 
 ### Timeline
@@ -257,22 +286,24 @@ components.badge('BUILD',   'passing');
 <img src="media/timeline.png" alt="Timeline" />
 
 ```ts
-components.timeline([
+import { components } from 'ansimax';
+
+console.log(components.timeline([
   { label: 'Project init',   done: true,  time: '10:00' },
   { label: 'Build pipeline', done: true,  time: '10:15' },
   { label: 'Run tests',      done: false, time: '10:32' },
   { label: 'Deploy to npm',  done: false },
-]);
+]));
 ```
 
 ### Loaders & Progress
 
 ```ts
-import { loader } from 'ansimax';
+import { loader, sleep } from 'ansimax';
 
 // Spinner with success/failure
 const stop = loader.spin('Loading...', { color: '#bd93f9' });
-await work();
+await sleep(1500);
 stop('Done!', true);   // ✓ green icon
 
 // Animated progress bar
@@ -282,18 +313,22 @@ await loader.progressAnimate(100, 'Downloading', {
 
 // Hierarchical tasks with parallel execution
 await loader.tasks([
-  { text: 'Build', fn: async () => build(), subtasks: [
-    { text: 'TypeScript', fn: async () => tsc() },
-    { text: 'Bundle',     fn: async () => bundle() },
-  ]},
-  { text: 'Test',  fn: async () => test() },
+  {
+    text: 'Build',
+    fn: async () => await sleep(500),
+    subtasks: [
+      { text: 'TypeScript', fn: async () => await sleep(800) },
+      { text: 'Bundle',     fn: async () => await sleep(600) },
+    ],
+  },
+  { text: 'Test', fn: async () => await sleep(700) },
 ], { parallel: true });
 ```
 
 ### Animations
 
 ```ts
-import { animate, gradient } from 'ansimax';
+import { animate, gradient, sleep } from 'ansimax';
 
 await animate.typewriter('Welcome to the deployment wizard...', {
   speed: 30,
@@ -304,9 +339,9 @@ await animate.fadeIn('Loading complete', { duration: 600 });
 
 // Race steps against a timeout — never hang
 await animate.parallel([
-  async () => await checkNetwork(),
-  async () => await checkDatabase(),
-  async () => await checkAuth(),
+  async () => await sleep(500),   // simulated network check
+  async () => await sleep(700),   // simulated database check
+  async () => await sleep(400),   // simulated auth check
 ], { timeout: 5000 });
 ```
 
@@ -319,7 +354,7 @@ import { themes, createTheme } from 'ansimax';
 
 // Built-in themes
 themes.use('dracula');
-themes.primary('hello');
+console.log(themes.primary('hello'));
 
 // Listen for changes
 const off = themes.onChange((newTheme, oldTheme) => {
@@ -329,28 +364,60 @@ const off = themes.onChange((newTheme, oldTheme) => {
 // Multi-tenant: each instance fully isolated
 const tenantA = createTheme('nord');
 const tenantB = createTheme('matrix');
-tenantA.register('custom', myDef);  // doesn't leak to tenantB
+
+// Define a custom theme and register it ONLY in tenantA
+tenantA.register('custom', {
+  name: 'Custom',
+  primary:   '#ff5e5e',
+  secondary: '#5e5eff',
+  accent:    '#5eff5e',
+  success:   '#10b981',
+  warning:   '#fbbf24',
+  error:     '#ef4444',
+  info:      '#06b6d4',
+  muted:     '#6b7280',
+  bg:        '#1e293b',
+  surface:   '#334155',
+  text:      '#f1f5f9',
+  gradient:  ['#ff5e5e', '#5eff5e', '#5e5eff'],
+});
+
+console.log('tenantA themes include custom?', tenantA.list().includes('custom'));
+console.log('tenantB themes include custom?', tenantB.list().includes('custom'));
+//                                            ↑ false — full isolation
 ```
 
 ---
 
 ## 📚 Examples
 
-Seven production-grade examples ship in the npm package and are runnable directly. Find them in [`/examples`](./examples) once you install:
+Eleven production-grade examples ship in the npm package and are runnable directly. Find them in [`/examples`](./examples) once you install:
 
 | File | What it demonstrates |
 |---|---|
-| `trees-basic.ts` | Minimal trees example — builder API + algorithms |
-| `01-cli-installer.ts` | npm-create style installer — banner + hierarchical tasks + status icons + summary box |
-| `02-live-dashboard.ts` | Real-time dashboard — `frames.live` + service table + gradient bars + `onResize` + SIGINT cleanup |
-| `03-pixel-art-game.ts` | Bouncing rocket sprite — canvas + alpha blending + gradient + FPS counter + drift-corrected loop |
-| `04-interactive-deploy.ts` | Menu + multi-select + `loader.multi` + `createTheme` + `onConfigChange` |
-| `05-tree-visualizations.ts` | Filesystem + dependency + JSON + decision trees (`walk` + `measure` bonus) |
-| `06-everything-together.ts` | Comprehensive showcase — every module exercised in one cohesive demo |
+| `01-quick-smoke.ts` | Quick smoke test — verifies every major import works |
+| `02-colors-gradients.ts` | Every color fn, gradient types, presets, compose, chain API |
+| `03-ascii-banners.ts` | Banners (`big`/`small`), 6 box styles, dividers, logo composer |
+| `04-trees.ts` | Tree builder + plain-data API, 4 styles, palettes, algorithms (walk/find/map/filter) |
+| `05-components.ts` | Tables, badges, status, sections, columns, timelines, progress bars |
+| `06-pixel-art.ts` | Sprites, custom canvas, gradient rects with dither, transforms (flip/rotate) |
+| `07-animations.ts` | typewriter, fadeIn/Out, slide, pulse, wave, glitch, reveal |
+| `08-loaders.ts` | spinner styles, animated progress, hierarchical tasks, countdown |
+| `09-themes.ts` | All 8 built-in themes, listeners, custom theme registration, per-instance isolation |
+| `10-everything.ts` | Comprehensive showcase — every module exercised in one cohesive demo |
+| `all-in-one.mjs` | Full demo in **ESM** (plain JS with `import`) — no TypeScript needed |
+| `all-in-one.cjs` | Full demo in **CommonJS** (plain JS with `require`) — no TypeScript needed |
 
 Run any example with:
 ```bash
-npx tsx examples/06-everything-together.ts
+# TypeScript examples
+npx tsx examples/10-everything.ts
+
+# Plain JS — ESM
+node examples/all-in-one.mjs
+
+# Plain JS — CommonJS
+node examples/all-in-one.cjs
 ```
 
 ---
@@ -388,11 +455,11 @@ const off = onConfigKeyChange('theme', (newTheme, oldTheme) => {
 
 // Temporary override + auto-restore on completion or throw
 await withConfig({ animationSpeed: 'fast' }, async () => {
-  await runDemo();
+  // ...your fast-mode code here...
 });
 
 // Strict mode catches config typos
-configure({ unknwnKey: 'x' }, { strict: true });  // throws RangeError
+// configure({ unknwnKey: 'x' }, { strict: true });  // throws RangeError
 ```
 
 ---
@@ -604,7 +671,7 @@ ansimax/
 │   ├── trees/          Tree builder + algorithms
 │   ├── utils/          ANSI primitives + helpers
 │   └── configure.ts    Global config + subscribers
-├── examples/           7 production-grade examples
+├── examples/           10 examples (TS) + 2 (JS — ESM & CJS) — all features covered
 └── __tests__/          16 test suites, 1700+ tests
 ```
 
@@ -612,6 +679,28 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.1.2 — Maturity & robustness
+
+Patch release focused on quality refinements — no API changes.
+
+- 🛡️ **`process.setMaxListeners` defensive bump** — prevents `MaxListenersExceededWarning` in HMR / nodemon / ts-node-dev setups where ansimax modules re-register cursor-restore handlers
+- 🧪 **Uniform `TypeError` for theme validation** — `themes.register()` now consistently throws `TypeError` for structural / type errors (was a mix of `Error` and `TypeError`)
+- 🎯 **`themes.use()` throws `RangeError`** for unknown theme names (was `Error`) — better semantic match for "value out of allowed set"
+- 📝 **Cleaner barrel re-exports** — header comment now documents legacy aliases and recommends canonical names
+
+Drop-in replacement for `1.1.1`.
+
+### v1.1.1 — Bug fixes + cleaner examples
+
+Patch release fixing two bugs from real-world v1.1.0 testing, plus a refreshed examples folder.
+
+- 🐛 **Fixed `box()` crash** with `padding: { x, y }` — now gracefully falls back to default for non-numeric padding (also handles NaN, Infinity, strings)
+- 🐛 **Fixed `components.menu()` cursor leak** on abrupt exit (Ctrl+C, SIGTERM) — emergency cleanup handlers now restore the cursor even when the process is killed mid-menu
+- 📚 **New examples** — 10 TypeScript examples + 2 plain JS variants (`all-in-one.mjs` for ESM, `all-in-one.cjs` for CommonJS)
+- 📖 **READMEs updated** — preview GIFs in the header, comprehensive showcase GIF in the footer
+
+No API changes — drop-in replacement for `1.1.0`.
+
 ### v1.1.0 — Comprehensive hardening + new features
 
 A massive robustness pass across every module, plus a new `trees` module. **100% backward compatible** — every existing API works identically.
@@ -676,6 +765,18 @@ If Ansimax saves you time, please star the repo on [GitHub](https://github.com/B
 
 ---
 
+## 🎬 Full showcase
+
+<div align="center">
+
+<img src="media/all-ansimax.gif" alt="Ansimax full showcase — everything in action" width="720"/>
+
+_All features in action — typewriter, gradients, ASCII banners, trees, tables, spinners, themes, and pixel art_
+
+</div>
+
+---
+
 ## 📜 License
 
 [Apache License 2.0](LICENSE) © 2026 Brashkie

package/dist/index.js

@@ -225,6 +225,11 @@ var cursor = {
 var _exitHandlerRegistered = false;
 var _isTestEnv = () => process.env["JEST_WORKER_ID"] !== void 0 || process.env["VITEST"] !== void 0 || process.env["NODE_ENV"] === "test";
 var _installCursorRestoreImpl = () => {
+  try {
+    const current = process.getMaxListeners?.() ?? 10;
+    if (current < 20) process.setMaxListeners?.(20);
+  } catch {
+  }
   const restore = () => {
     try {
       safeStreamWrite(process.stdout, cursor.show());
@@ -2264,7 +2269,8 @@ var banner = (text, opts = {}) => {
 var box = (text, opts = {}) => {
   const safe = ensureString2(text, "box(text)");
   const { padding = 1, borderStyle = "rounded", width = null } = opts;
-  const safePadding = Math.max(0, Math.floor(padding));
+  const padNum = typeof padding === "number" && Number.isFinite(padding) ? padding : 1;
+  const safePadding = Math.max(0, Math.floor(padNum));
   const b = BOX_STYLES[borderStyle] ?? BOX_STYLES.rounded;
   const lines = safe.split("\n");
   const inner = width != null ? lines.map((l) => padEnd(truncateAnsi(l, width, ""), width)) : lines;
@@ -3677,7 +3683,32 @@ var menu = (items, opts = {}) => {
       }
       cursorHidden = false;
     }
+    try {
+      process.off("SIGINT", emergencyCleanup);
+      process.off("SIGTERM", emergencyCleanup);
+      process.off("exit", emergencyCleanup);
+    } catch {
+    }
+  };
+  const emergencyCleanup = () => {
+    if (cursorHidden) {
+      try {
+        out.write(cursor.show());
+      } catch {
+      }
+      cursorHidden = false;
+    }
+    try {
+      if (inp.setRawMode) inp.setRawMode(false);
+    } catch {
+    }
   };
+  try {
+    process.once("SIGINT", emergencyCleanup);
+    process.once("SIGTERM", emergencyCleanup);
+    process.once("exit", emergencyCleanup);
+  } catch {
+  }
   try {
     emit(cursor.hide());
     cursorHidden = true;
@@ -4087,12 +4118,12 @@ var validateTheme = (t) => {
   }
   const obj = t;
   if (typeof obj.name !== "string" || obj.name.length === 0) {
-    throw new Error('Theme must have a non-empty "name" string.');
+    throw new TypeError('Theme must have a non-empty "name" string.');
   }
   for (const key of REQUIRED_COLOR_KEYS) {
     const value = obj[key];
     if (typeof value !== "string" || !HEX_RE4.test(value)) {
-      throw new Error(
+      throw new TypeError(
         `Invalid hex in theme "${obj.name}" \u2192 ${key}: ${JSON.stringify(value)}. Expected #RGB or #RRGGBB.`
       );
     }
@@ -4101,20 +4132,20 @@ var validateTheme = (t) => {
     const value = obj[key];
     if (value === void 0) continue;
     if (typeof value !== "string" || !HEX_RE4.test(value)) {
-      throw new Error(
+      throw new TypeError(
         `Invalid hex in theme "${obj.name}" \u2192 ${key}: ${JSON.stringify(value)}.`
       );
     }
   }
   if (!Array.isArray(obj.gradient) || obj.gradient.length < 2) {
-    throw new Error(
+    throw new TypeError(
       `Theme "${obj.name}" must define a "gradient" array with at least 2 colors.`
     );
   }
   for (let i = 0; i < obj.gradient.length; i++) {
     const stop = obj.gradient[i];
     if (typeof stop !== "string" || !HEX_RE4.test(stop)) {
-      throw new Error(
+      throw new TypeError(
         `Invalid hex in theme "${obj.name}" \u2192 gradient[${i}]: ${JSON.stringify(stop)}.`
       );
     }
@@ -4426,8 +4457,8 @@ var themes = {
   use(name) {
     const t = _globalRegistry.get(name);
     if (!t) {
-      throw new Error(
-        `Theme "${name}" not found. Available: ${[..._globalRegistry.keys()].join(", ")}`
+      throw new RangeError(
+        `Theme "${name}" not found. Available themes: ${[..._globalRegistry.keys()].join(", ")}`
       );
     }
     const old = _globalActive;

package/dist/index.mjs

@@ -53,6 +53,11 @@ var cursor = {
 var _exitHandlerRegistered = false;
 var _isTestEnv = () => process.env["JEST_WORKER_ID"] !== void 0 || process.env["VITEST"] !== void 0 || process.env["NODE_ENV"] === "test";
 var _installCursorRestoreImpl = () => {
+  try {
+    const current = process.getMaxListeners?.() ?? 10;
+    if (current < 20) process.setMaxListeners?.(20);
+  } catch {
+  }
   const restore = () => {
     try {
       safeStreamWrite(process.stdout, cursor.show());
@@ -2092,7 +2097,8 @@ var banner = (text, opts = {}) => {
 var box = (text, opts = {}) => {
   const safe = ensureString2(text, "box(text)");
   const { padding = 1, borderStyle = "rounded", width = null } = opts;
-  const safePadding = Math.max(0, Math.floor(padding));
+  const padNum = typeof padding === "number" && Number.isFinite(padding) ? padding : 1;
+  const safePadding = Math.max(0, Math.floor(padNum));
   const b = BOX_STYLES[borderStyle] ?? BOX_STYLES.rounded;
   const lines = safe.split("\n");
   const inner = width != null ? lines.map((l) => padEnd(truncateAnsi(l, width, ""), width)) : lines;
@@ -3505,7 +3511,32 @@ var menu = (items, opts = {}) => {
       }
       cursorHidden = false;
     }
+    try {
+      process.off("SIGINT", emergencyCleanup);
+      process.off("SIGTERM", emergencyCleanup);
+      process.off("exit", emergencyCleanup);
+    } catch {
+    }
+  };
+  const emergencyCleanup = () => {
+    if (cursorHidden) {
+      try {
+        out.write(cursor.show());
+      } catch {
+      }
+      cursorHidden = false;
+    }
+    try {
+      if (inp.setRawMode) inp.setRawMode(false);
+    } catch {
+    }
   };
+  try {
+    process.once("SIGINT", emergencyCleanup);
+    process.once("SIGTERM", emergencyCleanup);
+    process.once("exit", emergencyCleanup);
+  } catch {
+  }
   try {
     emit(cursor.hide());
     cursorHidden = true;
@@ -3915,12 +3946,12 @@ var validateTheme = (t) => {
   }
   const obj = t;
   if (typeof obj.name !== "string" || obj.name.length === 0) {
-    throw new Error('Theme must have a non-empty "name" string.');
+    throw new TypeError('Theme must have a non-empty "name" string.');
   }
   for (const key of REQUIRED_COLOR_KEYS) {
     const value = obj[key];
     if (typeof value !== "string" || !HEX_RE4.test(value)) {
-      throw new Error(
+      throw new TypeError(
         `Invalid hex in theme "${obj.name}" \u2192 ${key}: ${JSON.stringify(value)}. Expected #RGB or #RRGGBB.`
       );
     }
@@ -3929,20 +3960,20 @@ var validateTheme = (t) => {
     const value = obj[key];
     if (value === void 0) continue;
     if (typeof value !== "string" || !HEX_RE4.test(value)) {
-      throw new Error(
+      throw new TypeError(
         `Invalid hex in theme "${obj.name}" \u2192 ${key}: ${JSON.stringify(value)}.`
       );
     }
   }
   if (!Array.isArray(obj.gradient) || obj.gradient.length < 2) {
-    throw new Error(
+    throw new TypeError(
       `Theme "${obj.name}" must define a "gradient" array with at least 2 colors.`
     );
   }
   for (let i = 0; i < obj.gradient.length; i++) {
     const stop = obj.gradient[i];
     if (typeof stop !== "string" || !HEX_RE4.test(stop)) {
-      throw new Error(
+      throw new TypeError(
         `Invalid hex in theme "${obj.name}" \u2192 gradient[${i}]: ${JSON.stringify(stop)}.`
       );
     }
@@ -4254,8 +4285,8 @@ var themes = {
   use(name) {
     const t = _globalRegistry.get(name);
     if (!t) {
-      throw new Error(
-        `Theme "${name}" not found. Available: ${[..._globalRegistry.keys()].join(", ")}`
+      throw new RangeError(
+        `Theme "${name}" not found. Available themes: ${[..._globalRegistry.keys()].join(", ")}`
       );
     }
     const old = _globalActive;