@tuidom/inspector 0.1.0

package/dist/InspectorCore.d.ts

@@ -0,0 +1,33 @@
+import type { TUIElement } from "@tuidom/core/dom/tuiElement";
+import type { InspectorDriver } from "./InspectorDriver.js";
+import { type InspectorRequest, type InspectorResponse } from "./protocol.js";
+/**
+ * Read-only view of the inspected application. Decouples the core from
+ * `TuiApplication` so the same core can be driven by a WS server, an in-process
+ * inspector widget, or a test.
+ */
+export interface InspectorTarget {
+    getRoot(): TUIElement | null;
+    getFocused(): TUIElement | null;
+}
+type MethodHandler = (params: unknown) => unknown;
+/**
+ * Transport-agnostic inspector. Holds a read-only reference to the inspected
+ * app via `InspectorTarget` and answers protocol methods. Methods are a
+ * registry, so new ones extend the inspector without touching `dispatch`.
+ *
+ * When constructed with an optional {@link InspectorDriver}, it additionally
+ * registers the write/capture methods (`sendKey`, `sendText`, `resize`,
+ * `captureFrame`, `shutdown`) — used by `--headless` mode. Without a driver the
+ * inspector stays read-only.
+ */
+export declare class InspectorCore {
+    private readonly target;
+    private readonly methods;
+    constructor(target: InspectorTarget, driver?: InspectorDriver);
+    register(method: string, handler: MethodHandler): void;
+    dispatch(request: InspectorRequest): Promise<InspectorResponse>;
+    private getDocument;
+    private registerDriverMethods;
+}
+export {};

package/dist/InspectorCore.js

