summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-08 12:00:28 -0300
committerGabriel Schneider <[email protected]>2026-10-22 10:03:15 -0300
commit13d5613b77c62c425c3a124a34c0c2528cc6251f (patch)
treef3cbe41683ef31641ea087039db9fc3be81e141f /docs
parent046979b877f02a91cf52cc86b84c5619cb9363d3 (diff)
downloadpardes-13d5613b77c62c425c3a124a34c0c2528cc6251f.tar.gz
pardes-13d5613b77c62c425c3a124a34c0c2528cc6251f.zip
Follow Helix search registers for n/N; keep Look navigation as named builtins
Diffstat (limited to 'docs')
-rw-r--r--docs/helix-keys.md19
-rw-r--r--docs/typ/guide.typ7
2 files changed, 14 insertions, 12 deletions
diff --git a/docs/helix-keys.md b/docs/helix-keys.md
index 6249fc15..ddbab93b 100644
--- a/docs/helix-keys.md
+++ b/docs/helix-keys.md
@@ -48,7 +48,7 @@ at the bottom.
collapse) — the checked-in helix goldens are the ground truth, verified
case-by-case by `zig build hxdiff`. Motion-created ranges live in
`pane.vsel` marked IMPLICIT (`vsel.explicit = false`); `v` extend mode,
- `x`/`X` and `n`/`N` (the look-ring walk, `lookWalk`) set EXPLICIT ones.
+ `x`/`X` and search `n`/`N` set EXPLICIT ones.
`d`/`c`/`y`/`~`/… act on the active selection either
way — that is the point of the model. The pardes-specific chords
(normal-mode Enter look / Tab execute)
@@ -134,13 +134,14 @@ language-backend queries, and the shell pipe.
| `Space` (normal, body) | starts the pardes LEADER: a key path runs the same builtin words used by tags and the topbar. The main groups are `f` files, `h` docs, `c` columns, `t` toggles/effects, `a` panel animations, `s` session, `j` jumps, `l` language, and `w` directional focus; `SPC ?` lists every path and `<prefix> ?` lists one group in `+Help`. Neither `Exit` (quits the editor, acme's Exit) nor `Kill` (stops the commands pardes typed into terminals, acme's Kill) has a leader path: both are the topbar's and the root `ctl`'s. The pending path appears on the active pane's transient body/message row. Esc or an unmapped key abandons it. Paths, Help rows, and dispatch are all generated from the builtin registry at comptime; the leader applies only to a BODY in normal mode because tags and tty programs own their input | pardes-specific; helix spends Space on pickers/LSP (section C), while pardes uses acme-style executable words |
| `SPC y` `SPC Y` `SPC p` `SPC P` `SPC R` | helix's clipboard menu on helix's own letters: yank the selection to the system clipboard (`ClipYank`) or the PRIMARY selection alone (`ClipYankMain`), paste the system clipboard after (`ClipPaste`) / before (`ClipPasteBefore`) the selection, replace the selection with it (`ClipReplace`) | the same as `"+y`, `"+p`, `"+P`, `"+R`: register `+` (and `*`) IS the desktop's clipboard, the only register that reaches it. `SPC y` writes `+` alone, as helix's does, not the default register too. Builtins rather than bare chords because a leader path names a builtin: they land in Help's index and are executable words like every other verb. The clipboard holds one text, so N values go out joined by newlines, as helix sends them. On a tty the write is OSC 52 out and the READ is OSC 52 back, which many terminals refuse or gate — so `SPC y` works there and `SPC p` can be a no-op | out of corpus |
| a paste from the OUTER terminal | one `Event.paste`, spliced in at the cursor | the tty shell enables bracketed paste and coalesces `paste_start`..`paste_end` into a single event; before that the bytes arrived as individual key presses and normal mode RAN them, which is how a pasted `d` deleted a line. The bytes deliberately never enter the yank register — clipboard and default register are separate stores in both directions | pardes-specific |
-| `/` (any pane) | pardes' own plain-substring search into a `+Search` output buffer: the pattern is typed on a line of its own on the pane's notice band, Enter fills the buffer, and its rows are ordinary look targets. Enter also GOES to the first row — the buffer is focused and then the step `n` is and the look Enter is run in it (`Pardes.lookFirstHit`), so `/foo` lands on the first hit with the matched span selected. A pattern that matched nothing opens its empty buffer and moves nothing | KEEP, do not touch; not in the corpus (helix `/` is regex search). Find and Grep answer with OTHER files and deliberately do NOT jump. The stepping half is the next row | pardes-specific |
-| `n` / `N` (any pane) | MOTION, not a jump: move the SELECTION to the next / previous look-able text and open NOTHING. Enter — the look chord — on what it leaves selected is what opens it | KEEP, do not touch; not in the corpus (helix's `n`/`N` walk regex search hits). What a step selects is the pane's GRAIN (`output_pane.Grain`, read in `Pardes.lookSpanIn`): in FREE TEXT — a terminal, a file, a PDF, a prose answer buffer — the largest whitespace-delimited run `look.resolve` can act on (`look.lookableSpan`, wrapper punctuation peeled off both ends), several to a line; in a RESULTS BUFFER one stop per ROW, the largest run its head resolves as (`look.lookableLineSpan`), because a row there IS one location and the words after it are the match rather than a second place to go; in a COMMAND list the whole line. The walk is a RING across PANES: every pane that has performed a Look, most recent first (`Pardes.look_src`), then the output buffers that have not, newest first, and only when both are empty the active pane. Exhausting a pane enters the next at its first (forward) / last (backward) span and the end wraps to the start, so `N` is the exact inverse of `n`. What it lands on becomes an EXPLICIT `vsel` with the cursor on its FIRST column, in the pane the walk focuses. ONE motion in every pane kind and every buffer kind — a PDF steps the `+Search` buffer its own search filled, `n` to select the row and Enter to jump. The single thing a buffer may change is that grain, and it changes it by BEING a kind of buffer rather than by a branch: `output_pane.Traits.steps` (a list of locations) makes a step take one row at a time, and `Traits.commands` makes it take the WHOLE LINE, because a command list (`Themes`/`Fonts`) holds words to run and there is no path inside `Theme gruvbox` to pick out. Tab on what `n` selected wears the theme, which is the same middle click on the row is. `]d`/`[d` are helix's diagnostic motions, a different binding, and they do still jump to each diagnostic (`docs/typ/guide.typ`, Keys) | pardes-specific |
+| `/` (any pane) | pardes' own plain-substring search into a `+Search` output buffer: the pattern is typed on a line of its own on the pane's notice band, Enter fills the buffer, and its rows are ordinary look targets. Enter also goes to the first row using `Pardes.lookFirstHit`, so `/foo` lands on the first hit with the matched span selected. A pattern that matched nothing opens its empty buffer and moves nothing | kept as-is; not in the corpus (helix `/` is regex search). Find and Grep answer with other files and deliberately do not jump. `LookNext` / `LookPrev` select subsequent result rows | pardes-specific |
+| `n` / `N` | next / previous regex match in the current text, using the last search register; counts repeat and ends wrap | only the primary selection is replaced; in select mode each match is added and becomes primary. Named registers work. `*` sets the pattern from selections with word boundaries, `Alt-*` without. The former Look ring is `LookNext` / `LookPrev`, `SPC j n` / `SPC j p`. The change is bookmarked `pardes-nN-helix`; its predecessor is `pardes-nN-before-helix`. PDFs retain their location-result navigation | helix-verified |
+
| insert: printable text | file: real edit; terminal: typed run splice | | helix-verified (file) |
| insert: `Enter` | newline; keeps the current full indent levels and adds one 4-space logical tab when the text before the cursor ends in `(`, `[`, `{`, or `)` (including `})`) | plain lines match `insert_newline`; delimiter heuristic is pardes-specific | helix-verified (plain) / pardes-specific (delimiter) |
| insert: `Backspace` (+ `Shift-Backspace`) | delete prev char, joins lines at col 0; in a line's leading blanks, back to the previous 4-column indent stop (a whole unit when on one; a tab still goes alone) | matches `delete_char_backward` and its dedent; `Ctrl-h` alias in B | helix-verified |
| insert: `Up` `Down` `Left` `Right` | move cursor | matches helix's "not recommended" insert arrows | helix-verified |
-| `gd` `gD` `gy` `gi` `gr` | LSP definition / declaration / type-definition / implementation / references. ONE answer jumps straight there; several fill `+Search`, where n/N walk and Enter opens | in-process ZLS (`src/lsp/lsp_zls.zig`), `.zig` only — on a file the backend does not speak these do nothing at all, with no error row. Ctrl+left-click is the mouse spelling of `gd` | out of corpus |
+| `gd` `gD` `gy` `gi` `gr` | LSP definition / declaration / type-definition / implementation / references. One answer jumps straight there; several fill `+Search`, where `LookNext` / `LookPrev` walk and Enter opens | Ctrl+left-click is the mouse spelling of `gd`; language support depends on the configured backend | out of corpus |
| `]d` `[d` / `]D` `[D` | step the diagnostics list / go to its last or first; if no list is up, asking the backend for one is part of the press | | out of corpus |
| `=` | `format_selections` — writes a `- old` / `+ new` diff into `+Lsp` | deliberate divergence: the seam returns ROWS, not edits, so this SHOWS the formatting instead of applying it. Not in the corpus, so there is no waiver to name — the query leaves the core as an effect the headless harness has no shell to perform | out of corpus |
| `Ctrl-o` / `Ctrl-i` | jumplist back / forward (also Mouse4 / Mouse5 in SDL, macOS and web); successful navigation clears selections in both panes and places the cursor at the saved location; raw tty forwards both to the child — the `Back` / `Forward` builtins, also on `SPC j o` / `SPC j i`, with `SPC j l` rendering the stack as a buffer; a closed file's entry stays, marked `(closed)`, and a jump to it opens the file again at its place | helix binds both keys (`jump_backward` / `jump_forward`) but to a POSITION jumplist; pardes' stack is over panes and focus, so the keys agree and the semantics do not. `Ctrl-i` and Tab are the same byte under the legacy encoding; there Tab keeps meaning execute, and the pair only separates where the host speaks the kitty keyboard protocol | pardes-specific |
@@ -352,7 +353,7 @@ text.
| Key(s) | Helix behavior | Reason |
| --- | --- | --- |
-| `?`, `*`, `Alt-*` | rsearch / selection-as-pattern | search — pardes has its own `/` (plain substring into an output buffer, kept as-is) and an `n`/`N` that SELECTS the next look-able text instead of walking match hits; helix regex search machinery not wanted |
+| `?` | reverse search prompt | pardes keeps its own `/` plain substring search into an output buffer. `*`, `Alt-*` and search-repeat `n`/`N` are implemented and verified above |
| `Space` mode: `f F e . b j g G ' w c C Alt-c / ?` | pickers, global search, palette | pickers and the command palette do not exist here — but the KEY is taken: pardes' own leader runs the acme builtins (section A). Two halves of helix's space mode DO exist and are in section A: the clipboard menu (`<space>y Y p P R`, helix's letters on helix's leader) and the LSP menu, moved one prefix deeper to `SPC l k/r/a/h/s/S/d/D` because `d`, `k`, `s` and `h` were already pardes' most-pressed keys |
| Popup `Ctrl-u`/`Ctrl-d`, Completion menu, Signature help tables | LSP popups | LSP |
| Picker table (all rows), Prompt table (all rows) | picker / prompt internals | pickers — pardes' tag line is its own one-line editor |
@@ -364,7 +365,7 @@ text.
| `:` | command mode | side-effects/file-ops — pardes builtins live in the tag, and `:` is bound to focusing it (section A) |
| `gf` | goto file under selection | covered by pardes Enter-look |
| `Ctrl-z` | suspend | pardes IS the terminal multiplexer |
-| Select/extend mode section (prose) | `v` turns all motions into extenders, `n`/`N` keep selections | implemented for motions (phase 5: `pane.select` + the fixed anchor, differential-verified — see the `v` row in A); helix's search-`n`/`N` extension doesn't apply (pardes' `n`/`N` is the look-ring motion, which REPLACES the selection with the span it lands on) |
+| Select/extend mode section (prose) | `v` turns all motions into extenders, `n`/`N` keep selections | implemented for motions (phase 5: `pane.select` + the fixed anchor, differential-verified — see the `v` row in A); search `n`/`N` add matches in select mode, as in helix |
## Differential testing (phase 5)
@@ -421,9 +422,9 @@ Files (all in `test/hxcases/`):
of the command from helix's own text there, so a later step is still
tested when an earlier one misses. The goldens are
`hx-harness test/hxcases/golf.jsonl`; `zig build hxgolf` runs them.
- `golf-waivers.jsonl` pins the seven `reverse_golf_example` steps from `""N`
- on: they walk the search register with `*`, `N` and `n`, which in pardes
- are the acme look ring, by decision. All ten examples reproduce their published result in hx 25.07.1 under
+ `golf-waivers.jsonl` is empty: all 124 cases pass, including the
+ search-register steps of `reverse_golf_example`. All ten examples
+ reproduce their published result in hx 25.07.1 under
the site's own conditions (a file of the example's language, auto-pairs
on). Under the harness two do not, and their goldens are the harness's
anyway, which pardes follows: `csv_to_sql` needs auto-pairs (off in the
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 89323766..55f8a4f0 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -167,7 +167,7 @@ the #word("Look") came from, then of each pane on the jump list, most
recent first.
#pairs(
- [#key("/") `TODO` #key("Enter")], [a `+Search` of the lines holding `TODO`, the cursor on the first; #keys("n", "N") step through],
+ [#key("/") `TODO` #key("Enter")], [a `+Search` of the lines holding `TODO`, the cursor on the first; #keys("n", "N") select the next or previous match],
[#word("Find") `conf`], [a `+Search` of the files below the pane's directory with `conf` in their names],
[#word("Grep") `TODO`], [a `+Search` of the lines holding `TODO`, literally, under every pane's directory],
)
@@ -213,7 +213,7 @@ is drawn as a diff, each hunk in its file's language. #btn("B3") on:
A `.diff` or `.patch` looked at, and a diff paged (`git show`), opens as
a `+Diff`, stacked as delta shows one: each hunk under its `path:line`
-(`n`/`N` step through them, #btn("B3") opens it) and the declarations
+(`Space j n`/`Space j p` step through them, #btn("B3") opens it) and the declarations
around it, a `+`/`-` before each line, the words a changed line changed
tinted and a line added or removed whole faintly. A mailed patch keeps its
message and diffstat above. The files are found from the diff's directory
@@ -241,7 +241,8 @@ refusals and `--nested` are in the reference.
[#key("w") #key("d")], [select a word, delete it: motions select, edits act on the selection],
[#key("x"), #key("v"), #key(";")], [select the line; extend; collapse to the cursor],
[#key("s")], [a cursor per regex match; every edit acts at each],
- [#key("/"), #keys("n", "N")], [substring search; step through everything #word("Look") would open, across panes],
+ [#key("/"), #keys("n", "N")], [substring search; repeat the search in the current text, wrapping at the ends],
+ [#keys("Space j n", "Space j p")], [#word("LookNext") / #word("LookPrev"): select locations across panes; #key("Enter") opens one],
[#key("g l")], [line end],
[`12G`], [line 12; a bare #key("G") does nothing],
[#key("SPC ?")], [#word("Help"): every builtin, with its leader path and keys; `SPC w ?` only the paths under `SPC w`; #word("Tutor") (#key("SPC h t")) practises them],