@gajae-code/tui 0.12.21 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added atomic same-line deletion APIs and an `Editor` undo callback for keeping application state synchronized with editor history.
+### Fixed
+
+- macOS Terminal.app Option+Arrow input is now buffered and decoded as a single Meta-wrapped escape sequence, so Option+Up/Down can open and navigate queued-message selectors.
+- Terminal.app Meta-prefix decoding now covers legacy Option shortcuts for printable symbols, digits, spaces, and Ctrl+Option symbol chords while preserving enhanced Kitty and modifyOtherKeys Super/Command matching.
+- Kitty and modifyOtherKeys function-key sequences now match consistently for F1–F12, including unmodified CSI forms.
+
 ## [0.12.21] - 2026-08-09
 
 ## [0.12.20] - 2026-08-09

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

@@ -44,6 +44,7 @@ export declare class Editor implements Component, Focusable {
     onSubmit?: (text: string) => void;
     onAltEnter?: (text: string) => void;
     onChange?: (text: string) => void;
+    onUndo?: (text: string) => void;
     onAutocompleteCancel?: () => void;
     onTabDeclined?: (text: string) => void;
     /**
@@ -122,6 +123,16 @@ export declare class Editor implements Component, Focusable {
     setText(text: string): void;
     /** Insert text at the current cursor position */
     insertText(text: string): void;
+    /**
+     * Delete an exact text run immediately before the cursor as one edit.
+     * Returns false without changing the document when the text is not present.
+     */
+    deleteTextBeforeCursor(text: string): boolean;
+    /**
+     * Delete a same-line text range containing the cursor as one edit.
+     * Returns false without changing the document when the range is invalid.
+     */
+    deleteTextRangeAroundCursor(startCol: number, endCol: number): boolean;
     isShowingAutocomplete(): boolean;
 }
 export {};

package/dist/types/keys.d.ts

@@ -62,6 +62,7 @@ export interface ParsedKeyId {
  * Parse a case-insensitive key identifier into normalized dispatch parts.
  * The legacy `plus` base-key alias normalizes to `+`; the trailing `+` in
  * values such as `ctrl++` is the literal plus base.
+ * Modifier aliases `option`/`meta` and `command`/`cmd` normalize to `alt` and `super`.
  */
 export declare function parseKeyId(value: string): ParsedKeyId | undefined;
 /** Whether a value is a valid canonical key identifier. */
@@ -73,10 +74,7 @@ export declare function isKeyId(value: string): value is KeyId;
  * is literally `"enter"`); the value of `Key` over a bag of magic strings is
  * that each property is typed to the exact `KeyId` literal it produces and the
  * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
