explorer: document loadRes-chase invariant on tryEnterPointModeIfNeeded (closes #194)

[rdhyee]

Summary

Closes #194. Doc-only change to explorer.qmd — adds a load-bearing INVARIANT block to the doc comment of tryEnterPointModeIfNeeded() plus a short pointer above the !loading short-circuit inside the function.

The invariant: every loadRes call site in the zoomWatcher cell that could be in flight when the user crosses below ENTER_POINT_ALT MUST be followed by await tryEnterPointModeIfNeeded(). Without the chase, the helper's !loading bail-out can strand the user in cluster mode at point altitude — the exact bug round 3 of #191 fixed by adding the source-filter handler's chase call.

Why this matters

Future contributors adding a new loadRes site without the chase would silently break supersession recovery. The bug would surface only as a rare liveness regression (user at point altitude, mode stays cluster, no further events fire) that's hard to attribute back to the missing chase. The PR thread for #191 documented this; this PR moves it to the code itself.

Test plan

• No behavior change — quarto render explorer.qmd produces identical output to main.
• grep -nE 'loadRes\(' explorer.qmd returns the same set of call sites as main, each either inside tryEnterPointModeIfNeeded itself or followed by await tryEnterPointModeIfNeeded().

🤖 Generated with Claude Code

[rdhyee]

Codex review round 1

Codex flagged one blocking issue + offered a precision tweak.

Blocking

The suggested grep -nE "loadRes\(" explorer.qmd matches comments at L1615 and L1623 (which mention loadRes(...) in prose), not just call sites. Misleading for someone running the verification.

Fix in b87cb49: changed the documented command to grep -nE "await[[:space:]]+loadRes\(" explorer.qmd, which matches exactly four lines — the helper's own internal call plus the three external callers — with no false-positive comment matches.

Verified locally:

$ grep -nE "await[[:space:]]+loadRes\(" explorer.qmd
1653:            res8Ready = await loadRes(8, h3_res8_url, {       (inside the helper)
1830:                await loadRes(currentRes, resUrls[currentRes]);  (source-filter handler — chase ✓)
1944:                    await loadRes(target, ...)[target]);          (camera→cluster reload — chase ✓)
1957:                    await loadRes(target, ...)[target]);          (camera→cluster-resolution change — chase ✓)

Precision tweak (also addressed)

Optional: say "every loadRes call site outside this helper..." to avoid the helper's own internal call looking like an exception to the invariant sentence.

Added the "outside this helper" qualifier in the same commit.

Codex's other answers (no action needed)

• ✓ Invariant matches the actual current call sites.
• ✓ Prose is clear without PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191 context. "Chase" is local jargon but explained.

Asking for re-review.

[rdhyee]

Codex review round 2 — LGTM

No blocking issues found.

The round-2 fix resolves the round-1 finding: the updated grep now matches only awaited loadRes(...) call sites, not explanatory comment mentions. I verified it returns the expected four lines, and the three external call sites are immediately followed by await tryEnterPointModeIfNeeded().

No new issues introduced by round 2.

LGTM, ready to merge.

Merging.