explorer: map position and size jump between views because surrounding elements shift

[rdhyee]

Symptom

The Cesium globe (#cesiumContainer) changes both vertical position on the page and rendered size as the user moves between views (cold-load, search-active, point-mode, cluster-mode, table-mode). The user has to re-orient on the map each time something above or beside it changes.

Diagnosis

Two distinct causes, both in explorer.qmd:

1. Map size is content-width-dependent

#cesiumContainer (explorer.qmd:40-44) is currently sized as:

#cesiumContainer {
    width: 100%;
    min-height: 500px;
    aspect-ratio: 4/3;
}

Height is derived from width via aspect-ratio. Width is the left column of grid-template-columns: 1fr 340px on .globe-layout. So any viewport-width change resizes the map.

The side-panel column has max-height: 700px; overflow-y: auto, which is the right pattern (bounded + internal scroll), but the map column has no comparable height anchor.

2. Map position drifts because variable-height content lives above it

The flow above .globe-layout:

• .search-bar — fixed
• .search-actions — fixed
• .search-help — fixed
• #searchResults (.search-results) — variable, grows with results
• .view-toolbar — fixed, but #tableControls toggles visibility
• Phase / "Fetching sample index…" / error banners (added in 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 / PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191) — appear and disappear

When any of those grow/shrink, #cesiumContainer.getBoundingClientRect().top shifts and the map jumps vertically.

Proposed fix (CSS + light HTML restructure)

Treat the globe as an app-shell anchor, not a flow-layout element:

1. Replace aspect-ratio: 4/3 + min-height: 500px on #cesiumContainer with a viewport-stable height (e.g., height: clamp(500px, 70vh, 800px)). Map height becomes a function of viewport height alone.
2. Bound #searchResults with min-height: 0; max-height: <small>; overflow-y: auto — or move inline status into a Cesium overlay (.cesium-topleft slot already styled at explorer.qmd:23-30).
3. Reserve a fixed-height slot for banner-style messages above the map (loading, phase, error) so the slot exists whether or not a message is showing.
4. Verify with Playwright: snapshot #cesiumContainer.getBoundingClientRect() across the five views; assert top/height stable within ε.

No JS logic changes expected. Scope is similar to a single Codex-loop PR.

Open design choices

• Target height: clamp(500px, 70vh, 800px) is a starting point. May want to align with the Hana mockup direction referenced near .cesium-viewer-toolbar styling (explorer.qmd:~98).
• Status banners — overlay vs reserved slot: overlay (Cesium top-left badge, reusing .cesium-topleft styling) is denser; reserved slot is more conventional. PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191's "Fetching sample index…" UX is currently implemented one of these ways — choice should be consistent with that.

Acceptance criteria

• #cesiumContainer.getBoundingClientRect() has constant top-y and height across cold-load, search-active, point-mode, cluster-mode, and table-mode (within a small ε).
• Window resize changes map size monotonically with viewport height, not with side-panel content state.
• No regression in the cold-cache UX from 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 / PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191 (loading message still visible, doesn't itself shift the map).
• Playwright spec covering the stable-geometry invariant.

[rdhyee]

Codex review of the diagnosis + proposed fix

Posted on behalf of OpenAI Codex (gpt-5.4), invoked via CC. Codex read explorer.qmd directly. Verbatim review below — it caught three factual errors in my original diagnosis worth noting.

---

1. Critique

The two-cause framing is mostly right, but it overstates one part.

Cause 1 is correct: #cesiumContainer at explorer.qmd:40-44 derives height from width via aspect-ratio: 4/3, and the width is the left track of .globe-layout. That means viewport width changes, body scrollbar appearance/disappearance, and any layout-width changes can resize the map.

Cause 2 is partly correct: the map's top is vulnerable because search/status controls sit above .globe-layout in normal flow at explorer.qmd:266-288. #searchResults can wrap, and .view-toolbar can change height if controls wrap.

Incorrect or misleading claims in the original issue:

• #phaseMsg is not above the map. It is inside the right side panel at explorer.qmd:339-341, and PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191's "Fetching sample index…" path updates that element via updatePhaseMsg() at explorer.qmd:709-715. It should not shift #cesiumContainer.getBoundingClientRect().top.
• .cesium-topleft is only a CSS rule at explorer.qmd:23-30; there is no corresponding static status slot in the current HTML. So the "overlay vs reserved slot consistency with PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191" framing in the issue is moot — there is nothing to be consistent with.
• #searchResults does not currently grow into a result list. It is a short text status at explorer.qmd:2249-2386; real result rows go into #samplesSection. It can still wrap, but it is not unbounded today.

Things missing from the diagnosis:

• Body scrollbar shifts are a plausible contributor. Table mode or long side-panel/table content can change document height, which can add/remove the vertical scrollbar and change available content width. With the current aspect-ratio map, even a small width delta changes height.
• Adjacent vertical margins are not the main problem, but wrapping plus margins on .view-toolbar can produce visible top changes. A wrapper using gap would be cleaner.
• OJS re-renders do not look like the primary cause. The layout is static HTML, the viewer is created once, and the relevant OJS cells are output: false.

2. Concrete plan

Recommended height:

Use a shared CSS variable, not a raw one-off height:

:root {
  --explorer-map-height: clamp(500px, 70vh, 760px);
}

@media (max-width: 900px) {
  :root {
    --explorer-map-height: clamp(360px, 58vh, 520px);
  }
}

Then:

#cesiumContainer {
  width: 100%;
  height: var(--explorer-map-height);
  min-height: 0;
  aspect-ratio: auto;
  position: relative;
}

