1 files changed, 45 insertions, 0 deletions
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.