@oh-my-pi/pi-tui 17.3.8 → 17.4.0

package/src/components/composer/rule.ts

@@ -0,0 +1,55 @@
+/**
+ * Single-rule composer: a borderless prompt docked below one top rule. The
+ * right status group rides the rule while the left group remains below the
+ * editor, preserving the compact status split without a closing rule.
+ */
+import { truncateToWidth, visibleWidth } from "../../utils";
+import type { ComposerChromeContext, ComposerRowContext, ComposerStyle } from "./types";
+
+/** Draw a full-width rule with status content docked at its right edge.
+ * Over-wide content is truncated (keeping one rule cell on each side) rather
+ * than dropped, so the chip survives narrow terminals and previews. */
+export function renderTopRule(ctx: ComposerChromeContext): string {
+	const { box, width, borderColor, topBorder } = ctx;
+	if (topBorder && topBorder.width > 0 && width > 2) {
+		let { content, width: chipWidth } = topBorder;
+		if (chipWidth > width - 2) {
+			content = truncateToWidth(content, width - 2);
+			chipWidth = visibleWidth(content);
+		}
+		const leftFill = Math.max(0, width - chipWidth - 1);
+		return borderColor(box.horizontal.repeat(leftFill)) + content + borderColor(box.horizontal);
+	}
+	return borderColor(box.horizontal.repeat(width));
+}
+
+/** Composer style with one status-bearing top rule and no bottom chrome. */
+export const ruleComposerStyle: ComposerStyle = {
+	id: "rule",
+	sideBorders: false,
+	verticalChrome: 1,
+	statusAttachment: "top-rule-chip",
+	bottomBar: "left",
+	bottomBarGap: true,
+	defaultPromptGutter: "❯ ",
+
+	defaultPaddingX(): number {
+		return 0;
+	},
+
+	sideChromeWidth(paddingX: number): number {
+		return paddingX;
+	},
+
+	renderTop(ctx: ComposerChromeContext): string {
+		return renderTopRule(ctx);
+	},
+
+	renderRow(ctx: ComposerRowContext): string[] {
+		return [ctx.gutter + ctx.text + ctx.pad];
+	},
+
+	renderBottom(): undefined {
+		return undefined;
+	},
+};

