Skip to content

fix(mobile): recompose iOS NFD Hangul before terminal send - #11246

Closed
brennanb2025 wants to merge 1 commit into
mainfrom
brennanb2025/mobile-ios-hangul-nfd
Closed

brennanb2025 wants to merge 1 commit into
mainfrom
brennanb2025/mobile-ios-hangul-nfd

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Jul 28, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • NFC-normalize outbound terminal text so Apple NFD Hangul reaches the live mirror as complete syllables.
  • Keep the React Native field write-back verbatim for iOS dictation/IME stability, and deliberately avoid lossy NFKC folding.
  • Add real mirror-pipeline coverage for Hangul and Latin NFD plus compatibility-form guards.

Fixes #11235. Thanks @lkjsays for the iOS reproduction report in #6995.

Test: NFC(안녕하세요) == 안녕하세요

Screenshots

No visual change.

Testing

  • pnpm --dir mobile lint
  • pnpm --dir mobile typecheck
  • pnpm --dir mobile test — 352 files, 2,596 passed, 2 skipped
  • pnpm --dir mobile format:check
  • pnpm build — not run; no native or build-system changes
  • Added regression tests; removing the NFC normalization makes four new assertions fail

AI Review Report

A same-model independent review returned clean. It checked the real live-mirror pipeline, raw field write-back, NFC versus NFKC fidelity, neighboring input paths, and per-keystroke cost; no correctness, regression, or meaningful performance concerns were found. The change is platform-neutral outside the documented iOS source behavior and touches no shortcuts, labels, paths, shell behavior, Git/provider behavior, or Electron platform branches; SSH and folder workspaces use the same pre-transport mobile path.

Security Audit

Reviewed the command-input transformation for silent rewriting risk. NFC only recomposes canonically equivalent text; tests prove compatibility jamo, full-width forms, and circled characters are preserved, and the change introduces no auth, secret, dependency, path, IPC, or command-execution surface.

Notes

The rebased branch bundle loaded on an iPhone 17 Pro simulator running iOS 26.5, and a connected session plus real terminal surface rendered successfully. Simulator automation could not inject Korean IME composition events end to end, so device-level Korean typing remains unverified; the regression is proven through the production mirror algorithm with real NFD field states.

image
image
image
image

…the PTY

Apple text input hands React Native decomposed text, so one Hangul syllable
arrives as 2-3 conjoining jamo (안 = U+110B U+1161 U+11AB). The live-input
mirror holds only the trailing code point as the in-composition syllable, so
every leading jamo is committed to the PTY on its own and is never recombined:
typing 안녕하세요 lands 12 lone jamo instead of 5 syllables.

This is a third mechanism behind the #6995 symptom, distinct from the Samsung
Keyboard inputType kill on Android — the iOS field itself composes correctly,
it is the string handed to JS that is decomposed, which is why the report
survives autoCorrect={false}.

NFC-normalize at the existing normalizeTerminalTextInput choke point, which
covers both the live mirror and the command-bar send. NFC only, never NFKC:
NFKC folds compatibility jamo and full-width forms into different characters
and would silently rewrite a command. The field write-back stays verbatim, so
the iOS dictation/IME constraint from #7925 is untouched.

Fixes #11235
Refs #6995, #7925
@brennanb2025

Copy link
Copy Markdown
Contributor Author

Thanks again @lkjsays for the precise iOS report — it led to a separate NFD mechanism rather than the Android/Samsung path. The review loop is clean, all 2,596 mobile tests pass, and the four new assertions go red when NFC recomposition is removed. Device caveat: the branch bundle and live terminal loaded on an iOS 26.5 simulator, but automated Korean IME keystrokes were unavailable, so I am not claiming end-to-end keyboard validation.

@coderabbitai

