How chjj/blessed works
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.