@tuidom/core 0.1.0

package/dist/rendering/cell.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A single terminal cell. Mutable for performance — avoids allocations on every frame.
+ */
+export declare class Cell {
+    /** The displayed character (single grapheme) */
+    char: string;
+    /** Foreground color as packed 24-bit RGB, or DEFAULT_COLOR */
+    fg: number;
+    /** Background color as packed 24-bit RGB, or DEFAULT_COLOR */
+    bg: number;
+    /** Bitmask of StyleFlags */
+    style: number;
+    /**
+     * Display width of this cell in terminal columns.
+     * - 1 for normal characters
+     * - 2 for wide characters (CJK, emoji) — only on the "head" cell
+     * - 0 for continuation cells (second column of a wide character)
+     */
+    width: number;
+    constructor(char?: string, fg?: number, bg?: number, style?: number, width?: number);
+    static empty(): Cell;
+    equals(other: Cell): boolean;
+    copyFrom(other: Cell): void;
+}

package/dist/rendering/cell.js

@@ -0,0 +1,46 @@
+import { DEFAULT_COLOR } from "../common/colorUtils.js";
+import { StyleFlags } from "../common/styleFlags.js";
+/**
+ * A single terminal cell. Mutable for performance — avoids allocations on every frame.
+ */
+export class Cell {
+    /** The displayed character (single grapheme) */
+    char;
+    /** Foreground color as packed 24-bit RGB, or DEFAULT_COLOR */
+    fg;
+    /** Background color as packed 24-bit RGB, or DEFAULT_COLOR */
+    bg;
+    /** Bitmask of StyleFlags */
+    style;
+    /**
+     * Display width of this cell in terminal columns.
+     * - 1 for normal characters
+     * - 2 for wide characters (CJK, emoji) — only on the "head" cell
+     * - 0 for continuation cells (second column of a wide character)
+     */
+    width;
+    constructor(char = " ", fg = DEFAULT_COLOR, bg = DEFAULT_COLOR, style = StyleFlags.None, width = 1) {
+        this.char = char;
+        this.fg = fg;
+        this.bg = bg;
+        this.style = style;
+        this.width = width;
+    }
+    static empty() {
+        return new Cell();
+    }
+    equals(other) {
+        return (this.char === other.char &&
+            this.fg === other.fg &&
+            this.bg === other.bg &&
+            this.style === other.style &&
+            this.width === other.width);
+    }
+    copyFrom(other) {
+        this.char = other.char;
+        this.fg = other.fg;
+        this.bg = other.bg;
+        this.style = other.style;
+        this.width = other.width;
+    }
+}

package/dist/rendering/damage.d.ts

@@ -0,0 +1,35 @@
+import { Rect } from "../common/geometryPromitives.js";
+/**
+ * Кап списка damage-областей кадра. Больше — слишком дробный кадр (оверхед
+ * прохода на каждый rect), меньше — слияния накрывают чистые виджеты между
+ * повреждёнными. 8 хватает на типичный кадр воркбенча: виджет + статусбар +
+ * пара лейблов.
+ */
+export declare const MAX_DAMAGE_RECTS = 8;
+/**
+ * Накопитель повреждённых областей кадра (в экранных координатах).
+ *
+ * `add` поглощает вложенные rect'ы (damage-обход идёт pre-order, родитель
+ * раньше детей — вложенные добавления схлопываются дёшево). `finalize` даёт
+ * итоговые области прохода отрисовки: клип к экрану, слияние пересекающихся,
+ * кап {@link MAX_DAMAGE_RECTS} слиянием пары с минимальным приростом площади.
+ *
+ * Области НЕ дилатируются: расширение «на всякий случай» заставляло бы
+ * соседний виджет рендериться на каждый чужой кадр (клип срезает запись, но
+ * не работу — редактор сегментирует все видимые строки независимо от ширины
+ * клипа). Wide-char пары на кромке области защищает содержимо-зависимый снап
+ * Grid.snapToWideChars в renderFrame.
+ *
+ * Инвариант потребителя (renderFrame): множество очищаемых ячеек обязано
+ * совпадать с множеством, по которому идёт прунинг прохода, — поэтому и
+ * очистка, и клип каждого прохода берут ровно rect'ы из finalize() (после
+ * снапа).
+ */
+export declare class DamageList {
+    private rects;
+    add(rect: Rect): void;
+    get isEmpty(): boolean;
+    /** Сырые накопленные rect'ы (до дилатации/слияния) — для тестов и инспектора. */
+    snapshot(): readonly Rect[];
+    finalize(screenBounds: Rect): Rect[];
+}

