#208 PR4b: shared settled-camera tail (reconcileSettledCamera)

[rdhyee]

isamplesorg#208 PR4b — shared settled-camera tail (reconcileSettledCamera())

Continues the isamplesorg#249 strangler refactor (PR4a centralized hash writes behind writeGlobeHash). Targets isamplesorg#208 smell 1b: a single settled-camera reconciliation entry point shared by both globe listeners. Branch off main (fork staging); promote upstream later like isamplesorg#287/isamplesorg#288.

What

Extracts the shared tail both camera.changed and moveEnd run once the camera settles — the cluster "Samples in View" stat refresh + the URL-hash write — into a local reconcileSettledCamera(v), called from both.

This gives moveEnd the same cluster-stat refresh camera.changed already did, closing the sub-10%-pan gap: a small cluster-mode drag fires moveEnd (which kept the URL fresh via isamplesorg#204) but not camera.changed (debounced away by percentageChanged=0.1), so the "Samples in View" count went stale until a larger move.

Scope (deliberately minimal — Codex Q3 / REFACTOR_PR4_PLAN.md §3)

• NOT the full camera.changed/moveEnd handler merge (those encode explorer: 60–90 s 'no dots' window on cold-cache deep-link to point mode (DuckDB-WASM 1.24.0 falls back to full HTTP read) isamplesorg/isamplesorg.github.io#190/explorer: smooth failure-message flicker when tryEnterPointModeIfNeeded chases a failed cluster reload isamplesorg/isamplesorg.github.io#193/explorer: 'Samples in View' shows the 5000 fetch budget, not real count + URL round-trip doesn't reproduce view isamplesorg/isamplesorg.github.io#201/explorer: small camera moves don't update URL (Bug A residual, follow-up to #201) isamplesorg/isamplesorg.github.io#204/Samples table and phase-msg 'Samples in View' diverge during point-mode cache-hit pans isamplesorg/isamplesorg.github.io#221/explorer: architectural direction — make filter semantics coherent across all surfaces isamplesorg/isamplesorg.github.io#234/explorer: B1 viewport-aware facet counts (#234 step 3) isamplesorg/isamplesorg.github.io#237/explorer: heatmap overlay spike — phase 1 (#233) isamplesorg/isamplesorg.github.io#240/explorer: turning off heatmap then zooming out doesn't restore clusters (if session started in heatmap) isamplesorg/isamplesorg.github.io#262 edge-cases — too risky).
• Mode-transition + resolution-reload stays camera.changed-only; facet/heatmap/point-exit stays moveEnd-only.
• explorer: turning off heatmap then zooming out doesn't restore clusters (if session started in heatmap) isamplesorg/isamplesorg.github.io#262 (heatmap→zoom-out cluster restore) stays a separate tracked sibling, NOT folded in.

Behavior

• camera.changed: behavior-neutral — same order (cluster-stat then hash), early pre-await write intact.
• moveEnd: adds the cluster-stat refresh. Point mode skips it via the getMode()==='cluster' guard (unchanged there). The stat read is synchronous, guarded by _clusterData, and writes no mode/selection/URL/facet/heatmap state.

Verification

• ✅ smoke 4 + characterization 7 + url-roundtrip 5 all green (behavior-neutral URL contract from both handlers — incl. explorer: add camera.moveEnd URL-write backstop (closes #204) isamplesorg/isamplesorg.github.io#205 sub-threshold moveEnd + cross-context round-trip).
• ✅ quarto render explorer.qmd clean.
• ✅ Codex review of the diff: no blocking findings (confirmed camera.changed neutral, no boot/flight hazard from the moveEnd cluster-stat, ordering safe, satisfies explorer: refactor URL/mode state management (centralize writers, collapse dual mode) isamplesorg/isamplesorg.github.io#208 smell 1b as scoped).
• ⚠️ A dedicated headless regression for the moveEnd cluster-stat refresh proved unreliable — the explorer OJS cell re-evaluates during headless boot, yielding multiple viewer instances; the one reachable via value('viewer') at interaction time often has no camera listeners, so a forced moveEnd never reaches the handler. Rather than ship a flaky test, the rationale is documented inline in url-roundtrip.spec.js. A manual probe confirms a settled cluster camera writes <count> | Samples in View via the shared tail.

🤖 Generated with Claude Code