# Search, converged: the query pane The design the twelve prototypes added up to (CONVERGE.md), built as the product in six changes. One pane kind does all searching: the **query pane**, a `+Search` attached under the pane that asked (its *owner*), whose body's line 1 is the query, typed into, and whose rows below are made live from a source. The owner shows the set in its own text (its **places**: tints, rail ticks, the current one selected), and a row that points at a file no pane shows is shown in a **+Preview** attached under the query pane. Everything on screen is text in a pane: B1/B2/B3 and the chords work on all of it, nothing is drawn over anything, and the notice band keeps only the prompts that are not search. ## The pieces, and where they came from | piece | file | lifted from | |---|---|---| | attached panes: a group under its owner, rows from the owner alone, moving/folding/closing with it, seam drag, Dump/Restore, `Unattach` | `src/layout.zig` "Attached panes", `Pane.attached_to` | attached | | places: every match tinted, rail ticks (B1 on a tick goes there), current selected and in view, smart-case regex, view-first sliced scan, silent wrap | `src/Places.zig`, `Pane.places` | incsearch (MatchSet) | | the query pane: line 1, its first word the source, live rows, preview, Enter/Esc/Del, reuse, settings | `src/Query.zig`, `Pane.query` | queryline, pick, live, preview, everywhere | | fuzzy names (files, recent, panes, declarations) | `src/Names.zig` | pick (its scorer, whole) | | the disk engine: Grep and Find's listing on a worker, rg or the walk, generations, debounce, cap + `More`; and the declarations parse | `src/Stream.zig`, `Pardes.stream` | stream | | the finder column (`SearchPlace column`) | `src/Finder.zig`, `Pardes.finder` | column | ## Semantics **Line 1's first word names the source**; editing it changes the source. | line 1 | searches | keys | |---|---|---| | `/pat` | the owner's text, a regex, any case unless a capital | `/`, `*` (keyboard stays) | | `Find name` | the files below the pane's directory, fuzzy | `SPC f f`, `Find` | | `Grep text` | their lines, literally, smart case | `SPC f g`, `Grep` | | `Recent name` | the files opened lately, fuzzy | `SPC f r`, `Recent` | | `Panes name` | the open panes, fuzzy | `SPC b b`, `Panes` | | `Symbols name` | the owner's declarations, fuzzy | `SPC s s` | | `All pat` | every open pane's text, rows under `@pN name (count)` | `SPC /` | | `Refs`, `Def`, `Impl`, `Diagnostics` | the language server's lists | `gr`, `gd`, `gi`, `]d`, ... | `Search ` is the builtin under the three argument paths (`config.leader_args`, pick's table). **Rows look like Callstack's**: each row's place first, as text, `path:line:col`, the path the shortest a Look from the query pane resolves (relative to its directory, `../` included, when that is shorter, else absolute; `Query.lookPath`), never an `@pN` but for a text with no file, padded so a group's code starts in one column, then the hit's line coloured as its file's language colours it, the match tinted over that (every match on a line tinted, one row a line); under the declaration it is in (once a parse exists, see below; the header has its `path:line` too), under the file (Grep, the LSP lists), under `@pN name (count)` in serial order (All). B3 on the address is a Look as anywhere, a sweep copies it, and a frozen pane saved is a list of addresses that still work; B3 on its code is a word Look; B2 on line 1 runs it again. The pane has no gutter of its own, and its rows are read-only while live (queryline's clampEdit). The address is on every row, `/`'s included: a bare `:12:5` would be looked up in the +Search itself (a Look resolves against the pane it is in), and a saved list would lose its file. The rows' colours are their files' whole (`Stream.paintRows`): a file is painted once on the worker (`syntax.highlightApart`, the text of the pane that shows it, else read there from disk), kept in the locations cache beside Callstack's, and each row takes its line's slice when the line still reads as the row does (`Query.Shades`, one walk down each file a refill). Until then the rows are plain; when a file lands, every query pane's plain rows from it are coloured in place (`Query.recolor`), which asks for the next file, one at a time. Without workers (tests) the rows stay plain. **The +Preview is the file as its own pane shows it**: its colours are the file's (`colorAlgo` `.source`, painted ahead as any pane), and the query's hits in it are its places (a Grep's searched there as in an open pane, a list's fed from its rows), tinted and ticked, the current row's one current and selected, centred with its neighbours round it. A pane that already shows the file gets the same: its places, the row's one selected. **Keys** on line 1, typing: Ctrl-n / Ctrl-p (and Down / Up, `config.query_next` / `query_prev`) step the current row; Enter lands; Esc cancels. Tab stays the exec chord. In the pane's normal mode (live or frozen): n / N step its rows (the caret with them when it is on them), j / k onto a row make it current, Enter lands the current row. In the owner: n / N step its places, round the end without a word; with no places (or after an `s` changed the register) they are helix's register search as before. `]d` / `[d` step the diagnostics' places once a Diagnostics query fed them. **A language server's list is answered, not typed.** `gd`, `gr`, `gi` and `SPC l d` ask; the answer decides: one place is a jump (the keyboard on it, the place that text's places, so it is tinted and n/N have it; no query pane); several open the query pane with its rows there and the keyboard in its normal mode on the current row (the first after where it was asked), its target shown, so j/k/n/N step, Enter lands and Esc goes back to the text as it was; none is a message. Line 1 reads `Refs` as text (B2 asks again; editing it to `/x` works), but no language key puts the keyboard there in insert mode. Diagnostics keep the keyboard in the text so `]d`/`[d` step their places. `Symbols` (`SPC s s`) is fuzzy, typed into: a query. **The current row shows its target**, the keyboard staying on line 1: a place in an open pane's text is selected there and scrolled into view (remembered for Esc); a file an open pane shows, its line there; any other file in the +Preview. Only the keyboard moves it: Ctrl-n / Ctrl-p on line 1, n / N in the pane's normal mode, and j / k taking the caret onto a row (a helix picker's preview follows its selection the same way). The mouse never does: B1 (a click, a sweep, the chords) places the caret and selects as in any pane, no other pane moves, nothing is previewed; B3 on a row's address is a Look as anywhere, on its code a word Look; B2 on line 1 runs it again. Enter lands the current row, which is the caret's once j / k put it there, never a row B1 only clicked; Callstack has no current row apart from its caret, so the two agree except after a click. The current row's mark is its own, a row tint drawn from the current row under the match's tint (`Query.paintMark`), no selection: a click, a sweep or a chord never erases it and B2 / B3 on it take the word clicked, as on any row. **Enter** puts the keyboard on the current hit in its pane (the +Preview promoted in place: same slot, serial, rect, an unattached file pane from then on), fills `/`, and freezes the rows into ordinary text (tag ` Save Unattach Del`). A `/` freezes its whole list (every place found first, 2000 rows at most), a Grep every line it has. **Esc** while typing puts every view back, clears the places it fed and closes the pane, its rows back to the owner; a reused pane's frozen rows and their places come back instead. **Del** closes it; closing the owner closes its group. **Nothing moves while you type.** The pane is born at tag + 1 + `SearchRows` (8) rows out of the owner's rows alone, with its +Preview when the source can preview (the owner's spare rows split between the two if it is short); it never resizes, closes or rewrites line 1 by itself, and while typed line 1 never scrolls away (the live rows start two places before the current one, so it sits under line 1). Zero hits is `0` in the tag. A preview made later (line 1's word edited to a source that previews) takes rows from the query pane's own bottom, so line 1 stays put; a reused pane gets its preview at the key that asked. **Settings**: `SearchPlace attached|column`, `SearchPane reuse|new`, `SearchRows N` (1-100). ## Storyboards Text: `/` in the 1.2 MB stress file (playground `src/layout.zig` x23), cursor on line 15000. | step | the screen | |---|---| | `/` | A `+Search` opens under layout.zig, taking 10 of its rows; line 1 reads `/`, the caret after it in insert mode; tag `^ +Search 0 Del`. Nothing else moves. | | keystroke 1, `p` | Every `p` in the view tinted at once, the rest found a 4 ms slice a frame (the tag `1/38479+` until done); rail ticks fill in; the first `p` at or after the cursor selected in layout.zig (scrolled only if off screen). Rows: the lines holding `p`, each ` 15003 code`, from two before the current one, the current marked as the visited row, a note row above saying how many places come before them. | | keystroke 2, `a` | `pa`: tints, ticks and rows narrow (`1/10189`); the current is again the first at or after where `/` was pressed, not after the last preview. The pane is the same size, line 1 where it was. | | Ctrl-n / Ctrl-p | The next / previous `pa` current, selected in layout.zig; `2/10189`. | | Enter | The keyboard on that `pa`, `pa` in `/`, the rows frozen (the whole list, 2000 rows), tag `+Search 2/10189 Save Unattach Del`; tints and ticks stay while the pane lives. Ctrl-o goes back to where `/` was pressed. | | `n` | The next `pa` in layout.zig, `3/10189`, its row marked in the +Search. | | `N` | Back to `2/10189`; from the first, round to the last with no message. | | Esc (typing) | layout.zig's selection and scroll exactly as at `/`, tints and ticks gone, the +Search closed, its rows back to layout.zig. | Files: `SPC f f` from the playground's README.md, whose directory is the playground's root (the snapshot `find.snap` runs the same steps). | step | the screen | |---|---| | `SPC f f` | The query pane under the pane with its +Preview under it, both out of that pane's rows; line 1 `Find `; the 15 files below the directory listed at once (rg `--files` on the worker; dot-files like `.fill-section.py` and .gitignore'd ones passed over), the first current; tag `1/15`. | | keystroke 1, `l` | The names scored fuzzily (pick's scorer: segment starts, basename, camel humps), best first, the matched letters tinted: `src/layout.zig`, `src/locations.zig`, `open-all.sh`, `notes/helix-keys.md`, ...; the best current, its head in the +Preview; tag `1/7`. | | keystroke 2, `a` | `la`: `src/layout.zig`, `src/locations.zig`; tag `1/2`, layout.zig's head in the preview. Nothing moves. | | Ctrl-n / Ctrl-p | `src/locations.zig` current, its head in the preview. | | Enter | The preview becomes `src/locations.zig`'s pane where it stands (same rect and serial); the list frozen above it. | | `n` / `N` | In the query pane: the next / previous name current, shown in a new preview under it (or in its pane when open). In the opened file: helix's register search (a list of names has no places in a text). | | Esc (typing) | The query pane and its preview closed, their rows back to the pane that asked; nothing opened. | Grep is Find's twin with rows under each file's name, run once the typing pauses (80 ms), stopping at 2000 lines with `More` in the tag; hits in an open file are that pane's places (n/N there). ## Numbers Debug build (what the playground runs), 160x50, each step `update` + a full render, machine load ~3. Unit tests `zz query timings` / `zz stream timings` / `places: a big file...` (run with QUERY_TIMES / PLACES_TIMES). | what | cost | |---|---| | a cursor move and its frame, no search (baseline) | 0.70 ms | | `/` opens | 1.05 ms | | a keystroke of `/pane.v` (38 479 -> 276 places) | 3.0-3.5 ms | | the ticks after it (7-11 of them, scan slice + rows every third) | worst 6.8-7.3 ms | | an edit in the owner with the frozen pane open (insert `x` + a tick) | 8.3 ms mean, 10.9 worst | | the same edit with no search | 7.5 ms | | places' share of an edit on 1.9 MB (one-splice shift) | 0.44 ms | | the declarations parse of the 1.2 MB file, on the worker | 474 ms, off the loop; worst frame meanwhile 7.5 ms | | a keystroke once the rows are grouped under declarations | 4.4 ms | | Grep race test: 2 engines x 12 rounds, a rogue thread pushing the stale generation | every round only B's lines land | So the search costs a keystroke ~2.5 ms over a plain frame and an edit ~0.8 ms, in Debug. Three fixes the numbers forced: `Text.primaryRange` counted lines from the top for a selection's anchor on every call (18% of a run; now through the line index, which also took the editor's own insert-mode key on this file from 11.5 to 7.1 ms); live rows are a window of 100 (the Debug SafeAllocator's stack capture per allocation was 30% at 1000 rows); the keystroke scans only the view. ## What differs from CONVERGE, and why - **Declaration grouping is the worker's.** A tree-sitter parse of the stress file is 4.8 s in Debug and the owner's "existing tree" exists only with TreeContext on. The parse runs on the disk engine's worker with a parser of its own (`syntax.declarationsApart`, cancellable through tree-sitter's progress callback) and lands in the pane's `context_declarations` (what sticky headers read); rows stay ungrouped until then (live's trick). Without workers (tests) only texts under 64 KB are parsed, on the loop. - **Places shift on an edit** instead of being found again view-first: `File.State.splice` records each edit's span, and the places before it stay, those after move, only the touched lines are searched again. - **Grep is literal** (smart case): rg's regex dialect is not mvzr's sam rules (stream's call). `/` and All are regex. - **All** follows the open panes (selection and scroll, put back on Esc) rather than previewing a pane that is on screen anyway. - **Terminals keep the band `/`**, as PDFs do: a terminal's text is no `File`, and places need one. - **A list's places feed every open file its rows land in**, not only the owner (Refs in main.rs, asked from lib.rs: n/N in main.rs step them). - **The live rows are a window**: 100 rows from two before the current place; the whole list on Enter. - A dumped query pane restores as a plain +Search, and a dumped finder column as a plain column. ## Rough - LookNext / LookPrev do not step query rows (their addresses are in row metadata, not text). - Rows of a file bigger than 4 MB, of markdown and typst (their injections share parsers, so no worker paints them) stay plain; a disk file changed after it was painted keeps plain rows for its changed lines until the next Grep. - Rail ticks are not carried over the detached wire (a detached frontend shows tints, not ticks). - In a window too short for the group (4 rows), only the query pane's tag shows. - The finder column keeps 8 query panes; older ones close.