coderabbitai Bot commented Jul 28, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Terminal text input now applies NFC normalization before iOS smart-dash restoration. Tests cover decomposed Hangul and Latin diacritics, preserve compatibility forms, verify idempotence, and simulate live-mirror replay into the PTY for composed output.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The changes match #11235 by normalizing only outbound terminal text with NFC while preserving verbatim field write-back and avoiding NFKC folding.
Out of Scope Changes check ✅ Passed The PR stays focused on the normalization fix and regression tests, with no obvious unrelated changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check ✅ Passed The title clearly summarizes the main change: NFC recomposition of iOS NFD Hangul before terminal send.
Description check ✅ Passed The description includes all required template sections and sufficiently covers summary, testing, review, security, screenshots, and notes.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@greptile-apps

greptile-apps Bot commented Jul 28, 2026

Copy link
Copy Markdown

Greptile Summary

Adds .normalize('NFC') to normalizeTerminalTextInput so that iOS-delivered NFD Hangul (and Latin diacritics) are recomposed into complete syllables before reaching the live-mirror algorithm, fixing the bug where individual jamo were committed to the PTY instead of composed syllables. The React Native field write-back intentionally stays verbatim (NFD) to preserve iOS IME/dictation stability.

  • Core fix (terminal-text-input-normalization.ts): one-line addition of text.normalize('NFC') before the existing smart-dash replacement; NFC is a no-op on already-composed input and deliberately avoids NFKC to preserve compatibility jamo, full-width forms, and circled characters.
  • Unit tests (terminal-text-input-normalization.test.ts): new assertions cover Hangul NFD recomposition, Latin diacritic idempotency, and compatibility-form preservation.
  • Pipeline integration tests (terminal-ios-hangul-nfd-input.test.ts): replays the full normalizeTerminalTextInput → computeTerminalLiveMirrorStep → buildTerminalLiveMirrorPayload pipeline with NFD Hangul field states, NFC Hangul (Android baseline), and NFD Latin to confirm all paths produce correctly composed PTY output.

Confidence Score: 5/5

Safe to merge — the change is a single idempotent call confined to the mobile terminal send path, with no effect on Android, Electron, or any non-iOS path.

The fix is minimal and well-bounded: NFC is canonical-equivalence-only, it is a no-op for already-composed input, and leaves compatibility characters (jamo, full-width, circled) untouched. The smart-dash replacement order is unaffected since U+2013/U+2014 have no canonical decompositions. The new integration tests exercise the real pipeline functions with raw NFD field states.

Files Needing Attention: No files require special attention. All three changed files are tightly scoped to the iOS terminal text normalization path.

Important Files Changed

Filename Overview
mobile/src/terminal/terminal-text-input-normalization.ts Adds .normalize('NFC') before the smart-dash replacement; one-line core fix that recomposes iOS-NFD Hangul (and Latin diacritics) before the live-mirror algorithm sees them.
mobile/src/terminal/terminal-text-input-normalization.test.ts Extends existing unit tests with Hangul NFD recomposition, Latin diacritic idempotency, and compatibility-form preservation (jamo, full-width, circled chars) to guard against future NFKC regressions.
mobile/src/terminal/terminal-ios-hangul-nfd-input.test.ts New integration-style test that replays the full live-mirror pipeline with NFD field states for Hangul, NFC Hangul, and Latin NFD, confirming the PTY receives complete syllables.

Sequence Diagram

sequenceDiagram
    participant iOS as iOS TextInput (NFD)
    participant HLC as handleLiveInputChange
    participant Norm as normalizeTerminalTextInput
    participant Mirror as computeTerminalLiveMirrorStep
    participant PTY as PTY (terminal)
    participant Field as RN Controlled Field

    iOS->>HLC: onChangeText("안" NFD jamo)
    HLC->>Field: setLiveInputCapture(raw NFD text)
    Note over Field: Verbatim write-back keeps iOS IME/dictation alive
    HLC->>Norm: normalizeTerminalTextInput(NFD text)
    Norm->>Norm: text.normalize('NFC')
    Norm->>Norm: .replace(smart dashes to '--')
    Norm-->>HLC: NFC composed syllable "안"
    HLC->>Mirror: applyLiveInputMirror(handle, NFC text)
    Mirror->>Mirror: Hold last Hangul code point
    Mirror-->>PTY: Commit completed syllables only
    Note over PTY: Receives composed syllables, never raw jamo fragments
