@tuidom/testing 0.1.0

package/dist/FakeTerminalSurface.d.ts

@@ -0,0 +1,71 @@
+import type { IDisposable } from "@tuidom/core/common/disposable";
+import type { ITerminalSurface, TerminalCell, TerminalMouseEventData } from "@tuidom/core/common/iTerminalSurface";
+export interface FakeCellOptions {
+    fg?: number;
+    bg?: number;
+    style?: number;
+    width?: number;
+}
+/**
+ * Скриптованная реализация {@link ITerminalSurface} для тестов `TerminalViewElement`.
+ * Сетку задаём построчно (`setGrid`) или поячеечно (`setCell` — для цветов/стилей/wide-char),
+ * курсор — `setCursor`, флаг выхода — `isExited`. Все обращения виджета наружу
+ * (`write`/`sendMouse`/`resize`) пишутся в публичные массивы для ассертов, а `onUpdate`/
+ * `onExit` дёргаются вручную через `emitUpdate`/`emitExit`.
+ *
+ * Прокрутка смоделирована состоянием, а не историей: `scrollbackLines` задаёт потолок
+ * для `scrollLines`, а `scrollOffset` можно проверять напрямую. Сетка — это всегда
+ * вьюпорт как он есть, смещение её не двигает (настоящий сдвиг строк проверяется на
+ * `EmbeddedTerminalSession`).
+ */
+export declare class FakeTerminalSurface implements ITerminalSurface, IDisposable {
+    private grid;
+    private cursor;
+    private readonly updateListeners;
+    private readonly exitListeners;
+    isExited: boolean;
+    /** Включила ли «программа в шелле» mouse-tracking — от этого зависит судьба колеса. */
+    mouseEventsActive: boolean;
+    /** Сколько строк истории лежит выше вьюпорта: потолок для `scrollLines`. */
+    scrollbackLines: number;
+    scrollOffset: number;
+    /** Стал ли фейк «убитым» — контроллер обязан звать dispose() при закрытии терминала. */
+    disposed: boolean;
+    readonly writes: string[];
+    readonly mouseEvents: TerminalMouseEventData[];
+    readonly resizes: {
+        cols: number;
+        rows: number;
+    }[];
+    /** Заполнить сетку строками текста (каждый символ — обычная ячейка ширины 1). */
+    setGrid(lines: string[]): void;
+    /**
+     * Задать одну ячейку — здесь навешиваем цвета/стиль/ширину. При `width === 2`
+     * правый сосед (`x + 1`) помечается как continuation (readCell вернёт там false).
+     */
+    setCell(x: number, y: number, char: string, options?: FakeCellOptions): void;
+    setCursor(cursor: {
+        x: number;
+        y: number;
+    } | null): void;
+    /** Дёрнуть подписчиков onUpdate (эмуляция «пришли новые данные из шелла»). */
+    emitUpdate(): void;
+    /** Дёрнуть подписчиков onExit (эмуляция выхода шелла). */
+    emitExit(exitCode: number): void;
+    readCell(x: number, y: number, out: TerminalCell): boolean;
+    getCursor(): {
+        x: number;
+        y: number;
+    } | null;
+    write(data: string): void;
+    /** Прокрутка вьюпорта: `delta < 0` — вверх, в историю; клампится в [0, scrollbackLines]. */
+    scrollLines(delta: number): void;
+    sendMouse(event: TerminalMouseEventData): void;
+    resize(cols: number, rows: number): void;
+    onUpdate(cb: () => void): IDisposable;
+    onExit(cb: (exitCode: number) => void): IDisposable;
+    /** Помечает фейк убитым (в реале — kill PTY + dispose эмулятора). */
+    dispose(): void;
+    private setScrollOffset;
+    private ensureRow;
+}

package/dist/FakeTerminalSurface.js

