summaryrefslogtreecommitdiff
path: root/docs/search-proto-converge.md
blob: 7a3e361ac47601f2f0a178c0df76d5083be3f1c1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
# 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 <line 1>` 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.