@tuidom/core 0.2.3 → 0.4.0

package/dist/backend/iTerminalBackend.d.ts

@@ -27,6 +27,16 @@ export interface ITerminalBackend {
      * reply within the probe window). Fire-and-forget — callers must not block on it.
      */
     probeKeyboardProtocol(onResult: (supported: boolean) => void): void;
+    /**
+     * Asynchronously ask the terminal for its name and version (XTVERSION: `CSI > 0 q`
+     * → `DCS > | <name(version)> ST`). `onResult` fires exactly once with the reported
+     * string as-is (e.g. `"iTerm2 3.5.0"`, `"kitty(0.35.2)"`, `"WezTerm 20240203…"`), or
+     * `undefined` if the terminal doesn't answer within the probe window. The reply is
+     * consumed by the backend and never reaches `onInput`. Inside tmux the query goes
+     * to tmux itself (like the other probes), so the answer is tmux's own (`"tmux 3.4"`).
+     * Fire-and-forget — callers must not block on it.
+     */
+    probeTerminalVersion(onResult: (nameAndVersion: string | undefined) => void): void;
     /**
      * Render a frame: receive the current grid and cursor position.
      * The backend decides how to output it (ANSI diffing, simple copy, etc.).

package/dist/common/colorUtils.d.ts

@@ -3,17 +3,66 @@
  * Must be negative so it's never confused with a packed RGB value (0x000000–0xFFFFFF).
  */
 export declare const DEFAULT_COLOR = -1;
+/**
+ * Полностью прозрачный цвет (`#RRGGBB00`, CSS `transparent`): при наложении
+ * ничего не меняет, а как собственный bg элемента — не красит. Сентинел, а не
+ * упаковка с альфой 0: старший байт 0 занят непрозрачными 24-битными числами.
+ */
+export declare const TRANSPARENT_COLOR = -2;
 /** Pack three 8-bit channels into a single 24-bit integer. */
 export declare function packRgb(r: number, g: number, b: number): number;
+/**
+ * Упаковывает цвет с альфой (0..255). Непрозрачный (`a === 255`) даёт обычное
+ * 24-битное число — то же, что {@link packRgb}; `a === 0` — {@link TRANSPARENT_COLOR};
+ * промежуточная альфа кладётся в старший байт (`0xAARRGGBB`, беззнаковое
+ * значение > 0xFFFFFF). Так весь существующий код с 24-битными литералами
+ * остаётся валидным без миграции, а полупрозрачность — отличима одним сравнением.
+ */
+export declare function packRgba(r: number, g: number, b: number, a: number): number;
 /** Extract the red channel (bits 16–23). */
 export declare function unpackR(color: number): number;
 /** Extract the green channel (bits 8–15). */
 export declare function unpackG(color: number): number;
 /** Extract the blue channel (bits 0–7). */
 export declare function unpackB(color: number): number;
+/**
+ * Альфа цвета: 255 у 24-битных чисел и сентинелов (`DEFAULT_COLOR` — цвет
+ * терминала, он непрозрачен), 0 у {@link TRANSPARENT_COLOR}, иначе старший байт.
+ */
+export declare function unpackA(color: number): number;
+/** true для полупрозрачного цвета (альфа 1..254) — того, что требует композитинга с подложкой. */
+export declare function isTranslucent(color: number): boolean;
+/**
+ * true, если число — легальное значение цвета: 24-битный RGB, упаковка с
+ * альфой, {@link DEFAULT_COLOR} или {@link TRANSPARENT_COLOR}. Сентинелы
+ * каскада (`INHERITED_*`) и мусор — false.
+ */
+export declare function isColorValue(color: number): boolean;
 /**
  * Накладывает полупрозрачный `fg` на непрозрачную подложку `bg` и возвращает
  * непрозрачный результат: терминал альфы не умеет, поэтому композитинг
  * выполняется заранее (`alpha` — доля 0..1).
  */
 export declare function blendRgb(fg: number, bg: number, alpha: number): number;