package/dist/rendering/damage.js

@@ -0,0 +1,99 @@
+import { Point, Rect, Size } from "../common/geometryPromitives.js";
+/** Сливает пересекающиеся rect'ы на месте до неподвижной точки. */
+function mergeIntersecting(out) {
+    let merged = true;
+    while (merged) {
+        merged = false;
+        outer: for (let i = 0; i < out.length; i++) {
+            for (let j = i + 1; j < out.length; j++) {
+                if (out[i].intersects(out[j])) {
+                    out[i] = out[i].union(out[j]);
+                    out.splice(j, 1);
+                    merged = true;
+                    break outer;
+                }
+            }
+        }
+    }
+}
+/**
+ * Кап списка damage-областей кадра. Больше — слишком дробный кадр (оверхед
+ * прохода на каждый rect), меньше — слияния накрывают чистые виджеты между
+ * повреждёнными. 8 хватает на типичный кадр воркбенча: виджет + статусбар +
+ * пара лейблов.
+ */
+export const MAX_DAMAGE_RECTS = 8;
+/**
+ * Накопитель повреждённых областей кадра (в экранных координатах).
+ *
+ * `add` поглощает вложенные rect'ы (damage-обход идёт pre-order, родитель
+ * раньше детей — вложенные добавления схлопываются дёшево). `finalize` даёт
+ * итоговые области прохода отрисовки: клип к экрану, слияние пересекающихся,
+ * кап {@link MAX_DAMAGE_RECTS} слиянием пары с минимальным приростом площади.
+ *
+ * Области НЕ дилатируются: расширение «на всякий случай» заставляло бы
+ * соседний виджет рендериться на каждый чужой кадр (клип срезает запись, но
+ * не работу — редактор сегментирует все видимые строки независимо от ширины
+ * клипа). Wide-char пары на кромке области защищает содержимо-зависимый снап
+ * Grid.snapToWideChars в renderFrame.
+ *
+ * Инвариант потребителя (renderFrame): множество очищаемых ячеек обязано
+ * совпадать с множеством, по которому идёт прунинг прохода, — поэтому и
+ * очистка, и клип каждого прохода берут ровно rect'ы из finalize() (после
+ * снапа).
+ */
+export class DamageList {
+    rects = [];
+    add(rect) {
+        if (rect.isEmpty)
+            return;
+        for (let i = 0; i < this.rects.length; i++) {
+            const existing = this.rects[i];
+            if (existing.containsRect(rect))
+                return;
+            if (rect.containsRect(existing)) {
+                this.rects[i] = rect;
+                return;
+            }
+        }
+        this.rects.push(rect);
+    }
+    get isEmpty() {
+        return this.rects.length === 0;
+    }
+    /** Сырые накопленные rect'ы (до дилатации/слияния) — для тестов и инспектора. */
+    snapshot() {
+        return this.rects;
+    }
+    finalize(screenBounds) {
+        const out = [];
+        for (const rect of this.rects) {
+            const clipped = rect.intersect(screenBounds);
+            if (!clipped.isEmpty)
+                out.push(clipped);
+        }
+        mergeIntersecting(out);
+        while (out.length > MAX_DAMAGE_RECTS) {
+            // Слить пару с минимальным приростом площади объединения.
+            let bestI = 0;
+            let bestJ = 1;
+            let bestGrowth = Infinity;
+            for (let i = 0; i < out.length; i++) {
+                for (let j = i + 1; j < out.length; j++) {
+                    const union = out[i].union(out[j]);
+                    const growth = union.width * union.height - out[i].width * out[i].height - out[j].width * out[j].height;
+                    if (growth < bestGrowth) {
+                        bestGrowth = growth;
+                        bestI = i;
+                        bestJ = j;
+                    }
+                }
+            }
+            out[bestI] = out[bestI].union(out[bestJ]);
+            out.splice(bestJ, 1);
+            // Объединение могло пересечься с остальными.
+            mergeIntersecting(out);
+        }
+        return out;
+    }
+}

