Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
52 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
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,190 @@
# 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. Amended 2026-11-13: the redraw
capability contract tightened to full-sequence consumption across every
reachable keymap (review round 13, PR #653) — see the last Decision
bullet.

## 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
(`pebrel_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` (`pebrel_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

- `pebrel_app/src/main.rs` selects `product_input.rs` for `input` when the legacy
shell is disabled; `input::Processor` / `process_key_bindings` are legacy-only.
- `pebrel_app/src/config/bindings/defaults.rs` macOS platform table binds ⌘K twice
(`Esc("\x0c")`, `ClearHistory`); `pebrel_terminal/src/term/clear.rs` shows
`ClearMode::Saved` clears only the scrollback while `ClearMode::All` clears the
viewport.
- `pebrel_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).
- **Amendment (2026-11-13, review round 13):** ownership of the Bash/zsh redraw
key is all-or-nothing across keymaps. A multi-byte chord is not consumed as a
whole in an unbound keymap — vi(zsh) `vicmd` and readline `vi-command` leave
the trailing `~` bound to the invert-case command, so a redraw sent into a
merely-unbound keymap rewrote the user's line ("original" → "originaL").
Installation therefore scans every reachable keymap and either installs the
built-in clear-screen into each of them (vi users included) or, if any keymap
holds a user binding, installs nothing at all; keymaps that refuse binding
(zsh protected keymaps like `.safe`) are unreachable through a typed chord and
are excluded from the contract rather than killing it. The per-prompt probe
re-verifies exactly the recorded keymap set: anything that is not our
binding — rebind, unbind, macro — revokes the announcement and the view falls
back to the app-side cursor home.

## 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 pebrel --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 pebrel --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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Pointer chord turns must not overlap a render burst

## Status

Implemented in the PTY harness (`scripts/tests/test_powershell_pointer.py`).
The chord transport itself is unchanged from
[the native PSReadLine pointer decision](2026-10-31-powershell-native-pointer.md);
this note records a harness contract and the load-fragility evidence behind it.

## Context

CI (macos-26-intel) failed `test_native_unicode_moves_range_delete_and_one_undo`
sporadically while the same test passed on the same runner image at other times
of the same day. The pointer protocol drives PSReadLine with ESC-prefixed CSI
chords (`Ctrl+Shift+F10,digit`, `Ctrl+Shift+F12`) written over a real PTY, and
the harness schedules its next chord after a wall-clock quiet window.

## Evidence

A byte-level trace (both PTY directions, timestamps) of a failing run showed:

- The numeric query completed normally (`pebrel_pointer` var arrived).
- The move chord and the snapshot chord were written 304 ms apart with **zero
output between them**: pwsh had not yet reacted to the move chord when the
snapshot chord landed inside its in-flight render burst.
- The subsequent renders show the snapshot chord torn: a standalone Escape
(Windows mode reverts the line — the buffer render collapses to spaces),
then literal `[` and `;` keys inserted (digits swallowed by DigitArgument),
and the `pebrel_editor` var never emitted; the harness timed out after 12 s.

Reproduced under a 4-way parallel stress loop on macOS x64: 36/40 runs failed,
23 of them with exactly this tear signature (matching the CI assertion and the
captured buffer residues). The same test passes deterministically without
parallel load. In every passing turn the chord was parsed only after the
previous burst had drained (probe, render, quiet).

## Decision

The harness serializes protocol turns: before writing any chord it waits
(bounded) for the editor's first reaction byte to the previous write, then
drains the burst to quiet (`PowerShellSession.turn`). The wait-loop poll
interval drops from 100 ms to 20 ms so cursor-position replies land closer to
real-terminal timing. Test assertions are unchanged; no coverage is removed.

## Rejected alternatives

- Retry or restart the session on corruption: masks the tear instead of
removing its cause, and could hide a genuinely corrupted buffer behind a
fresh one.
- Longer wall-clock quiet windows: the quiet window expired mid-burst in the
failing trace (304 ms of total silence), so tuning the window alone cannot
anchor on the editor's actual progress.
- Changing the protocol chords: unbound CSI chords necessarily carry an ESC
prefix, and the same encoding is what the GUI negotiates through its
keyboard encoder; there is no non-ESC alternative in the xterm space.
- A background reader thread for cursor-position replies: the failing trace
shows replies arriving 1 ms after each probe, so reply latency was not the
cause; threading would rewrite the harness without addressing the overlap.

## Consequences

Each chord is parsed from a quiescent input queue, and the harness now states
its turn discipline in code rather than relying on runner idle time. Turns
cost one reaction wait plus the drain window, so the suite runs somewhat
slower under load. The production exposure is unchanged and documented: the
GUI sends the same chords over a real PTY, so the same tear remains possible
under extreme load; the protocol's query/snapshot replies let the GUI detect a
desynchronized editor, and no field occurrence is known.

## Validation

`scripts.tests.test_powershell_pointer` passes. Under the identical 4-way
parallel stress: before the change 23/40 runs showed the tear signature,
after the change 0/40 (the remaining 8 are pwsh cold starts starved past the
12 s startup timeout by four concurrent instances — an artifact of the
artificial parallel load, never observed in CI's serial native jobs).

## Supersedes

None. Evidence amendment for
[the native PSReadLine pointer decision](2026-10-31-powershell-native-pointer.md).

## Revisit when

A tear is observed outside the test harness, PSReadLine or .NET documents a
reliable ESC-sequence read contract, or the GUI starts batching pointer chords
with its own turn scheduling.
1 change: 1 addition & 0 deletions pebrel_app/i18n/en-US.json
Original file line number Diff line number Diff line change
Expand Up @@ -755,6 +755,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 pebrel_app/i18n/zh-CN.json
Original file line number Diff line number Diff line change
Expand Up @@ -755,6 +755,7 @@
"edit": "编辑",
"rename": "重命名",
"rename_tab": "重命名标签页",
"clear_screen": "清屏",
"copy": "复制",
"paste": "粘贴",
"cut": "剪切",
Expand Down
9 changes: 9 additions & 0 deletions pebrel_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
Loading
Loading