Skip to content
Open
Show file tree
Hide file tree
Changes from 38 commits
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
932ce2a
feat(gpui): a bindable clear-screen action for the terminal
zher52 Oct 15, 2026
6d10f8c
test(keymap): drop the platform conditional from the clear-screen con…
zher52 Oct 15, 2026
94cdb39
test(keymap): expect the released Ctrl+K default after the #656 policy
zher52 Oct 19, 2026
30fdc81
Merge commit 'b49b53515d3e6513e363de7f842436f23680e614' into review/c…
Kuddev Oct 19, 2026
92516fe
Verify clear-screen state transitions and preserve macOS shortcut own…
Kuddev Oct 19, 2026
db35ebd
Keep clear-screen policy test independent of legacy defaults
Kuddev Oct 19, 2026
5bf5974
Merge remote-tracking branch 'origin/main' into review/clear-history-653
Kuddev Oct 19, 2026
d29d203
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 21, 2026
dab38ca
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 21, 2026
06fbd22
ci: retrigger the flaky Windows bash-input native test
zher52 Oct 22, 2026
d08d739
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 23, 2026
4022ff2
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Oct 26, 2026
32dc755
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 26, 2026
039c0fd
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 26, 2026
3ff04c8
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 26, 2026
c1981c2
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 27, 2026
2d4329c
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Oct 29, 2026
aba6013
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Nov 2, 2026
8245a9d
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Nov 3, 2026
6241dbd
Merge branch 'main' into feat/gpui-clear-terminal-action
zher52 Nov 4, 2026
3d2dc37
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 4, 2026
d2f490c
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 4, 2026
9329bb7
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 9, 2026
da78ebd
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 9, 2026
3425dab
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 10, 2026
5cf3a9b
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 12, 2026
ca073ee
fix(gpui): redraw the prompt through an owned shell integration key
zher52 Nov 12, 2026
b6604cc
test(pwsh): keep the redraw chord ownership test off the sample user key
zher52 Nov 12, 2026
48b0f2a
fix(tty): probe both private keys before installing either binding
zher52 Nov 12, 2026
8bc09aa
fix(tty): advertise prompt redraw as its own capability
zher52 Nov 12, 2026
e082a9e
fix(tty): re-verify redraw ownership at every prompt
zher52 Nov 12, 2026
681274e
fix(tty): match the redraw entry's tail in the Bash ownership probe
zher52 Nov 12, 2026
554235a
fix(tty): move the pwsh redraw off the paste chord and probe exact keys
zher52 Nov 12, 2026
266f49a
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 12, 2026
90860de
fix(tty): redraw ownership survives lookalike bindings and keymap swi…
zher52 Nov 12, 2026
589e650
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 12, 2026
30b5aed
fix(tty): install the pwsh redraw in a supported parameter set
zher52 Nov 12, 2026
8a743a0
test(pwsh): inject the redraw refusal observably and key chords after…
zher52 Nov 13, 2026
83b5f46
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 13, 2026
0aa8f10
fix(tty): announce redraw only when every reachable keymap consumes t…
zher52 Nov 13, 2026
aafbcdb
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 14, 2026
476ae02
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 14, 2026
c93b4ac
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 15, 2026
a3833cb
Settle the flaky PTY and resize windows behind the native CI failures
zher52 Nov 16, 2026
f093a23
Break the settle chain the way stable rustfmt formats it
zher52 Nov 16, 2026
3bf3c83
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 16, 2026
873e8c6
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 16, 2026
c0450e7
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 16, 2026
e76c27b
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 16, 2026
79001f6
Anchor pointer harness chords on editor turn boundaries
zher52 Nov 17, 2026
026241a
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 17, 2026
c68871d
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 17, 2026
af53126
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 18, 2026
af7da01
Merge remote-tracking branch 'origin/main' into feat/gpui-clear-termi…
zher52 Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
# Bindable terminal clear action (GPUI shell)

## Status

Implemented; resolves the clear-screen limitation recorded in
[2026-09-21-macos-command-key-aliases.md](2026-09-21-macos-command-key-aliases.md)
under Consequences and Revisit when.

## Context

