ansimax 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -3,6 +3,184 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.3.3] — Feature additions to panels, json, ascii
+
+Patch release adding new functionality to three modules. No breaking changes —
+all additions are opt-in via new options/exports.
+
+### Added — `panels.grid(blocks, opts)`
+
+N-column grid layout with auto-flow (reading order). Each row auto-sizes to
+the tallest block; each column auto-sizes to its widest member.
+
+```js
+import { panels, ascii } from 'ansimax';
+
+const cards = [
+  ascii.box('FILES\n42',   { padding: 1 }),
+  ascii.box('LINES\n1247', { padding: 1 }),
+  ascii.box('TESTS\n38',   { padding: 1 }),
+  ascii.box('COV\n98%',    { padding: 1 }),
+];
+
+// 2×2 grid
+console.log(panels.grid(cards, { columns: 2, gapX: 2, gapY: 1 }));
+
+// 3-column with auto-flow (7 items → 3 rows: [3, 3, 1])
+console.log(panels.grid(items, { columns: 3, gapX: 4 }));
+
+// Fixed cell width for uniform appearance
+console.log(panels.grid(blocks, {
+  columns: 4,
+  cellWidth: 15,
+  alignX: 'center',
+}));
+```
+
+Options: `columns` (required), `gapX`, `gapY`, `alignX`, `alignY`, `cellWidth`.
+
+### Added — `panels.frame` option `titleAlign`
+
+Frame titles can now be aligned `'left'`, `'center'` (default), or `'right'`.
+
+```js
+panels.frame('Body', { title: 'Section', titleAlign: 'left' });
+// ─ Section ───────────
+//
+// Body
+// ────────────────────
+
+panels.frame('Body', { title: 'Section', titleAlign: 'right' });
+// ─────────── Section ─
+//
+// Body
+// ────────────────────
+```
+
+### Added — `ascii.box` options `title` + `titleAlign`
+
+Boxes can now have a title in the top border. When the title is wider than the
+content, the box expands to fit it.
+
+```js
+console.log(ascii.box('Body content', {
+  title: 'Header',
+  titleAlign: 'left',     // 'left' | 'center' (default) | 'right'
+  borderStyle: 'rounded',
+}));
+
+// ╭─ Header ──────╮
+// │ Body content  │
+// ╰───────────────╯
+```
+
+### Added — `ascii.divider` option `align`
+
+Divider labels can now be aligned similar to box titles.
+
+```js
+ascii.divider({ label: 'Section', align: 'left',   width: 40 });
+// ─ Section ──────────────────────────────
+ascii.divider({ label: 'Section', align: 'center', width: 40 });
+// ─────────────── Section ────────────────
+ascii.divider({ label: 'Section', align: 'right',  width: 40 });
+// ────────────────────────────── Section ─
+```
+
+### Added — `json.pretty` native types support: `Map`, `Set`, `Date`
+
+```js
+import { json } from 'ansimax';
+
+const data = {
+  created: new Date('2026-06-13'),
+  cache: new Map([['user1', 'Alice'], ['user2', 'Bob']]),
+  tags: new Set(['frontend', 'react']),
+};
+
+console.log(json.pretty(data));
+// {
+//   "created": Date(2026-06-13T00:00:00.000Z),
+//   "cache": Map(2) [...],
+//   "tags": Set(2) ["frontend", "react"]
+// }
+```
+
+### Added — `json.pretty` option `mode: 'json'`
+
+Produces **strict, parseable JSON** instead of display-only output. Useful
+for piping to files, scripts, or other tools.
+
+```js
+const out = json.pretty(myData, { mode: 'json' });
+const parsed = JSON.parse(out);   // ✓ works
+```
+
+In `'json'` mode:
+- Colors are forced off (output is always plain text)
+- `undefined` / functions / symbols are dropped from objects, become `null` in arrays
+- `NaN` / `Infinity` / `-Infinity` become `null`
+- `BigInt` becomes a number (if safe) or a string (if out of safe range)
+- `Date` becomes its ISO string
+- `Map` becomes a plain object (string-keys only)
+- `Set` becomes an array
+- Circular references throw `TypeError` (matches `JSON.stringify` behavior)
+
+Default `'display'` mode preserves all v1.3.2 behavior. **No breaking changes.**
+
+### Improved — Tests
+
+- `+8` tests for `panels.grid`
+- `+3` tests for `panels.frame` titleAlign
+- `+5` tests for `ascii.box` title/titleAlign
+- `+4` tests for `ascii.divider` align
+- `+18` tests for `json` Map/Set/Date/mode
+
+### Notes
+
+- No runtime dependencies — still zero
+- No breaking changes — drop-in replacement for `1.3.2`
+- All new options have backward-compatible defaults
+
+---
+
+## [1.3.2] — Documentation polish for frames + images
+
+Patch release improving JSDoc + IntelliSense coverage for the two largest
+modules that were under-documented. No code changes — pure DX upgrade.
+
+### Improved — JSDoc with runnable examples
+
+**`frames` module (previously 0 examples → now 17):**
+- `frames.play` — 5 examples (basic loop, play-once, abortable, pause/resume, custom onFrame)
+- `frames.generate` — 3 examples (pulsing dot, progress bar, error tolerance)
+- `frames.live` — 3 examples (reactive counter, async data stream, FPS clamping)
+- `frames.morph` — 3 examples (basic, custom charset, chained sequences)
+- `frames.presets` — 3 examples (loadingBar, pulse, wave with custom rendering)
+
+**`images` module (previously 0 examples → now 18):**
+- `renderPixelArt` — 4 examples (heart sprite, scaling, background, sprite lookup)
+- `gradientRect` — 7 examples (horizontal, vertical, diagonal, radial, conic, dithered, braille)
+- `createCanvas` — 4 examples (basic scene, animated frame, sprite composition, resize)
+- `SPRITES` — 3 examples (render single, list all, compose on canvas)
+
+### Why this matters
+
+Before v1.3.2, users hovering `frames.play(...)` in their editor saw just
+the signature `(frames: string[], opts?: PlayOptions): PlayController`.
+Now they see 5 runnable examples showing pause/resume patterns, AbortSignal
+integration, custom rendering callbacks — significantly reducing the
+"what do I pass here?" friction for new users.
+
+### Notes
+
+- No code changes — pure documentation
+- No runtime dependencies — still zero
+- No new tests required — existing test coverage unchanged
+- Drop-in replacement for `1.3.1`
+
+---
+
 ## [1.3.1] — Polish for panels + json
 
 Patch release improving the two modules introduced in v1.3.0 — adds layout

