@tuidom/core 0.1.0

package/dist/dom/tuiSelector.d.ts

@@ -0,0 +1,9 @@
+import type { TUIElement } from "./tuiElement.js";
+export interface ParsedSelector {
+    tag: string | undefined;
+    id: string | undefined;
+    role: string | undefined;
+}
+export declare function parseSelector(selector: string): ParsedSelector[];
+export declare function querySelector(root: TUIElement, selector: string): TUIElement | null;
+export declare function querySelectorAll(root: TUIElement, selector: string): TUIElement[];

package/dist/dom/tuiSelector.js

@@ -0,0 +1,82 @@
+function parseSingleSelector(part) {
+    let tag;
+    let id;
+    let role;
+    let remaining = part;
+    // Extract #id
+    const idMatch = /#([a-zA-Z0-9_-]+)/.exec(remaining);
+    if (idMatch) {
+        id = idMatch[1];
+        remaining = remaining.replace(idMatch[0], "");
+    }
+    // Extract @role
+    const roleMatch = /@([a-zA-Z0-9_-]+)/.exec(remaining);
+    if (roleMatch) {
+        role = roleMatch[1];
+        remaining = remaining.replace(roleMatch[0], "");
+    }
+    // Whatever is left is the tag (constructor name)
+    if (remaining.length > 0) {
+        tag = remaining;
+    }
+    return { tag, id, role };
+}
+function matchesSingleSelector(element, selector) {
+    if (selector.tag && element.constructor.name !== selector.tag)
+        return false;
+    if (selector.id && element.id !== selector.id)
+        return false;
+    if (selector.role && element.role !== selector.role)
+        return false;
+    return true;
+}
+export function parseSelector(selector) {
+    const parts = selector.trim().split(/\s+/);
+    return parts.map(parseSingleSelector);
+}
+export function querySelector(root, selector) {
+    const parsed = parseSelector(selector);
+    return queryDescendant(root, parsed, 0);
+}
+export function querySelectorAll(root, selector) {
+    const parsed = parseSelector(selector);
+    const results = [];
+    queryDescendantAll(root, parsed, 0, results);
+    return results;
+}
+function queryDescendant(element, selectors, depth) {
+    for (const child of element.getChildren()) {
+        if (matchesSingleSelector(child, selectors[depth])) {
+            if (depth === selectors.length - 1)
+                return child;
+            const found = queryDescendant(child, selectors, depth + 1);
+            if (found)
+                return found;
+        }
+        /* v8 ignore start -- depth>0 only happens for multi-part selectors (length>1), so the guard is always true; the false side is unreachable */
+        if (depth === 0 || selectors.length > 1) {
+            const found = queryDescendant(child, selectors, depth);
+            if (found)
+                return found;
+        }
+        /* v8 ignore stop */
+    }
+    return null;
+}
+function queryDescendantAll(element, selectors, depth, results) {
+    for (const child of element.getChildren()) {
+        if (matchesSingleSelector(child, selectors[depth])) {
+            if (depth === selectors.length - 1) {
+                results.push(child);
+            }
+            else {
+                queryDescendantAll(child, selectors, depth + 1, results);
+            }
+        }
+        /* v8 ignore start -- depth>0 only happens for multi-part selectors (length>1), so the guard is always true; the false side is unreachable */
+        if (depth === 0 || selectors.length > 1) {
+            queryDescendantAll(child, selectors, depth, results);
+        }
+        /* v8 ignore stop */
+    }
+}

package/dist/dom/validateTree.d.ts

