@tuidom/core 0.1.0

package/dist/dom/styles/styleTokens.js

@@ -0,0 +1,122 @@
+import { DEFAULT_COLOR, packRgb } from "../../common/colorUtils.js";
+/**
+ * Дефолтные значения цветовых токенов tuidom — единственное место, где у
+ * виджетов tuidom/ui есть RGB-литералы. Правило: токен, на который ссылается
+ * виджет, ОБЯЗАН иметь строку здесь — иначе резолв без хостовой таблицы
+ * (тесты, stories, standalone-использование) упадёт fail-fast'ом.
+ *
+ * Имена — в конвенции color id VS Code ("list.activeSelectionBackground"),
+ * чтобы хост перекрывал дефолты ключами своей темы без функций-мостов;
+ * tuidom-специфика без темного эквивалента — под собственным именем
+ * ("menu.shortcutForeground", "quickPick.*", "titledPanel.*", "menuBar.*").
+ * Значения — только конкретные числа (packed RGB | DEFAULT_COLOR); сентинелы
+ * INHERITED_* в таблицах запрещены (проверяется в setStyleVars).
+ *
+ * Дефолты сохраняют исторический вид unthemed-палитр, которые сюда переехали
+ * (Н3): под управлением хоста всё перекрывается активной темой.
+ */
+export const STYLE_TOKEN_DEFAULTS = {
+    // ── Кнопка (base = secondary-вид, focus/checked = primary) ──
+    "button.foreground": packRgb(255, 255, 255),
+    "button.background": packRgb(0, 120, 215),
+    "button.hoverBackground": packRgb(26, 134, 224),
+    "button.secondaryForeground": packRgb(204, 204, 204),
+    "button.secondaryBackground": packRgb(60, 60, 60),
+    "button.secondaryHoverBackground": packRgb(69, 73, 78),
+    // ── Меню (попапы, дропдауны, контекстные) ──
+    "menu.foreground": packRgb(204, 204, 204),
+    "menu.background": packRgb(37, 37, 38),
+    "menu.selectionForeground": packRgb(255, 255, 255),
+    "menu.selectionBackground": packRgb(4, 57, 94),
+    "menu.border": packRgb(83, 83, 83),
+    "menu.separatorBackground": packRgb(83, 83, 83),
+    "menu.shortcutForeground": packRgb(128, 128, 128),
+    // ── Полоса меню ──
+    "menuBar.foreground": DEFAULT_COLOR,
+    "menuBar.background": packRgb(64, 64, 64),
+    "menubar.selectionForeground": packRgb(255, 255, 255),
+    "menubar.selectionBackground": packRgb(0, 90, 180),
+    // ── Списки и деревья ──
+    "list.activeSelectionBackground": packRgb(4, 57, 94),
+    "list.activeSelectionForeground": packRgb(255, 255, 255),
+    "list.inactiveSelectionBackground": packRgb(55, 55, 61),
+    "list.inactiveSelectionForeground": packRgb(204, 204, 204),
+    "list.hoverBackground": packRgb(42, 45, 46),
+    "list.deemphasizedForeground": packRgb(150, 150, 150),
+    "list.highlightForeground": packRgb(100, 200, 255),
+    // ── Скроллбар (фон колонки наследуется каскадом от хозяина) ──
+    "scrollbarSlider.background": packRgb(100, 100, 100),
+    "scrollbar.background": packRgb(50, 50, 50),
+    // ── Вкладки редактора ──
+    "tab.activeForeground": packRgb(255, 255, 255),
+    "tab.activeBackground": packRgb(30, 30, 30),
+    "tab.inactiveForeground": packRgb(150, 150, 150),
+    "tab.inactiveBackground": packRgb(45, 45, 45),
+    "editorGroupHeader.tabsBackground": packRgb(37, 37, 38),
+    // ── Панель ──
+    "panel.background": packRgb(24, 24, 24),
+    "panelTitle.inactiveForeground": packRgb(142, 142, 142),
+    "panel.border": packRgb(43, 43, 43),
+    "titledPanel.titleForeground": packRgb(130, 130, 130),
+    // ── Терминал ──
+    "terminal.foreground": DEFAULT_COLOR,
+    "terminal.background": DEFAULT_COLOR,
+    // ── Селектбокс ──
+    "dropdown.foreground": packRgb(240, 240, 240),
+    "dropdown.background": packRgb(60, 60, 60),
+    "dropdown.border": packRgb(60, 60, 60),
+    "dropdown.listBackground": packRgb(37, 37, 38),
+    // ── Инпут ──
+    "input.foreground": packRgb(204, 204, 204),
+    "input.background": packRgb(60, 60, 60),
+    "input.placeholderForeground": packRgb(110, 110, 110),
+    "input.border": packRgb(60, 60, 60),
+    "input.selectionBackground": packRgb(38, 79, 120),
+    focusBorder: packRgb(0, 127, 212),
+    // ── Sash ──
+    "sash.hoverBorder": packRgb(0, 120, 215),
+    // ── Квик-пик ──
+    "quickInput.foreground": packRgb(204, 204, 204),
+    "quickInput.background": packRgb(37, 37, 38),
+    "quickPick.border": packRgb(83, 83, 83),
+    "quickPick.badgeForeground": packRgb(150, 190, 100),
+    "quickPick.shortcutForeground": packRgb(128, 128, 128),
+    "quickPick.hintForeground": packRgb(100, 150, 200),
+    "quickPick.titleForeground": packRgb(230, 230, 230),
+    "quickPick.promptForeground": packRgb(140, 140, 140),
+    descriptionForeground: packRgb(125, 125, 125),
+    // ── Автодополнение ──
+    "editorSuggestWidget.border": packRgb(83, 83, 83),
+    "editorSuggestWidget.background": packRgb(34, 34, 40),
+    "editorSuggestWidget.foreground": packRgb(204, 204, 204),
+    "editorSuggestWidget.selectedBackground": packRgb(56, 62, 90),
+    "editorSuggestWidget.selectedForeground": packRgb(255, 255, 255),
+    "editorSuggestWidget.iconForeground": packRgb(130, 170, 255),
+    "editorSuggestWidget.detailForeground": packRgb(120, 120, 130),
+    // ── Виджеты редактора (диалоги, find) ──
+    "editorWidget.foreground": packRgb(204, 204, 204),
+    "editorWidget.background": packRgb(37, 37, 38),
+    "editorWidget.border": packRgb(69, 69, 69),
+    "textLink.foreground": packRgb(55, 148, 255),
+    // ── Редактор ──
+    "editorLineNumber.foreground": packRgb(133, 133, 133),
+    "editorLineNumber.activeForeground": packRgb(198, 198, 198),
+    "editor.wordHighlightBackground": packRgb(71, 71, 71),
+    "editorGutter.foldingControlForeground": packRgb(197, 197, 197),
+    "editorIndentGuide.background1": packRgb(64, 64, 64),
+    "editorIndentGuide.activeBackground1": packRgb(112, 112, 112),
+    "editorError.foreground": packRgb(241, 76, 76),
+    "editorWarning.foreground": packRgb(204, 167, 0),
+    "editorInfo.foreground": packRgb(55, 148, 255),
+    "editorHint.foreground": packRgb(238, 238, 238),
+    // ── Diff ──
+    "diffEditor.insertedLineBackground": 0x373d29,
+    "diffEditor.removedLineBackground": 0x4b1818,
+    "diffEditor.unchangedRegionForeground": 0x8c8c8c,
+};
+/**
+ * Дно прототипной цепочки var-scope'ов: замороженные дефолты с null-прототипом
+ * (лукап по цепочке не должен находить ключи Object.prototype). Пользовательские
+ * таблицы (setStyleVars) ложатся ПОВЕРХ через Object.create.
+ */
+export const ROOT_VAR_SCOPE = Object.freeze(Object.assign(Object.create(null), STYLE_TOKEN_DEFAULTS));

