explorer.qmd

---
title: "Interactive Explorer"
subtitle: "Search and explore 6.7 million material samples"
categories: [parquet, spatial, h3, performance, isamples]
sidebar: false
# No TOC: this page is an app, not an article. The right-hand TOC sidebar
# (#quarto-margin-sidebar) was overlapping .side-panel and silently
# intercepting clicks on the Source filter checkboxes — see issue #127.
toc: false
format:
  html:
    include-in-header:
      text: |
        <link rel="preconnect" href="https://data.isamples.org" crossorigin>
        <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/isamples_202601_h3_summary_res4.parquet">
        <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/isamples_202601_facet_summaries.parquet">
        <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>
    :root {
        /* Map is shorter now that the samples table is permanent below it
           (issue #200 / M-5). The grid sidebar tracks this height. */
        --explorer-map-height: clamp(400px, 50vh, 540px);
        --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;
        background: #00000099;
        color: white;
        height: auto;
        z-index: 999;
    }
    .globe-layout {
        display: grid;
        grid-template-columns: minmax(0, 1fr) 340px;
        gap: 12px;
        margin-bottom: 16px;
    }
    @media (max-width: 900px) {
        :root {
            --explorer-map-height: clamp(360px, 50vh, 480px);
            --explorer-shell-width: calc(100vw - 32px);
        }
        .globe-layout { grid-template-columns: 1fr; }
    }
    .map-wrap {
        position: relative;
        width: 100%;
    }
    #cesiumContainer {
        width: 100%;
        height: var(--explorer-map-height);
        min-height: 0;
        aspect-ratio: auto;
    }
    /* Slim top-right search overlay (Hana Figma node 222:456). The earlier
       multi-row treatment (M-1A, PR #200) ate ~480px × ~100px on the left
       side of the map; this collapses to one row at the right. The
       Cesium toolbar is still at top-left (left:5px), so positioning at
       top-right keeps both surfaces clear of each other. */
    .map-search-overlay {
        position: absolute;
        top: 8px;
        right: 8px;
        z-index: 1000;
        display: flex;
        align-items: center;
        gap: 4px;
        background: rgba(255, 255, 255, 0.94);
        backdrop-filter: blur(4px);
        padding: 0 4px;
        border-radius: 6px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
        height: 32px; /* slim row; Figma 222:456 target is ~28 + 4 chrome */
        box-sizing: border-box;
    }
    .map-search-overlay input[type="text"] {
        width: 260px;
        max-width: 100%;
        height: 24px;
        padding: 0 8px;
        border: 1px solid #ccc;
        border-radius: 4px;
        font-size: 13px;
        outline: none;
        background: white;
        box-sizing: border-box;
    }
    .map-search-overlay input[type="text"]:focus {
        border-color: #1565c0;
        box-shadow: 0 0 0 2px rgba(21, 101, 192, 0.15);
    }
    .map-search-overlay #searchSubmitBtn {
        background: #1565c0;
        color: white;
        border: none;
        width: 24px;
        height: 24px;
        border-radius: 4px;
        cursor: pointer;
        display: inline-flex;
        align-items: center;
        justify-content: center;
        padding: 0;
        font-size: 14px;
        box-sizing: border-box;
        flex-shrink: 0;
    }
    .map-search-overlay #searchSubmitBtn:hover { background: #0d47a1; }
    .map-search-overlay #searchSubmitBtn:focus-visible {
        outline: 2px solid #0d47a1;
        outline-offset: 2px;
    }
    /* Scope buttons + help paragraph are preserved in the DOM (handlers in
       zoomWatcher / search wiring bind by id) but hidden in the slim
       layout. Area-scoped search is still reachable via `?search_scope=area`
       URL hydration, which calls doSearch('area') on boot. */
    .map-search-overlay .search-actions,
    .map-search-overlay .search-help { display: none; }
    /* The aria-live results-count line sits just under the overlay at the
       same right edge. Hidden visually when empty so it doesn't add a
       blank strip; aria-live still announces. */
    .map-search-results-line {
        position: absolute;
        top: 46px;
        right: 8px;
        max-width: 340px;
        z-index: 1000;
        font-size: 12px;
        color: #333;
        background: rgba(255, 255, 255, 0.92);
        backdrop-filter: blur(4px);
        padding: 3px 8px;
        border-radius: 4px;
        box-shadow: 0 1px 4px rgba(0, 0, 0, 0.12);
    }
    .map-search-results-line:empty { display: none; }
    @media (max-width: 600px) {
        .map-search-overlay input[type="text"] { width: 160px; }
    }
    @media (max-width: 400px) {
        .map-search-overlay input[type="text"] { width: 120px; }
    }
    /* Display-only color legend at bottom-center of the map. The functional
       source filter (toggle/show-hide) lives in #sourceFilter in the side
       panel. aria-hidden="true" on this element keeps screen readers from
       reading the palette twice. Sits above Cesium's bottom-left credits. */
    .map-color-legend {
        position: absolute;
        bottom: 30px;
        left: 50%;
        transform: translateX(-50%);
        z-index: 1000;
        display: flex;
        gap: 14px;
        font-size: 12px;
        color: #333;
        background: rgba(255, 255, 255, 0.92);
        backdrop-filter: blur(4px);
        padding: 6px 12px;
        border-radius: 16px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
        pointer-events: none; /* never intercept globe interaction */
        white-space: nowrap;
    }
    .map-color-legend > span {
        display: inline-flex;
        align-items: center;
        gap: 4px;
    }
    .map-color-legend .map-color-legend-dot {
        width: 9px;
        height: 9px;
        border-radius: 50%;
        display: inline-block;
    }
    @media (max-width: 600px) {
        /* Below 600px the four-source row gets cramped — let it wrap and
           shrink the padding so it doesn't crowd the map. */
        .map-color-legend {
            flex-wrap: wrap;
            gap: 6px 10px;
            max-width: calc(100% - 24px);
            justify-content: center;
            font-size: 11px;
            padding: 4px 8px;
        }
    }
    .sidebar-search { display: flex; flex-direction: column; gap: 4px; }
    .sidebar-search input {
        width: 100%;
        padding: 7px 10px;
        border: 1px solid #ccc;
        border-radius: 4px;
        font-size: 13px;
        outline: none;
    }
    .sidebar-search input:focus { border-color: #1565c0; box-shadow: 0 0 0 2px rgba(21,101,192,0.15); }
    .sidebar-search-hint { font-size: 11px; color: #888; }
    .side-panel {
        display: flex;
        flex-direction: column;
        gap: 8px;
        max-height: var(--explorer-map-height);
        overflow-y: auto;
    }
    .panel-section {
        background: #f8f9fa;
        border-radius: 6px;
        padding: 12px;
        font-size: 13px;
    }
    .panel-section h4 { margin: 0 0 8px 0; font-size: 14px; }
    .stats-compact {
        display: grid;
        grid-template-columns: 1fr 1fr;
        gap: 6px;
    }
    .stat-box {
        background: #1a1a2e;
        color: white;
        padding: 8px 10px;
        border-radius: 4px;
        text-align: center;
    }
    .stat-box .val { font-weight: bold; font-size: 16px; font-family: monospace; display: block; }
    .stat-box .lbl { color: #aaa; font-size: 11px; }
    .legend { display: flex; gap: 8px; flex-wrap: wrap; font-size: 12px; }
    .legend-item { display: flex; align-items: center; gap: 3px; cursor: pointer; user-select: none; }
    .legend-item.disabled { opacity: 0.3; }
    .legend-dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; }
    .legend-item input[type="checkbox"] { margin: 0; width: 12px; height: 12px; cursor: pointer; }
    .source-badge { color: white; padding: 2px 8px; border-radius: 10px; font-size: 0.8em; white-space: nowrap; }
    .cluster-card { border-left: 4px solid #ccc; padding: 10px 12px; background: white; border-radius: 0 6px 6px 0; }
    .sample-row { padding: 6px 0; border-bottom: 1px solid #eee; line-height: 1.4; }
    .sample-row:last-child { border-bottom: none; }
    .sample-label { font-weight: 600; font-size: 13px; }
    .sample-desc { font-size: 12px; color: #555; margin-top: 2px; }
    .sample-meta { font-size: 11px; color: #888; margin-top: 2px; }
    .phase-msg { padding: 6px 10px; border-radius: 4px; font-size: 12px; transition: all 0.3s ease; }
    #clusterSection .empty-state { color: #999; text-align: center; padding: 20px; }
    .detail-loading { text-align: center; color: #999; padding: 8px; font-size: 12px; }
    .detail-link { color: #1565c0; text-decoration: none; font-size: 12px; }
    .detail-link:hover { text-decoration: underline; }
    .share-btn {
        background: #1565c0; color: white; border: none;
        padding: 10px 16px; border-radius: 6px;
        font-size: 14px; font-weight: 500; cursor: pointer;
        width: 100%;
    }
    .share-btn:hover { background: #0d47a1; }
    .share-toast { display: block; font-size: 12px; color: #2e7d32; opacity: 0; transition: opacity 0.3s; margin-top: 4px; text-align: center; }
    /* Cesium toolbar — relocate to top-left of globe (Hana mockup, #178) */
    .cesium-viewer-toolbar {
        top: 5px;
        left: 5px;
        right: auto !important;
        display: flex;
        flex-direction: column;
        gap: 4px;
        align-items: flex-start;
    }
    .cesium-viewer-toolbar > * { margin-left: 0 !important; }
    /* Open baseLayerPicker dropdown to the right since we're left-anchored.
       z-index must beat .map-search-overlay (1000) so the dropdown is not
       occluded by the in-map search controls. */
    .cesium-baseLayerPicker-dropDown {
        left: 36px;
        right: auto;
        z-index: 1100;
    }
    .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;
    }
    .search-actions button {
        flex: 1; border: none; padding: 8px 12px; border-radius: 4px;
        cursor: pointer; font-size: 13px; font-weight: 500; color: white;
        white-space: nowrap;
    }
    .search-actions #searchAreaBtn { background: #ef6c00; }
    .search-actions #searchAreaBtn:hover { background: #e65100; }
    .search-actions #searchWorldBtn { background: #1565c0; }
    .search-actions #searchWorldBtn:hover { background: #0d47a1; }
    .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;
    }
    #tableContainer {
        margin-bottom: 16px;
    }
    /* Stale-while-loading: dim the existing table to ~60% opacity while
       a new page or filter result is being fetched, so the user can see
       that the visible rows are not yet current. The CSS-animated spinner
       in #tableMeta provides the explicit "working" affordance. */
    #tableContainer.is-loading .samples-table {
        opacity: 0.6;
    }
    .samples-table { transition: opacity 0.15s ease; }
    .table-loading-spinner {
        display: inline-block;
        width: 12px;
        height: 12px;
        border: 2px solid #cfd8e3;
        border-top-color: #1565c0;
        border-radius: 50%;
        animation: tableSpin 0.8s linear infinite;
        vertical-align: -2px;
        margin-right: 6px;
    }
    @keyframes tableSpin { to { transform: rotate(360deg); } }
    @media (prefers-reduced-motion: reduce) {
        .table-loading-spinner { animation: none; border-top-color: #1565c0; }
    }
    .samples-section-heading {
        font-size: 15px;
        font-weight: 600;
        color: #234;
        margin: 18px 0 8px;
    }
    .samples-table tbody tr {
        cursor: pointer;
    }
    .samples-table tbody tr:hover {
        background: #f3f7fc;
    }
    .samples-table tbody tr.selected {
        background: #d8e8fa;
    }
    .samples-table tbody tr.selected:hover {
        background: #cfe1f7;
    }
    .table-meta {
        font-size: 12px;
        color: #555;
        margin: 4px 0 8px;
    }
    .table-scroll {
        overflow-x: auto;
        border: 1px solid #d8dee6;
        border-radius: 6px;
    }
    .samples-table {
        width: 100%;
        border-collapse: collapse;
        font-size: 12px;
        background: white;
    }
    .samples-table th, .samples-table td {
        padding: 7px 9px;
        border-bottom: 1px solid #edf0f4;
        text-align: left;
        vertical-align: top;
    }
    .samples-table th {
        background: #f6f8fb;
        color: #344;
        font-weight: 600;
        white-space: nowrap;
    }
    .samples-table tr:last-child td { border-bottom: 0; }
    .table-badge {
        color: white;
        padding: 2px 7px;
        border-radius: 10px;
        font-size: 10px;
        white-space: nowrap;
    }
    .table-link { color: #1565c0; text-decoration: none; }
    .table-link:hover { text-decoration: underline; }
    .table-pager {
        display: flex;
        justify-content: space-between;
        align-items: center;
        gap: 8px;
        margin-top: 8px;
        font-size: 12px;
        color: #555;
    }
    .table-pager button {
        background: #1565c0;
        color: white;
        border: 0;
        border-radius: 4px;
        padding: 5px 10px;
        cursor: pointer;
        font-size: 12px;
    }
    .table-pager button:disabled {
        background: #c7d2df;
        cursor: default;
    }
    .filter-section { border-top: 1px solid #eee; padding-top: 8px; margin-top: 8px; }
    .filter-header {
        font-size: 12px; font-weight: 600; color: #555; cursor: pointer;
        display: flex; justify-content: space-between; align-items: center;
        padding: 4px 0; user-select: none;
    }
    .filter-header:hover { color: #1565c0; }
    .filter-body { padding: 4px 0; }
    .filter-body label { display: block; font-size: 12px; padding: 2px 0; cursor: pointer; }
    .filter-body label:hover { color: #1565c0; }
    /* Cross-filter zero-count dimming. Don't hide unavailable values; keep
       them visible so users can understand the current filter context. */
    .facet-row.zero { opacity: 0.4; }
    .facet-row.zero:hover { opacity: 0.65; }
    .facet-count.recomputing { opacity: 0.55; font-style: italic; }
</style>
```

::: {.callout-note collapse="true"}
## How It Works

1. **Instant** (<1s): Pre-aggregated H3 res4 summary (580 KB) → 38K colored circles
2. **Zoom in**: Automatically switches to res6 (112K) then res8 (176K) clusters
3. **Zoom deeper** (<120 km): Individual sample points from 60 MB lite parquet
4. **Click**: Cluster info or individual sample card with full metadata
5. **Search**: Find samples by name — results fly to the location on the globe

Circle size = log(sample count). Color = dominant data source.
:::

<!-- Static layout: globe + side panel + permanent samples table. Updated via
     DOM, not OJS reactivity. Wrapped in `{=html}` raw-html fence because
     otherwise Quarto's Pandoc pass parses Markdown inside the HTML and wraps
     bare `<input>` / `<label>` in `<p>` tags, breaking flex layouts and
     adding paragraph margins to control rows. -->
```{=html}
<div class="globe-layout">
<div class="map-wrap">
<div id="cesiumContainer"></div>
<!-- Slim search overlay (Hana Figma 222:456). One-line input + magnifier
     button at the top-right of the map. The two scope buttons and the
     help paragraph are preserved in the DOM (display:none via CSS) so
     existing zoomWatcher handlers bind by id and the `?search_scope=area`
     URL hydration path still works — area-scoped search is no longer
     surfaced in the in-map UI but remains reachable via the URL. -->
<div class="map-search-overlay">
<input type="text" id="sampleSearch"
       placeholder="Search samples — e.g., pottery Cyprus"
       title="Searches labels, descriptions, and place names. First search can take 10-15 seconds while data loads; subsequent searches are faster. Press Enter or click the search button to submit." />
<button id="searchSubmitBtn" type="button" aria-label="Search samples" title="Search (Enter)">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="7"></circle><line x1="20" y1="20" x2="16.65" y2="16.65"></line></svg>
</button>
<!-- Preserved-but-hidden scope buttons: kept so existing zoomWatcher
     `searchAreaBtn.addEventListener('click', ...)` / `searchWorldBtn`
     bindings continue to compile and so any external code (tests,
     bookmarklets) that clicks them programmatically still works.
     `?search_scope=area` URL hydration does NOT depend on these — it
     sets `_searchScope` directly and the boot auto-search reads it. -->
<div class="search-actions" aria-hidden="true">
<button id="searchAreaBtn" type="button" tabindex="-1">Search Selected Areas</button>
<button id="searchWorldBtn" type="button" tabindex="-1">Search Entire World</button>
</div>
<div class="search-help" aria-hidden="true"></div>
</div>
<div id="searchResults" class="map-search-results-line" aria-live="polite"></div>
<div class="map-color-legend" aria-hidden="true">
<span><span class="map-color-legend-dot" style="background:#3366CC"></span>SESAR</span>
<span><span class="map-color-legend-dot" style="background:#DC3912"></span>OpenContext</span>
<span><span class="map-color-legend-dot" style="background:#109618"></span>GEOME</span>
<span><span class="map-color-legend-dot" style="background:#FF9900"></span>Smithsonian</span>
</div>
</div>
<div class="side-panel">
<div class="panel-section sidebar-search">
<input type="text" id="sampleSearchSidebar" placeholder="Search samples (press Enter to search globally)" aria-label="Search samples globally" />
<div class="sidebar-search-hint">Enter searches the entire world. Use the in-map controls for area-limited search.</div>
</div>
<div class="panel-section">
<div class="stats-compact">
<div class="stat-box"><span id="sPhase" class="val">Loading...</span><span class="lbl">Resolution</span></div>
<div class="stat-box"><span id="sPoints" class="val">0</span><span id="sPointsLbl" class="lbl">Clusters Loaded</span></div>
<div class="stat-box"><span id="sSamples" class="val">0</span><span id="sSamplesLbl" class="lbl">Samples Loaded</span></div>
<div class="stat-box"><span id="sTime" class="val">-</span><span class="lbl">Load Time</span></div>
</div>
<div style="margin-top: 8px;">
<div class="legend" id="sourceFilter">
<label class="legend-item facet-row" data-facet="source" data-value="SESAR"><input type="checkbox" value="SESAR" checked><span class="legend-dot" style="background:#3366CC"></span> SESAR <span class="facet-count" data-facet="source" data-value="SESAR" style="color:#888"></span></label>
<label class="legend-item facet-row" data-facet="source" data-value="OPENCONTEXT"><input type="checkbox" value="OPENCONTEXT" checked><span class="legend-dot" style="background:#DC3912"></span> OpenContext <span class="facet-count" data-facet="source" data-value="OPENCONTEXT" style="color:#888"></span></label>
<label class="legend-item facet-row" data-facet="source" data-value="GEOME"><input type="checkbox" value="GEOME" checked><span class="legend-dot" style="background:#109618"></span> GEOME <span class="facet-count" data-facet="source" data-value="GEOME" style="color:#888"></span></label>
<label class="legend-item facet-row" data-facet="source" data-value="SMITHSONIAN"><input type="checkbox" value="SMITHSONIAN" checked><span class="legend-dot" style="background:#FF9900"></span> Smithsonian <span class="facet-count" data-facet="source" data-value="SMITHSONIAN" style="color:#888"></span></label>
</div>
</div>
<div class="filter-section" id="materialFilter">
<div class="filter-header" onclick="this.nextElementSibling.style.display = this.nextElementSibling.style.display === 'none' ? 'block' : 'none'">
Material <span>▾</span>
</div>
<div class="filter-body" style="display: none;" id="materialFilterBody">
<em style="font-size: 11px; color: #999;">Loading...</em>
</div>
</div>
<div class="filter-section" id="contextFilter">
<div class="filter-header" onclick="this.nextElementSibling.style.display = this.nextElementSibling.style.display === 'none' ? 'block' : 'none'">
Sampled Feature <span>▾</span>
</div>
<div class="filter-body" style="display: none;" id="contextFilterBody">
<em style="font-size: 11px; color: #999;">Loading...</em>
</div>
</div>
<div class="filter-section" id="objectTypeFilter">
<div class="filter-header" onclick="this.nextElementSibling.style.display = this.nextElementSibling.style.display === 'none' ? 'block' : 'none'">
Specimen Type <span>▾</span>
</div>
<div class="filter-body" style="display: none;" id="objectTypeFilterBody">
<em style="font-size: 11px; color: #999;">Loading...</em>
</div>
</div>
<div id="facetNote" style="display: none; font-size: 11px; color: #888; margin-top: 4px; font-style: italic;">
Material / feature / specimen filters apply at sample zoom level — zoom in or click a cluster.
</div>
<div style="margin-top: 12px;">
<button id="shareBtn" class="share-btn" title="Copy link to current view">Copy Link to Current View</button>
<span id="shareToast" class="share-toast">Link copied!</span>
</div>
<div id="phaseMsg" class="phase-msg" style="margin-top: 8px; background: #e3f2fd; color: #1565c0;">
Loading H3 global overview...
</div>
</div>
<div id="clusterSection" class="panel-section">
<div class="empty-state">Click a cluster or sample on the globe</div>
</div>
<div id="samplesSection" class="panel-section" style="flex: 1; overflow-y: auto;"></div>
</div>
</div>

<h3 class="samples-section-heading">Samples table</h3>
<div id="tableContainer" aria-busy="false">
<div id="tableMeta" class="table-meta">Loading samples matching the current filters...</div>
<div id="samplesTable"></div>
<div class="table-pager">
<button id="tablePrev" type="button">Previous</button>
<span id="tablePageInfo"></span>
<button id="tableNext" type="button">Next</button>
</div>
</div>
```

```{ojs}
//| output: false
Cesium.Ion.defaultAccessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwNzk3NjkyMy1iNGI1LTRkN2UtODRiMy04OTYwYWE0N2M3ZTkiLCJpZCI6Njk1MTcsImlhdCI6MTYzMzU0MTQ3N30.e70dpNzOCDRLDGxRguQCC-tRzGzA-23Xgno5lNgCeB4';
```

```{ojs}
//| echo: false
//| output: false

// === Constants ===
R2_BASE = "https://data.isamples.org"
h3_res4_url = `${R2_BASE}/isamples_202601_h3_summary_res4.parquet`
h3_res6_url = `${R2_BASE}/isamples_202601_h3_summary_res6.parquet`
h3_res8_url = `${R2_BASE}/isamples_202601_h3_summary_res8.parquet`
lite_url = `${R2_BASE}/isamples_202601_samples_map_lite.parquet`
// Stable alias that 302-redirects to the current enriched wide parquet
// (isamples_YYYYMM_wide.parquet). Gets OpenContext thumbnails populated.
wide_url = `${R2_BASE}/current/wide.parquet`
// v2 carries object_type alongside material and context (URI-string columns).
facets_url = `${R2_BASE}/isamples_202601_sample_facets_v2.parquet`
facet_summaries_url = `${R2_BASE}/isamples_202601_facet_summaries.parquet`
// Pre-aggregated single-filter cache for fast cross-filtered facet counts.
cross_filter_url = `${R2_BASE}/isamples_202601_facet_cross_filter.parquet`
// SKOS prefLabels for Material / Sampled Feature / Specimen Type URIs.
// ~60 KB lookup; falls back to URI tail if a URI isn't covered.
vocab_labels_url = `${R2_BASE}/vocab_labels.parquet`

// Canonical palette — see issue #113. Path-relative so this works under
// both isamples.org (custom domain at root) and project-pages fork
// previews (rdhyee.github.io/isamplesorg.github.io/...).
_palette = await import(new URL('assets/js/source-palette.js', document.baseURI).href)
SOURCE_COLORS = _palette.SOURCE_COLORS
SOURCE_NAMES = _palette.SOURCE_NAMES

// === Source URL: resolve pid to original repository ===
function sourceUrl(pid) {
    if (!pid) return null;
    // All sources resolve via n2t.net:
    // ARK pids (OpenContext, GEOME, Smithsonian) → n2t.net/ark:/...
    // IGSN pids (SESAR) → n2t.net/IGSN:...
    return `https://n2t.net/${pid}`;
}

// === Source Filter: get active sources and build SQL clause ===
function getActiveSources() {
    const checks = document.querySelectorAll('#sourceFilter input[type="checkbox"]');
    return Array.from(checks).filter(c => c.checked).map(c => c.value);
}

function sourceFilterSQL(col) {
    const active = getActiveSources();
    if (active.length === 0) return ' AND 1=0';  // nothing checked = show nothing
    if (active.length === 4) return '';           // all checked = no filter
    const list = active.map(s => `'${s}'`).join(',');
    return ` AND ${col} IN (${list})`;
}

SOURCE_VALUES = ['SESAR', 'OPENCONTEXT', 'GEOME', 'SMITHSONIAN']
DEFAULT_POINT_BUDGET = 5000

// Disable per-primitive depth test below this camera distance (meters).
// All cluster and sample point primitives are placed at altitude=0 (ellipsoid
// surface). With Cesium world terrain enabled, terrain mesh in hilly regions
// (e.g. Troodos mountains in Cyprus, Birmingham AL hills) rises hundreds to
// thousands of meters above ellipsoid — making sea-level primitives
// physically underground and depth-culled by the standard per-pixel depth
// test (issue #185).
//
// Bypass scope: only when the camera is closer than 2,000 km, which covers
// every realistic interactive altitude (point mode <120 km, res8 cluster
// mode up to ~300 km, res6 up to ~3,000 km — the upper range is technically
// outside the bypass but at that altitude dots are tiny anyway, so this is
// where the existing pre-issue behavior is preserved).
//
// Why bounded (2.0e6) and not POSITIVE_INFINITY: PR #181 used Infinity and
// caused back-side-of-globe primitive bleed-through (the depth test was the
// only thing keeping points on the FAR hemisphere from rendering through
// the Earth). A 2,000 km bound preserves globe-ellipsoid occlusion at
// long range while bypassing terrain occlusion at every interactive zoom.
POINT_DEPTH_TEST_DISTANCE = 2.0e6

function csvParamValues(params, key) {
    if (!params.has(key)) return null;
    const raw = params.get(key) || '';
    if (raw.trim() === '') return [];
    return raw.split(',').map(s => s.trim()).filter(Boolean);
}

function updateSourceLegendState() {
    document.querySelectorAll('#sourceFilter .legend-item').forEach(li => {
        const cb = li.querySelector('input');
        li.classList.toggle('disabled', !cb.checked);
    });
}

function applyQueryToSourceFilter() {
    const params = new URLSearchParams(location.search);
    const initialSources = csvParamValues(params, 'sources');
    if (initialSources == null) return;
    const allowed = new Set(SOURCE_VALUES);
    const selected = new Set(initialSources.filter(s => allowed.has(s)));
    document.querySelectorAll('#sourceFilter input[type="checkbox"]').forEach(cb => {
        cb.checked = selected.has(cb.value);
    });
    updateSourceLegendState();
}

// URL param is `search`, not `q` — Quarto's site-wide search hijacks `?q=`
// (highlights matches and strips the param via replaceState).
// See docs/site_libs/quarto-search/quarto-search.js.
function applyQueryToSearch() {
    const input = document.getElementById('sampleSearch');
    const sidebarInput = document.getElementById('sampleSearchSidebar');
    if (!input && !sidebarInput) return;
    const params = new URLSearchParams(location.search);
    const q = params.get('search');
    if (q != null) {
        if (input) input.value = q;
        if (sidebarInput) sidebarInput.value = q;
    }
}

function setCheckedValues(containerId, values) {
    if (values == null) return;
    const selected = new Set(values);
    document.querySelectorAll(`#${containerId} input[type="checkbox"]`).forEach(cb => {
        cb.checked = selected.has(cb.value);
    });
}

function applyQueryToFacetFilters() {
    const params = new URLSearchParams(location.search);
    setCheckedValues('materialFilterBody', csvParamValues(params, 'material'));
    setCheckedValues('contextFilterBody', csvParamValues(params, 'context'));
    setCheckedValues('objectTypeFilterBody', csvParamValues(params, 'object_type'));
}


function writeQueryState() {
    const params = new URLSearchParams(location.search);
    const searchInput = document.getElementById('sampleSearch');
    const q = searchInput ? searchInput.value.trim() : '';
    if (q) params.set('search', q);
    else params.delete('search');

    const activeSources = getActiveSources();
    if (activeSources.length === SOURCE_VALUES.length) params.delete('sources');
    else params.set('sources', activeSources.join(','));

    [
        ['material', 'materialFilterBody'],
        ['context', 'contextFilterBody'],
        ['object_type', 'objectTypeFilterBody'],
    ].forEach(([key, containerId]) => {
        const values = getCheckedValues(containerId);
        if (values.length > 0) params.set(key, values.join(','));
        else params.delete(key);
    });

    // Canonicalize away the legacy `view` param (issue #200 / M-5 removed
    // the Globe/Table toggle). A bookmarked `?view=table&...` URL would
    // otherwise stick through filter/share flows.
    params.delete('view');

    const qs = params.toString();
    const url = `${location.pathname}${qs ? `?${qs}` : ''}${location.hash}`;
    if (url !== `${location.pathname}${location.search}${location.hash}`) {
        history.replaceState(null, '', url);
    }
}

function searchTerms(value) {
    return String(value || '').trim().split(/\s+/).filter(Boolean);
}

function escapeIlikePattern(value) {
    return escSql(value).replace(/[\\%_]/g, "\\$&");
}

function textSearchWhere(terms, columns) {
    return terms.map(raw => {
        const term = escapeIlikePattern(raw);
        const checks = columns.map(col => `${col} ILIKE '%${term}%' ESCAPE '\\'`);
        return `(${checks.join(' OR ')})`;
    }).join(' AND ');
}

function textSearchScore(terms, weightedColumns) {
    if (!terms.length) return '0';
    return terms.map(raw => {
        const term = escapeIlikePattern(raw);
        return weightedColumns.map(({ col, weight }) =>
            `CASE WHEN ${col} ILIKE '%${term}%' ESCAPE '\\' THEN ${weight} ELSE 0 END`
        ).join(' + ');
    }).map(score => `(${score})`).join(' + ');
}

// === Material / Sampled Feature / Specimen Type Filters ===
// Checkbox semantics: start UNCHECKED (no filter; show everything). User
// checks items to *include only those*. Empty = no filter. Matches the
// explorer's URI-valued facet UX — with hundreds of materials, defaulting
// to "all checked" would be unusable, and "empty = no filter" is the
// natural reading. See issue #155.
function getCheckedValues(containerId) {
    const checks = document.querySelectorAll(`#${containerId} input[type="checkbox"]`);
    return Array.from(checks).filter(c => c.checked).map(c => c.value);
}

function hasFacetFilters() {
    return getCheckedValues('materialFilterBody').length > 0
        || getCheckedValues('contextFilterBody').length > 0
        || getCheckedValues('objectTypeFilterBody').length > 0;
}

function escSql(value) {
    return String(value).replace(/'/g, "''");
}

// Returns a portable predicate fragment (no outer-table alias dependency)
// that callers append to a WHERE: ` AND ${facetFilterSQL()}`. Uses a
// `pid IN (SELECT pid FROM facets WHERE ...)` subquery so it works
// without a JOIN and avoids duplicate rows from multi-valued facets
// (a sample with two materials would appear twice via JOIN). Required
// for Phase 4's table mode and any non-JOIN caller. See issue #156.
function facetFilterSQL() {
    const mat = getCheckedValues('materialFilterBody');
    const ctx = getCheckedValues('contextFilterBody');
    const ot  = getCheckedValues('objectTypeFilterBody');

    const conds = [];
    if (mat.length > 0) {
        const list = mat.map(s => `'${escSql(s)}'`).join(',');
        conds.push(`material IN (${list})`);
    }
    if (ctx.length > 0) {
        const list = ctx.map(s => `'${escSql(s)}'`).join(',');
        conds.push(`context IN (${list})`);
    }
    if (ot.length > 0) {
        const list = ot.map(s => `'${escSql(s)}'`).join(',');
        conds.push(`object_type IN (${list})`);
    }
    if (conds.length === 0) return '';
    return ` AND pid IN (SELECT DISTINCT pid FROM read_parquet('${facets_url}') WHERE ${conds.join(' AND ')})`;
}

// Shared viewport-padding factor. The samples table (PR #219), the
// point-mode sample loader, and the cluster-mode "Samples in View"
// stat (issue #221 round 2) all expand the raw view rectangle by this
// factor so the three surfaces agree on a single "in view" predicate.
// Pass 0 (or undefined) for exact-viewport semantics (area search).
// OJS cell syntax (bare `name = value`); `const` here would not bind
// the name into the OJS module scope and would break every dependent
// cell (issue #223 quick-fix).
VIEWPORT_PAD_FACTOR = 0.3

// Return the viewer's current view rectangle, optionally padded in each
// direction by `padFactor × span`, normalized into [-180, 180] longitude
// (wrapping the antimeridian when needed). Returns null when the camera
// can't produce a rectangle (off-globe; rare).
//
// Dateline crossing: when the returned `west > east` the rectangle
// wraps the antimeridian; callers that filter sample longitudes must
// split on that boundary.
//
// Normalization after padding:
//   - Total span >= 360 → padding consumed the globe; return west=-180,
//     east=180 (no wrap).
//   - west < -180 or east > 180 → rotate the endpoint by 360 so it
//     lands in [-180, 180]. A non-wrapping rect like west=170, east=179
//     padded 30% becomes (167.3, 181.7); east wraps to -178.3 and the
//     `west > east` flag flips on.
function paddedViewportBounds(padFactor) {
    if (typeof viewer === 'undefined') return null;
    const rect = viewer.camera.computeViewRectangle(viewer.scene.globe.ellipsoid);
    if (!rect) return null;
    let south = Cesium.Math.toDegrees(rect.south);
    let north = Cesium.Math.toDegrees(rect.north);
    let west = Cesium.Math.toDegrees(rect.west);
    let east = Cesium.Math.toDegrees(rect.east);
    if (padFactor && padFactor > 0) {
        const latPad = (north - south) * padFactor;
        // Original longitude span. Wraps the antimeridian iff west > east.
        const originalSpan = (west > east) ? (180 - west) + (east + 180) : east - west;
        const lngPad = originalSpan * padFactor;
        south -= latPad;
        north += latPad;
        west -= lngPad;
        east += lngPad;
        if (south < -90) south = -90;
        if (north > 90) north = 90;
        const totalSpan = originalSpan + 2 * lngPad;
        if (totalSpan >= 360) {
            west = -180; east = 180;
        } else {
            if (west < -180) west += 360;
            if (east > 180) east -= 360;
        }
    }
    return { south, north, west, east };
}

// Build a viewport-bbox SQL predicate for the given lat/lng column names.
// Returns null when the camera can't produce a rectangle (off-globe; rare).
// Callers must decide what to do with null — fall back to world (search)
// vs. show empty state (table). NEVER fall back to no-bbox-filter for
// surfaces that are labeled "in view" — that recreates the bug shape
// PR #219 was filed for.
//
// Used by:
// - tableView (PR #219): scopes the samples table to the current viewport
//   so "samples in view" in cluster/point mode == table row count.
// - doSearch('area') (#178 light path): exact-viewport text search.
function viewerBboxSQL(latCol, lngCol, padFactor) {
    const b = paddedViewportBounds(padFactor);
    if (!b) return null;
    const { south, north, west, east } = b;
    const lngClause = (west > east)
        ? `(${lngCol} BETWEEN ${west} AND 180 OR ${lngCol} BETWEEN -180 AND ${east})`
        : `${lngCol} BETWEEN ${west} AND ${east}`;
    return ` AND ${latCol} BETWEEN ${south} AND ${north} AND ${lngClause}`;
}

// === Cross-filter facet count UI helpers ===
function applyFacetCounts(facetKey, countsMap) {
    const baseline = (viewer && viewer._baselineCounts) ? viewer._baselineCounts[facetKey] : null;
    document.querySelectorAll(`.facet-count[data-facet="${facetKey}"]`).forEach(el => {
        const value = el.getAttribute('data-value');
        let count;
        if (countsMap) {
            count = countsMap.has(value) ? countsMap.get(value) : 0;
        } else {
            count = baseline ? (baseline.get(value) ?? 0) : 0;
        }
        el.textContent = `(${Number(count).toLocaleString()})`;
        el.classList.remove('recomputing');

        const row = document.querySelector(`.facet-row[data-facet="${facetKey}"][data-value="${CSS.escape(value)}"]`);
        if (row) row.classList.toggle('zero', count === 0);
    });
}

function markFacetCountsRecomputing() {
    document.querySelectorAll('.facet-count').forEach(el => el.classList.add('recomputing'));
}

// === URL State: encode/decode globe state in hash fragment ===
function parseNum(val, def, min, max) {
    if (val == null) return def;
    const n = parseFloat(val);
    if (!Number.isFinite(n)) return def;
    if (min != null && n < min) return min;
    if (max != null && n > max) return max;
    return n;
}

function readHash() {
    const params = new URLSearchParams(location.hash.slice(1));
    return {
        v: parseInt(params.get('v')) || 0,
        lat: parseNum(params.get('lat'), null, -90, 90),
        lng: parseNum(params.get('lng'), null, -180, 180),
        alt: parseNum(params.get('alt'), null, 100, 40000000),
        heading: parseNum(params.get('heading'), 0, 0, 360),
        pitch: parseNum(params.get('pitch'), -90, -90, 0),
        mode: params.get('mode') || null,
        pid: params.get('pid') || null,
        h3: params.get('h3') || null,
    };
}

function buildHash(v) {
    const cam = v.camera;
    const carto = cam.positionCartographic;
    const params = new URLSearchParams();
    params.set('v', '1');
    params.set('lat', Cesium.Math.toDegrees(carto.latitude).toFixed(4));
    params.set('lng', Cesium.Math.toDegrees(carto.longitude).toFixed(4));
    params.set('alt', Math.round(carto.height).toString());
    const heading = Cesium.Math.toDegrees(cam.heading) % 360;
    const pitch = Cesium.Math.toDegrees(cam.pitch);
    if (Math.abs(heading) > 1) params.set('heading', heading.toFixed(1));
    if (Math.abs(pitch + 90) > 1) params.set('pitch', pitch.toFixed(1));
    const gs = v._globeState;
    if (gs.mode === 'point') params.set('mode', 'point');
    // pid and h3 are mutually exclusive at runtime; emit at most one. Sample
    // selection (pid) wins if somehow both are set — matches the hydration
    // priority in the hashchange handler.
    if (gs.selectedPid) params.set('pid', gs.selectedPid);
    else if (gs.selectedH3) params.set('h3', gs.selectedH3);
    return '#' + params.toString();
}

// === Selection freshness primitive ===
//
// Async work that updates `viewer._globeState`, the URL hash, or the side
// panel must check freshness after every await. A user input (click,
// hashchange, source-filter toggle, boot deep-link) bumps `_selGen`; any
// in-flight async work whose generation no longer matches must NOT mutate
// anything that an interactive newer event has already moved.
//
// Usage:
//   const isStale = freshSelectionToken(viewer);
//   await someWork();
//   if (isStale()) return;
//   updateDOM();
//
// Pass `isStale` into helpers (see hydrateClusterUI) so their internal
// awaits also bail before touching DOM. Top-level so both the viewer-cell
// click handler and the zoomWatcher-cell handlers can reach it. See issue
// #187 for the post-mortem that motivated extracting this primitive.
function freshSelectionToken(v) {
    v._selGen = (v._selGen || 0) + 1;
    const gen = v._selGen;
    return () => gen !== v._selGen;
}

// === Helpers: update DOM imperatively (no OJS reactivity) ===
function updateStats(phase, points, samples, time, pointsLabel, samplesLabel) {
    const s = (id, v) => { const e = document.getElementById(id); if (e) e.textContent = v; };
    s('sPhase', phase);
    s('sPoints', typeof points === 'string' ? points : points.toLocaleString());
    s('sSamples', typeof samples === 'string' ? samples : samples.toLocaleString());
    if (time != null) s('sTime', time);
    if (pointsLabel) s('sPointsLbl', pointsLabel);
    if (samplesLabel) s('sSamplesLbl', samplesLabel);
}

function updatePhaseMsg(text, type) {
    const m = document.getElementById('phaseMsg');
    if (!m) return;
    m.textContent = text;
    if (type === 'loading') { m.style.background = '#e3f2fd'; m.style.color = '#1565c0'; }
    else { m.style.background = '#e8f5e9'; m.style.color = '#2e7d32'; }
}

function updateClusterCard(info) {
    const el = document.getElementById('clusterSection');
    if (!el) return;
    if (!info) {
        el.innerHTML = '<div class="empty-state">Click a cluster or sample on the globe</div>';
        return;
    }
    const color = SOURCE_COLORS[info.source] || '#666';
    const name = SOURCE_NAMES[info.source] || info.source;
    el.innerHTML = `<h4>Selected Cluster</h4>
        <div class="cluster-card" style="border-left-color: ${color}">
            <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 6px;">
                <span class="source-badge" style="background: ${color}">${name}</span>
                <span style="font-size: 11px; color: #999;">H3 res${info.resolution}</span>
            </div>
            <div style="font-size: 22px; font-weight: bold; margin-bottom: 4px;">
                ${info.count.toLocaleString()} <span style="font-size: 13px; font-weight: normal; color: #666;">samples</span>
            </div>
            <div style="font-size: 12px; color: #666;">
                ${info.lat.toFixed(4)}, ${info.lng.toFixed(4)}
            </div>
        </div>`;
}

function updateSampleCard(sample) {
    const el = document.getElementById('clusterSection');
    if (!el) return;
    const color = SOURCE_COLORS[sample.source] || '#666';
    const name = SOURCE_NAMES[sample.source] || sample.source;
    const placeParts = sample.place_name;
    const placeStr = Array.isArray(placeParts) && placeParts.length > 0
        ? placeParts.filter(Boolean).join(' › ')
        : '';
    const srcUrl = sourceUrl(sample.pid);
    el.innerHTML = `<h4>Sample</h4>
        <div class="cluster-card" style="border-left-color: ${color}">
            <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 6px;">
                <span class="source-badge" style="background: ${color}">${name}</span>
            </div>
            <div style="font-size: 15px; font-weight: bold; margin-bottom: 4px;">
                ${sample.label || sample.pid || 'Unnamed'}
            </div>
            <div style="font-size: 12px; color: #666; margin-bottom: 4px;">
                ${sample.lat.toFixed(5)}, ${sample.lng.toFixed(5)}
            </div>
            ${placeStr ? `<div style="font-size: 12px; color: #555; margin-bottom: 4px;">${placeStr}</div>` : ''}
            ${sample.result_time ? `<div style="font-size: 11px; color: #888;">Date: ${sample.result_time}</div>` : ''}
            ${srcUrl ? `<div style="margin-top: 4px;"><a class="detail-link" href="${srcUrl}" target="_blank" rel="noopener noreferrer">View at ${name} →</a></div>` : ''}
            <div id="sampleDetail" class="detail-loading">Loading full details...</div>
        </div>`;
}

function updateSampleDetail(detail) {
    const el = document.getElementById('sampleDetail');
    if (!el) return;
    if (!detail) {
        el.innerHTML = '<span style="color: #c62828; font-size: 12px;">Detail query failed</span>';
        return;
    }
    const desc = detail.description
        ? (detail.description.length > 300 ? detail.description.slice(0, 300) + '...' : detail.description)
        : '';
    el.innerHTML = `${desc ? `<div style="font-size: 12px; color: #444; margin-top: 6px; line-height: 1.4;">${desc}</div>` : ''}`;
}

function updateSamples(samples) {
    const el = document.getElementById('samplesSection');
    if (!el) return;
    if (!samples || samples.length === 0) {
        el.innerHTML = '';
        return;
    }
    let h = `<h4>Nearby Samples (${samples.length})</h4>`;
    for (const s of samples) {
        const color = SOURCE_COLORS[s.source] || '#666';
        const name = SOURCE_NAMES[s.source] || s.source;
        const placeParts = s.place_name;
        const desc = Array.isArray(placeParts) && placeParts.length > 0
            ? placeParts.filter(Boolean).join(' › ')
            : '';
        const sUrl = sourceUrl(s.pid);
        h += `<div class="sample-row">
            <div style="display: flex; align-items: center; gap: 6px;">
                ${sUrl ? `<a class="sample-label" href="${sUrl}" target="_blank" rel="noopener noreferrer" style="color: #1565c0; text-decoration: none;">${s.label || s.pid}</a>` : `<span class="sample-label">${s.label || s.pid}</span>`}
                <span class="source-badge" style="background: ${color}; font-size: 10px;">${name}</span>
            </div>
            ${desc ? `<div class="sample-desc">${desc}</div>` : ''}
        </div>`;
    }
    el.innerHTML = h;
}

// === Samples table (permanent below globe; M-5) ===
// Server-side pagination via DuckDB LIMIT/OFFSET (table v2, #200 follow-up).
// Previously the table loaded up to 25,000-100,000 rows up-front and sliced
// client-side; now each page is a fresh DuckDB query, and a COUNT(*) is
// issued on filter change so the pager knows the total. The deterministic
// ORDER BY pid makes "Page N is the same N rows" actually true.
TABLE_PAGE_SIZE = 100

function escapeHtml(value) {
    return String(value ?? '')
        .replace(/&/g, '&amp;')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;')
        .replace(/"/g, '&quot;')
        .replace(/'/g, '&#39;');
}

```

```{ojs}
//| echo: false
//| output: false

// === DuckDB ===
db = {
    performance.mark('duckdb-init-start');
    const instance = await DuckDBClient.of();
    performance.mark('duckdb-init-end');
    performance.measure('duckdb_init', 'duckdb-init-start', 'duckdb-init-end');
    return instance;
}
```

```{ojs}
//| echo: false
//| output: false

// === Cesium Viewer (created once, never re-created) ===
viewer = {
    performance.mark('viewer-init-start');
    const v = new Cesium.Viewer("cesiumContainer", {
        timeline: false,
        animation: false,
        baseLayerPicker: true,
        fullscreenElement: "cesiumContainer",
        terrain: Cesium.Terrain.fromWorldTerrain()
    });

    // URL deep-link state (must be set before globalRect/once block reads it)
    v._globeState = { mode: 'cluster', selectedPid: null, selectedH3: null };
    v._initialHash = readHash();
    v._suppressHashWrite = true;  // cleared after zoomWatcher initializes
    v._suppressTimer = null;

    const globalRect = Cesium.Rectangle.fromDegrees(-180, -60, 180, 80);
    Cesium.Camera.DEFAULT_VIEW_RECTANGLE = globalRect;
    Cesium.Camera.DEFAULT_VIEW_FACTOR = 0.5;
    const ih = v._initialHash;
    const once = () => {
        if (ih.lat != null && ih.lng != null) {
            v.camera.setView({
                destination: Cesium.Cartesian3.fromDegrees(ih.lng, ih.lat, ih.alt || 20000000),
                orientation: {
                    heading: Cesium.Math.toRadians(ih.heading),
                    pitch: Cesium.Math.toRadians(ih.pitch)
                }
            });
        } else {
            v.camera.setView({ destination: globalRect });
        }
        // Signal to dependent cells (e.g. tableView) that the URL-hydrated
        // camera position has been applied. Anything that snapshots the
        // viewer bbox at boot should wait for this rather than running
        // against the default-constructed camera.
        v._initialCameraApplied = true;
        v.scene.postRender.removeEventListener(once);
    };
    v.scene.postRender.addEventListener(once);

    // Two separate point collections: clusters and individual samples
    v.h3Points = new Cesium.PointPrimitiveCollection();
    v.scene.primitives.add(v.h3Points);

    v.samplePoints = new Cesium.PointPrimitiveCollection();
    v.scene.primitives.add(v.samplePoints);
    v.samplePoints.show = false; // hidden until point mode

    // Hover tooltip — works for both clusters and samples
    v.pointLabel = v.entities.add({
        label: {
            show: false, showBackground: true, font: "13px monospace",
            horizontalOrigin: Cesium.HorizontalOrigin.LEFT,
            verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
            pixelOffset: new Cesium.Cartesian2(15, 0),
            disableDepthTestDistance: Number.POSITIVE_INFINITY, text: "",
        }
    });

    new Cesium.ScreenSpaceEventHandler(v.scene.canvas).setInputAction((movement) => {
        const picked = v.scene.pick(movement.endPosition);
        if (Cesium.defined(picked) && picked.primitive && picked.id) {
            v.pointLabel.position = picked.primitive.position;
            v.pointLabel.label.show = true;
            const meta = picked.id;
            if (typeof meta === 'object' && meta.type === 'sample') {
                v.pointLabel.label.text = `${meta.label || meta.pid}`;
            } else if (typeof meta === 'object' && meta.count) {
                v.pointLabel.label.text = `${meta.source}: ${meta.count.toLocaleString()} samples`;
            } else {
                v.pointLabel.label.text = String(meta);
            }
        } else {
            v.pointLabel.label.show = false;
        }
    }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);

    // Click handler — routes to cluster card or sample card.
    // Uses freshSelectionToken so a slow detail/nearby fetch doesn't repaint
    // the side panel after the user has clicked a different sample/cluster.
    new Cesium.ScreenSpaceEventHandler(v.scene.canvas).setInputAction(async (e) => {
        const picked = v.scene.pick(e.position);
        if (!Cesium.defined(picked) || !picked.primitive || !picked.id) return;
        const meta = picked.id;
        const isStale = freshSelectionToken(v);

        if (typeof meta === 'object' && meta.type === 'sample') {
            // --- Individual sample click ---
            updateSampleCard(meta);
            v._globeState.selectedPid = meta.pid;
            v._globeState.selectedH3 = null;
            history.pushState(null, '', buildHash(v));
            // Clear nearby list
            const sampEl = document.getElementById('samplesSection');
            if (sampEl) sampEl.innerHTML = '';

            // Stage 2: lazy-load full description from wide parquet
            try {
                const detail = await db.query(`
                    SELECT description
                    FROM read_parquet('${wide_url}')
                    WHERE pid = '${meta.pid.replace(/'/g, "''")}'
                    LIMIT 1
                `);
                if (isStale()) return;
                if (detail && detail.length > 0) {
                    updateSampleDetail(detail[0]);
                } else {
                    updateSampleDetail({ description: '' });
                }
            } catch(err) {
                if (isStale()) return;
                console.error("Detail query failed:", err);
                updateSampleDetail(null);
            }

        } else if (typeof meta === 'object' && meta.count) {
            // --- Cluster click ---
            updateClusterCard(meta);
            v._globeState.selectedPid = null;
            v._globeState.selectedH3 = meta.h3_cell || null;
            history.pushState(null, '', buildHash(v));

            const sampEl = document.getElementById('samplesSection');
            if (sampEl) sampEl.innerHTML = '<div style="text-align: center; color: #999; padding: 12px;">Loading nearby samples...</div>';

            const delta = meta.resolution === 4 ? 2.0 : meta.resolution === 6 ? 0.5 : 0.1;
            try {
                // facetFilterSQL() returns a portable `pid IN (...)` predicate,
                // so the same query works whether or not facet filters are active.
                const nearbyQuery = `
                    SELECT pid, label, source, latitude, longitude, place_name
                    FROM read_parquet('${lite_url}')
                    WHERE latitude BETWEEN ${meta.lat - delta} AND ${meta.lat + delta}
                      AND longitude BETWEEN ${meta.lng - delta} AND ${meta.lng + delta}
                      ${sourceFilterSQL('source')}
                      ${facetFilterSQL()}
                    LIMIT 30
                `;
                const samples = await db.query(nearbyQuery);
                if (isStale()) return;
                updateSamples(samples);
            } catch(err) {
                if (isStale()) return;
                console.error("Sample query failed:", err);
                if (sampEl) sampEl.innerHTML = '<div style="color: #c62828; padding: 12px;">Query failed — try again.</div>';
            }
        }
    }, Cesium.ScreenSpaceEventType.LEFT_CLICK);

    // Timing: viewer ready (mount complete, pre-first-render)
    performance.mark('viewer-init-end');
    performance.measure('viewer_init', 'viewer-init-start', 'viewer-init-end');

    // Timing: first Cesium frame painted (globe visible, may be pre-cluster)
    const firstGlobeFrame = () => {
        performance.mark('first-globe-frame');
        v.scene.postRender.removeEventListener(firstGlobeFrame);
    };
    v.scene.postRender.addEventListener(firstGlobeFrame);

    return v;
}
```

```{ojs}
//| echo: false
//| output: false

// === PHASE 1: Load H3 res4 globally (instant) ===
phase1 = {
    performance.mark('p1-start');
    applyQueryToSearch();
    applyQueryToSourceFilter();

    const data = await db.query(`
        SELECT CAST(h3_cell AS VARCHAR) AS h3_cell_dec,
               sample_count, center_lat, center_lng,
               dominant_source, source_count
        FROM read_parquet('${h3_res4_url}')
        WHERE 1=1${sourceFilterSQL('dominant_source')}
    `);

    const scalar = new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.5);
    let totalSamples = 0;

    for (const row of data) {
        const count = row.sample_count;
        totalSamples += count;
        const size = Math.min(3 + Math.log10(count) * 4, 20);
        // h3_cell is UBIGINT (>2^53 for typical H3 indices). DuckDB-WASM
        // returns UBIGINT as a JS Number, losing precision in toString(16).
        // SELECT casts to VARCHAR (decimal); convert to hex via BigInt here.
        const h3Hex = BigInt(row.h3_cell_dec).toString(16);
        viewer.h3Points.add({
            id: { h3_cell: h3Hex, count, source: row.dominant_source, lat: row.center_lat, lng: row.center_lng, resolution: 4 },
            position: Cesium.Cartesian3.fromDegrees(row.center_lng, row.center_lat, 0),
            pixelSize: size,
            color: Cesium.Color.fromCssColorString(SOURCE_COLORS[row.dominant_source] || '#666').withAlpha(0.8),
            outlineColor: Cesium.Color.WHITE,
            outlineWidth: 1.5,
            scaleByDistance: scalar,
            disableDepthTestDistance: POINT_DEPTH_TEST_DISTANCE,  // issue #185
        });
    }

    // Cache cluster data for viewport counting
    viewer._clusterData = Array.from(data);
    viewer._clusterTotal = { clusters: data.length, samples: totalSamples };

    performance.mark('p1-end');
    performance.measure('p1', 'p1-start', 'p1-end');
    const elapsed = performance.getEntriesByName('p1').pop().duration;

    updateStats('H3 Res4', data.length, totalSamples, `${(elapsed/1000).toFixed(1)}s`, 'Clusters Loaded', 'Samples Loaded');
    updatePhaseMsg(`${data.length.toLocaleString()} clusters, ${totalSamples.toLocaleString()} samples. Zoom in for finer detail.`, 'done');
    console.log(`Phase 1: ${data.length} clusters in ${elapsed.toFixed(0)}ms`);

    return { count: data.length, samples: totalSamples };
}
```

```{ojs}
//| echo: false
//| output: false

// === Load facet summaries + SKOS prefLabels, populate filter checkboxes ===
//
// Checkbox value = full URI (matches the URI strings stored in
// sample_facets_v2.parquet's material / context / object_type columns).
// Display label = SKOS prefLabel (en) when available, URI tail otherwise.
// Default state: UNCHECKED — empty = no filter.
facetFilters = {
    if (!phase1) return;

    // Tiny URI → prefLabel lookup. ~60 KB. Best-effort: fallback to URI tail.
    const vocabMap = new Map();
    try {
        const vocab = await db.query(
            `SELECT uri, pref_label FROM read_parquet('${vocab_labels_url}') WHERE lang = 'en'`
        );
        for (const r of vocab) vocabMap.set(r.uri, r.pref_label);
    } catch (err) {
        console.warn("vocab_labels load failed; falling back to URI tails:", err);
    }
    const prettyLabel = (uri) => {
        if (uri == null) return "";
        const hit = vocabMap.get(uri);
        if (hit) return hit;
        const s = String(uri);
        if (!/^https?:\/\//.test(s)) return s;
        const parts = s.replace(/[#?].*$/, "").split("/").filter(Boolean);
        return parts.length ? parts[parts.length - 1] : s;
    };

    try {
        const summaries = await db.query(`
            SELECT facet_type, facet_value, count
            FROM read_parquet('${facet_summaries_url}')
            ORDER BY facet_type, count DESC
        `);

        const grouped = { source: [], material: [], context: [], object_type: [] };
        for (const row of summaries) {
            if (grouped[row.facet_type]) {
                grouped[row.facet_type].push({
                    uri: row.facet_value,
                    label: prettyLabel(row.facet_value),
                    count: row.count
                });
            }
        }

        viewer._baselineCounts = {
            source: new Map(grouped.source.map(s => [s.uri, s.count])),
            material: new Map(grouped.material.map(m => [m.uri, m.count])),
            context: new Map(grouped.context.map(c => [c.uri, c.count])),
            object_type: new Map(grouped.object_type.map(o => [o.uri, o.count])),
        };

        // HTML attribute / text escapers for safety when interpolating URIs.
        const escAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
        const escText = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;');

        // Render checkboxes with `data-facet` / `data-value` attributes so
        // Phase 2's cross-filter count updates can mutate counts in place
        // without rebuilding the HTML (which would lose mid-interaction
        // selections). See issue #156, Phase 2.
        const renderFilter = (bodyId, facetKey, items) => {
            const body = document.getElementById(bodyId);
            if (!body) return;
            if (items.length === 0) {
                body.innerHTML = '<em style="font-size: 11px; color: #999;">No values</em>';
                return;
            }
            body.innerHTML = items.map(it =>
                `<label class="facet-row" data-facet="${facetKey}" data-value="${escAttr(it.uri)}" title="${escAttr(it.uri)}"><input type="checkbox" value="${escAttr(it.uri)}"> ${escText(it.label)} <span class="facet-count" data-facet="${facetKey}" data-value="${escAttr(it.uri)}" style="color:#999">(${Number(it.count).toLocaleString()})</span></label>`
            ).join('');
        };

        renderFilter('materialFilterBody', 'material', grouped.material);
        renderFilter('contextFilterBody', 'context', grouped.context);
        renderFilter('objectTypeFilterBody', 'object_type', grouped.object_type);
        applyFacetCounts('source', null);
        applyQueryToFacetFilters();

        console.log(`Facet filters loaded: ${grouped.material.length} materials, ${grouped.context.length} contexts, ${grouped.object_type.length} object types (vocab labels: ${vocabMap.size})`);
    } catch(err) {
        console.warn("Facet summaries failed to load:", err);
    }
    return "loaded";
}
```

```{ojs}
//| echo: false
//| output: false

// === Table view: server-side paginated sample rows (table v2) ===
//
// Architecture:
// - One DuckDB query per page (LIMIT TABLE_PAGE_SIZE OFFSET page*size).
// - One COUNT(*) query per filter change (cached until filters change again).
// - ORDER BY pid for deterministic page contents.
// - Stale-while-loading: old rows stay visible (dimmed via .is-loading class)
//   while the new page/count is fetched in the DuckDB Web Worker. aria-busy
//   on #tableContainer signals to screen readers.
// - pageGen invalidates in-flight queries when a newer one starts.
tableView = {
    if (!facetFilters) return;

    let totalRows = null;          // null = "unknown / fetching"; set by loadCount()
    let pageRows = [];             // rows visible right now
    let pageRowsByPid = new Map(); // pid → row lookup for row-click handler
    let currentPage = 0;
    let pageGen = 0;               // bumped on any new load; in-flight callbacks check this
    let lastPageFailed = false;    // surfaces a sentinel table state when loadPage errors

    const prevBtn = document.getElementById('tablePrev');
    const nextBtn = document.getElementById('tableNext');
    const metaEl = document.getElementById('tableMeta');
    const pageInfoEl = document.getElementById('tablePageInfo');
    const tableEl = document.getElementById('samplesTable');
    const containerEl = document.getElementById('tableContainer');

    function totalPagesFor(total) {
        return Math.max(1, Math.ceil(total / TABLE_PAGE_SIZE));
    }

    function setLoading(loading) {
        if (containerEl) {
            containerEl.classList.toggle('is-loading', loading);
            containerEl.setAttribute('aria-busy', String(loading));
        }
        // Disable pager during load so a user can't queue a second click while
        // a query is in flight. updatePagerEdges() re-enables based on edge.
        if (loading) {
            if (prevBtn) prevBtn.disabled = true;
            if (nextBtn) nextBtn.disabled = true;
        } else {
            updatePagerEdges();
        }
    }

    function updatePagerEdges() {
        if (prevBtn) prevBtn.disabled = currentPage <= 0;
        if (nextBtn) {
            // Next is disabled when totalRows is unknown (count query
            // failed or hasn't returned) — otherwise the button looks
            // active but its click handler bails, which is confusing.
            // It's also disabled once we're at the last page.
            if (totalRows == null) {
                nextBtn.disabled = true;
            } else {
                nextBtn.disabled = currentPage >= totalPagesFor(totalRows) - 1;
            }
        }
    }

    function setMeta(text, isError) {
        if (!metaEl) return;
        metaEl.textContent = text;
        metaEl.style.color = isError ? '#c62828' : '#555';
    }

    function setMetaLoading(text) {
        if (!metaEl) return;
        metaEl.innerHTML = `<span class="table-loading-spinner" aria-hidden="true"></span>${escapeHtml(text)}`;
        metaEl.style.color = '#1565c0';
        // Clear the pager-info text while loading so it doesn't show
        // stale "Page 3 of 12 (200-300 of 1,200)" against an incoming
        // filter change. renderTable() repopulates it after data arrives.
        if (pageInfoEl) pageInfoEl.textContent = '';
    }

    function tableSourceBadge(source) {
        const color = SOURCE_COLORS[source] || '#666';
        const name = SOURCE_NAMES[source] || source || '';
        return `<span class="table-badge" style="background:${color}">${escapeHtml(name)}</span>`;
    }

    function renderTable() {
        const selectedPid = (typeof viewer !== 'undefined' && viewer._globeState)
            ? viewer._globeState.selectedPid : null;

        if (!tableEl) return;
        if (lastPageFailed) {
            // Page query failed — show an explicit sentinel rather than
            // leaving the old, now-inert rows visible (they'd look
            // clickable but pageRowsByPid is empty, so clicks would
            // silently no-op).
            tableEl.innerHTML = '<div class="table-scroll"><table class="samples-table"><tbody><tr><td>Page query failed. Adjust filters or click Previous/Next to retry.</td></tr></tbody></table></div>';
        } else if (pageRows.length === 0 && totalRows === 0) {
            tableEl.innerHTML = '<div class="table-scroll"><table class="samples-table"><tbody><tr><td>No samples match the current filters.</td></tr></tbody></table></div>';
        } else if (pageRows.length > 0) {
            const body = pageRows.map(r => {
                const placeParts = r.place_name;
                const place = Array.isArray(placeParts) && placeParts.length > 0
                    ? placeParts.filter(Boolean).join(' › ')
                    : '';
                const lat = r.latitude != null ? Number(r.latitude).toFixed(5) : '';
                const lng = r.longitude != null ? Number(r.longitude).toFixed(5) : '';
                const label = r.label || r.pid || '';
                const url = sourceUrl(r.pid);
                const labelHtml = url
                    ? `<a class="table-link" href="${escapeHtml(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml(label)}</a>`
                    : escapeHtml(label);
                const pidAttr = escapeHtml(r.pid || '');
                const selectedClass = (r.pid && r.pid === selectedPid) ? ' class="selected"' : '';
                return `<tr data-pid="${pidAttr}"${selectedClass}>
                    <td>${tableSourceBadge(r.source)}</td>
                    <td>${labelHtml}</td>
                    <td>${escapeHtml(place)}</td>
                    <td>${escapeHtml(r.result_time || '')}</td>
                    <td>${escapeHtml(lat)}</td>
                    <td>${escapeHtml(lng)}</td>
                </tr>`;
            }).join('');
            tableEl.innerHTML = `<div class="table-scroll">
                <table class="samples-table">
                    <thead><tr><th>Source</th><th>Label</th><th>Place</th><th>Date</th><th>Lat</th><th>Lon</th></tr></thead>
                    <tbody>${body}</tbody>
                </table>
            </div>`;
            // Wire row clicks. Each click follows the same ceremony as the
            // search-row click handler (see #207 item 8): bump the freshness
            // token first, set selection state, hydrate the card, fly the
            // camera, then lazy-load description. Reusing the sample-mode
            // selection path keeps the URL (`#pid=...`) and sidebar in sync
            // regardless of which surface initiated the selection.
            tableEl.querySelectorAll('tbody tr[data-pid]').forEach(tr => {
                tr.addEventListener('click', async (e) => {
                    if (e.target.tagName === 'A') return; // let label links work
                    const pid = tr.dataset.pid;
                    const sample = pid ? pageRowsByPid.get(pid) : null;
                    if (!sample || sample.latitude == null || sample.longitude == null) return;
                    if (typeof viewer === 'undefined') return;

                    const isStale = freshSelectionToken(viewer);
                    viewer._globeState.selectedPid = pid;
                    viewer._globeState.selectedH3 = null;
                    updateSampleCard({
                        pid: sample.pid,
                        label: sample.label,
                        source: sample.source,
                        lat: sample.latitude,
                        lng: sample.longitude,
                        place_name: sample.place_name,
                        result_time: sample.result_time
                    });
                    viewer.camera.flyTo({
                        destination: Cesium.Cartesian3.fromDegrees(sample.longitude, sample.latitude, 50000),
                        duration: 1.5
                    });
                    // Write the #pid hash directly here rather than relying on
                    // zoomWatcher's listener. zoomWatcher may not be wired yet
                    // at very-early-boot click time, and even when it is, the
                    // _suppressHashWrite gate could swallow the write.
                    history.replaceState(null, '', buildHash(viewer));
                    // Repaint to apply .selected class without a full refresh.
                    tableEl.querySelectorAll('tbody tr.selected').forEach(el => el.classList.remove('selected'));
                    tr.classList.add('selected');

                    try {
                        const detail = await db.query(`
                            SELECT description
                            FROM read_parquet('${wide_url}')
                            WHERE pid = '${pid.replace(/'/g, "''")}'
                            LIMIT 1
                        `);
                        if (isStale()) return;
                        if (detail && detail.length > 0) updateSampleDetail(detail[0]);
                        else updateSampleDetail({ description: '' });
                    } catch(err) {
                        if (isStale()) return;
                        console.error('Table-row detail query failed:', err);
                        updateSampleDetail(null);
                    }
                });
            });
        }

        // Pager text. While totalRows is null (count still in flight after a
        // filter change) we still know the current page index from the
        // page-data query, so render that without the total.
        if (pageInfoEl) {
            if (lastPageFailed) {
                pageInfoEl.textContent = '';
            } else if (totalRows === 0) {
                pageInfoEl.textContent = '';
            } else if (totalRows == null) {
                pageInfoEl.textContent = pageRows.length > 0
                    ? `Page ${currentPage + 1}`
                    : '';
            } else {
                const totalPages = totalPagesFor(totalRows);
                const first = currentPage * TABLE_PAGE_SIZE + 1;
                const last = Math.min(totalRows, first + pageRows.length - 1);
                pageInfoEl.textContent = `Page ${currentPage + 1} of ${totalPages} (${first.toLocaleString()}-${last.toLocaleString()} of ${totalRows.toLocaleString()})`;
            }
        }
    }

    async function loadCount(genAtStart, bboxSQL) {
        try {
            // pid IS NOT NULL mirrors the page query so the total counts only
            // rows that are actually pageable. Without this, totalRows could
            // overcount and the pager could enable Next past the last
            // non-null page.
            const data = await db.query(`
                SELECT COUNT(*) AS n
                FROM read_parquet('${lite_url}')
                WHERE pid IS NOT NULL
                  ${sourceFilterSQL('source')}
                  ${facetFilterSQL()}
                  ${bboxSQL}
            `);
            if (genAtStart !== pageGen) return true;
            // DuckDB-WASM returns BigInt for COUNT(*); coerce safely.
            const arr = Array.from(data);
            totalRows = arr.length > 0 ? Number(arr[0].n) : 0;
            renderTable();
            return true;
        } catch (err) {
            if (genAtStart !== pageGen) return false;
            console.error('Table count query failed:', err);
            // Leave totalRows null; the page query may still succeed and
            // render rows without a total. The meta line surfaces the error.
            return false;
        }
    }

    async function loadPage(p, genAtStart, bboxSQL) {
        try {
            const offset = p * TABLE_PAGE_SIZE;
            // AND pid IS NOT NULL: belt-and-suspenders. pid is the primary
            // identifier and should never be null, but ORDER BY a column
            // that contains nulls is only deterministic by accident on a
            // read-only parquet snapshot. Filter them defensively so the
            // page contract holds even if a future parquet rev allows nulls.
            const data = await db.query(`
                SELECT pid, label, source, latitude, longitude, place_name, result_time
                FROM read_parquet('${lite_url}')
                WHERE pid IS NOT NULL
                  ${sourceFilterSQL('source')}
                  ${facetFilterSQL()}
                  ${bboxSQL}
                ORDER BY pid
                LIMIT ${TABLE_PAGE_SIZE} OFFSET ${offset}
            `);
            if (genAtStart !== pageGen) return true;
            const arr = Array.from(data);
            pageRows = arr;
            pageRowsByPid = new Map(arr.map(r => [r.pid, r]));
            currentPage = p;
            lastPageFailed = false;
            renderTable();
            return true;
        } catch (err) {
            if (genAtStart !== pageGen) return false;
            console.error('Table page query failed:', err);
            pageRows = [];
            pageRowsByPid = new Map();
            lastPageFailed = true;
            renderTable();
            return false;
        }
    }

    function summaryText() {
        if (totalRows == null) return 'Counting samples...';
        if (totalRows === 0) return 'No samples match the current filters.';
        const total = totalRows.toLocaleString();
        return `${total} sample${totalRows === 1 ? '' : 's'} match the current filters.`;
    }

    async function refreshAll() {
        const gen = ++pageGen;
        currentPage = 0;
        totalRows = null;
        // Snapshot the viewport bbox at refresh-start time so the count and
        // page queries see the same predicate. The user could pan during
        // the async window; pageGen invalidates the in-flight result, and
        // moveEnd will fire a fresh refreshAll() against the new bbox.
        // VIEWPORT_PAD_FACTOR is shared with the point-mode loader and the
        // cluster-mode "Samples in View" stat (issue #221).
        const bboxSQL = viewerBboxSQL('latitude', 'longitude', VIEWPORT_PAD_FACTOR);
        if (bboxSQL === null) {
            // No view rectangle (rare; off-globe). Don't fall back to a
            // no-bbox query — that's the bug shape that motivated PR #219.
            // Clear the table and surface a status message.
            pageRows = [];
            pageRowsByPid = new Map();
            totalRows = 0;
            lastPageFailed = false;
            renderTable();
            setLoading(false);
            setMeta('No globe area in view; pan or zoom the globe to see samples.', true);
            return;
        }
        setLoading(true);
        setMetaLoading('Loading samples in view...');
        // Stale-while-loading: leave existing pageRows rendered (dimmed by
        // .is-loading) so the table doesn't blink to empty.
        const [countOk, pageOk] = await Promise.all([loadCount(gen, bboxSQL), loadPage(0, gen, bboxSQL)]);
        if (gen !== pageGen) return;
        setLoading(false);
        if (pageOk && countOk) {
            setMeta(summaryText());
        } else if (pageOk) {
            // Count failed but page succeeded: show row totals from the page
            // alone (caller can still navigate; Next is enabled only if
            // totalRows is known).
            setMeta('Page loaded, but the total-row count failed; try again to recompute.', true);
        } else {
            setMeta('Table query failed; adjust filters and try again.', true);
        }
    }

    async function refreshPage(newPage) {
        const gen = ++pageGen;
        // Page navigation uses the CURRENT viewport bbox. Counting was
        // already done against this bbox (refreshAll caches totalRows for
        // the filter+bbox combo until the next refreshAll).
        const bboxSQL = viewerBboxSQL('latitude', 'longitude', VIEWPORT_PAD_FACTOR);
        if (bboxSQL === null) {
            // User somehow paged while the camera went off-globe; refresh
            // re-scopes properly.
            return refreshAll();
        }
        setLoading(true);
        setMetaLoading(`Loading page ${newPage + 1}...`);
        const ok = await loadPage(newPage, gen, bboxSQL);
        if (gen !== pageGen) return;
        setLoading(false);
        if (ok) {
            setMeta(summaryText());
        } else {
            setMeta('Page query failed; adjust filters and try again.', true);
        }
    }

    if (prevBtn) prevBtn.addEventListener('click', () => {
        if (currentPage <= 0) return;
        refreshPage(currentPage - 1);
    });
    if (nextBtn) nextBtn.addEventListener('click', () => {
        if (totalRows == null) return;
        if (currentPage >= totalPagesFor(totalRows) - 1) return;
        refreshPage(currentPage + 1);
    });

    document.getElementById('sourceFilter')?.addEventListener('change', refreshAll);
    document.getElementById('materialFilterBody')?.addEventListener('change', refreshAll);
    document.getElementById('contextFilterBody')?.addEventListener('change', refreshAll);
    document.getElementById('objectTypeFilterBody')?.addEventListener('change', refreshAll);

    // Re-scope the table to the viewport on every camera settle. moveEnd
    // fires once per user gesture (after the pan/zoom ends), so this is
    // already debounced by user input. pageGen invalidates any racing
    // in-flight query. This listener also covers the boot case: when the
    // viewer's once() handler does the URL-hydrated setView, moveEnd
    // fires once and the initial table query runs against the correct
    // bbox.
    if (typeof viewer !== 'undefined') {
        viewer.camera.moveEnd.addEventListener(() => {
            refreshAll();
        });
    }

    window.refreshSamplesTable = refreshAll;
    // Boot: defer the initial refresh until the URL-hydrated camera has
    // been applied (otherwise the first query runs against the
    // default-constructed camera, briefly showing the wrong table).
    // viewer.camera.moveEnd will fire when once() does setView and trigger
    // the refresh via the listener above. If the camera is already
    // settled (e.g. fast-path re-runs of this cell), refresh immediately.
    if (typeof viewer !== 'undefined' && viewer._initialCameraApplied) {
        refreshAll();
    } else {
        // Show the loading state so the user sees the spinner immediately
        // rather than a stale "Loading samples matching the current
        // filters..." default-meta line.
        setLoading(true);
        setMetaLoading('Loading samples in view...');
    }

    return "active";
}
```

```{ojs}
//| echo: false
//| output: false

// === Zoom watcher: H3 cluster mode + individual sample point mode ===
zoomWatcher = {
    if (!phase1) return;
    if (!facetFilters) return;  // wait for facet checkboxes

    // --- State ---
    // `viewer._globeState.mode` is the single source of truth for cluster/
    // point mode (issue #208 smell 2). The closure-private `mode` variable
    // that used to live here was removed; reads now go through the helper
    // below, writes only via `setExplorerMode()` (in enterPointMode /
    // exitPointMode).
    const getMode = () => viewer._globeState.mode;
    const setExplorerMode = (next) => { viewer._globeState.mode = next; };
    let currentRes = 4;
    let loading = false;
    let requestId = 0;      // stale-request guard
    // clusterDataCache stored on viewer._clusterData (set by phase1 and loadRes)

    // freshSelectionToken(viewer) is defined at top level (alongside readHash /
    // buildHash) so the viewer cell's click handler and this cell's handlers
    // can both reach it. See issue #187.

    // Hysteresis thresholds to avoid flicker
    const ENTER_POINT_ALT = 120000;  // 120 km → enter point mode
    const EXIT_POINT_ALT = 180000;   // 180 km → exit point mode
    const POINT_BUDGET = DEFAULT_POINT_BUDGET;

    // No viewport cache: the samples table (PR #219) re-queries on every
    // `moveEnd` against the current padded bbox, so reusing a cached
    // `cachedTotalCount` here would have point-mode show a stale count
    // while the table shows the fresh one (issue #221). Both surfaces
    // now re-fetch in lockstep — small perf cost on rapid panning, but
    // the two counts no longer diverge.

    // --- H3 cluster loading (existing logic) ---
    //
    // `opts.loadingMsg` / `opts.errorMsg` override the default phase text so
    // callers like the boot→point-mode path can show a coherent
    // "Fetching sample index…" / "Failed to fetch the sample index…" pair
    // (issue #190 fix 2) instead of internal "H3 res8" jargon.
    //
    // Return value: `true` if this call applied fresh data and `currentRes`
    // is now `res`; `false` if the call was superseded by a newer one (stale
    // generation) or failed. Callers that gate follow-up work on the cluster
    // resolution being ready (e.g. the camera handler before `enterPointMode`)
    // must use the return value rather than treating a normal `await` return
    // as success.
    let loadResGen = 0;  // generation counter to discard stale results
    const loadRes = async (res, url, opts = {}) => {
        const gen = ++loadResGen;  // claim a generation
        loading = true;
        updatePhaseMsg(opts.loadingMsg || `Loading H3 res${res}...`, 'loading');

        try {
            performance.mark(`r${res}-s`);
            const data = await db.query(`
                SELECT CAST(h3_cell AS VARCHAR) AS h3_cell_dec,
                       sample_count, center_lat, center_lng,
                       dominant_source, source_count
                FROM read_parquet('${url}')
                WHERE 1=1${sourceFilterSQL('dominant_source')}
            `);

            if (gen !== loadResGen) return false;  // stale — a newer call superseded this one
            viewer.h3Points.removeAll();
            const scalar = new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.3);
            let total = 0;

            for (const row of data) {
                total += row.sample_count;
                const size = Math.min(3 + Math.log10(row.sample_count) * 3.5, 18);
                const h3Hex = BigInt(row.h3_cell_dec).toString(16);
                viewer.h3Points.add({
                    id: { h3_cell: h3Hex, count: row.sample_count, source: row.dominant_source, lat: row.center_lat, lng: row.center_lng, resolution: res },
                    position: Cesium.Cartesian3.fromDegrees(row.center_lng, row.center_lat, 0),
                    pixelSize: size,
                    color: Cesium.Color.fromCssColorString(SOURCE_COLORS[row.dominant_source] || '#666').withAlpha(0.85),
                    outlineColor: Cesium.Color.WHITE,
                    outlineWidth: 1.5,
                    scaleByDistance: scalar,
                    disableDepthTestDistance: POINT_DEPTH_TEST_DISTANCE,  // issue #185
                });
            }

            // Cache for viewport counting
            viewer._clusterData = Array.from(data);
            viewer._clusterTotal = { clusters: data.length, samples: total };

            performance.mark(`r${res}-e`);
            performance.measure(`r${res}`, `r${res}-s`, `r${res}-e`);
            const elapsed = performance.getEntriesByName(`r${res}`).pop().duration;

            // Show viewport count immediately. Use the same padded bbox
            // the samples table queries with (issue #221 round 2), so the
            // cluster-mode "Samples in View" stat agrees with the table's
            // row total.
            const inView = countInViewport(paddedViewportBounds(VIEWPORT_PAD_FACTOR));
            updateStats(`H3 Res${res}`, `${inView.clusters.toLocaleString()} / ${data.length.toLocaleString()}`, inView.samples.toLocaleString(), `${(elapsed/1000).toFixed(1)}s`, 'Clusters in View / Loaded', 'Samples in View');
            // Skip the "Zoom closer for individual samples." done message when
            // the caller is about to transition into point mode itself — the
            // next step (loadViewportSamples) immediately overwrites it with
            // its own "Loading individual samples…" loading state, so flashing
            // a misleading "zoom closer" hint at a user who is already deep
            // in point altitude is just noise (issue #190 fix 2).
            if (!opts.suppressDoneMsg) {
                updatePhaseMsg(`${data.length.toLocaleString()} clusters, ${total.toLocaleString()} samples. ${res < 8 ? 'Zoom in for finer detail.' : 'Zoom closer for individual samples.'}`, 'done');
            }

            currentRes = res;
            console.log(`Res${res}: ${data.length} clusters in ${elapsed.toFixed(0)}ms`);
            return true;
        } catch(err) {
            // Same generation guard as the success path — a stale failure
            // must not overwrite UI state owned by a newer in-flight call.
            if (gen !== loadResGen) return false;
            console.error(`Failed to load res${res}:`, err);
            updatePhaseMsg(opts.errorMsg || `Failed to load H3 res${res} — try zooming again.`, 'loading');
            return false;
        } finally {
            // Only release the busy flag if we're still the current generation.
            // A stale call's `finally` running after a newer call has set
            // `loading = true` would otherwise clear the flag while the newer
            // load is still in flight.
            if (gen === loadResGen) loading = false;
        }
    };

    // --- Get camera viewport bounds ---
    function getViewportBounds() {
        const rect = viewer.camera.computeViewRectangle(viewer.scene.globe.ellipsoid);
        if (!rect) return null;
        return {
            south: Cesium.Math.toDegrees(rect.south),
            north: Cesium.Math.toDegrees(rect.north),
            west: Cesium.Math.toDegrees(rect.west),
            east: Cesium.Math.toDegrees(rect.east)
        };
    }

    // --- Count clusters visible in current viewport (from cached array) ---
    function countInViewport(bounds) {
        const cache = viewer._clusterData;
        if (!bounds || !cache || cache.length === 0) return { clusters: 0, samples: 0 };
        const { south, north, west, east } = bounds;
        const wrapLng = west > east;  // dateline crossing
        let clusters = 0, samples = 0;
        for (const row of cache) {
            if (row.center_lat < south || row.center_lat > north) continue;
            if (wrapLng ? (row.center_lng < west && row.center_lng > east) : (row.center_lng < west || row.center_lng > east)) continue;
            clusters++;
            samples += row.sample_count;
        }
        return { clusters, samples };
    }

    // --- Load individual samples for current viewport ---
    async function loadViewportSamples() {
        const myReqId = ++requestId;
        const bounds = getViewportBounds();
        if (!bounds) return;

        // Fetch with VIEWPORT_PAD_FACTOR (30%) padding so this fetch
        // covers the same bbox as the table query and the cluster-mode
        // "Samples in View" count (issue #221).
        const latPad = (bounds.north - bounds.south) * VIEWPORT_PAD_FACTOR;
        const lngPad = (bounds.east - bounds.west) * VIEWPORT_PAD_FACTOR;
        const padded = {
            south: bounds.south - latPad,
            north: bounds.north + latPad,
            west: bounds.west - lngPad,
            east: bounds.east + lngPad
        };

        updatePhaseMsg('Loading individual samples...', 'loading');

        try {
            performance.mark('sp-s');
            // facetFilterSQL() returns a portable `pid IN (...)` predicate,
            // so the same query works whether or not facet filters are active.
            //
            // ORDER BY pid (issue #206): without explicit ordering, which
            // POINT_BUDGET-worth of rows the LIMIT returns is undefined and
            // can differ across browsers/sessions for the same query.
            const whereClause = `
                WHERE latitude BETWEEN ${padded.south} AND ${padded.north}
                  AND longitude BETWEEN ${padded.west} AND ${padded.east}
                  ${sourceFilterSQL('source')}
                  ${facetFilterSQL()}
            `;
            const query = `
                SELECT pid, label, source, latitude, longitude,
                       place_name, result_time
                FROM read_parquet('${lite_url}')
                ${whereClause}
                ORDER BY pid
                LIMIT ${POINT_BUDGET}
            `;
            const data = await db.query(query);
            performance.mark('sp-e');
            performance.measure('sp', 'sp-s', 'sp-e');
            const elapsed = performance.getEntriesByName('sp').pop().duration;

            // Stale guard: discard if a newer request was issued
            if (myReqId !== requestId) {
                console.log(`Discarding stale sample response (req ${myReqId}, current ${requestId})`);
                return;
            }

            // Real in-view count (issue #206). Without this, the "Samples in
            // View" counter caps at POINT_BUDGET, silently understating dense
            // regions (Cyprus/Polis: real count 23,421 vs displayed 5,000).
            // Only query when we hit the cap — when LIMIT returned fewer
            // rows than the budget, that count IS the real count and a
            // second query would be wasteful.
            let totalCount = data.length;
            let capReached = false;
            if (data.length >= POINT_BUDGET) {
                try {
                    const countRow = await db.query(`
                        SELECT count(*) AS n
                        FROM read_parquet('${lite_url}')
                        ${whereClause}
                    `);
                    if (myReqId !== requestId) return;  // stale guard
                    totalCount = Number(countRow[0]?.n ?? data.length);
                    capReached = totalCount > data.length;
                } catch(err) {
                    // Stale guard before any state mutation/logging:
                    // a newer request may have started while count was in
                    // flight (Codex review of PR #210).
                    if (myReqId !== requestId) return;
                    // Don't fail the whole load if the count query fails;
                    // just fall back to the displayed-count behavior.
                    console.warn("Real-count query failed; falling back to rendered count:", err);
                }
            }

            const samples = Array.from(data);
            renderSamplePoints(samples, bounds);

            // Stat boxes: LEFT (sPoints) always shows rendered count under
            // "Samples Rendered", RIGHT (sSamples) always shows real in-view
            // total under "Samples in View". Stable labels even when both
            // numbers are equal (Codex review preference: avoids label
            // flipping as the user zooms across the cap boundary).
            updateStats('Samples', samples.length, totalCount, `${(elapsed/1000).toFixed(1)}s`, 'Samples Rendered', 'Samples in View');
            const phaseMsg = capReached
                ? `${totalCount.toLocaleString()} samples in view (showing ${samples.length.toLocaleString()} — zoom in for more). Click one for details.`
                : `${samples.length.toLocaleString()} individual samples. Click one for details.`;
            updatePhaseMsg(phaseMsg, 'done');
            console.log(`Point mode: rendered ${samples.length} of ${totalCount} samples in ${elapsed.toFixed(0)}ms${capReached ? ' (cap reached)' : ''}`);

        } catch(err) {
            if (myReqId !== requestId) return;
            console.error("Viewport sample query failed:", err);
            updatePhaseMsg('Sample query failed — try again.', 'loading');
        }
    }

    // --- Render sample points on globe ---
    function renderSamplePoints(data, bounds) {
        viewer.samplePoints.removeAll();
        const scalar = new Cesium.NearFarScalar(1e2, 8, 2e5, 3);

        for (const row of data) {
            const color = SOURCE_COLORS[row.source] || '#666';
            viewer.samplePoints.add({
                id: {
                    type: 'sample',
                    pid: row.pid,
                    label: row.label,
                    source: row.source,
                    lat: row.latitude,
                    lng: row.longitude,
                    place_name: row.place_name,
                    result_time: row.result_time
                },
                position: Cesium.Cartesian3.fromDegrees(row.longitude, row.latitude, 0),
                pixelSize: 6,
                color: Cesium.Color.fromCssColorString(color).withAlpha(0.9),
                outlineColor: Cesium.Color.WHITE,
                outlineWidth: 1.5,
                scaleByDistance: scalar,
                disableDepthTestDistance: POINT_DEPTH_TEST_DISTANCE,  // issue #185
            });
        }
    }

    // --- Mode transitions ---
    function enterPointMode(pushHistory) {
        setExplorerMode('point');
        viewer.h3Points.show = false;
        viewer.samplePoints.show = true;
        if (pushHistory !== false) history.pushState(null, '', buildHash(viewer));
        loadViewportSamples();
        console.log('Entered point mode');
    }

    function exitPointMode(pushHistory) {
        setExplorerMode('cluster');
        viewer.samplePoints.show = false;
        viewer.samplePoints.removeAll();
        viewer.h3Points.show = true;
        if (pushHistory !== false) history.pushState(null, '', buildHash(viewer));

        // Invalidate any in-flight `loadViewportSamples()` so a slow sample
        // query that returns after we've already restored cluster stats
        // can't repaint the stat boxes / phase-msg with stale point-mode
        // numbers (Codex review of #221). Without this bump, a pending
        // sample query's renderSamplePoints + updateStats would still pass
        // the stale-request guard on completion.
        ++requestId;

        // Restore cluster stats with viewport count. Use the padded bbox
        // shared with the samples table (issue #221 round 2).
        const inView = countInViewport(paddedViewportBounds(VIEWPORT_PAD_FACTOR));
        const total = viewer._clusterTotal;
        if (total) {
            updateStats(`H3 Res${currentRes}`, `${inView.clusters.toLocaleString()} / ${total.clusters.toLocaleString()}`, inView.samples.toLocaleString(), '—', 'Clusters in View / Loaded', 'Samples in View');
        } else {
            updateStats(`H3 Res${currentRes}`, viewer.h3Points.length, '—', '—', 'Clusters Loaded', 'Samples Loaded');
        }
        updatePhaseMsg(`${inView.clusters.toLocaleString()} clusters in view. Zoom closer for individual samples.`, 'done');
        console.log('Exited point mode');
    }

    // --- Boot→point-mode transition (issue #190 fix 2) ---
    //
    // Idempotent helper that runs the cluster→point-mode transition iff the
    // camera is currently at point-mode altitude. Called from three paths:
    //
    //  1. The camera-changed handler, when `targetMode === 'point' && mode
    //     !== 'point'` — the normal cold-cache deep-link path.
    //  2. The source-filter handler's `mode === 'cluster'` branch, after its
    //     own `loadRes(currentRes, ...)` settles. Without this second call,
    //     a source-filter toggle during the 60-90s cold-cache wait would
    //     supersede the camera handler's pending res8 load (`loadResGen`++),
    //     the camera handler's post-await re-check would correctly refuse
    //     to enter point mode, and then no camera event would necessarily
    //     fire to retry — leaving the user in cluster mode at point altitude
    //     until they nudged the camera (issue #190 round-2 review).
    //  3. The camera handler's cluster-resolution reload branches, after
    //     their `loadRes(target, ...)` settles. This covers the same liveness
    //     shape when a camera-initiated cluster load was already in flight as
    //     the user crossed into point altitude.
    //
    // The function re-checks altitude/`mode` after its own (potentially
    // long) `loadRes` await for the same reason: if the user zooms back out
    // or another path enters point mode during the wait, we must not force
    // entry afterwards.
    //
    // INVARIANT: every `loadRes` call site in this cell *outside this
    // helper* that could be in flight when the user crosses below
    // `ENTER_POINT_ALT` MUST capture the call's return value and chase
    // with `await tryEnterPointModeIfNeeded()` *iff that return is `true`*
    // (i.e., fresh data was applied). Idiom:
    //
    //   const applied = await loadRes(...);
    //   if (applied) await tryEnterPointModeIfNeeded();
    //
    // The `!loading` short-circuit below relies on this — when an unrelated
    // `loadRes` is in flight we bail and leave recovery to that call site's
    // own post-await chase.
    //
    // Why gate the chase on `applied` (issue #193):
    //  - On `false`-stale: a newer `loadRes` caller superseded us; that
    //    caller chases when it settles, so our chase would be redundant.
    //  - On `false`-failed: `loadRes` already painted a "Failed to load…"
    //    phase message that the user should be able to read; chasing here
    //    would immediately overpaint it with "Fetching sample index…".
    //
    // A new `loadRes` caller added without the chase would silently break
    // supersession recovery and only surface as a rare liveness regression
    // (see issue #194). Verify with:
    //   grep -nE "await[[:space:]]+loadRes\(" explorer.qmd
    // which lists exactly the awaited call sites (one inside this helper,
    // and one per external caller). For each external match, confirm it
    // captures the return into `applied` and is immediately followed by
    // `if (applied) await tryEnterPointModeIfNeeded();`.
    async function tryEnterPointModeIfNeeded(opts) {
        if (getMode() === 'point') return;
        if (viewer.camera.positionCartographic.height >= ENTER_POINT_ALT) return;

        let res8Ready = currentRes === 8;
        // See INVARIANT above: if an unrelated load is in flight, that
        // call site is responsible for chasing with this helper when it
        // settles. Don't second-guess it from here.
        if (!res8Ready && !loading) {
            res8Ready = await loadRes(8, h3_res8_url, {
                loadingMsg: 'Fetching sample index…',
                suppressDoneMsg: true,
                errorMsg: 'Failed to fetch the sample index — try zooming out and back in.',
            });
        }
        const hNow = viewer.camera.positionCartographic.height;
        if (res8Ready && getMode() !== 'point' && hNow < ENTER_POINT_ALT) {
            // Propagate `pushHistory` so boot/hash hydration callers can
            // avoid growing the browser history stack (issue #207 item 3).
            enterPointMode(opts && opts.pushHistory);
        }
    }

    // === Cross-filter facet count refresh (issue #156, Phase 2) ===
    //
    // Counts answer: for each value in facet D, how many samples would match
    // this value plus the active filters in all OTHER facets. This keeps
    // selected facets useful as drill-out controls instead of just echoing the
    // selected values.
    let facetCountsReqId = 0;
    let facetCountsDebounce = null;

    function describeCrossFilters() {
        const sourceChecks = document.querySelectorAll('#sourceFilter input[type="checkbox"]');
        const sourceTotal = sourceChecks.length;
        const sources = getActiveSources();
        const mat = getCheckedValues('materialFilterBody');
        const ctx = getCheckedValues('contextFilterBody');
        const ot = getCheckedValues('objectTypeFilterBody');
        const dims = [
            { key: 'source', col: 'source', values: sources.length < sourceTotal ? sources : [] },
            { key: 'material', col: 'material', values: mat },
            { key: 'context', col: 'context', values: ctx },
            { key: 'object_type', col: 'object_type', values: ot },
        ];
        const activeDims = dims.filter(d => d.values.length > 0);
        const totalActiveValues = activeDims.reduce((n, d) => n + d.values.length, 0);
        return {
            dims,
            activeDims,
            totalActiveValues,
            sourceImpossible: sourceTotal > 0 && sources.length === 0,
        };
    }

    function buildCrossFilterWhere(excludeFacet) {
        const { activeDims, sourceImpossible } = describeCrossFilters();
        if (sourceImpossible && excludeFacet !== 'source') return '1=0';

        const conds = activeDims
            .filter(d => d.key !== excludeFacet)
            .map(d => {
                const list = d.values.map(v => `'${escSql(v)}'`).join(',');
                return `${d.col} IN (${list})`;
            });

        return conds.length > 0 ? conds.join(' AND ') : '1=1';
    }

    async function updateCrossFilteredCounts(myReq) {
        if (myReq !== facetCountsReqId) return;
        const { dims, activeDims, totalActiveValues, sourceImpossible } = describeCrossFilters();

        if (!sourceImpossible && activeDims.length === 0) {
            for (const d of dims) applyFacetCounts(d.key, null);
            return;
        }

        markFacetCountsRecomputing();

        const singleActiveDim = !sourceImpossible
            && activeDims.length === 1 && activeDims[0].values.length === 1
            ? activeDims[0] : null;
        if (singleActiveDim && totalActiveValues === 1) {
            try {
                const filterCols = ['filter_source', 'filter_material', 'filter_context', 'filter_object_type'];
                const filterColForKey = {
                    source: 'filter_source',
                    material: 'filter_material',
                    context: 'filter_context',
                    object_type: 'filter_object_type',
                };
                const targetCol = filterColForKey[singleActiveDim.key];
                const value = escSql(singleActiveDim.values[0]);
                const whereParts = filterCols.map(c =>
                    c === targetCol ? `${c} = '${value}'` : `${c} IS NULL`
                );
                const rows = await db.query(`
                    SELECT facet_type, facet_value, count
                    FROM read_parquet('${cross_filter_url}')
                    WHERE ${whereParts.join(' AND ')}
                `);
                if (myReq !== facetCountsReqId) return;
                if (rows && rows.length > 0) {
                    const grouped = { source: new Map(), material: new Map(), context: new Map(), object_type: new Map() };
                    for (const r of rows) {
                        if (grouped[r.facet_type]) grouped[r.facet_type].set(r.facet_value, Number(r.count));
                    }
                    for (const d of dims) {
                        applyFacetCounts(d.key, d.key === singleActiveDim.key ? null : grouped[d.key]);
                    }
                    return;
                }
            } catch (err) {
                console.warn('Cross-filter cache lookup failed; falling back to on-the-fly:', err);
            }
        }

        await Promise.all(dims.map(async (d) => {
            const where = buildCrossFilterWhere(d.key);
            try {
                const rows = await db.query(`
                    SELECT ${d.col} AS value, COUNT(*) AS count
                    FROM read_parquet('${facets_url}')
                    WHERE ${where} AND ${d.col} IS NOT NULL
                    GROUP BY ${d.col}
                `);
                if (myReq !== facetCountsReqId) return;
                const map = new Map();
                for (const r of rows) map.set(r.value, Number(r.count));
                applyFacetCounts(d.key, map);
            } catch (err) {
                if (myReq !== facetCountsReqId) return;
                console.warn(`Cross-filter count query failed for ${d.key}:`, err);
                applyFacetCounts(d.key, null);
            }
        }));
    }

    function refreshFacetCounts() {
        clearTimeout(facetCountsDebounce);
        const myReq = ++facetCountsReqId;
        facetCountsDebounce = setTimeout(() => {
            updateCrossFilteredCounts(myReq);
        }, 250);
    }

    // --- Busy-flag depth counter (#173 review round 2) ---
    //
    // body.classList 'explorer-busy' tracks "any change-triggered async
    // work in flight." Without depth counting, overlapping handlers race:
    // a fast handler's `finally` removes the class while a slower
    // handler's loadRes / facet recompute is still running, defeating the
    // whole point of the flag. Depth-counted: class is added on the
    // 0 → 1 transition and removed on the 1 → 0 transition.
    let _busyDepth = 0;
    function busyAcquire() {
        if (_busyDepth === 0) document.body.classList.add('explorer-busy');
        _busyDepth++;
    }
    function busyRelease() {
        _busyDepth = Math.max(0, _busyDepth - 1);
        if (_busyDepth === 0) document.body.classList.remove('explorer-busy');
    }

    // --- Source filter change handler ---
    //
    // The body.classList 'explorer-busy' flag wraps every async work path
    // out of this handler so external observers (Playwright tests,
    // perf-smoke harnesses) can wait for "all triggered work has settled"
    // without race conditions against the debounced facet recompute. The
    // 300ms post-refreshFacetCounts wait is intentional: refreshFacetCounts
    // schedules a 250ms debounce that THEN sets the .recomputing class on
    // facet count spans; we hold the busy flag until that has fired so the
    // .recomputing-clear poll downstream is meaningful. See #173 review.
    const resUrls = { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url };
    document.getElementById('sourceFilter').addEventListener('change', async () => {
        busyAcquire();
        // Source filter affects which clusters / samples are visible. Invalidate
        // any in-flight selection lookup AND re-validate the current selection
        // (cluster or sample) under the new filter — if it's filtered out, drop
        // it from runtime state and the URL so the side panel matches the globe.
        const isStale = freshSelectionToken(viewer);
        try {
            updateSourceLegendState();
            writeQueryState();
            if (getMode() === 'cluster') {
                loading = false;
                const applied = await loadRes(currentRes, resUrls[currentRes]);
                // Liveness recovery (issue #190 round-2 review): if the user
                // is sitting at point-mode altitude — e.g. they toggled the
                // source filter mid-way through the cold-cache boot wait,
                // which superseded the camera handler's pending res8 load —
                // drive the cluster→point transition forward here.
                //
                // Only chase on `applied === true` (issue #193): on `false`
                // we either lost to a newer call (in which case that call's
                // chase will recover) or we caught an error (in which case
                // the user has a "Failed to load…" message they should be
                // able to read, not have it papered over by "Fetching
                // sample index…").
                if (applied) await tryEnterPointModeIfNeeded();
            } else {
                await loadViewportSamples();
            }
            refreshFacetCounts();

            // Re-validate selection (only if no newer filter change has fired).
            if (!isStale()) {
                const sel = viewer._globeState;
                if (sel.selectedH3) {
                    const meta = await fetchClusterByH3(sel.selectedH3);
                    if (isStale()) return;
                    if (!meta) {
                        sel.selectedH3 = null;
                        updateClusterCard(null);
                        const sampEl = document.getElementById('samplesSection');
                        if (sampEl) sampEl.innerHTML = '';
                        history.replaceState(null, '', buildHash(viewer));
                    } else {
                        // Cluster's dominant_source still checked, but the
                        // nearby-samples list inside hydrateClusterUI is
                        // source-filtered too — re-run it under the new filter
                        // so the panel doesn't show stale rows from unchecked
                        // sources (or miss newly-checked ones).
                        await hydrateClusterUI(meta, isStale);
                    }
                } else if (sel.selectedPid) {
                    const safe = sel.selectedPid.replace(/'/g, "''");
                    const stillVisible = await db.query(`
                        SELECT 1 FROM read_parquet('${lite_url}')
                        WHERE pid = '${safe}'
                        ${sourceFilterSQL('source')}
                        LIMIT 1
                    `);
                    if (isStale()) return;
                    if (!stillVisible || stillVisible.length === 0) {
                        sel.selectedPid = null;
                        updateClusterCard(null);
                        const sampEl = document.getElementById('samplesSection');
                        if (sampEl) sampEl.innerHTML = '';
                        history.replaceState(null, '', buildHash(viewer));
                    }
                }
            }

            await new Promise(r => setTimeout(r, 300));
        } finally {
            busyRelease();
        }
    });

    // --- Material / Context / Specimen Type filter change handler ---
    //
    // Cluster-mode honesty: the H3 summary parquets only carry
    // `dominant_source`, so material / context / object_type filters cannot
    // affect cluster counts. When any of these is active in cluster mode,
    // surface the explanatory `#facetNote` so users understand the filter
    // takes effect at neighborhood zoom. See issue #156, Phase 1.
    const facetNote = document.getElementById('facetNote');
    async function handleFacetFilterChange() {
        busyAcquire();
        try {
            const active = hasFacetFilters();
            if (facetNote) facetNote.style.display = (active && getMode() === 'cluster') ? 'block' : 'none';
            writeQueryState();
            if (getMode() === 'point') {
                await loadViewportSamples();
            }
            refreshFacetCounts();
            await new Promise(r => setTimeout(r, 300));
        } finally {
            busyRelease();
        }
    }
    document.getElementById('materialFilterBody').addEventListener('change', handleFacetFilterChange);
    document.getElementById('contextFilterBody').addEventListener('change', handleFacetFilterChange);
    document.getElementById('objectTypeFilterBody').addEventListener('change', handleFacetFilterChange);

    // --- Camera change handler ---
    let timer = null;
    viewer.camera.changed.addEventListener(() => {
        if (timer) clearTimeout(timer);
        timer = setTimeout(async () => {
            const h = viewer.camera.positionCartographic.height;

            // Write the URL hash BEFORE any awaits (issue #201, Bug A).
            // The camera position/heading is known synchronously; without this
            // early write, a user who pans into a region that triggers a
            // resolution change (cluster→res8) or a cold-cache point-mode
            // transition won't see the URL update until the await chain
            // below settles — and a URL copy in the meantime captures the
            // PREVIOUS state. We still write again at the end of the
            // handler to capture any mode change that the awaits produced.
            if (!viewer._suppressHashWrite) {
                history.replaceState(null, '', buildHash(viewer));
            }

            // Determine target mode with hysteresis
            const targetMode = h < ENTER_POINT_ALT ? 'point'
                             : h > EXIT_POINT_ALT ? 'cluster'
                             : getMode();

            if (targetMode === 'point' && getMode() !== 'point') {
                // Cold-cache deep-link: the res8 + samples_map_lite fetches
                // can take 60-90s (DuckDB-WASM 1.24.0 falls back to a full
                // HTTP read; see issue #190). Delegate to the shared helper
                // so the source-filter handler can call the same path on
                // supersession recovery.
                await tryEnterPointModeIfNeeded();
            } else if (targetMode === 'cluster' && getMode() !== 'cluster') {
                exitPointMode();
                // Reload appropriate resolution
                const target = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
                if (target !== currentRes && !loading) {
                    const applied = await loadRes(target, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[target]);
                    // The user may have crossed below ENTER_POINT_ALT while
                    // this cluster load was in flight; reconcile after it
                    // settles so no extra camera nudge is required.
                    //
                    // Skip chase on non-applied returns (issue #193): a
                    // stale return is recovered by the supersedor's own
                    // chase, and a failed return should leave the user's
                    // "Failed to load…" message visible instead of
                    // overpainting it with "Fetching sample index…".
                    if (applied) await tryEnterPointModeIfNeeded();
                }
            } else if (targetMode === 'point') {
                // Already in point mode — viewport sample refresh is driven
                // by the `moveEnd` listener below (issue #221), in lockstep
                // with the samples table. `camera.changed` is debounced
                // (`percentageChanged = 0.1`) so sub-10% pans don't fire
                // here; the `moveEnd` path catches every settled move.
            } else {
                // Cluster mode — check if resolution should change
                const target = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
                if (target !== currentRes && !loading) {
                    const applied = await loadRes(target, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[target]);
                    // The user may have crossed below ENTER_POINT_ALT while
                    // this cluster load was in flight; reconcile after it
                    // settles so no extra camera nudge is required.
                    // Same chase gate as the cluster-reload branch above (issue #193).
                    if (applied) await tryEnterPointModeIfNeeded();
                }
            }

            // Update viewport cluster count (cluster mode only; point mode
            // already shows viewport count). Padded bbox so the cluster
            // "Samples in View" stat matches the samples table row total
            // (issue #221 round 2).
            if (getMode() === 'cluster' && viewer._clusterData) {
                const inView = countInViewport(paddedViewportBounds(VIEWPORT_PAD_FACTOR));
                const total = viewer._clusterTotal;
                if (total) {
                    updateStats(`H3 Res${currentRes}`, `${inView.clusters.toLocaleString()} / ${total.clusters.toLocaleString()}`, inView.samples.toLocaleString(), null, 'Clusters in View / Loaded', 'Samples in View');
                }
            }

            // Update URL hash (replaceState for continuous movement)
            if (!viewer._suppressHashWrite) {
                history.replaceState(null, '', buildHash(viewer));
            }
        }, 600);
    });
    viewer.camera.percentageChanged = 0.1;

    // Backstop URL-write + point-mode sample-refresh trigger.
    //
    // URL write (issue #204): `camera.changed` is suppressed for
    // sub-`percentageChanged` moves, so a small drag-pan that doesn't
    // cross the 10% threshold never schedules the debounced callback above —
    // and the URL stays stale until a larger move fires the event. `moveEnd`
    // fires once per discrete settled camera move regardless of magnitude
    // (mouseup on a drag, wheel-stop on a zoom, flight-complete on flyTo),
    // so this catches every camera position the user can pan/zoom to.
    // The `_suppressHashWrite` gate keeps the hashchange-flight path
    // unaffected.
    //
    // Point-mode samples (issue #221): the samples table re-queries on
    // every `moveEnd`. Refresh point-mode samples on the same trigger so
    // the "Samples in View" stat / phase-msg stay in lockstep with the
    // table's row count even on small sub-10% pans that `camera.changed`
    // doesn't fire for.
    viewer.camera.moveEnd.addEventListener(() => {
        if (!viewer._suppressHashWrite) {
            history.replaceState(null, '', buildHash(viewer));
        }
        if (getMode() !== 'point') return;
        const h = viewer.camera.positionCartographic.height;
        if (h > EXIT_POINT_ALT) {
            // Sub-10% zoom-out from point mode (e.g. 175 km → 181 km) won't
            // fire `camera.changed`, so without driving the exit here we'd
            // be stuck in point mode above `EXIT_POINT_ALT` until a larger
            // camera move. Mirror the `camera.changed` cluster-transition
            // branch's `exitPointMode()` (Codex round-2 review of #221).
            // The cluster-resolution reload that `camera.changed` also
            // does is not needed for these small zoom-outs: in the
            // 180–300 km band the target resolution stays res8, which
            // point mode already had loaded. Larger zoom-outs that cross
            // a resolution threshold will themselves fire `camera.changed`
            // and run the normal reload path. The reverse direction
            // (sub-10% zoom-in past `ENTER_POINT_ALT` from cluster mode)
            // is left to `camera.changed` — pre-existing behavior, out of
            // scope here.
            exitPointMode();
            return;
        }
        // In point mode and at point-mode altitude: refresh samples in
        // lockstep with the samples table (issue #221).
        loadViewportSamples();
    });

    // --- Helper: hydrate cluster row from H3 cell index ---
    // Canonical H3 cells encode resolution in the 2nd hex char (the leading-zero-
    // stripped form is `8<res><...>` for cell-mode indices). We support res 4/6/8
    // — the parquets we have. Reject malformed input rather than silently strip:
    // a stray prefix (`xxx843f...`) would otherwise change which key we look up.
    // h3_cell is UBIGINT in the parquet; DuckDB-WASM rejects `0x...` literals, so
    // hex → decimal happens in JS via BigInt, then CAST to UBIGINT in SQL.
    const RES_TO_H3_URL = { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url };
    async function fetchClusterByH3(cellHex) {
        if (typeof cellHex !== 'string') return null;
        const lower = cellHex.toLowerCase();
        if (!/^[0-9a-f]{15}$/.test(lower)) return null;
        // First nibble of the leading-zero-stripped 15-char form is the H3 mode
        // (cells are mode 1 → '8' here). Reject non-cell modes (edges, vertices,
        // etc.) so we don't issue spurious lookups for them.
        if (lower[0] !== '8') return null;
        const res = parseInt(lower[1], 16);
        const url = RES_TO_H3_URL[res];
        if (!url) return null;
        let decimal;
        try { decimal = BigInt('0x' + lower).toString(); }
        catch { return null; }
        try {
            // Honor the active ?sources= filter — same predicate phase1/loadRes
            // apply when rendering clusters (`:976`, `:1319`). A cluster whose
            // dominant_source is currently unchecked wouldn't be visible on the
            // globe, so hydrating its side panel would mismatch the user's view
            // (and would inconsistently combine unfiltered cluster card with
            // source-filtered nearby-samples in hydrateClusterUI).
            const result = await db.query(`
                SELECT sample_count, center_lat, center_lng, dominant_source, source_count
                FROM read_parquet('${url}')
                WHERE h3_cell = CAST('${decimal}' AS UBIGINT)
                ${sourceFilterSQL('dominant_source')}
                LIMIT 1
            `);
            if (!result || result.length === 0) return null;
            const r = result[0];
            return {
                // The validated input `lower` is the canonical hex; round-tripping
                // r.h3_cell would lose precision (DuckDB-WASM returns UBIGINT as
                // JS Number for values > 2^53).
                h3_cell: lower,
                count: r.sample_count,
                source: r.dominant_source,
                lat: r.center_lat,
                lng: r.center_lng,
                resolution: res,
            };
        } catch(err) {
            console.error("fetchClusterByH3 query failed:", err);
            return null;
        }
    }

    // --- Helper: populate side panel + nearby-samples list from a cluster meta object ---
    // Mirrors the cluster-click handler at the LEFT_CLICK input action above.
    // The optional `isStale` predicate is consulted *after* the inner await so
    // that a hashchange superseded by a newer one doesn't paint stale samples
    // into the side panel. The cluster-click caller passes a no-op predicate
    // because click selection is its own latest event.
    async function hydrateClusterUI(meta, isStale) {
        if (!meta) return;
        updateClusterCard(meta);
        const sampEl = document.getElementById('samplesSection');
        if (sampEl) sampEl.innerHTML = '<div style="text-align: center; color: #999; padding: 12px;">Loading nearby samples...</div>';
        const delta = meta.resolution === 4 ? 2.0 : meta.resolution === 6 ? 0.5 : 0.1;
        try {
            const samples = await db.query(`
                SELECT pid, label, source, latitude, longitude, place_name
                FROM read_parquet('${lite_url}')
                WHERE latitude BETWEEN ${meta.lat - delta} AND ${meta.lat + delta}
                  AND longitude BETWEEN ${meta.lng - delta} AND ${meta.lng + delta}
                  ${sourceFilterSQL('source')}
                  ${facetFilterSQL()}
                LIMIT 30
            `);
            if (isStale && isStale()) return;
            updateSamples(samples);
        } catch(err) {
            if (isStale && isStale()) return;
            console.error("Cluster hydration nearby query failed:", err);
            if (sampEl) sampEl.innerHTML = '<div style="color: #c62828; padding: 12px;">Query failed — try again.</div>';
        }
    }

    // --- Handle browser back/forward ---
    window.addEventListener('hashchange', async () => {
        // Bump the selection generation BEFORE any early-return so even
        // hashchanges that lack lat/lng invalidate stale async work.
        const isStale = freshSelectionToken(viewer);
        const state = readHash();
        if (state.lat == null || state.lng == null) return;

        viewer._suppressHashWrite = true;
        clearTimeout(viewer._suppressTimer);
        viewer.camera.cancelFlight();
        viewer.camera.flyTo({
            destination: Cesium.Cartesian3.fromDegrees(state.lng, state.lat, state.alt || 20000000),
            orientation: {
                heading: Cesium.Math.toRadians(state.heading),
                pitch: Cesium.Math.toRadians(state.pitch)
            },
            duration: 1.5,
        });

        // After flight settles, force mode and clear suppress flag.
        // Use the same altitude-authoritative predicate as the boot path
        // (issue #207 item 4 → Codex follow-up): without this, back/forward
        // through a `#alt=8000` URL with no `mode=point` would exit point
        // mode here even though boot would have entered it.
        viewer._suppressTimer = setTimeout(() => {
            viewer._suppressHashWrite = false;
            const s = readHash();
            const wantsPoint = s.mode === 'point' || (s.alt != null && s.alt < ENTER_POINT_ALT);
            if (wantsPoint && getMode() !== 'point') enterPointMode(false);
            else if (!wantsPoint && getMode() === 'point') exitPointMode(false);
        }, 2000);

        // Handle pid / h3 selection (sample mode wins if both present — see
        // EXPLORER_CLUSTER_URL_PROPOSAL §4). Both branches do an `await` against
        // a remote parquet, so a fast back/forward could race: an older fetch
        // resolves AFTER a newer hash has applied, and would otherwise repaint
        // the side panel with stale data. `isStale` is the freshness token
        // captured at the top of this handler; we check it after each await.
        if (state.pid) {
            viewer._globeState.selectedPid = state.pid;
            viewer._globeState.selectedH3 = null;
            try {
                const sample = await db.query(`
                    SELECT pid, label, source, latitude, longitude, place_name, result_time
                    FROM read_parquet('${lite_url}')
                    WHERE pid = '${state.pid.replace(/'/g, "''")}'
                    LIMIT 1
                `);
                if (isStale()) return;
                if (sample && sample.length > 0) {
                    const s = sample[0];
                    updateSampleCard({
                        pid: s.pid, label: s.label, source: s.source,
                        lat: s.latitude, lng: s.longitude,
                        place_name: s.place_name, result_time: s.result_time
                    });
                }
            } catch(err) {
                console.error("Hash pid query failed:", err);
            }
        } else if (state.h3) {
            viewer._globeState.selectedPid = null;
            viewer._globeState.selectedH3 = state.h3.toLowerCase();
            const meta = await fetchClusterByH3(state.h3);
            if (isStale()) return;
            if (meta) {
                viewer._globeState.selectedH3 = meta.h3_cell;  // canonical lowercase
                await hydrateClusterUI(meta, isStale);
            } else {
                // Unknown / malformed h3, OR filtered out by ?sources= —
                // clear the side panel rather than leaving prior content
                // stranded, AND drop the h3 from runtime state so
                // buildHash() doesn't keep emitting it (issue #207 item 6:
                // restores symmetry with the boot deep-link path which
                // already does this).
                viewer._globeState.selectedH3 = null;
                updateClusterCard(null);
                const sampEl = document.getElementById('samplesSection');
                if (sampEl) sampEl.innerHTML = '';
            }
        } else {
            viewer._globeState.selectedPid = null;
            viewer._globeState.selectedH3 = null;
            updateClusterCard(null);
            const sampEl = document.getElementById('samplesSection');
            if (sampEl) sampEl.innerHTML = '';
        }
    });

    // --- Share button ---
    const shareBtn = document.getElementById('shareBtn');
    if (shareBtn) {
        shareBtn.addEventListener('click', async () => {
            history.replaceState(null, '', buildHash(viewer));
            try {
                await navigator.clipboard.writeText(location.href);
                const toast = document.getElementById('shareToast');
                if (toast) {
                    toast.style.opacity = '1';
                    setTimeout(() => { toast.style.opacity = '0'; }, 2000);
                }
            } catch(err) {
                prompt('Copy this link:', location.href);
            }
        });
    }

    // --- Search handler ---
    const searchAreaBtn = document.getElementById('searchAreaBtn');
    const searchWorldBtn = document.getElementById('searchWorldBtn');
    const searchInput = document.getElementById('sampleSearch');
    const searchResults = document.getElementById('searchResults');

    let _searchSeq = 0;
    // Initial scope hydrated from URL; default 'world' on missing/unknown.
    let _searchScope = (
        new URLSearchParams(location.search).get('search_scope') === 'area'
    ) ? 'area' : 'world';

    function persistSearchScope(scope) {
        // writeQueryState() doesn't know about scope; keep the URL param
        // honest by manipulating directly. 'world' is default, omitted from
        // URL.
        const params = new URLSearchParams(location.search);
        if (scope === 'area') params.set('search_scope', 'area');
        else params.delete('search_scope');
        const qs = params.toString();
        const url = `${location.pathname}${qs ? `?${qs}` : ''}${location.hash}`;
        if (url !== `${location.pathname}${location.search}${location.hash}`) {
            history.replaceState(null, '', url);
        }
    }

    async function doSearch(scope) {
        if (scope === 'area' || scope === 'world') _searchScope = scope;
        const effectiveScope = _searchScope;

        const term = searchInput.value.trim();
        if (!term || term.length < 2) {
            searchResults.textContent = 'Type at least 2 characters';
            writeQueryState();
            persistSearchScope(effectiveScope);
            return;
        }
        writeQueryState();
        persistSearchScope(effectiveScope);
        searchResults.textContent = effectiveScope === 'area'
            ? 'Searching selected areas...'
            : 'Searching entire world...';

        // Per-search perf instrumentation (#167). Captures cold/warm latency,
        // result count, and bytes transferred from data.isamples.org during
        // the search window. transferSize is 0 for cross-origin responses
        // missing Timing-Allow-Origin; we fall back to encodedBodySize.
        const searchId = ++_searchSeq;
        const markStart = `search-${searchId}-start`;
        const markEnd = `search-${searchId}-end`;
        performance.mark(markStart);
        const tStart = performance.now();
        const terms = searchTerms(term);
        let resultsCount = 0;
        let errorMessage = null;

        try {
            // INTERIM RECALL FIX (#168 Direction A) — knowingly accepts the
            // latency regression in exchange for fixing false-zero results.
            //
            // Background: the previous query searched samples_map_lite over
            // label + place_name only; samples_map_lite does not carry
            // description, so queries like `pottery Cyprus` returned zero
            // even when ~7,124 samples actually match (Cyprus appears only
            // in description). This is a *broken* user experience even
            // though it's fast.
            //
            // This is NOT the FTS solution. The proper substrate work in
            // #169-#172 builds a sample-centric document projection with
            // hash-partitioned BM25 indexes that fixes both recall AND
            // latency. This code path goes away when #171 lands.
            //
            // CTE-then-keyed-join shape (NOT a naive LEFT JOIN). Native
            // DuckDB benchmark: naive 4.2 s vs CTE 0.5 s for `pottery`.
            // The browser DuckDB-WASM penalty makes the difference even
            // more pronounced; the naive form times out on `pottery` cold.
            // Use `f.`-qualified columns so the same searchWhere/score
            // strings work for both the world-mode CTE (single table aliased
            // f) and the area-mode INNER JOIN (f + l, both via USING (pid)).
            const searchWhere = textSearchWhere(terms, [
                'f.label',
                'f.description',
                'CAST(f.place_name AS VARCHAR)',
            ]);
            const score = textSearchScore(terms, [
                { col: 'f.label',                       weight: 3 },
                { col: 'f.description',                 weight: 1 },
                { col: 'CAST(f.place_name AS VARCHAR)', weight: 2 },
            ]);

            // Two SQL shapes — one per scope. The fix per #179 round-2
            // review: in area mode, the viewport predicate MUST run BEFORE
            // the top-50 selection, otherwise we're searching only the
            // global top-50 within the area ("current viewport among the
            // global top 50") rather than "top 50 within the current
            // viewport." For broad terms like `pottery`, the global top-50
            // is concentrated in a few hot regions, so a Sudan-area query
            // would return zero even though Sudan has plenty of pottery.
            //
            // World mode keeps the original CTE-then-LEFT-JOIN shape so
            // samples that have facets but no `samples_map_lite` row
            // (i.e., no coordinates) still appear in the results, with
            // null lat/lng. The click-to-fly handler already guards on
            // isNaN(lat).
            //
            // Area mode uses INNER JOIN inside the candidate selection
            // because area-scoped search by definition requires
            // coordinates. Drop coord-less samples before ranking; apply
            // the viewport predicate; THEN top-50.
            let results;
            if (effectiveScope === 'area') {
                const bboxSQL = viewerBboxSQL('l.latitude', 'l.longitude');
                if (!bboxSQL) {
                    // Camera couldn't produce a view rectangle (shouldn't
                    // happen in practice; defensive). Fall through to the
                    // world query so the user gets results, with a console
                    // hint for diagnostics.
                    console.warn('Area scope requested but no view rectangle; falling back to world.');
                    results = await runWorldQuery();
                } else {
                    results = await db.query(`
                        SELECT f.pid, f.label, f.source, l.latitude, l.longitude,
                               f.place_name, (${score}) AS relevance_score
                        FROM read_parquet('${facets_url}') f
                        INNER JOIN read_parquet('${lite_url}') l USING (pid)
                        WHERE ${searchWhere}
                          ${bboxSQL}
                        ${sourceFilterSQL('f.source')}
                        ${facetFilterSQL()}
                        ORDER BY relevance_score DESC, f.label
                        LIMIT 50
                    `);
                }
            } else {
                results = await runWorldQuery();
            }

            async function runWorldQuery() {
                return db.query(`
                    WITH matches AS (
                        SELECT f.pid, f.label, f.source, f.place_name,
                               (${score}) AS relevance_score
                        FROM read_parquet('${facets_url}') f
                        WHERE ${searchWhere}
                        ${sourceFilterSQL('f.source')}
                        ${facetFilterSQL()}
                        ORDER BY relevance_score DESC
                        LIMIT 50
                    )
                    SELECT m.pid, m.label, m.source, l.latitude, l.longitude,
                           m.place_name, m.relevance_score
                    FROM matches m
                    LEFT JOIN read_parquet('${lite_url}') l USING (pid)
                    ORDER BY m.relevance_score DESC, m.label
                `);
            }
            resultsCount = results.length;
            if (results.length === 0) {
                searchResults.textContent = `No results for "${term}"`;
                return;
            }
            searchResults.textContent = `${results.length}${results.length === 50 ? '+' : ''} results for "${term}"`;

            // Show results in the samples panel
            const sampEl = document.getElementById('samplesSection');
            if (sampEl) {
                let h = `<h4>Search: "${term}" (${results.length})</h4>`;
                for (const s of results) {
                    const color = SOURCE_COLORS[s.source] || '#666';
                    const name = SOURCE_NAMES[s.source] || s.source;
                    const sUrl = sourceUrl(s.pid);
                    h += `<div class="sample-row" style="cursor: pointer;" data-lat="${s.latitude}" data-lng="${s.longitude}" data-pid="${s.pid}">
                        <div style="display: flex; align-items: center; gap: 6px;">
                            ${sUrl ? `<a class="sample-label" href="${sUrl}" target="_blank" rel="noopener noreferrer" style="color: #1565c0; text-decoration: none;">${s.label || s.pid}</a>` : `<span class="sample-label">${s.label || s.pid}</span>`}
                            <span class="source-badge" style="background: ${color}; font-size: 10px;">${name}</span>
                        </div>
                    </div>`;
                }
                sampEl.innerHTML = h;

                // Click search result → treat as a full selection event
                // (issue #207 item 8 → Codex follow-up): freshness token
                // bump, sample-card hydration, selection state, flight,
                // and lazy detail load — matching the on-globe sample
                // click ceremony at line ~944. Without the full ceremony
                // a slow prior selection load could repaint the panel
                // after the click, leaving UI inconsistent with URL.
                const resultsByPid = new Map(results.map(s => [s.pid, s]));
                sampEl.querySelectorAll('.sample-row[data-lat]').forEach(row => {
                    row.addEventListener('click', async (e) => {
                        if (e.target.tagName === 'A') return; // let links work
                        const pid = row.dataset.pid;
                        const sample = pid ? resultsByPid.get(pid) : null;
                        if (!sample || sample.latitude == null || sample.longitude == null) return;

                        // Bump the freshness token BEFORE any async work so
                        // a prior cluster/sample detail load can't repaint
                        // the panel after we navigate.
                        const isStale = freshSelectionToken(viewer);

                        viewer._globeState.selectedPid = pid;
                        viewer._globeState.selectedH3 = null;
                        updateSampleCard({
                            pid: sample.pid,
                            label: sample.label,
                            source: sample.source,
                            lat: sample.latitude,
                            lng: sample.longitude,
                            place_name: sample.place_name,
                            result_time: sample.result_time
                        });
                        viewer.camera.flyTo({
                            destination: Cesium.Cartesian3.fromDegrees(sample.longitude, sample.latitude, 50000),
                            duration: 1.5
                        });

                        // Lazy-load full description (mirrors the globe
                        // click handler). Don't clear samplesSection here —
                        // it currently holds the search results the user
                        // is browsing.
                        try {
                            const detail = await db.query(`
                                SELECT description
                                FROM read_parquet('${wide_url}')
                                WHERE pid = '${pid.replace(/'/g, "''")}'
                                LIMIT 1
                            `);
                            if (isStale()) return;
                            if (detail && detail.length > 0) updateSampleDetail(detail[0]);
                            else updateSampleDetail({ description: '' });
                        } catch(err) {
                            if (isStale()) return;
                            console.error("Search-row detail query failed:", err);
                            updateSampleDetail(null);
                        }
                    });
                });
            }

            // Fly to the first result. Skip for area-scoped searches —
            // the user is already at the area they care about; flying
            // would zoom in and disorient.
            //
            // Auto-flight is a NUDGE, not an explicit selection — clear
            // any prior selectedPid/selectedH3 so the resulting URL
            // doesn't carry stale selection state across the flight
            // (issue #207 item 8). User clicks on a specific row to
            // establish a new selection.
            if (effectiveScope === 'world' && results[0].latitude && results[0].longitude) {
                viewer._globeState.selectedPid = null;
                viewer._globeState.selectedH3 = null;
                viewer.camera.flyTo({
                    destination: Cesium.Cartesian3.fromDegrees(results[0].longitude, results[0].latitude, 200000),
                    duration: 1.5
                });
            }
        } catch(err) {
            console.error("Search failed:", err);
            searchResults.textContent = `Search error: ${err.message}`;
            errorMessage = err.message || String(err);
        } finally {
            performance.mark(markEnd);
            try { performance.measure(`search-${searchId}`, markStart, markEnd); } catch (e) {}
            const elapsedMs = performance.now() - tStart;

            // Per-URL byte data from data.isamples.org during the search
            // window. transferSize is 0 cross-origin without Timing-Allow-Origin;
            // encodedBodySize is reported as a fallback. Per-URL detail (rather
            // than just summed bytes) lets analysis post-hoc-filter concurrent
            // fetches that are not actually attributable to the search.
            const seenUrls = [];
            let transferBytes = 0;
            let bodyBytes = 0;
            try {
                const entries = performance.getEntriesByType('resource');
                for (const e of entries) {
                    if (!e.name.startsWith(R2_BASE)) continue;
                    if (e.startTime < tStart || e.startTime > tStart + elapsedMs) continue;
                    seenUrls.push({
                        name: e.name,
                        transfer_size: e.transferSize || 0,
                        body_size: e.encodedBodySize || 0,
                    });
                    transferBytes += (e.transferSize || 0);
                    bodyBytes += (e.encodedBodySize || 0);
                }
            } catch (e) {}

            // Structured log for Playwright capture (#167).
            try {
                console.log(JSON.stringify({
                    event: 'isamples.search',
                    id: searchId,
                    term: term,
                    terms_count: terms.length,
                    scope: effectiveScope,
                    results_count: resultsCount,
                    elapsed_ms: Math.round(elapsedMs),
                    bytes_transfer: transferBytes,
                    bytes_body: bodyBytes,
                    seen_urls: seenUrls,
                    has_source_filter: getActiveSources().length !== SOURCE_VALUES.length,
                    has_facet_filter: hasFacetFilters(),
                    error: errorMessage,
                }));
            } catch (e) {}

            // Append a row to the ?perf=1 panel if it's open. The panel
            // renders once at boot from existing performance.measure entries
            // (perfPanel cell, ~:2010); this hooks each subsequent search
            // so the panel stays current per the #173 review.
            try {
                const panel = document.getElementById('perfPanel');
                if (panel) {
                    const tbl = panel.querySelector('table');
                    if (tbl) {
                        const fmt = (ms) => ms >= 1000
                            ? (ms / 1000).toFixed(2) + ' s'
                            : Math.round(ms) + ' ms';
                        const tr = document.createElement('tr');
                        const labelCell = document.createElement('td');
                        labelCell.style.cssText = 'padding:1px 8px 1px 0;color:#bbb;';
                        labelCell.textContent = `search #${searchId} ${effectiveScope}: "${term}" (${resultsCount})`;
                        const valCell = document.createElement('td');
                        valCell.style.cssText = 'padding:1px 0;text-align:right;color:#a5d6a7;font-variant-numeric:tabular-nums;';
                        valCell.textContent = fmt(elapsedMs);
                        tr.appendChild(labelCell);
                        tr.appendChild(valCell);
                        tbl.appendChild(tr);
                    }
                }
            } catch (e) {}
        }
    }

    if (searchAreaBtn) searchAreaBtn.addEventListener('click', () => doSearch('area'));
    if (searchWorldBtn) searchWorldBtn.addEventListener('click', () => doSearch('world'));
    // Slim-overlay submit button — same behavior as Enter on `#sampleSearch`.
    // Uses `_searchScope` so URL-hydrated `?search_scope=area` still routes
    // to the area-scoped query path even though the scope toggle UI is
    // hidden in the slim treatment.
    const searchSubmitBtn = document.getElementById('searchSubmitBtn');
    if (searchSubmitBtn) searchSubmitBtn.addEventListener('click', () => doSearch(_searchScope));
    // Enter key uses the last-clicked scope (or the URL-hydrated scope if
    // no button has been clicked yet). Defaults to 'world' for keyboard-only
    // users on first invocation.
    if (searchInput) searchInput.addEventListener('keydown', (e) => {
        // Skip Enter during IME composition — IMEs send Enter to commit a
        // candidate, and submitting then would fire on the pre-commit value.
        if (e.key === 'Enter' && !e.isComposing && e.keyCode !== 229) {
            doSearch(_searchScope);
        }
    });

    // Sidebar open-text search (M-1B). Mirrors #sampleSearch so there's one
    // logical query term with two input chrome. Enter on sidebar always
    // submits world scope — typed-text-from-sidebar implies "find anywhere".
    // The mirror guards against feedback loops by comparing values before
    // setting; setting .value does not fire 'input' so a simple guard suffices.
    const searchInputSidebar = document.getElementById('sampleSearchSidebar');
    if (searchInputSidebar && searchInput) {
        searchInputSidebar.addEventListener('input', () => {
            if (searchInput.value !== searchInputSidebar.value) {
                searchInput.value = searchInputSidebar.value;
            }
        });
        searchInput.addEventListener('input', () => {
            if (searchInputSidebar.value !== searchInput.value) {
                searchInputSidebar.value = searchInput.value;
            }
        });
    }
    if (searchInputSidebar) searchInputSidebar.addEventListener('keydown', (e) => {
        if (e.key === 'Enter' && !e.isComposing && e.keyCode !== 229) {
            doSearch('world');
        }
    });

    if (searchInput && searchInput.value.trim().length >= 2) {
        doSearch(_searchScope);
    }

    refreshFacetCounts();

    // --- Deep-link: restore selection from initial hash ---
    // Sample mode wins if both &pid= and &h3= are present (see EXPLORER_CLUSTER_URL_PROPOSAL §4).
    // The boot path runs once, but the hashchange listener is already registered
    // by this point — back/forward or a manual hash edit during the boot await
    // could supersede this lookup. Capture the same freshness token the
    // hashchange handler uses; bumping it here also invalidates any in-flight
    // lookups.
    // Wrap in try/finally so `_suppressHashWrite = false` always runs even if
    // a stale early-return aborts the deep-link work — otherwise a no-lat/lng
    // hashchange during boot could leave hash writes suppressed forever.
    const isStale = freshSelectionToken(viewer);
    const ih = viewer._initialHash;
    try {
        if (ih.pid) {
            viewer._globeState.selectedPid = ih.pid;
            viewer._globeState.selectedH3 = null;
            try {
                const sample = await db.query(`
                    SELECT pid, label, source, latitude, longitude, place_name, result_time
                    FROM read_parquet('${lite_url}')
                    WHERE pid = '${ih.pid.replace(/'/g, "''")}'
                    LIMIT 1
                `);
                if (isStale()) return "active";
                if (sample && sample.length > 0) {
                    const s = sample[0];
                    updateSampleCard({
                        pid: s.pid, label: s.label, source: s.source,
                        lat: s.latitude, lng: s.longitude,
                        place_name: s.place_name, result_time: s.result_time
                    });
                    const detail = await db.query(`
                        SELECT description FROM read_parquet('${wide_url}')
                        WHERE pid = '${ih.pid.replace(/'/g, "''")}'
                        LIMIT 1
                    `);
                    if (isStale()) return "active";
                    if (detail && detail.length > 0) updateSampleDetail(detail[0]);
                    else updateSampleDetail({ description: '' });
                }
            } catch(err) {
                console.error("Deep-link pid query failed:", err);
            }
        } else if (ih.h3) {
            viewer._globeState.selectedH3 = ih.h3.toLowerCase();
            const meta = await fetchClusterByH3(ih.h3);
            if (isStale()) return "active";
            if (meta) {
                viewer._globeState.selectedH3 = meta.h3_cell;  // canonical lowercase
                await hydrateClusterUI(meta, isStale);
            } else {
                // Unknown / malformed h3, OR filtered out by ?sources=. Drop it
                // from runtime state so buildHash() doesn't keep emitting it.
                viewer._globeState.selectedH3 = null;
            }
        }
    } finally {
        // Enable hash writing now that everything is initialized — runs even on
        // stale-abort early returns above.
        viewer._suppressHashWrite = false;
    }

    // Deep-link mode hydration (issue #201 Bug B + issue #207 item 4).
    // The boot path positions the camera via `camera.setView`, which in
    // some cases (notably when the URL omits `heading` — i.e. heading
    // defaults to 0 — at point altitudes) does not raise `camera.changed`,
    // so the camera-changed handler never runs and the URL's `mode=point`
    // is silently ignored. Drive the mode transition explicitly here so
    // the boot is independent of whether `setView` happened to fire the
    // event.
    //
    // Trigger on EITHER `ih.mode === 'point'` OR low altitude (< ENTER_POINT_ALT).
    // The altitude branch closes the loophole introduced by #203's early
    // URL write: a user copying mid-transition can produce a URL like
    // `alt=8000` *without* `mode=point`, which previously round-tripped
    // as cluster mode at low altitude. Now boot enters point mode for
    // any URL whose altitude says it should. `tryEnterPointModeIfNeeded()`
    // short-circuits if alt >= ENTER_POINT_ALT or we're already in point
    // mode, so this is a no-op for cluster deep-links at cluster altitude.
    if (ih.mode === 'point' || (ih.alt != null && ih.alt < ENTER_POINT_ALT)) {
        // pushHistory: false — boot should reconcile state without adding
        // a history entry (issue #207 item 3).
        await tryEnterPointModeIfNeeded({ pushHistory: false });
    }

    return "active";
}
```

```{ojs}
//| echo: false
//| output: false

// === Performance timing panel (opt-in: append ?perf=1 to URL) ===
// v0: reads performance.mark/measure entries and renders a small fixed panel.
// Reports navigation→duckdb_init, navigation→viewer_init, phase 1 res4 load,
// and navigation→first paint. Also dumps to console.table for CI / Playwright.
perfPanel = {
    if (!phase1) return;  // wait for phase 1 to have run

    const params = new URLSearchParams(location.search);
    const isOn = params.get('perf') === '1';
    if (!isOn) return;

    // Give first-paint a tick to fire, then collect
    await new Promise(r => setTimeout(r, 100));

    const origin = performance.timeOrigin;
    const mark = (name) => {
        const e = performance.getEntriesByName(name, 'mark').pop();
        return e ? e.startTime : null;
    };
    const measure = (name) => {
        const e = performance.getEntriesByName(name, 'measure').pop();
        return e ? e.duration : null;
    };

    // Paint timings from the browser (free, no instrumentation needed)
    const paintEntries = performance.getEntriesByType('paint');
    const fcp = paintEntries.find(e => e.name === 'first-contentful-paint')?.startTime;
    const fp = paintEntries.find(e => e.name === 'first-paint')?.startTime;

    const rows = [
        ['first-paint (browser)',        fp],
        ['first-contentful-paint',        fcp],
        ['duckdb init',                   measure('duckdb_init')],
        ['viewer init',                   measure('viewer_init')],
        ['nav → viewer ready',            mark('viewer-init-end')],
        ['phase 1 res4 (duration)',       measure('p1')],
        ['nav → phase 1 complete',        mark('p1-end')],
        ['nav → first globe frame',       mark('first-globe-frame')],
    ].filter(([, v]) => v != null);

    // Append search timings if any have run by the time the panel renders
    // (#167). Each search emits a structured console.log; the panel surface
    // is purely informational here.
    const searchMeasures = performance.getEntriesByType('measure')
        .filter(e => e.name.startsWith('search-'));
    for (const m of searchMeasures) {
        rows.push([`search ${m.name.replace(/^search-/, '#')}`, m.duration]);
    }

    // Console table for CI / offline capture
    console.table(Object.fromEntries(rows.map(([k, v]) => [k, `${v.toFixed(0)} ms`])));

    // Render a small floating panel
    const fmt = (ms) => ms == null ? '—' : ms >= 1000 ? `${(ms/1000).toFixed(2)} s` : `${ms.toFixed(0)} ms`;
    const panel = document.createElement('div');
    panel.id = 'perfPanel';
    panel.style.cssText = `
        position: fixed; bottom: 12px; right: 12px; z-index: 9999;
        background: rgba(0,0,0,0.82); color: #e8f5e9; padding: 10px 12px;
        border-radius: 6px; font: 11px/1.4 ui-monospace, SFMono-Regular, monospace;
        max-width: 320px; box-shadow: 0 2px 12px rgba(0,0,0,0.3);
    `;
    panel.innerHTML = `
        <div style="font-weight:600;color:#fff;margin-bottom:6px;display:flex;justify-content:space-between;align-items:center;">
            <span>⏱ Perf timings</span>
            <button id="perfClose" style="background:none;border:none;color:#aaa;cursor:pointer;font-size:14px;padding:0 4px;">×</button>
        </div>
        <table style="border-collapse:collapse;width:100%;">
            ${rows.map(([label, v]) => `
                <tr><td style="padding:1px 8px 1px 0;color:#bbb;">${label}</td>
                    <td style="padding:1px 0;text-align:right;color:#a5d6a7;font-variant-numeric:tabular-nums;">${fmt(v)}</td></tr>
            `).join('')}
        </table>
        <div style="margin-top:6px;color:#777;font-size:10px;">timeOrigin: ${new Date(origin).toISOString().split('T')[1].slice(0,12)}</div>
    `;
    document.body.appendChild(panel);
    panel.querySelector('#perfClose').onclick = () => panel.remove();

    return "shown";
}
```

## How This Demo Works

Pre-aggregated H3 hexagonal indices achieve near-instant globe rendering, with seamless drill-down to individual samples:

| Phase | Data | Size | Points |
|-------|------|------|--------|
| **Instant** | H3 res4 | 580 KB | 38K clusters (continental) |
| **Zoom in** | H3 res6 | 1.6 MB | 112K clusters (city) |
| **Zoom more** | H3 res8 | 2.5 MB | 176K clusters (neighborhood) |
| **Zoom deep** | Map lite | 60 MB (range req.) | Up to 5K individual samples |
| **Click sample** | Full dataset | ~280 MB (range req.) | Full metadata for 1 sample |

**4 parquet files, zero backend.** All queries run in your browser via DuckDB-WASM with HTTP range requests — only the bytes you need are transferred.

## See Also

- [Deep-Dive Analysis](/tutorials/zenodo_isamples_analysis.html) — DuckDB-WASM SQL tutorial
- [Tutorials](/tutorials/) — index of all interactive tutorials