Ground-state UTF-8 paths treat C0 bytes 0x10-0x1F (except ESC) as printable text

[aolast]

Issue Description

I started investigating with a font symptom. Despite no known software update or configuration change, after closing and reopening the lid on my MacBook I noticed that:

• Chinese text in one Ghostty window suddenly used two fonts within the same line: most characters rendered in Wawati TC, while a few rendered in PingFang SC.
• English text still rendered normally, and Chinese text in other applications was unaffected.

I have two findings after investigation:

1. Ghostty treats some C0 controls as printable text
2. once treated as printable text, a C0 control can trigger font lookup, pollute Ghostty's font Collection, and cause mixed-font rendering within a line

I created this discussion primarily about how C0 controls are and should be handled. The mixed-font behavior is a downstream consequence showing that sending a C0 control into the printable-text path can do more then create a blank cell.

---

The following is the full story of my investigation.

AI assistance disclosure: I used OpenAI Codex CLI to inspect the source, analyze code history, design reproductions. I personally thought I already understand what I am writing but still could be wrong due to limited knowledge on Ghostty.

1. I found that U+0014 appeared in the font lookup path while U+0014 is DC4, a C0 control character, not ordinary text. Tracing that lookup backward toward the input showed that Ghostty's scalar and batched UTF-8 paths in the ground state only classify U+0000..U+000F as controls. The 15 values in U+0010..U+001F other than ESC (U+001B) can enter .print or .print_slice. (See in scalar path and batched path).

2. I also checked the following code/PRs and still curious about Why does the above code's boundary stop at 0x0F instead of 0x1F? Personally I did not understand and could only regard it as a miss.

   • ground-state parser table already covered the complete C0 range
   • [PR #1473](Replace UTF8 decoder #1473) moved UTF-8 decoding out of the general parser table and introduced < 0x0F in the scalar path
   • [PR #1472](SIMD Beginnings #1472) introduced the same boundary in the batched path. [PR #1478](fix(terminal): send SI to execute instead of print #1478) later fixed SI (0x0F) being printed by changing < 0x0F to <= 0x0F, but it did not address U+0010..U+001F.
   • Terminal.printSlice explicitly requires that its input contain no C0 control characters

3. My proposal is to route these C0 controls into the control path rather than .print or .print_slice. For values such as DC4 that currently have no dedicated implementation, the existing execute default branch logs the unsupported control once and ignores it.

---

The next question was how DC4 handling related to the mixed-font rendering ？
Recall that the original symptom showed in my mac was:

• English text in Ghostty rendered normally.
• Most Chinese characters in Ghostty rendered in Wawati TC, while a few rendered in PingFang SC. Before the symptom appeared, those Chinese characters all rendered in PingFang SC.
  I read [discussion #9410], [discussion #12919] and [issue #12916], but did not find a root cause being confirmed. And I realized that it could be the C0 issue.

How can an invisible control cause later Chinese text to use a font that was never configured?

1. Start from a DC4 is treated as printable, the terminal creates a cell and the shaper performs the same codepoint-to-face lookup for the stored U+0014 that it would for ordinary text. If Ghostty's current Collection has no usable face, CodepointResolver asks CoreText for a fallback and adds the winning face to the Collection. Even if that face returns no visible outline for DC4, the lookup still changes the font-selection state used later.

2. Consider the normal path when no CJK font is configured explicitly

   • An empty configuration does not mean that Ghostty uses only one font. The primary monospace face normally covers ASCII but often does not cover Chinese. English therefore resolves directly in the primary face, and fallback faces added later neither replace the primary face nor participate in those ASCII lookups. This explains why English remained normal.
   • When Ghostty encounters an uncached Chinese character, it first checks font-codepoint-map and faces already loaded in the Collection.
     • If none cover the character, the macOS backend uses a locale-aware CTFontCreateForString path for U+4E00..U+9FFF, allowing CoreText to select a CJK fallback from the system fonts and locale. In this Simplified Chinese environment, the normal result was PingFang SC. Ghostty then adds that face to the Collection and SharedGrid caches the result for the codepoint.
     • In other words, without an explicitly configured CJK font, the system fallback is resolved on demand rather than being a second font fixed in the configuration.

3. Once DC4 is printed, it enters the same ordinary font-resolution path. If SharedGrid has not cached U+0014 and none of the faces already in the Collection cover it, CodepointResolver asks CoreText for a fallback and adds the returned face to the Collection.

4. To produce the mixed Chinese rendering I saw, Wawati TC needs to enter the Collection before the normal PingFang SC CJK fallback. Every later uncached Chinese character then checks Wawati TC first and only reaches the locale-aware CJK fallback when Wawati TC lacks that character. This is how a font never configured in Ghostty can affect later Chinese text: it was not selected as the "default Chinese font"; it was inserted early in the normal lookup order by the erroneous DC4 lookup.

Example screenshots for the mixed font issues from my reverse engineering:

Expected Behavior

1. In the ground state, U+0000..U+001F should be recognized as C0 control input not a printable text.
2. Further, control input like DC4 should not triggering creating a printable cell or triggering ordinary text font lookup.

The expected output from the minimal reproduction (printf '| X|\r\n|\024X|\r\n') is:

| X|
|X|

Actual Behavior

1. DC4 is rendered as a blank.

2. Mixed font could be triggered from this path as attached in the issue description section.

Reproduction Steps

To reproduce the printable nature of DC4

1. Run printf '| X|\r\n|\024X|\r\n' directly in Ghostty
2. The first line contains SPACE (0x20) between | and X. The second line contains DC4 (0x14) in the same position and should contain no SPACE but currently Ghostty displays both lines as | X|.

---

Only read the following if you are interested on reproducing the mixed-font issue.

To reproduce a mixed-font reproduction

1. Run the following shell script.
2. You should see two fonts mixed in a line as showing in the second screenshot above.

The script starts an isolated Ghostty instance that does not read the user's default configuration and uses only test-specific font-codepoint-map entries. Faces A and B construct the relevant Collection order without depending on the original CoreText state. DC4 is mapped to a visibly different serif face A, but the mapping is resolved lazily. Face A enters the Collection before reference face B only when DC4 reaches glyph lookup. The script then loads sans-serif reference face B through a mapping for U+3000.

The test text maps the fullwidth Latin vowels and the second character of each Chinese pair explicitly to face B. The remaining characters have no explicit mapping and therefore encounter face A first in the Collection. On the affected parser, each line contains both A and B. Fullwidth Latin is used so that English-speaking maintainers can read the sample while it still bypasses the primary monospace face's ordinary ASCII coverage.

#!/bin/sh

set -eu

render_trigger() {
    if [ ! -t 1 ]; then
        printf '%s\n' 'error: stdout must be a terminal' >&2
        exit 2
    fi

    printf '\033[2J\033[H'
    printf '\033]2;Ghostty C0 mixed-font trigger\007'
    printf '%s\r\n' \
        'DC4 MIXED-FONT TRIGGER' \
        'Expected on affected parser: two fonts within each sample' \
        '' \
        'LATIN - sans vowels, serif consonants:'

    printf '\024'
    sleep 2
    printf '\343\200\200'
    sleep 2

    printf '%s\r\n' 'ＡＢ ＥＦ ＩＪ ＯＰ ＵＶ  Ｔｈｅ Ｑｕｉｃｋ Ｂｒｏｗｎ Ｆｏｘ．'
    printf '\r\n%s\r\n' 'CHINESE - serif first character, sans second character:'
    printf '%s\r\n' '就开 看见 中文 字体'
    printf '\r\n%s\r\n' 'Press Enter to close.'
    IFS= read -r _ || :
}

if [ "${1-}" = "--render" ]; then
    render_trigger
    exit 0
fi

if [ "$#" -ne 0 ]; then
    printf 'usage: sh %s\n' "$0" >&2
    exit 2
fi

script_dir=$(CDPATH='' cd -P "$(dirname "$0")" && pwd)
script_path=$script_dir/$(basename "$0")

exec /usr/bin/open -n -a Ghostty.app --args \
    --config-default-files=false \
    --font-family=Menlo \
    --font-size=24 \
    '--font-codepoint-map=U+0014=Hiragino Mincho ProN' \
    '--font-codepoint-map=U+10FFFF=Menlo' \
    '--font-codepoint-map=U+3000=Hiragino Sans GB' \
    '--font-codepoint-map=U+FF21,U+FF25,U+FF29,U+FF2F,U+FF35,U+FF41,U+FF45,U+FF49,U+FF4F,U+FF55=Hiragino Sans GB' \
    '--font-codepoint-map=U+5F00,U+89C1,U+6587,U+4F53=Hiragino Sans GB' \
    --confirm-close-surface=false \
    -e /bin/sh "$script_path" --render

---

The following is how I investigated and reproduced the issue and this is just for reference not a step that you need to follow

Experiment 1: Wawati TC and CoreText

I first tested whether DC4 would bring Wawati TC into the Collection when Wawati TC was visible in the Ghostty process's CoreText registry. In an isolated copy of the official Ghostty 1.3.1 app, I registered Wawati TC with CoreText process-scoped registration, then emitted DC4 followed by Chinese text. Ghostty's parser, resolver, Collection, shaper, and renderer remained unchanged. The registration only made Wawati TC visible to that process.

A CLI probe saw 24 U+0014 candidates without Wawati before registration. After registration, it saw 25 candidates and selected Wawati TC. In this construction, Wawati TC and the previously available Apple SD Gothic Neo had equal values in Ghostty's higher-priority score fields, while glyph_count is the final tie-breaker. Wawati TC has 36,992 glyphs and Apple SD Gothic Neo has 18,662, so Wawati TC ranked first and CodepointResolver added it to the Collection. Once in the Collection, its effect on later Chinese text depended on per-character coverage rather than switching an entire line to one font. The experiment produced:

Later characters	Wawati TC	Resolution
就 看 了 解 离	covered	Existing Wawati TC face matched in the Collection
开 见 测 试	missing	Continued to normal CJK fallback and resolved to PingFang SC

For 就开, 就 matched Wawati TC before CoreText was asked for a normal CJK fallback. Wawati TC lacked 开, so that character continued to PingFang SC. The same line therefore rendered with both Wawati TC and PingFang SC. "Later Chinese text is affected" does not mean that every Chinese character changes to Wawati. Each uncached character checks Wawati first; covered and missing characters resolve differently.

This experiment reproduced the complete chain: DC4 is printed incorrectly -> font discovery runs for U+0014 -> Wawati TC enters the Collection -> later Chinese characters split between Wawati TC and PingFang SC according to Wawati TC's glyph coverage -> mixed fonts appear within the line.

Experiment 2: Visual reproduction that can be attached to the Discussion

To let other people see the same issue without depending on Wawati or the earlier CoreText state, I wrote the Shell script described in Reproduction Steps below. The script uses font-codepoint-map to map DC4 to a serif face A, but that face is loaded only if DC4 actually enters font lookup. It then loads a sans-serif face B and prints fullwidth Latin and Chinese samples. If DC4 is treated as printable text, face A enters the Collection first and later characters use either face A or face B according to glyph coverage, so two fonts appear within one line. If DC4 enters the control path, face A is never loaded and the later characters all use face B.

The two experiments use different constructions, but both reproduce the same chain. The Wawati experiment uses real CoreText fallback to reproduce the original font combination; the visual reproduction uses explicitly configured faces A and B to demonstrate the same mechanism reliably.

Ghostty Logs

No response

Ghostty Version

Ghostty 1.3.1

Version
  - version: 1.3.1
  - channel: stable
Build Config
  - Zig version   : 0.15.2
  - build mode    : .ReleaseFast
  - app runtime   : .none
  - font engine   : .coretext
  - renderer      : renderer.generic.Renderer(renderer.Metal)
  - libxev        : kqueue

OS Version Information

macOS 26.6.1 (Build 25G76), Apple Silicon

(Linux only) Display Server

None

(Linux only) Desktop Environment/Window Manager

No response

Minimal Ghostty Configuration

# I have no Ghostty config when I got the issue and when investigating.

Additional Relevant Configuration

No response

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty documentation and confirm there doesn't exist a configuration option that solves my issue.
• I have searched the Ghostty repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
• I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (```) on separate lines.

[mitchellh]

#14022

[aolast]

Thanks for the quick fix! I hope the investigation was helpful. I learned a lot through the process and look forward to contributing to Ghostty in the future. Nice project : )