@@ -0,0 +1,144 @@
+import { InspectorMethod, } from "./protocol.js";
+import { serializeTree } from "./serializeTree.js";
+/**
+ * Transport-agnostic inspector. Holds a read-only reference to the inspected
+ * app via `InspectorTarget` and answers protocol methods. Methods are a
+ * registry, so new ones extend the inspector without touching `dispatch`.
+ *
+ * When constructed with an optional {@link InspectorDriver}, it additionally
+ * registers the write/capture methods (`sendKey`, `sendText`, `resize`,
+ * `captureFrame`, `shutdown`) — used by `--headless` mode. Without a driver the
+ * inspector stays read-only.
+ */
+export class InspectorCore {
+    target;
+    methods = new Map();
+    constructor(target, driver) {
+        this.target = target;
+        this.register(InspectorMethod.getDocument, () => this.getDocument());
+        if (driver !== undefined)
+            this.registerDriverMethods(driver);
+    }
+    register(method, handler) {
+        this.methods.set(method, handler);
+    }
+    async dispatch(request) {
+        const handler = this.methods.get(request.method);
+        if (handler === undefined) {
+            return { id: request.id, error: { message: `Unknown method: ${request.method}` } };
+        }
+        try {
+            return { id: request.id, result: await handler(request.params) };
+        }
+        catch (err) {
+            return { id: request.id, error: { message: err instanceof Error ? err.message : String(err) } };
+        }
+    }
+    getDocument() {
+        return { root: serializeTree(this.target.getRoot(), this.target.getFocused()) };
+    }
+    registerDriverMethods(driver) {
+        this.register(InspectorMethod.sendKey, (params) => {
+            driver.sendKey(asSendKeyParams(params).name);
+            return {};
+        });
+        this.register(InspectorMethod.sendText, (params) => {
+            driver.sendText(asSendTextParams(params).text);
+            return {};
+        });
+        this.register(InspectorMethod.sendMouse, (params) => {
+            driver.sendMouse(asSendMouseParams(params));
+            return {};
+        });
+        this.register(InspectorMethod.resize, (params) => {
+            const { cols, rows } = asResizeParams(params);
+            driver.resize(cols, rows);
+            return {};
+        });
+        this.register(InspectorMethod.captureFrame, async () => {
+            return { frame: await driver.captureFrame() };
+        });
+        this.register(InspectorMethod.waitForIdle, (params) => {
+            return driver.waitForIdle(asWaitForIdleParams(params));
+        });
+        this.register(InspectorMethod.shutdown, () => {
+            driver.shutdown();
+            return {};
+        });
+    }
+}
+function asRecord(params) {
+    if (typeof params !== "object" || params === null) {
+        throw new Error("Expected object params");
+    }
+    return params;
+}
+function asSendKeyParams(params) {
+    const { name } = asRecord(params);
+    if (typeof name !== "string" || name.length === 0) {
+        throw new Error("sendKey requires a non-empty string 'name'");
+    }
+    return { name };
+}
+function asSendTextParams(params) {
+    const { text } = asRecord(params);
+    if (typeof text !== "string") {
+        throw new Error("sendText requires a string 'text'");
+    }
+    return { text };
+}
+const MOUSE_ACTIONS = new Set([
+    "press",
+    "release",
+    "move",
+    "scroll-up",
+    "scroll-down",
+    "scroll-left",
+    "scroll-right",
+]);
+const MOUSE_BUTTONS = new Set(["left", "middle", "right", "none"]);
+function asSendMouseParams(params) {
+    const { action, button, x, y, shiftKey, altKey, ctrlKey } = asRecord(params);
+    if (typeof action !== "string" || !MOUSE_ACTIONS.has(action)) {
+        throw new Error(`sendMouse requires 'action' one of: ${[...MOUSE_ACTIONS].join(", ")}`);
+    }
+    if (button !== undefined && (typeof button !== "string" || !MOUSE_BUTTONS.has(button))) {
+        throw new Error(`sendMouse 'button' must be one of: ${[...MOUSE_BUTTONS].join(", ")}`);
+    }
+    if (!Number.isInteger(x) || !Number.isInteger(y) || x < 0 || y < 0) {
+        throw new Error("sendMouse requires non-negative integer 'x' and 'y'");
+    }
+    return {
+        action: action,
+        ...(button === undefined ? {} : { button: button }),
+        x: x,
+        y: y,
+        shiftKey: shiftKey === true,
+        altKey: altKey === true,
+        ctrlKey: ctrlKey === true,
+    };
+}
+function asWaitForIdleParams(params) {
+    if (params === undefined || params === null)
+        return {};
+    const { quietMs, timeoutMs } = asRecord(params);
+    const out = {};
+    if (quietMs !== undefined) {
+        if (!Number.isFinite(quietMs) || quietMs < 0)
+            throw new Error("waitForIdle 'quietMs' must be a non-negative number");
+        out.quietMs = quietMs;
+    }
+    if (timeoutMs !== undefined) {
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+            throw new Error("waitForIdle 'timeoutMs' must be a non-negative number");
+        out.timeoutMs = timeoutMs;
+    }
+    return out;
+}
+function asResizeParams(params) {
+    const { cols, rows } = asRecord(params);
+    if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols <= 0 || rows <= 0) {
+        throw new Error("resize requires positive integer 'cols' and 'rows'");
+    }
+    return { cols: cols, rows: rows };
+}

package/dist/InspectorDriver.d.ts

@@ -0,0 +1,35 @@
+import type { GridSnapshot } from "@tuidom/core/rendering/gridSnapshot";
+import type { SendMouseParams, WaitForIdleParams, WaitForIdleResult } from "./protocol.js";
+/**
+ * Write/capture side of the inspector — the counterpart to the read-only
+ * {@link import("./InspectorCore.js").InspectorTarget}. Present only when the app
+ * runs in a drivable mode (headless capture); a normal terminal session attaches
+ * the inspector without a driver and stays read-only.
+ *
+ * The App layer supplies the concrete adapter (over `HeadlessCaptureBackend`), so
+ * the Inspector layer never imports Backend — it only depends on this port and on
+ * the {@link GridSnapshot} data type.
+ */
+export interface InspectorDriver {
+    /** Inject a key by DSL name (`"a"`, `"Enter"`, `"Ctrl+P"`). */
+    sendKey(name: string): void;
+    /** Inject literal text as a single bracketed paste. */
+    sendText(text: string): void;
+    /** Inject a mouse event at 0-based screen coordinates (see {@link SendMouseParams}). */
+    sendMouse(params: SendMouseParams): void;
+    /** Resize the virtual terminal. */
+    resize(cols: number, rows: number): void;
+    /**
+     * Capture the current screen. Async so the adapter can first drain any
+     * deferred render (the app schedules some renders on `setImmediate`).
+     */
+    captureFrame(): Promise<GridSnapshot>;
+    /**
+     * Wait until the app stops repainting (frame counter stable + no scheduled
+     * render). Lets a client settle after injecting input without guessing a
+     * `sleep`. Resolves `idle: false` on timeout rather than rejecting.
+     */
+    waitForIdle(params: WaitForIdleParams): Promise<WaitForIdleResult>;
+    /** Tear down the session and exit the process. */
+    shutdown(): void;
+}

