Analyzed and documented IME focus propagation fix

Summary

Closed, Completed

Understand
Reviewed closed GitHub IME positioning bug.
Understand
Understand
Identified fix and examined code changes.
Understand
Edit
Added documentation on focus propagation pattern.
Edit
Verify
Committed and pushed documentation updates.
Verify

Analyze GitHub issue(s): https://github.com/badlogic/pi-mono/issues/827

For each issue:

Read the issue in full, including all comments and linked issues/PRs.
For bugs:
- Ignore any root cause analysis in the issue (likely wrong)
- Read all related code files in full (no truncation)
- Trace the code path and identify the actual root cause
- Propose a fix
For feature requests:
- Read all related code files in full (no truncation)
- Propose the most concise implementation approach
- List affected files and changes needed

Do NOT implement unless explicitly asked. Analyze and propose only.

The issue is about IME (Input Method Editor) candidate window appearing in the wrong position when typing with Chinese IME in pi's menu filtering. The issue is already CLOSED.

This is a bug related to the TUI (Terminal User Interface) component, specifically the menu filtering functionality. The IME candidate window position is typically controlled by the cursor position in the terminal.

Let me check if this issue was fixed by looking at recent commits or related code. First, let me understand the architecture by looking at relevant files.

The issue involves:

The / command menu
The /model model selector
IME input handling

Let me look at the TUI code to understand how menus work and where cursor positioning happens.

The issue is already CLOSED, but let me analyze it anyway to understand what was involved.

Issue #827: IME candidate window appears in wrong position when filtering menu options

Type: Bug
State: Closed
Version: 0.49.0

Problem: When using Chinese IME to filter menu options (via / command or /model selector), the IME candidate window appears in the wrong position on screen.

Let me check how this was resolved and understand the relevant code:

Found the fix. Let me examine what was changed:

Now I have a clear picture of the issue and its fix.

Summary

Issue #827 Analysis

Problem: When using IME (Input Method Editor) like Chinese IME to filter menu options in pi's TUI, the IME candidate window appeared in the wrong position on screen. This affected:

The / command menu
The /model model selector
Other menu selectors with search/filter inputs

Root Cause: The Focusable interface in pi-tui controls hardware cursor positioning for IME support. When a component has an embedded Input component (search field), the focus state needs to propagate from the parent container to the child Input so the cursor is positioned at the actual text input location.

The affected components were:

ModelSelectorComponent - model picker
ScopedModelsSelectorComponent - Ctrl+P model cycling selector
SessionSelectorComponent (and internal SessionList) - session picker
ExtensionInputComponent - extension text inputs
LoginDialogComponent - OAuth login flow
TreeSelectorComponent (and internal LabelInput) - session tree navigation

These components contained Input children but didn't implement the Focusable interface or propagate focus state to their inputs.

Fix Applied: Each affected component now:

Implements the Focusable interface from @mariozechner/pi-tui
Has a private _focused field with getter/setter
Propagates the focused state to its child Input component(s)

This ensures the hardware cursor is positioned correctly at the actual text input position, allowing the terminal/OS to display the IME candidate window in the correct location.

The issue is already closed and fixed in commit b4f833c2.

Analysis Summary

Issue #827: IME candidate window appears in wrong position when filtering menus

Status: Already CLOSED and fixed in commit b4f833c2

Root Cause

The Focusable interface in pi-tui controls hardware cursor positioning for IME support. Components with embedded Input children (search fields) weren't propagating the focused state to their child inputs. Without this propagation, the hardware cursor remained at the wrong position, causing IME candidate windows to appear misplaced.

The Fix (already applied)

Each affected component now:

Implements the Focusable interface from @mariozechner/pi-tui
Adds a private _focused field with getter/setter
Propagates the focused state to child Input components

Affected components:

ModelSelectorComponent - model picker
ScopedModelsSelectorComponent - Ctrl+P model cycling selector
SessionSelectorComponent (and internal SessionList) - session picker
ExtensionInputComponent - extension text inputs
LoginDialogComponent - OAuth login flow
TreeSelectorComponent (and internal LabelInput) - session tree navigation

Pattern used (example from ModelSelectorComponent):

typescript

export class ModelSelectorComponent extends Container implements Focusable {  private searchInput: Input;    // Focusable implementation - propagate to searchInput for IME cursor positioning  private _focused = false;  get focused(): boolean { return this._focused; }  set focused(value: boolean) {    this._focused = value;    this.searchInput.focused = value;  }  // ...}

export class ModelSelectorComponent extends Container implements Focusable {  private searchInput: Input;    // Focusable implementation - propagate to searchInput for IME cursor positioning  private _focused = false;  get focused(): boolean { return this._focused; }  set focused(value: boolean) {    this._focused = value;    this.searchInput.focused = value;  }  // ...}

This issue is resolved. No further action needed.

ok, we should likely also update @packages/coding-agent/docs/tui.md and @packages/tui/README.md to describe this pattern

Readtui.md

ReadREADME.md

Now I understand both files. I need to add documentation about the pattern for components with embedded Input children that need to propagate focus state for IME cursor positioning.

Looking at the existing content:

packages/coding-agent/docs/tui.md already has a "Focusable Interface (IME Support)" section that explains the basic Focusable interface. I need to add a subsection about Container Components with Embedded Inputs that explains the pattern of propagating focus state.
packages/tui/README.md doesn't mention the Focusable interface at all. I should add a section about it, including the pattern for container components.

Let me add the documentation for both files.

I'll add documentation about the focus propagation pattern to both files.

Editedtui.md

EditedREADME.md

Done. Added documentation about the focus propagation pattern to both files:

packages/coding-agent/docs/tui.md - Added a new subsection "Container Components with Embedded Inputs" under the existing "Focusable Interface (IME Support)" section, with a code example showing how to implement the pattern.

packages/tui/README.md - Added a new "Focusable Interface (IME Support)" section after the Component Interface section, explaining both the basic interface and the container propagation pattern.

Both include:

Code example showing the getter/setter pattern for propagating focused state
Explanation of why this is needed (IME candidate window positioning)
Mention of affected input methods (Chinese, Japanese, Korean)

commit and push

Pushed ad337e30 - documentation for the Focusable interface propagation pattern added to both packages/coding-agent/docs/tui.md and packages/tui/README.md.