xonecas.io
64875
Mc

mini-coder / commit c304c51

feat: better help text, minor ux tweaks

xonecas2026-04-16 c304c51f2914e72c3dc7aea4891322eddb331962 parent ff7c9d1

12 files changed

spec.md+1−1
@@ -563,7 +563,7 @@ Tool blocks share a common frame: a left border (`│`) plus a compact header pi
563563 - **Tool calls — todoWrite / todoRead**: rendered in the shared tool frame. Successful results render the full current todo list as a structured themed checklist with status markers (`[ ]`, `[~]`, `[x]`). This checklist is always shown in full and never truncated, regardless of `/verbose`. Errors render the returned error text.
564564 - **Tool calls — readImage**: rendered in the shared tool frame. The assistant tool call streams the path as it arrives. Successful results render a compact result block (`read image <-` plus the file path) rather than rendering the image itself.
565565 - **Tool calls — plugin tools**: rendered in the shared tool frame, prefixed with plugin/tool name when available.
566-- **UI messages**: internal app messages such as `/help` output, OAuth progress, `/fork` notices, and other session-local notices. They are rendered in the conversation log, persisted with the session, excluded from model context, and do not participate in conversational turn numbering. `/todo` output is also UI-only, but it renders using the same structured todo-checklist block as todo tool results instead of plain info text.
566+- **UI messages**: internal app messages such as `/help` output, OAuth progress, `/fork` notices, and other session-local notices. They are rendered in the conversation log, persisted with the session, excluded from model context, and do not participate in conversational turn numbering. `/help` output renders as syntax-highlighted raw markdown so headings, lists, and inline code stay scannable while preserving the literal markdown markers. `/todo` output is also UI-only, but it renders using the …
567567 - **Errors**: one-line summary, styled distinctly.
568568
569569 #### Verbose tool rendering
src/input.ts+1−1
@@ -17,7 +17,6 @@ import { extname, isAbsolute, join } from "node:path";
1717
1818 /** All recognized slash commands. */
1919 export const COMMANDS = [
20- "model",
2120 "session",
2221 "new",
2322 "fork",
@@ -28,6 +27,7 @@ export const COMMANDS = [
2827 "login",
2928 "logout",
3029 "help",
30+ "model",
3131 "effort",
3232 ] as const;
3333
src/session.test.ts+12−0
@@ -317,6 +317,18 @@ describe("message persistence and turn numbering", () => {
317317 db.close();
318318 });
319319
320+ test("loadMessages round-trips markdown-formatted UI info messages", () => {
321+ const db = openDatabase(":memory:");
322+ const session = createSession(db, { cwd: "/tmp/test" });
323+ const uiMessage = createUiMessage("# Help", "markdown");
324+
325+ appendMessage(db, session.id, uiMessage);
326+
327+ const msgs = loadMessages(db, session.id);
328+ expect(msgs).toEqual([uiMessage]);
329+ db.close();
330+ });
331+
320332 test("loadMessages skips invalid persisted rows and keeps valid messages", () => {
321333 const db = openDatabase(":memory:");
322334 const session = createSession(db, { cwd: "/tmp/test" });
src/session.ts+15−2
@@ -95,6 +95,9 @@ interface AppendPromptHistoryOpts {
9595 sessionId?: string;
9696 }
9797
98+/** Rich-text format hints supported by persisted UI info messages. */
99+export type UiInfoFormat = "markdown";
100+
98101 /** A persisted UI-only info message shown in the conversation log. */
99102 export interface UiInfoMessage {
100103 /** Identifies this as an internal UI message. */
@@ -103,6 +106,8 @@ export interface UiInfoMessage {
103106 kind: "info";
104107 /** Display text shown in the conversation log. */
105108 content: string;
109+ /** Optional rich-text format hint for the content. */
110+ format?: UiInfoFormat;
106111 /** Unix timestamp in milliseconds. */
107112 timestamp: number;
108113 }
@@ -513,7 +518,10 @@ function isUiMessageRecord(value: unknown): value is UiMessage {
513518 }
514519
515520 if (record.kind === "info") {
516- return typeof record.content === "string";
521+ return (
522+ typeof record.content === "string" &&
523+ (record.format === undefined || record.format === "markdown")
524+ );
517525 }
518526
519527 return (
@@ -629,13 +637,18 @@ export function truncateSessions(
629637 * Create a persisted UI info message.
630638 *
631639 * @param content - Display text shown in the conversation log.
640+ * @param format - Optional rich-text format hint for the content.
632641 * @returns A new {@link UiInfoMessage}.
633642 */
634-export function createUiMessage(content: string): UiInfoMessage {
643+export function createUiMessage(
644+ content: string,
645+ format?: UiInfoFormat,
646+): UiInfoMessage {
635647 return {
636648 role: "ui",
637649 kind: "info",
638650 content,
651+ ...(format ? { format } : {}),
639652 timestamp: Date.now(),
640653 };
641654 }
src/ui.test.ts+2−1
@@ -733,7 +733,8 @@ describe("ui rendering", () => {
733733 expect(countSessions(state)).toBe(0);
734734 expect(state.messages).toHaveLength(1);
735735 expect(state.messages[0]?.role).toBe("ui");
736- expect(logText.some((line) => line.includes("Commands:"))).toBe(true);
736+ expect(logText.some((line) => line.includes("# Help"))).toBe(true);
737+ expect(logText.some((line) => line.includes("## Commands"))).toBe(true);
737738 } finally {
738739 state.db.close();
739740 }
src/ui.ts+8−2
@@ -26,6 +26,7 @@ import {
2626 appendMessage,
2727 createUiMessage,
2828 createUiTodoMessage,
29+ type UiInfoFormat,
2930 } from "./session.ts";
3031 import type { Theme } from "./theme.ts";
3132 import {
@@ -660,9 +661,14 @@ function appendUiMessage(
660661 *
661662 * @param text - Display text to append.
662663 * @param state - Application state.
664+ * @param format - Optional rich-text format hint for the content.
663665 */
664-function appendInfoMessage(text: string, state: AppState): void {
665- appendUiMessage(createUiMessage(text), state);
666+function appendInfoMessage(
667+ text: string,
668+ state: AppState,
669+ format?: UiInfoFormat,
670+): void {
671+ appendUiMessage(createUiMessage(text, format), state);
666672 }
667673
668674 /**
src/ui/commands.test.ts+38−0
@@ -520,6 +520,44 @@ describe("ui/commands", () => {
520520 }
521521 });
522522
523+ test("/help appends markdown help without creating a session", () => {
524+ const state = createTestState();
525+ const appended: Array<{
526+ text: string;
527+ format: string | undefined;
528+ sessionId: string | null;
529+ }> = [];
530+ const controller = createCommandController({
531+ openOverlay: () => {},
532+ dismissOverlay: () => {},
533+ setInputValue: () => {},
534+ appendInfoMessage: (text, nextState, format) => {
535+ appended.push({
536+ text,
537+ format,
538+ sessionId: nextState.session?.id ?? null,
539+ });
540+ },
541+ appendTodoMessage: () => {},
542+ scrollConversationToBottom: () => {},
543+ render: () => {},
544+ reloadPromptContext: async () => {},
545+ openInBrowser: () => {},
546+ });
547+
548+ try {
549+ expect(controller.handleCommand("help", state)).toBe(true);
550+ expect(appended).toHaveLength(1);
551+ expect(appended[0]?.text).toContain("# Help");
552+ expect(appended[0]?.text).toContain("## Commands");
553+ expect(appended[0]?.format).toBe("markdown");
554+ expect(appended[0]?.sessionId).toBeNull();
555+ expect(state.session).toBeNull();
556+ } finally {
557+ state.db.close();
558+ }
559+ });
560+
523561 test("/todo appends the current todo list without creating a session", () => {
524562 const state = createTestState();
525563 state.messages = [
src/ui/commands.ts+7−2
@@ -26,6 +26,7 @@ import {
2626 listSessions,
2727 loadMessages,
2828 type SessionListEntry,
29+ type UiInfoFormat,
2930 undoLastTurn,
3031 } from "../session.ts";
3132 import { updateSettings } from "../settings.ts";
@@ -51,7 +52,11 @@ interface UiCommandRuntime {
5152 /** Update the current input draft. */
5253 setInputValue: (value: string) => void;
5354 /** Append a UI-only info message to the conversation log. */
54- appendInfoMessage: (text: string, state: AppState) => void;
55+ appendInfoMessage: (
56+ text: string,
57+ state: AppState,
58+ format?: UiInfoFormat,
59+ ) => void;
5560 /** Append a UI-only todo snapshot to the conversation log. */
5661 appendTodoMessage: (
5762 todos: ReturnType<typeof getTodoItems>,
@@ -583,7 +588,7 @@ export function createCommandController(
583588 };
584589
585590 const handleHelpCommand = (state: AppState): void => {
586- runtime.appendInfoMessage(buildHelpText(state), state);
591+ runtime.appendInfoMessage(buildHelpText(state), state, "markdown");
587592 };
588593
589594 const handleTodoCommand = (state: AppState): void => {
src/ui/conversation.test.ts+51−0
@@ -1372,6 +1372,57 @@ describe("ui/conversation", () => {
13721372 expect(text.some((line) => line.startsWith("And "))).toBe(false);
13731373 });
13741374
1375+ test("buildConversationLogNodes syntax-highlights markdown-formatted UI info messages", async () => {
1376+ const theme = {
1377+ ...DEFAULT_THEME,
1378+ accentText: "color14",
1379+ secondaryAccentText: "color09",
1380+ diffAdded: "color10",
1381+ } satisfies typeof DEFAULT_THEME;
1382+ const state = {
1383+ messages: [
1384+ {
1385+ role: "ui" as const,
1386+ kind: "info" as const,
1387+ format: "markdown" as const,
1388+ content: "# Help\n\n## Commands\n\n- `/model` — Select a model",
1389+ timestamp: 1,
1390+ },
1391+ ],
1392+ showReasoning: false,
1393+ verbose: false,
1394+ theme,
1395+ };
1396+
1397+ const rows = await renderBufferRows(
1398+ VStack(
1399+ {},
1400+ buildConversationLogNodes(
1401+ state,
1402+ { isStreaming: false, content: [], pendingToolResults: [] },
1403+ 0,
1404+ PREVIEW_WIDTH,
1405+ ),
1406+ ),
1407+ PREVIEW_WIDTH,
1408+ 24,
1409+ );
1410+ const headingRow = rows.find((row) => row.text.includes("# Help"));
1411+ const bulletRow = rows.find((row) => row.text.includes("- `/model`"));
1412+
1413+ expect(headingRow).toBeDefined();
1414+ expect(bulletRow).toBeDefined();
1415+ expect(headingRow?.fgColors[headingRow.text.indexOf("#")]).toBe(
1416+ theme.accentText ?? null,
1417+ );
1418+ expect(bulletRow?.fgColors[bulletRow.text.indexOf("-")]).toBe(
1419+ theme.secondaryAccentText ?? null,
1420+ );
1421+ expect(bulletRow?.fgColors[bulletRow.text.indexOf("`")]).toBe(
1422+ theme.diffAdded ?? null,
1423+ );
1424+ });
1425+
13751426 test("buildConversationLogNodes renders UI todo messages with the shared checklist block", async () => {
13761427 const state = {
13771428 messages: [
src/ui/conversation.ts+18−4
@@ -1161,14 +1161,28 @@ function renderUiTodoMessage(
11611161 }
11621162
11631163 /** Render an internal UI message in the conversation log. */
1164-function renderUiMessage(msg: UiMessage, theme: Theme): Node {
1164+function renderUiMessage(
1165+ msg: UiMessage,
1166+ opts: Pick<ConversationRenderOpts, "previewWidth" | "theme">,
1167+): Node {
11651168 if (msg.kind === "todo") {
1166- return renderUiTodoMessage(msg, theme);
1169+ return renderUiTodoMessage(msg, opts.theme);
1170+ }
1171+
1172+ if (msg.format === "markdown") {
1173+ const markdown = renderMarkdownTextBlock(
1174+ msg.content,
1175+ opts.theme,
1176+ opts.previewWidth,
1177+ );
1178+ if (markdown) {
1179+ return markdown;
1180+ }
11671181 }
11681182
11691183 return VStack({ padding: { x: 1 } }, [
11701184 Text(msg.content, {
1171- fgColor: theme.mutedText,
1185+ fgColor: opts.theme.mutedText,
11721186 italic: true,
11731187 wrap: "word",
11741188 }),
@@ -1231,7 +1245,7 @@ function renderConversationMessage(
12311245 theme: Theme,
12321246 ): Node | null {
12331247 if (message.role === "ui") {
1234- return renderUiMessage(message, theme);
1248+ return renderUiMessage(message, renderOpts);
12351249 }
12361250 if (message.role === "user") {
12371251 return renderUserMessage(message, theme);
src/ui/help.test.ts+23−8
@@ -3,7 +3,7 @@ import { DEFAULT_SHOW_REASONING } from "../settings.ts";
33 import { buildHelpText, type HelpRenderState } from "./help.ts";
44
55 describe("ui/help", () => {
6- test("buildHelpText includes current reasoning and verbose state", () => {
6+ test("buildHelpText formats commands as markdown list items with current state", () => {
77 const helpState: HelpRenderState = {
88 providers: new Map(),
99 model: null,
@@ -16,16 +16,18 @@ describe("ui/help", () => {
1616
1717 const text = buildHelpText(helpState);
1818
19+ expect(text).toContain("# Help");
20+ expect(text).toContain("## Commands");
1921 expect(text).toContain(
20- `/reasoning Toggle thinking display (currently ${DEFAULT_SHOW_REASONING ? "on" : "off"})`,
22+ `- \`/reasoning\` — Toggle thinking display _(currently ${DEFAULT_SHOW_REASONING ? "on" : "off"})_`,
2123 );
2224 expect(text).toContain(
23- "/verbose Toggle verbose tool rendering (currently off)",
25+ "- `/verbose` — Toggle verbose tool rendering _(currently off)_",
2426 );
25- expect(text).toContain("/todo Show the current todo list");
27+ expect(text).toContain("- `/todo` — Show the current todo list");
2628 });
2729
28- test("buildHelpText describes the current Escape behavior", () => {
30+ test("buildHelpText lists the supported keyboard shortcuts in markdown", () => {
2931 const helpState: HelpRenderState = {
3032 providers: new Map(),
3133 model: null,
@@ -38,13 +40,26 @@ describe("ui/help", () => {
3840
3941 const text = buildHelpText(helpState);
4042
43+ expect(text).toContain("## Keyboard");
44+ expect(text).toContain("- `Enter` submits the current draft.");
45+ expect(text).toContain("- `Shift+Enter` inserts a newline.");
4146 expect(text).toContain(
42- "Escape closes the current overlay and returns focus to the input",
47+ "- `Tab` opens command autocomplete when the draft starts with `/`.",
4348 );
4449 expect(text).toContain(
45- "With no overlay open, Escape interrupts the current turn",
50+ "- Otherwise, `Tab` autocompletes file paths and can open a path picker when there are multiple matches.",
4651 );
47- expect(text).toContain("Otherwise Escape does nothing");
52+ expect(text).toContain("- `Ctrl+R` opens global input history search.");
53+ expect(text).toContain(
54+ "- `Escape` closes the current overlay and returns focus to the input.",
55+ );
56+ expect(text).toContain(
57+ "- With no overlay open, `Escape` interrupts the current turn.",
58+ );
59+ expect(text).toContain("- Otherwise, `Escape` does nothing.");
60+ expect(text).toContain("- `Ctrl+C` exits gracefully.");
61+ expect(text).toContain("- `Ctrl+D` exits when the input is empty.");
62+ expect(text).toContain("- `Ctrl+Z` suspends the app to the background.");
4863 expect(text).not.toContain("Escape blurs the input first");
4964 });
5065 });
src/ui/help.ts+47−33
@@ -47,7 +47,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
4747 *
4848 * @param command - Command name.
4949 * @param state - Help-relevant application state.
50- * @returns Human-readable command description.
50+ * @returns Markdown-ready command description.
5151 */
5252 function getHelpCommandDescription(
5353 command: (typeof COMMANDS)[number],
@@ -55,72 +55,86 @@ function getHelpCommandDescription(
5555 ): string {
5656 const description = COMMAND_DESCRIPTIONS[command] ?? "";
5757 if (command === "reasoning") {
58- return `${description} (currently ${state.showReasoning ? "on" : "off"})`;
58+ return `${description} _(currently ${state.showReasoning ? "on" : "off"})_`;
5959 }
6060 if (command === "verbose") {
61- return `${description} (currently ${state.verbose ? "on" : "off"})`;
61+ return `${description} _(currently ${state.verbose ? "on" : "off"})_`;
6262 }
6363 return description;
6464 }
6565
66+function formatInlineCode(text: string): string {
67+ return `\`${text}\``;
68+}
69+
70+function formatInlineCodeList(items: readonly string[]): string {
71+ return items.map((item) => formatInlineCode(item)).join(", ");
72+}
73+
6674 /**
6775 * Build the `/help` text shown in the conversation log.
6876 *
6977 * @param state - Help-relevant application state.
70- * @returns Multi-line help text for display.
78+ * @returns Multi-line markdown help text for display.
7179 */
7280 export function buildHelpText(state: HelpRenderState): string {
73- const lines: string[] = [];
81+ const lines: string[] = ["# Help", "", "## Commands", ""];
7482
75- lines.push("Commands:");
7683 for (const command of COMMANDS) {
77- lines.push(` /${command} ${getHelpCommandDescription(command, state)}`);
84+ lines.push(
85+ `- ${formatInlineCode(`/${command}`)} — ${getHelpCommandDescription(command, state)}`,
86+ );
7887 }
7988
8089 const providerNames = Array.from(state.providers.keys());
81- lines.push("");
82- lines.push("Note:");
83- lines.push(
84- " Escape closes the current overlay and returns focus to the input.",
85- );
86- lines.push(" With no overlay open, Escape interrupts the current turn.");
87- lines.push(" Otherwise Escape does nothing.");
88-
89- lines.push("");
9090 lines.push(
91+ "",
92+ "## Keyboard",
93+ "",
94+ "- `Enter` submits the current draft.",
95+ "- `Shift+Enter` inserts a newline.",
96+ "- `Tab` opens command autocomplete when the draft starts with `/`.",
97+ "- Otherwise, `Tab` autocompletes file paths and can open a path picker when there are multiple matches.",
98+ "- `Ctrl+R` opens global input history search.",
99+ "- `Escape` closes the current overlay and returns focus to the input.",
100+ "- With no overlay open, `Escape` interrupts the current turn.",
101+ "- Otherwise, `Escape` does nothing.",
102+ "- `Ctrl+C` exits gracefully.",
103+ "- `Ctrl+D` exits when the input is empty.",
104+ "- `Ctrl+Z` suspends the app to the background.",
105+ "",
106+ "## Current state",
107+ "",
91108 providerNames.length > 0
92- ? `Providers: ${providerNames.join(", ")}`
93- : "Providers: none (use /login)",
94- );
95-
96- lines.push(
109+ ? `- Providers: ${formatInlineCodeList(providerNames)}`
110+ : "- Providers: none — use `/login`",
97111 state.model
98- ? `Model: ${state.model.provider}/${state.model.id}`
99- : "Model: none (use /model)",
112+ ? `- Model: ${formatInlineCode(`${state.model.provider}/${state.model.id}`)}`
113+ : "- Model: none — use `/model`",
100114 );
101115
102116 if (state.agentsMd.length > 0) {
103- lines.push("");
104- lines.push("AGENTS.md files:");
117+ lines.push("", "## Loaded `AGENTS.md` files", "");
105118 for (const agentFile of state.agentsMd) {
106- lines.push(` ${abbreviatePath(agentFile.path)}`);
119+ lines.push(`- ${formatInlineCode(abbreviatePath(agentFile.path))}`);
107120 }
108121 }
109122
110123 if (state.skills.length > 0) {
111- lines.push("");
112- lines.push("Skills:");
124+ lines.push("", "## Skills", "");
113125 for (const skill of state.skills) {
114- const description = skill.description ? ` ${skill.description}` : "";
115- lines.push(` ${skill.name}${description}`);
126+ lines.push(
127+ skill.description
128+ ? `- ${formatInlineCode(skill.name)} — ${skill.description}`
129+ : `- ${formatInlineCode(skill.name)}`,
130+ );
116131 }
117132 }
118133
119134 if (state.plugins.length > 0) {
120- lines.push("");
121- lines.push("Plugins:");
135+ lines.push("", "## Plugins", "");
122136 for (const plugin of state.plugins) {
123- lines.push(` ${plugin.entry.name}`);
137+ lines.push(`- ${formatInlineCode(plugin.entry.name)}`);
124138 }
125139 }