Reuse bounded source analysis and speed up result context traversal

2 files changed, 48 insertions, 0 deletions

diff --git a/docs/config.md b/docs/config.md
index 6f3273b9..972f9403 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -177,6 +177,9 @@ depth (for example, `main.zig:42 ***`). Ordinary neighboring source lines retain
 syntax colors; declaration headers do not.
 A declaration context line ends with ` ...` when source lines are omitted
 before the next displayed row from that file.
+Source analysis is reused across result queries while the source bytes stay the
+same. The cache retains at most 64 files and 64 MiB; it checks current buffer or
+filesystem contents on each refresh.
 Open file buffers supply context from their current edits. Missing files still
 leave the original result available. These settings apply to subsequent result
 generation and survive `Dump`/`Restore`. Invalid fields reject the entire
diff --git a/docs/locations-performance.md b/docs/locations-performance.md
new file mode 100644
index 00000000..32ee08bd
--- /dev/null
+++ b/docs/locations-performance.md
@@ -0,0 +1,45 @@
+# Location results performance
+
+Run `zig build locations-bench -Doptimize=ReleaseFast` from the repository root.
+CSV measurements are written to stderr. The benchmark covers 100, 500 and
+1,500 matches, both layouts, and ordinary/tree-sitter context separately and
+together. Each configuration starts with an empty analysis cache and then
+repeats twice with unchanged source and producer results. There are no timing
+thresholds in the tests.
+
+The fixtures are open, unsaved Zig buffers: one module containing functions
+with 20 local declarations and one match per function. The largest is
+1,813,921 bytes. Timings cover `Output.fillResults`, including sorting,
+formatting, metadata and refresh comparison. Source generation, input
+allocation, filesystem I/O, subprocess startup and GUI drawing are excluded.
+
+## Measurement on September 15, 2026
+
+Milliseconds for 1,500 matches on the development Linux machine:
+
+| Layout / context | Before optimization, repeated | After, cold | After, warm repeats |
+| --- | ---: | ---: | ---: |
+| Inline / declaration headers | 1,259 | 224 | 2.32 / 2.14 |
+| Inline / headers and two neighboring lines | 1,250 | 291 | 4.80 / 4.66 |
+| Stacked / declaration headers | — | 224 | 2.04 / 1.88 |
+| Stacked / headers and two neighboring lines | — | 294 | 3.92 / 3.65 |
+
+The before figures are medians of three runs of the same fixture with the
+previous parser/traversal path. After figures are one cold and two warm
+samples from the repository benchmark. Stacked layout has no before figure.
+These are focused formatter measurements, not end-to-end GUI latency promises.
+
+## Changes
+
+- Declaration traversal uses a tree cursor that retains its ancestor stack.
+- Declarations and ordinary-context colors share a single parse.
+- Muted declaration headers do not request unused source colors.
+- Exact source snapshots cache complete analysis across queries. Unsaved
+  buffers take precedence; filesystem sources are reread to detect changes.
+- The cache retains at most 64 entries and 64 MiB, evicting the least recently
+  used entry. Oversized analysis is used for the current result without being
+  retained. Pending context owns its selected color bytes so later eviction
+  cannot invalidate rows already collected.
+
+Cold parsing remains proportional to source size. Unchanged refreshes still
+read/compare source bytes and assemble results, but skip parsing and analysis.