@f5xc-salesdemos/xcsh 19.41.1 → 19.42.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "19.41.1",
+	"version": "19.42.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -39,6 +39,7 @@
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
+		"mermaid:gallery": "bun scripts/mermaid-gallery.ts",
 		"generate-docs-index": "bun scripts/generate-docs-index.ts",
 		"generate-api-spec-index": "bun scripts/generate-api-spec-index.ts",
 		"generate-branding-index": "bun scripts/generate-branding-index.ts",
@@ -51,13 +52,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "19.41.1",
-		"@f5xc-salesdemos/pi-agent-core": "19.41.1",
-		"@f5xc-salesdemos/pi-ai": "19.41.1",
-		"@f5xc-salesdemos/pi-natives": "19.41.1",
-		"@f5xc-salesdemos/pi-resource-management": "19.41.1",
-		"@f5xc-salesdemos/pi-tui": "19.41.1",
-		"@f5xc-salesdemos/pi-utils": "19.41.1",
+		"@f5xc-salesdemos/xcsh-stats": "19.42.1",
+		"@f5xc-salesdemos/pi-agent-core": "19.42.1",
+		"@f5xc-salesdemos/pi-ai": "19.42.1",
+		"@f5xc-salesdemos/pi-natives": "19.42.1",
+		"@f5xc-salesdemos/pi-resource-management": "19.42.1",
+		"@f5xc-salesdemos/pi-tui": "19.42.1",
+		"@f5xc-salesdemos/pi-utils": "19.42.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/mermaid-gallery.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env bun
+/**
+ * F5 XC Mermaid — visual gallery harness for human UAT.
+ *
+ * Renders the F5 Distributed Cloud mermaid sample library through the real
+ * display pipeline (themed per-role palette + per-node tint) so you can visually
+ * inspect the colorized output in your own terminal and give feedback.
+ *
+ * Usage:
+ *   bun scripts/mermaid-gallery.ts                       # all samples, dark theme, truecolor
+ *   bun scripts/mermaid-gallery.ts --theme light
+ *   bun scripts/mermaid-gallery.ts --color ansi256       # none | ansi256 | truecolor
+ *   bun scripts/mermaid-gallery.ts --ascii               # ASCII box chars instead of Unicode
+ *   bun scripts/mermaid-gallery.ts --type flowchart      # filter by diagram type
+ *   bun scripts/mermaid-gallery.ts --filter waf          # regex over id/category/prompt
+ *   bun scripts/mermaid-gallery.ts --list                # list samples, don't render
+ *
+ * Tip: pipe through `less -R` to page while keeping color.
+ */
+import type { MermaidColorMode } from "@f5xc-salesdemos/pi-utils";
+import { renderMermaidThemed } from "../src/modes/theme/mermaid-cache";
+import { getThemeByName } from "../src/modes/theme/theme";
+import { XC_MERMAID_SAMPLES, type XcMermaidSample } from "../test/fixtures/xc-mermaid-samples";
+
+interface Args {
+	theme: string;
+	color: MermaidColorMode;
+	ascii: boolean;
+	type?: string;
+	filter?: RegExp;
+	list: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+	const args: Args = { theme: "xcsh-dark", color: "truecolor", ascii: false, list: false };
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		const next = () => argv[++i] ?? "";
+		switch (a) {
+			case "--theme":
+				args.theme = next() === "light" ? "xcsh-light" : "xcsh-dark";
+				break;
+			case "--color":
+				args.color = next() as MermaidColorMode;
+				break;
+			case "--ascii":
+				args.ascii = true;
+				break;
+			case "--type":
+				args.type = next();
+				break;
+			case "--filter":
+				args.filter = new RegExp(next(), "i");
+				break;
+			case "--list":
+				args.list = true;
+				break;
+			case "--help":
+			case "-h":
+				console.log(
+					"bun scripts/mermaid-gallery.ts [--theme dark|light] [--color none|ansi256|truecolor] [--ascii] [--type <t>] [--filter <regex>] [--list]",
+				);
+				process.exit(0);
+		}
+	}
+	return args;
+}
+
+function selectSamples(args: Args): XcMermaidSample[] {
+	return XC_MERMAID_SAMPLES.filter(s => {
+		if (args.type && s.type !== args.type) return false;
+		if (args.filter && !args.filter.test(`${s.id} ${s.category} ${s.prompt}`)) return false;
+		return true;
+	});
+}
+
+async function main(): Promise<void> {
+	const args = parseArgs(process.argv.slice(2));
+	const theme = await getThemeByName(args.theme);
+	if (!theme) {
+		console.error(`Unknown theme: ${args.theme}`);
+		process.exit(1);
+	}
+	const samples = selectSamples(args);
+	const width = Math.min(process.stdout.columns ?? 100, 110);
+	const rule = (ch: string) => theme.fg("accent", ch.repeat(width));
+
+	console.log(`\n${rule("━")}`);
+	console.log(
+		theme.fg("mdHeading", "  F5 XC Mermaid Gallery") +
+			theme.fg(
+				"muted",
+				`   theme=${args.theme}  color=${args.color}  ascii=${args.ascii}  samples=${samples.length}`,
+			),
+	);
+	console.log(rule("━"));
+
+	if (args.list) {
+		for (const [i, s] of samples.entries()) {
+			console.log(
+				`  ${theme.fg("dim", String(i + 1).padStart(2, "0"))}  ` +
+					`${theme.fg("accent", s.type.padEnd(10))} ${theme.fg("mdHeading", s.id.padEnd(28))} ${theme.fg("muted", s.category)}`,
+			);
+		}
+		console.log("");
+		return;
+	}
+
+	for (const [i, s] of samples.entries()) {
+		console.log(
+			`\n${theme.fg("accent", "━━━")} ${theme.fg("dim", `[${i + 1}/${samples.length}]`)} ${theme.fg("mdHeading", s.category)} ${theme.fg("muted", "·")} ${theme.fg("success", s.type)} ${theme.fg("accent", "━".repeat(Math.max(0, width - s.category.length - s.type.length - 18)))}`,
+		);
+		console.log(`  ${theme.fg("dim", "▸")} ${theme.fg("mdLink", s.id)}`);
+		console.log(`  ${theme.fg("muted", `"${s.prompt}"`)}\n`);
+
+		const out = renderMermaidThemed(s.source, theme, { colorMode: args.color, render: { useAscii: args.ascii } });
+		if (out == null) {
+			console.log(`  ${theme.fg("error", "⚠ failed to render")}\n`);
+			continue;
+		}
+		for (const line of out.split("\n")) console.log(`  ${line}`);
+	}
+
+	console.log(`\n${rule("━")}`);
+	console.log(
+		theme.fg("muted", `  Rendered ${samples.length} sample(s). Inspect the colors above and note anything to tune `) +
+			theme.fg("dim", "(borders, labels, edges, arrows, per-node tints, contrast)."),
+	);
+	console.log(rule("━") + "\n");
+}
+
+await main();

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.41.1",
-	"commit": "0744c7f8bafe717d59be1fd3bc46fac5a79ba629",
-	"shortCommit": "0744c7f",
+	"version": "19.42.1",
+	"commit": "164a80d621b7e0c5f5e89bf9cd7caac2911eb764",
+	"shortCommit": "164a80d",
 	"branch": "main",
