@tuidom/core 0.3.0 → 0.5.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/overlayLayer.d.ts

@@ -41,6 +41,13 @@ export interface OverlaySessionOptions {
      * (владелец обработает Escape сам — например закроет только верхнее подменю).
      */
     shouldCloseOnEscape?: () => boolean;
+    /**
+     * Рисовать тень под оверлеем (`TUIElement.shadow`, цвет `widget.shadow`) —
+     * TUI-аналог box-shadow попапов VS Code. Выключено по умолчанию у всех
+     * сессий, включая меню tuidom: включает хост. Не задано — остаётся
+     * `element.shadow` как выставил владелец.
+     */
+    shadow?: boolean;
 }
 export interface OverlaySessionHandle {
     readonly element: TUIElement;

package/dist/dom/overlayLayer.js

@@ -1,4 +1,4 @@
-import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
+import { BoxConstraints, Point, Size } from "../common/geometryPromitives.js";
 import { RenderContext, TUIElement } from "./tuiElement.js";
 export class OverlayLayer extends TUIElement {
     items = [];
@@ -42,6 +42,8 @@ export class OverlayLayer extends TUIElement {
     createSession(element, position, options) {
         this.disposeSessionByElement(element);
         const initialVisible = options.visible ?? false;
+        if (options.shadow !== undefined)
+            element.shadow = options.shadow;
         this.addItem(element, position, false);
         const session = {
             element,
@@ -201,15 +203,9 @@ export class OverlayLayer extends TUIElement {
                 continue;
             // Позиция — из localPosition (её выставил layoutChild), не из
             // item.position: после layout авторитетна геометрия элемента (Н5).
-            // Клип по границам ребёнка — инвариант отрисовки (Н2): нарисованное
-            // не выходит за layoutSize, хит-зона совпадает с видимым.
-            const child = item.element;
-            const childOffset = new Offset(child.localPosition.dx, child.localPosition.dy);
-            const clip = new Rect(child.globalPosition, child.layoutSize);
-            const childContext = context.withOffset(childOffset).withClip(clip);
-            if (childContext.clipRect.isEmpty)
-                continue;
-            child.render(childContext);
+            // Клип по границам ребёнка и тень за ним — общий renderChild (Н2):
+            // нарисованное не выходит за layoutSize, хит-зона совпадает с видимым.
+            this.renderChild(context, item.element);
         }
     }
     openSession(session) {

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

@@ -72,6 +72,7 @@ export declare const STYLE_TOKEN_DEFAULTS: {
     "editorSuggestWidget.selectedForeground": number;
     "editorSuggestWidget.iconForeground": number;
     "editorSuggestWidget.detailForeground": number;
+    "widget.shadow": number;
     "editorWidget.foreground": number;
     "editorWidget.background": number;
     "editorWidget.border": number;

package/dist/dom/styles/styleTokens.js

@@ -1,4 +1,4 @@
-import { DEFAULT_COLOR, packRgb } from "../../common/colorUtils.js";
+import { DEFAULT_COLOR, packRgb, packRgba } from "../../common/colorUtils.js";
 /**
  * Дефолтные значения цветовых токенов tuidom — единственное место, где у
  * виджетов tuidom/ui есть RGB-литералы. Правило: токен, на который ссылается
@@ -85,6 +85,10 @@ export const STYLE_TOKEN_DEFAULTS = {
     "editorSuggestWidget.selectedForeground": packRgb(255, 255, 255),
     "editorSuggestWidget.iconForeground": packRgb(130, 170, 255),
     "editorSuggestWidget.detailForeground": packRgb(120, 120, 130),
+    // ── Оверлеи ──
+    // Тень попапа (`TUIElement.shadow`): полупрозрачный чёрный, композитится с
+    // тем, что под ним. Значение — дефолт VS Code для тёмных тем (`#00000059`).
+    "widget.shadow": packRgba(0, 0, 0, 0x59),
     // ── Виджеты редактора (диалоги, find) ──
     "editorWidget.foreground": packRgb(204, 204, 204),
     "editorWidget.background": packRgb(37, 37, 38),

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;
@@ -182,6 +184,25 @@ export declare class TUIElement {
     get hidden(): boolean;
     set hidden(value: boolean);
     private hiddenValue;
+    /**
+     * Тень оверлея — TUI-аналог `box-shadow` VS Code: колонка справа и строка
+     * снизу от элемента (сдвиг 1×1) затемняются цветом `widget.shadow`
+     * (с альфой, композитится с тем, что уже нарисовано). Рисует не сам
+     * элемент, а его родитель после него ({@link renderChildren},
+     * `OverlayLayer.render`): клип ребёнка не выпускает его за собственный
+     * rect (Н2), а тень лежит снаружи. Damage-обход учитывает её через
+     * {@link paintOutset}. Отдаёт форму оверлею там, где тема рисует рамку
+     * цветом фона (Catppuccin: `menu.border` = фон меню).
+     *
+     * Рисуют её канонические циклы — {@link renderChildren} и
+     * `OverlayLayer.render` (оба через {@link renderChild}). Контейнеры со своим
+     * циклом (`SizedBoxElement`, `ScrollViewport`, строки списка) ребёнка
+     * растягивают на весь свой rect — тени там некуда лечь, она осталась бы за
+     * клипом самого контейнера.
+     */
+    get shadow(): boolean;
+    set shadow(value: boolean);
+    private shadowValue;
     /** Прикрепляет ребёнка в конец списка (снимая с прежнего родителя). */
     protected appendChild(child: TUIElement): void;
     /** Прикрепляет ребёнка на позицию index (снимая с прежнего родителя). */
@@ -283,8 +304,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;
     /**
@@ -360,6 +382,11 @@ export declare class TUIElement {
      * запустило бы lazy-layout с мусорными constraints).
      */
     collectDamage(sink: DamageList, parentOrigin: Point): void;
+    /**
+     * На сколько ячеек вправо и вниз родитель рисует за границей элемента
+     * (тень, см. {@link shadow}). Damage-rect элемента расширяется на столько же.
+     */
+    protected get paintOutset(): number;
     /** Обход детей damage-сбора — seam для контейнеров с нестандартной структурой. */
     protected collectChildrenDamage(sink: DamageList, origin: Point): void;
     /**
@@ -503,6 +530,10 @@ export declare class TUIElement {
      * флагов стиля: собственный фон — это новая поверхность, и атрибуты того,
      * что нарисовано под ней раньше в этом кадре (подчёркивание диагностики под
      * попапом, жирный токен под диалогом), на ней проступать не должны.
+     *
+     * Полупрозрачный собственный bg уже скомпозичен каскадом с унаследованным
+     * (см. {@link performStyleResolution}); `TRANSPARENT_COLOR` (`#RRGGBB00`)
+     * считается «фона нет» — как CSS `transparent`, элемент ничего не красит.
      */
     protected paintOwnBackground(context: RenderContext): void;
     /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */
@@ -522,6 +553,32 @@ export declare class TUIElement {
      * самый цикл, который раньше был скопирован в десяток контейнеров.
      */
     protected renderChildren(context: RenderContext): void;
+    /**
+     * Отрисовка одного ребёнка в контексте родителя: сдвиг на localPosition,
+     * клип по границам ребёнка, затем его тень (см. {@link shadow}) — уже в
+     * контексте родителя, потому что она лежит за клипом ребёнка. Тень не
+     * зависит от того, попал ли сам ребёнок в клип: damage-rect может задеть
+     * только полосу тени (перерисовался виджет под ней), и тогда ребёнок
+     * пропускается, а тень обязана лечь заново.
+     */
+    protected renderChild(context: RenderContext, child: TUIElement): void;
+    /**
+     * Тень ребёнка (см. {@link shadow}) в контексте РОДИТЕЛЯ: колонка справа
+     * (x = right, строки top+1…bottom) и строка снизу (y = bottom, колонки
+     * left+1…right) — классический сдвиг 1×1. Ячейка затемняется цветом
+     * `widget.shadow` из var-scope ребёнка: bg композитит грид, fg — здесь
+     * (грид кладёт fg с альфой на bg, а не на прежний fg); терминальный
+     * DEFAULT_COLOR у fg не трогаем — смешивать не с чем.
+     *
+     * Широкий глиф (CJK, эмодзи) наполовину не красится: голова тянет цвета в
+     * продолжение (`Grid.updateCell`), поэтому глиф под кромкой тени
+     * затемняется целиком — тень на этой строке шире на колонку. Продолжение
+     * в полосе пропускается: его голова либо сама в полосе (уже покрашена —
+     * иначе двойная тень), либо внутри ребёнка (его глиф у правой кромки).
+     * Единственное исключение — голова в пропущенном нижнем левом углу: такой
+     * глиф красится целиком через голову.
+     */
+    protected paintChildShadow(context: RenderContext, child: TUIElement): void;
     /**
      * Финальный шаблон хит-теста — НЕ переопределять (кастомизация — через
      * {@link hitTestChildren}/{@link hitTestSelf}): скрытое не кликается,

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;
@@ -310,6 +312,32 @@ export class TUIElement {
         this.markDirty();
     }
     hiddenValue = false;
+    /**
+     * Тень оверлея — TUI-аналог `box-shadow` VS Code: колонка справа и строка
+     * снизу от элемента (сдвиг 1×1) затемняются цветом `widget.shadow`
+     * (с альфой, композитится с тем, что уже нарисовано). Рисует не сам
+     * элемент, а его родитель после него ({@link renderChildren},
+     * `OverlayLayer.render`): клип ребёнка не выпускает его за собственный
+     * rect (Н2), а тень лежит снаружи. Damage-обход учитывает её через
+     * {@link paintOutset}. Отдаёт форму оверлею там, где тема рисует рамку
+     * цветом фона (Catppuccin: `menu.border` = фон меню).
+     *
+     * Рисуют её канонические циклы — {@link renderChildren} и
+     * `OverlayLayer.render` (оба через {@link renderChild}). Контейнеры со своим
+     * циклом (`SizedBoxElement`, `ScrollViewport`, строки списка) ребёнка
+     * растягивают на весь свой rect — тени там некуда лечь, она осталась бы за
+     * клипом самого контейнера.
+     */
+    get shadow() {
+        return this.shadowValue;
+    }
+    set shadow(value) {
+        if (this.shadowValue === value)
+            return;
+        this.shadowValue = value;
+        this.markDirty();
+    }
+    shadowValue = false;
     /** Прикрепляет ребёнка в конец списка (снимая с прежнего родителя). */
     appendChild(child) {
         this.insertChild(this.childrenList.length, child);
@@ -571,13 +599,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 +670,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]} — таблицы принимают только конкретные цвета`);
                 }
             }
@@ -804,7 +839,11 @@ export class TUIElement {
             this.hasPaintDirtyDescendant = false;
             return;
         }
-        const rect = new Rect(new Point(parentOrigin.x + this.localPosition.dx, parentOrigin.y + this.localPosition.dy), this.allocatedSize);
+        // Rect для damage — с outset'ом: тень родитель рисует за границей
+        // allocatedSize, и её ячейки тоже должны перерисоваться при переезде,
+        // скрытии и paint-dirty.
+        const outset = this.paintOutset;
+        const rect = new Rect(new Point(parentOrigin.x + this.localPosition.dx, parentOrigin.y + this.localPosition.dy), new Size(this.allocatedSize.width + outset, this.allocatedSize.height + outset));
         const old = this.lastPaintedRect;
         // Ещё не рисовался — тоже moved. Optional chain здесь не подходит: после
         // первого `old?.x` тип уже сужен, и остальные `old?.` стали бы лишними.
@@ -830,6 +869,13 @@ export class TUIElement {
         if (descend)
             this.collectChildrenDamage(sink, rect.origin);
     }
+    /**
+     * На сколько ячеек вправо и вниз родитель рисует за границей элемента
+     * (тень, см. {@link shadow}). Damage-rect элемента расширяется на столько же.
+     */
+    get paintOutset() {
+        return this.shadowValue ? 1 : 0;
+    }
     /** Обход детей damage-сбора — seam для контейнеров с нестандартной структурой. */
     collectChildrenDamage(sink, origin) {
         for (const child of this.childrenList)
@@ -1101,9 +1147,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 +1165,7 @@ export class TUIElement {
     }
     /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */
     get hasOwnBackground() {
-        return this.appliedBgValue !== undefined;
+        return this.paintsOwnBackgroundValue;
     }
     /**
      * Сырые цвета после when-merge, до резолва токенов/сентинелов: что элемент
@@ -1134,16 +1184,75 @@ export class TUIElement {
         for (const child of this.getChildren()) {
             if (child.hidden)
                 continue;
-            const offset = new Offset(child.localPosition.dx, child.localPosition.dy);
-            const clip = new Rect(child.globalPosition, child.layoutSize);
-            const childContext = context.withOffset(offset).withClip(clip);
-            // Пустой клип — ребёнок целиком вне отрисовываемой области: пропуск
-            // всего поддерева, включая side-эффекты его render.
-            if (childContext.clipRect.isEmpty)
-                continue;
-            child.render(childContext);
+            this.renderChild(context, child);
         }
     }
+    /**
+     * Отрисовка одного ребёнка в контексте родителя: сдвиг на localPosition,
+     * клип по границам ребёнка, затем его тень (см. {@link shadow}) — уже в
+     * контексте родителя, потому что она лежит за клипом ребёнка. Тень не
+     * зависит от того, попал ли сам ребёнок в клип: damage-rect может задеть
+     * только полосу тени (перерисовался виджет под ней), и тогда ребёнок
+     * пропускается, а тень обязана лечь заново.
+     */
+    renderChild(context, child) {
+        const offset = new Offset(child.localPosition.dx, child.localPosition.dy);
+        const clip = new Rect(child.globalPosition, child.layoutSize);
+        const childContext = context.withOffset(offset).withClip(clip);
+        // Пустой клип — ребёнок целиком вне отрисовываемой области: пропуск
+        // всего поддерева, включая side-эффекты его render.
+        if (!childContext.clipRect.isEmpty)
+            child.render(childContext);
+        if (child.shadow)
+            this.paintChildShadow(context, child);
+    }
+    /**
+     * Тень ребёнка (см. {@link shadow}) в контексте РОДИТЕЛЯ: колонка справа
+     * (x = right, строки top+1…bottom) и строка снизу (y = bottom, колонки
+     * left+1…right) — классический сдвиг 1×1. Ячейка затемняется цветом
+     * `widget.shadow` из var-scope ребёнка: bg композитит грид, fg — здесь
+     * (грид кладёт fg с альфой на bg, а не на прежний fg); терминальный
+     * DEFAULT_COLOR у fg не трогаем — смешивать не с чем.
+     *
+     * Широкий глиф (CJK, эмодзи) наполовину не красится: голова тянет цвета в
+     * продолжение (`Grid.updateCell`), поэтому глиф под кромкой тени
+     * затемняется целиком — тень на этой строке шире на колонку. Продолжение
+     * в полосе пропускается: его голова либо сама в полосе (уже покрашена —
+     * иначе двойная тень), либо внутри ребёнка (его глиф у правой кромки).
+     * Единственное исключение — голова в пропущенном нижнем левом углу: такой
+     * глиф красится целиком через голову.
+     */
+    paintChildShadow(context, child) {
+        const color = child.styleVar("widget.shadow");
+        if (color === TRANSPARENT_COLOR)
+            return;
+        const left = child.localPosition.dx;
+        const top = child.localPosition.dy;
+        const right = left + child.layoutSize.width;
+        const bottom = top + child.layoutSize.height;
+        const shadeCell = (x, y, cell) => {
+            context.setCell(x, y, { bg: color, fg: cell.fg < 0 ? cell.fg : compositeOver(color, cell.fg) });
+        };
+        const shade = (x, y, wholeGlyph) => {
+            const cell = context.getCell(x, y);
+            if (cell === null)
+                return;
+            if (cell.width !== 0) {
+                shadeCell(x, y, cell);
+                return;
+            }
+            if (!wholeGlyph)
+                return;
+            const head = context.getCell(x - 1, y);
+            if (head === null)
+                return;
+            shadeCell(x - 1, y, head);
+        };
+        for (let y = top + 1; y <= bottom; y++)
+            shade(right, y, false);
+        for (let x = left + 1; x < right; x++)
+            shade(x, bottom, x === left + 1);
+    }
     // ─── Hit-testing ───
     //
     // Правило системы (Н6): рендер и Tab обходят детей ВПЕРЁД, хит-тест — тем

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.5.0",
     "type": "module",
     "description": "Experimental terminal UI DOM — core: element tree, flex layout, grid rendering, input parsing. API is unstable.",
     "license": "MIT",