fix(terminal): improve keyboard navigation for macOS shortcuts (#448)

This commit is contained in:
José Almeida
2026-03-19 12:02:33 +00:00
committed by GitHub
parent f06577e989
commit 3426eb5f6f
7 changed files with 318 additions and 43 deletions
@@ -643,6 +643,12 @@ func mergeEnv(env map[string]string) []string {
}
}
// Set terminal type for xterm.js PTY connections. The parent process's TERM
// reflects its own terminal (e.g. "screen" in tmux), not the xterm.js frontend,
// so we always override it. Custom env vars (below) can still override if needed.
base["TERM"] = "xterm-256color"
base["COLORTERM"] = "truecolor"
// Override with custom variables
for k, v := range env {
base[k] = v
@@ -104,6 +104,13 @@ func checkWebSocketOrigin(r *http.Request) bool {
// First byte 0x01 indicates resize, followed by JSON {cols, rows}.
const resizeCommandByte = 0x01
// isResizeCommand checks whether a binary frame is a resize command.
// Resize messages use 0x01 as a prefix followed by a JSON object (starts with '{').
// A bare 0x01 or 0x01 followed by non-JSON data is regular PTY input (e.g. Ctrl+A).
func isResizeCommand(data []byte) bool {
return len(data) >= 2 && data[0] == resizeCommandByte && data[1] == '{'
}
const (
passthroughReadyTimeout = 30 * time.Second
shellExecutionTimeout = 15 * time.Second
@@ -535,7 +542,7 @@ func (h *TerminalHandler) runTerminalBridge(
continue
}
if data[0] == resizeCommandByte {
if isResizeCommand(data) {
newID, newDirect := h.handleResizeCommand(data[1:], sessionID, processID, interactiveRunner, wsw, directOutputSet, &ptyWriter)
processID = newID
directOutputSet = newDirect
@@ -1032,7 +1039,7 @@ func (h *TerminalHandler) runUserShellBridge(
continue
}
if data[0] == resizeCommandByte {
if isResizeCommand(data) {
directOutputSet = h.handleUserShellResizeCommand(
data[1:], sessionID, terminalID, processID,
interactiveRunner, wsw, directOutputSet, &ptyWriter,
@@ -13,12 +13,12 @@ import { useSessionAgentctl } from "@/hooks/domains/session/use-session-agentctl
import { getBackendConfig } from "@/lib/config";
import { useTerminalLinkHandler } from "@/hooks/use-terminal-link-handler";
import {
log,
MIN_WIDTH,
MIN_HEIGHT,
useTerminalInit,
useWebSocketConnection,
useSendResize,
useSendInput,
useFitAndResize,
} from "./use-passthrough-terminal";
@@ -73,15 +73,10 @@ export function PassthroughTerminal(props: PassthroughTerminalProps) {
}, []);
const [isTerminalReady, setIsTerminalReady] = useState(false);
const onTerminalReady = useCallback(() => {
log("Terminal ready — will trigger WebSocket connection");
setIsTerminalReady(true);
}, []);
const onTerminalReady = useCallback(() => setIsTerminalReady(true), []);
// Track which session has an active WebSocket connection. The loading
// overlay is shown whenever the current sessionId doesn't match the
// connected one — this naturally resets on session switches without
// needing a separate effect that calls setState.
// Track which session has an active WebSocket connection. The loading overlay
// resets on session switches without needing a separate setState effect.
const [connectedSessionId, setConnectedSessionId] = useState<string | null>(null);
const isConnected = sessionId != null && connectedSessionId === sessionId;
const onConnected = useCallback(() => {
@@ -99,6 +94,7 @@ export function PassthroughTerminal(props: PassthroughTerminalProps) {
sendResize,
});
const sendInput = useSendInput(wsRef);
const toggleBottomTerminal = useAppStore((s) => s.toggleBottomTerminal);
useTerminalInit({
terminalRef,
@@ -112,6 +108,7 @@ export function PassthroughTerminal(props: PassthroughTerminalProps) {
onReady: onTerminalReady,
linkHandler,
onToggleBottomTerminal: toggleBottomTerminal,
sendInput,
});
useWebSocketConnection({
@@ -11,6 +11,7 @@ import { useSession } from "@/hooks/domains/session/use-session";
import { useSessionAgentctl } from "@/hooks/domains/session/use-session-agentctl";
import { getTerminalTheme } from "@/lib/theme/terminal-theme";
import { useTerminalLinkHandler } from "@/hooks/use-terminal-link-handler";
import { exposeBufferReader } from "./terminal-buffer-reader";
type ShellTerminalProps = {
sessionId?: string;
@@ -44,6 +45,7 @@ function useTerminalInit(
convertEol: isReadOnlyMode,
fontSize: isReadOnlyMode ? 12 : 13,
fontFamily: 'Menlo, Monaco, "Courier New", monospace',
macOptionIsMeta: true,
theme: getTerminalTheme(terminalRef.current),
});
const fitAddon = new FitAddon();
@@ -51,6 +53,7 @@ function useTerminalInit(
const webLinksAddon = new WebLinksAddon(linkHandler);
terminal.loadAddon(webLinksAddon);
terminal.open(terminalRef.current);
exposeBufferReader(terminalRef.current, terminal);
fitAddon.fit();
xtermRef.current = terminal;
fitAddonRef.current = fitAddon;
@@ -238,6 +241,44 @@ function useTerminalOutputWrite(
}, [xtermRef, shellOutput, processOutput, isReadOnlyMode, lastOutputLengthRef]);
}
/** Cmd+Arrow → Home/End on macOS for the shell terminal. */
function useCmdArrowHandler(
xtermRef: React.RefObject<Terminal | null>,
isReadOnlyMode: boolean,
sessionId: string | null | undefined,
send: (action: string, payload: Record<string, unknown>) => void,
) {
// Use a ref so the handler (attached once) always reads the latest values
// without needing cleanup (attachCustomKeyEventHandler has no dispose).
const stateRef = useRef({ sessionId, send });
useEffect(() => {
stateRef.current = { sessionId, send };
});
const attachedRef = useRef(false);
useEffect(() => {
if (!xtermRef.current || isReadOnlyMode || !sessionId || attachedRef.current) return;
attachedRef.current = true;
xtermRef.current.attachCustomKeyEventHandler((event) => {
const { sessionId: sid, send: sendFn } = stateRef.current;
if (
event.type === "keydown" &&
event.metaKey &&
!event.ctrlKey &&
!event.altKey &&
sid &&
(event.key === "ArrowLeft" || event.key === "ArrowRight")
) {
event.preventDefault();
const seq = event.key === "ArrowLeft" ? "\x01" : "\x05";
sendFn("shell.input", { session_id: sid, data: seq });
return false;
}
return true;
});
}, [xtermRef, sessionId, send, isReadOnlyMode, stateRef]);
}
export function ShellTerminal({
sessionId: propSessionId,
processOutput,
@@ -301,6 +342,8 @@ export function ShellTerminal({
onDataDisposableRef.current = null;
};
}, [taskId, sessionId, send, isReadOnlyMode]);
useCmdArrowHandler(xtermRef, isReadOnlyMode, sessionId, send);
useTerminalOutputWrite(xtermRef, isReadOnlyMode, processOutput, shellOutput, lastOutputLengthRef);
useShellSubscription({
@@ -0,0 +1,19 @@
import type { Terminal } from "@xterm/xterm";
type TerminalContainerWithBuffer = HTMLDivElement & { __xtermReadBuffer?: () => string };
/** Expose buffer reader on the container for e2e tests (xterm renders to canvas). */
export function exposeBufferReader(container: HTMLDivElement, terminal: Terminal) {
(container as TerminalContainerWithBuffer).__xtermReadBuffer = () => {
const buf = terminal.buffer.active;
const lines: string[] = [];
for (let i = 0; i <= buf.baseY + buf.cursorY; i++) {
lines.push(buf.getLine(i)?.translateToString(true) ?? "");
}
return lines.join("\n");
};
}
export function clearBufferReader(container: HTMLDivElement) {
(container as TerminalContainerWithBuffer).__xtermReadBuffer = undefined;
}
@@ -9,6 +9,7 @@ import { getTerminalTheme } from "@/lib/theme/terminal-theme";
import { startReconnectLoop } from "./ws-reconnect";
import { SHORTCUTS } from "@/lib/keyboard/constants";
import { matchesShortcut } from "@/lib/keyboard/utils";
import { exposeBufferReader, clearBufferReader } from "./terminal-buffer-reader";
// Debug flag - set to true to see detailed logs
const DEBUG = false;
@@ -20,20 +21,6 @@ export const log = (...args: unknown[]) => {
export const MIN_WIDTH = 100;
export const MIN_HEIGHT = 100;
type TerminalContainerWithBuffer = HTMLDivElement & { __xtermReadBuffer?: () => string };
/** Expose buffer reader on the container for e2e tests (xterm renders to canvas). */
function exposeBufferReader(container: HTMLDivElement, terminal: Terminal) {
(container as TerminalContainerWithBuffer).__xtermReadBuffer = () => {
const buf = terminal.buffer.active;
const lines: string[] = [];
for (let i = 0; i <= buf.baseY + buf.cursorY; i++) {
lines.push(buf.getLine(i)?.translateToString(true) ?? "");
}
return lines.join("\n");
};
}
export type TerminalInitOptions = {
terminalRef: React.RefObject<HTMLDivElement | null>;
xtermRef: React.MutableRefObject<Terminal | null>;
@@ -46,6 +33,40 @@ export type TerminalInitOptions = {
onReady: () => void;
};
type TerminalKeyHandlerOptions = {
onToggleBottomTerminal?: () => void;
sendInput?: (data: string) => void;
};
/** Handles app-level shortcuts and Cmd+Arrow→Home/End mapping for macOS. */
function createKeyEventHandler(options: TerminalKeyHandlerOptions) {
return (event: KeyboardEvent): boolean => {
if (matchesShortcut(event, SHORTCUTS.BOTTOM_TERMINAL)) {
event.preventDefault();
if (event.type === "keydown" && options.onToggleBottomTerminal) {
options.onToggleBottomTerminal();
}
return false;
}
// Cmd+Arrow → beginning/end of line on macOS (same as iTerm2)
if (
event.type === "keydown" &&
event.metaKey &&
!event.ctrlKey &&
!event.altKey &&
(event.key === "ArrowLeft" || event.key === "ArrowRight")
) {
event.preventDefault();
// Ctrl+A (0x01) = beginning-of-line, Ctrl+E (0x05) = end-of-line
// Works universally in bash/zsh emacs mode (the default)
const seq = event.key === "ArrowLeft" ? "\x01" : "\x05";
options.sendInput?.(seq);
return false;
}
return true;
};
}
function initTerminalInstance(
termContainer: HTMLDivElement,
refs: Pick<
@@ -58,8 +79,7 @@ function initTerminalInstance(
| "resizeTimeoutRef"
>,
fitAndResize: (force?: boolean) => void,
linkHandler?: (event: MouseEvent, uri: string) => void,
onToggleBottomTerminal?: () => void,
options: { linkHandler?: (event: MouseEvent, uri: string) => void } & TerminalKeyHandlerOptions,
) {
if (refs.isInitializedRef.current || refs.xtermRef.current) return undefined;
refs.isInitializedRef.current = true;
@@ -73,6 +93,7 @@ function initTerminalInstance(
scrollback: 5000,
fontSize: 13,
fontFamily: 'Menlo, Monaco, "Courier New", monospace',
macOptionIsMeta: true,
theme: getTerminalTheme(termContainer),
});
const fitAddon = new FitAddon();
@@ -80,18 +101,10 @@ function initTerminalInstance(
const unicode11Addon = new Unicode11Addon();
terminal.loadAddon(unicode11Addon);
terminal.unicode.activeVersion = "11";
const webLinksAddon = new WebLinksAddon(linkHandler);
const webLinksAddon = new WebLinksAddon(options.linkHandler);
terminal.loadAddon(webLinksAddon);
terminal.open(termContainer);
// Intercept bottom terminal shortcut to toggle panel
terminal.attachCustomKeyEventHandler((event) => {
if (matchesShortcut(event, SHORTCUTS.BOTTOM_TERMINAL)) {
event.preventDefault();
if (event.type === "keydown" && onToggleBottomTerminal) onToggleBottomTerminal();
return false;
}
return true;
});
terminal.attachCustomKeyEventHandler(createKeyEventHandler(options));
try {
fitAddon.fit();
refs.lastDimensionsRef.current = { cols: terminal.cols, rows: terminal.rows };
@@ -143,7 +156,7 @@ function initTerminalInstance(
refs.webglAddonRef.current = null;
}
terminal.dispose();
(termContainer as TerminalContainerWithBuffer).__xtermReadBuffer = undefined;
clearBufferReader(termContainer);
refs.xtermRef.current = null;
refs.fitAddonRef.current = null;
refs.isInitializedRef.current = false;
@@ -151,10 +164,10 @@ function initTerminalInstance(
};
}
type TerminalInitHookOptions = TerminalInitOptions & {
linkHandler?: (event: MouseEvent, uri: string) => void;
onToggleBottomTerminal?: () => void;
};
type TerminalInitHookOptions = TerminalInitOptions &
TerminalKeyHandlerOptions & {
linkHandler?: (event: MouseEvent, uri: string) => void;
};
export function useTerminalInit({
terminalRef,
@@ -168,6 +181,7 @@ export function useTerminalInit({
onReady,
linkHandler,
onToggleBottomTerminal,
sendInput,
}: TerminalInitHookOptions) {
const refs = {
xtermRef,
@@ -194,7 +208,11 @@ export function useTerminalInit({
const rect = container.getBoundingClientRect();
log("Init check: dimensions", rect.width, "x", rect.height);
if (rect.width >= MIN_WIDTH && rect.height >= MIN_HEIGHT) {
initTerminalInstance(container, refs, fitAndResize, linkHandler, onToggleBottomTerminal);
initTerminalInstance(container, refs, fitAndResize, {
linkHandler,
onToggleBottomTerminal,
sendInput,
});
onReady();
return true;
}
@@ -494,6 +512,19 @@ export function useSendResize(wsRef: React.MutableRefObject<WebSocket | null>) {
);
}
/** Returns a stable ref whose `.current` sends raw string data to the PTY via WebSocket. */
export function useSendInput(wsRef: React.MutableRefObject<WebSocket | null>) {
return useCallback(
(data: string) => {
const ws = wsRef.current;
if (ws && ws.readyState === WebSocket.OPEN) {
ws.send(new TextEncoder().encode(data));
}
},
[wsRef],
);
}
export type FitAndResizeOptions = {
xtermRef: React.MutableRefObject<Terminal | null>;
fitAddonRef: React.MutableRefObject<FitAddon | null>;
@@ -0,0 +1,172 @@
import { type Page } from "@playwright/test";
import { test, expect } from "../fixtures/test-base";
import type { SeedData } from "../fixtures/test-base";
import type { ApiClient } from "../helpers/api-client";
import { SessionPage } from "../pages/session-page";
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/** Create a non-TUI task and navigate to its session. Waits for agent idle. */
async function seedTaskWithSession(
testPage: Page,
apiClient: ApiClient,
seedData: SeedData,
title: string,
): Promise<SessionPage> {
const task = await apiClient.createTaskWithAgent(
seedData.workspaceId,
title,
seedData.agentProfileId,
{
description: "/e2e:simple-message",
workflow_id: seedData.workflowId,
workflow_step_id: seedData.startStepId,
repository_ids: [seedData.repositoryId],
},
);
if (!task.session_id) throw new Error("createTaskWithAgent did not return a session_id");
await testPage.goto(`/s/${task.session_id}`);
const session = new SessionPage(testPage);
await session.waitForLoad();
await expect(session.idleInput()).toBeVisible({ timeout: 30_000 });
return session;
}
/** Focus the terminal and wait for the shell to be ready (prompt visible). */
async function focusTerminal(page: Page, session: SessionPage): Promise<void> {
await expect(session.terminal).toBeVisible({ timeout: 15_000 });
await expect
.poll(
async () => {
const buf = await readTerminalBuffer(page);
return buf.length > 0;
},
{ timeout: 15_000, message: "Waiting for terminal shell to connect" },
)
.toBe(true);
const xterm = session.terminal.locator(".xterm");
await xterm.click();
}
/** Read the terminal panel's xterm buffer text. */
async function readTerminalBuffer(page: Page): Promise<string> {
return page.evaluate(() => {
const panel = document.querySelector('[data-testid="terminal-panel"]');
if (!panel) return "";
const xtermEl = panel.querySelector(".xterm");
type XC = HTMLElement & { __xtermReadBuffer?: () => string };
const container = xtermEl?.parentElement as XC | null | undefined;
return container?.__xtermReadBuffer?.() ?? "";
});
}
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
test.describe("Terminal keyboard navigation", () => {
// Standalone executor can fail on cold start; retry once for transient failures.
test.describe.configure({ retries: 1 });
test("TERM is set to xterm-256color", async ({ testPage, apiClient, seedData }) => {
const session = await seedTaskWithSession(testPage, apiClient, seedData, "TERM Check");
await focusTerminal(testPage, session);
await testPage.keyboard.type("echo $TERM");
await testPage.keyboard.press("Enter");
await session.expectTerminalHasText("xterm-256color");
});
test("COLORTERM is set to truecolor", async ({ testPage, apiClient, seedData }) => {
const session = await seedTaskWithSession(testPage, apiClient, seedData, "COLORTERM Check");
await focusTerminal(testPage, session);
await testPage.keyboard.type("echo $COLORTERM");
await testPage.keyboard.press("Enter");
await session.expectTerminalHasText("truecolor");
});
test("Ctrl+Arrow moves cursor between words", async ({ testPage, apiClient, seedData }) => {
const session = await seedTaskWithSession(testPage, apiClient, seedData, "CtrlArrow Test");
await focusTerminal(testPage, session);
// Start bash explicitly — it has Ctrl+Arrow bindings via /etc/inputrc
// (zsh without .zshrc doesn't bind Ctrl+Arrow by default)
await testPage.keyboard.type("bash --norc --noprofile");
await testPage.keyboard.press("Enter");
// Wait for bash prompt (bash --norc uses "bash-X.Y$ " pattern)
await expect
.poll(async () => (await readTerminalBuffer(testPage)).includes("bash"), {
timeout: 5_000,
message: "Waiting for bash prompt",
})
.toBe(true);
// Type a multi-word echo command (don't press Enter yet)
await testPage.keyboard.type("echo aaa bbb ccc");
// Ctrl+Left twice: end → start of "ccc" → start of "bbb"
await testPage.keyboard.press("Control+ArrowLeft");
await testPage.keyboard.press("Control+ArrowLeft");
// Insert "X" at cursor (before "bbb") → "echo aaa Xbbb ccc"
await testPage.keyboard.type("X");
await testPage.keyboard.press("Enter");
// The shell should output "aaa Xbbb ccc"
await session.expectTerminalHasText("aaa Xbbb ccc");
});
test("Meta+Arrow moves cursor to start/end of line", async ({
testPage,
apiClient,
seedData,
}) => {
const session = await seedTaskWithSession(testPage, apiClient, seedData, "MetaArrow Test");
await focusTerminal(testPage, session);
// Start bash for a clean prompt
await testPage.keyboard.type("bash --norc --noprofile");
await testPage.keyboard.press("Enter");
await expect
.poll(async () => (await readTerminalBuffer(testPage)).includes("bash"), {
timeout: 5_000,
message: "Waiting for bash prompt",
})
.toBe(true);
// Type text without "echo " prefix (just raw text, not a valid command)
await testPage.keyboard.type("aaa bbb ccc");
// Meta+Left → Home (cursor moves to start of line, sends Ctrl+A)
await testPage.keyboard.press("Meta+ArrowLeft");
// Type "echo " at the beginning → line becomes "echo aaa bbb ccc"
await testPage.keyboard.type("echo ");
await testPage.keyboard.press("Enter");
// If Home worked, "echo " was inserted at the start and output is "aaa bbb ccc".
// If Home failed, "echo " was appended and the command would fail.
// Use a unique marker in the output to avoid matching the typed command itself.
await expect
.poll(
async () => {
const buf = await readTerminalBuffer(testPage);
// Find lines that contain "aaa bbb ccc" but NOT "echo" (output lines, not command lines)
const lines = buf.split("\n");
return lines.some(
(line) => line.includes("aaa bbb ccc") && !line.includes("echo") && !line.includes("$"),
);
},
{ timeout: 10_000, message: "Expected output line with 'aaa bbb ccc'" },
)
.toBe(true);
});
});