@sayknow-cli/tui 0.3.16 → 0.4.0

package/README.md

@@ -328,6 +328,8 @@ interface SelectItem {
 	value: string;
 	label: string;
 	description?: string;
+	hint?: string; // Autocomplete hint consumed by Editor; SelectList does not render it
+	disabled?: boolean; // Dimmed, unselectable entry (see "Disabled items")
 }
 
 interface SelectListTheme {
@@ -352,14 +354,29 @@ list.onSelect = (item) => console.log("Selected:", item);
 list.onCancel = () => console.log("Cancelled");
 list.onSelectionChange = (item) => console.log("Highlighted:", item);
 list.setFilter("opt"); // Filter items
+list.setSelectedIndex(1); // Select first enabled item at/after index 1, then search backward
 ```
 
 **Controls:**
 
-- Arrow keys: Navigate
+- Arrow keys: Navigate and wrap at list edges
+- PageUp/PageDown: Move by a visible page and clamp at list boundaries
 - Enter: Select
 - Escape: Cancel
 
+**Disabled items:**
+
+Items with `disabled: true` stay visible but can never be selected:
+
+- They render dimmed (via `theme.description`) and never show the selection cursor.
+- Arrow keys wrap while skipping disabled entries; PageUp/PageDown skip disabled targets and clamp at list boundaries.
+- Filtering (`setFilter`) resets the selection to the first *enabled* item.
+- `setSelectedIndex(i)` selects the first enabled item at or after the clamped index, falling back backward.
+- `onSelect` and `onSelectionChange` never receive a disabled item.
+- When every visible item is disabled, `getSelectedItem()` returns `null` and no
+  row shows a cursor. Arrow keys wrap the viewport, PageUp/PageDown clamp it,
+  and the scroll indicator reports `(-/N)` without claiming a selected row.
+
 ### SettingsList
 
 Settings panel with value cycling and submenus.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.16",
+	"version": "0.4.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -27,7 +27,7 @@
 		"cli"
 	],
 	"main": "./src/index.ts",
-	"types": "./dist/types/index.d.ts",
+	"types": "./src/index.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
@@ -53,20 +53,19 @@
 	"files": [
 		"src",
 		"README.md",
-		"CHANGELOG.md",
-		"dist/types"
+		"CHANGELOG.md"
 	],
 	"exports": {
 		".": {
-			"types": "./dist/types/index.d.ts",
+			"types": "./src/index.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./dist/types/*.d.ts",
+			"types": "./src/*.ts",
 			"import": "./src/*.ts"
 		},
 		"./components/*": {
-			"types": "./dist/types/components/*.d.ts",
+			"types": "./src/components/*.ts",
 			"import": "./src/components/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/autocomplete.ts

@@ -190,10 +190,38 @@ function normalizeSlashCommandText(value: string): string {
 		.replace(/\s+/g, " ");
 }
 const NON_COMMAND_SLASH_PREFIX_PRECEDERS = new Set(["/", "\\", ":", ".", "~"]);
+function findOpenInlineCodeSpanStart(text: string): number | null {
+	let openDelimiter: number | null = null;
+
+	for (let i = 0; i < text.length; ) {
+		if (text[i] !== "`") {
+			i += 1;
+			continue;
+		}
+
+		let runEnd = i + 1;
+		while (text[runEnd] === "`") runEnd += 1;
+		if (runEnd - i !== 1) {
+			i = runEnd;
+			continue;
+		}
+
+		let backslashCount = 0;
+		for (let j = i - 1; j >= 0 && text[j] === "\\"; j -= 1) backslashCount += 1;
+		if (backslashCount % 2 === 0) openDelimiter = openDelimiter === null ? i : null;
+		i = runEnd;
+	}
+
+	return openDelimiter;
+}
+export function isInsideInlineCodeSpan(text: string): boolean {
+	return findOpenInlineCodeSpanStart(text) !== null;
+}
 
 export function extractSlashCommandTokenPrefix(text: string): string | null {
 	const slashIndex = text.lastIndexOf("/");
 	if (slashIndex === -1) return null;
+	if (isInsideInlineCodeSpan(text.slice(0, slashIndex + 1))) return null;
 
 	const token = text.slice(slashIndex);
 	if (/[\s]/.test(token)) return null;
@@ -556,7 +584,9 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		}
 
 		const lastDelimiterIndex = findLastDelimiter(text);