package/src/components/composer/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Composer chrome contract. A {@link ComposerStyle} owns everything about how
+ * the input editor's frame looks — top/bottom chrome, per-row side chrome,
+ * default padding and prompt gutter — plus metadata telling the host where the
+ * status bar attaches. The editor, the /settings preview, and the setup-wizard
+ * preview all render through the same style object, so the three surfaces can
+ * never drift apart.
+ */
+import type { SymbolTheme } from "../../symbols";
+
+/** Box-drawing glyph set used for composer chrome (the theme's `boxRound`). */
+export type ComposerBox = SymbolTheme["boxRound"];
+
+/** Built-in composer shape identifiers shipped by pi-tui. */
+export const BUILTIN_EDITOR_BORDER_STYLES = ["box", "claude", "pi", "borderless", "rule", "field", "rail"] as const;
+
+/** Identifier for a built-in composer shape. */
+export type BuiltinEditorBorderStyle = (typeof BUILTIN_EDITOR_BORDER_STYLES)[number];
+
+/** Composer shape identifier; extensions may register additional strings. */
+export type EditorBorderStyle = string;
+
+/** Pre-rendered status content injected into the top chrome. */
+export interface EditorTopBorder {
+	/** The status content (already styled) */
+	content: string;
+	/** Visible width of the content */
+	width: number;
+	/** Optional logical revision that changes independently of available width. */
+	revision?: number;
+}
+
+/** Inputs shared by every chrome row. */
+export interface ComposerChromeContext {
+	/** Full terminal width available to the composer. */
+	width: number;
+	/** Horizontal padding inside the side chrome. */
+	paddingX: number;
+	borderColor: (str: string) => string;
+	/** Stable accent used by shape-defining chrome such as field caps and rails. */
+	accentColor: (str: string) => string;
+	/** Background fill for composer surfaces; preserves the fill across nested SGR resets. */
+	surfaceColor: (str: string) => string;
+	/** Box-drawing glyph set (theme's `boxRound`). */
+	box: ComposerBox;
+	/** Status content for the top chrome; box embeds it after the corner while
+	 * rule-based styles dock it against the right edge. */
+	topBorder?: EditorTopBorder;
+}
+
+/** Inputs for one content row. */
+export interface ComposerRowContext extends ComposerChromeContext {
+	/** Fully decorated row text (cursor glyph / IME marker included). */
+	text: string;
+	/** Spaces padding the text out to the content width. */
+	pad: string;
+	/** Prompt gutter cells for this row ("" when the style has none). */
+	gutter: string;
+	isLastRow: boolean;
+	/** Cells the end-of-line cursor overflowed into the right chrome (box). */
+	cursorOverflow: number;
+	/** Emit an empty right chrome after the cursor so terminal-local IME
+	 *  preedit cannot shift the frame (box last row). */
+	imeSafeCursorTail: boolean;
+	/** Row lies inside the right-border scrollbar thumb (box). */
+	scrollbarThumb: boolean;
+}
+
+export interface ComposerStyle {
+	readonly id: EditorBorderStyle;
+	/** Content rows carry left/right border glyphs; drives the cursor-reserve
+	 *  column, IME-safe layout, and the right-border scrollbar. */
+	readonly sideBorders: boolean;
+	/** Rows consumed by top+bottom chrome (drives maxHeight budgeting). */
+	readonly verticalChrome: 0 | 1 | 2;
+	/** Where the host should attach the status bar: embedded in the top border,
+	 * docked onto a top rule, or detached into a standalone bottom bar. */
+	readonly statusAttachment: "top-border" | "top-rule-chip" | "none";
+	/** Which segment groups the standalone bottom status bar shows. */
+	readonly bottomBar: "none" | "left" | "full";
+	/** Insert a blank spacer row between the editor and the standalone bottom
+	 * bar. Styles without bottom chrome need it so the bar doesn't sit flush
+	 * against the last input row. */
+	readonly bottomBarGap: boolean;
+	/** Default prompt gutter when the host sets none. */
+	readonly defaultPromptGutter: string | undefined;
+	/** Default horizontal padding; `themePaddingX` is the theme's request. */
+	defaultPaddingX(themePaddingX: number | undefined): number;
+	/** Cells consumed per side on content rows (border glyph + padding). */
+	sideChromeWidth(paddingX: number): number;
+	/** Top chrome row; `undefined` renders none. */
+	renderTop(ctx: ComposerChromeContext): string | undefined;
+	/** Chrome-wrapped content row; box's IME-safe last row emits two rows. */
+	renderRow(ctx: ComposerRowContext): string[];
+	/** Bottom chrome row; `undefined` renders none (box merges the bottom
+	 *  border into its last content row). */
+	renderBottom(ctx: ComposerChromeContext): string | undefined;
+}

package/src/components/editor.ts

@@ -23,8 +23,21 @@ import {
 	truncateToWidth,
 	visibleWidth,
 } from "../utils";
+import {
+	borderlessComposerStyle,
+	type ComposerChromeContext,
+	type ComposerStyle,
+	type EditorBorderStyle,
+	type EditorTopBorder,
+	getComposerStyle,
+} from "./composer";
+
+export type { EditorBorderStyle, EditorTopBorder };
+
 import { type SelectItem, SelectList, type SelectListLayoutOptions, type SelectListTheme } from "./select-list";
 
+const PASSTHROUGH_COLOR = (text: string): string => text;
+
 const AUTOCOMPLETE_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
 	overflowSearch: false,
 };
