explorer: align with Hana's mockup (rolling target, revisions still coming)

[rdhyee]

Purpose

Umbrella tracking issue for aligning the Interactive Explorer with Hana's wireframe mockup (Figma node 213:394, first discussed at the 2026-05-08 tech call, per #178). Revisions from Hana are expected; this issue treats the mockup as strong guidance but not final law.

Each delta below either points to an existing issue/PR that handles it, or is a candidate for its own follow-up issue. As Hana's "corrections coming" iterations land, we update the list and adjust scope rather than re-litigating the law.

Layout & geometry deltas (newly observed from the mockup, 2026-05-11)

• Map height is viewport-stable, not aspect-ratio-of-width. Mockup's map frame is ~907×626 design-units (≈1.45:1, not the current 4:3). → explorer: map position and size jump between views because surrounding elements shift #199 closed by PR [codex] Stabilize explorer map layout #202 (2026-05-12). Target adopted: clamp(500px, 65vh, 680px) desktop.
• Side panel and map are sibling-aligned in height. → explorer: map position and size jump between views because surrounding elements shift #199 / PR [codex] Stabilize explorer map layout #202. .side-panel max-height now ties to the same CSS variable.
• Search buttons ("Search Selected Areas" + "Search Entire World") live inside the side panel. Currently they sit above the map (explorer.qmd:269-272), contributing to position drift. The button-creation work is already merged via Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178 / PR docs: explorer state contract (closes #164) #166; the relocation into the side panel is still pending. → Candidate for a separate small PR. Note: superseded in part by the 2026-05-08 meeting delta (M-1) below — the mockup now shows TWO search affordances, not just relocated buttons.
• Cesium left-edge native toolbar is visible in the mockup. Currently hidden by the Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178 toolbar relocation to top-left. Mockup re-introduces it as a left-edge vertical strip (~167×583 design-units). → Needs its own issue once Hana confirms this in the next revision.

Search-semantics delta (already shipped)

• Two search buttons with viewport-vs-world scope. → Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178 (closed) / PR docs: explorer state contract (closes #164) #166. Light-path complete; EXPLORER_STATE.md §6 amended.

UX deltas (separate follow-ups, mostly from the original #178 list)

• Permanent samples table below the globe (always visible, replacing the Globe/Table toggle). Conflicts with current binary view (Phase 5: rename Interactive Explorer to /explorer.html with redirects #162). Needs a UX call once Hana's revisions stabilize.
• Educational tooltips ("What is a Cluster?", "What is a Sample?") as boxes on the left edge of the explorer.
• Tree-selection vocabularies for material / sample / sample-feature hierarchies — Hana to provide a mockup diagram.
• Top-level sample-type icons (5 per category) for missing-image fallback in sample cards.
• Visual accessibility halos around dots for color-blind / low-vision users.
• Quick Stats panel restructure — Selected Cluster moved into the same table as Quick Stats.
• Visible "Copy Link to Selected View" button — currently shareBtn; mockup styles it as a prominent labeled button.
• Sample-detail tooltip overlay anchored over the globe (visible in mockup; consistent with .cesium-topleft styling that's currently stranded at explorer.qmd:23-30).

Meeting deltas — 2026-05-08 tech call notes (folded in 2026-05-12)

Attendees: Raymond, Eric, Hana, Sean, Saebs (regrets: Andrea, John K.). Andrea + Hana met separately on the Interactive Explorer ahead of the call. Hana hasn't edited the Figma file since 2026-05-08 02:04 PT (verified via Figma API lastModified) — these deltas reflect what the meeting surfaced beyond the mockup as it stands, and will largely manifest in Hana's next mockup pass.

New deltas (no existing #200 line item)

• M-1: Two search affordances, not one. Permanent search bar inside the map application (in-map overlay) AND a separate open-text search in the sidebar. Subtly different from the existing "relocate the two buttons into the side panel" line above — meeting describes them as additive, not a relocation.
• M-2: Key / legend at the bottom of the map. "Adding key? On the bottom" — new map-frame element. Color-swatch legend most likely, mapping the dot colors to sources.
• M-3: Contextual info markers on Quick Stats values. "Clusters in view etc have mark where it gives information in context of application" — small info-icon / tooltip next to each stat value explaining what it means in context (cold-cache total vs in-view, sample-cap vs unbounded, etc.).
• M-4: Open — facet counts in the sidebar? Undecided in the meeting. ("Do we want facet counts along the side bar?") May overlap with the existing "Quick Stats panel restructure" item depending on layout.
• M-5: Open — single-item selection from table view, where does it live? Undecided. Hana to mockup.
• M-6: Open — sample quick-view granularity. Globe overlay AND/OR bottom-under-cluster panel? Explicitly "Will decide after seeing what mockups look like." Hana to mockup. Adjacent to the existing "Sample-detail tooltip overlay anchored over the globe" item — may converge with it.

Hana's follow-up mockup deliverables (committed in the meeting)

• Tree-selection vocabularies diagram (already an existing explorer: align with Hana's mockup (rolling target, revisions still coming) #200 item, now confirmed deliverable for next mockup pass).
• M-5 (table-view single-item selection) and M-6 (sample quick-view granularity) — both gated on Hana's next mockup.

Backend / data notes (out of mockup scope, captured for cross-reference)

• Full-text search substrate still WIP — see Improve Interactive Explorer full-text search substrate #165.
• Geohash + facet-count optimization: Solr facet bottleneck above ~200k results; multi-resolution geohash on backend; dataframe-driven geohash reduction. Not a mockup item; backlogged separately.
• TODO Eric: provide OpenContext queries with iSamples-equivalent results as a guide for Raymond.

Working principles

1. Mockup is guidance, not law. Where mockup intent is unclear or conflicts with shipped contracts (e.g., Explorer state contract: URL/DOM/widget-state inventory + search-as-global-filter decision #164 state contract), we keep the shipped contract and flag the conflict here.
2. Each delta becomes its own scoped PR when ready — no big-bang mockup-alignment PR. PRs should cross-link this umbrella so the audit trail is clear.
3. Revisions update this issue's checklist, not the closed sub-issues. If Hana changes her mind about something we already shipped (Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178), file a new issue rather than reopening.
4. Stop conditions: this issue closes when (a) the remaining checklist items are either shipped, filed as their own issues, or explicitly deferred-with-rationale, AND (b) we've received what Hana considers her final mockup pass.

Refs

• Figma mockup (node 213:394) — file lastModified = 2026-05-08 02:04 PT, unchanged since.
• Interactive Explorer: integrate Hana mockup feedback (Light path on search semantics) #178 (closed) — Light-path search semantics, the initial mockup integration
• explorer: map position and size jump between views because surrounding elements shift #199 (closed) / PR [codex] Stabilize explorer map layout #202 — Map position/size stability; landed 2026-05-12
• Interactive Explorer rethink: architecture review + UX/feature backlog #163 — UX rework backlog (feature-level)
• Explorer state contract: URL/DOM/widget-state inventory + search-as-global-filter decision #164 — Explorer state contract (option C, locked)
• Phase 5: rename Interactive Explorer to /explorer.html with redirects #162 — Globe/Table binary view (may be superseded by permanent-table-below-globe direction)
• Improve Interactive Explorer full-text search substrate #165 — Full-text search substrate improvements (backend backlog)

[rdhyee]

Evaluation / plan after checking current repo and related PRs

Key read: #200 is a rolling umbrella, so the first move should be checklist cleanup, not a broad implementation PR. A few unchecked items are already shipped or partly shipped.

Corrections to #200

• The two-button search work shipped in PR explorer: two-button search semantics (closes #178, Light path) #179, not PR docs: explorer state contract (closes #164) #166.
• Native Cesium toolbar, prominent Copy Link to Current View, and white point halos already shipped in PR explorer: native Cesium toolbar + prominent share button + a11y halos #180. Current explorer.qmd confirms the toolbar CSS, share button styling/label, and point outlines on both cluster and sample point primitives.
• Map/side-panel height stability shipped in PR [codex] Stabilize explorer map layout #202, with dedicated Playwright coverage in tests/playwright/explorer-layout-stability.spec.js.

Current implementation state

• Search controls still live above the map, outside the side panel (explorer.qmd around the explorer-controls block).
• The side panel currently owns stats, source legend/filter, material/context/specimen filters, share button, phase message, selection detail, and nearby samples.
• Globe/Table is still a binary view toggle; the samples table is not permanent below the globe.

Plan

1. Triage/update this umbrella
   Update the checklist to mark the PR explorer: native Cesium toolbar + prominent share button + a11y halos #180 items as done, fix the explorer: two-button search semantics (closes #178, Light path) #179/docs: explorer state contract (closes #164) #166 attribution, and split “search buttons relocate” from M-1 because M-1 describes additive search affordances, not just moving the existing buttons.

2. Immediate small PR candidate
   Add contextual info markers/tooltips to Quick Stats. This is low-risk if kept purely presentational and if the copy explains the existing semantics for Resolution, Clusters in View / Loaded, Samples in View, and Load Time without changing state or query behavior.

3. Design-confirmation PR candidates
   Hold these until Hana’s next mockup or a UX call:

   • in-map search overlay plus sidebar open-text search
   • bottom-of-map key/legend versus the existing side-panel source filter
   • permanent samples table below globe
   • sample quick-view placement
   • single-item table selection behavior

4. Larger follow-up issues
   File separate scoped issues for:

   • tree-selection vocabulary UI
   • top-level sample-type fallback icons
   • permanent table replacing Globe/Table toggle
   • sample-detail overlay behavior and URL/state contract impacts

5. Verification baseline for each UI PR
   Use Quarto preview plus the relevant Playwright/Python smoke tests:

   • tests/playwright/explorer-layout-stability.spec.js
   • tests/playwright/url-roundtrip.spec.js
   • relevant tests/test_globe.py cases

Any change touching search state should also update/check EXPLORER_STATE.md, especially the ?search= and ?search_scope= contract.