@gajae-code/tui 0.15.2 → 0.15.4

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.15.4] - 2026-08-29
+
+### Fixed
+
+- Path autocomplete matches decomposed (NFD) file names against composed (NFC) input. Composer keystrokes are NFC-normalized while macOS volumes commonly return Hangul and other composed scripts in NFD, so `@한` found nothing even though `한글.txt` existed; both the directory-listing prefix match and the fuzzy filter now compare NFC forms while completion values keep the on-disk name. The native fuzzy finder applies the same normalization to queries and candidates.
+
+## [0.15.3] - 2026-08-27
+
+### Fixed
+
+- Loader instances can opt into layout-only repaint requests so transient status animation does not force unchanged transcript subtree reconstruction.
+
 ## [0.15.2] - 2026-08-25
 
 ### Changed
@@ -18,6 +30,11 @@
 
 - Mouse selection now supports double-click word select and triple-click line select. Enabling GJC's own mouse capture previously removed the terminal's native word/line selection without replacing it: SGR mouse reports carry no click counter, so the TUI only ever saw single presses and drags. Repeat presses on the same cell within `DEFAULT_MULTI_CLICK_INTERVAL_MS` (400ms) now escalate char -> word -> line, a fourth press stays on line rather than cycling back, and any wheel notch, different cell, or expired window restarts at char. A word/line press is a complete selection, so it paints and copies on release without needing a drag; a plain single click still copies nothing. Dragging after a double or triple click extends by whole words or rows in either direction, pivoting on the anchor span instead of collapsing it. Word bounds use the xterm `wordSeparator` set, so a path stays intact and a click on whitespace selects the whitespace run, and all ranges are measured in grapheme-aligned columns so wide CJK and emoji cells are never split. `TUI`'s new `multiClickIntervalMs` option overrides the window; `0` disables escalation entirely.
 
+### Fixed
+
+- `ctrl+backspace` now deletes the previous word in the composer, including on Windows Terminal. `tui.editor.deleteWordBackward` has always declared `ctrl+w`, `alt+backspace` **and** `ctrl+backspace`, but the editor's literal chain only implemented the first two, so the third declared chord silently did nothing. Windows Terminal additionally sends raw `0x08` for that chord while the native matcher resolves `0x08` as unmodified backspace only, so `matchesKey` now disambiguates the byte on that host (a purpose-built heuristic for this existed but had no caller). Raw `0x08` still means plain backspace everywhere else, including a Windows Terminal session forwarded over SSH.
+- Composer kill-ring, word-delete and line-kill chords are now resolved through the keybinding registry instead of hard-coded literals, so remapping them actually moves them: `tui.editor.deleteToLineEnd`, `tui.editor.deleteToLineStart`, `tui.editor.deleteWordBackward`, `tui.editor.deleteWordForward`, `tui.editor.yank`, and `tui.editor.yankPop`. `docs/keybindings.md` already advertised these as registry-managed, so this makes the published contract true; the same file now also names the two remaining exceptions (`tui.editor.cursorLineStart` and `tui.editor.cursorLineEnd`, still matched by literal `ctrl+a` / `ctrl+e` ahead of their registry branches). Default behavior for all five migrated chords is unchanged, and `Editor` now dispatches these ids the same way `Input` and `SecretInput` already did.
+
 ## [0.15.0] - 2026-08-22
 
 ### Fixed

package/dist/types/components/loader.d.ts

