@nghyane/arcane-tui 0.1.8 → 0.1.10

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@nghyane/arcane-tui",
-	"version": "0.1.8",
+	"version": "0.1.10",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/nghyane/arcane",
 	"author": "Can Bölük",

package/src/buffer/render.ts

@@ -5,7 +5,7 @@ function styleEquals(a: Style, b: Style): boolean {
 	return a.fg === b.fg && a.bg === b.bg && a.mods === b.mods && a.link === b.link;
 }
 
-function emitStyleDiff(prev: Style, next: Style, parts: string[]): void {
+function emitStyleDiff(prev: Style, next: Style, parts: string[], defaultBg = 0): void {
 	// Check if reset is simpler
 	const needReset =
 		(prev.mods & ~next.mods) !== 0 ||
@@ -23,6 +23,9 @@ function emitStyleDiff(prev: Style, next: Style, parts: string[]): void {
 		if (hasColor(next.bg)) {
 			const [r, g, b] = unpackRgb(next.bg);
 			parts.push(`\x1b[48;2;${r};${g};${b}m`);
+		} else if (defaultBg) {
+			const [r, g, b] = unpackRgb(defaultBg);
+			parts.push(`\x1b[48;2;${r};${g};${b}m`);
 		}
 	} else {
 		if (prev.fg !== next.fg) {
@@ -38,7 +41,12 @@ function emitStyleDiff(prev: Style, next: Style, parts: string[]): void {
 				const [r, g, b] = unpackRgb(next.bg);
 				parts.push(`\x1b[48;2;${r};${g};${b}m`);
 			} else {
-				parts.push("\x1b[49m");
+				if (defaultBg) {
+					const [r, g, b] = unpackRgb(defaultBg);
+					parts.push(`\x1b[48;2;${r};${g};${b}m`);
+				} else {
+					parts.push("\x1b[49m");
+				}
 			}
 		}
 		if (prev.mods !== next.mods) {
@@ -78,7 +86,7 @@ function emitMods(prev: number, next: number, parts: string[]): void {
 	if (removed & Mod.Strikethrough) parts.push("\x1b[29m");
 }
 
-export function renderDiff(changes: CellChange[], _width: number): string {
+export function renderDiff(changes: CellChange[], _width: number, defaultBg = 0): string {
 	if (changes.length === 0) return "";
 
 	const sorted = [...changes].sort((a, b) => (a.row !== b.row ? a.row - b.row : a.col - b.col));
@@ -104,7 +112,7 @@ export function renderDiff(changes: CellChange[], _width: number): string {
 
 		// Style changes
 		if (!styleEquals(curStyle, cell.style)) {
-			emitStyleDiff(curStyle, cell.style, parts);
+			emitStyleDiff(curStyle, cell.style, parts, defaultBg);
 			curStyle = { ...cell.style };
 		}
 
@@ -113,10 +121,14 @@ export function renderDiff(changes: CellChange[], _width: number): string {
 	}
 
 	parts.push("\x1b[0m");
+	if (defaultBg) {
+		const [r, g, b] = unpackRgb(defaultBg);
+		parts.push(`\x1b[48;2;${r};${g};${b}m`);
+	}
 	return parts.join("");
 }
 
-export function renderBuffer(buf: Buffer): string[] {
+export function renderBuffer(buf: Buffer, defaultBg = 0): string[] {
 	const lines: string[] = [];
 
 	for (let row = 0; row < buf.height; row++) {
@@ -130,7 +142,7 @@ export function renderBuffer(buf: Buffer): string[] {
 			if (cell.width === 0) continue;
 
 			if (!styleEquals(curStyle, cell.style)) {
-				emitStyleDiff(curStyle, cell.style, parts);
+				emitStyleDiff(curStyle, cell.style, parts, defaultBg);
 				curStyle = { ...cell.style };
 			}
 
@@ -140,6 +152,10 @@ export function renderBuffer(buf: Buffer): string[] {
 		// Reset at end of line
 		if (!styleEquals(curStyle, DEFAULT_STYLE)) {
 			parts.push("\x1b[0m");
+			if (defaultBg) {
+				const [r, g, b] = unpackRgb(defaultBg);
+				parts.push(`\x1b[48;2;${r};${g};${b}m`);
+			}
 		}
 
 		lines.push(parts.join(""));

package/src/components/markdown.ts

@@ -22,6 +22,8 @@ export interface DefaultTextStyle {
 	strikethrough?: boolean;
 	/** Underline text */
 	underline?: boolean;
+	leftBorder?: string;
+	/** Left border string (already styled, prepended to each line) */
 }
 
 /**
@@ -106,8 +108,9 @@ export class Markdown implements Component {
 			return this.#cachedLines;
 		}
 
-		// Calculate available width for content (subtract horizontal padding)
-		const contentWidth = Math.max(1, width - this.#paddingX * 2);
+		const leftBorder = this.#defaultTextStyle?.leftBorder ?? "";
+		const borderWidth = visibleWidth(leftBorder);
+		const contentWidth = Math.max(1, width - this.#paddingX * 2 - borderWidth);
 
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
@@ -153,26 +156,23 @@ export class Markdown implements Component {
 		const contentLines: string[] = [];
 
 		for (const line of wrappedLines) {
-			// Image lines must be output raw - no margins or background
 			if (TERMINAL.isImageLine(line)) {
 				contentLines.push(line);
 				continue;
 			}
 
-			const lineWithMargins = leftMargin + line + rightMargin;
+			const lineWithMargins = leftBorder + leftMargin + line + rightMargin;
 
 			if (bgFn) {
 				contentLines.push(applyBackgroundToLine(lineWithMargins, width, bgFn));
 			} else {
-				// No background - just pad to width
 				const visibleLen = visibleWidth(lineWithMargins);
 				const paddingNeeded = Math.max(0, width - visibleLen);
 				contentLines.push(lineWithMargins + padding(paddingNeeded));
 			}
 		}
 
-		// Add top/bottom padding (empty lines)
-		const emptyLine = padding(width);
+		const emptyLine = leftBorder + padding(width - borderWidth);
 		const emptyLines: string[] = [];
 		for (let i = 0; i < this.#paddingY; i++) {
 			const line = bgFn ? applyBackgroundToLine(emptyLine, width, bgFn) : emptyLine;
@@ -365,13 +365,15 @@ export class Markdown implements Component {
 					applyText: quoteStyle,
 					stylePrefix: this.#getStylePrefix(quoteStyle),
 				};
-				const quoteText = this.#renderInlineTokens(token.tokens || [], quoteStyleContext);
-				const quoteLines = quoteText.split("\n");
+
+				// Blockquote tokens contain block-level children (paragraph, code, list, etc.)
+				// Render each child appropriately, then prefix every line with the quote border.
+				const quoteContentLines = this.#renderBlockquoteTokens(token.tokens || [], quoteStyleContext, width - 2);
 
 				// Calculate available width for quote content (subtract border + space = 2 chars)
 				const quoteContentWidth = Math.max(1, width - 2);
 
-				for (const quoteLine of quoteLines) {
+				for (const quoteLine of quoteContentLines) {
 					// Wrap the styled line, then add border to each wrapped line
 					const wrappedLines = wrapTextWithAnsi(quoteLine, quoteContentWidth);
 					for (const wrappedLine of wrappedLines) {
@@ -601,6 +603,81 @@ export class Markdown implements Component {
 		return lines;
 	}
 
+	/**
+	 * Render tokens inside a blockquote, handling block-level elements
+	 * (code, list, heading) that #renderInlineTokens cannot process.
+	 */
+	#renderBlockquoteTokens(tokens: Token[], styleContext: InlineStyleContext, availableWidth: number): string[] {
+		const lines: string[] = [];
+
+		for (let i = 0; i < tokens.length; i++) {
+			const token = tokens[i];
+			const nextToken = tokens[i + 1];
+
+			switch (token.type) {
+				case "paragraph": {
+					const text = this.#renderInlineTokens(token.tokens || [], styleContext);
+					lines.push(text);
+					if (nextToken && nextToken.type !== "space") {
+						lines.push("");
+					}
+					break;
+				}
+
+				case "code": {
+					const codeIndent = padding(this.#codeBlockIndent);
+					lines.push(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
+					if (this.#theme.highlightCode) {
+						const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
+						for (const hlLine of highlightedLines) {
+							lines.push(`${codeIndent}${hlLine}`);
+						}
+					} else {
+						const codeLines = token.text.split("\n");
+						for (const codeLine of codeLines) {
+							lines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
+						}
+					}
+					lines.push(this.#theme.codeBlockBorder("```"));
+					if (nextToken && nextToken.type !== "space") {
+						lines.push("");
+					}
+					break;
+				}
+
+				case "heading": {
+					const headingLines = this.#renderToken(token, availableWidth, nextToken?.type);
+					lines.push(...headingLines);
+					break;
+				}
+
+				case "list": {
+					const listLines = this.#renderList(token as any, 0);
+					lines.push(...listLines);
+					break;
+				}
+
+				case "hr": {
+					lines.push(this.#theme.hr(this.#theme.symbols.hrChar.repeat(Math.min(availableWidth, 80))));
+					break;
+				}
+
+				case "space":
+					lines.push("");
+					break;
+
+				default: {
+					const text = this.#renderInlineTokens([token], styleContext);
+					if (text) {
+						lines.push(text);
+					}
+				}
+			}
+		}
+
+		return lines;
+	}
+
 	/**
 	 * Get the visible width of the longest word in a string.
 	 */

package/src/components/tab-bar.ts

@@ -10,7 +10,7 @@
  */
 import { matchesKey } from "../keys";
 import type { Component } from "../tui";
-import { wrapTextWithAnsi } from "../utils";
+import { truncateToWidth, visibleWidth } from "../utils";
 
 /** Tab definition */
 export interface Tab {
@@ -112,31 +112,64 @@ export class TabBar implements Component {
 
 	/** Render the tab bar, wrapping to multiple lines if needed */
 	render(width: number): string[] {
-		const parts: string[] = [];
+		const maxWidth = Math.max(1, width);
+		const chunks: string[] = [];
 
 		// Label prefix
-		parts.push(this.#theme.label(`${this.#label}:`));
-		parts.push("  ");
+		chunks.push(this.#theme.label(`${this.#label}:`));
+		chunks.push("  ");
 
 		// Tab buttons
 		for (let i = 0; i < this.#tabs.length; i++) {
 			const tab = this.#tabs[i];
 			if (i === this.#activeIndex) {
-				parts.push(this.#theme.activeTab(` ${tab.label} `));
+				chunks.push(this.#theme.activeTab(` ${tab.label} `));
 			} else {
-				parts.push(this.#theme.inactiveTab(` ${tab.label} `));
+				chunks.push(this.#theme.inactiveTab(` ${tab.label} `));
 			}
 			if (i < this.#tabs.length - 1) {
-				parts.push("  ");
+				chunks.push("  ");
 			}
 		}
 
 		// Navigation hint
-		parts.push("  ");
-		parts.push(this.#theme.hint("(tab to cycle)"));
+		chunks.push("  ");
+		chunks.push(this.#theme.hint("(tab to cycle)"));
 
-		const line = parts.join("");
-		const maxWidth = Math.max(1, width);
-		return wrapTextWithAnsi(line, maxWidth);
+		const lines: string[] = [];
+		let currentLine = "";
+		let currentWidth = 0;
+
+		for (const chunk of chunks) {
+			const chunkWidth = visibleWidth(chunk);
+			if (chunkWidth <= 0) {
+				continue;
+			}
+
+			if (chunkWidth > maxWidth) {
+				if (currentLine) {
+					lines.push(currentLine);
+					currentLine = "";
+					currentWidth = 0;
+				}
+				lines.push(truncateToWidth(chunk, maxWidth));
+				continue;
+			}
+
+			if (currentWidth > 0 && currentWidth + chunkWidth > maxWidth) {
+				lines.push(currentLine);
+				currentLine = "";
+				currentWidth = 0;
+			}
+
+			currentLine += chunk;
+			currentWidth += chunkWidth;
+		}
+
+		if (currentLine) {
+			lines.push(currentLine);
+		}
+
+		return lines.length > 0 ? lines : [""];
 	}
 }

package/src/index.ts

@@ -59,7 +59,7 @@ export {
 export { StdinBuffer, type StdinBufferEventMap, type StdinBufferOptions } from "./stdin-buffer";
 export type { BoxSymbols, SymbolTheme } from "./symbols";
 // Terminal interface and implementations
-export { emergencyTerminalRestore, ProcessTerminal, type Terminal } from "./terminal";
+export { emergencyTerminalRestore, ProcessTerminal, queryTerminalBackground, type Terminal } from "./terminal";
 // Terminal image support
 export * from "./terminal-capabilities";
 // TTY ID

package/src/terminal.ts

@@ -56,6 +56,56 @@ export function emergencyTerminalRestore(): void {
 		// Terminal may already be dead during crash cleanup - ignore errors
 	}
 }
+
+/**
+ * Query terminal background color via OSC 11.
+ * Returns hex color string (e.g. "#1c1e26") or null if terminal does not respond.
+ * Must be called before TUI start() — temporarily enters raw mode.
+ */
+export async function queryTerminalBackground(timeoutMs = 150): Promise<string | null> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+
+	const wasRaw = process.stdin.isRaw;
+	if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+	process.stdin.setEncoding("utf8");
+	process.stdin.resume();
+
+	const { promise, resolve } = Promise.withResolvers<string | null>();
+	let settled = false;
+	let buf = "";
+
+	const onData = (data: string) => {
+		buf += data;
+		// OSC 11 response: \x1b]11;rgb:RRRR/GGGG/BBBB\x1b\\ or ...\x07
+		const match = buf.match(/\x1b\]11;rgb:([0-9a-fA-F]{2,4})\/([0-9a-fA-F]{2,4})\/([0-9a-fA-F]{2,4})/);
+		if (match && !settled) {
+			settled = true;
+			const r = parseInt(match[1].slice(0, 2), 16);
+			const g = parseInt(match[2].slice(0, 2), 16);
+			const b = parseInt(match[3].slice(0, 2), 16);
+			resolve(
+				`#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`,
+			);
+		}
+	};
+
+	process.stdin.on("data", onData);
+	process.stdout.write("\x1b]11;?\x1b\\");
+
+	const timer = setTimeout(() => {
+		if (!settled) {
+			settled = true;
+			resolve(null);
+		}
+	}, timeoutMs);
+
+	const result = await promise;
+	clearTimeout(timer);
+	process.stdin.removeListener("data", onData);
+	if (process.stdin.setRawMode) process.stdin.setRawMode(wasRaw);
+	if (!wasRaw) process.stdin.pause();
+	return result;
+}
 export interface Terminal {
 	// Start the terminal with input and resize handlers
 	start(onInput: (data: string) => void, onResize: () => void): void;

package/src/tui.ts

@@ -1,6 +1,6 @@
 import { linesToBuffer } from "./buffer/ansi-parser.js";
 import type { Buffer as CellBuffer, CellChange } from "./buffer/buffer.js";
-import { Mod } from "./buffer/cell.js";
+import { Mod, unpackRgb } from "./buffer/cell.js";
 import { renderBuffer, renderDiff } from "./buffer/render.js";
 import { isKeyRelease, matchesKey } from "./keys";
 import { type MouseEvent, SCROLL_DOWN, SCROLL_UP, type Terminal } from "./terminal";
@@ -186,6 +186,7 @@ export class Container implements Component {
 	}
 
 	render(width: number): string[] {
+		width = Math.max(1, width);
 		const lines: string[] = [];
 		for (const child of this.children) {
 			lines.push(...child.render(width));
@@ -222,6 +223,7 @@ export class TUI extends Container {
 	#scrollFlushScheduled = false; // Whether a flush is scheduled on next tick
 	#fullRenderCache: string[] = []; // Cached full render output for native scroll
 	#previousBuffer: CellBuffer | null = null; // Previous viewport buffer for cell-level diff
+	#appBg = 0; // Packed RGB for app-wide background (0 = terminal default)
 
 	// Selection state for mouse text selection
 	#selectionActive = false;
@@ -275,6 +277,11 @@ export class TUI extends Container {
 		this.#clearOnShrink = enabled;
 	}
 
+	setAppBg(packedRgb: number): void {
+		this.#appBg = packedRgb;
+		this.#previousBuffer = null; // Force full redraw
+	}
+
 	setFocus(component: Component | null): void {
 		// Clear focused flag on old component
 		if (isFocusable(this.#focusedComponent)) {
@@ -475,10 +482,14 @@ export class TUI extends Container {
 		if (this.#previousBuffer) {
 			const changes = currentBuffer.diff(this.#previousBuffer);
 			if (changes.length > 0) {
-				out += renderDiff(changes, width);
+				out += renderDiff(changes, width, this.#appBg);
 			}
 		} else {
 			// No previous buffer — full viewport redraw
+			if (this.#appBg) {
+				const [r, g, b] = unpackRgb(this.#appBg);
+				out += `\x1b[48;2;${r};${g};${b}m`;
+			}
 			out += "\x1b[H";
 			for (let i = 0; i < viewportLines.length; i++) {
 				if (i > 0) out += "\r\n";
@@ -715,7 +726,7 @@ export class TUI extends Container {
 		// Output only the changed cells
 		let out = "\x1b[?2026h"; // Synchronized output
 		out += "\x1b7"; // Save cursor position
-		out += renderDiff(changes, width);
+		out += renderDiff(changes, width, this.#appBg);
 		out += "\x1b8"; // Restore cursor position
 		out += "\x1b[?2026l";
 		this.terminal.write(out);
@@ -1046,8 +1057,12 @@ export class TUI extends Container {
 			// No previous buffer — full render
 			this.#fullRedrawCount += 1;
 			let out = "\x1b[?2026h"; // Begin synchronized output
+			if (this.#appBg) {
+				const [r, g, b] = unpackRgb(this.#appBg);
+				out += `\x1b[48;2;${r};${g};${b}m`;
+			}
 			out += this.#clearScrollbackOnNextFullRender ? "\x1b[3J\x1b[2J\x1b[H" : "\x1b[2J\x1b[H";
-			const renderedLines = renderBuffer(currentBuffer);
+			const renderedLines = renderBuffer(currentBuffer, this.#appBg);
 			for (let i = 0; i < renderedLines.length; i++) {
 				if (i > 0) out += "\r\n";
 				out += renderedLines[i];
@@ -1083,7 +1098,7 @@ export class TUI extends Container {
 			} else {
 				// Emit minimal ANSI for changed cells
 				let out = "\x1b[?2026h"; // Begin synchronized output
-				out += renderDiff(changes, width);
+				out += renderDiff(changes, width, this.#appBg);
 				const adjCursorPos = cursorPos
 					? { row: cursorPos.row - Math.max(0, newLines.length - height), col: cursorPos.col }
 					: null;