-	"tag": "v19.41.1",
-	"commitDate": "2026-06-23T18:52:47Z",
-	"buildDate": "2026-06-23T19:26:09.570Z",
+	"tag": "v19.42.1",
+	"commitDate": "2026-06-24T02:41:01Z",
+	"buildDate": "2026-06-24T03:11:24.436Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/0744c7f8bafe717d59be1fd3bc46fac5a79ba629",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.41.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/164a80d621b7e0c5f5e89bf9cd7caac2911eb764",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.42.1"
 };

package/src/modes/components/assistant-message.ts

@@ -2,7 +2,7 @@ import type { AssistantMessage, ImageContent, Usage } from "@f5xc-salesdemos/pi-
 import { Container, Image, ImageProtocol, Markdown, Spacer, TERMINAL, Text } from "@f5xc-salesdemos/pi-tui";
 import { formatNumber, logger } from "@f5xc-salesdemos/pi-utils";
 import { settings } from "../../config/settings";
-import { hasPendingMermaid, prerenderMermaid } from "../../modes/theme/mermaid-cache";
+import { hasPendingMermaid, mermaidThemeSignature, prerenderMermaid } from "../../modes/theme/mermaid-cache";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
 import { resolveImageOptions } from "../../tools/render-utils";
 
@@ -86,10 +86,14 @@ export class AssistantMessageComponent extends Container {
 		}
 	}
 	#triggerMermaidPrerender(message: AssistantMessage): void {
