@tuidom/core 0.1.0

package/dist/dom/tuiElement.d.ts

@@ -0,0 +1,528 @@
+import { DisplayLine } from "../common/displayLine.js";
+import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
+import type { DamageList } from "../rendering/damage.js";
+import type { CellPatch, ReadonlyCellData } from "../rendering/grid.js";
+import { TerminalScreen } from "../rendering/terminalScreen.js";
+import { type BorderStyle } from "./borderStyle.js";
+import type { FocusManager } from "./events/focusManager.js";
+import { TUIEventBase } from "./events/tuiEventBase.js";
+import type { TUIFocusEvent } from "./events/tuiFocusEvent.js";
+import { TUIKeyboardEvent } from "./events/tuiKeyboardEvent.js";
+import type { TUIMouseEvent } from "./events/tuiMouseEvent.js";
+import type { TUIPasteEvent } from "./events/tuiPasteEvent.js";
+import type { OverlayLayer } from "./overlayLayer.js";
+import type { AnyStyleToken } from "./styles/styleTokens.js";
+import type { ResolvedTUIStyle, StyleColor, StyleResolutionContext, StyleState, TUIStyle } from "./styles/tuiStyle.js";
+export declare class RenderContext {
+    readonly canvas: TerminalScreen;
+    readonly offset: Offset;
+    readonly clipRect: Rect;
+    constructor(canvas: TerminalScreen, offset?: Offset, clipRect?: Rect);
+    withOffset(extra: Offset): RenderContext;
+    withClip(rect: Rect): RenderContext;
+    setCell(x: number, y: number, cell: CellPatch): void;
+    /**
+     * Читает уже отрисованную ячейку в локальных координатах (тот же оффсет и
+     * клип, что у {@link setCell}). Возвращает null вне клипа или вне экрана.
+     * Нужен пост-обработке вроде оверлея выделения в списках: прочитать ячейку,
+     * решить по её текущим цветам и патчнуть через {@link setCell}.
+     */
+    getCell(x: number, y: number): ReadonlyCellData | null;
+    setCursorPosition(x: number, y: number): void;
+    /**
+     * Render a text string at (x, y), handling wide chars, tabs, combining marks and emoji.
+     * Each column within [startCol, startCol + maxWidth) is rendered.
+     *
+     * @param x       Left screen column (local coordinates)
+     * @param y       Screen row (local coordinates)
+     * @param text    Raw text to render
+     * @param style   Optional cell style (fg, bg, style flags) applied to every cell
+     * @param options tabSize (default 4) and maxWidth (default: no limit);
+     *   displayLine — готовый DisplayLine, чтобы не сегментировать text заново
+     *   на каждом кадре; вызывающий гарантирует, что он построен из тех же
+     *   text/tabSize
+     * @returns Number of display columns written
+     */
+    drawText(x: number, y: number, text: string, style?: {
+        fg?: number;
+        bg?: number;
+        style?: number;
+    }, options?: {
+        tabSize?: number;
+        maxWidth?: number;
+        displayLine?: DisplayLine;
+        getStyle?: (offset: number) => {
+            fg?: number;
+            bg?: number;
+            style?: number;
+        } | undefined;
+    }): number;
+    /**
+     * Отрисовывает прямоугольную рамку box-drawing глифами — единый хелпер для
+     * всех бордер-виджетов (см. {@link BorderStyle}). Рисует углы, верхнюю/нижнюю
+     * горизонтали и боковые вертикали; строки из `separators` (offset от верха
+     * рамки, 1-based относительно `y`) рисуются как T-коннекторы `├───┤`.
+     *
+     * Координаты локальные (как у {@link drawText}). Клиппинг/оффсет применяются
+     * через {@link setCell}.
+     *
+     * @param x       Левый столбец рамки
+     * @param y       Верхняя строка рамки
+     * @param width   Ширина рамки в столбцах (>= 2)
+     * @param height  Высота рамки в строках (>= 2)
+     * @param options fg/bg, пресет `style` (по умолчанию {@link BORDER_ROUNDED} —
+     *                канонический стиль оверлеев Vexx), `fill` (залить фон внутри
+     *                рамки), `separators` (ряды-разделители)
+     */
+    drawBox(x: number, y: number, width: number, height: number, options?: {
+        fg?: number;
+        bg?: number;
+        style?: BorderStyle;
+        fill?: boolean;
+        separators?: readonly number[];
+    }): void;
+}
+export interface AddEventListenerOptions {
+    capture?: boolean;
+}
+export interface TUIElementEventMap {
+    keydown: TUIKeyboardEvent;
+    keyup: TUIKeyboardEvent;
+    keypress: TUIKeyboardEvent;
+    focus: TUIFocusEvent;
+    blur: TUIFocusEvent;
+    mousedown: TUIMouseEvent;
+    mouseup: TUIMouseEvent;
+    mousemove: TUIMouseEvent;
+    click: TUIMouseEvent;
+    dblclick: TUIMouseEvent;
+    mouseenter: TUIMouseEvent;
+    mouseleave: TUIMouseEvent;
+    wheel: TUIMouseEvent;
+    paste: TUIPasteEvent;
+}
+export declare class TUIElement {
+    private allocatedSize;
+    dirty: boolean;
+    layoutStyle: unknown;
+    layoutState: unknown;
+    id: string | undefined;
+    role: string | undefined;
+    focusable: boolean;
+    capturesPointer: boolean;
+    localPosition: Offset;
+    isLayoutDirty: boolean;
+    private isPaintDirty;
+    private hasPaintDirtyDescendant;
+    private lastPaintedRect;
+    private pendingDetachDamage;
+    protected _parent: TUIElement | null;
+    private isRootAnchor;
+    private requestRenderCallback;
+    focusManager: FocusManager | null;
+    private styleValue;
+    private resolvedStyleValue;
+    private isStyleDirty;
+    private subtreeStyleDirty;
+    private appliedFgValue;
+    private appliedBgValue;
+    private styleStatesSet;
+    private styleVarsValue;
+    private varScopeRef;
+    private childStyleContext;
+    get style(): Readonly<TUIStyle>;
+    set style(value: TUIStyle);
+    private _listeners;
+    /**
+     * Allocated visible area on screen, set by parent container via layout().
+     * Lazy fallback: if layout is dirty, triggers layout with loose constraints.
+     */
+    get layoutSize(): Size;
+    get isFocused(): boolean;
+    getParent(): TUIElement | null;
+    /**
+     * Абсолютная позиция элемента на экране — **производная** от цепочки
+     * родителей: `parent.globalPosition + localPosition`. Раньше это было поле,
+     * которое каждый контейнер обязан был выставлять руками параллельно с
+     * `localPosition` (LAYOUT.md честно писал «в корректном состоянии они
+     * равны») — забытая запись давала элемент, который рисуется, но не
+     * кликается. Теперь рассинхрон невозможен по построению.
+     *
+     * У отсоединённого элемента (parent=null) равна `localPosition` — так
+     * standalone-рендер в тестах может позиционировать элемент напрямую.
+     */
+    get globalPosition(): Point;
+    private childrenList;
+    getChildren(): readonly TUIElement[];
+    /**
+     * Видимость (аналог display:none): скрытый элемент ОСТАЁТСЯ в дереве —
+     * root и каскад стилей до него доходят, — но выпадает из hit-теста и
+     * Tab-обхода (базовые обходы), а контейнер не раскладывает и не рисует его.
+     * Это разводит «структуру» и «что сейчас видно», которые раньше смешивал
+     * getChildren(): контейнеры исключали скрытых детей из структуры и потом
+     * руками чинили пропагацию при показе (источник семейства багов #204).
+     */
+    get hidden(): boolean;
+    set hidden(value: boolean);
+    private hiddenValue;
+    /** Прикрепляет ребёнка в конец списка (снимая с прежнего родителя). */
+    protected appendChild(child: TUIElement): void;
+    /** Прикрепляет ребёнка на позицию index (снимая с прежнего родителя). */
+    protected insertChild(index: number, child: TUIElement): void;
+    /** Отцепляет ребёнка (no-op, если он не наш). */
+    protected removeChild(child: TUIElement): void;
+    /**
+     * Заменяет ребёнка, сохраняя позицию в списке — а значит z-порядок и место
+     * в Tab-обходе (важно слотовым контейнерам: content меняется, а overlay
+     * обязан остаться поверх).
+     */
+    protected replaceChild(oldChild: TUIElement, newChild: TUIElement): void;
+    /**
+     * Декларативно приводит список детей к заданному (слотовые контейнеры
+     * пересобирают канонический порядок одним вызовом). Лишние отцепляются,
+     * новые прикрепляются, порядок — как в next.
+     */
+    protected setChildren(next: readonly TUIElement[]): void;
+    /** Гасит фокус, если activeElement — этот элемент или его потомок. */
+    private releaseFocusIfInside;
+    /**
+     * Observable state for the inspector, self-described by the widget. The base
+     * returns `undefined` (no state to report); interactive widgets override to
+     * expose what a test would otherwise have to infer from rendered cells — an
+     * editor's cursor/selection/readonly, a panel's active tab, a quick-pick's
+     * items. Must be a plain JSON-serialisable snapshot, not live internals:
+     * it crosses the inspector wire and is a public contract (test it).
+     */
+    inspectState(): Record<string, unknown> | undefined;
+    /**
+     * Builds the path from root to this element (inclusive on both ends).
+     */
+    getAncestorPath(): TUIElement[];
+    /**
+     * Порядок Tab-обхода поддерева: фокусируемые (focusable) в глубину.
+     * Скрытые (hidden) поддеревья пропускаются целиком — Tab не должен уводить
+     * фокус в невидимый инпут (закрытый find-виджет, неактивная вкладка).
+     */
+    getDepthFirstFocusableOrder(): TUIElement[];
+    addEventListener<K extends keyof TUIElementEventMap>(type: K, handler: (event: TUIElementEventMap[K]) => void, options?: AddEventListenerOptions): void;
+    addEventListener(type: string, handler: (event: TUIEventBase) => void, options?: AddEventListenerOptions): void;
+    removeEventListener<K extends keyof TUIElementEventMap>(type: K, handler: (event: TUIElementEventMap[K]) => void, options?: AddEventListenerOptions): void;
+    removeEventListener(type: string, handler: (event: TUIEventBase) => void, options?: AddEventListenerOptions): void;
+    /**
+     * Dispatches event with capture → target → bubble phases (DOM-like).
+     * Returns true if preventDefault() was NOT called.
+     */
+    dispatchEvent(event: TUIEventBase): boolean;
+    /**
+     * Override in subclasses to define built-in element behavior (like opening a menu on click).
+     * Called after all capture/target/bubble listeners. Skipped if preventDefault() was called.
+     * Analogous to Web DOM default actions (e.g. <a> navigation, <input> text entry).
+     */
+    protected performDefaultAction(event: TUIEventBase): void;
+    /**
+     * Invoke listeners on an element for the given event.
+     * captureFilter: true = only capture, false = only bubble, null = both (target phase)
+     */
+    private _invokeListeners;
+    get resolvedStyle(): ResolvedTUIStyle;
+    /**
+     * Forces a style re-resolution of this element and its whole subtree (and
+     * schedules a render). Public so a container can refresh a subtree it just
+     * re-attached — e.g. a panel that was excluded from `getChildren()` while
+     * hidden and thus missed style propagation.
+     */
+    markStyleDirty(): void;
+    /**
+     * isStyleDirty вглубь по поддереву — БЕЗ подъёма вверх и без markDirty.
+     * Подъём достаточен один раз от вершины каскада (внутренним узлам
+     * subtreeStyleDirty не нужен — они и так isStyleDirty); прежняя рекурсия
+     * через markStyleDirty гоняла markDirty до корня из каждого потомка,
+     * O(N×глубина) на каскад.
+     */
+    private markStyleSubtree;
+    private markSubtreeStyleDirtyUp;
+    performStyleResolution(context: StyleResolutionContext): void;
+    /**
+     * Спуск стилевого прохода в детей. Переопределяется виртуализирующим
+     * контейнером, чтобы резолвить только видимое окно строк (зеркально
+     * hitTestChildren/getDepthFirstFocusableOrder); офскрин-строки остаются
+     * style-dirty и дорезолвливаются, когда въезжают в окно — см.
+     * {@link markSubtreeStyleDirty}.
+     */
+    protected performChildrenStyleResolution(context: StyleResolutionContext): void;
+    /**
+     * «У потомков могут быть неразрезолвленные стили»: subtreeStyleDirty здесь
+     * и вверх до корня, БЕЗ пометки самих детей и без markDirty. Для
+     * виртуализирующего контейнера, чей performLayout сместил окно: следующий
+     * стилевой проход обязан зайти внутрь и дорезолвить въехавшие строки
+     * (чистые отсеются ранним выходом performStyleResolution).
+     */
+    protected markSubtreeStyleDirty(): void;
+    private isStyleSelectorActive;
+    private buildChildStyleContext;
+    private describeForStyleError;
+    /**
+     * Кладёт таблицу токен→число, каскадирующую в поддерево ПОВЕРХ таблиц
+     * предков и дефолтов tuidom (STYLE_TOKEN_DEFAULTS). Обычное место — корень:
+     * хост транслирует сюда палитру темы одним вызовом (hot-swap = повторный
+     * вызов). Таблица заменяется целиком, null — снимает. Значения — только
+     * конкретные числа (packed RGB | DEFAULT_COLOR); сентинелы INHERITED_*
+     * нелегальны.
+     */
+    setStyleVars(vars: Readonly<Record<string, number>> | null): void;
+    /**
+     * Читает токен из ближайшего резолвленного var-scope — для painter-виджетов,
+     * рисующих несколько цветов в custom render. Валидно после резолва стилей
+     * (render всегда после него в кадре); до первого резолва видит дефолты
+     * tuidom. Незнакомый токен — throw; передан fallback (аналог второго
+     * аргумента CSS var()) — возвращается он. Fallback — для токенов, чьё
+     * отсутствие ЛЕГАЛЬНО и означает «взять из каскада» (editorGutter.background
+     * → фон редактора), а не страховка от опечаток.
+     */
+    styleVar(name: AnyStyleToken, fallback?: number): number;
+    /**
+     * Резолвит StyleColor (число | сентинел INHERITED_* | имя токена) в
+     * конкретный цвет в контексте ЭТОГО элемента (его resolvedStyle и
+     * var-scope). Для painter-виджетов, принимающих цвета данными
+     * (посимвольные стили TextLabel, iconColor строк дерева): данные могут
+     * ссылаться на токены и переживать смену темы без пере-пуша.
+     */
+    resolveColor(color: StyleColor): number;
+    /**
+     * Ставит/снимает состояние стиля. hover и focus ведёт ядро (диспатчер
+     * мыши и менеджер фокуса); произвольные строковые состояния ("selected",
+     * "checked", …) виджеты ставят сами. Смена состояния перерезолвит стиль
+     * элемента и поддерева: дети наследуют РЕЗУЛЬТАТ родителя с учётом его
+     * состояний, а `in:`-селекторы потомков видят состояния предков.
+     */
+    setStyleState(state: StyleState, active: boolean): void;
+    /**
+     * Как {@link setStyleState}, но для вызова из performLayout уже идущего
+     * кадра (виртуализирующие контейнеры синхронизируют selected/hover строк в
+     * layout). Стилевой проход идёт сразу после layout и потребит флаги, а
+     * markDirty здесь лишь оставлял бы корень layout-грязным ПОСЛЕ кадра — и
+     * следующее событие ввода рендерило бы пустой кадр (dirty-гейт
+     * TuiApplication).
+     */
+    setStyleStateDuringLayout(state: StyleState, active: boolean): void;
+    /** Мутация набора состояний; true — значение реально изменилось. */
+    private applyStyleState;
+    hasStyleState(state: StyleState): boolean;
+    /**
+     * Состояние активно на самом элементе ИЛИ на любом предке — рантайм-двойник
+     * `in:`-селектора для кода, который решает не цветом, а геометрией
+     * (инлайн-кнопка строки списка раскрывается, только когда строка активна).
+     * Селектор в `when` даёт ту же семантику декларативно и дешевле (готовый
+     * `ancestorStates` из контекста резолва); этот метод — для тех, кому
+     * состояние нужно ДО стилевого прохода, прямо в performLayout.
+     */
+    hasStyleStateWithin(state: StyleState): boolean;
+    /** Активные состояния (порядок вставки) — инспектор/тесты. */
+    get activeStyleStates(): readonly string[];
+    focus(): void;
+    blur(): void;
+    /**
+     * Marks this element and ancestors as dirty.
+     * Call this when layout-affecting properties change.
+     *
+     * When propagation reaches the root (no parent), fires the
+     * requestRenderCallback so TuiApplication can schedule a deferred render.
+     * Batching is handled by TuiApplication.scheduleRender().
+     */
+    markDirty(): void;
+    /**
+     * Пост-layout damage-обход (pre-order): собирает в sink повреждённые
+     * экранные области — rect'ы paint-dirty элементов и old∪new переехавших /
+     * изменивших размер / скрывшихся — и актуализирует lastPaintedRect.
+     * Спуск только по путям hasPaintDirtyDescendant или под переехавшим
+     * предком; устоявшееся поддерево стоит одну проверку флагов.
+     *
+     * Не заходит в скрытые и в не разложенные этим кадром поддеревья
+     * (isLayoutDirty после полного layout корня — виртуализация: контейнер их
+     * не раскладывал ⇒ не рисует ⇒ на экране их нет; чтение layoutSize там
+     * запустило бы lazy-layout с мусорными constraints).
+     */
+    collectDamage(sink: DamageList, parentOrigin: Point): void;
+    /** Обход детей damage-сбора — seam для контейнеров с нестандартной структурой. */
+    protected collectChildrenDamage(sink: DamageList, origin: Point): void;
+    /**
+     * true — поддерево рисуется как одно целое: любой paint-dirty потомок
+     * повреждает весь rect элемента, damage-обход внутрь не заходит. Для
+     * виртуализирующих контейнеров (ListViewElement: тысячи строк-детей с
+     * протухшими офскрин-позициями не итерируются) и контейнеров, рисующих
+     * собственный хром по состоянию ребёнка вне его rect'а (ScrollBarDecorator:
+     * бегунок в колонке за пределами ребёнка).
+     */
+    protected get paintsSubtreeAtomically(): boolean;
+    /** Рекурсивно забывает lastPaintedRect поддерева (отцепление/скрытие). */
+    private clearPaintedRects;
+    /**
+     * Только для TuiApplication: забрать rect'ы поддеревьев, отцеплённых от
+     * этого корня с прошлого кадра (закрытие оверлея, смена вкладки).
+     */
+    takePendingDetachDamage(): Rect[];
+    /**
+     * Внутренний сеттер обратной ссылки — вызывается ТОЛЬКО из
+     * appendChild/insertChild/removeChild/replaceChild/setChildren, поэтому
+     * список детей и parent меняются строго вместе. Отцепление (parent=null)
+     * гасит фокус, если он был внутри отцепляемого поддерева — иначе
+     * клавиатура продолжала бы уходить в элемент, которого больше нет на
+     * экране. После смены зовёт {@link onDidChangeParent} (хук для виджетов,
+     * вешающих слушатели на родителя, — MenuBarElement).
+     */
+    private setParent;
+    /**
+     * Хук смены родителя: вызывается после каждого перецепления. Базовая
+     * реализация пуста; переопределяется вместо запрещённого override
+     * setParent. Для доступа к КОРНЮ используйте {@link onDidConnect} — на
+     * момент этого хука поддерево может быть ещё не укоренено.
+     */
+    protected onDidChangeParent(_oldParent: TUIElement | null, _newParent: TUIElement | null): void;
+    /**
+     * Поддерево подключилось к укоренённому дереву: внутри хука
+     * `getRoot() === root`. Перенос между родителями (даже внутри одного
+     * дерева) — это всегда пара disconnect → connect: будьте идемпотентны.
+     * Скрытые (hidden) узлы получают хук наравне с видимыми — подключение
+     * не зависит от видимости. НЕ полагайтесь на `root.focusManager` — он
+     * появляется позже (TuiApplication.run). Хук не должен бросать; мутации
+     * разрешены только в собственном поддереве. Если хук удаляет узел из ещё
+     * не обойдённой части дерева, тот получит disconnect без предшествовавшего
+     * connect-уведомления (подключение — факт топологии, уведомления
+     * догоняют).
+     */
+    protected onDidConnect(_root: TUIElement): void;
+    /**
+     * Поддерево отключилось от укоренённого дерева: внутри хука
+     * `getRoot() === null`. Прежний root хук хранит сам, если нужен для
+     * отписки (DOM-прецедент: disconnectedCallback тоже без аргументов).
+     */
+    protected onDidDisconnect(): void;
+    /** Подключён ли элемент к укоренённому дереву. */
+    get isConnected(): boolean;
+    /**
+     * Pre-order обход поддерева (родитель раньше детей — DOM tree order).
+     * Снимок детей берётся ДО вызова хука узла, перед рекурсией проверяется
+     * актуальность связи: ребёнок, добавленный хуком, получит свой connect
+     * через собственный setParent; удалённый — уже получил disconnect и
+     * пропускается.
+     */
+    private fireDidConnect;
+    private fireDidDisconnect;
+    /**
+     * Корень дерева — **производный** от цепочки родителей: прогулка вверх до
+     * вершины; если вершина — якорь (setAsRoot), это и есть корень, иначе
+     * поддерево отсоединено и корня нет. Раньше root был кэшем, который
+     * пропагировался вниз через getChildren() при setParent — контейнеры,
+     * прячущие детей из getChildren() (неактивные вкладки), оставляли их с
+     * протухшим null-root навсегда (семейство багов #204: focus()/open()
+     * молча не работали). Живая цепочка родителей протухнуть не может.
+     */
+    getRoot(): TUIElement | null;
+    /**
+     * Ближайший overlay-слой вверх по дереву (попапы, контекстные меню,
+     * докнутые виджеты). Элементы-хосты слоёв (BodyElement, OverlayHostElement)
+     * переопределяют и возвращают свой слой.
+     */
+    getOverlayLayer(): OverlayLayer | null;
+    /**
+     * Sets this element as the root (used for testing and by BodyElement).
+     * Помечает элемент якорем — getRoot() признаёт корнем только вершину
+     * цепочки с этой меткой. Уже собранное поддерево получает
+     * {@link onDidConnect} (поздний setAsRoot легален); повторный вызов —
+     * no-op; якорь на узле с родителем запрещён (getRoot() не видит якорь в
+     * середине цепочки — сработал бы только после detach, миной).
+     */
+    setAsRoot(): void;
+    /**
+     * Sets a callback to be invoked when markDirty() reaches the root element.
+     * Used by TuiApplication to schedule async re-renders.
+     */
+    setRequestRenderCallback(callback: (() => void) | null): void;
+    getMinIntrinsicWidth(_height: number): number;
+    getMaxIntrinsicWidth(_height: number): number;
+    getMinIntrinsicHeight(_width: number): number;
+    getMaxIntrinsicHeight(_width: number): number;
+    /**
+     * Хелпер контейнера: позиционирует ребёнка (localPosition) и прогоняет его
+     * layout — одна строка вместо ритуала из двух-трёх записей. globalPosition
+     * не трогает: он производный.
+     */
+    protected layoutChild(child: TUIElement, x: number, y: number, constraints: BoxConstraints): Size;
+    /**
+     * Единственный публичный вход в layout — НЕ переопределять (переопределяется
+     * {@link performLayout}). Запоминает входные constraints (их читает
+     * геометрическая проверка validateTree) и следит за контрактом: размер после
+     * layout обязан удовлетворять constraints. «Контент не влез» — вопрос
+     * отрисовки (клип), а не геометрии; занимать меньше выделенного можно только
+     * под loose-constraints родителя. См. docs/LAYOUT.md, «Контракт performLayout».
+     */
+    layout(constraints: BoxConstraints): Size;
+    /** Constraints последнего layout() — null, если layout ещё не вызывался. */
+    get lastLayoutConstraints(): BoxConstraints | null;
+    private lastConstraintsValue;
+    /**
+     * Переопределяемая реализация layout: применяет constraints к выделенной
+     * области. Вызывается ТОЛЬКО из {@link layout} — снаружи зовите layout().
+     */
+    protected performLayout(constraints: BoxConstraints): Size;
+    /**
+     * Дефолт: залить собственный фон (если он задан собственным стилем) и
+     * отрисовать детей. Контейнер, которому нужно собственное полотно (рамка,
+     * заголовок), рисует его и зовёт {@link renderChildren}; полностью
+     * кастомный рендер (виртуализация, скролл-сдвиг) переопределяет метод
+     * целиком — и тогда сам зовёт {@link paintOwnBackground} первой строкой,
+     * если хочет фон от каскада.
+     */
+    render(context: RenderContext): void;
+    /**
+     * Заливает прямоугольник элемента resolvedStyle.bg, если bg задан
+     * СОБСТВЕННЫМ стилем — базой или сработавшим when-вариантом. Элементы без
+     * собственного bg прозрачны (как в CSS). Сентинелы INHERITED_* тоже
+     * считаются «задан»: это намеренная перезаливка цветом родителя (INHERITED_BG)
+     * или инверсия (INHERITED_FG). Выход за границы невозможен — контекст
+     * элемента уже клипован родителем.
+     */
+    protected paintOwnBackground(context: RenderContext): void;
+    /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */
+    get hasOwnBackground(): boolean;
+    /**
+     * Сырые цвета после when-merge, до резолва токенов/сентинелов: что элемент
+     * «попросил сам» (undefined = наследует). Для инспектора и тестов.
+     */
+    get appliedStyle(): {
+        fg?: StyleColor;
+        bg?: StyleColor;
+    };
+    /**
+     * Каноничная отрисовка детей: каждый видимый ребёнок получает контекст со
+     * сдвигом на свою localPosition и клипом по своим границам (дети не рисуют
+     * за пределами выделенной области). Скрытые (hidden) пропускаются. Это тот
+     * самый цикл, который раньше был скопирован в десяток контейнеров.
+     */
+    protected renderChildren(context: RenderContext): void;
+    /**
+     * Финальный шаблон хит-теста — НЕ переопределять (кастомизация — через
+     * {@link hitTestChildren}/{@link hitTestSelf}): скрытое не кликается,
+     * вне собственных границ хита нет (инвариант вложенности Н2 гарантирует,
+     * что и у детей его там нет), дети опрашиваются в обратном порядке
+     * отрисовки, затем — сам элемент.
+     */
+    elementFromPoint(point: Point): TUIElement | null;
+    /**
+     * Хит-тест детей — зеркало {@link renderChildren}: тот же список, обратный
+     * порядок (верхний — первый), скрытых пропускает сам elementFromPoint
+     * ребёнка. Переопределение — для контейнеров с осознанно другой политикой:
+     * презентационные строки ListViewElement (`null` — мышь у контейнера),
+     * modal-хвост OverlayLayer.
+     */
+    protected hitTestChildren(point: Point): TUIElement | null;
+    /**
+     * Берёт ли элемент точку на себя, когда никто из детей её не взял.
+     * Дефолт — да (непрозрачный бокс). `false` — прозрачный для кликов
+     * контейнер: точка проваливается к элементам ПОД ним (OverlayLayer без
+     * попапа в этой точке).
+     */
+    protected hitTestSelf(_point: Point): boolean;
+    querySelector(selector: string): TUIElement | null;
+    querySelectorAll(selector: string): TUIElement[];
+}