.side-panel {
  max-height: var(--explorer-map-height);
}

Cap at 760px, not 800px, unless Hana's mockup explicitly expects a taller globe. 760px keeps a large map on 1080p/tall desktop screens without letting very tall monitors turn the explorer into mostly map. Mobile should not inherit a 500px minimum; it leaves too little room for controls and the stacked side panel.

Also add:

html {
  scrollbar-gutter: stable;
}

That directly addresses small width jumps when table/search content changes page scrollability.

Banner/status strategy:

Do not move PR #191's #phaseMsg into a Cesium overlay for this issue. The consistent path is to keep loading/index/phase messages in the side panel, because that is what PR #191 implemented and what the existing Playwright helper tests observe.

For above-map content, reserve/bound only the existing search status area:

.search-results {
  min-height: calc(1.35em + 8px);
  max-height: calc(2.7em + 8px);
  overflow-y: auto;
  line-height: 1.35;
}

If a future design wants map-overlay status, do it as a separate UX PR. Overlaying status now risks colliding with the Cesium toolbar moved to top-left in #178.

File change inventory:

• explorer.qmd:31-50: change .globe-layout to grid-template-columns: minmax(0, 1fr) 340px; replace map aspect-ratio sizing with fixed viewport-stable height; tie .side-panel max-height to the same variable.
• explorer.qmd:37-44: add a mobile-specific map-height override under the existing @media (max-width: 900px).
• explorer.qmd:114-140: clean up top controls so vertical spacing is stable. Prefer wrapping explorer.qmd:266-288 in something like <div class="explorer-controls"> and using gap instead of separate margins.
• explorer.qmd:132: give .search-results a reserved bounded slot.
• explorer.qmd:277: add aria-live="polite" to #searchResults.
• Leave #phaseMsg at explorer.qmd:339-341 in the side panel for the first PR.

Playwright spec sketch (new file: tests/playwright/explorer-layout-stability.spec.js):

Selectors: #cesiumContainer, .globe-layout, #searchResults, #globeViewBtn, #tableViewBtn, #tableContainer, #phaseMsg.

Assertions:

• Measure #cesiumContainer.getBoundingClientRect() after initial DOM load and after cluster boot. Assert top and height stable within 1-2 px.
• After setting a representative search status in #searchResults or driving a short real search state, assert map top and height unchanged.
• In cluster mode after boot, record baseline.
• Use the existing OJS viewer access pattern from explorer-helper.spec.js to fly into point altitude, wait for viewer._globeState.mode === "point", then assert map top and height unchanged.
• For table mode, do not assert #cesiumContainer while hidden. Instead click Table, assert .globe-layout hidden and #tableContainer top is close to the prior map top, then click Globe and assert the map rect returns to baseline.
• Run at least desktop 1280x900; add a mobile 390x844 case to verify the max-width: 900px height override.

Risks:

