From 4e89db185fa4e3bfe4358d2da3b76fad0cc7e547 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 21 Oct 2026 21:30:24 -0300 Subject: Esc in a raw terminal is pardes's; Shift-Esc goes to the program (ProgramEsc) --- README.md | 4 ++-- docs/helix-keys.md | 4 ++-- docs/typ/builtins-gui.json | 1 + docs/typ/builtins-tty.json | 1 + docs/typ/cheatsheet.typ | 4 ++-- docs/typ/guide.typ | 2 +- docs/typ/reference.typ | 3 ++- src/CHANGELOG.md | 5 +++++ src/config.zig | 13 +++++++++--- src/pardes.zig | 47 ++++++++++++++++++++++++++++++++++++++---- src/tutor.txt | 4 ++-- test/snapshots/builtins.golden | 4 ++-- test/snapshots/builtins.snap | 1 + 13 files changed, 74 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 0a03bdba..4ad49cc6 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Get the source with `git clone https://git.sr.ht/~gbrls/pardes && cd pardes` (also at https://git.0x4200.cafe/pardes). Install with Zig 0.17: `zig build -Dplatform=tty --prefix ~/.local` for `pardes` in a terminal, or `-Dplatform=gui` for the `pardes-gui` window. -The terminal should report the mouse; Shift-Esc needs the kitty keyboard -protocol, and images need kitty graphics (else they are drawn as PETSCII +The terminal should report the mouse; Shift-Esc (the Esc a terminal +pane's program gets) needs the kitty keyboard protocol, and images need kitty graphics (else they are drawn as PETSCII glyphs). Run `pardes` or `pardes FILE`. Read the [guide](docs/typ/guide.typ) (about 15 minutes), then try `Tutor` diff --git a/docs/helix-keys.md b/docs/helix-keys.md index ddbab93b..0b71f60b 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -107,7 +107,7 @@ language-backend queries, and the shell pipe. | `gh` / `gl` | line start / line end (last char, not the newline) | | helix-verified | | `Ctrl-d` / `Ctrl-u` | half page down/up, cursor follows | matches `page_cursor_half_down/up` | helix-verified | | `Ctrl-f` | full page down | matches `page_down`; file panes only get `Ctrl-b` (see next row) | helix-verified | -| `Ctrl-b` | file panes: full page up. Terminal panes: **toggle raw tty/editor mode** (`opts.tty_toggle`, configurable; `Shift-Esc` also enters). In raw tty Shift-Esc goes to the child | tty toggle is pardes-specific and wins on terminals; harness `pane:"tty"` cases avoid `Ctrl-b` | helix-verified (file) / pardes-specific (tty) | +| `Ctrl-b` | file panes: full page up. Terminal panes: **toggle raw tty/editor mode** (`opts.tty_toggle`, configurable). In raw tty Esc runs `Last` and Shift-Esc goes to the child as a plain Esc (`ProgramEsc on` swaps them) | tty toggle is pardes-specific and wins on terminals; harness `pane:"tty"` cases avoid `Ctrl-b` | helix-verified (file) / pardes-specific (tty) | | `PageUp` / `PageDown` | full page | matches helix `page_up`/`page_down` (view scroll + cursor snap to the scrolloff edge) | helix-verified | | `zt` / `zz` / `zb` | scroll current line to top / center / bottom | matches `align_view_top/center/bottom` (helix harness pins scrolloff to pardes' 3) | helix-verified | | `Z` | sticky view mode: the `z` keys stay armed after each until Esc, which only leaves the mode; other keys do nothing meanwhile | helix's sticky view node | helix-verified | @@ -122,7 +122,7 @@ language-backend queries, and the shell pipe. | `y` | yank each range's text into the register (`"` names one, else `"`), one value per range | line-yank vim-ism removed (phase 5); yank keeps selection AND cursor (helix). The system clipboard is `"+y` / `SPC y`, helix's own split: a `d` of one character never clobbers what the desktop holds | helix-verified | | `u` / `U` | undo / redo | restores the pre-edit selection (helix); snapshot granularity, `Alt-u`/`Alt-U` are the same two: helix walks a history tree by time with them, and pardes's history is linear, so earlier and later ARE undo and redo | helix-verified | | `p` (normal) | paste the register after each range: value i at range i, the last value repeated when there are fewer | helix `paste_impl`. `"+p` asks the system clipboard (`SPC p`); on a tty that read is OSC 52, which most terminals refuse: an honest no-op rather than a paste of the wrong text | helix-verified | -| `Esc` (body normal) | clear a pending modal prefix / exit select mode, keeping the selection, then run `Last`: hop to the pane you were in before this one, whichever kind it was, exactly like `SPC j j` — so held down it alternates between two panes, two files as readily as a file and its shell. A PDF pane is the ONE exception: there Esc is the document's own cancel (drop the mouse selection and the search overlay, stay where you are reading) and `Shift-Esc` is the hop out, while raw tty only intercepts unmodified Esc at a detected shell prompt | Pardes-specific focus binding layered on helix's cleanup. A leader path, tag, topbar or search owns Esc while it is active; raw tty forwards it | pardes-specific (cleanup helix-verified) | +| `Esc` (body normal) | clear a pending modal prefix / exit select mode, keeping the selection, then run `Last`: hop to the pane you were in before this one, whichever kind it was, exactly like `SPC j j` — so held down it alternates between two panes, two files as readily as a file and its shell. A PDF pane is the ONE exception: there Esc is the document's own cancel (drop the mouse selection and the search overlay, stay where you are reading) and `Shift-Esc` is the hop out, while raw tty takes unmodified Esc as `Last` and sends Shift-Esc to the program (with `ProgramEsc on`, Esc goes to the program except at a detected shell prompt) | Pardes-specific focus binding layered on helix's cleanup. A leader path, tag, topbar or search owns Esc while it is active; raw tty forwards it | pardes-specific (cleanup helix-verified) | | `Esc` (insert) | back to normal mode, cursor right after the insertion (no vim left-step) | | helix-verified | | `Enter` (normal) | acme **look** chord: EXPLICIT selection, else file-ish word under cursor | pardes-specific, keep (helix normal-mode Enter unbound). Covers helix `gf`. Implicit motion residue falls back to the cursor word | pardes-specific | | `Tab` (normal) | acme **execute** chord | pardes-specific, keep; explicit-selection rule as Enter | pardes-specific | diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json index f602ee92..851b8673 100644 --- a/docs/typ/builtins-gui.json +++ b/docs/typ/builtins-gui.json @@ -109,6 +109,7 @@ {"name": "Pet", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "An optional SDL workspace-tag companion; never consumes input or text cells."}, {"name": "Petscii", "leader": "SPC t p", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "glyph art over the host's pixels: an image pane's picture, or the kitty graphics a terminal's program placed (yazi's previews)"}, {"name": "Placement", "leader": "SPC c p", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "acme, pardes", "doc": "Where a new pane goes: acme, as makenewwindow does, or pardes, the older rules."}, + {"name": "ProgramEsc", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "In a raw terminal, Esc goes to the program and Shift-Esc backs out, on; off (the default) swaps them."}, {"name": "Putall", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "acme's Putall: every pane holding unsaved edits to a file is saved, each as its own Save; one that is refused (changed on disk since, a write that fails) says so and the rest are saved all the same."}, {"name": "Recent", "leader": "SPC f r", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "List the files opened lately, closed ones too, each a place to open again."}, {"name": "Redo", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Redo the last undone edit."}, diff --git a/docs/typ/builtins-tty.json b/docs/typ/builtins-tty.json index e02f4201..e1276117 100644 --- a/docs/typ/builtins-tty.json +++ b/docs/typ/builtins-tty.json @@ -96,6 +96,7 @@ {"name": "PdfTint", "leader": "SPC t i", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Tint the PDF page to the theme, or show it as printed, stepping through them (or to the one named, `disabled|filtered|full`)."}, {"name": "Petscii", "leader": "SPC t p", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "glyph art over the host's pixels: an image pane's picture, or the kitty graphics a terminal's program placed (yazi's previews)"}, {"name": "Placement", "leader": "SPC c p", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "acme, pardes", "doc": "Where a new pane goes: acme, as makenewwindow does, or pardes, the older rules."}, + {"name": "ProgramEsc", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "In a raw terminal, Esc goes to the program and Shift-Esc backs out, on; off (the default) swaps them."}, {"name": "Putall", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "acme's Putall: every pane holding unsaved edits to a file is saved, each as its own Save; one that is refused (changed on disk since, a write that fails) says so and the rest are saved all the same."}, {"name": "Recent", "leader": "SPC f r", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "List the files opened lately, closed ones too, each a place to open again."}, {"name": "Redo", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Redo the last undone edit."}, diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ index d2df7e70..36bff0a7 100644 --- a/docs/typ/cheatsheet.typ +++ b/docs/typ/cheatsheet.typ @@ -72,8 +72,8 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla == Keys: panes #pairs( [#key("Ctrl-w") #keys("h", "j", "k", "l")], [then a direction: focus a neighbour (not in insert or raw `$`)], - [#key("Esc")], [back to the previous pane (raw: only at a prompt with nothing typed; insert: to normal)], - [#key("Shift-Esc")], [back to the previous pane from any mode, with the kitty keyboard protocol or in the GUI; elsewhere a plain Esc], + [#key("Esc")], [back to the previous pane (insert: to normal)], + [#key("Shift-Esc")], [back to the previous pane from any mode but raw, where it is the program's Esc; needs the kitty keyboard protocol or the GUI, elsewhere a plain Esc], [#keys("Ctrl-o", "Ctrl-i")], [jump history back, forward; this file first], [#key("Alt-n")], [new terminal below], [#key("Alt-c")], [move the pane to a new column], diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index 7058592f..93bc653a 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -42,7 +42,7 @@ steps raw, normal, insert. #pairs( [#mode-box(" ") normal], [#key("Esc"): back to the previous pane (#word("Last")), unlike helix. #key("Shift-Esc"): the same.], [#mode-box("^") insert], [#key("Esc"): back to normal. #key("Shift-Esc"): out of insert and back to the previous pane.], - [#mode-box("$") raw], [#key("Esc"): to the program, except at a shell prompt with nothing typed on it, where it goes back to the previous pane. #key("Shift-Esc"): always back. Either way the terminal stays raw.], + [#mode-box("$") raw], [#key("Esc"): back to the previous pane. #key("Shift-Esc"): an Esc to the program. Either way the terminal stays raw. #word("ProgramEsc") `on` swaps them back: #key("Esc") goes to the program, except at a shell prompt with nothing typed on it, and #key("Shift-Esc") always goes back.], [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.], ) diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 05176951..455d2645 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -415,6 +415,7 @@ word clicked in a tag does. The same lines go in the startup file [#word("MessageAnimation")], [on: messages ease in and dissolve], [#word("MessageLinger"), #word("MessageFall"), #word("MessageDissolve")], [800, 180, 150 milliseconds, at most 60000], [#word("PagerColor")], [on: the next paged text keeps its colours], + [#word("ProgramEsc")], [off: in a raw terminal #key("Esc") goes back a pane and #key("Shift-Esc") is the program's Esc; on swaps them, and #key("Esc") goes back only at an empty shell prompt], [#word("Pager") `pardes|off`], [`pardes`: what a terminal's commands page through, `pardes -`; `off` leaves `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` as the environment has them (#doc("fs", section: "pardes-stdin")). It applies to terminals started after it], [#word("Placement") `acme|pardes`], [`acme`: where new panes go (#doc("fs", section: "placement"))], [#word("BootShell") `keep|replace`], [`keep`; `replace` closes the untouched lone shell a dragged document lands beside], @@ -969,7 +970,7 @@ it was. = On screen -- *Esc at a prompt.* pardes knows a shell prompt with nothing typed on it +- *Esc at a prompt* (with #word("ProgramEsc") on). pardes knows a shell prompt with nothing typed on it from the OSC 133 marks it injects into bash and fish (marks a shell sends itself do not count); for other shells, from no program holding the terminal, typed text or not. diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index 362aaf5b..76a1fd56 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -24,6 +24,11 @@ scroll as it glides, instead of jumping a row of the track at a time. - A click in another pane glides the cursor once, straight to where it was clicked, no longer first to that pane's old cursor. +- Esc in a raw terminal goes back to the previous pane, as it does from + normal mode; Shift-Esc sends the program its Esc. `ProgramEsc on` + restores the old way round. A terminal without the kitty keyboard + protocol sends Shift-Esc as a plain Esc, so under one a program gets + no Esc unless ProgramEsc is on. - Built with Zig 0.17. A bare `zig build` still puts the binaries in `~/.local/bin`, now as a copy beside the prefix, which `--prefix` no diff --git a/src/config.zig b/src/config.zig index 8166954d..f3cc0948 100644 --- a/src/config.zig +++ b/src/config.zig @@ -153,6 +153,7 @@ pub const leader_path = paths: { table.set(.JumpTrail, null); table.set(.ChipShadow, null); table.set(.ThumbFlash, null); + table.set(.ProgramEsc, null); if (builtins.capabilities.lift) table.set(.Lift, null); table.set(.Motion, null); table.set(.InactiveDim, null); @@ -283,8 +284,9 @@ pub const jump_keys = [_]struct { chord: Chord, cmd: Builtin }{ }; /// Shift-Esc: the Esc nothing swallows. In every mode and pane it does what -/// Esc does from normal mode, back to the previous pane (Last); a raw -/// terminal's program never sees it. Ctrl-b alone toggles raw. +/// Esc does from normal mode, back to the previous pane (Last); in a raw +/// terminal plain Esc does it and Shift-Esc is the program's Esc, unless +/// ProgramEsc is on. Ctrl-b alone toggles raw. pub const back_out: []const Chord = &.{.{ .cp = Key.escape, .shift = true }}; pub const tty_toggle_default: u21 = 'b'; @@ -764,6 +766,9 @@ pub const Runtime = struct { /// T7: in a terminal, a pane's scroll thumb brightens as it scrolls and /// fades back (truecolor terminals). thumb_flash: bool = false, + /// In a raw terminal, Esc goes to the program and Shift-Esc backs out + /// (off, the default: Esc backs out and Shift-Esc is the program's). + program_esc: bool = false, /// How long a message stays after the key or click that dismisses it. message_linger_ms: u16 = 800, /// How long its fall into the row takes, easing out (§8.1: arriving, @@ -1022,7 +1027,7 @@ pub const Runtime = struct { /// The message timings a setting word sets, each in milliseconds. pub const MessageTime = enum { linger, fall, dissolve }; - pub const Toggle = enum { colors, wrap, tree_context_tag_style, tag_bottom, debug, focus_tint, syntax_bold, pager_color, verbose, message_animation, ligatures, cursor_blink, selection_glow, hover_glow, occlusion, parallax, jump_trail, chip_shadow, thumb_flash }; + pub const Toggle = enum { colors, wrap, tree_context_tag_style, tag_bottom, debug, focus_tint, syntax_bold, pager_color, verbose, message_animation, ligatures, cursor_blink, selection_glow, hover_glow, occlusion, parallax, jump_trail, chip_shadow, thumb_flash, program_esc }; /// A bundled post pass, a Shadertoy file in shaders/post/: the CRT, and /// G4's bloom, vignette and grain (docs/effects.md). pub const Scene = enum { crt, bloom, vignette, grain }; @@ -1090,6 +1095,7 @@ pub const Runtime = struct { .{ .word = "JumpTrail", .action = .{ .toggle = .jump_trail }, .doc = "In a terminal, a jump of the cursor leaves a short trail that fades, on or off." }, .{ .word = "ChipShadow", .action = .{ .toggle = .chip_shadow }, .doc = "In a terminal, a notice chip casts a cell's shadow right and down, on or off." }, .{ .word = "ThumbFlash", .action = .{ .toggle = .thumb_flash }, .doc = "In a terminal, a pane's scroll thumb brightens as it scrolls and fades back, on or off." }, + .{ .word = "ProgramEsc", .action = .{ .toggle = .program_esc }, .doc = "In a raw terminal, Esc goes to the program and Shift-Esc backs out, on; off (the default) swaps them." }, .{ .word = "Lift", .action = .lift, .availability = .lift, .doc = "How the focused pane stands off the page: off, shadow, rim or auto." }, .{ .word = "Motion", .action = .motion, .doc = "How animations move: off, crisp, smooth, bouncy or playful." }, .{ .word = "InactiveDim", .action = .inactive_dim, .doc = "Fade the unfocused panes' text by a percentage, 0 through 100, 0 off." }, @@ -1876,6 +1882,7 @@ pub const Runtime = struct { .jump_trail => "JumpTrail on\n", .chip_shadow => "ChipShadow on\n", .thumb_flash => "ThumbFlash on\n", + .program_esc => "ProgramEsc on\n", }, .shell => "Shell fish\n", .tagline_size => "TaglineSize 73\n", diff --git a/src/pardes.zig b/src/pardes.zig index 72470490..c885acc2 100644 --- a/src/pardes.zig +++ b/src/pardes.zig @@ -6374,10 +6374,23 @@ pub const Pardes = struct { } const pane = p.panes[p.active] orelse return; p.noteTyped(); + // In a raw terminal the two Escs swap unless ProgramEsc is on: Esc + // backs out, and Shift-Esc is the program's, sent as a plain Esc. + const raw_esc = key.cp == Key.escape and !key.ctrl and !key.alt and !p.settings.program_esc and + pane.isTerminal() and pane.body.mode == .tty and pane.focus == .body and pane.prompt == .none and + tagline.focusedHeader(p) == null; + if (raw_esc and key.shift) { + p.leader_on = false; + p.ctrl_w_pending = false; + panes.terminal.followOutput(pane); + var plain = key; + plain.shift = false; + return panes.terminal.forwardKey(p, p.active, plain); + } // Shift-Esc backs out of whatever the pane is in -- a prompt, insert // mode, a pending count, a raw program -- to the previous pane, as // Esc does from normal mode. Nothing under it sees the key. - if (hit(key, config.back_out)) { + if (raw_esc or hit(key, config.back_out)) { p.leader_on = false; p.ctrl_w_pending = false; if (pane.prompt != .none) { @@ -6405,8 +6418,8 @@ pub const Pardes = struct { p.ctrl_w_pending = false; if (key.ctrl and !key.alt and key.cp == p.opts.tty_toggle) return p.toggleTty(p.active); - // Bare Escape leaves only at a shell prompt (Shift-Esc, above, - // always). + // With ProgramEsc on, bare Escape leaves only at a shell prompt + // (Shift-Esc, above, always). if (key.cp == Key.escape and !key.ctrl and !key.alt and !key.shift and exec.takesCommandLine(p, p.active)) return exec.runBuiltin(p, .Last, p.active, "", null); panes.terminal.followOutput(pane); // typing snaps back to live output @@ -8442,10 +8455,36 @@ test "Esc back into a file leaves its view where it was" { try std.testing.expectEqual(@as(usize, @intCast(row)) -| @as(usize, dp.rows) / 2, dp.file.?.scroll); } -test "raw tty Escape only leaves at a shell prompt" { +test "raw tty Esc backs out and Shift-Esc is the program's Esc" { + if (platform == .web) return; + const p = try Pardes.init(std.testing.allocator, .{ .cols = 80, .rows = 24, .file = "mise.toml" }); + defer p.deinit(); + _ = exec.spawnTty(p, 0); + const shell = p.active; + const pane = p.panes[shell].?; + var buf: [256]u8 = undefined; + _ = drainWrites(p, &buf); + + p.update(.{ .key = .{ .cp = 'x', .text = "x" } }); + _ = drainWrites(p, &buf); + p.update(.{ .key = .{ .cp = Key.escape } }); // past typed text too + try std.testing.expectEqual(@as(usize, 0), p.active); + try std.testing.expectEqualStrings("", drainWrites(p, &buf)); + try std.testing.expectEqual(Text.Mode.tty, pane.body.mode); + + p.update(.{ .key = .{ .cp = Key.escape } }); // back into the shell + try std.testing.expectEqual(shell, p.active); + _ = drainWrites(p, &buf); + p.update(.{ .key = .{ .cp = Key.escape, .shift = true } }); + try std.testing.expectEqual(shell, p.active); + try std.testing.expectEqualStrings("\x1b", drainWrites(p, &buf)); +} + +test "with ProgramEsc raw tty Escape only leaves at a shell prompt" { if (platform == .web) return; const p = try Pardes.init(std.testing.allocator, .{ .cols = 80, .rows = 24, .file = "mise.toml" }); defer p.deinit(); + p.settings.program_esc = true; _ = exec.spawnTty(p, 0); const shell = p.active; const pane = p.panes[shell].?; diff --git a/src/tutor.txt b/src/tutor.txt index 8f5cf241..5df02f1a 100644 --- a/src/tutor.txt +++ b/src/tutor.txt @@ -29,8 +29,8 @@ pane you were in before (not what helix does). Come back with Esc again. 3. Press Alt-n: a terminal opens, in NORMAL mode. Press Ctrl-b: its - box shows $ (RAW), and keys go to the shell. At its empty prompt, - Esc brings you back here; the terminal stays $. + box shows $ (RAW), and keys go to the shell. Esc brings you back + here; the terminal stays $. Shift-Esc sends the shell an Esc. -> Guide: Modes diff --git a/test/snapshots/builtins.golden b/test/snapshots/builtins.golden index b9d5c5b2..9eb9718b 100644 --- a/test/snapshots/builtins.golden +++ b/test/snapshots/builtins.golden @@ -59,8 +59,8 @@ |44: 29 pane you were in before (not what helix does). Come back with |45: 30 Esc again. |46: 31 3. Press Alt-n: a terminal opens, in NORMAL mode. Press Ctrl-b: its -|47: 32 box shows $ (RAW), and keys go to the shell. At its empty prompt, -|48: 33 Esc brings you back here; the terminal stays $. +|47: 32 box shows $ (RAW), and keys go to the shell. Esc brings you back +|48: 33 here; the terminal stays $. Shift-Esc sends the shell an Esc. |49: 34 |50: 35 -> Guide: Modes |51: 36 diff --git a/test/snapshots/builtins.snap b/test/snapshots/builtins.snap index fc0ab796..c59b79d6 100644 --- a/test/snapshots/builtins.snap +++ b/test/snapshots/builtins.snap @@ -32,6 +32,7 @@ wheel up 110 50 wheel up 110 50 wheel up 110 50 wheel up 110 50 +wheel up 110 50 wait 10000 Look enter, right-click wait 10000 Exec tab, middle-click wait 10000 Filter -- cgit v1.3