package/dist/dom/styles/tuiStyle.d.ts

@@ -0,0 +1,75 @@
+import type { AnyStyleToken } from "./styleTokens.js";
+export declare const INHERITED_FG = -100;
+export declare const INHERITED_BG = -101;
+export type StyleColor = number | AnyStyleToken;
+/** Таблица токен→число. Лукап идёт по прототипной цепочке до ROOT_VAR_SCOPE. */
+export type StyleVarScope = Readonly<Record<string, number>>;
+export type StyleState = "hover" | "focus" | (string & {});
+/**
+ * Селектор состояния в when-записи:
+ * - `"selected"` — состояние активно на САМОМ элементе;
+ * - `"in:focus"` — активно на самом элементе ИЛИ любом предке («внутри
+ *   сфокусированного»; заменяет descendant-комбинатор CSS). Осторожно:
+ *   `in:hover` шире CSS-`:hover` — сработает и когда курсор на сиблинге
+ *   внутри hovered-контейнера; «hover именно на мне» — простой `"hover"`.
+ */
+export type StyleStateSelector = StyleState | `in:${string}`;
+/** Запись применяется, когда активны ВСЕ её селекторы (AND). */
+export interface StyleStateVariant {
+    readonly states: readonly StyleStateSelector[];
+    readonly fg?: StyleColor;
+    readonly bg?: StyleColor;
+}
+export interface TUIStyle {
+    fg?: StyleColor;
+    bg?: StyleColor;
+    /**
+     * Варианты по состояниям. Позже объявленная активная запись побеждает
+     * (порядок = приоритет, как порядок правил CSS). `states: []` легален —
+     * «всегда активна» (удобная база, переопределяемая последующими).
+     */
+    when?: readonly StyleStateVariant[];
+}
+export interface ResolvedTUIStyle {
+    readonly fg: number;
+    readonly bg: number;
+}
+export declare const ROOT_RESOLVED_STYLE: ResolvedTUIStyle;
+export interface StyleResolutionContext {
+    readonly fg: number;
+    readonly bg: number;
+    /** Ближайший var-scope (собственные таблицы предков поверх дефолтов). */
+    readonly vars: StyleVarScope;
+    /** Объединение СОБСТВЕННЫХ состояний всех предков — для `in:`-селекторов. */
+    readonly ancestorStates: ReadonlySet<string>;
+}
+export declare const ROOT_STYLE_CONTEXT: StyleResolutionContext;
+/**
+ * Пользовательская таблица поверх родительского scope — прототипная цепочка,
+ * без копий. Свойства создаются через defineProperty: обычное присваивание
+ * ([[Set]]) отказало бы — родительские scope'ы заморожены, и цепочка прототипов
+ * блокирует запись одноимённого ключа.
+ */
+export declare function extendVarScope(parent: StyleVarScope, own: Readonly<Record<string, number>>): StyleVarScope;
+/**
+ * Структурное равенство деклараций стиля. Используется сеттером `style`,
+ * чтобы повторный пуш того же значения (JSX-rebuild, reconcile, повторное
+ * применение темы) не помечал грязным всё поддерево.
+ */
+export declare function styleEquals(a: TUIStyle, b: TUIStyle): boolean;
+/**
+ * Токен → число из scope (fail-fast на незнакомом), затем сентинелы
+ * INHERITED_* → унаследованные цвета. Проверка значения через typeof — защита
+ * от ключей Object.prototype ("toString") у пользовательских таблиц.
+ */
+export declare function resolveStyleColor(color: StyleColor, inheritedFg: number, inheritedBg: number, vars?: StyleVarScope, describeOwner?: () => string): number;
+/**
+ * Схлопывает базовые fg/bg и активные when-записи в «применённые» сырые цвета
+ * (ещё до резолва сентинелов). Позже объявленная активная запись побеждает.
+ * undefined в результате = «наследовать».
+ */
+export declare function mergeStyleVariants(style: TUIStyle, isActive: (selector: StyleStateSelector) => boolean): {
+    fg: StyleColor | undefined;
+    bg: StyleColor | undefined;
+};
+export declare function resolveStyle(style: TUIStyle, inherited: ResolvedTUIStyle): ResolvedTUIStyle;