package/README.es.md

@@ -7,7 +7,7 @@
 _Colores • Gradientes • Animaciones • ASCII Art • Pixel Art • Árboles • Componentes • Temas_
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-v1.3.1-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.3.3-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-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -215,6 +215,8 @@ console.log(rainbow('preset rainbow integrado'));
 
 ### Gradientes animados (v1.2.0)
 
+<img src="media/animated-gradients.gif" alt="Vista previa de gradientes animados" />
+
 ```js
 import { animateGradient, sleep } from 'ansimax';
 
@@ -273,6 +275,8 @@ console.log(gradientRect({
 
 ### Gradientes reusables (v1.2.3)
 
+<img src="media/reusable-gradients.gif" alt="Vista previa de gradientes reusables" />
+
 ```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
@@ -319,6 +323,33 @@ console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }
 
 ### Imagen → ASCII (v1.2.5)
 
+<div align="center">
+  <img src="media/image-ascii-original.png" alt="Foto original" width="40%" />
+</div>
+
+<table>
+  <tr>
+    <td align="center">
+      <img src="media/image-ascii-1.png" alt="Modo monocromo" /><br/>
+      <sub><b>1. Monocromo</b></sub>
+    </td>
+    <td align="center">
+      <img src="media/image-ascii-2.png" alt="Color + dithering Floyd-Steinberg" /><br/>
+      <sub><b>2. Color + Floyd-Steinberg</b></sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="media/image-ascii-3.png" alt="Detección de bordes (Sobel)" /><br/>
+      <sub><b>3. Detección de bordes (Sobel)</b></sub>
+    </td>
+    <td align="center">
+      <img src="media/image-ascii-4.png" alt="Modo rostro para retratos" /><br/>
+      <sub><b>4. Modo rostro (retratos)</b></sub>
+    </td>
+  </tr>
+</table>
+
 ```js
 import { ascii } from 'ansimax';
 import sharp from 'sharp';
@@ -342,10 +373,10 @@ for (let y = 0; y < info.height; y++) {
 
 // Ahora usa ansimax — varias formas:
 
-// Monocromo
+// 1. Monocromo
 console.log(ascii.fromImage(pixels, { width: 80 }));
 
-// Color + dithering Floyd-Steinberg + ramp detallado
+// 2. Color + dithering Floyd-Steinberg + ramp detallado
 console.log(ascii.fromImage(pixels, {
   width: 100,
   color: true,
@@ -353,7 +384,7 @@ console.log(ascii.fromImage(pixels, {
   ramp: 'detailed',
 }));
 
-// Modo detección de bordes (line art)
+// 3. Modo detección de bordes (line art)
 console.log(ascii.fromImage(pixels, {
   width: 80,
   edgeDetect: 'sobel',
@@ -361,7 +392,7 @@ console.log(ascii.fromImage(pixels, {
   ramp: 'blocks',
 }));
 
-// Modo rostro para retratos (mejora contraste de tonos medios)
+// 4. Modo rostro para retratos (mejora contraste de tonos medios)
 console.log(ascii.fromImage(pixels, {
   width: 60,
   ramp: 'detailed',
@@ -371,6 +402,8 @@ console.log(ascii.fromImage(pixels, {
 
 ### Fuentes Figlet (v1.2.5)
 
+<img src="media/figlet_fonts.png" alt="Vista previa de fuentes figlet" />
+
 ```js
 import { readFileSync } from 'node:fs';
 import { parseFiglet, ascii, gradient } from 'ansimax';