package/dist/rendering/grid.d.ts

@@ -0,0 +1,49 @@
+import { Point, Rect, Size } from "../common/geometryPromitives.js";
+export interface ReadonlyCellData {
+    readonly char: string;
+    readonly fg: number;
+    readonly bg: number;
+    readonly style: number;
+    readonly width: number;
+}
+export interface CellPatch {
+    char?: string;
+    fg?: number;
+    bg?: number;
+    style?: number;
+    width?: number;
+}
+/**
+ * 2D grid of terminal cells backed by a flat array for cache-friendly access.
+ */
+export declare class Grid {
+    readonly size: Size;
+    private readonly cells;
+    get width(): number;
+    get height(): number;
+    get cellCount(): number;
+    constructor(size: Size);
+    getCell(position: Point): ReadonlyCellData;
+    getCellAt(x: number, y: number): ReadonlyCellData;
+    setCell(position: Point, char: string, fg?: number, bg?: number, style?: number, width?: number): void;
+    updateCell(position: Point, patch: CellPatch): void;
+    cellEqualsAt(x: number, y: number, other: Grid): boolean;
+    copyCellFrom(x: number, y: number, source: Grid): void;
+    copyAllCellsFrom(source: Grid): void;
+    /**
+     * Расширяет rect так, чтобы его вертикальные границы не рассекали wide-char
+     * пары ТЕКУЩЕГО содержимого: продолжение (width 0) на левой кромке тянет
+     * внутрь голову слева, голова (width 2) на правой — продолжение справа.
+     * Иначе частичная очистка damage-области лечила бы голову в пробел ВНЕ
+     * области перерисовки — видимая порча соседнего чистого виджета. Одного
+     * прохода достаточно: за расширенной кромкой пара уже целиком внутри.
+     */
+    snapToWideChars(rect: Rect): Rect;
+    /**
+     * Сбрасывает ячейки rect'а к значениям clear() — через {@link updateCell},
+     * чтобы wide-char пара, пересекающая границу rect'а, чинилась штатной
+     * бухгалтерией головы/продолжения, а не оставляла осиротевшие половинки.
+     */
+    clearRect(rect: Rect): void;
+    fill(char?: string, fg?: number, bg?: number, style?: number): void;
+}

package/dist/rendering/grid.js

