@nghyane/arcane-tui 0.1.0

package/src/keys.ts

@@ -0,0 +1,270 @@
+/**
+ * Keyboard input handling for terminal applications.
+ *
+ * Supports both legacy terminal sequences and Kitty keyboard protocol.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ * Reference: https://github.com/sst/opentui/blob/7da92b4088aebfe27b9f691c04163a48821e49fd/packages/core/src/lib/parse.keypress.ts
+ *
+ * Symbol keys are also supported, however some ctrl+symbol combos
+ * overlap with ASCII codes, e.g. ctrl+[ = ESC.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#legacy-ctrl-mapping-of-ascii-keys
+ * Those can still be * used for ctrl+shift combos
+ *
+ * API:
+ * - matchesKey(data, keyId) - Check if input matches a key identifier
+ * - parseKey(data) - Parse input and return the key identifier
+ * - Key - Helper object for creating typed key identifiers
+ * - setKittyProtocolActive(active) - Set global Kitty protocol state
+ * - isKittyProtocolActive() - Query global Kitty protocol state
+ */
+
+import {
+	type KeyEventType,
+	matchesKey as matchesKeyNative,
+	parseKey as parseKeyNative,
+	parseKittySequence as parseKittySequenceNative,
+} from "@nghyane/arcane-natives";
+
+// =============================================================================
+// Global Kitty Protocol State
+// =============================================================================
+
+let kittyProtocolActive = false;
+
+/**
+ * Set the global Kitty keyboard protocol state.
+ * Called by ProcessTerminal after detecting protocol support.
+ */
+export function setKittyProtocolActive(active: boolean): void {
+	kittyProtocolActive = active;
+}
+
+/**
+ * Query whether Kitty keyboard protocol is currently active.
+ */
+export function isKittyProtocolActive(): boolean {
+	return kittyProtocolActive;
+}
+
+// =============================================================================
+// Type-Safe Key Identifiers
+// =============================================================================
+
+type Letter =
+	| "a"
+	| "b"
+	| "c"
+	| "d"
+	| "e"
+	| "f"
+	| "g"
+	| "h"
+	| "i"
+	| "j"
+	| "k"
+	| "l"
+	| "m"
+	| "n"
+	| "o"
+	| "p"
+	| "q"
+	| "r"
+	| "s"
+	| "t"
+	| "u"
+	| "v"
+	| "w"
+	| "x"
+	| "y"
+	| "z";
+
+type SymbolKey =
+	| "`"
+	| "-"
+	| "="
+	| "["
+	| "]"
+	| "\\"
+	| ";"
+	| "'"
+	| ","
+	| "."
+	| "/"
+	| "!"
+	| "@"
+	| "#"
+	| "$"
+	| "%"
+	| "^"
+	| "&"
+	| "*"
+	| "("
+	| ")"
+	| "_"
+	| "+"
+	| "|"
+	| "~"
+	| "{"
+	| "}"
+	| ":"
+	| "<"
+	| ">"
+	| "?";
+
+type SpecialKey =
+	| "escape"
+	| "esc"
+	| "enter"
+	| "return"
+	| "tab"
+	| "space"
+	| "backspace"
+	| "delete"
+	| "insert"
+	| "clear"
+	| "home"
+	| "end"
+	| "pageUp"
+	| "pageDown"
+	| "up"
+	| "down"
+	| "left"
+	| "right"
+	| "f1"
+	| "f2"
+	| "f3"
+	| "f4"
+	| "f5"
+	| "f6"
+	| "f7"
+	| "f8"
+	| "f9"
+	| "f10"
+	| "f11"
+	| "f12";
+
+type BaseKey = Letter | SymbolKey | SpecialKey;
+
+/**
+ * Union type of all valid key identifiers.
+ * Provides autocomplete and catches typos at compile time.
+ */
+export type KeyId =
+	| BaseKey
+	| `ctrl+${BaseKey}`
+	| `shift+${BaseKey}`
+	| `alt+${BaseKey}`
+	| `ctrl+shift+${BaseKey}`
+	| `shift+ctrl+${BaseKey}`
+	| `ctrl+alt+${BaseKey}`
+	| `alt+ctrl+${BaseKey}`
+	| `shift+alt+${BaseKey}`
+	| `alt+shift+${BaseKey}`
+	| `ctrl+shift+alt+${BaseKey}`
+	| `ctrl+alt+shift+${BaseKey}`
+	| `shift+ctrl+alt+${BaseKey}`
+	| `shift+alt+ctrl+${BaseKey}`
+	| `alt+ctrl+shift+${BaseKey}`
+	| `alt+shift+ctrl+${BaseKey}`;
+
+// =============================================================================
+// Kitty Protocol Parsing
+// =============================================================================
+
+interface ParsedKittySequence {
+	codepoint: number;
+	shiftedKey?: number; // Shifted version of the key (when shift is pressed)
+	baseLayoutKey?: number; // Key in standard PC-101 layout (for non-Latin layouts)
+	modifier: number;
+	eventType?: KeyEventType;
+}
+
+// Regex for Kitty protocol event type detection
+// Matches CSI sequences with :2 (repeat) or :3 (release) event type
+// Format: \x1b[...;modifier:event_type<terminator> where terminator is u, ~, or A-F/H
+const KITTY_RELEASE_PATTERN = /^\x1b\[[\d:;]*:3[u~ABCDHF]$/;
+const KITTY_REPEAT_PATTERN = /^\x1b\[[\d:;]*:2[u~ABCDHF]$/;
+
+/**
+ * Check if the input is a key release event.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Returns false if Kitty protocol is not active.
+ */
+export function isKeyRelease(data: string): boolean {
+	// Only detect release events when Kitty protocol is active
+	if (!kittyProtocolActive) {
+		return false;
+	}
+
+	// Don't treat bracketed paste content as key release
+	if (data.includes("\x1b[200~")) {
+		return false;
+	}
+
+	// Match the full CSI sequence pattern for release events
+	return KITTY_RELEASE_PATTERN.test(data);
+}
+
+/**
+ * Check if the input is a key repeat event.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Returns false if Kitty protocol is not active.
+ */
+export function isKeyRepeat(data: string): boolean {
+	// Only detect repeat events when Kitty protocol is active
+	if (!kittyProtocolActive) {
+		return false;
+	}
+
+	// Don't treat bracketed paste content as key repeat
+	if (data.includes("\x1b[200~")) {
+		return false;
+	}
+
+	// Match the full CSI sequence pattern for repeat events
+	return KITTY_REPEAT_PATTERN.test(data);
+}
+
+export function parseKittySequence(data: string): ParsedKittySequence | null {
+	const result = parseKittySequenceNative(data);
+	if (!result) return null;
+	return {
+		codepoint: result.codepoint,
+		shiftedKey: result.shiftedKey ?? undefined,
+		baseLayoutKey: result.baseLayoutKey ?? undefined,
+		modifier: result.modifier,
+		eventType: result.eventType,
+	};
+}
+
+/**
+ * Match input data against a key identifier string.
+ *
+ * Supported key identifiers:
+ * - Single keys: "escape", "tab", "enter", "backspace", "delete", "home", "end", "space"
+ * - Arrow keys: "up", "down", "left", "right"
+ * - Ctrl combinations: "ctrl+c", "ctrl+z", etc.
+ * - Shift combinations: "shift+tab", "shift+enter"
+ * - Alt combinations: "alt+enter", "alt+backspace"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x"
+ *
+ * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p")
+ *
+ * @param data - Raw input data from terminal
+ * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
+ */
+export function matchesKey(data: string, keyId: KeyId): boolean {
+	return matchesKeyNative(data, keyId, kittyProtocolActive);
+}
+
+/**
+ * Parse terminal input and return a normalized key identifier.
+ *
+ * Returns key names like "escape", "ctrl+c", "shift+tab", "alt+enter".
+ * Returns undefined if the input is not a recognized key sequence.
+ *
+ * @param data - Raw input data from terminal
+ */
+export function parseKey(data: string): string | undefined {
+	return parseKeyNative(data, kittyProtocolActive) ?? undefined;
+}

package/src/kill-ring.ts

@@ -0,0 +1,46 @@
+/**
+ * Ring buffer for Emacs-style kill/yank operations.
+ *
+ * Tracks killed (deleted) text entries. Consecutive kills can accumulate
+ * into a single entry. Supports yank (paste most recent) and yank-pop
+ * (cycle through older entries).
+ */
+export class KillRing {
+	#ring: string[] = [];
+
+	/**
+	 * Add text to the kill ring.
+	 *
+	 * @param text - The killed text to add
+	 * @param opts - Push options
+	 * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
+	 * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
+	 */
+	push(text: string, opts: { prepend: boolean; accumulate?: boolean }): void {
+		if (!text) return;
+
+		if (opts.accumulate && this.#ring.length > 0) {
+			const last = this.#ring.pop()!;
+			this.#ring.push(opts.prepend ? text + last : last + text);
+		} else {
+			this.#ring.push(text);
+		}
+	}
+
+	/** Get most recent entry without modifying the ring. */
+	peek(): string | undefined {
+		return this.#ring.length > 0 ? this.#ring[this.#ring.length - 1] : undefined;
+	}
+
+	/** Move last entry to front (for yank-pop cycling). */
+	rotate(): void {
+		if (this.#ring.length > 1) {
+			const last = this.#ring.pop()!;
+			this.#ring.unshift(last);
+		}
+	}
+
+	get length(): number {
+		return this.#ring.length;
+	}
+}

package/src/mermaid.ts

@@ -0,0 +1,140 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $ } from "bun";
+
+export interface MermaidImage {
+	base64: string;
+	widthPx: number;
+	heightPx: number;
+}
+
+export interface MermaidRenderOptions {
+	theme?: "default" | "dark" | "forest" | "neutral";
+	backgroundColor?: string;
+	width?: number;
+	scale?: number;
+}
+
+/**
+ * Render mermaid diagram source to PNG.
+ *
+ * Uses `mmdc` (mermaid-cli) which must be installed and in PATH.
+ * Returns null if rendering fails or mmdc is unavailable.
+ */
+export async function renderMermaidToPng(
+	source: string,
+	options: MermaidRenderOptions = {},
+): Promise<MermaidImage | null> {
+	const mmdc = Bun.which("mmdc");
+	if (!mmdc) {
+		return null;
+	}
+
+	const tmpDir = path.join(os.tmpdir(), `mermaid-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	const inputPath = path.join(tmpDir, "input.mmd");
+	const outputPath = path.join(tmpDir, "output.png");
+
+	try {
+		await Bun.write(inputPath, source);
+
+		const args: string[] = ["-i", inputPath, "-o", outputPath, "-q"];
+
+		if (options.theme) {
+			args.push("-t", options.theme);
+		}
+		if (options.backgroundColor) {
+			args.push("-b", options.backgroundColor);
+		}
+		if (options.width) {
+			args.push("-w", String(options.width));
+		}
+		if (options.scale) {
+			args.push("-s", String(options.scale));
+		}
+
+		const result = await $`${mmdc} ${args}`.quiet().nothrow();
+		if (result.exitCode !== 0) {
+			return null;
+		}
+
+		const outputFile = Bun.file(outputPath);
+		if (!(await outputFile.exists())) {
+			return null;
+		}
+
+		const buffer = await outputFile.bytes();
+		const base64 = buffer.toBase64();
+
+		const dims = parsePngDimensions(buffer);
+		if (!dims) {
+			return null;
+		}
+
+		return {
+			base64,
+			widthPx: dims.width,
+			heightPx: dims.height,
+		};
+	} catch {
+		return null;
+	} finally {
+		await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+	}
+}
+
+function parsePngDimensions(buffer: Uint8Array): { width: number; height: number } | null {
+	if (buffer.length < 24) return null;
+	if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {
+		return null;
+	}
+	const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+	return {
+		width: view.getUint32(16, false),
+		height: view.getUint32(20, false),
+	};
+}
+
+/**
+ * Extract mermaid code blocks from markdown text.
+ * Returns array of { source, startIndex, endIndex } for each block.
+ */
+export function extractMermaidBlocks(markdown: string): { source: string; hash: string }[] {
+	const blocks: { source: string; hash: string }[] = [];
+	const regex = /```mermaid\s*\n([\s\S]*?)```/g;
+
+	for (let match = regex.exec(markdown); match !== null; match = regex.exec(markdown)) {
+		const source = match[1].trim();
+		const hash = Bun.hash(source).toString(16);
+		blocks.push({ source, hash });
+	}
+
+	return blocks;
+}
+
+/**
+ * Pre-render all mermaid blocks in markdown text.
+ * Returns a cache map: hash → MermaidImage.
+ */
+export async function prerenderMermaidBlocks(
+	markdown: string,
+	options: MermaidRenderOptions = {},
+): Promise<Map<string, MermaidImage>> {
+	const blocks = extractMermaidBlocks(markdown);
+	const cache = new Map<string, MermaidImage>();
+
+	const results = await Promise.all(
+		blocks.map(async ({ source, hash }) => {
+			const image = await renderMermaidToPng(source, options);
+			return { hash, image };
+		}),
+	);
+
+	for (const { hash, image } of results) {
+		if (image) {
+			cache.set(hash, image);
+		}
+	}
+
+	return cache;
+}