summaryrefslogtreecommitdiff
path: root/docs/next-searchrows.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-30 17:35:06 -0300
committerGabriel Schneider <[email protected]>2026-10-30 17:35:06 -0300
commit6d8da8721141284cf33bb901168b26135893eb86 (patch)
tree791d63401d4e85fbca1d597a8ce0326e70efd545 /docs/next-searchrows.md
parentefd43a3a2cf03bb741366331158b368abf9ac583 (diff)
parentbf6810a8f9d6cc82050e7d9c0cfb06358301b574 (diff)
downloadpardes-6d8da8721141284cf33bb901168b26135893eb86.tar.gz
pardes-6d8da8721141284cf33bb901168b26135893eb86.zip
Merge latest upstream into the macOS branch for Zig 0.17
Retain the macOS branch history and local Acme selection color while adopting upstream's current core and platform changes. Pin Zig and ZLS to 0.17.0, and fetch the existing zstbi compatibility commit through upstream after its original fork was removed.
Diffstat (limited to 'docs/next-searchrows.md')
-rw-r--r--docs/next-searchrows.md89
1 files changed, 89 insertions, 0 deletions
diff --git a/docs/next-searchrows.md b/docs/next-searchrows.md
new file mode 100644
index 00000000..79ffc444
--- /dev/null
+++ b/docs/next-searchrows.md
@@ -0,0 +1,89 @@
+# searchrows: query rows that are addresses, coloured as their files
+
+The author's ask (2026-10-25): the search results "should show Lookable
+locations for the matches, and it should highlight the near text on the
+preview/result pane", then "using treesitter for the highlight I mean",
+then on the row format: "the row can be just path:line:row but the path
+should be minimal i.e. it should be the smallest one that doesn't refer to
+panes like @p1 but that resolves a Look". Change `tsyvmpux`, on
+`zmluwpuv`. Positions, not a verdict.
+
+## The row
+
+ Places.zig:163:8 pub fn firstFrom(hits: []const Hit, at: usize) usize {
+ Places.zig:237:19 const i = firstFrom(set.hits.items, at);
+ ../shade.zig:1:11 pub const Shade = enum {
+
+- `path:line:col`, then the line's code from its first non-blank: plain
+ text, so B3 anywhere 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.
+- The path is `Query.lookPath(buf, path, dir)`: the shortest text a Look
+ from the query pane resolves: relative to the pane's directory (`x`,
+ `sub/x`, `../x`) when strictly shorter, else absolute. A relative name a
+ Look would read as something else (`@p...`, `://`) stays absolute. One
+ function, used by every hit row and by the file and declaration headers
+ of Grep, `/`/All and the language server lists.
+- On every row, `/` in the owner 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.
+- A group's code starts in one column: the address padded to
+ `path + ':' + digits(longest line in the group) + ':' + 3`, then two
+ spaces (a column of four digits or more pushes its own row one cell).
+- Declaration headers carry `path:line` in the same column; file headers
+ stay the bare path (itself a Look).
+
+## Colours
+
+- Rows: `Stream.paintRows` paints a whole file on the worker
+ (`syntax.highlightApart`, the same call as the anim paint-ahead): the text
+ of the pane that shows it, else read from disk there. It lands in the
+ locations cache beside Callstack's (`locations.Cache.put`); 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 rows are
+ plain; on arrival `Query.recolor` colours every query pane's plain rows
+ in place and asks for the next file: one at a time, each (path, revision)
+ once a Grep (a 256 ring). The match tint (`decorateRow`) sits on top, its
+ position past the address (`code_start`). Not on the loop, not in a 9P
+ write (asked again on the next step), not without workers.
+- The +Preview: colours are its own pane's (painted as any file pane), and
+ the query's hits in that file are its places (`Places.search` literal for
+ a Grep, `Places.feed` from the rows for a list), tinted and ticked, the
+ current row's one current and selected, centred. A pane that already
+ shows the file gets the same (`selectPlace`).
+
+## Numbers
+
+`zz grep rows timings` (src/Stream.zig, `GREP_TIMES=<path>`): Debug, a
+TestShell worker, 160x50, the stress file (src/layout.zig x17, 1.22 MB,
+29002 lines), typing `pane` three times with 400 ms of frames after each
+key, then Enter on 2000 rows. Load 2.4-3.0 before, 2.7-2.8 after; after is
+three runs.
+
+| frame work | before | after |
+|---|---|---|
+| keystroke (update + render) p50 / p90 / max | 2.2 / 4.2 / 6.0 ms | 2.0-2.1 / 2.9-6.5 / 4.4-6.7 ms |
+| refill frame (rows remade) p50 / p90 / max | 4.4 / 5.2 / 5.2 ms | 4.8-5.1 / 5.4-6.1 / 5.4-6.1 ms |
+| other frames p50 / p90 / max | 0.9 / 1.3 / 10.6 ms | 0.9 / 1.2-1.3 / 10.0-10.2 ms |
+| Enter (2000 rows written) | 27.0 ms | 28.2-28.7 ms |
+| frames after Enter p50 / max | 0.9 / 1.7 ms | 0.9 / 1.3-1.7 ms |
+
+Rows coloured after Enter: 1718 of 2000; the other 282 are plain in the
+file's own colours too (checked against `highlightApart` of the file). A
+refill costs ~0.4 ms more (the wider rows and the Shades walk), inside the
+noise of the keystroke column; the paint itself never shows on the loop.
+
+## Pushback and rough edges
+
+- The current row's address is barely legible: the address's dim location
+ colour on the current row's mark tint (visible in the screenshot). The
+ thing B3 aims at should read; a brighter location fg on the marked row is
+ a one-line theme decision I left to you.
+- A text with no file (a +New scratch) has no path any Look resolves, so
+ its `/` rows keep `@pN`, the only address that works there.
+- `lsprelpath` asserted the opposite policy ("must NOT become
+ `../shade.zig`"); the author's shortest-path rule wins, the script says so.
+- Rows of a file over 4 MB, and of markdown/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.
+- One file painted at a time: a Grep over hundreds of files colours file
+ by file (each lands in a frame); a worker per file if that is slow.