@@ -0,0 +1,122 @@
+import { DEFAULT_COLOR } from "@tuidom/core/common/colorUtils";
+/**
+ * Скриптованная реализация {@link ITerminalSurface} для тестов `TerminalViewElement`.
+ * Сетку задаём построчно (`setGrid`) или поячеечно (`setCell` — для цветов/стилей/wide-char),
+ * курсор — `setCursor`, флаг выхода — `isExited`. Все обращения виджета наружу
+ * (`write`/`sendMouse`/`resize`) пишутся в публичные массивы для ассертов, а `onUpdate`/
+ * `onExit` дёргаются вручную через `emitUpdate`/`emitExit`.
+ *
+ * Прокрутка смоделирована состоянием, а не историей: `scrollbackLines` задаёт потолок
+ * для `scrollLines`, а `scrollOffset` можно проверять напрямую. Сетка — это всегда
+ * вьюпорт как он есть, смещение её не двигает (настоящий сдвиг строк проверяется на
+ * `EmbeddedTerminalSession`).
+ */
+export class FakeTerminalSurface {
+    grid = [];
+    cursor = null;
+    updateListeners = new Set();
+    exitListeners = new Set();
+    isExited = false;
+    /** Включила ли «программа в шелле» mouse-tracking — от этого зависит судьба колеса. */
+    mouseEventsActive = false;
+    /** Сколько строк истории лежит выше вьюпорта: потолок для `scrollLines`. */
+    scrollbackLines = 0;
+    scrollOffset = 0;
+    /** Стал ли фейк «убитым» — контроллер обязан звать dispose() при закрытии терминала. */
+    disposed = false;
+    // Записи обращений виджета — для ассертов.
+    writes = [];
+    mouseEvents = [];
+    resizes = [];
+    /** Заполнить сетку строками текста (каждый символ — обычная ячейка ширины 1). */
+    setGrid(lines) {
+        this.grid = lines.map((line) => Array.from(line, (char) => makeCell(char)));
+    }
+    /**
+     * Задать одну ячейку — здесь навешиваем цвета/стиль/ширину. При `width === 2`
+     * правый сосед (`x + 1`) помечается как continuation (readCell вернёт там false).
+     */
+    setCell(x, y, char, options = {}) {
+        const row = this.ensureRow(y);
+        const width = options.width ?? 1;
+        row[x] = {
+            char,
+            fg: options.fg ?? DEFAULT_COLOR,
+            bg: options.bg ?? DEFAULT_COLOR,
+            style: options.style ?? 0,
+            width,
+        };
+        if (width === 2)
+            row[x + 1] = "continuation";
+    }
+    setCursor(cursor) {
+        this.cursor = cursor;
+    }
+    /** Дёрнуть подписчиков onUpdate (эмуляция «пришли новые данные из шелла»). */
+    emitUpdate() {
+        for (const cb of this.updateListeners)
+            cb();
+    }
+    /** Дёрнуть подписчиков onExit (эмуляция выхода шелла). */
+    emitExit(exitCode) {
+        this.isExited = true;
+        for (const cb of this.exitListeners)
+            cb(exitCode);
+    }
+    // ─── ITerminalSurface ───
+    readCell(x, y, out) {
+        const slot = this.grid[y]?.[x];
+        if (slot === undefined || slot === "continuation")
+            return false;
+        out.char = slot.char;
+        out.fg = slot.fg;
+        out.bg = slot.bg;
+        out.style = slot.style;
+        out.width = slot.width;
+        return true;
+    }
+    getCursor() {
+        return this.scrollOffset > 0 ? null : this.cursor; // в скролбэке курсор прячем
+    }
+    write(data) {
+        this.writes.push(data);
+        this.setScrollOffset(0); // как настоящая поверхность: ввод возвращает на дно
+    }
+    /** Прокрутка вьюпорта: `delta < 0` — вверх, в историю; клампится в [0, scrollbackLines]. */
+    scrollLines(delta) {
+        this.setScrollOffset(this.scrollOffset - delta);
+    }
+    sendMouse(event) {
+        this.mouseEvents.push(event);
+    }
+    resize(cols, rows) {
+        this.resizes.push({ cols, rows });
+    }
+    onUpdate(cb) {
+        this.updateListeners.add(cb);
+        return { dispose: () => this.updateListeners.delete(cb) };
+    }
+    onExit(cb) {
+        this.exitListeners.add(cb);
+        return { dispose: () => this.exitListeners.delete(cb) };
+    }
+    /** Помечает фейк убитым (в реале — kill PTY + dispose эмулятора). */
+    dispose() {
+        this.disposed = true;
+    }
+    setScrollOffset(value) {
+        const next = Math.max(0, Math.min(value, this.scrollbackLines));
+        if (next === this.scrollOffset)
+            return;
+        this.scrollOffset = next;
+        this.emitUpdate();
+    }
+    ensureRow(y) {
+        while (this.grid.length <= y)
+            this.grid.push([]);
+        return this.grid[y];
+    }
+}
+function makeCell(char) {
+    return { char, fg: DEFAULT_COLOR, bg: DEFAULT_COLOR, style: 0, width: 1 };
+}

package/dist/TestApp.d.ts

@@ -0,0 +1,21 @@
+import { Size } from "@tuidom/core/common/geometryPromitives";
+import { TuiApplication } from "@tuidom/core/dom/tuiApplication";
+import type { TUIElement } from "@tuidom/core/dom/tuiElement";
+import { BodyElement } from "@tuidom/elements/body/bodyElement";
+import { MockTerminalBackend } from "./mockTerminalBackend.js";
+export declare class TestApp {
+    readonly backend: MockTerminalBackend;
+    readonly app: TuiApplication;
+    private constructor();
+    static create(root: BodyElement, size?: Size, styleVars?: Readonly<Record<string, number>> | null): TestApp;
+    static createWithContent(content: TUIElement, size?: Size, styleVars?: Readonly<Record<string, number>> | null): TestApp;
+    /** Корень как BodyElement: TuiApplication хранит рут широким типом (ядро
+     * tuidom не знает о виджетах), тестовый харнесс — конкретным. */
+    private readonly bodyRoot;
+    get root(): BodyElement;
+    get focusedElement(): TUIElement | null;
+    sendKey(name: string): void;
+    querySelector(selector: string): TUIElement | null;
+    querySelectorAll(selector: string): TUIElement[];
+    render(): void;
+}

package/dist/TestApp.js

@@ -0,0 +1,58 @@
+import { Size } from "@tuidom/core/common/geometryPromitives";
+import { TuiApplication } from "@tuidom/core/dom/tuiApplication";
+import { BodyElement } from "@tuidom/elements/body/bodyElement";
+import { DARK_PLUS_STYLE_VARS } from "./darkPlusStyleVars.js";
+import { MockTerminalBackend } from "./mockTerminalBackend.js";
+export class TestApp {
+    backend;
+    app;
+    constructor(backend, root, styleVars) {
+        this.backend = backend;
+        this.app = new TuiApplication(backend);
+        this.app.root = root;
+        this.bodyRoot = root;
+        // Корень получает палитру var-scope до первого кадра — компоненты в
+        // тестах резолвят токены в конкретные цвета. Дефолт — снапшот Dark+
+        // (паритет с приложением vexx); хост может подложить свою палитру.
+        if (styleVars !== null) {
+            root.setStyleVars(styleVars);
+        }
+        // Каждый кадр в тестах верифицирует инварианты дерева (симметрия parent,
+        // укоренённость) — молчаливые полуприкреплённые состояния падают сразу.
+        this.app.validateTreeAfterRender = true;
+        this.app.run();
+    }
+    static create(root, size = new Size(80, 24), styleVars = DARK_PLUS_STYLE_VARS) {
+        return new TestApp(new MockTerminalBackend(size), root, styleVars);
+    }
+    static createWithContent(content, size = new Size(80, 24), styleVars = DARK_PLUS_STYLE_VARS) {
+        const body = new BodyElement();
+        body.setContent(content);
+        return new TestApp(new MockTerminalBackend(size), body, styleVars);
+    }
+    /** Корень как BodyElement: TuiApplication хранит рут широким типом (ядро
+     * tuidom не знает о виджетах), тестовый харнесс — конкретным. */
+    bodyRoot;
+    get root() {
+        return this.bodyRoot;
+    }
+    get focusedElement() {
+        return this.app.focusManager?.activeElement ?? null;
+    }
+    sendKey(name) {
+        this.backend.sendKey(name);
+    }
+    querySelector(selector) {
+        return this.root.querySelector(selector);
+    }
+    querySelectorAll(selector) {
+        return this.root.querySelectorAll(selector);
+    }
+    render() {
+        // Force a synchronous render (app.run already did the initial one,
+        // and handleInput renders after each key, but this is useful
+        // if the test mutates state without going through input).
+        // @ts-expect-error Just for testing purposes, we want to bypass the normal async render scheduling
+        this.app.renderFrame();
+    }
+}

