Fixed terminal rendering bug and cleaned test helper

Summary

Closed, Completed

Understand
Reviewed GitHub issue and image.
Understand
Understand
Examined terminal UI editor code.
Understand
Build
Fixed screen corruption bug.
Build
Edit
Removed unnecessary test helper file.
Edit
Cleanup
Merged fix and cleaned branch.
Cleanup

Analyze GitHub issue(s): https://github.com/badlogic/pi-mono/issues/732 you will have to pull downt he image and read it as well to understand.

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.

Let me download and view that image to understand the visual issue:

The image shows a severe rendering bug where the content is being double-rendered (ghosting/overlapping lines). Lines appear duplicated, and the entire layout is corrupted. This looks like a classic terminal rendering issue where content is being written beyond the visible terminal area, causing screen corruption.

The issue mentions:

setEditorText with text larger than screen causes corruption
ESC stops working (but ctrl+c still works)
The editor should scroll when reaching terminal limits

Let me look at the TUI package, specifically the editor component and how setEditorText works.

The image shows severe screen corruption with doubled/overlapping lines. This is a classic terminal rendering issue where content overflows the visible area. Let me examine the TUI editor code:

Now let me examine the main TUI rendering system:

Now let me look at how the editor is used in the interactive mode:

The file is large. Let me search for the key methods related to setEditorText and the editor layout:

The editor has no height constraint. Let me understand how the TUI lays out components and why there's no scrolling.

The issue is clear: the Editor component in the TUI renders ALL lines, with no maximum height or scrolling capability. When setEditorText sets text larger than the terminal can fit, the editor renders all those lines, which causes the TUI's rendering to overflow the terminal, resulting in:

Visual corruption (lines rendered off-screen wrap back)
ESC stops working (because the rendering state tracking is broken)

The fix would be to add a maximum height to the editor and implement vertical scrolling within it. Let me look more closely at how rendering works and propose a specific fix.

Let me check how the TUI's doRender manages screen overflow:

Now I understand the full picture. The issue is:

The TUI renders all content lines sequentially without any viewport clipping
When the total content exceeds terminal height, the cursor tracking (cursorRow) gets out of sync
The differential rendering assumes content stays within certain bounds but doesn't handle overflow

The key insight is in doRender():

It writes all lines directly to the terminal using \r\n sequences
If newLines.length > terminal height, the lines wrap/scroll in unpredictable ways
cursorRow is set to newLines.length - 1, but this doesn't account for terminal scrolling

The editor is the problematic component because:

It renders ALL layout lines without any height constraint
When setEditorText sets a large prompt, the editor could generate dozens of lines
The TUI then tries to render these, exceeding terminal height

Let me also check if there's any maxHeight concept for regular (non-overlay) components.

Now let me check the CustomEditor component that's used in interactive mode:

Let me check the TUI documentation:

Now I have a complete understanding of the problem:

Root Cause Analysis

The issue is that the Editor component renders ALL lines without any maximum height constraint. When setEditorText is called with text that produces more lines than the terminal can display:

The Editor.render() method generates ALL layoutLines (see line 325-390 in editor.ts)
The TUI's doRender() outputs ALL these lines sequentially with \r\n
When total lines exceed terminal height, the terminal scrolls unpredictably
The cursor tracking (cursorRow) becomes incorrect
Subsequent renders corrupt the display because differential rendering assumes lines stay in place

Evidence from the Screenshot

The image shows the classic "double-rendering" artifact where:

Lines appear to be written twice (shifted/overlapping)
Content wraps back around after going off-screen
The state tracking is completely broken

Why ESC Stops Working

ESC stops working because:

The input handling depends on handleInput() being called on the focused component
When the TUI's cursor tracking is broken, the rendering gets into a bad state
The TUI may not be correctly forwarding input, OR the component itself is in a bad state

However, Ctrl+C still works because it's handled at a lower level (SIGINT).

Proposed Fix

The Editor component needs a maximum height constraint with vertical scrolling. Here's the approach:

Option A: Add maxHeight to Editor (Recommended)

Add maxHeight?: number parameter to Editor (passed during render or set externally)
Track a scrollOffset for vertical scrolling
In render(), only output lines from scrollOffset to scrollOffset + maxHeight
Ensure the cursor line is always visible by adjusting scrollOffset
The cursor movement methods need to call a method to ensure the cursor is in view
Alternatively, the TUI could pass available height to components, but this requires changing the Component interface and is less ideal.

