feat(tui): render mermaid code blocks as diagrams in the terminal (#3851)

Author: Grapedge

.agents/skills/write-tui/SKILL.md

@@ -23,7 +23,7 @@ For any list dialog, selector, input box, or status/toggle list, the interaction
   - `editor-keyboard.ts` — editor keyboard handling, exit shortcuts, external editor, clipboard image.
   - `auth-flow.ts` — login/auth orchestration (`refreshConfigAfterLogin`, etc.).
 - `src/tui/commands/` — slash-command declaration, parsing, ordering, and dynamic skill-command generation. Parsing and types only; execution is dispatched from `KimiTUI`'s slash-command handler section, and complex execution sinks into `utils` or focused components.
-- `src/tui/components/` — pi-tui components by UI type: `chrome/` (footer, todo, welcome, loader, device code), `dialogs/` (selectors, approval/question panels, settings popups that replace the editor), `editor/` (input box + mention provider), `media/` (image, diff, code highlight), `messages/` (transcript blocks + tool-renderers), `panes/` (activity, queue).
+- `src/tui/components/` — pi-tui components by UI type: `chrome/` (footer, todo, welcome, loader, device code), `dialogs/` (selectors, approval/question panels, settings popups that replace the editor), `editor/` (input box + mention provider), `media/` (image, diff, code highlight), `markdown/` (the app's Markdown wrapper and mermaid art), `messages/` (transcript blocks + tool-renderers), `panes/` (activity, queue).
 - `src/tui/reverse-rpc/` — adapts SDK approval/question callbacks into UI panel data and the user's choice back into an SDK response.
 - `src/tui/theme/` — themes, color tokens, style helpers, pi-tui markdown theme, terminal-background detection. The single source of truth for color.
 - `src/tui/utils/` — TUI-only utilities (need `TUIState` or a component). App-wide, UI-independent helpers go in `src/utils/`.

.changeset/tui-mermaid-diagrams.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Render mermaid code blocks as diagrams in the terminal; turn it off under /settings → Mermaid diagrams, or set `mermaid = "off"` in the `[markdown]` section of tui.toml.

apps/kimi-code/package.json

@@ -102,6 +102,7 @@
     "cli-highlight": "^2.1.11",
     "commander": "^13.1.0",
     "jimp": "^1.6.1",
+    "lovely-mermaid": "0.3.3",
     "pathe": "^2.0.3",
     "postject": "1.0.0-alpha.6",
     "semver": "^7.7.4",

apps/kimi-code/src/tui/commands/config.ts

@@ -15,18 +15,20 @@ import {
   ExperimentsSelectorComponent,
   type ExperimentalFeatureDraftChange,
 } from '../components/dialogs/experiments-selector';
+import { MermaidPreferenceSelectorComponent } from '../components/dialogs/mermaid-preference-selector';
 import { modelDisplayName, segmentsFor } from '../components/dialogs/model-selector';
 import { TabbedModelSelectorComponent } from '../components/dialogs/tabbed-model-selector';
 import { PermissionSelectorComponent } from '../components/dialogs/permission-selector';
 import { SettingsSelectorComponent, type SettingsSelection } from '../components/dialogs/settings-selector';
 import { SurveyPreferenceSelectorComponent } from '../components/dialogs/survey-preference-selector';
 import { ThemeSelectorComponent } from '../components/dialogs/theme-selector';
 import { UpdatePreferenceSelectorComponent } from '../components/dialogs/update-preference-selector';
-import { DEFAULT_TUI_CONFIG, saveTuiConfig, type TuiConfig } from '../config';
+import { DEFAULT_MARKDOWN_CONFIG, DEFAULT_TUI_CONFIG, saveTuiConfig, type MarkdownConfig, type TuiConfig } from '../config';
 import type { ThemeName } from '#/tui/theme';
 import { currentTheme, isBuiltInTheme, lightColors, loadCustomThemeMerged } from '#/tui/theme';
 import { NO_ACTIVE_SESSION_MESSAGE } from '../constant/kimi-tui';
 import { formatErrorMessage } from '../utils/event-payload';
+import { setMarkdownMermaidMode, type MermaidRenderMode } from '../utils/markdown-options';
 import { PERMISSION_MODE_DESCRIPTIONS, PERMISSION_MODE_DISPLAY_NAMES } from '../utils/permission-mode';
 import { thinkingEffortToConfig } from '../utils/thinking-config';
 import { showUsage } from './info';
@@ -66,6 +68,7 @@ export function currentTuiConfig(host: Pick<SlashCommandHost, 'state'>): TuiConf
     notifications: host.state.appState.notifications,
     upgrade: host.state.appState.upgrade,
     statusLine: host.state.appState.statusLine ?? DEFAULT_TUI_CONFIG.statusLine,
+    markdown: host.state.appState.markdown ?? DEFAULT_MARKDOWN_CONFIG,
   };
 }
 
