@prometheus-ai/tui 0.5.4 → 0.5.8

package/dist/types/tui.d.ts

@@ -1,11 +1,12 @@
 import { ImageBudget } from "./components/image";
-import type { Terminal } from "./terminal";
+import { type Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
 type InputListenerResult = {
     consume?: boolean;
     data?: string;
 } | undefined;
 type InputListener = (data: string) => InputListenerResult;
+type StartListener = () => void;
 export interface RenderTimer {
     cancel(): void;
 }
@@ -17,16 +18,32 @@ export interface RenderScheduler {
 export interface TUIOptions {
     renderScheduler?: RenderScheduler;
 }
+export interface TUIStartOptions {
+    /** Clear saved native scrollback before the first paint. */
+    clearScrollback?: boolean;
+}
 /**
  * Component interface - all components must implement this
+ *
+ * Render contract: the returned array (and its rows) belongs to the component.
+ * Callers MUST NOT mutate it — components are allowed to return a cached array
+ * and will return the exact same reference for as long as their rendered
+ * content is unchanged. Conversely, a component MUST return a fresh array
+ * reference whenever its content changed; reference equality across two
+ * render() calls is the engine's proof that the rows are byte-identical
+ * (containers memoize their concatenation on it, and the TUI derives the
+ * frame's stable prefix from it). A component that mutates a previously
+ * returned array in place must implement {@link RenderStablePrefix} to declare
+ * which leading rows survived.
  */
 export interface Component {
     /**
-     * Render the component to lines for the given viewport width
-     * @param width - Current viewport width
-     * @returns Array of strings, each representing a line
+     * Render the component to an array of physical rows at the given width.
+     * The result is component-owned and `readonly` to the caller; an unchanged
+     * component may (and should) return the same array reference it returned
+     * last time.
      */
-    render(width: number): string[];
+    render(width: number): readonly string[];
     /**
      * Optional handler for keyboard input when component has focus
      */
@@ -37,32 +54,108 @@ export interface Component {
      */
     wantsKeyRelease?: boolean;
     /**
-     * Invalidate any cached rendering state.
+     * Optional hook to invalidate any cached rendering state.
      * Called when theme changes or when component needs to re-render from scratch.
      */
-    invalidate(): void;
+    invalidate?(): void;
+    /**
+     * Optional teardown. Called when the component is permanently removed from
+     * the live tree (e.g. a transcript reset). Release timers, intervals, and
+     * subscriptions here. Must be idempotent. Containers propagate dispose to
+     * their children; leaf components without resources may omit it.
+     */
+    dispose?(): void;
 }
 /**
- * Optional component seam for native-scrollback pinning. A component that
- * renders a stable prefix followed by a live/transient suffix reports the local
- * line index where that suffix begins after each render. TUI treats that suffix
- * — and every root child rendered below it — as not yet safe to commit to native
- * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ * Component seam for append-only native-scrollback commits. A component that
+ * renders a finalized prefix followed by a live/mutating suffix reports the
+ * local line index where that suffix begins after each render. The engine
+ * commits rows to native scrollback only up to that boundary; everything
+ * below repaints in place inside the visible window and never enters history
+ * until it finalizes.
  *
  * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
- * inside that live suffix: the line index up to which the live region is
- * append-only (its earlier rows never re-layout, only new rows append at the
- * bottom — a streaming assistant message). Rows in `[liveRegionStart,
- * commitSafeEnd)` that scroll above the viewport are safe to commit to native
- * scrollback even though they are technically live, because they will never
- * change. Without this, a single live block that alone overflows the viewport
- * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
- * live blocks (tool previews that collapse) omit it, so their mutable rows stay
- * deferred. Defaults to `liveRegionStart` when absent.
+ * inside the live suffix: the line index up to which the live region is
+ * append-only (earlier rows never re-layout — a streaming assistant message).
+ * Rows in `[liveRegionStart, commitSafeEnd)` may commit even though they are
+ * technically live, because they will never change. Without it, a single live
+ * block that alone overflows the window would hold its scrolled-off head out
+ * of history until it finalizes. Volatile live blocks (tool previews that
+ * collapse) omit it. Defaults to `liveRegionStart` when absent; a root that
+ * reports no seam at all commits everything that scrolls (shell semantics).
+ * `getNativeScrollbackSnapshotSafeEnd` optionally reports a still deeper
+ * boundary: the line index up to which the live region is *durable* — its rows
+ * may still change bytes later (a streaming markdown table re-aligning its
+ * columns every row), but their CURRENT snapshot is permanent content, so
+ * dropping them when they scroll above the window is forbidden. Unlike
+ * `commitSafeEnd` (byte-stable: offered rows are asserted never to re-layout and
+ * stay under the committed-prefix audit), rows committed under the snapshot end
+ * are audit-EXEMPT once they pass the window top — the engine appends their
+ * scroll-off snapshot and never recommits them, so later layout drift becomes a
+ * frozen stale row in history (duplication never loss) instead of either a
+ * dropped row or an audit re-anchor spray. Provisional live blocks (collapsing
+ * tool/edit previews whose head is a throwaway tail window) omit it. Defaults to
+ * `commitSafeEnd ?? liveRegionStart` when absent.
+ *
+ * When several root children report a seam in the same frame, the topmost
+ * one (and its commit-safe / snapshot-safe extension) defines the boundary:
+ * commits are prefix-only, so everything below the first seam is already
+ * excluded.
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
     getNativeScrollbackCommitSafeEnd?(): number | undefined;
+    getNativeScrollbackSnapshotSafeEnd?(): number | undefined;
+}
+export interface NativeScrollbackCommittedRows {
+    setNativeScrollbackCommittedRows(rows: number): void;
+}
+/**
+ * Opt-in stability report for components that mutate their returned render
+ * array in place across frames (instead of returning a fresh array per
+ * change). The engine reads it right after the component's `render()` returns:
+ * the report counts the leading rows of the just-returned array that are
+ * byte-identical to the array state the reader last observed. The engine uses
+ * it to reuse the composed frame's prefix — skipping marker extraction, line
+ * preparation, and the committed-prefix audit for those rows.
+ *
+ * Contract:
+ * - Reading CONSUMES the report: it re-bases the baseline to the current
+ *   array state. The accumulated count therefore covers every render since
+ *   the previous read, so out-of-band `render()` calls between engine frames
+ *   (an exporter walking the tree) can only lower the report, never inflate
+ *   it past what the engine actually has.
+ * - An implementer that cannot prove stability for a frame must lower the
+ *   accumulated count to 0 for that render.
+ * - Rows at or beyond the report may have been mutated in place; rows before
+ *   it must be the identical string values at the identical indices.
+ */
+export interface RenderStablePrefix {
+    getRenderStablePrefixRows(): number;
+}
+/**
+ * Opt-in fast path for composing only the visible tail of a tall component
+ * during a terminal resize. A drag emits a SIGWINCH burst, and the width
+ * changes on every event: a full compose re-lays-out (and, for markdown,
+ * re-lexes) the entire transcript per event — O(history) work that is
+ * discarded the instant the next event arrives. While the resize is in flight
+ * the engine paints only the viewport, so it asks each tall root child for at
+ * most `maxRows` rows from the bottom of its render at `width` and skips
+ * composing everything above the fold. The authoritative full paint replays
+ * once the drag settles (see {@link TUI} resize handling).
+ *
+ * Contract:
+ * - Returns the BOTTOM rows of the component's full render at `width`, in
+ *   top-to-bottom order, capped at `maxRows` (fewer when the component is
+ *   shorter). The rows MUST be byte-identical to the corresponding tail of
+ *   what `render(width)` would have returned, modulo a one-row separator at
+ *   the very top edge (a transient frame the settle paint overwrites).
+ * - MUST NOT mutate any persistent full-compose state: the next `render()`
+ *   (the settle paint) has to reconcile exactly as if the tail render never
+ *   happened. Warming pure per-width render caches is fine and desirable.
+ */
+export interface ViewportTailProvider {
+    renderViewportTail(width: number, maxRows: number): readonly string[];
 }
 /**
  * Interface for components that can receive focus and display a cursor.
@@ -85,22 +178,6 @@ export interface Focusable {
 export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
-    /**
-     * Bypass the unknown-Windows-viewport deferral for this render so the
-     * caller's intentional live UI mutation reaches the terminal even when
-     * `Terminal#isNativeViewportAtBottom()` cannot answer.
-     *
-     * Use only for renders driven by direct user interaction (autocomplete
-     * updates, IME, etc.). Any background/offscreen transcript change that
-     * coalesces into the same frame WILL also bypass the deferral and reach
-     * native scrollback — that is the trade-off, and the reason ordinary
-     * `requestRender()` calls must continue to omit this flag.
-     */
-    allowUnknownViewportMutation?: boolean;
-}
-/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
-export interface NativeScrollbackRefreshOptions {
-    allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
 export declare function isFocusable(component: Component | null): component is Component & Focusable;
@@ -156,6 +233,15 @@ export interface OverlayOptions {
      * Called each render cycle with current terminal dimensions.
      */
     visible?: (termWidth: number, termHeight: number) => boolean;
+    /**
+     * Borrow the terminal's alternate screen buffer for this overlay's lifetime
+     * (vim/less idiom). While the topmost visible overlay sets this, the engine
+     * paints only the modal on the alt screen and emits no ED3 / scrollback
+     * bytes, so the transcript on the normal screen stays untouched and is not
+     * scrollable behind the modal. Defaults off — all other overlays are
+     * unchanged and still draw over the transcript on the normal screen.
+     */
+    fullscreen?: boolean;
 }
 /**
  * Handle returned by showOverlay for controlling the overlay
@@ -172,13 +258,40 @@ export interface OverlayHandle {
  * Container - a component that contains other components
  */
 export declare class Container implements Component {
+    #private;
     children: Component[];
     addChild(component: Component): void;
     removeChild(component: Component): void;
     clear(): void;
     invalidate(): void;
-    render(width: number): string[];
+    /**
+     * Propagate teardown to children. Call when the container's children are
+     * being permanently discarded (not when they are detached for reuse — use
+     * {@link clear} for that). Idempotent per child via each child's own dispose.
+     */
+    dispose(): void;
+    render(width: number): readonly string[];
 }
+/**
+ * Decide whether `frame` still aligns with the committed prefix, and where to
+ * re-anchor the commit index when it does not. Returns the resync row index,
+ * or -1 when no resync is needed.
+ *
+ * The detector exploits the asymmetry between the two mutation classes: an
+ * in-place edit or restyle of committed rows disturbs only the touched rows
+ * (alignment below them is intact — the stale copy in history is the
+ * long-accepted artifact), while any insertion or deletion shifts EVERY row
+ * below it, including the rows just above the commit boundary. So the prefix
+ * *tail* is sampled (up to 8 non-blank rows within the last 24, compared
+ * SGR-stripped so theme changes stay quiet, tolerating one mismatch for a
+ * legitimate single-row edit): aligned ⇒ no resync; misaligned ⇒ resync at
+ * the first non-equivalent row, recommitting from there — duplication, never
+ * loss. Highly repetitive tails (identical filler rows) can mask a shift, in
+ * which case the skipped rows are content-identical to the committed ones —
+ * observationally harmless. Exported for the render-stress harness, whose
+ * shadow commit ledger must mirror the engine's law exactly.
+ */
+export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[], auditLimit?: number): number;
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -194,8 +307,16 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
-    render(width: number): string[];
+    render(width: number): readonly string[];
     get fullRedraws(): number;
+    /**
+     * Transient viewport-only paints emitted by the non-multiplexer resize fast
+     * path. These never touch native scrollback or the commit ledger, so they
+     * are counted apart from {@link fullRedraws}.
+     */
+    get resizeViewportPaints(): number;
+    /** Whether a non-multiplexer resize drag is currently in flight. */
+    get resizeViewportActive(): boolean;
     /** Shared budget that caps how many inline images render as live graphics. */
     get imageBudget(): ImageBudget;
     /**
@@ -206,44 +327,16 @@ export declare class TUI extends Container {
     setMaxInlineImages(cap: number): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
-    getClearOnShrink(): boolean;
-    /**
-     * Set whether to trigger full re-render when content shrinks.
-     * When true (default), empty rows are cleared when content shrinks.
-     * When false, empty rows remain (reduces redraws on slower terminals).
-     */
-    setClearOnShrink(enabled: boolean): void;
     /**
      * Whether DEC 2026 synchronized-output wrappers are currently emitted around
-     * paints. Starts from conservative terminal/env detection and is force-disabled
-     * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
+     * paints. Starts from conservative terminal/env detection and is reconciled at
+     * runtime against the terminal's DECRQM mode-2026 report — enabled on a
+     * positive report, disabled on a negative one.
      */
     get synchronizedOutput(): boolean;
-    /**
-     * When enabled, live render frames rebuild native scrollback on offscreen and
-     * structural changes even when the viewport position is unobservable (POSIX,
-     * where `isNativeViewportAtBottom()` is `undefined`), instead of deferring to a
-     * non-destructive repaint. This trades the anti-yank guarantee for a clean,
-     * duplicate-free history and is meant for windows where output above the fold
-     * is actively re-rendering — e.g. a tool whose result is still streaming and
-     * re-laying-out rows that have already scrolled into history. A terminal that
-     * reports a *known*-scrolled viewport still defers, as does native Windows
-     * (the viewport is never observable there and ConPTY hosts erase host
-     * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
-     * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
-     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
-     * rebuilds are unaffected.
-     *
-     * Disabling stays active through one already-requested frame: the event batch
-     * that ends a foreground stream both removes its UI rows (loader/status
-     * teardown — a shrink) and clears this flag before the throttled render timer
-     * fires. If the flag dropped immediately, that teardown frame would hit the
-     * ED3-risk idle deferral and freeze on screen (stale spinner) until the next
-     * keystroke. When no render is pending, disable immediately so a later
-     * unrelated content mutation does not inherit foreground-stream privileges.
-     */
-    setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;
+    /** Component currently receiving keyboard input, if any. */
+    getFocused(): Component | null;
     /**
      * Show an overlay component with configurable positioning and sizing.
      * Returns a handle to control the overlay's visibility.
@@ -254,22 +347,41 @@ export declare class TUI extends Container {
     /** Check if there are any visible overlays */
     hasOverlay(): boolean;
     invalidate(): void;
-    start(): void;
+    start(options?: TUIStartOptions): void;
+    addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
-    /**
-     * Rebuild native terminal scrollback if live rendering deferred a history rewrite.
-     * Callers should only invoke this at checkpoints where the user is expected to be
-     * at the terminal bottom, such as after submitting a new prompt.
-     */
-    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
     /**
      * Force an immediate full replay of the current frame, including native
      * scrollback. This is the keyboard-accessible equivalent of the resize reset:
      * no queued diff frame or terminal scrollback probe can downgrade it to a
      * viewport-only repaint.
+     *
+     * Invalidates every component first so the replay reflects current state. A
+     * geometry-driven reset thaws frozen scrollback snapshots implicitly (the new
+     * width misses every cached snapshot), but a same-width reset would otherwise
+     * replay stale snapshots — leaving host-frozen blocks (e.g. a transcript whose
+     * committed rows are immutable on ED3-risk terminals) showing pre-mutation
+     * content. Invalidation is the generic signal those containers use to retire
+     * their snapshots, which is exactly what a user-driven display reset wants.
      */
     resetDisplay(): void;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
+    /**
+     * Schedule a render on behalf of `component` after a self-contained change
+     * (spinner frame, blink) that cannot have affected any other component.
+     *
+     * When every request since the last frame is component-scoped and the
+     * frame is otherwise quiet — no resize or geometry change, no overlays, no
+     * live inline images, no forced repaint, unchanged root child list — the
+     * next compose re-renders only the root subtrees containing the requesting
+     * components and reuses the previous frame's rows (and seam reports) for
+     * every other root child, skipping the full component-tree walk that makes
+     * long transcripts expensive to repaint at animation rate. Any concurrent
+     * full request or unsafe condition downgrades the frame to a normal full
+     * compose, so this is never less correct than `requestRender()` — only
+     * cheaper.
+     */
+    requestComponentRender(component: Component): void;
 }

package/dist/types/utils.d.ts

@@ -33,9 +33,12 @@ export declare function padding(n: number): string;
  * Get the shared grapheme segmenter instance.
  */
 export declare function getSegmenter(): Intl.Segmenter;
-export declare function visibleWidthRaw(str: string): number;
 /**
- * Calculate the visible width of a string in terminal columns.
+ * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
+ *
+ * `Bun.stringWidth` does the heavy lifting (UAX#11 width tables + ANSI/OSC
+ * stripping); this adds the two corrections it omits — tabs (expanded to
+ * `tabWidth` cells) and OSC 66 text-sizing payloads (scaled by `s=`).
  */
 export declare function visibleWidth(str: string): number;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@prometheus-ai/tui",
-	"version": "0.5.4",
+	"version": "0.5.8",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://prometheus.trivlab.com",
 	"author": "Uttam Trivedi",
@@ -34,10 +34,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@prometheus-ai/natives": "0.5.4",
-		"@prometheus-ai/utils": "0.5.4",
+		"@prometheus-ai/natives": "0.5.8",
+		"@prometheus-ai/utils": "0.5.8",
 		"lru-cache": "11.5.1",
-		"marked": "^18.0.4"
+		"marked": "^18.0.5"
 	},
 	"devDependencies": {
 		"chalk": "^5.6.2",

package/src/autocomplete.ts

@@ -160,6 +160,7 @@ type Awaitable<T> = T | Promise<T>;
 
 export interface SlashCommand {
 	name: string;
+	aliases?: string[];
 	description?: string;
 	argumentHint?: string;
 	// Function to get argument completions for this command
@@ -210,9 +211,81 @@ export interface AutocompleteProvider {
 	trySyncInlineReplace?(textBeforeCursor: string): { replaceLen: number; insert: string } | null;
 }
 
+type CommandEntry = SlashCommand | AutocompleteItem;
+
+function getCommandName(cmd: CommandEntry): string | undefined {
+	return "name" in cmd ? cmd.name : cmd.value;
+}
+
+function getCommandAliases(cmd: CommandEntry): string[] {
+	if (!("aliases" in cmd) || !Array.isArray(cmd.aliases)) return [];
+	return cmd.aliases.filter(alias => typeof alias === "string" && alias.length > 0);
+}
+
+function commandMatchesNameOrAlias(cmd: CommandEntry, commandName: string): boolean {
+	const name = getCommandName(cmd);
+	if (name === commandName) return true;
+	return getCommandAliases(cmd).includes(commandName);
+}
+
+function scoreCommandTextMatch(lowerPrefix: string, lowerTarget: string): number {
+	if (lowerPrefix.length === 0) return 1;
+	if (lowerPrefix === lowerTarget) return 1000;
+	// Flat score for every prefix match so same-prefix commands keep registry
+	// order under the stable sort. A length penalty here would rank the shorter
+	// name first (e.g. `/set` → `setup` above `settings`), silently changing the
+	// command that the sync-completion path applies on Enter.
+	if (lowerTarget.startsWith(lowerPrefix)) return 900;
+	return fuzzyMatch(lowerPrefix, lowerTarget) ? fuzzyScore(lowerPrefix, lowerTarget) : 0;
+}
+
+function buildSlashCommandCompletions(commands: CommandEntry[], lowerPrefix: string): AutocompleteItem[] {
+	return commands
+		.flatMap(cmd => {
+			const name = getCommandName(cmd);
+			if (!name) return [];
+			const hint = "argumentHint" in cmd && cmd.argumentHint ? cmd.argumentHint : undefined;
+			const desc = cmd.description ?? "";
+			const fullDesc = hint ? (desc ? `${hint} — ${desc}` : hint) : desc;
+			const candidates: Array<AutocompleteItem & { score: number }> = [];
+
+			const nameScore = scoreCommandTextMatch(lowerPrefix, name.toLowerCase());
+			const lowerDesc = desc.toLowerCase();
+			const descScore =
+				lowerDesc && fuzzyMatch(lowerPrefix, lowerDesc) ? fuzzyScore(lowerPrefix, lowerDesc) * 0.5 : 0;
+			const primaryScore = Math.max(nameScore, descScore);
+			if (primaryScore > 0) {
+				candidates.push({
+					value: name,
+					label: "name" in cmd ? cmd.name : cmd.label,
+					score: primaryScore,
+					...(fullDesc && { description: fullDesc }),
+				});
+			}
+
+			if (lowerPrefix.length > 0) {
+				for (const alias of getCommandAliases(cmd)) {
+					if (alias === name) continue;
+					const aliasScore = scoreCommandTextMatch(lowerPrefix, alias.toLowerCase());
+					if (aliasScore === 0) continue;
+					candidates.push({
+						value: alias,
+						label: alias,
+						score: aliasScore,
+						...(fullDesc && { description: fullDesc }),
+					});
+				}
+			}
+
+			return candidates;
+		})
+		.sort((a, b) => b.score - a.score)
+		.map(({ score: _, ...rest }) => rest);
+}
+
 // Combined provider that handles both slash commands and file paths.
 export class CombinedAutocompleteProvider implements AutocompleteProvider {
-	#commands: (SlashCommand | AutocompleteItem)[];
+	#commands: CommandEntry[];
 	#basePath: string;
 	// Intentionally separate from prometheus-natives cache: this cache is a local,
 	// per-directory readdir fast-path for prefix completions. Global fuzzy
@@ -220,7 +293,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 	#dirCache: Map<string, { entries: fs.Dirent[]; timestamp: number }> = new Map();
 	readonly #DIR_CACHE_TTL = 2000; // 2 seconds
 
-	constructor(commands: (SlashCommand | AutocompleteItem)[] = [], basePath: string = getProjectDir()) {
+	constructor(commands: CommandEntry[] = [], basePath: string = getProjectDir()) {
 		this.#commands = commands;
 		this.#basePath = basePath;
 	}
@@ -274,35 +347,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				const prefix = textBeforeCursor.slice(1); // Remove the "/"
 				const lowerPrefix = prefix.toLowerCase();
 
-				// Filter commands using fuzzy matching (subsequence match)
-				const matches = this.#commands
-					.filter(cmd => {
-						const name = "name" in cmd ? cmd.name : cmd.value;
-						if (!name) return false;
-						// Match name or description
-						if (fuzzyMatch(lowerPrefix, name.toLowerCase())) return true;
-						const desc = cmd.description?.toLowerCase();
-						return desc ? fuzzyMatch(lowerPrefix, desc) : false;
-					})
-					.map(cmd => {
-						const name = "name" in cmd ? cmd.name : cmd.value;
-						const lowerName = name?.toLowerCase() ?? "";
-						const lowerDesc = cmd.description?.toLowerCase() ?? "";
-						// Score name matches higher than description matches
-						const nameScore = fuzzyMatch(lowerPrefix, lowerName) ? fuzzyScore(lowerPrefix, lowerName) : 0;
-						const descScore = fuzzyMatch(lowerPrefix, lowerDesc) ? fuzzyScore(lowerPrefix, lowerDesc) * 0.5 : 0;
-						const hint = "argumentHint" in cmd && cmd.argumentHint ? cmd.argumentHint : undefined;
-						const desc = cmd.description ?? "";
-						const fullDesc = hint ? (desc ? `${hint} — ${desc}` : hint) : desc;
-						return {
-							value: name,
-							label: "name" in cmd ? cmd.name : cmd.label,
-							score: Math.max(nameScore, descScore),
-							...(fullDesc && { description: fullDesc }),
-						};
-					})
-					.sort((a, b) => b.score - a.score)
-					.map(({ score: _, ...rest }) => rest);
+				const matches = buildSlashCommandCompletions(this.#commands, lowerPrefix);
 
 				if (matches.length === 0) return null;
 
@@ -315,10 +360,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				const commandName = textBeforeCursor.slice(1, spaceIndex); // Command without "/"
 				const argumentText = textBeforeCursor.slice(spaceIndex + 1); // Text after space
 
-				const command = this.#commands.find(cmd => {
-					const name = "name" in cmd ? cmd.name : cmd.value;
-					return name === commandName;
-				});
+				const command = this.#commands.find(cmd => commandMatchesNameOrAlias(cmd, commandName));
 				if (!command || !("getArgumentCompletions" in command) || !command.getArgumentCompletions) {
 					return null; // No argument completion for this command
 				}
@@ -819,10 +861,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const commandName = textBeforeCursor.slice(1, spaceIndex);
 		const argumentText = textBeforeCursor.slice(spaceIndex + 1);
 
-		const command = this.#commands.find(cmd => {
-			const name = "name" in cmd ? cmd.name : cmd.value;
-			return name === commandName;
-		});
+		const command = this.#commands.find(cmd => commandMatchesNameOrAlias(cmd, commandName));
 
 		if (!command || !("getInlineHint" in command) || !command.getInlineHint) {
 			return null;
@@ -838,32 +877,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const prefix = textBeforeCursor.slice(1);
 		const lowerPrefix = prefix.toLowerCase();
 
-		const matches = this.#commands
-			.filter(cmd => {
-				const name = "name" in cmd ? cmd.name : cmd.value;
-				if (!name) return false;
-				if (fuzzyMatch(lowerPrefix, name.toLowerCase())) return true;
-				const desc = cmd.description?.toLowerCase();
-				return desc ? fuzzyMatch(lowerPrefix, desc) : false;
-			})
-			.map(cmd => {
-				const name = "name" in cmd ? cmd.name : cmd.value;
-				const lowerName = name?.toLowerCase() ?? "";
-				const lowerDesc = cmd.description?.toLowerCase() ?? "";
-				const nameScore = fuzzyMatch(lowerPrefix, lowerName) ? fuzzyScore(lowerPrefix, lowerName) : 0;
-				const descScore = fuzzyMatch(lowerPrefix, lowerDesc) ? fuzzyScore(lowerPrefix, lowerDesc) * 0.5 : 0;
-				const hint = "argumentHint" in cmd && cmd.argumentHint ? cmd.argumentHint : undefined;
-				const desc = cmd.description ?? "";
-				const fullDesc = hint ? (desc ? `${hint} — ${desc}` : hint) : desc;
-				return {
-					value: name,
-					label: "name" in cmd ? cmd.name : cmd.label,
-					score: Math.max(nameScore, descScore),
-					...(fullDesc && { description: fullDesc }),
-				} as AutocompleteItem & { score: number };
-			})
-			.sort((a, b) => b.score - a.score)
-			.map(({ score: _, ...rest }) => rest);
+		const matches = buildSlashCommandCompletions(this.#commands, lowerPrefix);
 
 		if (matches.length === 0) return null;
 		return { items: matches, prefix: textBeforeCursor };