Skip to content

Commit 2bec420

Browse files
committed
feat(gpui): a bindable clear-screen action for the terminal
The GPUI shell had no clear-screen action at all: the macOS config table's ⌘K ClearHistory default executes only in the legacy shell, so after unbinding the Shell picker row ⌘K stayed inert and no settings row offered clear screen — the known limitation recorded in the 2026-09-21 macOS command-key aliases note. Map config::Action::ClearHistory to a new ClearTerminal workspace action and expose it as a Terminal-group row on the settings keymap page. No default shortcut changes on any platform: ⌘K stays on the Shell picker, and the feature is opt-in through a user keybind= row that applies without restart. After an instant app-side wipe of the viewport and scrollback, the action branches on the pane's foreground state: at a prompt it writes ^L to the pane's PTY so the shell repaints its prompt on the fresh screen; while a command runs it moves the terminal cursor home app-side so sequential output continues from the top; on the alternate screen it does nothing. The row label uses a typed i18n message (zh/en catalogs, English fallback elsewhere). Adds adapter, dispatch-probe and label regressions, and the decision note architecture/notes/nebula_app/gpui_shell/2026-10-14-terminal-clear-action.md (recording why pre-existing files need one re-record after upgrading, and why an app-side cursor-home and an unconditional ^L were rejected).
1 parent a2f9b0f commit 2bec420

9 files changed

Lines changed: 325 additions & 6 deletions

