fix: hide terminal AI shortcut hint in alternate screens

Author: ZhaoJiSen

ui/composables/useTerminalAiHudLayout.test.ts

@@ -1,16 +1,30 @@
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import { effectScope, nextTick, ref } from "vue";
+import type { TerminalCursorAnchor } from "#koko";
 import { useTerminalAiHudLayout } from "./useTerminalAiHudLayout";
+import { TERMINAL_AI_HINT_IDLE_MS } from "~/utils/terminalAiCommand";
 
 const terminal = vi.hoisted(() => ({
-  anchor: { left: 140, top: 100, width: 8, height: 18 },
-  element: null as HTMLElement | null
+  anchor: { left: 140, top: 100, width: 8, height: 18, bufferType: "normal" } as TerminalCursorAnchor,
+  element: null as HTMLElement | null,
+  cursorListener: (_anchor: TerminalCursorAnchor | null) => {},
+  inputListener: () => {}
 }));
 vi.mock("#koko", () => ({
   getKokoTerminalCursorAnchor: () => terminal.anchor,
   getKokoTerminalElement: () => terminal.element,
-  subscribeKokoTerminalCursorAnchor: () => () => {},
-  subscribeKokoTerminalUserInput: () => () => {}
+  subscribeKokoTerminalCursorAnchor: (_paneId: string, listener: typeof terminal.cursorListener) => {
+    terminal.cursorListener = listener;
+    return () => {
+      terminal.cursorListener = () => {};
+    };
+  },
+  subscribeKokoTerminalUserInput: (_paneId: string, listener: () => void) => {
+    terminal.inputListener = listener;
+    return () => {
+      terminal.inputListener = () => {};
+    };
+  }
 }));
 
 const cleanups: Array<() => void> = [];
@@ -20,14 +34,15 @@ beforeEach(() => {
     vi.stubGlobal("innerWidth", 1000);
     vi.stubGlobal("innerHeight", 800);
   }
-  terminal.anchor = { left: 140, top: 100, width: 8, height: 18 };
+  terminal.anchor = { left: 140, top: 100, width: 8, height: 18, bufferType: "normal" };
 });
 afterEach(() => {
   cleanups.splice(0).forEach((cleanup) => cleanup());
+  vi.useRealTimers();
   vi.unstubAllGlobals();
 });
 
