@tuidom/core 0.1.0

package/dist/dom/tuiElement.js

@@ -0,0 +1,1168 @@
+import { DEFAULT_COLOR } from "../common/colorUtils.js";
+import { DisplayLine } from "../common/displayLine.js";
+import { BoxConstraints, Offset, Point, Rect, Size } from "../common/geometryPromitives.js";
+import { TerminalScreen } from "../rendering/terminalScreen.js";
+import { BORDER_ROUNDED } from "./borderStyle.js";
+import { EventPhase, TUIEventBase } from "./events/tuiEventBase.js";
+import { TUIKeyboardEvent } from "./events/tuiKeyboardEvent.js";
+import { ROOT_VAR_SCOPE } from "./styles/styleTokens.js";
+import { extendVarScope, mergeStyleVariants, resolveStyleColor, ROOT_RESOLVED_STYLE, ROOT_STYLE_CONTEXT, styleEquals, } from "./styles/tuiStyle.js";
+import { querySelector, querySelectorAll } from "./tuiSelector.js";
+const MAX_COORD = 100_000;
+const INFINITE_CLIP = new Rect(new Point(0, 0), new Size(MAX_COORD, MAX_COORD));
+export class RenderContext {
+    canvas;
+    offset;
+    clipRect;
+    constructor(canvas, offset = new Offset(0, 0), clipRect = INFINITE_CLIP) {
+        this.canvas = canvas;
+        this.offset = offset;
+        this.clipRect = clipRect;
+    }
+    withOffset(extra) {
+        return new RenderContext(this.canvas, new Offset(this.offset.dx + extra.dx, this.offset.dy + extra.dy), this.clipRect);
+    }
+    withClip(rect) {
+        return new RenderContext(this.canvas, this.offset, this.clipRect.intersect(rect));
+    }
+    setCell(x, y, cell) {
+        const screenX = x + this.offset.dx;
+        const screenY = y + this.offset.dy;
+        if (!this.clipRect.containsPoint(new Point(screenX, screenY)))
+            return;
+        this.canvas.setCell(new Point(screenX, screenY), cell);
+    }
+    /**
+     * Читает уже отрисованную ячейку в локальных координатах (тот же оффсет и
+     * клип, что у {@link setCell}). Возвращает null вне клипа или вне экрана.
+     * Нужен пост-обработке вроде оверлея выделения в списках: прочитать ячейку,
+     * решить по её текущим цветам и патчнуть через {@link setCell}.
+     */
+    getCell(x, y) {
+        const screenX = x + this.offset.dx;
+        const screenY = y + this.offset.dy;
+        if (!this.clipRect.containsPoint(new Point(screenX, screenY)))
+            return null;
+        if (screenX < 0 || screenY < 0 || screenX >= this.canvas.width || screenY >= this.canvas.height)
+            return null;
+        return this.canvas.getCell(new Point(screenX, screenY));
+    }
+    setCursorPosition(x, y) {
+        const screenX = x + this.offset.dx;
+        const screenY = y + this.offset.dy;
+        if (!this.clipRect.containsPoint(new Point(screenX, screenY)))
+            return;
+        this.canvas.setCursorPosition(new Point(screenX, screenY));
+    }
+    /**
+     * 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, y, text, style, options) {
+        const dl = options?.displayLine ?? new DisplayLine(text, options?.tabSize);
+        const maxWidth = options?.maxWidth ?? dl.displayWidth;
+        let col = 0;
+        while (col < maxWidth) {
+            const char = dl.charAtColumn(col);
+            /* v8 ignore start -- unreachable: the loop always advances col past a wide char's continuation cell, so charAtColumn never returns "" here */
+            if (char === "") {
+                col++;
+                continue;
+            }
+            /* v8 ignore stop */
+            const slot = dl.graphemeAtColumn(col);
+            const w = slot ? slot.displayWidth : 1;
+            const slotStyle = slot && options?.getStyle ? options.getStyle(slot.offset) : undefined;
+            const resolvedStyle = slotStyle !== undefined ? { ...style, ...slotStyle } : style;
+            if (w === 2 && col + 1 >= maxWidth) {
+                this.setCell(x + col, y, { char: " ", width: 1, ...resolvedStyle });
+                col++;
+            }
+            else {
+                this.setCell(x + col, y, { char, width: w, ...resolvedStyle });
+                col += w;
+            }
+        }
+        return col;
+    }
+    /**
+     * Отрисовывает прямоугольную рамку 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, y, width, height, options = {}) {
+        const style = options.style ?? BORDER_ROUNDED;
+        const fg = options.fg;
+        const bg = options.bg;
+        const right = x + width - 1;
+        const bottom = y + height - 1;
+        if (options.fill === true) {
+            for (let yy = y; yy <= bottom; yy++) {
+                for (let xx = x; xx <= right; xx++) {
+                    this.setCell(xx, yy, { char: " ", fg, bg });
+                }
+            }
+        }
+        const separators = new Set(options.separators);
+        // Top border.
+        this.setCell(x, y, { char: style.topLeft, fg, bg });
+        this.setCell(right, y, { char: style.topRight, fg, bg });
+        for (let xx = x + 1; xx < right; xx++)
+            this.setCell(xx, y, { char: style.horizontal, fg, bg });
+        // Side borders (+ separator T-connectors).
+        for (let yy = y + 1; yy < bottom; yy++) {
+            if (separators.has(yy - y)) {
+                this.setCell(x, yy, { char: style.leftJoint, fg, bg });
+                this.setCell(right, yy, { char: style.rightJoint, fg, bg });
+                for (let xx = x + 1; xx < right; xx++)
+                    this.setCell(xx, yy, { char: style.horizontal, fg, bg });
+            }
+            else {
+                this.setCell(x, yy, { char: style.vertical, fg, bg });
+                this.setCell(right, yy, { char: style.vertical, fg, bg });
+            }
+        }
+        // Bottom border.
+        this.setCell(x, bottom, { char: style.bottomLeft, fg, bg });
+        this.setCell(right, bottom, { char: style.bottomRight, fg, bg });
+        for (let xx = x + 1; xx < right; xx++)
+            this.setCell(xx, bottom, { char: style.horizontal, fg, bg });
+    }
+}
+export class TUIElement {
+    allocatedSize = new Size(80, 24);
+    dirty = false;
+    layoutStyle = undefined;
+    layoutState = undefined;
+    // Identity
+    id = undefined;
+    role = undefined;
+    // Участие в Tab-обходе и фокусе по клику. Порядок обхода — это порядок
+    // детей в дереве (как z-порядок и хит-тест); числового приоритета в духе
+    // DOM tabindex нет намеренно — он был бы вторым источником порядка.
+    focusable = false;
+    // Pointer capture (opt-in): while a button is held on this element, the dispatcher
+    // routes subsequent move/release events here even if the cursor leaves its bounds.
+    capturesPointer = false;
+    // Coordinate system
+    localPosition = new Offset(0, 0);
+    isLayoutDirty = true;
+    // ─── Damage-tracking отрисовки (см. docs/LAYOUT.md) ───
+    // Сам элемент просил перерисовку (его markDirty). Снимается в collectDamage.
+    isPaintDirty = true;
+    // В поддереве есть paint-dirty потомок — путь для damage-обхода (аналог
+    // subtreeStyleDirty). Снимается в collectDamage.
+    hasPaintDirtyDescendant = false;
+    // Экранный rect на момент последнего damage-обхода; null — не рисовался
+    // или отцеплён. Даёт old-rect повреждение при переезде/скрытии/отцеплении.
+    lastPaintedRect = null;
+    // Только на корне: rect'ы поддеревьев, отцеплённых с последнего кадра.
+    pendingDetachDamage = [];
+    _parent = null;
+    // Якорь дерева: выставляется setAsRoot() (BodyElement, тестовые корни).
+    // Сам root НЕ кэшируется — getRoot() выводит его из цепочки родителей.
+    isRootAnchor = false;
+    // Callback invoked when markDirty reaches the root — used by TuiApplication to schedule a render
+    requestRenderCallback = null;
+    // Focus manager — set only on root element
+    focusManager = null;
+    // ─── Style system ───
+    styleValue = {};
+    resolvedStyleValue = ROOT_RESOLVED_STYLE;
+    isStyleDirty = true;
+    subtreeStyleDirty = false;
+    // Сырые цвета ПОСЛЕ when-merge (до резолва сентинелов) — отвечают на
+    // вопрос «задан ли цвет собственным стилем» (заливка фона, инспектор).
+    appliedFgValue;
+    appliedBgValue;
+    // Активные состояния (hover/focus ведёт ядро, прочие — виджеты). Lazy:
+    // у подавляющего большинства элементов состояний нет.
+    styleStatesSet = null;
+    // Собственная таблица токенов (обычно только у корня — хост кладёт тему).
+    styleVarsValue = null;
+    // Ближайший резолвленный var-scope — источник styleVar(). До первого
+    // резолва — дефолты tuidom.
+    varScopeRef = ROOT_VAR_SCOPE;
+    // Контекст, переданный детям на последнем резолве. Валиден, пока элемент
+    // чист: любая смена входа (стиль/состояние предка) дирявит всё поддерево.
+    childStyleContext = ROOT_STYLE_CONTEXT;
+    get style() {
+        return this.styleValue;
+    }
+    set style(value) {
+        if (styleEquals(this.styleValue, value))
+            return;
+        this.styleValue = value;
+        this.markStyleDirty();
+    }
+    // Event listener storage — supports any event type + capture flag
+    _listeners = new Map();
+    /**
+     * Allocated visible area on screen, set by parent container via layout().
+     * Lazy fallback: if layout is dirty, triggers layout with loose constraints.
+     */
+    get layoutSize() {
+        if (this.isLayoutDirty) {
+            const constraints = BoxConstraints.loose(this.allocatedSize);
+            this.layout(constraints);
+        }
+        return this.allocatedSize;
+    }
+    get isFocused() {
+        const fm = this.getRoot()?.focusManager ?? null;
+        return fm !== null && fm.activeElement === this;
+    }
+    getParent() {
+        return this._parent;
+    }
+    /**
+     * Абсолютная позиция элемента на экране — **производная** от цепочки
+     * родителей: `parent.globalPosition + localPosition`. Раньше это было поле,
+     * которое каждый контейнер обязан был выставлять руками параллельно с
+     * `localPosition` (LAYOUT.md честно писал «в корректном состоянии они
+     * равны») — забытая запись давала элемент, который рисуется, но не
+     * кликается. Теперь рассинхрон невозможен по построению.
+     *
+     * У отсоединённого элемента (parent=null) равна `localPosition` — так
+     * standalone-рендер в тестах может позиционировать элемент напрямую.
+     */
+    get globalPosition() {
+        const parent = this._parent;
+        if (parent === null) {
+            return new Point(this.localPosition.dx, this.localPosition.dy);
+        }
+        const parentGlobal = parent.globalPosition;
+        return new Point(parentGlobal.x + this.localPosition.dx, parentGlobal.y + this.localPosition.dy);
+    }
+    // ─── Владение детьми ───
+    //
+    // Список детей принадлежит базовому классу; топология меняется ТОЛЬКО через
+    // appendChild/insertChild/removeChild/replaceChild/setChildren — они же
+    // атомарно поддерживают обратную ссылку parent. getChildren() не
+    // переопределяется: «ребёнок в списке, но parent не выставлен» (и наоборот)
+    // непредставимы. Порядок детей — это z-порядок хит-теста (последний сверху)
+    // и порядок Tab-обхода; контейнер задаёт его порядком вставки/setChildren.
+    childrenList = [];
+    getChildren() {
+        return this.childrenList;
+    }
+    /**
+     * Видимость (аналог display:none): скрытый элемент ОСТАЁТСЯ в дереве —
+     * root и каскад стилей до него доходят, — но выпадает из hit-теста и
+     * Tab-обхода (базовые обходы), а контейнер не раскладывает и не рисует его.
+     * Это разводит «структуру» и «что сейчас видно», которые раньше смешивал
+     * getChildren(): контейнеры исключали скрытых детей из структуры и потом
+     * руками чинили пропагацию при показе (источник семейства багов #204).
+     */
+    get hidden() {
+        return this.hiddenValue;
+    }
+    set hidden(value) {
+        if (this.hiddenValue === value)
+            return;
+        this.hiddenValue = value;
+        // Фокус НЕ трогаем: куда уходит фокус при скрытии — политика уровня
+        // workbench (PanelFocusContribution возвращает его в редактор, оверлей
+        // восстанавливает savedFocus). База лишь гарантирует, что Tab-обход и
+        // hit-test в скрытое не заходят.
+        this.markDirty();
+    }
+    hiddenValue = false;
+    /** Прикрепляет ребёнка в конец списка (снимая с прежнего родителя). */
+    appendChild(child) {
+        this.insertChild(this.childrenList.length, child);
+    }
+    /** Прикрепляет ребёнка на позицию index (снимая с прежнего родителя). */
+    insertChild(index, child) {
+        if (child === this) {
+            throw new Error("TUIElement: элемент не может быть собственным ребёнком");
+        }
+        child._parent?.removeChild(child);
+        this.childrenList.splice(index, 0, child);
+        child.setParent(this);
+        this.markDirty();
+    }
+    /** Отцепляет ребёнка (no-op, если он не наш). */
+    removeChild(child) {
+        const index = this.childrenList.indexOf(child);
+        if (index === -1)
+            return;
+        this.childrenList.splice(index, 1);
+        child.setParent(null);
+        this.markDirty();
+    }
+    /**
+     * Заменяет ребёнка, сохраняя позицию в списке — а значит z-порядок и место
+     * в Tab-обходе (важно слотовым контейнерам: content меняется, а overlay
+     * обязан остаться поверх).
+     */
+    replaceChild(oldChild, newChild) {
+        if (oldChild === newChild)
+            return;
+        const index = this.childrenList.indexOf(oldChild);
+        if (index === -1) {
+            this.appendChild(newChild);
+            return;
+        }
+        newChild._parent?.removeChild(newChild);
+        oldChild.setParent(null);
+        this.childrenList[index] = newChild;
+        newChild.setParent(this);
+        this.markDirty();
+    }
+    /**
+     * Декларативно приводит список детей к заданному (слотовые контейнеры
+     * пересобирают канонический порядок одним вызовом). Лишние отцепляются,
+     * новые прикрепляются, порядок — как в next.
+     */
+    setChildren(next) {
+        const nextSet = new Set(next);
+        if (nextSet.size !== next.length) {
+            throw new Error("TUIElement.setChildren: один элемент дважды в списке");
+        }
+        for (const child of this.childrenList) {
+            if (!nextSet.has(child)) {
+                child.setParent(null);
+            }
+        }
+        for (const child of next) {
+            if (child._parent !== this) {
+                child._parent?.removeChild(child);
+                child.setParent(this);
+            }
+        }
+        this.childrenList = [...next];
+        this.markDirty();
+    }
+    /** Гасит фокус, если activeElement — этот элемент или его потомок. */
+    releaseFocusIfInside() {
+        const fm = this.getRoot()?.focusManager ?? null;
+        let node = fm?.activeElement ?? null;
+        while (node !== null && node !== this) {
+            node = node.getParent();
+        }
+        if (node === this) {
+            fm.setFocus(null);
+        }
+    }
+    /**
+     * 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() {
+        return undefined;
+    }
+    /**
+     * Builds the path from root to this element (inclusive on both ends).
+     */
+    getAncestorPath() {
+        const path = [];
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let current = this;
+        while (current !== null) {
+            path.push(current);
+            current = current._parent;
+        }
+        path.reverse();
+        return path;
+    }
+    /**
+     * Порядок Tab-обхода поддерева: фокусируемые (focusable) в глубину.
+     * Скрытые (hidden) поддеревья пропускаются целиком — Tab не должен уводить
+     * фокус в невидимый инпут (закрытый find-виджет, неактивная вкладка).
+     */
+    getDepthFirstFocusableOrder() {
+        if (this.hidden)
+            return [];
+        const result = [];
+        if (this.focusable)
+            result.push(this);
+        for (const child of this.getChildren()) {
+            result.push(...child.getDepthFirstFocusableOrder());
+        }
+        return result;
+    }
+    addEventListener(type, handler, options) {
+        const capture = options?.capture ?? false;
+        let entries = this._listeners.get(type);
+        if (!entries) {
+            entries = [];
+            this._listeners.set(type, entries);
+        }
+        entries.push({ handler, capture });
+    }
+    removeEventListener(type, handler, options) {
+        const capture = options?.capture ?? false;
+        const entries = this._listeners.get(type);
+        if (!entries)
+            return;
+        const index = entries.findIndex((e) => e.handler === handler && e.capture === capture);
+        if (index !== -1) {
+            entries.splice(index, 1);
+        }
+    }
+    /**
+     * Dispatches event with capture → target → bubble phases (DOM-like).
+     * Returns true if preventDefault() was NOT called.
+     */
+    dispatchEvent(event) {
+        event.target = this;
+        // Build path from root → ... → parent (excluding target)
+        const path = [];
+        let current = this._parent;
+        while (current !== null) {
+            path.push(current);
+            current = current._parent;
+        }
+        path.reverse(); // root first
+        // Capture phase
+        event.eventPhase = EventPhase.CAPTURING;
+        for (const el of path) {
+            event.currentTarget = el;
+            this._invokeListeners(el, event, true);
+            if (event.propagationStopped)
+                break;
+        }
+        // Target phase
+        if (!event.propagationStopped) {
+            event.eventPhase = EventPhase.AT_TARGET;
+            event.currentTarget = this;
+            this._invokeListeners(this, event, null); // both capture and bubble listeners
+        }
+        // Bubble phase
+        if (!event.propagationStopped && event.bubbles) {
+            event.eventPhase = EventPhase.BUBBLING;
+            for (let i = path.length - 1; i >= 0; i--) {
+                event.currentTarget = path[i];
+                this._invokeListeners(path[i], event, false);
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- side effect from handler
+                if (event.propagationStopped)
+                    break;
+            }
+        }
+        event.eventPhase = EventPhase.NONE;
+        event.currentTarget = null;
+        // Default action — analogous to Web DOM default actions.
+        // Runs on the target element after all propagation phases.
+        // Cancelled by preventDefault() from any listener.
+        if (!event.defaultPrevented) {
+            this.performDefaultAction(event);
+        }
+        return !event.defaultPrevented;
+    }
+    /**
+     * 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).
+     */
+    performDefaultAction(event) {
+        if (event.type === "mousedown" && this.focusable) {
+            this.focus();
+        }
+    }
+    /**
+     * Invoke listeners on an element for the given event.
+     * captureFilter: true = only capture, false = only bubble, null = both (target phase)
+     */
+    _invokeListeners(el, event, captureFilter) {
+        const entries = el._listeners.get(event.type);
+        if (!entries)
+            return;
+        // Snapshot to avoid mutation during iteration
+        const snapshot = entries.slice();
+        for (const entry of snapshot) {
+            if (captureFilter === null || entry.capture === captureFilter) {
+                entry.handler(event);
+                if (event.immediatePropagationStopped)
+                    break;
+            }
+        }
+    }
+    // ─── Style system ───
+    get resolvedStyle() {
+        return this.resolvedStyleValue;
+    }
+    /**
+     * 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() {
+        this.markStyleSubtree();
+        this.markSubtreeStyleDirtyUp();
+        this.markDirty();
+    }
+    /**
+     * isStyleDirty вглубь по поддереву — БЕЗ подъёма вверх и без markDirty.
+     * Подъём достаточен один раз от вершины каскада (внутренним узлам
+     * subtreeStyleDirty не нужен — они и так isStyleDirty); прежняя рекурсия
+     * через markStyleDirty гоняла markDirty до корня из каждого потомка,
+     * O(N×глубина) на каскад.
+     */
+    markStyleSubtree() {
+        this.isStyleDirty = true;
+        for (const child of this.getChildren()) {
+            child.markStyleSubtree();
+        }
+    }
+    markSubtreeStyleDirtyUp() {
+        let current = this._parent;
+        while (current && !current.subtreeStyleDirty) {
+            current.subtreeStyleDirty = true;
+            current = current._parent;
+        }
+    }
+    performStyleResolution(context) {
+        if (!this.isStyleDirty && !this.subtreeStyleDirty)
+            return;
+        if (this.isStyleDirty) {
+            const applied = mergeStyleVariants(this.style, (selector) => this.isStyleSelectorActive(selector, context.ancestorStates));
+            this.appliedFgValue = applied.fg;
+            this.appliedBgValue = applied.bg;
+            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
+                ? resolveStyleColor(applied.bg, context.fg, context.bg, vars, describe)
+                : context.bg;
+            this.resolvedStyleValue = { fg, bg };
+            this.childStyleContext = this.buildChildStyleContext(context);
+        }
+        this.isStyleDirty = false;
+        this.subtreeStyleDirty = false;
+        this.performChildrenStyleResolution(this.childStyleContext);
+    }
+    /**
+     * Спуск стилевого прохода в детей. Переопределяется виртуализирующим
+     * контейнером, чтобы резолвить только видимое окно строк (зеркально
+     * hitTestChildren/getDepthFirstFocusableOrder); офскрин-строки остаются
+     * style-dirty и дорезолвливаются, когда въезжают в окно — см.
+     * {@link markSubtreeStyleDirty}.
+     */
+    performChildrenStyleResolution(context) {
+        for (const child of this.getChildren()) {
+            child.performStyleResolution(context);
+        }
+    }
+    /**
+     * «У потомков могут быть неразрезолвленные стили»: subtreeStyleDirty здесь
+     * и вверх до корня, БЕЗ пометки самих детей и без markDirty. Для
+     * виртуализирующего контейнера, чей performLayout сместил окно: следующий
+     * стилевой проход обязан зайти внутрь и дорезолвить въехавшие строки
+     * (чистые отсеются ранним выходом performStyleResolution).
+     */
+    markSubtreeStyleDirty() {
+        this.subtreeStyleDirty = true;
+        this.markSubtreeStyleDirtyUp();
+    }
+    isStyleSelectorActive(selector, ancestorStates) {
+        if (selector.startsWith("in:")) {
+            const state = selector.slice(3);
+            return this.styleStatesSet?.has(state) === true || ancestorStates.has(state);
+        }
+        return this.styleStatesSet?.has(selector) === true;
+    }
+    buildChildStyleContext(context) {
+        const { fg, bg } = this.resolvedStyleValue;
+        let ancestorStates = context.ancestorStates;
+        if (this.styleStatesSet !== null && this.styleStatesSet.size > 0) {
+            const union = new Set(context.ancestorStates);
+            for (const state of this.styleStatesSet) {
+                union.add(state);
+            }
+            ancestorStates = union;
+        }
+        return { fg, bg, vars: this.varScopeRef, ancestorStates };
+    }
+    describeForStyleError() {
+        const id = this.id !== undefined ? `#${this.id}` : "";
+        return `${this.constructor.name}${id}`;
+    }
+    // ─── Переменные стиля (токены) ───
+    /**
+     * Кладёт таблицу токен→число, каскадирующую в поддерево ПОВЕРХ таблиц
+     * предков и дефолтов tuidom (STYLE_TOKEN_DEFAULTS). Обычное место — корень:
+     * хост транслирует сюда палитру темы одним вызовом (hot-swap = повторный
+     * вызов). Таблица заменяется целиком, null — снимает. Значения — только
+     * конкретные числа (packed RGB | DEFAULT_COLOR); сентинелы INHERITED_*
+     * нелегальны.
+     */
+    setStyleVars(vars) {
+        if (vars === this.styleVarsValue)
+            return;
+        if (vars !== null) {
+            for (const key of Object.keys(vars)) {
+                if (vars[key] < DEFAULT_COLOR) {
+                    throw new Error(`${this.describeForStyleError()}.setStyleVars: токен "${key}" содержит сентинел/некорректное значение ${vars[key]} — таблицы принимают только конкретные цвета`);
+                }
+            }
+        }
+        this.styleVarsValue = vars;
+        this.markStyleDirty();
+    }
+    /**
+     * Читает токен из ближайшего резолвленного var-scope — для painter-виджетов,
+     * рисующих несколько цветов в custom render. Валидно после резолва стилей
+     * (render всегда после него в кадре); до первого резолва видит дефолты
+     * tuidom. Незнакомый токен — throw; передан fallback (аналог второго
+     * аргумента CSS var()) — возвращается он. Fallback — для токенов, чьё
+     * отсутствие ЛЕГАЛЬНО и означает «взять из каскада» (editorGutter.background
+     * → фон редактора), а не страховка от опечаток.
+     */
+    styleVar(name, fallback) {
+        const value = this.varScopeRef[name];
+        if (typeof value !== "number") {
+            if (fallback !== undefined)
+                return fallback;
+            throw new Error(`${this.describeForStyleError()}.styleVar: неизвестный цветовой токен "${name}"`);
+        }
+        return value;
+    }
+    /**
+     * Резолвит StyleColor (число | сентинел INHERITED_* | имя токена) в
+     * конкретный цвет в контексте ЭТОГО элемента (его resolvedStyle и
+     * var-scope). Для painter-виджетов, принимающих цвета данными
+     * (посимвольные стили TextLabel, iconColor строк дерева): данные могут
+     * ссылаться на токены и переживать смену темы без пере-пуша.
+     */
+    resolveColor(color) {
+        const { fg, bg } = this.resolvedStyleValue;
+        return resolveStyleColor(color, fg, bg, this.varScopeRef, () => this.describeForStyleError());
+    }
+    // ─── Состояния стиля ───
+    /**
+     * Ставит/снимает состояние стиля. hover и focus ведёт ядро (диспатчер
+     * мыши и менеджер фокуса); произвольные строковые состояния ("selected",
+     * "checked", …) виджеты ставят сами. Смена состояния перерезолвит стиль
+     * элемента и поддерева: дети наследуют РЕЗУЛЬТАТ родителя с учётом его
+     * состояний, а `in:`-селекторы потомков видят состояния предков.
+     */
+    setStyleState(state, active) {
+        if (this.applyStyleState(state, active)) {
+            this.markStyleDirty();
+        }
+    }
+    /**
+     * Как {@link setStyleState}, но для вызова из performLayout уже идущего
+     * кадра (виртуализирующие контейнеры синхронизируют selected/hover строк в
+     * layout). Стилевой проход идёт сразу после layout и потребит флаги, а
+     * markDirty здесь лишь оставлял бы корень layout-грязным ПОСЛЕ кадра — и
+     * следующее событие ввода рендерило бы пустой кадр (dirty-гейт
+     * TuiApplication).
+     */
+    setStyleStateDuringLayout(state, active) {
+        if (this.applyStyleState(state, active)) {
+            this.markStyleSubtree();
+            this.markSubtreeStyleDirtyUp();
+        }
+    }
+    /** Мутация набора состояний; true — значение реально изменилось. */
+    applyStyleState(state, active) {
+        const current = this.styleStatesSet?.has(state) === true;
+        if (current === active)
+            return false;
+        if (active) {
+            (this.styleStatesSet ??= new Set()).add(state);
+        }
+        else {
+            this.styleStatesSet?.delete(state);
+        }
+        return true;
+    }
+    hasStyleState(state) {
+        return this.styleStatesSet?.has(state) === true;
+    }
+    /**
+     * Состояние активно на самом элементе ИЛИ на любом предке — рантайм-двойник
+     * `in:`-селектора для кода, который решает не цветом, а геометрией
+     * (инлайн-кнопка строки списка раскрывается, только когда строка активна).
+     * Селектор в `when` даёт ту же семантику декларативно и дешевле (готовый
+     * `ancestorStates` из контекста резолва); этот метод — для тех, кому
+     * состояние нужно ДО стилевого прохода, прямо в performLayout.
+     */
+    hasStyleStateWithin(state) {
+        let node = this;
+        while (node !== null) {
+            if (node.styleStatesSet?.has(state) === true)
+                return true;
+            node = node._parent;
+        }
+        return false;
+    }
+    /** Активные состояния (порядок вставки) — инспектор/тесты. */
+    get activeStyleStates() {
+        return this.styleStatesSet !== null ? [...this.styleStatesSet] : [];
+    }
+    // ─── Focus convenience ───
+    focus() {
+        const fm = this.getRoot()?.focusManager ?? null;
+        if (fm) {
+            fm.setFocus(this);
+        }
+    }
+    blur() {
+        const fm = this.getRoot()?.focusManager ?? null;
+        if (fm?.activeElement === this) {
+            fm.setFocus(null);
+        }
+    }
+    /**
+     * 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() {
+        // Paint-dirty — ТОЛЬКО сам элемент: повреждается его rect, а не вся
+        // цепочка предков (иначе любой markDirty = полноэкранный damage).
+        this.isPaintDirty = true;
+        this.isLayoutDirty = true;
+        let top = this;
+        for (let current = this._parent; current !== null; current = current._parent) {
+            current.isLayoutDirty = true;
+            current.hasPaintDirtyDescendant = true;
+            top = current;
+        }
+        top.requestRenderCallback?.();
+    }
+    /**
+     * Пост-layout damage-обход (pre-order): собирает в sink повреждённые
+     * экранные области — rect'ы paint-dirty элементов и old∪new переехавших /
+     * изменивших размер / скрывшихся — и актуализирует lastPaintedRect.
+     * Спуск только по путям hasPaintDirtyDescendant или под переехавшим
+     * предком; устоявшееся поддерево стоит одну проверку флагов.
+     *
+     * Не заходит в скрытые и в не разложенные этим кадром поддеревья
+     * (isLayoutDirty после полного layout корня — виртуализация: контейнер их
+     * не раскладывал ⇒ не рисует ⇒ на экране их нет; чтение layoutSize там
+     * запустило бы lazy-layout с мусорными constraints).
+     */
+    collectDamage(sink, parentOrigin) {
+        if (this.hidden || this.isLayoutDirty) {
+            if (this.lastPaintedRect !== null) {
+                // Скрылся (или выпал из раскладки) — место под ним перерисовать.
+                sink.add(this.lastPaintedRect);
+                this.clearPaintedRects();
+            }
+            this.isPaintDirty = false;
+            this.hasPaintDirtyDescendant = false;
+            return;
+        }
+        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 ||
+            old.x !== rect.x ||
+            old.y !== rect.y ||
+            old.width !== rect.width ||
+            old.height !== rect.height;
+        const atomic = this.paintsSubtreeAtomically;
+        if (this.isPaintDirty || moved || (atomic && this.hasPaintDirtyDescendant)) {
+            sink.add(rect);
+            if (old !== null && moved)
+                sink.add(old);
+        }
+        // Спуск: найти paint-dirty потомков и/или обновить их lastPaintedRect
+        // после переезда предка (их экранные rect'ы сменились все разом).
+        const descend = !atomic && (moved || this.hasPaintDirtyDescendant);
+        this.lastPaintedRect = rect;
+        this.isPaintDirty = false;
+        this.hasPaintDirtyDescendant = false;
+        if (descend)
+            this.collectChildrenDamage(sink, rect.origin);
+    }
+    /** Обход детей damage-сбора — seam для контейнеров с нестандартной структурой. */
+    collectChildrenDamage(sink, origin) {
+        for (const child of this.childrenList)
+            child.collectDamage(sink, origin);
+    }
+    /**
+     * true — поддерево рисуется как одно целое: любой paint-dirty потомок
+     * повреждает весь rect элемента, damage-обход внутрь не заходит. Для
+     * виртуализирующих контейнеров (ListViewElement: тысячи строк-детей с
+     * протухшими офскрин-позициями не итерируются) и контейнеров, рисующих
+     * собственный хром по состоянию ребёнка вне его rect'а (ScrollBarDecorator:
+     * бегунок в колонке за пределами ребёнка).
+     */
+    get paintsSubtreeAtomically() {
+        return false;
+    }
+    /** Рекурсивно забывает lastPaintedRect поддерева (отцепление/скрытие). */
+    clearPaintedRects() {
+        this.lastPaintedRect = null;
+        for (const child of this.childrenList)
+            child.clearPaintedRects();
+    }
+    /**
+     * Только для TuiApplication: забрать rect'ы поддеревьев, отцеплённых от
+     * этого корня с прошлого кадра (закрытие оверлея, смена вкладки).
+     */
+    takePendingDetachDamage() {
+        if (this.pendingDetachDamage.length === 0)
+            return this.pendingDetachDamage;
+        const out = this.pendingDetachDamage;
+        this.pendingDetachDamage = [];
+        return out;
+    }
+    /**
+     * Внутренний сеттер обратной ссылки — вызывается ТОЛЬКО из
+     * appendChild/insertChild/removeChild/replaceChild/setChildren, поэтому
+     * список детей и parent меняются строго вместе. Отцепление (parent=null)
+     * гасит фокус, если он был внутри отцепляемого поддерева — иначе
+     * клавиатура продолжала бы уходить в элемент, которого больше нет на
+     * экране. После смены зовёт {@link onDidChangeParent} (хук для виджетов,
+     * вешающих слушатели на родителя, — MenuBarElement).
+     */
+    setParent(parent) {
+        const oldRoot = this.getRoot(); // снимок ДО мутации — по ещё живой цепочке
+        if (parent === null && this._parent !== null) {
+            this.releaseFocusIfInside();
+            // Отцепление — место, где поддерево рисовалось, надо перерисовать.
+            // Rect потомков вложены в наш (Н2) — достаточно верхнего. Запись
+            // на СТАРЫЙ корень: только он знает экранные координаты кадра.
+            if (this.lastPaintedRect !== null && oldRoot !== null) {
+                oldRoot.pendingDetachDamage.push(this.lastPaintedRect);
+            }
+            this.clearPaintedRects();
+        }
+        const oldParent = this._parent;
+        this._parent = parent;
+        if (parent) {
+            // Безусловно: даже чистое поддерево обязано пере-резолвиться в
+            // контексте нового родителя (другой каскад/состояния предков).
+            this.markStyleDirty();
+        }
+        this.onDidChangeParent(oldParent, parent);
+        const newRoot = this.getRoot();
+        if (oldRoot !== newRoot) {
+            if (oldRoot !== null)
+                this.fireDidDisconnect();
+            if (newRoot !== null)
+                this.fireDidConnect(newRoot);
+        }
+    }
+    /**
+     * Хук смены родителя: вызывается после каждого перецепления. Базовая
+     * реализация пуста; переопределяется вместо запрещённого override
+     * setParent. Для доступа к КОРНЮ используйте {@link onDidConnect} — на
+     * момент этого хука поддерево может быть ещё не укоренено.
+     */
+    onDidChangeParent(_oldParent, _newParent) {
+        // Базовая реализация ничего не делает.
+    }
+    // ─── Подключение к дереву (аналог DOM connectedCallback) ───
+    //
+    // «Прикреплён к родителю» ≠ «подключён к укоренённому дереву»: поддерево
+    // может собираться отвязанно и укорениться позже (или наоборот). Хуки ниже
+    // сообщают каждому узлу перемещаемого поддерева о смене укоренённости —
+    // это пропагация СОБЫТИЯ, не состояния (getRoot() остаётся производным,
+    // протухать нечему; ср. кэш root, удалённый в #214).
+    /**
+     * Поддерево подключилось к укоренённому дереву: внутри хука
+     * `getRoot() === root`. Перенос между родителями (даже внутри одного
+     * дерева) — это всегда пара disconnect → connect: будьте идемпотентны.
+     * Скрытые (hidden) узлы получают хук наравне с видимыми — подключение
+     * не зависит от видимости. НЕ полагайтесь на `root.focusManager` — он
+     * появляется позже (TuiApplication.run). Хук не должен бросать; мутации
+     * разрешены только в собственном поддереве. Если хук удаляет узел из ещё
+     * не обойдённой части дерева, тот получит disconnect без предшествовавшего
+     * connect-уведомления (подключение — факт топологии, уведомления
+     * догоняют).
+     */
+    onDidConnect(_root) {
+        // Базовая реализация ничего не делает.
+    }
+    /**
+     * Поддерево отключилось от укоренённого дерева: внутри хука
+     * `getRoot() === null`. Прежний root хук хранит сам, если нужен для
+     * отписки (DOM-прецедент: disconnectedCallback тоже без аргументов).
+     */
+    onDidDisconnect() {
+        // Базовая реализация ничего не делает.
+    }
+    /** Подключён ли элемент к укоренённому дереву. */
+    get isConnected() {
+        return this.getRoot() !== null;
+    }
+    /**
+     * Pre-order обход поддерева (родитель раньше детей — DOM tree order).
+     * Снимок детей берётся ДО вызова хука узла, перед рекурсией проверяется
+     * актуальность связи: ребёнок, добавленный хуком, получит свой connect
+     * через собственный setParent; удалённый — уже получил disconnect и
+     * пропускается.
+     */
+    fireDidConnect(root) {
+        const children = [...this.getChildren()];
+        this.onDidConnect(root);
+        for (const child of children) {
+            if (child.getParent() === this)
+                child.fireDidConnect(root);
+        }
+    }
+    fireDidDisconnect() {
+        const children = [...this.getChildren()];
+        this.onDidDisconnect();
+        for (const child of children) {
+            if (child.getParent() === this)
+                child.fireDidDisconnect();
+        }
+    }
+    /**
+     * Корень дерева — **производный** от цепочки родителей: прогулка вверх до
+     * вершины; если вершина — якорь (setAsRoot), это и есть корень, иначе
+     * поддерево отсоединено и корня нет. Раньше root был кэшем, который
+     * пропагировался вниз через getChildren() при setParent — контейнеры,
+     * прячущие детей из getChildren() (неактивные вкладки), оставляли их с
+     * протухшим null-root навсегда (семейство багов #204: focus()/open()
+     * молча не работали). Живая цепочка родителей протухнуть не может.
+     */
+    getRoot() {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let current = this;
+        while (current._parent !== null) {
+            current = current._parent;
+        }
+        return current.isRootAnchor ? current : null;
+    }
+    /**
+     * Ближайший overlay-слой вверх по дереву (попапы, контекстные меню,
+     * докнутые виджеты). Элементы-хосты слоёв (BodyElement, OverlayHostElement)
+     * переопределяют и возвращают свой слой.
+     */
+    getOverlayLayer() {
+        return this.getParent()?.getOverlayLayer() ?? null;
+    }
+    /**
+     * Sets this element as the root (used for testing and by BodyElement).
+     * Помечает элемент якорем — getRoot() признаёт корнем только вершину
+     * цепочки с этой меткой. Уже собранное поддерево получает
+     * {@link onDidConnect} (поздний setAsRoot легален); повторный вызов —
+     * no-op; якорь на узле с родителем запрещён (getRoot() не видит якорь в
+     * середине цепочки — сработал бы только после detach, миной).
+     */
+    setAsRoot() {
+        if (this.isRootAnchor)
+            return;
+        if (this._parent !== null) {
+            throw new Error("TUIElement.setAsRoot: якорь корня допустим только на вершине цепочки (без родителя)");
+        }
+        this.isRootAnchor = true;
+        this.fireDidConnect(this);
+    }
+    /**
+     * Sets a callback to be invoked when markDirty() reaches the root element.
+     * Used by TuiApplication to schedule async re-renders.
+     */
+    setRequestRenderCallback(callback) {
+        this.requestRenderCallback = callback;
+    }
+    // ─── Intrinsic Size API ───
+    getMinIntrinsicWidth(_height) {
+        return 0;
+    }
+    getMaxIntrinsicWidth(_height) {
+        return 0;
+    }
+    getMinIntrinsicHeight(_width) {
+        return 0;
+    }
+    getMaxIntrinsicHeight(_width) {
+        return 0;
+    }
+    /**
+     * Хелпер контейнера: позиционирует ребёнка (localPosition) и прогоняет его
+     * layout — одна строка вместо ритуала из двух-трёх записей. globalPosition
+     * не трогает: он производный.
+     */
+    layoutChild(child, x, y, constraints) {
+        child.localPosition = new Offset(x, y);
+        return child.layout(constraints);
+    }
+    /**
+     * Единственный публичный вход в layout — НЕ переопределять (переопределяется
+     * {@link performLayout}). Запоминает входные constraints (их читает
+     * геометрическая проверка validateTree) и следит за контрактом: размер после
+     * layout обязан удовлетворять constraints. «Контент не влез» — вопрос
+     * отрисовки (клип), а не геометрии; занимать меньше выделенного можно только
+     * под loose-constraints родителя. См. docs/LAYOUT.md, «Контракт performLayout».
+     */
+    layout(constraints) {
+        this.lastConstraintsValue = constraints;
+        const result = this.performLayout(constraints);
+        if (!constraints.isSatisfiedBy(result)) {
+            throw new Error(`${this.constructor.name}: performLayout вернул ${result.width}×${result.height}, ` +
+                `нарушив constraints [${constraints.minWidth}..${constraints.maxWidth}]×` +
+                `[${constraints.minHeight}..${constraints.maxHeight}]`);
+        }
+        if (result.width !== this.allocatedSize.width || result.height !== this.allocatedSize.height) {
+            throw new Error(`${this.constructor.name}: performLayout вернул ${result.width}×${result.height}, ` +
+                `но записал allocatedSize ${this.allocatedSize.width}×${this.allocatedSize.height}`);
+        }
+        return result;
+    }
+    /** Constraints последнего layout() — null, если layout ещё не вызывался. */
+    get lastLayoutConstraints() {
+        return this.lastConstraintsValue;
+    }
+    lastConstraintsValue = null;
+    /**
+     * Переопределяемая реализация layout: применяет constraints к выделенной
+     * области. Вызывается ТОЛЬКО из {@link layout} — снаружи зовите layout().
+     */
+    performLayout(constraints) {
+        const resultSize = constraints.constrain(this.allocatedSize);
+        this.allocatedSize = resultSize;
+        this.isLayoutDirty = false;
+        return resultSize;
+    }
+    /**
+     * Дефолт: залить собственный фон (если он задан собственным стилем) и
+     * отрисовать детей. Контейнер, которому нужно собственное полотно (рамка,
+     * заголовок), рисует его и зовёт {@link renderChildren}; полностью
+     * кастомный рендер (виртуализация, скролл-сдвиг) переопределяет метод
+     * целиком — и тогда сам зовёт {@link paintOwnBackground} первой строкой,
+     * если хочет фон от каскада.
+     */
+    render(context) {
+        this.paintOwnBackground(context);
+        this.renderChildren(context);
+    }
+    /**
+     * Заливает прямоугольник элемента resolvedStyle.bg, если bg задан
+     * СОБСТВЕННЫМ стилем — базой или сработавшим when-вариантом. Элементы без
+     * собственного bg прозрачны (как в CSS). Сентинелы INHERITED_* тоже
+     * считаются «задан»: это намеренная перезаливка цветом родителя (INHERITED_BG)
+     * или инверсия (INHERITED_FG). Выход за границы невозможен — контекст
+     * элемента уже клипован родителем.
+     */
+    paintOwnBackground(context) {
+        if (this.appliedBgValue === undefined)
+            return;
+        const { fg, bg } = this.resolvedStyleValue;
+        const { width, height } = this.layoutSize;
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                context.setCell(x, y, { char: " ", fg, bg });
+            }
+        }
+    }
+    /** true, если фон задан собственным стилем (см. {@link paintOwnBackground}). */
+    get hasOwnBackground() {
+        return this.appliedBgValue !== undefined;
+    }
+    /**
+     * Сырые цвета после when-merge, до резолва токенов/сентинелов: что элемент
+     * «попросил сам» (undefined = наследует). Для инспектора и тестов.
+     */
+    get appliedStyle() {
+        return { fg: this.appliedFgValue, bg: this.appliedBgValue };
+    }
+    /**
+     * Каноничная отрисовка детей: каждый видимый ребёнок получает контекст со
+     * сдвигом на свою localPosition и клипом по своим границам (дети не рисуют
+     * за пределами выделенной области). Скрытые (hidden) пропускаются. Это тот
+     * самый цикл, который раньше был скопирован в десяток контейнеров.
+     */
+    renderChildren(context) {
+        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);
+        }
+    }
+    // ─── Hit-testing ───
+    //
+    // Правило системы (Н6): рендер и Tab обходят детей ВПЕРЁД, хит-тест — тем
+    // же списком НАЗАД (последний нарисован сверху). Правило зашито в шаблон
+    // ниже и не переопределяется; контейнер объявляет отличия только в двух
+    // симметричных точках — {@link hitTestChildren} (зеркало
+    // {@link renderChildren}) и {@link hitTestSelf}.
+    /**
+     * Финальный шаблон хит-теста — НЕ переопределять (кастомизация — через
+     * {@link hitTestChildren}/{@link hitTestSelf}): скрытое не кликается,
+     * вне собственных границ хита нет (инвариант вложенности Н2 гарантирует,
+     * что и у детей его там нет), дети опрашиваются в обратном порядке
+     * отрисовки, затем — сам элемент.
+     */
+    elementFromPoint(point) {
+        if (this.hidden)
+            return null; // скрытое не кликается
+        const bounds = new Rect(this.globalPosition, this.layoutSize);
+        if (!bounds.containsPoint(point))
+            return null;
+        const hit = this.hitTestChildren(point);
+        if (hit)
+            return hit;
+        return this.hitTestSelf(point) ? this : null;
+    }
+    /**
+     * Хит-тест детей — зеркало {@link renderChildren}: тот же список, обратный
+     * порядок (верхний — первый), скрытых пропускает сам elementFromPoint
+     * ребёнка. Переопределение — для контейнеров с осознанно другой политикой:
+     * презентационные строки ListViewElement (`null` — мышь у контейнера),
+     * modal-хвост OverlayLayer.
+     */
+    hitTestChildren(point) {
+        const children = this.getChildren();
+        for (let i = children.length - 1; i >= 0; i--) {
+            const hit = children[i].elementFromPoint(point);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    /**
+     * Берёт ли элемент точку на себя, когда никто из детей её не взял.
+     * Дефолт — да (непрозрачный бокс). `false` — прозрачный для кликов
+     * контейнер: точка проваливается к элементам ПОД ним (OverlayLayer без
+     * попапа в этой точке).
+     */
+    hitTestSelf(_point) {
+        return true;
+    }
+    // ─── Query API (querySelector / querySelectorAll) ───
+    querySelector(selector) {
+        return querySelector(this, selector);
+    }
+    querySelectorAll(selector) {
+        return querySelectorAll(this, selector);
+    }
+}