explorer: skip tryEnterPointModeIfNeeded chase on non-applied loadRes (closes #193)

[rdhyee]

Summary

Closes #193. Stops tryEnterPointModeIfNeeded() from being invoked after a loadRes call returns false, so the user-facing failure phase message (Failed to load H3 res${target} — try zooming again.) no longer flickers before being overpainted by the chase's own Fetching sample index….

Root cause

After PR #191, three external loadRes call sites unconditionally chased with await tryEnterPointModeIfNeeded():

await loadRes(target, ...);
await tryEnterPointModeIfNeeded();   // unconditional

If loadRes failed (caught error → returned false), it painted Failed to load H3 res${target} — try zooming again. But the immediate chase, if the user is at point altitude, fired its own loadRes(8, ...) which painted Fetching sample index… over the failure. The user saw the failure message for ~1 frame.

If loadRes was superseded (stale → also false), the chase was technically harmless but redundant — the supersedor's own chase recovers the user.

Fix

Capture the return into applied and gate the chase:

const applied = await loadRes(target, ...);
if (applied) await tryEnterPointModeIfNeeded();

• applied === true: fresh data applied; chase fires as before.
• applied === false (stale): supersedor's own chase will handle recovery (per the invariant documented in explorer: document the 'every loadRes caller chases with tryEnterPointModeIfNeeded' invariant #194). Skipping our chase is a no-op for liveness.
• applied === false (failed): failure phase message stays visible; user can read and act on it.

Applied at the three external call sites:

1. Source-filter handler's mode === 'cluster' branch
2. Camera handler's cluster-reload branch (targetMode === 'cluster' && mode !== 'cluster')
3. Camera handler's cluster-mode resolution-change branch (else branch)

Documentation

Updates the tryEnterPointModeIfNeeded() doc-block (added in #194 / #195) to:

• Show the new idiom: const applied = await loadRes(...); if (applied) await tryEnterPointModeIfNeeded();
• Explain why we gate on applied (one bullet per false-stale and false-failed case)
• Update the verification-grep instructions to point reviewers at the new shape

Test plan

• Cold-cache deep-link still works (the original 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) #190 fix 2 path). Fetching sample index… → Loading individual samples... → dots.
• Source-filter toggle during cold-cache wait still recovers into point mode (the round-3 fix in explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191 — applied=true for the source-filter handler's loadRes(currentRes), so chase fires).
• Synthetic res4/res6 fetch failure while crossing into point altitude: throttle network, deep-zoom across cluster thresholds straight into point altitude. Confirm Failed to load H3 res${target} — try zooming again. stays visible (does not flicker to Fetching sample index…).
• Unrelated regressions: confirm existing cluster→cluster resolution changes still update the cluster overlays (they should — applied=true on success, chase only matters at point altitude).

Refs

• explorer: smooth failure-message flicker when tryEnterPointModeIfNeeded chases a failed cluster reload #193 — this issue
• explorer: document the 'every loadRes caller chases with tryEnterPointModeIfNeeded' invariant #194 / explorer: document loadRes-chase invariant on tryEnterPointModeIfNeeded (closes #194) #195 — the loadRes-chase invariant (this PR updates the same doc-block to reflect the conditional chase idiom)
• 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) #190 / explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191 — original PR thread for the supersession recovery this builds on

🤖 Generated with Claude Code

[rdhyee]

Codex review round 1 — LGTM

Findings: None. I don't see a blocking counterexample.

Verified against HEAD on fix/193-skip-chase-on-loadres-failure:

1. The stale-recovery claim is sound for the current code. A stale loadRes return means a newer loadRes incremented loadResGen; the only live external superseding sites are the three edited sites, and each now chases when its own load applies. The helper's internal res8 load will not start while another loadRes is in flight because of the !loading guard.
2. Yes, this fixes the failure-message flicker path. loadRes paints the failure message and returns false; the three external callers now skip tryEnterPointModeIfNeeded() on that false, so they no longer immediately trigger the helper's "Fetching sample index…" path.
3. The edits are complete. rg "await\s+loadRes\(" explorer.qmd shows one internal helper call and three external call sites — all three external sites have the new const applied = ...; if (applied) await tryEnterPointModeIfNeeded(); shape.
4. The doc block is consistent with the code.
5. No new issue introduced. The only non-recovery case left is an actual newest-load failure, which is intentional so the user can read the failure message.

git diff --check upstream/main..HEAD passed.

LGTM, ready to merge.

Merging.