-async function setup() {
+async function setup(sessionInfoReady = false) {
   const area = { left: 100, top: 50, right: 900, bottom: 750, width: 800, height: 700 };
   terminal.element = { getBoundingClientRect: () => area } as HTMLElement;
   const measured = { height: 110, scrollHeight: 110 };
@@ -42,9 +57,12 @@ async function setup() {
   const open = ref(false);
   const scope = effectScope();
   const layout = scope.run(() =>
-    useTerminalAiHudLayout({ paneId: () => "pane", open, sessionInfoReady: () => false })
+    useTerminalAiHudLayout({ paneId: () => "pane", open, sessionInfoReady: () => sessionInfoReady })
   )!;
-  layout.hostRef.value = { getBoundingClientRect: () => area } as HTMLElement;
+  layout.hostRef.value = {
+    getBoundingClientRect: () => area,
+    style: { setProperty: vi.fn() }
+  } as unknown as HTMLElement;
   layout.panelRef.value = Object.defineProperties(new EventTarget(), {
     getBoundingClientRect: { value: () => measured },
     scrollHeight: { get: () => measured.scrollHeight }
@@ -102,6 +120,41 @@ async function setup() {
   return { area, measured, handle, open, layout, dispatch, dispatchResize, position, size };
 }
 
+it("hides the caret hint in alternate screens, keeps it hidden after idle, and restores it on exit", async () => {
+  vi.useFakeTimers();
+  if (!window.setTimeout) {
+    window.setTimeout = globalThis.setTimeout as unknown as typeof window.setTimeout;
+    window.clearTimeout = globalThis.clearTimeout as typeof window.clearTimeout;
+  }
+  vi.stubGlobal("getComputedStyle", () => ({ backgroundColor: "rgb(0, 0, 0)" }));
+  const { layout, open } = await setup(true);
+  open.value = false;
+  layout.startCursorTracking();
+  await nextTick();
+  expect(layout.hintVisible.value).toBe(true);
+
+  terminal.anchor = { ...terminal.anchor, bufferType: "alternate" };
+  terminal.cursorListener(terminal.anchor);
+  await nextTick();
+  expect(layout.hintVisible.value).toBe(false);
+
+  terminal.inputListener();
+  await vi.advanceTimersByTimeAsync(TERMINAL_AI_HINT_IDLE_MS);
+  expect(layout.hintVisible.value).toBe(false);
+
+  terminal.anchor = { ...terminal.anchor, bufferType: "normal" };
+  terminal.cursorListener(terminal.anchor);
+  await nextTick();
+  expect(layout.hintVisible.value).toBe(true);
+
+  terminal.anchor = { ...terminal.anchor, bufferType: "alternate" };
+  terminal.cursorListener(terminal.anchor);
+  await nextTick();
+  await layout.reveal(terminal.element!);
+  expect(open.value).toBe(true);
+  expect(layout.hintVisible.value).toBe(false);
+});
+
 it("moves from the original pointer position without drift and stays moved when the cursor or content changes", async () => {
   const { layout, measured, dispatch, position } = await setup();
   expect(position()).toEqual({ left: "140px", top: "126px" });

ui/composables/useTerminalAiHudLayout.ts

@@ -285,7 +285,8 @@ export function useTerminalAiHudLayout(options: {
       return;
     }
     const host = hostRef.value;
-    if (!host || !anchor) {
+    // Full-screen terminal apps own the content around their cursor.
+    if (!host || !anchor || anchor.bufferType === "alternate") {
       hideHint();
       return;
     }

ui/koko/composables/useTerminalSessionRegistry.ts

@@ -14,6 +14,7 @@ export interface TerminalCursorAnchor {
   top: number;
   width: number;
   height: number;
+  bufferType?: "normal" | "alternate";
 }
 
 interface LocalShellSession {
@@ -47,7 +48,11 @@ function getRegisteredTerminal(tabId: string) {
 function sameCursorAnchor(left: TerminalCursorAnchor | null | undefined, right: TerminalCursorAnchor | null) {
   if (!left || !right) return left === right;
   return (
-    left.left === right.left && left.top === right.top && left.width === right.width && left.height === right.height
+    left.left === right.left &&
+    left.top === right.top &&
+    left.width === right.width &&
+    left.height === right.height &&
+    left.bufferType === right.bufferType
   );
 }
 
@@ -88,10 +93,12 @@ function rebindTerminalCursorAnchor(tabId: string) {
   const cursorDisposable = terminal.onCursorMove(schedule);
   const resizeDisposable = terminal.onResize(schedule);
   const scrollDisposable = terminal.onScroll(schedule);
+  const bufferDisposable = terminal.buffer.onBufferChange(schedule);
   stopCursorAnchorBindings.set(tabId, () => {
     cursorDisposable.dispose();
     resizeDisposable.dispose();
     scrollDisposable.dispose();
+    bufferDisposable.dispose();
   });
   emitTerminalCursorAnchor(tabId);
 }
@@ -225,7 +232,8 @@ export function getKokoTerminalCursorAnchor(tabId: string): TerminalCursorAnchor
     left: bounds.left + buffer.cursorX * cellWidth,
     top: bounds.top + cursorRow * cellHeight,
     width: cellWidth,
-    height: cellHeight
+    height: cellHeight,
+    bufferType: buffer.type
   };
 }
 

ui/koko/tests/terminal/terminalCursorAnchor.test.ts

@@ -6,6 +6,7 @@ import {
   subscribeKokoTerminalUserInput,
   unregisterKokoTerminalSession
 } from "#koko/composables/useTerminalSessionRegistry";
+import type { TerminalCursorAnchor } from "#koko/composables/useTerminalSessionRegistry";
 
 function flushCursorAnchor() {
   return new Promise<void>((resolve) => {
@@ -16,17 +17,25 @@ function flushCursorAnchor() {
 it("tracks the Xterm buffer cursor for the inline Terminal AI hint", async () => {
   let cursorListener = () => {};
   let scrollListener = () => {};
+  let bufferListener = () => {};
   const cursorDisposable = { dispose: vi.fn() };
   const resizeDisposable = { dispose: vi.fn() };
   const scrollDisposable = { dispose: vi.fn() };
+  const bufferDisposable = { dispose: vi.fn() };
   const screen = {
     getBoundingClientRect: () => ({ left: 100, top: 200, width: 800, height: 400 })
   };
-  const activeBuffer = { cursorX: 2, cursorY: 3, baseY: 40, viewportY: 40 };
+  const activeBuffer = { type: "normal", cursorX: 2, cursorY: 3, baseY: 40, viewportY: 40 };
   const terminal = {
     cols: 80,
     rows: 20,
-    buffer: { active: activeBuffer },
+    buffer: {
+      active: activeBuffer,
+      onBufferChange: vi.fn((listener: () => void) => {
+        bufferListener = listener;
+        return bufferDisposable;
+      })
+    },
     element: { querySelector: () => screen },
     onCursorMove: vi.fn((listener: () => void) => {
       cursorListener = listener;
@@ -38,7 +47,7 @@ it("tracks the Xterm buffer cursor for the inline Terminal AI hint", async () =>
       return scrollDisposable;
     })
   } as unknown as Terminal;
-  const anchors: Array<{ left: number; top: number; width: number; height: number } | null> = [];
+  const anchors: Array<TerminalCursorAnchor | null> = [];
 
   registerKokoTerminalSession("cursor-pane", {
     socket: { readyState: WebSocket.OPEN, send: vi.fn() } as unknown as WebSocket,
@@ -47,13 +56,13 @@ it("tracks the Xterm buffer cursor for the inline Terminal AI hint", async () =>
   });
   const unsubscribe = subscribeKokoTerminalCursorAnchor("cursor-pane", (anchor) => anchors.push(anchor));
 
-  expect(anchors.at(-1)).toEqual({ left: 120, top: 260, width: 10, height: 20 });
+  expect(anchors.at(-1)).toEqual({ left: 120, top: 260, width: 10, height: 20, bufferType: "normal" });
   expect(anchors).toHaveLength(1);
 
   activeBuffer.viewportY = 35;
   scrollListener();
   await flushCursorAnchor();
-  expect(anchors.at(-1)).toEqual({ left: 120, top: 360, width: 10, height: 20 });
+  expect(anchors.at(-1)).toEqual({ left: 120, top: 360, width: 10, height: 20, bufferType: "normal" });
 
   activeBuffer.viewportY = 20;
   scrollListener();
@@ -70,17 +79,30 @@ it("tracks the Xterm buffer cursor for the inline Terminal AI hint", async () =>
 
   await flushCursorAnchor();
   expect(anchors).toHaveLength(4);
-  expect(anchors.at(-1)).toEqual({ left: 140, top: 300, width: 10, height: 20 });
+  expect(anchors.at(-1)).toEqual({ left: 140, top: 300, width: 10, height: 20, bufferType: "normal" });
 
   cursorListener();
   await flushCursorAnchor();
   expect(anchors).toHaveLength(4);
 
+  // Buffer switches must notify even when the cursor geometry stays unchanged.
+  activeBuffer.type = "alternate";
+  bufferListener();
+  await flushCursorAnchor();
+  expect(anchors).toHaveLength(5);
+  expect(anchors.at(-1)?.bufferType).toBe("alternate");
+  activeBuffer.type = "normal";
+  bufferListener();
+  await flushCursorAnchor();
+  expect(anchors).toHaveLength(6);
+  expect(anchors.at(-1)?.bufferType).toBe("normal");
+
   unsubscribe();
   unregisterKokoTerminalSession("cursor-pane");
   expect(cursorDisposable.dispose).toHaveBeenCalled();
   expect(resizeDisposable.dispose).toHaveBeenCalled();
   expect(scrollDisposable.dispose).toHaveBeenCalled();
+  expect(bufferDisposable.dispose).toHaveBeenCalled();
 });
 
 it("notifies Terminal AI when the user types without intercepting xterm data", () => {