From 9299281492d63e549ab274034efb59ab4e9d96f6 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Sat, 24 Oct 2026 13:11:11 -0300 Subject: Search converge 6/6: SearchPlace column, the finder column at the right edge holding the query panes; n/N in a frozen query pane; the design doc --- docs/search-proto-converge.md | 183 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 docs/search-proto-converge.md (limited to 'docs') diff --git a/docs/search-proto-converge.md b/docs/search-proto-converge.md new file mode 100644 index 00000000..4c7b7006 --- /dev/null +++ b/docs/search-proto-converge.md @@ -0,0 +1,183 @@ +# 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**: a gutter line number, the hit's line with +the match tinted (every match on a line tinted, one row a line), under the +declaration it is in (once a parse exists, see below), under the file +(Grep, the LSP lists), under `@pN name (count)` in serial order (All). +B3 on a row's line number looks at its address; B3 on its code is a word +Look as anywhere; 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). + +**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, +Enter on a row lands on it. 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. + +**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. Never the pointer. + +**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). +- Grep rows carry no syntax colours; `/` rows are coloured where the + owner's highlights cover them (zeros elsewhere, so no fragment parse per + refill). +- 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. -- cgit v1.3