SDK: surface text-search match snippets/positions from Find/FindPage

[hk9890]

Motivation

Find / FindPage / List return matched issues but no information about why a text ~ "..." query matched. UIs that render search results have nothing to highlight.

Concretely, beads-workbench's search results carry a Snippet field that is currently always empty, because the SDK exposes no match context — only the matched *Issue.

Proposal (additive, optional)

For text (text ~) searches, optionally surface per-result match context — e.g. a short snippet around the match, or match field + byte offsets — so consumers can render highlights. Possible shapes:

• a new optional method/return (e.g. FindPage returning results with an optional Snippet/Matches alongside each issue), or
• a helper that, given an issue + query text, returns the snippet (keeps Find unchanged).

Low priority / nice-to-have — purely additive; no behavior change for existing callers.

[hk9890]

Findings from code investigation

Confirmed this is valid but more invasive than the additive framing suggests, because of two facts in the current evaluator:

1. The evaluator is boolean-only. Predicate.Match(row Row) bool (internal/query/eval.go:67) and evalTextField (eval.go:238-255) compute the match and immediately discard position:

return strings.Contains(strings.ToLower(fv.S), strings.ToLower(sv.S))

There is no plumbing for "where did it match" — surfacing a snippet means either a new match-collecting pass or threading match context through the Predicate interface.

2. The "text" field is a pre-concatenated blob. The Row adapter (query.go) hands the evaluator one concatenated searchable string (title + body + comments). So a raw byte offset into that blob does not map back to a specific field without extra structure — highlighting "which field matched" needs more than an offset.

Two design shapes (matching the proposal)

• Standalone helper — Snippet(issue, queryText) string that recomputes context on demand. Leaves Find / FindPage / Match untouched; the consumer (beads-workbench) calls it per result. Lowest blast radius — recommended starting point.
• Threaded match context — FindPage results carry Snippet / Matches. Touches the Predicate interface (or adds a parallel match pass) and forces a decision on the concatenated-blob → originating-field mapping.

Recommendation

Start with the standalone helper; it unblocks beads-workbench's empty Snippet field with no behavior change for existing callers. Only thread context through FindPage if/when highlighting needs to know the originating field (title vs body vs comment), which the current concatenated representation can't express.

Correctly labelled low-priority. Independent of #21/#22 (just fixed in #24); this one needs a small design decision before implementation.