@gajae-code/tui 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-06-10
+
+### Fixed
+
+- Fixed Korean (and other multi-byte UTF-8) paste mojibake in terminal input: `StdinBuffer` is now the single raw-stdin decoding boundary using a persistent `StringDecoder`, so multi-byte characters split across stdin read boundaries are reassembled instead of producing U+FFFD. `ProcessTerminal` no longer relies on `process.stdin.setEncoding("utf8")` and forwards raw Buffers; the legacy single-high-byte meta conversion is preserved. (#454)
+
 ## [0.4.0] - 2026-06-06
 
 ### Changed

package/dist/types/stdin-buffer.d.ts

@@ -31,6 +31,13 @@ export type StdinBufferEventMap = {
 /**
  * Buffers stdin input and emits complete sequences via the 'data' event.
  * Handles partial escape sequences that arrive across multiple chunks.
+ *
+ * StdinBuffer is the single raw-stdin decoding boundary: raw terminal bytes
+ * enter via `process()` and decoded string events leave via the 'data' and
+ * 'paste' events. UTF-8 is decoded exactly once here (using a persistent
+ * StringDecoder) so multi-byte characters split across chunk boundaries are
+ * reassembled rather than corrupted into U+FFFD. All downstream parsing
+ * (escape sequences, bracketed paste, Kitty/CSI, OSC/DA1) operates on strings.
  */
 export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
     #private;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.4.1",
-		"@gajae-code/utils": "0.4.1",
+		"@gajae-code/natives": "0.4.3",
+		"@gajae-code/utils": "0.4.3",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/stdin-buffer.ts

@@ -16,6 +16,8 @@
  * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
  * MIT License - Copyright (c) 2025 opentui
  */
+
+import { StringDecoder } from "node:string_decoder";
 import { EventEmitter } from "events";
 
 const ESC = "\x1b";
@@ -246,6 +248,13 @@ export type StdinBufferEventMap = {
 /**
  * Buffers stdin input and emits complete sequences via the 'data' event.
  * Handles partial escape sequences that arrive across multiple chunks.
+ *
+ * StdinBuffer is the single raw-stdin decoding boundary: raw terminal bytes
+ * enter via `process()` and decoded string events leave via the 'data' and
+ * 'paste' events. UTF-8 is decoded exactly once here (using a persistent
+ * StringDecoder) so multi-byte characters split across chunk boundaries are
+ * reassembled rather than corrupted into U+FFFD. All downstream parsing
+ * (escape sequences, bracketed paste, Kitty/CSI, OSC/DA1) operates on strings.
  */
 export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	#buffer: string = "";
@@ -254,6 +263,11 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	#pasteMode: boolean = false;
 	#pasteBuffer: string = "";
 	#pendingKittyPrintableCodepoint: number | undefined;
+	// Persistent UTF-8 decoder. Holds an incomplete trailing multi-byte
+	// sequence between chunks so split reads (e.g. a 3-byte Korean syllable
+	// split across two stdin events) reassemble correctly instead of emitting
+	// U+FFFD. Reset on clear()/destroy(); never finalized on normal flush.
+	#decoder = new StringDecoder("utf8");
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
@@ -267,22 +281,38 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			this.#timeout = undefined;
 		}
 
-		// Handle high-byte conversion (for compatibility with parseKeypress)
-		// If buffer has single byte > 127, convert to ESC + (byte - 128)
+		// Decode raw bytes into a string. Buffers come from raw stdin; strings
+		// come from tests or non-terminal callers and are already decoded.
 		let str: string;
+		let decodedFromBuffer = false;
 		if (Buffer.isBuffer(data)) {
+			// Legacy 8-bit meta: an isolated high byte (0x80-0xFF) is treated
+			// as ESC + (byte - 128) for Alt/meta compatibility, BEFORE UTF-8
+			// decoding. This is the one documented exception to UTF-8 boundary
+			// decoding — a lone high byte that is also a valid UTF-8 lead byte
+			// is still read as meta — so such a byte is never fed to the decoder.
 			if (data.length === 1 && data[0]! > 127) {
 				const byte = data[0]! - 128;
 				str = `\x1b${String.fromCharCode(byte)}`;
 			} else {
-				str = data.toString();
+				// Decode through the persistent StringDecoder so a multi-byte
+				// sequence split across chunks (e.g. a 3-byte Korean syllable)
+				// is reassembled instead of emitting U+FFFD.
+				str = this.#decoder.write(data);
+				decodedFromBuffer = true;
 			}
 		} else {
 			str = data;
 		}
 
 		if (str.length === 0 && this.#buffer.length === 0) {
-			this.#emitDataSequence("");
+			// A Buffer that decoded to nothing means the decoder is holding an
+			// incomplete UTF-8 prefix; emit nothing and wait for the completing
+			// bytes. Preserve the historical empty 'data' event for explicit
+			// empty-string input only.
+			if (!decodedFromBuffer) {
+				this.#emitDataSequence("");
+			}
 			return;
 		}
 
@@ -398,6 +428,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		this.#pasteMode = false;
 		this.#pasteBuffer = "";
 		this.#pendingKittyPrintableCodepoint = undefined;
+		// Drop any incomplete multi-byte sequence the decoder is holding so a
+		// stale partial prefix cannot combine with future input. destroy()
+		// resets the decoder by calling clear().
+		this.#decoder = new StringDecoder("utf8");
 	}
 
 	getBuffer(): string {

package/src/terminal.ts

@@ -123,7 +123,7 @@ export class ProcessTerminal implements Terminal {
 	#modifyOtherKeysActive = false;
 	#modifyOtherKeysTimeout?: Timer;
 	#stdinBuffer?: StdinBuffer;
-	#stdinDataHandler?: (data: string) => void;
+	#stdinDataHandler?: (data: string | Buffer) => void;
 	#dead = false;
 	#writeLogPath = $env.PI_TUI_WRITE_LOG || "";
 	#detachLogPath = $env.PI_TUI_TERMINAL_DETACH_LOG || "";
@@ -165,7 +165,11 @@ export class ProcessTerminal implements Terminal {
 		if (process.stdin.setRawMode) {
 			process.stdin.setRawMode(true);
 		}
-		process.stdin.setEncoding("utf8");
+		// Do NOT setEncoding("utf8"): raw stdin chunks may split a multi-byte
+		// UTF-8 character across reads, and Bun's raw-TTY string decoding does
+		// not reliably reassemble them (issue #454 — Korean paste mojibake).
+		// StdinBuffer is the single decoding boundary and decodes Buffers via a
+		// persistent StringDecoder, so we forward raw Buffers untouched.
 		process.stdin.resume();
 
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
@@ -420,7 +424,7 @@ export class ProcessTerminal implements Terminal {
 		});
 
 		// Handler that pipes stdin data through the buffer
-		this.#stdinDataHandler = (data: string) => {
+		this.#stdinDataHandler = (data: string | Buffer) => {
 			this.#stdinBuffer!.process(data);
 		};
 	}

package/src/ttyid.ts

@@ -39,6 +39,13 @@ export function getTtyPath(): string | null {
  * Returns null if no terminal can be identified (e.g., piped input).
  */
 export function getTerminalId(): string | null {
+	// Inside tmux the stdin TTY path is unstable (it tracks the attached
+	// client, not the pane), which spawns duplicate sessions and breaks
+	// /resume. Prefer the stable per-pane TMUX_PANE identifier instead.
+	if (process.env.TMUX && process.env.TMUX_PANE) {
+		return `tmux-${process.env.TMUX_PANE}`;
+	}
+
 	// TTY device path — most reliable, unique per terminal tab
 	if (process.stdin.isTTY) {
 		try {

package/src/tui.ts

@@ -641,6 +641,15 @@ export class TUI extends Container {
 		} catch {
 			this.#markTerminalUnavailable();
 		}
+		// Teardown: release the retained rendered transcript so a stopped TUI does
+		// not pin a flat copy of every emitted line for the process lifetime.
+		// Safe across temporary stop/start (Ctrl-Z resume, external editor): start()
+		// issues a forced render that rebuilds this state and fully redraws, and
+		// focus/listener state is intentionally preserved so input routing survives
+		// a resume.
+		this.#previousLines = [];
+		this.#previousWidth = 0;
+		this.#previousHeight = 0;
 	}
 
 	requestRender(force = false, source = "unknown"): void {