Mermaid emoji labels render following text as tofu on macOS
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 19.9k
- Forks
- 2.3k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 30
Description
Reproduction
On macOS, a Mermaid label containing emoji plus normal text renders the emoji, but the following text becomes tofu boxes:
flowchart LR
A["🧠 Memory"] --> B["🖥️ Your Mac apps"]
B --> C["👨👩👧👦 Family + 👍🏽 ready"]
ASCII-only labels render normally.
Environment: macOS aarch64, reproduced on Jcode v0.61.1 using the usvg/resvg 0.46 PNG path.
Diagnosis
Two font-selection behaviors interact:
- The Mermaid theme starts with
Interand CSS system aliases, followed by platform emoji fonts. The existing helper skips generic aliases. On a stock Mac without Inter, Apple Color Emoji can therefore become the selected "normal" face. - During mixed-span shaping, Apple Color Emoji's box glyphs count as present.
usvgfallback can then replace a valid normal-font result for the complete text chunk, producing readable emoji followed by tofu.
This is related to the explicit mixed-font run guidance in linebender/resvg#916, with an additional Apple Color Emoji fallback interaction.
Expected behavior
- Emoji use Apple Color Emoji on macOS.
- Normal text uses Inter when installed, otherwise Helvetica through
system-ui/sans-serif. - CJK, math, and other Unicode retain normal font fallback.
Tested patch
I prepared and validated a patch here:
- Commit: https://github.com/brenden7158/jcode/commit/714259da93c098699cdc962a02e73d155d0cba23
- Compare: https://github.com/1jehuang/jcode/compare/master...brenden7158:fix/mermaid-emoji-font-fallback
The patch:
- resolves CSS generic families through
fontdb - maps macOS generic sans-serif to Helvetica when available
- splits generated Mermaid text into grapheme-safe sibling normal/emoji
<tspan>runs - preserves positioning, attributes, and XML entities
- suppresses fallback only for emoji characters already handled by explicit runs
- retains ordinary behavior when no known platform emoji font is installed
Regression coverage includes ASCII, non-emoji Unicode, ZWJ families, skin tones, keycaps, flags, XML entities, positioned/existing tspans, missing emoji fonts, CJK/math fallback, and Helvetica resolution.
Validation performed:
cargo fmt --all -- --checkscripts/dev_cargo.sh test -p jcode-tui-mermaid(74 passed)scripts/dev_cargo.sh check -p jcode-tui-mermaid --no-default-featuresscripts/dev_cargo.sh clippy -p jcode-tui-mermaid --lib --all-features -- -D warningsscripts/dev_cargo.sh build --profile selfdev -p jcode --bin jcode- local server smoke test and manual macOS render with Apple Color Emoji + Inter +
中文 ∑ fallback
GitHub rejected PR creation from my current CLI authentication context, so I am sharing the ready-to-review commit and compare link here while the corresponding PR is submitted manually.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the referenced commit and the Mermaid rendering code exercised by jcode-tui-mermaid. Run scripts/dev_cargo.sh test -p jcode-tui-mermaid first, then inspect the listed regression cases and macOS rendering behavior. Done means emoji uses the platform emoji font, normal text remains readable, and the reported validation commands pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, rust
- Domain
- computer-graphics
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100