|
| 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. |
0 commit comments