@tuidom/core 0.3.0 → 0.4.0

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;
@@ -571,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;
@@ -636,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]} — таблицы принимают только конкретные цвета`);
                 }
             }
@@ -1101,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;
@@ -1115,7 +1128,7 @@ export class TUIElement {
     }
     /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */
     get hasOwnBackground() {
-        return this.appliedBgValue !== undefined;
+        return this.paintsOwnBackgroundValue;
     }
     /**
      * Сырые цвета после when-merge, до резолва токенов/сентинелов: что элемент

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.3.0",
+    "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",