Ansilust Project

A next-generation text art processing system inspired by the legendary ansilove project. Ansilust provides a unified intermediate representation (IR) for working with both classic BBS-era text art formats and modern terminal output.

---

Status	Package	Purpose
	16c	coming soon
	16colors	coming soon
	ansilust	coming sooner

---

🚀 Quick Start

# Render classic ANSI art to your terminal
zig build run -- path/to/artwork.ans

# Or build and use the binary
zig build
./zig-out/bin/ansilust path/to/artwork.ans

📦 Installation (COMING SOON)

npm (Cross-Platform)

# Install globally
npm install -g ansilust

# Or run directly without installing
npx ansilust path/to/artwork.ans

Bash Installer (Linux/macOS)

curl -fsSL https://ansilust.com/install | bash

PowerShell Installer (Windows)

irm https://ansilust.com/install.ps1 | iex

AUR (Arch Linux)

yay -S ansilust

Nix (All Platforms)

nix run github:effect-native/ansilust -- path/to/artwork.ans

Docker

docker run ghcr.io/effect-native/ansilust:latest path/to/artwork.ans

From Source

git clone https://github.com/effect-native/ansilust.git
cd ansilust
zig build -Doptimize=ReleaseSafe
./zig-out/bin/ansilust path/to/artwork.ans

📊 Current Status

✅ What's Implemented (Ready to Use)

Core Infrastructure:

• IR (Intermediate Representation) - Complete cell grid system with:
  • Structure-of-arrays layout for efficient memory access
  • CP437 and Unicode character support
  • 16-color palette and 24-bit RGB color support
  • Text attributes (bold, italic, underline, blink, etc.)
  • SAUCE metadata parsing and preservation
  • Animation frame support (snapshot and delta frames)
  • Hyperlink tracking (OSC 8)
  • Wide character and grapheme cluster handling

Parsers (Input → IR):

• ANSI Parser (src/parsers/ansi.zig) ✅ WORKING
  • CP437 character encoding
  • SGR (Select Graphic Rendition) attributes
  • Cursor positioning and control sequences
  • SAUCE metadata extraction
  • Tested with real-world BBS art from 1996 artpacks

Renderers (IR → Output):

• UTF8ANSI Renderer (src/renderers/utf8ansi.zig) ✅ WORKING
  • Converts classic CP437 ANSI art to modern UTF-8 terminal output
  • DOS palette to ANSI 256-color mapping
  • 24-bit RGB (truecolor) support
  • Style batching optimization
  • TTY vs file mode distinction
  • Visual fidelity adjustments for modern terminal fonts:
    • CP437 control characters (0x00-0x1F) mapped to visible glyphs
    • Baseline alignment fixes (▃ instead of ▬, ˜ instead of ~)
    • Weight adjustments (‧ instead of ∙)
  • Targets: Ghostty, Alacritty, Kitty, WezTerm, and other modern terminals

Testing:

• 127 unit tests (all passing)
• Memory leak detection via std.testing.allocator in all tests
• Real-world corpus validation (137+ ANSI files from sixteencolors archive)
• Visual fidelity validation with H4-2017.ANS (Fire artpack)

🚧 What's Planned (Not Yet Implemented)

Additional Parsers:

• Binary format (.BIN) - 160-column format
• PCBoard (.PCB) - BBS-specific format with @X color codes
• XBin (.XB) - Extended Binary with embedded fonts
• Tundra/TheDraw (.TND/.IDF) - Editor formats
• ArtWorx (.ADF) - Artworx Data Format
• iCE Draw (.IDF) - iCE Draw format
• UTF8ANSI input parser - Read modern terminal sequences as input

Additional Renderers:

• HTML Canvas Renderer - Browser-based rendering
• PNG Renderer - Static image output (like original ansilove)
• OpenTUI integration - Direct conversion to OptimizedBuffer format

Animation Support:

• Ansimation playback (ANSI animations)
• Frame-by-frame rendering
• Timing control

📁 Repository Structure

This is a monorepo managed with npm workspaces. The packages/ directory contains:

Main Package

• packages/ansilust/ - Meta package (platform launcher)
  • Detects your OS and CPU architecture
  • Automatically uses the correct native binary
  • Single ansilust command works across all platforms

Platform Packages (Published Separately)

