@linxiraos/pi-tui 1.0.0

package/src/fuzzy.ts

@@ -0,0 +1,384 @@
+/**
+ * Fuzzy matching utilities.
+ *
+ * Matching is deliberately word-local for normal words. This keeps a query like
+ * "image provider" from matching a long setting description only because the
+ * letters i-m-a-g-e appear somewhere in order across unrelated words.
+ *
+ * Lower score = better match.
+ */
+
+export interface FuzzyMatch {
+	matches: boolean;
+	score: number;
+}
+
+export interface FuzzyFilterResult<T> {
+	item: T;
+	score: number;
+}
+
+interface CharacterMatch {
+	matches: boolean;
+	score: number;
+	span: number;
+}
+
+interface SearchWord {
+	text: string;
+	index: number;
+	ordinal: number;
+}
+
+interface SearchIndex {
+	normalized: string;
+	compact: string;
+	/** Start offsets of each word within `compact` (cumulative word lengths). */
+	compactWordStarts: Set<number>;
+	words: SearchWord[];
+}
+
+const ALPHANUMERIC_SWAP_PENALTY = 5;
+const COMPACT_PHRASE_BONUS = 1200;
+const PHRASE_BONUS = 1000;
+
+function normalizeForSearch(value: string): string {
+	return value
+		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.toLowerCase()
+		.replace(/[^\p{Letter}\p{Mark}\p{Number}]+/gu, " ")
+		.trim()
+		.replace(/\s+/g, " ");
+}
+
+// Module-level memo of the per-text search index. `buildSearchIndex` is a pure
+// function of `text`, but selectors call it once per candidate per keystroke —
+// the same stable candidate list is re-filtered as the user types. Caching the
+// index across keystrokes eliminates the redundant normalize + word-split + Set
+// build on every character. Consumers only read the result, so sharing is safe.
+//
+// Admission is conservative so the cache helps the repeated-filter hot path
+// without paying for one-off text: only short texts are cached (long inputs —
+// pasted prompts, transcripts searched via the message selector — would bloat
+// memory), and admission stops at the cap instead of evicting, so a stream of
+// unique texts (message/session search) can't churn the map.
+const INDEX_CACHE_MAX = 4096;
+const MAX_CACHED_TEXT_LEN = 4096;
+const indexCache = new Map<string, SearchIndex>();
+
+function buildSearchIndex(text: string): SearchIndex {
+	// Long inputs (pasted prompts, transcripts) are never cached; bypass the Map
+	// entirely so they don't pay a hash lookup on every search.
+	if (text.length > MAX_CACHED_TEXT_LEN) return buildUncachedSearchIndex(text);
+
+	const cached = indexCache.get(text);
+	if (cached !== undefined) return cached;
+
+	const result = buildUncachedSearchIndex(text);
+	if (indexCache.size < INDEX_CACHE_MAX) {
+		indexCache.set(text, result);
+	}
+	return result;
+}
+
+function buildUncachedSearchIndex(text: string): SearchIndex {
+	const normalized = normalizeForSearch(text);
+	if (normalized.length === 0) {
+		return { normalized, compact: "", compactWordStarts: new Set(), words: [] };
+	}
+
+	const words: SearchWord[] = [];
+	const compactWordStarts = new Set<number>();
+	let index = 0;
+	let compactIndex = 0;
+	let ordinal = 0;
+	for (const word of normalized.split(" ")) {
+		words.push({ text: word, index, ordinal });
+		compactWordStarts.add(compactIndex);
+		index += word.length + 1;
+		compactIndex += word.length;
+		ordinal++;
+	}
+
+	return { normalized, compact: normalized.replaceAll(" ", ""), compactWordStarts, words };
+}
+
+function scoreCharacters(queryLower: string, textLower: string): CharacterMatch {
+	if (queryLower.length === 0) {
+		return { matches: true, score: 0, span: 0 };
+	}
+
+	if (queryLower.length > textLower.length) {
+		return { matches: false, score: 0, span: 0 };
+	}
+
+	let queryIndex = 0;
+	let score = 0;
+	let firstMatchIndex = -1;
+	let lastMatchIndex = -1;
+	let consecutiveMatches = 0;
+
+	for (let i = 0; i < textLower.length && queryIndex < queryLower.length; i++) {
+		if (textLower[i] === queryLower[queryIndex]) {
+			if (firstMatchIndex < 0) firstMatchIndex = i;
+
+			if (lastMatchIndex === i - 1) {
+				consecutiveMatches++;
+				score -= consecutiveMatches * 5;
+			} else {
+				consecutiveMatches = 0;
+				if (lastMatchIndex >= 0) {
+					score += (i - lastMatchIndex - 1) * 2;
+				}
+			}
+
+			score += i * 0.1;
+			lastMatchIndex = i;
+			queryIndex++;
+		}
+	}
+
+	if (queryIndex < queryLower.length) {
+		return { matches: false, score: 0, span: 0 };
+	}
+
+	return { matches: true, score, span: lastMatchIndex - firstMatchIndex + 1 };
+}
+
+function buildAlphanumericSwapQueries(queryLower: string): string[] {
+	const variants = new Set<string>();
+	for (let i = 0; i < queryLower.length - 1; i++) {
+		const current = queryLower[i];
+		const next = queryLower[i + 1];
+		const isAlphaNumSwap =
+			(current && /[a-z]/.test(current) && next && /\d/.test(next)) ||
+			(current && /\d/.test(current) && next && /[a-z]/.test(next));
+		if (!isAlphaNumSwap) continue;
+		const swapped = queryLower.slice(0, i) + next + current + queryLower.slice(i + 2);
+		variants.add(swapped);
+	}
+	return [...variants];
+}
+
+function withPosition(score: number, index: number): number {
+	return score + index * 0.01;
+}
+
+function isWordBoundaryPhrase(normalized: string, index: number, length: number): boolean {
+	const before = index === 0 || normalized[index - 1] === " ";
+	const afterIndex = index + length;
+	const after = afterIndex === normalized.length || normalized[afterIndex] === " ";
+	return before && after;
+}
+
+function scoreTokenAgainstWord(token: string, word: SearchWord): FuzzyMatch | null {
+	if (word.text === token) {
+		return { matches: true, score: withPosition(-200, word.index) };
+	}
+
+	if (word.text.startsWith(token)) {
+		return { matches: true, score: withPosition(-170 + (word.text.length - token.length) * 0.5, word.index) };
+	}
+
+	if (token.startsWith(word.text) && token.length - word.text.length <= 2) {
+		return { matches: true, score: withPosition(-150 + token.length - word.text.length, word.index) };
+	}
+
+	const substringIndex = word.text.indexOf(token);
+	if (substringIndex >= 0) {
+		return { matches: true, score: withPosition(-20 + substringIndex, word.index) };
+	}
+
+	const characterMatch = scoreCharacters(token, word.text);
+	if (!characterMatch.matches) return null;
+
+	const maxSpan = Math.max(token.length + 2, Math.ceil(token.length * 1.8));
+	if (characterMatch.span > maxSpan) return null;
+
+	return { matches: true, score: withPosition(-40 + characterMatch.score, word.index) };
+}
+
+function scoreAcronym(token: string, index: SearchIndex): FuzzyMatch | null {
+	if (token.length < 2 || token.length > 4 || index.words.length === 0) return null;
+
+	let queryIndex = 0;
+	let firstOrdinal = -1;
+	let lastOrdinal = -1;
+	let firstTextIndex = 0;
+
+	for (const word of index.words) {
+		if (word.text[0] !== token[queryIndex]) continue;
+		if (firstOrdinal < 0) {
+			firstOrdinal = word.ordinal;
+			firstTextIndex = word.index;
+		}
+		lastOrdinal = word.ordinal;
+		queryIndex++;
+		if (queryIndex === token.length) break;
+	}
+
+	if (queryIndex < token.length || firstOrdinal < 0 || lastOrdinal < 0) return null;
+
+	const wordSpan = lastOrdinal - firstOrdinal + 1;
+	if (wordSpan > token.length + 2) return null;
+
+	return { matches: true, score: withPosition(-30 + wordSpan * 4 - token.length * 2, firstTextIndex) };
+}
+
+function scoreTokenDirect(token: string, index: SearchIndex): FuzzyMatch {
+	if (token.length === 0) return { matches: true, score: 0 };
+
+	let best: FuzzyMatch | null = null;
+	const compactIndex = index.compact.indexOf(token);
+	if (compactIndex >= 0 && index.compactWordStarts.has(compactIndex)) {
+		best = { matches: true, score: withPosition(-140, compactIndex) };
+	}
+
+	for (const word of index.words) {
+		const match = scoreTokenAgainstWord(token, word);
+		if (match && (!best || match.score < best.score)) {
+			best = match;
+		}
+	}
+
+	const acronym = scoreAcronym(token, index);
+	if (acronym && (!best || acronym.score < best.score)) {
+		best = acronym;
+	}
+
+	return best ?? { matches: false, score: 0 };
+}
+
+function scoreToken(token: string, index: SearchIndex): FuzzyMatch {
+	let best = scoreTokenDirect(token, index);
+	if (best.matches) return best;
+
+	for (const variant of buildAlphanumericSwapQueries(token)) {
+		const match = scoreTokenDirect(variant, index);
+		if (!match.matches) continue;
+		const score = match.score + ALPHANUMERIC_SWAP_PENALTY;
+		if (!best.matches || score < best.score) {
+			best = { matches: true, score };
+		}
+	}
+
+	return best;
+}
+
+/** A query normalized and split once, so `fuzzyRank` doesn't re-normalize the
+ * same query for every candidate in the list. */
+interface PreparedQuery {
+	normalized: string;
+	tokens: string[];
+	compact: string;
+}
+
+function prepareQuery(query: string): PreparedQuery | null {
+	const normalized = normalizeForSearch(query);
+	if (normalized.length === 0) return null;
+	return { normalized, tokens: normalized.split(" "), compact: normalized.replaceAll(" ", "") };
+}
+
+function fuzzyMatchCore(pq: PreparedQuery | null, index: SearchIndex): FuzzyMatch {
+	if (pq === null) {
+		return { matches: true, score: 0 };
+	}
+
+	if (index.words.length === 0) {
+		return { matches: false, score: 0 };
+	}
+
+	let totalScore = 0;
+	const phraseIndex = index.normalized.indexOf(pq.normalized);
+	if (phraseIndex >= 0 && isWordBoundaryPhrase(index.normalized, phraseIndex, pq.normalized.length)) {
+		totalScore -= PHRASE_BONUS;
+		totalScore += phraseIndex * 0.01;
+	}
+
+	const compactPhraseIndex = index.compact.indexOf(pq.compact);
+	if (compactPhraseIndex >= 0 && index.compactWordStarts.has(compactPhraseIndex)) {
+		totalScore -= COMPACT_PHRASE_BONUS;
+		totalScore += compactPhraseIndex * 0.01;
+	}
+
+	for (const token of pq.tokens) {
+		const match = scoreToken(token, index);
+		if (!match.matches) {
+			return { matches: false, score: 0 };
+		}
+		totalScore += match.score;
+	}
+
+	return { matches: true, score: totalScore };
+}
+
+export function fuzzyMatch(query: string, text: string): FuzzyMatch {
+	const pq = prepareQuery(query);
+	if (pq === null) return { matches: true, score: 0 };
+	return fuzzyMatchCore(pq, buildSearchIndex(text));
+}
+
+/**
+ * A text prepared once for repeated fuzzy matching.
+ *
+ * `fuzzyMatch` builds a search index per call; the module cache only admits
+ * texts up to {@link MAX_CACHED_TEXT_LEN}, so long corpora (session or
+ * transcript search) rebuild the index on every keystroke — the dominant cost
+ * when a selector re-filters a stable candidate list as the user types. Build
+ * one `FuzzyText` per candidate and call {@link match} per query instead; the
+ * index lives exactly as long as the caller's reference.
+ */
+export class FuzzyText {
+	readonly #index: SearchIndex;
+
+	constructor(text: string) {
+		this.#index = buildUncachedSearchIndex(text);
+	}
+
+	/** Match `query` (space-separated tokens; all must match) against the prepared text. */
+	match(query: string): FuzzyMatch {
+		return fuzzyMatchCore(prepareQuery(query), this.#index);
+	}
+}
+
+/**
+ * Filter and sort items by fuzzy match quality (best matches first).
+ * Supports space-separated tokens: all tokens must match.
+ */
+export function fuzzyRank<T>(items: T[], query: string, getText: (item: T) => string): FuzzyFilterResult<T>[] {
+	if (!query.trim()) {
+		return items.map(item => ({ item, score: 0 }));
+	}
+
+	// A non-blank query that normalizes to empty (pure punctuation) matches
+	// everything with score 0, but still calls getText per item — consumers rely
+	// on its side effects (see fuzzy-cache.test.ts).
+	const pq = prepareQuery(query);
+	const results: FuzzyFilterResult<T>[] = [];
+	for (const item of items) {
+		const text = getText(item);
+		const match = pq === null ? { matches: true, score: 0 } : fuzzyMatchCore(pq, buildSearchIndex(text));
+		if (match.matches) {
+			results.push({ item, score: match.score });
+		}
+	}
+
+	results.sort((a, b) => a.score - b.score);
+	return results;
+}
+
+export function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[] {
+	return fuzzyRank(items, query, getText).map(result => result.item);
+}
+
+/**
+ * Clear the fuzzy search-index cache. Intended for tests/benchmarks so a fresh
+ * cold-start typing session can be measured on demand; not part of the supported
+ * TUI API.
+ *
+ * @internal
+ */
+export function resetFuzzyIndexCache(): void {
+	indexCache.clear();
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// Core TUI interfaces and classes
+
+// Autocomplete support
+export * from "./autocomplete";
+// Components
+export * from "./components/box";
+export * from "./components/cancellable-loader";
+export * from "./components/editor";
+export * from "./components/image";
+export * from "./components/input";
+export * from "./components/loader";
+export * from "./components/markdown";
+export * from "./components/scroll-view";
+export * from "./components/select-list";
+export * from "./components/settings-list";
+export * from "./components/spacer";
+export * from "./components/tab-bar";
+export * from "./components/text";
+export * from "./components/truncated-text";
+// DECCARA rectangular-SGR background-fill optimizer
+export * from "./deccara";
+// Desktop notifications via D-Bus (Linux freedesktop notifications)
+export * from "./desktop-notify";
+// Editor component interface (for custom editors)
+export type * from "./editor-component";
+// Fuzzy matching
+export * from "./fuzzy";
+// Keybindings
+export * from "./keybindings";
+// Kitty keyboard protocol helpers
+export * from "./keys";
+// Kitty graphics: Unicode placeholders
+export * from "./kitty-graphics";
+// LaTeX → Unicode/ANSI math rendering
+export * from "./latex-block";
+export * from "./latex-to-unicode";
+// SGR mouse report parsing
+export * from "./mouse";
+// Mermaid diagram support
+// Input buffering for batch splitting
+export * from "./stdin-buffer";
+export type * from "./symbols";
+// Terminal interface and implementations
+export * from "./terminal";
+// Terminal image support
+export * from "./terminal-capabilities";
+// TTY ID
+export * from "./ttyid";
+export * from "./tui";
+// Utilities
+export * from "./utils";