+/**
+ * Композитинг «`color` поверх `under`» (source-over): результат всегда
+ * непрозрачен или `DEFAULT_COLOR`. Непрозрачный `color` (и `DEFAULT_COLOR`)
+ * возвращается как есть — путь нулевой стоимости, одно сравнение;
+ * {@link TRANSPARENT_COLOR} оставляет подложку. Полупрозрачный цвет смешивается
+ * с `under` по альфе; если подложка — `DEFAULT_COLOR` (цвет терминала, нам
+ * неизвестен), смешивать не с чем — альфа отбрасывается, цвет ложится непрозрачным.
+ */
+export declare function compositeOver(color: number, under: number): number;
+/**
+ * Разбирает CSS-подобный hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+ * (решётка необязательна, регистр любой) в упакованный цвет (см.
+ * {@link packRgba}). Некорректная строка — throw: цвет темы с опечаткой
+ * должен падать на разборе, а не красить в чёрный.
+ */
+export declare function parseHexColor(hex: string): number;
+/**
+ * Обратное к {@link parseHexColor}: `#rrggbb` для непрозрачного, `#rrggbbaa`
+ * с альфой, `#00000000` для {@link TRANSPARENT_COLOR}. `DEFAULT_COLOR` hex не
+ * имеет — throw.
+ */
+export declare function formatHexColor(color: number): string;

package/dist/common/colorUtils.js

@@ -3,10 +3,34 @@
  * Must be negative so it's never confused with a packed RGB value (0x000000–0xFFFFFF).
  */
 export const DEFAULT_COLOR = -1;
+/**
+ * Полностью прозрачный цвет (`#RRGGBB00`, CSS `transparent`): при наложении
+ * ничего не меняет, а как собственный bg элемента — не красит. Сентинел, а не
+ * упаковка с альфой 0: старший байт 0 занят непрозрачными 24-битными числами.
+ */
+export const TRANSPARENT_COLOR = -2;
+/** Максимальное упакованное значение с альфой (`0xFE_FFFFFF`); всё выше — не цвет. */
+const MAX_PACKED_COLOR = 0xfeffffff;
+/** Множитель старшего байта — альфа хранится через умножение, а не `<<`, чтобы не уйти в отрицательные. */
+const ALPHA_UNIT = 0x1000000;
 /** Pack three 8-bit channels into a single 24-bit integer. */
 export function packRgb(r, g, b) {
     return (r << 16) | (g << 8) | b;
 }
