@tuidom/core 0.1.0

package/dist/rendering/gridToSvg.js

@@ -0,0 +1,145 @@
+import { DEFAULT_COLOR, unpackB, unpackG, unpackR } from "../common/colorUtils.js";
+import { StyleFlags } from "../common/styleFlags.js";
+// VS Code Dark+ editor foreground / background.
+const DEFAULT_FG = 0xd4d4d4;
+const DEFAULT_BG = 0x1e1e1e;
+function resolveOptions(options) {
+    const cellHeight = options.cellHeight ?? 18;
+    return {
+        cellWidth: options.cellWidth ?? 9,
+        cellHeight,
+        fontSize: options.fontSize ?? 15,
+        baseline: options.baseline ?? Math.round(cellHeight * 0.76),
+        fontFamily: options.fontFamily ?? "monospace",
+        defaultFg: options.defaultFg ?? DEFAULT_FG,
+        defaultBg: options.defaultBg ?? DEFAULT_BG,
+    };
+}
+function toHex(color) {
+    const r = unpackR(color).toString(16).padStart(2, "0");
+    const g = unpackG(color).toString(16).padStart(2, "0");
+    const b = unpackB(color).toString(16).padStart(2, "0");
+    return `#${r}${g}${b}`;
+}
+function resolveColor(color, fallback) {
+    return color === DEFAULT_COLOR ? fallback : color;
+}
+function escapeXml(text) {
+    return text.replace(/[&<>]/gu, (ch) => (ch === "&" ? "&amp;" : ch === "<" ? "&lt;" : "&gt;"));
+}
+function styleAttrs(style) {
+    const attrs = [];
+    if ((style & StyleFlags.Bold) !== 0)
+        attrs.push(`font-weight="bold"`);
+    if ((style & StyleFlags.Italic) !== 0)
+        attrs.push(`font-style="italic"`);
+    const decorations = [];
+    if ((style & (StyleFlags.Underline | StyleFlags.Undercurl)) !== 0)
+        decorations.push("underline");
+    if ((style & StyleFlags.Strikethrough) !== 0)
+        decorations.push("line-through");
+    if (decorations.length > 0)
+        attrs.push(`text-decoration="${decorations.join(" ")}"`);
+    if ((style & StyleFlags.Dim) !== 0)
+        attrs.push(`opacity="0.6"`);
+    return attrs.length > 0 ? " " + attrs.join(" ") : "";
+}
+const TEXT_STYLE_MASK = ~StyleFlags.Inverse;
+/**
+ * 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 function gridToSvg(snapshot, options = {}) {
+    const opts = resolveOptions(options);
+    const { cols, rows, cells } = snapshot;
+    const width = cols * opts.cellWidth;
+    const height = rows * opts.cellHeight;
+    const parts = [];
+    parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" ` +
+        `viewBox="0 0 ${width} ${height}" font-family="${escapeXml(opts.fontFamily)}" ` +
+        `font-size="${opts.fontSize}">`);
+    parts.push(`<rect width="${width}" height="${height}" fill="${toHex(opts.defaultBg)}"/>`);
+    // Effective per-cell colours with Inverse applied and defaults resolved.
+    const effFg = new Array(cells.length);
+    const effBg = new Array(cells.length);
+    for (let i = 0; i < cells.length; i++) {
+        const cell = cells[i];
+        let fg = resolveColor(cell.fg, opts.defaultFg);
+        let bg = resolveColor(cell.bg, opts.defaultBg);
+        if ((cell.style & StyleFlags.Inverse) !== 0) {
+            const tmp = fg;
+            fg = bg;
+            bg = tmp;
+        }
+        effFg[i] = fg;
+        effBg[i] = bg;
+    }
+    // Background: merge horizontal runs of identical bg per row; skip page default.
+    for (let y = 0; y < rows; y++) {
+        let x = 0;
+        while (x < cols) {
+            const bg = effBg[y * cols + x];
+            let end = x;
+            while (end + 1 < cols && effBg[y * cols + end + 1] === bg)
+                end++;
+            if (bg !== opts.defaultBg) {
+                const rx = x * opts.cellWidth;
+                const rw = (end - x + 1) * opts.cellWidth;
+                parts.push(`<rect x="${rx}" y="${y * opts.cellHeight}" width="${rw}" height="${opts.cellHeight}" fill="${toHex(bg)}"/>`);
+            }
+            x = end + 1;
+        }
+    }
+    // Text: merge contiguous glyph cells sharing fg + text-style into one <text>.
+    for (let y = 0; y < rows; y++) {
+        let x = 0;
+        let runStartCol = -1;
+        let runCols = 0;
+        let runText = "";
+        let runFg = 0;
+        let runStyle = 0;
+        const flush = () => {
+            if (runStartCol >= 0 && runText.length > 0) {
+                const tx = runStartCol * opts.cellWidth;
+                const ty = y * opts.cellHeight + opts.baseline;
+                const tl = runCols * opts.cellWidth;
+                parts.push(`<text x="${tx}" y="${ty}" textLength="${tl}" lengthAdjust="spacingAndGlyphs" ` +
+                    `fill="${toHex(runFg)}"${styleAttrs(runStyle)}>${escapeXml(runText)}</text>`);
+            }
+            runStartCol = -1;
+            runCols = 0;
+            runText = "";
+        };
+        while (x < cols) {
+            const cell = cells[y * cols + x];
+            const advance = cell.width === 0 ? 1 : cell.width;
+            const isGlyph = cell.width !== 0 && cell.char !== " " && cell.char !== "";
+            if (!isGlyph) {
+                flush();
+                x += advance;
+                continue;
+            }
+            const fg = effFg[y * cols + x];
+            const style = cell.style & TEXT_STYLE_MASK;
+            if (runStartCol >= 0 && (fg !== runFg || style !== runStyle || runStartCol + runCols !== x)) {
+                flush();
+            }
+            if (runStartCol < 0) {
+                runStartCol = x;
+                runFg = fg;
+                runStyle = style;
+            }
+            runText += cell.char;
+            runCols += cell.width;
+            x += cell.width;
+        }
+        flush();
+    }
+    parts.push(`</svg>`);
+    return parts.join("");
+}

package/dist/rendering/terminalRenderer.d.ts

@@ -0,0 +1,28 @@
+import type { Grid } from "./grid.js";
+/** Minimal writable interface so we can inject a test double instead of real stdout. */
+export interface WritableOutput {
+    write(data: string): void;
+}
+/**
+ * High-performance terminal renderer.
+ *
+ * - On `setup()` switches to Alternate Screen Buffer and hides the cursor.
+ * - On `destroy()` restores the original screen and shows the cursor.
+ * - `render(current, previous)` diffs two grids, emits minimal ANSI escape
+ *   sequences via an internal state machine, and flushes exactly one
+ *   `stdout.write()` per frame.
+ */
+export declare class TerminalRenderer {
+    private readonly out;
+    constructor(out?: WritableOutput);
+    setup(): void;
+    destroy(): void;
+    /**
+     * Diff `currentGrid` against `previousGrid`, emit only changed cells,
+     * then update `previousGrid` in-place so it mirrors `currentGrid` for the
+     * next frame.
+     *
+     * Exactly one `stdout.write()` at the end.
+     */
+    render(currentGrid: Grid, previousGrid: Grid): void;
+}