@@ -11,6 +11,8 @@ import { Text } from "./text";
  */
 export interface LoaderOptions {
     timeDependentColor?: boolean;
+    /** Request a layout-only repaint when the loader is outside the transcript anchor. */
+    renderScope?: "full" | "layout";
 }
 /** Test-only performance counters for advisory baseline tests. */
 export declare const __loaderPerfCounters: {

package/dist/types/keys.d.ts

@@ -28,7 +28,15 @@ declare function isWindowsTerminalSession(): boolean;
  * Prefer explicit Kitty / CSI-u / modifyOtherKeys sequences whenever they are
  * available. Fall back to a Windows Terminal heuristic only for raw BS bytes.
  */
-declare function matchesRawBackspace(data: string, expectedModifier: number): boolean;
+/**
+ * Resolve the ambiguous raw backspace bytes against a chord's expected modifier.
+ *
+ * `\x7f` is always plain backspace. `\x08` is the ambiguous one: Windows
+ * Terminal sends it for Ctrl+Backspace, while legacy terminals and some tmux
+ * setups send it for plain Backspace. Returns undefined when the byte is neither,
+ * meaning the caller should fall through to normal matching.
+ */
+declare function matchesRawBackspace(data: string, expectedModifier: number): boolean | undefined;
 export { isWindowsTerminalSession, matchesRawBackspace };
 /**
  * Set the global Kitty keyboard protocol state.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.15.2",
+	"version": "0.15.4",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.15.2",
-		"@gajae-code/utils": "0.15.2",
+		"@gajae-code/natives": "0.15.4",
+		"@gajae-code/utils": "0.15.4",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/autocomplete.ts

@@ -18,6 +18,10 @@ async function fuzzyFindNative(): Promise<NativeFuzzyFind> {
 
 const PATH_DELIMITERS = new Set([" ", "\t", '"', "'", "="]);
 
+function isAbsolutePathLike(value: string): boolean {
+	return path.isAbsolute(value) || path.win32.isAbsolute(value);
+}
+
 function buildAutocompleteFuzzyDiscoveryProfile(
 	query: string,
 	basePath: string,
@@ -310,7 +314,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 	// Intentionally separate from pi-natives cache: this cache is a local,
 	// per-directory readdir fast-path for prefix completions. Global fuzzy
 	// discovery continues to use native fuzzyFind + shared scan cache.
-	#dirCache: Map<string, { entries: fs.Dirent[]; timestamp: number }> = new Map();
+	#dirCache: Map<string, { entries: fs.Dirent[]; resolvedDir: string; timestamp: number }> = new Map();
 	readonly #DIR_CACHE_TTL = 2000; // 2 seconds
 
 	constructor(commands: (SlashCommand | AutocompleteItem)[] = [], basePath: string = getProjectDir()) {
@@ -589,7 +593,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 	async #resolveScopedFuzzyQuery(
 		rawQuery: string,
 	): Promise<{ baseDir: string; query: string; displayBase: string } | null> {
-		const slashIndex = rawQuery.lastIndexOf("/");
+		const slashIndex = Math.max(rawQuery.lastIndexOf("/"), rawQuery.lastIndexOf("\\"));
 		if (slashIndex === -1) {
 			return null;
 		}
@@ -606,15 +610,16 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			baseDir = path.join(this.#basePath, displayBase);
 		}
 
-		try {
-			if (!(await fs.promises.stat(baseDir)).isDirectory()) {
-				return null;
-			}
-		} catch {
+		const resolvedDir = await this.#resolveDirectoryPath(baseDir);
+		if (!resolvedDir) {
 			return null;
 		}
 
-		return { baseDir, query, displayBase };
+		return {
+			baseDir: resolvedDir,
+			query,
+			displayBase: this.#formatResolvedDirectoryPrefix(displayBase, resolvedDir),
+		};
 	}
 
 	#scopedPathForDisplay(displayBase: string, relativePath: string): string {
@@ -624,16 +629,75 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		return `${displayBase}${relativePath}`;
 	}
 
-	async #getCachedDirEntries(searchDir: string): Promise<fs.Dirent[]> {
+	async #resolveDirectoryPath(candidate: string): Promise<string | null> {
+		const absoluteCandidate = path.resolve(candidate);
+		const root = path.parse(absoluteCandidate).root;
+		const relativePath = path.relative(root, absoluteCandidate);
+		const components = relativePath ? relativePath.split(path.sep).filter(Boolean) : [];
+		let resolvedPath = root;
+
+		for (const component of components) {
+			let entries: fs.Dirent[];
+			try {
+				entries = await fs.promises.readdir(resolvedPath, { withFileTypes: true });
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+				throw error;
+			}
+
+			const exactEntry = entries.find(entry => entry.name === component);
+			const matchingEntries = exactEntry
+				? [exactEntry]
+				: entries.filter(entry => entry.name.normalize("NFC") === component.normalize("NFC"));
+			// An exact spelling is unambiguous even when a Linux directory contains
+			// both NFC and NFD variants. A normalized-only match must not guess
+			// between siblings, since doing so can expose the wrong subtree.
+			if (matchingEntries.length !== 1) return null;
+
+			const entry = matchingEntries[0];
+			if (!entry) return null;
+			let isDirectory = entry.isDirectory();
+			if (!isDirectory && entry.isSymbolicLink()) {
+				isDirectory = (await fs.promises.stat(path.join(resolvedPath, entry.name))).isDirectory();
+			}
+			if (!isDirectory) return null;
+			resolvedPath = path.join(resolvedPath, entry.name);
+		}
+
+		return resolvedPath;
+	}
+
+	#formatResolvedDirectoryPrefix(rawPrefix: string, resolvedDir: string): string {
+		const normalizedResolvedDir = resolvedDir.replaceAll(path.sep, "/");
+		if (rawPrefix === "~" || rawPrefix.startsWith("~/")) {
+			const homeRelative = path.relative(path.resolve(os.homedir()), resolvedDir).replaceAll(path.sep, "/");
+			return homeRelative ? `~/${homeRelative}/` : "~/";
+		}
+		if (isAbsolutePathLike(rawPrefix)) {
+			return normalizedResolvedDir === "/" ? "/" : `${normalizedResolvedDir}/`;
+		}
+
+		const relative = path.relative(path.resolve(this.#basePath), resolvedDir).replaceAll(path.sep, "/");
+		if (rawPrefix.startsWith("./")) {
+			return relative ? `./${relative}/` : "./";
+		}
+		return relative ? `${relative}/` : "";
+	}
+
+	async #getCachedDirEntries(searchDir: string): Promise<{ entries: fs.Dirent[]; resolvedDir: string }> {
 		const now = Date.now();
 		const cached = this.#dirCache.get(searchDir);
 
 		if (cached && now - cached.timestamp < this.#DIR_CACHE_TTL) {
-			return cached.entries;
+			return { entries: cached.entries, resolvedDir: cached.resolvedDir };
 		}
 
-		const entries = await fs.promises.readdir(searchDir, { withFileTypes: true });
-		this.#dirCache.set(searchDir, { entries, timestamp: now });
+		const resolvedDir = await this.#resolveDirectoryPath(searchDir);
+		if (!resolvedDir) {
+			throw new Error(`Directory not found: ${searchDir}`);
+		}
+		const entries = await fs.promises.readdir(resolvedDir, { withFileTypes: true });
+		this.#dirCache.set(searchDir, { entries, resolvedDir, timestamp: now });
 
 		if (this.#dirCache.size > 100) {
 			const sortedKeys = [...this.#dirCache.entries()]
@@ -645,7 +709,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			}
 		}
 
-		return entries;
+		return { entries, resolvedDir };
 	}
 
 	invalidateDirCache(dir?: string): void {
@@ -680,7 +744,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 
 			if (isRootPrefix) {
 				// Complete from specified position
-				if (rawPrefix.startsWith("~") || expandedPrefix.startsWith("/")) {
+				if (rawPrefix.startsWith("~") || isAbsolutePathLike(expandedPrefix)) {
 					searchDir = expandedPrefix;
 				} else {
 					searchDir = path.join(this.#basePath, expandedPrefix);
@@ -688,7 +752,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				searchPrefix = "";
 			} else if (rawPrefix.endsWith("/")) {
 				// If prefix ends with /, show contents of that directory
-				if (rawPrefix.startsWith("~") || expandedPrefix.startsWith("/")) {
+				if (rawPrefix.startsWith("~") || isAbsolutePathLike(expandedPrefix)) {
 					searchDir = expandedPrefix;
 				} else {
 					searchDir = path.join(this.#basePath, expandedPrefix);
@@ -698,7 +762,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				// Split into directory and file prefix
 				const dir = path.dirname(expandedPrefix);
 				const file = path.basename(expandedPrefix);
-				if (rawPrefix.startsWith("~") || expandedPrefix.startsWith("/")) {
+				if (rawPrefix.startsWith("~") || isAbsolutePathLike(expandedPrefix)) {
 					searchDir = dir;
 				} else {
 					searchDir = path.join(this.#basePath, dir);
@@ -706,11 +770,13 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				searchPrefix = file;
 			}
 
-			const entries = await this.#getCachedDirEntries(searchDir);
+			const { entries, resolvedDir } = await this.#getCachedDirEntries(searchDir);
 			const suggestions: AutocompleteItem[] = [];
+			const lowerSearchPrefix = searchPrefix.normalize("NFC").toLowerCase();
+			const displayDirectoryPrefix = this.#formatResolvedDirectoryPrefix(rawPrefix, resolvedDir);
 
 			for (const entry of entries) {
-				if (!entry.name.toLowerCase().startsWith(searchPrefix.toLowerCase())) {
+				if (!entry.name.normalize("NFC").toLowerCase().startsWith(lowerSearchPrefix)) {
 					continue;
 				}
 				// Skip .git directory
@@ -722,7 +788,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				let isDirectory = entry.isDirectory();
 				if (!isDirectory && entry.isSymbolicLink()) {
 					try {
-						const fullPath = path.join(searchDir, entry.name);
+						const fullPath = path.join(resolvedDir, entry.name);
 						isDirectory = (await fs.promises.stat(fullPath)).isDirectory();
 					} catch {
 						// Broken symlink, file deleted between readdir and stat, or permission error
@@ -730,41 +796,8 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 					}
 				}
 
-				let relativePath: string;
 				const name = entry.name;
-				const displayPrefix = rawPrefix;
-
-				if (displayPrefix.endsWith("/")) {
-					// If prefix ends with /, append entry to the prefix
-					relativePath = displayPrefix + name;
-				} else if (displayPrefix.includes("/")) {
-					// Preserve ~/ format for home directory paths
-					if (displayPrefix.startsWith("~/")) {
-						const homeRelativeDir = displayPrefix.slice(2); // Remove ~/
-						const dir = path.dirname(homeRelativeDir);
-						relativePath = `~/${dir === "." ? name : path.join(dir, name)}`;
-					} else if (displayPrefix.startsWith("/")) {
-						// Absolute path - construct properly
-						const dir = path.dirname(displayPrefix);
-						if (dir === "/") {
-							relativePath = `/${name}`;
-						} else {
-							relativePath = `${dir}/${name}`;
-						}
-					} else {
-						relativePath = path.join(path.dirname(displayPrefix), name);
-						if (displayPrefix.startsWith("./") && !relativePath.startsWith("./")) {
-							relativePath = `./${relativePath}`;
-						}
-					}
-				} else {
-					// For standalone entries, preserve ~/ if original prefix was ~/
-					if (displayPrefix.startsWith("~")) {
-						relativePath = `~/${name}`;
-					} else {
-						relativePath = name;
-					}
-				}
+				const relativePath = `${displayDirectoryPrefix}${name}`;
 
 				const pathValue = isDirectory ? `${relativePath}/` : relativePath;
 				const value = buildCompletionValue(pathValue, {
@@ -798,17 +831,20 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 	async #getFuzzyFileSuggestions(query: string, options: { isQuotedPrefix: boolean }): Promise<AutocompleteItem[]> {
 		try {
 			const scopedQuery = await this.#resolveScopedFuzzyQuery(query);
+			if (query.includes("/") && !scopedQuery) {
+				return [];
+			}
 			const searchPath = scopedQuery?.baseDir ?? this.#basePath;
 			const fuzzyQuery = scopedQuery?.query ?? query;
 			const result = await (await fuzzyFindNative())(buildAutocompleteFuzzyDiscoveryProfile(fuzzyQuery, searchPath));
-			const lowerQuery = fuzzyQuery.toLowerCase();
+			const lowerQuery = fuzzyQuery.normalize("NFC").toLowerCase();
 			const filteredMatches = result.matches.filter(entry => {
 				const p = entry.path.endsWith("/") ? entry.path.slice(0, -1) : entry.path;
 				const normalized = p.replaceAll("\\", "/");
 				if (/(^|\/)\.git(\/|$)/.test(normalized)) {
 					return false;
 				}
-				return lowerQuery.length === 0 || fuzzyMatch(lowerQuery, normalized.toLowerCase());
+				return lowerQuery.length === 0 || fuzzyMatch(lowerQuery, normalized.normalize("NFC").toLowerCase());
 			});
 			const topEntries = filteredMatches.slice(0, 20);
 			const suggestions: AutocompleteItem[] = [];

package/src/components/editor.ts

@@ -1359,32 +1359,34 @@ export class Editor implements Component, Focusable {
 		}
 
 		// Continue with rest of input handling
-		// Ctrl+K - Delete to end of line
-		if (matchesKey(data, "ctrl+k")) {
+		// Kill/yank/word-delete actions resolve through the keybinding registry so a
+		// user remap actually moves them, matching `Input` and `SecretInput`. The
+		// five parity ids below declare exactly the chords the previous literals
+		// implemented, so default behavior is unchanged.
+		if (kb.matches(data, "tui.editor.deleteToLineEnd")) {
 			this.#deleteToEndOfLine();
 		}
 		// Ctrl+U - Delete to start of line
-		else if (matchesKey(data, "ctrl+u")) {
+		else if (kb.matches(data, "tui.editor.deleteToLineStart")) {
 			this.#deleteToStartOfLine();
 		}
-		// Ctrl+W - Delete word backwards
-		else if (matchesKey(data, "ctrl+w")) {
-			this.#deleteWordBackwards();
-		}
-		// Option/Alt+Backspace - Delete word backwards
-		else if (matchesKey(data, "alt+backspace")) {
+		// Deliberate repair, not parity: `tui.editor.deleteWordBackward` declares
+		// ctrl+w, alt+backspace AND ctrl+backspace, but the previous literal chain
+		// implemented only the first two, so the declared ctrl+backspace never
+		// worked in the composer.
+		else if (kb.matches(data, "tui.editor.deleteWordBackward")) {
 			this.#deleteWordBackwards();
 		}
 		// Option/Alt+D - Delete word forwards
-		else if (matchesKey(data, "alt+d") || matchesKey(data, "alt+delete")) {
+		else if (kb.matches(data, "tui.editor.deleteWordForward")) {
 			this.#deleteWordForwards();
 		}
 		// Ctrl+Y - Yank from kill ring
-		else if (matchesKey(data, "ctrl+y")) {
+		else if (kb.matches(data, "tui.editor.yank")) {
 			this.#yankFromKillRing();
 		}
 		// Alt+Y - Yank-pop (cycle kill ring)
-		else if (matchesKey(data, "alt+y")) {
+		else if (kb.matches(data, "tui.editor.yankPop")) {
 			this.#yankPop();
 		}
 		// Ctrl+A - Move to start of line

package/src/components/loader.ts

@@ -17,6 +17,8 @@ const SPINNER_ADVANCE_MS = 80;
  */
 export interface LoaderOptions {
 	timeDependentColor?: boolean;
+	/** Request a layout-only repaint when the loader is outside the transcript anchor. */
+	renderScope?: "full" | "layout";
 }
 
 const SMOOTH_ANIMATION_MS = 16;
@@ -115,6 +117,7 @@ export class Loader extends Text {
 		this.#lastDisplayed = next;
 		this.setText(next);
 		__loaderPerfCounters.renderRequests += 1;
-		this.#ui?.requestRender(false, "loader");
+		if (this.options.renderScope === "layout") this.#ui?.requestLayoutRender("loader");
+		else this.#ui?.requestRender(false, "loader");
 	}
 }

