summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/search-proto-converge.md183
1 files changed, 183 insertions, 0 deletions
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 <line 1>` 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.