@@ -0,0 +1,42 @@
+import type { TUIElement } from "./tuiElement.js";
+/**
+ * Проверка структурных инвариантов дерева элементов. Обходит дерево от корня
+ * через `getChildren()` и находит состояния, которые «работают наполовину»:
+ * элемент рисуется, но не кликается; получает кадры, но не получает стили.
+ * Такие состояния — источник целого класса багов «элемент есть, но не
+ * показывается/не реагирует» (#204 и родня), и простыми тестами они не
+ * ловятся, потому что каждый отдельный механизм (render, hit-test, стили,
+ * фокус) отказывает молча.
+ *
+ * Инварианты:
+ * - **Симметрия parent**: каждый ребёнок из `getChildren()` указывает
+ *   `getParent()` ровно на свой контейнер. Нарушение = забытый `setParent`
+ *   (markDirty не доходит до корня, события не всплывают) или устаревшая
+ *   ссылка после перецепления.
+ * - **Достижимость root**: `getRoot()` каждого узла равен корню обхода.
+ *   Нарушение = элемент прикрепили до укоренения контейнера и нисходящая
+ *   пропагация его не увидела — `focus()`/`open()` будут молча no-op.
+ * - **Единственность прикрепления**: узел встречается в дереве один раз
+ *   (нет циклов, нет двух родителей, отдающих один элемент).
+ * - **Layout-контракт**: размер узла удовлетворяет constraints его последнего
+ *   `layout()` (Н1, см. LAYOUT.md «Контракт performLayout»). Ловит мутации
+ *   размера после layout без markDirty — сам layout() ассертит в моменте.
+ *   Пропускаются узлы с `isLayoutDirty` (офскрин-строки виртуализирующего
+ *   ListViewElement легитимно несут устаревший layout), скрытые (`hidden`)
+ *   поддеревья целиком (их никто не раскладывал) и ни разу не разложенные.
+ * - **Вложенность**: ребёнок геометрически внутри родителя —
+ *   `Rect(child) ⊆ Rect(parent)` (Н2, см. LAYOUT.md «Инвариант вложенности»).
+ *   Исключений нет: «переполнение» (попапы, дропдауны) реализуется переносом в
+ *   OverlayLayer, а не рисованием за границами. Пропуски те же, что у
+ *   layout-контракта, плюс пары, где dirty сам родитель (его геометрия stale).
+ *
+ * Использование: в тестах — автоматически после каждого кадра
+ * (`TuiApplication.validateTreeAfterRender`, включает TestApp); в приложении —
+ * опционально через тот же флаг (env `VEXX_VALIDATE_TREE=1` в main).
+ */
+export declare function validateTree(root: TUIElement): string[];
+/**
+ * Бросает с перечнем нарушений, если дерево невалидно. Вызывается после кадра
+ * при включённом `TuiApplication.validateTreeAfterRender`.
+ */
+export declare function assertValidTree(root: TUIElement): void;

package/dist/dom/validateTree.js