package/dist/rendering/terminalRenderer.js

@@ -0,0 +1,161 @@
+import { DEFAULT_COLOR, unpackB, unpackG, unpackR } from "../common/colorUtils.js";
+import { StyleFlags } from "../common/styleFlags.js";
+/**
+ * High-performance terminal renderer.
+ *
+ * - On `setup()` switches to Alternate Screen Buffer and hides the cursor.
+ * - On `destroy()` restores the original screen and shows the cursor.
+ * - `render(current, previous)` diffs two grids, emits minimal ANSI escape
+ *   sequences via an internal state machine, and flushes exactly one
+ *   `stdout.write()` per frame.
+ */
+export class TerminalRenderer {
+    out;
+    constructor(out = process.stdout) {
+        this.out = out;
+    }
+    // ── Lifecycle ────────────────────────────────────────────────
+    setup() {
+        this.out.write("\x1b[?1049h" + // alternate screen buffer
+            "\x1b[?25l");
+    }
+    destroy() {
+        this.out.write("\x1b[?25h" + // show cursor
+            "\x1b[?1049l");
+    }
+    // ── Render ───────────────────────────────────────────────────
+    /**
+     * Diff `currentGrid` against `previousGrid`, emit only changed cells,
+     * then update `previousGrid` in-place so it mirrors `currentGrid` for the
+     * next frame.
+     *
+     * Exactly one `stdout.write()` at the end.
+     */
+    render(currentGrid, previousGrid) {
+        const width = currentGrid.width;
+        const height = currentGrid.height;
+        let buf = "";
+        // State machine: track what the terminal "thinks" is active so we
+        // only emit SGR codes when something actually changes.
+        let activeFg = -2; // impossible sentinel — forces first emission
+        let activeBg = -2;
+        let activeStyle = -1; // impossible sentinel
+        let cursorX = -1; // current cursor column (0-based, -1 = unknown)
+        let cursorY = -1;
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                // Skip bottom-right corner: writing here triggers hardware scroll.
+                if (x === width - 1 && y === height - 1)
+                    continue;
+                if (currentGrid.cellEqualsAt(x, y, previousGrid))
+                    continue;
+                const cur = currentGrid.getCellAt(x, y);
+                // Skip continuation cells (second column of a wide character).
+                // The head cell already wrote the character, and the terminal
+                // auto-advanced the cursor past the continuation column.
+                if (cur.width === 0) {
+                    previousGrid.copyCellFrom(x, y, currentGrid);
+                    continue;
+                }
+                // ── Cursor positioning ──────────────────────────
+                // If the cursor is already at (x, y) we can skip the CUP sequence.
+                // After writing a character the cursor auto-advances by one column.
+                if (cursorY !== y || cursorX !== x) {
+                    buf += `\x1b[${(y + 1).toString()};${(x + 1).toString()}H`;
+                }
+                // ── SGR (Select Graphic Rendition) ──────────────
+                const needFg = cur.fg;
+                const needBg = cur.bg;
+                const needStyle = cur.style;
+                if (needStyle !== activeStyle) {
+                    // Style changed — cheapest strategy: full reset + re-apply everything.
+                    buf += "\x1b[0m";
+                    // activeFg = DEFAULT_COLOR;
+                    // activeBg = DEFAULT_COLOR;
+                    activeStyle = StyleFlags.None;
+                    if (needStyle !== StyleFlags.None) {
+                        buf += styleToSgr(needStyle);
+                        activeStyle = needStyle;
+                    }
+                    // After reset we must re-emit colors even if they haven't changed,
+                    // because the reset wiped them.
+                    if (needFg !== DEFAULT_COLOR) {
+                        buf += fgSgr(needFg);
+                    }
+                    activeFg = needFg;
+                    if (needBg !== DEFAULT_COLOR) {
+                        buf += bgSgr(needBg);
+                    }
+                    activeBg = needBg;
+                }
+                else {
+                    // Style unchanged — update colors individually.
+                    if (needFg !== activeFg) {
+                        buf += needFg === DEFAULT_COLOR ? "\x1b[39m" : fgSgr(needFg);
+                        activeFg = needFg;
+                    }
+                    if (needBg !== activeBg) {
+                        buf += needBg === DEFAULT_COLOR ? "\x1b[49m" : bgSgr(needBg);
+                        activeBg = needBg;
+                    }
+                }
+                // ── Character ───────────────────────────────────
+                buf += cur.char;
+                // Update cursor tracking (character auto-advances).
+                // Wide characters (width=2) advance the cursor by 2 columns.
+                const charWidth = cur.width;
+                if (x + charWidth >= width) {
+                    // Right margin: terminal behaviour is unpredictable after
+                    // writing the last column (may or may not auto-wrap).
+                    // Invalidate cursor so the next cell gets an absolute CUP.
+                    cursorX = -1;
+                    cursorY = -1;
+                }
+                else {
+                    cursorX = x + charWidth;
+                    cursorY = y;
+                }
+                // Update previous-frame buffer so the next render sees no diff.
+                previousGrid.copyCellFrom(x, y, currentGrid);
+            }
+        }
+        // Reset SGR at the end of the frame so we don't leave the terminal
+        // in a weird state between frames. Only if we actually emitted any cells.
+        if (buf.length > 0 &&
+            (activeStyle !== StyleFlags.None || activeFg !== DEFAULT_COLOR || activeBg !== DEFAULT_COLOR)) {
+            buf += "\x1b[0m";
+        }
+        if (buf.length > 0) {
+            this.out.write(buf);
+        }
+    }
+}
+// ── SGR helpers  ─────────────────────────────────────────────────
+function fgSgr(packedRgb) {
+    return `\x1b[38;2;${unpackR(packedRgb).toString()};${unpackG(packedRgb).toString()};${unpackB(packedRgb).toString()}m`;
+}
+function bgSgr(packedRgb) {
+    return `\x1b[48;2;${unpackR(packedRgb).toString()};${unpackG(packedRgb).toString()};${unpackB(packedRgb).toString()}m`;
+}
+/**
+ * Convert a StyleFlags bitmask to the corresponding SGR escape sequence(s).
+ * Returns a single concatenated string (e.g. `"\x1b[1m\x1b[3m"` for Bold+Italic).
+ */
+function styleToSgr(flags) {
+    let s = "";
+    if (flags & StyleFlags.Bold)
+        s += "\x1b[1m";
+    if (flags & StyleFlags.Dim)
+        s += "\x1b[2m";
+    if (flags & StyleFlags.Italic)
+        s += "\x1b[3m";
+    if (flags & StyleFlags.Underline)
+        s += "\x1b[4m";
+    if (flags & StyleFlags.Undercurl)
+        s += "\x1b[4:3m";
+    if (flags & StyleFlags.Inverse)
+        s += "\x1b[7m";
+    if (flags & StyleFlags.Strikethrough)
+        s += "\x1b[9m";
+    return s;
+}

