ansimax 1.2.8 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,12 +7,13 @@
7
7
  _Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_
8
8
 
9
9
  [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
10
- [![npm](https://img.shields.io/badge/npm-v1.2.8-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
10
+ [![npm](https://img.shields.io/badge/npm-v1.3.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
11
11
  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
12
12
  [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
13
- [![Tests](https://img.shields.io/badge/tests-1900%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
13
+ [![Tests](https://img.shields.io/badge/tests-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
14
14
  [![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](#)
15
- [![Bundle](https://img.shields.io/badge/bundle-%3C100kb-brightgreen.svg?style=flat-square)](#)
15
+ [![Node](https://img.shields.io/badge/Node-%3E%3D18-43853d.svg?style=flat-square)](#requirements)
16
+ [![ESM%20%2B%20CJS](https://img.shields.io/badge/ESM%20%2B%20CJS-dual-blueviolet.svg?style=flat-square)](#)
16
17
 
17
18
  **English** · [Español](README.es.md)
18
19
 
@@ -79,30 +80,40 @@ stop('Build complete', true);
79
80
 
80
81
  ## 🆚 Comparison with the Node.js ecosystem
81
82
 
82
- Ansimax replaces a dependency stack of popular Node.js libraries with one coherent, typed package:
83
+ Ansimax replaces a stack of popular Node.js libraries with **one coherent, typed, zero-dependency package**:
83
84
 
84
85
  | Feature | chalk | gradient-string | ora | cli-progress | figlet | boxen | inquirer | cli-table3 | **Ansimax** |
85
86
  |---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
86
87
  | Basic + 256 colors | ✅ | — | — | — | — | — | — | — | ✅ |
87
88
  | Truecolor with adaptive fallback | ✅ | ✅ | — | — | — | — | — | — | ✅ |
88
89
  | Multi-stop gradients | — | ✅ | — | — | — | — | — | — | ✅ |
89
- | **Animated gradients** | — | — | — | — | — | — | — | — | 🔜 |
90
+ | **Animated gradients** | — | — | — | — | — | — | — | — | |
91
+ | **Easing curves (5 presets + custom)** | — | — | — | — | — | — | — | — | ✅ |
92
+ | **Conic gradients (radial sweep)** | — | — | — | — | — | — | — | — | ✅ |
90
93
  | ASCII banners | — | — | — | — | ✅ | — | — | — | ✅ |
94
+ | **Image → ASCII converter** | — | — | — | — | — | — | — | — | ✅ |
95
+ | **Figlet `.flf` font parser** | — | — | — | — | ✅ (own) | — | — | — | ✅ (250+ fonts) |
91
96
  | Custom font registry | — | — | — | — | partial | — | — | — | ✅ |
92
- | Boxes with multiple styles | — | — | — | — | — | ✅ | — | — | ✅ |
97
+ | Boxes with multiple styles | — | — | — | — | — | ✅ | — | — | ✅ (6 styles) |
93
98
  | Spinners (multiple styles) | — | — | ✅ | — | — | — | — | — | ✅ (11 styles) |
94
99
  | Animated progress bars | — | — | — | ✅ | — | — | — | — | ✅ |
95
100
  | **Hierarchical/parallel tasks** | — | — | — | — | — | — | — | — | ✅ |
96
101
  | Tables (multi-line, ANSI-aware) | — | — | — | — | — | — | — | ✅ | ✅ |
97
102
  | Interactive menus + multi-select | — | — | — | — | — | — | ✅ | — | ✅ |
98
103
  | **Trees with cycle detection** | — | — | — | — | — | — | — | — | ✅ |
104
+ | **Split layouts (vsplit/hsplit)** | — | — | — | — | — | — | — | — | ✅ (v1.3.0) |
105
+ | **JSON colored pretty-printer** | — | — | — | — | — | — | — | — | ✅ (v1.3.0) |
99
106
  | **Pixel art + canvas + sprites** | — | — | — | — | — | — | — | — | ✅ |
100
107
  | **Theme system + per-instance isolation** | — | — | — | — | — | — | — | — | ✅ |
101
108
  | `AbortSignal` everywhere | — | — | partial | — | — | — | partial | — | ✅ |
102
109
  | `NO_COLOR` env support | ✅ | partial | partial | — | — | — | — | — | ✅ |
103
- | TypeScript-first | partial | partial | | partial | partial | | partial | partial | ✅ |
104
- | Zero runtime dependencies | | | | | | | | | ✅ |
105
- | **Total install size** | small | small | medium | medium | medium | small | large | medium | **< 100 KB** |
110
+ | Stable error codes (`ANSIMAX_*`) | | | | | | | | | ✅ |
111
+ | TypeScript-first (strict mode) | partial | partial | | partial | partial | | partial | partial | ✅ |
112
+ | **Zero runtime dependencies** | | | | | | | | | |
113
+ | ESM + CJS dual export | partial | partial | ✅ | ✅ | partial | ✅ | partial | partial | ✅ |
114
+ | **Test coverage** | ~95% | partial | partial | partial | partial | partial | partial | partial | **~98% (2000+ tests)** |
115
+
116
+ > Comparison reflects what each library officially supports at time of writing. Some libraries can be combined to approach ansimax's feature set, but at the cost of bundle size, version-skew bugs, and inconsistent APIs.
106
117
 
107
118
  ---
108
119
 
@@ -225,7 +236,7 @@ await animateGradient('Done!', ['#50fa7b', '#bd93f9'], {
225
236
 
226
237
  ### Easing Curves (v1.2.0)
227
238
 
228
- <img src="media/easing_curves.png" alt="Colors and gradients" />
239
+ <img src="media/easing_curves.png" alt="Easing curves preview" />
229
240
 
230
241
  ```js
231
242
  import { gradient } from 'ansimax';
@@ -245,7 +256,7 @@ console.log(gradient('hello world', stops, { easing: (t) => t * t * t }));
245
256
 
246
257
  ### Conic Gradients (v1.2.0)
247
258
 
248
- <img src="media/conic_gradients.png" alt="Colors and gradients" />
259
+ <img src="media/conic_gradients.png" alt="Conic gradients preview" />
249
260
 
250
261
  ```js
251
262
  import { gradientRect } from 'ansimax';
@@ -434,7 +445,7 @@ console.log(components.table([
434
445
  ['loaders', color.green('● ready'), '100%'],
435
446
  ], { borderStyle: 'rounded' }));
436
447
 
437
- console.log(components.badge('VERSION', 'v1.2.8'));
448
+ console.log(components.badge('VERSION', 'v1.3.0'));
438
449
  console.log(components.badge('BUILD', 'passing'));
439
450
  ```
440
451
 
@@ -544,6 +555,61 @@ console.log('tenantB themes include custom?', tenantB.list().includes('custom'))
544
555
  // ↑ false — full isolation
545
556
  ```
546
557
 
558
+ ### Panels — Split Layouts (v1.3.0)
559
+
560
+ ```js
561
+ import { panels, ascii } from 'ansimax';
562
+
563
+ // Side-by-side columns
564
+ const left = ascii.box('Sidebar', { borderStyle: 'rounded' });
565
+ const right = ascii.box('Main view', { borderStyle: 'rounded' });
566
+
567
+ console.log(panels.vsplit([left, right], { gap: 2, align: 'center' }));
568
+
569
+ // Vertical stacking
570
+ console.log(panels.hsplit([
571
+ '── Application ──',
572
+ ascii.box('Body content'),
573
+ '── Footer ──',
574
+ ], { gap: 1, align: 'center' }));
575
+
576
+ // Nested — sidebar + main inside an app shell
577
+ console.log(panels.hsplit([
578
+ '── My App ──',
579
+ panels.vsplit([
580
+ ascii.box('Sidebar', { width: 20 }),
581
+ ascii.box('Main', { width: 40 }),
582
+ ], { gap: 2 }),
583
+ '── End ──',
584
+ ]));
585
+ ```
586
+
587
+ ### JSON Pretty-print (v1.3.0)
588
+
589
+ ```js
590
+ import { json } from 'ansimax';
591
+
592
+ // Colored, depth-aware pretty-printing
593
+ console.log(json.pretty({
594
+ name: 'ansimax',
595
+ version: '1.3.0',
596
+ features: ['colors', 'gradients', 'panels'],
597
+ stats: { tests: 2000, coverage: 0.98 },
598
+ active: true,
599
+ }));
600
+
601
+ // Depth limit — collapses deep objects to {...}
602
+ console.log(json.pretty(deeplyNested, { maxDepth: 2 }));
603
+
604
+ // Item limit — huge arrays show "... (N more)"
605
+ console.log(json.pretty(largeArray, { maxItems: 10 }));
606
+
607
+ // Circular references handled gracefully
608
+ const obj = { name: 'foo' };
609
+ obj.self = obj;
610
+ console.log(json.pretty(obj)); // → "self": [Circular]
611
+ ```
612
+
547
613
  ---
548
614
 
549
615
  ## 📚 Examples
@@ -655,6 +721,68 @@ try {
655
721
 
656
722
  ---
657
723
 
724
+ ## 🧩 Ecosystem packages
725
+
726
+ The **ansimax ecosystem** is structured in two tiers — companion packages that extend the core, and independent evolutions that target different platforms.
727
+
728
+ ### `@ansimax/*` — Companion packages
729
+
730
+ Scoped packages that extend `ansimax` without breaking its zero-dependency promise. Each is published independently but shares ansimax's philosophy and naming.
731
+
732
+ | Package | Status | Description |
733
+ |---|:-:|---|
734
+ | `ansimax` | ✅ stable | Terminal-rendering core. Zero dependencies. |
735
+ | `@ansimax/image` | 🟡 planned | Image-to-ASCII loader — PNG/JPEG/WebP from file/buffer/URL |
736
+ | `@ansimax/cli` | 🟡 planned | Standalone binary — `npx @ansimax/cli demo`, font browser, image converter |
737
+ | `@ansimax/fonts` | 🟡 planned | 250+ figlet `.flf` fonts pre-bundled, ready to use |
738
+ | `@ansimax/sprites` | 🔴 future | Curated sprite library (animals, UI icons, technical diagrams) |
739
+ | `@ansimax/video` | 🔴 future | Video frame extraction → ASCII playback |
740
+ | `@ansimax/themes-extra` | 🔴 future | Community-contributed themes pack |
741
+
742
+ **How they connect:**
743
+
744
+ ```
745
+ ┌─────────────────────────────┐
746
+ │ ansimax (zero deps) │ ← core, you always install
747
+ │ • colors, ASCII, panels │
748
+ │ • types: PixelGrid, etc. │
749
+ └────────────┬────────────────┘
750
+ │ peer dependency
751
+ ┌────────────────────┼────────────────────┐
752
+ ▼ ▼ ▼
753
+ @ansimax/image @ansimax/cli @ansimax/fonts
754
+ (deps: jimp) (binary) (data only)
755
+ ```
756
+
757
+ Each companion declares `"ansimax": "^X.Y.Z"` as `peerDependency` — semver-coordinated, never duplicated, never out of sync.
758
+
759
+ ### `ansimax-*` — Independent evolutions
760
+
761
+ Standalone projects that build **alongside** ansimax for different platforms. Not companions — these are separate identities with their own scope and release cycle.
762
+
763
+ | Package | Status | Description |
764
+ |---|:-:|---|
765
+ | `ansimax-native` | 🔴 future | **Rust + TS rewrite** of the rendering hot path. Native performance via napi-rs. Same API surface as `ansimax`. |
766
+ | `ansimax-web` | 🔴 future | **Browser rendering** layer. ANSI → HTML/CSS conversion + canvas rendering. For demos, docs sites, web terminals. |
767
+
768
+ **Sub-ecosystems**: each of these can have their own scoped sub-packages (`@ansimax-native/image`, `@ansimax-web/canvas`, etc.) over time.
769
+
770
+ ### Why two naming conventions?
771
+
772
+ Industry convention used by many mature ecosystems (Babel, Vue, Webpack, etc.):
773
+
774
+ - **`@scope/*`** = "same project family, coordinated release, same team"
775
+ - **`name-*`** = "inspired by / works alongside, independent identity"
776
+
777
+ By using both, ansimax signals:
778
+ - The **core** (`ansimax`) stays small, zero-dep, focused on terminal rendering
779
+ - The **ecosystem** (`@ansimax/*`) grows around it as opt-in extensions
780
+ - **Evolutions** (`ansimax-native`, `ansimax-web`) explore different platforms without compromising the core
781
+
782
+ > 💡 **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.
783
+
784
+ ---
785
+
658
786
  ## 🛣️ Roadmap
659
787
 
660
788
  Ansimax is being built toward a **full terminal rendering platform** — a Node-native answer to what Python developers get from `rich` + `textual` combined, with Node-specific improvements where it matters.
@@ -706,12 +834,12 @@ The roadmap intentionally targets — and aims to surpass — gaps that even mat
706
834
  - [x] Columns layout (truncate/wrap overflow)
707
835
  - [x] Sections (gradient headers with auto-width)
708
836
  - [x] Trees (collapsible, max-depth, cycle-safe)
709
- - [ ] **Panels** (split layouts: hsplit, vsplit)
837
+ - [x] **Panels** split layouts: `hsplit`, `vsplit` with alignment + nesting (v1.3.0)
838
+ - [x] **JSON/YAML pretty-printing** — colored, depth-limit, circular-safe (v1.3.0)
710
839
  - [ ] **Layouts** (flexbox-style positioning)
711
840
  - [ ] **Grid system** (CSS Grid-inspired column/row spans)
712
841
  - [ ] **Markdown rendering** (headings, lists, code blocks, tables)
713
842
  - [ ] **Syntax highlighting** (built-in language grammars)
714
- - [ ] **JSON/YAML pretty-printing** (with depth limit + collapse)
715
843
  - [ ] **Logging integration** (drop-in replacement for `console`/`pino`/`winston` transports)
716
844
 
717
845
  ### ✅ Phase 5 — Cursor & screen control
@@ -826,16 +954,23 @@ The roadmap intentionally targets — and aims to surpass — gaps that even mat
826
954
  ## 🧪 Testing
827
955
 
828
956
  ```bash
829
- npm test # Run all 1700+ tests
957
+ npm test # Run all 2000+ tests
830
958
  npm run test:watch # Watch mode
831
959
  npm run test:coverage # Coverage report
832
960
  ```
833
961
 
834
- Coverage targets:
835
- - Statements: **98%**
836
- - Branches: **95%**
837
- - Functions: **99%**
838
- - Lines: **99%**
962
+ Coverage (as of v1.3.0):
963
+
964
+ | Metric | Score |
965
+ |---|:-:|
966
+ | **Statements** | ~98% |
967
+ | **Branches** | ~95% |
968
+ | **Functions** | ~99% |
969
+ | **Lines** | ~99% |
970
+ | **Total tests** | **2,000+** |
971
+ | **Test suites** | 18 |
972
+ | **CI matrix** | Node 18, 20, 22, latest |
973
+ | **Platforms tested** | Linux, macOS, Windows |
839
974
 
840
975
  ---
841
976
 
@@ -871,6 +1006,29 @@ ansimax/
871
1006
 
872
1007
  ## 📝 Changelog
873
1008
 
1009
+ ### v1.3.0 — Phase 4 progress: Panels + JSON pretty-print
1010
+
1011
+ Minor release adding two new top-level modules — split layouts and JSON pretty-printing:
1012
+
1013
+ - 🪟 **`panels` module** — `vsplit` (columns) + `hsplit` (rows) with ANSI-aware width, alignment (`start`/`center`/`end`), gap, fixed-width mode, nesting
1014
+ - 🎨 **`json` module** — colored JSON pretty-printer with depth limit, item limit, string truncation, circular reference detection
1015
+ - 🛣️ **Phase 4 roadmap**: 8/15 → **10/15** complete
1016
+
1017
+ ```js
1018
+ import { panels, json, ascii } from 'ansimax';
1019
+
1020
+ // Side-by-side columns
1021
+ console.log(panels.vsplit([
1022
+ ascii.box('Sidebar', { width: 20 }),
1023
+ ascii.box('Main', { width: 40 }),
1024
+ ], { gap: 2 }));
1025
+
1026
+ // Pretty-print JSON
1027
+ console.log(json.pretty({ name: 'app', tests: 2000 }, { maxDepth: 3 }));
1028
+ ```
1029
+
1030
+ Drop-in replacement for `1.2.8`. Two new modules, zero breaking changes.
1031
+
874
1032
  ### v1.2.8 — Documentation polish
875
1033
 
876
1034
  Patch release with massively improved JSDoc + IntelliSense coverage:
package/dist/index.d.mts CHANGED
@@ -1904,6 +1904,224 @@ declare const clearThemeColorCache: () => void;
1904
1904
  */
1905
1905
  declare const themes: ThemeInstance;
1906
1906
 
1907
+ /**
1908
+ * ansimax — panels module
1909
+ * ─────────────────────────────────────────────
1910
+ *
1911
+ * Split layouts for composing terminal UIs: hsplit (top/bottom) and
1912
+ * vsplit (left/right). Both operate on already-rendered string blocks
1913
+ * (typically from `ascii.box`, `components.table`, etc.) and handle:
1914
+ *
1915
+ * • ANSI-aware width measurement
1916
+ * • Variable height (each block keeps its own line count)
1917
+ * • Alignment within columns
1918
+ * • Configurable gap between blocks
1919
+ * • Nesting (panels can contain panels)
1920
+ *
1921
+ * Philosophy: panels do composition, not styling. Style your blocks
1922
+ * first (with `ascii.box`, `components.timeline`, etc.), then compose
1923
+ * them with `panels.hsplit` / `panels.vsplit`.
1924
+ */
1925
+ type Alignment = 'start' | 'center' | 'end';
1926
+ interface VsplitOptions {
1927
+ /** Horizontal gap (in space characters) between columns. Default `1`. */
1928
+ gap?: number;
1929
+ /**
1930
+ * Vertical alignment of shorter blocks within the joined column row.
1931
+ * `'start'` (default) keeps blocks top-aligned; shorter blocks have
1932
+ * padding below. `'center'` centers each block. `'end'` aligns to bottom.
1933
+ */
1934
+ align?: Alignment;
1935
+ /**
1936
+ * Pad each block with spaces to a fixed width. Useful for grids where
1937
+ * each cell should be the same size regardless of content.
1938
+ * If omitted, each column uses its natural max-line width.
1939
+ */
1940
+ widths?: number[] | null;
1941
+ }
1942
+ interface HsplitOptions {
1943
+ /** Vertical gap (in blank lines) between rows. Default `0`. */
1944
+ gap?: number;
1945
+ /**
1946
+ * Horizontal alignment of narrower blocks within the joined width.
1947
+ * `'start'` (default) keeps blocks left-aligned. `'center'` and `'end'`
1948
+ * pad with spaces on the appropriate side.
1949
+ */
1950
+ align?: Alignment;
1951
+ }
1952
+ /**
1953
+ * Split blocks side-by-side (left / right / right ...).
1954
+ *
1955
+ * Each block is split into lines, then joined column-by-column with a
1956
+ * configurable gap. Shorter blocks are padded to match the tallest one.
1957
+ *
1958
+ * @param blocks - Pre-rendered string blocks (multi-line OK).
1959
+ * @param opts - Layout options.
1960
+ *
1961
+ * @example basic two-column layout
1962
+ * ```js
1963
+ * import { panels, ascii } from 'ansimax';
1964
+ *
1965
+ * console.log(panels.vsplit([
1966
+ * ascii.box('Left side', { borderStyle: 'rounded' }),
1967
+ * ascii.box('Right side', { borderStyle: 'rounded' }),
1968
+ * ], { gap: 2 }));
1969
+ * ```
1970
+ *
1971
+ * @example three columns with centered vertical alignment
1972
+ * ```js
1973
+ * console.log(panels.vsplit([
1974
+ * 'Short',
1975
+ * 'A\nMedium\nblock',
1976
+ * 'A\nlonger\nblock\nwith\nfive lines',
1977
+ * ], { align: 'center', gap: 4 }));
1978
+ * ```
1979
+ *
1980
+ * @example fixed column widths (grid-like)
1981
+ * ```js
1982
+ * console.log(panels.vsplit([col1, col2, col3], {
1983
+ * widths: [20, 30, 20],
1984
+ * gap: 2,
1985
+ * }));
1986
+ * ```
1987
+ */
1988
+ declare const vsplit: (blocks: string[], opts?: VsplitOptions) => string;
1989
+ /**
1990
+ * Stack blocks vertically (top / bottom / bottom ...).
1991
+ *
1992
+ * Each block is concatenated with `\n` between them. With `gap > 0`,
1993
+ * additional blank lines are inserted between blocks.
1994
+ *
1995
+ * @param blocks - Pre-rendered string blocks (multi-line OK).
1996
+ * @param opts - Layout options.
1997
+ *
1998
+ * @example basic stacking
1999
+ * ```js
2000
+ * import { panels, ascii } from 'ansimax';
2001
+ *
2002
+ * console.log(panels.hsplit([
2003
+ * '── Header ──',
2004
+ * ascii.box('Body content', { borderStyle: 'rounded' }),
2005
+ * '── Footer ──',
2006
+ * ]));
2007
+ * ```
2008
+ *
2009
+ * @example with vertical gap + centered alignment
2010
+ * ```js
2011
+ * console.log(panels.hsplit([
2012
+ * 'Top',
2013
+ * ascii.box('Middle'),
2014
+ * 'Bottom',
2015
+ * ], { gap: 1, align: 'center' }));
2016
+ * ```
2017
+ *
2018
+ * @example nested (an hsplit inside a vsplit)
2019
+ * ```js
2020
+ * const sidebar = ascii.box('Sidebar', { width: 20 });
2021
+ * const main = ascii.box('Main content area', { width: 40 });
2022
+ *
2023
+ * console.log(panels.hsplit([
2024
+ * '── Application ──',
2025
+ * panels.vsplit([sidebar, main], { gap: 2 }),
2026
+ * '── End ──',
2027
+ * ]));
2028
+ * ```
2029
+ */
2030
+ declare const hsplit: (blocks: string[], opts?: HsplitOptions) => string;
2031
+ declare const panels: {
2032
+ vsplit: (blocks: string[], opts?: VsplitOptions) => string;
2033
+ hsplit: (blocks: string[], opts?: HsplitOptions) => string;
2034
+ };
2035
+
2036
+ /**
2037
+ * ansimax — json module
2038
+ * ─────────────────────────────────────────────
2039
+ *
2040
+ * Colored JSON / YAML pretty-printer for terminal display.
2041
+ *
2042
+ * Features:
2043
+ * • Configurable indent
2044
+ * • Color-coded by value type (string, number, boolean, null, key)
2045
+ * • Max depth with collapse marker (`{...}` / `[...]`)
2046
+ * • Circular reference detection (avoids infinite recursion)
2047
+ * • ANSI cleanly disabled in NO_COLOR / non-TTY environments
2048
+ *
2049
+ * Philosophy: data → human-readable text. Not a parser, not a validator —
2050
+ * just pretty rendering of in-memory JS values.
2051
+ */
2052
+ interface PrettyOptions {
2053
+ /** Indent width in spaces. Default `2`. */
2054
+ indent?: number;
2055
+ /**
2056
+ * Apply ANSI colors to keys/values. Default `true`. Auto-disabled when
2057
+ * `NO_COLOR` is set or output is non-TTY.
2058
+ */
2059
+ colors?: boolean;
2060
+ /**
2061
+ * Maximum nesting depth. Objects/arrays beyond this level are collapsed
2062
+ * to `{...}` / `[...]`. Default `Infinity` (no limit).
2063
+ */
2064
+ maxDepth?: number;
2065
+ /**
2066
+ * Maximum array length to display fully. Arrays longer than this show
2067
+ * the first N items + a `... (M more)` marker. Default `Infinity`.
2068
+ */
2069
+ maxItems?: number;
2070
+ /**
2071
+ * Maximum string length before truncation with ellipsis. Default `Infinity`.
2072
+ */
2073
+ maxStringLength?: number;
2074
+ }
2075
+ /**
2076
+ * Pretty-print a JavaScript value with colored output suitable for
2077
+ * terminal display. Handles primitives, objects, arrays, and circular
2078
+ * references gracefully.
2079
+ *
2080
+ * @param value - Any JavaScript value to render.
2081
+ * @param opts - Optional formatting configuration.
2082
+ *
2083
+ * @example basic
2084
+ * ```js
2085
+ * import { json } from 'ansimax';
2086
+ *
2087
+ * console.log(json.pretty({
2088
+ * name: 'ansimax',
2089
+ * version: '1.3.0',
2090
+ * features: ['colors', 'gradients', 'panels'],
2091
+ * stats: { tests: 2000, coverage: 0.98 },
2092
+ * }));
2093
+ * ```
2094
+ *
2095
+ * @example with depth limit (collapses deeply nested objects)
2096
+ * ```js
2097
+ * console.log(json.pretty(deeplyNestedObject, { maxDepth: 2 }));
2098
+ * // Anything beyond depth 2 renders as {...} or [...]
2099
+ * ```
2100
+ *
2101
+ * @example with item limit (for huge arrays)
2102
+ * ```js
2103
+ * console.log(json.pretty(largeArray, { maxItems: 10 }));
2104
+ * // Shows first 10 items + "... (N more)"
2105
+ * ```
2106
+ *
2107
+ * @example monochrome (e.g. for log files)
2108
+ * ```js
2109
+ * console.log(json.pretty(data, { colors: false }));
2110
+ * ```
2111
+ *
2112
+ * @example handles circular references
2113
+ * ```js
2114
+ * const obj = { name: 'foo' };
2115
+ * obj.self = obj; // circular!
2116
+ * console.log(json.pretty(obj));
2117
+ * // → { "name": "foo", "self": [Circular] }
2118
+ * ```
2119
+ */
2120
+ declare const pretty: (value: unknown, opts?: PrettyOptions) => string;
2121
+ declare const json: {
2122
+ pretty: (value: unknown, opts?: PrettyOptions) => string;
2123
+ };
2124
+
1907
2125
  declare const ansimax: {
1908
2126
  color: {
1909
2127
  black: ColorFn;
@@ -2070,4 +2288,4 @@ declare const ansimax: {
2070
2288
  configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
2071
2289
  };
2072
2290
 
2073
- export { ASCII_RAMPS, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, hasFont, hexToRgb, hideCursor, images, isHexColor, isNoColor, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rotate90, safeJson, screen, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$1 as stripAnsi, stripAnsi$2 as stripAnsiCodes, stripAnsi as stripAnsiColors, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
2291
+ export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, hasFont, hexToRgb, hideCursor, hsplit, images, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rotate90, safeJson, screen, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$1 as stripAnsi, stripAnsi$2 as stripAnsiCodes, stripAnsi as stripAnsiColors, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };