1jehuang / 1jehuang/jcode

Mermaid emoji labels render following text as tofu on macOS

Open
#647 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

autonomous: no bug priority: low triage: needs-decision triage: reproducible
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:

  1. The Mermaid theme starts with Inter and 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.
  2. During mixed-span shaping, Apple Color Emoji's box glyphs count as present. usvg fallback 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:

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 -- --check
  • scripts/dev_cargo.sh test -p jcode-tui-mermaid (74 passed)
  • scripts/dev_cargo.sh check -p jcode-tui-mermaid --no-default-features
  • scripts/dev_cargo.sh clippy -p jcode-tui-mermaid --lib --all-features -- -D warnings
  • scripts/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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.