package/dist/dom/styles/tuiStyle.js

@@ -0,0 +1,121 @@
+import { DEFAULT_COLOR } from "../../common/colorUtils.js";
+import { ROOT_VAR_SCOPE } from "./styleTokens.js";
+// ─── Inherited Color Sentinels ───
+// Sentinel values that resolve to the inherited fg/bg from the parent.
+// Start at -100 to avoid collision with DEFAULT_COLOR (-1).
+export const INHERITED_FG = -100;
+export const INHERITED_BG = -101;
+// ─── Root default ───
+export const ROOT_RESOLVED_STYLE = {
+    fg: DEFAULT_COLOR,
+    bg: DEFAULT_COLOR,
+};
+const EMPTY_STATES = new Set();
+export const ROOT_STYLE_CONTEXT = {
+    fg: DEFAULT_COLOR,
+    bg: DEFAULT_COLOR,
+    vars: ROOT_VAR_SCOPE,
+    ancestorStates: EMPTY_STATES,
+};
+/**
+ * Пользовательская таблица поверх родительского scope — прототипная цепочка,
+ * без копий. Свойства создаются через defineProperty: обычное присваивание
+ * ([[Set]]) отказало бы — родительские scope'ы заморожены, и цепочка прототипов
+ * блокирует запись одноимённого ключа.
+ */
+export function extendVarScope(parent, own) {
+    const scope = Object.create(parent);
+    for (const key of Object.keys(own)) {
+        Object.defineProperty(scope, key, { value: own[key], enumerable: true, writable: false, configurable: false });
+    }
+    return scope;
+}
+// ─── Comparison ───
+/**
+ * Структурное равенство деклараций стиля. Используется сеттером `style`,
+ * чтобы повторный пуш того же значения (JSX-rebuild, reconcile, повторное
+ * применение темы) не помечал грязным всё поддерево.
+ */
+export function styleEquals(a, b) {
+    if (a === b)
+        return true;
+    // Сравниваются ВСЕ собственные ключи: подклассы расширяют стиль своими
+    // полями (исторический прецедент — TitledPanelStyle), и они обязаны участвовать в
+    // равенстве. Ключ с undefined против отсутствия ключа считается различием —
+    // консервативно в безопасную сторону (лишний резолв, а не пропущенный).
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (key === "when")
+            continue; // массив — структурно, ниже
+        if (a[key] !== b[key])
+            return false;
+    }
+    return whenEquals(a.when, b.when);
+}
+// Порядок when-записей — семантика (приоритет), сравнение позиционное.
+function whenEquals(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || a.length !== b?.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (x.fg !== y.fg || x.bg !== y.bg || x.states.length !== y.states.length)
+            return false;
+        for (let j = 0; j < x.states.length; j++) {
+            if (x.states[j] !== y.states[j])
+                return false;
+        }
+    }
+    return true;
+}
+// ─── Resolution functions ───
+/**
+ * Токен → число из scope (fail-fast на незнакомом), затем сентинелы
+ * INHERITED_* → унаследованные цвета. Проверка значения через typeof — защита
+ * от ключей Object.prototype ("toString") у пользовательских таблиц.
+ */
+export function resolveStyleColor(color, inheritedFg, inheritedBg, vars = ROOT_VAR_SCOPE, describeOwner) {
+    if (typeof color === "string") {
+        const value = vars[color];
+        if (typeof value !== "number") {
+            const owner = describeOwner !== undefined ? describeOwner() : "TUIStyle";
+            throw new Error(`${owner}: неизвестный цветовой токен "${color}"`);
+        }
+        return value;
+    }
+    if (color === INHERITED_FG)
+        return inheritedFg;
+    if (color === INHERITED_BG)
+        return inheritedBg;
+    return color;
+}
+/**
+ * Схлопывает базовые fg/bg и активные when-записи в «применённые» сырые цвета
+ * (ещё до резолва сентинелов). Позже объявленная активная запись побеждает.
+ * undefined в результате = «наследовать».
+ */
+export function mergeStyleVariants(style, isActive) {
+    let fg = style.fg;
+    let bg = style.bg;
+    if (style.when !== undefined) {
+        for (const variant of style.when) {
+            if (variant.states.every(isActive)) {
+                if (variant.fg !== undefined)
+                    fg = variant.fg;
+                if (variant.bg !== undefined)
+                    bg = variant.bg;
+            }
+        }
+    }
+    return { fg, bg };
+}
+export function resolveStyle(style, inherited) {
+    const fg = style.fg !== undefined ? resolveStyleColor(style.fg, inherited.fg, inherited.bg) : inherited.fg;
+    const bg = style.bg !== undefined ? resolveStyleColor(style.bg, inherited.fg, inherited.bg) : inherited.bg;
+    return { fg, bg };
+}