package/src/keys.ts

@@ -47,13 +47,24 @@ function isWindowsTerminalSession(): boolean {
  * Prefer explicit Kitty / CSI-u / modifyOtherKeys sequences whenever they are
  * available. Fall back to a Windows Terminal heuristic only for raw BS bytes.
  */
-function matchesRawBackspace(data: string, expectedModifier: number): boolean {
+/**
+ * Resolve the ambiguous raw backspace bytes against a chord's expected modifier.
+ *
+ * `\x7f` is always plain backspace. `\x08` is the ambiguous one: Windows
+ * Terminal sends it for Ctrl+Backspace, while legacy terminals and some tmux
+ * setups send it for plain Backspace. Returns undefined when the byte is neither,
+ * meaning the caller should fall through to normal matching.
+ */
+function matchesRawBackspace(data: string, expectedModifier: number): boolean | undefined {
 	if (data === "\x7f") return expectedModifier === 0;
-	if (data !== "\x08") return false;
+	if (data !== "\x08") return undefined;
 	// On Windows Terminal, 0x08 = Ctrl+Backspace. On others, it's plain Backspace.
-	return isWindowsTerminalSession() ? expectedModifier === 4 : expectedModifier === 0;
+	return isWindowsTerminalSession() ? expectedModifier === RAW_BACKSPACE_CTRL_MODIFIER : expectedModifier === 0;
 }
 
+/** Modifier code the raw-backspace heuristic treats as Ctrl. */
+const RAW_BACKSPACE_CTRL_MODIFIER = 4;
+
 export { isWindowsTerminalSession, matchesRawBackspace };
 
 // =============================================================================
@@ -744,6 +755,15 @@ export function decodePrintableKey(data: string): string | undefined {
  * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
  */
 export function matchesKey(data: string, keyId: KeyId): boolean {
+	if (data === "\x08") {
+		// Raw 0x08 is ambiguous and the native matcher resolves it as unmodified
+		// backspace only, so on Windows Terminal -- where the byte means
+		// ctrl+backspace -- every chord declaring ctrl+backspace silently never
+		// fired. One helper owns that decision for both chords so the two cannot
+		// drift apart.
+		if (keyId === "ctrl+backspace") return matchesRawBackspace(data, RAW_BACKSPACE_CTRL_MODIFIER) === true;
+		if (keyId === "backspace") return matchesRawBackspace(data, 0) === true;
+	}
 	return (
 		nativeKeys().matchesKey(data, keyId, kittyProtocolActive) ||
 		(kittyProtocolActive && matchesKoreanDubeolsikKittySequence(data, keyId))

package/src/tui.ts

@@ -1172,6 +1172,7 @@ export class TUI extends Container {
 	}
 
 	#visibleWidthForDifferentialGuard(line: string): number {
+		if (line.length === 0) return 0;
 		const cached = this.#lineEmitWidthCache.get(line);
 		if (cached !== undefined) return cached;
 		TUI.#renderCounters.differentialGuardVisibleWidthCalls += 1;