• Moving or renaming #phaseMsg will break the existing PR explorer: surface 'Fetching sample index…' during cold-cache boot→point-mode wait (#190 fix 2) #191 tests and cold-cache UX. Keep the id stable.
• Any overlay status near top-left can conflict with the Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178 Cesium toolbar relocation and base-layer picker.
• A too-large mobile minimum height will make the stacked layout worse.
• scrollbar-gutter is the right fix for modern Chromium, but check Safari support expectations if this page has strict cross-browser requirements.
• Table mode hides the map; testing "map rect in table mode" literally will produce a zero rect. Test the table top and the globe round trip instead.

3. Sequencing

Single PR is fine if scoped to CSS/HTML layout plus one Playwright spec. This is not large enough to justify multiple PRs unless you decide to redesign status placement.

Smallest first slice with visible win:

1. Replace aspect-ratio map sizing with height: var(--explorer-map-height).
2. Add stable scrollbar gutter.
3. Bound/reserve #searchResults.

That should fix the obvious size jump and most top drift without touching data/load logic.

Then add the Playwright regression test in the same PR or immediately after.

4. Open questions for the user

• Should the desktop map visually align with the side panel height, or is a slightly taller map acceptable? This determines whether the cap should be closer to 700px, 760px, or 800px.
• Is table-mode continuity supposed to mean "the table starts where the map starts," or only "when returning to globe, the map returns to the same rect"?
• How important is mobile map height versus seeing filters/search controls without scrolling? That affects the mobile clamp values.
• Do we want to reserve one line or two lines for #searchResults? One line is denser; two lines handles wrapped errors/search messages without movement.

[rdhyee]

Plan refinement after consulting Hana's mockup

After Codex's review (comment above), checked Hana's wireframe mockup (Figma 213:394, via #178 / #200) to ground the four open questions Codex surfaced.

Mockup observations relevant to #199

• Map frame: ~907×626 design-units → ~1.45:1 aspect, not 4:3. Map ends up around 626px tall at design scale.
• Side panel and map are sibling-aligned in height in the mockup.
• Search buttons ("Search Selected Areas" + "Search Entire World") sit inside the side panel in the mockup, not above the map as they do today (explorer.qmd:269-272).
• Samples table is permanent below the globe (no Globe/Table toggle) — out of explorer: map position and size jump between views because surrounding elements shift #199 scope but reframes the table-mode-continuity question (see below).

Mockup-informed answers to Codex's four open questions

#	Question	Decision	Source
1	Desktop height cap	clamp(500px, 65vh, 680px) (lower than Codex's 760px to match mockup)	Mockup map ≈ 626 design-px
2	Table-mode continuity meaning	Just "globe rect returns to baseline on round-trip" — full mockup eventually eliminates the toggle (tracked in #200)	Mockup → permanent table below globe
3	Mobile clamp values	Adopt Codex's clamp(360px, 58vh, 520px)	Mockup doesn't show mobile
4	.search-results reserved height	2 lines, per Codex	Mockup has no above-map status area

Scope decision: Option A (recommended)

Codex's plan presumed Option A. Hana's mockup shows the search buttons in the side panel — moving them would close part of #178's follow-up list and remove a ~80px variable-height block from above the map. But:

• Option B (move buttons in this PR) risks regressing search interaction (button id, click handlers, ARIA, the keyboard-default question in Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178 still open).
• Option A keeps explorer: map position and size jump between views because surrounding elements shift #199 a focused CSS/layout-only PR with a single Codex review round.
• The button relocation has a natural home in explorer: align with Hana's mockup (rolling target, revisions still coming) #200 (mockup-alignment umbrella) and can be its own small PR.

Going with Option A. Cross-linked to #200.

Updated unified plan (diff from Codex's plan above)

• --explorer-map-height: clamp(500px, 65vh, 680px) (was 760)
• .side-panel max-height: var(--explorer-map-height) (mockup endorses sibling alignment)
• Everything else stands: scrollbar-gutter: stable, minmax(0, 1fr), .search-results 2-line reservation + aria-live, .explorer-controls wrapper, leave #phaseMsg in side panel, Playwright spec (tests/playwright/explorer-layout-stability.spec.js) with desktop 1280×900 + mobile 390×844, round-trip assertion for table mode.

Ready to branch and implement. Will run a second Codex review on the diff before requesting merge.