package/dist/dom/tuiApplication.d.ts

@@ -0,0 +1,57 @@
+import type { ITerminalBackend } from "../backend/iTerminalBackend.js";
+import { TerminalScreen } from "../rendering/terminalScreen.js";
+import { FocusManager } from "./events/focusManager.js";
+import { MouseEventDispatcher } from "./events/mouseEventDispatcher.js";
+import { type TUIElement } from "./tuiElement.js";
+export declare class TuiApplication {
+    backend: ITerminalBackend;
+    root: TUIElement | null;
+    screen: TerminalScreen;
+    focusManager: FocusManager | null;
+    mouseDispatcher: MouseEventDispatcher;
+    private renderScheduled;
+    /**
+     * Прогонять {@link assertValidTree} после каждого кадра. Включено в тестовых
+     * харнессах (TestApp) и опционально в приложении (env VEXX_VALIDATE_TREE=1):
+     * забытый setParent / неукоренённое поддерево падают громко на первом же
+     * кадре, а не молчаливым «не показывается / не кликается».
+     */
+    validateTreeAfterRender: boolean;
+    private frameCounter;
+    private pinnedKeypressTarget;
+    private needsFullRepaint;
+    constructor(backend: ITerminalBackend);
+    /** Сколько кадров отрисовано с запуска. Растёт при каждой перерисовке. */
+    get frameCount(): number;
+    /** Есть ли отложенный (setImmediate) рендер, ещё не выполненный. */
+    get isRenderScheduled(): boolean;
+    private renderFrame;
+    /**
+     * Принудительно сделать следующий кадр полным (clear + рендер всего
+     * дерева). Для потребителей, меняющих картинку мимо markDirty-контракта
+     * (ресайз, тестовые харнессы).
+     */
+    invalidateScreen(): void;
+    /**
+     * Schedules a deferred render via setImmediate.
+     * Batches multiple markDirty() calls into a single frame.
+     * Skips rendering if layout is already clean (e.g. a synchronous
+     * renderFrame from handleInput already ran).
+     */
+    scheduleRender(): void;
+    private handleInput;
+    private handlePaste;
+    private handleMouse;
+    /**
+     * Синхронный кадр после события ввода — только если обработчики что-то
+     * пометили грязным. Одно физическое нажатие приходит 2–3 событиями
+     * (keydown + синтезированный keypress, под Kitty ещё keyup) — раньше
+     * каждое рендерило полный кадр, из которых пустые давали чистый diff и
+     * жгли CPU впустую. Стилевые изменения гейт проходят: markStyleDirty
+     * заканчивается markDirty. Синхронность оставлена намеренно: тесты и
+     * обработчики читают экран/геометрию сразу после события.
+     */
+    private renderAfterInput;
+    private handleResize;
+    run(): void;
+}