The GPUI product shell had no clear-screen action at all. `config::Action::ClearHistory`
and the `Esc("\x0c")` sibling existed only in the legacy shell's action table
(`nebula_app/src/input/action.rs`), and the product build replaces that module with
`product_input.rs`, so the macOS config-table defaults `⌘K → Esc("\x0c")` plus
`⌘K → ClearHistory` (`nebula_app/src/config/bindings/defaults.rs`, macOS platform
section) were inert data. Runtime ⌘K belongs to the Shell picker via
`display::keymap::MACOS_COMMAND_ALIASES`. After a user cleared the Shell picker row,
`clear_action` wrote `keybind=cmd+k:ReceiveChar`, which the shell registers as
`NoAction`; ⌘K became inert. Even a hand-written `keybind=cmd+k:ClearHistory` was
dropped because `workspace_binding_in_context` had no `ClearHistory` arm, and the
settings keymap page offered no clear-screen row. Users coming from the
established macOS ⌘K clear convention had no path to that behavior.

## Evidence

- `nebula_app/src/main.rs` selects `product_input.rs` for `input` when the legacy
shell is disabled; `input::Processor` / `process_key_bindings` are legacy-only.
- `nebula_app/src/config/bindings/defaults.rs` macOS platform table binds ⌘K twice
(`Esc("\x0c")`, `ClearHistory`); `nebula_terminal/src/term/clear.rs` shows
`ClearMode::Saved` clears only the scrollback while `ClearMode::All` clears the
viewport.
- `nebula_app/src/gpui_shell/workspace/keyboard_bindings.rs`: the adapter's match
fell through to `_ => None` for `ClearHistory` before this change; user rows are
registered at workspace and terminal depth by `update_keybinds`.
- The 2026-09-21 alias note documents "⌘K after unbinding does not clear the
screen … the key is released but inert" and defers the decision.

## Decision

