@jsvision/ui / Surface
Class: Surface
Defined in: ui/src/surface/surface.ts:73
An offscreen, freely-writable cell buffer. Draw into it via the Surface.getDrawContext paint facade (the primary API) or the raw Surface.buffer; a bound SurfaceView displays a scrollable window onto it. Every mutation bumps a version counter so a bound view repaints automatically.
Example
import { Surface, SurfaceView, signal } from '@jsvision/ui';
// A canvas larger than the viewport that will display it.
const surface = new Surface({ size: { x: 96, y: 36 } });
const ctx = surface.getDrawContext();
ctx.text(2, 1, 'Hello from the offscreen canvas', { fg: 'brightCyan', bg: 'default' });
// Show a scrollable window onto it; write `delta` to pan.
const delta = signal({ x: 0, y: 0 });
const view = new SurfaceView({ surface, delta });
view.layout = { position: 'absolute', rect: { x: 0, y: 0, width: 40, height: 12 } };
// Or build one straight from text rows:
const banner = Surface.from(['+--------+', '| hello |', '+--------+']);Constructors
Constructor
new Surface(
opts):Surface
Defined in: ui/src/surface/surface.ts:91
Parameters
opts
The size (clamped ≥ 1) + optional paint-facade theme/caps defaults + initial fill.
Returns
Surface
Properties
size
size:
Point
Defined in: ui/src/surface/surface.ts:77
Current size {x,y}; mirrors buf.width/buf.height.
Accessors
buffer
Get Signature
get buffer():
ScreenBuffer
Defined in: ui/src/surface/surface.ts:119
The raw wrapped buffer — an escape hatch; poke it directly, then call invalidate.
Returns
ScreenBuffer
Methods
at()
at(
x,y):Readonly<Cell> |undefined
Defined in: ui/src/surface/surface.ts:162
Read the cell at (x, y) as a read-only frozen copy, or undefined when out of bounds. The returned cell is a copy, not a live handle, so it cannot be mutated. Writes go through Surface.set or the paint facade.
Parameters
x
number
y
number
Returns
Readonly<Cell> | undefined
clear()
clear(
style?):void
Defined in: ui/src/surface/surface.ts:152
Blank every cell to a space in style (default terminal colours). Bumps the version.
Parameters
style?
Style = DEFAULT_FILL
Returns
void
getDrawContext()
getDrawContext(
overrides?):DrawContext
Defined in: ui/src/surface/surface.ts:186
A DrawContext covering the whole surface — the primary way to author content (the same paint facade a View.draw receives). Its writers sanitize input, stay width-correct, and bump the version so a bound SurfaceView repaints. theme/caps default to the construction values and may be overridden per call.
Parameters
overrides?
Optional per-call theme/caps.
caps?
theme?
Theme
Returns
A draw context whose mutating writers also bump the surface's version.
grow()
grow(
delta):void
Defined in: ui/src/surface/surface.ts:147
Grow (or shrink) by a per-axis delta — equivalent to resize(size + delta).
Parameters
delta
Returns
void
invalidate()
invalidate():
void
Defined in: ui/src/surface/surface.ts:225
Manually bump the version — for callers that poke Surface.buffer directly.
Returns
void
resize()
resize(
size):void
Defined in: ui/src/surface/surface.ts:129
Resize to size, preserving the overlapping region and blanking the newly-exposed area. Allocates a fresh buffer and copies the overlap cell-by-cell (wide glyphs are re-emitted so their continuation cell is recreated), then swaps in the new buffer and bumps the version. A non-positive dimension clamps to 1, so the buffer is never unusable.
Parameters
size
Returns
void
set()
set(
x,y,char,style):void
Defined in: ui/src/surface/surface.ts:172
Write one glyph at (x, y) in style — the single-cell write path. Out-of-bounds writes are a no-op, and control bytes are sanitized to a space. Bumps the version.
Parameters
x
number
y
number
char
string
style
Returns
void
snapshot()
snapshot():
ScreenBuffer
Defined in: ui/src/surface/surface.ts:230
A deep, independent copy of the current buffer.
Returns
ScreenBuffer
version()
version():
number
Defined in: ui/src/surface/surface.ts:220
Reactive content-version read. A bound SurfaceView tracks this in its draw, so reading it subscribes the caller to future mutations — every surface change then schedules a repaint.
Returns
number
from()
staticfrom(rows,opts?):Surface
Defined in: ui/src/surface/surface.ts:108
Build a Surface from an array of text rows. Sizes to max(displayWidth(row)) × rows.length (wide glyphs count as 2; at least 1×1) and writes each row through the sanitizing text writer, so no control byte becomes a cell.
Parameters
rows
readonly string[]
The text rows (top to bottom).
opts?
Omit<SurfaceOptions, "size">
Optional theme/caps/fill (size is derived from rows).
Returns
Surface
A surface sized to fit the rows, with each row written at the left edge.