Point the real terminal cursor at the caret so IME candidate windows land in the input (#1128)

[KazenDev]

Takes Option A from #1128 — the minimal one — and adds the regression tests the report asked for. The real terminal cursor now sits on the caret, so a CJK IME anchors its composition string and candidate window inside the input box instead of wherever the frame last wrote text.

Why Option A and not Option B

Option B (migrate to OpenTUI's <textarea> / EditBufferRenderable) is the cleaner end state — it is what opencode uses — but it means replacing the hand-rolled editor: word wrap, word-wise navigation, tab expansion, paste handling, the queue-edit integration and the keyboard table all live in this component, and their tests are written against it. Positioning the cursor is the actual bug. Moving the editor is a separate change with a much larger blast radius, and it can be done later on a codebase that no longer has a parked cursor.

What this changes

File
cli/src/utils/ime-caret.ts	new, 72 — pure: caret index + wrap info + screen origin → 1-based cell, or null when off-screen
cli/src/utils/__tests__/ime-caret.test.ts	new, 111 — 9 tests of that geometry
cli/src/components/__tests__/multiline-input-caret.test.tsx	new, 145 — 8 tests of what the component publishes
cli/src/components/multiline-input.tsx	+97/-89 — publishes the caret each frame; the drawn caret is gone
cli/src/components/__tests__/multiline-input.test.tsx	-162 — the tests that asserted the drawn caret
cli/src/hooks/use-clipboard.ts	-2 — stopped stripping a cursor character that no longer exists
cli/src/components/input-cursor.tsx	deleted

441 insertions, 317 deletions across 7 files.

Three things that are easy to get wrong here

All three were hit while implementing, and each is why the code looks the way it does.

1. renderAfter looks like the right hook and is not

renderAfter fires after layout, which is exactly the timing this needs, and the React layer does forward it as a prop. It never runs on the input: TextBufferRenderable overrides render() without calling it, so a handler assigned there is silently dead — measured zero dispatches while the component was rendering normally. What works is renderer.setFrameCallback, which the codebase already uses elsewhere, and it has a side benefit: the cursor also follows a scroll or a resize, without waiting for a React re-render.

2. The first callback of a frame still sees the previous layout

The frame callback runs twice per frame: once with the layout of the previous frame (input box still 0 rows tall) and once with the current one. Publishing unconditionally makes the cursor blink off and back on every frame. When the geometry is not ready yet the cursor is now left alone.

3. Geometry is in cells, and one render-time value is a layout behind

A CJK glyph is two cells wide, so the column has to be measured with string-width, never by string index. The wrap info (lineInfo.lineStartCols) read during render belongs to the previous layout — with two lines, every multiline caret would resolve onto line 0. The helper reads it at frame time instead, which is what the input's own keyboard handlers already do.

Why the drawn caret goes away

The fake ▍ and the new real cursor cannot coexist — that is two cursors on screen — and the drawn one could only ever go stale, which is the bug. So input-cursor.tsx, the shouldHighlight branch and the inverted-span highlight all go. Vertical navigation still needs to know whether the caret sits on a character, so that decision survives as caretOverCharacter, with the same expression as before.

The cursor is hidden when the input is not focused. The report notes that OpenTUI's own renderCursor() early-returns when unfocused, and since this fix does not hand focus to an inner textarea, that hide has to be explicit.

How to try it

The report's own repro, on Windows Terminal + Microsoft Pinyin:

1. Run the CLI.
2. Switch to a Chinese IME.
3. Type nihao and watch where the composition text and candidate list land.
4. Keep typing after enough output to scroll the transcript, and type on a second line — the cursor should track the caret in both cases.

Verified

• bun test cli/src/utils/__tests__/ime-caret.test.ts cli/src/components/__tests__/multiline-input-caret.test.tsx — 17 pass. The component tests read the renderer's published cursor state after a frame, so they assert the position the terminal actually gets.
• bun run typecheck (in cli/) — unchanged at its 10 pre-existing errors (missing tar types, missing react-dom/server types). No new ones.
• Full CLI suite, same file list as bun run test (200 files, 3130 tests): 3090 → 3098 pass, same 20 pre-existing failures. The 8 are the net of the 17 tests added and the 9 obsolete ones removed; the 20 failures are environmental (release wrapper needs the tar module, and the env loader needs Infisical) and identical before and after.

Note for anyone re-running this: the package's bun run test script cannot start in this mirror, because its bunfig.toml preloads ../test/setup-scm-loader.ts, which is not part of the public tree. Passing the file list to bun test directly from the repository root works.

Not in this PR

• Mojibake and the lost last character on Enter (opentui improved model configuration menu logic in thinker and code-searcher #942, [feat][codecane] release the codecane #189). This is positioning only, and the report already separates them.
• Option B, migrating the input to <textarea> — see above.
• The real cursor is visible, so it now blinks per the shouldBlinkCursor preference, which is forwarded through setCursorStyle. The drawn caret had its own blink timing and a lime fallback for terminals without truecolor; neither is needed now that the terminal draws it.

[codebuff-team]

Good work. This addresses a real, well-documented bug (#1128) at the correct root: IMEs anchor to the terminal's actual cursor, not to drawn glyphs, so a hand-rolled ▍ cursor was always going to break CJK input. The write-up on why renderAfter looked right but silently never fires, and why the first frame-callback invocation still sees stale layout, reads like genuine debugging rather than guesswork, and both are exactly the kind of thing that bites a maintainer redoing this later if it isn't written down.

The scope is appropriately conservative (Option A, not a rip-and-replace of the editor), and ime-caret.ts is a small pure function with solid unit coverage (CJK width via string-width, tab expansion, multi-line wrap, scroll-out-of-view). multiline-input-caret.test.tsx exercises the actual component against createTestRenderer rather than mocking the geometry away, which is the right level for this kind of change.

Things worth double-checking before porting:

• publishCarets reads textBufferView.lineInfo.lineStartCols via a cast to an untyped shape (multiline-input.tsx, the lineStarts line). That's reaching into OpenTUI internals with no type contract; a note on why that's the only way to get frame-fresh wrap info (or a narrower internal type) would help future maintainers when OpenTUI changes.
• renderer.setCursorPosition(0, 0, false) is used both for "not ready yet" and "scrolled out of view" — worth confirming this doesn't visibly flash the cursor to (0,0) on terminals that ignore the visible flag.
• Deleting input-cursor.tsx and the tab/highlight tests is correct given the caret is no longer drawn, but it does mean this needs to be reviewed as one unit — there's no way to take just the caret-positioning fix without also accepting the render-loop rewrite.

Overall: correct diagnosis, in-scope, tested. Recommend a maintainer trace through the frame-callback path once against a real terminal (Windows Terminal / iTerm) before porting, since this is exactly the kind of behavior that's hard to unit-test fully.