package/dist/InspectorDriver.js

@@ -0,0 +1 @@
+export {};

package/dist/InspectorServer.d.ts

@@ -0,0 +1,23 @@
+import type { InspectorCore } from "./InspectorCore.js";
+export interface InspectorServerOptions {
+    host?: string;
+    port?: number;
+}
+/**
+ * WebSocket transport for the inspector: a hand-written RFC6455 server over
+ * node:http (zero runtime deps). Routes each inbound JSON message to
+ * `InspectorCore.dispatch` and writes back the response frame.
+ */
+export declare class InspectorServer {
+    private readonly core;
+    private readonly httpServer;
+    private readonly sockets;
+    constructor(core: InspectorCore);
+    listen(options?: InspectorServerOptions): Promise<{
+        port: number;
+    }>;
+    dispose(): void;
+    private handleUpgrade;
+    private handleFrame;
+    private dispatchAndReply;
+}

package/dist/InspectorServer.js

@@ -0,0 +1,89 @@
+import { createServer } from "node:http";
+import { decodeFrames, encodeFrame, encodeTextFrame, OPCODE_CLOSE, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, } from "./ws/frame.js";
+import { computeAcceptKey } from "./ws/handshake.js";
+/**
+ * WebSocket transport for the inspector: a hand-written RFC6455 server over
+ * node:http (zero runtime deps). Routes each inbound JSON message to
+ * `InspectorCore.dispatch` and writes back the response frame.
+ */
+export class InspectorServer {
+    core;
+    httpServer;
+    sockets = new Set();
+    constructor(core) {
+        this.core = core;
+        this.httpServer = createServer((_req, res) => {
+            res.writeHead(426); // Upgrade Required — this endpoint is WebSocket only
+            res.end("WebSocket only");
+        });
+        this.httpServer.on("upgrade", (req, socket) => {
+            this.handleUpgrade(req, socket);
+        });
+    }
+    listen(options = {}) {
+        const host = options.host ?? "127.0.0.1";
+        const port = options.port ?? 0;
+        return new Promise((resolve) => {
+            this.httpServer.listen(port, host, () => {
+                const addr = this.httpServer.address();
+                const boundPort = typeof addr === "object" && addr !== null ? addr.port : port;
+                resolve({ port: boundPort });
+            });
+        });
+    }
+    dispose() {
+        for (const socket of this.sockets)
+            socket.destroy();
+        this.sockets.clear();
+        this.httpServer.close();
+    }
+    handleUpgrade(req, socket) {
+        const key = req.headers["sec-websocket-key"];
+        if (typeof key !== "string") {
+            socket.destroy();
+            return;
+        }
+        socket.write("HTTP/1.1 101 Switching Protocols\r\n" +
+            "Upgrade: websocket\r\n" +
+            "Connection: Upgrade\r\n" +
+            `Sec-WebSocket-Accept: ${computeAcceptKey(key)}\r\n\r\n`);
+        this.sockets.add(socket);
+        let buffer = Buffer.alloc(0);
+        socket.on("data", (chunk) => {
+            buffer = Buffer.concat([buffer, chunk]);
+            const { frames, rest } = decodeFrames(buffer);
+            buffer = rest;
+            for (const frame of frames) {
+                this.handleFrame(socket, frame.opcode, frame.payload);
+            }
+        });
+        socket.on("close", () => this.sockets.delete(socket));
+        socket.on("error", () => this.sockets.delete(socket));
+    }
+    handleFrame(socket, opcode, payload) {
+        if (opcode === OPCODE_CLOSE) {
+            socket.end();
+            return;
+        }
+        if (opcode === OPCODE_PING) {
+            socket.write(encodeFrame(OPCODE_PONG, Buffer.from(payload, "utf8")));
+            return;
+        }
+        if (opcode !== OPCODE_TEXT)
+            return;
+        let request;
+        try {
+            request = JSON.parse(payload);
+        }
+        catch {
+            return; // ignore non-JSON frames
+        }
+        void this.dispatchAndReply(socket, request);
+    }
+    async dispatchAndReply(socket, request) {
+        const response = await this.core.dispatch(request);
+        if (socket.destroyed)
+            return;
+        socket.write(encodeTextFrame(JSON.stringify(response)));
+    }
+}

