xonecas.io
70160
Ce

cel-tui / commit 2bb8ffd

feat(core): implement CellBuffer with diff support

- 2D grid of styled cells (char, fgColor, bgColor, bold, italic, underline)
- get/set with safe out-of-bounds handling
- fill rectangular regions with clipping
- resize preserving existing content
- diff between buffers returning changed positions
- isEmpty for transparency detection in layer compositing
- 19 tests covering creation, get/set, clear, resize, fill, diff, isEmpty

xonecas2026-04-03 2bb8ffd26b37425715ee41bbc867bcb8ddd53073 parent fa34bca

2 files changed

packages/core/src/cell-buffer.test.ts+284−0
@@ -0,0 +1,284 @@
1+import { describe, expect, test } from "bun:test";
2+import { CellBuffer, type Cell, EMPTY_CELL } from "./cell-buffer.js";
3+
4+describe("CellBuffer", () => {
5+ describe("creation", () => {
6+ test("creates buffer with correct dimensions", () => {
7+ const buf = new CellBuffer(80, 24);
8+ expect(buf.width).toBe(80);
9+ expect(buf.height).toBe(24);
10+ });
11+
12+ test("all cells start empty", () => {
13+ const buf = new CellBuffer(3, 2);
14+ for (let y = 0; y < 2; y++) {
15+ for (let x = 0; x < 3; x++) {
16+ expect(buf.get(x, y)).toEqual(EMPTY_CELL);
17+ }
18+ }
19+ });
20+
21+ test("zero dimensions", () => {
22+ const buf = new CellBuffer(0, 0);
23+ expect(buf.width).toBe(0);
24+ expect(buf.height).toBe(0);
25+ });
26+ });
27+
28+ describe("get/set", () => {
29+ test("write and read a cell", () => {
30+ const buf = new CellBuffer(10, 5);
31+ const cell: Cell = {
32+ char: "A",
33+ fgColor: "red",
34+ bgColor: null,
35+ bold: true,
36+ italic: false,
37+ underline: false,
38+ };
39+ buf.set(3, 2, cell);
40+ expect(buf.get(3, 2)).toEqual(cell);
41+ });
42+
43+ test("out-of-bounds get returns empty cell", () => {
44+ const buf = new CellBuffer(5, 5);
45+ expect(buf.get(-1, 0)).toEqual(EMPTY_CELL);
46+ expect(buf.get(5, 0)).toEqual(EMPTY_CELL);
47+ expect(buf.get(0, -1)).toEqual(EMPTY_CELL);
48+ expect(buf.get(0, 5)).toEqual(EMPTY_CELL);
49+ });
50+
51+ test("out-of-bounds set is a no-op", () => {
52+ const buf = new CellBuffer(5, 5);
53+ const cell: Cell = {
54+ char: "X",
55+ fgColor: null,
56+ bgColor: null,
57+ bold: false,
58+ italic: false,
59+ underline: false,
60+ };
61+ buf.set(-1, 0, cell);
62+ buf.set(5, 0, cell);
63+ buf.set(0, -1, cell);
64+ buf.set(0, 5, cell);
65+ // Should not throw, buffer unchanged
66+ expect(buf.get(0, 0)).toEqual(EMPTY_CELL);
67+ });
68+
69+ test("overwrite existing cell", () => {
70+ const buf = new CellBuffer(5, 5);
71+ buf.set(0, 0, {
72+ char: "A",
73+ fgColor: null,
74+ bgColor: null,
75+ bold: false,
76+ italic: false,
77+ underline: false,
78+ });
79+ buf.set(0, 0, {
80+ char: "B",
81+ fgColor: "blue",
82+ bgColor: null,
83+ bold: true,
84+ italic: false,
85+ underline: false,
86+ });
87+ expect(buf.get(0, 0).char).toBe("B");
88+ expect(buf.get(0, 0).fgColor).toBe("blue");
89+ });
90+ });
91+
92+ describe("clear", () => {
93+ test("resets all cells to empty", () => {
94+ const buf = new CellBuffer(3, 3);
95+ buf.set(1, 1, {
96+ char: "X",
97+ fgColor: "red",
98+ bgColor: null,
99+ bold: true,
100+ italic: false,
101+ underline: false,
102+ });
103+ buf.clear();
104+ expect(buf.get(1, 1)).toEqual(EMPTY_CELL);
105+ });
106+ });
107+
108+ describe("resize", () => {
109+ test("grows buffer, new cells are empty", () => {
110+ const buf = new CellBuffer(3, 3);
111+ buf.set(1, 1, {
112+ char: "A",
113+ fgColor: null,
114+ bgColor: null,
115+ bold: false,
116+ italic: false,
117+ underline: false,
118+ });
119+ buf.resize(5, 5);
120+ expect(buf.width).toBe(5);
121+ expect(buf.height).toBe(5);
122+ expect(buf.get(1, 1).char).toBe("A");
123+ expect(buf.get(4, 4)).toEqual(EMPTY_CELL);
124+ });
125+
126+ test("shrinks buffer, clips content", () => {
127+ const buf = new CellBuffer(5, 5);
128+ buf.set(4, 4, {
129+ char: "X",
130+ fgColor: null,
131+ bgColor: null,
132+ bold: false,
133+ italic: false,
134+ underline: false,
135+ });
136+ buf.resize(3, 3);
137+ expect(buf.width).toBe(3);
138+ expect(buf.height).toBe(3);
139+ expect(buf.get(4, 4)).toEqual(EMPTY_CELL); // out of bounds now
140+ });
141+ });
142+
143+ describe("fill", () => {
144+ test("fills a rectangular region", () => {
145+ const buf = new CellBuffer(5, 5);
146+ const cell: Cell = {
147+ char: "#",
148+ fgColor: "green",
149+ bgColor: null,
150+ bold: false,
151+ italic: false,
152+ underline: false,
153+ };
154+ buf.fill(1, 1, 3, 2, cell);
155+ expect(buf.get(1, 1)).toEqual(cell);
156+ expect(buf.get(2, 1)).toEqual(cell);
157+ expect(buf.get(3, 1)).toEqual(cell);
158+ expect(buf.get(1, 2)).toEqual(cell);
159+ expect(buf.get(3, 2)).toEqual(cell);
160+ // Outside the fill region
161+ expect(buf.get(0, 0)).toEqual(EMPTY_CELL);
162+ expect(buf.get(4, 3)).toEqual(EMPTY_CELL);
163+ });
164+
165+ test("clips to buffer bounds", () => {
166+ const buf = new CellBuffer(3, 3);
167+ const cell: Cell = {
168+ char: "X",
169+ fgColor: null,
170+ bgColor: null,
171+ bold: false,
172+ italic: false,
173+ underline: false,
174+ };
175+ // Fill extends beyond bounds — should not throw
176+ buf.fill(1, 1, 5, 5, cell);
177+ expect(buf.get(1, 1)).toEqual(cell);
178+ expect(buf.get(2, 2)).toEqual(cell);
179+ });
180+ });
181+
182+ describe("diff", () => {
183+ test("identical buffers produce no changes", () => {
184+ const a = new CellBuffer(3, 3);
185+ const b = new CellBuffer(3, 3);
186+ expect(a.diff(b)).toEqual([]);
187+ });
188+
189+ test("detects changed cells", () => {
190+ const a = new CellBuffer(3, 3);
191+ const b = new CellBuffer(3, 3);
192+ b.set(1, 1, {
193+ char: "X",
194+ fgColor: null,
195+ bgColor: null,
196+ bold: false,
197+ italic: false,
198+ underline: false,
199+ });
200+ const changes = a.diff(b);
201+ expect(changes).toEqual([{ x: 1, y: 1 }]);
202+ });
203+
204+ test("detects multiple changes", () => {
205+ const a = new CellBuffer(3, 3);
206+ const b = new CellBuffer(3, 3);
207+ b.set(0, 0, {
208+ char: "A",
209+ fgColor: null,
210+ bgColor: null,
211+ bold: false,
212+ italic: false,
213+ underline: false,
214+ });
215+ b.set(2, 2, {
216+ char: "B",
217+ fgColor: null,
218+ bgColor: null,
219+ bold: false,
220+ italic: false,
221+ underline: false,
222+ });
223+ const changes = a.diff(b);
224+ expect(changes).toHaveLength(2);
225+ expect(changes).toContainEqual({ x: 0, y: 0 });
226+ expect(changes).toContainEqual({ x: 2, y: 2 });
227+ });
228+
229+ test("detects style-only changes", () => {
230+ const a = new CellBuffer(3, 3);
231+ const b = new CellBuffer(3, 3);
232+ a.set(0, 0, {
233+ char: "X",
234+ fgColor: null,
235+ bgColor: null,
236+ bold: false,
237+ italic: false,
238+ underline: false,
239+ });
240+ b.set(0, 0, {
241+ char: "X",
242+ fgColor: "red",
243+ bgColor: null,
244+ bold: false,
245+ italic: false,
246+ underline: false,
247+ });
248+ expect(a.diff(b)).toEqual([{ x: 0, y: 0 }]);
249+ });
250+ });
251+
252+ describe("isEmpty", () => {
253+ test("empty cell is transparent", () => {
254+ const buf = new CellBuffer(3, 3);
255+ expect(buf.isEmpty(0, 0)).toBe(true);
256+ });
257+
258+ test("non-empty cell is not transparent", () => {
259+ const buf = new CellBuffer(3, 3);
260+ buf.set(1, 1, {
261+ char: "X",
262+ fgColor: null,
263+ bgColor: null,
264+ bold: false,
265+ italic: false,
266+ underline: false,
267+ });
268+ expect(buf.isEmpty(1, 1)).toBe(false);
269+ });
270+
271+ test("space with background is not transparent", () => {
272+ const buf = new CellBuffer(3, 3);
273+ buf.set(0, 0, {
274+ char: " ",
275+ fgColor: null,
276+ bgColor: "blue",
277+ bold: false,
278+ italic: false,
279+ underline: false,
280+ });
281+ expect(buf.isEmpty(0, 0)).toBe(false);
282+ });
283+ });
284+});
packages/core/src/cell-buffer.ts+196−0
@@ -0,0 +1,196 @@
1+import type { Color } from "@cel-tui/types";
2+
3+/**
4+ * A single terminal cell with character content and styling.
5+ *
6+ * Each cell represents one column in the terminal grid.
7+ * Wide characters (CJK, emoji) occupy two cells — the first cell
8+ * holds the character, the second is a continuation marker.
9+ */
10+export interface Cell {
11+ /** The grapheme cluster displayed in this cell. */
12+ char: string;
13+ /** Foreground color, or null for terminal default. */
14+ fgColor: Color | null;
15+ /** Background color, or null for terminal default. */
16+ bgColor: Color | null;
17+ /** Bold weight. */
18+ bold: boolean;
19+ /** Italic style. */
20+ italic: boolean;
21+ /** Underline decoration. */
22+ underline: boolean;
23+}
24+
25+/**
26+ * The default empty cell — a space with no styling.
27+ * Used for cleared/uninitialized cells and transparency detection.
28+ */
29+export const EMPTY_CELL: Readonly<Cell> = {
30+ char: " ",
31+ fgColor: null,
32+ bgColor: null,
33+ bold: false,
34+ italic: false,
35+ underline: false,
36+};
37+
38+function cellsEqual(a: Cell, b: Cell): boolean {
39+ return (
40+ a.char === b.char &&
41+ a.fgColor === b.fgColor &&
42+ a.bgColor === b.bgColor &&
43+ a.bold === b.bold &&
44+ a.italic === b.italic &&
45+ a.underline === b.underline
46+ );
47+}
48+
49+/**
50+ * A 2D grid of styled terminal cells.
51+ *
52+ * The cell buffer is the core rendering target. The layout engine
53+ * computes rects, painting writes styled cells into those rects,
54+ * and the diff algorithm compares the current buffer against the
55+ * previous one to produce minimal terminal updates.
56+ *
57+ * Empty cells (matching {@link EMPTY_CELL}) are considered transparent
58+ * for layer compositing — higher layers overwrite lower layers only
59+ * where they have non-empty content.
60+ */
61+export class CellBuffer {
62+ private cells: Cell[];
63+ private _width: number;
64+ private _height: number;
65+
66+ /**
67+ * Create a new cell buffer filled with empty cells.
68+ *
69+ * @param width - Buffer width in columns.
70+ * @param height - Buffer height in rows.
71+ */
72+ constructor(width: number, height: number) {
73+ this._width = width;
74+ this._height = height;
75+ this.cells = new Array(width * height);
76+ this.clearCells(0, this.cells.length);
77+ }
78+
79+ /** Buffer width in columns. */
80+ get width(): number {
81+ return this._width;
82+ }
83+
84+ /** Buffer height in rows. */
85+ get height(): number {
86+ return this._height;
87+ }
88+
89+ /**
90+ * Get the cell at `(x, y)`.
91+ * Returns {@link EMPTY_CELL} for out-of-bounds coordinates.
92+ */
93+ get(x: number, y: number): Cell {
94+ if (x < 0 || x >= this._width || y < 0 || y >= this._height) {
95+ return EMPTY_CELL;
96+ }
97+ return this.cells[y * this._width + x]!;
98+ }
99+
100+ /**
101+ * Set the cell at `(x, y)`.
102+ * Out-of-bounds writes are silently ignored.
103+ */
104+ set(x: number, y: number, cell: Cell): void {
105+ if (x < 0 || x >= this._width || y < 0 || y >= this._height) return;
106+ this.cells[y * this._width + x] = cell;
107+ }
108+
109+ /**
110+ * Check if the cell at `(x, y)` is empty (transparent).
111+ * A cell is empty if it matches {@link EMPTY_CELL} exactly.
112+ */
113+ isEmpty(x: number, y: number): boolean {
114+ return cellsEqual(this.get(x, y), EMPTY_CELL);
115+ }
116+
117+ /** Reset all cells to {@link EMPTY_CELL}. */
118+ clear(): void {
119+ this.clearCells(0, this.cells.length);
120+ }
121+
122+ /**
123+ * Fill a rectangular region with a cell value.
124+ * Coordinates are clipped to buffer bounds.
125+ *
126+ * @param x - Left column (inclusive).
127+ * @param y - Top row (inclusive).
128+ * @param w - Width in columns.
129+ * @param h - Height in rows.
130+ * @param cell - Cell value to fill with.
131+ */
132+ fill(x: number, y: number, w: number, h: number, cell: Cell): void {
133+ const x0 = Math.max(0, x);
134+ const y0 = Math.max(0, y);
135+ const x1 = Math.min(this._width, x + w);
136+ const y1 = Math.min(this._height, y + h);
137+ for (let row = y0; row < y1; row++) {
138+ for (let col = x0; col < x1; col++) {
139+ this.cells[row * this._width + col] = cell;
140+ }
141+ }
142+ }
143+
144+ /**
145+ * Resize the buffer. Existing content within the new bounds is preserved.
146+ * New cells are initialized to {@link EMPTY_CELL}.
147+ *
148+ * @param width - New width in columns.
149+ * @param height - New height in rows.
150+ */
151+ resize(width: number, height: number): void {
152+ const newCells = new Array<Cell>(width * height);
153+ // Fill with empty
154+ for (let i = 0; i < newCells.length; i++) {
155+ newCells[i] = { ...EMPTY_CELL };
156+ }
157+ // Copy existing content
158+ const copyW = Math.min(this._width, width);
159+ const copyH = Math.min(this._height, height);
160+ for (let y = 0; y < copyH; y++) {
161+ for (let x = 0; x < copyW; x++) {
162+ newCells[y * width + x] = this.cells[y * this._width + x]!;
163+ }
164+ }
165+ this.cells = newCells;
166+ this._width = width;
167+ this._height = height;
168+ }
169+
170+ /**
171+ * Compare this buffer against another and return positions that differ.
172+ * Used for differential rendering — only changed cells need terminal updates.
173+ *
174+ * @param other - The buffer to compare against.
175+ * @returns Array of `{ x, y }` positions where cells differ.
176+ */
177+ diff(other: CellBuffer): { x: number; y: number }[] {
178+ const changes: { x: number; y: number }[] = [];
179+ const w = Math.min(this._width, other._width);
180+ const h = Math.min(this._height, other._height);
181+ for (let y = 0; y < h; y++) {
182+ for (let x = 0; x < w; x++) {
183+ if (!cellsEqual(this.get(x, y), other.get(x, y))) {
184+ changes.push({ x, y });
185+ }
186+ }
187+ }
188+ return changes;
189+ }
190+
191+ private clearCells(start: number, end: number): void {
192+ for (let i = start; i < end; i++) {
193+ this.cells[i] = { ...EMPTY_CELL };
194+ }
195+ }
196+}