package/dist/darkPlusStyleVars.d.ts

@@ -0,0 +1 @@
+export declare const DARK_PLUS_STYLE_VARS: Readonly<Record<string, number>>;

package/dist/darkPlusStyleVars.js

@@ -0,0 +1,128 @@
+// Снапшот палитры Dark+ (vexx), выгруженный данными: тест-харнесс tuidom
+// резолвит токены в те же цвета, что видит приложение vexx, не завися от
+// его кода темы. Регенерация (из репозитория vexx):
+//   npx tsx <scratchpad>/gen-dark-plus-vars.ts > tuidom/testing/darkPlusStyleVars.ts
+// где скрипт печатает computeThemeVars(WorkbenchTheme.fromThemeFile(darkPlusTheme)).
+export const DARK_PLUS_STYLE_VARS = {
+    "actionBar.toggledBackground": 0x383a49,
+    "activityBarBadge.background": 0x007acc,
+    "agentsChatInput.border": 0x303031,
+    "agentsChatInput.focusBorder": 0x007acc,
+    "agentsNewSessionButton.border": 0x303031,
+    "agentsPanel.border": 0x303031,
+    "button.background": 0x0078d7,
+    "button.foreground": 0xffffff,
+    "button.hoverBackground": 0x1a86e0,
+    "button.secondaryBackground": 0x3c3c3c,
+    "button.secondaryForeground": 0xcccccc,
+    "button.secondaryHoverBackground": 0x45494e,
+    "checkbox.border": 0x6b6b6b,
+    descriptionForeground: 0xababab,
+    "diffEditor.diagonalFill": 0x414141,
+    "diffEditor.insertedLineBackground": 0x373d29,
+    "diffEditor.insertedTextBackground": 0x374121,
+    "diffEditor.removedLineBackground": 0x4b1818,
+    "diffEditor.removedTextBackground": 0x4b1818,
+    "diffEditor.unchangedRegionForeground": 0x8c8c8c,
+    "dropdown.background": 0x3c3c3c,
+    "dropdown.border": 0x3c3c3c,
+    "dropdown.foreground": 0xf0f0f0,
+    "dropdown.listBackground": 0x1f1f1f,
+    "editor.background": 0x1e1e1e,
+    "editor.foreground": 0xd4d4d4,
+    "editor.inactiveSelectionBackground": 0x3a3d41,
+    "editor.selectionHighlightBackground": 0xadd6ff,
+    "editor.wordHighlightBackground": 0x474747,
+    "editorCursor.foreground": 0xaeafad,
+    "editorError.foreground": 0xf14c4c,
+    "editorGroupHeader.tabsBackground": 0x252526,
+    "editorGutter.addedBackground": 0x487e02,
+    "editorGutter.deletedBackground": 0xf14c4c,
+    "editorGutter.foldingControlForeground": 0xc5c5c5,
+    "editorGutter.modifiedBackground": 0x1b81a8,
+    "editorHint.foreground": 0xeeeeee,
+    "editorIndentGuide.activeBackground1": 0x707070,
+    "editorIndentGuide.background1": 0x404040,
+    "editorInfo.foreground": 0x3794ff,
+    "editorLineNumber.activeForeground": 0xc6c6c6,
+    "editorLineNumber.foreground": 0x858585,
+    "editorWarning.foreground": 0xcca700,
+    "editorWidget.background": 0x252526,
+    "editorWidget.border": 0x454545,
+    "editorWidget.foreground": 0xcccccc,
+    focusBorder: 0x007fd4,
+    foreground: 0xcccccc,
+    "gitDecoration.addedResourceForeground": 0x81b88b,
+    "gitDecoration.conflictingResourceForeground": 0xe4676b,
+    "gitDecoration.deletedResourceForeground": 0xc74e39,
+    "gitDecoration.ignoredResourceForeground": 0x8c8c8c,
+    "gitDecoration.modifiedResourceForeground": 0xe2c08d,
+    "gitDecoration.renamedResourceForeground": 0x73c991,
+    "gitDecoration.submoduleResourceForeground": 0x8db9e2,
+    "gitDecoration.untrackedResourceForeground": 0x73c991,
+    "input.background": 0x3c3c3c,
+    "input.border": 0x3c3c3c,
+    "input.foreground": 0xcccccc,
+    "input.placeholderForeground": 0xa6a6a6,
+    "input.selectionBackground": 0x264f78,
+    "list.activeSelectionBackground": 0x04395e,
+    "list.activeSelectionForeground": 0xffffff,
+    "list.activeSelectionIconForeground": 0xffffff,
+    "list.deemphasizedForeground": 0x808080,
+    "list.dropBackground": 0x383b3d,
+    "list.highlightForeground": 0x64c8ff,
+    "list.hoverBackground": 0x2a2d2e,
+    "list.inactiveSelectionBackground": 0x37373d,
+    "list.inactiveSelectionForeground": 0xcccccc,
+    "menu.background": 0x252526,
+    "menu.border": 0x454545,
+    "menu.foreground": 0xcccccc,
+    "menu.selectionBackground": 0x0078d4,
+    "menu.selectionForeground": 0xffffff,
+    "menu.separatorBackground": 0x454545,
+    "menubar.selectionBackground": 0x005ab4,
+    "menubar.selectionForeground": 0xffffff,
+    "panel.background": 0x181818,
+    "panel.border": 0x2b2b2b,
+    "panelTitle.activeBorder": 0xe7e7e7,
+    "panelTitle.activeForeground": 0xe7e7e7,
+    "panelTitle.inactiveForeground": 0x8e8e8e,
+    "ports.iconRunningProcessForeground": 0x369432,
+    "quickInput.background": 0x252526,
+    "quickInput.foreground": 0xcccccc,
+    "sash.hoverBorder": 0x007fd4,
+    "scmGraph.foreground1": 0xffb000,
+    "scmGraph.foreground2": 0xdc267f,
+    "scmGraph.foreground3": 0x994f00,
+    "scmGraph.foreground4": 0x40b0a6,
+    "scmGraph.foreground5": 0xb66dff,
+    "scmGraph.historyItemBaseRefColor": 0xea5c00,
+    "scmGraph.historyItemRefColor": 0x3794ff,
+    "scmGraph.historyItemRemoteRefColor": 0xb180d7,
+    "scrollbar.background": 0x3a3d3e,
+    "scrollbarSlider.background": 0x797979,
+    "sideBar.background": 0x252526,
+    "sideBar.foreground": 0xcccccc,
+    "sideBarSectionHeader.background": 0x000000,
+    "sideBarSectionHeader.border": 0xcccccc,
+    "sideBarTitle.foreground": 0xbbbbbb,
+    "statusBar.background": 0x007acc,
+    "statusBar.foreground": 0xffffff,
+    "statusBarItem.hoverBackground": 0x1e92d2,
+    "statusBarItem.hoverForeground": 0xffffff,
+    "statusBarItem.remoteBackground": 0x16825d,
+    "statusBarItem.remoteForeground": 0xffffff,
+    "tab.activeBackground": 0x1e1e1e,
+    "tab.activeForeground": 0xffffff,
+    "tab.inactiveBackground": 0x2d2d2d,
+    "tab.inactiveForeground": 0xffffff,
+    "tab.lastPinnedBorder": 0xcccccc,
+    "tab.selectedBackground": 0x222222,
+    "tab.selectedForeground": 0xffffff,
+    "terminal.background": 0x181818,
+    "terminal.foreground": 0xcccccc,
+    "terminal.inactiveSelectionBackground": 0x3a3d41,
+    "textLink.foreground": 0x3794ff,
+    "toolbar.hoverBackground": 0x5a5d5e,
+    "widget.border": 0x303031,
+};