package/dist/attachInspector.d.ts

@@ -0,0 +1,18 @@
+import type { TuiApplication } from "@tuidom/core/dom/tuiApplication";
+import { InspectorCore } from "./InspectorCore.js";
+import type { InspectorDriver } from "./InspectorDriver.js";
+import { InspectorServer, type InspectorServerOptions } from "./InspectorServer.js";
+export interface AttachedInspector {
+    core: InspectorCore;
+    server: InspectorServer;
+    port: number;
+    dispose(): void;
+}
+/**
+ * Attach an inspector to a running `TuiApplication` over WebSocket. Reads the
+ * app read-only (root/focus). When a {@link InspectorDriver} is supplied (headless
+ * mode) the inspector also exposes input-injection and frame-capture methods;
+ * without it the inspector stays read-only. For in-process use (e.g. a
+ * split-screen inspector widget) build an `InspectorCore` directly instead.
+ */
+export declare function attachInspector(app: TuiApplication, options?: InspectorServerOptions, driver?: InspectorDriver): Promise<AttachedInspector>;

package/dist/attachInspector.js

@@ -0,0 +1,26 @@
+import { InspectorCore } from "./InspectorCore.js";
+import { InspectorServer } from "./InspectorServer.js";
+/**
+ * Attach an inspector to a running `TuiApplication` over WebSocket. Reads the
+ * app read-only (root/focus). When a {@link InspectorDriver} is supplied (headless
+ * mode) the inspector also exposes input-injection and frame-capture methods;
+ * without it the inspector stays read-only. For in-process use (e.g. a
+ * split-screen inspector widget) build an `InspectorCore` directly instead.
+ */
+export async function attachInspector(app, options = {}, driver) {
+    const target = {
+        getRoot: () => app.root,
+        getFocused: () => app.focusManager?.activeElement ?? null,
+    };
+    const core = new InspectorCore(target, driver);
+    const server = new InspectorServer(core);
+    const { port } = await server.listen(options);
+    return {
+        core,
+        server,
+        port,
+        dispose: () => {
+            server.dispose();
+        },
+    };
+}

package/dist/idleWaiter.d.ts

@@ -0,0 +1,34 @@
+/** Наблюдаемое состояние отрисовки — то, что даёт `TuiApplication`. */
+export interface IdleSource {
+    /** Монотонный счётчик отрисованных кадров. */
+    frameCount(): number;
+    /** Есть ли ещё не выполненный отложенный рендер. */
+    isRenderScheduled(): boolean;
+}
+/** Часы: вынесены параметром ради детерминированных юнит-тестов. */
+export interface IdleClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export interface WaitForIdleOptions {
+    /** Сколько кадр должен простоять неизменным, чтобы считаться устоявшимся. */
+    quietMs?: number;
+    /** Предел ожидания; по истечении возвращаем `idle: false` (не бросаем). */
+    timeoutMs?: number;
+    /** Период опроса источника. */
+    pollMs?: number;
+    /** Подменяемые часы (по умолчанию — реальные). */
+    clock?: IdleClock;
+}
+export interface WaitForIdleResult {
+    /** `true` — дождались тишины; `false` — упёрлись в `timeoutMs`. */
+    idle: boolean;
+    /** `frameCount` на момент возврата. */
+    frames: number;
+}
+/**
+ * Ждёт, пока `source` перестанет перерисовываться. Возвращает `{ idle, frames }`;
+ * по таймауту — `idle: false` (решение, ждать ли дальше, за вызывающим). Никогда
+ * не бросает.
+ */
+export declare function waitForIdle(source: IdleSource, options?: WaitForIdleOptions): Promise<WaitForIdleResult>;

