From 589da57cddb9651666407f83c900bfcf3ec7ec5c Mon Sep 17 00:00:00 2001
From: Raymond Yee <raymond.yee@gmail.com>
Date: Mon, 11 May 2026 11:18:10 -0700
Subject: [PATCH 1/3] Stabilize explorer map layout

---
 explorer.qmd                                  |  52 +++++--
 .../explorer-layout-stability.spec.js         | 129 ++++++++++++++++++
 2 files changed, 171 insertions(+), 10 deletions(-)
 create mode 100644 tests/playwright/explorer-layout-stability.spec.js

diff --git a/explorer.qmd b/explorer.qmd
index 7c86c63..430f6ce 100644
--- a/explorer.qmd
+++ b/explorer.qmd
@@ -20,6 +20,12 @@ format:
 <script src="https://cesium.com/downloads/cesiumjs/releases/1.127/Build/Cesium/Cesium.js"></script>
 <link href="https://cesium.com/downloads/cesiumjs/releases/1.127/Build/Cesium/Widgets/widgets.css" rel="stylesheet"></link>
 <style>
+    :root {
+        --explorer-map-height: clamp(500px, 65vh, 680px);
+    }
+    html {
+        scrollbar-gutter: stable;
+    }
     div.cesium-topleft {
         display: block;
         position: absolute;
@@ -30,23 +36,27 @@ format:
     }
     .globe-layout {
         display: grid;
-        grid-template-columns: 1fr 340px;
+        grid-template-columns: minmax(0, 1fr) 340px;
         gap: 12px;
         margin-bottom: 16px;
     }
     @media (max-width: 900px) {
+        :root {
+            --explorer-map-height: clamp(360px, 58vh, 520px);
+        }
         .globe-layout { grid-template-columns: 1fr; }
     }
     #cesiumContainer {
         width: 100%;
-        min-height: 500px;
-        aspect-ratio: 4/3;
+        height: var(--explorer-map-height);
+        min-height: 0;
+        aspect-ratio: auto;
     }
     .side-panel {
         display: flex;
         flex-direction: column;
         gap: 8px;
-        max-height: 700px;
+        max-height: var(--explorer-map-height);
         overflow-y: auto;
     }
     .panel-section {
@@ -111,14 +121,20 @@ format:
         left: 36px;
         right: auto;
     }
