Search the scrollback without turning it into text

[JohnCampionJr]

No longer stacked — #45 merged and this is rebased down to the feature alone. Two commits, conflict-free against main, full suite green. Ready to review on its own.

Ghostty's most-requested feature until 1.3. The design note with the full reasoning is written up separately; the short version turns on one measurement.

The measurement

A 10,000-line scrollback at 240 columns, searched for error, both ways, same 25,325 hits:

approach	time	allocated
a string per line, then IndexOf	9.7 ms	16.3 MiB
codepoints read out of the cells	3.7 ms	0.0 MiB

A find box searches per keystroke, so the obvious implementation is ~80 MiB to type "error" — in a library that just spent #38 getting per-character allocation to zero. So BufferSearch walks cells and never builds a string.

What walking cells buys beyond the allocation

The offset-mapping problem dissolves. A string search returns character offsets that then have to be mapped back onto cells — wide characters, clusters, wraps. Here the position is the (row, column) cursor, and a match that crosses a wrap simply produces two runs because the cursor changed row part way through. The runs share a MatchId — the same shape as an OSC 8 link that wrapped — and TryMoveNext steps by match, so a wrapped one is one stop.

Logical lines, not physical. A search that stops at the right edge misses exactly the matches on long output, which are the ones worth finding.

Width-0 cells are stepped over, not compared. The placeholder behind a wide glyph and an orphaned combining mark aren't characters; comparing them would fail a needle against text that reads exactly like it.

Results that survive the buffer moving

The ring drops lines as output arrives, and a stale row index fails silently — the highlight just lands somewhere else. BufferSearch subscribes to Trimmed and shifts, as SelectionManager already does, dropping what fell off the top. There's a test that scrolls a match through a trim and checks the row it lands on still says needle.

Shaped for the renderer

HitsOnRow(row) answers by binary search over row-ordered hits and returns a span in place — asked once per row per frame, and the answer is almost always nothing. The cap (10,000 runs) is announced through Truncated rather than silently applied: a count that quietly stops being true reads as a bug in the search rather than a limit on it.

Deliberately no regex

Regex takes a string, so supporting it means materialising the buffer as text — the 16 MiB this design exists to avoid, and paid by every search rather than only the ones that asked. Substring, case-insensitive by default, whole-word as an option. If regex ever lands it should materialise one logical line at a time.

A measurement trap worth recording

This change's own zero-allocation test initially failed at 66 MB — against code that was allocating nothing. GC.GetTotalAllocatedBytes is process-wide and xUnit runs test classes in parallel, so it counted the rest of the suite's allocations on other threads against the search. GetAllocatedBytesForCurrentThread cannot be polluted. Filed here because it's the same trap anyone adding an allocation assertion to this suite will hit.

Tests

1191 pass, thirteen new: wrap-straddling matches, whole-word across a wrap, ring trimming, the cap admitting it bit, and the zero-allocation claim asserted per thread.

The renderer half — highlight in the render path, scroll-to-match, find-next forwarded to the control — is already written as Iciclecreek#88, and follows once this merges and a prerelease carries it. The terminal-side PRs deliberately come after the emulator ones: they cannot compile until the package exists.

🤖 Generated with Claude Code

[JohnCampionJr]

The compare failure was real, and it was not this PR — it was #45 underneath, and the gate did exactly what it was calibrated to do.

alt-redraw at +6.0% against a 6.0% gate, ±2% noise. The cause: NoteLink carried a remark saying "guarded at the CALL as well as inside" — and the three call sites were bare. The guard lived only inside the helper, so every printed character and every batched chunk paid a call to be told there is no link and never has been. The exact unguarded-call shape that cost alt-redraw 12% in the placeholder work, caught this time by CI instead of by hand.

Fixed in 40da2d4 on #45 and merged through: the three writers test _linkUrl is not null || line.HasLinks themselves, and the helper is gone — three guarded call sites plus a helper whose comment lied is worse than no helper. 1191 tests unchanged; compare re-running on the push.

[JohnCampionJr]

some stacking here, sorry about that. should be the last time. this is the last of what I wanted to land.

[Copilot]

🟡 Changes recommended

Confirmed correctness issues in the new search and hyperlink-span maintenance logic need fixes before the new APIs can be relied on.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds scrollback searching that operates directly on buffer cells (avoiding per-line string materialization/allocation) and expands line-level state to anchor OSC 8 hyperlinks and OSC 133 shell-integration marks to BufferLines for stable hit-testing and prompt navigation.

Changes:

• Introduces BufferSearch (and SearchHit/SearchOptions) to find matches across logical (wrapped) lines without building strings.
• Anchors OSC 133 marks (LineMark) and OSC 8 hyperlink spans (LineHyperlink) to BufferLine, with print-path bookkeeping and prompt navigation helpers on Terminal.
• Adds comprehensive tests covering wrapping, trimming, caps/truncation, hyperlink/mark anchoring, and allocation assertions.

File summaries

File	Description
src/XTerm.NET/Terminal.cs	Adds prompt navigation helpers based on anchored OSC 133 marks.
src/XTerm.NET/Search/SearchTypes.cs	Adds search result and option types (SearchHit, SearchOptions).
src/XTerm.NET/Search/BufferSearch.cs	Implements allocation-free scrollback search over buffer cells.
src/XTerm.NET/InputHandler.cs	Anchors shell marks to lines and records hyperlink spans during printing.
src/XTerm.NET/Buffer/LineMark.cs	Defines line-anchored shell-integration mark structure.
src/XTerm.NET/Buffer/LineHyperlink.cs	Defines line-anchored hyperlink span structure.
src/XTerm.NET/Buffer/BufferLine.cs	Stores/updates marks and hyperlink spans on lines; clears on reuse.
src/XTerm.NET.Tests/ShellIntegrationMarkAnchorTests.cs	Tests mark anchoring and prompt navigation behavior.
src/XTerm.NET.Tests/HyperlinkAnchorTests.cs	Tests hyperlink span anchoring and mutation under overwrites.
src/XTerm.NET.Tests/BufferSearchTests.cs	Tests search behavior (wraps, stepping, trimming, cap, allocations).

Review details

Suppressed comments (1)

src/XTerm.NET/Search/BufferSearch.cs:332

• Whole-word boundary check on the "after" side doesn't skip width-0 placeholder cells, so a match that ends before a wide glyph's placeholder may see the placeholder as the next character and incorrectly treat it as a boundary.

        if (!Advance(lines, endRow, ref r, ref c, skipZeroWidth: false))
            return false;   // end of the logical line

• Files reviewed: 10/10 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.