@oh-my-pi/pi-tui 17.4.2 → 18.0.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## [Unreleased]
 
+## [18.0.0] - 2026-08-22
+
+### Breaking Changes
+
+- Changed native macOS spelling and completion functions to return Promises.
+- Updated `EditorTextAssistProvider.tryAutocorrect` signature to receive editor state instead of raw text.
+- Updated `Editor.decorateText` signature to provide line and column context instead of raw text.
+
+### Added
+
+- Added `EditorTextAssistProvider` with spelling suggestion support (`ctrl+.`), word replacement choices, and async autocorrection handling.
+- Added `Terminal.pendingOutputBytes` and an output-backpressure render gate to drop stale frames on slow terminals.
+- Added `deferInput` startup option and `enableInput()` across `Terminal`, `TUI`, and `TUIStartOptions` to improve startup responsiveness.
+- Added icon support and customizable theming to autocomplete and select lists.
+- Added `MarkdownTheme.createHighlightStream` for incremental syntax highlighting of completed lines in streaming Markdown code blocks.
+- Added `maxDescriptionRows` option to `SelectList` layouts to truncate wrapped descriptions with an ellipsis.
+- Added `commandUsage` ranking callback support to `CombinedAutocompleteProvider` to prioritize frequently used slash commands.
+- Added `Editor.viewportRowsProvider` to constrain autocomplete dropdowns within the available terminal height.
+- Added `Editor.setTheme()` to dynamically change themes without recreating the editor or losing draft content.
+
+### Changed
+
+- Adjusted word completion to skip appending a trailing space when the following character is punctuation.
+- Increased default autocomplete dropdown height from 5 to 10 items.
+
+### Fixed
+
+- Fixed TUI freezing during large repaints on slow or occluded terminals by moving stdout writes to an off-thread writer.
+
+## [17.4.4] - 2026-08-22
+
+### Added
+
+- Added `setResizeScrollback()` / `ResizeScrollbackMode` (`PI_TUI_RESIZE_SCROLLBACK` env initializer) controlling what a settled in-place width resize does to native scrollback, which the host rewraps naively at the old width: `append` replays the transcript at the settled width below the old-wrap history, `rebuild` clears pane history first (ED3) so it holds exactly one current-width copy, and `preserve` repaints the viewport only with zero history growth. The raw engine defaults to `preserve`; the coding agent's `tui.resizeScrollback` setting (default `append`) governs interactive sessions.
+
+### Fixed
+
+- `visibleWidth` now measures APC sequences (Kitty graphics commands, cursor markers) as zero cells instead of counting their payload as printable text, matching the native width engine.
+- Kitty Unicode-placeholder rows with long styled prefixes (e.g. bordered thumbnail cards) are recognized as image lines again, keeping them on the verbatim render path instead of SGR coalescing/truncation.
+- Fixed multiplexer width-epoch resolution failing for every real component tree, which forced the conservative full-transcript replay (and one duplicated transcript copy in pane history) on every settled width resize: leading children without a width-epoch revision are no longer validated by width-dependent row counts (reflow is not mutation — identity plus the revision, when reported, is the stability proof), and `Markdown` now reports a width-independent mutation revision so it can sit above an epoch source ([#8193](https://github.com/can1357/oh-my-pi/issues/8193), [#7026](https://github.com/can1357/oh-my-pi/issues/7026)).
+
 ## [17.4.2] - 2026-08-21
 
 ### Added

package/README.md

@@ -539,7 +539,7 @@ interface Terminal {
 **Built-in implementations:**
 
 - `ProcessTerminal` - Uses `process.stdin/stdout`
-- `VirtualTerminal` - For testing (uses ghostty-web)
+- `VirtualTerminal` - For testing (uses kitty-vt-wasm)
 
 ## Utilities
 

package/dist/types/autocomplete.d.ts

@@ -10,6 +10,8 @@ export interface AutocompleteItem {
     value: string;
     label: string;
     description?: string;
+    /** Optional type-indicator glyph rendered in an aligned column before the label */
+    icon?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
 }
@@ -18,6 +20,8 @@ export interface SlashCommand {
     name: string;
     aliases?: string[];
     description?: string;
+    /** Optional type-indicator glyph shown before the command name in autocomplete */
+    icon?: string;
     argumentHint?: string;
     /** Whether the command consumes argument text after the command name. False means the full input stays normal prompt text once args are present. */
     allowArgs?: boolean;
@@ -73,6 +77,11 @@ export interface AutocompleteProvider {
     shouldTriggerFileCompletion?(lines: string[], cursorLine: number, cursorCol: number): boolean;
 }
 type CommandEntry = SlashCommand | AutocompleteItem;
+/** Optional behaviors for {@link CombinedAutocompleteProvider}. */
+export interface CombinedAutocompleteOptions {
+    /** Usage count per command name; higher counts rank earlier among equal text-match scores. */
+    commandUsage?: (name: string) => number;
+}
 export declare function scoreCommandTextMatch(lowerPrefix: string, lowerTarget: string): number;
 /**
  * Whether a mid-prompt slash token (`prose … /tok`) is skill-shaped enough to
@@ -90,7 +99,7 @@ export declare function scoreCommandTextMatch(lowerPrefix: string, lowerTarget:
 export declare function midPromptSkillTokenMatches(lowerToken: string, name: string, description?: string): boolean;
 export declare class CombinedAutocompleteProvider implements AutocompleteProvider {
     #private;
-    constructor(commands?: CommandEntry[], basePath?: string);
+    constructor(commands?: CommandEntry[], basePath?: string, options?: CombinedAutocompleteOptions);
     getSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
         items: AutocompleteItem[];
         prefix: string;

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

@@ -23,6 +23,38 @@ interface HistoryStorage {
     add(prompt: string, cwd?: string): Promise<void>;
     getRecent(limit: number): HistoryEntry[];
 }
+/** A synchronous replacement immediately before the editor cursor. */
+export interface EditorInlineReplacement {
+    /** UTF-16 code units to remove immediately before the cursor. */
+    replaceLen: number;
+    /** Literal text inserted where the removed suffix started. */
+    insert: string;
+}
+/** Replacement candidates and the current-line span they replace. */
+export interface EditorWordReplacements {
+    line: number;
+    startCol: number;
+    endCol: number;
+    items: readonly string[];
+}
+/** Source location for one visual text segment passed to `decorateText`. */
+export interface EditorTextDecorationContext {
+    line: number;
+    startCol: number;
+    endCol: number;
+}
+/**
+ * Optional prose assistance kept separate from command/file autocomplete.
+ * Hosts independently decide whether word completion and autocorrection are enabled.
+ */
+export interface EditorTextAssistProvider {
+    /** Return ghost-text suffix for the partial word at the cursor, or `null`. */
+    getWordCompletion?(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    /** Return a correction after one single-character insertion, or `null`. */
+    tryAutocorrect?(lines: string[], cursorLine: number, cursorCol: number): EditorInlineReplacement | null | Promise<EditorInlineReplacement | null>;
+    /** Return replacement candidates for the misspelled word at the cursor. */
+    getWordReplacements?(lines: string[], cursorLine: number, cursorCol: number): EditorWordReplacements | null | Promise<EditorWordReplacements | null>;
+}
 export declare class Editor implements Component, Focusable {
     #private;
     /** Focusable interface - set by TUI when focus changes */
@@ -34,9 +66,13 @@ export declare class Editor implements Component, Focusable {
     /** Optional hook that decorates displayed user text after source-text layout.
      *  Width-changing output is allowed on lines without the cursor; it is truncated
      *  to the content width rather than reflowed. Cursor glyphs and inline hints are excluded. */
-    decorateText: ((text: string) => string) | undefined;
+    decorateText: ((text: string, context: EditorTextDecorationContext) => string) | undefined;
     borderColor: (str: string) => string;
     onAutocompleteUpdate?: () => void;
+    /** Called after an async text-assist result mutates the document outside an input event, so hosts can schedule a repaint. */
+    onTextAssistApplied?: () => void;
+    /** Terminal height source for clamping the autocomplete dropdown. Hosts wire this to their Terminal's rows. */
+    viewportRowsProvider?: () => number;
     /** Optional pattern matching atomic placeholder tokens (e.g. `[Image #1, 800x600]` or
      *  `[Paste #2, +30 lines]`) that the editor treats as indivisible: a backspace or forward-delete
      *  landing on any character of a token removes the whole token instead of corrupting it into
@@ -56,7 +92,10 @@ export declare class Editor implements Component, Focusable {
     onAutocompleteCancel?: () => void;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
+    setTheme(theme: EditorTheme): void;
     setAutocompleteProvider(provider: AutocompleteProvider): void;
+    /** Install prose assistance without changing command/file autocomplete. */
+    setTextAssistProvider(provider: EditorTextAssistProvider | undefined): void;
     /**
      * Set custom content for the top border (e.g., status line).
      * Pass undefined to use the default plain border.

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

@@ -26,6 +26,14 @@ export interface DefaultTextStyle {
     /** Underline text */
     underline?: boolean;
 }
+/**
+ * Stateful incremental code highlighter carrying parser state across pushes.
+ * Produced per streaming fence by {@link MarkdownTheme.createHighlightStream}.
+ */
+export interface HighlightStreamSession {
+    /** Highlight the next chunk and advance parser state. */
+    push(chunk: string): string;
+}
 /**
  * Theme functions for markdown elements.
  * Each function takes text and returns styled text with ANSI codes.
@@ -46,6 +54,14 @@ export interface MarkdownTheme {
     strikethrough: (text: string) => string;
     underline: (text: string) => string;
     highlightCode?: (code: string, lang?: string) => string[];
+    /**
+     * Create a stateful incremental highlighter for one streaming code fence.
+     * `push` receives newline-terminated complete lines (only the final push
+     * may omit the trailing newline) and must return highlighted ANSI text for
+     * exactly the pushed chunk, byte-identical to highlighting the concatenated
+     * text through `highlightCode`. Return null when `lang` is unsupported.
+     */
+    createHighlightStream?: (lang?: string) => HighlightStreamSession | null;
     /**
      * Resolve a mermaid ASCII rendering by fenced block source text.
      * Return null to fall back to fenced code rendering.
@@ -58,6 +74,7 @@ export declare class Markdown implements Component, NativeScrollbackCommittedRow
     setIgnoreTight(ignore: boolean): this;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
     setText(text: string): boolean;
+    getNativeScrollbackWidthEpochRevision(): number;
     invalidate(): void;
     get transientRenderCache(): boolean;
     set transientRenderCache(value: boolean);

package/dist/types/components/select-list.d.ts

@@ -5,6 +5,8 @@ export interface SelectItem {
     value: string;
     label: string;
     description?: string;
+    /** Optional type-indicator glyph rendered in an aligned column before the label */
+    icon?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
 }
@@ -15,6 +17,8 @@ export interface SelectListTheme {
     scrollInfo: (text: string) => string;
     noMatch: (text: string) => string;
     symbols: SymbolTheme;
+    /** Style for the type-icon column on unselected rows. Defaults to plain text. */
+    icon?: (text: string) => string;
     /** Hover band applied to the full row under the mouse pointer. */
     hovered?: (text: string) => string;
 }
@@ -39,6 +43,11 @@ export interface SelectListLayoutOptions {
      * wrap unevenly.
      */
     wrapDescription?: boolean;
+    /**
+     * Cap wrapped descriptions at this many visual rows; the last kept row is
+     * ellipsized. Only meaningful with `wrapDescription`.
+     */
+    maxDescriptionRows?: number;
 }
 export declare class SelectList implements Component, MouseRoutable {
     #private;

package/dist/types/keybindings.d.ts

@@ -25,6 +25,7 @@ export interface Keybindings {
     "tui.editor.yank": true;
     "tui.editor.yankPop": true;
     "tui.editor.undo": true;
+    "tui.editor.spellingSuggestions": true;
     "tui.input.newLine": true;
     "tui.input.submit": true;
     "tui.input.tab": true;
@@ -129,6 +130,10 @@ export declare const TUI_KEYBINDINGS: {
         readonly defaultKeys: ["ctrl+-", "ctrl+_"];
         readonly description: "Undo";
     };
+    readonly "tui.editor.spellingSuggestions": {
+        readonly defaultKeys: "ctrl+.";
+        readonly description: "Show spelling replacements";
+    };
     readonly "tui.input.newLine": {
         readonly defaultKeys: ["shift+enter", "ctrl+j"];
         readonly description: "Insert newline";

package/dist/types/terminal.d.ts

@@ -58,10 +58,30 @@ export declare function setAltScreenActive(active: boolean): void;
 export declare function emergencyTerminalRestore(): void;
 /** Terminal-reported appearance (dark/light mode). */
 export type TerminalAppearance = "dark" | "light";
+/** Options for {@link Terminal.start}. */
+export interface TerminalStartOptions {
+    /**
+     * Paint-only start: skip raw mode, stdin ownership, and every probe that
+     * elicits a response on stdin. The host tty keeps cooked-mode line editing
+     * (kernel echo lands at the hardware cursor), and typed bytes stay queued
+     * in the kernel until {@link Terminal.enableInput} takes ownership and
+     * replays them through `onInput`. Used for the startup prepaint so typing
+     * echoes even while module loading blocks the event loop.
+     */
+    deferInput?: boolean;
+}
 /** Identity of an accepted explicit terminal appearance refresh request. */
 export type TerminalAppearanceRequestToken = number;
 export interface Terminal {
-    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
+    /**
+     * Take ownership of stdin after a `deferInput` start: enable raw mode,
+     * attach input handlers, and run the capability probes start() skipped.
+     * Bytes the user typed in cooked mode meanwhile are replayed through
+     * `onInput`. No-op when input was never deferred. Optional so custom
+     * Terminals built against older pi-tui versions keep working.
+     */
+    enableInput?(): void;
     stop(): void;
     /**
      * Drain stdin before exiting to prevent Kitty key release events from
@@ -73,6 +93,14 @@ export interface Terminal {
     write(data: string): void;
     get columns(): number;
     get rows(): number;
+    /**
+     * Output bytes accepted but not yet delivered to the terminal, when the
+     * implementation can report it. The renderer skips composing new frames
+     * while this backlog is deep, so a slow terminal receives only fresh
+     * frames instead of a queue of stale ones. Optional so custom Terminals
+     * built against older pi-tui versions keep working.
+     */
+    readonly pendingOutputBytes?: number;
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
     readonly keyboardEnhancementEnterSequence?: string | null;
@@ -158,11 +186,13 @@ export declare class ProcessTerminal implements Terminal {
      */
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
-    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
+    enableInput(): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;
     get columns(): number;
+    get pendingOutputBytes(): number;
     get rows(): number;
     moveBy(lines: number): void;
     hideCursor(force?: boolean): void;

package/dist/types/tui.d.ts

@@ -21,6 +21,12 @@ export interface TUIOptions {
 export interface TUIStartOptions {
     /** Clear saved native scrollback before the first paint. */
     clearScrollback?: boolean;
+    /**
+     * Paint without owning stdin: the terminal stays in cooked mode (kernel
+     * echo + line editing at the hardware cursor) until {@link TUI.enableInput}
+     * switches to raw input and replays the kernel-buffered keystrokes.
+     */
+    deferInput?: boolean;
 }
 /**
  * Component interface - all components must implement this
@@ -200,6 +206,26 @@ export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
 }
+/**
+ * What a settled in-place width resize (multiplexer pane or an in-place-latched
+ * direct terminal) does to native scrollback, which the host rewrapped at the
+ * old width:
+ * - `append`: replay the transcript at the current width below the old-wrap
+ *   history — one fresh copy per settled resize, nothing destroyed.
+ * - `rebuild`: clear native history first (ED3) and replay — history holds the
+ *   transcript exactly once at the current width. Requires a host that honors
+ *   an inner ED3 (tmux does; GNU screen ignores it, degrading to `append`),
+ *   and erases pre-session pane history.
+ * - `preserve`: repaint the viewport only — zero history growth; scrollback
+ *   keeps the old-width wrap until content next scrolls off.
+ *
+ * The raw engine defaults to `preserve` (append-only native scrollback, the
+ * engine's baseline contract); `PI_TUI_RESIZE_SCROLLBACK` overrides that
+ * initial value. The coding agent applies its `tui.resizeScrollback` setting
+ * (default `append`) on top at startup, so interactive sessions refresh
+ * stale-width history out of the box.
+ */
+export type ResizeScrollbackMode = "rebuild" | "append" | "preserve";
 /** Type guard to check if a component implements Focusable */
 export declare function isFocusable(component: Component | null): component is Component & Focusable;
 /**
@@ -407,6 +433,16 @@ export declare class TUI extends Container {
      * duplicate blocks when a block's final form replaces its live preview.
      */
     setScrollbackRebuild(enabled: boolean): void;
+    /**
+     * Get how a settled in-place width resize refreshes native scrollback.
+     */
+    getResizeScrollback(): ResizeScrollbackMode;
+    /**
+     * Set how a settled in-place width resize refreshes native scrollback
+     * (see {@link ResizeScrollbackMode}; engine default `preserve` — the coding
+     * agent applies its `tui.resizeScrollback` setting, default `append`).
+     */
+    setResizeScrollback(mode: ResizeScrollbackMode): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
     /**
@@ -430,6 +466,13 @@ export declare class TUI extends Container {
     hasOverlay(): boolean;
     invalidate(): void;
     start(options?: TUIStartOptions): void;
+    /**
+     * Take ownership of stdin after a `deferInput` start: raw mode, input
+     * handlers, and the response-eliciting capability probes start() skipped.
+     * Keystrokes typed in cooked mode meanwhile arrive through the normal input
+     * path. Idempotent; no-op when input was never deferred.
+     */
+    enableInput(): void;
     addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;

package/dist/types/utils.d.ts

@@ -42,8 +42,9 @@ export declare function getSegmenter(): Intl.Segmenter;
  * 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=`).
+ * stripping); this adds the corrections it omits — tabs (expanded to
+ * `tabWidth` cells), OSC 66 text-sizing payloads (scaled by `s=`), and APC
+ * sequences (counted as printable by Bun, actually zero cells).
  */
 export declare function visibleWidth(str: string): number;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.4.2",
+	"version": "18.0.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,11 +37,11 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.4.2",
-		"@oh-my-pi/pi-utils": "17.4.2"
+		"@oh-my-pi/pi-natives": "18.0.0",
+		"@oh-my-pi/pi-utils": "18.0.0"
 	},
 	"devDependencies": {
-		"ghostty-web": "^0.4.0"
+		"kitty-vt-wasm": "^0.2.0"
 	},
 	"engines": {
 		"bun": ">=1.3.14"

package/src/autocomplete.ts

@@ -171,6 +171,8 @@ export interface AutocompleteItem {
 	value: string;
 	label: string;
 	description?: string;
+	/** Optional type-indicator glyph rendered in an aligned column before the label */
+	icon?: string;
 	/** Dim hint text shown inline after cursor when this item is selected */
 	hint?: string;
 }
@@ -181,6 +183,8 @@ export interface SlashCommand {
 	name: string;
 	aliases?: string[];
 	description?: string;
+	/** Optional type-indicator glyph shown before the command name in autocomplete */
+	icon?: string;
 	argumentHint?: string;
 	/** Whether the command consumes argument text after the command name. False means the full input stays normal prompt text once args are present. */
 	allowArgs?: boolean;
@@ -249,6 +253,11 @@ export interface AutocompleteProvider {
 }
 
 type CommandEntry = SlashCommand | AutocompleteItem;
+/** Optional behaviors for {@link CombinedAutocompleteProvider}. */
+export interface CombinedAutocompleteOptions {
+	/** Usage count per command name; higher counts rank earlier among equal text-match scores. */
+	commandUsage?: (name: string) => number;
+}
 
 function getCommandName(cmd: CommandEntry): string | undefined {
 	return "name" in cmd ? cmd.name : cmd.value;
@@ -287,64 +296,79 @@ export function scoreCommandTextMatch(lowerPrefix: string, lowerTarget: string):
 	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 staticDesc = getStaticCommandDescription(cmd);
-			let fullDescMemo: string | undefined;
-			let fullDescComputed = false;
-			// Resolve the (possibly live) display description lazily, only once a
-			// candidate actually matches — getAutocompleteDescription reads live
-			// session state and must not run for every command on each keystroke.
-			const resolveFullDesc = (): string | undefined => {
-				if (!fullDescComputed) {
-					const displayDesc = getAutocompleteCommandDescription(cmd);
-					fullDescMemo = hint ? (displayDesc ? `${hint} - ${displayDesc}` : hint) : displayDesc;
-					fullDescComputed = true;
-				}
-				return fullDescMemo;
-			};
-			let best: (AutocompleteItem & { score: number }) | undefined;
-
-			const isSkillCommand = name.startsWith("skill:");
-			const nameScore =
-				lowerPrefix.length === 0 && isSkillCommand ? 950 : scoreCommandTextMatch(lowerPrefix, name.toLowerCase());
-			const lowerDesc = staticDesc.toLowerCase();
-			const descScore =
-				lowerDesc && fuzzyMatch(lowerPrefix, lowerDesc) ? fuzzyScore(lowerPrefix, lowerDesc) * 0.5 : 0;
-			const primaryScore = Math.max(nameScore, descScore);
-			if (primaryScore > 0) {
-				const fullDesc = resolveFullDesc();
-				best = {
-					value: name,
-					label: "name" in cmd ? cmd.name : cmd.label,
-					score: primaryScore,
-					...(fullDesc && { description: fullDesc }),
+function buildSlashCommandCompletions(
+	commands: CommandEntry[],
+	lowerPrefix: string,
+	commandUsage?: (name: string) => number,
+): AutocompleteItem[] {
+	return (
+		commands
+			.flatMap(cmd => {
+				const name = getCommandName(cmd);
+				if (!name) return [];
+				const usage = commandUsage?.(name) ?? 0;
+				const hint = "argumentHint" in cmd && cmd.argumentHint ? cmd.argumentHint : undefined;
+				const staticDesc = getStaticCommandDescription(cmd);
+				let fullDescMemo: string | undefined;
+				let fullDescComputed = false;
+				// Resolve the (possibly live) display description lazily, only once a
+				// candidate actually matches — getAutocompleteDescription reads live
+				// session state and must not run for every command on each keystroke.
+				const resolveFullDesc = (): string | undefined => {
+					if (!fullDescComputed) {
+						const displayDesc = getAutocompleteCommandDescription(cmd);
+						fullDescMemo = hint ? (displayDesc ? `${hint} - ${displayDesc}` : hint) : displayDesc;
+						fullDescComputed = true;
+					}
+					return fullDescMemo;
 				};
-			}
-
-			if (lowerPrefix.length > 0) {
-				for (const alias of getCommandAliases(cmd)) {
-					if (alias === name) continue;
-					const aliasScore = scoreCommandTextMatch(lowerPrefix, alias.toLowerCase());
-					if (aliasScore === 0 || (best && aliasScore <= best.score)) continue;
+				let best: (AutocompleteItem & { score: number; usage: number }) | undefined;
+
+				const isSkillCommand = name.startsWith("skill:");
+				const nameScore =
+					lowerPrefix.length === 0 && isSkillCommand
+						? 950
+						: scoreCommandTextMatch(lowerPrefix, name.toLowerCase());
+				const lowerDesc = staticDesc.toLowerCase();
+				const descScore =
+					lowerDesc && fuzzyMatch(lowerPrefix, lowerDesc) ? fuzzyScore(lowerPrefix, lowerDesc) * 0.5 : 0;
+				const primaryScore = Math.max(nameScore, descScore);
+				if (primaryScore > 0) {
 					const fullDesc = resolveFullDesc();
 					best = {
-						value: alias,
-						label: alias,
-						score: aliasScore,
+						value: name,
+						label: "name" in cmd ? cmd.name : cmd.label,
+						score: primaryScore,
+						usage,
+						...(cmd.icon && { icon: cmd.icon }),
 						...(fullDesc && { description: fullDesc }),
 					};
 				}
-			}
 
-			return best ? [best] : [];
-		})
-		.sort((a, b) => b.score - a.score)
-		.map(({ score: _, ...rest }) => rest);
+				if (lowerPrefix.length > 0) {
+					for (const alias of getCommandAliases(cmd)) {
+						if (alias === name) continue;
+						const aliasScore = scoreCommandTextMatch(lowerPrefix, alias.toLowerCase());
+						if (aliasScore === 0 || (best && aliasScore <= best.score)) continue;
+						const fullDesc = resolveFullDesc();
+						best = {
+							value: alias,
+							label: alias,
+							score: aliasScore,
+							usage,
+							...(cmd.icon && { icon: cmd.icon }),
+							...(fullDesc && { description: fullDesc }),
+						};
+					}
+				}
+
+				return best ? [best] : [];
+			})
+			// Equal text-match scores fall back to usage frequency, then to the
+			// stable registry order.
+			.sort((a, b) => b.score - a.score || b.usage - a.usage)
+			.map(({ score: _, usage: _usage, ...rest }) => rest)
+	);
 }
 
 function hasPromptTextBeforeSlash(
@@ -401,15 +425,21 @@ function buildMidPromptSkillCompletions(commands: CommandEntry[], lowerPrefix: s
 export class CombinedAutocompleteProvider implements AutocompleteProvider {
 	#commands: CommandEntry[];
 	#basePath: string;
+	#commandUsage?: (name: string) => number;
 	// Intentionally separate from pi-natives cache: this cache is a local,
 	// per-directory readdir fast-path for prefix completions. Global fuzzy
 	// discovery continues to use native fuzzyFind + shared scan cache.
 	#dirCache: Map<string, { entries: fs.Dirent[]; timestamp: number }> = new Map();
 	readonly #DIR_CACHE_TTL = 2000; // 2 seconds
 
-	constructor(commands: CommandEntry[] = [], basePath: string = getProjectDir()) {
+	constructor(
+		commands: CommandEntry[] = [],
+		basePath: string = getProjectDir(),
+		options?: CombinedAutocompleteOptions,
+	) {
 		this.#commands = commands;
 		this.#basePath = basePath;
+		this.#commandUsage = options?.commandUsage;
 	}
 
 	async getSuggestions(
@@ -444,7 +474,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 
 				const matches = isMidPromptSkillLookup
 					? buildMidPromptSkillCompletions(this.#commands, lowerPrefix)
-					: buildSlashCommandCompletions(this.#commands, lowerPrefix);
+					: buildSlashCommandCompletions(this.#commands, lowerPrefix, this.#commandUsage);
 
 				if (matches.length > 0) {
 					return {
@@ -1069,7 +1099,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 		const prefix = commandText.slice(1);
 		const lowerPrefix = prefix.toLowerCase();
 
-		const matches = buildSlashCommandCompletions(this.#commands, lowerPrefix);
+		const matches = buildSlashCommandCompletions(this.#commands, lowerPrefix, this.#commandUsage);
 
 		if (matches.length === 0) return null;
 		// Mirror `getSuggestions`: preserve leading whitespace so the editor's