# chjj/blessed architecture

> Architecture diagram of the GitHub repository chjj/blessed, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chjj/blessed
- Repository: https://github.com/chjj/blessed

## Overview

##### Project type and purpose
- This is an open-source Node.js library (“blessed”) that reimplements curses-style terminal control and provides a high-level widget API for building terminal UIs.
- Its two primary goals are:
– A low-level Program + Tput engine that parses terminfo/termcap and emits escape sequences.

##### File structure
– bin/
- CLI entrypoints (tput.js, tput CLI shim)
– lib/
- Core modules:
– program.js (low-level terminal driver)
– tput.js (terminfo/termcap parser & compiler)
– widgets/… (all high-level widget implementations)
– browser/
- Bundler scripts and Makefile for building a browser-compatible version.
– usr/
- Terminfo, termcap databases and font JSONs used by tput and BigText widget.
– example/
- Usage samples demonstrating telnet server, multiplex, forms, layouts.
– test/
- Interactive and unit tests validating core, widget, and rendering behavior.
– index.js & package.json
- Main module entrypoint and NPM metadata.

##### README for additional insights
– Describes two layers: the “Program” (escape code generator) and the “Widget API.”
– Enumerates all widget types, options, events, and helper functions.
– Mentions rendering optimizations (CSR, damage buffer, painter’s algorithm).
– Contains telnet/server-side usage, browser bundling, and low-level tput examples.

##### Main components
a. Core Engine Layer
- Program (lib/program.js): Coordinates input/output, buffers, cursor, mouse, alternate buffer.
- Tput (lib/tput.js + usr/terminfo): Parses terminfo & termcap, compiles to JS functions for capabilities (setaf, cup, sgr0, etc.).
b. Rendering Layer
- Screen (inherits Node/Element): Maintains two screen buffers, damage tracking, CSR & BCE optimizations.
- Renderer: Painter’s algorithm, smart cursor movements, region clearing & filling.
c. Widget Layer
- Base Nodes: Node, Screen, Element.
- Composite/Input Widgets: List, Form, Input, Textbox, Checkbox, RadioButton.
- Data Display Widgets: Table, Log, ProgressBar.
- Special Widgets: Terminal (pty+term.js), ANSIImage, OverlayImage, Video, Layout.
d. Helpers & Utilities
- helpers.js (merge, parseTags, escape, cleanTags)
- events.js (event bubbling, custom events)
e. I/O & Environment
- process.stdin/stdout or custom streams (telnet client, net.Socket).
- Terminal environment variables ($TERM), terminfo lookup.
f. Browser Build
- browser/transform.js builds a UMD bundle for in-browser use.

##### Relationships and interactions
- Tput loads terminfo tables → compiles JS functions → provided to Program.
- Program exposes cursor/mouse APIs and writes raw escape codes to output.
- Screen wraps Program, holds widget tree, manages two buffers.
- Screen.render() traverses widget tree → each Element.render() writes to the screen buffer → Renderer diffs old/new buffer and invokes Program’s write methods.
- Widgets listen for input events (keypress, mouse) bubbled from Program via Screen.
- Examples instantiate a blessed.screen, build a widget tree, attach event handlers, and call screen.render().
- Browser build substitutes Program/Tput with a virtual DOM or polyfilled console.

##### Architectural patterns and design principles
- Layered architecture: separation of low-level terminal driving (Program/Tput), rendering engine (Screen/Renderer), and high-level UI widgets.
- Event-driven (EventEmitter inheritance, event bubbling from leaves to Screen).
- Painter’s algorithm with retained mode: maintain screen state and only redraw damage.
- Extensibility: widget library is modular; new widgets can plug into the same render pipeline.
- Data-driven styling: tag parsing and style objects separated from render logic.

##### Diagramming conventions
– Core Engine (blue)
– Rendering layer (green)
– Widget API (orange)
– Data / External (gray)
– Helpers & Utilities (purple)