@@ -0,0 +1,216 @@
+import { DEFAULT_COLOR } from "../common/colorUtils.js";
+import { Point, Rect, Size } from "../common/geometryPromitives.js";
+import { StyleFlags } from "../common/styleFlags.js";
+import { Cell } from "./cell.js";
+/**
+ * 2D grid of terminal cells backed by a flat array for cache-friendly access.
+ */
+export class Grid {
+    size;
+    cells;
+    get width() {
+        return this.size.width;
+    }
+    get height() {
+        return this.size.height;
+    }
+    get cellCount() {
+        return this.cells.length;
+    }
+    constructor(size) {
+        this.size = size;
+        const total = size.width * size.height;
+        this.cells = new Array(total);
+        for (let i = 0; i < total; i++) {
+            this.cells[i] = Cell.empty();
+        }
+    }
+    getCell(position) {
+        return this.cells[position.y * this.size.width + position.x];
+    }
+    getCellAt(x, y) {
+        return this.cells[y * this.size.width + x];
+    }
+    setCell(position, char, fg = DEFAULT_COLOR, bg = DEFAULT_COLOR, style = StyleFlags.None, width = 1) {
+        const x = position.x;
+        const y = position.y;
+        const idx = y * this.size.width + x;
+        const cell = this.cells[idx];
+        // If overwriting a continuation cell, clear the head cell of that wide char
+        if (cell.width === 0 && x > 0) {
+            const head = this.cells[idx - 1];
+            if (head.width === 2) {
+                head.char = " ";
+                head.width = 1;
+            }
+        }
+        // If overwriting a head cell of a wide char, clear its continuation
+        if (cell.width === 2 && x + 1 < this.size.width) {
+            const cont = this.cells[idx + 1];
+            /* v8 ignore start -- a wide head is always followed by a width-0 continuation; the else is an unreachable invariant guard */
+            if (cont.width === 0) {
+                cont.char = " ";
+                cont.width = 1;
+            }
+            /* v8 ignore stop */
+        }
+        cell.char = char;
+        cell.fg = fg;
+        cell.bg = bg;
+        cell.style = style;
+        cell.width = width;
+        // For wide chars, set up the continuation cell
+        if (width === 2 && x + 1 < this.size.width) {
+            const cont = this.cells[idx + 1];
+            // If the continuation position holds a wide char head, clear its own continuation
+            if (cont.width === 2 && x + 2 < this.size.width) {
+                const nextCont = this.cells[idx + 2];
+                /* v8 ignore start -- a wide head is always followed by a width-0 continuation; the else is an unreachable invariant guard */
+                if (nextCont.width === 0) {
+                    nextCont.char = " ";
+                    nextCont.width = 1;
+                }
+                /* v8 ignore stop */
+            }
+            cont.char = "";
+            cont.fg = fg;
+            cont.bg = bg;
+            cont.style = style;
+            cont.width = 0;
+        }
+    }
+    updateCell(position, patch) {
+        const x = position.x;
+        const y = position.y;
+        const w = this.size.width;
+        const idx = y * w + x;
+        const cell = this.cells[idx];
+        // Wide-char bookkeeping only when char or width are being set
+        if (patch.char !== undefined || patch.width !== undefined) {
+            // If overwriting a continuation cell, clear the head cell of that wide char
+            if (cell.width === 0 && x > 0) {
+                const head = this.cells[idx - 1];
+                if (head.width === 2) {
+                    head.char = " ";
+                    head.width = 1;
+                }
+            }
+            // If overwriting a head cell of a wide char, clear its continuation
+            if (cell.width === 2 && x + 1 < w) {
+                const cont = this.cells[idx + 1];
+                /* v8 ignore start -- a wide head is always followed by a width-0 continuation; the else is an unreachable invariant guard */
+                if (cont.width === 0) {
+                    cont.char = " ";
+                    cont.width = 1;
+                }
+                /* v8 ignore stop */
+            }
+        }
+        if (patch.char !== undefined)
+            cell.char = patch.char;
+        if (patch.fg !== undefined)
+            cell.fg = patch.fg;
+        if (patch.bg !== undefined)
+            cell.bg = patch.bg;
+        if (patch.style !== undefined)
+            cell.style = patch.style;
+        if (patch.width !== undefined)
+            cell.width = patch.width;
+        // For wide chars, set up the continuation cell
+        const newWidth = patch.width ?? cell.width;
+        if (newWidth === 2 && x + 1 < w) {
+            const cont = this.cells[idx + 1];
+            // If the continuation position holds a wide char head, clear its own continuation
+            if (cont.width === 2 && x + 2 < w) {
+                const nextCont = this.cells[idx + 2];
+                /* v8 ignore start -- a wide head is always followed by a width-0 continuation; the else is an unreachable invariant guard */
+                if (nextCont.width === 0) {
+                    nextCont.char = " ";
+                    nextCont.width = 1;
+                }
+                /* v8 ignore stop */
+            }
+            cont.char = "";
+            cont.width = 0;
+            if (patch.fg !== undefined)
+                cont.fg = patch.fg;
+            if (patch.bg !== undefined)
+                cont.bg = patch.bg;
+            if (patch.style !== undefined)
+                cont.style = patch.style;
+        }
+    }
+    cellEqualsAt(x, y, other) {
+        const idx = y * this.size.width + x;
+        return this.cells[idx].equals(other.cells[idx]);
+    }
+    copyCellFrom(x, y, source) {
+        const idx = y * this.size.width + x;
+        this.cells[idx].copyFrom(source.cells[idx]);
+    }
+    copyAllCellsFrom(source) {
+        for (let i = 0, len = this.cells.length; i < len; i++) {
+            this.cells[i].copyFrom(source.cells[i]);
+        }
+    }
+    /**
+     * Расширяет rect так, чтобы его вертикальные границы не рассекали wide-char
+     * пары ТЕКУЩЕГО содержимого: продолжение (width 0) на левой кромке тянет
+     * внутрь голову слева, голова (width 2) на правой — продолжение справа.
+     * Иначе частичная очистка damage-области лечила бы голову в пробел ВНЕ
+     * области перерисовки — видимая порча соседнего чистого виджета. Одного
+     * прохода достаточно: за расширенной кромкой пара уже целиком внутри.
+     */
+    snapToWideChars(rect) {
+        const w = this.size.width;
+        const x0 = Math.max(0, rect.x);
+        const y0 = Math.max(0, rect.y);
+        const x1 = Math.min(w, rect.right);
+        const y1 = Math.min(this.size.height, rect.bottom);
+        let extendLeft = false;
+        let extendRight = false;
+        for (let y = y0; y < y1; y++) {
+            if (x0 > 0 && this.cells[y * w + x0].width === 0)
+                extendLeft = true;
+            if (x1 < w && x1 > 0 && this.cells[y * w + x1 - 1].width === 2)
+                extendRight = true;
+        }
+        if (!extendLeft && !extendRight)
+            return rect;
+        const newX0 = extendLeft ? x0 - 1 : x0;
+        const newX1 = extendRight ? x1 + 1 : x1;
+        return new Rect(new Point(newX0, rect.y), new Size(newX1 - newX0, rect.height));
+    }
+    /**
+     * Сбрасывает ячейки rect'а к значениям clear() — через {@link updateCell},
+     * чтобы wide-char пара, пересекающая границу rect'а, чинилась штатной
+     * бухгалтерией головы/продолжения, а не оставляла осиротевшие половинки.
+     */
+    clearRect(rect) {
+        const x0 = Math.max(0, rect.x);
+        const y0 = Math.max(0, rect.y);
+        const x1 = Math.min(this.size.width, rect.right);
+        const y1 = Math.min(this.size.height, rect.bottom);
+        for (let y = y0; y < y1; y++) {
+            for (let x = x0; x < x1; x++) {
+                this.updateCell(new Point(x, y), {
+                    char: " ",
+                    fg: DEFAULT_COLOR,
+                    bg: DEFAULT_COLOR,
+                    style: StyleFlags.None,
+                    width: 1,
+                });
+            }
+        }
+    }
+    fill(char = " ", fg = DEFAULT_COLOR, bg = DEFAULT_COLOR, style = StyleFlags.None) {
+        for (let i = 0, len = this.cells.length; i < len; i++) {
+            const cell = this.cells[i];
+            cell.char = char;
+            cell.fg = fg;
+            cell.bg = bg;
+            cell.style = style;
+            cell.width = 1;
+        }
+    }
+}