@@ -884,6 +887,65 @@ export async function applySurveyPreferenceChoice(
   host.showStatus(`Feedback survey ${enabled ? 'enabled' : 'disabled'}.`);
 }
 
+export function showMermaidPreferencePicker(host: SlashCommandHost): void {
+  host.mountEditorReplacement(
+    new MermaidPreferenceSelectorComponent({
+      currentValue: host.state.appState.markdown?.mermaid !== 'off',
+      onSelect: (value) => {
+        host.restoreEditor();
+        void applyMermaidPreferenceChoice(host, value);
+      },
+      onCancel: () => {
+        host.restoreEditor();
+      },
+    }),
+  );
+}
+
+type MermaidPreferenceHost = {
+  readonly state: {
+    readonly appState: Pick<
+      SlashCommandHost['state']['appState'],
+      'theme' | 'editorCommand' | 'notifications' | 'upgrade' | 'markdown'
+    >;
+    readonly transcriptContainer: { invalidate(): void };
+    readonly ui: { requestRender(force?: boolean): void };
+  };
+  setAppState(patch: Pick<SlashCommandHost['state']['appState'], 'markdown'>): void;
+  showStatus(msg: string, color?: string): void;
+};
+
+export async function applyMermaidPreferenceChoice(
+  host: MermaidPreferenceHost,
+  enabled: boolean,
+): Promise<void> {
+  const mermaid: MermaidRenderMode = enabled ? 'final' : 'off';
+  if (mermaid === (host.state.appState.markdown?.mermaid ?? DEFAULT_MARKDOWN_CONFIG.mermaid)) {
+    host.showStatus(`Mermaid diagrams already ${enabled ? 'enabled' : 'disabled'}.`);
+    return;
+  }
+
+  const markdown: MarkdownConfig = { mermaid };
+  try {
+    await saveTuiConfig({
+      ...currentTuiConfig(host as unknown as SlashCommandHost),
+      markdown,
+    });
+  } catch (error) {
+    host.showStatus(
+      `Failed to save mermaid diagram setting: ${formatErrorMessage(error)}`,
+      'error',
+    );
+    return;
+  }
+
+  setMarkdownMermaidMode(mermaid);
+  host.setAppState({ markdown });
+  host.state.transcriptContainer.invalidate();
+  host.state.ui.requestRender(true);
+  host.showStatus(`Mermaid diagrams ${enabled ? 'enabled' : 'disabled'}.`);
+}
+
 export function showSettingsSelector(host: SlashCommandHost): void {
   host.mountEditorReplacement(
     new SettingsSelectorComponent({
@@ -903,6 +965,7 @@ function handleSettingsSelection(host: SlashCommandHost, value: SettingsSelectio
     case 'model': showModelPicker(host); return;
     case 'permission': showPermissionPicker(host); return;
     case 'theme': showThemePicker(host); return;
+    case 'mermaid': showMermaidPreferencePicker(host); return;
     case 'editor': showEditorPicker(host); return;
     case 'survey': showSurveyPreferencePicker(host); return;
     case 'experiments': void showExperimentsPanel(host); return;

apps/kimi-code/src/tui/commands/plugins.ts

@@ -8,7 +8,9 @@ import {
   type PluginSummary,
   type Session,
 } from '@moonshot-ai/kimi-code-sdk';
-import { Markdown, Spacer } from '@moonshot-ai/pi-tui';
+import { Spacer } from '@moonshot-ai/pi-tui';
+
+import { Markdown } from '#/tui/components/markdown/markdown';
 
 import {
   PluginInstallTrustConfirmComponent,
@@ -592,7 +594,10 @@ async function installCapabilityFromPanel(
     host.showNotice(`${label} is installed.`);
     host.state.transcriptContainer.addChild(new Spacer(1));
     host.state.transcriptContainer.addChild(
-      new Markdown(WEBBRIDGE_POST_INSTALL_MARKDOWN, 2, 0, createMarkdownTheme(), undefined, createMarkdownOptions()),
+      new Markdown(WEBBRIDGE_POST_INSTALL_MARKDOWN, 2, 0, createMarkdownTheme(), undefined, {
+        ...createMarkdownOptions(),
+        copySource: true,
+      }),
     );
     host.state.ui.requestRender();
     return;

apps/kimi-code/src/tui/commands/reload.ts

@@ -1,8 +1,8 @@
 import type { KimiConfig } from '@moonshot-ai/kimi-code-sdk';
 
 import { currentTheme, lightColors } from '#/tui/theme';
-import { loadTuiConfig, type TuiConfig } from '../config';
-import { setMarkdownRenderLatex } from '../utils/markdown-options';
+import { DEFAULT_MARKDOWN_CONFIG, loadTuiConfig, type TuiConfig } from '../config';
+import { setMarkdownMermaidMode, setMarkdownRenderLatex } from '../utils/markdown-options';
 import type { SlashCommandHost } from './dispatch';
 import { setExperimentalFeatures } from './experimental-flags';
 
@@ -60,6 +60,7 @@ export async function applyReloadedTuiConfig(
   // transcript components, which rebuild their Markdown children and copy the
   // options at construction — so the new value must be live by then.
   setMarkdownRenderLatex(config.renderLatex ?? true);
+  setMarkdownMermaidMode(config.markdown?.mermaid ?? DEFAULT_MARKDOWN_CONFIG.mermaid);
   const resolved = config.theme === 'auto'
     ? (currentTheme.palette === lightColors ? 'light' : 'dark')
     : undefined;
@@ -74,6 +75,7 @@ export async function applyReloadedTuiConfig(
     notifications: config.notifications,
     upgrade: config.upgrade,
     statusLine: config.statusLine,
+    markdown: config.markdown,
   });
   host.state.editor.setDisablePasteBurst(config.disablePasteBurst);
 }

apps/kimi-code/src/tui/components/chrome/notify-panel.ts

@@ -14,9 +14,11 @@
  */
 
 import type { Component } from '@moonshot-ai/pi-tui';
-import { Markdown, truncateToWidth, visibleWidth } from '@moonshot-ai/pi-tui';
+import { truncateToWidth, visibleWidth } from '@moonshot-ai/pi-tui';
 import chalk from 'chalk';
 
+import { Markdown } from '#/tui/components/markdown/markdown';
+
 import { MAIN_AGENT_ID } from '#/tui/constant/kimi-tui';
 import { currentTheme } from '#/tui/theme';
 import { createMarkdownTheme } from '#/tui/theme/pi-tui-theme';

apps/kimi-code/src/tui/components/dialogs/mermaid-preference-selector.ts

@@ -0,0 +1,34 @@
+import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
+
+const MERMAID_PREFERENCE_OPTIONS: readonly ChoiceOption[] = [
+  {
+    value: 'on',
+    label: 'On',
+    description: 'Draw mermaid code blocks as diagrams in the terminal.',
+  },
+  {
+    value: 'off',
+    label: 'Off',
+    description: 'Keep mermaid code blocks as highlighted source.',
+  },
+];
+
+export interface MermaidPreferenceSelectorOptions {
+  readonly currentValue: boolean;
+  readonly onSelect: (value: boolean) => void;
+  readonly onCancel: () => void;
+}
+
+export class MermaidPreferenceSelectorComponent extends ChoicePickerComponent {
+  constructor(opts: MermaidPreferenceSelectorOptions) {
+    super({
+      title: 'Mermaid diagrams',
+      options: [...MERMAID_PREFERENCE_OPTIONS],
+      currentValue: opts.currentValue ? 'on' : 'off',
+      onSelect: (value) => {
+        opts.onSelect(value === 'on');
+      },
+      onCancel: opts.onCancel,
+    });
+  }
+}

apps/kimi-code/src/tui/components/dialogs/settings-selector.ts

@@ -3,6 +3,7 @@ import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
 export type SettingsSelection =
   | 'model'
   | 'theme'
+  | 'mermaid'
   | 'editor'
   | 'permission'
   | 'survey'
@@ -26,6 +27,11 @@ const SETTINGS_OPTIONS: readonly ChoiceOption[] = [
     label: 'Theme',
     description: 'Change the terminal UI theme.',
   },
+  {
+    value: 'mermaid',
+    label: 'Mermaid diagrams',
+    description: 'Draw mermaid code blocks as diagrams, or keep them as source.',
+  },
   {
     value: 'editor',
     label: 'Editor',
@@ -57,6 +63,7 @@ function isSettingsSelection(value: string): value is SettingsSelection {
   return (
     value === 'model' ||
     value === 'theme' ||
+    value === 'mermaid' ||
     value === 'editor' ||
     value === 'permission' ||
     value === 'survey' ||