-    .search-bar { display: flex; gap: 6px; margin-bottom: 6px; }
+    .explorer-controls {
+        display: flex;
+        flex-direction: column;
+        gap: 6px;
+        margin-bottom: 12px;
+    }
+    .search-bar { display: flex; gap: 6px; }
     .search-bar input {
         flex: 1; padding: 8px 12px; border: 1px solid #ccc; border-radius: 4px;
         font-size: 14px; outline: none;
     }
     .search-bar input:focus { border-color: #1565c0; box-shadow: 0 0 0 2px rgba(21,101,192,0.15); }
     .search-actions {
-        display: flex; gap: 6px; margin-bottom: 8px;
+        display: flex; gap: 6px;
     }
     .search-actions button {
         flex: 1; border: none; padding: 8px 12px; border-radius: 4px;
@@ -129,14 +145,28 @@ format:
     .search-actions #searchAreaBtn:hover { background: #e65100; }
     .search-actions #searchWorldBtn { background: #1565c0; }
     .search-actions #searchWorldBtn:hover { background: #0d47a1; }
-    .search-results { font-size: 12px; color: #666; padding: 4px 0; }
+    .search-help {
+        font-size: 11px;
+        color: #888;
+        line-height: 1.3;
+    }
+    .search-results {
+        font-size: 12px;
+        color: #666;
+        padding: 4px 0;
+        min-height: calc(2.7em + 8px);
+        max-height: calc(2.7em + 8px);
+        overflow-y: auto;
+        line-height: 1.35;
+    }
     .view-toolbar {
         display: flex;
         justify-content: space-between;
         align-items: center;
         gap: 12px;
-        margin: 10px 0 12px;
+        margin: 4px 0 0;
         flex-wrap: wrap;
+        min-height: 50px;
     }
     .view-toggle {
         display: inline-flex;
@@ -263,6 +293,7 @@ Circle size = log(sample count). Color = dominant data source.
 :::
 
 <!-- Static layout: globe + side panel. Updated via DOM, not OJS reactivity. -->
+<div class="explorer-controls">
 <div class="search-bar">
 <input type="text" id="sampleSearch" placeholder="Search samples — multiple words narrow results (e.g., pottery Cyprus)" />
 </div>
@@ -270,11 +301,11 @@ Circle size = log(sample count). Color = dominant data source.
 <button id="searchAreaBtn" type="button" title="Limit results to samples within the current map view">Search Selected Areas</button>
 <button id="searchWorldBtn" type="button" title="Search all samples globally">Search Entire World</button>
 </div>
-<div class="search-help" style="font-size: 11px; color: #888; padding: 2px 0 6px 0; line-height: 1.3;">
+<div class="search-help">
 Searches labels, descriptions, and place names. <strong>First search can take 10-15 seconds</strong> while data loads; subsequent searches are faster.
 <a href="https://github.com/isamplesorg/isamplesorg.github.io/issues/169" target="_blank" rel="noopener noreferrer" style="color: #888; text-decoration: underline;">Tracking issue: faster substrate FTS in progress</a>.
 </div>
-<div id="searchResults" class="search-results"></div>
+<div id="searchResults" class="search-results" aria-live="polite"></div>
 
 <div class="view-toolbar">
 <div class="view-toggle" role="group" aria-label="View mode">
@@ -286,6 +317,7 @@ Searches labels, descriptions, and place names. <strong>First search can take 10
 <input type="number" id="maxSamples" min="1000" max="100000" step="1000" value="25000">
 </div>
 </div>
+</div>
 
 <div class="globe-layout">
 <div id="cesiumContainer"></div>
diff --git a/tests/playwright/explorer-layout-stability.spec.js b/tests/playwright/explorer-layout-stability.spec.js
new file mode 100644
index 0000000..7cca50b
--- /dev/null
+++ b/tests/playwright/explorer-layout-stability.spec.js
@@ -0,0 +1,129 @@
+const { test, expect } = require('@playwright/test');
+
+const BASE_URL = process.env.TEST_URL || 'http://localhost:5860';
+const EXPLORER_PATH = '/explorer.html';
+
+const ALT_WORLD = 10000000;
+const ALT_POINT_CYPRUS = 62054;
+const LAT_CYPRUS = 34.9954;
+const LNG_CYPRUS = 33.7052;
+
+async function waitForPhaseMessage(page, substring, timeoutMs = 60000) {
+  return await page.waitForFunction(
+    (sub) => {
+      const el = document.getElementById('phaseMsg');
+      const text = el ? el.textContent : '';
+      return text.includes(sub) ? text.trim() : null;
+    },
+    substring,
+    { timeout: timeoutMs }
+  ).then(handle => handle.jsonValue());
+}
+
+async function waitForClusterBoot(page) {
+  await waitForPhaseMessage(page, 'clusters,');
+  await page.evaluate(async () => {
+    return await window._ojs.ojsConnector.mainModule.value('zoomWatcher');
+  });
+}
+
+async function waitForMode(page, expected, timeoutMs = 120000) {
+  await page.waitForFunction(
+    async (expectedMode) => {
+      const v = await window._ojs.ojsConnector.mainModule.value('viewer');
+      return v && v._globeState && v._globeState.mode === expectedMode;
+    },
+    expected,
+    { timeout: timeoutMs }
+  );
+}
+
+async function flyCameraTo(page, lat, lng, alt) {
+  await page.evaluate(async ({ lat, lng, alt }) => {
+    const v = await window._ojs.ojsConnector.mainModule.value('viewer');
+    v.scene.requestRenderMode = false;
+    v.camera.flyTo({
+      destination: Cesium.Cartesian3.fromDegrees(lng, lat, alt),
+      duration: 1.0,
+    });
+  }, { lat, lng, alt });
+}
+
+async function settleLayout(page) {
+  await page.evaluate(() => new Promise((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(resolve));
+  }));
+}
+
+async function elementRect(page, selector) {
+  await settleLayout(page);
+  return await page.locator(selector).evaluate((el) => {
+    const r = el.getBoundingClientRect();
+    return {
+      top: r.top,
+      height: r.height,
+    };
+  });
+}
+
+function expectRectStable(actual, expected, tolerance = 2) {
+  expect(Math.abs(actual.top - expected.top)).toBeLessThanOrEqual(tolerance);
+  expect(Math.abs(actual.height - expected.height)).toBeLessThanOrEqual(tolerance);
+}
+
+test.describe('explorer layout stability', () => {
+  test('desktop globe rect is stable across boot, status, point mode, and table round trip', async ({ page }) => {
+    await page.setViewportSize({ width: 1280, height: 900 });
+    await page.goto(`${BASE_URL}${EXPLORER_PATH}#v=1&lat=20&lng=0&alt=${ALT_WORLD}`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 60000,
+    });
+    await page.waitForSelector('#cesiumContainer', { timeout: 30000 });
+
+    const initialRect = await elementRect(page, '#cesiumContainer');
+    expect(Math.abs(initialRect.height - 585)).toBeLessThanOrEqual(2);
+
+    await waitForClusterBoot(page);
+    expectRectStable(await elementRect(page, '#cesiumContainer'), initialRect);
+
+    await page.locator('#searchResults').evaluate((el) => {
+      el.textContent = '50+ results for a deliberately long search status that wraps across two reserved lines';
+    });
+    expectRectStable(await elementRect(page, '#cesiumContainer'), initialRect);
+
+    await flyCameraTo(page, LAT_CYPRUS, LNG_CYPRUS, ALT_POINT_CYPRUS);
+    await waitForMode(page, 'point');
+    await waitForPhaseMessage(page, 'individual samples', 120000);
+    expectRectStable(await elementRect(page, '#cesiumContainer'), initialRect);
+
+    await page.locator('#tableViewBtn').click();
+    await expect(page.locator('.globe-layout')).toBeHidden();
+    await expect(page.locator('#tableContainer')).toBeVisible();
+    const tableRect = await elementRect(page, '#tableContainer');
+    expect(Math.abs(tableRect.top - initialRect.top)).toBeLessThanOrEqual(2);
+
+    await page.locator('#globeViewBtn').click();
+    await expect(page.locator('.globe-layout')).toBeVisible();
+    expectRectStable(await elementRect(page, '#cesiumContainer'), initialRect);
+  });
+
+  test('mobile globe height override is stable across boot and wrapped status', async ({ page }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await page.goto(`${BASE_URL}${EXPLORER_PATH}#v=1&lat=20&lng=0&alt=${ALT_WORLD}`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 60000,
+    });
+    await page.waitForSelector('#cesiumContainer', { timeout: 30000 });
+
+    const initialRect = await elementRect(page, '#cesiumContainer');
+    expect(Math.abs(initialRect.height - 489.52)).toBeLessThanOrEqual(2);
+
+    await waitForClusterBoot(page);
+    expectRectStable(await elementRect(page, '#cesiumContainer'), initialRect);
+
+    await page.locator('#searchResults').evaluate((el) => {
+      el.textContent = 'Search error: a long mobile status message that should scroll inside its reserved slot';
+    });
+    expectRectStable(await elementRect(page, '#cesiumContainer'), initialRect);
+  });
+});

From 5b12ed8941fd81f67e24ded2516c05616d69d9bd Mon Sep 17 00:00:00 2001
From: Raymond Yee <raymond.yee@gmail.com>
Date: Mon, 11 May 2026 11:40:31 -0700
Subject: [PATCH 2/3] Preserve explorer inline CSS as raw HTML

---
 explorer.qmd | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/explorer.qmd b/explorer.qmd
index 430f6ce..3992d3a 100644
--- a/explorer.qmd
+++ b/explorer.qmd
@@ -17,6 +17,7 @@ format:
         <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/vocab_labels.parquet">
 ---
 
+```{=html}
 <script src="https://cesium.com/downloads/cesiumjs/releases/1.127/Build/Cesium/Cesium.js"></script>
 <link href="https://cesium.com/downloads/cesiumjs/releases/1.127/Build/Cesium/Widgets/widgets.css" rel="stylesheet"></link>
 <style>
@@ -279,6 +280,7 @@ format:
     .facet-row.zero:hover { opacity: 0.65; }
     .facet-count.recomputing { opacity: 0.55; font-style: italic; }
 </style>
+```
 
 ::: {.callout-note collapse="true"}
 ## How It Works

From 561c0d2be5168ba69be39a658604e1ac0ef98068 Mon Sep 17 00:00:00 2001
From: Raymond Yee <raymond.yee@gmail.com>
Date: Mon, 11 May 2026 11:54:41 -0700
Subject: [PATCH 3/3] Widen explorer app layout

---
 explorer.qmd                                       | 8 ++++++++
 tests/playwright/explorer-layout-stability.spec.js | 3 +++
 2 files changed, 11 insertions(+)

diff --git a/explorer.qmd b/explorer.qmd
index 3992d3a..d26165f 100644
--- a/explorer.qmd
+++ b/explorer.qmd
@@ -23,10 +23,17 @@ format:
 <style>
     :root {
         --explorer-map-height: clamp(500px, 65vh, 680px);
+        --explorer-shell-width: min(1420px, calc(100vw - 64px));
     }
     html {
         scrollbar-gutter: stable;
     }
+    #quarto-document-content {
+        max-width: none;
+        width: var(--explorer-shell-width);
+        margin-left: 50%;
+        transform: translateX(-50%);
+    }
     div.cesium-topleft {
         display: block;
         position: absolute;
@@ -44,6 +51,7 @@ format:
     @media (max-width: 900px) {
         :root {
             --explorer-map-height: clamp(360px, 58vh, 520px);
+            --explorer-shell-width: calc(100vw - 32px);
         }
         .globe-layout { grid-template-columns: 1fr; }
     }
diff --git a/tests/playwright/explorer-layout-stability.spec.js b/tests/playwright/explorer-layout-stability.spec.js
index 7cca50b..08a365e 100644
--- a/tests/playwright/explorer-layout-stability.spec.js
+++ b/tests/playwright/explorer-layout-stability.spec.js
@@ -61,6 +61,7 @@ async function elementRect(page, selector) {
     const r = el.getBoundingClientRect();
     return {
       top: r.top,
+      width: r.width,
       height: r.height,
     };
   });
@@ -68,6 +69,7 @@ async function elementRect(page, selector) {
 
 function expectRectStable(actual, expected, tolerance = 2) {
   expect(Math.abs(actual.top - expected.top)).toBeLessThanOrEqual(tolerance);
+  expect(Math.abs(actual.width - expected.width)).toBeLessThanOrEqual(tolerance);
   expect(Math.abs(actual.height - expected.height)).toBeLessThanOrEqual(tolerance);
 }
 
@@ -81,6 +83,7 @@ test.describe('explorer layout stability', () => {
     await page.waitForSelector('#cesiumContainer', { timeout: 30000 });
 
     const initialRect = await elementRect(page, '#cesiumContainer');
+    expect(initialRect.width).toBeGreaterThanOrEqual(840);
     expect(Math.abs(initialRect.height - 585)).toBeLessThanOrEqual(2);
 
     await waitForClusterBoot(page);