Implementation Details (Option A)

I need to add state variables for maxLines (defaulting to Infinity, configurable) and scrollOffset (starting at 0) to track the viewport. Then modify render() to slice the layoutLines array between scrollOffset and scrollOffset + maxLines, calling ensureCursorVisible() first to adjust the scroll position so the cursor stays in view.

The ensureCursorVisible() method should locate which layout line has the cursor, then adjust scrollOffset upward if the cursor is above the current view or downward if it's below. I'll also add a setMaxLines() setter for external control, which the interactive mode can call after calculating the available terminal height minus space for other UI elements.

Affected Files

Changes needed in packages/tui/src/components/editor.ts for the scrolling logic, and potentially packages/coding-agent/src/modes/interactive/interactive-mode.ts to set the editor's max height based on terminal dimensions.

The cleanest approach avoids breaking the Component interface—instead of modifying render(width: number) to accept height, I'll add an optional maxLines property directly to the Editor class. This follows the existing pattern used by SelectList with its maxVisible parameter, keeping the implementation consistent with other height-constrained components in the codebase.

Now I have a complete understanding of the issue.

Issue #732 Analysis: "Prompts larger than the screen fuck up everything"

Summary

When setEditorText loads text that produces more lines than fit in the terminal, the TUI rendering breaks completely, causing visual corruption (doubled/overlapping lines) and ESC stops working.

Root Cause

The Editor component has no height constraint. It renders ALL layout lines regardless of terminal size:

In packages/tui/src/components/editor.ts (lines 318-390):

typescript