• packages/ansilust-darwin-arm64/ - macOS Apple Silicon
• packages/ansilust-darwin-x64/ - macOS Intel
• packages/ansilust-linux-x64-gnu/ - Linux x64 (glibc)
• packages/ansilust-linux-x64-musl/ - Linux x64 (musl)
• packages/ansilust-linux-arm64-gnu/ - Linux ARM64 (glibc)
• packages/ansilust-linux-arm64-musl/ - Linux ARM64 (musl)
• packages/ansilust-linux-armv7-gnu/ - Linux ARMv7 (glibc)
• packages/ansilust-linux-armv7-musl/ - Linux ARMv7 (musl)
• packages/ansilust-linux-i386-musl/ - Linux i386 (musl)
• packages/ansilust-win32-x64/ - Windows x64

Each platform package contains a pre-built native binary for that architecture.

Development

# Install all workspace packages
npm install

# List all workspaces
npm ls --workspaces

# Run build for all packages
npm run build --workspaces

Project Architecture

Intermediate Representation (IR)

The IR is a unified format that bridges classic BBS art and modern terminal capabilities:

• Cell Grid: Efficient structure-of-arrays layout
• Character Support: CP437 (DOS) and full Unicode
• Color Models: 16-color palette, 256-color, and 24-bit RGB
• Metadata: Complete SAUCE record preservation
• Modern Features: Hyperlinks, grapheme clusters, wide characters

Module Structure

src/
├── ir/              # Intermediate representation core
│   ├── cell_grid.zig      # Cell grid and grapheme pool
│   ├── color.zig          # Color types and palettes
│   ├── attributes.zig     # Text attributes (bold, italic, etc.)
│   ├── sauce.zig          # SAUCE metadata
│   ├── animation.zig      # Animation frames
│   ├── document.zig       # Root IR container
│   └── ...
├── parsers/         # Format parsers (Input → IR)
│   ├── ansi.zig          # ANSI/ANSI-BBS parser ✅
│   └── ...               # (Binary, XBin, etc. - planned)
└── renderers/       # Output renderers (IR → Output)
    ├── utf8ansi.zig      # UTF-8 terminal renderer ✅
    └── ...               # (HTML, PNG, etc. - planned)

Design Philosophy

Ansilust's IR is designed based on research from multiple reference projects:

Classic BBS Art (from libansilove):

• CP437 character encoding and DOS code pages
• SAUCE metadata (128-byte records with rendering hints)
• Bitmap font support (embeddable in XBin, ArtWorx formats)
• iCE colors mode (high-intensity backgrounds)
• DOS aspect ratio handling (non-square CRT pixels)

Modern Terminals (from Ghostty):

• Full Unicode support (21-bit codepoints)
• Wide character and grapheme cluster handling
• Rich text attributes (underline styles, separate underline colors)
• Hyperlink support (OSC 8)
• Efficient memory layout (reference-counted styles)

Integration Targets (from OpenTUI):

• Structure-of-arrays cell grid layout
• RGBA color representation
• Diff-based rendering for efficiency
• Animation frame support

Development & Testing

Building

# Build the project
zig build

# Run tests
zig build test

# Format code
zig fmt src/**/*.zig

Test Corpus

The project includes a test corpus from the sixteencolors archive:

• 137+ ANSI files from 1996 artpacks (ACiD, iCE, Fire)
• 6 ansimation (animated ANSI) files
• Real-world complexity and edge cases

See CORPUS.md for detailed corpus documentation.

Documentation

• STATUS.md - Detailed implementation status and phase completion
• TODO.md - Planned features and future work
• AGENTS.md - Complete project architecture and reference materials
• IR-RESEARCH.md - Intermediate representation design research
• .specs/ir/ - Detailed IR specifications and design documents

Reference Projects

The reference/ directory contains submodules and documentation for projects that informed the design:

• libansilove - Classic BBS art format parsers (C)
• ansilove - CLI tool and SAUCE metadata handling
• Ghostty - Modern terminal emulator architecture (Zig)
• OpenTUI - TUI framework integration target
• Effect-TS - TypeScript functional programming patterns
• Bun - Zig/TypeScript FFI reference

See individual AGENTS.md files in each reference directory for detailed guides.

Contributing

This project follows test-driven development (TDD) with:

• Red/Green/Refactor cycles for new features
• Atomic git commits for each TDD phase
• Memory leak detection using std.testing.allocator in all tests
• 100% test pass rate before commits

See .specs/ir/PHASE5_XP_TDD_SUMMARY.md for detailed TDD methodology.

License

See LICENSE file for details.