diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-05 23:27:29 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-05 23:58:31 -0300 |
| commit | cd3627307740896426830423598d2e1a8e27b024 (patch) | |
| tree | 8cb845c8da5d07c15d9d234f285bff9cffb83449 /docs | |
| parent | 342650183a54dcfcdce6ca4d45d6fdf48b2d1c1c (diff) | |
| download | pardes-cd3627307740896426830423598d2e1a8e27b024.tar.gz pardes-cd3627307740896426830423598d2e1a8e27b024.zip | |
settings #5, three behaviour knobs go, each the value it had by default: ProgramEsc (in a raw terminal Esc goes back a pane and Shift-Esc is the program's Esc; keys.zig's at-the-prompt Esc, which only ProgramEsc reached, goes), JumpScope (Back and Forward keep to the focused pane's file first; Jump.jumpBy's scope test goes) and WindowBlur (the macOS window draws no blur: macos.zig's pardes_window_blur, its header line, and AppDelegate.swift's NSVisualEffectView backdrop go, built nowhere here; Capabilities.window_blur with them); deleted tests: "with ProgramEsc raw tty Escape only leaves at a shell prompt", "modes: with JumpScope all, Ctrl-o and Ctrl-i take every place in the order it was jumped to, and bare JumpScope is file again", "window blur defaults off and validates without changing opacity", macos.zig's "mac window blur builtin reaches the ABI without changing opacity", and the JumpScope all half of "settings: Back and Forward written to exec keep to the focused file"; rewritten: dump's settings test on Wrap, the PDF jump test without its scope check, other-files' jump to a closed file from the +Jumps listing (no file to keep to); the reference, guide, helix-keys and macos docs lose the three; no golden changes; gates on tui: core-test 961/961, behaviour-test 240/240, unit-test 1476/1477, pane-test 171/172, snap all 105 scripts ok, process-test 0 of 37 failed; gui unit-test 1520/1521
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/helix-keys.md | 4 | ||||
| -rw-r--r-- | docs/macos.md | 34 | ||||
| -rw-r--r-- | docs/typ/builtins-gui.json | 2 | ||||
| -rw-r--r-- | docs/typ/builtins-tui.json | 2 | ||||
| -rw-r--r-- | docs/typ/guide.typ | 4 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 4 |
6 files changed, 8 insertions, 42 deletions
diff --git a/docs/helix-keys.md b/docs/helix-keys.md index 16ad856b..3e2d0ebb 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -110,7 +110,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). 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) | +| `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 | 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 | @@ -125,7 +125,7 @@ language-backend queries, and the shell pipe. | `y` | yank each range's text into the register (`"<reg>` 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. In a PDF pane Esc first drops the mouse selection and the search highlights when the page shows any, staying where you are reading, and the next Esc hops; `Shift-Esc` hops at once. 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` (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. In a PDF pane Esc first drops the mouse selection and the search highlights when the page shows any, staying where you are reading, and the next Esc hops; `Shift-Esc` hops at once. Raw tty takes unmodified Esc as `Last` and sends Shift-Esc to the program | 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/macos.md b/docs/macos.md index 9b8f82ec..d767dce2 100644 --- a/docs/macos.md +++ b/docs/macos.md @@ -722,18 +722,12 @@ A theme with `bg = null` — the curated `dark`, and every vendored `*_transparent` — declares no background of its own. In a terminal that means "wear whatever the terminal is wearing"; a window has nothing to wear, so `pardes_theme_bg` answers `PARDES_COLOR_DEFAULT` and the host goes see-through: -`window.isOpaque = false`, a clear background colour, and an -`NSVisualEffectView` (`.underWindowBackground`, `.behindWindow`, `.active`) -behind the grid when `WindowBlur` is enabled. `PardesView` stops painting the ground at all — it *clears*, +`window.isOpaque = false` and a clear background colour. `PardesView` stops painting the ground at all — it *clears*, because AppKit does not blank a non-opaque view — and any cell whose background is still the default resolves to `bgClear` and is skipped by the run loop. Reversed cells are not: a reverse puts the text colour in the background, and text is a real colour that paints. -The blur is a **sibling** of the grid inside a plain container, never its -parent. Hiding a superview hides its subviews, so a nested backdrop drew a -blank window for every opaque theme the moment it was hidden. - `WindowOpacity <0..100>` sets one background coverage throughout the frame. Background fills replace existing coverage, so overlapping ground, cell, tag and context layers cannot increase the requested opacity. The window itself @@ -741,7 +735,7 @@ stays clear below 100%; a second tinted window backdrop would compound it. Text and cursor ink stay opaque. PDFs render onto a transparent MuPDF pixmap, which preserves the coverage of text, paths, photos, and highlights. The host paints paper at `WindowOpacity`, then composites PDF content at its original -opacity. Blank paper therefore reveals the blurred backdrop while lettering +opacity. Blank paper therefore reveals the desktop while lettering stays readable even at `WindowOpacity 0`. Paper is white with `PdfTint` disabled and uses the theme background otherwise. Explicit PDF background rectangles and scanned page images remain content: this does not guess paper from pixel @@ -753,30 +747,8 @@ destination by source coverage, then add the image at the requested opacity. Theme colours and attachment rasters are interpreted as sRGB. The PDF paper separation is currently macOS-specific; other hosts keep the opaque raster path. -`WindowBlur <0..100>` controls the strength of that native backdrop independently -of `WindowOpacity`. It is a macOS-only builtin, also accepted in the startup -config and reported by `DumpConfig`. It defaults to 0 (off); 100 shows the full -AppKit material and intermediate values blend the material with the unblurred -backdrop using the effect view's alpha. An opaque themed background hides the -effect; lowering `WindowOpacity` makes the remembered strength visible again. -For example: - -```text -WindowOpacity 71 -WindowBlur 60 -``` - -This is material strength, not a Gaussian radius in pixels. AppKit's public -`NSVisualEffectView` API chooses its own blur and tint for the material. It -samples behind the window; text and cursors are drawn in a separate sibling -above the effect and remain sharp. macOS accessibility settings such as Reduce -Transparency can override the material's appearance. `WindowBlur 0` also turns -off the formerly implicit blur for background-less themes; set it to 100 to -restore that appearance. The compositor must be checked in a live window: -offscreen grid captures cannot verify behind-window blur. - `test/macos-snapshots/rendering-parity.snap` checks background colour and alpha, -regular and bottom tags, compact context separators, and PDF fit, tint and +tags, compact context separators, and PDF fit, tint and scrolling. Its native-metrics mode uses backing pixels like the shipping app; the older grid-only tests keep their display-independent point metrics. diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json index 996ea7fa..6a5856a9 100644 --- a/docs/typ/builtins-gui.json +++ b/docs/typ/builtins-gui.json @@ -47,7 +47,6 @@ {"name": "Incl", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "acme's Incl, for the session: `Incl dir ...` adds directories a look at a name found nowhere else is tried in (`stdio.h`, `<foo.h>`), bare lists them, `Incl -` empties the list."}, {"name": "Index", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Run the file's language indexer at its project root, writing the index.scip the language words ask first."}, {"name": "Joincol", "leader": "SPC c j", "also": ["topbar"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Fold the active pane's column into the one on its right, keeping its panes."}, - {"name": "JumpScope", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "file, all", "doc": "What Back and Forward keep to: file, the focused pane's file until it runs out that way, or all, every place in order."}, {"name": "JumpTrail", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A jump of the cursor leaves a short trail that fades, on or off."}, {"name": "Jumplist", "leader": "SPC j l", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "List the places jumped from, each a place to go."}, {"name": "Kill", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "acme's Kill: stop the commands pardes started -- the lines it typed into a terminal, from an exec, a middle click or a pty/run, while their shell says they run (C mark to D)."}, @@ -76,7 +75,6 @@ {"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": "Pet", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "off, cat, frog", "doc": "The window's companion in the workspace tag's blank space: off, cat or frog."}, {"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": "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": true, "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-tui.json b/docs/typ/builtins-tui.json index 010aaea1..1a6a4023 100644 --- a/docs/typ/builtins-tui.json +++ b/docs/typ/builtins-tui.json @@ -43,7 +43,6 @@ {"name": "Incl", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "acme's Incl, for the session: `Incl dir ...` adds directories a look at a name found nowhere else is tried in (`stdio.h`, `<foo.h>`), bare lists them, `Incl -` empties the list."}, {"name": "Index", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Run the file's language indexer at its project root, writing the index.scip the language words ask first."}, {"name": "Joincol", "leader": "SPC c j", "also": ["topbar"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Fold the active pane's column into the one on its right, keeping its panes."}, - {"name": "JumpScope", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "file, all", "doc": "What Back and Forward keep to: file, the focused pane's file until it runs out that way, or all, every place in order."}, {"name": "JumpTrail", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A jump of the cursor leaves a short trail that fades, on or off."}, {"name": "Jumplist", "leader": "SPC j l", "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "List the places jumped from, each a place to go."}, {"name": "Kill", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "acme's Kill: stop the commands pardes started -- the lines it typed into a terminal, from an exec, a middle click or a pty/run, while their shell says they run (C mark to D)."}, @@ -71,7 +70,6 @@ {"name": "PdfSections", "leader": "SPC t s", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the PDF's sections in a pane, each a place to go."}, {"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": "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": true, "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/guide.typ b/docs/typ/guide.typ index 62aab397..d69b1471 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"): 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.], + [#mode-box("$") raw], [#key("Esc"): back to the previous pane. #key("Shift-Esc"): an Esc to the program. Either way the terminal stays raw.], [a PDF], [#key("Esc"): clears the selection and the search highlights, and with none shown goes back to the previous pane. #key("Shift-Esc"): back at once.], ) @@ -55,7 +55,7 @@ the next pane down the column. #pairs( [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag. #key("d") is #word("Del") on the outlined pane (between two panes it waits for #key("k") or #key("j"), as #key("SPC d") does) and the outline moves to the pane that took its rows; #key("c") is #word("Collapse"). The mode stays on for the next key], - [#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list), this file's first: another file's only once it has none left that way (#word("JumpScope") `all`: every place in order). #key("Ctrl-i") needs the kitty keyboard protocol or the GUI, being #key("Tab") elsewhere: there use #key("SPC j i") and #key("SPC j o"), or the mouse's side buttons], + [#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list), this file's first: another file's only once it has none left that way. #key("Ctrl-i") needs the kitty keyboard protocol or the GUI, being #key("Tab") elsewhere: there use #key("SPC j i") and #key("SPC j o"), or the mouse's side buttons], ) Raw mode sends almost every key to the program. Leave it (#key("Ctrl-b")) diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index c9e117e8..72d0b5ee 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -440,8 +440,6 @@ word clicked in a tag does. The same lines go in the startup file [#word("ThemeFile") `<path>`], [a `.zon` theme, relative to the config directory; reloads live when saved], [#word("Verbose")], [on: a builtin announces its name on the message row], [#word("MessageLinger")], [800 milliseconds, at most 60000: how long a message stays after the key or click that dismisses it], - [#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("JumpScope") `file|all`], [`file`: #word("Back") and #word("Forward") keep to the focused pane's file, that pane's places first, then the file's in another pane, and go to another file only when the file has no place left that way; from a terminal or a pane with no file they step through every place; `all`: every place, in the order it was jumped to], [#word("Shell") `<name or path>`], [`$SHELL` when it is executable, else `/bin/sh`: the shell the next terminal and command pane run; a bare name is searched for in the usual bin directories, not `$PATH`; bare #word("Shell"): `$SHELL` if it is executable, else `/bin/sh`], [#word("DumpDir") `<dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: the directory of the state file, `pardes.xitdb`, which keeps Recent and the dumps and which every session of the user shares (one that cannot be read as one is kept aside as `pardes.xitdb.broken` and a new one started); an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default], [#word("TreeContext")], [off: sticky declaration headers in a source pane, in the tagline style (per pane, dumped)], @@ -1027,7 +1025,7 @@ to its end before the write is answered, and one that finds nothing fails, = On screen <on-screen> -- *Esc at a prompt* (with #word("ProgramEsc") on). pardes knows a shell prompt with nothing typed on it +- *A command at a prompt.* A command run from a terminal's text is typed at its shell when the shell sits at a prompt with nothing typed on it, else run in a pane of its own. pardes knows such a prompt 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. |
