Documentation / @ripl/terminal

@ripl/terminal

Terminal rendering context for Ripl — draw the same 2D graphics and charts to a terminal as braille-character output with ANSI truecolor.

Installation

npm install @ripl/terminal

Overview

@ripl/terminal implements Ripl's Context abstraction without any DOM. It rasterizes elements into a grid of Unicode braille dots (each character cell packs a 2×4 sub-pixel grid) and writes them to a runtime-agnostic TerminalOutput adapter — process.stdout in Node, or an xterm.js instance in the browser. Because every Ripl element renders through the shared Context API, scenes written for Canvas or SVG render unchanged in the terminal.

Optional logicalWidth/logicalHeight options let you author a scene in CSS-pixel coordinates; the context uniformly scales and letterboxes that space into the character grid so it renders proportionally in any terminal size.

Note: the terminal context is a rasterizer — pointer events/hit-testing, gradients, images, and transforms are not supported.

Usage

import {
    createContext,
} from '@ripl/terminal';

import {
    createCircle,
} from '@ripl/core';

// `output` implements { write, columns, rows, onResize? }
const context = createContext(output, {
    logicalWidth: 800,
    logicalHeight: 600,
});

createCircle({
    stroke: '#38bdf8',
    cx: 400,
    cy: 300,
    radius: 150,
}).render(context);

In Node, use @ripl/node to obtain a stdout-backed output adapter.

Exporting

const text = context.export().toString(); // plain braille art
const image = await context.export().toImage(); // ImageData (rasterized)
const url = context.export().toURL(); // PNG object URL (browser)

Documentation

Full documentation and interactive demos are available at ripl.run.

License

MIT

Classes

Class	Description
BrailleRasterizer	Braille-dot rasterizer. Each terminal cell encodes a 2×4 grid of sub-pixel dots via Unicode braille patterns (U+2800–U+28FF).
TerminalContext	Terminal rendering context that rasterizes Ripl elements into character-based output via a TerminalOutput adapter.
TerminalPath	Terminal path implementation that records drawing commands for later rasterization.

Interfaces

Interface	Description
Rasterizer	Abstract rasterizer interface for converting pixel data to terminal characters.
SerializeOptions	Options controlling how a rasterizer serializes its grid to a string.
TerminalContextOptions	Options for constructing a terminal rendering context.
TerminalOutput	Abstract terminal output interface — runtime-agnostic.
TerminalPathCommand	A recorded drawing command with its type and parameters.
Vertex	A 2D point in raster (pixel) space.

Type Aliases

Type Alias	Description
PixelCallback	Callback invoked for each pixel in a rasterization pass.
TerminalPathCommandType	Types of drawing commands recorded by a terminal path.

Variables

Variable	Description
ANSI_RESET	ANSI SGR reset sequence.
BRAILLE_CELL_HEIGHT	Each braille cell is 2 pixels wide and 4 pixels tall.
BRAILLE_CELL_WIDTH	Each braille cell is 2 pixels wide and 4 pixels tall.

Functions

Function	Description
colorToAnsiBg	Converts a CSS color string to an ANSI truecolor background escape sequence. Returns empty string for invalid/transparent colors.
colorToAnsiFg	Converts a CSS color string to an ANSI truecolor foreground escape sequence. Returns empty string for invalid/transparent colors.
createContext	Creates a terminal rendering context bound to the given output adapter.
fillPolygon	Fills the interior of one or more closed contours using the even-odd rule. Each contour is a polyline (implicitly closed); interiors are determined per scanline from edge crossings, so concave shapes, circular segments, and annular sectors (holes) fill correctly.
flattenArc	Samples an arc from startAngle to endAngle into a polyline of points (inclusive of both endpoints).
flattenCubicBezier	Samples a cubic bezier curve into a polyline of points (inclusive of both endpoints).
flattenEllipse	Samples a full ellipse outline into a closed polyline of points.
flattenQuadBezier	Samples a quadratic bezier curve into a polyline of points (inclusive of both endpoints).
rasterizeArc	Rasterizes an arc from startAngle to endAngle at (cx,cy) with given radius by subdivision into line segments.
rasterizeCircle	Rasterizes a circle outline at (cx,cy) with the given radius using the midpoint algorithm.
rasterizeCubicBezier	Rasterizes a cubic bezier curve by adaptive subdivision into line segments.
rasterizeEllipse	Rasterizes an ellipse outline at (cx,cy) with the given radii using the midpoint algorithm.
rasterizeLine	Rasterizes a line segment from (x0,y0) to (x1,y1) using Bresenham's algorithm.
rasterizeQuadBezier	Rasterizes a quadratic bezier curve by adaptive subdivision into line segments.
rasterizeRect	Rasterizes a rectangle outline.