- * is `"ctrl+c"`, not just `string`). This mirrors the upstream
- * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
- * scope alias (`@mariozechner`, `@earendil-works`, `@gajae-code`) keep working
- * once the specifier shim remaps them to this package.
+ * The canonical modifier helpers mirror the upstream `@mariozechner/pi-tui` `Key` export so plugins built against any scope alias (`@mariozechner`, `@earendil-works`, `@gajae-code`) keep working once the specifier shim remaps them to this package. The additional `option`/`command` helpers normalize macOS naming to the portable `alt`/`super` identifiers.
  */
 export declare const Key: {
     readonly escape: "escape";
@@ -143,7 +141,10 @@ export declare const Key: {
     readonly ctrl: <K extends BaseKey>(key: K) => `ctrl+${K}`;
     readonly shift: <K extends BaseKey>(key: K) => `shift+${K}`;
     readonly alt: <K extends BaseKey>(key: K) => `alt+${K}`;
+    readonly option: <K extends BaseKey>(key: K) => `alt+${K}`;
     readonly super: <K extends BaseKey>(key: K) => `super+${K}`;
+    readonly cmd: <K extends BaseKey>(key: K) => `super+${K}`;
+    readonly command: <K extends BaseKey>(key: K) => `super+${K}`;
     readonly ctrlShift: <K extends BaseKey>(key: K) => `ctrl+shift+${K}`;
     readonly shiftCtrl: <K extends BaseKey>(key: K) => `shift+ctrl+${K}`;
     readonly ctrlAlt: <K extends BaseKey>(key: K) => `ctrl+alt+${K}`;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.12.21",
+	"version": "0.13.0",
 	"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.12.21",
-		"@gajae-code/utils": "0.12.21",
+		"@gajae-code/natives": "0.13.0",
+		"@gajae-code/utils": "0.13.0",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/components/editor.ts

@@ -490,6 +490,7 @@ export class Editor implements Component, Focusable {
 	onSubmit?: (text: string) => void;
 	onAltEnter?: (text: string) => void;
 	onChange?: (text: string) => void;
+	onUndo?: (text: string) => void;
 	onAutocompleteCancel?: () => void;
 	onTabDeclined?: (text: string) => void;
 	/**
@@ -1878,6 +1879,50 @@ export class Editor implements Component, Focusable {
 		this.#exitHistoryForEditing();
 		this.#insertTextAtCursor(text);
 	}
+	/**
+	 * Delete an exact text run immediately before the cursor as one edit.
+	 * Returns false without changing the document when the text is not present.
+	 */
+	deleteTextBeforeCursor(text: string): boolean {
+		if (text.length === 0 || this.#state.cursorCol < text.length) return false;
+
+		const line = this.#state.lines[this.#state.cursorLine] || "";
+		const startCol = this.#state.cursorCol - text.length;
+		if (line.slice(startCol, this.#state.cursorCol) !== text) return false;
+
+		this.#exitHistoryForEditing();
+		this.#resetKillSequence();
+		this.#recordUndoState();
+		this.#state.lines[this.#state.cursorLine] = line.slice(0, startCol) + line.slice(this.#state.cursorCol);
+		this.#setCursorCol(startCol);
+		this.#notifyBackwardDelete();
+		return true;
+	}
+	/**
+	 * Delete a same-line text range containing the cursor as one edit.
+	 * Returns false without changing the document when the range is invalid.
+	 */
+	deleteTextRangeAroundCursor(startCol: number, endCol: number): boolean {
+		const line = this.#state.lines[this.#state.cursorLine] || "";
+		if (
+			!Number.isInteger(startCol) ||
+			!Number.isInteger(endCol) ||
+			startCol < 0 ||
+			startCol >= endCol ||
+			endCol > line.length ||
+			startCol > this.#state.cursorCol ||
+			endCol < this.#state.cursorCol
+		)
+			return false;
+
+		this.#exitHistoryForEditing();
+		this.#resetKillSequence();
+		this.#recordUndoState();
+		this.#state.lines[this.#state.cursorLine] = line.slice(0, startCol) + line.slice(endCol);
+		this.#setCursorCol(startCol);
+		this.#notifyBackwardDelete();
+		return true;
+	}
 
 	// All the editor methods from before...
 	#insertCharacter(char: string): void {
@@ -2130,6 +2175,10 @@ export class Editor implements Component, Focusable {
 			this.#setCursorCol(previousLine.length);
 		}
 
+		this.#notifyBackwardDelete();
+	}
+
+	#notifyBackwardDelete(): void {
 		if (this.onChange) {
 			this.onChange(this.getText());
 		}
@@ -2290,6 +2339,7 @@ export class Editor implements Component, Focusable {
 		this.#preferredVisualCol = null;
 		Object.assign(this.#state, snapshot);
 		this.#bumpDocumentVersion();
+		this.onUndo?.(this.getText());
 
 		if (this.onChange) {
 			this.onChange(this.getText());

package/src/keys.ts

@@ -263,12 +263,22 @@ const BASE_KEYS = new Set<string>([
 	"f12",
 ]);
 
-const KEY_MODIFIERS: readonly KeyModifier[] = ["ctrl", "alt", "shift", "super"];
+const KEY_MODIFIER_ALIASES: Readonly<Partial<Record<string, KeyModifier>>> = {
+	ctrl: "ctrl",
+	alt: "alt",
+	shift: "shift",
+	super: "super",
+	option: "alt",
+	meta: "alt",
+	cmd: "super",
+	command: "super",
+};
 
 /**
  * Parse a case-insensitive key identifier into normalized dispatch parts.
  * The legacy `plus` base-key alias normalizes to `+`; the trailing `+` in
  * values such as `ctrl++` is the literal plus base.
+ * Modifier aliases `option`/`meta` and `command`/`cmd` normalize to `alt` and `super`.
  */
 export function parseKeyId(value: string): ParsedKeyId | undefined {
 	if (hasControlChars(value) || value.length === 0) return undefined;
@@ -289,10 +299,12 @@ export function parseKeyId(value: string): ParsedKeyId | undefined {
 					.slice(0, -1)
 					.split("+")
 					.map(part => part.trim());
-	if (modifierParts.some(part => !KEY_MODIFIERS.includes(part as KeyModifier))) return undefined;
-
-	const modifiers = modifierParts as KeyModifier[];
-	if (new Set(modifiers).size !== modifiers.length) return undefined;
+	const modifiers: KeyModifier[] = [];
+	for (const part of modifierParts) {
+		const modifier = KEY_MODIFIER_ALIASES[part];
+		if (!modifier || modifiers.includes(modifier)) return undefined;
+		modifiers.push(modifier);
+	}
 
 	const canonicalBase = baseKey === "pageup" ? "pageUp" : baseKey === "pagedown" ? "pageDown" : baseKey;
 	return {
@@ -314,10 +326,7 @@ export function isKeyId(value: string): value is KeyId {
  * is literally `"enter"`); the value of `Key` over a bag of magic strings is
  * that each property is typed to the exact `KeyId` literal it produces and the
  * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
- * is `"ctrl+c"`, not just `string`). This mirrors the upstream
- * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
- * scope alias (`@mariozechner`, `@earendil-works`, `@gajae-code`) keep working
- * once the specifier shim remaps them to this package.
+ * The canonical modifier helpers mirror the upstream `@mariozechner/pi-tui` `Key` export so plugins built against any scope alias (`@mariozechner`, `@earendil-works`, `@gajae-code`) keep working once the specifier shim remaps them to this package. The additional `option`/`command` helpers normalize macOS naming to the portable `alt`/`super` identifiers.
  */
 export const Key = {
 	escape: "escape",
@@ -384,7 +393,10 @@ export const Key = {
 	ctrl: <K extends BaseKey>(key: K) => `ctrl+${key}` as const,
 	shift: <K extends BaseKey>(key: K) => `shift+${key}` as const,
 	alt: <K extends BaseKey>(key: K) => `alt+${key}` as const,
+	option: <K extends BaseKey>(key: K) => `alt+${key}` as const,
 	super: <K extends BaseKey>(key: K) => `super+${key}` as const,
+	cmd: <K extends BaseKey>(key: K) => `super+${key}` as const,
+	command: <K extends BaseKey>(key: K) => `super+${key}` as const,
 	ctrlShift: <K extends BaseKey>(key: K) => `ctrl+shift+${key}` as const,
 	shiftCtrl: <K extends BaseKey>(key: K) => `shift+ctrl+${key}` as const,
 	ctrlAlt: <K extends BaseKey>(key: K) => `ctrl+alt+${key}` as const,

package/src/stdin-buffer.ts

@@ -114,6 +114,14 @@ function isCompleteSequence(data: string): "complete" | "incomplete" | "not-esca
 	}
 
 	const afterEsc = data.slice(1);
+	// macOS Terminal.app with "Use Option as Meta key" applies to both
+	// physical Option keys and wraps an escape sequence with a second ESC
+	// (for example Option+Up: ESC ESC [ A).
+	// Delegate completeness to the inner sequence so the pair is emitted
+	// atomically instead of being split into ESC ESC and the CSI suffix.
+	if (afterEsc.startsWith(ESC)) {
+		return isCompleteSequence(afterEsc);
+	}
 
 	// CSI sequences: ESC [
 	if (afterEsc.startsWith("[")) {