@@ -445,7 +478,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.3.1'));
+console.log(components.badge('VERSION', 'v1.3.3'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -466,6 +499,8 @@ console.log(components.timeline([
 
 ### Loaders y Progreso
 
+<img src="media/loaders.png" alt="Vista previa de loaders y barras de progreso" />
+
 ```js
 import { loader, sleep } from 'ansimax';
 
@@ -495,6 +530,8 @@ await loader.tasks([
 
 ### Animaciones
 
+<img src="media/animations-1.gif" alt="Vista previa de animaciones" />
+
 ```js
 import { animate, gradient, sleep } from 'ansimax';
 
@@ -557,6 +594,8 @@ console.log('tenantB incluye custom?', tenantB.list().includes('custom'));
 
 ### Panels — Layouts divididos (v1.3.0)
 
+<img src="media/panels.png" alt="Vista previa de panels y layouts divididos" />
+
 ```js
 import { panels, ascii } from 'ansimax';
 
@@ -586,6 +625,8 @@ console.log(panels.hsplit([
 
 ### JSON Pretty-print (v1.3.0)
 
+<img src="media/json_pretty.png" alt="Vista previa de JSON pretty-print" />
+
 ```js
 import { json } from 'ansimax';
 
@@ -599,10 +640,12 @@ console.log(json.pretty({
 }));
 
 // Límite de profundidad — colapsa objetos profundos a {...}
+const deeplyNested = { a: { b: { c: { d: { e: 'muy profundo' } } } } };
 console.log(json.pretty(deeplyNested, { maxDepth: 2 }));
 
 // Límite de items — arrays grandes muestran "... (N more)"
-console.log(json.pretty(largeArray, { maxItems: 10 }));
+const largeArray = Array.from({ length: 50 }, (_, i) => `item_${i}`);
+console.log(json.pretty(largeArray, { maxItems: 5 }));
 
 // Referencias circulares manejadas con gracia
 const obj = { name: 'foo' };
@@ -612,6 +655,22 @@ console.log(json.pretty(obj));   // → "self": [Circular]
 
 ---
 
+## 📖 Documentación
+
+La carpeta [`docs/`](./docs) contiene ejemplos completos para cada módulo:
+
+| Documento | Descripción |
+|---|---|
+| [`docs/README.md`](./docs/README.md) | Índice de documentación — empieza aquí |
+| [`docs/examples-ts.md`](./docs/examples-ts.md) | 33 ejemplos en TypeScript (3 por módulo × 11 módulos) |
+| [`docs/examples-mjs.md`](./docs/examples-mjs.md) | 33 ejemplos en JavaScript ESM |
+| [`docs/examples-cjs.md`](./docs/examples-cjs.md) | 33 ejemplos en JavaScript CommonJS |
+| [`docs/showcase.md`](./docs/showcase.md) | App completa que combina todos los módulos |
+
+Cada ejemplo es **copy-paste ejecutable** con escenarios realistas de complejidad media — no solo one-liners.
+
+---
+
 ## 📚 Ejemplos
 
 Once ejemplos de calidad de producción se publican en el paquete npm y son ejecutables directamente. Los encuentras en [`/examples`](./examples) después de instalar:
@@ -1006,6 +1065,56 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.3.3 — Features para panels, json, ascii
+
+Release patch con nuevas features opt-in. Cero breaking changes:
+
+- 📐 **`panels.grid(blocks, opts)`** — layout de grid en N columnas con auto-flow, gaps, alineación, y opción de ancho uniforme de celda
+- 🎯 **`panels.frame` + `ascii.box` + `ascii.divider`** todos reciben opción `titleAlign` (o `align`): `'left'`, `'center'` (default), `'right'`
+- 🏷️ **`ascii.box` nueva opción `title`** — muestra un label en el borde superior (expande el box si el title es más ancho que el contenido)
+- 📅 **`json.pretty` soporta Map / Set / Date nativamente** — `Date(...)`, `Map(N) [...]`, `Set(N) [...]` en modo display
+- 📤 **`json.pretty` nueva opción `mode: 'json'`** — produce JSON estricto y parseable (sin colores, descarta undefined/functions/symbols, lanza en circulares)
+- 🧪 **+38 tests** entre panels + json + ascii
+
+```js
+import { panels, json, ascii } from 'ansimax';
+
+// Grid de 2×2 con metric cards
+console.log(panels.grid(cards, { columns: 2, gapX: 2 }));
+
+// Title en el borde del box
+console.log(ascii.box('content', { title: 'Section', titleAlign: 'left' }));
+
+// Output JSON estricto (parseable)
+const out = json.pretty(data, { mode: 'json' });
+JSON.parse(out);   // ✓ funciona
+```
+
+Drop-in replacement para `1.3.2`.
+
+### v1.3.2 — Pulido de documentación para frames + images
+
+Release patch con cobertura JSDoc + IntelliSense significativamente mejorada:
+
+- 📝 **Módulo `frames`** — `play`, `generate`, `live`, `morph`, `presets` ahora tienen JSDoc completo con 17 ejemplos ejecutables
+- 📝 **Módulo `images`** — `renderPixelArt`, `gradientRect`, `createCanvas`, `SPRITES` ahora tienen 18 ejemplos ejecutables
+- 🎯 **Total**: +35 nuevos bloques `@example` visibles en tu editor
+
+```js
+// Pasando el cursor sobre frames.play() en VS Code ahora muestra patrones de uso:
+import { frames } from 'ansimax';
+
+await frames.play(myFrames, {
+  interval: 80,
+  loop: true,
+  signal: ctrl.signal,
+  onFrame: (f, i) => color.cyan(`[${i}] ${f}`),
+}).promise;
+```
+
+Release puramente de documentación — cero cambios en código, API o tests.
+Drop-in replacement para `1.3.1`.
+
 ### v1.3.1 — Pulido de panels + json
 
 Release patch que mejora los módulos de v1.3.0 con quality-of-life:
@@ -1349,4 +1458,4 @@ Ansimax está licenciada bajo **Apache License, Version 2.0** — una licencia p
 
 Si Ansimax te ayuda a hacer mejores CLIs, ¡dale ⭐ en [GitHub](https://github.com/Brashkie/ansimax)!
 
-</div>
+</div>

package/README.md

@@ -7,7 +7,7 @@
 _Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-v1.3.1-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.3.3-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-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -215,6 +215,8 @@ console.log(rainbow('built-in rainbow preset'));
 
 ### Animated Gradients (v1.2.0)
 
+<img src="media/animated-gradients.gif" alt="Animated gradients preview" />
+
 ```js
 import { animateGradient, sleep } from 'ansimax';
 
@@ -273,6 +275,8 @@ console.log(gradientRect({
 
 ### Reusable Gradients (v1.2.3)
 
+<img src="media/reusable-gradients.gif" alt="Reusable gradients preview" />
+
 ```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
@@ -319,6 +323,33 @@ console.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));
 
 ### Image → ASCII (v1.2.5)
 
+<div align="center">
+  <img src="media/image-ascii-original.png" alt="Original photo" width="40%" />
+</div>
+
+<table>
+  <tr>
+    <td align="center">
+      <img src="media/image-ascii-1.png" alt="Monochrome mode" /><br/>
+      <sub><b>1. Monochrome</b></sub>
+    </td>
+    <td align="center">
+      <img src="media/image-ascii-2.png" alt="Color + Floyd-Steinberg dithering" /><br/>
+      <sub><b>2. Color + Floyd-Steinberg</b></sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="media/image-ascii-3.png" alt="Edge detection (Sobel)" /><br/>
+      <sub><b>3. Edge detection (Sobel)</b></sub>
+    </td>
+    <td align="center">
+      <img src="media/image-ascii-4.png" alt="Face mode for portraits" /><br/>
+      <sub><b>4. Face mode (portraits)</b></sub>
+    </td>
+  </tr>
+</table>
+
 ```js
 import { ascii } from 'ansimax';
 import sharp from 'sharp';
@@ -342,10 +373,10 @@ for (let y = 0; y < info.height; y++) {
 
 // Now use ansimax — multiple ways:
 
-// Monochrome
+// 1. Monochrome
 console.log(ascii.fromImage(pixels, { width: 80 }));
 
-// Color + Floyd-Steinberg dithering + detailed ramp
+// 2. Color + Floyd-Steinberg dithering + detailed ramp
 console.log(ascii.fromImage(pixels, {
   width: 100,
   color: true,
@@ -353,7 +384,7 @@ console.log(ascii.fromImage(pixels, {
   ramp: 'detailed',
 }));
 
-// Edge-detection mode (line art)
+// 3. Edge-detection mode (line art)
 console.log(ascii.fromImage(pixels, {
   width: 80,
   edgeDetect: 'sobel',
@@ -361,7 +392,7 @@ console.log(ascii.fromImage(pixels, {
   ramp: 'blocks',
 }));
 
-// Face mode for portraits (boosts midtone contrast)
+// 4. Face mode for portraits (boosts midtone contrast)
 console.log(ascii.fromImage(pixels, {
   width: 60,
   ramp: 'detailed',
@@ -371,6 +402,8 @@ console.log(ascii.fromImage(pixels, {
 
 ### Figlet Fonts (v1.2.5)
 
+<img src="media/figlet_fonts.png" alt="Figlet fonts preview" />
+
 ```js
 import { readFileSync } from 'node:fs';
 import { parseFiglet, ascii, gradient } from 'ansimax';
@@ -445,7 +478,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.3.1'));
+console.log(components.badge('VERSION', 'v1.3.3'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -466,6 +499,8 @@ console.log(components.timeline([
 
 ### Loaders & Progress
 
+<img src="media/loaders.png" alt="Loaders and progress bars preview" />
+
 ```js
 import { loader, sleep } from 'ansimax';
 
@@ -495,6 +530,8 @@ await loader.tasks([
 
 ### Animations
 
+<img src="media/animations-1.gif" alt="Animations preview" />
+
 ```js
 import { animate, gradient, sleep } from 'ansimax';
 
@@ -557,6 +594,8 @@ console.log('tenantB themes include custom?', tenantB.list().includes('custom'))
 
 ### Panels — Split Layouts (v1.3.0)
 
+<img src="media/panels.png" alt="Panels and split layouts preview" />
+
 ```js
 import { panels, ascii } from 'ansimax';
 
@@ -586,6 +625,8 @@ console.log(panels.hsplit([
 
 ### JSON Pretty-print (v1.3.0)
 
+<img src="media/json_pretty.png" alt="JSON pretty-print preview" />
+
 ```js
 import { json } from 'ansimax';
 
@@ -599,10 +640,12 @@ console.log(json.pretty({
 }));
 
 // Depth limit — collapses deep objects to {...}
+const deeplyNested = { a: { b: { c: { d: { e: 'too deep' } } } } };
 console.log(json.pretty(deeplyNested, { maxDepth: 2 }));
 
 // Item limit — huge arrays show "... (N more)"
-console.log(json.pretty(largeArray, { maxItems: 10 }));
+const largeArray = Array.from({ length: 50 }, (_, i) => `item_${i}`);
+console.log(json.pretty(largeArray, { maxItems: 5 }));
 
 // Circular references handled gracefully
 const obj = { name: 'foo' };
@@ -612,6 +655,22 @@ console.log(json.pretty(obj));   // → "self": [Circular]
 
 ---
 
+## 📖 Documentation
+
+The [`docs/`](./docs) folder contains comprehensive examples for every module:
+
+| Document | Description |
+|---|---|
+| [`docs/README.md`](./docs/README.md) | Documentation index — start here |
+| [`docs/examples-ts.md`](./docs/examples-ts.md) | 33 TypeScript examples (3 per module × 11 modules) |
+| [`docs/examples-mjs.md`](./docs/examples-mjs.md) | 33 JavaScript ESM examples |
+| [`docs/examples-cjs.md`](./docs/examples-cjs.md) | 33 JavaScript CommonJS examples |
+| [`docs/showcase.md`](./docs/showcase.md) | Complete demo app combining every module |
+
+Every example is **copy-paste runnable** with realistic, mid-complexity scenarios — not just one-liners.
+
+---
+
 ## 📚 Examples
 
 Eleven production-grade examples ship in the npm package and are runnable directly. Find them in [`/examples`](./examples) once you install:
@@ -1006,6 +1065,56 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.3.3 — Features for panels, json, ascii
+
+Patch release with new opt-in features. Zero breaking changes:
+
+- 📐 **`panels.grid(blocks, opts)`** — N-column grid layout with auto-flow, gaps, alignment, and optional uniform cell width
+- 🎯 **`panels.frame` + `ascii.box` + `ascii.divider`** all get a `titleAlign` (or `align`) option: `'left'`, `'center'` (default), `'right'`
+- 🏷️ **`ascii.box` new `title` option** — show a label in the top border (expands box if title is wider than content)
+- 📅 **`json.pretty` supports Map / Set / Date natively** — `Date(...)`, `Map(N) [...]`, `Set(N) [...]` in display mode
+- 📤 **`json.pretty` new `mode: 'json'`** — produces strict, parseable JSON (no colors, drops undefined/functions/symbols, throws on circular)
+- 🧪 **+38 tests** across panels + json + ascii
+
+```js
+import { panels, json, ascii } from 'ansimax';
+
+// 2×2 grid of metric cards
+console.log(panels.grid(cards, { columns: 2, gapX: 2 }));
+
+// Title in box top border
+console.log(ascii.box('content', { title: 'Section', titleAlign: 'left' }));
+
+// Strict JSON output (parseable)
+const out = json.pretty(data, { mode: 'json' });
+JSON.parse(out);   // ✓ works
+```
+
+Drop-in replacement for `1.3.2`.
+
+### v1.3.2 — Documentation polish for frames + images
+
+Patch release with significantly improved JSDoc + IntelliSense coverage:
+
+- 📝 **`frames` module** — `play`, `generate`, `live`, `morph`, `presets` now have full JSDoc with 17 runnable examples
+- 📝 **`images` module** — `renderPixelArt`, `gradientRect`, `createCanvas`, `SPRITES` now have 18 runnable examples
+- 🎯 **Total**: +35 new `@example` blocks visible in your editor
+
+```js
+// Hovering frames.play() in VS Code now shows usage patterns:
+import { frames } from 'ansimax';
+
+await frames.play(myFrames, {
+  interval: 80,
+  loop: true,
+  signal: ctrl.signal,
+  onFrame: (f, i) => color.cyan(`[${i}] ${f}`),
+}).promise;
+```
+
+Pure documentation release — no code, API, or test changes.
+Drop-in replacement for `1.3.1`.
+
 ### v1.3.1 — Polish for panels + json
 
 Patch release improving the modules from v1.3.0 with quality-of-life additions:
@@ -1349,4 +1458,4 @@ Ansimax is licensed under the **Apache License, Version 2.0** — a permissive l
 
 If Ansimax helps you ship better CLIs, give it a ⭐ on [GitHub](https://github.com/Brashkie/ansimax)!
 
-</div>
+</div>