package/dist/rendering/gridSnapshot.d.ts

@@ -0,0 +1,33 @@
+import type { Point } from "../common/geometryPromitives.js";
+import type { Grid } from "./grid.js";
+/**
+ * Plain-data snapshot of a single rendered {@link Grid} cell. Colours are packed
+ * 24-bit RGB or the `DEFAULT_COLOR` sentinel; `style` is a `StyleFlags` bitmask;
+ * `width` mirrors {@link Grid} cell width (1 normal, 2 wide head, 0 continuation).
+ */
+export interface CellSnapshot {
+    char: string;
+    fg: number;
+    bg: number;
+    style: number;
+    width: number;
+}
+/**
+ * Serialized terminal frame: everything needed to re-draw the screen elsewhere
+ * (an image rasterizer, a diff viewer) without a terminal. Pure data — safe to
+ * JSON-encode and send over the inspector protocol. `cells` is row-major with
+ * `cols * rows` entries.
+ */
+export interface GridSnapshot {
+    cols: number;
+    rows: number;
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+    cells: CellSnapshot[];
+}
+/** Freeze the current state of `grid` (plus cursor) into a {@link GridSnapshot}. */
+export declare function snapshotGrid(grid: Grid, cursor: Point | null): GridSnapshot;
+/** An empty snapshot of the given size — used before the first frame is rendered. */
+export declare function emptyGridSnapshot(cols: number, rows: number): GridSnapshot;

