@dex-ai/vue-tui 0.1.10

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dex-ai/vue-tui",
+  "version": "0.1.10",
+  "description": "Vue-powered terminal UI renderer. CSS-like styling, composable components, reactive updates, SFC support.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./plugin": {
+      "types": "./src/plugin.ts",
+      "default": "./src/plugin.ts"
+    },
+    "./register": {
+      "default": "./src/register.ts"
+    },
+    "./composables": {
+      "types": "./src/composables/index.ts",
+      "default": "./src/composables/index.ts"
+    },
+    "./components": {
+      "types": "./src/components/index.ts",
+      "default": "./src/components/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "demo": "bun run examples/agent.ts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "@vue/runtime-core": "^3.5.0",
+    "@vue/reactivity": "^3.5.0",
+    "@vue/compiler-sfc": "^3.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@changesets/cli": "^2.29.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/app.ts

@@ -0,0 +1,385 @@
+import type { Component, App } from "@vue/runtime-core";
+import { createElement } from "./nodes";
+import type { TElement } from "./nodes";
+import type { Theme } from "./style";
+import { defaultTheme } from "./theme";
+import { createTerminalRenderer } from "./renderer";
+import { renderToLines } from "./render";
+import type { KeyEvent, KeyHandler, RawInputHandle } from "./input";
+import { createRawInput } from "./input";
+
+export interface TerminalApp {
+	mount(): void;
+	unmount(): void;
+	forceRedraw(): void;
+	/** Get the last rendered frame as an array of ANSI-styled lines. */
+	getFrame(): string[];
+}
+
+/** A key binding matcher — matches against a KeyEvent. */
+export interface KeyBinding {
+	key?: string; // key name: "enter", "c", "up", etc.
+	shift?: boolean;
+	alt?: boolean;
+	ctrl?: boolean;
+	raw?: string; // exact raw sequence match (terminal-specific)
+}
+
+/** Maps key bindings to action names. */
+export type KeyMap = Record<string, KeyBinding | KeyBinding[]>;
+
+export type ActionHandler = (action: string, key: KeyEvent) => void;
+
+export interface TerminalAppOptions {
+	theme?: Theme | undefined;
+	stdout?: NodeJS.WriteStream | undefined;
+	stdin?: NodeJS.ReadStream | undefined;
+	/** Key handler — called for each key press (after keyMap resolution). */
+	onKey?: KeyHandler | undefined;
+	/** Key map — maps action names to key bindings. */
+	keyMap?: KeyMap | undefined;
+	/** Action handler — called when a keyMap match is found. */
+	onAction?: ActionHandler | undefined;
+}
+
+/** Detect if the terminal supports kitty keyboard protocol. */
+function detectKittyKeyboard(): boolean {
+	const term = process.env["TERM_PROGRAM"] ?? "";
+	const termName = process.env["TERM"] ?? "";
+	// Kitty, WezTerm, and foot natively support it
+	if (term === "kitty" || term === "WezTerm" || term === "foot") return true;
+	// xterm-kitty TERM value
+	if (termName === "xterm-kitty") return true;
+	// Ghostty supports it
+	if (term === "ghostty") return true;
+	return false;
+}
+
+/** Check if a KeyEvent matches a KeyBinding. */
+function matchesBinding(key: KeyEvent, binding: KeyBinding): boolean {
+	// Raw sequence match — takes priority, bypasses name/modifier checks
+	if (binding.raw) {
+		return key.raw === binding.raw;
+	}
+
+	if (!binding.key || key.name !== binding.key) {
+		return false;
+	}
+	if (binding.shift && !key.shift) return false;
+	if (binding.alt && !key.alt) return false;
+	if (binding.ctrl && !key.ctrl) return false;
+	if (!binding.shift && key.shift) return false;
+	if (!binding.alt && key.alt) return false;
+	if (!binding.ctrl && key.ctrl) return false;
+	return true;
+}
+
+/** Resolve a KeyEvent against a KeyMap, returning the action name or null. */
+function resolveKeyMap(key: KeyEvent, keyMap: KeyMap): string | null {
+	for (const [action, bindings] of Object.entries(keyMap)) {
+		const bindingList = Array.isArray(bindings) ? bindings : [bindings];
+		for (const binding of bindingList) {
+			if (matchesBinding(key, binding)) {
+				return action;
+			}
+		}
+	}
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// ANSI cursor helpers
+// ---------------------------------------------------------------------------
+
+/** Move cursor up N lines. */
+function cursorUp(n: number): string {
+	return n > 0 ? `\x1b[${n}A` : "";
+}
+
+/** Clear from cursor to end of line. */
+const CLEAR_LINE = "\x1b[2K\r";
+
+/** Synchronized output begin/end (prevents flicker). */
+const SYNC_START = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
+
+// ---------------------------------------------------------------------------
+// Diff writer
+// ---------------------------------------------------------------------------
+
+/** Move cursor down N lines. */
+function cursorDown(n: number): string {
+	return n > 0 ? `\x1b[${n}B` : "";
+}
+
+interface FrameState {
+	/** Lines from the previous render. */
+	lines: string[];
+	/** Where the viewport top is in the buffer (line index). */
+	viewportTop: number;
+	/** The row the hardware cursor is on (buffer-absolute). */
+	cursorRow: number;
+}
+
+/**
+ * Write the new frame to stdout using differential rendering.
+ *
+ * Strategy inspired by Pi TUI:
+ * - Track where the viewport top is (viewportTop).
+ * - Find firstChanged and lastChanged lines.
+ * - If firstChanged is above viewportTop, do a full clear+redraw.
+ * - Otherwise, move cursor to firstChanged, rewrite only changed lines.
+ * - Append new lines at the bottom naturally.
+ * - Never cursor-up past the viewport top.
+ */
+function writeFrame(
+	state: FrameState,
+	next: string[],
+	out: NodeJS.WriteStream,
+): void {
+	const height = out.rows ?? 24;
+	const prev = state.lines;
+
+	out.write(SYNC_START);
+
+	// Helper: compute screen-row delta from current cursor to target buffer row
+	const computeMove = (targetRow: number): number => {
+		const currentScreen = state.cursorRow - state.viewportTop;
+		const targetScreen = targetRow - state.viewportTop;
+		return targetScreen - currentScreen;
+	};
+
+	// --- First render or force-redraw ---
+	if (prev.length === 0) {
+		// If cursorRow > 0, this is a force-redraw (not truly the first render).
+		// Move cursor back to the top of the viewport before rewriting.
+		if (state.cursorRow > 0) {
+			const moveUp = state.cursorRow - state.viewportTop;
+			if (moveUp > 0) out.write(cursorUp(moveUp));
+		}
+		for (let i = 0; i < next.length; i++) {
+			if (i > 0) out.write("\n");
+			out.write(CLEAR_LINE + next[i]!);
+		}
+		// Clear any leftover lines below (in case frame shrank since last render)
+		out.write("\x1b[J");
+		state.cursorRow = Math.max(0, next.length - 1);
+		state.viewportTop = Math.max(0, next.length - height);
+		state.lines = next;
+		out.write(SYNC_END);
+		return;
+	}
+
+	// --- Find changed region ---
+	let firstChanged = -1;
+	let lastChanged = -1;
+	const maxLines = Math.max(prev.length, next.length);
+
+	for (let i = 0; i < maxLines; i++) {
+		const oldLine = i < prev.length ? prev[i] : undefined;
+		const newLine = i < next.length ? next[i] : undefined;
+		if (oldLine !== newLine) {
+			if (firstChanged === -1) firstChanged = i;
+			lastChanged = i;
+		}
+	}
+
+	// Nothing changed
+	if (firstChanged === -1) {
+		out.write(SYNC_END);
+		return;
+	}
+
+	// If change is above the viewport, do a full clear+redraw.
+	// This handles the scroll-desync case: user scrolled up, changes are in
+	// scrollback that we can't reliably reach.
+	if (firstChanged < state.viewportTop) {
+		// Clear screen and scrollback, redraw everything
+		out.write("\x1b[2J\x1b[H\x1b[3J");
+		for (let i = 0; i < next.length; i++) {
+			if (i > 0) out.write("\n");
+			out.write(next[i]!);
+		}
+		state.cursorRow = Math.max(0, next.length - 1);
+		state.viewportTop = Math.max(0, next.length - height);
+		state.lines = next;
+		out.write(SYNC_END);
+		return;
+	}
+
+	// --- Differential render within viewport ---
+
+	// Detect append-only: new lines added at the end, nothing else changed
+	const appendOnly = firstChanged >= prev.length && next.length > prev.length;
+
+	if (appendOnly) {
+		// Move cursor to end of prev content and append new lines
+		const move = computeMove(prev.length - 1);
+		if (move > 0) out.write(cursorDown(move));
+		else if (move < 0) out.write(cursorUp(-move));
+
+		for (let i = prev.length; i < next.length; i++) {
+			out.write("\n" + CLEAR_LINE + next[i]!);
+		}
+		state.cursorRow = next.length - 1;
+	} else {
+		// Move cursor to firstChanged
+		const move = computeMove(firstChanged);
+		if (move > 0) out.write(cursorDown(move));
+		else if (move < 0) out.write(cursorUp(-move));
+
+		// Render from firstChanged to lastChanged (or end of next, whichever is greater)
+		const renderEnd = Math.max(lastChanged, next.length - 1);
+		for (let i = firstChanged; i <= renderEnd; i++) {
+			if (i > firstChanged) out.write("\n");
+			out.write(CLEAR_LINE + (i < next.length ? next[i]! : ""));
+		}
+
+		state.cursorRow = renderEnd;
+
+		// If prev was longer and there are lines beyond renderEnd to clear,
+		// move down and erase them. (In practice renderEnd >= prev.length - 1
+		// because the diff loop detects removed lines, but guard defensively.)
+		if (prev.length - 1 > renderEnd) {
+			const extra = prev.length - 1 - renderEnd;
+			for (let i = 0; i < extra; i++) {
+				out.write("\n" + CLEAR_LINE);
+			}
+			// Move back up to end of new content
+			out.write(cursorUp(extra));
+			state.cursorRow = renderEnd;
+		}
+	}
+
+	// Update viewport top
+	state.viewportTop = Math.max(state.viewportTop, state.cursorRow - height + 1);
+	state.lines = next;
+	out.write(SYNC_END);
+}
+
+// ---------------------------------------------------------------------------
+// createTerminalApp
+// ---------------------------------------------------------------------------
+
+export function createTerminalApp(
+	rootComponent: Component,
+	options?: TerminalAppOptions,
+): TerminalApp {
+	const theme = options?.theme ?? defaultTheme;
+	const stdout: NodeJS.WriteStream = options?.stdout ?? process.stdout;
+	const stdin: NodeJS.ReadStream = options?.stdin ?? process.stdin;
+
+	let vueApp: App<TElement> | null = null;
+	let rootEl: TElement | null = null;
+	const frameState: FrameState = { lines: [], viewportTop: 0, cursorRow: 0 };
+	let scheduled = false;
+	let inputHandle: RawInputHandle | null = null;
+	const useKitty = detectKittyKeyboard();
+
+	function scheduleRender(): void {
+		if (scheduled) return;
+		scheduled = true;
+		// Use microtask to batch multiple synchronous mutations
+		queueMicrotask(doRender);
+	}
+
+	/** Force a full redraw by invalidating the previous frame cache. */
+	function forceRedraw(): void {
+		frameState.lines = [];
+		scheduleRender();
+	}
+
+	function doRender(): void {
+		scheduled = false;
+		if (rootEl === null) return;
+
+		const width = stdout.columns ?? 80;
+		const next = renderToLines(rootEl, width, theme);
+
+		writeFrame(frameState, next, stdout);
+	}
+
+	return {
+		getFrame(): string[] {
+			return [...frameState.lines];
+		},
+
+		mount(): void {
+			rootEl = createElement("root");
+
+			const { createApp } = createTerminalRenderer(scheduleRender);
+			vueApp = createApp(rootComponent);
+
+			// Hide hardware cursor — the app renders its own software cursor
+			stdout.write("\x1b[?25l");
+
+			// Enable bracketed paste mode so we can detect pastes
+			stdout.write("\x1b[?2004h");
+
+			// Enable kitty keyboard protocol if terminal supports it
+			if (useKitty) {
+				stdout.write("\x1b[>1u");
+			}
+
+			// Force full redraw on terminal resize
+			stdout.on("resize", forceRedraw);
+
+			// Force full redraw when returning from background (e.g. Ctrl+Z → fg)
+			process.on("SIGCONT", forceRedraw);
+
+			// Set up raw stdin input if onKey handler provided
+			if (options?.onKey) {
+				inputHandle = createRawInput((key) => {
+					// Resolve key through keyMap if provided
+					if (options.keyMap) {
+						const action = resolveKeyMap(key, options.keyMap);
+						if (action && options.onAction) {
+							options.onAction(action, key);
+							return;
+						}
+					}
+					options.onKey!(key);
+				}, stdin);
+			}
+
+			// Mount onto the root element — Vue will populate it
+			vueApp.mount(rootEl);
+
+			// Trigger initial render
+			scheduleRender();
+		},
+
+		forceRedraw,
+
+		unmount(): void {
+			// Tear down input
+			if (inputHandle !== null) {
+				inputHandle.destroy();
+				inputHandle = null;
+			}
+
+			// Remove event listeners
+			stdout.off("resize", forceRedraw);
+			process.off("SIGCONT", forceRedraw);
+
+			if (vueApp !== null) {
+				vueApp.unmount();
+				vueApp = null;
+			}
+			rootEl = null;
+			frameState.lines = [];
+			frameState.viewportTop = 0;
+			frameState.cursorRow = 0;
+			// Move cursor below rendered content so shell prompt doesn't overwrite
+			stdout.write("\r\n");
+			// Disable bracketed paste mode
+			stdout.write("\x1b[?2004l");
+			// Disable kitty keyboard protocol if it was enabled
+			if (useKitty) {
+				stdout.write("\x1b[<u");
+			}
+			// Ensure cursor is visible
+			stdout.write("\x1b[?25h");
+		},
+	};
+}

package/src/components/TuiCheckbox.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui — TuiCheckbox component
+// ---------------------------------------------------------------------------
+
+import { defineComponent, h } from "@vue/runtime-core";
+
+/**
+ * Renders a checkbox as `[x]` or `[ ]` with a label.
+ *
+ * Props:
+ * - checked: boolean
+ * - label: string
+ * - focused: boolean (optional) — highlights when focused
+ */
+export const TuiCheckbox = defineComponent({
+	name: "TuiCheckbox",
+	props: {
+		checked: { type: Boolean, required: true },
+		label: { type: String, required: true },
+		focused: { type: Boolean, default: false },
+	},
+	setup(props) {
+		return () => {
+			const box = props.checked ? "[x]" : "[ ]";
+			const color = props.focused ? "accent" : undefined;
+
+			return h("line", {}, [
+				h("text", { color, bold: props.focused }, box),
+				h("text", { color, style: { paddingLeft: 1 } }, props.label),
+			]);
+		};
+	},
+});
+
+export default TuiCheckbox;

package/src/components/TuiField.ts

@@ -0,0 +1,123 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui — TuiField component
+// ---------------------------------------------------------------------------
+
+import { defineComponent, h, type PropType } from "@vue/runtime-core";
+import type { FormField } from "../types/form";
+import { TuiCheckbox } from "./TuiCheckbox";
+
+/**
+ * Renders a single form field line with focus indicator, label, separator,
+ * and value display. Handles text, password, select, checkbox, and number types.
+ *
+ * Props:
+ * - field: FormField
+ * - focused: boolean
+ * - editing: boolean
+ * - editBuffer: string
+ * - value: string | boolean | undefined
+ * - error: string | undefined
+ */
+export const TuiField = defineComponent({
+	name: "TuiField",
+	props: {
+		field: { type: Object as PropType<FormField>, required: true },
+		focused: { type: Boolean, default: false },
+		editing: { type: Boolean, default: false },
+		editBuffer: { type: String, default: "" },
+		value: { type: [String, Boolean], default: undefined },
+		error: { type: String, default: undefined },
+	},
+	setup(props) {
+		return () => {
+			const { field, focused, editing, editBuffer, value, error } = props;
+
+			// Checkbox — delegate to TuiCheckbox
+			if (field.type === "checkbox") {
+				return h(TuiCheckbox, {
+					checked: value === true,
+					label: field.label,
+					focused,
+				});
+			}
+
+			// Standard field layout: [indicator] [label] │ [value]
+			const children = [];
+
+			// Focus indicator
+			children.push(
+				h(
+					"text",
+					{ color: focused ? "accent" : "muted" },
+					focused ? "❯ " : "  ",
+				),
+			);
+
+			// Label
+			children.push(
+				h(
+					"text",
+					{
+						color: focused ? "text" : "muted",
+						bold: focused,
+					},
+					field.label,
+				),
+			);
+
+			// Required indicator
+			if (field.required && !field.readonly && !value) {
+				children.push(
+					h("text", { color: "warn", style: { paddingLeft: 1 } }, "*"),
+				);
+			}
+
+			// Separator
+			children.push(h("text", { dim: true }, " │ "));
+
+			// Value display
+			if (editing) {
+				// Show edit buffer with cursor
+				children.push(
+					h("text", { color: "accent" }, editBuffer + "▏"),
+				);
+			} else if (field.readonly && value) {
+				children.push(h("text", { dim: true }, String(value)));
+			} else if (field.readonly) {
+				children.push(h("text", { dim: true }, "—"));
+			} else if (field.type === "password" && value) {
+				children.push(h("text", {}, maskPassword(String(value))));
+			} else if (value !== undefined && value !== "") {
+				children.push(h("text", {}, String(value)));
+			} else if (field.placeholder) {
+				children.push(h("text", { dim: true }, field.placeholder));
+			}
+
+			// Select type indicator
+			if (field.type === "select" && !editing) {
+				children.push(h("text", { dim: true, style: { paddingLeft: 1 } }, "▾"));
+			}
+
+			const nodes = [h("line", {}, children)];
+
+			// Error display
+			if (error) {
+				nodes.push(
+					h("line", {}, [
+						h("text", { color: "error", style: { paddingLeft: 4 } }, `⚠ ${error}`),
+					]),
+				);
+			}
+
+			return h("stack", {}, nodes);
+		};
+	},
+});
+
+/** Mask a password value, showing only the last 4 chars. */
+function maskPassword(val: string): string {
+	if (val.length <= 4) return "••••";
+	return "••••••••" + val.slice(-4);
+}
+
+export default TuiField;

package/src/components/TuiSelect.ts

@@ -0,0 +1,86 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui — TuiSelect component
+// ---------------------------------------------------------------------------
+
+import { defineComponent, h, type PropType } from "@vue/runtime-core";
+
+/**
+ * Renders a vertical select list with one highlighted option.
+ *
+ * Props:
+ * - options: string[]
+ * - selectedIndex: number
+ * - filter: string (optional) — shows filter text above options
+ * - maxVisible: number (optional, default 8) — scroll window height
+ * - scrollOffset: number (optional, default 0) — current scroll position
+ */
+export const TuiSelect = defineComponent({
+	name: "TuiSelect",
+	props: {
+		options: { type: Array as PropType<string[]>, required: true },
+		selectedIndex: { type: Number, required: true },
+		filter: { type: String, default: "" },
+		maxVisible: { type: Number, default: 8 },
+		scrollOffset: { type: Number, default: 0 },
+	},
+	setup(props) {
+		return () => {
+			const children = [];
+
+			// Filter indicator
+			if (props.filter) {
+				children.push(
+					h("line", {}, [
+						h("text", { dim: true }, "filter: "),
+						h("text", { color: "accent" }, props.filter),
+					]),
+				);
+			}
+
+			// Compute visible window
+			const total = props.options.length;
+			const visCount = Math.min(props.maxVisible, total);
+			const start = props.scrollOffset;
+			const end = Math.min(start + visCount, total);
+
+			// Scroll indicator (top)
+			if (start > 0) {
+				children.push(h("text", { dim: true }, "  ↑ more"));
+			}
+
+			// Visible options
+			for (let i = start; i < end; i++) {
+				const selected = i === props.selectedIndex;
+				const option = props.options[i] ?? "";
+
+				children.push(
+					h("line", {}, [
+						h(
+							"text",
+							selected
+								? { color: "accent", bold: true }
+								: {},
+							selected ? "▸ " : "  ",
+						),
+						h(
+							"text",
+							selected
+								? { color: "accent", bold: true }
+								: {},
+							option,
+						),
+					]),
+				);
+			}
+
+			// Scroll indicator (bottom)
+			if (end < total) {
+				children.push(h("text", { dim: true }, "  ↓ more"));
+			}
+
+			return h("stack", {}, children);
+		};
+	},
+});
+
+export default TuiSelect;

package/src/components/index.ts

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui/components — barrel export
+// ---------------------------------------------------------------------------
+
+export { TuiField } from "./TuiField";
+export { TuiSelect } from "./TuiSelect";
+export { TuiCheckbox } from "./TuiCheckbox";