- `nebula_workspace::ClearTerminal` is a new GPUI action. `Action::ClearHistory`
maps to it in `workspace_binding_in_context` with the terminal key context,
the same shape as Copy/Paste, so text inputs never lose the key.
- **No default binding is registered anywhere.** ⌘K stays on the Shell picker on
macOS and nothing changes on Windows/Linux. The action is reachable only through
a user `keybind=` row, now writable from the settings page: `EDITABLE_ACTIONS`
gains a terminal-group row backed by `Action::ClearHistory` (a unit variant that
already round-trips through `parse_action` / `action_storage_name`).
- Semantics branch on the pane's foreground state after an instant app-side wipe
of the viewport and scrollback (`ClearMode::All` + `Saved`):
- Shell at a prompt (OSC 133 `nebula_prompt_active`) with the explicit
redraw capability advertised (`pebrel_editor_redraw`, independent of the
query readiness `pebrel_editor_ready`): write the integration-owned clear
key — `\e[46~` bound to the readline/zle `clear-screen` function, or the
PSReadLine `Ctrl+Shift+F9` → `ClearScreen` chord (`Ctrl+Shift+F11` stays
with clipboard.ps1's native paste) — so the shell's own line editor
clears the glass and repaints prompt, buffer and caret, keeping its line
state in sync.
- Prompt without the advertised redraw capability — no integration at all,
a pre-redraw (2.5.3) integration whose query-only readiness says nothing
about the unbound key, a user-owned redraw key, or a same-shell rebind
that took the key back after the integration had owned it — or a running
command: the view moves the terminal cursor home app-side
(`Handler::goto(0, 0)`); sequential output continues from the top and the
next prompt lands after the last output line. No keyboard byte is ever
written at the prompt (see Rejected alternatives).
- Alternate screen (vim, less, other full-screen programs): the action does
nothing — `^L` is a redraw there, not a clear.
Clearing the grid alone leaves the cursor on its original row and the prompt
stranded; manual acceptance rejected that. The redraw key is a direct PTY
write on the focused pane, not a user-input event, so broadcast fan-out stays
out of scope. Without shell integration the prompt probe reads false, so
clears take the cursor-home branch; the wipe still works and the next Enter
restores a prompt.
- The row label uses the typed message `common.clear_screen` (Simplified Chinese
and English catalogs; other languages fall back per the catalog contract).

## Rejected alternatives

- A pure app-side grid clear with no PTY write (the first implementation):
deterministic under any foreground program, but the cursor stays on its
original row and the shell never repaints the prompt — after the wipe the
screen is blank with a stray cursor, and only the next Enter restores a
visible prompt. Manual acceptance rejected this as broken.
- An app-side cursor-home instead of `^L` at the prompt: desynchronizes the
shell's line state from the screen and breaks cursor-addressed redraws
(wrapped input lines, history search) without any cooperation from the shell.
- An unconditional `^L` (the exact legacy ⌘K pair): correct at the prompt, but
while a command runs the byte stays queued in the tty input queue and the
shell consumes it only after the command exits — clearing the screen a second
time and wiping the output the command produced in between. The prompt-state
probe avoids the deferred wipe.
- Scrollback-only (`ClearMode::Saved` alone, matching the legacy `ClearHistory`
executor): leaves the screen populated; users asking for clear screen expect a
blank viewport plus a dropped scrollback.
- Writing `^L` at the prompt (the first implementation, rejected in review
2026-11-12): at an OSC 133 prompt the byte is keyboard input to whatever owns
the tty, so it invokes the user's *remapped* Ctrl+L binding, not clear screen.
With a fixture Readline binding that inserts a marker, the marker was appended
to live input; the dispatch test only verified the byte was sent and could not
catch it. The owned redraw key above keeps redraw semantics independent of any
user binding; where the channel is not advertised the action degrades to the
app-side cursor home instead of falling back to a keyboard byte.
- Reassigning ⌘K in `MACOS_COMMAND_ALIASES` to `ClearHistory` (the common macOS
terminal clear convention): changes shipped default behavior for every macOS
user. This change
deliberately preserves existing defaults; users who want it bind ⌘K themselves
through the new row.
- Registering the config table's ⌘K `ClearHistory` default as a GPUI workspace
default: collides with the Shell picker alias in the same keymap source tier and
makes dispatch ambiguous.

## Consequences

- The current GPUI shortcut policy assigns Command+K to the Shell picker and
removes competing legacy defaults. Clear screen therefore starts unbound on
macOS as well. Clearing or resetting an unbound Clear screen row does not
consume or release the picker's chord. An explicit user binding still wins
through the existing keymap ownership rules.
- Windows/Linux gain an unbound row and no behavior change; existing default
keybindings are untouched on every platform.
- Files written by earlier builds hold no `ClearHistory` line — the old shell
could not express one — only the `ReceiveChar` leftovers of unbinding the
Shell picker row. Those lines keep their "release the key" semantics after
upgrading, so a pre-update clear-screen attempt stays inert until the user
records the row once (verified against a real upgraded file: the re-record
replaced `cmd+k:ReceiveChar` with `win+k:ReceiveChar` plus the new
`win+k:ClearHistory`, where the later line wins). Auto-rewriting
`ReceiveChar` lines into `ClearHistory` would overwrite an explicitly chosen
"release the key" decision and is rejected.
- At the prompt the redraw key reaches the shell only when the integration
explicitly owns it — query readiness (`pebrel_editor_ready`) and redraw
ownership (`pebrel_editor_redraw`) are separate capabilities, so an upgraded
client facing a live pre-redraw integration (query-only, key unbound) degrades
to the app-side cursor home instead of writing the key. The redraw
advertisement is re-verified against the live binding at every prompt and a
same-shell rebind revokes it with an empty value, which makes the view forget
the ownership; a binding the integration still owns keeps announcing its
token. A user-owned redraw key — including an inert Bash string macro, which
`bind -p`/`bind -X` do not list — withdraws only the redraw capability: query,
completion and pointer support keep working exactly as in the pre-redraw
releases. In the running-command branch no PTY write happens; alternate-screen
sessions are left untouched entirely.
- The legacy shell already executes `Action::ClearHistory` and is unchanged.

## Validation

`cargo fmt --all -- --check`, `cargo check -p nebula --bin pebrel --features
gpui-shell --tests --locked`, the `display::keymap` and
`gpui_shell::workspace::keyboard_bindings` test groups (including the new
adapter, dispatch-probe and label regressions), the clear-screen view matrix
(prompt with query-only readiness — the 2.5.3 regression — with the explicit
redraw capability, with no advertisement, running command, and alternate screen;
the remapped-key case asserts no `^L` byte ever leaves the app), the
settings-pane suite, the i18n contract suites, the
`scripts/tests/test_completion_editor.py` redraw regressions (installed key
clears and keeps the buffer through a real bash/zsh PTY; a user-owned function
binding and a Bash string macro each keep the query capability alive while the
redraw advertisement stays off and the user binding keeps firing; a query-only
session leaves the key unbound; a same-shell rebind revokes the advertisement
with an empty value while a still-owned binding keeps announcing),
`cargo test -p nebula --test file_line_budget`
and `python3 scripts/check_architecture.py --base <PR base>` pass. The dispatch
regression fails without the adapter arm; the label regression fails without the
catalog entries.

## Supersedes

None. Extends [2026-09-21-macos-command-key-aliases.md](2026-09-21-macos-command-key-aliases.md);
its alias-table authority and unbind vocabulary are reused unchanged.

## Revisit when

The product decides clear screen deserves a default key of its own, or native
shell feedback shows that prompt redraw needs a different integration contract.
1 change: 1 addition & 0 deletions nebula_app/i18n/en-US.json
Original file line number Diff line number Diff line change
Expand Up @@ -746,6 +746,7 @@
"edit": "Edit",
"rename": "Rename",
"rename_tab": "Rename tab",
"clear_screen": "Clear screen",
"copy": "Copy",
"paste": "Paste",
"cut": "Cut",
Expand Down
1 change: 1 addition & 0 deletions nebula_app/i18n/zh-CN.json
Original file line number Diff line number Diff line change
Expand Up @@ -746,6 +746,7 @@
"edit": "编辑",
"rename": "重命名",
"rename_tab": "重命名标签页",
"clear_screen": "清屏",
"copy": "复制",
"paste": "粘贴",
"cut": "剪切",
Expand Down
9 changes: 9 additions & 0 deletions nebula_app/res/shell/powershell.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ if (-not $global:PebrelUnixReadLineInstalled) {
if ($global:PebrelCompletionInputReady) {
[Console]::Write("$([char]27)]1337;SetUserVar=pebrel_editor_ready=$global:PebrelEditorReady$([char]7)")
}
if ($global:PebrelRedrawReady) {
# Re-verify the live chord each prompt: a same-shell rebind revokes
# the capability with an empty value so the view forgets it.
if (Test-PebrelRedrawBinding) {
[Console]::Write("$([char]27)]1337;SetUserVar=pebrel_editor_redraw=$global:PebrelShellToken$([char]7)")
} else {
[Console]::Write("$([char]27)]1337;SetUserVar=pebrel_editor_redraw=$([char]7)")
}
}
# OSC 7 is the native location, including paths with spaces or Unicode.
if ($PWD.Provider.Name -eq 'FileSystem') {
$uri = [Uri]::new($PWD.Path).AbsoluteUri
Expand Down
39 changes: 38 additions & 1 deletion nebula_app/src/display/keymap.rs
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,9 @@ pub(crate) const EDITABLE_ACTIONS: &[(Action, &str, &str)] = &[
(Action::IncreaseFontSize, "增大字号", "Font size up"),
(Action::DecreaseFontSize, "减小字号", "Font size down"),
(Action::ResetFontSize, "重置字号", "Reset font size"),
// GPUI 壳的清屏没有静态默认键(⌘K 归 Shell 选择器);这一行让用户
// 能把任意键(含 ⌘K)绑到清屏,落到 ClearTerminal 动作。
(Action::ClearHistory, "清屏", "Clear screen"),
];

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

/// 只读展示行(无法在图形页编辑,TOML/settings 行仍可覆盖其中的表驱动键)。
Expand Down Expand Up @@ -216,6 +219,7 @@ fn action_message(action: &Action) -> Option<crate::i18n::Message> {
Action::IncreaseFontSize => Message::SettingsKeymapActionFontSizeUp,
Action::DecreaseFontSize => Message::SettingsKeymapActionFontSizeDown,
Action::ResetFontSize => Message::SettingsKeymapActionResetFontSize,
Action::ClearHistory => Message::CommonClearScreen,
_ => return None,
})
}
Expand Down Expand Up @@ -976,6 +980,24 @@ mod tests {
);
}