package/dist/expectScreen.d.ts

@@ -0,0 +1,25 @@
+import type { MockTerminalBackend } from "./mockTerminalBackend.js";
+/**
+ * Tagged template literal that strips leading/trailing blank lines
+ * and removes common indentation (dedent). Produces a clean multi-line
+ * string for visual screen assertions.
+ *
+ * Usage:
+ *   screen`
+ *     +----+
+ *     |    |
+ *     +----+
+ *   `
+ */
+export declare function screen(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Assert that the backend's current screen matches the expected output.
+ *
+ * Usage:
+ *   expectScreen(backend, screen`
+ *     +----+
+ *     |    |
+ *     +----+
+ *   `);
+ */
+export declare function expectScreen(backend: MockTerminalBackend, expected: string): void;

package/dist/expectScreen.js

@@ -0,0 +1,64 @@
+import { expect } from "vitest";
+/**
+ * Tagged template literal that strips leading/trailing blank lines
+ * and removes common indentation (dedent). Produces a clean multi-line
+ * string for visual screen assertions.
+ *
+ * Usage:
+ *   screen`
+ *     +----+
+ *     |    |
+ *     +----+
+ *   `
+ */
+export function screen(strings, ...values) {
+    // Reconstruct the full string from template parts
+    let raw = strings[0];
+    for (let i = 0; i < values.length; i++) {
+        raw += String(values[i]) + strings[i + 1];
+    }
+    // Split into lines, remove first and last blank lines
+    let lines = raw.split("\n");
+    if (lines.length > 0 && lines[0].trim() === "") {
+        lines.shift();
+    }
+    if (lines.length > 0 && lines[lines.length - 1].trim() === "") {
+        lines.pop();
+    }
+    // Find minimum indentation (ignore empty lines)
+    const nonEmptyLines = lines.filter((l) => l.trim().length > 0);
+    const minIndent = nonEmptyLines.length > 0
+        ? /* v8 ignore next -- /^(\s*)/ always matches, so exec never returns null; the ?? 0 fallback is unreachable */
+            Math.min(...nonEmptyLines.map((l) => /^(\s*)/.exec(l)?.[1].length ?? 0))
+        : 0;
+    // Strip common indent and trailing whitespace per line
+    lines = lines.map((l) => l.slice(minIndent).trimEnd());
+    return lines.join("\n");
+}
+/**
+ * Normalize backend screen output: trim trailing spaces per line,
+ * then trim trailing empty lines. Returns a compact string that
+ * can be compared to `screen` tagged template output.
+ */
+function normalizeScreen(raw) {
+    const lines = raw.split("\n").map((l) => l.trimEnd());
+    // Remove trailing empty lines
+    while (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines.join("\n");
+}
+/**
+ * Assert that the backend's current screen matches the expected output.
+ *
+ * Usage:
+ *   expectScreen(backend, screen`
+ *     +----+
+ *     |    |
+ *     +----+
+ *   `);
+ */
+export function expectScreen(backend, expected) {
+    const actual = normalizeScreen(backend.screenToString());
+    expect(actual).toBe(expected);
+}

package/dist/mockTerminalBackend.d.ts

@@ -0,0 +1,97 @@
+import type { ITerminalBackend } from "@tuidom/core/backend/iTerminalBackend";
+import { Point, Size } from "@tuidom/core/common/geometryPromitives";
+import type { KeyPressEvent } from "@tuidom/core/input/keyEvent";
+import type { MouseToken } from "@tuidom/core/input/rawTerminalToken";
+import type { Grid } from "@tuidom/core/rendering/grid";
+/**
+ * In-memory terminal backend for testing.
+ *
+ * Provides two ways to simulate input:
+ * - `sendKey('a')`, `sendKey('Ctrl+C')` — human-readable DSL
+ * - `sendRaw('\x1b[A')` — raw escape sequences for edge cases
+ *
+ * Stores screen state in a 2D grid for assertions via getTextAt() / screenToString().
+ */
+export declare class MockTerminalBackend implements ITerminalBackend {
+    private inputCallbacks;
+    private mouseCallbacks;
+    private pasteCallbacks;
+    private resizeCallbacks;
+    private oscResponseCallbacks;
+    private keyboardProbeCallbacks;
+    private cells;
+    private bgs;
+    private fgs;
+    size: Size;
+    private readonly inputParser;
+    constructor(size?: Size);
+    private createEmptyGrid;
+    private createBgGrid;
+    onInput(callback: (event: KeyPressEvent) => void): void;
+    onMouse(callback: (event: MouseToken) => void): void;
+    onPaste(callback: (text: string) => void): void;
+    onResize(callback: (size: Size) => void): void;
+    onOscResponse(callback: (code: number, data: string) => void): void;
+    probeKeyboardProtocol(onResult: (supported: boolean) => void): void;
+    cursorPosition: Point;
+    renderFrame(grid: Grid, cursorPosition: Point): void;
+    getSize(): Size;
+    setup(): void;
+    teardown(): void;
+    /** Set a character directly in the screen grid (test helper, not part of ITerminalBackend) */
+    setCellAt(position: Point, char: string): void;
+    /**
+     * Simulate a key press using human-readable name.
+     * Examples: sendKey('a'), sendKey('Enter'), sendKey('Ctrl+C')
+     */
+    sendKey(name: string): void;
+    /**
+     * Force-deliver any partial sequence still buffered in the parser (test analogue of
+     * NodeTerminalBackend's flush timeout). Call after sending split raw chunks if the
+     * final piece left a dangling tail.
+     */
+    flushInput(): void;
+    /**
+     * Simulate a bracketed paste: wrap `text` in the ESC[200~ … ESC[201~ markers the
+     * terminal emits and feed it through the parser, so the whole block is delivered to
+     * paste subscribers as one string.
+     */
+    sendPaste(text: string): void;
+    private emitStreams;
+    /**
+     * Simulate a mouse event using a MouseToken object.
+     */
+    simulateMouse(token: MouseToken): void;
+    /**
+     * Simulate an OSC response from the terminal (test helper).
+     */
+    simulateOscResponse(code: number, data: string): void;
+    /**
+     * Resolve a pending keyboard-protocol probe (test helper) — simulates the terminal
+     * answering (or not) the Kitty keyboard-protocol query.
+     */
+    resolveKeyboardProtocol(supported: boolean): void;
+    /**
+     * Simulate raw terminal input (escape sequences etc.)
+     * Example: sendRaw('\x1b[A') for arrow up
+     */
+    sendRaw(data: string): void;
+    /**
+     * Read a horizontal run of characters from the screen grid.
+     */
+    getTextAt(position: Point, length: number): string;
+    /**
+     * Render the entire screen as plain text (rows joined by \n).
+     * Useful for snapshot testing.
+     */
+    screenToString(): string;
+    /** Clear the screen grid back to empty */
+    clearScreen(): void;
+    /**
+     * Simulate a terminal resize.
+     * Updates dimensions, recreates the grid, and notifies all resize callbacks.
+     */
+    getBgAt(position: Point): number;
+    getFgAt(position: Point): number;
+    resize(size: Size): void;
+}

package/dist/mockTerminalBackend.js

@@ -0,0 +1,229 @@
+import { DEFAULT_COLOR } from "@tuidom/core/common/colorUtils";
+import { Point, Size } from "@tuidom/core/common/geometryPromitives";
+import { KeyInputParser } from "@tuidom/core/input/keyInputParser";
+import { serializeKey } from "@tuidom/core/input/serializeKey";
+/**
+ * In-memory terminal backend for testing.
+ *
+ * Provides two ways to simulate input:
+ * - `sendKey('a')`, `sendKey('Ctrl+C')` — human-readable DSL
+ * - `sendRaw('\x1b[A')` — raw escape sequences for edge cases
+ *
+ * Stores screen state in a 2D grid for assertions via getTextAt() / screenToString().
+ */
+export class MockTerminalBackend {
+    inputCallbacks = [];
+    mouseCallbacks = [];
+    pasteCallbacks = [];
+    resizeCallbacks = [];
+    oscResponseCallbacks = [];
+    keyboardProbeCallbacks = [];
+    cells;
+    bgs;
+    fgs;
+    size;
+    inputParser = new KeyInputParser();
+    constructor(size = new Size(80, 24)) {
+        this.size = size;
+        this.cells = this.createEmptyGrid();
+        this.bgs = this.createBgGrid();
+        this.fgs = this.createBgGrid();
+    }
+    createEmptyGrid() {
+        const value = null;
+        return new Array(this.size.height)
+            .fill([])
+            .map(() => new Array(this.size.width).fill(value));
+    }
+    createBgGrid() {
+        return new Array(this.size.height)
+            .fill([])
+            .map(() => new Array(this.size.width).fill(DEFAULT_COLOR));
+    }
+    onInput(callback) {
+        this.inputCallbacks.push(callback);
+    }
+    onMouse(callback) {
+        this.mouseCallbacks.push(callback);
+    }
+    onPaste(callback) {
+        this.pasteCallbacks.push(callback);
+    }
+    onResize(callback) {
+        this.resizeCallbacks.push(callback);
+    }
+    onOscResponse(callback) {
+        this.oscResponseCallbacks.push(callback);
+    }
+    probeKeyboardProtocol(onResult) {
+        this.keyboardProbeCallbacks.push(onResult);
+    }
+    cursorPosition = new Point(0, 0);
+    renderFrame(grid, cursorPosition) {
+        for (let y = 0; y < grid.height && y < this.size.height; y++) {
+            for (let x = 0; x < grid.width && x < this.size.width; x++) {
+                const cell = grid.getCellAt(x, y);
+                this.cells[y][x] = cell.char;
+                this.bgs[y][x] = cell.bg;
+                this.fgs[y][x] = cell.fg;
+            }
+        }
+        this.cursorPosition = cursorPosition;
+    }
+    getSize() {
+        return this.size;
+    }
+    setup() {
+        // No-op for mock
+    }
+    teardown() {
+        // No-op for mock
+    }
+    // ─── Test helpers ───
+    /** Set a character directly in the screen grid (test helper, not part of ITerminalBackend) */
+    setCellAt(position, char) {
+        if (position.y >= 0 && position.y < this.size.height && position.x >= 0 && position.x < this.size.width) {
+            this.cells[position.y][position.x] = char;
+        }
+    }
+    /**
+     * Simulate a key press using human-readable name.
+     * Examples: sendKey('a'), sendKey('Enter'), sendKey('Ctrl+C')
+     */
+    sendKey(name) {
+        const raw = serializeKey(name);
+        this.emitStreams(this.inputParser.parseWithMouse(raw));
+        // serializeKey always produces a complete sequence, so deliver immediately —
+        // a lone ESC ("Escape") would otherwise sit buffered awaiting a continuation.
+        this.flushInput();
+    }
+    /**
+     * Force-deliver any partial sequence still buffered in the parser (test analogue of
+     * NodeTerminalBackend's flush timeout). Call after sending split raw chunks if the
+     * final piece left a dangling tail.
+     */
+    flushInput() {
+        if (this.inputParser.hasPending()) {
+            this.emitStreams(this.inputParser.flush());
+        }
+    }
+    /**
+     * Simulate a bracketed paste: wrap `text` in the ESC[200~ … ESC[201~ markers the
+     * terminal emits and feed it through the parser, so the whole block is delivered to
+     * paste subscribers as one string.
+     */
+    sendPaste(text) {
+        this.sendRaw(`\x1b[200~${text}\x1b[201~`);
+    }
+    emitStreams(streams) {
+        for (const event of streams.keys) {
+            for (const cb of this.inputCallbacks) {
+                cb(event);
+            }
+        }
+        for (const text of streams.paste) {
+            for (const cb of this.pasteCallbacks) {
+                cb(text);
+            }
+        }
+    }
+    /**
+     * Simulate a mouse event using a MouseToken object.
+     */
+    simulateMouse(token) {
+        for (const cb of this.mouseCallbacks) {
+            cb(token);
+        }
+    }
+    /**
+     * Simulate an OSC response from the terminal (test helper).
+     */
+    simulateOscResponse(code, data) {
+        for (const cb of this.oscResponseCallbacks) {
+            cb(code, data);
+        }
+    }
+    /**
+     * Resolve a pending keyboard-protocol probe (test helper) — simulates the terminal
+     * answering (or not) the Kitty keyboard-protocol query.
+     */
+    resolveKeyboardProtocol(supported) {
+        const callbacks = this.keyboardProbeCallbacks;
+        this.keyboardProbeCallbacks = [];
+        for (const cb of callbacks) {
+            cb(supported);
+        }
+    }
+    /**
+     * Simulate raw terminal input (escape sequences etc.)
+     * Example: sendRaw('\x1b[A') for arrow up
+     */
+    sendRaw(data) {
+        // No implicit flush: callers may deliberately send a partial sequence to
+        // simulate stdin packetization (use flushInput() to drain a leftover tail).
+        this.emitStreams(this.inputParser.parseWithMouse(data));
+    }
+    // ─── Screen assertions ───
+    /**
+     * Read a horizontal run of characters from the screen grid.
+     */
+    getTextAt(position, length) {
+        let result = "";
+        for (let i = 0; i < length; i++) {
+            const cell = position.y >= 0 &&
+                position.y < this.size.height &&
+                position.x + i >= 0 &&
+                position.x + i < this.size.width
+                ? this.cells[position.y][position.x + i]
+                : null;
+            result += cell ?? " ";
+        }
+        return result;
+    }
+    /**
+     * Render the entire screen as plain text (rows joined by \n).
+     * Useful for snapshot testing.
+     */
+    screenToString() {
+        const lines = [];
+        for (let y = 0; y < this.size.height; y++) {
+            let line = "";
+            for (let x = 0; x < this.size.width; x++) {
+                line += this.cells[y][x] ?? " ";
+            }
+            lines.push(line);
+        }
+        return lines.join("\n");
+    }
+    /** Clear the screen grid back to empty */
+    clearScreen() {
+        this.cells = this.createEmptyGrid();
+        this.bgs = this.createBgGrid();
+        this.fgs = this.createBgGrid();
+    }
+    /**
+     * Simulate a terminal resize.
+     * Updates dimensions, recreates the grid, and notifies all resize callbacks.
+     */
+    getBgAt(position) {
+        if (position.y >= 0 && position.y < this.size.height && position.x >= 0 && position.x < this.size.width) {
+            return this.bgs[position.y][position.x];
+        }
+        return DEFAULT_COLOR;
+    }
+    getFgAt(position) {
+        if (position.y >= 0 && position.y < this.size.height && position.x >= 0 && position.x < this.size.width) {
+            return this.fgs[position.y][position.x];
+        }
+        return DEFAULT_COLOR;
+    }
+    resize(size) {
+        this.size = size;
+        this.cells = this.createEmptyGrid();
+        this.bgs = this.createBgGrid();
+        this.fgs = this.createBgGrid();
+        for (const cb of this.resizeCallbacks) {
+            cb(size);
+        }
+    }
+}

package/dist/perfFixtures.d.ts

@@ -0,0 +1,38 @@
+import type { ITreeDataProvider } from "@tuidom/elements/tree/iTreeDataProvider";
+/** Создаёт уникальную временную директорию под os.tmpdir(). */
+export declare function createTempDir(prefix?: string): string;
+/** Рекурсивно удаляет директорию (для afterAll/afterEach). */
+export declare function cleanupDir(dirPath: string): void;
+export interface GenerateFileTreeOptions {
+    /** Сколько файлов всего сгенерировать. */
+    files: number;
+    /** Сколько файлов кладём в каждую директорию (default 50). */
+    filesPerDir?: number;
+    /** Сколько разных директорий на каждом уровне вложенности (default 8). */
+    breadth?: number;
+    /** Максимальная глубина вложенности директорий (default 4). */
+    maxDepth?: number;
+}
+/**
+ * Генерирует вложенное дерево пустых файлов под `root`.
+ *
+ * Файлы раскидываются по директориям разной глубины, чтобы фикстура была
+ * похожа на реальный репозиторий (а не плоский список). Возвращает фактическое
+ * число записанных файлов.
+ */
+export declare function generateFileTree(root: string, options: GenerateFileTreeOptions): number;
+export interface PerfTreeNode {
+    id: string;
+    label: string;
+    children?: PerfTreeNode[];
+}
+/**
+ * Строит вложенное in-memory дерево примерно из `targetCount` узлов с заданным
+ * ветвлением `fanout`. Без обращений к файловой системе — чтобы бенчмарки
+ * виджета мерили стоимость flatten/сканов, а не диск.
+ */
+export declare function buildInMemoryTree(targetCount: number, fanout?: number): PerfTreeNode[];
+/** ITreeDataProvider поверх in-memory дерева PerfTreeNode. */
+export declare function makeInMemoryTreeProvider(roots: PerfTreeNode[]): ITreeDataProvider<PerfTreeNode>;
+/** Собирает все collapsible-узлы дерева (для массового раскрытия в бенче). */
+export declare function collectCollapsibleNodes(roots: PerfTreeNode[]): PerfTreeNode[];

package/dist/perfFixtures.js

@@ -0,0 +1,97 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+// ─── Файловые фикстуры ──────────────────────────────────────────────────────
+/** Создаёт уникальную временную директорию под os.tmpdir(). */
+export function createTempDir(prefix = "vexx-perf-") {
+    return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+/** Рекурсивно удаляет директорию (для afterAll/afterEach). */
+export function cleanupDir(dirPath) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+}
+/**
+ * Генерирует вложенное дерево пустых файлов под `root`.
+ *
+ * Файлы раскидываются по директориям разной глубины, чтобы фикстура была
+ * похожа на реальный репозиторий (а не плоский список). Возвращает фактическое
+ * число записанных файлов.
+ */
+export function generateFileTree(root, options) {
+    const { files, filesPerDir = 50, breadth = 8, maxDepth = 4 } = options;
+    let written = 0;
+    let dirIndex = 0;
+    while (written < files) {
+        // Псевдослучайная (детерминированная) вложенность для разнообразия.
+        const depth = (dirIndex % maxDepth) + 1;
+        const segments = [];
+        for (let level = 0; level < depth; level++) {
+            const bucket = Math.floor(dirIndex / breadth ** level) % breadth;
+            segments.push(`dir${level}_${bucket}`);
+        }
+        const dirAbs = path.join(root, ...segments);
+        fs.mkdirSync(dirAbs, { recursive: true });
+        for (let f = 0; f < filesPerDir && written < files; f++) {
+            fs.writeFileSync(path.join(dirAbs, `module${written}.ts`), "");
+            written++;
+        }
+        dirIndex++;
+    }
+    return written;
+}
+/**
+ * Строит вложенное in-memory дерево примерно из `targetCount` узлов с заданным
+ * ветвлением `fanout`. Без обращений к файловой системе — чтобы бенчмарки
+ * виджета мерили стоимость flatten/сканов, а не диск.
+ */
+export function buildInMemoryTree(targetCount, fanout = 6) {
+    let created = 0;
+    const makeLevel = (prefix, depth) => {
+        const nodes = [];
+        for (let i = 0; i < fanout && created < targetCount; i++) {
+            const id = `${prefix}/${i}`;
+            created++;
+            const node = { id, label: `node-${id}` };
+            // Ветвимся, пока не набрали нужное число узлов и не ушли слишком глубоко.
+            if (depth < 5 && created < targetCount) {
+                node.children = makeLevel(id, depth + 1);
+            }
+            nodes.push(node);
+        }
+        return nodes;
+    };
+    return makeLevel("n", 0);
+}
+/** ITreeDataProvider поверх in-memory дерева PerfTreeNode. */
+export function makeInMemoryTreeProvider(roots) {
+    return {
+        getTreeItem(element) {
+            return {
+                label: element.label,
+                collapsible: (element.children?.length ?? 0) > 0,
+            };
+        },
+        getChildren(element) {
+            if (!element)
+                return roots;
+            return element.children ?? [];
+        },
+        getKey(element) {
+            return element.id;
+        },
+    };
+}
+/** Собирает все collapsible-узлы дерева (для массового раскрытия в бенче). */
+export function collectCollapsibleNodes(roots) {
+    const out = [];
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (node.children && node.children.length > 0) {
+                out.push(node);
+                walk(node.children);
+            }
+        }
+    };
+    walk(roots);
+    return out;
+}