File tree

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Bindable terminal clear action (GPUI shell)
2+
3+
## Status
4+
5+
Implemented; resolves the clear-screen limitation recorded in
6+
[2026-09-21-macos-command-key-aliases.md](2026-09-21-macos-command-key-aliases.md)
7+
under Consequences and Revisit when.
8+
9+
## Context
10+
11+
The GPUI product shell had no clear-screen action at all. `config::Action::ClearHistory`
12+
and the `Esc("\x0c")` sibling existed only in the legacy shell's action table
13+
(`nebula_app/src/input/action.rs`), and the product build replaces that module with
14+
`product_input.rs`, so the macOS config-table defaults `⌘K → Esc("\x0c")` plus
15+
`⌘K → ClearHistory` (`nebula_app/src/config/bindings/defaults.rs`, macOS platform
16+
section) were inert data. Runtime ⌘K belongs to the Shell picker via
17+
`display::keymap::MACOS_COMMAND_ALIASES`. After a user cleared the Shell picker row,
18+
`clear_action` wrote `keybind=cmd+k:ReceiveChar`, which the shell registers as
19+
`NoAction`; ⌘K became inert. Even a hand-written `keybind=cmd+k:ClearHistory` was
20+
dropped because `workspace_binding_in_context` had no `ClearHistory` arm, and the
21+
settings keymap page offered no clear-screen row. Users coming from the
22+
established macOS ⌘K clear convention had no path to that behavior.
23+
24+
## Evidence
25+
26+
- `nebula_app/src/main.rs` selects `product_input.rs` for `input` when the legacy
27+
shell is disabled; `input::Processor` / `process_key_bindings` are legacy-only.
28+
- `nebula_app/src/config/bindings/defaults.rs` macOS platform table binds ⌘K twice
29+
(`Esc("\x0c")`, `ClearHistory`); `nebula_terminal/src/term/clear.rs` shows
30+
`ClearMode::Saved` clears only the scrollback while `ClearMode::All` clears the
31+
viewport.
32+
- `nebula_app/src/gpui_shell/workspace/keyboard_bindings.rs`: the adapter's match
33+
fell through to `_ => None` for `ClearHistory` before this change; user rows are
34+
registered at workspace and terminal depth by `update_keybinds`.
35+
- The 2026-09-21 alias note documents "⌘K after unbinding does not clear the
36+
screen … the key is released but inert" and defers the decision.
37+
38+
## Decision
39+
40+
- `nebula_workspace::ClearTerminal` is a new GPUI action. `Action::ClearHistory`
41+
maps to it in `workspace_binding_in_context` with the terminal key context,
42+
the same shape as Copy/Paste, so text inputs never lose the key.
43+
- **No default binding is registered anywhere.** ⌘K stays on the Shell picker on
44+
macOS and nothing changes on Windows/Linux. The action is reachable only through
45+
a user `keybind=` row, now writable from the settings page: `EDITABLE_ACTIONS`
46+
gains a terminal-group row backed by `Action::ClearHistory` (a unit variant that
47+
already round-trips through `parse_action` / `action_storage_name`).
48+
- Semantics branch on the pane's foreground state after an instant app-side wipe
49+
of the viewport and scrollback (`ClearMode::All` + `Saved`, zero-latency
50+
feedback):
51+
- Shell at a prompt (OSC 133 `nebula_prompt_active`): write `\x0c` to that
52+
pane's PTY so the shell moves the cursor home and repaints the prompt on the
53+
fresh screen, keeping its line state in sync.
54+
- Command running: the shell cannot act on `^L` (it would stay queued and
55+
clear the screen a second time when the command exits, wiping the output
56+
produced in between). Instead the view moves the terminal cursor home
57+
app-side (`Handler::goto(0, 0)`); sequential output continues from the top
58+
and the next prompt lands after the last output line.
59+
- Alternate screen (vim, less, other full-screen programs): the action does
60+
nothing — `^L` is a redraw there, not a clear.
61+
Clearing the grid alone leaves the cursor on its original row and the prompt
62+
stranded; manual acceptance rejected that. The `^L` byte is a direct PTY write
63+
on the focused pane, not a user-input event, so broadcast fan-out stays out of
64+
scope. Without shell integration the prompt probe reads false, so clears take
65+
the cursor-home branch; the wipe still works and the next Enter restores a
66+
prompt.
67+
- The row label uses the typed message `common.clear_screen` (Simplified Chinese
68+
and English catalogs; other languages fall back per the catalog contract).
69+
70+
## Rejected alternatives
71+
72+
- A pure app-side grid clear with no PTY write (the first implementation):
73+
deterministic under any foreground program, but the cursor stays on its
74+
original row and the shell never repaints the prompt — after the wipe the
75+
screen is blank with a stray cursor, and only the next Enter restores a
76+
visible prompt. Manual acceptance rejected this as broken.
77+
- An app-side cursor-home instead of `^L` at the prompt: desynchronizes the
78+
shell's line state from the screen and breaks cursor-addressed redraws
79+
(wrapped input lines, history search) without any cooperation from the shell.
80+
- An unconditional `^L` (the exact legacy ⌘K pair): correct at the prompt, but
81+
while a command runs the byte stays queued in the tty input queue and the
82+
shell consumes it only after the command exits — clearing the screen a second
83+
time and wiping the output the command produced in between. The prompt-state
84+
probe avoids the deferred wipe.
85+
- Scrollback-only (`ClearMode::Saved` alone, matching the legacy `ClearHistory`
86+
executor): leaves the screen populated; users asking for clear screen expect a
87+
blank viewport plus a dropped scrollback.
88+
- Reassigning ⌘K in `MACOS_COMMAND_ALIASES` to `ClearHistory` (the common macOS
89+
terminal clear convention): changes shipped default behavior for every macOS
90+
user. This change
91+
deliberately preserves existing defaults; users who want it bind ⌘K themselves
92+
through the new row.
93+
- Registering the config table's ⌘K `ClearHistory` default as a GPUI workspace
94+
default: collides with the Shell picker alias in the same keymap source tier and
95+
makes dispatch ambiguous.
96+
97+
## Consequences
98+
99+
- On a fresh macOS install the Clear screen row displays `Command+K`, because
100+
`effective_combo` reads the config table and `mods_prefix` renders `super`
101+
natively — while runtime ⌘K actually opens the Shell picker. This is the same
102+
config-table display convention recorded in the 2026-09-21 note ("the keymap
103+
page still shows Ctrl keys for actions whose macOS binding set includes ⌘"),
104+
not a new runtime claim. Capturing any key on the row writes a user row that
105+
wins immediately.
106+
- Resetting the Clear screen row also removes `cmd+k:ReceiveChar` lines
107+
(`reset_action`'s vocabulary includes config-table defaults), which hands ⌘K
108+
back to the Shell picker. Clearing the row writes `keybind=cmd+k:ReceiveChar`,
109+
which shadows the picker's ⌘K — ordinary combo-level shadowing, identical to
110+
every other row.
111+
- Windows/Linux gain an unbound row and no behavior change; existing default
112+
keybindings are untouched on every platform.
113+
- Files written by earlier builds hold no `ClearHistory` line — the old shell
114+
could not express one — only the `ReceiveChar` leftovers of unbinding the
115+
Shell picker row. Those lines keep their "release the key" semantics after
116+
upgrading, so a pre-update clear-screen attempt stays inert until the user
117+
records the row once (verified against a real upgraded file: the re-record
118+
replaced `cmd+k:ReceiveChar` with `win+k:ReceiveChar` plus the new
119+
`win+k:ClearHistory`, where the later line wins). Auto-rewriting
120+
`ReceiveChar` lines into `ClearHistory` would overwrite an explicitly chosen
121+
"release the key" decision and is rejected.
122+
- At the prompt the `^L` byte reaches whatever shell owns the normal-screen PTY,
123+
exactly as the legacy ⌘K pair behaved. In the running-command branch no PTY
124+
write happens; alternate-screen sessions are left untouched entirely.
125+
- The legacy shell already executes `Action::ClearHistory` and is unchanged.
126+
127+
## Validation
128+
129+
`cargo fmt --all -- --check`, `cargo check -p nebula --bin pebrel --features
130+
gpui-shell --tests --locked`, the `display::keymap` and
131+
`gpui_shell::workspace::keyboard_bindings` test groups (including the new
132+
adapter, dispatch-probe and label regressions), the settings-pane suite, the
133+
i18n contract suites, `cargo test -p nebula --test file_line_budget` and
134+
`python3 scripts/check_architecture.py --base <PR base>` pass. The dispatch
135+
regression fails without the adapter arm; the label regression fails without the
136+
catalog entries.
137+
138+
## Supersedes
139+
140+
None. Extends [2026-09-21-macos-command-key-aliases.md](2026-09-21-macos-command-key-aliases.md);
141+
its alias-table authority and unbind vocabulary are reused unchanged.
142+
143+
## Revisit when
144+
145+
The keymap page renders platform-native or runtime-truth keycaps (removing the
146+
Command+K display quirk), or the product decides clear screen deserves a default
147+
key of its own.

‎nebula_app/i18n/en-US.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,7 @@
310310
"edit": "Edit",
311311
"rename": "Rename",
312312
"rename_tab": "Rename tab",
313+
"clear_screen": "Clear screen",
313314
"copy": "Copy",
314315
"paste": "Paste",
315316
"cut": "Cut",

‎nebula_app/i18n/zh-CN.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,7 @@
310310
"edit": "编辑",
311311
"rename": "重命名",
312312
"rename_tab": "重命名标签页",
313+
"clear_screen": "清屏",
313314
"copy": "复制",
314315
"paste": "粘贴",
315316
"cut": "剪切",

‎nebula_app/src/display/keymap.rs‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ pub(crate) const EDITABLE_ACTIONS: &[(Action, &str, &str)] = &[
6969
(Action::IncreaseFontSize, "增大字号", "Font size up"),
7070
(Action::DecreaseFontSize, "减小字号", "Font size down"),
7171
(Action::ResetFontSize, "重置字号", "Reset font size"),
72+
// GPUI 壳的清屏没有静态默认键(⌘K 归 Shell 选择器);这一行让用户
73+
// 能把任意键(含 ⌘K)绑到清屏,落到 ClearTerminal 动作。
74+
(Action::ClearHistory, "清屏", "Clear screen"),
7275
];
7376

7477
/// 设置页分组(无框裁定 2026-08-09:只用段标题+间距分组,不画容器)。
@@ -78,7 +81,7 @@ pub(crate) const GROUPS: &[(&str, &str, usize)] = &[
7881
("标签页", "Tabs", 5),
7982
("窗格", "Panes", 7),
8083
("侧栏面板", "Side panels", 2),
81-
("终端", "Terminal", 9),
84+
("终端", "Terminal", 10),
8285
];
8386

8487
/// 只读展示行(无法在图形页编辑,TOML/settings 行仍可覆盖其中的表驱动键)。
@@ -146,10 +149,10 @@ pub(crate) fn action_label(
146149
row: &(Action, &'static str, &'static str),
147150
language: super::UiLanguage,
148151
) -> &'static str {
149-
if row.0 == Action::RenameTab {
150-
language.text(crate::i18n::Message::CommonRenameTab)
151-
} else {
152-
language.pick(row.1, row.2)
152+
match row.0 {
153+
Action::RenameTab => language.text(crate::i18n::Message::CommonRenameTab),
154+
Action::ClearHistory => language.text(crate::i18n::Message::CommonClearScreen),
155+
_ => language.pick(row.1, row.2),
153156
}
154157
}
155158

@@ -727,6 +730,21 @@ mod tests {
727730
assert_eq!(action_label(row, super::super::UiLanguage::ZhCn), "重命名标签页");
728731
}
729732

733+
#[test]
734+
fn clear_screen_is_editable_and_localized_through_the_typed_message() {
735+
use super::*;
736+
let row =
737+
EDITABLE_ACTIONS.iter().find(|(action, ..)| *action == Action::ClearHistory).unwrap();
738+
for language in super::super::UiLanguage::ALL {
739+
assert_eq!(
740+
action_label(row, *language),
741+
language.text(crate::i18n::Message::CommonClearScreen)
742+
);
743+
assert!(!action_label(row, *language).is_empty());
744+
}
745+
assert_eq!(action_label(row, super::super::UiLanguage::ZhCn), "清屏");
746+
}
747+
730748
#[test]
731749
fn clearing_ctrl_k_survives_persistence_and_restore_is_explicit() {
732750
use super::*;

‎nebula_app/src/gpui_shell/terminal/view.rs‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ use nebula_terminal::index::{Column, Line, Point as TermPoint, Side};
4949
use nebula_terminal::render::{CellMetrics, TerminalViewport, ViewportTracker};
5050
use nebula_terminal::selection::{Selection, SelectionType};
5151
use nebula_terminal::term::TermMode;
52-
use nebula_terminal::vte::ansi::CursorStyle;
52+
use nebula_terminal::vte::ansi::{ClearMode, CursorStyle, Handler as _};
5353

5454
use std::sync::Arc;
5555

@@ -1067,6 +1067,32 @@ impl TerminalView {
10671067
true
10681068
}
10691069

1070+
/// 清屏(设置页「清屏」动作的落点)。应用侧立刻清掉可见屏与回滚(零
1071+
/// 延迟反馈),随后按前台状态分流:
1072+
/// - 提示符状态(shell 在等输入,OSC 133 跟踪):发 ^L 让 shell 光标归
1073+
/// 顶并重绘提示符,行状态与屏幕保持同步;
1074+
/// - 命令运行中:shell 读不到 ^L(只会排队到命令结束后再清一次屏,冲
1075+
/// 掉运行期输出),应用侧直接把光标归顶,顺序输出从顶部继续;
1076+
/// - 备用屏(vim/less 等全屏程序):^L 不是清屏,整键不动。
1077+
pub fn clear_screen(&mut self, cx: &mut Context<Self>) {
1078+
let Some(session) = &self.session else { return };
1079+
{
1080+
let mut term = session.term.lock();
1081+
if term.mode().contains(TermMode::ALT_SCREEN) {
1082+
return;
1083+
}
1084+
term.clear_screen(ClearMode::All);
1085+
term.clear_screen(ClearMode::Saved);
1086+
if term.nebula_prompt_active() {
1087+
drop(term);
1088+
self.write_bytes(b"\x0c".to_vec());
1089+
} else {
1090+
term.goto(0, 0);
1091+
}
1092+
}
1093+
cx.notify();
1094+
}
1095+
10701096
fn paste_now(&mut self, text: &str, cx: &mut Context<Self>) {
10711097
self.paste_now_impl(text, true, cx);
10721098
}

‎nebula_app/src/gpui_shell/workspace/key_actions.rs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,4 +123,13 @@ impl NebulaWorkspace {
123123
view.update(cx, |view, cx| view.paste(window, cx));
124124
}
125125
}
126+
127+
/// 清空焦点终端。清屏由焦点 pane 的视图执行(提示符状态随附的 ^L
128+
/// 也只写该 pane 的 PTY);它不是用户输入事件,与复制/粘贴一样不走
129+
/// 广播扇出。
130+
pub(super) fn clear_focused_terminal(&mut self, cx: &mut Context<Self>) {
131+
if let Some(view) = self.tabs.get(self.active).and_then(WorkspaceTab::focused_view) {
132+
view.update(cx, |view, cx| view.clear_screen(cx));
133+
}
134+
}
126135
}

‎nebula_app/src/gpui_shell/workspace/keyboard_bindings.rs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,13 @@ pub(super) struct SelectTab {
187187
#[action(namespace = nebula_workspace, no_json)]
188188
pub(super) struct QuitApp;
189189

190+
/// 清屏(`Action::ClearHistory` 的 GPUI 落点),与 SelectTab/QuitApp 同属
191+
/// 适配层动作。没有静态默认绑定:⌘K 已归 Shell 选择器,清屏只能经设置页
192+
/// keybind= 行注册。
193+
#[derive(Clone, Debug, PartialEq, gpui::Action)]
194+
#[action(namespace = nebula_workspace, no_json)]
195+
pub(super) struct ClearTerminal;
196+
190197
impl SelectTab {
191198
fn from_config(action: &crate::config::Action) -> Option<Self> {
192199
use crate::config::Action;
@@ -262,6 +269,13 @@ fn workspace_binding_in_context(
262269
PasteClipboard,
263270
scope.or(Some(crate::gpui_shell::terminal::KEY_CONTEXT)),
264271
)),
272+
// 清屏只有用户 keybind= 行会走到这里(无静态默认,⌘K 归 Shell
273+
// 选择器);作用域与 Copy/Paste 同型,输入框聚焦时不抢键。
274+
Action::ClearHistory => Some(KeyBinding::new(
275+
&combo,
276+
ClearTerminal,
277+
scope.or(Some(crate::gpui_shell::terminal::KEY_CONTEXT)),
278+
)),
265279
Action::ToggleFullscreen => Some(KeyBinding::new(&combo, ToggleFullscreen, scope)),
266280
Action::OpenQuickJump => Some(KeyBinding::new(&combo, OpenQuickJump, scope)),
267281
// macOS 的退出键走与托盘退出同一条路径:先落盘会话与草稿,再停 PTY。

0 commit comments

Comments
 (0)