@kitlangton/terminal-control-opentui 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kit Langton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @kitlangton/terminal-control-opentui
+
+Expose a consistent semantic snapshot from any OpenTUI application controlled by Terminal Control.
+
+```bash
+bun add @kitlangton/terminal-control-opentui @opentui/core
+```
+
+Pass the application's live `CliRenderer` during startup:
+
+```ts
+import { provideTerminalControl } from "@kitlangton/terminal-control-opentui"
+
+const terminalControl = provideTerminalControl(renderer, {
+  application: { name: "my-tui", version: "1.0.0" },
+})
+
+renderer.once("destroy", () => terminalControl.close())
+```
+
+Outside Terminal Control the integration is a no-op. Launch the application with Terminal Control's
+OpenTUI host profile, then inspect the semantic tree:
+
+```bash
+termctrl start app --host opentui -- my-tui
+termctrl show app --format semantic
+```
+
+The package walks the live OpenTUI render tree and consistently discovers visible focused editors,
+focusable controls, and reachable mouse targets. It derives roles, labels, focus state, and live
+numeric element handles without requiring every application to maintain its own walker.
+
+`elements(renderer)` and `semanticSnapshot(renderer)` are also exported for tests and custom
+integrations.
+
+This package is released with Terminal Control's fixed-version package group. See the repository's
+`docs/releasing.md` process rather than publishing this directory directly.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type { CliRenderer } from "@opentui/core";
+import { type Provider } from "./provider.js";
+export type InteractableElement = {
+    readonly id: string;
+    readonly num: number;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly focusable: boolean;
+    readonly focused: boolean;
+    readonly clickable: boolean;
+    readonly editor: boolean;
+};
+export type SemanticNode = {
+    readonly id: string;
+    readonly role: string;
+    readonly label?: string;
+    readonly element: number;
+    readonly focused: boolean;
+    readonly disabled: boolean;
+};
+export type SemanticSnapshot = {
+    readonly format: "termctrl-semantic-snapshot-v1";
+    readonly nodes: ReadonlyArray<SemanticNode>;
+};
+export declare function elements(renderer: CliRenderer): InteractableElement[];
+export declare function semanticSnapshot(renderer: CliRenderer): SemanticSnapshot;
+export declare function provideTerminalControl(renderer: CliRenderer, options: {
+    readonly application: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    readonly socketPath?: string;
+    readonly onError?: (error: unknown) => void;
+}): Provider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,eAAe,CAAA;AAC5D,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAEtE,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAA;IAChD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;CAC5C,CAAA;AA4BD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,mBAAmB,EAAE,CAkBrE;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,gBAAgB,CAoBxE;AA6BD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE;IACP,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC5C,GACA,QAAQ,CASV"}

package/dist/index.js

