@oh-my-pi/pi-tui 18.2.6 → 18.2.7

package/src/overlays/model-browser.ts

@@ -11,6 +11,7 @@ import { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Model } from "@oh-my-pi/pi-ai";
 import { buildModel } from "@oh-my-pi/pi-catalog/build";
 import { modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
+import type { ModelKind } from "@oh-my-pi/pi-catalog/types";
 import type { Component } from "../tui";
 import { fuzzyRank } from "../fuzzy";
 import { Input } from "../components/input";
@@ -33,7 +34,22 @@ import { MenuSelection } from "../components/menu-selection";
 import { clampScrollOffset, scrollOffsetForRow } from "../components/scroll-viewport";
 
 /** Canonical display ordering of built-in model roles. */
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "tiny" | "task" | "advisor";
+export type ModelRole =
+	| "default"
+	| "smol"
+	| "slow"
+	| "vision"
+	| "plan"
+	| "commit"
+	| "tiny"
+	| "memory"
+	| "task"
+	| "advisor"
+	| "image"
+	| "web"
+	| "speech"
+	| "dictation"
+	| "judge";
 export const MODEL_ROLE_IDS: ModelRole[] = [
 	"default",
 	"smol",
@@ -42,9 +58,28 @@ export const MODEL_ROLE_IDS: ModelRole[] = [
 	"plan",
 	"commit",
 	"tiny",
+	"memory",
 	"task",
 	"advisor",
+	"image",
+	"web",
+	"speech",
+	"dictation",
+	"judge",
 ];
+export const CHAT_MODEL_ROLE_IDS: ModelRole[] = [
+	"default",
+	"smol",
+	"slow",
+	"vision",
+	"plan",
+	"commit",
+	"tiny",
+	"memory",
+	"task",
+	"advisor",
+];
+export const KIND_ROLE_IDS: ModelRole[] = ["image", "web", "speech", "dictation", "judge"];
 
 /** Measured model performance shown in browser rows. */
 export interface ModelBrowserPerf {
@@ -59,6 +94,8 @@ export interface ModelBrowserRoleInfo {
 	name: string;
 	color?: ThemeColor;
 	hidden?: boolean;
+	section: "chat" | "kind";
+	accepts(model: Model): boolean;
 }
 
 /** Role lookup used for scoped model resolution. */
@@ -82,14 +119,15 @@ export interface ModelBrowserSource extends ModelRoleLookup {
 	readonly mruOrder: readonly string[];
 	readonly modelPerf: ReadonlyMap<string, ModelBrowserPerf>;
 	getRoleInfo(role: string): ModelBrowserRoleInfo;
+	defaultRoleChain(role: string): string[];
 	resolveRoleValue(value: string | undefined, models: Model[], roleLookup?: ModelRoleLookup): ResolvedModelRoleValue;
 }
 
 /** Read-only catalog surface consumed by model browsers. */
 export interface ModelBrowserRegistry {
 	getError(): unknown;
-	getAvailable(): Model[];
-	getAll(): Model[];
+	getAvailable(kind?: ModelKind | "all"): Model[];
+	getAll(kind?: ModelKind | "all"): Model[];
 }
 
 /** One selectable row. `selector` is a canonical model key or host-specific virtual key. */
@@ -146,7 +184,7 @@ export function resolveRoleAssignments(
 		const roleValue = settings.getModelRole(role);
 		if (!roleValue) continue;
 		configuredRoles.add(role);
-		const resolved = settings.resolveRoleValue(roleValue, catalog);
+		const resolved = settings.resolveRoleValue(roleValue, catalog.filter(settings.getRoleInfo(role).accepts));
 		if (resolved.model) {
 			roles[role] = {
 				model: resolved.model,
@@ -160,7 +198,10 @@ export function resolveRoleAssignments(
 		const candidates = [...autoCandidates];
 		for (const role of knownRoles) {
 			if (configuredRoles.has(role)) continue;
-			const resolved = settings.resolveRoleValue(`pi/${role}`, candidates);
+			const resolved = settings.resolveRoleValue(
+				`pi/${role}`,
+				candidates.filter(settings.getRoleInfo(role).accepts),
+			);
 			if (!resolved.model) continue;
 			roles[role] = {
 				model: resolved.model,
@@ -311,7 +352,7 @@ export function buildSessionModelScope(
 			models = [];
 		}
 	}
-	const allModels = scopedModels.length > 0 ? models : registry.getAll();
+	const allModels = scopedModels.length > 0 ? models : registry.getAll("all");
 	const roles = resolveRoleAssignments(settings, allModels, models);
 	const mruOrder = settings.mruOrder;
 	const items = buildBrowserItems(models);

package/src/overlays/model-hub.ts

@@ -15,6 +15,7 @@ import type { Model } from "@oh-my-pi/pi-ai";
 import { getOAuthProviders } from "@oh-my-pi/pi-ai/oauth";
 import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
 import { providerEntry } from "@oh-my-pi/pi-catalog/compat/providers";
+import { MODEL_KINDS, modelKind, type ModelKind } from "@oh-my-pi/pi-catalog/types";
 import type { Component, TUI } from "../tui";
 import { extractPrintableText, matchesKey } from "../keys";
 import { fuzzyFilter } from "../fuzzy";
@@ -187,6 +188,9 @@ type StripState =
 
 const PROVIDER_REFRESH_DEBOUNCE_MS = 120;
 const RECENT_LIMIT = 15;
+const MODEL_KIND_TABS: ReadonlyArray<"all" | ModelKind> = ["all", ...MODEL_KINDS];
+const ROLE_TABS = ["all", "chat", "kind"] as const;
+type RoleTab = (typeof ROLE_TABS)[number];
 
 /**
  * Providers already auto-refreshed this process. Selecting a provider fetches
@@ -215,6 +219,9 @@ export class ModelHubComponent implements Component {
 	#roles: RoleAssignments = {};
 	#availableItems: ModelBrowserItem[] = [];
 	#recentItems: ModelBrowserItem[] = [];
+	#candidateItems: ModelBrowserItem[] = [];
+	#modelKindTab: "all" | ModelKind = "all";
+	#roleTab: RoleTab = "all";
 	#configError: string | undefined;
 
 	#entries: SidebarEntry[] = [];
@@ -268,7 +275,8 @@ export class ModelHubComponent implements Component {
 		} else if (entry.kind === "provider" && entry.locked && this.#assigning === null) {
 			lines.push(...this.#renderLockedView(entry, width, rows - 1));
 		} else {
-			this.#browser.setMaxVisible(rows - 1 - 5);
+			lines.push(this.#renderModelKindTabs(width));
+			this.#browser.setMaxVisible(rows - 2 - 5);
 			this.#browser.setFocused(this.#focus === "list");
 			lines.push(...this.#browser.render(width));
 		}
@@ -360,7 +368,7 @@ export class ModelHubComponent implements Component {
 
 	/** Resolve every known role: configured values first, auto-selection for the rest. */
 	#reloadRoles(autoCandidates: ReadonlyArray<Model>): void {
-		const allModels = this.#scopedModels.length > 0 ? autoCandidates : this.#registry.getAll();
+		const allModels = this.#scopedModels.length > 0 ? autoCandidates : this.#registry.getAll("all");
 		this.#roles = resolveRoleAssignments(this.#settings, allModels, autoCandidates);
 	}
 
@@ -379,9 +387,9 @@ export class ModelHubComponent implements Component {
 		} else {
 			const loadError = this.#registry.getError();
 			this.#configError = loadError ? String(loadError) : undefined;
-			allModels = this.#registry.getAll();
+			allModels = this.#registry.getAll("all");
 			try {
-				availableModels = this.#registry.getAvailable();
+				availableModels = this.#registry.getAvailable("all");
 			} catch (error) {
 				this.#configError = error instanceof Error ? error.message : String(error);
 				availableModels = [];
@@ -602,18 +610,18 @@ export class ModelHubComponent implements Component {
 		switch (entry.kind) {
 			case "recent":
 				this.#browser.setShowProvider(true);
-				this.#browser.setItems([...this.#recentItems]);
+				this.#setCandidateItems(this.#recentItems);
 				break;
 			case "provider": {
 				if (entry.locked) {
 					// Assign-mode renders the browser regardless of scope; a locked
 					// provider contributes nothing selectable.
-					this.#browser.setItems([]);
+					this.#setCandidateItems([]);
 					break;
 				}
 				const providerId = entry.providerId;
 				this.#browser.setShowProvider(false);
-				this.#browser.setItems(this.#availableItems.filter(item => item.provider === providerId));
+				this.#setCandidateItems(this.#availableItems.filter(item => item.provider === providerId));
 				break;
 			}
 			case "roles":
@@ -621,11 +629,25 @@ export class ModelHubComponent implements Component {
 				break;
 			default:
 				this.#browser.setShowProvider(true);
-				this.#browser.setItems([...this.#availableItems]);
+				this.#setCandidateItems(this.#availableItems);
 				break;
 		}
 	}
 
+	#setCandidateItems(items: ReadonlyArray<ModelBrowserItem>): void {
+		this.#candidateItems = [...items];
+		this.#applyModelKind();
+	}
+
+	#applyModelKind(): void {
+		const kind = this.#modelKindTab;
+		this.#browser.setItems(
+			kind === "all"
+				? [...this.#candidateItems]
+				: this.#candidateItems.filter(item => modelKind(item.model) === kind),
+		);
+	}
+
 	/**
 	 * The configured `retry.fallbackChains` record with malformed keys/entries
 	 * dropped: non-array chains and non-string selectors never reach the rows
@@ -655,12 +677,24 @@ export class ModelHubComponent implements Component {
 	#buildRolesRows(): void {
 		const rows: RolesRow[] = [];
 		const chains = this.#fallbackChains();
-		for (const role of this.#visibleRoleIds()) {
-			rows.push({ kind: "role", role });
-			const chain = chains[role] ?? [];
-			for (let i = 0; i < chain.length; i++) {
-				rows.push({ kind: "fallback", role, chainIndex: i, selector: chain[i] });
+		const appendRoles = (roles: ReadonlyArray<string>): void => {
+			for (const role of roles) {
+				rows.push({ kind: "role", role });
+				const chain = chains[role] ?? [];
+				for (let i = 0; i < chain.length; i++) {
+					rows.push({ kind: "fallback", role, chainIndex: i, selector: chain[i] });
+				}
 			}
+		};
+		const visibleRoles = this.#visibleRoleIds();
+		if (this.#roleTab === "all") {
+			const chatRoles = visibleRoles.filter(role => this.#settings.getRoleInfo(role).section === "chat");
+			const kindRoles = visibleRoles.filter(role => this.#settings.getRoleInfo(role).section === "kind");
+			appendRoles(chatRoles);
+			if (chatRoles.length > 0 && kindRoles.length > 0) rows.push({ kind: "separator" });
+			appendRoles(kindRoles);
+		} else {
+			appendRoles(visibleRoles.filter(role => this.#settings.getRoleInfo(role).section === this.#roleTab));
 		}
 		rows.push({ kind: "newRole" });
 		rows.push({ kind: "separator" });
@@ -912,7 +946,7 @@ export class ModelHubComponent implements Component {
 		const roleValue =
 			scope === "project" ? this.#settings.getProjectModelRole(role) : this.#settings.getGlobalModelRole(role);
 		const allModels =
-			this.#scopedModels.length > 0 ? this.#scopedModels.map(scoped => scoped.model) : this.#registry.getAll();
+			this.#scopedModels.length > 0 ? this.#scopedModels.map(scoped => scoped.model) : this.#registry.getAll("all");
 		const roleLookup: ModelRoleLookup = {
 			getModelRole: scopedRole =>
 				scope === "project"
@@ -987,12 +1021,14 @@ export class ModelHubComponent implements Component {
 		return [ThinkingLevel.Inherit, ThinkingLevel.Off, AUTO_THINKING, ...getSupportedEfforts(model)];
 	}
 
+	/** Offer only the roles this model can actually fill (chat roles for chat models, `web` for search runners, …). */
 	#openRoleStrip(item: ModelBrowserItem): void {
 		const chips: StripChip[] = [];
 		const scopedStorage = this.#settings.modelRoleStorage === "project";
 		const scopes: readonly ModelRoleSelectionScope[] = scopedStorage ? ["project", "global"] : ["global"];
 		for (const role of this.#visibleRoleIds()) {
 			const info = this.#settings.getRoleInfo(role);
+			if (!info.accepts(item.model)) continue;
 			const assignment = this.#roles[role];
 			for (const scope of scopes) {
 				const scopedModel = scopedStorage
@@ -1029,7 +1065,10 @@ export class ModelHubComponent implements Component {
 			styled: theme.fg("muted", `fallbacks:${item.model.provider}/*`),
 			action: "fallbackProvider",
 		});
-		chips.push({ label: "fallback", styled: theme.fg("muted", "retry-fallback"), action: "fallback" });
+		// `retry-fallback` appends to the default chain, so only chat-capable models qualify.
+		if (this.#settings.getRoleInfo("default").accepts(item.model)) {
+			chips.push({ label: "fallback", styled: theme.fg("muted", "retry-fallback"), action: "fallback" });
+		}
 		this.#strip = { kind: "role", item, chips, index: 0, returnToRoles: false };
 	}
 
@@ -1290,7 +1329,9 @@ export class ModelHubComponent implements Component {
 		this.#assigning = { kind: "role", role };
 		this.#focus = "scope";
 		this.#browser.setShowProvider(true);
-		this.#browser.setItems([...this.#availableItems]);
+		this.#setCandidateItems(
+			this.#availableItems.filter(item => this.#settings.getRoleInfo(role).accepts(item.model)),
+		);
 		this.#browser.setQuery("");
 		const current = this.#roles[role];
 		if (current) {
@@ -1303,7 +1344,7 @@ export class ModelHubComponent implements Component {
 		this.#assigning = { kind: "fallback", role, index };
 		this.#focus = "scope";
 		this.#browser.setShowProvider(true);
-		this.#browser.setItems([...this.#availableItems]);
+		this.#setCandidateItems(this.#availableItems);
 		this.#browser.setQuery("");
 		if (index !== null) {
 			const selector = this.#fallbackChains()[role]?.[index];
@@ -1321,7 +1362,7 @@ export class ModelHubComponent implements Component {
 		this.#assigning = { kind: "fallbackKey" };
 		this.#focus = "scope";
 		this.#browser.setShowProvider(true);
-		this.#browser.setItems([...this.#availableItems]);
+		this.#setCandidateItems(this.#availableItems);
 		this.#browser.setQuery("");
 	}
 
@@ -1462,6 +1503,22 @@ export class ModelHubComponent implements Component {
 	// Input
 	// ═══════════════════════════════════════════════════════════════════════
 
+	#moveModelKind(delta: -1 | 1): void {
+		const current = MODEL_KIND_TABS.indexOf(this.#modelKindTab);
+		const next = (Math.max(0, current) + delta + MODEL_KIND_TABS.length) % MODEL_KIND_TABS.length;
+		this.#modelKindTab = MODEL_KIND_TABS[next] ?? "all";
+		this.#applyModelKind();
+	}
+
+	#moveRoleTab(delta: -1 | 1): void {
+		const current = ROLE_TABS.indexOf(this.#roleTab);
+		const next = (Math.max(0, current) + delta + ROLE_TABS.length) % ROLE_TABS.length;
+		this.#roleTab = ROLE_TABS[next] ?? "all";
+		this.#roleIndex = 0;
+		this.#roleScrollStart = 0;
+		this.#buildRolesRows();
+	}
+
 	handleInput(data: string): void {
 		if (this.#assignmentPending) {
 			if (matchesSelectCancel(data)) this.#callbacks.onCancel();
@@ -1505,6 +1562,21 @@ export class ModelHubComponent implements Component {
 			}
 			return;
 		}
+		// Alt+←/→ cycles whichever tab strip is on screen: role tabs in the
+		// Roles view, kind tabs in every browser view. Ctrl+←/→ is unusable on
+		// macOS (Spaces shortcut). macOS terminals (ghostty, Terminal.app,
+		// iTerm) send ESC b / ESC f for Option+←/→, which parse as alt+b /
+		// alt+f — the same aliases the editor's word-motion bindings accept.
+		if (matchesKey(data, "alt+left") || matchesKey(data, "alt+b")) {
+			if (rolesView) this.#moveRoleTab(-1);
+			else this.#moveModelKind(-1);
+			return;
+		}
+		if (matchesKey(data, "alt+right") || matchesKey(data, "alt+f")) {
+			if (rolesView) this.#moveRoleTab(1);
+			else this.#moveModelKind(1);
+			return;
+		}
 
 		// ←/→ are spatial pane switches: the sidebar sits left of the rows.
 		// They never reach the search caret — fuzzy queries don't need one.
@@ -1797,8 +1869,8 @@ export class ModelHubComponent implements Component {
 			} else if (overBody) {
 				if (entry.kind === "roles" && this.#assigning === null) {
 					this.#roleIndex = this.#stepRoleIndex(this.#roleIndex, event.wheel > 0 ? 1 : -1, { wrap: false });
-				} else if (this.#isBrowserView(entry)) {
-					this.#browser.routeMouse(event, bodyLine);
+				} else if (this.#isBrowserView(entry) && bodyLine > 0) {
+					this.#browser.routeMouse(event, bodyLine - 1);
 				}
 			}
 			return true;
@@ -1812,8 +1884,8 @@ export class ModelHubComponent implements Component {
 					roleLine >= 0 && roleLine < this.#rolesVisibleCount ? roleLine + this.#roleScrollStart : null;
 			} else {
 				this.#roleHover = null;
-				if (overBody && this.#isBrowserView(entry)) {
-					this.#browser.routeMouse(event, bodyLine);
+				if (overBody && this.#isBrowserView(entry) && bodyLine > 0) {
+					this.#browser.routeMouse(event, bodyLine - 1);
 				} else {
 					// Pointer left the browser pane: without this, the last
 					// hovered row keeps its band while the sidebar hovers too.
@@ -1860,8 +1932,8 @@ export class ModelHubComponent implements Component {
 				if (this.#lockedLoginLine !== null && bodyLine === this.#lockedLoginLine) {
 					this.#requestLogin(entry);
 				}
-			} else if (this.#isBrowserView(entry)) {
-				this.#browser.routeMouse(event, bodyLine);
+			} else if (this.#isBrowserView(entry) && bodyLine > 0) {
+				this.#browser.routeMouse(event, bodyLine - 1);
 			}
 		}
 		return true;
@@ -1927,6 +1999,24 @@ export class ModelHubComponent implements Component {
 		};
 	};
 
+	#renderModelKindTabs(width: number): string {
+		const active = MODEL_KIND_TABS.indexOf(this.#modelKindTab);
+		const track = renderSegmentTrack(
+			MODEL_KIND_TABS.map(kind => ({ label: kind })),
+			Math.max(0, active),
+		);
+		return truncateToWidth(` ${theme.fg("dim", "Kind:")} ${track}  ${theme.fg("dim", "Alt+←/→")}`, width);
+	}
+
+	#renderRoleTabs(width: number): string {
+		const active = ROLE_TABS.indexOf(this.#roleTab);
+		const track = renderSegmentTrack(
+			ROLE_TABS.map(tab => ({ label: tab === "kind" ? "kinds" : tab })),
+			Math.max(0, active),
+		);
+		return truncateToWidth(` ${theme.fg("dim", "Roles:")} ${track}  ${theme.fg("dim", "Alt+←/→")}`, width);
+	}
+
 	#statusRow(width: number): string {
 		if (this.#assignmentPending) {
 			return truncateToWidth(theme.fg("accent", " Applying model…"), width);
@@ -1995,10 +2085,9 @@ export class ModelHubComponent implements Component {
 
 	#renderRolesView(width: number, rows: number): string[] {
 		const lines: string[] = [];
-		lines.push("");
+		lines.push(this.#renderRoleTabs(width));
 		// First row's offset in bodyLine coordinates: the mouse router's
-		// `bodyLine` has already dropped the status row, so this is just the
-		// leading blank line — no extra status-row offset here.
+		// `bodyLine` has already dropped the status row, leaving the tabs row.
 		this.#rolesRowStart = lines.length;
 
 		let tagWidth = 0;
@@ -2162,7 +2251,7 @@ export class ModelHubComponent implements Component {
 		const catalogCount = entry.catalogCount ?? 0;
 		if (catalogCount > 0) {
 			lines.push(truncateToWidth(theme.fg("dim", `  ${catalogCount} models in catalog:`), width));
-			const preview = this.#scopedModels.length > 0 ? [] : this.#registry.getAll();
+			const preview = this.#scopedModels.length > 0 ? [] : this.#registry.getAll("all");
 			for (const model of preview) {
 				if (model.provider !== entry.providerId) continue;
 				if (lines.length >= rows) break;
@@ -2186,17 +2275,17 @@ export class ModelHubComponent implements Component {
 		if (this.#assigning !== null) {
 			switch (this.#assigning.kind) {
 				case "fallback":
-					return "Enter pick fallback · ↑/↓ providers · type to search · Esc cancel";
+					return "Enter pick fallback · ↑/↓ providers · type to search · Alt+←/→ kind · Esc cancel";
 				case "fallbackKey":
-					return "Enter pick the protected model · ↑/↓ providers · type to search · Esc cancel";
+					return "Enter pick the protected model · ↑/↓ providers · type to search · Alt+←/→ kind · Esc cancel";
 				default:
-					return "Enter assign · ↑/↓ providers · type to search · Esc cancel";
+					return "Enter assign · ↑/↓ providers · type to search · Alt+←/→ kind · Esc cancel";
 			}
 		}
 		const entry = this.#activeEntry();
 		if (entry.kind === "roles") {
 			if (this.#focus !== "list") {
-				return "↑/↓ providers · → roles · Esc close";
+				return "↑/↓ providers · → roles · Alt+←/→ tabs · Esc close";
 			}
 			const row = this.#rolesRows[this.#roleIndex];
 			if (row?.kind === "fallback") {
@@ -2220,7 +2309,7 @@ export class ModelHubComponent implements Component {
 		}
 		const arrows = this.#focus === "scope" ? "↑/↓ providers · → models" : "↑/↓ models · ← providers";
 		const refresh = entry.kind === "provider" ? " · F5 refresh" : "";
-		return `Enter assign roles · ${arrows} · type to search${refresh} · Esc close`;
+		return `Enter assign roles · ${arrows} · type to search · Alt+←/→ kind${refresh} · Esc close`;
 	}
 
 	#renderFooter(width: number): string {

package/src/prompt/gradient-highlight.ts

@@ -14,8 +14,8 @@ export type KeywordHighlighter = (text: string, resetTo?: string, phase?: number
 
 /** Declarative spec for {@link createGradientHighlighter}. */
 export interface GradientHighlightSpec {
-	/** Cheap, stateless presence probe used to skip the boundary regex on most lines. Must be non-global. */
-	probe: RegExp;
+	/** Literal substring whose absence skips the boundary regex on most lines. */
+	probe: string;
 	/** Global, word-bounded match regex walked by `.replace`. */
 	highlight: RegExp;
 	/** Number of color stops swept across the gradient. */
@@ -82,7 +82,7 @@ export function createGradientHighlighter(spec: GradientHighlightSpec): KeywordH
 	};
 
 	return (text: string, resetTo: string = FG_RESET, phase: number = 0): string => {
-		if (!probe.test(text)) return text;
+		if (!text.includes(probe)) return text;
 		// Wrap phase into [0, 1) so negative inputs and values ≥ 1 stay well-defined.
 		const wrappedPhase = ((phase % 1) + 1) % 1;
 		// Match against a code/markup-masked copy so keywords inside code spans,

package/src/prompt/macos-spelling.ts

@@ -2,6 +2,7 @@ import * as native from "@oh-my-pi/pi-natives";
 import { TERMINAL } from "../index";
 import type { EditorInlineReplacement, EditorTextAssistProvider, EditorWordReplacements } from "../components/editor";
 import { logger } from "@oh-my-pi/pi-utils";
+import { isMagicKeyword } from "./magic-keywords";
 import { maskNonProse } from "./markdown-prose";
 
 /** Styled underline: red curly undercurl via colon-subparameter SGR (4:3 + SGR 58 color). */
@@ -200,6 +201,8 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		const match = COMPLETED_WORD.exec(textBeforeCursor);
 		if (!match) return null;
 		const word = match[1] ?? "";
+		// Magic keywords are deliberate non-dictionary words; never "fix" them.
+		if (isMagicKeyword(word)) return null;
 		const boundary = match[2] ?? "";
 		const start = match.index;
 		const masked = maskNonProse(textBeforeCursor);
@@ -350,7 +353,10 @@ export class MacOSSpellingProvider implements EditorTextAssistProvider {
 		if (generation !== this.#cacheGeneration || !this.#available) return [];
 		const masked = maskNonProse(text);
 		const ranges = checked
-			.filter(range => isProseWord(text, masked, range.start, range.start + range.length))
+			.filter(range => {
+				const end = range.start + range.length;
+				return isProseWord(text, masked, range.start, end) && !isMagicKeyword(text.slice(range.start, end));
+			})
 			.toSorted((left, right) => left.start - right.start);
 		const hadProjectedRanges = (this.#projectTypoRanges(text)?.length ?? 0) > 0;
 		if (this.#typoCache.size >= CACHE_LIMIT) this.#typoCache.clear();

package/src/prompt/magic-keywords.ts

@@ -1,14 +1,98 @@
-import { containsOrchestrate, highlightOrchestrate } from "./orchestrate";
-import { containsUltrathink, highlightUltrathink } from "./ultrathink";
-import { containsWorkflow, highlightWorkflow } from "./workflow";
+import { createGradientHighlighter, type KeywordHighlighter } from "./gradient-highlight";
+import { keywordInProse } from "./markdown-prose";
 
 /**
- * Gradient-highlight every magic keyword ("ultrathink", "orchestrate",
- * "workflowz") that appears as standalone prose, skipping any occurrence inside a
- * code block, inline code span, or XML/HTML section. Each highlighter paints its
- * own keyword with its own gradient, so chaining is order-independent — the
- * earlier passes only inject zero-width SGR escapes (no backticks or angle
- * brackets), which never confuse the later passes' markdown masking.
+ * Magic-keyword engine: standalone prose words the host registers via
+ * {@link setMagicKeywords} glow with a per-word gradient in the editor and in
+ * sent bubbles, and are exempt from spelling autocorrect. The host (coding-agent
+ * `modes/magic-keywords.ts`) owns the word list and the notices each word
+ * injects; this module only knows how to find and paint them.
+ */
+
+/** One registered magic keyword: the prose trigger and its editor gradient. */
+export interface MagicKeywordSpec {
+	/** Exact lowercase trigger, matched only as standalone prose. */
+	readonly word: string;
+	/** HSL hue sweep `[from, to]` in degrees painted across the word; `to` may exceed 360 to wrap through red. */
+	readonly hue: readonly [number, number];
+}
+
+/** Characters that bind a magic keyword into an identifier or path segment. */
+const LEFT_BOUNDARY = String.raw`(?<![\p{L}\p{N}_./\\-])(?<!::)`;
+
+/** Characters that cannot immediately follow a standalone magic keyword. */
+const RIGHT_BOUNDARY = String.raw`(?![\p{L}\p{N}_/\\-])(?!\.[\p{L}\p{N}_-])(?!\()`;
+
+/**
+ * Build a case-sensitive matcher for `word` at prose punctuation boundaries.
+ *
+ * Sentence punctuation and quotes may touch the keyword, but letters, digits,
+ * underscores, slashes, backslashes, hyphens, file-extension dots, symbol
+ * references (`foo::keyword`), and immediate call parentheses (`keyword()`)
+ * keep the occurrence embedded in code rather than prose.
+ */
+function magicKeywordRegex(word: string, flags = ""): RegExp {
+	const escaped = word.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+	return new RegExp(`${LEFT_BOUNDARY}${escaped}${RIGHT_BOUNDARY}`, `${flags}u`);
+}
+
+interface RegisteredKeyword {
+	readonly word: string;
+	readonly highlight: KeywordHighlighter;
+}
+
+let registry: readonly RegisteredKeyword[] = [];
+
+/** Non-global standalone-prose matcher per word, shared by detection paths. */
+const matchers = new Map<string, RegExp>();
+
+function matcherFor(word: string): RegExp {
+	let matcher = matchers.get(word);
+	if (!matcher) {
+		matcher = magicKeywordRegex(word);
+		matchers.set(word, matcher);
+	}
+	return matcher;
+}
+
+/**
+ * Replace the registered keyword set. The host calls this once at startup;
+ * until then nothing glows and no word is exempt from autocorrect.
+ */
+export function setMagicKeywords(specs: readonly MagicKeywordSpec[]): void {
+	registry = specs.map(({ word, hue: [from, to] }) => ({
+		word,
+		highlight: createGradientHighlighter({
+			probe: word,
+			highlight: magicKeywordRegex(word, "g"),
+			stops: 14,
+			hue: t => (from + t * (to - from)) % 360,
+		}),
+	}));
+}
+
+/** Whether `word` is exactly a registered magic keyword (used to shield it from spelling autocorrect). */
+export function isMagicKeyword(word: string): boolean {
+	for (const keyword of registry) if (keyword.word === word) return true;
+	return false;
+}
+
+/**
+ * Whether `text` contains `word` as standalone lowercase prose — never inside
+ * a code block, inline code span, or XML/HTML section. Pure: does not require
+ * `word` to be registered.
+ */
+export function containsMagicKeyword(text: string, word: string): boolean {
+	return keywordInProse(text, matcherFor(word));
+}
+
+/**
+ * Gradient-highlight every registered keyword that appears as standalone
+ * prose, skipping any occurrence inside a code block, inline code span, or
+ * XML/HTML section. Each pass paints one word with its own gradient, so order
+ * is irrelevant — earlier passes only inject zero-width SGR escapes (no
+ * backticks or angle brackets), which never confuse later passes' markdown
+ * masking.
  *
  * `resetTo` is the SGR foreground sequence restored after each painted keyword;
  * pass the surrounding text color when decorating already-colored content (e.g.
@@ -21,22 +105,20 @@ import { containsWorkflow, highlightWorkflow } from "./workflow";
  * to keep the static gradient.
  */
 export function highlightMagicKeywords(text: string, resetTo?: string, phase?: number): string {
-	return highlightWorkflow(
-		highlightOrchestrate(highlightUltrathink(text, resetTo, phase), resetTo, phase),
-		resetTo,
-		phase,
-	);
+	let out = text;
+	for (const keyword of registry) out = keyword.highlight(out, resetTo, phase);
+	return out;
 }
 
 /**
- * Cheap test for "does this text contain any magic keyword as standalone prose?".
- * Short-circuits on a substring probe before paying for the markdown-aware
- * prose check, so the common "no keyword in buffer" path is just three
- * `String#indexOf`s. Used by the live editor to gate the shimmer timer.
+ * Cheap test for "does this text contain any registered keyword as standalone
+ * prose?". Short-circuits on a substring probe before paying for the
+ * markdown-aware prose check, so the common "no keyword in buffer" path is one
+ * `String#includes` per word. Used by the live editor to gate the shimmer timer.
  */
 export function hasMagicKeyword(text: string): boolean {
-	if (!text.includes("ultrathink") && !text.includes("orchestrate") && !text.includes("workflowz")) {
-		return false;
+	for (const keyword of registry) {
+		if (text.includes(keyword.word) && containsMagicKeyword(text, keyword.word)) return true;
 	}
-	return containsUltrathink(text) || containsOrchestrate(text) || containsWorkflow(text);
+	return false;
 }

package/src/prompt/markdown-prose.ts

@@ -1,8 +1,8 @@
 import { FENCE_RE } from "../render/render-utils";
 
 /**
- * Markdown structure awareness for the magic-keyword affordances
- * ("ultrathink"/"orchestrate"/"workflowz").
+ * Markdown structure awareness for the magic-keyword affordances (see
+ * `magic-keywords.ts`) and the spelling provider.
  *
  * Keyword detection and editor/transcript highlighting must fire only on prose
  * the user is actually addressing to the model — never on a word that happens to