Loading

Reviews (1): Last reviewed commit: "fix(mobile): recompose iOS decomposed (N..." | Re-trigger Greptile

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
mobile/src/terminal/terminal-ios-hangul-nfd-input.test.ts (1)

65-74: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove redundant Given/When/Then narration.

These comments restate the test names and assertions; retain only comments that explain non-obvious fixture behavior.

Proposed fix
-    // Given: Apple text input hands React Native decomposed conjoining jamo, so
-    // one syllable arrives as 2-3 code points instead of one.
     const nfdStates = DUBEOLSIK_FIELD_STATES.map((state) => state.normalize('NFD'))
     expect(Array.from(nfdStates.at(-1) ?? '')).toHaveLength(12)
 
-    // When
     const pty = replayLiveInput(nfdStates)
 
-    // Then: the mirror holds only the trailing code point, so without
-    // recomposition every leading jamo is committed on its own (`#6995` iOS).
     expect(Array.from(pty)).toHaveLength(5)
     expect(pty).toBe('안녕하세요')
@@
-    // Given / When
     const pty = replayLiveInput(DUBEOLSIK_FIELD_STATES)
 
-    // Then
     expect(pty).toBe('안녕하세요')
@@
-    // Given / When: iOS also hands back NFD for Vietnamese/European accents.
     const pty = replayLiveInput(['tie', 'tiế', 'tiếng'].map((state) => state.normalize('NFD')))
 
-    // Then
     expect(pty).toBe('tiếng')

As per coding guidelines, “Comments must be concise, limited to non-obvious information, and preferably one line.”

Also applies to: 79-92

Source: Coding guidelines


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3ed8f2a6-7b71-4c3f-8060-5ef0149c4cf5

📥 Commits

Reviewing files that changed from the base of the PR and between a6423d5 and 949099d.

📒 Files selected for processing (3)
  • mobile/src/terminal/terminal-ios-hangul-nfd-input.test.ts
  • mobile/src/terminal/terminal-text-input-normalization.test.ts
  • mobile/src/terminal/terminal-text-input-normalization.ts

Comment on lines +7 to +11
// Why: Apple text input hands back decomposed (NFD) text, so one Hangul syllable
// arrives as 2-3 conjoining jamo. The live mirror holds only the trailing code
// point, so every leading jamo would commit on its own (#6995 iOS). NFC — never
// NFKC, which rewrites compatibility jamo and full-width forms — recomposes them
// before the PTY sees anything; it is a no-op for already-composed input.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct and shorten this rationale comment.

Line 9 references #6995, but the PR objective identifies the affected issue as #11235. Reduce this to one concise rationale line while correcting or removing the ticket reference.

Proposed fix
-// Why: Apple text input hands back decomposed (NFD) text, so one Hangul syllable
-// arrives as 2-3 conjoining jamo. The live mirror holds only the trailing code
-// point, so every leading jamo would commit on its own (`#6995` iOS). NFC — never
-// NFKC, which rewrites compatibility jamo and full-width forms — recomposes them
-// before the PTY sees anything; it is a no-op for already-composed input.
+// NFC recomposes iOS NFD input; avoid NFKC to preserve compatibility forms (`#11235`).

As per coding guidelines, “Comments must be concise, limited to non-obvious information, and preferably one line.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// Why: Apple text input hands back decomposed (NFD) text, so one Hangul syllable
// arrives as 2-3 conjoining jamo. The live mirror holds only the trailing code
// point, so every leading jamo would commit on its own (#6995 iOS). NFC — never
// NFKC, which rewrites compatibility jamo and full-width forms — recomposes them
// before the PTY sees anything; it is a no-op for already-composed input.
// NFC recomposes iOS NFD input; avoid NFKC to preserve compatibility forms (`#11235`).

Source: Coding guidelines

@brennanb2025

Copy link
Copy Markdown
Contributor Author

Physical-device A/B run — this did not reproduce, so I would not merge it as a fix for #6995 yet.