package/dist/rendering/gridSnapshot.js

@@ -0,0 +1,32 @@
+import { DEFAULT_COLOR } from "../common/colorUtils.js";
+/** Freeze the current state of `grid` (plus cursor) into a {@link GridSnapshot}. */
+export function snapshotGrid(grid, cursor) {
+    const { width: cols, height: rows } = grid;
+    const cells = new Array(cols * rows);
+    for (let y = 0; y < rows; y++) {
+        for (let x = 0; x < cols; x++) {
+            const cell = grid.getCellAt(x, y);
+            cells[y * cols + x] = {
+                char: cell.char,
+                fg: cell.fg,
+                bg: cell.bg,
+                style: cell.style,
+                width: cell.width,
+            };
+        }
+    }
+    return {
+        cols,
+        rows,
+        cursor: cursor === null ? null : { x: cursor.x, y: cursor.y },
+        cells,
+    };
+}
+/** An empty snapshot of the given size — used before the first frame is rendered. */
+export function emptyGridSnapshot(cols, rows) {
+    const cells = new Array(cols * rows);
+    for (let i = 0; i < cells.length; i++) {
+        cells[i] = { char: " ", fg: DEFAULT_COLOR, bg: DEFAULT_COLOR, style: 0, width: 1 };
+    }
+    return { cols, rows, cursor: null, cells };
+}

package/dist/rendering/gridToSvg.d.ts

@@ -0,0 +1,29 @@
+import type { GridSnapshot } from "./gridSnapshot.js";
+/**
+ * Options for {@link gridToSvg}. Colours are packed 24-bit RGB. Metrics are in
+ * pixels; the cell grid is drawn on a fixed lattice so every run lands exactly on
+ * `col * cellWidth` regardless of the viewer's font advance.
+ */
+export interface GridToSvgOptions {
+    cellWidth?: number;
+    cellHeight?: number;
+    fontSize?: number;
+    /** Vertical baseline offset inside a cell (0 = top). */
+    baseline?: number;
+    /** Font family used for glyphs. For PNG rendering pass a concrete family. */
+    fontFamily?: string;
+    /** Resolves cells whose fg is `DEFAULT_COLOR`. */
+    defaultFg?: number;
+    /** Resolves cells whose bg is `DEFAULT_COLOR`, and paints the page background. */
+    defaultBg?: number;
+}
+/**
+ * Render a {@link GridSnapshot} into a standalone, self-contained SVG string.
+ *
+ * Pure — no fonts, no libraries, no I/O. Background is drawn as merged per-row
+ * rects; glyphs as per-run `<text>` with `textLength`/`lengthAdjust` so the run
+ * fills exactly its column span (grid stays aligned under any font). `Inverse`
+ * swaps fg/bg per cell; wide cells (`width === 2`) span two columns and their
+ * continuation (`width === 0`) is skipped.
+ */
+export declare function gridToSvg(snapshot: GridSnapshot, options?: GridToSvgOptions): string;