package/dist/dom/tuiApplication.js

@@ -0,0 +1,231 @@
+import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
+import { DamageList } from "../rendering/damage.js";
+import { TerminalScreen } from "../rendering/terminalScreen.js";
+import { contextMenuEventFromKeydown } from "./events/contextMenuEventSource.js";
+import { FocusManager } from "./events/focusManager.js";
+import { MouseEventDispatcher } from "./events/mouseEventDispatcher.js";
+import { TUIKeyboardEvent } from "./events/tuiKeyboardEvent.js";
+import { TUIPasteEvent } from "./events/tuiPasteEvent.js";
+import { ROOT_STYLE_CONTEXT } from "./styles/tuiStyle.js";
+import { RenderContext } from "./tuiElement.js";
+import { assertValidTree } from "./validateTree.js";
+export class TuiApplication {
+    backend;
+    root = null;
+    screen;
+    focusManager = null;
+    mouseDispatcher = new MouseEventDispatcher();
+    renderScheduled = false;
+    /**
+     * Прогонять {@link assertValidTree} после каждого кадра. Включено в тестовых
+     * харнессах (TestApp) и опционально в приложении (env VEXX_VALIDATE_TREE=1):
+     * забытый setParent / неукоренённое поддерево падают громко на первом же
+     * кадре, а не молчаливым «не показывается / не кликается».
+     */
+    validateTreeAfterRender = false;
+    // Монотонный счётчик отрисованных кадров. Инкремент на каждый renderFrame —
+    // инспектор ждёт «рендер устоялся» (frameCount не менялся + нет
+    // запланированного рендера), не завися от sleep. См. inspector/idleWaiter.
+    frameCounter = 0;
+    // Цель keydown, закреплённая за парным keypress того же физического нажатия
+    // (см. handleInput).
+    pinnedKeypressTarget = null;
+    // Следующий кадр — полный (первый кадр, ресайз, invalidateScreen).
+    needsFullRepaint = true;
+    constructor(backend) {
+        this.backend = backend;
+        this.screen = new TerminalScreen(backend.getSize());
+    }
+    /** Сколько кадров отрисовано с запуска. Растёт при каждой перерисовке. */
+    get frameCount() {
+        return this.frameCounter;
+    }
+    /** Есть ли отложенный (setImmediate) рендер, ещё не выполненный. */
+    get isRenderScheduled() {
+        return this.renderScheduled;
+    }
+    renderFrame() {
+        if (this.root) {
+            this.frameCounter++;
+            // Root at (0, 0) — top-left of screen. globalPosition производный
+            // (localPosition корня без родителя), выставлять его не нужно.
+            this.root.localPosition = new Offset(0, 0);
+            // Layout и стили — полные каждый кадр (дёшево, геометрия и
+            // validateTree не зависят от damage); стили гейтятся внутри.
+            const constraints = BoxConstraints.tight(this.screen.size);
+            this.root.layout(constraints);
+            this.root.performStyleResolution(ROOT_STYLE_CONTEXT);
+            // Damage-обход — всегда: и собирает области, и актуализирует
+            // lastPaintedRect/флаги (даже когда кадр будет полным).
+            const damage = new DamageList();
+            for (const detached of this.root.takePendingDetachDamage()) {
+                damage.add(detached);
+            }
+            this.root.collectDamage(damage, new Point(0, 0));
+            const screenBounds = new Rect(new Point(0, 0), this.screen.size);
+            let rects;
+            if (this.needsFullRepaint) {
+                this.needsFullRepaint = false;
+                this.screen.clear();
+                rects = [screenBounds];
+            }
+            else {
+                rects = damage.finalize(screenBounds);
+            }
+            // Экран — ретейн-буфер: перерисовываются только повреждённые
+            // области. Инвариант: множество очищенных ячеек == множеству,
+            // по которому клипуется (и прунится) проход отрисовки. Внутри
+            // области канонический обход идентичен полному кадру — прозрачные
+            // элементы, хром родителей и оверлеи корректны по построению.
+            for (let rect of rects) {
+                // Кромка области не должна рассекать wide-char пару ретейн-грида:
+                // очистка лечила бы голову вне области перерисовки (см. Grid).
+                rect = this.screen.snapToWideChars(rect);
+                this.screen.clearRect(rect);
+                // Аппаратный курсор ставится только в render его владельца:
+                // позиция в повреждённой области гаснет и пере-ставится тем,
+                // кто её снова нарисует (или остаётся погашенной — паритет с
+                // полным кадром, где clear() гасил её всегда).
+                if (this.screen.cursorPosition !== null && rect.containsPoint(this.screen.cursorPosition)) {
+                    this.screen.clearCursorPosition();
+                }
+                this.root.render(new RenderContext(this.screen, new Offset(0, 0), rect));
+            }
+            // Всегда: пустой damage — пустой diff, ноль байт в терминал.
+            this.screen.flush(this.backend);
+            if (this.validateTreeAfterRender) {
+                assertValidTree(this.root);
+            }
+        }
+    }
+    /**
+     * Принудительно сделать следующий кадр полным (clear + рендер всего
+     * дерева). Для потребителей, меняющих картинку мимо markDirty-контракта
+     * (ресайз, тестовые харнессы).
+     */
+    invalidateScreen() {
+        this.needsFullRepaint = true;
+    }
+    /**
+     * Schedules a deferred render via setImmediate.
+     * Batches multiple markDirty() calls into a single frame.
+     * Skips rendering if layout is already clean (e.g. a synchronous
+     * renderFrame from handleInput already ran).
+     */
+    scheduleRender() {
+        if (this.renderScheduled)
+            return;
+        this.renderScheduled = true;
+        setImmediate(() => {
+            this.renderScheduled = false;
+            if (this.root?.isLayoutDirty) {
+                this.renderFrame();
+            }
+        });
+    }
+    handleInput(event) {
+        if (this.root) {
+            // Dispatch to focused element (or root) with capture/bubble
+            const tuiEvent = new TUIKeyboardEvent(event.type, {
+                key: event.key,
+                code: event.code,
+                ctrlKey: event.ctrlKey,
+                shiftKey: event.shiftKey,
+                altKey: event.altKey,
+                metaKey: event.metaKey,
+                raw: event.raw,
+            });
+            // Одно физическое нажатие — один логический получатель: парсер на каждый
+            // keydown синтезирует keypress сразу следом, и если обработчик keydown
+            // сменил фокус (оверлей закрылся, restoreFocus вернул фокус дереву),
+            // парный keypress не должен «протечь» новому владельцу фокуса. Поэтому
+            // цель keypress закрепляется за целью её keydown; keyup — отдельный
+            // момент времени, он идёт текущему фокусу.
+            let target = this.focusManager?.activeElement ?? this.root;
+            if (event.type === "keypress" &&
+                /* v8 ignore next 2 -- defensive: keypress эмитится парсером только сразу после парного keydown, который уже выставил пин */
+                this.pinnedKeypressTarget !== null) {
+                target = this.pinnedKeypressTarget;
+            }
+            this.pinnedKeypressTarget = event.type === "keydown" ? target : null;
+            const notPrevented = target.dispatchEvent(tuiEvent);
+            // Клавиатурный запрос контекстного меню (ContextMenu / Shift+F10)
+            // синтезируется в общее событие "contextmenu" — только если keydown
+            // не съеден (глобальный кейбинд делает preventDefault сам).
+            if (notPrevented && event.type === "keydown") {
+                const contextMenuEvent = contextMenuEventFromKeydown(tuiEvent, target);
+                if (contextMenuEvent) {
+                    target.dispatchEvent(contextMenuEvent);
+                }
+            }
+            // Tab focus cycling (default behavior if not prevented, only on keydown)
+            if (notPrevented && event.key === "Tab" && event.type === "keydown" && this.focusManager) {
+                const direction = event.shiftKey ? "backward" : "forward";
+                this.focusManager.cycleFocus(direction);
+            }
+            this.renderAfterInput();
+        }
+    }
+    handlePaste(text) {
+        if (this.root) {
+            const event = new TUIPasteEvent(text);
+            const target = this.focusManager?.activeElement ?? this.root;
+            target.dispatchEvent(event);
+            this.renderAfterInput();
+        }
+    }
+    handleMouse(token) {
+        if (this.root) {
+            this.mouseDispatcher.handleMouseToken(token, this.root);
+            this.renderAfterInput();
+        }
+    }
+    /**
+     * Синхронный кадр после события ввода — только если обработчики что-то
+     * пометили грязным. Одно физическое нажатие приходит 2–3 событиями
+     * (keydown + синтезированный keypress, под Kitty ещё keyup) — раньше
+     * каждое рендерило полный кадр, из которых пустые давали чистый diff и
+     * жгли CPU впустую. Стилевые изменения гейт проходят: markStyleDirty
+     * заканчивается markDirty. Синхронность оставлена намеренно: тесты и
+     * обработчики читают экран/геометрию сразу после события.
+     */
+    renderAfterInput() {
+        if (this.root?.isLayoutDirty) {
+            this.renderFrame();
+        }
+    }
+    handleResize(size) {
+        this.screen = new TerminalScreen(size);
+        this.needsFullRepaint = true;
+        // Mark root as dirty so next render recalculates layout
+        if (this.root) {
+            this.root.markDirty();
+        }
+        this.renderFrame();
+    }
+    run() {
+        // Set up focus manager on root
+        if (this.root) {
+            this.focusManager = new FocusManager(this.root);
+            this.root.focusManager = this.focusManager;
+            this.root.setRequestRenderCallback(() => {
+                this.scheduleRender();
+            });
+        }
+        this.backend.setup();
+        this.backend.onInput((event) => {
+            this.handleInput(event);
+        });
+        this.backend.onResize((size) => {
+            this.handleResize(size);
+        });
+        this.backend.onPaste((text) => {
+            this.handlePaste(text);
+        });
+        this.backend.onMouse((token) => {
+            this.handleMouse(token);
+        });
+        // Initial render
+        this.renderFrame();
+    }
+}