@jsvision/core / ScreenBuffer
Class: ScreenBuffer
Defined in: render/buffer.ts:77
A mutable 2-D grid of styled cells — the surface you draw a frame onto before handing it to serialize for painting.
Fill it at construction with a background style, then draw with set (one glyph), text (a left-aligned string), fillRect, box, and shadow. All writes are width-correct and clipped to the buffer bounds, and every string is sanitized so untrusted text cannot inject an escape sequence at paint time.
Example
import { ScreenBuffer, serialize, resolveCapabilities } from '@jsvision/core';
const buf = new ScreenBuffer(20, 3, { fg: 'white', bg: 'blue' });
buf.box(0, 0, 20, 3, { fg: 'white', bg: 'blue' }, 'single', 'Title');
buf.text(2, 1, 'Hello, 世界', { fg: 'brightWhite', bg: 'blue' });
const caps = resolveCapabilities().profile;
process.stdout.write(serialize(buf, null, { caps })); // full first paintConstructors
Constructor
new ScreenBuffer(
width,height,fill):ScreenBuffer
Defined in: render/buffer.ts:91
Create a buffer with every cell pre-filled with a background style.
Parameters
width
number
Buffer width in columns (clamped to at least 1).
height
number
Buffer height in rows (clamped to at least 1).
fill
Style & object
The style (and optional single narrow glyph, default space) every cell starts with.
Returns
ScreenBuffer
Properties
cells
protectedreadonlycells:Cell[]
Defined in: render/buffer.ts:81
Row-major cell storage; index y * width + x.
height
readonlyheight:number
Defined in: render/buffer.ts:79
width
readonlywidth:number
Defined in: render/buffer.ts:78
Methods
appendCombining()
protectedappendCombining(x,y,mark):void
Defined in: render/buffer.ts:244
Append a zero-width combining mark to the base cell at (x, y), keeping the cell's width. No-op when (x, y) is out of bounds or the base cell was cleared to empty (nothing to compose on).
Parameters
x
number
Column of the base cell (a wide glyph's lead).
y
number
Row of the base cell.
mark
string
The combining mark glyph to append.
Returns
void
blank()
protectedblank(cell):void
Defined in: render/buffer.ts:122
Reduce a cell to a width-1 space, keeping its colors (clears a wide orphan).
Parameters
cell
Returns
void
box()
box(
x,y,w,h,style,variant?,title?):void
Defined in: render/buffer.ts:258
Draw a framed box with an opaque interior fill and an optional centered title. The real Unicode box glyphs are stored; the serializer substitutes ASCII (+, -, |) when the terminal lacks box-drawing support.
Parameters
x
number
y
number
w
number
h
number
style
variant?
"single" | "double"
'double' for ╔═╗ frames or 'single' for ┌─┐.
title?
string
Returns
void
cellAt()
protectedcellAt(x,y):Cell
Defined in: render/buffer.ts:108
The cell at (x, y); caller must have bounds-checked.
Parameters
x
number
y
number
Returns
clearOrphan()
protectedclearOrphan(x,y):void
Defined in: render/buffer.ts:132
Before overwriting (x, y), repair any wide glyph this write would split: if the existing cell is a wide lead, blank its continuation; if it is a continuation, blank its lead. Prevents a stale half-glyph.
Parameters
x
number
y
number
Returns
void
clone()
clone():
ScreenBuffer
Defined in: render/buffer.ts:349
Create a deep, independent copy of this buffer: same width/height and an element-wise copy of every cell — char, fg/bg/attrs, and width (0/1/2, so wide-lead and continuation cells are reproduced exactly). The copy shares no cell objects with the original, so mutating either one never affects the other.
Use it to snapshot the previous frame before drawing the next, then pass both to serialize(current, previous, …) for a minimal damage diff. An exact clone is required here because a get/set-based copy would recompute each cell's width from its char and so could not reproduce continuation cells faithfully.
Returns
ScreenBuffer
A new ScreenBuffer equal to this one cell-for-cell.
Example
import { ScreenBuffer, serialize, resolveCapabilities } from '@jsvision/core';
const caps = resolveCapabilities().profile;
let previous = new ScreenBuffer(10, 1, { fg: 'default', bg: 'default' });
const next = previous.clone();
next.set(2, 0, 'Z', { fg: 'red', bg: 'default' });
const diff = serialize(next, previous, { caps }); // emits only the one changed cell
previous = next; // snapshot becomes the baseline for the following framefillRect()
fillRect(
x,y,w,h,char,style):void
Defined in: render/buffer.ts:186
Fill a rectangle with a single glyph and style (width-correct via set).
Parameters
x
number
y
number
w
number
h
number
char
string
style
Returns
void
get()
get(
x,y):Cell|undefined
Defined in: render/buffer.ts:180
Read a cell, or undefined when out of bounds.
Parameters
x
number
y
number
Returns
Cell | undefined
inBounds()
protectedinBounds(x,y):boolean
Defined in: render/buffer.ts:103
True when (x, y) lies inside the buffer bounds.
Parameters
x
number
y
number
Returns
boolean
rows()
rows(): readonly
Cell[][]
Defined in: render/buffer.ts:318
Expose the grid as rows of cells for the serializer (read-only view).
Returns
readonly Cell[][]
set()
set(
x,y,char,style,widthMode?):void
Defined in: render/buffer.ts:151
Write a single glyph at (x, y); out-of-bounds writes are silently clipped. A wide glyph (display width 2) occupies (x, y) as a width: 2 lead and (x+1, y) as a width: 0 continuation; a wide glyph in the last column has no room for its continuation and clips to a space (never a half glyph).
Parameters
x
number
y
number
char
string
style
widthMode?
WidthMode = DEFAULT_WIDTH_MODE
Width-resolution mode; defaults to 'wcwidth'.
Returns
void
shadow()
shadow(
x,y,w,h,style):void
Defined in: render/buffer.ts:297
Cast a drop shadow by darkening the cells one column right and one row below the rectangle (classic text-mode style). Only the colors change; glyphs stay.
Parameters
x
number
y
number
w
number
h
number
style
Returns
void
text()
text(
x,y,str,style,widthMode?):number
Defined in: render/buffer.ts:206
Draw a left-aligned string starting at (x, y), advancing by each glyph's display width (wide glyphs advance 2 columns). Glyphs outside the buffer are clipped.
The string is sanitized first: control bytes never become cells, so untrusted text cannot inject an escape sequence at serialize time.
Parameters
x
number
y
number
str
string
style
widthMode?
WidthMode = DEFAULT_WIDTH_MODE
Width-resolution mode; defaults to 'wcwidth'.
Returns
number
The column just past the written text (display columns, not code-point count).
write()
protectedwrite(cell,char,style,cellWidth):void
Defined in: render/buffer.ts:113
Overwrite a cell's contents in place.
Parameters
cell
char
string
style
cellWidth
0 | 1 | 2
Returns
void