@@ -0,0 +1,125 @@
+import { Rect } from "../common/geometryPromitives.js";
+/**
+ * Проверка структурных инвариантов дерева элементов. Обходит дерево от корня
+ * через `getChildren()` и находит состояния, которые «работают наполовину»:
+ * элемент рисуется, но не кликается; получает кадры, но не получает стили.
+ * Такие состояния — источник целого класса багов «элемент есть, но не
+ * показывается/не реагирует» (#204 и родня), и простыми тестами они не
+ * ловятся, потому что каждый отдельный механизм (render, hit-test, стили,
+ * фокус) отказывает молча.
+ *
+ * Инварианты:
+ * - **Симметрия parent**: каждый ребёнок из `getChildren()` указывает
+ *   `getParent()` ровно на свой контейнер. Нарушение = забытый `setParent`
+ *   (markDirty не доходит до корня, события не всплывают) или устаревшая
+ *   ссылка после перецепления.
+ * - **Достижимость root**: `getRoot()` каждого узла равен корню обхода.
+ *   Нарушение = элемент прикрепили до укоренения контейнера и нисходящая
+ *   пропагация его не увидела — `focus()`/`open()` будут молча no-op.
+ * - **Единственность прикрепления**: узел встречается в дереве один раз
+ *   (нет циклов, нет двух родителей, отдающих один элемент).
+ * - **Layout-контракт**: размер узла удовлетворяет constraints его последнего
+ *   `layout()` (Н1, см. LAYOUT.md «Контракт performLayout»). Ловит мутации
+ *   размера после layout без markDirty — сам layout() ассертит в моменте.
+ *   Пропускаются узлы с `isLayoutDirty` (офскрин-строки виртуализирующего
+ *   ListViewElement легитимно несут устаревший layout), скрытые (`hidden`)
+ *   поддеревья целиком (их никто не раскладывал) и ни разу не разложенные.
+ * - **Вложенность**: ребёнок геометрически внутри родителя —
+ *   `Rect(child) ⊆ Rect(parent)` (Н2, см. LAYOUT.md «Инвариант вложенности»).
+ *   Исключений нет: «переполнение» (попапы, дропдауны) реализуется переносом в
+ *   OverlayLayer, а не рисованием за границами. Пропуски те же, что у
+ *   layout-контракта, плюс пары, где dirty сам родитель (его геометрия stale).
+ *
+ * Использование: в тестах — автоматически после каждого кадра
+ * (`TuiApplication.validateTreeAfterRender`, включает TestApp); в приложении —
+ * опционально через тот же флаг (env `VEXX_VALIDATE_TREE=1` в main).
+ */
+export function validateTree(root) {
+    const violations = [];
+    const expectedRoot = root.getRoot();
+    if (expectedRoot !== root) {
+        violations.push(`корень обхода ${describe(root)} не считает себя корнем: getRoot() → ${describeOrNull(expectedRoot)}`);
+    }
+    checkLayoutContract(root, violations);
+    const visited = new Set();
+    // hiddenAncestor: внутри скрытого поддерева геометрия не проверяется — дети
+    // скрытого могут быть «чистыми» со stale-layout прошлых кадров.
+    const stack = [{ node: root, hiddenAncestor: root.hidden }];
+    visited.add(root);
+    while (stack.length > 0) {
+        const { node, hiddenAncestor } = stack.pop();
+        for (const child of node.getChildren()) {
+            if (visited.has(child)) {
+                violations.push(`${describe(child)} встречается в дереве дважды (второй раз — как ребёнок ${describe(node)})`);
+                continue; // не обходим поддерево второй раз
+            }
+            visited.add(child);
+            const parent = child.getParent();
+            if (parent !== node) {
+                violations.push(`${describe(child)} — ребёнок ${describe(node)} (по getChildren), но getParent() → ${describeOrNull(parent)}`);
+            }
+            const childRoot = child.getRoot();
+            if (childRoot !== root) {
+                violations.push(`${describe(child)} не укоренён: getRoot() → ${describeOrNull(childRoot)} (ожидался ${describe(root)})`);
+            }
+            const childHidden = hiddenAncestor || child.hidden;
+            if (!childHidden) {
+                checkLayoutContract(child, violations);
+                checkContainment(node, child, violations);
+            }
+            stack.push({ node: child, hiddenAncestor: childHidden });
+        }
+    }
+    return violations;
+}
+/** Проверка layout-контракта одного узла (пропуски описаны в docstring выше). */
+function checkLayoutContract(node, violations) {
+    if (node.isLayoutDirty)
+        return;
+    const constraints = node.lastLayoutConstraints;
+    if (constraints === null)
+        return;
+    const size = node.layoutSize; // isLayoutDirty=false → lazy-layout не сработает
+    if (!constraints.isSatisfiedBy(size)) {
+        violations.push(`${describe(node)} нарушает layout-контракт: размер ${size.width}×${size.height} ` +
+            `не удовлетворяет constraints [${constraints.minWidth}..${constraints.maxWidth}]×` +
+            `[${constraints.minHeight}..${constraints.maxHeight}] последнего layout()`);
+    }
+}
+/** Инвариант вложенности (Н2): ребёнок геометрически внутри родителя. */
+function checkContainment(parent, child, violations) {
+    if (parent.isLayoutDirty || child.isLayoutDirty)
+        return;
+    if (parent.lastLayoutConstraints === null || child.lastLayoutConstraints === null)
+        return;
+    const parentRect = new Rect(parent.globalPosition, parent.layoutSize);
+    const childRect = new Rect(child.globalPosition, child.layoutSize);
+    const inside = childRect.x >= parentRect.x &&
+        childRect.y >= parentRect.y &&
+        childRect.right <= parentRect.right &&
+        childRect.bottom <= parentRect.bottom;
+    if (!inside) {
+        violations.push(`${describe(child)} вылезает за родителя ${describe(parent)}: ` +
+            `ребёнок [${childRect.x}..${childRect.right})×[${childRect.y}..${childRect.bottom}), ` +
+            `родитель [${parentRect.x}..${parentRect.right})×[${parentRect.y}..${parentRect.bottom})`);
+    }
+}
+/**
+ * Бросает с перечнем нарушений, если дерево невалидно. Вызывается после кадра
+ * при включённом `TuiApplication.validateTreeAfterRender`.
+ */
+export function assertValidTree(root) {
+    const violations = validateTree(root);
+    if (violations.length > 0) {
+        throw new Error(`Дерево TUIDom нарушает инварианты (${violations.length}):\n- ${violations.join("\n- ")}`);
+    }
+}
+function describe(element) {
+    const name = element.constructor.name;
+    const id = element.id !== undefined ? `#${element.id}` : "";
+    const role = element.role !== undefined ? `[role=${element.role}]` : "";
+    return `${name}${id}${role}`;
+}
+function describeOrNull(element) {
+    return element === null ? "null" : describe(element);
+}