##### Essential elements to capture
- Separation of concerns (terminfo parsing, terminal IO, buffer diffing, widget tree).
- Key data stores: terminfo tables, screen buffers, widget state.
- Control flow: render loop, input event dispatch, widget event listeners.
- Extension points: new widgets, custom renderers (Layout), helper APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine Layer
    subgraph "Core Engine" 
        direction TB
        TPUT["Tput (lib/tput.js)"]:::core
        click TPUT "https://github.com/chjj/blessed/blob/master/lib/tput.js"
        TERMINFO["Terminfo Data (usr/)"]:::data
        click TERMINFO "https://github.com/chjj/blessed/tree/master/usr/"
        PROGRAM["Program (lib/program.js)"]:::core
        click PROGRAM "https://github.com/chjj/blessed/blob/master/lib/program.js"
        APIFACADE["API Façade (lib/blessed.js)"]:::core
        click APIFACADE "https://github.com/chjj/blessed/blob/master/lib/blessed.js"
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        direction TB
        SCREEN["Screen & Renderer (lib/widgets/screen.js)"]:::render
        click SCREEN "https://github.com/chjj/blessed/blob/master/lib/widgets/screen.js"
    end

    %% Widget API Layer
    subgraph "Widget API" 
        direction TB
        subgraph "Base Classes"
            NODE["Node (lib/widgets/node.js)"]:::widget
            click NODE "https://github.com/chjj/blessed/blob/master/lib/widgets/node.js"
            ELEMENT["Element (lib/widgets/element.js)"]:::widget
            click ELEMENT "https://github.com/chjj/blessed/blob/master/lib/widgets/element.js"
            WIDGETBASE["Widget Base (lib/widget.js)"]:::widget
            click WIDGETBASE "https://github.com/chjj/blessed/blob/master/lib/widget.js"
        end
        subgraph "Primitive Widgets"
            BOX["Box (lib/widgets/box.js)"]:::widget
            click BOX "https://github.com/chjj/blessed/blob/master/lib/widgets/box.js"
            TEXT["Text (lib/widgets/text.js)"]:::widget
            click TEXT "https://github.com/chjj/blessed/blob/master/lib/widgets/text.js"
            LINE["Line (lib/widgets/line.js)"]:::widget
            click LINE "https://github.com/chjj/blessed/blob/master/lib/widgets/line.js"
        end
        subgraph "Composite/Input Widgets"
            LIST["List (lib/widgets/list.js)"]:::widget
            click LIST "https://github.com/chjj/blessed/blob/master/lib/widgets/list.js"
            FORM["Form (lib/widgets/form.js)"]:::widget
            click FORM "https://github.com/chjj/blessed/blob/master/lib/widgets/form.js"
            INPUT["Input (lib/widgets/input.js)"]:::widget
            click INPUT "https://github.com/chjj/blessed/blob/master/lib/widgets/input.js"
            TEXTBOX["Textbox (lib/widgets/textbox.js)"]:::widget
            click TEXTBOX "https://github.com/chjj/blessed/blob/master/lib/widgets/textbox.js"
            CHECKBOX["Checkbox (lib/widgets/checkbox.js)"]:::widget
            click CHECKBOX "https://github.com/chjj/blessed/blob/master/lib/widgets/checkbox.js"
            RADIOBTN["RadioButton (lib/widgets/radiobutton.js)"]:::widget
            click RADIOBTN "https://github.com/chjj/blessed/blob/master/lib/widgets/radiobutton.js"
            RADIOSET["RadioSet (lib/widgets/radioset.js)"]:::widget
            click RADIOSET "https://github.com/chjj/blessed/blob/master/lib/widgets/radioset.js"
        end
        subgraph "Data Display Widgets"
            TABLE["Table (lib/widgets/table.js)"]:::widget
            click TABLE "https://github.com/chjj/blessed/blob/master/lib/widgets/table.js"
            LISTTABLE["ListTable (lib/widgets/listtable.js)"]:::widget
            click LISTTABLE "https://github.com/chjj/blessed/blob/master/lib/widgets/listtable.js"
            LOG["Log (lib/widgets/log.js)"]:::widget
            click LOG "https://github.com/chjj/blessed/blob/master/lib/widgets/log.js"
            PROGRESS["ProgressBar (lib/widgets/progressbar.js)"]:::widget
            click PROGRESS "https://github.com/chjj/blessed/blob/master/lib/widgets/progressbar.js"
        end
        subgraph "Special Widgets"
            TERMINAL["Terminal (lib/widgets/terminal.js)"]:::widget
            click TERMINAL "https://github.com/chjj/blessed/blob/master/lib/widgets/terminal.js"
            ANSIIMG["ANSIImage (lib/widgets/ansiimage.js)"]:::widget
            click ANSIIMG "https://github.com/chjj/blessed/blob/master/lib/widgets/ansiimage.js"
            OVERLAY["OverlayImage (lib/widgets/overlayimage.js)"]:::widget
            click OVERLAY "https://github.com/chjj/blessed/blob/master/lib/widgets/overlayimage.js"
            VIDEO["Video (lib/widgets/video.js)"]:::widget
            click VIDEO "https://github.com/chjj/blessed/blob/master/lib/widgets/video.js"
            LAYOUT["Layout (lib/widgets/layout.js)"]:::widget
            click LAYOUT "https://github.com/chjj/blessed/blob/master/lib/widgets/layout.js"
            BIGTEXT["BigText (lib/widgets/bigtext.js)"]:::widget
            click BIGTEXT "https://github.com/chjj/blessed/blob/master/lib/widgets/bigtext.js"
        end
    end

    %% Helpers & Utilities
    subgraph "Helpers & Utilities"
        direction TB
        HELPERS["Helpers (lib/helpers.js)"]:::util
        click HELPERS "https://github.com/chjj/blessed/blob/master/lib/helpers.js"
        EVENTS["Events (lib/events.js)"]:::util
        click EVENTS "https://github.com/chjj/blessed/blob/master/lib/events.js"
        KEYS["Keys (lib/keys.js)"]:::util
        click KEYS "https://github.com/chjj/blessed/blob/master/lib/keys.js"
        COLORS["Colors (lib/colors.js)"]:::util
        click COLORS "https://github.com/chjj/blessed/blob/master/lib/colors.js"
        ALIAS["Aliases (lib/alias.js)"]:::util
        click ALIAS "https://github.com/chjj/blessed/blob/master/lib/alias.js"
        UNICODE["Unicode Support (lib/unicode.js)"]:::util
        click UNICODE "https://github.com/chjj/blessed/blob/master/lib/unicode.js"
    end

    %% I/O & Environment
    subgraph "I/O & Environment"
        direction TB
        STREAM["Input/Output Streams"]:::data
        ENV["Terminal Env ($TERM)"]:::data
    end

    %% Browser Build
    subgraph "Browser Build"
        direction TB
        TRANSFORM["transform.js"]:::data
        click TRANSFORM "https://github.com/chjj/blessed/blob/master/browser/transform.js"
        MAKEFILE["Makefile"]:::data
        click MAKEFILE "https://github.com/chjj/blessed/tree/master/browser/Makefile"
    end

    %% Examples & Tests
    EXAMPLES["Examples (example/)"]:::data
    click EXAMPLES "https://github.com/chjj/blessed/tree/master/example/"
    TESTS["Tests (test/)"]:::data
    click TESTS "https://github.com/chjj/blessed/tree/master/test/"

    %% Entry Points
    ENTRY["CLI Entry (bin/tput.js)"]:::data
    click ENTRY "https://github.com/chjj/blessed/blob/master/bin/tput.js"
    MAIN["Main Module (index.js/package.json)"]:::data
    click MAIN "https://github.com/chjj/blessed/blob/master/index.js"
    click MAIN "https://github.com/chjj/blessed/blob/master/package.json"

    %% Connections - Data Flow
    TERMINFO -->|loads tables| TPUT -->|compiles capabilities| PROGRAM
    PROGRAM -->|exposes APIs| APIFACADE
    PROGRAM -->|drives| SCREEN
    SCREEN -->|renders via| RENDERER[Renderer]:::render
    RENDERER -->|writes escape codes| PROGRAM
    SCREEN -->|manages tree| NODE
    NODE --> ELEMENT --> WIDGETBASE

    %% Widgets rendering
    ELEMENT --> BOX & TEXT & LINE
    WIDGETBASE --> LIST & FORM & INPUT & TEXTBOX & CHECKBOX & RADIOBTN & RADIOSET
    LISTTABLE & TABLE --> LOG & PROGRESS
    WIDGETBASE -->|special| TERMINAL & ANSIIMG & OVERLAY & VIDEO & LAYOUT & BIGTEXT

    %% Events Flow
    STREAM -.->|keypress/mouse| PROGRAM -.-> SCREEN -.->|bubbles| EVENTS -.-> NODE

    %% Helpers usage
    HELPERS -->|used by| PROGRAM & ELEMENT & WIDGETBASE
    EVENTS -->|used by| SCREEN & WIDGETBASE
    KEYS -->|used for| PROGRAM & INPUT
    COLORS -->|used for| TPUT & BOX
    ALIAS -->|utilities| HELPERS
    UNICODE -->|used by| TEXT & BIGTEXT

    %% Browser substitutions
    TRANSFORM -->|polyfills| VIRTUAL[Virtual Program/Tput]:::data
    VIRTUAL --> SCREEN

    %% Examples & Tests usage
    EXAMPLES -->|demo usage| APIFACADE & SCREEN
    TESTS -->|validate| PROGRAM & SCREEN & WIDGETBASE

    %% Entry
    ENTRY --> PROGRAM
    MAIN --> APIFACADE

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef render fill:#d4edda,stroke:#28a745,color:#000;
    classDef widget fill:#ffe5b4,stroke:#ff9900,color:#000;
    classDef util fill:#e5ccff,stroke:#9933ff,color:#000;
    classDef data fill:#ebebeb,stroke:#666666,color:#000;
```