@@ -0,0 +1,116 @@
+import { provideSemanticSnapshot } from "./provider.js";
+function children(renderable) {
+    return renderable.getChildren().filter((child) => "num" in child);
+}
+function all(renderable) {
+    return [renderable, ...children(renderable).flatMap(all)];
+}
+function hasMouseListeners(renderable) {
+    const listener = Reflect.get(renderable, "_mouseListener");
+    const listeners = Reflect.get(renderable, "_mouseListeners");
+    return Boolean(listener) || (isRecord(listeners) && Object.keys(listeners).length > 0);
+}
+function receivesClick(renderer, renderable) {
+    const bounds = visibleBounds(renderer, renderable);
+    if (!bounds)
+        return false;
+    const targets = new Set(all(renderable).map((item) => item.num));
+    for (let y = Math.floor(bounds.y); y < Math.ceil(bounds.y + bounds.height); y++) {
+        for (let x = Math.floor(bounds.x); x < Math.ceil(bounds.x + bounds.width); x++) {
+            if (targets.has(renderer.hitTest(x, y)))
+                return true;
+        }
+    }
+    return false;
+}
+export function elements(renderer) {
+    return all(renderer.root)
+        .flatMap((renderable) => {
+        const bounds = visibleBounds(renderer, renderable);
+        if (!bounds)
+            return [];
+        return [
+            {
+                id: renderable.id,
+                num: renderable.num,
+                ...bounds,
+                focusable: renderable.focusable,
+                focused: renderable.focused,
+                clickable: hasMouseListeners(renderable) && receivesClick(renderer, renderable),
+                editor: renderer.currentFocusedEditor === renderable,
+            },
+        ];
+    })
+        .filter((element) => element.focusable || element.clickable || element.editor);
+}
+export function semanticSnapshot(renderer) {
+    const renderables = new Map(all(renderer.root).map((renderable) => [renderable.num, renderable]));
+    const ids = new Set();
+    return {
+        format: "termctrl-semantic-snapshot-v1",
+        nodes: elements(renderer).map((element) => {
+            const preferred = element.id || `renderable-${element.num}`;
+            let id = preferred;
+            for (let suffix = element.num; ids.has(id); suffix++)
+                id = `${preferred}-${suffix}`;
+            ids.add(id);
+            return {
+                id,
+                role: element.editor ? "textbox" : element.clickable ? "button" : "control",
+                label: label(renderer, renderables.get(element.num), element),
+                element: element.num,
+                focused: element.focused || element.editor,
+                disabled: false,
+            };
+        }),
+    };
+}
+function visibleBounds(renderer, renderable) {
+    if (renderable.isDestroyed ||
+        !renderable.visible ||
+        renderable.opacity <= 0 ||
+        renderable.width <= 0 ||
+        renderable.height <= 0) {
+        return undefined;
+    }
+    let left = Math.max(0, renderable.screenX);
+    let top = Math.max(0, renderable.screenY);
+    let right = Math.min(renderer.width, renderable.screenX + renderable.width);
+    let bottom = Math.min(renderer.height, renderable.screenY + renderable.height);
+    for (let parent = renderable.parent; parent; parent = parent.parent) {
+        if (parent.isDestroyed || !parent.visible || parent.opacity <= 0)
+            return undefined;
+        if (parent.overflow !== "visible") {
+            left = Math.max(left, parent.screenX);
+            top = Math.max(top, parent.screenY);
+            right = Math.min(right, parent.screenX + parent.width);
+            bottom = Math.min(bottom, parent.screenY + parent.height);
+        }
+    }
+    if (right <= left || bottom <= top)
+        return undefined;
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+export function provideTerminalControl(renderer, options) {
+    return provideSemanticSnapshot({
+        ...options,
+        snapshot: async () => {
+            renderer.requestRender();
+            await renderer.idle();
+            return semanticSnapshot(renderer);
+        },
+    });
+}
+function label(renderer, renderable, element) {
+    if (!renderable || element.editor)
+        return element.id || undefined;
+    const text = all(renderable)
+        .filter((item) => visibleBounds(renderer, item) !== undefined)
+        .map((item) => Reflect.get(item, "plainText"))
+        .find((value) => typeof value === "string" && value.trim().length > 0);
+    return text?.replaceAll(/\s+/g, " ").trim() || element.id || undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/provider.d.ts

@@ -0,0 +1,15 @@
+export type Provider = {
+    readonly enabled: boolean;
+    readonly ready: Promise<boolean>;
+    close(): void;
+};
+export declare function provideSemanticSnapshot(options: {
+    readonly application: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    readonly snapshot: () => unknown | Promise<unknown>;
+    readonly socketPath?: string;
+    readonly onError?: (error: unknown) => void;
+}): Provider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAChC,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC5C,GAAG,QAAQ,CAuHX"}

package/dist/provider.js

@@ -0,0 +1,121 @@
+import { createConnection } from "node:net";
+export function provideSemanticSnapshot(options) {
+    if (!options.application.name)
+        throw new TypeError("application.name is required");
+    const socketPath = options.socketPath ?? process.env.TERMCTRL_SEMANTIC_SOCKET;
+    if (!socketPath)
+        return { enabled: false, ready: Promise.resolve(false), close() { } };
+    const semanticSocketPath = socketPath;
+    let readySettled = false;
+    let connectedOnce = false;
+    let closed = false;
+    let socket;
+    let reconnectTimer;
+    let reconnectDelay = 25;
+    let resolveReady;
+    const ready = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    const settleReady = (value) => {
+        if (readySettled)
+            return;
+        readySettled = true;
+        resolveReady(value);
+    };
+    connect();
+    function connect() {
+        let buffer = "";
+        let protocolReady = false;
+        const connection = createConnection(semanticSocketPath);
+        socket = connection;
+        connection.setEncoding("utf8");
+        const handshakeTimer = setTimeout(() => fail(new Error("Terminal Control semantic handshake timed out")), 5_000);
+        handshakeTimer.unref();
+        connection.once("connect", () => send({
+            type: "hello",
+            protocolVersion: 1,
+            application: options.application,
+            capabilities: ["semantic.snapshot"],
+        }));
+        connection.on("data", (chunk) => {
+            buffer += chunk;
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (!line)
+                    return fail(new Error("Terminal Control sent an empty semantic message"));
+                try {
+                    receive(JSON.parse(line));
+                }
+                catch (error) {
+                    return fail(error);
+                }
+            }
+        });
+        connection.once("error", fail);
+        connection.once("close", () => {
+            clearTimeout(handshakeTimer);
+            if (socket === connection)
+                socket = undefined;
+            settleReady(false);
+            if (!closed && connectedOnce) {
+                reconnectTimer = setTimeout(connect, reconnectDelay);
+                reconnectTimer.unref();
+                reconnectDelay = Math.min(reconnectDelay * 2, 1_000);
+            }
+        });
+        function receive(message) {
+            if (!isRecord(message))
+                throw new Error("Terminal Control sent an invalid semantic message");
+            if (message.type === "ready" && message.protocolVersion === 1 && !protocolReady) {
+                protocolReady = true;
+                connectedOnce = true;
+                reconnectDelay = 25;
+                clearTimeout(handshakeTimer);
+                settleReady(true);
+                return;
+            }
+            if (message.type !== "semantic.snapshot" || !protocolReady || !Number.isSafeInteger(message.id)) {
+                throw new Error("Terminal Control sent an invalid semantic snapshot request");
+            }
+            const id = message.id;
+            Promise.resolve()
+                .then(options.snapshot)
+                .then((value) => send({ type: "result", id, value }))
+                .catch((error) => send({
+                type: "error",
+                id,
+                error: {
+                    code: isRecord(error) && typeof error.code === "string" ? error.code : "SNAPSHOT_FAILED",
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            }));
+        }
+        function send(message) {
+            if (!connection.destroyed)
+                connection.write(`${JSON.stringify(message)}\n`);
+        }
+        function fail(error) {
+            clearTimeout(handshakeTimer);
+            if (!connectedOnce)
+                settleReady(false);
+            options.onError?.(error);
+            connection.destroy();
+        }
+    }
+    return {
+        enabled: true,
+        ready,
+        close() {
+            closed = true;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            settleReady(false);
+            socket?.destroy();
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAe,MAAM,UAAU,CAAA;AAQxD,MAAM,UAAU,uBAAuB,CAAC,OAKvC;IACC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI;QAAE,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAA;IAClF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAA;IAC7E,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,CAAA;IACrF,MAAM,kBAAkB,GAAG,UAAU,CAAA;IAErC,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,IAAI,aAAa,GAAG,KAAK,CAAA;IACzB,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,IAAI,MAA0B,CAAA;IAC9B,IAAI,cAAyD,CAAA;IAC7D,IAAI,cAAc,GAAG,EAAE,CAAA;IACvB,IAAI,YAAuC,CAAA;IAC3C,MAAM,KAAK,GAAG,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;QAC7C,YAAY,GAAG,OAAO,CAAA;IACxB,CAAC,CAAC,CAAA;IACF,MAAM,WAAW,GAAG,CAAC,KAAc,EAAE,EAAE;QACrC,IAAI,YAAY;YAAE,OAAM;QACxB,YAAY,GAAG,IAAI,CAAA;QACnB,YAAY,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC,CAAA;IACD,OAAO,EAAE,CAAA;IAET,SAAS,OAAO;QACd,IAAI,MAAM,GAAG,EAAE,CAAA;QACf,IAAI,aAAa,GAAG,KAAK,CAAA;QACzB,MAAM,UAAU,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CAAA;QACvD,MAAM,GAAG,UAAU,CAAA;QACnB,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;QAC9B,MAAM,cAAc,GAAG,UAAU,CAC/B,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC,EACtE,KAAK,CACN,CAAA;QACD,cAAc,CAAC,KAAK,EAAE,CAAA;QAEtB,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAC9B,IAAI,CAAC;YACH,IAAI,EAAE,OAAO;YACb,eAAe,EAAE,CAAC;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,CAAC,mBAAmB,CAAC;SACpC,CAAC,CACH,CAAA;QACD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAC9B,MAAM,IAAI,KAAK,CAAA;YACf,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAChC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAA;YAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,IAAI;oBAAE,OAAO,IAAI,CAAC,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC,CAAA;gBACpF,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;gBAC3B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,IAAI,CAAC,KAAK,CAAC,CAAA;gBACpB,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAA;QACF,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QAC9B,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YAC5B,YAAY,CAAC,cAAc,CAAC,CAAA;YAC5B,IAAI,MAAM,KAAK,UAAU;gBAAE,MAAM,GAAG,SAAS,CAAA;YAC7C,WAAW,CAAC,KAAK,CAAC,CAAA;YAClB,IAAI,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;gBAC7B,cAAc,GAAG,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;gBACpD,cAAc,CAAC,KAAK,EAAE,CAAA;gBACtB,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,CAAC,EAAE,KAAK,CAAC,CAAA;YACtD,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,SAAS,OAAO,CAAC,OAAgB;YAC/B,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;YAC5F,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,eAAe,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;gBAChF,aAAa,GAAG,IAAI,CAAA;gBACpB,aAAa,GAAG,IAAI,CAAA;gBACpB,cAAc,GAAG,EAAE,CAAA;gBACnB,YAAY,CAAC,cAAc,CAAC,CAAA;gBAC5B,WAAW,CAAC,IAAI,CAAC,CAAA;gBACjB,OAAM;YACR,CAAC;YACD,IAAI,OAAO,CAAC,IAAI,KAAK,mBAAmB,IAAI,CAAC,aAAa,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChG,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAA;YAC/E,CAAC;YACD,MAAM,EAAE,GAAG,OAAO,CAAC,EAAY,CAAA;YAC/B,OAAO,CAAC,OAAO,EAAE;iBACd,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;iBACtB,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;iBACpD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CACf,IAAI,CAAC;gBACH,IAAI,EAAE,OAAO;gBACb,EAAE;gBACF,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB;oBACxF,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAChE;aACF,CAAC,CACH,CAAA;QACL,CAAC;QAED,SAAS,IAAI,CAAC,OAAgB;YAC5B,IAAI,CAAC,UAAU,CAAC,SAAS;gBAAE,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC7E,CAAC;QAED,SAAS,IAAI,CAAC,KAAc;YAC1B,YAAY,CAAC,cAAc,CAAC,CAAA;YAC5B,IAAI,CAAC,aAAa;gBAAE,WAAW,CAAC,KAAK,CAAC,CAAA;YACtC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;YACxB,UAAU,CAAC,OAAO,EAAE,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,KAAK;QACL,KAAK;YACH,MAAM,GAAG,IAAI,CAAA;YACb,IAAI,cAAc;gBAAE,YAAY,CAAC,cAAc,CAAC,CAAA;YAChD,WAAW,CAAC,KAAK,CAAC,CAAA;YAClB,MAAM,EAAE,OAAO,EAAE,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kitlangton/terminal-control-opentui",
+  "version": "0.6.0",
+  "description": "Expose consistent OpenTUI semantic snapshots through Terminal Control",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anomalyco/terminal-control.git",
+    "directory": "packages/opentui"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "bun test src/index.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "release": "node script/release.mjs",
+    "release:check": "node script/release.mjs --check"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.4.1 <0.5.0"
+  },
+  "devDependencies": {
+    "@opentui/core": "^0.4.5",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}