package/dist/input/convertToken.d.ts

@@ -0,0 +1,3 @@
+import { type KeyPressEvent } from "./keyEvent.js";
+import type { RawKeyToken } from "./rawTerminalToken.js";
+export declare function convertTokenToKeyPressEvent(token: RawKeyToken): KeyPressEvent;

package/dist/input/convertToken.js

@@ -0,0 +1,114 @@
+import { createKeyPressEvent } from "./keyEvent.js";
+/**
+ * Map Kitty event type number to TUI event type string.
+ *
+ * Browser-aligned semantics: a held key fires repeated `keydown` events
+ * (with `repeat: true`), not `keypress`. We follow the same model so
+ * keydown listeners (e.g. the workbench for arrows/Backspace) auto-repeat.
+ *
+ * - 0 (not specified) → "keydown" (default is press per spec)
+ * - 1 (press) → "keydown"
+ * - 2 (repeat) → "keydown" (held key — also marked via the caller as a repeat)
+ * - 3 (release) → "keyup"
+ */
+function kittyEventType(eventType) {
+    switch (eventType) {
+        case 3:
+            return "keyup";
+        default:
+            return "keydown";
+    }
+}
+/**
+ * Физическая клавиша для control-кода: буквы дают `KeyA`…`KeyZ`, а пробел и
+ * символы из 0x1c–0x1f — свои `code` из UI Events, как в браузере (`Key\` и
+ * `Key6` там не существуют).
+ */
+function ctrlCharCode(letter) {
+    switch (letter) {
+        case " ":
+            return "Space";
+        case "\\":
+            return "Backslash";
+        case "]":
+            return "BracketRight";
+        case "6":
+            return "Digit6";
+        case "/":
+            return "Slash";
+        default:
+            return `Key${letter.toUpperCase()}`;
+    }
+}
+export function convertTokenToKeyPressEvent(token) {
+    switch (token.kind) {
+        case "csi-u": {
+            let key = token.key;
+            if (token.shiftedKey !== undefined) {
+                key = String.fromCodePoint(token.shiftedKey);
+            }
+            else if (token.shiftKey && key.length === 1 && key !== key.toUpperCase()) {
+                key = key.toUpperCase();
+            }
+            return createKeyPressEvent(key, token.raw, {
+                type: kittyEventType(token.eventType),
+                code: token.code,
+                shiftKey: token.shiftKey,
+                altKey: token.altKey,
+                ctrlKey: token.ctrlKey,
+                metaKey: token.metaKey,
+            });
+        }
+        case "csi-letter":
+            return createKeyPressEvent(token.key, token.raw, {
+                type: kittyEventType(token.eventType),
+                shiftKey: token.shiftKey,
+                altKey: token.altKey,
+                ctrlKey: token.ctrlKey,
+                metaKey: token.metaKey,
+            });
+        case "csi-tilde":
+            return createKeyPressEvent(token.key, token.raw, {
+                type: kittyEventType(token.eventType),
+                shiftKey: token.shiftKey,
+                altKey: token.altKey,
+                ctrlKey: token.ctrlKey,
+                metaKey: token.metaKey,
+            });
+        case "ss3":
+            return createKeyPressEvent(token.key, token.raw);
+        case "pua":
+            return createKeyPressEvent(token.key, token.raw, {
+                type: "keydown",
+                code: token.code,
+            });
+        case "esc-char":
+            return createKeyPressEvent(token.char, token.raw, { altKey: true });
+        case "esc-control":
+            return createKeyPressEvent(token.letter, token.raw, {
+                altKey: true,
+                ctrlKey: true,
+                code: `Key${token.letter.toUpperCase()}`,
+            });
+        case "esc-special":
+            return createKeyPressEvent(token.key, token.raw, { altKey: true });
+        case "standalone-esc":
+            return createKeyPressEvent("Escape", token.raw);
+        case "char":
+            return createKeyPressEvent(token.char, token.raw);
+        case "special-key":
+            return createKeyPressEvent(token.key, token.raw);
+        case "ctrl-char":
+            return createKeyPressEvent(token.letter, token.raw, {
+                ctrlKey: true,
+                code: ctrlCharCode(token.letter),
+            });
+        case "unknown-byte":
+            return createKeyPressEvent(`<0x${token.byte.toString(16).padStart(2, "0")}>`, token.raw);
+        /* v8 ignore next 4 -- exhaustiveness guard: RawKeyToken is a closed union, no other kind is constructible */
+        default: {
+            const exhaustive = token;
+            throw new Error(`Unhandled token kind: ${exhaustive.kind}`);
+        }
+    }
+}