Setup: iPhone 14, iOS 26.5.2, dev build of this branch, paired to a desktop runtime over LAN. Typed 안녕하세요 with the iOS Korean 2-set keyboard into a terminal live input.

Build Result
This branch (NFC normalize present) 안녕하세요 — 5 composed syllables
Same build, text.normalize('NFC') removed via hot reload 안녕하세요 — 5 composed syllables

Identical. So on this device the normalize is not load-bearing: iOS handed React Native already-composed text, and the premise that Apple returns NFD here does not hold on iOS 26.5.2.

The change itself is still safe — NFC is a verified no-op on composed input, and NFKC was correctly avoided — but the tests only prove the normalize recomposes synthetic NFD strings; nothing demonstrates iOS produces them. That is inference, and the device run contradicts it.

One real observation from the same run, unrelated to NFD: mid-composition after a backspace, a lone jamo (ㄴ) briefly reached the terminal before the mirror's DEL repair cleaned it up. That is transient in-composition leakage — the flicker/destructive-intermediate-bytes behaviour described on #7427 — not decomposition.

Suggested next step: confirm with the original reporter what iPhone and iOS version they were on. If they were on an older iOS, that likely explains the difference and this fix is still correct for them; if they are on 26.x, the root cause is something else and this PR should be reframed or closed.

Holding this open rather than merging.

@nwparker

Copy link
Copy Markdown
Contributor

Thanks @brennanb2025 — and genuinely, thanks for the device A/B on this. That's the part that settled it, and it's the harder thing to publish about your own PR.

I re-ran the pipeline on current main and I think we close both. Two reasons, in order of weight.

1. The mechanism no longer exists. #15007 replaced the one-trailing-code-point hold with the text system's marked-text report, and it holds the entire unsent preedit region. That one-code-point window was the whole bug: an NFD syllable spans 2–3 code points, so every leading jamo fell outside it. Replaying the 두벌식 sequence for 안녕하세요 with NFD field states:

rule writes to the pty
old one-code-point hold 12 separate writes — ᄋ ᅡ ᆫ ᄂ ᅧ ᆼ ᄒ ᅡ ᄉ ᅦ ᄋ ᅭ, exactly as reported
current, marked-text reported (iOS) one write, whole string
current, no report (Android fallback) one write, whole string

No fragmentation left. The residual difference is 12 conjoining jamo instead of 5 precomposed syllables in a single atomic write — canonically equivalent. And where the mirror still splits under NFD (settle timer firing mid-syllable), NFD is actually cheaper than NFC: the trailing jamo appends, where NFC costs a DEL and a retype. The PR also no longer applies — its test imports terminal-live-hangul-mirror, which #15007 deleted.

2. The premise is still unreproduced. Your iOS 26.5.2 run showed Apple handing React Native composed text with and without the normalize. The tests prove NFC recomposes a synthetic NFD string; nothing shows iOS produces one. You named that gap yourself and I couldn't close it either — there's no capture or fixture anywhere in the repo containing real iOS NFD.

For what it's worth I did check whether we should normalise, before realising we didn't have to. A mature reference terminal implementation doesn't normalise keystroke or IME text on the way to the pty at all — one has no normalization code in its tree; the other has it only for text being drawn into the on-screen grid, behind a setting that defaults off, with every key-mapper's insert transform a literal identity. Normalise what you draw, never what you send. Orca already agrees with that, apparently by accident: no normalization on any terminal input path, desktop or mobile, and every normalize('NFC') site in the app is filesystem-path comparison.

The counter-argument is real and worth naming: NFD at a shell prompt won't match an NFC filename on a byte-exact filesystem — macOS APFS resolves either form, Linux won't. If NFD ever does show up we'll need an answer for that. But it isn't the answer to a bug nobody can reproduce.

The code was correct and the NFC-not-NFKC reasoning was exactly right. A different fix just removed the failure first.

@nwparker nwparker closed this Aug 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: iOS Korean input reaches the terminal as decomposed (NFD) jamo — third mechanism behind #6995

2 participants