@@ -379,6 +392,10 @@ interface WrapEntry {
 
 export interface EditorTheme {
 	borderColor: (str: string) => string;
+	/** Stable accent for composer chrome that should not follow the mutable border state. */
+	accentColor?: (str: string) => string;
+	/** Background fill used by filled composer styles. */
+	surfaceColor?: (str: string) => string;
 	selectList: SelectListTheme;
 	symbols: SymbolTheme;
 	editorPaddingX?: number;
@@ -386,15 +403,6 @@ export interface EditorTheme {
 	hintStyle?: (text: string) => string;
 }
 
-export interface EditorTopBorder {
-	/** The status content (already styled) */
-	content: string;
-	/** Visible width of the content */
-	width: number;
-	/** Optional logical revision that changes independently of available width. */
-	revision?: number;
-}
-
 interface HistoryEntry {
 	prompt: string;
 }
@@ -523,7 +531,7 @@ export class Editor implements Component, Focusable {
 	#topBorderProviderSignature: string | undefined;
 	#topBorderProviderRevision: number | undefined;
 	#borderVisible = true;
-
+	#borderStyle: EditorBorderStyle = "box";
 	constructor(theme: EditorTheme) {
 		this.#theme = theme;
 		this.borderColor = theme.borderColor;
@@ -581,6 +589,20 @@ export class Editor implements Component, Focusable {
 	setPromptGutter(promptGutter: string | undefined): void {
 		this.#promptGutter = promptGutter;
 	}
+	getBorderStyle(): EditorBorderStyle {
+		return this.#borderStyle;
+	}
+
+	setBorderStyle(style: EditorBorderStyle): void {
+		if (this.#borderStyle === style) return;
+		this.#borderStyle = style;
+		this.#widthEpochRevision++;
+	}
+
+	/** True while the autocomplete/slash-command menu is open below the editor. */
+	isAutocompleteActive(): boolean {
+		return this.#autocompleteState !== null;
+	}
 
 	/**
 	 * Get the available width for top border content given a total terminal width.
@@ -724,31 +746,50 @@ export class Editor implements Component, Focusable {
 		// No cached state to invalidate currently
 	}
 
+	/** Active chrome style; a hidden border collapses every shape to borderless. */
+	#effectiveStyle(): ComposerStyle {
+		return this.#borderVisible ? getComposerStyle(this.#borderStyle) : borderlessComposerStyle;
+	}
+
+	#getEffectivePromptGutter(): string | undefined {
+		const style = this.#effectiveStyle();
+		// The box frame never renders a gutter; hosts that set one expect it only
+		// in borderless contexts (hook editors, agents hub).
+		if (style.sideBorders) return undefined;
+		if (this.#promptGutter !== undefined) return this.#promptGutter;
+		// Legacy `setBorderVisible(false)` callers control the gutter themselves;
+		// only an explicitly selected composer shape gets the style default.
+		if (!this.#borderVisible) return undefined;
+		return style.defaultPromptGutter;
+	}
+
 	#getEditorPaddingX(): number {
-		const padding = this.#paddingXOverride ?? this.#theme.editorPaddingX ?? 2;
-		return Math.max(0, padding);
+		if (this.#paddingXOverride !== undefined) return Math.max(0, this.#paddingXOverride);
+		return this.#effectiveStyle().defaultPaddingX(this.#theme.editorPaddingX);
 	}
 
 	#getHorizontalChromeWidth(paddingX: number): number {
-		return this.#borderVisible ? paddingX + 1 : 0;
+		return this.#effectiveStyle().sideChromeWidth(paddingX);
 	}
 
 	#getPromptGutterWidth(width: number, paddingX: number): number {
-		if (this.#borderVisible || !this.#promptGutter) return 0;
+		const gutter = this.#getEffectivePromptGutter();
+		if (!gutter) return 0;
 		const chromeWidth = 2 * this.#getHorizontalChromeWidth(paddingX);
 		const availableWidth = Math.max(0, width - chromeWidth);
-		return Math.min(visibleWidth(this.#promptGutter), availableWidth);
+		return Math.min(visibleWidth(gutter), availableWidth);
 	}
 
 	#getPromptGutter(
 		width: number,
 		paddingX: number,
 	): { firstLine: string; continuation: string; width: number } | undefined {
-		if (this.#borderVisible || !this.#promptGutter) return undefined;
+		const gutter = this.#getEffectivePromptGutter();
+		if (!gutter) return undefined;
 		const gutterWidth = this.#getPromptGutterWidth(width, paddingX);
 		if (gutterWidth === 0) return undefined;
 		return {
-			firstLine: sliceByColumn(this.#promptGutter, 0, gutterWidth, true),
+			firstLine: sliceByColumn(gutter, 0, gutterWidth, true),
 			continuation: padding(gutterWidth),
 			width: gutterWidth,
 		};
@@ -761,17 +802,15 @@ export class Editor implements Component, Focusable {
 
 	#getLayoutWidth(width: number, paddingX: number): number {
 		const contentWidth = this.#getContentWidth(width, paddingX);
-		const cursorReserve = this.#borderVisible && paddingX === 0 ? 1 : 0;
+		const cursorReserve = this.#effectiveStyle().sideBorders && paddingX === 0 ? 1 : 0;
 		// Keep cursor/scroll layout addressable even when a borderless prompt gutter consumes every visible column.
 		return Math.max(1, contentWidth - cursorReserve);
 	}
 
 	#getVisibleContentHeight(contentLines: number): number {
 		if (this.#maxHeight === undefined) return contentLines;
-		const verticalChrome = this.#borderVisible ? 2 : 0;
-		return Math.max(1, this.#maxHeight - verticalChrome);
+		return Math.max(1, this.#maxHeight - this.#effectiveStyle().verticalChrome);
 	}
-
 	/** Apply the optional input decorator to a plain (ANSI-free) text segment.
 	 *  Decoration only adds zero-width SGR codes, so visible width is unchanged.
 	 *  Splits around CURSOR_MARKER so each user-text segment is decorated in
@@ -882,20 +921,16 @@ export class Editor implements Component, Focusable {
 	}
 
 	render(width: number): readonly string[] {
+		const style = this.#effectiveStyle();
 		const paddingX = this.#getEditorPaddingX();
-		const borderVisible = this.#borderVisible;
+		const isSideBordered = style.sideBorders;
 		const promptGutter = this.#getPromptGutter(width, paddingX);
 		const contentAreaWidth = this.#getContentWidth(width, paddingX);
 		const layoutWidth = this.#getLayoutWidth(width, paddingX);
 		this.#lastLayoutWidth = layoutWidth;
 
-		// Box-drawing characters for rounded corners
 		const box = this.#theme.symbols.boxRound;
 		const borderWidth = this.#getHorizontalChromeWidth(paddingX);
-		const topLeft = this.borderColor(`${box.topLeft}${box.horizontal.repeat(paddingX)}`);
-		const topRight = this.borderColor(`${box.horizontal.repeat(paddingX)}${box.topRight}`);
-		const bottomLeft = this.borderColor(`${box.bottomLeft}${box.horizontal}${padding(Math.max(0, paddingX - 1))}`);
-		const horizontal = this.borderColor(box.horizontal);
 
 		// Layout the text
 		const layoutLines = this.#layoutText(layoutWidth);
@@ -921,13 +956,12 @@ export class Editor implements Component, Focusable {
 			scrollbarThumb = { start, end: start + thumbSize };
 		}
 
-		if (borderVisible) {
-			// Render top border: ╭─ [status content] ────────────────╮
-			const topFillWidth = Math.max(0, width - borderWidth * 2);
-			// Provider (lazy) wins over eager content — a host that installs both
-			// wants the coalesced path; falling back to eager keeps existing
-			// setTopBorder callers working unchanged.
-			let topBorder: EditorTopBorder | undefined;
+		// Resolve the custom top-border content once per frame; the style decides
+		// how (and whether) to draw it. Provider caching stays editor-owned so
+		// per-event rebuilds keep coalescing to one per painted frame.
+		const topFillWidth = Math.max(0, width - borderWidth * 2);
+		let topBorder: EditorTopBorder | undefined;
+		if (style.statusAttachment !== "none") {
 			if (this.#topBorderProvider) {
 				const previousWidth = this.#topBorderProviderWidth;
 				topBorder = this.#topBorderProvider(topFillWidth);
@@ -948,24 +982,21 @@ export class Editor implements Component, Focusable {
 			} else {
 				topBorder = this.#topBorderContent;
 			}
-			if (topBorder) {
-				const { content, width: statusWidth } = topBorder;
-				if (statusWidth <= topFillWidth) {
-					// Status fits - add fill after it
-					const fillWidth = topFillWidth - statusWidth;
-					result.push(topLeft + content + this.borderColor(box.horizontal.repeat(fillWidth)) + topRight);
-				} else {
-					// Status too long - truncate it
-					const truncated = truncateToWidth(content, Math.max(0, topFillWidth - 1));
-					const truncatedWidth = visibleWidth(truncated);
-					const fillWidth = Math.max(0, topFillWidth - truncatedWidth);
-					result.push(topLeft + truncated + this.borderColor(box.horizontal.repeat(fillWidth)) + topRight);
-				}
-			} else {
-				result.push(topLeft + horizontal.repeat(topFillWidth) + topRight);
-			}
 		}
 
+		const chromeCtx: ComposerChromeContext = {
+			width,
+			paddingX,
+			borderColor: (str: string) => this.borderColor(str),
+			accentColor: this.#theme.accentColor ?? this.borderColor,
+			surfaceColor: this.#theme.surfaceColor ?? PASSTHROUGH_COLOR,
+			box,
+			topBorder,
+		};
+
+		const topRow = style.renderTop(chromeCtx);
+		if (topRow !== undefined) result.push(topRow);
+
 		// Render each layout line
 		// Keep the hardware cursor at the text insertion point while autocomplete
 		// rows render below it; terminals use that position to anchor IME candidates.
@@ -991,12 +1022,12 @@ export class Editor implements Component, Focusable {
 			const hasCursor = layoutLine.hasCursor && layoutLine.cursorPos !== undefined;
 			const marker = emitCursorMarker ? CURSOR_MARKER : "";
 
-			if (!borderVisible && displayWidth > lineContentWidth) {
+			if (!isSideBordered && displayWidth > lineContentWidth) {
 				displayText = sliceByColumn(displayText, 0, lineContentWidth, true);
 				displayWidth = visibleWidth(displayText);
 			}
 
-			if (!borderVisible && lineContentWidth === 0) {
+			if (!isSideBordered && lineContentWidth === 0) {
 				if (hasCursor && !this.#useTerminalCursor) {
 					const zeroWidthCursorBudget = visibleWidth(gutterText);
 					const zeroWidthCursorReplacement = this.cursorOverride
@@ -1039,7 +1070,7 @@ export class Editor implements Component, Focusable {
 				if (marker) {
 					const before = displayText.slice(0, layoutLine.cursorPos);
 					const after = displayText.slice(layoutLine.cursorPos);
-					if (this.#imeSafeCursorLayout && after.length === 0 && borderVisible) {
+					if (this.#imeSafeCursorLayout && after.length === 0 && isSideBordered) {
 						// Terminal frontends render IME marked text locally before committed bytes
 						// reach the application. Keep the end-of-input cursor row empty to its
 						// right so that insertion cannot shift box chrome onto the next row.
@@ -1050,7 +1081,7 @@ export class Editor implements Component, Focusable {
 						const hintText = hintStyle(truncateToWidth(inlineHint, availWidth));
 						displayText = before + marker + hintText;
 						displayWidth += Math.min(visibleWidth(inlineHint), availWidth);
-					} else if (after.length === 0 && !borderVisible && displayWidth >= lineContentWidth) {
+					} else if (after.length === 0 && !isSideBordered && displayWidth >= lineContentWidth) {
 						displayText = this.#renderTerminalCursorMarker(before, marker, lineContentWidth);
 					} else {
 						displayText = before + marker + after;
@@ -1076,7 +1107,7 @@ export class Editor implements Component, Focusable {
 				} else if (this.cursorOverride) {
 					// Cursor override replaces the normal end-of-text cursor glyph
 					const overrideWidth = this.cursorOverrideWidth ?? 1;
-					if (!borderVisible && displayWidth + overrideWidth > lineContentWidth) {
+					if (!isSideBordered && displayWidth + overrideWidth > lineContentWidth) {
 						// Borderless editors have no spare padding cell for an end-of-line cursor glyph.
 						// Preserve cursorOverride by replacing the tail of the line with it.
 						const widthLimitedCursor = this.#renderEndOfLineCursorAtWidthLimit(before, marker, lineContentWidth, {
@@ -1097,7 +1128,7 @@ export class Editor implements Component, Focusable {
 				} else {
 					// Cursor is at the end - add thin cursor glyph
 					const { text: cursor, width: cursorWidth } = this.#getStyledInputCursor();
-					if (!borderVisible && displayWidth + cursorWidth > lineContentWidth) {
+					if (!isSideBordered && displayWidth + cursorWidth > lineContentWidth) {
 						// Borderless editors have no spare padding cell for an end-of-line cursor glyph.
 						// Highlight the last grapheme so the cursor stays visible without consuming width.
 						const widthLimitedCursor = this.#renderEndOfLineCursorAtWidthLimit(before, marker, lineContentWidth);
@@ -1136,44 +1167,24 @@ export class Editor implements Component, Focusable {
 
 			const linePad = padding(Math.max(0, lineContentWidth - displayWidth));
 
-			if (!borderVisible) {
-				result.push(gutterText + displayText + linePad);
-				continue;
-			}
-
-			// All lines have consistent borders based on padding. When the end-of-line cursor
-			// glyph (or a wide trailing grapheme) extends past `lineContentWidth`, shrink the
-			// right chrome by the exact overflow count: drop padding spaces first, then the
-			// trailing `─`, but never the corner/vertical bar itself.
-			const isLastLine = visibleIndex === visibleLayoutLines.length - 1;
-			const rightChromeCells = Math.max(1, paddingX + 1 - cursorPaddingOverflow);
-			if (isLastLine && imeSafeCursorTail) {
-				const leftBorder = this.borderColor(`${box.vertical}${padding(paddingX)}`);
-				const bottomBorder = this.borderColor(
-					`${box.bottomLeft}${box.horizontal.repeat(Math.max(0, width - 2))}${box.bottomRight}`,
-				);
-				result.push(leftBorder + displayText);
-				result.push(bottomBorder);
-				continue;
-			}
-			if (isLastLine) {
-				const rightPad = Math.max(0, rightChromeCells - 2);
-				const includeHorizontal = rightChromeCells >= 2;
-				const bottomRightAdjusted = this.borderColor(
-					`${padding(rightPad)}${includeHorizontal ? box.horizontal : ""}${box.bottomRight}`,
-				);
-				result.push(`${bottomLeft}${displayText}${linePad}${bottomRightAdjusted}`);
-			} else {
-				const leftBorder = this.borderColor(`${box.vertical}${padding(paddingX)}`);
-				// When scrollbar is active, replace the right border vertical with a
-				// thumb glyph (█) on lines inside the thumb range, keeping the track (│) elsewhere.
-				const inThumb = scrollbarThumb && visibleIndex >= scrollbarThumb.start && visibleIndex < scrollbarThumb.end;
-				const rightGlyph = inThumb ? "█" : box.vertical;
-				const rightBorder = this.borderColor(`${padding(Math.max(0, rightChromeCells - 1))}${rightGlyph}`);
-				result.push(leftBorder + displayText + linePad + rightBorder);
-			}
+			result.push(
+				...style.renderRow({
+					...chromeCtx,
+					text: displayText,
+					pad: linePad,
+					gutter: gutterText,
+					isLastRow: visibleIndex === visibleLayoutLines.length - 1,
+					cursorOverflow: cursorPaddingOverflow,
+					imeSafeCursorTail,
+					scrollbarThumb:
+						scrollbarThumb !== null && visibleIndex >= scrollbarThumb.start && visibleIndex < scrollbarThumb.end,
+				}),
+			);
 		}
 
+		const bottomRow = style.renderBottom(chromeCtx);
+		if (bottomRow !== undefined) result.push(bottomRow);
+
 		// Add autocomplete list if active
 		if (this.#autocompleteState && this.#autocompleteList) {
 			const autocompleteResult = this.#autocompleteList.render(width);

package/src/components/settings-list.ts

@@ -20,6 +20,8 @@ export interface SettingItem {
 	label: string;
 	/** Optional description shown when selected */
 	description?: string;
+	/** Optional risk note shown in warning styling above the description, with a glyph on the row. */
+	warning?: string;
 	/** Current value to display (right side) */
 	currentValue: string;
 	/** If provided, Enter/Space cycles through these values */
@@ -36,6 +38,10 @@ export interface SettingsListTheme {
 	label: (text: string, selected: boolean, changed: boolean) => string;
 	value: (text: string, selected: boolean, changed: boolean) => string;
 	description: (text: string) => string;
+	/** Style for risk notes and the row warning glyph. Falls back to `description` when omitted. */
+	warning?: (text: string) => string;
+	/** Glyph marking rows that carry a `warning`. Omitted hides the row marker. */
+	warningMark?: string;
 	cursor: string;
 	hint: (text: string) => string;
 	/** Style for section heading rows (dimmed when outside the active section). Falls back to `hint` when omitted. */
@@ -78,12 +84,15 @@ export interface SettingsListOptions {
 	sidebarWidth?: number;
 }
 
-/** Searchable text for a setting item: label, id, value, description, and cycle values. */
+/** Searchable text for a setting item: label, id, value, description, warning, and cycle values. */
 export function getSettingItemFilterText(item: SettingItem): string {
 	let text = `${item.label} ${item.id} ${item.currentValue}`;
 	if (item.description) {
 		text += ` ${item.description}`;
 	}
+	if (item.warning) {
+		text += ` ${item.warning}`;
+	}
 	if (item.values) {
 		text += ` ${item.values.join(" ")}`;
 	}
@@ -477,6 +486,11 @@ export class SettingsList implements Component {
 		return this.#padLines(this.#renderMainList(width));
 	}
 
+	/** Warning glyph suffix for a row that carries a risk note, or "" when none applies. */
+	#warningMark(item: SettingItem): string {
+		return item.warning && this.#theme.warningMark ? ` ${this.#theme.warningMark}` : "";
+	}
+
 	#renderItemRow(
 		item: SettingItem,
 		index: number,
@@ -495,7 +509,9 @@ export class SettingsList implements Component {
 		const isSelected = index === this.#selectedIndex && !this.#sectionFocus;
 		const prefix = isSelected ? this.#theme.cursor : "  ";
 		const prefixWidth = visibleWidth(prefix);
-		const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+		const mark = this.#warningMark(item);
+		const labelPlain = item.label + mark;
+		const labelPad = padding(Math.max(0, maxLabelWidth - visibleWidth(labelPlain)));
 		const separator = "  ";
 		const valueMaxWidth = rowWidth - prefixWidth - maxLabelWidth - visibleWidth(separator) - 2;
 		const valuePlain = truncateToWidth(String(item.currentValue ?? ""), valueMaxWidth, Ellipsis.Omit);
@@ -504,11 +520,13 @@ export class SettingsList implements Component {
 		// under one dim wash so inner label/value colors don't fight it.
 		if (dimmed && !isSelected) {
 			const text = this.#theme.hint(
-				truncateToWidth(`  ${labelPadded}${separator}${valuePlain}`, Math.max(0, rowWidth)),
+				truncateToWidth(`  ${labelPlain}${labelPad}${separator}${valuePlain}`, Math.max(0, rowWidth)),
 			);
 			return hovered && this.#theme.hovered ? this.#theme.hovered(text) : text;
 		}
-		const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
+		const warningStyle = this.#theme.warning ?? this.#theme.description;
+		const labelText =
+			this.#theme.label(item.label, isSelected, item.changed === true) + (mark ? warningStyle(mark) : "") + labelPad;
 		const valueText = this.#theme.value(valuePlain, isSelected, item.changed === true);
 		const text = truncateToWidth(prefix + labelText + separator + valueText, Math.max(0, rowWidth));
 		// Pointer hover paints a band behind the whole row, distinct from the
@@ -550,7 +568,9 @@ export class SettingsList implements Component {
 				0,
 				Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#filteredItems.length - viewportHeight),
 			);
-			const labelWidths = this.#filteredItems.filter(item => !item.heading).map(item => visibleWidth(item.label));
+			const labelWidths = this.#filteredItems
+				.filter(item => !item.heading)
+				.map(item => visibleWidth(item.label + this.#warningMark(item)));
 			const maxLabelWidth = Math.min(30, labelWidths.length > 0 ? Math.max(...labelWidths) : 0);
 			const itemRowsOverflow = this.#filteredItems.length > viewportHeight;
 			const itemRowWidth = Math.max(0, width - (itemRowsOverflow ? 1 : 0));
@@ -589,15 +609,25 @@ export class SettingsList implements Component {
 
 		// Description area: 1 blank + exactly 3 rows, clamped with an ellipsis,
 		// so moving between items with/without descriptions never shifts rows.
+		// The risk note leads so it survives the clamp when both are present.
 		lines.push("");
 		const selectedItem = this.#filteredItems[this.#selectedIndex];
 		const descLines: string[] = [];
-		if (selectedItem?.description && !selectedItem.heading) {
-			const wrappedDesc = wrapTextWithAnsi(selectedItem.description, width - 4);
-			for (const line of wrappedDesc.slice(0, 3)) {
-				descLines.push(this.#theme.description(`  ${line}`));
+		if (selectedItem && !selectedItem.heading) {
+			if (selectedItem.warning) {
+				const warningStyle = this.#theme.warning ?? this.#theme.description;
+				const mark = this.#theme.warningMark ? `${this.#theme.warningMark} ` : "";
+				for (const line of wrapTextWithAnsi(`${mark}${selectedItem.warning}`, width - 4)) {
+					descLines.push(warningStyle(`  ${line}`));
+				}
+			}
+			if (selectedItem.description) {
+				for (const line of wrapTextWithAnsi(selectedItem.description, width - 4)) {
+					descLines.push(this.#theme.description(`  ${line}`));
+				}
 			}
-			if (wrappedDesc.length > 3) {
+			if (descLines.length > 3) {
+				descLines.splice(3);
 				descLines[2] = truncateToWidth(`${descLines[2]}…`, width);
 			}
 		}
@@ -659,7 +689,9 @@ export class SettingsList implements Component {
 			Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#filteredItems.length - viewportHeight),
 		);
 		// Label column width spans all items so the layout stays stable across sections.
-		const labelWidths = this.#filteredItems.filter(item => !item.heading).map(item => visibleWidth(item.label));
+		const labelWidths = this.#filteredItems
+			.filter(item => !item.heading)
+			.map(item => visibleWidth(item.label + this.#warningMark(item)));
 		const maxLabelWidth = Math.min(30, labelWidths.length > 0 ? Math.max(...labelWidths) : 0);
 		const overflow = this.#filteredItems.length > viewportHeight;
 		const rowWidth = Math.max(0, paneWidth - (overflow ? 1 : 0));

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./autocomplete";
 // Components
 export * from "./components/box";
 export * from "./components/cancellable-loader";
+export * from "./components/composer";
 export * from "./components/editor";
 export * from "./components/image";
 export * from "./components/input";