package/dist/input/keyEvent.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TUI event types — web-style keyboard events with individual modifier flags.
+ *
+ * KeyPressEvent follows the DOM KeyboardEvent naming conventions:
+ * - `key`  — the value produced by the key ("a", "Enter", "ArrowUp")
+ * - `code` — the physical key identifier ("KeyA", "Enter", "ArrowUp")
+ * - Boolean modifier flags: ctrlKey, shiftKey, altKey, metaKey
+ *
+ * Discriminated union `TUIEvent` is extensible for future event types (click, focus, etc.)
+ */
+export interface KeyPressEvent {
+    /**
+     * Event type, following DOM KeyboardEvent naming:
+     * - "keypress" — synthesized companion event for printable input (legacy)
+     * - "keydown"  — key press or auto-repeat (Kitty event type 1 or 2)
+     * - "keyup"    — key release (Kitty event type 3)
+     */
+    readonly type: "keypress" | "keydown" | "keyup";
+    /**
+     * Key value, following the DOM KeyboardEvent.key naming convention.
+     *
+     * For printable characters: the character itself ("a", "A", "1", "!")
+     * For Ctrl+letter: just the lowercase letter ("c", not "Ctrl+C")
+     * For special keys: DOM name ("Enter", "ArrowUp", "F1", "Escape", etc.)
+     * For modifier keys: "Shift", "Control", "Alt", "Meta" (Kitty protocol)
+     */
+    readonly key: string;
+    /**
+     * Physical key code, following the DOM KeyboardEvent.code naming convention.
+     *
+     * "KeyA", "Digit1", "Space", "Enter", "ArrowUp", "F1", etc.
+     * For modifier keys: "ShiftLeft", "ControlLeft", "AltLeft", "MetaLeft", etc.
+     */
+    readonly code: string;
+    readonly ctrlKey: boolean;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+    /** Original raw bytes from the terminal (for debugging) */
+    readonly raw: string;
+}
+/** Discriminated union of all TUI events (extensible for click, focus, etc.) */
+export type TUIEvent = KeyPressEvent;
+/** Helper to create a KeyPressEvent with sensible defaults */
+export declare function createKeyPressEvent(key: string, raw: string, overrides?: Partial<KeyPressEvent>): KeyPressEvent;
+export { inferCode } from "./tokenize.js";

package/dist/input/keyEvent.js

