ANSI Escape Sequence Support

May 28, 2026 · View on GitHub

BinktermPHP includes full support for ANSI escape sequences (also called ANSI codes or escape codes) used for text formatting, colors, and cursor control in messages.

What are ANSI Escape Sequences?

ANSI escape sequences are special character sequences that control text formatting and cursor positioning in terminals. They begin with the ESC character (ASCII 27, \x1b) followed by control codes.

ANSI codes were standardized by ANSI X3.64 and are widely used in:

  • Unix/Linux terminals
  • BBS systems
  • FidoNet message systems
  • ASCII/ANSI art

Format

ESC[<parameters>m

Where:

  • ESC is the escape character (ASCII 27, \x1b)
  • [ begins a Control Sequence Introducer (CSI)
  • <parameters> are semicolon-separated numeric codes
  • m indicates SGR (Select Graphic Rendition)

Example: \x1b[1;31m = Bold + Red text

Color Codes

Standard Foreground Colors (30-37)

  • 30 - Black
  • 31 - Red
  • 32 - Green
  • 33 - Yellow
  • 34 - Blue
  • 35 - Magenta
  • 36 - Cyan
  • 37 - White

Bright Foreground Colors (90-97)

  • 90 - Bright Black (Gray)
  • 91 - Bright Red
  • 92 - Bright Green
  • 93 - Bright Yellow
  • 94 - Bright Blue
  • 95 - Bright Magenta
  • 96 - Bright Cyan
  • 97 - Bright White

Standard Background Colors (40-47)

  • 40 - Black background
  • 41 - Red background
  • 42 - Green background
  • 43 - Yellow background
  • 44 - Blue background
  • 45 - Magenta background
  • 46 - Cyan background
  • 47 - White background

Bright Background Colors (100-107)

  • 100 - Bright Black background
  • 101 - Bright Red background
  • 102 - Bright Green background
  • 103 - Bright Yellow background
  • 104 - Bright Blue background
  • 105 - Bright Magenta background
  • 106 - Bright Cyan background
  • 107 - Bright White background

Reset Colors

  • 39 - Default foreground color
  • 49 - Default background color

Text Formatting Codes

Styles

  • 0 - Reset all attributes (default)
  • 1 - Bold / Increased intensity
  • 2 - Dim / Faint
  • 3 - Italic
  • 4 - Underline
  • 5 - Slow blink
  • 6 - Fast blink
  • 7 - Reverse video (swap foreground/background)
  • 8 - Hidden / Concealed
  • 9 - Strikethrough / Crossed out

Reset Specific Attributes

  • 22 - Normal intensity (not bold, not dim)
  • 23 - Not italic
  • 24 - Not underlined
  • 25 - Not blinking
  • 27 - Not reversed
  • 28 - Not hidden
  • 29 - Not strikethrough

Cursor Control Sequences

BinktermPHP supports cursor positioning for ASCII/ANSI art:

Cursor Movement

  • ESC[<n>A - Cursor up n lines
  • ESC[<n>B - Cursor down n lines
  • ESC[<n>C - Cursor forward n columns
  • ESC[<n>D - Cursor back n columns
  • ESC[<n>E - Cursor next line (beginning of line, n lines down)
  • ESC[<n>F - Cursor previous line (beginning of line, n lines up)
  • ESC[<n>G - Cursor horizontal absolute (column n)
  • ESC[<row>;<col>H - Cursor position (row, col)
  • ESC[<row>;<col>f - Cursor position (alternative)

Screen Control

  • ESC[<n>J - Clear screen
    • 0 - Clear from cursor to end of screen
    • 1 - Clear from cursor to beginning of screen
    • 2 - Clear entire screen
    • 3 - Clear entire screen and scrollback buffer
  • ESC[<n>K - Clear line
    • 0 - Clear from cursor to end of line
    • 1 - Clear from cursor to beginning of line
    • 2 - Clear entire line
  • ESC[<n>S - Scroll up n lines
  • ESC[<n>T - Scroll down n lines

Cursor Position Save/Restore

  • ESC[s - Save cursor position
  • ESC[u - Restore cursor position

Implementation

Terminal Emulation

BinktermPHP includes a full ANSI terminal emulator that:

  • Maintains a virtual screen buffer (80 columns × variable rows)
  • Processes cursor positioning sequences
  • Handles screen clearing and scrolling
  • Renders to HTML with CSS classes

Automatic Detection

The system automatically detects message content type:

ASCII/ANSI Art (uses terminal emulation):

  • Contains cursor positioning codes
  • Dense ANSI formatting (4+ lines, 30+ chars/line)
  • Leading space patterns (ASCII art detection)

Regular Text (line-by-line parsing):

  • Simple color codes without positioning
  • Normal message formatting
  • Better performance for non-art content

Rendering Pipeline

  1. Detection - Check for ANSI codes and cursor positioning
  2. Processing
    • ASCII/ANSI art → Terminal emulator → HTML
    • Regular text → Line-by-line parser → HTML
  3. Output - HTML with CSS classes for styling

JavaScript Functions

Main Functions

renderAnsiTerminal(text, cols=80, rows=500) Main rendering function that:

  • Auto-detects ANSI art vs regular text
  • Uses terminal emulation for cursor positioning
  • Falls back to simple parsing for better performance
  • Returns HTML with CSS classes

parseAnsi(text) Fast line-by-line ANSI parser for regular messages:

  • Processes SGR color/style codes
  • Strips cursor control sequences
  • Returns HTML with CSS classes

hasAnsiCodes(text) Detects if text contains ANSI escape sequences.

Terminal Emulator Class

AnsiTerminal(cols, rows) Full terminal emulator with:

  • Virtual screen buffer
  • Cursor positioning
  • Attribute tracking (colors, bold, etc.)
  • Screen clearing and scrolling
  • HTML rendering with proper formatting

CSS Classes

ANSI codes are rendered as HTML spans with CSS classes:

Colors

  • ansi-black, ansi-red, ansi-green, ansi-yellow, ansi-blue, ansi-magenta, ansi-cyan, ansi-white
  • ansi-bright-black, ansi-bright-red, etc.
  • ansi-bg-black, ansi-bg-red, etc. (backgrounds)

Styles

  • ansi-bold - Bold text
  • ansi-dim - Dim/faint text
  • ansi-italic - Italic text
  • ansi-underline - Underlined text
  • ansi-blink - Blinking text
  • ansi-reverse - Reversed colors
  • ansi-hidden - Hidden text
  • ansi-strike - Strikethrough text

Usage Examples

Simple Color Change

\x1b[31mThis is red\x1b[0m and this is normal

Output: This is red and this is normal

Bold + Color

\x1b[1;34mBold Blue Text\x1b[0m

Output: Bold Blue Text

Background Color

\x1b[41;37mWhite text on red background\x1b[0m

Output: White text on red background

ASCII Art with Positioning

\x1b[2J\x1b[H\x1b[1;32m
  ╔════════════╗
  ║   MENU     ║
  ╚════════════╝
\x1b[5;5H\x1b[37m1) Option One
\x1b[6;5H2) Option Two

Uses cursor positioning to place text precisely on screen.

Multiple Attributes

\x1b[1;4;31mBold, Underlined, Red\x1b[0m

User Settings

ANSI parsing can be controlled via user settings:

window.userSettings.ansi_parsing = false;  // Disable ANSI parsing

When disabled, ANSI codes are stripped and messages display as plain text.

Renderer Mode

The HTML renderer can operate in two modes, controlled by the ANSI_RENDERER_MODE environment variable in .env:

ValueBehaviourDefault
groupedConsecutive characters with identical styling are merged into a single <span>. Produces compact HTML and enables URL hyperlinking inside ANSI art.✅ Yes
percharEvery character gets its own <span>. Maximally precise — each cell is independently addressable — but URLs cannot be auto-hyperlinked because they are fragmented across individual spans.No
# .env
ANSI_RENDERER_MODE=grouped   # default
ANSI_RENDERER_MODE=perchar   # one span per character

Pipe-code recognition has a separate environment control:

PIPE_CODE_PARSER_MODE=decimal_relaxed
  • strict keeps the conservative uppercase-only boundary checks.
  • decimal_relaxed is the default mode and greedily accepts two-digit decimal codes such as |01 even when followed by uppercase text.
  • loose restores the older permissive behavior for testing.

Use perchar if you observe rendering differences with specific art files and want to compare. grouped is recommended for normal operation.

Compatibility

Fully Supported

  • ✅ SGR color and style codes (CSI m)
  • ✅ Cursor positioning (CSI H, f, A-G)
  • ✅ Screen clearing (CSI J, K)
  • ✅ Scrolling (CSI S, T)
  • ✅ Save/restore cursor (CSI s, u)
  • ✅ 256-color palette (CSI 38;5;n / 48;5;n)

Partially Supported

  • ⚠️ Blink - Mapped to CSS but may not render in all browsers

Not Supported (Stripped)

  • ❌ Other escape sequences (OSC, etc.)
  • ❌ Non-CSI escape codes

Works With

  • Traditional BBS ANSI art
  • FidoNet message formatting
  • ASCII art with cursor positioning
  • Terminal-style colored output
  • Mixed ANSI and pipe codes

Performance Optimization

BinktermPHP uses intelligent detection to optimize performance:

  1. Simple messages → Fast line-by-line parser
  2. ASCII art → Full terminal emulation
  3. No codes → Plain text rendering

This ensures fast rendering for most messages while still supporting complex ANSI art when needed.

Amiga ANSI

Amiga ANSI art uses the same ANSI X3.64 escape sequence syntax as standard PC ANSI but was authored for the Amiga's Topaz terminal font and colour palette rather than IBM's CP437 character set.

BinktermPHP renders Amiga ANSI through a separate ArtAmigaAnsiDecoder that extends the standard decoder with two differences:

  1. Font — the art-format-amiga-ansi CSS class selects the Topaz Unicode KS13 font (with Topaz Plus as a fallback), which reproduces the authentic Amiga screen appearance. Place the font files at public_html/fonts/TopazPlus.ttf and public_html/fonts/topaz_unicode_ks13_regular.ttf to activate them.

  2. Default colours — the container uses a dark blue-tinted background (#06090f) with light blue default text (#cfd8ff) instead of the standard black/white ANSI defaults, matching the Amiga Workbench palette.

  3. Character translation — non-breaking space (U+00A0) is mapped to a regular space to prevent layout issues; ÷ and × pass through unchanged.

Selecting Amiga ANSI rendering

Set a message's Art Format field to amiga_ansi, or use the render mode cycle button in the message viewer to switch to Amiga ANSI manually.

The escape sequence parser itself is identical to the standard ANSI renderer — only the font and default colour scheme differ.

  • Pipe Code Support - BBS pipe codes (|XX format)
  • CSS styling in public_html/css/ansisys.css
  • JavaScript implementation in public_html/js/ansisys.js

References

  • ANSI X3.64 (ECMA-48) standard
  • VT100/VT220 terminal sequences
  • FidoNet Technical Standards (FTS-0001)