fix(tui): rebuild chat after closing full viewport interactions (#328)

Author: hetaoBackend

docs/tui-capabilities.md

@@ -85,8 +85,10 @@ and initial prompt are not applied.
 
 In regular mode, independent feature panels occupy the complete visible terminal
 area, including short Rewind previews and scope pickers. Closing a panel restores
-the current conversation. When running content shrinks entirely within the current
-screen, the renderer keeps native scrollback and the Composer position stable.
+the current conversation. Closing a full-viewport interaction rebuilds the chat
+screen so its temporary rows do not leave a large blank area above the conversation.
+When running content shrinks entirely within the current screen, the renderer
+keeps native scrollback and the Composer position stable.
 Freed rows temporarily remain blank at the top of the active screen and subsequent
 output reuses them. This avoids resetting the host's scroll position when a turn
 finishes. Redundant resize notifications with unchanged dimensions do not rebuild

packages/tui/src/tui/app-composition.ts

@@ -425,7 +425,7 @@ export function createTuiApplicationSurface(options: {
   readonly liveRunId: (snapshot?: TuiChatSnapshot) => string | undefined;
   readonly shouldResumeDraftAfterLogin: () => boolean;
   readonly isActive: () => boolean;
-  readonly requestInteractionRender: () => void;
+  readonly requestInteractionRender: (rebuild?: boolean) => void;
   readonly mode: () => TuiMode;
   readonly switchMode: (mode: TuiMode) => boolean;
   readonly chatMode: TuiMode;

packages/tui/src/tui/app.ts

@@ -820,8 +820,10 @@ export function createTuiApp(options: CreateTuiAppOptions): TuiApp {
     activity,
     composer,
   });
-  function requestInteractionRender(): void {
-    if (started && !stopped) tui.requestImmediateRender();
+  function requestInteractionRender(rebuild = false): void {
+    if (!started || stopped) return;
+    if (rebuild) tui.requestRender(true);
+    else tui.requestImmediateRender();
   }
   const controllerReady = controller.initialize();
   const ready = controllerReady.then(async () => {

packages/tui/src/tui/shell/interaction-surface.ts

@@ -8,7 +8,7 @@ export class TuiInteractionSurface {
   constructor(
     private readonly host: TuiInlinePanelHost,
     private readonly surfaces: TuiSurfaceHost,
-    private readonly requestRender: () => void,
+    private readonly requestRender: (rebuild?: boolean) => void,
     private readonly onActiveChanged?: (active: boolean) => void,
     private readonly followFullscreenBottom?: () => void,
   ) {}
@@ -38,11 +38,13 @@ export class TuiInteractionSurface {
 
   close(panel?: Component): boolean {
     if (!this.host.isActive(panel)) return false;
+    const rebuild = this.surfaces.getChatMode() === 'regular' && this.host.fullscreenViewport;
     if (this.layer && !this.layer.close()) return false;
     this.layer = undefined;
     if (!this.host.close(panel)) return false;
     this.onActiveChanged?.(false);
-    this.requestRender();
+    if (rebuild) this.requestRender(true);
+    else this.requestRender();
     return true;
   }
 

packages/tui/test/unit/tui-app.test.ts

@@ -189,6 +189,13 @@ class FakeTerminal implements Terminal {
   }
 }
 
+// Apple Terminal can save ED 2 clears into scrollback before the renderer clears history.
+class ClearToScrollbackTerminal extends VirtualTerminal {
+  override write(data: string): void {
+    super.write(data.replaceAll("\x1b[2J", `\x1b[${this.rows};1H${"\r\n".repeat(this.rows)}\x1b[2J`));
+  }
+}
+
 function renderTerminalViewport(
   app: ReturnType<typeof createTuiApp>,
   terminal: FakeTerminal,
@@ -6041,6 +6048,93 @@ describe("createTuiApp", () => {
     await app.stop();
   });
 
+  it("does not push the conversation downward after closing /usage", async () => {
+    const terminal = new VirtualTerminal(80, 50);
+    const runtime = createRuntime();
+    vi.mocked(runtime.getAccountStatus).mockResolvedValue({
+      status: "ready",
+      authMode: "managed-login",
+      managedTokenPresent: true,
+      modelSource: "token-plan",
+      tokenPlanQuotaState: "available",
+      tokenPlanSummary: { tier: "Ultra Plan", creditBalance: "100" },
+      tokenPlanQuota: {
+        fiveHour: { remainingPercent: 75, unlimited: false },
+        weekly: { remainingPercent: 50, unlimited: false },
+        video: { remainingCount: 5, totalCount: 5, unlimited: false },
+      },
+      warnings: [],
+    });
+    const app = createTuiApp({
+      runtime,
+      terminal,
+      version: "0.1.0",
+      workspaceDir: "/workspace",
+    });
+
+    app.start();
+    try {
+      await app.ready;
+      for (let index = 0; index < 2; index++) await app.submit(`Message ${index}`);
+      app.tui.renderNow();
+      await terminal.flush();
+      expect(terminal.getViewport().join("\n")).toContain("Message 1");
+      const firstContentRowBefore = terminal.getViewport().findIndex((line) => line.trim().length > 0);
+
+      await app.submit("/usage");
+      app.tui.renderNow();
+      await terminal.flush();
+      expect(terminal.getViewport().join("\n")).toContain("Usage");
+
+      terminal.sendInput("\x1b");
+      app.tui.renderNow();
+      await terminal.flush();
+      const viewport = terminal.getViewport().join("\n");
+      expect(viewport).toContain("Message 1");
+      expect(viewport).toContain("Message");
+      expect(app.tui.render(80).findIndex((line) => line.trim().length > 0)).toBe(firstContentRowBefore);
+      expect(terminal.getViewport().findIndex((line) => line.trim().length > 0)).toBe(firstContentRowBefore);
+    } finally {
+      await app.stop();
+    }
+  });
+
+  it.each([
+    ['xterm', VirtualTerminal],
+    ['clear-to-scrollback terminal', ClearToScrollbackTerminal],
+  ] as const)('restores unique long history after /usage on %s', async (_name, Terminal) => {
+    const terminal = new Terminal(80, 24);
+    const app = createTuiApp({
+      runtime: createRuntime(),
+      terminal,
+      version: "0.1.0",
+      workspaceDir: "/workspace",
+    });
+
+    app.start();
+    try {
+      await app.ready;
+      for (let index = 0; index < 12; index++) await app.submit(`Message ${index}`);
+      await app.submit("/usage");
+      app.tui.renderNow();
+      await terminal.flush();
+      expect(terminal.getViewport().join("\n")).toContain("Usage");
+
+      terminal.sendInput("\x1b");
+      app.tui.renderNow();
+      await terminal.flush();
+      const history = terminal.getScrollBuffer();
+      for (let index = 0; index < 12; index++) {
+        expect(history.filter((line) => line.trimEnd().endsWith(`› Message ${index}`))).toHaveLength(1);
+      }
+      expect(history.join("\n")).not.toContain("Session usage");
+      expect(terminal.getViewport().join("\n")).toContain("Ask Mcode to do anything");
+      expect(terminal.getViewport().join("\n")).toContain("/workspace");
+    } finally {
+      await app.stop();
+    }
+  });
+
   it("uses public Runtime owners for Session inspection commands", async () => {
     const terminal = new FakeTerminal();
     terminal.rows = 40;

packages/tui/test/unit/tui-surface-host.test.ts

@@ -70,6 +70,31 @@ function createRecordingPresenter(): {
 }
 
 describe('TuiSurfaceHost', () => {
+  it.each([
+    { mode: 'regular', fullscreenViewport: true, rebuild: true },
+    { mode: 'regular', fullscreenViewport: false, rebuild: false },
+    { mode: 'fullscreen', fullscreenViewport: true, rebuild: false },
+  ] as const)('requests rebuild on interaction close only for a regular full-viewport panel ($mode, $fullscreenViewport)', ({ mode, fullscreenViewport, rebuild }) => {
+    const inline = new TuiInlinePanelHost();
+    const host = createSurfaceHost({
+      chat: { component: inline, focus: component([]) },
+      chatMode: mode,
+      mode: () => mode,
+      setFocus: vi.fn(),
+      requestRender: vi.fn(),
+    });
+    const requestRender = vi.fn();
+    const interaction = new TuiInteractionSurface(inline, host, requestRender);
+    const panel = { ...component(['inspection']), fullscreenViewport };
+
+    interaction.show(panel);
+    requestRender.mockClear();
+    expect(interaction.close(panel)).toBe(true);
+    expect(requestRender).toHaveBeenCalledOnce();
+    if (rebuild) expect(requestRender).toHaveBeenCalledWith(true);
+    else expect(requestRender).toHaveBeenCalledWith();
+  });
+
   it.each(['regular', 'fullscreen'] as const)(
     'passes current terminal size to leaf features in %s',
     (mode) => {