package/dist/rendering/terminalScreen.d.ts

@@ -0,0 +1,25 @@
+import type { ITerminalBackend } from "../backend/iTerminalBackend.js";
+import { Point, type Rect, Size } from "../common/geometryPromitives.js";
+import type { CellPatch, ReadonlyCellData } from "./grid.js";
+export declare class TerminalScreen {
+    private grid;
+    size: Size;
+    cursorPosition: Point | null;
+    get width(): number;
+    get height(): number;
+    constructor(size?: Size);
+    setCursorPosition(position: Point): void;
+    clearCursorPosition(): void;
+    setCell(position: Point, cell: CellPatch): void;
+    getCell(position: Point): ReadonlyCellData;
+    flush(backend: ITerminalBackend): void;
+    clear(): void;
+    /**
+     * Семантика {@link clear} в границах rect'а — очистка damage-области перед
+     * частичным проходом отрисовки. Курсор НЕ трогает: им управляет кадр
+     * (renderFrame гасит позицию, только если она попала в damage).
+     */
+    clearRect(rect: Rect): void;
+    /** См. {@link Grid.snapToWideChars} — границы области не рассекают wide-пары. */
+    snapToWideChars(rect: Rect): Rect;
+}

package/dist/rendering/terminalScreen.js

@@ -0,0 +1,50 @@
+import { DEFAULT_COLOR } from "../common/colorUtils.js";
+import { Point, Size } from "../common/geometryPromitives.js";
+import { StyleFlags } from "../common/styleFlags.js";
+import { Grid } from "./grid.js";
+export class TerminalScreen {
+    grid;
+    size;
+    cursorPosition = null;
+    get width() {
+        return this.size.width;
+    }
+    get height() {
+        return this.size.height;
+    }
+    constructor(size = new Size(80, 24)) {
+        this.size = size;
+        this.grid = new Grid(size);
+    }
+    setCursorPosition(position) {
+        this.cursorPosition = position;
+    }
+    clearCursorPosition() {
+        this.cursorPosition = null;
+    }
+    setCell(position, cell) {
+        this.grid.updateCell(position, cell);
+    }
+    getCell(position) {
+        return this.grid.getCell(position);
+    }
+    flush(backend) {
+        backend.renderFrame(this.grid, this.cursorPosition);
+    }
+    clear() {
+        this.grid.fill(" ", DEFAULT_COLOR, DEFAULT_COLOR, StyleFlags.None);
+        this.cursorPosition = null;
+    }
+    /**
+     * Семантика {@link clear} в границах rect'а — очистка damage-области перед
+     * частичным проходом отрисовки. Курсор НЕ трогает: им управляет кадр
+     * (renderFrame гасит позицию, только если она попала в damage).
+     */
+    clearRect(rect) {
+        this.grid.clearRect(rect);
+    }
+    /** См. {@link Grid.snapToWideChars} — границы области не рассекают wide-пары. */
+    snapToWideChars(rect) {
+        return this.grid.snapToWideChars(rect);
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@tuidom/core",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "Experimental terminal UI DOM — core: element tree, flex layout, grid rendering, input parsing. API is unstable.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/tuidom/tuidom.git",
+        "directory": "packages/core"
+    },
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "keywords": [
+        "tui",
+        "terminal",
+        "ui",
+        "dom"
+    ],
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        "./package.json": "./package.json",
+        "./*.js": "./dist/*.js",
+        "./*": "./dist/*.js"
+    }
+}