package/dist/idleWaiter.js

@@ -0,0 +1,45 @@
+// Ожидание «рендер устоялся» для инспектора. Клиент (e2e) после инъекции ввода
+// хочет дождаться, пока приложение перестанет перерисовываться, — не угадывая
+// паузу `sleep`, а наблюдая за реальным счётчиком кадров. «Устоялся» = frameCount
+// не менялся в течение `quietMs` И нет отложенного (setImmediate) рендера.
+//
+// Важно: это «рендер устоялся», а НЕ «все эффекты завершились». Асинхронные
+// хвосты (ответ ext-host'а, дебаунс StateService) idle не ловит — под них клиент
+// использует предикат по дереву/кадру, а не увеличенный quietMs.
+const DEFAULT_QUIET_MS = 40;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_POLL_MS = 10;
+const realClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Ждёт, пока `source` перестанет перерисовываться. Возвращает `{ idle, frames }`;
+ * по таймауту — `idle: false` (решение, ждать ли дальше, за вызывающим). Никогда
+ * не бросает.
+ */
+export async function waitForIdle(source, options = {}) {
+    const quietMs = options.quietMs ?? DEFAULT_QUIET_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const clock = options.clock ?? realClock;
+    const start = clock.now();
+    let lastFrame = source.frameCount();
+    let lastChange = start;
+    for (;;) {
+        const now = clock.now();
+        const frame = source.frameCount();
+        const busy = frame !== lastFrame || source.isRenderScheduled();
+        if (busy) {
+            lastFrame = frame;
+            lastChange = now;
+        }
+        else if (now - lastChange >= quietMs) {
+            return { idle: true, frames: frame };
+        }
+        if (now - start >= timeoutMs) {
+            return { idle: false, frames: frame };
+        }
+        await clock.sleep(pollMs);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type AttachedInspector, attachInspector } from "./attachInspector.js";
+export { InspectorCore, type InspectorTarget } from "./InspectorCore.js";
+export type { InspectorDriver } from "./InspectorDriver.js";
+export { InspectorServer, type InspectorServerOptions } from "./InspectorServer.js";
+export * from "./protocol.js";
+export { serializeTree } from "./serializeTree.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { attachInspector } from "./attachInspector.js";
+export { InspectorCore } from "./InspectorCore.js";
+export { InspectorServer } from "./InspectorServer.js";
+export * from "./protocol.js";
+export { serializeTree } from "./serializeTree.js";

package/dist/protocol.d.ts

@@ -0,0 +1,133 @@
+import type { MouseAction, MouseButton } from "@tuidom/core/input/rawTerminalToken";
+import type { GridSnapshot } from "@tuidom/core/rendering/gridSnapshot";
+/** Method names (namespace `TUIDom.*`). */
+export declare const InspectorMethod: {
+    readonly getDocument: "TUIDom.getDocument";
+    /** Inject a key by DSL name. Requires a driver (headless mode). */
+    readonly sendKey: "TUIDom.sendKey";
+    /** Inject literal text as a paste. Requires a driver. */
+    readonly sendText: "TUIDom.sendText";
+    /** Inject a mouse event at screen coordinates. Requires a driver. */
+    readonly sendMouse: "TUIDom.sendMouse";
+    /** Resize the virtual terminal. Requires a driver. */
+    readonly resize: "TUIDom.resize";
+    /** Capture the current screen as a {@link GridSnapshot}. Requires a driver. */
+    readonly captureFrame: "TUIDom.captureFrame";
+    /** Wait until the app stops repainting (render settles). Requires a driver. */
+    readonly waitForIdle: "TUIDom.waitForIdle";
+    /** Tear down the session and exit. Requires a driver. */
+    readonly shutdown: "TUIDom.shutdown";
+};
+/** Params for `TUIDom.sendKey`. */
+export interface SendKeyParams {
+    name: string;
+}
+/** Params for `TUIDom.sendText`. */
+export interface SendTextParams {
+    text: string;
+}
+/**
+ * Params for `TUIDom.sendMouse`.
+ *
+ * Coordinates are **0-based screen cells**, the same frame of reference as
+ * {@link NodeSnapshot.box} — so a client can read the document, take a node's
+ * `box` and click into it without any coordinate arithmetic.
+ *
+ * A click is two calls (`press` then `release`) — the same pair a terminal sends;
+ * the DOM's `click`/`dblclick` events are synthesized from it downstream.
+ */
+export interface SendMouseParams {
+    action: MouseAction;
+    /** Defaults to `"none"` — the only meaningful button for wheel actions. */
+    button?: MouseButton;
+    /** 0-based column */
+    x: number;
+    /** 0-based row */
+    y: number;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+}
+/** Params for `TUIDom.resize`. */
+export interface ResizeParams {
+    cols: number;
+    rows: number;
+}
+/** Result of `TUIDom.captureFrame`. */
+export interface CaptureFrameResult {
+    frame: GridSnapshot;
+}
+/** Params for `TUIDom.waitForIdle`. */
+export interface WaitForIdleParams {
+    /** How long a frame must stay unchanged to count as settled (ms). */
+    quietMs?: number;
+    /** Give up after this long and report `idle: false` (ms). */
+    timeoutMs?: number;
+}
+/** Result of `TUIDom.waitForIdle`. */
+export interface WaitForIdleResult {
+    /** `true` — render settled; `false` — timed out while still repainting. */
+    idle: boolean;
+    /** Frame counter at return. */
+    frames: number;
+}
+/** Serialized tree node. */
+export interface NodeSnapshot {
+    /** Sequential id within a single snapshot (pre-order). Not stable across snapshots yet. */
+    nodeId: number;
+    /** Runtime class name (e.g. "BodyElement"). */
+    type: string;
+    id?: string;
+    role?: string;
+    focusable?: true;
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    style: {
+        fg: number;
+        bg: number;
+    };
+    /** Активные состояния стиля (hover/focus/произвольные) — если есть. */
+    styleStates?: string[];
+    /** Исходные имена токенов рядом с резолвленными числами style — если стиль ссылается на токены. */
+    styleTokens?: {
+        fg?: string;
+        bg?: string;
+    };
+    /** Элемент владеет заливкой фона (bg задан собственным стилем). */
+    ownBackground?: true;
+    focused: boolean;
+    text?: string;
+    /**
+     * Observable widget state, self-described by the element's `inspectState()`
+     * (cursor/selection/readonly for an editor, active tab for a panel, …).
+     * Absent when the element exposes none. Lets e2e assert on data instead of
+     * guessing from rendered cells.
+     */
+    state?: Record<string, unknown>;
+    children: NodeSnapshot[];
+}
+/** Result of `TUIDom.getDocument`. */
+export interface GetDocumentResult {
+    root: NodeSnapshot | null;
+}
+/** Inbound request envelope. */
+export interface InspectorRequest {
+    id: number;
+    method: string;
+    params?: unknown;
+}
+export interface InspectorSuccessResponse {
+    id: number;
+    result: unknown;
+}
+export interface InspectorErrorResponse {
+    id: number;
+    error: {
+        message: string;
+    };
+}
+export type InspectorResponse = InspectorSuccessResponse | InspectorErrorResponse;

package/dist/protocol.js

@@ -0,0 +1,24 @@
+// TUIDom inspector protocol — own, CDP-shaped (not CDP-compatible).
+//
+// Wire form mirrors Chrome DevTools Protocol in shape only: a request carries
+// `{ id, method, params? }`, a reply is `{ id, result }` or `{ id, error }`.
+// Methods live under the `TUIDom.*` namespace. The protocol is transport-
+// agnostic — InspectorCore speaks it directly (in-process) or over WebSocket.
+/** Method names (namespace `TUIDom.*`). */
+export const InspectorMethod = {
+    getDocument: "TUIDom.getDocument",
+    /** Inject a key by DSL name. Requires a driver (headless mode). */
+    sendKey: "TUIDom.sendKey",
+    /** Inject literal text as a paste. Requires a driver. */
+    sendText: "TUIDom.sendText",
+    /** Inject a mouse event at screen coordinates. Requires a driver. */
+    sendMouse: "TUIDom.sendMouse",
+    /** Resize the virtual terminal. Requires a driver. */
+    resize: "TUIDom.resize",
+    /** Capture the current screen as a {@link GridSnapshot}. Requires a driver. */
+    captureFrame: "TUIDom.captureFrame",
+    /** Wait until the app stops repainting (render settles). Requires a driver. */
+    waitForIdle: "TUIDom.waitForIdle",
+    /** Tear down the session and exit. Requires a driver. */
+    shutdown: "TUIDom.shutdown",
+};

package/dist/serializeTree.d.ts

@@ -0,0 +1,7 @@
+import type { TUIElement } from "@tuidom/core/dom/tuiElement";
+import type { NodeSnapshot } from "./protocol.js";
+/**
+ * Serialize a TUIDom subtree into a plain JSON snapshot, reading only public
+ * accessors of TUIElement (no widget changes). `nodeId` is assigned pre-order.
+ */
+export declare function serializeTree(root: TUIElement | null, focused: TUIElement | null): NodeSnapshot | null;

package/dist/serializeTree.js

@@ -0,0 +1,58 @@
+import { TextLabelElement } from "@tuidom/elements/text/textLabelElement";
+/**
+ * Serialize a TUIDom subtree into a plain JSON snapshot, reading only public
+ * accessors of TUIElement (no widget changes). `nodeId` is assigned pre-order.
+ */
+export function serializeTree(root, focused) {
+    if (root === null)
+        return null;
+    return serializeNode(root, focused, { next: 0 });
+}
+function serializeNode(element, focused, counter) {
+    const nodeId = counter.next++;
+    const pos = element.globalPosition;
+    const size = element.layoutSize;
+    const style = element.resolvedStyle;
+    const snapshot = {
+        nodeId,
+        type: element.constructor.name,
+        box: { x: pos.x, y: pos.y, width: size.width, height: size.height },
+        style: { fg: style.fg, bg: style.bg },
+        focused: element === focused,
+        children: [],
+    };
+    if (element.id !== undefined)
+        snapshot.id = element.id;
+    if (element.role !== undefined)
+        snapshot.role = element.role;
+    if (element.focusable)
+        snapshot.focusable = true;
+    const states = element.activeStyleStates;
+    if (states.length > 0)
+        snapshot.styleStates = [...states];
+    const applied = element.appliedStyle;
+    if (typeof applied.fg === "string" || typeof applied.bg === "string") {
+        snapshot.styleTokens = {};
+        if (typeof applied.fg === "string")
+            snapshot.styleTokens.fg = applied.fg;
+        if (typeof applied.bg === "string")
+            snapshot.styleTokens.bg = applied.bg;
+    }
+    if (element.hasOwnBackground)
+        snapshot.ownBackground = true;
+    if (element instanceof TextLabelElement)
+        snapshot.text = element.getText();
+    const state = element.inspectState();
+    if (state !== undefined)
+        snapshot.state = state;
+    // Скрытые (hidden) поддеревья не сериализуются: инспектор — «глаз
+    // пользователя», а скрытое не рисуется, не кликается и не участвует в
+    // Tab-обходе. Структурно такие элементы остаются в дереве (стили/root
+    // доходят) — но e2e-тест, ждущий исчезновения виджета со сцены
+    // (waitForNoNode), должен видеть ровно то же, что видит пользователь.
+    snapshot.children = element
+        .getChildren()
+        .filter((child) => !child.hidden)
+        .map((child) => serializeNode(child, focused, counter));
+    return snapshot;
+}

package/dist/ws/frame.d.ts

@@ -0,0 +1,20 @@
+export declare const OPCODE_TEXT = 1;
+export declare const OPCODE_CLOSE = 8;
+export declare const OPCODE_PING = 9;
+export declare const OPCODE_PONG = 10;
+export interface DecodedFrame {
+    opcode: number;
+    payload: string;
+}
+/**
+ * Extract every complete frame buffered so far. Returns the decoded frames and
+ * the unconsumed tail (a partial frame awaiting more bytes).
+ */
+export declare function decodeFrames(buffer: Buffer): {
+    frames: DecodedFrame[];
+    rest: Buffer;
+};
+/** Encode a server→client frame (unmasked, single fragment). */
+export declare function encodeFrame(opcode: number, payload: Buffer): Buffer;
+/** Encode a server→client text frame. */
+export declare function encodeTextFrame(text: string): Buffer;

package/dist/ws/frame.js

@@ -0,0 +1,78 @@
+// Minimal RFC6455 codec. Scope: single-fragment frames (FIN=1), client→server
+// masked, payloads up to 64 KiB practical. No continuation frames — inspector
+// messages are small JSON. Enough for the inspector transport.
+export const OPCODE_TEXT = 0x1;
+export const OPCODE_CLOSE = 0x8;
+export const OPCODE_PING = 0x9;
+export const OPCODE_PONG = 0xa;
+/**
+ * Extract every complete frame buffered so far. Returns the decoded frames and
+ * the unconsumed tail (a partial frame awaiting more bytes).
+ */
+export function decodeFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (offset + 2 <= buffer.length) {
+        const b1 = buffer[offset + 1];
+        const opcode = buffer[offset] & 0x0f;
+        const masked = (b1 & 0x80) !== 0;
+        let len = b1 & 0x7f;
+        let pos = offset + 2;
+        if (len === 126) {
+            if (pos + 2 > buffer.length)
+                break;
+            len = buffer.readUInt16BE(pos);
+            pos += 2;
+        }
+        else if (len === 127) {
+            if (pos + 8 > buffer.length)
+                break;
+            len = Number(buffer.readBigUInt64BE(pos));
+            pos += 8;
+        }
+        const maskLen = masked ? 4 : 0;
+        if (pos + maskLen + len > buffer.length)
+            break; // frame not fully arrived
+        let payload;
+        if (masked) {
+            const mask = buffer.subarray(pos, pos + 4);
+            pos += 4;
+            payload = Buffer.allocUnsafe(len);
+            for (let i = 0; i < len; i++) {
+                payload[i] = buffer[pos + i] ^ mask[i & 3];
+            }
+        }
+        else {
+            payload = buffer.subarray(pos, pos + len);
+        }
+        pos += len;
+        frames.push({ opcode, payload: payload.toString("utf8") });
+        offset = pos;
+    }
+    return { frames, rest: buffer.subarray(offset) };
+}
+/** Encode a server→client frame (unmasked, single fragment). */
+export function encodeFrame(opcode, payload) {
+    const len = payload.length;
+    let header;
+    if (len < 126) {
+        header = Buffer.from([0x80 | opcode, len]);
+    }
+    else if (len < 65536) {
+        header = Buffer.allocUnsafe(4);
+        header[0] = 0x80 | opcode;
+        header[1] = 126;
+        header.writeUInt16BE(len, 2);
+    }
+    else {
+        header = Buffer.allocUnsafe(10);
+        header[0] = 0x80 | opcode;
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(len), 2);
+    }
+    return Buffer.concat([header, payload]);
+}
+/** Encode a server→client text frame. */
+export function encodeTextFrame(text) {
+    return encodeFrame(OPCODE_TEXT, Buffer.from(text, "utf8"));
+}

