explorer: B1 viewport-aware facet counts (#234 step 3)

[rdhyee]

Summary

The facet legend now scopes per-source / per-material / per-context / per-object_type counts to the current map viewport bbox instead of the whole dataset. Pan or zoom → counts recompute. This resolves the silent disagreement between the legend ("global pivot tool") and the rest of the page ("Samples in View", table count, map dots) that the 2026-05-22 design session called out and that #234 picks as direction B1.

This is step 3 of the #234 roadmap, after #235 (facetNote URL-load, merged) and #236 (search real-count, merged). Subsequent steps (A1 search-as-global-filter, C3 auto-promote to point mode) are independent and build on this.

Decisions locked with @rdhyee before implementation

Q	Decision
Q1 — where do coordinates live for the bbox JOIN?	No existing parquet carries both the four facet columns and lat/lon. JOIN facets_url to lite_url on pid for this PR; follow-up to bake a pre-joined parquet if real-world latency proves bad.
Q2 — progressive refinement now?	Single-pass full query, debounced 250 ms via the existing facetCountsReqId infrastructure. Defer coarse-then-fine scaffold until latency shows it's needed.
Q3 — error-path semantics?	Fall back to global baseline via existing applyFacetCounts(key, null) — matches current no-filter behavior; user can re-pan to retry.

Architectural changes

• New isGlobalView() helper (altitude shortcut + rect-saturation check) decides when the cube fast-path stays valid. At alt > 10,000 km the camera is treated as global regardless of computeViewRectangle per-angle quirks, so legend totals don't jiggle on tiny camera rotations near the default zoom-out.
• updateCrossFilteredCounts snapshots bboxSQL once at function entry. Cube fast-path gated additionally on bboxSQL === null. The no-filter + non-global case now falls through to the slow path (B1's whole point: counts reflect what's in view even with zero facet filters).
• Slow path (when bboxSQL set): JOIN facets_url f ↔ lite_url l ON l.pid = f.pid and apply the bbox predicate against (l.latitude, l.longitude). buildCrossFilterWhere takes an optional column-prefix arg so the JOIN-shape WHERE qualifies columns with f. to avoid ambiguity with lite_url.source.
• viewer.camera.moveStart → synchronous markFacetCountsRecomputing(). Italic-stale legend appears the instant the user starts panning, cleared when applyFacetCounts writes the post-moveEnd result.
• viewer.camera.moveEnd → refreshFacetCounts(). Reuses the existing 250 ms debounce + facetCountsReqId stale guard — bursts coalesce to one query, superseded in-flight queries discard their result on await resume.

Test plan

• quarto render explorer.qmd — passes
• New tests/playwright/facet-viewport.spec.js — 3 specs pass locally
  • zoom-in → counts shrink relative to global, per-source counts ≤ global; zoom-out → restore to within 1 %
  • moveStart marks .recomputing synchronously (verified via in-page listener that runs after the explorer's)
  • negative control: cold global-view boot leaves no .recomputing stuck
• Regression suite — facetnote-url-load.spec.js (2), search-real-count.spec.js (3), url-roundtrip.spec.js (5) — all pass (10/10)
• git diff --check upstream/main...HEAD — clean
• Pre-deploy smoke gate on CI

Known follow-ups

• Latency not formally benchmarked. The JOIN turns 4 parallel GROUP BY queries into 4 parallel JOIN+GROUP BY queries against the ≈300 MB lite_url parquet. If UX feels slow in real use, follow-up to bake a pre-joined facets-with-coords parquet and route the bbox path through it (Q1 fallback).
• Cancellation-race spec deferred. The facetCountsReqId stale guard is in place but not exercised by a Playwright test (two pans back-to-back inside the 250 ms window). Add if Codex flags it as a coverage gap.
• Progressive refinement (coarse-then-fine) explicitly out of scope — Q2 locked single-pass. File as a separate issue if latency benchmarks demand it.

Cross-refs

• Closes the B1 row in explorer: architectural direction — make filter semantics coherent across all surfaces #234
• Supersedes the bbox-scope portion of explorer: facet counts — remaining work after #157/#226 #230
• Unblocks step 4 (A1 search-as-global-filter)

---

Roadmap context: #234. Direction is A1 + B1 + (C3-when-feasible, C2-with-warning) with progressive refinement underlying the dynamic surfaces.

[rdhyee]

Codex review iteration log (2 rounds → LGTM)

Round	Codex finding	Resolution	Commit
1	(BLOCKING) moveStart only marked .recomputing; did not bump facetCountsReqId or clear the pending debounce. An older updateCrossFilteredCounts could resume mid-pan, pass the stale guard, write pre-move counts, and clear .recomputing — leaving the legend looking authoritative but stale until moveEnd's debounce fired the new query.	moveStart now clearTimeout(facetCountsDebounce); ++facetCountsReqId; in addition to marking the italic state. moveEnd's refreshFacetCounts() bumps the id AGAIN — supersession of already-superseded work, debounce coalesced.	63b0457
1	Test coverage gap: the spec exercised the no-filter bbox path but NOT the filter-active JOIN path — exactly the new SQL shape this PR introduces.	Added bbox-aware count under an active source filter (JOIN + filter): activate a single source filter (cube fast-path at global view), capture filtered material counts, fly to Cyprus → forces slow path with f.source IN (…) JOIN. Assertion cyprusTotal < filteredTotal catches the silent fallback-to-baseline case (column-ambiguity SQL errors fall back to unfiltered globals, which would GROW back instead of shrinking — caught).	63b0457
1	1 % restore tolerance was too loose. At alt=15e6 the altitude shortcut forces the no-bbox baseline path, so restored counts should be value-by-value EXACTLY equal to the first global capture.	expect(restoredCounts).toEqual(globalCounts) — strict equality.	63b0457
1	Polish: moveStart comment missed the rationale for the id bump.	Comment expanded with the race-condition explanation.	63b0457
1	Documentation polish — high-altitude shortcut can return "global" for a non-fully-data-covering camera angle.	Intentional per the design rationale; no change. (Existing comment in isGlobalView() already explains the UX call.)	n/a

Round 2: LGTM (Codex)

Findings: none. I don't see a new correctness issue in 63b0457. […] moveStart double-bump: safe. […] JOIN + filter test exercises the intended SQL shape because the checkbox state is changed synchronously before the Cyprus fly. […] Handler mechanics: clearTimeout(null) is safe, facetCountsReqId is initialized, and the mark/clear/bump ordering is fine under JS's single-threaded event execution.

Final test count: 14 passed locally (4 new B1 specs + 10 regression: 2 facetnote-url-load + 3 search-real-count + 5 url-roundtrip).

Known follow-ups deferred per Q1/Q2 plan decisions, not raised by Codex:

• Latency was not formally benchmarked; baking a pre-joined facets+coords parquet (Q1 fallback) waits on real-world UX feedback.
• Cancellation-race Playwright spec (two pans back-to-back inside the 250 ms window) — not added; the facetCountsReqId stale guard is now exercised structurally by moveStart's invalidation, which Codex round 2 walked through and accepted.

Thanks codex for the round-1 catch on moveStart — the stale-and-not-italic interval was a real bug, not a theoretical one.