explorer: report real Samples-in-View count when cap is reached (closes #206)

[rdhyee]

Closes #206. First item from the #203 retrospective Codex review (cluster D).

Problem

In point mode, the viewport sample query is capped at POINT_BUDGET = 5000 with no ORDER BY. The "Samples in View" stat box displayed cachedData.length, which equals the cap in any region dense enough to exceed it. Cyprus deep-link (#v=1&lat=34.9957&lng=33.6798&alt=15212&mode=point) showed exactly 5,000 — real count from a direct DuckDB query against the lite parquet: 23,421 samples in the same viewport. ~5x understatement.

Fix

Two changes in loadViewportSamples:

1. Real count: after the LIMIT POINT_BUDGET data fetch, run a count(*) against the same WHERE clause only when the cap is reached. Stat box sSamples now displays the true count; sPoints shows the rendered count under a "Samples Rendered" label so the user sees both numbers. Phase message becomes "23,422 samples in view (showing 5,000 — zoom in for more). Click one for details." when capped. Stale-guard applied between the two queries.

   Below the cap the second query is skipped (data.length == real count by definition), so no extra round-trip in the common case.

2. ORDER BY pid on the data query, so the POINT_BUDGET-worth of rows the LIMIT returns is deterministic across browsers and sessions. (Codex recommendation 4 from the explorer: fix URL state round-trip (closes #201 parts A+B) #203 retrospective.)

Verification

Smoke test against localhost with this branch (Quarto preview):

Cyprus (alt=15212) point-mode display:
  mode: point
  Samples Rendered: 5,000
  Samples in View: 23,422
  phase: 23,422 samples in view (showing 5,000 — zoom in for more). Click one for details.

The 23,422 real count matches the OC investigation's DuckDB result (23,421 at ±0.1°; 23,481 at ±0.13° — explorer's 30%-padded viewport sits between).

url_roundtrip_investigation.js still passes all 6 iterations against localhost, so no regression in #203/#205 URL state work.

Risks

• One extra DuckDB-WASM query per point-mode load when capped only. count(*) on a filtered parquet scan is comparable cost to the data fetch but returns a single number — under 100ms on warm cache in typical viewports. Acceptable for the UX win, especially since dense viewports are exactly the case where users were getting wrong information.
• ORDER BY pid adds a sort step. Affects performance only in the capped case (sort happens on the result of the WHERE-filtered scan). pid is the primary key on the parquet — sort is on small string keys.
• Stat box label change ("Samples Rendered" appears when capped). Could be jarring if a label-stability test exists; none in the current spec set.

Test plan

• Smoke: Cyprus deep-link shows real count = 23,422, rendered = 5,000
• url_roundtrip_investigation.js — all 6 iterations green against localhost
• Manual smoke on deploy preview: Cyprus + a non-capped viewport (small island somewhere with <5k samples)
• Codex review (recommended)

🤖 Generated with Claude Code

[rdhyee]

Codex review applied (commit ca8407c)

Posted the Codex review on this PR. Acted on it. Three changes:

1. Stale guard in count-query catch. The Codex-flagged race (count fails after a newer request starts → stale catch path mutates state) is closed: if (myReqId !== requestId) return at the top of the catch.

2. Cache-hit stats. cachedTotalCount + cachedCapReached now cached alongside cachedBounds/cachedData. loadViewportSamples's cache short-circuit now re-applies them to the stat boxes, so panning inside the padded cache window doesn't leave stale figures on screen. All four cachedBounds = null reset sites also clear the new fields.

3. Always-on stable labels. Dropped the conditional label flip (Samples in View ⇄ Samples Rendered as cap is crossed) in favor of stable labels: sPoints always says Samples Rendered, sSamples always says Samples in View. Redundancy when uncapped is intentional per Codex's preference.

Filed Codex's other suggestion as #211: tighten the count to the visible viewport rather than the 30%-padded fetch box. Out of scope here; folds naturally into #208 if scope grows.

Verified locally:

• Cyprus smoke still reads Samples Rendered: 5,000 / Samples in View: 23,422
• url_roundtrip_investigation.js all 6 iterations green

Codex review verbatim (for the record):

1. Race bug in count-query failure path [...] If the count query fails after a newer camera/filter request starts, the stale request can still update cachedBounds, cachedData, points, stats, and phase text. Add the same guard inside the catch before logging/fallback.
2. Cache-hit stats remain stale [...] Panning inside the padded cached area can leave the previous 'Samples in View' count on screen.
3. 'Samples in View' is still padded-area count [...] If the goal is strict honesty, count against actual bounds; if the goal is only 'not silently capped,' this is acceptable but should probably be called out as a follow-up. [→ explorer: point-mode counts use padded fetch box, not visible viewport #211]

UX: I would prefer always-stable labels: Samples Rendered and Samples in View, even when equal. [✅]

I would not defer this to #208. Add the stale guard in the count catch, then ship. [✅]

Ready to merge from my side.