package/dist/renderElement.d.ts

@@ -0,0 +1,24 @@
+import { BoxConstraints } from "@tuidom/core/common/geometryPromitives";
+import type { TUIElement } from "@tuidom/core/dom/tuiElement";
+import { MockTerminalBackend } from "./mockTerminalBackend.js";
+export interface IRenderElementOptions {
+    /** Constraints для layout; по умолчанию `BoxConstraints.tight(size)` бэкенда. */
+    readonly constraints?: BoxConstraints;
+    /** Прогнать `performStyleResolution` перед render (нужно элементам с per-char стилями). */
+    readonly resolveStyles?: boolean;
+    /**
+     * Положить палитру dark+ в var-scope элемента перед резолвом — для
+     * хостовых компонентов, чьи токены (sideBar.*, statusBar.*) не имеют
+     * дефолтов tuidom. Включает resolveStyles.
+     */
+    readonly themeVars?: boolean;
+    /** Явная палитра var-scope вместо снапшота dark+. Включает resolveStyles. */
+    readonly styleVars?: Readonly<Record<string, number>>;
+}
+/**
+ * Single-shot рендер standalone-элемента в {@link MockTerminalBackend}
+ * заданного размера: layout → (опц.) style resolution → render → flush.
+ * Результат скармливается прямо в `expectScreen`. Для мультифреймовых
+ * сценариев или доступа к `TerminalScreen` — ручной сетап.
+ */
+export declare function renderElement(element: TUIElement, width: number, height: number, options?: IRenderElementOptions): MockTerminalBackend;

