explorer: two-button search semantics (closes #178, Light path)

[rdhyee]

Summary

Light path of #178 — Hana's mockup feedback for the Interactive Explorer (discussed in 2026-05-08 tech call). Replaces the single "Search" button with two scope buttons:

• Search Selected Areas (orange) — limits results to samples whose lat/lng falls in the current camera view rectangle.
• Search Entire World (blue) — runs the existing full-corpus search.

Backend stays option C (per EXPLORER_STATE.md §6) — search is still side-panel + result-pin overlay; cluster layer and facet counts are unaffected. Heavy revisit (full A/B/C rethink) explicitly deferred per #178.

Verified locally

Manual browser eyeball check at `http://localhost:5880/explorer.html?perf=1#v=1&lat=35&lng=33&alt=2000000\` (Cyprus camera position):

step	result
Page loads, two buttons visible, old `#searchBtn` removed	✓
Type `pottery` → click "Search Selected Areas"	URL becomes `?perf=1&search=pottery&search_scope=area`, search runs
Area-scoped result	0 results — verified natively that none of the top-50 `pottery` matches fall in lat 30-40 / lng 25-40
Camera stays at Cyprus (auto-fly suppressed)	✓
Click "Search Entire World"	URL drops `search_scope` param; 50+ results; camera flies to top-1 (Italy)
Perf panel row shows `search #N area: "pottery" (0) 4.02 s`	✓

The 0-result outcome from Cyprus is correct behavior per the contract — the area is genuinely too tight to contain any of the top-50 hits. Users widen by panning out, which the search-help and the second button signal.

Implementation notes

SQL shape: viewport predicate goes on the OUTER query (post-join), not the inner CTE, because lat/lng live in `samples_map_lite` not `sample_facets_v2`. This means area-scoped searches can return < 50 results when the inner top-50 don't all satisfy viewport. Acceptable v1 behavior. A future tuning could increase the inner LIMIT in area mode if data shows users hit this bound often.

Dateline-crossing: when `west > east` (camera over the international date line), the longitude predicate splits into two ranges:

```sql
AND (l.longitude BETWEEN ${west} AND 180
OR l.longitude BETWEEN -180 AND ${east})
```

URL persistence: `persistSearchScope()` is separate from `writeQueryState()` because the latter doesn't know about scope. `?search_scope=area` is written when area is chosen; deleted when world (default).

Auto-fly suppression: only `world` searches fly to the first result. `area` searches preserve the user's current camera — they're already where they want to be.

Enter key: uses the last-clicked scope, or URL-hydrated scope on cold boot. Defaults to `world` for keyboard-only first-time users.

Doc + tests

• EXPLORER_STATE.md §6: new "Light-path addendum" explains the two-button design as an extension of option C; Heavy revisit deferred until Explorer FTS Track 3: Offline index builder + tokenizer regression set #170-Explorer FTS Track 5: GO/NO-GO decision gate #172 land.
• `tests/test_search_perf.py`: new `area-scope` canonical query uses `url_hash` to set the camera before clicking `#searchAreaBtn`. `_run_search` takes a `scope` param routing to the right button.

Out of scope (other Hana mockup items, deferred)

Listed in #178: educational tooltips, vocabulary tree-selection, sample-type icons, accessibility halos, native Cesium control panel, table-always-visible. Each gets its own issue once Hana's "corrections coming" iteration lands.

Test plan

• Open Explorer, type a query, click both buttons. Verify URL updates correctly.
• At a global camera view, both buttons should return ~50 results.
• Zoomed in tightly, "Search Selected Areas" should return < 50 (or 0) depending on what's in view.
• `?perf=1` panel rows include scope label.
• Reload with `?search=foo&search_scope=area` — search runs in area mode on boot.

Closes #178. Refs #163, #165, #166, #177.

🤖 Generated with Claude Code

[rdhyee]

Review finding:

Medium: Search Selected Areas can return false zeroes because the viewport filter runs after the global top-50 limit. In explorer.qmd, the CTE ranks and limits 50 matches from sample_facets_v2 first, then the outer query joins coordinates and applies viewportPredicate. That means area mode only searches “current viewport among the global top 50,” not “top 50 within the current viewport.” For broad terms like pottery, this can show 0 results in a real area that has matches, simply because none of that area’s samples made the global top 50. This undercuts the button’s promise and reintroduces the false-zero problem the interim search work is trying to reduce.

The fix is to make area scope apply before the top-K selection. Since lat/lng live in samples_map_lite, area mode likely needs a separate query shape that joins lite inside the candidate CTE before ORDER BY ... LIMIT 50. If that is too slow, use an explicit larger candidate cap and document it as approximate, but the current exact-looking label is misleading.

Test gap: the perf harness adds an area-scope canonical query, but the committed tests/search_baseline_2026-05-08.json still has only the prior 9 labels. If the baseline artifact is meant to track the canonical query set, it should be rerun or explicitly left as historical pre-#179 data.

I did not run the full browser perf-smoke.

[rdhyee]

Round-2 fix (commit `cc79ec0`)

Codex was right — the previous shape had a real semantic bug. The viewport predicate ran AFTER the global top-50 selection, so "Search Selected Areas" was actually "current viewport among the global top 50," not "top 50 within the current viewport."

The bug was visible-in-the-wild: for `pottery` the global top-50 is dominated by one Alaska collection (label='Pottery AM662:...', all at lat=57.7 lng=-152.4). Any non-Alaska area-scope query for `pottery` would return zero — including the canonical Cyprus case the interim search work was built to fix.

Fix

Split into two SQL shapes (committed):

mode	shape
world	CTE over sample_facets_v2 → top-50 → LEFT JOIN samples_map_lite. Unchanged. Coord-less samples still appear in results.
area	INNER JOIN samples_map_lite inside the candidate selection. Viewport BETWEEN applied BEFORE `ORDER BY ... LIMIT 50`. Drops coord-less samples (required by area).

Both use `f.`-qualified column names so the same `searchWhere`/`score` strings work for both.

Verified

Native (TIGHT Cyprus rect lat 30-40 lng 25-40):

SQL form	top-50 result
Old (filter after CTE LIMIT)	0 ← false-zero bug
New (filter inside CTE)	50 ✓

Browser at Cyprus camera (`lat=35, lng=33, alt=1Mm`): "Search Selected Areas" for `pottery` → 50+ results, all clustered at the Dead Sea pottery site (31.13, 35.53). Exactly what the user expects.

Doc

EXPLORER_STATE.md §6 Light-path addendum updated to describe both SQL shapes and why area mode drops coord-less samples.

Baseline JSON refresh coming in a follow-up commit on this branch — the perf-smoke is running now against the fixed code; the previous `tests/search_baseline_2026-05-08.json` was from a build before the area-scope canonical query was added (and before this fix).

Diff: +89 / -54.

[rdhyee]

Refreshed baseline (commit `d37f703`)

Perf-smoke against the fixed code, all 10 canonical queries:

label	results	cold (ms)	warm (ms)
single-common	50	10534	4566
single-rare	50	9744	4493
multi-term	50	10013	4515
no-hit	0	9840	4644
wildcard-pct	50	12216	4362
wildcard-under	0	10134	4575
diacritic	50	13237	4878
composed-source	50	6072	5486
composed-source-material	0	6582	3427
area-scope	50	10483	4165

`area-scope` now returns 50 results (previously 0 with the pre-fix SQL). Latency envelope ~10-13s cold, ~4-5s warm — same shape as world mode; no regression from adding the INNER JOIN inside the area-mode CTE.

Also fixed: the `field_subset` JSON metadata string (was stale: `"label+place_name samples_map_lite"` from before #177 Direction A; now reads `"label+description+place_name (sample_facets_v2 + lite for coords; world via LEFT JOIN, area via INNER JOIN with viewport predicate inside CTE)"`).