package/dist/ws/handshake.d.ts

@@ -0,0 +1,2 @@
+/** Compute the Sec-WebSocket-Accept value for a client's Sec-WebSocket-Key. */
+export declare function computeAcceptKey(secWebSocketKey: string): string;

package/dist/ws/handshake.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+// RFC6455 magic GUID appended to Sec-WebSocket-Key before hashing.
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+/** Compute the Sec-WebSocket-Accept value for a client's Sec-WebSocket-Key. */
+export function computeAcceptKey(secWebSocketKey) {
+    return createHash("sha1")
+        .update(secWebSocketKey + WS_GUID)
+        .digest("base64");
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@tuidom/inspector",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "Experimental terminal UI DOM — WebSocket inspector for devtools/e2e (hand-written RFC6455, zero-dep). API is unstable.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/tuidom/tuidom.git",
+        "directory": "packages/inspector"
+    },
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "keywords": [
+        "tui",
+        "terminal",
+        "ui",
+        "dom",
+        "inspector",
+        "devtools"
+    ],
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        "./package.json": "./package.json",
+        "./*.js": "./dist/*.js",
+        "./*": "./dist/*.js"
+    },
+    "dependencies": {
+        "@tuidom/core": "0.1.0",
+        "@tuidom/elements": "0.1.0"
+    }
+}