package/dist/renderElement.js

@@ -0,0 +1,33 @@
+import { BoxConstraints, Offset, Point, Rect, Size } from "@tuidom/core/common/geometryPromitives";
+import { ROOT_STYLE_CONTEXT } from "@tuidom/core/dom/styles/tuiStyle";
+import { RenderContext } from "@tuidom/core/dom/tuiElement";
+import { TerminalScreen } from "@tuidom/core/rendering/terminalScreen";
+import { DARK_PLUS_STYLE_VARS } from "./darkPlusStyleVars.js";
+import { MockTerminalBackend } from "./mockTerminalBackend.js";
+/**
+ * Single-shot рендер standalone-элемента в {@link MockTerminalBackend}
+ * заданного размера: layout → (опц.) style resolution → render → flush.
+ * Результат скармливается прямо в `expectScreen`. Для мультифреймовых
+ * сценариев или доступа к `TerminalScreen` — ручной сетап.
+ */
+export function renderElement(element, width, height, options = {}) {
+    const size = new Size(width, height);
+    const backend = new MockTerminalBackend(size);
+    const termScreen = new TerminalScreen(size);
+    // globalPosition производный: у элемента без родителя он равен localPosition.
+    element.localPosition = new Offset(0, 0);
+    element.layout(options.constraints ?? BoxConstraints.tight(size));
+    const styleVars = options.styleVars ?? (options.themeVars === true ? DARK_PLUS_STYLE_VARS : undefined);
+    if (styleVars !== undefined) {
+        element.setStyleVars(styleVars);
+    }
+    if (options.resolveStyles === true || styleVars !== undefined) {
+        element.performStyleResolution(ROOT_STYLE_CONTEXT);
+    }
+    // Клип по краям экрана — как в TuiApplication: переполняющий layout не
+    // должен писать за пределы grid (там нет bounds-чека, это crash).
+    const screenClip = new Rect(new Point(0, 0), size);
+    element.render(new RenderContext(termScreen, new Offset(0, 0), screenClip));
+    termScreen.flush(backend);
+    return backend;
+}

