docs: explorer state contract (closes #164)

[rdhyee]

Summary

Adds EXPLORER_STATE.md — the state-contract doc for explorer.qmd, requested in #164.

• Inventory tables for every piece of explorer state: URL query params, URL hash params, DOM-as-state, viewer.* / window.* fields, OJS cells with deps + side effects.
• Search-semantics decision: option C (side-panel lookup with result-pin overlay). Updated from the original option-B framing after Codex review on Improve Interactive Explorer full-text search substrate #165 surfaced a sharper third option. The §6 implementation rules (50-pin cap, z-order above cluster + sample-mode, hollow-ring styling on source palette, fit-to-bounds only when result extent < 30° × 30°, lifecycle tied to ?search= non-empty) and a result-set-shape acceptance table (zero / one / local-many / global-many) are non-negotiable defaults for the implementer.
• Facet-count contract restated to match [codex] Phase 2: add globe cross-filter facet counts #158 and the option-C decision (?search= does NO modify facet counts; backend contract unchanged from option B).
• All references cite explorer.qmd line numbers against current main (94e7674).
• Confirmed _urlParamsHydrated is gone.

PR is doc-only, no code changes. Three commits: original doc (78ec90a), option C addition (d139313), option C UX-rule + §9 reconciliation + pin-count wording (cdab34a + 062863d).

What this unblocks

Once merged, the items in #163 can be re-scoped against the contract:

• Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 4 (zero search results + populated map looks broken) is resolved by option C, not by side-panel copy. Implementation must visually verify the four result-set shape cases (zero / one / local-many / global-many).
• Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 6 (page in URL) gets a clear contract slot in the writeQueryState / hydration cycle.
• Items 1, 2, 3, 5, 7 are state-preserving UI fixes that don't perturb this contract.

Coordinating with the parallel FTS workstream

The search-backend question is intentionally orthogonal to option C. The state contract specifies which UI surfaces display matches (side panel + result-pin overlay); the FTS substrate work in #165 / #169-#172 specifies how matches are computed. The two land independently; the contract is compatible with every backend the FTS work might choose (in-browser ILIKE, static-Parquet inverted index, hosted-search service).

Test plan

• Review inventory tables against current explorer.qmd
• Confirm option-C decision and rationale (vs A and original B framing)
• Confirm option-C implementation rules table is non-negotiable defaults the implementer should respect
• Confirm facet-count contract matches landed behavior from [codex] Phase 2: add globe cross-filter facet counts #158

Closes #164. Refs #163, #158, PR #162, #165 (Codex review surfaced option C).

🤖 Generated with Claude Code

[rdhyee]

Updated: option C added per Codex review on #165

Codex's review on #165 surfaced a third option that supersedes the prior A/B framing in §6:

(C) Side-panel lookup with result-pin overlay — search backend is unchanged from option B (cluster layer and facet counts remain unaffected), but the UI surface gains a temporary point-overlay of the matching samples on the globe. Cleared when the search is cleared. Resolves #163 item 4 cleanly without making H3 clusters text-aware.

The new commit (`26429ec`):

• Reframes §6 around three options (A/B/C) with rationale for adopting (C).
• Adds an "Addendum to state inventory" naming the new `viewer.searchResultPoints` collection and an optional `viewer._searchResults` cache.
• Updates the §7 facet-count-contract row to reference (C) instead of (B); facet counts are still NO for search since (C) preserves (B)'s data contract.

URL/hash params and DOM-as-state are unchanged. The "backend orthogonal to UI surface" framing is preserved — (C) is compatible with every search backend the substrate work in #169-#172 might land.

Diff is +96/-40 against the original PR; same author, same scope.

[rdhyee]

Review follow-up from the FTS/state-contract pass:

The option C revision is the right direction, but I would tighten two things before treating #163 item 4 as closed.

1. There is a doc mismatch in EXPLORER_STATE.md: section 6 says option C solves Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 4 through a result-pin overlay, but section 9 still says item 4 is now a side-panel-copy fix. That weakens the implementation target. If option C is the contract, acceptance should include overlay behavior, not only copy.

2. Option C should specify the failure modes explicitly before implementation: zero results render zero pins and clear no-match state; one result can fly/select normally; local-many results can fit-to-bounds; global-many results should probably not auto-zoom to the whole world. Fit-to-bounds is only good when the result extent is bounded. For broad result sets, keep camera stable or use a gentler "show pins, don't yank camera" behavior.

I'd also make the overlay styling part of the contract: distinct ring/halo pins, capped to the displayed result set, layered above clusters/sample points, and click behavior matching sample-mode point selection. Without that, the new pathology is visual competition with the cluster layer, even though the backend/facet-count semantics are clean.

[rdhyee]

Round-2 fixes (commit `9d35a30`)

Codex round-2 review on #165 flagged two things in this PR:

1. Option C UX was under-specified. Pin count cap, z-order, styling, fit-to-bounds policy, lifecycle were all left to implementation interpretation. Now locked: 50-pin cap, hollow ring above cluster + sample-mode, fit-to-bounds only when result extent < 30° × 30° (otherwise fly-to-top-1 — avoids the disorienting zoom-out on globally distributed result sets like `basalt`). Lifecycle tied to `?search=` non-empty.
2. §9 still pointed at the superseded framing. `Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 4` was described as a "side-panel-copy fix" — that was the option-B framing, not option-C. Reconciled to "resolved by option C with the four result-set shape cases verified."

Also added a result-set shape acceptance table in §6 — implementation must visually verify zero, one, local-many (regional cluster), and global-many (multi-continent spread) before this counts as done.

Diff: +30/-7 on top of the existing PR.

[rdhyee]

Round-3 cleanup applied

Three small fixes per Codex round-3 review on #165:

1. Rebased to drop the unrelated provenance commit. PR was carrying `94e7674` (scancode-2026-05-04.json, ~20k lines) — same scope-creep that hit PR explorer: search perf-smoke baseline (#167) #173 earlier. PR is now 3 commits, single file (`EXPLORER_STATE.md`), +351/-0.
2. PR body refreshed to describe option C (was stale on option B).
3. Pin-count wording nit in §6 implementation table (commit `062863d`): "never render more, never render fewer than the result set size" → "Pin count equals `min(50, total_matches)`" — disambiguates "result set size" from "full match set."

[rdhyee]

Review result: no blocking issues found. The state-contract doc is internally consistent with the option-C decision, and it keeps the UI-surface contract orthogonal to the search substrate work.