#[test]
#[cfg(target_os = "macos")]
fn clear_screen_does_not_claim_the_shell_picker_default() {
assert_eq!(GPUI.effective_combo(&Action::ClearHistory, &[]), None);
assert_eq!(
GPUI.effective_combo(&Action::ToggleShellPicker, &[]),
Some(("Command+K".into(), false))
);
let mut raw = Vec::new();
GPUI.clear_action(&mut raw, &Action::ClearHistory);
GPUI.reset_action(&mut raw, &Action::ClearHistory);
assert!(raw.is_empty());
assert_eq!(
GPUI.effective_combo(&Action::ToggleShellPicker, &build_bindings(&raw)),
Some(("Command+K".into(), false))
);
}

#[test]
fn frontend_policies_do_not_share_defaults_or_digit_identity() {
use super::*;
Expand Down Expand Up @@ -1074,6 +1096,21 @@ mod tests {
assert_eq!(action_label(row, super::super::UiLanguage::ZhCn), "重命名标签页");
}

#[test]
fn clear_screen_is_editable_and_localized_through_the_typed_message() {
use super::*;
let row =
EDITABLE_ACTIONS.iter().find(|(action, ..)| *action == Action::ClearHistory).unwrap();
for language in super::super::UiLanguage::ALL {
assert_eq!(
action_label(row, *language),
language.text(crate::i18n::Message::CommonClearScreen)
);
assert!(!action_label(row, *language).is_empty());
}
assert_eq!(action_label(row, super::super::UiLanguage::ZhCn), "清屏");
}

#[test]
fn clearing_ctrl_k_survives_persistence_and_restore_is_explicit() {
use super::*;
Expand Down
40 changes: 39 additions & 1 deletion nebula_app/src/gpui_shell/terminal/view.rs
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ use nebula_terminal::index::{Column, Line, Point as TermPoint, Side};
use nebula_terminal::render::{CellMetrics, TerminalViewport, ViewportTracker};
use nebula_terminal::selection::{Selection, SelectionType};
use nebula_terminal::term::TermMode;
use nebula_terminal::vte::ansi::CursorStyle;
use nebula_terminal::vte::ansi::{ClearMode, CursorStyle, Handler as _};

use std::sync::Arc;

Expand Down Expand Up @@ -530,6 +530,10 @@ pub struct TerminalView {
suggestion_task: Option<suggest::Pending>,
completion_session: crate::completion::Session,
completion_editor: editor::Editor,
/// 拥有 redraw 键的 shell token(`pebrel_editor_redraw` 上报)。与查询
/// 能力(`completion_editor`)分开声明:旧集成只报 query、不装 redraw
/// 键,二者混用会让升级后的客户端把键发进未绑定它的活动 shell。
editor_redraw_owner: Option<String>,
editor_query_task: Option<gpui::Task<()>>,
ghost_enabled: bool,
completion_style: crate::display::CompletionStyle,
Expand Down Expand Up @@ -1291,6 +1295,40 @@ impl TerminalView {
true
}

/// 清屏(设置页「清屏」动作的落点)。应用侧立刻清掉可见屏与回滚(零
/// 延迟反馈),随后按前台状态分流:
/// - 提示符状态(shell 在等输入,OSC 133 跟踪):发集成自有键让 shell
/// 行编辑器自己清屏重绘提示符,行状态与屏幕保持同步;
/// - 命令运行中或集成通道未就绪:应用侧直接把光标归顶,顺序输出从顶
/// 部继续;绝不发送 ^L 之类的键盘字节——那会执行 shell 里用户对
/// Ctrl+L 的任意重绑定(审查裁定 2026-11-12);
/// - 备用屏(vim/less 等全屏程序):^L 不是清屏,整键不动。
pub fn clear_screen(&mut self, cx: &mut Context<Self>) {
let Some(session) = &self.session else { return };
{
let mut term = session.term.lock();
if term.mode().contains(TermMode::ALT_SCREEN) {
return;
}
term.clear_screen(ClearMode::All);
term.clear_screen(ClearMode::Saved);
if term.nebula_prompt_active() {
drop(term);
// editor_clear_bytes reads term_mode(), which re-locks the same
// term mutex; the redraw decision must run after the guard is
// released, and the fallback re-locks for the cursor home.
if let Some(bytes) = self.editor_clear_bytes() {
self.write_bytes(bytes);
} else {
session.term.lock().goto(0, 0);
}
} else {
term.goto(0, 0);
}
}
cx.notify();
}

fn paste_now(&mut self, text: &str, cx: &mut Context<Self>) {
self.paste_now_impl(text, true, cx);
}
Expand Down
Loading
Loading