ansimax 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [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.2-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-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.png" 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.png" alt="Vista previa de gradientes reusables" />
+
 ```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
@@ -319,6 +323,8 @@ console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }
 
 ### Imagen → ASCII (v1.2.5)
 
+<img src="media/image_to_ascii.png" alt="Vista previa de Image-to-ASCII" />
+
 ```js
 import { ascii } from 'ansimax';
 import sharp from 'sharp';
@@ -371,6 +377,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 +453,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.2'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -466,6 +474,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 +505,8 @@ await loader.tasks([
 
 ### Animaciones
 
+<img src="media/animations.png" alt="Vista previa de animaciones" />
+
 ```js
 import { animate, gradient, sleep } from 'ansimax';
 
@@ -557,6 +569,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 +600,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';
 
@@ -612,6 +628,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 +1038,29 @@ ansimax/
 
 ## 📝 Changelog
 
+### 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:

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.2-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-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.png" 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.png" alt="Reusable gradients preview" />
+
 ```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
@@ -319,6 +323,8 @@ console.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));
 
 ### Image → ASCII (v1.2.5)
 
+<img src="media/image_to_ascii.png" alt="Image-to-ASCII preview" />
+
 ```js
 import { ascii } from 'ansimax';
 import sharp from 'sharp';
@@ -371,6 +377,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 +453,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.2'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -466,6 +474,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 +505,8 @@ await loader.tasks([
 
 ### Animations
 
+<img src="media/animations.png" alt="Animations preview" />
+
 ```js
 import { animate, gradient, sleep } from 'ansimax';
 
@@ -557,6 +569,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 +600,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';
 
@@ -612,6 +628,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 +1038,29 @@ ansimax/
 
 ## 📝 Changelog
 
+### 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:

package/dist/index.d.mts

@@ -960,7 +960,82 @@ interface RenderOptions$1 {
     /** Use braille (2×4 sub-char resolution). Overrides halfBlock. */
     braille?: boolean;
 }
+/**
+ * Render a 2D grid of pixels (`{r, g, b, a?}` objects) as terminal output
+ * using half-block characters (`▀`) to fit two vertical pixels per row.
+ * This doubles vertical resolution compared to one-character-per-pixel.
+ *
+ * @param pixels - 2D grid of pixel objects.
+ * @param opts   - Render options (scale, background, etc.).
+ *
+ * @example basic pixel art
+ * ```js
+ * import { renderPixelArt } from 'ansimax';
+ *
+ * const heart = [
+ *   [null, {r:255,g:0,b:0}, null, {r:255,g:0,b:0}, null],
+ *   [{r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}],
+ *   [{r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}],
+ *   [null, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, null],
+ *   [null, null, {r:255,g:0,b:0}, null, null],
+ * ];
+ *
+ * console.log(renderPixelArt(heart));
+ * ```
+ *
+ * @example with scale (each pixel rendered as multiple chars)
+ * ```js
+ * console.log(renderPixelArt(myPixels, { scale: 2 }));
+ * // Each pixel becomes 2x2 in the output
+ * ```
+ *
+ * @example with background color (transparent pixels show through)
+ * ```js
+ * console.log(renderPixelArt(myPixels, {
+ *   background: { r: 30, g: 30, b: 30 },
+ * }));
+ * ```
+ *
+ * @example combined with a sprite from SPRITES
+ * ```js
+ * import { renderPixelArt, SPRITES } from 'ansimax';
+ *
+ * console.log(renderPixelArt(SPRITES.heart.pixels, { scale: 3 }));
+ * ```
+ */
 declare const renderPixelArt: (pixels: PixelGrid, opts?: RenderOptions$1) => string;
+/**
+ * Built-in sprite library — small pre-defined pixel art ready for use.
+ *
+ * Each entry has a `pixels` property containing a `PixelGrid`.
+ *
+ * Currently available: `heart`, `star`, `arrow`, `check`, `x`, `bell`,
+ * `gear`, `bolt`, `flag`, `crown`.
+ *
+ * @example render a built-in sprite
+ * ```js
+ * import { renderPixelArt, SPRITES } from 'ansimax';
+ *
+ * console.log(renderPixelArt(SPRITES.heart.pixels));
+ * console.log(renderPixelArt(SPRITES.star.pixels, { scale: 2 }));
+ * ```
+ *
+ * @example list all available sprites
+ * ```js
+ * console.log('Available sprites:', Object.keys(SPRITES).join(', '));
+ * ```
+ *
+ * @example compose sprites on a canvas
+ * ```js
+ * import { createCanvas, SPRITES } from 'ansimax';
+ *
+ * const canvas = createCanvas(30, 10);
+ * canvas.drawSprite(2,  2, SPRITES.heart.pixels);
+ * canvas.drawSprite(10, 2, SPRITES.star.pixels);
+ * canvas.drawSprite(18, 2, SPRITES.crown.pixels);
+ * canvas.print();
+ * ```
+ */
 declare const SPRITES: Record<string, {
     pixels: PixelGrid;
 }>;
@@ -985,6 +1060,78 @@ interface GradientRectOptions {
     /** Render in braille mode for 2× horizontal × 4× vertical resolution. */
     braille?: boolean;
 }
