fix: use valid CID font names for Chinese text rendering (fixes HKUDS#24)

Exploreunive · Exploreunive · commit 7143dd6482d1 · 2026-03-21T16:14:49.000+08:00
UnicodeCIDFont only supports a fixed set of CID font names:
  STSong-Light, MSung-Light, HeiseiMin-W3, HeiseiKakuGo-W5, HYSMyeongJo-Medium

The old code used system font names (SimSun, SimHei, STHeiti) which are NOT
valid CID names, causing silent font registration failures on Windows and
partial failures on macOS. Chinese text would render as black squares or
fallback to default Latin fonts.

Fix:
- Replace platform-specific invalid font name lists with STSong-Light,
  the standard cross-platform CID font for Simplified Chinese
- Only apply fallback font when WenQuanYi (Linux) is not already set
- Add tests verifying CID font name validity

Co-Authored-By: OpenClaw
diff --git a/raganything/parser.py b/raganything/parser.py
@@ -346,38 +346,22 @@ def convert_text_to_pdf(
                     heading_style.fontName = "WenQuanYi"
 
                 # Try to register a font that supports Chinese characters
+                # UnicodeCIDFont only supports specific CID font names:
+                #   STSong-Light (Chinese), MSung-Light (Chinese Traditional),
+                #   HeiseiMin-W3 / HeiseiKakuGo-W5 (Japanese),
+                #   HYSMyeongJo-Medium (Korean)
+                # System font names like "SimSun", "SimHei", "STHeiti" are
+                # NOT valid CID names and silently fail (#24).
                 try:
-                    # Try to use system fonts that support Chinese
-                    import platform
-
-                    system = platform.system()
-                    if system == "Windows":
-                        # Try common Windows fonts
-                        for font_name in ["SimSun", "SimHei", "Microsoft YaHei"]:
-                            try:
-                                from reportlab.pdfbase.cidfonts import (
-                                    UnicodeCIDFont,
-                                )
-
-                                pdfmetrics.registerFont(UnicodeCIDFont(font_name))
-                                normal_style.fontName = font_name
-                                heading_style.fontName = font_name
-                                break
-                            except Exception:
-                                continue
-                    elif system == "Darwin":  # macOS
-                        for font_name in ["STSong-Light", "STHeiti"]:
-                            try:
-                                from reportlab.pdfbase.cidfonts import (
-                                    UnicodeCIDFont,
-                                )
-
-                                pdfmetrics.registerFont(UnicodeCIDFont(font_name))
-                                normal_style.fontName = font_name
-                                heading_style.fontName = font_name
-                                break
-                            except Exception:
-                                continue
+                    from reportlab.pdfbase.cidfonts import UnicodeCIDFont
+
+                    # STSong-Light is the standard CID font for Simplified
+                    # Chinese and works cross-platform (reportlab ships the
+                    # required CID resources internally).
+                    pdfmetrics.registerFont(UnicodeCIDFont("STSong-Light"))
+                    if not support_chinese:
+                        normal_style.fontName = "STSong-Light"
+                        heading_style.fontName = "STSong-Light"
                 except Exception:
                     pass  # Use default fonts if Chinese font setup fails
 
diff --git a/tests/test_chinese_cid_font.py b/tests/test_chinese_cid_font.py
@@ -0,0 +1,44 @@
+"""Tests for Chinese CID font registration (issue #24).
+
+Verifies that STSong-Light is registered as the cross-platform Chinese CID
+font instead of invalid system font names like SimSun/SimHei.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+class TestChineseCIDFont:
+    """Test CID font registration for Chinese text rendering."""
+
+    def test_stsong_light_is_valid_cid_font(self):
+        """STSong-Light should register successfully as a CID font."""
+        from reportlab.pdfbase.cidfonts import UnicodeCIDFont
+        from reportlab.pdfbase import pdfmetrics
+
+        font = UnicodeCIDFont("STSong-Light")
+        pdfmetrics.registerFont(font)
+        # No exception means it worked
+
+    def test_invalid_cid_font_names_raise(self):
+        """Font names used in the old code should fail as CID fonts."""
+        from reportlab.pdfbase.cidfonts import UnicodeCIDFont
+
+        invalid_names = ["SimSun", "SimHei", "Microsoft YaHei", "STHeiti"]
+        for name in invalid_names:
+            with pytest.raises(Exception):
+                UnicodeCIDFont(name)
+
+    def test_all_valid_cid_cjk_font_names(self):
+        """Verify the set of valid CJK CID font names in reportlab."""
+        from reportlab.pdfbase.cidfonts import UnicodeCIDFont
+        from reportlab.pdfbase import pdfmetrics
+
+        valid_cjk = ["STSong-Light", "MSung-Light", "HeiseiMin-W3", "HeiseiKakuGo-W5", "HYSMyeongJo-Medium"]
+        for name in valid_cjk:
+            font = UnicodeCIDFont(name)
+            pdfmetrics.registerFont(font)
