\n\n
![\"Ansimax](\"media/ansimax.png\")
\n\n### The ultimate CLI rendering library for Node.js\n\n_Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_\n\n[](LICENSE)\n[](https://www.npmjs.com/package/ansimax)\n[](tsconfig.json)\n[](#testing)\n[](#testing)\n[](#)\n[](#requirements)\n[](#)\n\n**English** · [Español](README.es.md)\n\n
![\"Ansimax](\"media/animations.gif\")
\n ![\"Ansimax](\"media/loaders.gif\")
\n ![\"Colors](\"media/colors.png\")
\n\n```js\nimport { color, gradient, rainbow } from 'ansimax';\n\n// Basic colors\nconsole.log(color.red('red'), color.green('green'), color.blue('blue'));\n\n// Style modifiers\nconsole.log(color.bold('bold'), color.italic('italic'), color.underline('underlined'));\n\n// Multi-stop gradient\nconsole.log(gradient('fire to ocean', ['#ff6b6b', '#feca57', '#48dbfb']));\n\n// Built-in rainbow preset\nconsole.log(rainbow('built-in rainbow preset'));\n```\n\n### Animated Gradients (v1.2.0)\n\n![\"Animated](\"media/animated-gradients.gif\")
\n\n```js\nimport { animateGradient, sleep } from 'ansimax';\n\n// Color flow animation — runs until you call stop()\nconst ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd'], {\n duration: 2000, // ms per cycle\n fps: 30,\n direction: 'forward', // or 'reverse'\n});\n\nawait sleep(3000);\nctrl.stop();\n\n// v1.2.2: await directly (no .done needed)\nawait animateGradient('Done!', ['#50fa7b', '#bd93f9'], {\n infinite: false, cycles: 2, duration: 800,\n});\n```\n\n### Easing Curves (v1.2.0)\n\n![\"Easing](\"media/easing_curves.png\")
\n\n```js\nimport { gradient } from 'ansimax';\n\nconst stops = ['#ff79c6', '#bd93f9', '#8be9fd'];\n\n// Five built-in easings + custom function support\nconsole.log(gradient('hello world', stops, { easing: 'linear' }));\nconsole.log(gradient('hello world', stops, { easing: 'ease-in' }));\nconsole.log(gradient('hello world', stops, { easing: 'ease-out' }));\nconsole.log(gradient('hello world', stops, { easing: 'ease-in-out' }));\nconsole.log(gradient('hello world', stops, { easing: 'cubic-bezier' }));\n\n// Or pass your own easing function (t → eased t, both in [0,1])\nconsole.log(gradient('hello world', stops, { easing: (t) => t * t * t }));\n```\n\n### Conic Gradients (v1.2.0)\n\n![\"Conic](\"media/conic_gradients.png\")
\n\n```js\nimport { gradientRect } from 'ansimax';\n\n// Radial sweep around center — rainbow wheel\nconsole.log(gradientRect({\n width: 30, height: 15,\n colors: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff00ff', '#ff0000'],\n style: 'conic',\n startAngle: 0, // rotation angle in degrees\n dither: 'bayer',\n}));\n```\n\n### Reusable Gradients (v1.2.3)\n\n![\"Reusable](\"media/reusable-gradients.gif\")
\n\n```js\nimport { createGradient, reverseGradient, ascii } from 'ansimax';\n\n// Pre-resolve hex stops once — significantly faster for repeated use\nconst fire = createGradient(['#ff5555', '#ffb86c', '#f1fa8c']);\n\nconsole.log(fire('First line'));\nconsole.log(fire('Second line'));\nconsole.log(fire('Third line'));\n\n// Use as a colorFn for banners — same ColorFn signature\nconsole.log(ascii.banner('FIRE', { colorFn: fire }));\n\n// v1.2.4: inspect metadata\nconsole.log('Stops:', fire.stops); // → ['#ff5555', '#ffb86c', '#f1fa8c']\nconsole.log('Resolved:', fire.resolvedStops); // → [{r:255,g:85,b:85}, ...]\n\n// v1.2.4: reverse a gradient (preserves default options)\nconst ice = reverseGradient(fire);\nconsole.log(ice('Cool side'));\n\n// Per-call options still work — perfect for animation\nfor (let p = 0; p < 1; p += 0.05) {\n process.stdout.write('\\r' + fire('flowing', { phase: p }));\n await new Promise((r) => setTimeout(r, 50));\n}\n```\n\n### ASCII Art\n\n![\"ASCII](\"media/ascii_art.png\")
\n\n```js\nimport { ascii, gradient } from 'ansimax';\n\nconsole.log(ascii.banner('HELLO', {\n font: 'big',\n align: 'center',\n colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9']),\n}));\n\nconsole.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));\n```\n\n### Image → ASCII (v1.2.5)\n\n![\"Original](\"media/image-ascii-original.png\")
\n![\"Monochrome](\"media/image-ascii-1.png\")
![\"Color](\"media/image-ascii-2.png\")
![\"Edge](\"media/image-ascii-3.png\")
![\"Face](\"media/image-ascii-4.png\")
![\"Figlet](\"media/figlet_fonts.png\")
\n\n```js\nimport { readFileSync } from 'node:fs';\nimport { parseFiglet, ascii, gradient } from 'ansimax';\n\n// Download fonts from http://www.figlet.org/fontdb.cgi\nconst font = parseFiglet(readFileSync('./standard.flf', 'utf8'));\n\nconsole.log(ascii.figletText('Hello!', font));\n\n// With color\nconsole.log(ascii.figletText('STYLE', font, {\n colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),\n}));\n```\n\n### Trees\n\n![\"Trees\"](\"media/trees.png\")
\n\n```js\nimport { tree, color } from 'ansimax';\n\nconst project = tree({ label: 'my-app', icon: '📦', color: color.bold });\nconst src = project.add({ label: 'src', icon: '📁' });\nsrc.addLeaf({ label: 'index.ts', icon: '📄' });\nsrc.addLeaf({ label: 'app.ts', icon: '📄' });\n\nconsole.log(project.render({\n style: 'rounded',\n palette: [color.cyan, color.green, color.magenta],\n guideColor: color.dim,\n}));\n```\n\n### Pixel Art & Canvas\n\n![\"Pixel](\"media/pixel_art.png\"){kind=tracking}
\n\n```js\nimport { images, createCanvas, gradientRect, SPRITES } from 'ansimax';\n\n// Built-in sprite\nconsole.log(images.sprite('heart'));\n\n// Smooth gradient with Bayer dither\nconsole.log(gradientRect({\n width: 50, height: 4,\n colors: ['#ff6b6b', '#feca57', '#48dbfb'],\n dither: 'bayer',\n}));\n\n// Custom canvas\nconst c = createCanvas(40, 10);\nc.fill({ r: 18, g: 18, b: 38 });\nc.drawCircle(20, 5, 4, { r: 255, g: 200, b: 0 }, true);\nconst starSprite = SPRITES.star;\nif (starSprite) c.drawSprite(2, 2, starSprite.pixels);\nc.print();\n```\n\n### Components\n\n![\"Components\"](\"media/components.png\")
\n\n```js\nimport { components, color } from 'ansimax';\n\nconsole.log(components.table([\n ['Module', 'Status', 'Coverage'],\n ['colors', color.green('● ready'), '100%'],\n ['animations', color.green('● ready'), '100%'],\n ['loaders', color.green('● ready'), '100%'],\n], { borderStyle: 'rounded' }));\n\nconsole.log(components.badge('VERSION', 'v1.7.0'));\nconsole.log(components.badge('BUILD', 'passing'));\n```\n\n### Timeline\n\n![\"Timeline\"](\"media/timeline.png\")
\n\n```js\nimport { components } from 'ansimax';\n\nconsole.log(components.timeline([\n { label: 'Project init', done: true, time: '10:00' },\n { label: 'Build pipeline', done: true, time: '10:15' },\n { label: 'Run tests', done: false, time: '10:32' },\n { label: 'Deploy to npm', done: false },\n]));\n```\n\n### Loaders & Progress\n\n![\"Loaders](\"media/loaders.png\")
\n\n```js\nimport { loader, sleep } from 'ansimax';\n\n// Spinner with success/failure\nconst stop = loader.spin('Loading...', { color: '#bd93f9' });\nawait sleep(1500);\nstop('Done!', true); // ✓ green icon\n\n// Animated progress bar\nawait loader.progressAnimate(100, 'Downloading', {\n color: '#50fa7b', delay: 25,\n});\n\n// Hierarchical tasks with parallel execution\nawait loader.tasks([\n {\n text: 'Build',\n fn: async () => await sleep(500),\n subtasks: [\n { text: 'TypeScript', fn: async () => await sleep(800) },\n { text: 'Bundle', fn: async () => await sleep(600) },\n ],\n },\n { text: 'Test', fn: async () => await sleep(700) },\n], { parallel: true });\n```\n\n### Animations\n\n![\"Animations](\"media/animations-1.gif\")
\n\n```js\nimport { animate, gradient, sleep } from 'ansimax';\n\nawait animate.typewriter('Welcome to the deployment wizard...', {\n speed: 30,\n colorFn: (t) => gradient(t, ['#bd93f9', '#ff79c6']),\n});\n\nawait animate.fadeIn('Loading complete', { duration: 600 });\n\n// Race steps against a timeout — never hang\nawait animate.parallel([\n async () => await sleep(500), // simulated network check\n async () => await sleep(700), // simulated database check\n async () => await sleep(400), // simulated auth check\n], { timeout: 5000 });\n```\n\n### Themes\n\n![\"Themes\"](\"media/themes.png\")
\n\n```js\nimport { themes, createTheme } from 'ansimax';\n\n// Built-in themes\nthemes.use('dracula');\nconsole.log(themes.primary('hello'));\n\n// Listen for changes\nconst off = themes.onChange((newTheme, oldTheme) => {\n console.log(`Theme: ${oldTheme.name} → ${newTheme.name}`);\n});\n\n// Multi-tenant: each instance fully isolated\nconst tenantA = createTheme('nord');\nconst tenantB = createTheme('matrix');\n\n// Define a custom theme and register it ONLY in tenantA\ntenantA.register('custom', {\n name: 'Custom',\n primary: '#ff5e5e',\n secondary: '#5e5eff',\n accent: '#5eff5e',\n success: '#10b981',\n warning: '#fbbf24',\n error: '#ef4444',\n info: '#06b6d4',\n muted: '#6b7280',\n bg: '#1e293b',\n surface: '#334155',\n text: '#f1f5f9',\n gradient: ['#ff5e5e', '#5eff5e', '#5e5eff'],\n});\n\nconsole.log('tenantA themes include custom?', tenantA.list().includes('custom'));\nconsole.log('tenantB themes include custom?', tenantB.list().includes('custom'));\n// ↑ false — full isolation\n```\n\n### Panels — Split Layouts (v1.3.0)\n\n![\"Panels](\"media/panels.png\")
\n\n```js\nimport { panels, ascii } from 'ansimax';\n\n// Side-by-side columns\nconst left = ascii.box('Sidebar', { borderStyle: 'rounded' });\nconst right = ascii.box('Main view', { borderStyle: 'rounded' });\n\nconsole.log(panels.vsplit([left, right], { gap: 2, align: 'center' }));\n\n// Vertical stacking\nconsole.log(panels.hsplit([\n '── Application ──',\n ascii.box('Body content'),\n '── Footer ──',\n], { gap: 1, align: 'center' }));\n\n// Nested — sidebar + main inside an app shell\nconsole.log(panels.hsplit([\n '── My App ──',\n panels.vsplit([\n ascii.box('Sidebar', { width: 20 }),\n ascii.box('Main', { width: 40 }),\n ], { gap: 2 }),\n '── End ──',\n]));\n```\n\n### JSON Pretty-print (v1.3.0)\n\n![\"JSON](\"media/json_pretty.png\")
\n\n```js\nimport { json } from 'ansimax';\n\n// Colored, depth-aware pretty-printing\nconsole.log(json.pretty({\n name: 'ansimax',\n version: '1.3.0',\n features: ['colors', 'gradients', 'panels'],\n stats: { tests: 2000, coverage: 0.98 },\n active: true,\n}));\n\n// Depth limit — collapses deep objects to {...}\nconst deeplyNested = { a: { b: { c: { d: { e: 'too deep' } } } } };\nconsole.log(json.pretty(deeplyNested, { maxDepth: 2 }));\n\n// Item limit — huge arrays show \"... (N more)\"\nconst largeArray = Array.from({ length: 50 }, (_, i) => `item_${i}`);\nconsole.log(json.pretty(largeArray, { maxItems: 5 }));\n\n// Circular references handled gracefully\nconst obj = { name: 'foo' };\nobj.self = obj;\nconsole.log(json.pretty(obj)); // → \"self\": [Circular]\n```\n\n---\n\n## 📖 Documentation\n\nThe [`docs/`](./docs) folder contains comprehensive examples for every module:\n\n| Document | Description |\n|---|---|\n| [`docs/README.md`](./docs/README.md) | Documentation index — start here |\n| [`docs/examples-ts.md`](./docs/examples-ts.md) | 33 TypeScript examples (3 per module × 11 modules) |\n| [`docs/examples-mjs.md`](./docs/examples-mjs.md) | 33 JavaScript ESM examples |\n| [`docs/examples-cjs.md`](./docs/examples-cjs.md) | 33 JavaScript CommonJS examples |\n| [`docs/showcase.md`](./docs/showcase.md) | Complete demo app combining every module |\n\nEvery example is **copy-paste runnable** with realistic, mid-complexity scenarios — not just one-liners.\n\n---\n\n## 📚 Examples\n\nEleven production-grade examples ship in the npm package and are runnable directly. Find them in [`/examples`](./examples) once you install:\n\n| File | What it demonstrates |\n|---|---|\n| `01-quick-smoke.ts` | Quick smoke test — verifies every major import works |\n| `02-colors-gradients.ts` | Every color fn, gradient types, presets, compose, chain API |\n| `03-ascii-banners.ts` | Banners (`big`/`small`), 6 box styles, dividers, logo composer |\n| `04-trees.ts` | Tree builder + plain-data API, 4 styles, palettes, algorithms (walk/find/map/filter) |\n| `05-components.ts` | Tables, badges, status, sections, columns, timelines, progress bars |\n| `06-pixel-art.ts` | Sprites, custom canvas, gradient rects with dither, transforms (flip/rotate) |\n| `07-animations.ts` | typewriter, fadeIn/Out, slide, pulse, wave, glitch, reveal |\n| `08-loaders.ts` | spinner styles, animated progress, hierarchical tasks, countdown |\n| `09-themes.ts` | All 8 built-in themes, listeners, custom theme registration, per-instance isolation |\n| `10-everything.ts` | Comprehensive showcase — every module exercised in one cohesive demo |\n| `all-in-one.mjs` | Full demo in **ESM** (plain JS with `import`) — no TypeScript needed |\n| `all-in-one.cjs` | Full demo in **CommonJS** (plain JS with `require`) — no TypeScript needed |\n\nRun any example with:\n```bash\n# TypeScript examples\nnpx tsx examples/10-everything.ts\n\n# Plain JS — ESM\nnode examples/all-in-one.mjs\n\n# Plain JS — CommonJS\nnode examples/all-in-one.cjs\n```\n\n---\n\n## 🎯 Use Cases\n\n- **CLI installers & scaffolders** — beautiful first-run experience (create-react-app, create-next-app style)\n- **DevOps tools** — deployment dashboards, build pipelines, health monitors\n- **Dev experience** — better test runners, lint output, error formatting\n- **Interactive prompts** — menus, confirmations, multi-select wizards\n- **Data exploration** — tables, trees, charts for terminal-first workflows\n- **Status reporters** — real-time progress, multi-task orchestration\n- **ASCII intros** — game launchers, demo splash screens, login banners\n\n---\n\n## ⚙️ Configuration\n\nGlobal config affects every module that respects it (colors, themes, animation speed, etc.):\n\n```js\nimport { configure, getConfig, withConfig, onConfigKeyChange } from 'ansimax';\n\nconfigure({\n colorMode: 'auto', // 'none' | 'basic' | '256' | 'truecolor' | 'auto'\n animationSpeed: 'normal', // 'slow' | 'normal' | 'fast' | 'instant'\n theme: 'dracula', // any registered theme\n reducedMotion: false,\n});\n\n// Listen for changes (per-key — avoids over-firing)\nconst off = onConfigKeyChange('theme', (newTheme, oldTheme) => {\n console.log(`Theme: ${oldTheme} → ${newTheme}`);\n});\n\n// Temporary override + auto-restore on completion or throw\nawait withConfig({ animationSpeed: 'fast' }, async () => {\n // ...your fast-mode code here...\n});\n\n// Strict mode catches config typos\n// configure({ unknwnKey: 'x' }, { strict: true }); // throws RangeError\n```\n\n---\n\n## ⚠️ Error codes\n\nSeveral ansimax functions throw `Error` / `TypeError` / `RangeError` for invalid input.\nCatching by error code is the **stable, recommended** way to handle them programmatically — message text may evolve, but `.code` values are guaranteed semver-stable.\n\n```js\nimport { themes, ascii, parseFiglet } from 'ansimax';\n\ntry {\n themes.use('inexistent-theme');\n} catch (e) {\n if (e.code === 'ANSIMAX_UNKNOWN_THEME') {\n themes.use('dracula'); // fallback\n } else {\n throw e; // re-throw unexpected errors\n }\n}\n```\n\n### All error codes\n\n| Code | Thrown by | Type | When |\n|---|---|---|---|\n| `ANSIMAX_INVALID_THEME` | `themes.register` | `TypeError` | Theme value is not a plain object |\n| `ANSIMAX_INVALID_THEME_NAME` | `themes.register` | `TypeError` | Theme has missing/empty `name` |\n| `ANSIMAX_UNKNOWN_THEME` | `themes.use` | `RangeError` | Requested theme name not registered |\n| `ANSIMAX_INVALID_FONT_NAME` | `ascii.registerFont` | `TypeError` | Empty or non-string font name |\n| `ANSIMAX_RESERVED_FONT_NAME` | `ascii.registerFont` | `Error` | Overwriting built-in font without `{ force: true }` |\n| `ANSIMAX_INVALID_FIGLET_INPUT` | `parseFiglet` | `TypeError` | Non-string or empty `.flf` content |\n| `ANSIMAX_INVALID_FIGLET_HEADER` | `parseFiglet` | `TypeError` | First line is not a valid FIGfont header |\n| `ANSIMAX_INVALID_FIGLET_HEIGHT` | `parseFiglet` | `TypeError` | Header declared zero/negative height |\n\n---\n\n## 🧩 Ecosystem packages\n\nThe **ansimax ecosystem** is structured in two tiers — companion packages that extend the core, and independent evolutions that target different platforms.\n\n### `@ansimax/*` — Companion packages\n\nScoped packages that extend `ansimax` without breaking its zero-dependency promise. Each is published independently but shares ansimax's philosophy and naming.\n\n| Package | Status | Description |\n|---|:-:|---|\n| `ansimax` | ✅ stable | Terminal-rendering core. Zero dependencies. |\n| `@ansimax/image` | 🟡 planned | Image-to-ASCII loader — PNG/JPEG/WebP from file/buffer/URL |\n| `@ansimax/cli` | 🟡 planned | Standalone binary — `npx @ansimax/cli demo`, font browser, image converter |\n| `@ansimax/fonts` | 🟡 planned | 250+ figlet `.flf` fonts pre-bundled, ready to use |\n| `@ansimax/sprites` | 🔴 future | Curated sprite library (animals, UI icons, technical diagrams) |\n| `@ansimax/video` | 🔴 future | Video frame extraction → ASCII playback |\n| `@ansimax/themes-extra` | 🔴 future | Community-contributed themes pack |\n\n**How they connect:**\n\n```\n ┌─────────────────────────────┐\n │ ansimax (zero deps) │ ← core, you always install\n │ • colors, ASCII, panels │\n │ • types: PixelGrid, etc. │\n └────────────┬────────────────┘\n │ peer dependency\n ┌────────────────────┼────────────────────┐\n ▼ ▼ ▼\n @ansimax/image @ansimax/cli @ansimax/fonts\n (deps: jimp) (binary) (data only)\n```\n\nEach companion declares `\"ansimax\": \"^X.Y.Z\"` as `peerDependency` — semver-coordinated, never duplicated, never out of sync.\n\n### `ansimax-*` — Independent evolutions\n\nStandalone projects that build **alongside** ansimax for different platforms. Not companions — these are separate identities with their own scope and release cycle.\n\n| Package | Status | Description |\n|---|:-:|---|\n| `ansimax-native` | 🔴 future | **Rust + TS rewrite** of the rendering hot path. Native performance via napi-rs. Same API surface as `ansimax`. |\n| `ansimax-web` | 🔴 future | **Browser rendering** layer. ANSI → HTML/CSS conversion + canvas rendering. For demos, docs sites, web terminals. |\n\n**Sub-ecosystems**: each of these can have their own scoped sub-packages (`@ansimax-native/image`, `@ansimax-web/canvas`, etc.) over time.\n\n### Why two naming conventions?\n\nIndustry convention used by many mature ecosystems (Babel, Vue, Webpack, etc.):\n\n- **`@scope/*`** = \"same project family, coordinated release, same team\"\n- **`name-*`** = \"inspired by / works alongside, independent identity\"\n\nBy using both, ansimax signals:\n- The **core** (`ansimax`) stays small, zero-dep, focused on terminal rendering\n- The **ecosystem** (`@ansimax/*`) grows around it as opt-in extensions\n- **Evolutions** (`ansimax-native`, `ansimax-web`) explore different platforms without compromising the core\n\n> 💡 **Coming soon**: When `@ansimax/image` or similar packages are released, this section will link to them. Want one of these built sooner? [Open an issue](https://github.com/Brashkie/ansimax/issues) to vote.\n\n---\n\n## 🛣️ Roadmap\n\nAnsimax 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.\n\nThe 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.\n\n### ✅ Phase 1 — Core foundation\n- [x] Styling engine — ANSI 16 / 256 / truecolor with adaptive fallback\n- [x] Hex + RGB helpers with clamping and validation\n- [x] `NO_COLOR` / `FORCE_COLOR` env support + non-TTY auto-detection\n- [x] `AbortSignal` integration across animations and loaders\n- [x] `compose()` style stacking with single-reset emission\n- [x] Bounded LRU escape cache (512 entries, packed-RGB keyed)\n- [x] Custom preset registry (`registerPreset`, `listPresets`)\n\n### ✅ Phase 2 — Gradient engine\n- [x] Linear gradients (multi-stop)\n- [x] Rainbow + 6 built-in presets\n- [x] Radial gradients (in `gradientRect`)\n- [x] Diagonal gradients\n- [x] Arbitrary-angle gradients\n- [x] Bayer 4×4 dithering for smooth tonal transitions\n- [x] Single-stop UX (CSS-style behavior)\n- [x] **Animated gradients** — color flow over time with `animateGradient()` (v1.2.0)\n- [x] **Gradient interpolation curves** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / custom (v1.2.0)\n- [x] **Conic gradients** — radial sweep with `style: 'conic'` (v1.2.0)\n- [x] **Mirror gradients** — symmetric `A→B→C→B→A` fill via `mirror` (v1.4.13)\n- [x] **Interpolation space** — `rgb` / `hsl` / `oklab` color-space blending (v1.4.13)\n- [x] **16 named gradient presets** — `viridis`, `plasma`, `pastel`, `cyberpunk`, and more (v1.6.0)\n- [x] **`presetStops()` + `gradientRect({ preset })`** — reuse named preset colors anywhere (v1.6.1)\n- [x] **`gradientScale()`** — sample a gradient into N discrete palette colors (v1.6.3)\n\n### ✅ Phase 3 — ASCII engine\n- [x] Block fonts (`big`, `small`)\n- [x] Banner with gradient + alignment + per-char coloring\n- [x] Box drawing (6 border styles)\n- [x] Divider with style variants\n- [x] Logo composer (gradient + box wrapping)\n- [x] Custom font registry (`registerFont`, `hasFont`, `listFonts`)\n- [x] Stream API (`ascii.stream()` with AbortSignal)\n- [x] **Image → ASCII** converter — `ascii.fromImage()` with luminance mapping (v1.2.5)\n- [x] **Color ASCII** rendering — preserve image colors via `color: true` (v1.2.5)\n- [x] **Image dithering** — Floyd-Steinberg error diffusion (v1.2.5)\n- [x] **4 dithering algorithms** — Floyd-Steinberg, Atkinson, JJN, Sierra (v1.6.2)\n- [x] **Face-optimized ASCII** — histogram stretching for portraits (v1.2.5)\n- [x] **Figlet font support** — `.flf` parser + renderer (`parseFiglet` + `ascii.figletText`) (v1.2.5)\n- [x] **Edge detection** — Sobel operator integrated in `fromImage` (v1.2.5, bonus)\n- [x] **ASCII ramp registry** — `registerAsciiRamp` + named presets (v1.4.13)\n\n### ✅ Phase 4 — Terminal UI primitives\n- [x] Tables (irregular rows, multi-line cells, ANSI-aware)\n- [x] Boxes with multiple styles\n- [x] Status messages + badges (with border option)\n- [x] Timelines with done/pending states\n- [x] Interactive menus (single + multi-select)\n- [x] Columns layout (truncate/wrap overflow)\n- [x] Sections (gradient headers with auto-width)\n- [x] Trees (collapsible, max-depth, cycle-safe)\n- [x] **Panels** — split layouts: `hsplit`, `vsplit` with alignment + nesting (v1.3.0)\n- [x] **Balanced table wrap** — minimum-raggedness word wrap for even cell lines (v1.6.2)\n- [x] **JSON/YAML pretty-printing** — colored, depth-limit, circular-safe (v1.3.0)\n- [x] **Grid system** — CSS Grid-inspired: `colSpan`, `rowSpan` (mark-and-pack), `flow`, `cellWidth`/`cellHeight`, and `gridAreas` template areas (v1.4.1–v1.4.4)\n- [x] **Markdown rendering** — headings (ATX + setext), lists (nested + task lists), code blocks, tables, blockquotes, inline styles, CommonMark escapes, autolinks, reference links, footnotes, HTML blocks (v1.4.0–v1.4.11)\n- [x] **Markdown theme registry** — custom palettes via `registerMarkdownTheme` (v1.4.11)\n- [x] **Syntax highlighting** — built-in grammars for JS/TS/JSON/Bash with aliases (v1.4.5)\n- [x] **Layouts** — CSS Grid (`grid`/`gridAreas`) + flexbox-style flow (`flex` with justify + grow, v1.4.7)\n- [x] **Logging integration** — createLogger with levels, fields, child loggers, transports + console/pino/winston shims (v1.4.12)\n\n### ✅ Phase 5 — Cursor & screen control\n- [x] Cursor visibility, save/restore, positioning, line navigation\n- [x] Screen clearing (line, area, full)\n- [x] Reference-counted cursor (overlapping calls safe)\n- [x] Crash-safe restore (exit/SIGINT/SIGTERM handlers)\n- [x] Terminal hyperlinks (OSC 8)\n- [x] Window title (OSC 2)\n- [x] Bell (BEL)\n- [x] **Managed alternate screen** — `createScreen` (alt buffer, guaranteed restore on crash) — TUI foundation (v1.7.0)\n\n### ✅ Phase 6 — Animation engine\n- [x] Typewriter, fadeIn, fadeOut, slide, pulse, wave, glitch, reveal\n- [x] All `AbortSignal`-aware\n- [x] `reducedMotion` mode for accessibility\n- [x] Frame morph (text → text interpolation, cinematic decryption)\n- [x] `parallel()` with timeout\n- [x] Signal propagation to nested animations\n- [x] **Easing functions library** (31 standard easings: cubic, elastic, bounce, back) (v1.3.5)\n- [x] **Animation composition** (`parallel + sequence + delay` DSL) (v1.5.0)\n- [x] **Spring physics** animations (`react-spring` style) (v1.5.0)\n- [x] **Tween engine** (interpolate any value type) (v1.5.0)\n\n### ✅ Phase 7 — Progress ecosystem\n- [x] Spinners (11 styles) with color + AbortSignal\n- [x] Animated progress bars\n- [x] Multi-task runners (sequential + parallel)\n- [x] Countdown timers\n- [x] Multi-spinner manager (stacked concurrent spinners)\n- [x] Hierarchical tasks (parent + subtasks rollup)\n- [x] **Live ETA estimation** (rolling average) (v1.6.0)\n- [x] **Live refresh diff renderer** (no flicker, only redraw changed lines) (v1.6.0)\n- [x] **Progress groups** (named groups with shared theme) (v1.6.1)\n- [x] **Throughput meters** (bytes/sec, ops/sec with auto-scaling units) (v1.6.0)\n\n### 🟡 Phase 8 — Capability detection\n- [x] TTY detection (auto-disable in pipes/CI)\n- [x] `NO_COLOR` / `FORCE_COLOR` env support\n- [x] Color depth detection (16 / 256 / truecolor)\n- [x] CI provider detection (GitHub Actions, CircleCI, GitLab, Buildkite, Drone, Travis)\n- [x] Terminal program detection (iTerm, vscode, WezTerm, Hyper, Apple_Terminal)\n- [x] Windows Terminal detection (`WT_SESSION`)\n- [x] **Unicode width detection** (CJK halfwidth/fullwidth, emoji clusters, ZWJ sequences) (v1.6.5)\n- [x] **Image protocol detection** — *detection only*, not an encoder: reports which protocol the terminal advertises so callers can plug in their own; ansimax itself renders via the universal path (v1.6.4)\n- [ ] **Terminal capability database** (full xterm capability flags + version probes)\n- [x] **Font metrics detection** — cell aspect ratio (`cellAspectRatio`, `aspectScale`) for pixel-accurate sub-cell layouts; overridable, defaults to the near-universal 0.5 (v1.7.1)\n\n### 🟡 Phase 9 — Advanced rendering\n- [x] Dirty-rectangle canvas (only redraw changed pixels)\n- [x] Bounded LRU caches (escape sequences, render cache, ANSI cache)\n- [x] Drift-corrected timing (animations stay locked to wall-clock)\n- [ ] **Diff renderer** (line-level damage tracking for full UIs)\n- [ ] **Virtual buffer** (compose UI without writing to stdout)\n- [ ] **Z-index / layering** (overlap panels with priority)\n- [ ] **Mouse event support** (click, hover, drag, scroll wheel)\n- [ ] **Keyboard event abstraction** (arrow keys, modifiers, key sequences, dead keys)\n- [ ] **Full TUI framework** (reactive components — Textual-equivalent for Node)\n\n### 🔴 Phase 10 — Terminal charts\n- [~] Bar charts (horizontal + vertical, grouped, stacked) — horizontal bar + histogram (v1.6.6)\n- [x] Line charts (with braille for sub-character resolution) — `lineChart`, 8× sub-pixel, multi-series, Wu-style per-cell coverage color (v1.7.1)\n- [x] Sparklines (inline mini-charts for status bars) (v1.6.6)\n- [ ] Area charts (filled with gradients)\n- [ ] Heatmaps (color-mapped 2D grids)\n- [ ] Pie / donut charts (with percentage labels)\n- [ ] Scatter plots\n- [ ] Box plots / candlestick charts\n- [ ] Real-time streaming charts (live data feed with rolling window)\n- [ ] **Plot composer** (multi-chart dashboards with shared axes)\n\n### 🔴 Phase 11 — Forms & Input\n- [ ] Text input prompts (with autocomplete + history)\n- [ ] Password prompts (masked, strength meter)\n- [ ] Confirm dialogs (yes/no with default highlight)\n- [ ] Numeric input (with min/max validation)\n- [ ] Date/time pickers (calendar widget)\n- [ ] File picker (filesystem navigator)\n- [ ] Form composer (multi-field with validation + error display)\n- [ ] **Wizard flows** (multi-step forms with back/forward, progress indicator)\n\n### 🔴 Phase 12 — Image & media\n\n**Philosophy:** ansimax renders images through *universal, self-generated*\nmethods that work in any terminal — never by depending on a proprietary\nprotocol. Kitty/iTerm/Sixel are treated as *detection* (Phase 8); emitting\nthem is optional and left to the caller. `renderImageAuto` already picks the\nbest portable method automatically.\n\n- [x] **Universal auto-render** — `renderImageAuto` picks half-blocks (color) or ASCII (no color) by capability (v1.6.7)\n- [x] **Half-block rendering** — `▀`/`▄` with fg/bg color, double vertical resolution, any truecolor terminal\n- [ ] Sixel encoder (open DEC format — pure algorithm, portable to any Sixel terminal)\n- [x] **Perceptual quantization** — `rgbTo256Perceptual` / `nearestPerceptual` via Oklab ΔE (kills banding vs RGB L2) (v1.7.0)\n- [ ] PNG/JPEG decode → pixel grid (feed into the universal renderers)\n- [ ] QR code generation (with size + ECC level options)\n- [ ] Bar code generation (Code 128, EAN-13)\n- [ ] *(detection-only, opt-in)* iTerm2 / Kitty encoders — caller-supplied, never the default\n\n### 🔴 Phase 13 — Plugin system\n- [ ] Plugin API for custom components\n- [ ] Theme marketplace\n- [ ] Custom font registration via npm packages\n- [ ] Community animations registry\n- [ ] Capability provider interface (plug in custom detectors)\n- [ ] Renderer plugins (swap stdout for any writable stream)\n\n### 🔴 Phase 14 — Reactivity layer (TUI framework)\n- [ ] **Component lifecycle** (mount/unmount/update hooks)\n- [ ] **Reactive state** (auto re-render on data change, signals or hooks)\n- [ ] **Virtual DOM diffing** (line-level updates)\n- [ ] **Event bus** (component communication)\n- [ ] **Application loop** (single render tree with full lifecycle)\n- [ ] **Routing** (multi-screen apps with history)\n- [ ] **DevTools integration** (inspect component tree, mark changed nodes)\n- [ ] **CSS-in-TS styling** (scoped styles per component)\n\n### 🔵 Phase 15 — AXSS / AXB styling pipeline (ecosystem)\n\nA dedicated stylesheet language for terminal UIs (**AXSS** — *Ansi eXtended\nStyle Sheets*) that compiles to a portable binary format (**AXB** — *Ansi\nBinary*) consumed by `ansimax-native`. The design is **frozen**;\nimplementation waits on `ansimax-native` (there is no engine to consume AXB\nyet, so this is deliberately not rushed).\n\n- [ ] **AXSS language** — high-level terminal stylesheets (`Button { color: yellow; padding: 1 2; }`) with type / id / multi-class / state selectors\n- [ ] **AXB binary format** — portable, versioned, little-endian bytecode; magic + format version + minimum engine version + CRC; extensible sections\n- [ ] **Declarative model** — AXB describes *state per selector*, not imperative instructions; the engine decides when each state applies\n- [ ] **Compile-time cascade & specificity** — resolved by the compiler (`id > class > type`, ties → last rule wins); the runtime receives flattened `StyleState`s\n- [ ] **Stable ID tables** — `PropertyId` / `StateId` / `ColorKind` are part of the spec with explicit values, never reordered or recycled\n- [ ] **Color encoding** — named / ANSI-256 / RGB tri-form with a discriminant byte\n- [ ] **`ansimax axb inspect`** — a disassembler/debugger born alongside the compiler (with optional debug metadata: `background: BLUE ← inherited from Button`)\n- [ ] **Multiple frontends** (later) — CSS / TOML / YAML / JSON / XML all producing the same AST → the same AXB, making AXB the engine's universal format\n\n> **Note:** AXSS is the human-readable frontend; AXB is the compact binary\n> the engine consumes. `.axb` is *bytecode* — low-level relative to AXSS, but\n> high-level relative to the hardware (closer to WASM/SPIR-V than to machine\n> code). It is designed to be shipped with your app, like a compiled shader.\n\n**Legend:** ✅ Complete · 🟡 Partial · 🔴 Planned · 🔵 Designed (awaiting `ansimax-native`)\n\n---\n\n## 🧪 Testing\n\n```bash\nnpm test # Run all 3000+ tests\nnpm run test:watch # Watch mode\nnpm run test:coverage # Coverage report\n```\n\nCoverage (as of v1.3.0):\n\n| Metric | Score |\n|---|:-:|\n| **Statements** | ~98% |\n| **Branches** | ~95% |\n| **Functions** | ~99% |\n| **Lines** | ~99% |\n| **Total tests** | **2,000+** |\n| **Test suites** | 27 |\n| **CI matrix** | Node 18, 20, 22, latest |\n| **Platforms tested** | Linux, macOS, Windows |\n\n---\n\n## 🛠️ Requirements\n\n- **Node.js** ≥ 18\n- **TypeScript** ≥ 5.0 (for typed consumption — optional)\n- **Terminal** with truecolor support recommended (Windows Terminal, iTerm2, WezTerm, Kitty, modern xterm). Gracefully degrades to 256 / 16 / no-color.\n\n---\n\n## 🏗️ Project Structure\n\n```\nansimax/\n├── src/\n│ ├── colors/ Color rendering + gradient engine\n│ ├── themes/ Theme system + 8 built-ins\n│ ├── ascii/ Banners, boxes, fonts\n│ ├── animations/ Typewriter, fade, slide, pulse, wave, glitch, reveal\n│ ├── loaders/ Spinners, progress, tasks, multi-loader\n│ ├── frames/ Sequenced playback + live renderer + morph\n│ ├── components/ Tables, badges, status, timelines, menus\n│ ├── images/ Sprites, canvas, dithered gradients\n│ ├── trees/ Tree builder + algorithms\n│ ├── utils/ ANSI primitives + helpers\n│ └── configure.ts Global config + subscribers\n├── examples/ 10 examples (TS) + 2 (JS — ESM & CJS) — all features covered\n└── __tests__/ 27 test suites, 3000+ tests\n```\n\n---\n\n## 📝 Changelog\n\n### v1.7.0 — Perceptual color, managed screen, spline gradients, lap timing\n\nA larger minor. Highlights:\n\n- 🎨 **Perceptual quantization** — `rgbTo256Perceptual`, `nearestPerceptual`, `oklabDistance` (Oklab ΔE — kills banding vs RGB L2)\n- 🖥️ **Managed alternate screen** — `createScreen` (vim/htop-style full-screen with guaranteed restore) — TUI foundation\n- 🌈 **Spline gradients** — `gradientColorSpline` (Catmull-Rom C¹, smooth through multi-stops)\n- ⏱️ **Lap stopwatch** — `createStopwatch` (labelled splits, `report()`, `slowest()`)\n- 🧪 **+60 tests**\n\n```js\nimport { createScreen, rgbTo256Perceptual, gradientColorSpline, createStopwatch } from 'ansimax';\n\nawait createScreen().run((s) => { s.moveTo(1,1); s.write('Full-screen app'); });\nrgbTo256Perceptual(128, 64, 32); // nearest xterm-256 by perceptual ΔE\ngradientColorSpline(stops, 0.25); // smooth multi-stop sampling\nconst sw = createStopwatch(); sw.lap('load'); // profile stages\n```\n\nDrop-in replacement for `1.6.7`.\n\n### v1.6.7 — Universal image auto-render + cubic-bezier easing + event counter\n\n- 🖼️ **`renderImageAuto`** — picks half-blocks (color) or ASCII (no color) by capability; portable, no proprietary encoders\n- 📐 **`cubicBezier(x1,y1,x2,y2)`** — CSS-style easing factory (Newton–Raphson solve; supports overshoot)\n- 🔢 **`createCounter`** — event counter with EMA rate, total, and lifetime average\n- 🧪 **+50 tests**\n\n```js\nimport { renderImageAuto, cubicBezier, createCounter } from 'ansimax';\n\nconst { output, method } = renderImageAuto(pixels); // 'halfblock' | 'ascii'\nconst ease = cubicBezier(0.25, 0.1, 0.25, 1); // CSS \"ease\"\nconst c = createCounter(); c.tick(); c.formatRate(); // \"1.2K/s\"\n```\n\n> **On image protocols:** ansimax renders via universal, self-generated methods (half-blocks / ASCII) that work in any terminal. Sixel/Kitty/iTerm are *detection only* — surfaced so callers can plug in their own encoder, never emitted by default.\n\nDrop-in replacement for `1.6.6`.\n\n### v1.6.6 — Inline charts (Phase 10 begins) + stepped easings\n\n- 📊 **Inline charts** — `sparkline`, `bar`, `histogram` (also the `chart` namespace)\n- 🪜 **Stepped easings** — `steps(n, position)`, `stepStart`, `stepEnd` (CSS `steps()` style)\n- 〰️ **Smoothstep easings** — `smoothStep`, `smootherStep` (shader S-curves)\n- 🧪 **+45 tests**\n\n```js\nimport { sparkline, bar, histogram, steps } from 'ansimax';\n\nsparkline([1, 5, 2, 8, 3, 7, 9, 4]); // '▁▅▂▇▃▆█▄'\nbar(0.66, { width: 12 }); // eighth-cell precision\nhistogram([{ label: 'GET', value: 1240 }, { label: 'POST', value: 430 }]);\nsteps(4); // staircase easing\n```\n\nDrop-in replacement for `1.6.5`.\n\n### v1.6.5 — Unicode width detection + ETA smoothing + numeric table alignment\n\n- 📏 **Unicode width detection** — `stringWidth`, `isFullWidth`, `isEmoji`, `isCombining`\n- 📊 **Rate formatters** — `formatPercent`, `formatRate` (`\"1.5 MB/s\"`, `\"1.2K req/s\"`)\n- 📈 **ETA EMA smoothing** — `createETA({ smoothing: 'ema' })` reacts faster to speed changes\n- 🔢 **Auto-aligned numeric columns** — `ascii.table({ autoAlignNumbers: true })`\n- 🧪 **+40 tests**\n\n```js\nimport { stringWidth, formatRate, createETA, ascii } from 'ansimax';\n\nstringWidth('中文'); // 4\nformatRate(1572864); // \"1.5 MB/s\"\ncreateETA({ total: 1000, smoothing: 'ema' }); // faster reaction\nascii.table(rows, { autoAlignNumbers: true }); // numbers right-aligned\n```\n\nDrop-in replacement for `1.6.4`.\n\n### v1.6.4 — Image protocol detection + elapsed timer + colors refactor\n\n- 🖼️ **Image protocol detection** — `detectImageProtocol()` → `'kitty'` / `'iterm'` / `'sixel'` / `'none'`\n- ⏱️ **`createTimer`** — elapsed-time stopwatch (start/stop/reset, pause-aware)\n- 🧹 **Colors refactor** — shared core moved to `colors/internal.ts`; public API byte-for-byte identical\n- 🧪 **+40 tests**\n\n```js\nimport { detectImageProtocol, supportsInlineImages, createTimer } from 'ansimax';\n\ndetectImageProtocol(); // 'kitty' | 'iterm' | 'sixel' | 'none'\nsupportsInlineImages(); // boolean\n\nconst t = createTimer();\nt.start(); /* ...work... */ t.stop();\nt.formatted(); // \"1.5s\"\n```\n\nDrop-in replacement for `1.6.3`.\n\n### v1.6.3 — Refactor: split animations + contrast/a11y + gradient scale\n\n- 🧹 **Animations split** — the ~1,100-line module is now 5 focused files; public API byte-for-byte identical\n- ♿ **WCAG contrast helpers** — `relativeLuminance`, `contrastRatio`, `readableTextColor`, `meetsContrast`\n- 🎨 **`gradientScale()`** — sample a gradient into N discrete palette colors\n- 🧪 **+30 tests**\n\n```js\nimport { contrastRatio, readableTextColor, gradientScale } from 'ansimax';\n\ncontrastRatio({ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 }); // 21 (max)\nreadableTextColor({ r: 255, g: 235, b: 59 }); // black on yellow\ngradientScale(['#ff0000', '#0000ff'], 3); // ['#ff0000','#800080','#0000ff']\n```\n\nDrop-in replacement for `1.6.2`.\n\n### v1.6.2 — Advanced algorithms: dithering, balanced wrap, statistics\n\n- 🖼️ **4 dithering algorithms** — `floyd-steinberg`, `atkinson`, `jjn`, `sierra` (error-diffusion kernels)\n- 📐 **Balanced table wrap** — minimum-raggedness word wrap (`balancedWrap: true`) for even cell lines\n- 🧮 **7 math helpers** — `median`, `variance`, `stddev`, `percentile`, `quantize`, `catmullRom`, `gaussian`\n- 🧪 **+45 tests**\n\n```js\nimport { ascii, balancedWrap, catmullRom, percentile } from 'ansimax';\n\nascii.fromImage(pixels, { dither: 'atkinson' }); // crisp, high contrast\nascii.table(rows, { wrap: true, balancedWrap: true }); // even wrapped lines\n\nbalancedWrap('I am a very long sentence here', 11); // minimum raggedness\ncatmullRom(0, 10, 20, 30, 0.5); // → 15 (smooth spline)\npercentile([1, 2, 3, 4, 5], 50); // → 3\n```\n\nDrop-in replacement for `1.6.1`.\n\n### v1.6.1 — Phase 7 complete (progress groups) + gradient preset reuse\n\n- 📊 **`createProgressGroup`** — several named bars under one title/theme, flicker-free (completes **Phase 7**)\n- 🎨 **`presetStops(name)`** + **`hasPreset(name)`** — reuse a preset's colors anywhere\n- 🖼️ **`gradientRect({ preset })`** — fill a rectangle from a named preset\n- 🧪 **+45 tests**\n\n```js\nimport { createProgressGroup, presetStops, gradientRect } from 'ansimax';\n\nconst group = createProgressGroup({ title: 'Deploying' });\ngroup.add('api', 'API').add('web', 'Web');\ngroup.update('api', 0.4, '12 MB/s');\ngroup.complete('web');\ngroup.render();\n\ngradient('text', presetStops('viridis'), { mirror: true });\ngradientRect({ width: 40, height: 10, preset: 'plasma' });\n```\n\nDrop-in replacement for `1.6.0`.\n\n### v1.6.0 — Phase 7 progress meters + more gradient presets\n\n- ⏱️ **`createETA`** — rolling-average time-remaining estimator (`eta()`, `rate()`, `progress()`)\n- 📊 **`createThroughput`** — bytes/sec or ops/sec with auto-scaling units (`\"1.5 MB/s\"`)\n- 🖥️ **`createLiveRegion`** — flicker-free multi-line region: redraws only changed lines\n- 🎨 **8 new gradient presets** — `viridis`, `plasma`, `pastel`, `cyberpunk`, `mono`, `mint`, `dusk`, `cotton` (16 total)\n- 🧪 **+35 tests**\n\n```js\nimport { createETA, createThroughput, createLiveRegion } from 'ansimax';\n\nconst eta = createETA({ total: 1000 });\neta.update(downloaded);\nconsole.log(eta.eta()); // \"3.2s\"\n\nconst tp = createThroughput({ unit: 'bytes' });\ntp.update(bytesSoFar);\nconsole.log(tp.format()); // \"1.5 MB/s\"\n\nconst region = createLiveRegion();\nregion.render(['A: 10%', 'B: 0%']);\nregion.render(['A: 100%', 'B: 0%']); // only line A rewritten\n```\n\nDrop-in replacement for `1.5.2`.\n\n### v1.5.2 — Documentation audit: every example verified copy-paste-runnable\n\n- ✅ **All 52 README examples** executed against the real package and fixed (missing imports, self-contained snippets)\n- ✅ **docs/examples-{mjs,cjs,ts}.md** — 33/33 blocks each pass (ran ESM/CJS, type-checked TS); fixed 8 real TS API/type bugs\n- 🎬 **showcase.md rewritten** as one cohesive enterprise app (\"Stardust Deploy\") combining every module — not isolated snippets\n- 📝 **No library code changed** — documentation-only quality release\n\nDrop-in replacement for `1.5.1`.\n\n### v1.5.1 — Tween/spring quality-of-life: repeat, yoyo, callbacks, stagger\n\n- 🔁 **`repeat` + `yoyo`** — loop a tween N times (or `Infinity`), alternating direction\n- 📣 **`onStart` / `onComplete`** — lifecycle callbacks on `tween` and `spring` (not fired on abort)\n- 🎞️ **`stagger()`** — cascade a list of animations, each offset by `gap × index`\n- 🧪 **+22 tests**\n- 🔵 **Roadmap**: declared the frozen **AXSS → AXB** styling pipeline (Phase 15, awaiting `ansimax-native`)\n\n```js\nimport { tween, stagger } from 'ansimax';\n\nconst draw = (v) => process.stdout.write(`\\r${v.toFixed(2)}`);\nconst ctrl = new AbortController();\nsetTimeout(() => ctrl.abort(), 1500);\nawait tween({ from: 0, to: 1, duration: 200, repeat: Infinity, yoyo: true, onUpdate: draw, signal: ctrl.signal });\n\n// stagger a list — each row's animation starts 80ms after the previous\nconst rows = [{ setOpacity(v) {} }, { setOpacity(v) {} }, { setOpacity(v) {} }];\nawait stagger(rows.map((row) => (s) =>\n tween({ from: 0, to: 1, duration: 200, onUpdate: (v) => row.setOpacity(v), signal: s })\n), 80);\n```\n\nDrop-in replacement for `1.5.0`.\n\n### v1.5.0 — Phase 6 closure: tween engine, spring physics, composition DSL\n\n- 🎬 **Tween engine** — `tween()` interpolates numbers, arrays, and objects over time with easing\n- 🌱 **Spring physics** — `spring()` react-spring-style (stiffness/damping/mass)\n- 🔗 **Composition DSL** — `sequence`, `parallel`, `delay`, `tweenStep`, `springStep`\n- 🧪 **+40 tests** · **Phase 6 complete**\n\n```js\nimport { tween, spring, sequence, delay } from 'ansimax';\n\n// `draw` is your render callback — here it just prints the current value\nconst draw = (v) => process.stdout.write(`\\r${Math.round(v)} `);\n\nawait tween({ from: 0, to: 100, duration: 1000, easing: 'easeOutCubic', onUpdate: draw });\nawait spring({ from: 0, to: 100, config: { stiffness: 210, damping: 20 }, onUpdate: draw });\n\nawait sequence([\n (s) => tween({ from: 0, to: 100, duration: 300, onUpdate: draw, signal: s }),\n delay(200),\n (s) => tween({ from: 100, to: 0, duration: 300, onUpdate: draw, signal: s }),\n]);\n```\n\nAll `AbortSignal`- and `reducedMotion`-aware. Drop-in replacement for `1.4.13`.\n\n### v1.4.13 — Phase 2 & 3 improvements: mirror gradients, HSL interpolation, ramp registry\n\n- 🔁 **Mirror gradients** — `mirror: true` reflects the palette (`A→B→C→B→A`) on `gradient`, `createGradient`, `gradientRect`\n- 🎨 **Interpolation space** — `interpolation: 'rgb' | 'hsl' | 'oklab'` for vivid or perceptually-smooth blends\n- 🖼️ **ASCII ramp registry** — `registerAsciiRamp` + 3 new presets (`minimal`, `thermal`, `hearts`)\n- 🧪 **+27 tests**\n\n```js\nimport { gradient, registerAsciiRamp, ascii } from 'ansimax';\n\ngradient('symmetric', ['#ff0000', '#00ff00', '#0000ff'], { mirror: true });\ngradient('vivid', ['#ff0000', '#0000ff'], { interpolation: 'hsl' });\n\nregisterAsciiRamp('retro', ' .oO0');\n// `pixels` is a 2D array of { r, g, b } — here a tiny 2×2 sample\nconst pixels = [\n [{ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 }],\n [{ r: 128, g: 128, b: 128 }, { r: 0, g: 0, b: 0 }],\n];\nconsole.log(ascii.fromImage(pixels, { ramp: 'retro' }));\n```\n\nDrop-in replacement for `1.4.12`.\n\n### v1.4.12 — Logging integration + Phase 4/2 improvements\n\n- 🪵 **Logging** — `createLogger()` with 7 levels, structured fields, child loggers, pluggable transports\n- 🔌 **Drop-in shims** — `asConsole`, `pinoShim`, `winstonTransport`\n- 🖊️ **Markdown `==highlight==`** — GFM/Obsidian mark support\n- 📋 **`ascii.table` caption** — dimmed, centered note below the table\n- 🧪 **+40 tests**\n\n```js\nimport { createLogger } from 'ansimax';\n\nconst log = createLogger({ level: 'debug', name: 'api' });\nlog.info('server started', { port: 3000 });\nlog.child({ reqId: 'abc' }).debug('handling request');\n```\n\n**Phase 4 is now complete** (logging was the final item). Drop-in replacement for `1.4.11`.\n\n### v1.4.11 — Phase 4 closure: theme registry, footnotes, HTML blocks\n\n- 🎨 **Custom markdown themes** — `registerMarkdownTheme(name, palette)`, validated at registration\n- 📌 **Footnotes** — `[^label]` + `[^label]: text`, numbered by first reference (GFM behavior)\n- 🏷️ **HTML blocks** — `htmlMode: 'strip' | 'raw' | 'hide'` (CommonMark §4.6)\n- 🧪 **+38 tests**\n\n```js\nimport { registerMarkdownTheme, markdown } from 'ansimax';\n\nregisterMarkdownTheme('solarized', {\n h1: ['#b58900', '#cb4b16'], h2: '#cb4b16', h3: '#d33682',\n h4: '#6c71c4', h5: '#268bd2', h6: '#2aa198',\n code: '#b58900', codeBlockBorder: '#586e75', link: '#268bd2',\n blockquote: '#586e75', hr: '#586e75', tableHeader: '#cb4b16',\n});\n\nmarkdown.render('# Title\\n\\nCited[^a].\\n\\n[^a]: The note.', { theme: 'solarized' });\n```\n\n**Phase 4 is now complete.** Drop-in replacement for `1.4.10`.\n\n### v1.4.10 — ascii module split + table minColWidth\n\n- 🧩 **`ascii/` module split** — 1575-line `index.ts` → 9 focused modules (types/fonts/render/shapes/image/figlet/stream/table/index)\n- 📏 **`ascii.table` `minColWidth`** — floor on column shrinking so narrow columns stay legible\n\n```js\nimport { ascii } from 'ansimax';\n\nconst rows = [\n ['Name', 'Role', 'Location'],\n ['Ada Lovelace', 'Engineer', 'London'],\n ['Alan Turing', 'Researcher', 'Manchester'],\n];\nconsole.log(ascii.table(rows, { maxWidth: 30, minColWidth: 4 }));\n// No column shrinks below 4 visible chars\n```\n\nThe module split is pure rearrangement — the `ascii` namespace and all exports are 100% backward-compatible. The dependency graph is strictly layered and acyclic. Drop-in replacement for `1.4.9`.\n\n### v1.4.9 — Table cell wrapping + coverage hardening\n\n- 📝 **`ascii.table` cell wrapping** — `wrap: true` word-wraps long cells to multiple lines instead of truncating\n- 🧪 **Coverage hardening** — closed remaining v1.4.8 branch gaps (reachable → tests, unreachable → documented `istanbul ignore`)\n\n```js\nimport { ascii } from 'ansimax';\n\nascii.table([\n ['id', 'description'],\n ['1', 'a fairly long description that wraps neatly across several lines'],\n], { maxWidth: 40, wrap: true });\n```\n\nColumn sizing runs first (water-filling), then cells wrap within the resulting widths. Rows grow to fit their tallest cell. `wrap: false` (default) keeps v1.4.8 ellipsis behavior.\n\nDrop-in replacement for `1.4.8`.\n\n### v1.4.8 — Grids, tables, wrapping + scroll regions\n\nFour additive features, zero breaking changes:\n\n- 📊 **`ascii.table`** — auto-layout tables with 6 border styles + water-filling column sizing\n- 🔲 **`panels.wrap`** — flex-wrap-style block flow (greedy bin-packing)\n- 📐 **`grid` per-cell align** — `cellAlign: ['start', 'center', 'end']`\n- 🖥️ **`cursor.scrollRegion` + `cursor.batch`** — DECSTBM scroll regions + atomic writes (Phase 5)\n- 🧪 **+36 tests**\n\n```js\nimport { ascii, panels, cursor } from 'ansimax';\n\n// Auto-sized table (widest column shrinks first when over budget)\nconsole.log(ascii.table([\n ['Name', 'Role', 'Commits'],\n ['Ada', 'Author', '1200'],\n], { align: ['left', 'left', 'right'], maxWidth: 40 }));\n\n// Wrap cards to fit the terminal width\nconst cards = ['A', 'B', 'C', 'D'].map((c) => ascii.box(c, { padding: 1 }));\nconsole.log(panels.wrap(cards, { maxWidth: 60, gapX: 2, gapY: 1 }));\n\n// Pinned header/footer with a scrolling body\nprocess.stdout.write(cursor.scrollRegion(2, 23));\n```\n\nDrop-in replacement for `1.4.7`.\n\n### v1.4.7 — Reference links + flexbox layout\n\nTwo roadmap items, zero breaking changes:\n\n- 🔗 **Markdown reference links** — `[text][ref]`, `[text][]`, `[shortcut]` + `[ref]: url \"title\"` definitions\n- 📐 **`panels.flex`** — flexbox-style layout with `justify` (start/end/center/between/around/evenly) + `grow` weights\n- 🧪 **+30 tests**\n\n```js\nimport { panels, ascii, markdown } from 'ansimax';\n\nconst [boxA, boxB, boxC] = ['A', 'B', 'C'].map((c) => ascii.box(c, { padding: 1 }));\n\n// Flexbox layout\nconsole.log(panels.flex([boxA, boxB, boxC], { width: 60, justify: 'between' }));\nconsole.log(panels.flex([boxA, boxB], { width: 40, grow: [3, 1] })); // A grows 3× as much\n\n// Reference links\nmarkdown.render(`\nSee [the docs][docs] and [shortcut].\n\n[docs]: https://docs.example.com \"Documentation\"\n[shortcut]: https://example.com\n`);\n```\n\nBoth build on v1.4.6 foundations (link placeholders + `distribute`). Every `flex` justify strategy conserves total width exactly.\n\nDrop-in replacement for `1.4.6`.\n\n### v1.4.6 — Consolidation v4 + math toolkit + autolinks\n\nMaintenance + feature release. Zero breaking changes:\n\n- 🧹 **`HEX_RE` consolidated** — 5 duplicate copies → 1 (`isHexColor`)\n- 🔢 **New `utils/math` toolkit** — `lerp`, `smoothstep`, `mod`, `gcd`, `distribute`, and more (15 pure functions)\n- 🔗 **Markdown autolinks** — `