+/**
+ * Render a rectangle filled with a multi-color gradient. Supports horizontal,
+ * vertical, diagonal, arbitrary-angle, radial, and conic gradient styles.
+ *
+ * @param opts - Configuration: dimensions, colors, style, dithering.
+ *
+ * @example horizontal gradient (default)
+ * ```js
+ * import { gradientRect } from 'ansimax';
+ *
+ * console.log(gradientRect({
+ *   width: 40, height: 10,
+ *   colors: ['#ff0000', '#0000ff'],
+ * }));
+ * ```
+ *
+ * @example vertical gradient with multiple stops
+ * ```js
+ * console.log(gradientRect({
+ *   width: 30, height: 15,
+ *   colors: ['#ff0000', '#ffff00', '#00ff00', '#0000ff'],
+ *   style: 'vertical',
+ * }));
+ * ```
+ *
+ * @example arbitrary angle (45° = bottom-left to top-right)
+ * ```js
+ * console.log(gradientRect({
+ *   width: 40, height: 20,
+ *   colors: ['#bd93f9', '#ff79c6'],
+ *   style: 'diagonal',
+ *   angle: 45,
+ * }));
+ * ```
+ *
+ * @example radial gradient (center to edge)
+ * ```js
+ * console.log(gradientRect({
+ *   width: 30, height: 15,
+ *   colors: ['#ffffff', '#000000'],
+ *   style: 'radial',
+ * }));
+ * ```
+ *
+ * @example conic (rainbow wheel) — v1.2.0+
+ * ```js
+ * console.log(gradientRect({
+ *   width: 30, height: 15,
+ *   colors: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff00ff', '#ff0000'],
+ *   style: 'conic',
+ *   startAngle: 0,
+ * }));
+ * ```
+ *
+ * @example with Bayer dithering for smoother tonal transitions
+ * ```js
+ * console.log(gradientRect({
+ *   width: 60, height: 20,
+ *   colors: ['#000033', '#ffcc00'],
+ *   dither: 'bayer',
+ * }));
+ * ```
+ *
+ * @example braille mode (4× vertical resolution per cell)
+ * ```js
+ * console.log(gradientRect({
+ *   width: 60, height: 30,
+ *   colors: ['#ff0000', '#0000ff'],
+ *   braille: true,
+ * }));
+ * ```
+ */
 declare const gradientRect: (opts?: GradientRectOptions) => string;
 interface CanvasRenderOptions extends RenderOptions$1 {
     /** Render only the dirty region instead of the whole canvas. Default: false. */
@@ -1011,6 +1158,61 @@ interface Canvas {
     /** Deep copy of the current pixel grid. Mutations don't affect the canvas. */
     pixels: PixelGrid;
 }
+/**
+ * Create a mutable in-memory canvas with drawing primitives (line, rect,
+ * circle, sprite). The canvas tracks dirty regions so subsequent renders
+ * can update only changed pixels (useful for animation).
+ *
+ * @param width     - Canvas width in pixels (1 to MAX_DIMENSION).
+ * @param height    - Canvas height in pixels (1 to MAX_DIMENSION).
+ * @param fillColor - Initial fill (`null` for transparent). Default `null`.
+ * @returns A Canvas object with drawing methods.
+ *
+ * @example draw and render a simple scene
+ * ```js
+ * import { createCanvas } from 'ansimax';
+ *
+ * const canvas = createCanvas(40, 20, { r: 20, g: 20, b: 30 });
+ *
+ * canvas.drawRect(5, 5, 30, 10, { r: 100, g: 200, b: 255 }, true);
+ * canvas.drawCircle(20, 10, 4, { r: 255, g: 200, b: 0 }, true);
+ * canvas.drawLine(0, 0, 39, 19, { r: 255, g: 0, b: 100 });
+ *
+ * canvas.print();  // render and write to stdout
+ * ```
+ *
+ * @example animated frame with dirty-region tracking
+ * ```js
+ * const canvas = createCanvas(60, 30);
+ *
+ * for (let frame = 0; frame < 100; frame++) {
+ *   canvas.setPixel(frame % 60, 15, { r: 255, g: 0, b: 0 });
+ *
+ *   // Only re-render changed pixels (much faster than full redraw)
+ *   process.stdout.write(canvas.render({ dirtyOnly: true }));
+ *   await new Promise(r => setTimeout(r, 50));
+ * }
+ * ```
+ *
+ * @example composite sprites
+ * ```js
+ * import { createCanvas, SPRITES } from 'ansimax';
+ *
+ * const canvas = createCanvas(40, 20);
+ * canvas.drawSprite(5, 5, SPRITES.heart.pixels);
+ * canvas.drawSprite(20, 5, SPRITES.star.pixels);
+ * canvas.print();
+ * ```
+ *
+ * @example resize while preserving content
+ * ```js
+ * const canvas = createCanvas(20, 10, { r: 50, g: 50, b: 50 });
+ * canvas.drawCircle(10, 5, 3, { r: 255, g: 0, b: 0 });
+ *
+ * canvas.resize(40, 20);  // existing pixels remain in upper-left
+ * canvas.print();
+ * ```
+ */
 declare const createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
 declare const images: {
     render: (pixels: PixelGrid, opts?: RenderOptions$1) => string;