-		if (!TERMINAL.imageProtocol || this.#prerenderInFlight) return;
+		// ASCII/Unicode mermaid renders in any terminal — do NOT gate on image protocol.
+		if (this.#prerenderInFlight) return;
 
+		const sig = mermaidThemeSignature(theme);
 		// Check if any text content has pending mermaid blocks
-		const hasPending = message.content.some(c => c.type === "text" && c.text.trim() && hasPendingMermaid(c.text));
+		const hasPending = message.content.some(
+			c => c.type === "text" && c.text.trim() && hasPendingMermaid(c.text, sig),
+		);
 		if (!hasPending) return;
 
 		this.#prerenderInFlight = true;
@@ -98,8 +102,8 @@ export class AssistantMessageComponent extends Container {
 		void (async () => {
 			try {
 				for (const content of message.content) {
-					if (content.type === "text" && content.text.trim() && hasPendingMermaid(content.text)) {
-						prerenderMermaid(content.text);
+					if (content.type === "text" && content.text.trim() && hasPendingMermaid(content.text, sig)) {
+						prerenderMermaid(content.text, theme);
 					}
 				}
 			} catch (error) {

package/src/modes/theme/mermaid-cache.ts

@@ -1,44 +1,93 @@
-import { extractMermaidBlocks, logger, renderMermaidAsciiSafe } from "@f5xc-salesdemos/pi-utils";
+import {
+	extractMermaidBlocks,
+	logger,
+	type MermaidAsciiRenderOptions,
+	type MermaidColorMode,
+	mermaidSourceExceedsLimit,
+	pickColorMode,
+	renderMermaidAsciiSafe,
+	tintMermaidNodes,
+} from "@f5xc-salesdemos/pi-utils";
+import { buildMermaidAsciiTheme, buildNodeAccents } from "./mermaid-palette";
+import type { Theme } from "./theme";
 
-const cache = new Map<bigint | number, string | null>();
+// Keyed by `${sourceHash}|${themeSignature}` so a theme switch re-renders rather
+// than serving a stale, differently-colored diagram.
+const cache = new Map<string, string | null>();
 
 let onRenderNeeded: (() => void) | null = null;
 
-/**
- * Set callback to trigger TUI re-render when mermaid ASCII renders become available.
- */
+/** Set callback to trigger a TUI re-render when new mermaid renders become available. */
 export function setMermaidRenderCallback(callback: (() => void) | null): void {
 	onRenderNeeded = callback;
 }
 
-/**
- * Get a pre-rendered mermaid ASCII diagram by hash.
- * Returns null if not cached or rendering failed.
- */
-export function getMermaidAscii(hash: bigint | number): string | null {
-	return cache.get(hash) ?? null;
+function colorModeFor(theme: Theme, override?: MermaidColorMode): MermaidColorMode {
+	if (override) return override;
+	return pickColorMode({ noColor: Boolean(Bun.env.NO_COLOR), trueColor: theme.getColorMode() === "truecolor" });
+}
+
+function paletteSignature(theme: Theme): string {
+	return `${JSON.stringify(buildMermaidAsciiTheme(theme))}|${buildNodeAccents(theme).join(",")}`;
+}
+
+/** Stable signature identifying a theme's mermaid appearance — used for cache keying. */
+export function mermaidThemeSignature(theme: Theme): string {
+	return `${colorModeFor(theme)}:${paletteSignature(theme)}`;
+}
+
+export interface RenderMermaidThemedOptions {
+	/** Force a color mode (otherwise derived from the theme + NO_COLOR). */
+	colorMode?: MermaidColorMode;
+	/** Extra layout options (padding, useAscii, …). */
+	render?: MermaidAsciiRenderOptions;
 }
 
 /**
- * Render all mermaid blocks in markdown text.
- * Caches results and calls render callback when new diagrams are available.
+ * Render mermaid source to a themed, per-node-tinted ASCII/Unicode string.
+ * Applies the theme's per-role palette, then the best-effort node-tint pass.
+ * Result is memoized per (source, theme, colorMode). Returns null on parse failure.
  */
-export function prerenderMermaid(markdown: string): void {
+export function renderMermaidThemed(source: string, theme: Theme, opts?: RenderMermaidThemedOptions): string | null {
+	// Oversized graphs can hang the synchronous pathfinder for tens of seconds; skip
+	// them so the display falls back to the raw code block instead of freezing the UI.
+	if (mermaidSourceExceedsLimit(source)) return null;
+
+	const mode = colorModeFor(theme, opts?.colorMode);
+	// Layout options (useAscii, padding, …) change the output, so they must be part
+	// of the key. Omitted when absent so the key matches mermaidThemeSignature() —
+	// the no-options form used by the inline-markdown prerender/lookup path.
+	const optsSig = opts?.render && Object.keys(opts.render).length > 0 ? `|${JSON.stringify(opts.render)}` : "";
+	const key = `${Bun.hash(source.trim())}|${mode}:${paletteSignature(theme)}${optsSig}`;
+	const cached = cache.get(key);
+	if (cached !== undefined) return cached;
+
+	const asciiTheme = buildMermaidAsciiTheme(theme);
+	const colored = renderMermaidAsciiSafe(source, { ...opts?.render, colorMode: mode, theme: asciiTheme });
+	if (colored == null) {
+		cache.set(key, null);
+		return null;
+	}
+	const result = mode === "none" ? colored : tintMermaidNodes(colored.split("\n"), buildNodeAccents(theme)).join("\n");
+	cache.set(key, result);
+	return result;
+}
+
+/** Get a pre-rendered mermaid diagram by source hash + theme signature, or null. */
+export function getMermaidAscii(hash: bigint | number, themeSig: string): string | null {
+	return cache.get(`${hash}|${themeSig}`) ?? null;
+}
+
+/** Render and cache every mermaid block in `markdown` for the given theme. */
+export function prerenderMermaid(markdown: string, theme: Theme): void {
 	const blocks = extractMermaidBlocks(markdown);
 	if (blocks.length === 0) return;
 
+	const sig = mermaidThemeSignature(theme);
 	let hasNew = false;
-
 	for (const { source, hash } of blocks) {
-		if (cache.has(hash)) continue;
-
-		const ascii = renderMermaidAsciiSafe(source);
-		if (ascii) {
-			cache.set(hash, ascii);
-			hasNew = true;
-		} else {
-			cache.set(hash, null);
-		}
+		if (cache.has(`${hash}|${sig}`)) continue;
+		if (renderMermaidThemed(source, theme) != null) hasNew = true;
 	}
 
 	if (hasNew && onRenderNeeded) {
@@ -52,17 +101,13 @@ export function prerenderMermaid(markdown: string): void {
 	}
 }
 
-/**
- * Check if markdown contains mermaid blocks that aren't cached yet.
- */
-export function hasPendingMermaid(markdown: string): boolean {
+/** Check whether `markdown` has mermaid blocks not yet cached for this theme. */
+export function hasPendingMermaid(markdown: string, themeSig: string): boolean {
 	const blocks = extractMermaidBlocks(markdown);
-	return blocks.some(({ hash }) => !cache.has(hash));
+	return blocks.some(({ hash }) => !cache.has(`${hash}|${themeSig}`));
 }
 
-/**
- * Clear the mermaid cache.
- */
+/** Clear the mermaid cache. */
 export function clearMermaidCache(): void {
 	cache.clear();
 }

package/src/modes/theme/mermaid-palette.ts

@@ -0,0 +1,43 @@
+/**
+ * Map the active xcsh UI theme onto a mermaid `AsciiTheme` (per-role hues) and a
+ * cycling list of node-accent ANSI escapes for the per-node tint pass. Reading the
+ * theme keeps diagrams on-brand and dark/light adaptive.
+ */
+import type { MermaidAsciiRenderOptions } from "@f5xc-salesdemos/pi-utils";
+import type { Theme } from "./theme";
+
+type AsciiTheme = NonNullable<MermaidAsciiRenderOptions["theme"]>;
+
+/**
+ * Per-role color palette: red node borders, gold labels, blue edges, green
+ * arrowheads. These show through wherever the per-node tint pass doesn't apply
+ * (edges, arrows, subgraph frames, and as the fallback when tinting is skipped).
+ */
+export function buildMermaidAsciiTheme(theme: Theme): AsciiTheme {
+	return {
+		fg: theme.getFgHex("mdHeading", "#febc38"), // node/edge labels
+		border: theme.getFgHex("accent", "#ca260a"), // node + subgraph borders
+		line: theme.getFgHex("mdLink", "#0088fa"), // edge lines
+		arrow: theme.getFgHex("success", "#00ff88"), // arrowheads
+		corner: theme.getFgHex("mdLink", "#0088fa"),
+		junction: theme.getFgHex("accent", "#ca260a"),
+	};
+}
+
+/**
+ * ANSI foreground escapes cycled across detected node boxes so each node reads as
+ * a distinct hue. Drawn from vivid, well-separated theme roles.
+ */
+export function buildNodeAccents(theme: Theme): string[] {
+	const roles = ["chromeAccent", "success", "warning", "mdLink", "accent"] as const;
+	const seen = new Set<string>();
+	const accents: string[] = [];
+	for (const role of roles) {
+		const ansi = theme.getFgAnsi(role);
+		if (!seen.has(ansi)) {
+			seen.add(ansi);
+			accents.push(ansi);
+		}
+	}
+	return accents;
+}

package/src/modes/theme/theme.ts

@@ -16,7 +16,7 @@ import { TypeCompiler } from "@sinclair/typebox/compiler";
 import chalk from "chalk";
 // Embed theme JSON files at build time
 import { defaultThemes } from "./defaults";
-import { getMermaidAscii } from "./mermaid-cache";
+import { getMermaidAscii, mermaidThemeSignature } from "./mermaid-cache";
 
 export { getLanguageFromPath } from "../../utils/lang-from-path";
 
@@ -1316,6 +1316,7 @@ const langMap: Record<string, SymbolKey> = {
 
 export class Theme {
 	#fgColors: Record<ThemeColor, string>;
+	#fgHex: Partial<Record<ThemeColor, string>>;
 	#bgColors: Record<ThemeBg, string>;
 	#symbols: SymbolMap;
 
@@ -1327,8 +1328,12 @@ export class Theme {
 		symbolOverrides: Partial<Record<SymbolKey, string>>,
 	) {
 		this.#fgColors = {} as Record<ThemeColor, string>;
+		this.#fgHex = {};
 		for (const [key, value] of Object.entries(fgColors) as [ThemeColor, string | number][]) {
 			this.#fgColors[key] = fgAnsi(value, mode);
+			// Retain the raw hex (when the role resolves to one) for consumers that need
+			// a color value rather than an ANSI escape — e.g. the mermaid AsciiTheme.
+			if (typeof value === "string" && value.startsWith("#")) this.#fgHex[key] = value;
 		}
 		// gutterError remains optional — neither shipped theme carries it
 		this.#fgColors.gutterError ??= this.#fgColors.error;
@@ -1386,6 +1391,15 @@ export class Theme {
 		return ansi;
 	}
 
+	/**
+	 * Raw hex (e.g. "#ca260a") for a color role, for consumers that need a color
+	 * value rather than an ANSI escape (e.g. the mermaid AsciiTheme). Roles that
+	 * resolve to "" (default fg) or an ansi256 index yield `fallback`.
+	 */
+	getFgHex(color: ThemeColor, fallback = "#cccccc"): string {
+		return this.#fgHex[color] ?? fallback;
+	}
+
 	/** Convert a ThemeColor's fg ANSI code to a bg ANSI code (swap \x1b[38; → \x1b[48;). */
 	fgColorAsBg(color: ThemeColor): string {
 		return this.getFgAnsi(color).replace("\x1b[38;", "\x1b[48;");
@@ -2495,7 +2509,7 @@ export function getMarkdownTheme(): MarkdownTheme {
 		underline: (text: string) => theme.underline(text),
 		strikethrough: (text: string) => chalk.strikethrough(text),
 		symbols: getSymbolTheme(),
-		getMermaidAscii,
+		getMermaidAscii: (hash: bigint | number) => getMermaidAscii(hash, mermaidThemeSignature(theme)),
 		highlightCode: (code: string, lang?: string): string[] => {
 			const validLang = lang && nativeSupportsLanguage(lang) ? lang : undefined;
 			try {

package/src/tools/mermaid-renderer.ts

@@ -1,7 +1,9 @@
-/** TUI renderer for the render_mermaid tool — bordered ASCII diagram output. */
+/** TUI renderer for the render_mermaid tool — bordered, themed, colorized diagram output. */
 import type { Component } from "@f5xc-salesdemos/pi-tui";
 import { Text } from "@f5xc-salesdemos/pi-tui";
+import { detectDiagramType, type MermaidDiagramType } from "@f5xc-salesdemos/pi-utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { renderMermaidThemed } from "../modes/theme/mermaid-cache";
 import type { Theme } from "../modes/theme/theme";
 import { CachedOutputBlock, F5_TOOL_BORDER_COLOR, renderStatusLine } from "../tui";
 import type { RenderMermaidToolDetails } from "./render-mermaid";
@@ -10,6 +12,26 @@ import { addSection, formatErrorMessage, replaceTabs } from "./render-utils";
 const TOOL_TITLE = "Mermaid";
 const MAX_DIAGRAM_LINES = 40;
 
+/** Human-friendly caption for the diagram-type badge in the block header. */
+function diagramTypeLabel(type: MermaidDiagramType): string {
+	switch (type) {
+		case "flowchart":
+			return "flowchart";
+		case "sequence":
+			return "sequence diagram";
+		case "class":
+			return "class diagram";
+		case "er":
+			return "ER diagram";
+		case "state":
+			return "state diagram";
+		case "xychart":
+			return "xychart";
+		default:
+			return "diagram";
+	}
+}
+
 type MermaidRenderArgs = {
 	mermaid?: string;
 };
@@ -31,7 +53,7 @@ export const mermaidRenderer = {
 		},
 		options: RenderResultOptions,
 		uiTheme: Theme,
-		_args?: MermaidRenderArgs,
+		args?: MermaidRenderArgs,
 	): Component {
 		const isError = result.isError === true;
 
@@ -44,11 +66,18 @@ export const mermaidRenderer = {
 		const meta: string[] = [];
 		const rawText = result.content?.find(c => c.type === "text")?.text ?? "";
 
-		// Strip artifact reference from display
+		// Strip artifact reference from the plain result text (fallback path).
 		const artifactIdx = rawText.indexOf("\n\nSaved artifact:");
-		const diagramText = artifactIdx >= 0 ? rawText.slice(0, artifactIdx) : rawText;
+		const plainText = artifactIdx >= 0 ? rawText.slice(0, artifactIdx) : rawText;
+
+		// Prefer re-rendering from the original source: this yields the themed,
+		// per-role-colored, node-tinted diagram. Fall back to the plain result text.
+		const source = args?.mermaid?.trim();
+		const diagramText = (source ? renderMermaidThemed(source, uiTheme) : null) ?? plainText;
+		const caption = source ? diagramTypeLabel(detectDiagramType(source)) : "diagram";
 
-		const diagramLines = diagramText.split("\n").map(line => replaceTabs(uiTheme.fg("toolOutput", line)));
+		// Keep the diagram's own colors — do NOT recolor each line a flat tool color.
+		const diagramLines = diagramText.split("\n").map(line => replaceTabs(line));
 		addSection(sections, "Diagram", diagramLines, uiTheme, MAX_DIAGRAM_LINES);
 
 		if (result.details?.artifactId) {
@@ -59,7 +88,7 @@ export const mermaidRenderer = {
 			{
 				title: TOOL_TITLE,
 				titleColor: "dim",
-				description: uiTheme.fg("muted", "diagram"),
+				description: uiTheme.fg("muted", caption),
 				meta: meta.length > 0 ? meta : undefined,
 			},
 			uiTheme,
@@ -69,7 +98,12 @@ export const mermaidRenderer = {
 		return {
 			render(width: number): string[] {
 				const state = options.isPartial ? "pending" : "success";
-				return outputBlock.render({ header, state, sections, width, borderColor: F5_TOOL_BORDER_COLOR }, uiTheme);
+				return outputBlock.render(
+					// Clip, don't wrap: a diagram is a fixed grid — word-wrapping reflows it
+					// and breaks alignment. Wide diagrams are truncated to the block width.
+					{ header, state, sections, width, borderColor: F5_TOOL_BORDER_COLOR, wrapContent: false },
+					uiTheme,
+				);
 			},
 			invalidate() {
 				outputBlock.invalidate();

package/src/tools/render-mermaid.ts

@@ -4,7 +4,12 @@ import type {
 	AgentToolResult,
 	AgentToolUpdateCallback,
 } from "@f5xc-salesdemos/pi-agent-core";
-import { type MermaidAsciiRenderOptions, prompt, renderMermaidAscii } from "@f5xc-salesdemos/pi-utils";
+import {
+	type MermaidAsciiRenderOptions,
+	mermaidSourceExceedsLimit,
+	prompt,
+	renderMermaidAsciiSafe,
+} from "@f5xc-salesdemos/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with { type: "text" };
 import type { ToolSession } from "./index";
@@ -55,7 +60,24 @@ export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema,
 		_onUpdate?: AgentToolUpdateCallback<RenderMermaidToolDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<RenderMermaidToolDetails>> {
-		const ascii = renderMermaidAscii(params.mermaid, sanitizeRenderConfig(params.config));
+		// Reject oversized graphs up front: beautiful-mermaid's pathfinder can hang
+		// for tens of seconds and then throw `RangeError: Out of memory` on them.
+		// Throwing here (fast) surfaces a clean tool error the agent can recover from.
+		if (mermaidSourceExceedsLimit(params.mermaid)) {
+			throw new Error(
+				"Mermaid diagram is too large to render safely. Reduce the number of nodes/edges and try again.",
+			);
+		}
+
+		// Safe variant: a parse failure or memory blow-up becomes null rather than a
+		// raw RangeError, so we can throw a clear, actionable message instead.
+		const ascii = renderMermaidAsciiSafe(params.mermaid, sanitizeRenderConfig(params.config));
+		if (ascii == null || ascii.trim() === "") {
+			throw new Error(
+				"Failed to render the Mermaid diagram — the syntax may be unsupported or too complex. Use newline-separated statements (no ';') and try a simpler diagram.",
+			);
+		}
+
 		const { path: artifactPath, id: artifactId } =
 			(await this.session.allocateOutputArtifact?.("render_mermaid")) ?? {};
 		if (artifactPath) {

package/src/tui/output-block.ts

@@ -23,6 +23,12 @@ export interface OutputBlockOptions {
 	applyBg?: boolean;
 	/** Override the state-derived border color. Always takes precedence, including on error. Use for branded core tools. */
 	borderColor?: ThemeColor;
+	/**
+	 * Word-wrap content lines to fit the inner width (default). Set false to CLIP
+	 * (truncate) instead — required for pre-formatted grid content like mermaid
+	 * diagrams, where wrapping reflows characters and destroys alignment.
+	 */
+	wrapContent?: boolean;
 }
 
 export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[] {
@@ -34,6 +40,7 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		width,
 		applyBg = true,
 		borderColor: borderColorOverride,
+		wrapContent = true,
 	} = options;
 	const h = theme.boxSharp.horizontal;
 	const v = theme.boxSharp.vertical;
@@ -100,7 +107,9 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 				lines.push(line);
 				continue;
 			}
-			const wrappedLines = wrapTextWithAnsi(line.trimEnd(), contentWidth);
+			const wrappedLines = wrapContent
+				? wrapTextWithAnsi(line.trimEnd(), contentWidth)
+				: [truncateToWidth(line.trimEnd(), contentWidth)];
 			for (const wrappedLine of wrappedLines) {
 				const innerPadding = padding(Math.max(0, contentWidth - visibleWidth(wrappedLine)));
 				const fullLine = `${contentPrefix}${wrappedLine}${innerPadding}${contentSuffix}`;
@@ -150,6 +159,7 @@ export class CachedOutputBlock {
 		h.optional(options.state);
 		h.bool(options.applyBg ?? true);
 		h.optional(options.borderColor);
+		h.bool(options.wrapContent ?? true);
 		if (options.sections) {
 			for (const s of options.sections) {
 				h.optional(s.label);