Skip to content

Your lightweight open-source personal agent.

fix(tui): resolve readable macOS CJK fonts for native diagrams

Xubin Ren3f5ca7e896e1
diff --git a/docs/releases/0.4.0.md b/docs/releases/0.4.0.md
index 37f2a1627..eb5934a03 100644
--- a/docs/releases/0.4.0.md
+++ b/docs/releases/0.4.0.md
@@ -26,6 +26,7 @@ The gateway now owns model history and WebUI display history in SQLite. Existing
### Terminal, models and integrations
- Native terminal packages include Mermaid image rendering and smaller standalone builds with target-specific native dependencies. Platform wheels include the matching TUI and built WebUI; supported wheel installations do not need Bun or a first-launch TUI download.
+- On macOS, diagram rendering uses installed Heiti SC fonts with readable outlines. It does not depend on private PingFang UI font files or require a font download.
- The TUI SVG parser is updated to the maintained `@xmldom/xmldom` 0.8.15 patch release. Restricted image rendering and isolated rendering workers remain in place.
- PDF and image readers and the memory Git backend use updated pypdf, Pillow and Dulwich releases. Compatibility extras such as `nanobot-ai[pdf]` select the same supported reader versions as the base installation.
- Model setup includes searchable providers, explicit API choices and per-preset request overrides. Shared proxy settings can be selected independently by supported providers, web tools and MCP connections.
diff --git a/tui/scripts/native_smoke.py b/tui/scripts/native_smoke.py
index 47f7fead5..d19322f40 100644
--- a/tui/scripts/native_smoke.py
+++ b/tui/scripts/native_smoke.py
@@ -24,7 +24,8 @@ from zipfile import ZipFile
REPLY_LIMIT = 16_000_000
REQUEST = {"kind": "render", "input": {
- "source": "graph TD\n A[Start] --> B{Check data}\n B -->|Pass| C[Done]",
+ # Exercise real CJK outlines and C4's generated Latin punctuation together.
+ "source": 'C4Container\n Person(user, "用户")\n Container(api, "API 服务", "TypeScript")\n Rel(user, api, "调用", "HTTPS")',
"width": 800, "scale": 2,
"colors": {"foreground": "#202020", "muted": "#666666", "surface": "#eeeeee",
"border": "#888888", "accent": "#3366cc"},
@@ -143,6 +144,7 @@ def main() -> None:
"executable_sha256": hashlib.sha256(binary.read_bytes()).hexdigest(),
"first_screen_ms": frames, "render_ms_cold_then_warm": renders,
"render_after_restart_ms": restarted, "unicode_input_resize_exit": True,
+ "render_fixture": "C4Container: Chinese labels and Latin stereotypes",
"default_system_font_resolution": True, "worker_termination_restart": True,
"connected_gateway_or_model": False, "os_cache_controlled": False}
report["temporary_directory_removed"] = not root.exists()
diff --git a/tui/src/rendering/mermaid/macos-fonts.test.ts b/tui/src/rendering/mermaid/macos-fonts.test.ts
index f16bbd533..fa0af9b9f 100644
--- a/tui/src/rendering/mermaid/macos-fonts.test.ts
+++ b/tui/src/rendering/mermaid/macos-fonts.test.ts
@@ -3,8 +3,8 @@ import * as childProcess from "node:child_process"
import { macOSFonts } from "./macos-fonts"
test("macOS font lookup preserves system-resolved paths and regular/bold face identity", () => {
- const regular = { path: "/System/Library/AssetsV2/font-version/AssetData/PingFang.ttc", postscriptName: "PingFangSC-Regular" }
- const bold = { ...regular, postscriptName: "PingFangSC-Semibold" }
+ const regular = { path: "/System/Library/Fonts/STHeiti Light.ttc", postscriptName: "STHeitiSC-Light" }
+ const bold = { path: "/System/Library/Fonts/STHeiti Medium.ttc", postscriptName: "STHeitiSC-Medium" }
const lookup = spyOn(childProcess, "execFileSync").mockReturnValue(JSON.stringify([regular, bold]))
try {
expect(macOSFonts()).toEqual({ regular, bold, mono: regular })
@@ -13,16 +13,16 @@ test("macOS font lookup preserves system-resolved paths and regular/bold face id
test("an unavailable macOS font URL is a font error, not an undefined file read", () => {
const lookup = spyOn(childProcess, "execFileSync").mockReturnValue(JSON.stringify([
- { postscriptName: "PingFangSC-Regular" }, { postscriptName: "PingFangSC-Semibold" },
+ { postscriptName: "STHeitiSC-Light" }, { postscriptName: "STHeitiSC-Medium" },
]))
try {
- expect(macOSFonts).toThrow("check PingFang in macOS Font Book")
+ expect(macOSFonts).toThrow("check Heiti SC in macOS Font Book")
} finally { lookup.mockRestore() }
})
test("a failed system lookup stays a recoverable diagram error", () => {
const lookup = spyOn(childProcess, "execFileSync").mockImplementation(() => { throw new Error("lookup timed out") })
try {
- expect(macOSFonts).toThrow("check PingFang in macOS Font Book")
+ expect(macOSFonts).toThrow("check Heiti SC in macOS Font Book")
} finally { lookup.mockRestore() }
})
diff --git a/tui/src/rendering/mermaid/macos-fonts.ts b/tui/src/rendering/mermaid/macos-fonts.ts
index dcc023375..76fe35366 100644
--- a/tui/src/rendering/mermaid/macos-fonts.ts
+++ b/tui/src/rendering/mermaid/macos-fonts.ts
@@ -3,14 +3,15 @@ import { homedir } from "node:os"
import { isAbsolute } from "node:path"
import type { DiagramFont, DiagramInput } from "./types"
-// Ask CoreText for installed font URLs: recent macOS versions manage PingFang
-// under versioned Assets directories. No app automation or development toolchain is used.
+// Resolve installed CJK faces with OpenType outlines that fontkit can read.
+// macOS 15 can map public PingFang names to private HVGL-only UI fonts instead.
+// No app automation, font download or development toolchain is used.
const query = `
ObjC.import("CoreText");
-JSON.stringify(["PingFangSC-Regular", "PingFangSC-Semibold"].map(function(name) {
+JSON.stringify(["STHeitiSC-Light", "STHeitiSC-Medium"].map(function(name) {
const font = $.CTFontCreateWithName($(name), 12, null);
const actual = ObjC.unwrap(ObjC.castRefToObject($.CTFontCopyPostScriptName(font)));
- if (actual !== name) throw new Error("PingFang font unavailable");
+ if (actual !== name) throw new Error("Heiti SC font unavailable");
const url = $.CTFontCopyAttribute(font, $.kCTFontURLAttribute);
return { path: ObjC.unwrap(url.path), postscriptName: actual };
}));
@@ -33,6 +34,6 @@ export function macOSFonts(): NonNullable<DiagramInput["fonts"]> {
const regular = fonts[0]!, bold = fonts[1]!
return { regular, bold, mono: regular }
} catch (cause) {
- throw new Error("Diagram font unavailable (check PingFang in macOS Font Book)", { cause })
+ throw new Error("Diagram font unavailable (check Heiti SC in macOS Font Book)", { cause })
}
}
diff --git a/tui/src/rendering/mermaid/render.ts b/tui/src/rendering/mermaid/render.ts
index 3c0c912a4..3257bcd5f 100644
--- a/tui/src/rendering/mermaid/render.ts
+++ b/tui/src/rendering/mermaid/render.ts
@@ -48,8 +48,9 @@ function getFonts(selected?: DiagramInput["fonts"]): FontSet {
const font = (face: DiagramFont): Font => {
const loaded = file(face.path)
const available = "fonts" in loaded ? loaded.fonts : [loaded]
- const result = available.find(font => font.postscriptName === face.postscriptName)
- if (!result) throw new Error(`Diagram font unavailable: ${face.postscriptName}; available faces: ${JSON.stringify(available.map(font => font.postscriptName))}`)
+ // Fontkit returns an ASCII Buffer for some legacy macOS name-table records.
+ const result = available.find(font => String(font.postscriptName) === face.postscriptName)
+ if (!result) throw new Error(`Diagram font unavailable: ${face.postscriptName}`)
return result
}
activeFonts = { selected: faces, regular: font(faces.regular), bold: font(faces.bold), mono: font(faces.mono), system: !selected }