Explorer state contract: URL/DOM/widget-state inventory + search-as-global-filter decision

[rdhyee]

Sub-issue of #163 (architecture review). Blocks feature work in items 1–7 of #163.

Goal

Land a one-page design doc (PR against the repo, probably under docs/ or a top-level EXPLORER_STATE.md) that does two things:

1. State inventory — a table enumerating every piece of explorer state, who owns it, and its lifecycle.
2. Search-semantics decision — a written call on whether search is a global filter or a side-panel lookup, with the implications for facet counts spelled out.

No code changes in this issue. Output is a doc PR. Once merged, the items in #163 become small, parallelizable, and unambiguous.

State inventory — required schema

For each piece of state, the doc lists:

field	owner	default	URL repr	hydration site	write-back trigger	validation	notes

State items to cover (non-exhaustive — add what's actually in the code):

URL query params

• search
• sources (multi-select)
• material (multi-select)
• context (multi-select)
• object_type (multi-select)
• view (globe | table)
• page (table paging — currently not in URL, see Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 6)

URL hash params (camera/deep-link state)

• v (version marker)
• lat, lon, alt (camera)
• pid (selected sample)
• any other hash keys read by the camera flight / sample-card code

DOM-as-state

• body classes used as view markers (e.g. table-view toggle)
• any data-* attributes treated as state

Widget-internal state (viewer.*, window.*)

• viewer._globeState
• viewer._initialHash
• viewer._baselineCounts
• _urlParamsHydrated (recently removed — confirm gone)
• anything else stashed on viewer or window

OJS cell graph

• list of cells, their declared dependencies, and any side effects (DOM mutation, event-listener registration, fetch). Diagram if useful, but a table is fine.

Search-semantics decision

Pick one and document the consequences:

• (A) Global filter: active search restricts the map layer, table, and facet counts to the matching subset. Empty search = normal explorer. Resolves Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 4 cleanly. Forces a decision on what cluster mode does under active search (recommend: auto-drop to point mode since H3 summaries aren't text-indexed).
• (B) Side-panel lookup: search only populates #searchResults; map/table/facets ignore it. Matches Codex's facet-count fix already landed. Leaves Interactive Explorer rethink: architecture review + UX/feature backlog #163 item 4 as a UX wart (zero results + populated map).

The doc must call this out explicitly and state the resulting facet-count contract.

Facet-count contract

Once search semantics is decided, restate the cross-filter rule from Codex's recent fix and clarify:

• Counts respect other facet selections? (current: yes)
• Counts respect viewport? (recommend: no)
• Counts respect search? (depends on the decision above)
• Counts respect view (globe vs table)? (recommend: no — same dataset)

Out of scope

• Refactoring into modules (urlState, globeView, facetCounts, tableView, sampleCard, search) — that's a follow-up once the contract is stable.
• Switching to pure-OJS reactive or pure-imperative — the doc can recommend a direction (lean: imperative + URL-as-canonical) but the rewrite itself is separate.
• Any UX/copy items from Interactive Explorer rethink: architecture review + UX/feature backlog #163 (1, 2, 3, 5, 6).

Acceptance

• Doc PR merged with the inventory table populated against the current explorer.qmd.
• Search-semantics decision recorded with rationale.
• Facet-count contract restated to match.
• Interactive Explorer rethink: architecture review + UX/feature backlog #163 items unblocked and re-scoped against the contract.

Cross-refs: #163, #156, PR #162.