ansimax 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -3,6 +3,111 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.4.1] — Grid v2 + markdown internal refactor
+
+Patch release with two improvements: **grid** gains CSS Grid-style
+column spans + uniform row heights + flow direction control, and the
+**markdown** module is internally refactored from a 522-line monolith
+into 4 focused files (no API changes).
+
+### Added — `panels.grid` v2
+
+**`colSpan: number[]`** — per-block column span (CSS Grid-style):
+
+```js
+import { panels, ascii } from 'ansimax';
+
+const header   = ascii.box('Dashboard', { borderStyle: 'rounded' });
+const sidebar  = ascii.box('Sidebar', { borderStyle: 'rounded' });
+const content  = ascii.box('Main content area', { borderStyle: 'rounded' });
+const footer   = ascii.box('Footer', { borderStyle: 'rounded' });
+
+// 2 columns, header + footer span the full width
+console.log(panels.grid([header, sidebar, content, footer], {
+  columns: 2,
+  colSpan: [2, 1, 1, 2],
+}));
+```
+
+Auto-flow: each block consumes its `span` columns. If a row's remaining
+capacity can't fit the next block, the layout wraps to a new row.
+Invalid spans (NaN, negative, > columns) are normalized to safe values.
+
+**`cellHeight: number | null`** — uniform vertical sizing per row:
+
+```js
+// All rows exactly 5 lines tall — short blocks padded, tall blocks truncated
+panels.grid(blocks, { columns: 3, cellHeight: 5 });
+```
+
+Complements the existing `cellWidth` option for fully uniform grids.
+
+**`flow: 'row' | 'column'`** — auto-flow direction:
+
+```js
+// Default: row flow (left-to-right, then wrap down)
+panels.grid([1, 2, 3, 4, 5, 6], { columns: 3, flow: 'row' });
+//   1 2 3
+//   4 5 6
+
+// Column flow (top-to-bottom, then wrap right)
+panels.grid([1, 2, 3, 4, 5, 6], { columns: 3, flow: 'column' });
+//   1 3 5
+//   2 4 6
+```
+
+When `colSpan` contains values > 1, flow is forced to `'row'` (the
+column-flow + spans combination requires a full packing algorithm,
+deferred to a later release).
+
+### Improved — `markdown` module refactored
+
+The single-file `src/markdown/index.ts` (522 lines) split into 5 files
+of focused responsibility — **zero API changes, fully backward compatible**:
+
+```
+src/markdown/
+├── types.ts          — Public types (MarkdownTheme, Block, …)
+├── theme.ts          — Color palettes (THEMES record, private)
+├── block-parser.ts   — parseBlocks + line regexes
+├── inline-parser.ts  — parseInline + protected-code placeholders
+├── renderer.ts       — render (dispatches blocks → ansimax primitives)
+└── index.ts          — Re-exports + `markdown` namespace
+```
+
+External imports keep working unchanged:
+
+```js
+import { markdown, parseMarkdownBlocks, parseMarkdownInline, renderMarkdown }
+  from 'ansimax';
+```
+
+Submodule imports now also work (advanced use):
+
+```js
+import { parseBlocks } from 'ansimax/markdown/block-parser';   // tree-shake friendly
+```
+
+### Improved — Tests
+
+- `+18` tests for `colSpan` (defaults, clamping, wrapping, invalid input)
+- `+4` tests for `cellHeight` (pad, truncate, null, zero clamp)
+- `+5` tests for `flow` (row, column, non-multiples, fallback with colSpan)
+- `+1` integration test (colSpan + cellHeight together)
+- `+4` tests verifying submodule imports work after refactor
+
+Total: **+32 tests** in `panels.test.ts` and `markdown.test.ts`.
+
+### Notes
+
+- **Zero behavior changes** for v1.4.0 users — `panels.grid` without the
+  new options produces byte-identical output
+- **Zero breaking changes** — `markdown` API surface unchanged
+- Submodule imports enabled (`ansimax/markdown/block-parser`) for
+  tree-shaking-friendly bundling
+
+---
+
 ## [1.4.0] — Phase 4 closure: Markdown rendering
 
 **Minor release** introducing the long-planned `markdown` module — the

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.4.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.4.1-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -478,7 +478,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.4.0'));
+console.log(components.badge('VERSION', 'v1.4.1'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -1065,6 +1065,30 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.4.1 — Grid v2 + refactor markdown
+
+Release patch. Cero breaking changes:
+
+- 🎯 **`panels.grid` — colSpan**: span de columnas por bloque (auto-flow estilo CSS Grid)
+- 📏 **`panels.grid` — cellHeight**: alturas de fila uniformes (complementa `cellWidth`)
+- 🔀 **`panels.grid` — flow**: dirección de auto-flow `'row'` (default) o `'column'`
+- 📁 **`markdown` refactorizado** de monolito de 522 líneas → 5 submódulos enfocados (API sin cambios)
+- 🌳 Imports de submódulo habilitados: `import { parseBlocks } from 'ansimax/markdown/block-parser'`
+- 🧪 **+32 tests**
+
+```js
+import { panels, ascii } from 'ansimax';
+
+// Header span ambas columnas, luego sidebar + content lado a lado
+panels.grid([header, sidebar, content], {
+  columns: 2,
+  colSpan: [2, 1, 1],
+  cellHeight: 10,    // altura de fila uniforme
+});
+```
+
+Drop-in replacement para `1.4.0`.
+
 ### v1.4.0 — Cierre de Fase 4: Renderizado Markdown 🎉
 
 **Release minor** completando la Fase 4 con el nuevo módulo `markdown`:

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.4.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.4.1-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -478,7 +478,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.4.0'));
+console.log(components.badge('VERSION', 'v1.4.1'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -1065,6 +1065,30 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.4.1 — Grid v2 + markdown refactor
+
+Patch release. Zero breaking changes:
+
+- 🎯 **`panels.grid` — colSpan**: per-block column span (CSS Grid-style auto-flow)
+- 📏 **`panels.grid` — cellHeight**: uniform row heights (complements `cellWidth`)
+- 🔀 **`panels.grid` — flow**: `'row'` (default) or `'column'` auto-flow direction
+- 📁 **`markdown` refactored** from 522-line monolith → 5 focused submodules (API unchanged)
+- 🌳 Submodule imports enabled: `import { parseBlocks } from 'ansimax/markdown/block-parser'`
+- 🧪 **+32 tests**
+
+```js
+import { panels, ascii } from 'ansimax';
+
+// Header spans both columns, then sidebar + content side by side
+panels.grid([header, sidebar, content], {
+  columns: 2,
+  colSpan: [2, 1, 1],
+  cellHeight: 10,    // uniform row height
+});
+```
+
+Drop-in replacement for `1.4.0`.
+
 ### v1.4.0 — Phase 4 closure: Markdown rendering 🎉
 
 **Minor release** completing Phase 4 with the new `markdown` module:

package/dist/index.d.mts

@@ -1,3 +1,76 @@
+/** Visual theme for rendered output. */
+type MarkdownTheme = 'dark' | 'light';
+interface MarkdownOptions {
+    /**
+     * Maximum width in columns. Long lines wrap. Default: terminal width
+     * or 80 if unavailable.
+     */
+    width?: number;
+    /**
+     * Color theme. `'dark'` (default) uses bright colors for dark backgrounds.
+     * `'light'` uses dimmer/contrast colors for light backgrounds.
+     */
+    theme?: MarkdownTheme;
+    /**
+     * Override the gradient used for top-level (`# H1`) headings. Receives
+     * a list of hex colors. Default uses the dracula palette.
+     */
+    headingGradient?: string[];
+    /**
+     * Render code blocks inside an ASCII box. Default `true`. If `false`,
+     * code blocks render as indented dim text.
+     */
+    boxCodeBlocks?: boolean;
+    /**
+     * Inline code background tint. Default `true`. If `false`, inline code
+     * shows only as dim text (cleaner in some terminals).
+     */
+    inlineCodeBackground?: boolean;
+}
+/**
+ * Internal options shape passed to `parseInline`. Exposed for advanced
+ * use cases that bypass `render` (custom block handlers, etc.).
+ *
+ * @since 1.4.0
+ */
+interface InlineOptions {
+    theme: MarkdownTheme;
+    inlineCodeBackground: boolean;
+}
+/**
+ * Block-level token after parsing the markdown into structural pieces.
+ * Tokens contain raw inline text — inline parsing happens at render time.
+ *
+ * @since 1.4.0
+ */
+type Block = {
+    type: 'heading';
+    level: number;
+    text: string;
+} | {
+    type: 'paragraph';
+    text: string;
+} | {
+    type: 'codeblock';
+    lang: string;
+    code: string;
+} | {
+    type: 'list';
+    ordered: boolean;
+    items: string[];
+} | {
+    type: 'blockquote';
+    text: string;
+} | {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+} | {
+    type: 'hr';
+} | {
+    type: 'blank';
+};
+
 /** Color rendering capability. 'none' suppresses all color output. */
 type ColorMode = 'none' | 'basic' | '256' | 'truecolor' | 'auto';
 /** Animation pacing multiplier preset. */
@@ -2713,6 +2786,46 @@ interface GridOptions {
      * use the max width of the widest block in their column.
      */
     cellWidth?: number | null;
+    /**
+     * **v1.4.1+** Fix each row to this height (in lines). When the block has
+     * fewer lines, it is padded (using `alignY`). When it has more lines, it
+     * is truncated. If omitted (default), rows take the natural height of
+     * their tallest block.
+     *
+     * @since 1.4.1
+     */
+    cellHeight?: number | null;
+    /**
+     * **v1.4.1+** Per-block column span. `colSpan[i]` is the number of
+     * columns block `i` occupies. Defaults to `1` for every block when
+     * omitted or shorter than `blocks`.
+     *
+     * The auto-flow algorithm wraps to the next row when the current row's
+     * remaining capacity is less than the next block's span. Spans that
+     * exceed `columns` are clamped to `columns`.
+     *
+     * @example
+     * ```js
+     * // Header spans full width, then 2 cells in a row
+     * panels.grid([header, left, right], {
+     *   columns: 2,
+     *   colSpan: [2, 1, 1],
+     * });
+     * ```
+     *
+     * @since 1.4.1
+     */
+    colSpan?: number[];
+    /**
+     * **v1.4.1+** Auto-flow direction. `'row'` (default) fills cells
+     * left-to-right then wraps to the next row — matches CSS Grid's
+     * `grid-auto-flow: row`. `'column'` fills top-to-bottom then wraps to
+     * the next column. Not applicable when `colSpan` is set with any
+     * span > 1 (forces 'row' mode).
+     *
+     * @since 1.4.1
+     */
+    flow?: 'row' | 'column';
 }
 /**
  * Arrange blocks in a grid of N columns, flowing left-to-right then
@@ -2887,63 +3000,6 @@ declare const json: {
     pretty: (value: unknown, opts?: PrettyOptions) => string;
 };
 
-/** Visual theme for rendered output. */
-type MarkdownTheme = 'dark' | 'light';
-interface MarkdownOptions {
-    /**
-     * Maximum width in columns. Long lines wrap. Default: terminal width
-     * or 80 if unavailable.
-     */
-    width?: number;
-    /**
-     * Color theme. `'dark'` (default) uses bright colors for dark backgrounds.
-     * `'light'` uses dimmer/contrast colors for light backgrounds.
-     */
-    theme?: MarkdownTheme;
-    /**
-     * Override the gradient used for top-level (`# H1`) headings. Receives
-     * a list of hex colors. Default uses the dracula palette.
-     */
-    headingGradient?: string[];
-    /**
-     * Render code blocks inside an ASCII box. Default `true`. If `false`,
-     * code blocks render as indented dim text.
-     */
-    boxCodeBlocks?: boolean;
-    /**
-     * Inline code background tint. Default `true`. If `false`, inline code
-     * shows only as dim text (cleaner in some terminals).
-     */
-    inlineCodeBackground?: boolean;
-}
-/** Block-level token after parsing the markdown into structural pieces. */
-type Block = {
-    type: 'heading';
-    level: number;
-    text: string;
-} | {
-    type: 'paragraph';
-    text: string;
-} | {
-    type: 'codeblock';
-    lang: string;
-    code: string;
-} | {
-    type: 'list';
-    ordered: boolean;
-    items: string[];
-} | {
-    type: 'blockquote';
-    text: string;
-} | {
-    type: 'table';
-    headers: string[];
-    rows: string[][];
-} | {
-    type: 'hr';
-} | {
-    type: 'blank';
-};
 /**
  * Parse markdown source into a flat sequence of block tokens.
  * Tokens contain raw inline text — inline parsing happens at render time.
@@ -2951,15 +3007,14 @@ type Block = {
  * @since 1.4.0
  */
 declare const parseBlocks: (source: string) => Block[];
+
 /**
  * Apply inline markdown markup (bold/italic/code/links/etc.) to a string.
  *
  * @since 1.4.0
  */
-declare const parseInline: (text: string, opts?: {
-    theme: MarkdownTheme;
-    inlineCodeBackground: boolean;
-}) => string;
+declare const parseInline: (text: string, opts?: InlineOptions) => string;
+
 /**
  * Render a markdown source string to a terminal-ready string with ANSI
  * styling. Handles headings, paragraphs, code blocks, lists, blockquotes,
@@ -2988,6 +3043,7 @@ declare const parseInline: (text: string, opts?: {
  * @since 1.4.0
  */
 declare const render: (source: string, opts?: MarkdownOptions) => string;
+
 /**
  * Markdown → terminal renderer. Use `markdown.render(source, opts?)` to
  * convert a markdown string to an ANSI-styled string ready for
@@ -3001,10 +3057,7 @@ declare const render: (source: string, opts?: MarkdownOptions) => string;
 declare const markdown: {
     render: (source: string, opts?: MarkdownOptions) => string;
     parseBlocks: (source: string) => Block[];
-    parseInline: (text: string, opts?: {
-        theme: MarkdownTheme;
-        inlineCodeBackground: boolean;
-    }) => string;
+    parseInline: (text: string, opts?: InlineOptions) => string;
 };
 
 type EasingFunction = (t: number) => number;
@@ -3220,37 +3273,8 @@ declare const ansimax: {
     };
     markdown: {
         render: (source: string, opts?: MarkdownOptions) => string;
-        parseBlocks: (source: string) => ({
-            type: "heading";
-            level: number;
-            text: string;
-        } | {
-            type: "paragraph";
-            text: string;
-        } | {
-            type: "codeblock";
-            lang: string;
-            code: string;
-        } | {
-            type: "list";
-            ordered: boolean;
-            items: string[];
-        } | {
-            type: "blockquote";
-            text: string;
-        } | {
-            type: "table";
-            headers: string[];
-            rows: string[][];
-        } | {
-            type: "hr";
-        } | {
-            type: "blank";
-        })[];
-        parseInline: (text: string, opts?: {
-            theme: MarkdownTheme;
-            inlineCodeBackground: boolean;
-        }) => string;
+        parseBlocks: (source: string) => Block[];
+        parseInline: (text: string, opts?: InlineOptions) => string;
     };
 };
 

package/dist/index.d.ts

@@ -1,3 +1,76 @@
+/** Visual theme for rendered output. */
+type MarkdownTheme = 'dark' | 'light';
+interface MarkdownOptions {
+    /**
+     * Maximum width in columns. Long lines wrap. Default: terminal width
+     * or 80 if unavailable.
+     */
+    width?: number;
+    /**
+     * Color theme. `'dark'` (default) uses bright colors for dark backgrounds.
+     * `'light'` uses dimmer/contrast colors for light backgrounds.
+     */
+    theme?: MarkdownTheme;
+    /**
+     * Override the gradient used for top-level (`# H1`) headings. Receives
+     * a list of hex colors. Default uses the dracula palette.
+     */
+    headingGradient?: string[];
+    /**
+     * Render code blocks inside an ASCII box. Default `true`. If `false`,
+     * code blocks render as indented dim text.
+     */
+    boxCodeBlocks?: boolean;
+    /**
+     * Inline code background tint. Default `true`. If `false`, inline code
+     * shows only as dim text (cleaner in some terminals).
+     */
+    inlineCodeBackground?: boolean;
+}
+/**
+ * Internal options shape passed to `parseInline`. Exposed for advanced
+ * use cases that bypass `render` (custom block handlers, etc.).
+ *
+ * @since 1.4.0
+ */
+interface InlineOptions {
+    theme: MarkdownTheme;
+    inlineCodeBackground: boolean;
+}
+/**
+ * Block-level token after parsing the markdown into structural pieces.
+ * Tokens contain raw inline text — inline parsing happens at render time.
+ *
+ * @since 1.4.0
+ */
+type Block = {
+    type: 'heading';
+    level: number;
+    text: string;
+} | {
+    type: 'paragraph';
+    text: string;
+} | {
+    type: 'codeblock';
+    lang: string;
+    code: string;
+} | {
+    type: 'list';
+    ordered: boolean;
+    items: string[];
+} | {
+    type: 'blockquote';
+    text: string;
+} | {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+} | {
+    type: 'hr';
+} | {
+    type: 'blank';
+};
+
 /** Color rendering capability. 'none' suppresses all color output. */
 type ColorMode = 'none' | 'basic' | '256' | 'truecolor' | 'auto';
 /** Animation pacing multiplier preset. */
@@ -2713,6 +2786,46 @@ interface GridOptions {
      * use the max width of the widest block in their column.
      */
     cellWidth?: number | null;
+    /**
+     * **v1.4.1+** Fix each row to this height (in lines). When the block has
+     * fewer lines, it is padded (using `alignY`). When it has more lines, it
+     * is truncated. If omitted (default), rows take the natural height of
+     * their tallest block.
+     *
+     * @since 1.4.1
+     */
+    cellHeight?: number | null;
+    /**
+     * **v1.4.1+** Per-block column span. `colSpan[i]` is the number of
+     * columns block `i` occupies. Defaults to `1` for every block when
+     * omitted or shorter than `blocks`.
+     *
+     * The auto-flow algorithm wraps to the next row when the current row's
+     * remaining capacity is less than the next block's span. Spans that
+     * exceed `columns` are clamped to `columns`.
+     *
+     * @example
+     * ```js
+     * // Header spans full width, then 2 cells in a row
+     * panels.grid([header, left, right], {
+     *   columns: 2,
+     *   colSpan: [2, 1, 1],
+     * });
+     * ```
+     *
+     * @since 1.4.1
+     */
+    colSpan?: number[];
+    /**
+     * **v1.4.1+** Auto-flow direction. `'row'` (default) fills cells
+     * left-to-right then wraps to the next row — matches CSS Grid's
+     * `grid-auto-flow: row`. `'column'` fills top-to-bottom then wraps to
+     * the next column. Not applicable when `colSpan` is set with any
+     * span > 1 (forces 'row' mode).
+     *
+     * @since 1.4.1
+     */
+    flow?: 'row' | 'column';
 }
 /**
  * Arrange blocks in a grid of N columns, flowing left-to-right then
@@ -2887,63 +3000,6 @@ declare const json: {
     pretty: (value: unknown, opts?: PrettyOptions) => string;
 };
 
-/** Visual theme for rendered output. */
-type MarkdownTheme = 'dark' | 'light';
-interface MarkdownOptions {
-    /**
-     * Maximum width in columns. Long lines wrap. Default: terminal width
-     * or 80 if unavailable.
-     */
-    width?: number;
-    /**
-     * Color theme. `'dark'` (default) uses bright colors for dark backgrounds.
-     * `'light'` uses dimmer/contrast colors for light backgrounds.
-     */
-    theme?: MarkdownTheme;
-    /**
-     * Override the gradient used for top-level (`# H1`) headings. Receives
-     * a list of hex colors. Default uses the dracula palette.
-     */
-    headingGradient?: string[];
-    /**
-     * Render code blocks inside an ASCII box. Default `true`. If `false`,
-     * code blocks render as indented dim text.
-     */
-    boxCodeBlocks?: boolean;
-    /**
-     * Inline code background tint. Default `true`. If `false`, inline code
-     * shows only as dim text (cleaner in some terminals).
-     */
-    inlineCodeBackground?: boolean;
-}
-/** Block-level token after parsing the markdown into structural pieces. */
-type Block = {
-    type: 'heading';
-    level: number;
-    text: string;
-} | {
-    type: 'paragraph';
-    text: string;
-} | {
-    type: 'codeblock';
-    lang: string;
-    code: string;
-} | {
-    type: 'list';
-    ordered: boolean;
-    items: string[];
-} | {
-    type: 'blockquote';
-    text: string;
-} | {
-    type: 'table';
-    headers: string[];
-    rows: string[][];
-} | {
-    type: 'hr';
-} | {
-    type: 'blank';
-};
 /**
  * Parse markdown source into a flat sequence of block tokens.
  * Tokens contain raw inline text — inline parsing happens at render time.
@@ -2951,15 +3007,14 @@ type Block = {
  * @since 1.4.0
  */
 declare const parseBlocks: (source: string) => Block[];
+
 /**
  * Apply inline markdown markup (bold/italic/code/links/etc.) to a string.
  *
  * @since 1.4.0
  */
-declare const parseInline: (text: string, opts?: {
-    theme: MarkdownTheme;
-    inlineCodeBackground: boolean;
-}) => string;
+declare const parseInline: (text: string, opts?: InlineOptions) => string;
+
 /**
  * Render a markdown source string to a terminal-ready string with ANSI
  * styling. Handles headings, paragraphs, code blocks, lists, blockquotes,
@@ -2988,6 +3043,7 @@ declare const parseInline: (text: string, opts?: {
  * @since 1.4.0
  */
 declare const render: (source: string, opts?: MarkdownOptions) => string;
+
 /**
  * Markdown → terminal renderer. Use `markdown.render(source, opts?)` to
  * convert a markdown string to an ANSI-styled string ready for
@@ -3001,10 +3057,7 @@ declare const render: (source: string, opts?: MarkdownOptions) => string;
 declare const markdown: {
     render: (source: string, opts?: MarkdownOptions) => string;
     parseBlocks: (source: string) => Block[];
-    parseInline: (text: string, opts?: {
-        theme: MarkdownTheme;
-        inlineCodeBackground: boolean;
-    }) => string;
+    parseInline: (text: string, opts?: InlineOptions) => string;
 };
 
 type EasingFunction = (t: number) => number;
@@ -3220,37 +3273,8 @@ declare const ansimax: {
     };
     markdown: {
         render: (source: string, opts?: MarkdownOptions) => string;
-        parseBlocks: (source: string) => ({
-            type: "heading";
-            level: number;
-            text: string;
-        } | {
-            type: "paragraph";
-            text: string;
-        } | {
-            type: "codeblock";
-            lang: string;
-            code: string;
-        } | {
-            type: "list";
-            ordered: boolean;
-            items: string[];
-        } | {
-            type: "blockquote";
-            text: string;
-        } | {
-            type: "table";
-            headers: string[];
-            rows: string[][];
-        } | {
-            type: "hr";
-        } | {
-            type: "blank";
-        })[];
-        parseInline: (text: string, opts?: {
-            theme: MarkdownTheme;
-            inlineCodeBackground: boolean;
-        }) => string;
+        parseBlocks: (source: string) => Block[];
+        parseInline: (text: string, opts?: InlineOptions) => string;
     };
 };
 

package/dist/index.js

@@ -6158,37 +6158,105 @@ var grid = (blocks, opts) => {
   const alignX = opts.alignX ?? "start";
   const alignY = opts.alignY ?? "start";
   const cellW = opts.cellWidth != null ? Math.max(0, Math.floor(opts.cellWidth)) : null;
-  const rows = [];
-  for (let i = 0; i < blocks.length; i += columns2) {
-    rows.push(blocks.slice(i, i + columns2));
+  const cellH = opts.cellHeight != null ? Math.max(1, Math.floor(opts.cellHeight)) : null;
+  const flow = opts.flow === "column" ? "column" : "row";
+  const spans = blocks.map((_, i) => {
+    const raw = opts.colSpan?.[i];
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 1) return 1;
+    return Math.min(columns2, Math.floor(raw));
+  });
+  const hasSpans = spans.some((s) => s > 1);
+  const cellRows = [];
+  if (flow === "column" && !hasSpans) {
+    const rowCount = Math.ceil(blocks.length / columns2);
+    for (let r = 0; r < rowCount; r++) cellRows.push([]);
+    for (let i = 0; i < blocks.length; i++) {
+      const c = Math.floor(i / rowCount);
+      const r = i % rowCount;
+      cellRows[r].push({ block: blocks[i], span: 1, col: c });
+    }
+  } else {
+    let row = [];
+    let colInRow = 0;
+    for (let i = 0; i < blocks.length; i++) {
+      const span = spans[i];
+      if (colInRow + span > columns2 && row.length > 0) {
+        cellRows.push(row);
+        row = [];
+        colInRow = 0;
+      }
+      row.push({ block: blocks[i], span, col: colInRow });
+      colInRow += span;
+    }
+    if (row.length > 0) cellRows.push(row);
   }
-  let widths = null;
+  let widths;
   if (cellW != null) {
     widths = Array(columns2).fill(cellW);
   } else {
     widths = Array(columns2).fill(0);
-    for (const row of rows) {
-      for (let c = 0; c < row.length; c++) {
-        const { maxWidth } = _splitBlock(row[c]);
-        if (maxWidth > widths[c]) {
-          widths[c] = maxWidth;
+    for (const r of cellRows) {
+      for (const cell of r) {
+        if (cell.span === 1) {
+          const { maxWidth } = _splitBlock(cell.block);
+          if (maxWidth > widths[cell.col]) {
+            widths[cell.col] = maxWidth;
+          }
         }
       }
     }
-  }
-  const renderedRows = rows.map((row) => {
-    const padded = [];
     for (let c = 0; c < columns2; c++) {
-      padded.push(row[c] ?? "");
+      if (widths[c] === 0) {
+        for (const r of cellRows) {
+          for (const cell of r) {
+            if (cell.col <= c && cell.col + cell.span > c) {
+              const { maxWidth } = _splitBlock(cell.block);
+              const each = Math.ceil(maxWidth / cell.span);
+              if (each > widths[c]) widths[c] = each;
+            }
+          }
+        }
+      }
     }
-    return vsplit(padded, {
+  }
+  const renderedRows = cellRows.map((row) => {
+    const mergedBlocks = [];
+    const mergedWidths = [];
+    let nextCol = 0;
+    for (const cell of row) {
+      let w = 0;
+      for (let k = 0; k < cell.span; k++) {
+        w += widths[cell.col + k];
+      }
+      w += Math.max(0, cell.span - 1) * gapX;
+      let blockToRender = cell.block;
+      if (cellH != null) {
+        blockToRender = _fitHeight(cell.block, cellH);
+      }
+      mergedBlocks.push(blockToRender);
+      mergedWidths.push(w);
+      nextCol += cell.span;
+    }
+    while (nextCol < columns2) {
+      mergedBlocks.push("");
+      mergedWidths.push(widths[nextCol]);
+      nextCol++;
+    }
+    return vsplit(mergedBlocks, {
       gap: gapX,
       align: alignY,
-      widths
+      widths: mergedWidths
     });
   });
   return hsplit(renderedRows, { gap: gapY, align: alignX });
 };
+var _fitHeight = (block, targetH) => {
+  const lines = block.split("\n");
+  if (lines.length === targetH) return block;
+  if (lines.length > targetH) return lines.slice(0, targetH).join("\n");
+  const pad = Array(targetH - lines.length).fill("");
+  return [...lines, ...pad].join("\n");
+};
 var panels = {
   vsplit,
   hsplit,
@@ -6346,8 +6414,8 @@ var _renderValue = (value, depth, config) => {
           inlineItems.push(_c(`... (${remaining} more)`, COLORS.comment, useColor));
         }
         const candidate = _c("[", COLORS.bracket, useColor) + inlineItems.join(", ") + _c("]", COLORS.bracket, useColor);
-        const visibleLen3 = candidate.replace(/\x1b\[[0-9;]*m/g, "").length;
-        if (visibleLen3 <= inlineArrayMaxLength) {
+        const visibleLen2 = candidate.replace(/\x1b\[[0-9;]*m/g, "").length;
+        if (visibleLen2 <= inlineArrayMaxLength) {
           return candidate;
         }
       }
@@ -6426,38 +6494,7 @@ var json = {
   pretty
 };
 
-// src/markdown/index.ts
-var THEMES = {
-  dark: {
-    h1: ["#ff79c6", "#bd93f9", "#8be9fd"],
-    h2: "#bd93f9",
-    h3: "#8be9fd",
-    h4: "#50fa7b",
-    h5: "#f1fa8c",
-    h6: "#ffb86c",
-    code: "#ff79c6",
-    codeBlockBorder: "#6272a4",
-    link: "#8be9fd",
-    blockquote: "#6272a4",
-    hr: "#6272a4",
-    tableHeader: "#bd93f9"
-  },
-  light: {
-    h1: ["#d63384", "#6f42c1", "#0d6efd"],
-    h2: "#6f42c1",
-    h3: "#0d6efd",
-    h4: "#198754",
-    h5: "#664d03",
-    h6: "#fd7e14",
-    code: "#d63384",
-    codeBlockBorder: "#adb5bd",
-    link: "#0d6efd",
-    blockquote: "#6c757d",
-    hr: "#adb5bd",
-    tableHeader: "#6f42c1"
-  }
-};
-var _normalize = (text) => typeof text === "string" ? text.replace(/\r\n/g, "\n").replace(/\r/g, "\n") : "";
+// src/markdown/block-parser.ts
 var HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
 var ORDERED_LIST_RE = /^(\s*)(\d+)[.)]\s+(.+)$/;
 var UNORDERED_LIST_RE = /^(\s*)[-*+]\s+(.+)$/;
@@ -6467,6 +6504,11 @@ var CODEBLOCK_CLOSE_RE = /^```\s*$/;
 var BLOCKQUOTE_RE = /^>\s?(.*)$/;
 var TABLE_SEPARATOR_RE = /^\|?[ \t]*:?-{2,}:?[ \t]*(\|[ \t]*:?-{2,}:?[ \t]*)+\|?[ \t]*$/;
 var TABLE_ROW_RE = /^\|.*\|[ \t]*$/;
+var _normalize = (text) => typeof text === "string" ? text.replace(/\r\n/g, "\n").replace(/\r/g, "\n") : "";
+var _splitTableRow = (row) => {
+  const stripped = row.trim().replace(/^\|/, "").replace(/\|[ \t]*$/, "");
+  return stripped.split("|").map((c) => c.trim());
+};
 var parseBlocks = (source) => {
   if (typeof source !== "string" || source.length === 0) return [];
   const lines = _normalize(source).split("\n");
@@ -6562,14 +6604,41 @@ var parseBlocks = (source) => {
   }
   return out;
 };
-var _splitTableRow = (row) => {
-  const stripped = row.trim().replace(/^\|/, "").replace(/\|[ \t]*$/, "");
-  return stripped.split("|").map((c) => c.trim());
+
+// src/markdown/theme.ts
+var THEMES = {
+  dark: {
+    h1: ["#ff79c6", "#bd93f9", "#8be9fd"],
+    h2: "#bd93f9",
+    h3: "#8be9fd",
+    h4: "#50fa7b",
+    h5: "#f1fa8c",
+    h6: "#ffb86c",
+    code: "#ff79c6",
+    codeBlockBorder: "#6272a4",
+    link: "#8be9fd",
+    blockquote: "#6272a4",
+    hr: "#6272a4",
+    tableHeader: "#bd93f9"
+  },
+  light: {
+    h1: ["#d63384", "#6f42c1", "#0d6efd"],
+    h2: "#6f42c1",
+    h3: "#0d6efd",
+    h4: "#198754",
+    h5: "#664d03",
+    h6: "#fd7e14",
+    code: "#d63384",
+    codeBlockBorder: "#adb5bd",
+    link: "#0d6efd",
+    blockquote: "#6c757d",
+    hr: "#adb5bd",
+    tableHeader: "#6f42c1"
+  }
 };
-var parseInline = (text, opts = {
-  theme: "dark",
-  inlineCodeBackground: true
-}) => {
+
+// src/markdown/inline-parser.ts
+var parseInline = (text, opts = { theme: "dark", inlineCodeBackground: true }) => {
   if (typeof text !== "string" || text.length === 0) return "";
   const t = THEMES[opts.theme];
   const codeSlots = [];
@@ -6589,6 +6658,8 @@ var parseInline = (text, opts = {
   s = s.replace(/\x00CODE(\d+)\x00/g, (_m, idx) => codeSlots[Number(idx)] ?? "");
   return s;
 };
+
+// src/markdown/renderer.ts
 var _detectWidth = () => {
   const w = process.stdout?.columns;
   return isFiniteNumber2(w) && w > 10 ? w : 80;
@@ -6683,6 +6754,8 @@ var render = (source, opts = {}) => {
   while (out.length > 0 && out[out.length - 1] === "") out.pop();
   return out.join("\n");
 };
+
+// src/markdown/index.ts
 var markdown = {
   render,
   parseBlocks,

package/dist/index.mjs

@@ -5946,37 +5946,105 @@ var grid = (blocks, opts) => {
   const alignX = opts.alignX ?? "start";
   const alignY = opts.alignY ?? "start";
   const cellW = opts.cellWidth != null ? Math.max(0, Math.floor(opts.cellWidth)) : null;
-  const rows = [];
-  for (let i = 0; i < blocks.length; i += columns2) {
-    rows.push(blocks.slice(i, i + columns2));
+  const cellH = opts.cellHeight != null ? Math.max(1, Math.floor(opts.cellHeight)) : null;
+  const flow = opts.flow === "column" ? "column" : "row";
+  const spans = blocks.map((_, i) => {
+    const raw = opts.colSpan?.[i];
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 1) return 1;
+    return Math.min(columns2, Math.floor(raw));
+  });
+  const hasSpans = spans.some((s) => s > 1);
+  const cellRows = [];
+  if (flow === "column" && !hasSpans) {
+    const rowCount = Math.ceil(blocks.length / columns2);
+    for (let r = 0; r < rowCount; r++) cellRows.push([]);
+    for (let i = 0; i < blocks.length; i++) {
+      const c = Math.floor(i / rowCount);
+      const r = i % rowCount;
+      cellRows[r].push({ block: blocks[i], span: 1, col: c });
+    }
+  } else {
+    let row = [];
+    let colInRow = 0;
+    for (let i = 0; i < blocks.length; i++) {
+      const span = spans[i];
+      if (colInRow + span > columns2 && row.length > 0) {
+        cellRows.push(row);
+        row = [];
+        colInRow = 0;
+      }
+      row.push({ block: blocks[i], span, col: colInRow });
+      colInRow += span;
+    }
+    if (row.length > 0) cellRows.push(row);
   }
-  let widths = null;
+  let widths;
   if (cellW != null) {
     widths = Array(columns2).fill(cellW);
   } else {
     widths = Array(columns2).fill(0);
-    for (const row of rows) {
-      for (let c = 0; c < row.length; c++) {
-        const { maxWidth } = _splitBlock(row[c]);
-        if (maxWidth > widths[c]) {
-          widths[c] = maxWidth;
+    for (const r of cellRows) {
+      for (const cell of r) {
+        if (cell.span === 1) {
+          const { maxWidth } = _splitBlock(cell.block);
+          if (maxWidth > widths[cell.col]) {
+            widths[cell.col] = maxWidth;
+          }
         }
       }
     }
-  }
-  const renderedRows = rows.map((row) => {
-    const padded = [];
     for (let c = 0; c < columns2; c++) {
-      padded.push(row[c] ?? "");
+      if (widths[c] === 0) {
+        for (const r of cellRows) {
+          for (const cell of r) {
+            if (cell.col <= c && cell.col + cell.span > c) {
+              const { maxWidth } = _splitBlock(cell.block);
+              const each = Math.ceil(maxWidth / cell.span);
+              if (each > widths[c]) widths[c] = each;
+            }
+          }
+        }
+      }
     }
-    return vsplit(padded, {
+  }
+  const renderedRows = cellRows.map((row) => {
+    const mergedBlocks = [];
+    const mergedWidths = [];
+    let nextCol = 0;
+    for (const cell of row) {
+      let w = 0;
+      for (let k = 0; k < cell.span; k++) {
+        w += widths[cell.col + k];
+      }
+      w += Math.max(0, cell.span - 1) * gapX;
+      let blockToRender = cell.block;
+      if (cellH != null) {
+        blockToRender = _fitHeight(cell.block, cellH);
+      }
+      mergedBlocks.push(blockToRender);
+      mergedWidths.push(w);
+      nextCol += cell.span;
+    }
+    while (nextCol < columns2) {
+      mergedBlocks.push("");
+      mergedWidths.push(widths[nextCol]);
+      nextCol++;
+    }
+    return vsplit(mergedBlocks, {
       gap: gapX,
       align: alignY,
-      widths
+      widths: mergedWidths
     });
   });
   return hsplit(renderedRows, { gap: gapY, align: alignX });
 };
+var _fitHeight = (block, targetH) => {
+  const lines = block.split("\n");
+  if (lines.length === targetH) return block;
+  if (lines.length > targetH) return lines.slice(0, targetH).join("\n");
+  const pad = Array(targetH - lines.length).fill("");
+  return [...lines, ...pad].join("\n");
+};
 var panels = {
   vsplit,
   hsplit,
@@ -6134,8 +6202,8 @@ var _renderValue = (value, depth, config) => {
           inlineItems.push(_c(`... (${remaining} more)`, COLORS.comment, useColor));
         }
         const candidate = _c("[", COLORS.bracket, useColor) + inlineItems.join(", ") + _c("]", COLORS.bracket, useColor);
-        const visibleLen3 = candidate.replace(/\x1b\[[0-9;]*m/g, "").length;
-        if (visibleLen3 <= inlineArrayMaxLength) {
+        const visibleLen2 = candidate.replace(/\x1b\[[0-9;]*m/g, "").length;
+        if (visibleLen2 <= inlineArrayMaxLength) {
           return candidate;
         }
       }
@@ -6214,38 +6282,7 @@ var json = {
   pretty
 };
 
-// src/markdown/index.ts
-var THEMES = {
-  dark: {
-    h1: ["#ff79c6", "#bd93f9", "#8be9fd"],
-    h2: "#bd93f9",
-    h3: "#8be9fd",
-    h4: "#50fa7b",
-    h5: "#f1fa8c",
-    h6: "#ffb86c",
-    code: "#ff79c6",
-    codeBlockBorder: "#6272a4",
-    link: "#8be9fd",
-    blockquote: "#6272a4",
-    hr: "#6272a4",
-    tableHeader: "#bd93f9"
-  },
-  light: {
-    h1: ["#d63384", "#6f42c1", "#0d6efd"],
-    h2: "#6f42c1",
-    h3: "#0d6efd",
-    h4: "#198754",
-    h5: "#664d03",
-    h6: "#fd7e14",
-    code: "#d63384",
-    codeBlockBorder: "#adb5bd",
-    link: "#0d6efd",
-    blockquote: "#6c757d",
-    hr: "#adb5bd",
-    tableHeader: "#6f42c1"
-  }
-};
-var _normalize = (text) => typeof text === "string" ? text.replace(/\r\n/g, "\n").replace(/\r/g, "\n") : "";
+// src/markdown/block-parser.ts
 var HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
 var ORDERED_LIST_RE = /^(\s*)(\d+)[.)]\s+(.+)$/;
 var UNORDERED_LIST_RE = /^(\s*)[-*+]\s+(.+)$/;
@@ -6255,6 +6292,11 @@ var CODEBLOCK_CLOSE_RE = /^```\s*$/;
 var BLOCKQUOTE_RE = /^>\s?(.*)$/;
 var TABLE_SEPARATOR_RE = /^\|?[ \t]*:?-{2,}:?[ \t]*(\|[ \t]*:?-{2,}:?[ \t]*)+\|?[ \t]*$/;
 var TABLE_ROW_RE = /^\|.*\|[ \t]*$/;
+var _normalize = (text) => typeof text === "string" ? text.replace(/\r\n/g, "\n").replace(/\r/g, "\n") : "";
+var _splitTableRow = (row) => {
+  const stripped = row.trim().replace(/^\|/, "").replace(/\|[ \t]*$/, "");
+  return stripped.split("|").map((c) => c.trim());
+};
 var parseBlocks = (source) => {
   if (typeof source !== "string" || source.length === 0) return [];
   const lines = _normalize(source).split("\n");
@@ -6350,14 +6392,41 @@ var parseBlocks = (source) => {
   }
   return out;
 };
-var _splitTableRow = (row) => {
-  const stripped = row.trim().replace(/^\|/, "").replace(/\|[ \t]*$/, "");
-  return stripped.split("|").map((c) => c.trim());
+
+// src/markdown/theme.ts
+var THEMES = {
+  dark: {
+    h1: ["#ff79c6", "#bd93f9", "#8be9fd"],
+    h2: "#bd93f9",
+    h3: "#8be9fd",
+    h4: "#50fa7b",
+    h5: "#f1fa8c",
+    h6: "#ffb86c",
+    code: "#ff79c6",
+    codeBlockBorder: "#6272a4",
+    link: "#8be9fd",
+    blockquote: "#6272a4",
+    hr: "#6272a4",
+    tableHeader: "#bd93f9"
+  },
+  light: {
+    h1: ["#d63384", "#6f42c1", "#0d6efd"],
+    h2: "#6f42c1",
+    h3: "#0d6efd",
+    h4: "#198754",
+    h5: "#664d03",
+    h6: "#fd7e14",
+    code: "#d63384",
+    codeBlockBorder: "#adb5bd",
+    link: "#0d6efd",
+    blockquote: "#6c757d",
+    hr: "#adb5bd",
+    tableHeader: "#6f42c1"
+  }
 };
-var parseInline = (text, opts = {
-  theme: "dark",
-  inlineCodeBackground: true
-}) => {
+
+// src/markdown/inline-parser.ts
+var parseInline = (text, opts = { theme: "dark", inlineCodeBackground: true }) => {
   if (typeof text !== "string" || text.length === 0) return "";
   const t = THEMES[opts.theme];
   const codeSlots = [];
@@ -6377,6 +6446,8 @@ var parseInline = (text, opts = {
   s = s.replace(/\x00CODE(\d+)\x00/g, (_m, idx) => codeSlots[Number(idx)] ?? "");
   return s;
 };
+
+// src/markdown/renderer.ts
 var _detectWidth = () => {
   const w = process.stdout?.columns;
   return isFiniteNumber2(w) && w > 10 ? w : 80;
@@ -6471,6 +6542,8 @@ var render = (source, opts = {}) => {
   while (out.length > 0 && out[out.length - 1] === "") out.pop();
   return out.join("\n");
 };
+
+// src/markdown/index.ts
 var markdown = {
   render,
   parseBlocks,

package/examples/all-in-one.cjs

@@ -118,7 +118,7 @@ async function main() {
   console.log(components.section('🏷️  Badges & Status', { width: 60 }));
   console.log();
   console.log(' ',
-    components.badge('VERSION', 'v1.4.0'),
+    components.badge('VERSION', 'v1.4.1'),
     components.badge('BUILD', 'passing'),
     components.badge('LICENSE', 'Apache 2.0'));
   console.log();

package/examples/all-in-one.mjs

@@ -117,7 +117,7 @@ console.log();
 console.log(components.section('🏷️  Badges & Status', { width: 60 }));
 console.log();
 console.log(' ',
-  components.badge('VERSION', 'v1.4.0'),
+  components.badge('VERSION', 'v1.4.1'),
   components.badge('BUILD', 'passing'),
   components.badge('LICENSE', 'Apache 2.0'));
 console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ansimax",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Zero-dependency CLI rendering library: colors, gradients, animations, ASCII art, pixel art, components, and themes \u2014 all in TypeScript.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",