@@ -0,0 +1,26 @@
+/**
+ * TUI event types — web-style keyboard events with individual modifier flags.
+ *
+ * KeyPressEvent follows the DOM KeyboardEvent naming conventions:
+ * - `key`  — the value produced by the key ("a", "Enter", "ArrowUp")
+ * - `code` — the physical key identifier ("KeyA", "Enter", "ArrowUp")
+ * - Boolean modifier flags: ctrlKey, shiftKey, altKey, metaKey
+ *
+ * Discriminated union `TUIEvent` is extensible for future event types (click, focus, etc.)
+ */
+import { inferCode } from "./tokenize.js";
+/** Helper to create a KeyPressEvent with sensible defaults */
+export function createKeyPressEvent(key, raw, overrides) {
+    return {
+        type: overrides?.type ?? "keydown",
+        key,
+        code: overrides?.code ?? inferCode(key),
+        ctrlKey: overrides?.ctrlKey ?? false,
+        shiftKey: overrides?.shiftKey ?? false,
+        altKey: overrides?.altKey ?? false,
+        metaKey: overrides?.metaKey ?? false,
+        raw,
+    };
+}
+// inferCode re-exported from TokenParsing layer
+export { inferCode } from "./tokenize.js";

package/dist/input/keyInputParser.d.ts

@@ -0,0 +1,72 @@
+import { type KeyPressEvent } from "./keyEvent.js";
+import type { DeviceReportToken, MouseToken, OscToken } from "./rawTerminalToken.js";
+/**
+ * Stateful keyboard input parser — browser-like KeyboardEvent model.
+ *
+ * Normalizes both legacy terminal input and Kitty protocol into a uniform
+ * event sequence matching the DOM KeyboardEvent spec:
+ *
+ * Normal keys:
+ *   keydown → keypress  (legacy: no keyup since protocol doesn't send it)
+ *   keydown → keypress → keyup  (Kitty: full lifecycle)
+ *   keydown → keypress → keydown → keypress → ... → keyup  (Kitty hold/auto-repeat)
+ *
+ * Modifier-only keys (Shift, Ctrl, Alt, Meta):
+ *   keydown → keyup  (no keypress — same as browser)
+ *
+ * Orphaned keyup (macOS Cmd+Arrow — release without prior press):
+ *   synthesizes keydown + keypress before the keyup
+ *
+ * Usage:
+ *   const parser = new KeyInputParser();
+ *   stdin.on("data", (chunk) => {
+ *       const events = parser.parse(chunk);
+ *   });
+ */
+interface InputStreams {
+    keys: KeyPressEvent[];
+    mouse: MouseToken[];
+    osc: OscToken[];
+    deviceReports: DeviceReportToken[];
+    /** Text blocks delivered via bracketed paste (already newline-normalized). */
+    paste: string[];
+}
+export declare class KeyInputParser {
+    private readonly pressedKeys;
+    /** Tail of the previous chunk that was cut mid-escape-sequence; "" when none. */
+    private pending;
+    /** True while accumulating bracketed-paste content (between ESC[200~ and ESC[201~). */
+    private pasting;
+    /** Pasted text accumulated so far, awaiting the ESC[201~ end marker. */
+    private pasteBuffer;
+    /**
+     * Parse a chunk of raw terminal input into browser-like keyboard events.
+     */
+    parse(data: string): KeyPressEvent[];
+    /**
+     * Parse raw terminal input, returning both keyboard events and mouse tokens.
+     */
+    parseWithMouse(data: string): InputStreams;
+    /** True when a partial escape sequence is buffered, awaiting the rest of its bytes. */
+    hasPending(): boolean;
+    /**
+     * Force-process any buffered partial sequence as-is (a lone ESC becomes the
+     * Escape key). Callers use a short timeout so a real Escape keypress isn't
+     * held hostage waiting for a continuation that never comes.
+     *
+     * While a paste is in flight (ESC[200~ seen, ESC[201~ not yet), this is a no-op:
+     * the held tail is a split end marker, not a stuck escape — keep accumulating so
+     * the paste isn't corrupted or truncated.
+     */
+    flush(): InputStreams;
+    /**
+     * Reassemble the stream across reads, splitting out bracketed-paste blocks so
+     * their literal text bypasses key tokenization entirely. Normal segments keep the
+     * existing behavior: prepend any buffered tail, then hold back a fresh incomplete
+     * tail so an escape sequence cut across stdin reads is reassembled next chunk.
+     */
+    private ingest;
+    private tokenizeInto;
+    private processKeyEvents;
+}
+export {};