render(width: number): string[] {    const layoutLines = this.layoutText(width);  // Can be unlimited lines    const result: string[] = [];        result.push(horizontal.repeat(width));  // top border        // ❌ PROBLEM: Renders ALL layout lines without any limit    for (const layoutLine of layoutLines) {        // ... render each line        result.push(displayText + padding);    }        result.push(horizontal.repeat(width));  // bottom border    return result;}

render(width: number): string[] {    const layoutLines = this.layoutText(width);  // Can be unlimited lines    const result: string[] = [];        result.push(horizontal.repeat(width));  // top border        // ❌ PROBLEM: Renders ALL layout lines without any limit    for (const layoutLine of layoutLines) {        // ... render each line        result.push(displayText + padding);    }        result.push(horizontal.repeat(width));  // bottom border    return result;}

When the total rendered lines exceed terminal height:

The TUI writes lines sequentially with \r\n, causing terminal scrolling
The cursor position tracking (cursorRow in TUI) becomes desynchronized
Differential rendering then writes to wrong positions, creating the ghosting/corruption seen in the screenshot
Input handling breaks because the TUI state is inconsistent

Why ESC Stops Working

The TUI's input forwarding depends on consistent state. When rendering breaks, the component may not receive or correctly process input. Ctrl+C still works because it triggers SIGINT at the OS level.

Proposed Fix

Add vertical scrolling with a max height constraint to the Editor, following the same pattern as SelectList which already has maxVisible:

Changes to packages/tui/src/components/editor.ts:

Add new state:

typescript

private maxLines: number = Infinity;  // Max visible content linesprivate scrollOffset: number = 0;     // First visible line index

private maxLines: number = Infinity;  // Max visible content linesprivate scrollOffset: number = 0;     // First visible line index

Add setter method:

Add scroll adjustment method:

typescript

private ensureCursorVisible(visualLines: LayoutLine[]): void {    // Find which visual line has the cursor    const cursorVisualLine = visualLines.findIndex(vl => vl.hasCursor);    if (cursorVisualLine === -1) return;        // Adjust scroll if cursor is out of view    if (cursorVisualLine < this.scrollOffset) {        this.scrollOffset = cursorVisualLine;    } else if (cursorVisualLine >= this.scrollOffset + this.maxLines) {        this.scrollOffset = cursorVisualLine - this.maxLines + 1;    }}

private ensureCursorVisible(visualLines: LayoutLine[]): void {    // Find which visual line has the cursor    const cursorVisualLine = visualLines.findIndex(vl => vl.hasCursor);    if (cursorVisualLine === -1) return;        // Adjust scroll if cursor is out of view    if (cursorVisualLine < this.scrollOffset) {        this.scrollOffset = cursorVisualLine;    } else if (cursorVisualLine >= this.scrollOffset + this.maxLines) {        this.scrollOffset = cursorVisualLine - this.maxLines + 1;    }}

Modify render() to slice visible lines:

typescript

render(width: number): string[] {    const layoutLines = this.layoutText(width);        // Ensure cursor is visible before slicing    this.ensureCursorVisible(layoutLines);        // Slice to visible range    const visibleLines = this.maxLines === Infinity         ? layoutLines         : layoutLines.slice(this.scrollOffset, this.scrollOffset + this.maxLines);        const result: string[] = [];    result.push(horizontal.repeat(width));        for (const layoutLine of visibleLines) {  // Only visible lines        // ... existing rendering logic    }        result.push(horizontal.repeat(width));    // ... autocomplete rendering    return result;}

render(width: number): string[] {    const layoutLines = this.layoutText(width);        // Ensure cursor is visible before slicing    this.ensureCursorVisible(layoutLines);        // Slice to visible range    const visibleLines = this.maxLines === Infinity         ? layoutLines         : layoutLines.slice(this.scrollOffset, this.scrollOffset + this.maxLines);        const result: string[] = [];    result.push(horizontal.repeat(width));        for (const layoutLine of visibleLines) {  // Only visible lines        // ... existing rendering logic    }        result.push(horizontal.repeat(width));    // ... autocomplete rendering    return result;}

Call ensureCursorVisible() after cursor movements (or just let render() handle it)

Changes to packages/coding-agent/src/modes/interactive/interactive-mode.ts:

In init() or wherever the editor is configured, calculate and set a reasonable max height based on terminal dimensions minus other UI elements (header, footer, status, etc.).

Alternative Consideration

A more invasive fix would change the Component interface to pass both width and height:

However, this is a breaking change and affects all components. The maxLines approach is self-contained to the Editor.

Files Affected

packages/tui/src/components/editor.ts - Add scrolling logic (~30-40 lines)
packages/coding-agent/src/modes/interactive/interactive-mode.ts - Set editor max height (optional, could use a sensible default like terminal height - 10)

editor has access to tui, which has access to terminal, which tells us rows and cols, no?

The user is asking if the Editor has access to the TUI, which would give it access to terminal dimensions. Let me check if that's the case.

Looking at the Editor constructor:

typescript

constructor(theme: EditorTheme) {    this.theme = theme;    this.borderColor = theme.borderColor;}

constructor(theme: EditorTheme) {    this.theme = theme;    this.borderColor = theme.borderColor;}

No, the Editor doesn't receive a TUI instance. It only gets a theme.

Let me check the CustomEditor:

typescript

constructor(theme: EditorTheme, keybindings: KeybindingsManager) {    super(theme);    this.keybindings = keybindings;}

constructor(theme: EditorTheme, keybindings: KeybindingsManager) {    super(theme);    this.keybindings = keybindings;}

Also no TUI reference.

However, looking at how components like Loader work:

typescript

const loader = new Loader(  tui,                              // TUI instance for render updates  (s) => chalk.cyan(s),            // spinner color function  ...);

const loader = new Loader(  tui,                              // TUI instance for render updates  (s) => chalk.cyan(s),            // spinner color function  ...);

Loader gets the TUI passed to it. But Editor doesn't.

The user is suggesting that we could pass the TUI to the Editor, and then the Editor could query tui.terminal.rows to know the available height dynamically during render.

This would be a cleaner solution than having to externally set maxLines. The Editor could self-limit based on available terminal height.

Let me verify the TUI structure:

TUI has terminal: Terminal
Terminal interface has get rows(): number and get columns(): number

So yes, if the Editor had access to the TUI (or just the Terminal), it could query the height during render and auto-limit itself.

The question is whether to:

Pass TUI to Editor constructor
Pass Terminal to Editor constructor
Pass just a height getter function

Option 1 or 2 would work. Option 2 is cleaner (less coupling). But actually, looking at how the coding-agent creates the editor:

And the TUI is created right there too:

So it would be easy to pass this.ui or this.ui.terminal to the editor. Since the TUI is public, the Editor could access tui.terminal.rows directly. The simplest approach might be passing a getMaxHeight?: () => number callback function to the Editor constructor, allowing it to query available height dynamically during rendering without tight coupling to the TUI instance.

You're right, let me check:

So the Editor constructor only takes a theme. It doesn't have access to TUI or Terminal. But the user is right that we could pass it in.

Looking at the interactive-mode.ts, the TUI is created at line ~240-243:

typescript

this.ui = new TUI(new ProcessTerminal());...this.defaultEditor = new CustomEditor(getEditorTheme(), this.keybindings);

this.ui = new TUI(new ProcessTerminal());...this.defaultEditor = new CustomEditor(getEditorTheme(), this.keybindings);

So we could pass this.ui to the CustomEditor constructor, or just pass this.ui.terminal for the rows/cols.

The cleanest approach would be to:

Add an optional terminal?: Terminal parameter to Editor constructor
During render, if terminal is set, use terminal.rows to calculate max visible lines
This would be backward compatible (terminal is optional)

Or even simpler: just pass a getHeight?: () => number function.

Currently, Editor doesn't receive TUI or Terminal:

typescript

// Editor constructor - only gets themeconstructor(theme: EditorTheme) {    this.theme = theme;    this.borderColor = theme.borderColor;}
// CustomEditor - gets theme + keybindings, no TUIconstructor(theme: EditorTheme, keybindings: KeybindingsManager) {    super(theme);    this.keybindings = keybindings;}

// Editor constructor - only gets themeconstructor(theme: EditorTheme) {    this.theme = theme;    this.borderColor = theme.borderColor;}
// CustomEditor - gets theme + keybindings, no TUIconstructor(theme: EditorTheme, keybindings: KeybindingsManager) {    super(theme);    this.keybindings = keybindings;}

But you're right, it would be cleaner to pass a reference. Two options:

Option A: Pass Terminal to Editor

typescript

constructor(theme: EditorTheme, terminal?: Terminal) {    // In render(), use terminal?.rows to auto-limit}

constructor(theme: EditorTheme, terminal?: Terminal) {    // In render(), use terminal?.rows to auto-limit}

Option B: Pass a height getter (more decoupled)

typescript

constructor(theme: EditorTheme, options?: { getAvailableHeight?: () => number }) {    // In render(), call getAvailableHeight?.() }

constructor(theme: EditorTheme, options?: { getAvailableHeight?: () => number }) {    // In render(), call getAvailableHeight?.() }

Option B is nice because the caller can account for other UI elements (header, footer, status) when computing available height. The Editor doesn't need to know about the full layout.

In interactive-mode.ts, it would be:

ok, then lets have the editor (and customeditor) receive Tui as a parameter to the constructor (first parameter)

The user wants to pass TUI as the first parameter to both Editor and CustomEditor constructors. This will give the Editor access to terminal dimensions via tui.terminal.rows.

Let me outline the changes needed:

packages/tui/src/components/editor.ts:
- Add TUI as first constructor parameter
- Store reference to TUI
- In render(), use this.tui.terminal.rows to calculate max visible lines
- Implement scrolling logic
packages/coding-agent/src/modes/interactive/components/custom-editor.ts:
- Update constructor to take TUI as first parameter
- Pass it to super()
packages/coding-agent/src/modes/interactive/interactive-mode.ts:
- Update CustomEditor instantiation to pass this.ui
Any other places that create Editor instances need to be updated

Let me check for all Editor usages:

Let me find all places where Editor/CustomEditor is instantiated:

That's a lot of places. The tests use Editor without TUI. We need to make TUI optional to maintain backward compatibility, OR we need to update all tests.

Actually, for tests, we could pass undefined or create a mock TUI. But making it optional is cleaner for backward compatibility.

Wait, the user said "first parameter". If TUI is optional and first, the signature becomes awkward:

That's not great. Better options:

Make TUI required first param, update all call sites
Make TUI optional last param (but user said first)
Use an options object

Let me reconsider. The user specifically wants TUI as first parameter. For tests, we could:

Create a minimal mock TUI
Or pass null and have Editor handle it gracefully

Actually, looking at tests, they don't really need the height limiting behavior - they're unit tests for editing behavior. So we could make TUI optional (can be undefined), and if undefined, the editor just doesn't limit height (current behavior).

In render:

This maintains backward compatibility for tests while enabling the feature when TUI is provided.

Actually wait, looking at the user's request again - they said TUI as first parameter. I should make it TUI | undefined to keep tests working without major changes.

Let me draft the changes:

Editor: constructor(tui: TUI | undefined, theme: EditorTheme)
CustomEditor: constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager)
Update all usages
Tests pass undefined as the first argument, while production code passes the actual TUI instance. I should also check how extension examples and extension-editor.ts instantiate editors to see if they need TUI access.

There are many usages, mostly in tests. I'll make TUI the first parameter but allow undefined for backward compatibility in tests. When undefined, the editor won't limit height (current behavior).

Here's the proposed fix:

Files to modify:

packages/tui/src/components/editor.ts - Add TUI param, implement scrolling
packages/coding-agent/src/modes/interactive/components/custom-editor.ts - Add TUI param
packages/coding-agent/src/modes/interactive/interactive-mode.ts - Pass TUI
packages/coding-agent/src/modes/interactive/components/extension-editor.ts - Pass TUI
packages/coding-agent/examples/extensions/question.ts - Pass TUI
packages/coding-agent/examples/extensions/questionnaire.ts - Pass TUI
packages/tui/test/editor.test.ts - Pass undefined as first arg
packages/tui/test/chat-simple.ts - Pass TUI

Should I implement this now?

no backward compatibility

The user wants no backward compatibility - TUI should be a required first parameter. This means all usages must be updated to pass a TUI instance.

For tests, we'll need to either:

Create a mock TUI
Use a real TUI with a VirtualTerminal

Looking at the test file, they probably have access to TUI/VirtualTerminal already since this is the TUI package. Let me check what's available in the test setup.

Actually, for unit tests of editor behavior (text manipulation, cursor movement, etc.), we don't really need a real terminal. We could create a minimal TUI with a mock terminal that just returns fixed rows/cols.

Let me outline the changes:

packages/tui/src/components/editor.ts:
- Constructor: constructor(tui: TUI, theme: EditorTheme)
- Store this.tui = tui
- In render(), calculate max lines from this.tui.terminal.rows
- Implement scroll offset tracking
packages/coding-agent/src/modes/interactive/components/custom-editor.ts:
- Constructor: constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager)
- Pass tui to super()
All other files - update to pass TUI

For tests, we need to create a TUI instance. Looking at the test files, they likely can import TUI and create one with a VirtualTerminal or mock.

This is a clean breaking change - TUI is required.

Got it. TUI is required, all call sites must be updated.

Summary of changes:

packages/tui/src/components/editor.ts
- Constructor: constructor(tui: TUI, theme: EditorTheme)
- Add scroll offset tracking
- In render(): limit visible lines based on this.tui.terminal.rows, keep cursor in view
packages/coding-agent/src/modes/interactive/components/custom-editor.ts
- Constructor: constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager)
packages/coding-agent/src/modes/interactive/interactive-mode.ts
- Pass this.ui to CustomEditor
packages/coding-agent/src/modes/interactive/components/extension-editor.ts
- Pass TUI to Editor
packages/coding-agent/examples/extensions/question.ts
- Pass TUI to Editor
packages/coding-agent/examples/extensions/questionnaire.ts
- Pass TUI to Editor
packages/tui/test/editor.test.ts
- Create TUI with mock/virtual terminal for each test
packages/tui/test/chat-simple.ts
- Pass TUI to Editor

Should I implement?

create a feature branch, then go to town

you still there?

Yes, on it!

Now let me implement the changes. First, update the Editor:

Editededitor.ts

Good, TUI is exported. But wait, I'm importing TUI as a type but it's a class. Let me check if we need to import it differently. Actually, using import type { TUI } works for type annotations, but since we're storing a reference to it, we might need the actual import.

Actually, import type is fine because we're only using TUI for type annotations (the parameter type and the stored property type). We don't need to instantiate it.

Now let me update the class to add the TUI parameter and scrolling logic:

Editededitor.ts

Now update the CustomEditor:

Editedcustom-editor.ts

Now update interactive-mode.ts:

Editedinteractive-mode.ts

Editedextension-editor.ts

Editedquestion.ts

Editedquestionnaire.ts

Now update the test file:

Editededitor.test.ts

Editedchat-simple.ts