+/**
+ * Упаковывает цвет с альфой (0..255). Непрозрачный (`a === 255`) даёт обычное
+ * 24-битное число — то же, что {@link packRgb}; `a === 0` — {@link TRANSPARENT_COLOR};
+ * промежуточная альфа кладётся в старший байт (`0xAARRGGBB`, беззнаковое
+ * значение > 0xFFFFFF). Так весь существующий код с 24-битными литералами
+ * остаётся валидным без миграции, а полупрозрачность — отличима одним сравнением.
+ */
+export function packRgba(r, g, b, a) {
+    if (a >= 0xff)
+        return packRgb(r, g, b);
+    if (a <= 0)
+        return TRANSPARENT_COLOR;
+    return a * ALPHA_UNIT + packRgb(r, g, b);
+}
 /** Extract the red channel (bits 16–23). */
 export function unpackR(color) {
     return (color >> 16) & 0xff;
@@ -19,6 +43,31 @@ export function unpackG(color) {
 export function unpackB(color) {
     return color & 0xff;
 }
+/**
+ * Альфа цвета: 255 у 24-битных чисел и сентинелов (`DEFAULT_COLOR` — цвет
+ * терминала, он непрозрачен), 0 у {@link TRANSPARENT_COLOR}, иначе старший байт.
+ */
+export function unpackA(color) {
+    if (color === TRANSPARENT_COLOR)
+        return 0;
+    if (color <= 0xffffff)
+        return 0xff;
+    return color >>> 24;
+}
+/** true для полупрозрачного цвета (альфа 1..254) — того, что требует композитинга с подложкой. */
+export function isTranslucent(color) {
+    return color > 0xffffff;
+}
+/**
+ * true, если число — легальное значение цвета: 24-битный RGB, упаковка с
+ * альфой, {@link DEFAULT_COLOR} или {@link TRANSPARENT_COLOR}. Сентинелы
+ * каскада (`INHERITED_*`) и мусор — false.
+ */
+export function isColorValue(color) {
+    return (color === DEFAULT_COLOR ||
+        color === TRANSPARENT_COLOR ||
+        (Number.isInteger(color) && color >= 0 && color <= MAX_PACKED_COLOR));
+}
 /**
  * Накладывает полупрозрачный `fg` на непрозрачную подложку `bg` и возвращает
  * непрозрачный результат: терминал альфы не умеет, поэтому композитинг
@@ -28,3 +77,55 @@ export function blendRgb(fg, bg, alpha) {
     const mix = (f, b) => Math.round(f * alpha + b * (1 - alpha));
     return packRgb(mix(unpackR(fg), unpackR(bg)), mix(unpackG(fg), unpackG(bg)), mix(unpackB(fg), unpackB(bg)));
 }
+/**
+ * Композитинг «`color` поверх `under`» (source-over): результат всегда
+ * непрозрачен или `DEFAULT_COLOR`. Непрозрачный `color` (и `DEFAULT_COLOR`)
+ * возвращается как есть — путь нулевой стоимости, одно сравнение;
+ * {@link TRANSPARENT_COLOR} оставляет подложку. Полупрозрачный цвет смешивается
+ * с `under` по альфе; если подложка — `DEFAULT_COLOR` (цвет терминала, нам
+ * неизвестен), смешивать не с чем — альфа отбрасывается, цвет ложится непрозрачным.
+ */
+export function compositeOver(color, under) {
+    if (color <= 0xffffff)
+        return color === TRANSPARENT_COLOR ? under : color;
+    const rgb = color & 0xffffff;
+    if (under < 0)
+        return rgb;
+    return blendRgb(rgb, under, (color >>> 24) / 0xff);
+}
+/**
+ * Разбирает CSS-подобный hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+ * (решётка необязательна, регистр любой) в упакованный цвет (см.
+ * {@link packRgba}). Некорректная строка — throw: цвет темы с опечаткой
+ * должен падать на разборе, а не красить в чёрный.
+ */
+export function parseHexColor(hex) {
+    const digits = hex.startsWith("#") ? hex.slice(1) : hex;
+    const short = digits.length === 3 || digits.length === 4;
+    if (!(short || digits.length === 6 || digits.length === 8) || !/^[0-9a-fA-F]+$/.test(digits)) {
+        throw new Error(`parseHexColor: некорректный hex-цвет "${hex}"`);
+    }
+    const channel = (i) => {
+        if (short) {
+            const d = parseInt(digits[i], 16);
+            return d * 16 + d;
+        }
+        return parseInt(digits.slice(i * 2, i * 2 + 2), 16);
+    };
+    const hasAlpha = digits.length === 4 || digits.length === 8;
+    return packRgba(channel(0), channel(1), channel(2), hasAlpha ? channel(3) : 0xff);
+}
+/**
+ * Обратное к {@link parseHexColor}: `#rrggbb` для непрозрачного, `#rrggbbaa`
+ * с альфой, `#00000000` для {@link TRANSPARENT_COLOR}. `DEFAULT_COLOR` hex не
+ * имеет — throw.
+ */
+export function formatHexColor(color) {
+    if (color === DEFAULT_COLOR)
+        throw new Error("formatHexColor: DEFAULT_COLOR не имеет hex-представления");
+    if (color === TRANSPARENT_COLOR)
+        return "#00000000";
+    const hex2 = (n) => n.toString(16).padStart(2, "0");
+    const rgb = `#${hex2(unpackR(color))}${hex2(unpackG(color))}${hex2(unpackB(color))}`;
+    return isTranslucent(color) ? `${rgb}${hex2(unpackA(color))}` : rgb;
+}

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

@@ -72,4 +72,10 @@ export declare function mergeStyleVariants(style: TUIStyle, isActive: (selector:
     fg: StyleColor | undefined;
     bg: StyleColor | undefined;
 };
+/**
+ * Резолв базовых fg/bg без when-вариантов и var-scope (утилита для тестов и
+ * простых потребителей; ядро идёт через `TUIElement.performStyleResolution`,
+ * та же модель): цвет с альфой композитится с унаследованным bg, fg — с
+ * итоговым bg, наружу уходят непрозрачные значения.
+ */
 export declare function resolveStyle(style: TUIStyle, inherited: ResolvedTUIStyle): ResolvedTUIStyle;

package/dist/dom/styles/tuiStyle.js

@@ -1,4 +1,4 @@
-import { DEFAULT_COLOR } from "../../common/colorUtils.js";
+import { compositeOver, 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.
@@ -114,8 +114,16 @@ export function mergeStyleVariants(style, isActive) {
     }
     return { fg, bg };
 }
+/**
+ * Резолв базовых fg/bg без when-вариантов и var-scope (утилита для тестов и
+ * простых потребителей; ядро идёт через `TUIElement.performStyleResolution`,
+ * та же модель): цвет с альфой композитится с унаследованным bg, 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;
+    const ownBg = style.bg !== undefined ? resolveStyleColor(style.bg, inherited.fg, inherited.bg) : inherited.bg;
+    const bg = compositeOver(ownBg, inherited.bg);
+    const ownFg = style.fg !== undefined ? resolveStyleColor(style.fg, inherited.fg, inherited.bg) : inherited.fg;
+    const fg = compositeOver(ownFg, bg);
     return { fg, bg };
 }

package/dist/dom/tuiElement.d.ts

@@ -143,6 +143,8 @@ export declare class TUIElement {
     private subtreeStyleDirty;
     private appliedFgValue;
     private appliedBgValue;
+    /** Красит ли элемент собственный фон: bg задан своим стилем и не TRANSPARENT_COLOR. */
+    private paintsOwnBackgroundValue;
     private styleStatesSet;
     private styleVarsValue;
     private varScopeRef;
@@ -283,8 +285,9 @@ export declare class TUIElement {
      * предков и дефолтов tuidom (STYLE_TOKEN_DEFAULTS). Обычное место — корень:
      * хост транслирует сюда палитру темы одним вызовом (hot-swap = повторный
      * вызов). Таблица заменяется целиком, null — снимает. Значения — только
-     * конкретные числа (packed RGB | DEFAULT_COLOR); сентинелы INHERITED_*
-     * нелегальны.
+     * конкретные числа (packed RGB, в том числе с альфой — `packRgba`/
+     * `parseHexColor`, | DEFAULT_COLOR | TRANSPARENT_COLOR); сентинелы
+     * INHERITED_* нелегальны.
      */
     setStyleVars(vars: Readonly<Record<string, number>> | null): void;
     /**
@@ -503,6 +506,10 @@ export declare class TUIElement {
      * флагов стиля: собственный фон — это новая поверхность, и атрибуты того,
      * что нарисовано под ней раньше в этом кадре (подчёркивание диагностики под
      * попапом, жирный токен под диалогом), на ней проступать не должны.
+     *
+     * Полупрозрачный собственный bg уже скомпозичен каскадом с унаследованным
+     * (см. {@link performStyleResolution}); `TRANSPARENT_COLOR` (`#RRGGBB00`)
+     * считается «фона нет» — как CSS `transparent`, элемент ничего не красит.
      */
     protected paintOwnBackground(context: RenderContext): void;
     /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */

package/dist/dom/tuiElement.js

@@ -1,4 +1,4 @@
-import { DEFAULT_COLOR } from "../common/colorUtils.js";
+import { compositeOver, isColorValue, TRANSPARENT_COLOR } from "../common/colorUtils.js";
 import { DisplayLine } from "../common/displayLine.js";
 import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
 import { StyleFlags } from "../common/styleFlags.js";
@@ -217,6 +217,8 @@ export class TUIElement {
     // вопрос «задан ли цвет собственным стилем» (заливка фона, инспектор).
     appliedFgValue;
     appliedBgValue;
+    /** Красит ли элемент собственный фон: bg задан своим стилем и не TRANSPARENT_COLOR. */
+    paintsOwnBackgroundValue = false;
     // Активные состояния (hover/focus ведёт ядро, прочие — виджеты). Lazy:
     // у подавляющего большинства элементов состояний нет.
     styleStatesSet = null;
@@ -379,7 +381,9 @@ export class TUIElement {
     /** Гасит фокус, если activeElement — этот элемент или его потомок. */
     releaseFocusIfInside() {
         const fm = this.getRoot()?.focusManager ?? null;
-        let node = fm?.activeElement ?? null;
+        if (fm === null)
+            return;
+        let node = fm.activeElement ?? null;
         while (node !== null && node !== this) {
             node = node.getParent();
         }
@@ -569,13 +573,19 @@ export class TUIElement {
             const vars = this.styleVarsValue !== null ? extendVarScope(context.vars, this.styleVarsValue) : context.vars;
             this.varScopeRef = vars;
             const describe = () => this.describeForStyleError();
-            const fg = applied.fg !== undefined
-                ? resolveStyleColor(applied.fg, context.fg, context.bg, vars, describe)
-                : context.fg;
-            const bg = applied.bg !== undefined
+            // Цвет с альфой композитится уже здесь, с унаследованным bg: в
+            // resolvedStyle и детям уходят непрозрачные значения, иначе заливка
+            // фона и текст с тем же bg наложились бы на ячейку дважды.
+            const ownBg = applied.bg !== undefined
                 ? resolveStyleColor(applied.bg, context.fg, context.bg, vars, describe)
                 : context.bg;
+            const bg = compositeOver(ownBg, context.bg);
+            const ownFg = applied.fg !== undefined
+                ? resolveStyleColor(applied.fg, context.fg, context.bg, vars, describe)
+                : context.fg;
+            const fg = compositeOver(ownFg, bg);
             this.resolvedStyleValue = { fg, bg };
+            this.paintsOwnBackgroundValue = applied.bg !== undefined && ownBg !== TRANSPARENT_COLOR;
             this.childStyleContext = this.buildChildStyleContext(context);
         }
         this.isStyleDirty = false;
@@ -634,15 +644,16 @@ export class TUIElement {
      * предков и дефолтов tuidom (STYLE_TOKEN_DEFAULTS). Обычное место — корень:
      * хост транслирует сюда палитру темы одним вызовом (hot-swap = повторный
      * вызов). Таблица заменяется целиком, null — снимает. Значения — только
-     * конкретные числа (packed RGB | DEFAULT_COLOR); сентинелы INHERITED_*
-     * нелегальны.
+     * конкретные числа (packed RGB, в том числе с альфой — `packRgba`/
+     * `parseHexColor`, | DEFAULT_COLOR | TRANSPARENT_COLOR); сентинелы
+     * INHERITED_* нелегальны.
      */
     setStyleVars(vars) {
         if (vars === this.styleVarsValue)
             return;
         if (vars !== null) {
             for (const key of Object.keys(vars)) {
-                if (vars[key] < DEFAULT_COLOR) {
+                if (!isColorValue(vars[key])) {
                     throw new Error(`${this.describeForStyleError()}.setStyleVars: токен "${key}" содержит сентинел/некорректное значение ${vars[key]} — таблицы принимают только конкретные цвета`);
                 }
             }
@@ -731,6 +742,7 @@ export class TUIElement {
      * состояние нужно ДО стилевого прохода, прямо в performLayout.
      */
     hasStyleStateWithin(state) {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
         let node = this;
         while (node !== null) {
             if (node.styleStatesSet?.has(state) === true)
@@ -769,6 +781,7 @@ export class TUIElement {
         // цепочка предков (иначе любой markDirty = полноэкранный damage).
         this.isPaintDirty = true;
         this.isLayoutDirty = true;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
         let top = this;
         for (let current = this._parent; current !== null; current = current._parent) {
             current.isLayoutDirty = true;
@@ -802,7 +815,11 @@ export class TUIElement {
         }
         const rect = new Rect(new Point(parentOrigin.x + this.localPosition.dx, parentOrigin.y + this.localPosition.dy), this.allocatedSize);
         const old = this.lastPaintedRect;
-        const moved = old === null ||
+        // Ещё не рисовался — тоже moved. Optional chain здесь не подходит: после
+        // первого `old?.x` тип уже сужен, и остальные `old?.` стали бы лишними.
+        const moved = 
+        // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+        old === null ||
             old.x !== rect.x ||
             old.y !== rect.y ||
             old.width !== rect.width ||
@@ -835,6 +852,9 @@ export class TUIElement {
      * собственный хром по состоянию ребёнка вне его rect'а (ScrollBarDecorator:
      * бегунок в колонке за пределами ребёнка).
      */
+    // Именно геттер, не readonly-поле: подклассы переопределяют его геттером
+    // (ListViewElement, ScrollContainerElement), а поле базы затенило бы их прототипный аксессор.
+    // eslint-disable-next-line @typescript-eslint/class-literal-property-style
     get paintsSubtreeAtomically() {
         return false;
     }
@@ -1090,9 +1110,13 @@ export class TUIElement {
      * флагов стиля: собственный фон — это новая поверхность, и атрибуты того,
      * что нарисовано под ней раньше в этом кадре (подчёркивание диагностики под
      * попапом, жирный токен под диалогом), на ней проступать не должны.
+     *
+     * Полупрозрачный собственный bg уже скомпозичен каскадом с унаследованным
+     * (см. {@link performStyleResolution}); `TRANSPARENT_COLOR` (`#RRGGBB00`)
+     * считается «фона нет» — как CSS `transparent`, элемент ничего не красит.
      */
     paintOwnBackground(context) {
-        if (this.appliedBgValue === undefined)
+        if (!this.paintsOwnBackgroundValue)
             return;
         const { fg, bg } = this.resolvedStyleValue;
         const { width, height } = this.layoutSize;
@@ -1104,7 +1128,7 @@ export class TUIElement {
     }
     /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */
     get hasOwnBackground() {
-        return this.appliedBgValue !== undefined;
+        return this.paintsOwnBackgroundValue;
     }
     /**
      * Сырые цвета после when-merge, до резолва токенов/сентинелов: что элемент

package/dist/input/keyInputParser.js

@@ -1,6 +1,6 @@
 import { convertTokenToKeyPressEvent } from "./convertToken.js";
 import { createKeyPressEvent } from "./keyEvent.js";
-import { parseCSI, parseOSC, tokenize } from "./tokenize.js";
+import { parseCSI, parseOSC, parseXtversionReply, tokenize, XTVERSION_REPLY_PREFIX } from "./tokenize.js";
 /**
  * Index where an *incomplete* trailing escape sequence begins, or -1 if `data`
  * ends on a clean token boundary.
@@ -16,6 +16,12 @@ import { parseCSI, parseOSC, tokenize } from "./tokenize.js";
  * incomplete — anything before it is already followed by more bytes.
  */
 function incompleteTailStart(data) {
+    // Ответ XTVERSION (`ESC P > | … ESC \\`) — единственная строка, внутри которой
+    // может стоять «последний» ESC (от ST, разрезанного между чтениями), поэтому тело
+    // без терминатора проверяем раньше, чем ищем последний ESC.
+    const dcs = data.lastIndexOf(XTVERSION_REPLY_PREFIX);
+    if (dcs !== -1 && parseXtversionReply(data, dcs) === null)
+        return dcs;
     const esc = data.lastIndexOf("\x1b");
     if (esc === -1)
         return -1;
@@ -30,6 +36,10 @@ function incompleteTailStart(data) {
         return parseOSC(data, esc) === null ? esc : -1; // ESC ]
     if (next === 0x4f)
         return esc + 2 >= data.length ? esc : -1; // ESC O (SS3) needs its final letter
+    // ESC P: незавершённое начало ответа XTVERSION (`ESC P >`) ждём. Хвост, уже
+    // разошедшийся с префиксом, — обычный Alt+Shift+P (ESC + символ), он завершён.
+    if (next === 0x50)
+        return XTVERSION_REPLY_PREFIX.startsWith(data.slice(esc)) ? esc : -1;
     // ESC + printable / control / special is complete once the second byte is present (it is).
     return -1;
 }

package/dist/input/rawTerminalToken.d.ts

@@ -111,18 +111,24 @@ export interface OscToken {
     readonly raw: string;
 }
 /**
- * A private-mode CSI response to one of our capability probes — NOT a key event.
+ * A response to one of our capability probes — NOT a key event.
  *  - "kitty-flags": reply to the Kitty keyboard-protocol query `CSI ? u` → `CSI ? <flags> u`.
  *  - "da1":         reply to Primary Device Attributes `CSI c` → `CSI ? <attrs> c`.
- * These begin with the private marker `?`, which never appears in a real key event.
+ *  - "xtversion":   reply to XTVERSION `CSI > 0 q` → `DCS > | <name(version)> ST`.
+ * The CSI replies begin with the private marker `?`, which never appears in a real key
+ * event; the XTVERSION reply is a DCS string (`ESC P > |`), not a key either.
  */
 export interface DeviceReportToken {
     readonly kind: "device-report";
-    readonly report: "kitty-flags" | "da1";
-    /** Raw parameter bytes including the leading `?` (e.g. "?15" or "?62;1;6"). */
+    readonly report: DeviceReportKind;
+    /**
+     * For CSI replies — raw parameter bytes including the leading `?` (e.g. "?15" or
+     * "?62;1;6"). For "xtversion" — the payload between `DCS > |` and ST (e.g. "iTerm2 3.5.0").
+     */
     readonly params: string;
     readonly raw: string;
 }
+export type DeviceReportKind = "kitty-flags" | "da1" | "xtversion";
 export type MouseButton = "left" | "middle" | "right" | "none";
 export type MouseAction = "press" | "release" | "move" | "scroll-up" | "scroll-down" | "scroll-left" | "scroll-right";
 export interface MouseToken {

package/dist/input/serializeKey.d.ts

@@ -8,7 +8,10 @@
  *   serializeKey('Ctrl+ArrowUp')   → '\x1b[1;5A'
  *   serializeKey('F5')             → '\x1b[15~'
  *   serializeKey('Alt+a')          → '\x1ba'
+ *   serializeKey('Meta+s')         → '\x1b[115;9u'
+ *   serializeKey('Ctrl+Shift+a')   → '\x1b[97;6u'
  *
  * Supports modifier prefixes: Ctrl+, Shift+, Alt+, Meta+ (combinable).
+ * Meta — это super-бит kitty (8): так приходит Cmd на маке.
  */
 export declare function serializeKey(name: string): string;

package/dist/input/serializeKey.js

@@ -8,9 +8,13 @@
  *   serializeKey('Ctrl+ArrowUp')   → '\x1b[1;5A'
  *   serializeKey('F5')             → '\x1b[15~'
  *   serializeKey('Alt+a')          → '\x1ba'
+ *   serializeKey('Meta+s')         → '\x1b[115;9u'
+ *   serializeKey('Ctrl+Shift+a')   → '\x1b[97;6u'
  *
  * Supports modifier prefixes: Ctrl+, Shift+, Alt+, Meta+ (combinable).
+ * Meta — это super-бит kitty (8): так приходит Cmd на маке.
  */
+import { kittyCodepointMap } from "./tokenize.js";
 /** Simple special keys (no modifiers, no CSI) */
 const simpleSpecialKeys = {
     Enter: "\x0d",
@@ -73,6 +77,24 @@ function encodeModifier(ctrl, shift, alt, meta) {
         mod += 8;
     return mod;
 }
+/**
+ * Codepoint для общей CSI u-формы, если `ch` — один печатный символ, который
+ * parseInput вернёт как есть: не управляющий и не занятый kitty под
+ * функциональную клавишу (PUA). Буква сворачивается в нижний регистр — так
+ * kitty шлёт базовую клавишу; регистр в событии даёт Shift-бит.
+ */
+function printableCodepoint(ch) {
+    const lower = ch.toLowerCase();
+    const codepoint = lower.codePointAt(0);
+    // Пусто («Meta+»), имя клавиши («Foo») или буква, чей lowercase — не один символ («İ»).
+    if (codepoint === undefined || String.fromCodePoint(codepoint) !== lower)
+        return undefined;
+    if (codepoint < 0x20 || (codepoint >= 0x7f && codepoint <= 0x9f))
+        return undefined;
+    if (kittyCodepointMap[codepoint] !== undefined)
+        return undefined;
+    return codepoint;
+}
 export function serializeKey(name) {
     // Parse modifier prefixes: "Ctrl+Shift+ArrowUp" → modifiers + "ArrowUp"
     let ctrl = false;
@@ -175,5 +197,15 @@ export function serializeKey(name) {
     if (!hasModifiers && remaining.length === 1) {
         return remaining;
     }
+    // Печатный символ с любым другим набором модификаторов — общая форма kitty
+    // CSI <codepoint>;<mod>u. Сюда доходят только комбинации, у которых нет
+    // legacy-кодировки (ветки выше их уже вернули): Meta+s, Ctrl+Shift+a, Shift+1…
+    // Как и kitty, шлём codepoint базовой клавиши: буква — в нижнем регистре, а
+    // регистр задаёт только Shift-префикс (Meta+S ≡ Meta+s, как Ctrl+A ≡ Ctrl+a).
+    const codepoint = printableCodepoint(remaining === "Space" ? " " : remaining);
+    if (codepoint !== undefined) {
+        const mod = encodeModifier(ctrl, shift, alt, meta);
+        return `\x1b[${codepoint.toString()};${mod.toString()}u`;
+    }
     throw new Error(`serializeKey: unknown key name "${name}". Add it to the mapping.`);
 }

package/dist/input/tokenize.d.ts

@@ -56,4 +56,17 @@ interface OSCTokenResult {
  * Returns null if the sequence is not complete.
  */
 export declare function parseOSC(data: string, start: number): OSCTokenResult | null;
+/**
+ * Начало ответа на XTVERSION (`CSI > 0 q`): `DCS > |`. Разбираем только его: голое
+ * `ESC P` — это ещё и Alt+Shift+P legacy-терминала, так что произвольный DCS не ловим.
+ */
+export declare const XTVERSION_REPLY_PREFIX = "\u001BP>|";
+/**
+ * Parse an XTVERSION reply `ESC P > | <text> ESC \` starting at data[start] = ESC.
+ * Returns null if the string terminator (ST) hasn't arrived yet.
+ */
+export declare function parseXtversionReply(data: string, start: number): {
+    token: DeviceReportToken;
+    nextIndex: number;
+} | null;
 export {};

package/dist/input/tokenize.js

@@ -57,6 +57,18 @@ export function tokenize(data) {
                 tokens.push({ kind: "standalone-esc", raw: data[i] });
                 i++;
             }
+            else if (next === 0x50 && data.startsWith(XTVERSION_REPLY_PREFIX, i)) {
+                // DCS-ответ на XTVERSION: \x1bP>|<name(version)>\x1b\\. Без ST (обрезан, и
+                // KeyInputParser его уже не ждёт) — падаем в ESC+символ, как было до разбора DCS.
+                const dcsResult = parseXtversionReply(data, i);
+                if (dcsResult) {
+                    tokens.push(dcsResult.token);
+                    i = dcsResult.nextIndex;
+                    continue;
+                }
+                tokens.push({ kind: "esc-char", char: data[i + 1], charCode: next, raw: data.slice(i, i + 2) });
+                i += 2;
+            }
             else if (next === 0x4f) {
                 // SS3 sequence: \x1bO<letter>
                 if (i + 2 < data.length) {
@@ -679,3 +691,29 @@ function buildOscResult(body, raw, nextIndex) {
         nextIndex,
     };
 }
+// ─── DCS: XTVERSION reply ───
+/**
+ * Начало ответа на XTVERSION (`CSI > 0 q`): `DCS > |`. Разбираем только его: голое
+ * `ESC P` — это ещё и Alt+Shift+P legacy-терминала, так что произвольный DCS не ловим.
+ */
+export const XTVERSION_REPLY_PREFIX = "\x1bP>|";
+/**
+ * Parse an XTVERSION reply `ESC P > | <text> ESC \` starting at data[start] = ESC.
+ * Returns null if the string terminator (ST) hasn't arrived yet.
+ */
+export function parseXtversionReply(data, start) {
+    const bodyStart = start + XTVERSION_REPLY_PREFIX.length;
+    const end = data.indexOf("\x1b\\", bodyStart);
+    if (end === -1)
+        return null;
+    const nextIndex = end + 2;
+    return {
+        token: {
+            kind: "device-report",
+            report: "xtversion",
+            params: data.slice(bodyStart, end),
+            raw: data.slice(start, nextIndex),
+        },
+        nextIndex,
+    };
+}

package/dist/rendering/grid.d.ts

@@ -15,6 +15,12 @@ export interface CellPatch {
 }
 /**
  * 2D grid of terminal cells backed by a flat array for cache-friendly access.
+ *
+ * Ячейки хранят только непрозрачные цвета (или DEFAULT_COLOR): цвет с альфой,
+ * пришедший в {@link setCell}/{@link updateCell}, композитится с текущим
+ * содержимым ячейки на месте (см. `compositeOver`). Так порядок отрисовки —
+ * родитель, дети, оверлеи, патчи подсветок — становится порядком наложения
+ * слоёв, как в браузере, а бэкенды/снапшоты/SVG видят уже готовые цвета.
  */
 export declare class Grid {
     readonly size: Size;

package/dist/rendering/grid.js

@@ -1,9 +1,15 @@
-import { DEFAULT_COLOR } from "../common/colorUtils.js";
+import { compositeOver, 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.
+ *
+ * Ячейки хранят только непрозрачные цвета (или DEFAULT_COLOR): цвет с альфой,
+ * пришедший в {@link setCell}/{@link updateCell}, композитится с текущим
+ * содержимым ячейки на месте (см. `compositeOver`). Так порядок отрисовки —
+ * родитель, дети, оверлеи, патчи подсветок — становится порядком наложения
+ * слоёв, как в браузере, а бэкенды/снапшоты/SVG видят уже готовые цвета.
  */
 export class Grid {
     size;
@@ -55,8 +61,8 @@ export class Grid {
             /* v8 ignore stop */
         }
         cell.char = char;
-        cell.fg = fg;
-        cell.bg = bg;
+        cell.bg = compositeOver(bg, cell.bg);
+        cell.fg = compositeOver(fg, cell.bg);
         cell.style = style;
         cell.width = width;
         // For wide chars, set up the continuation cell
@@ -73,8 +79,8 @@ export class Grid {
                 /* v8 ignore stop */
             }
             cont.char = "";
-            cont.fg = fg;
-            cont.bg = bg;
+            cont.fg = cell.fg;
+            cont.bg = cell.bg;
             cont.style = style;
             cont.width = 0;
         }
@@ -108,10 +114,13 @@ export class Grid {
         }
         if (patch.char !== undefined)
             cell.char = patch.char;
-        if (patch.fg !== undefined)
-            cell.fg = patch.fg;
+        // Композитинг в порядке отрисовки: полупрозрачный bg ложится на то, что
+        // уже лежит в ячейке в этом кадре, полупрозрачный fg — на итоговый bg.
+        // Непрозрачные цвета проходят как раньше (compositeOver — одно сравнение).
         if (patch.bg !== undefined)
-            cell.bg = patch.bg;
+            cell.bg = compositeOver(patch.bg, cell.bg);
+        if (patch.fg !== undefined)
+            cell.fg = compositeOver(patch.fg, cell.bg);
         if (patch.style !== undefined)
             cell.style = patch.style;
         if (patch.width !== undefined)
@@ -132,10 +141,11 @@ export class Grid {
             }
             cont.char = "";
             cont.width = 0;
+            // Продолжение — та же ячейка: берёт уже скомпозиченные цвета головы.
             if (patch.fg !== undefined)
-                cont.fg = patch.fg;
+                cont.fg = cell.fg;
             if (patch.bg !== undefined)
-                cont.bg = patch.bg;
+                cont.bg = cell.bg;
             if (patch.style !== undefined)
                 cont.style = patch.style;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tuidom/core",
-    "version": "0.2.3",
+    "version": "0.4.0",
     "type": "module",
     "description": "Experimental terminal UI DOM — core: element tree, flex layout, grid rendering, input parsing. API is unstable.",
     "license": "MIT",