ansimax 1.0.0 → 1.1.1

package/README.md

@@ -1,19 +1,18 @@
 <div align="center">
 
-<img src="media/ansimax.png" alt="Ansimax" width="180"/>
-
-# Ansimax
+<img src="media/ansimax.png" alt="Ansimax logo" width="380"/>
 
 ### The ultimate CLI rendering library for Node.js
 
-Colors • Gradients • Animations • ASCII Art • Pixel Art • Components • Themes
+_Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_
 
-[![status](https://img.shields.io/badge/status-unreleased-orange?style=flat-square)](#)
-[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg?style=flat-square)](tsconfig.json)
-[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg?style=flat-square)](#)
-[![Tests](https://img.shields.io/badge/tests-750%2B%20passing-brightgreen.svg?style=flat-square)](#)
+[![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.1-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)
 [![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)](#)
 
 **English** · [Español](README.es.md)
 
@@ -21,60 +20,89 @@ Colors • Gradients • Animations • ASCII Art • Pixel Art • Components
 
 ---
 
-## 🎬 Live Preview
+<div align="center">
 
-See Ansimax in action — every animation and loader running live:
+### 🎬 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>
 
-### Animations
-
-https://github.com/Brashkie/ansimax/raw/main/media/animations.mp4
+</div>
 
-### Loaders
+---
 
-https://github.com/Brashkie/ansimax/raw/main/media/loaders.mp4
+## 🌟 What is Ansimax?
 
-> 💡 GitHub renders these MP4s as inline video players once the repo is pushed. Or run them locally with `npx tsx examples/animations.ts` and `npx tsx examples/loaders.ts`.
+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**.
 
----
+```bash
+npm install ansimax
+```
 
-## 🌟 What is Ansimax?
+```ts
+import { color, gradient, ascii, loader } from 'ansimax';
 
-**Ansimax** is a modern, zero-dependency rendering library for Node.js that turns your terminal into a vibrant, dynamic canvas. It bundles advanced ANSI colors, smooth animations, ASCII art, pixel art, interactive components, and theming into a single package — all written in strict TypeScript with full type definitions.
+console.log(ascii.banner('hello', {
+  colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
+}));
 
-Built for developers who want to ship CLIs that **feel** professional.
+const stop = loader.spin('Building project', { color: '#bd93f9' });
+await someAsyncWork();
+stop('Build complete', true);
+```
 
 ---
 
 ## 💡 Why Ansimax?
 
-- ⚡ **Zero dependencies** — no bloat, no transitive vulnerabilities, no version conflicts
-- 🎯 **One library instead of 10** — replaces `chalk` + `ora` + `cli-table3` + `figlet` + `gradient-string` + more
-- 🎨 **True 24-bit color + gradients** out of the box — auto-fallback to 256/16 when needed
-- 🧠 **Built for real-world CLIs** — `AbortSignal` support, `NO_COLOR` compliance, TTY-aware
-- 🛡️ **100% test coverage** — 750+ tests across every module
-- 📘 **TypeScript-first** — strict mode, full type defs, zero `any`
+| Without Ansimax | With Ansimax |
+|---|---|
+| Install 8+ packages: `chalk`, `gradient-string`, `figlet`, `ora`, `cli-progress`, `cli-table3`, `boxen`, `inquirer` | One install: `ansimax` |
+| Mix incompatible APIs, different paradigms, conflicting types | Consistent functional API, single source of truth |
+| No coherent theme system across packages | Built-in themes (Dracula, Nord, Matrix, Cyberpunk, +5) |
+| Manual cursor cleanup, no crash safety | Reference-counted cursor + crash handlers built in |
+| No `AbortSignal` support in most CLI libs | Every animation, loader, and prompt is abortable |
+| Each lib brings its own runtime fallback logic | Unified `NO_COLOR` / `FORCE_COLOR` / TTY detection |
+| No memory bounds on color caches | Bounded LRU caches everywhere (no leaks under load) |
 
 ---
 
-## 🆚 Comparison
-
-| Feature              | **Ansimax** | chalk | ora  | cli-table3 | figlet | gradient-string |
-|----------------------|-------------|-------|------|------------|--------|-----------------|
-| 16-color             | ✅          | ✅    | ➖   | ➖         | ➖     | ➖              |
-| 256-color            | ✅          | ✅    | ➖   | ➖         | ➖     | ➖              |
-| Truecolor (24-bit)   | ✅          | ✅    | ➖   | ➖         | ➖     | ✅              |
-| Gradients            | ✅          | ❌    | ❌   | ❌         | ❌     | ✅              |
-| Animations           | ✅          | ❌    | ❌   | ❌         | ❌     | ❌              |
-| Spinners             | ✅          | ❌    | ✅   | ❌         | ❌     | ❌              |
-| Progress bars        | ✅          | ❌    | ❌   | ❌         | ❌     | ❌              |
-| Tables               | ✅          | ❌    | ❌   | ✅         | ❌     | ❌              |
-| ASCII art / banners  | ✅          | ❌    | ❌   | ❌         | ✅     | ❌              |
-| Pixel art / canvas   | ✅          | ❌    | ❌   | ❌         | ❌     | ❌              |
-| Themes               | ✅          | ❌    | ❌   | ❌         | ❌     | ❌              |
-| AbortSignal support  | ✅          | ❌    | ❌   | ❌         | ❌     | ❌              |
-| Zero dependencies    | ✅          | ❌    | ❌   | ❌         | ❌     | ❌              |
-
-> Ansimax replaces 5+ separate packages with a single zero-dependency library.
+## 🆚 Comparison with the Node.js ecosystem
+
+Ansimax replaces a dependency stack of popular Node.js libraries with one coherent, typed package:
+
+| Feature | chalk | gradient-string | ora | cli-progress | figlet | boxen | inquirer | cli-table3 | **Ansimax** |
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| Basic + 256 colors | ✅ | — | — | — | — | — | — | — | ✅ |
+| Truecolor with adaptive fallback | ✅ | ✅ | — | — | — | — | — | — | ✅ |
+| Multi-stop gradients | — | ✅ | — | — | — | — | — | — | ✅ |
+| **Animated gradients** | — | — | — | — | — | — | — | — | 🔜 |
+| ASCII banners | — | — | — | — | ✅ | — | — | — | ✅ |
+| Custom font registry | — | — | — | — | partial | — | — | — | ✅ |
+| Boxes with multiple styles | — | — | — | — | — | ✅ | — | — | ✅ |
+| Spinners (multiple styles) | — | — | ✅ | — | — | — | — | — | ✅ (11 styles) |
+| Animated progress bars | — | — | — | ✅ | — | — | — | — | ✅ |
+| **Hierarchical/parallel tasks** | — | — | — | — | — | — | — | — | ✅ |
+| Tables (multi-line, ANSI-aware) | — | — | — | — | — | — | — | ✅ | ✅ |
+| Interactive menus + multi-select | — | — | — | — | — | — | ✅ | — | ✅ |
+| **Trees with cycle detection** | — | — | — | — | — | — | — | — | ✅ |
+| **Pixel art + canvas + sprites** | — | — | — | — | — | — | — | — | ✅ |
+| **Theme system + per-instance isolation** | — | — | — | — | — | — | — | — | ✅ |
+| `AbortSignal` everywhere | — | — | partial | — | — | — | partial | — | ✅ |
+| `NO_COLOR` env support | ✅ | partial | partial | — | — | — | — | — | ✅ |
+| TypeScript-first | partial | partial | ✅ | partial | partial | ✅ | partial | partial | ✅ |
+| Zero runtime dependencies | ✅ | — | — | — | — | — | — | — | ✅ |
+| **Total install size** | small | small | medium | medium | medium | small | large | medium | **< 100 KB** |
 
 ---
 
@@ -82,441 +110,488 @@ Built for developers who want to ship CLIs that **feel** professional.
 
 ```bash
 npm install ansimax
+# or
+pnpm add ansimax
+# or
+yarn add ansimax
 ```
 
-```bash
-yarn add ansimax    # Yarn
-pnpm add ansimax    # PNPM
-bun add ansimax     # Bun
-```
-
-**Requires Node.js >= 18**
+**Requirements:** Node.js ≥ 18. ESM and CJS both supported. Examples published with the package — see [`/examples`](./examples).
 
 ---
 
 ## ⚡ 30-second example
 
 ```ts
-import { color } from 'ansimax';
+import { color, gradient, loader, ascii } from 'ansimax';
 
-console.log(color.green('Hello world'));
-```
+console.log(ascii.banner('deploy', {
+  colorFn: (t) => gradient(t, ['#ff6b6b', '#feca57', '#48dbfb']),
+}));
 
-That's it. No config, no setup. Want more? Keep reading.
+const stop = loader.spin('Building project', { color: '#bd93f9' });
+await someAsyncWork();
+stop('Build complete', true);  // ✓ + success color
+
+console.log(color.green('✓') + ' Ready in ' + color.bold('1.4s'));
+```
 
 ---
 
 ## 🚀 Quick Start
 
 ```ts
-import { color, animate, loader, ascii, components, gradient } from 'ansimax';
-
-// Colors with stacked styles (single ANSI reset, no nesting)
-console.log(color.bold(color.cyan('Hello, terminal!')));
+import { configure, color, themes, gradient } from 'ansimax';
 
-// Gradient text
-console.log(gradient('Smooth color flow', ['#ff6b6b', '#feca57', '#48dbfb']));
+// Global configuration
+configure({ theme: 'dracula', animationSpeed: 'normal' });
 
-// Animated typewriter
-await animate.typewriter('Welcome to Ansimax...', { speed: 50 });
+// Basic styling
+console.log(color.red('error'));
+console.log(color.bold(color.cyan('important')));
 
-// Spinner with success state
-const stop = loader.spin('Building project...', { color: '#00ff88' });
-await doWork();
-stop('Built successfully', true);
+// Multi-stop gradient
+console.log(gradient('rainbow text', [
+  '#ff5555', '#ffaa00', '#ffff00',
+  '#00ff00', '#0099ff', '#cc44ff',
+]));
 
-// ASCII banner
-console.log(ascii.banner('ANSIMAX', { font: 'big', align: 'center' }));
-
-// Component table
-console.log(components.table([
-  ['Name', 'Status'],
-  ['Build', '✓ ready'],
-], { header: true, borderStyle: 'rounded' }));
+// Switch theme — fires subscribers
+themes.use('cyberpunk');
+console.log(themes.primary('cyberpunk primary'));
 ```
 
 ---
 
 ## ✨ Features
 
-| Module | Capabilities |
-|---|---|
-| 🎨 **Colors** | 16-color · 256-color · 24-bit truecolor · hex · RGB · `compose()` for stacking · `NO_COLOR` aware |
-| 🌈 **Gradients** | Linear · multi-stop · rainbow · gradient rectangles (horizontal, vertical, diagonal, radial) |
-| ⚡ **Animations** | typewriter · fadeIn · fadeOut · slide · pulse · wave · glitch · reveal — all `AbortSignal`-aware |
-| 🔄 **Loaders** | 11 spinner styles · animated progress bars · multi-task runners (sequential & parallel) · countdowns |
-| 🖼️ **ASCII Art** | Two built-in fonts · `box()` with 6 border styles · ANSI-aware dividers · banners with gradients |
-| 🎬 **Frames** | Custom frame engines · live updating renders · loading bars · bouncing balls · **morph** (text→text) |
-| 🧩 **Components** | Tables · status messages · badges · progress bars · timelines · interactive menus (single/multi-select) |
-| 🌃 **Themes** | 8 built-in themes (Dracula, Nord, Monokai, Cyberpunk, Pastel, Matrix, Ocean, Sunset) · custom theme support |
-| 🖌️ **Pixel Art** | Half-block rendering · sprite library · canvas drawing API · sprite transforms (flip, rotate) |
-| 🛠️ **Utilities** | `truncateAnsi` · `wordWrap` (with soft-break) · `repeatVisible` · `stripAnsi` · color math |
+- 🎨 **Colors** — Truecolor / 256 / basic with adaptive fallback. NO_COLOR / FORCE_COLOR / TTY detection
+- 🌈 **Gradients** — Multi-stop linear, radial, diagonal, arbitrary-angle. Custom presets via `registerPreset`
+- 🔠 **ASCII Art** — Banners (`big`/`small` fonts), boxes (6 styles), dividers, logos. Stream API + custom font registry
+- 🖼️ **Pixel Art** — Sprites, alpha blending, dithered gradients, canvas with dirty-rect rendering, braille mode (2×4 sub-pixel)
+- 🌳 **Trees** — Builder + plain-data API, 4 styles, per-node colors/icons, max-depth, cycle detection, walk/find/map/filter algorithms
+- 🎞️ **Animations** — Typewriter, fade, slide, pulse, wave, glitch, reveal. AbortSignal-aware, reducedMotion mode
+- ⏳ **Loaders** — 11 spinner styles, animated bars, hierarchical/parallel tasks, countdowns, multi-spinner manager
+- 🎬 **Frames** — Sequenced playback with pause/resume/seek, live push-based renderer, drift-corrected timing, morph
+- 🧱 **Components** — Tables (ANSI-aware, multi-line cells), badges, status lines, sections, columns, timelines, interactive menus
+- 🎨 **Themes** — 8 built-ins (Dracula, Nord, Monokai, Cyberpunk, Pastel, Matrix, Ocean, Sunset). Per-instance isolation, `onChange` listeners, `bg*` helpers
+- ⚙️ **Configure** — Centralized config with subscribers, batched updates, `withConfig()` temporary overrides, strict mode
+- 🛠️ **Utils** — ANSI primitives, cursor control, terminal hyperlinks (OSC 8), `setTitle`, `safeJson`, `onResize`, debounce/throttle/memoize
 
 ---
 
 ## 📸 Showcase
 
 ### Colors & Gradients
-<div align="center">
-  <img src="media/colors.png" alt="Colors and gradients" width="700"/>
-</div>
 
-```ts
-import { color, gradient, rainbow, compose } from 'ansimax';
-
-// 16, 256, and 24-bit colors
-color.red('basic');                          // 16-color
-color.color256(196)('palette');              // 256-color
-color.hex('#48dbfb')('truecolor');           // 24-bit
-color.rgb(255, 100, 50)('custom');           // RGB
+<img src="media/colors.png" alt="Colors and gradients" />
 
-// Stack styles with compose() — single reset, no nesting
-const errorStyle = compose(color.bold, color.red, color.underline);
-console.log(errorStyle('CRITICAL ERROR'));
+```ts
+import { color, gradient } from 'ansimax';
 
-// Multi-stop gradients
-gradient('Smooth flow', ['#ff6b6b', '#feca57', '#48dbfb']);
-rainbow('Rainbow text!');
+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');
 ```
 
----
-
 ### ASCII Art
-<div align="center">
-  <img src="media/ascii_art.png" alt="ASCII art" width="700"/>
-</div>
+
+<img src="media/ascii_art.png" alt="ASCII art" />
 
 ```ts
-import { ascii, rainbow } from 'ansimax';
+import { ascii, gradient } from 'ansimax';
 
-ascii.big('HELLO');                   // 5-line block font
-ascii.small('hello');                 // 3-line compact font
-ascii.banner('ANSIMAX', {
+ascii.banner('HELLO', {
   font: 'big',
-  colorFn: rainbow,
   align: 'center',
+  colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9']),
 });
 
-// Boxes with 6 border styles
-ascii.box(rainbow('Rainbow box!'), {
-  borderStyle: 'double',
-  padding: 2,
-});
+ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' });
+```
 
-// ANSI-aware dividers
-ascii.divider({
-  label: color.cyan(' SECTION '),
-  width: 60,
-});
+### Trees
+
+<img src="media/trees.png" alt="Trees" />
+
+```ts
+import { tree, color } from 'ansimax';
+
+const project = tree({ label: 'my-app', icon: '📦', color: color.bold });
+const src = project.add({ label: 'src', icon: '📁' });
+src.addLeaf({ label: 'index.ts', icon: '📄' });
+src.addLeaf({ label: 'app.ts',   icon: '📄' });
+
+console.log(project.render({
+  style: 'rounded',
+  palette: [color.cyan, color.green, color.magenta],
+  guideColor: color.dim,
+}));
 ```
 
----
+### Pixel Art & Canvas
+
+<img src="media/pixel_art.png" alt="Pixel art" />
+
+```ts
+import { images, createCanvas, gradientRect } from 'ansimax';
+
+// Built-in sprite
+console.log(images.sprite('heart'));
+
+// Smooth gradient with Bayer dither
+console.log(gradientRect({
+  width: 50, height: 4,
+  colors: ['#ff6b6b', '#feca57', '#48dbfb'],
+  dither: 'bayer',
+}));
+
+// Custom canvas
+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);
+c.print();
+```
 
 ### Components
-<div align="center">
-  <img src="media/components.png" alt="UI components" width="700"/>
-</div>
+
+<img src="media/components.png" alt="Components" />
 
 ```ts
-import { components } from 'ansimax';
+import { components, color } from 'ansimax';
 
-// Tables with auto-sizing
 components.table([
-  ['Name',    'Status',     'Score'],
-  ['Alice',   '✓ active',   '95'],
-  ['Bob',     '⚠ pending',  '78'],
-], { header: true, borderStyle: 'rounded' });
-
-// Status messages
-components.status('success', 'All tests passed');
-components.status('error',   'Build failed');
-components.status('warn',    'Deprecation notice');
-
-// Badges
-components.badge('VERSION', 'v1.0.0');
-components.badge('BUILD', 'passing');
-
-// Interactive menus (with AbortSignal support)
-const choice = await components.menu([
-  'Install dependencies',
-  'Run tests',
-  'Deploy',
-  'Cancel',
-], { multiSelect: false });
+  ['Module',     'Status',                'Coverage'],
+  ['colors',     color.green('● ready'),  '100%'],
+  ['animations', color.green('● ready'),  '100%'],
+  ['loaders',    color.green('● ready'),  '100%'],
+], { borderStyle: 'rounded' });
+
+components.badge('VERSION', 'v1.1.1');
+components.badge('BUILD',   'passing');
 ```
 
----
-
 ### Timeline
-<div align="center">
-  <img src="media/timeline.png" alt="Timeline component" width="700"/>
-</div>
+
+<img src="media/timeline.png" alt="Timeline" />
 
 ```ts
 components.timeline([
   { label: 'Project init',   done: true,  time: '10:00' },
   { label: 'Build pipeline', done: true,  time: '10:15' },
-  { label: 'Run tests',      done: true,  time: '10:32' },
-  { label: 'Deploy to npm',  done: false, time: 'pending' },
+  { label: 'Run tests',      done: false, time: '10:32' },
+  { label: 'Deploy to npm',  done: false },
 ]);
 ```
 
----
-
 ### Loaders & Progress
-<div align="center">
-  <img src="media/loaders.png" alt="Loaders and progress bars" width="700"/>
-</div>
 
 ```ts
 import { loader } from 'ansimax';
 
-// Spinner — 11 built-in styles
-const stop = loader.spin('Processing...', {
-  type: 'dots',          // dots, line, arrow, bounce, star, moon, clock...
-  color: '#00ff88',
-  signal: ctrl.signal,   // AbortSignal aware
-});
-stop('Complete', true);
+// Spinner with success/failure
+const stop = loader.spin('Loading...', { color: '#bd93f9' });
+await work();
+stop('Done!', true);   // ✓ green icon
 
 // Animated progress bar
-await loader.progressAnimate(50, 'Installing', {
-  delay: 30,
-  color: '#48dbfb',
+await loader.progressAnimate(100, 'Downloading', {
+  color: '#50fa7b', delay: 25,
 });
 
-// Multi-task runner — sequential or parallel
+// Hierarchical tasks with parallel execution
 await loader.tasks([
-  { text: 'Fetch deps',  fn: async () => fetch() },
-  { text: 'Compile src', fn: async () => compile() },
-  { text: 'Run tests',   fn: async () => test() },
-], { parallel: false });
-
-// Countdown
-await loader.countdown(5, {
-  label: 'Launching in',
-  color: '#ffd700',
-});
+  { text: 'Build', fn: async () => build(), subtasks: [
+    { text: 'TypeScript', fn: async () => tsc() },
+    { text: 'Bundle',     fn: async () => bundle() },
+  ]},
+  { text: 'Test',  fn: async () => test() },
+], { parallel: true });
 ```
 
----
-
-### Pixel Art & Canvas
-<div align="center">
-  <img src="media/pixel_art.png" alt="Pixel art and canvas drawing" width="700"/>
-</div>
+### Animations
 
 ```ts
-import { images, createCanvas } from 'ansimax';
-
-// Built-in sprites: heart, star, smiley, pacman
-console.log(images.sprite('heart', { scale: 2 }));
-
-// Sprite transforms
-const flipped = images.flipHorizontal(images.sprites.heart.pixels);
-const rotated = images.rotate90(images.sprites.star.pixels);
-
-// Custom canvas drawing
-const canvas = createCanvas(30, 10);
-canvas.drawRect(0, 0, 30, 10, { r: 30, g: 30, b: 50 }, true);
-canvas.drawCircle(15, 5, 4, { r: 255, g: 200, b: 0 }, true);
-canvas.print();
-
-// Gradient rectangles — horizontal, vertical, diagonal, radial
-images.gradientRect({
-  width: 50, height: 8,
-  colors: ['#ff0080', '#7928ca', '#0070f3'],
-  style: 'radial',
+import { animate, gradient } from 'ansimax';
+
+await animate.typewriter('Welcome to the deployment wizard...', {
+  speed: 30,
+  colorFn: (t) => gradient(t, ['#bd93f9', '#ff79c6']),
 });
-```
 
----
+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(),
+], { timeout: 5000 });
+```
 
 ### Themes
-<div align="center">
-  <img src="media/themes.png" alt="Built-in themes" width="700"/>
-</div>
+
+<img src="media/themes.png" alt="Themes" />
 
 ```ts
-import { themes, color } from 'ansimax';
-
-// 8 built-in themes
-themes.use('dracula');    // 'dracula', 'nord', 'monokai', 'cyberpunk',
-                          // 'pastel', 'matrix', 'ocean', 'sunset', 'custom'
-
-const t = themes.current();
-console.log(color.hex(t.primary)('Primary text'));
-console.log(color.hex(t.error)('Error message'));
-console.log(color.hex(t.success)('Success!'));
-
-// Define your own theme
-themes.define('mytheme', {
-  primary:   '#00ff88',
-  secondary: '#0070f3',
-  accent:    '#ffd700',
-  error:     '#ff4757',
-  warning:   '#ffa502',
-  success:   '#2ed573',
-});
-```
+import { themes, createTheme } from 'ansimax';
 
----
+// Built-in themes
+themes.use('dracula');
+themes.primary('hello');
 
-### Get Started
-<div align="center">
-  <img src="media/get_started.png" alt="Get started" width="700"/>
-</div>
+// Listen for changes
+const off = themes.onChange((newTheme, oldTheme) => {
+  console.log(`Theme: ${oldTheme.name} → ${newTheme.name}`);
+});
+
+// Multi-tenant: each instance fully isolated
+const tenantA = createTheme('nord');
+const tenantB = createTheme('matrix');
+tenantA.register('custom', myDef);  // doesn't leak to tenantB
+```
 
 ---
 
-## 📚 Full Examples
+## 📚 Examples
 
-The `examples/` folder contains runnable demos:
+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 |
+|---|---|
+| `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
-# TypeScript demo (all modules)
-npx tsx examples/demo.ts
-
-# JavaScript demo (CommonJS)
-npm run build
-node examples/demo.js
-
-# Visual showcase (great for screenshots)
-npx tsx examples/showcase.ts
+# TypeScript examples
+npx tsx examples/10-everything.ts
 
-# Animations recording demo
-npx tsx examples/animations.ts
+# Plain JS — ESM
+node examples/all-in-one.mjs
 
-# Loaders recording demo
-npx tsx examples/loaders.ts
+# Plain JS — CommonJS
+node examples/all-in-one.cjs
 ```
 
 ---
 
 ## 🎯 Use Cases
 
-- **Professional CLIs** — build tools that feel polished, not bare
-- **Build outputs** — replace boring `npm run build` logs with status timelines
-- **Interactive installers** — multi-select menus with theme support
-- **Live dashboards** — auto-refreshing frame engine with diff rendering
-- **Terminal games** — pixel art canvas + animation engine
-- **Dev tooling** — coverage reports, deployment trackers, status panels
-- **Educational tools** — animated explainers right in the terminal
+- **CLI installers & scaffolders** — beautiful first-run experience (create-react-app, create-next-app style)
+- **DevOps tools** — deployment dashboards, build pipelines, health monitors
+- **Dev experience** — better test runners, lint output, error formatting
+- **Interactive prompts** — menus, confirmations, multi-select wizards
+- **Data exploration** — tables, trees, charts for terminal-first workflows
+- **Status reporters** — real-time progress, multi-task orchestration
+- **ASCII intros** — game launchers, demo splash screens, login banners
 
 ---
 
 ## ⚙️ Configuration
 
+Global config affects every module that respects it (colors, themes, animation speed, etc.):
+
 ```ts
-import { configure } from 'ansimax';
+import { configure, getConfig, withConfig, onConfigKeyChange } from 'ansimax';
 
 configure({
-  colorMode: 'truecolor',      // 'basic' | '256' | 'truecolor'
-  animationSpeed: 'normal',    // 'slow' | 'normal' | 'fast'
+  colorMode:      'auto',     // 'none' | 'basic' | '256' | 'truecolor' | 'auto'
+  animationSpeed: 'normal',   // 'slow' | 'normal' | 'fast' | 'instant'
+  theme:          'dracula',  // any registered theme
+  reducedMotion:  false,
 });
 
-// Or override at runtime
-import { setNoColor } from 'ansimax';
-setNoColor(true);  // disable all colors (CI environments)
-```
+// Listen for changes (per-key — avoids over-firing)
+const off = onConfigKeyChange('theme', (newTheme, oldTheme) => {
+  console.log(`Theme: ${oldTheme} → ${newTheme}`);
+});
 
-Ansimax also respects the standard `NO_COLOR` environment variable and auto-detects non-TTY stdout (pipes, CI logs).
+// Temporary override + auto-restore on completion or throw
+await withConfig({ animationSpeed: 'fast' }, async () => {
+  await runDemo();
+});
+
+// Strict mode catches config typos
+configure({ unknwnKey: 'x' }, { strict: true });  // throws RangeError
+```
 
 ---
 
 ## 🛣️ Roadmap
 
-Ansimax is being built toward a full **terminal rendering platform**. Here's what's done and what's next:
+Ansimax is being built toward a **full terminal rendering platform** — a Node-native answer to what Python developers get from `rich` + `textual` combined, with Node-specific improvements where it matters.
 
-### ✅ Phase 1 — Core foundation (current)
+The roadmap intentionally targets — and aims to surpass — gaps that even mature Python TUI libraries haven't fully solved: live-diff renderers, animated gradients, terminal image protocols, and a true reactive layer.
 
-- [x] **Styling engine** — ANSI 16 / 256 / truecolor with auto-fallback
-- [x] **Hex + RGB helpers** with clamping and validation
-- [x] **`NO_COLOR` env support** + non-TTY auto-detection
-- [x] **`AbortSignal` integration** across animations and loaders
-- [x] **`compose()` style stacking** with single-reset emission
+### ✅ Phase 1 — Core foundation
+- [x] Styling engine — ANSI 16 / 256 / truecolor with adaptive fallback
+- [x] Hex + RGB helpers with clamping and validation
+- [x] `NO_COLOR` / `FORCE_COLOR` env support + non-TTY auto-detection
+- [x] `AbortSignal` integration across animations and loaders
+- [x] `compose()` style stacking with single-reset emission
+- [x] Bounded LRU escape cache (512 entries, packed-RGB keyed)
+- [x] Custom preset registry (`registerPreset`, `listPresets`)
 
 ### ✅ Phase 2 — Gradient engine
-
 - [x] Linear gradients (multi-stop)
-- [x] Rainbow presets
+- [x] Rainbow + 6 built-in presets
 - [x] Radial gradients (in `gradientRect`)
 - [x] Diagonal gradients
-- [ ] **Animated gradients** (color flow over time)
+- [x] Arbitrary-angle gradients
+- [x] Bayer 4×4 dithering for smooth tonal transitions
+- [x] Single-stop UX (CSS-style behavior)
+- [ ] **Animated gradients** (color flow over time, infinite loops)
+- [ ] **Gradient interpolation curves** (linear / ease-in / ease-out / cubic-bezier)
+- [ ] **Conic gradients** (radial sweep)
 
 ### 🟡 Phase 3 — ASCII engine
-
 - [x] Block fonts (`big`, `small`)
-- [x] Banner with gradient + alignment
+- [x] Banner with gradient + alignment + per-char coloring
 - [x] Box drawing (6 border styles)
-- [ ] **Image → ASCII** converter (with edge detection)
+- [x] Divider with style variants
+- [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
+- [ ] **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)
 
 ### ✅ Phase 4 — Terminal UI primitives
-
-- [x] Tables (irregular rows, jagged data)
+- [x] Tables (irregular rows, multi-line cells, ANSI-aware)
 - [x] Boxes with multiple styles
-- [x] Status messages + badges
+- [x] Status messages + badges (with border option)
 - [x] Timelines with done/pending states
 - [x] Interactive menus (single + multi-select)
-- [ ] **Trees** (collapsible, lazy-loadable)
-- [ ] **Panels** (split layouts)
+- [x] Columns layout (truncate/wrap overflow)
+- [x] Sections (gradient headers with auto-width)
+- [x] Trees (collapsible, max-depth, cycle-safe)
+- [ ] **Panels** (split layouts: hsplit, vsplit)
 - [ ] **Layouts** (flexbox-style positioning)
+- [ ] **Grid system** (CSS Grid-inspired column/row spans)
+- [ ] **Markdown rendering** (headings, lists, code blocks, tables)
+- [ ] **Syntax highlighting** (built-in language grammars)
+- [ ] **JSON/YAML pretty-printing** (with depth limit + collapse)
+- [ ] **Logging integration** (drop-in replacement for `console`/`pino`/`winston` transports)
 
 ### ✅ Phase 5 — Cursor & screen control
-
-- [x] Cursor visibility, save/restore, positioning
+- [x] Cursor visibility, save/restore, positioning, line navigation
 - [x] Screen clearing (line, area, full)
-- [x] Try/finally cleanup guarantees
+- [x] Reference-counted cursor (overlapping calls safe)
+- [x] Crash-safe restore (exit/SIGINT/SIGTERM handlers)
+- [x] Terminal hyperlinks (OSC 8)
+- [x] Window title (OSC 2)
+- [x] Bell (BEL)
 
 ### ✅ Phase 6 — Animation engine
-
 - [x] Typewriter, fadeIn, fadeOut, slide, pulse, wave, glitch, reveal
 - [x] All `AbortSignal`-aware
 - [x] `reducedMotion` mode for accessibility
-- [x] **Frame morph** (text → text interpolation)
+- [x] Frame morph (text → text interpolation, cinematic decryption)
+- [x] `parallel()` with timeout
+- [x] Signal propagation to nested animations
+- [ ] **Easing functions library** (24 standard easings: cubic, elastic, bounce, back)
+- [ ] **Animation composition** (`parallel + sequence + delay` DSL)
+- [ ] **Spring physics** animations (`react-spring` style)
+- [ ] **Tween engine** (interpolate any value type)
 
 ### 🟡 Phase 7 — Progress ecosystem
-
 - [x] Spinners (11 styles) with color + AbortSignal
 - [x] Animated progress bars
 - [x] Multi-task runners (sequential + parallel)
 - [x] Countdown timers
-- [ ] **Nested progress** (parent + children with rollup)
-- [ ] **ETA estimation** (rolling average + projection)
-- [ ] **Live refresh** without flicker (diff renderer)
+- [x] Multi-spinner manager (stacked concurrent spinners)
+- [x] Hierarchical tasks (parent + subtasks rollup)
+- [ ] **Live ETA estimation** (rolling average + Kalman filter projection)
+- [ ] **Live refresh diff renderer** (no flicker, only redraw changed lines)
+- [ ] **Progress groups** (named groups with shared theme)
+- [ ] **Throughput meters** (bytes/sec, ops/sec with auto-scaling units)
 
 ### 🟡 Phase 8 — Capability detection
-
 - [x] TTY detection (auto-disable in pipes/CI)
-- [x] `NO_COLOR` env support
-- [ ] **Color depth detection** (16 / 256 / truecolor)
-- [ ] **Unicode width detection** (CJK, emoji)
-- [ ] **Terminal capability database** (xterm, iTerm, Windows Terminal...)
-
-### 🔴 Phase 9 — Advanced rendering
-
-- [ ] **Diff renderer** (only redraw changed regions)
+- [x] `NO_COLOR` / `FORCE_COLOR` env support
+- [x] Color depth detection (16 / 256 / truecolor)
+- [x] CI provider detection (GitHub Actions, CircleCI, GitLab, Buildkite, Drone, Travis)
+- [x] Terminal program detection (iTerm, vscode, WezTerm, Hyper, Apple_Terminal)
+- [x] Windows Terminal detection (`WT_SESSION`)
+- [ ] **Unicode width detection** (CJK halfwidth/fullwidth, emoji clusters, ZWJ sequences)
+- [ ] **Image protocol detection** (Sixel, iTerm inline images, Kitty graphics protocol)
+- [ ] **Terminal capability database** (full xterm capability flags + version probes)
+- [ ] **Font metrics detection** (cell width/height for pixel-accurate layouts)
+
+### 🟡 Phase 9 — Advanced rendering
+- [x] Dirty-rectangle canvas (only redraw changed pixels)
+- [x] Bounded LRU caches (escape sequences, render cache, ANSI cache)
+- [x] Drift-corrected timing (animations stay locked to wall-clock)
+- [ ] **Diff renderer** (line-level damage tracking for full UIs)
 - [ ] **Virtual buffer** (compose UI without writing to stdout)
-- [ ] **Z-index / layering**
-- [ ] **Mouse event support**
+- [ ] **Z-index / layering** (overlap panels with priority)
+- [ ] **Mouse event support** (click, hover, drag, scroll wheel)
+- [ ] **Keyboard event abstraction** (arrow keys, modifiers, key sequences, dead keys)
+- [ ] **Full TUI framework** (reactive components — Textual-equivalent for Node)
 
 ### 🔴 Phase 10 — Terminal charts
-
-- [ ] Bar charts (horizontal + vertical)
+- [ ] Bar charts (horizontal + vertical, grouped, stacked)
 - [ ] Line charts (with braille for sub-character resolution)
-- [ ] Sparklines
-- [ ] Heatmaps
-- [ ] Real-time streaming charts
-
-### 🔴 Phase 11 — Plugin system
-
+- [ ] Sparklines (inline mini-charts for status bars)
+- [ ] Area charts (filled with gradients)
+- [ ] Heatmaps (color-mapped 2D grids)
+- [ ] Pie / donut charts (with percentage labels)
+- [ ] Scatter plots
+- [ ] Box plots / candlestick charts
+- [ ] Real-time streaming charts (live data feed with rolling window)
+- [ ] **Plot composer** (multi-chart dashboards with shared axes)
+
+### 🔴 Phase 11 — Forms & Input
+- [ ] Text input prompts (with autocomplete + history)
+- [ ] Password prompts (masked, strength meter)
+- [ ] Confirm dialogs (yes/no with default highlight)
+- [ ] Numeric input (with min/max validation)
+- [ ] Date/time pickers (calendar widget)
+- [ ] File picker (filesystem navigator)
+- [ ] Form composer (multi-field with validation + error display)
+- [ ] **Wizard flows** (multi-step forms with back/forward, progress indicator)
+
+### 🔴 Phase 12 — Image & media
+- [ ] Sixel image rendering (xterm, mlterm, WezTerm)
+- [ ] iTerm2 inline images (base64 protocol)
+- [ ] Kitty graphics protocol
+- [ ] PNG/JPEG → terminal image (auto-detect best protocol)
+- [ ] Video preview (frame-by-frame at low FPS)
+- [ ] QR code generation (with size + ECC level options)
+- [ ] Bar code generation (Code 128, EAN-13)
+
+### 🔴 Phase 13 — Plugin system
 - [ ] Plugin API for custom components
 - [ ] Theme marketplace
-- [ ] Custom font registration
+- [ ] Custom font registration via npm packages
 - [ ] Community animations registry
+- [ ] Capability provider interface (plug in custom detectors)
+- [ ] Renderer plugins (swap stdout for any writable stream)
+
+### 🔴 Phase 14 — Reactivity layer (TUI framework)
+- [ ] **Component lifecycle** (mount/unmount/update hooks)
+- [ ] **Reactive state** (auto re-render on data change, signals or hooks)
+- [ ] **Virtual DOM diffing** (line-level updates)
+- [ ] **Event bus** (component communication)
+- [ ] **Application loop** (single render tree with full lifecycle)
+- [ ] **Routing** (multi-screen apps with history)
+- [ ] **DevTools integration** (inspect component tree, mark changed nodes)
+- [ ] **CSS-in-TS styling** (scoped styles per component)
 
 **Legend:** ✅ Complete · 🟡 Partial · 🔴 Planned
 
@@ -524,20 +599,25 @@ Ansimax is being built toward a full **terminal rendering platform**. Here's wha
 
 ## 🧪 Testing
 
-Ansimax ships with **750+ tests** and **100% line coverage**:
-
 ```bash
-npm test                   # Run all tests
-npm run test:coverage      # Coverage report
-npm run typecheck          # Strict TypeScript check
+npm test              # Run all 1700+ tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
 ```
 
+Coverage targets:
+- Statements: **98%**
+- Branches: **95%**
+- Functions: **99%**
+- Lines: **99%**
+
 ---
 
 ## 🛠️ Requirements
 
-- Node.js **>= 18.0.0**
-- A terminal with ANSI escape support (every modern terminal)
+- **Node.js** ≥ 18
+- **TypeScript** ≥ 5.0 (for typed consumption — optional)
+- **Terminal** with truecolor support recommended (Windows Terminal, iTerm2, WezTerm, Kitty, modern xterm). Gracefully degrades to 256 / 16 / no-color.
 
 ---
 
@@ -546,84 +626,128 @@ npm run typecheck          # Strict TypeScript check
 ```
 ansimax/
 ├── src/
-│   ├── colors/          # Color system, gradients, compose, NO_COLOR
-│   ├── animations/      # 7 animation effects with AbortSignal
-│   ├── ascii/           # ASCII fonts, boxes, dividers, banners
-│   ├── components/      # Tables, menus, timelines, badges
-│   ├── loaders/         # Spinners, progress, tasks, countdowns
-│   ├── frames/          # Frame engine + morph + presets
-│   ├── images/          # Pixel art, sprites, canvas API
-│   ├── themes/          # 8 built-in themes + custom
-│   ├── utils/           # ANSI helpers, color math, string utils
-│   └── index.ts         # Public API barrel
-├── examples/            # Runnable demos (TS + JS)
-├── media/               # README screenshots and videos
-└── dist/                # Build output (CJS + ESM + types)
+│   ├── colors/         Color rendering + gradient engine
+│   ├── themes/         Theme system + 8 built-ins
+│   ├── ascii/          Banners, boxes, fonts
+│   ├── animations/     Typewriter, fade, slide, pulse, wave, glitch, reveal
+│   ├── loaders/        Spinners, progress, tasks, multi-loader
+│   ├── frames/         Sequenced playback + live renderer + morph
+│   ├── components/     Tables, badges, status, timelines, menus
+│   ├── images/         Sprites, canvas, dithered gradients
+│   ├── trees/          Tree builder + algorithms
+│   ├── utils/          ANSI primitives + helpers
+│   └── configure.ts    Global config + subscribers
+├── examples/           10 examples (TS) + 2 (JS — ESM & CJS) — all features covered
+└── __tests__/          16 test suites, 1700+ tests
 ```
 
 ---
 
+## 📝 Changelog
+
+### 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.
+
+**Highlights:**
+
+- 🌳 **New `trees` module** — builder API + plain-data API, 4 styles, cycle detection, algorithms (`walk`, `find`, `count`, `map`, `filter`)
+- ⚙️ **`configure.ts` upgrades** — `onConfigKeyChange`, `pauseListeners` / `resumeListeners`, `withConfig()`, strict mode
+- 🎨 **Themes** — per-instance isolation (multi-tenant safe), `tryUse`, `onChange` listeners, `unregister`, `bg*` helpers, dynamic `style(name)` accessor
+- 🌈 **Colors** — `registerPreset` / `listPresets`, bounded LRU escape cache, NaN/Infinity-safe RGB, single-stop gradient UX
+- 🖼️ **Images** — `Pixel` / `PixelGrid` exported, deep-clone `canvas.pixels`, defensive coords, ANSI cache LRU bounded
+- 🔠 **ASCII** — `hasFont`, `measure`, `stream` with AbortSignal, grapheme-aware
+- 🎞️ **Frames** — ref-counted cursor, crash-safe restore, `repeat: 0` = infinite, fps cap at 60, drift correction
+- 🧱 **Components** — `menu([])` returns `MENU_CANCELLED` (no throw), defensive numeric inputs everywhere
+- 🛠️ **Utils** — `setTitle`, `link` (OSC 8 hyperlinks), `bell`, `safeJson` (BigInt + circular), `once`, `escapeRegex`, `padBoth`, `nextTick`, `memoize` with custom keyFn, `debounce` with `maxWait`, throttled `onResize`
+- 🧪 **Tests** — ~1700+ tests across 16 suites, all green, ~98% coverage
+
+See [CHANGELOG.md](CHANGELOG.md) for the complete version history with per-module breakdowns.
+
+### v1.0.0 — Initial release
+
+- Core modules: `color`, `animate`, `ascii`, `loader`, `frames`, `components`, `themes`, `images`, `configure`
+- TypeScript types exported, ESM + CJS dual build
+- Adaptive color rendering (NO_COLOR / FORCE_COLOR / TTY detection)
+- `AbortSignal` support across all blocking APIs
+- 750+ tests, 85%+ coverage
+
+---
+
 ## 🤝 Contributing
 
-Contributions are welcome! To get started:
+Contributions welcome! Areas where help is especially appreciated:
 
-1. **Fork** the repo
-2. Create a branch: `git checkout -b feature/amazing-thing`
-3. Add tests for your changes (the bar is 100% coverage)
-4. Commit: `git commit -m 'Add: amazing thing'`
-5. Push: `git push origin feature/amazing-thing`
-6. Open a Pull Request
+- New animation presets (easing, spring physics)
+- Additional ASCII fonts (figlet `.flf` parser)
+- Terminal capability database entries
+- Translations (es, fr, de, ja, ...)
+- Real-world example apps
+- Chart implementations (Phase 10)
 
-Make sure:
-- All tests pass: `npm test`
-- TypeScript is happy: `npm run typecheck`
-- Code follows the existing style
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ---
 
 ## 🐛 Reporting Issues
 
-Found a bug or have a feature idea? Open an [issue](https://github.com/Brashkie/ansimax/issues) — please include a minimal reproduction.
+Found a bug? Have a feature request? [Open an issue](https://github.com/Brashkie/ansimax/issues/new).
+
+For security disclosures, please email [security@brashkie.dev](mailto:security@brashkie.dev) instead of opening a public issue.
 
 ---
 
 ## ⭐ Support
 
-If you like Ansimax:
+If Ansimax saves you time, please star the repo on [GitHub](https://github.com/Brashkie/ansimax) — it helps the project grow and accelerates the roadmap.
+
+---
 
-- ⭐ **Star the repo** — helps others discover the project
-- 🐛 **Report bugs** — open an [issue](https://github.com/Brashkie/ansimax/issues)
-- 🚀 **Use it in your CLI projects** — that's the best support there is
-- 📢 **Share it** — tweet, blog, mention it to a colleague who builds CLIs
-- 💬 **Spread the word** — tag your CLI with `#ansimax` so others can find inspiration
+## 👨‍💻 Author
 
-This helps the project grow and gives momentum to add the planned features faster.
+**Brashkie** · [@Brashkie](https://github.com/Brashkie)
 
 ---
 
-## 📝 Changelog
+## 🎬 Full showcase
 
-See [CHANGELOG.md](CHANGELOG.md) for the version history.
+<div align="center">
 
----
+<img src="media/all-ansimax.gif" alt="Ansimax full showcase — everything in action" width="720"/>
 
-## 👨‍💻 Author
+_All features in action — typewriter, gradients, ASCII banners, trees, tables, spinners, themes, and pixel art_
 
-**Brashkie** · [@Brashkie](https://github.com/Brashkie)
+</div>
 
 ---
 
 ## 📜 License
 
-[MIT](LICENSE) © 2026 Brashkie
+[Apache License 2.0](LICENSE) © 2026 Brashkie
+
+Ansimax is licensed under the **Apache License, Version 2.0** — a permissive license that allows commercial use, modification, distribution, and includes an explicit patent grant. See the [LICENSE](LICENSE) file for the full text.
 
 ---
 
-**Keywords:** cli, terminal, ansi, colors, gradients, animation, spinner, ascii, ascii-art, pixel-art, progress-bar, loader, components, table, banner, theme, typescript, nodejs, zero-dependencies
+**Keywords:** cli, terminal, ansi, colors, gradients, animation, spinner, ascii, ascii-art, pixel-art, progress-bar, loader, components, table, banner, theme, tree, trees, tui, typescript, nodejs, zero-dependencies, chalk, ora, boxen, figlet, inquirer
 
 ---
 
 <div align="center">
-  <p>Built with ❤️ and TypeScript</p>
-  <p>If Ansimax helps you ship better CLIs, give it a ⭐ on GitHub!</p>
+
+**Built with ❤️ and TypeScript**
+
+If Ansimax helps you ship better CLIs, give it a ⭐ on [GitHub](https://github.com/Brashkie/ansimax)!
+
 </div>