package/dist/storyTypes.d.ts

@@ -0,0 +1,17 @@
+import type { TuiApplication } from "@tuidom/core/dom/tuiApplication";
+import type { TUIElement } from "@tuidom/core/dom/tuiElement";
+import type { BodyElement } from "@tuidom/elements/body/bodyElement";
+export interface StoryContext {
+    readonly app: TuiApplication;
+    readonly body: BodyElement;
+    readonly args: string[];
+    afterRun(cb: () => void | Promise<void>): void;
+}
+export type StoryFunction = (ctx: StoryContext) => TUIElement | undefined | Promise<TUIElement | undefined>;
+export interface StoryMeta {
+    title?: string;
+}
+export interface StoryModule {
+    meta?: StoryMeta;
+    [key: string]: StoryFunction | StoryMeta | undefined;
+}

package/dist/storyTypes.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "@tuidom/testing",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "Experimental terminal UI DOM — test harness: TestApp, renderElement, expectScreen, mock terminal backend. API is unstable.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/tuidom/tuidom.git",
+        "directory": "packages/testing"
+    },
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "keywords": [
+        "tui",
+        "terminal",
+        "ui",
+        "dom",
+        "testing"
+    ],
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        "./package.json": "./package.json",
+        "./*.js": "./dist/*.js",
+        "./*": "./dist/*.js"
+    },
+    "dependencies": {
+        "@tuidom/core": "0.1.0",
+        "@tuidom/elements": "0.1.0"
+    }
+}