-		const pathPrefix = lastDelimiterIndex === -1 ? text : text.slice(lastDelimiterIndex + 1);
+		const inlineCodeStart = findOpenInlineCodeSpanStart(text);
+		const prefixStart = Math.max(lastDelimiterIndex, inlineCodeStart ?? -1);
+		const pathPrefix = prefixStart === -1 ? text : text.slice(prefixStart + 1);
 
 		// For forced extraction (Tab key), always return something
 		if (forceExtract) {

package/src/bracketed-paste.ts

@@ -1,47 +1,124 @@
 const PASTE_START = "\x1b[200~";
 const PASTE_END = "\x1b[201~";
 
-export type PasteResult = { handled: false } | { handled: true; pasteContent?: string; remaining: string };
+export const BRACKETED_PASTE_FRAME_TIMEOUT_MS = 1_000;
+export const BRACKETED_PASTE_FRAME_MAX_BYTES = 1024 * 1024;
+
+export type PasteResult =
+	| { handled: false }
+	| { handled: true; leading: string; pasteContent?: string; remaining: string };
+
+function partialStartSuffixLength(value: string): number {
+	const maxLength = Math.min(value.length, PASTE_START.length - 1);
+	for (let length = maxLength; length > 0; length -= 1) {
+		if (value.endsWith(PASTE_START.slice(0, length))) return length;
+	}
+	return 0;
+}
 
 /**
- * Handles bracketed paste mode buffering for terminal input components.
- *
- * Bracketed paste mode wraps pasted content between start (\x1b[200~) and
- * end (\x1b[201~) markers, which may arrive split across multiple chunks.
- * This class buffers incoming data and assembles complete paste payloads.
+ * Handles bracketed paste framing with bounded buffering. Leading ordinary
+ * input and split markers are retained byte-for-byte; stale or oversized
+ * incomplete frames are released as ordinary input on the next event.
  */
 export class BracketedPasteHandler {
 	#buffer = "";
+	#leading = "";
 	#active = false;
+	#pendingSince: number | undefined;
 
-	/**
-	 * Process incoming terminal data for bracketed paste sequences.
-	 *
-	 * @returns `{ handled: false }` if the data contains no paste sequence and
-	 *          should be processed normally. `{ handled: true }` if the data was
-	 *          consumed by paste buffering — `pasteContent` is set when a complete
-	 *          paste has been assembled; omitted when still buffering.
-	 */
-	process(data: string): PasteResult {
-		if (data.includes(PASTE_START)) {
-			this.#active = true;
-			this.#buffer = "";
-			data = data.replace(PASTE_START, "");
-		}
+	get hasPendingFrame(): boolean {
+		return this.#active || this.#buffer.length > 0 || this.#leading.length > 0;
+	}
 
-		if (!this.#active) return { handled: false };
+	#reset(): void {
+		this.#buffer = "";
+		this.#leading = "";
+		this.#active = false;
+		this.#pendingSince = undefined;
+	}
 
-		this.#buffer += data;
+	#flushBuffered(): string {
+		const buffered = this.#active
+			? `${this.#leading}${PASTE_START}${this.#buffer}`
+			: `${this.#leading}${this.#buffer}`;
+		this.#reset();
+		return buffered;
+	}
 
-		const endIndex = this.#buffer.indexOf(PASTE_END);
-		if (endIndex === -1) return { handled: true, remaining: "" };
+	#flushActive(remaining: string): PasteResult {
+		const leading = this.#leading;
+		const pasteContent = this.#buffer;
+		this.#reset();
+		return { handled: true, leading, pasteContent, remaining };
+	}
 
-		const pasteContent = this.#buffer.substring(0, endIndex);
-		const remaining = this.#buffer.substring(endIndex + PASTE_END.length);
+	process(data: string, now = Date.now()): PasteResult {
+		if (
+			this.hasPendingFrame &&
+			this.#pendingSince !== undefined &&
+			now - this.#pendingSince >= BRACKETED_PASTE_FRAME_TIMEOUT_MS
+		) {
+			return this.#active
+				? this.#flushActive(data)
+				: { handled: true, leading: `${this.#flushBuffered()}${data}`, remaining: "" };
+		}
+		if (this.hasPendingFrame && data === "\x1b") {
+			return this.#active
+				? this.#flushActive(data)
+				: { handled: true, leading: `${this.#flushBuffered()}${data}`, remaining: "" };
+		}
 
-		this.#buffer = "";
-		this.#active = false;
+		if (!this.#active) {
+			const hadBufferedInput = this.hasPendingFrame;
+			const combined = this.#buffer + data;
+			this.#buffer = "";
+			const startIndex = combined.indexOf(PASTE_START);
+			if (startIndex === -1) {
+				const partialLength = partialStartSuffixLength(combined);
+				if (partialLength > 0) {
+					const nextLeading = this.#leading + combined.slice(0, -partialLength);
+					const nextBuffer = combined.slice(-partialLength);
+					if (Buffer.byteLength(nextLeading) + Buffer.byteLength(nextBuffer) > BRACKETED_PASTE_FRAME_MAX_BYTES) {
+						this.#reset();
+						return { handled: true, leading: `${nextLeading}${nextBuffer}`, remaining: "" };
+					}
+					this.#leading = nextLeading;
+					this.#buffer = nextBuffer;
+					this.#pendingSince ??= now;
+					return { handled: true, leading: "", remaining: "" };
+				}
+				if (hadBufferedInput || this.#leading.length > 0) {
+					const leading = this.#leading + combined;
+					this.#reset();
+					return { handled: true, leading, remaining: "" };
+				}
+				return { handled: false };
+			}
+
+			this.#leading += combined.slice(0, startIndex);
+			this.#buffer = combined.slice(startIndex + PASTE_START.length);
+			this.#active = true;
+			this.#pendingSince ??= now;
+		} else {
+			this.#buffer += data;
+		}
+
+		const endIndex = this.#buffer.indexOf(PASTE_END);
+		if (endIndex === -1) {
+			if (
+				Buffer.byteLength(this.#leading) + Buffer.byteLength(PASTE_START) + Buffer.byteLength(this.#buffer) >
+				BRACKETED_PASTE_FRAME_MAX_BYTES
+			) {
+				return this.#flushActive("");
+			}
+			return { handled: true, leading: "", remaining: "" };
+		}
 
-		return { handled: true, pasteContent, remaining };
+		const leading = this.#leading;
+		const pasteContent = this.#buffer.slice(0, endIndex);
+		const remaining = this.#buffer.slice(endIndex + PASTE_END.length);
+		this.#reset();
+		return { handled: true, leading, pasteContent, remaining };
 	}
 }

package/src/components/editor.ts

@@ -3,6 +3,7 @@ import {
 	type AutocompleteProvider,
 	type CombinedAutocompleteProvider,
 	extractSlashCommandTokenPrefix,
+	isInsideInlineCodeSpan,
 } from "../autocomplete";
 import { BracketedPasteHandler } from "../bracketed-paste";
 import { getKeybindings, type KeybindingsManager } from "../keybindings";
@@ -459,6 +460,7 @@ export class Editor implements Component, Focusable {
 	#autocompleteState: "regular" | "force" | null = null;
 	#autocompletePrefix: string = "";
 	#autocompleteRequestId: number = 0;
+	#autocompleteOrigin?: { docVersion: number; cursorLine: number; cursorCol: number };
 	#autocompleteMaxVisible: number = 5;
 	onAutocompleteUpdate?: () => void;
 
@@ -1144,8 +1146,12 @@ export class Editor implements Component, Focusable {
 		}
 
 		// Handle bracketed paste mode
-		const paste = this.#pasteHandler.process(data);
+		const paste =
+			data === "\x1b" && !this.#pasteHandler.hasPendingFrame
+				? ({ handled: false } as const)
+				: this.#pasteHandler.process(data);
 		if (paste.handled) {
+			if (paste.leading.length > 0) this.handleInput(paste.leading);
 			if (paste.pasteContent !== undefined) {
 				this.#handlePaste(paste.pasteContent);
 				if (paste.remaining.length > 0) {
@@ -1205,6 +1211,11 @@ export class Editor implements Component, Focusable {
 
 				// If Tab was pressed, always apply the selection
 				if (kb.matches(data, "tui.input.tab")) {
+					if (!this.#isAutocompleteSelectionCurrent()) {
+						this.#cancelAutocomplete();
+						this.#handleTabCompletion();
+						return;
+					}
 					const selected = this.#autocompleteList.getSelectedItem();
 					if (selected && this.#autocompleteProvider) {
 						const shouldChainSlashCommandAutocomplete = this.#isSlashCommandNameAutocompleteSelection();
@@ -1238,36 +1249,38 @@ export class Editor implements Component, Focusable {
 				}
 
 				// If Enter was pressed on a slash command, apply completion and submit
-				if ((kb.matches(data, "tui.input.submit") || data === "\n") && this.#autocompletePrefix.startsWith("/")) {
-					// Check for stale autocomplete state due to debounce
-					const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
-					const currentTextBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					if (!currentTextBeforeCursor.endsWith(this.#autocompletePrefix)) {
-						// Autocomplete is stale - cancel and fall through to normal submission
+				if (
+					(kb.matches(data, "tui.input.submit") || data === "\n") &&
+					this.#autocompleteState === "regular" &&
+					this.#autocompletePrefix.startsWith("/")
+				) {
+					const selected = this.#autocompleteList.getSelectedItem();
+					if (!this.#isAutocompleteSelectionCurrent()) {
 						this.#cancelAutocomplete();
-					} else {
-						const selected = this.#autocompleteList.getSelectedItem();
-						if (selected && this.#autocompleteProvider) {
-							const result = this.#autocompleteProvider.applyCompletion(
-								this.#state.lines,
-								this.#state.cursorLine,
-								this.#state.cursorCol,
-								selected,
-								this.#autocompletePrefix,
-							);
+					} else if (selected && this.#autocompleteProvider) {
+						const result = this.#autocompleteProvider.applyCompletion(
+							this.#state.lines,
+							this.#state.cursorLine,
+							this.#state.cursorCol,
+							selected,
+							this.#autocompletePrefix,
+						);
 
-							this.#state.lines = result.lines;
-							this.#bumpDocumentVersion();
-							this.#state.cursorLine = result.cursorLine;
-							this.#setCursorCol(result.cursorCol);
-							result.onApplied?.();
-						}
+						this.#state.lines = result.lines;
+						this.#bumpDocumentVersion();
+						this.#state.cursorLine = result.cursorLine;
+						this.#setCursorCol(result.cursorCol);
+						result.onApplied?.();
 						this.#cancelAutocomplete();
 					}
 					// Don't return - fall through to submission logic
 				}
 				// If Enter was pressed on a file path, apply completion
 				else if (kb.matches(data, "tui.input.submit") || data === "\n") {
+					if (!this.#isAutocompleteSelectionCurrent()) {
+						this.#cancelAutocomplete();
+						return;
+					}
 					const selected = this.#autocompleteList.getSelectedItem();
 					if (selected && this.#autocompleteProvider) {
 						const result = this.#autocompleteProvider.applyCompletion(
@@ -1867,9 +1880,17 @@ export class Editor implements Component, Focusable {
 
 		// Check if we should trigger or update autocomplete
 		if (!this.#autocompleteState) {
-			// Auto-trigger for slash command tokens.
-			if (char === "/" && (this.#isAtStartOfSubmittedMessage() || this.#isInSlashTokenContext())) {
-				this.#tryTriggerAutocomplete();
+			// Auto-trigger slash commands, or path-only completion inside inline code.
+			if (char === "/") {
+				const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+				const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
+				if (this.#isInSubmittedSlashCommandContext()) {
+					this.#tryTriggerAutocomplete();
+				} else if (isInsideInlineCodeSpan(textBeforeCursor)) {
+					this.#forceFileAutocomplete();
+				} else if (this.#isInSlashTokenContext()) {
+					this.#tryTriggerAutocomplete();
+				}
 			}
 			// Auto-trigger for "@" file reference (fuzzy search)
 			else if (char === "@") {
@@ -2775,14 +2796,6 @@ export class Editor implements Component, Focusable {
 		return true;
 	}
 
-	// Slash commands execute only when the submitted prompt starts with the command.
-	#isAtStartOfSubmittedMessage(): boolean {
-		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
-		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
-
-		return this.#hasOnlyWhitespaceBeforeCursorLine() && (beforeCursor.trim() === "" || beforeCursor.trim() === "/");
-	}
-
 	#isInSubmittedSlashCommandContext(): boolean {
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
@@ -2798,6 +2811,30 @@ export class Editor implements Component, Focusable {
 	#isInSlashTokenContext(): boolean {
 		return this.#getSlashTokenBeforeCursor() !== null;
 	}
+	#isAutocompleteSelectionCurrent(): boolean {
+		if (!this.#isAutocompleteOriginCurrent()) return false;
+		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+		const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
+		if (!textBeforeCursor.endsWith(this.#autocompletePrefix)) return false;
+		if (this.#autocompleteState !== "regular" || !this.#autocompletePrefix.startsWith("/")) return true;
+		return extractSlashCommandTokenPrefix(textBeforeCursor) === this.#autocompletePrefix;
+	}
+	#captureAutocompleteOrigin(): { docVersion: number; cursorLine: number; cursorCol: number } {
+		return {
+			docVersion: this.#docVersion,
+			cursorLine: this.#state.cursorLine,
+			cursorCol: this.#state.cursorCol,
+		};
+	}
+
+	#isAutocompleteOriginCurrent(origin = this.#autocompleteOrigin): boolean {
+		return (
+			origin !== undefined &&
+			origin.docVersion === this.#docVersion &&
+			origin.cursorLine === this.#state.cursorLine &&
+			origin.cursorCol === this.#state.cursorCol
+		);
+	}
 
 	#isSlashCommandNameAutocompleteSelection(): boolean {
 		if (this.#autocompleteState !== "regular") {
@@ -2839,6 +2876,7 @@ export class Editor implements Component, Focusable {
 			}
 		}
 
+		const origin = this.#captureAutocompleteOrigin();
 		const requestId = ++this.#autocompleteRequestId;
 
 		const suggestions = await this.#autocompleteProvider.getSuggestions(
@@ -2846,12 +2884,13 @@ export class Editor implements Component, Focusable {
 			this.#state.cursorLine,
 			this.#state.cursorCol,
 		);
-		if (requestId !== this.#autocompleteRequestId) return;
+		if (requestId !== this.#autocompleteRequestId || !this.#isAutocompleteOriginCurrent(origin)) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "regular";
+			this.#autocompleteOrigin = origin;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();
@@ -2911,13 +2950,14 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			return;
 		}
 
+		const origin = this.#captureAutocompleteOrigin();
 		const requestId = ++this.#autocompleteRequestId;
 		const suggestions = await provider.getForceFileSuggestions(
 			this.#state.lines,
 			this.#state.cursorLine,
 			this.#state.cursorCol,
 		);
-		if (requestId !== this.#autocompleteRequestId) return;
+		if (requestId !== this.#autocompleteRequestId || !this.#isAutocompleteOriginCurrent(origin)) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
 			// If there's exactly one suggestion and this was an explicit Tab press, apply it immediately
@@ -2945,6 +2985,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "force";
+			this.#autocompleteOrigin = origin;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();
@@ -2959,6 +3000,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 		this.#autocompleteRequestId += 1;
 		this.#autocompleteState = null;
 		this.#autocompleteList = undefined;
+		this.#autocompleteOrigin = undefined;
 		this.#autocompletePrefix = "";
 		if (notifyCancel && wasAutocompleting) {
 			this.onAutocompleteCancel?.();
@@ -2978,6 +3020,7 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			return;
 		}
 
+		const origin = this.#captureAutocompleteOrigin();
 		const requestId = ++this.#autocompleteRequestId;
 
 		const suggestions = await this.#autocompleteProvider.getSuggestions(
@@ -2985,12 +3028,13 @@ https://github.com/EsotericSoftware/spine-runtimes/actions/runs/19536643416/job/
 			this.#state.cursorLine,
 			this.#state.cursorCol,
 		);
-		if (requestId !== this.#autocompleteRequestId) return;
+		if (requestId !== this.#autocompleteRequestId || !this.#isAutocompleteOriginCurrent(origin)) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
 			this.#autocompletePrefix = suggestions.prefix;
 			// Always create new SelectList to ensure update
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
+			this.#autocompleteOrigin = origin;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();

package/src/components/input.ts

@@ -64,8 +64,12 @@ export class Input implements Component, Focusable {
 
 	handleInput(data: string): void {
 		// Handle bracketed paste mode
-		const paste = this.#pasteHandler.process(data);
+		const paste =
+			data === "\x1b" && !this.#pasteHandler.hasPendingFrame
+				? ({ handled: false } as const)
+				: this.#pasteHandler.process(data);
 		if (paste.handled) {
+			if (paste.leading.length > 0) this.handleInput(paste.leading);
 			if (paste.pasteContent !== undefined) {
 				this.#handlePaste(paste.pasteContent);
 				if (paste.remaining.length > 0) {