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_202606_h3_summary_res4.parquet">
        <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/isamples_202606_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>
<script src="https://cdn.jsdelivr.net/npm/heatmap.js@2.0.5/build/heatmap.min.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;
    }
    /* Busy indicator while a filter/search/facet update is in flight.
       `progress` (arrow + spinner), NOT `wait` (hourglass): nothing freezes —
       we're signaling "updating", not "blocked". PAGE-WIDE on purpose: a CSS
       cursor only shows where the pointer actually is, and these updates are
       triggered with the pointer OFF the map (in the search box / sidebar
       checkboxes), so a map-only rule was invisible in practice. The `*` with
       !important overrides per-element cursors (text inputs, the Cesium canvas,
       buttons) so the signal shows wherever the pointer rests. The
       body.explorer-busy class is toggled by the depth-counted busyAcquire/
       busyRelease around the facet-change, source-change, and search/concept
       commit paths (with a 120s watchdog failsafe so it can never stick).
       Pan/zoom viewport reloads don't set the class yet — deferred follow-up. */
    body.explorer-busy, body.explorer-busy * {
        cursor: progress !important;
    }
    /* 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;
        }
    }
    .side-panel {
        display: flex;
        flex-direction: column;
        gap: 8px;
        max-height: var(--explorer-map-height);
        overflow-y: auto;
    }
    .filter-chip-host {
        position: sticky;
        top: 0;
        z-index: 3;
    }
    .filter-chip-host[hidden] { display: none; }
    .described-by-chip {
        display: flex;
        align-items: center;
        justify-content: space-between;
        gap: 8px;
        background: #ede7f6;
        border: 1px solid #d1c4e9;
        border-radius: 6px;
        color: #5e35b1;
        font-size: 12px;
        font-weight: 600;
        padding: 8px 10px;
    }
    .described-by-chip-label {
        min-width: 0;
        overflow-wrap: anywhere;
    }
    .described-by-chip-clear {
        flex: 0 0 auto;
        background: transparent;
        border: 0;
        border-radius: 4px;
        color: inherit;
        cursor: pointer;
        font-size: 14px;
        line-height: 1;
        padding: 2px 4px;
    }
    .described-by-chip-clear:hover,
    .described-by-chip-clear:focus {
        background: rgba(94, 53, 177, 0.12);
        outline: none;
    }
    .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;
    }
    .stats-disclosure { border-top: 0; padding-top: 0; margin-top: 0; }
    .stats-body { padding: 4px 0 0; }
    .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; }
    .heatmap-control {
        display: flex;
        align-items: center;
        gap: 5px;
        margin-top: 8px;
        font-size: 12px;
        cursor: pointer;
        user-select: none;
    }
    .heatmap-control input[type="checkbox"] { margin: 0; width: 12px; height: 12px; cursor: pointer; }
    #heatmapStatus {
        display: none;
        margin-top: 3px;
        font-size: 11px;
        color: #888;
        font-style: italic;
    }
    .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; }
    /* In-map detail card (Hana Figma node 225:1700). Anchored near the
       clicked sample dot, points "up-left" via drop shadow. Same data
       as the side-panel card; this is the in-map surface companion.
       See issue #226 for click-semantics framing. */
    .in-map-card {
        position: absolute;
        /* Sits above search overlay (1000), results line (1000), color
           legend (1000), and Cesium toolbar (z=2). Per Codex review of
           #226: any value below 1000 would let the card slide
           underneath those surfaces. */
        z-index: 1001;
        width: 220px;
        background: white;
        border: 0.7px solid #d9d9d9;
        border-radius: 7px;
        padding: 8px;
        filter: drop-shadow(-6px 6px 5px rgba(0,0,0,0.3));
        font-family: Inter, system-ui, sans-serif;
        font-size: 12px;
        line-height: 1.35;
        pointer-events: auto;
    }
    .in-map-card[hidden] { display: none; }
    .in-map-card .imc-head {
        display: flex; align-items: flex-start; justify-content: space-between;
        gap: 6px; margin-bottom: 6px;
    }
    .in-map-card .imc-title {
        font-weight: 700; color: #36c; text-decoration: underline;
        font-size: 13px; line-height: 1.25;
        word-break: break-word; flex: 1 1 auto;
    }
    .in-map-card .imc-title:hover { color: #0d47a1; }
    .in-map-card .imc-close {
        flex: 0 0 auto; background: none; border: none; cursor: pointer;
        font-size: 16px; line-height: 1; color: #666; padding: 0 2px;
    }
    .in-map-card .imc-close:hover { color: #000; }
    .in-map-card .imc-body { display: flex; gap: 8px; align-items: flex-start; }
    .in-map-card .imc-meta {
        flex: 1 1 auto; min-width: 0;
        /* Hard wrap: protects against unresolved vocab URIs or other
           long strings (no spaces → would otherwise overflow the
           220px card). overflow-wrap handles the no-space case;
           word-break is the legacy fallback. */
        overflow-wrap: anywhere;
        word-break: break-word;
    }
    .in-map-card .imc-meta > div { margin-bottom: 2px; }
    .in-map-card .imc-meta b { font-weight: 700; }
    .in-map-card .imc-coords { color: #555; margin-top: 4px; }
    .in-map-card .imc-thumb {
        flex: 0 0 auto; width: 56px; height: 56px;
        border: 1px solid #d9d9d9; border-radius: 3px;
        background: #f5f5f5;
        display: flex; align-items: center; justify-content: center;
        overflow: hidden;
    }
    .in-map-card .imc-thumb img { width: 100%; height: 100%; object-fit: cover; }
    .in-map-card .imc-thumb-placeholder {
        width: 100%; height: 100%; position: relative;
        background: linear-gradient(135deg, transparent calc(50% - 0.5px), #bbb calc(50% - 0.5px), #bbb calc(50% + 0.5px), transparent calc(50% + 0.5px)),
                    linear-gradient(45deg, transparent calc(50% - 0.5px), #bbb calc(50% - 0.5px), #bbb calc(50% + 0.5px), transparent calc(50% + 0.5px));
    }
    .in-map-card .imc-source-badge {
        display: inline-block; color: white; padding: 1px 6px;
        border-radius: 6px; font-size: 10px; font-weight: 700;
        margin-bottom: 4px;
    }
    .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;
    }
    /* Was an <a> until #226 — kept the visual styling but the element
       is now a role="button" span (no href) so click-anywhere-in-row
       opens the detail card uniformly. The external source URL lives
       inside the card. Keyboard parity via tabindex=0 + Enter/Space
       handled in the row-click handler. */
    .table-link {
        color: #1565c0; text-decoration: none;
        cursor: pointer; background: none; border: 0; padding: 0;
        font: inherit;
    }
    .table-link:hover { text-decoration: underline; }
    .table-link:focus-visible {
        outline: 2px solid #1565c0; outline-offset: 2px; border-radius: 2px;
    }
    .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>
<!-- In-map detail card (Hana Figma node 225:1700). Populated by the
     sample-click handler. Positioned absolutely inside .map-wrap.
     See issue #226 for the unified click-semantics framing. -->
<div id="inMapCard" class="in-map-card" hidden role="dialog" aria-label="Sample details"></div>
</div>
<div class="side-panel">
<div id="activeSearchChipHost" class="filter-chip-host" hidden></div>
<div class="panel-section">
<div class="filter-section stats-disclosure">
<div class="filter-header" role="button" tabindex="0" aria-expanded="false" aria-controls="statsPanelBody" onclick="const body = this.nextElementSibling; const open = body.style.display === 'none'; body.style.display = open ? 'block' : 'none'; this.setAttribute('aria-expanded', open ? 'true' : 'false'); this.querySelector('span').textContent = open ? '▾' : '▸';" onkeydown="if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); this.click(); }">
Stats <span>▸</span>
</div>
<div class="filter-body stats-body" style="display: none;" id="statsPanelBody">
<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>
</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>
<label class="heatmap-control"><input type="checkbox" id="heatmapToggle"> Heatmap (filtered density)</label>
<div id="heatmapStatus" aria-live="polite"></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 ===
// DEV: override the data origin to a fast local parquet mirror so the
// verify loop doesn't pay 40-90s of remote range-fetch per cold load.
//   ?data_base=/data            (same-origin mirror under docs/data, served
//                                by a RANGE-capable server — stock python
//                                http.server returns 200 not 206, breaking
//                                DuckDB-WASM partial reads; use dev_server.py)
//   localStorage ISAMPLES_DATA_BASE  (sticky per-browser override)
// Defaults to the production R2 origin, so shipped builds are unchanged.
R2_BASE = (() => {
    const raw = new URLSearchParams(location.search).get('data_base')
        || (typeof localStorage !== 'undefined' && localStorage.getItem('ISAMPLES_DATA_BASE'))
        || "https://data.isamples.org";
    // DuckDB-WASM's httpfs only range-fetches ABSOLUTE http(s) URLs. A root-
    // relative override (?data_base=/data) is read as a virtual-filesystem
    // glob and fails with "No files found that match the pattern" — silently,
    // before any network fetch. Resolve a relative override against the page
    // origin so the ergonomic ?data_base=/data form actually works. The prod
    // default and absolute overrides (http://localhost:8099/data) pass through.
    return raw.startsWith('/') ? new URL(raw, location.origin).href : raw;
})()
h3_res4_url = `${R2_BASE}/isamples_202606_h3_summary_res4.parquet`
h3_res6_url = `${R2_BASE}/isamples_202606_h3_summary_res6.parquet`
h3_res8_url = `${R2_BASE}/isamples_202606_h3_summary_res8.parquet`
lite_url = `${R2_BASE}/isamples_202606_samples_map_lite.parquet`
// Explicit versioned wide (#272: OC concept-enriched — popups read material/
// object-type from this file). The stable alias `current/wide.parquet` still
// points at the previous wide until the production cutover flips the manifest;
// pinning the version here keeps staging and prod each self-consistent.
wide_url = `${R2_BASE}/isamples_202606_wide.parquet`
// v2 carries object_type alongside material and context (URI-string columns).
facets_url = `${R2_BASE}/isamples_202606_sample_facets_v2.parquet`
facet_summaries_url = `${R2_BASE}/isamples_202606_facet_summaries.parquet`
// Pre-aggregated single-filter cache for fast cross-filtered facet counts.
cross_filter_url = `${R2_BASE}/isamples_202606_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');
    if (!input) return;
    const params = new URLSearchParams(location.search);
    const q = params.get('search');
    if (q != null) {
        input.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(opts = {}) {
    const params = new URLSearchParams(location.search);
    const searchInput = document.getElementById('sampleSearch');
    const q = searchInput ? searchInput.value.trim() : '';
    // #248 Flavor A: `search=` (free text) and `described-by=` (concept URI)
    // both produce the singleton search_pids and are mutually exclusive.
    //
    // doSearch passes `opts.commitText` to AUTHORITATIVELY persist (a term) or
    // clear ('') a text search: it calls writeQueryState EARLY, before
    // buildSearchFilter flips __searchFilter.kind to 'text', so it can't read
    // filter state — its committed term is the source of truth.
    //
    // Every OTHER caller (facet-change + source-change handlers, doDescribedBy)
    // omits commitText, so the URL mirrors the COMMITTED filter in
    // window.__searchFilter, NOT the raw text box. This is Codex finding #1:
    // with an active concept filter, draft (un-submitted) text in the box plus
    // a facet/source toggle must NOT clobber `described-by=` with a phantom
    // `search=`. Keying passive writes off __searchFilter (concept) vs. the box
    // (text) keeps the URL honest about what's actually filtering.
    const sf = (typeof window !== 'undefined') ? window.__searchFilter : null;
    const conceptActive = !!(sf && sf.active && sf.kind === 'concept' && sf.uri);
    if (opts.commitText !== undefined) {
        if (opts.commitText) params.set('search', opts.commitText);
        else params.delete('search');
        params.delete('described-by');
    } else if (conceptActive) {
        params.set('described-by', sf.uri);
        params.delete('search');
    } else {
        // No concept filter and no explicit text commit: preserve the prior
        // (pre-#248) behavior — reflect the text box. A committed text search
        // keeps its term across facet/source toggles (the box still holds it);
        // an inactive/empty state clears `search=`.
        params.delete('described-by');
        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;
}

// Single source of truth for #facetNote visibility. The note ("filter
// takes effect at neighborhood zoom") explains the cluster-mode honesty
// gap: H3 summary parquets only carry `dominant_source`, so material /
// context / object_type filters cannot affect cluster counts. Invariant:
//   visible ⇔ (any facet active) ∧ (mode === 'cluster') ∧ (heatmap off)
// Call sites that mutate any conjunct MUST call this to keep DOM and
// state in agreement:
//   - facetFilters cell (URL deep-link restore, #234 step 1)
//   - handleFacetFilterChange (user toggles a facet checkbox)
//   - enterPointMode / exitPointMode (mode transitions)
//   - heatmapToggle change handler (#233 phase 3)
// The heatmap conjunct: when the heatmap overlay is on, it IS the
// filter-aware density view (dots are generated from filtered data, not
// pre-baked dominant_source), so the apology is false and must be hidden
// (#233). The toggle state is read straight off the DOM rather than via
// heatmapEnabled() so this helper stays reachable from cells that run
// before the viewer cell defines that function.
function syncFacetNote() {
    const el = document.getElementById('facetNote');
    if (!el) return;
    const active = hasFacetFilters();
    const inCluster = (typeof viewer !== 'undefined') && viewer._globeState?.mode === 'cluster';
    const heatOn = document.getElementById('heatmapToggle')?.checked === true;
    el.style.display = (active && inCluster && !heatOn) ? 'block' : 'none';
}

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}`;
}

// True when the current camera shows ≈the whole world (initial zoom-out
// state), or when the camera can't compute a rectangle at all (off-globe).
// In either case a viewport bbox predicate would be a no-op, so fast-paths
// that depend on "no spatial constraint" (e.g. the pre-aggregated facet
// cross-filter cube) remain valid and can be used.
//
// Used by `updateCrossFilteredCounts` (B1, issue #234 step 3) to decide
// whether to gate the cube fast-path off and JOIN to `lite_url` for a
// bbox-scoped slow-path query.
//
// Implementation note — why an altitude shortcut:
//   At high altitudes Cesium's `computeViewRectangle` saturates at the
//   sphere's extent for some camera angles but returns a tight bounding
//   rect for others (e.g. at alt=5000 km over the equator the rect is
//   ≈hemispheric, not full). The user's intuition is "max zoom-out = global
//   counts," and at the explorer's default `globalRect` (which fits the
//   `[-180,-60,180,80]` data extent and sits roughly at altitude ≈12000 km)
//   the per-source legend totals should match the baselines, not jiggle on
//   tiny camera rotations. The altitude check captures that "I'm zoomed all
//   the way out" intent regardless of the exact rect Cesium reports. Below
//   the altitude threshold we still let the rect vote "global" so flyTo
//   to a true world-rect destination keeps working.
//
//   Constants live inside the function (not top-level `const`) because
//   Quarto `{ojs}` cells reject top-level `const`/`let`/`var` and a bad
//   declaration cascades — breaking every dependent cell (memory note
//   `feedback_qmd_ojs_top_level`).
function isGlobalView() {
    const ALT_THRESHOLD_M = 1.0e7;  // 10,000 km
    const LNG_PAD_DEG = 2;
    const LAT_PAD_DEG = 2;
    if (typeof viewer === 'undefined') return true;
    let h = NaN;
    try { h = viewer.camera.positionCartographic.height; } catch { /* mid-init */ }
    if (Number.isFinite(h) && h > ALT_THRESHOLD_M) return true;
    const b = paddedViewportBounds(0);
    if (!b) return true;              // off-globe → no meaningful bbox
    if (b.west > b.east) return false; // antimeridian-wrapping is never "global"
    return b.west  <= -180 + LNG_PAD_DEG
        && b.east  >=  180 - LNG_PAD_DEG
        && b.south <=  -90 + LAT_PAD_DEG
        && b.north >=   90 - LAT_PAD_DEG;
}

// === 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,
        heatmap: params.get('heatmap') === '1',
    };
}

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);
    // #233 phase 1: encode heatmap toggle in URL hash so "Copy Link to
    // Current View" preserves the overlay state. Reported by RY 2026-05-27
    // while reviewing PR #240 on staging.
    if (document.getElementById('heatmapToggle')?.checked) params.set('heatmap', '1');
    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>` : ''}`;
}

// === In-map detail card (Hana Figma 225:1700; issue #226) ============
// Companion floating surface to the side-panel sample card. Same data,
// anchored near the clicked dot. v1 reads the same fields that
// updateSampleCard() consumes; lazy-loaded thumbnail/feature/material
// follow the same async pattern as updateSampleDetail().
//
// Positioning: .map-wrap is position:relative; #cesiumContainer fills
// it, so Cesium canvas pixel coords (e.position from the scene click
// handler) translate 1:1 to absolute coords inside .map-wrap.
function showInMapCard(sample, screenPos) {
    const el = document.getElementById('inMapCard');
    if (!el) return;
    const color = SOURCE_COLORS[sample.source] || '#666';
    const name = SOURCE_NAMES[sample.source] || sample.source || '';
    const srcUrl = sourceUrl(sample.pid);
    const titleText = sample.label || sample.pid || 'Unnamed';
    const lat = sample.lat != null ? Number(sample.lat).toFixed(4) : '';
    const lng = sample.lng != null ? Number(sample.lng).toFixed(4) : '';
    const coords = (lat && lng) ? `${lat}, ${lng}` : '';

    // Codex review of #226: every interpolation below crosses an HTML
    // attribute or text boundary, so each value is escaped. The href
    // additionally only renders when srcUrl is a known-shape URL — we
    // do not put user-controlled data into the href attribute as a
    // raw string.
    const safeTitle = escapeHtml(titleText);
    const safeName = escapeHtml(name);
    const safeColor = escapeHtml(color);
    const safeCoords = escapeHtml(coords);
    const titleHtml = srcUrl
        ? `<a class="imc-title" href="${escapeHtml(srcUrl)}" target="_blank" rel="noopener noreferrer">${safeTitle}</a>`
        : `<span class="imc-title">${safeTitle}</span>`;

    el.innerHTML = `
        <div class="imc-head">
            ${titleHtml}
            <button class="imc-close" type="button" aria-label="Close" title="Close">×</button>
        </div>
        <div class="imc-body">
            <div class="imc-meta">
                <span class="imc-source-badge" style="background:${safeColor}">${safeName}</span>
                <div><b>Material:</b> <span id="imcMaterial">—</span></div>
                <div><b>Sample Feature:</b> <span id="imcFeature">—</span></div>
                <div><b>Specimen Type:</b> <span id="imcObjectType">—</span></div>
                ${safeCoords ? `<div class="imc-coords">${safeCoords}</div>` : ''}
            </div>
            <div class="imc-thumb" id="imcThumb">
                <div class="imc-thumb-placeholder" aria-label="No thumbnail"></div>
            </div>
        </div>
    `;

    // Wire close button.
    const closeBtn = el.querySelector('.imc-close');
    if (closeBtn) closeBtn.addEventListener('click', hideInMapCard);

    // Position with collision avoidance. Default: card to the right and
    // below the click point with a 12px offset. Flip horizontally if it
    // would overflow the map-wrap; clamp vertically to keep it on-canvas.
    const wrap = el.parentElement; // .map-wrap
    if (wrap && screenPos && typeof screenPos.x === 'number') {
        // Show invisibly first so we can measure.
        el.style.left = '0px';
        el.style.top = '0px';
        el.hidden = false;
        const wrapRect = wrap.getBoundingClientRect();
        const cardRect = el.getBoundingClientRect();
        const cardW = cardRect.width || 220;
        const cardH = cardRect.height || 120;
        let x = screenPos.x + 12;
        let y = screenPos.y + 12;
        // Flip to left of click if card would overflow right edge.
        if (x + cardW > wrapRect.width - 4) {
            x = screenPos.x - cardW - 12;
        }
        // Clamp.
        if (x < 4) x = 4;
        if (y + cardH > wrapRect.height - 4) y = wrapRect.height - cardH - 4;
        if (y < 4) y = 4;
        el.style.left = `${x}px`;
        el.style.top = `${y}px`;
    } else {
        el.hidden = false;
    }
}

function hideInMapCard() {
    const el = document.getElementById('inMapCard');
    if (!el) return;
    el.hidden = true;
}

// Populate the lazy-loaded fields (thumbnail, material, feature,
// specimen type) once the wide-parquet query returns. `detail` is the
// row from explorer.qmd's existing detail query, extended to include
// thumbnail_url / has_feature_of_interest / material_label /
// object_type_label. See updateSampleDetail() for the side-panel
// counterpart that uses the same row.
function populateInMapCardDetail(detail) {
    const el = document.getElementById('inMapCard');
    if (!el || el.hidden) return; // card was closed or replaced
    const setText = (id, val) => {
        const node = el.querySelector(`#${id}`);
        if (node) node.textContent = (val && String(val).trim()) ? val : 'Not Provided';
    };
    if (!detail) {
        setText('imcMaterial', null);
        setText('imcFeature', null);
        setText('imcObjectType', null);
        return;
    }
    setText('imcMaterial', detail.material_label);
    setText('imcFeature', detail.has_feature_of_interest);
    setText('imcObjectType', detail.object_type_label);

    if (detail.thumbnail_url) {
        const thumbEl = el.querySelector('#imcThumb');
        if (thumbEl) {
            // DOM construction (not innerHTML) so the thumbnail URL is
            // never interpolated into an HTML attribute string and the
            // onerror handler is a property, not an inline-JS string.
            // Codex review of #226.
            thumbEl.innerHTML = '';
            const img = document.createElement('img');
            img.alt = '';
            img.onerror = () => {
                const placeholder = document.createElement('div');
                placeholder.className = 'imc-thumb-placeholder';
                placeholder.setAttribute('aria-label', 'Thumbnail unavailable');
                thumbEl.innerHTML = '';
                thumbEl.appendChild(placeholder);
            };
            img.src = detail.thumbnail_url;
            thumbEl.appendChild(img);
        }
    }
}

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) {
            // Click on empty space → close the in-map card (deselect).
            hideInMapCard();
            return;
        }
        const meta = picked.id;
        const isStale = freshSelectionToken(v);

        if (typeof meta === 'object' && meta.type === 'sample') {
            // --- Individual sample click ---
            updateSampleCard(meta);
            // In-map floating card (issue #226). `e.position` is the
            // Cesium canvas pixel coord of the click; .map-wrap is
            // position:relative and #cesiumContainer fills it, so the
            // same x/y serves as absolute coords inside .map-wrap.
            showInMapCard(meta, { x: e.position.x, y: e.position.y });
            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 extended fields from wide parquet.
            // Extended beyond the original description-only query to
            // populate the in-map card (issue #226): thumbnail_url,
            // has_feature_of_interest, plus IdentifiedConcept labels
            // for material and specimen type via the wide row's
            // p__has_material_category[] / p__has_sample_object_type[]
            // arrays (DuckDB lists are 1-indexed).
            try {
                const pidEsc = meta.pid.replace(/'/g, "''");
                const detail = await db.query(`
                    SELECT
                        s.description,
                        s.thumbnail_url,
                        s.has_feature_of_interest,
                        mat_lbl.pref_label AS material_label,
                        obj_lbl.pref_label AS object_type_label
                    FROM read_parquet('${wide_url}') AS s
                    LEFT JOIN read_parquet('${wide_url}') AS mat
                      ON mat.row_id = s.p__has_material_category[1]
                     AND mat.otype = 'IdentifiedConcept'
                    LEFT JOIN read_parquet('${vocab_labels_url}') AS mat_lbl
                      ON mat_lbl.uri = mat.pid
                    LEFT JOIN read_parquet('${wide_url}') AS obj
                      ON obj.row_id = s.p__has_sample_object_type[1]
                     AND obj.otype = 'IdentifiedConcept'
                    LEFT JOIN read_parquet('${vocab_labels_url}') AS obj_lbl
                      ON obj_lbl.uri = obj.pid
                    WHERE s.pid = '${pidEsc}'
                      AND s.otype = 'MaterialSampleRecord'
                    LIMIT 1
                `);
                if (isStale()) return;
                if (detail && detail.length > 0) {
                    updateSampleDetail(detail[0]);
                    populateInMapCardDetail(detail[0]);
                } else {
                    updateSampleDetail({ description: '' });
                    populateInMapCardDetail(null);
                }
            } catch(err) {
                if (isStale()) return;
                console.error("Detail query failed:", err);
                updateSampleDetail(null);
                populateInMapCardDetail(null);
            }

        } else if (typeof meta === 'object' && meta.count) {
            // --- Cluster click ---
            updateClusterCard(meta);
            // Cluster click clears any prior sample selection; close
            // the in-map sample card so it doesn't outlive the context
            // that opened it (issue #226).
            hideInMapCard();
            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;
    };
    // #248: expose the URI→prefLabel resolver so the concept-filter producer
    // (buildConceptFilter, in the zoomWatcher cell) can label a `described-by=`
    // URI without re-querying vocab_labels. Best-effort: falls back to URI tail.
    if (typeof window !== 'undefined') window.conceptLabelForUri = prettyLabel;

    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();

        // Sync #facetNote visibility for URL-loaded filters. Restoring
        // checkbox state from `?material=…` does NOT fire `change`, so the
        // cluster-mode "filter takes effect at neighborhood zoom" note
        // would otherwise stay hidden on a shared deep-link even with
        // active facets. See #234 (roadmap step 1).
        syncFacetNote();

        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

    // A1 (#234 Step 4): semi-join predicate against the materialized
    // search_pids set, published by the search cell on window. Empty string
    // when no search is committed, so non-search queries are unchanged. Read
    // at query-build time (not cell-definition time), so it picks up a search
    // committed after this cell first ran.
    const searchFilterSQL = (col = 'pid') =>
        (typeof window !== 'undefined' && window.searchFilterSQL)
            ? window.searchFilterSQL(col) : '';

    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 || '';
                // #226: the title cell used to be an <a href={sourceUrl}>
                // that opened the source record on click. The href
                // contradicted the unified click-semantics goal (click
                // = open card, external link lives inside card), so
                // the element is now a role="button" span with the
                // same visual styling. Screen readers announce it as
                // a button, not as a misleading external link. The
                // external link is preserved one hop away in the
                // detail card's title.
                const safeLabel = escapeHtml(label);
                const labelHtml = `<span class="table-link" role="button" tabindex="0" aria-label="Open details for ${safeLabel}">${safeLabel}</span>`;
                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 => {
                // Row activation = open detail card. Pointer click on
                // any cell, Enter/Space on the role="button" title span,
                // and Enter on the row itself (when tab-focused on the
                // title) all route through the same handler. Issue
                // #226: there is no longer an <a href> in the row, so
                // the activation is uniform across surfaces.
                const activateRow = async (e) => {
                    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;
                    const sampleMeta = {
                        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
                    };
                    updateSampleCard(sampleMeta);
                    // Show the in-map card *immediately* (Codex review
                    // of #226). Previously we deferred showInMapCard()
                    // to flyTo.complete, but the lazy-load detail query
                    // could return inside the 1.5s flight window and
                    // populateInMapCardDetail() would either no-op
                    // (card still hidden) or mutate the previous-still-
                    // visible card. Anchoring at canvas centre is
                    // correct: that's where the sample lands after
                    // flyTo. The flight animates underneath the
                    // already-visible card.
                    const canvas = viewer.scene.canvas;
                    showInMapCard(sampleMeta, {
                        x: canvas.clientWidth / 2,
                        y: canvas.clientHeight / 2
                    });
                    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 {
                        // Same extended lazy-load as the map-click
                        // path — keeps the in-map card populated when
                        // the click originates from the table (issue
                        // #226). Wide-only via self-joins for material
                        // and specimen-type concept labels.
                        const pidEsc = pid.replace(/'/g, "''");
                        const detail = await db.query(`
                            SELECT
                                s.description,
                                s.thumbnail_url,
                                s.has_feature_of_interest,
                                mat_lbl.pref_label AS material_label,
                                obj_lbl.pref_label AS object_type_label
                            FROM read_parquet('${wide_url}') AS s
                            LEFT JOIN read_parquet('${wide_url}') AS mat
                              ON mat.row_id = s.p__has_material_category[1]
                             AND mat.otype = 'IdentifiedConcept'
                            LEFT JOIN read_parquet('${vocab_labels_url}') AS mat_lbl
                              ON mat_lbl.uri = mat.pid
                            LEFT JOIN read_parquet('${wide_url}') AS obj
                              ON obj.row_id = s.p__has_sample_object_type[1]
                             AND obj.otype = 'IdentifiedConcept'
                            LEFT JOIN read_parquet('${vocab_labels_url}') AS obj_lbl
                              ON obj_lbl.uri = obj.pid
                            WHERE s.pid = '${pidEsc}'
                              AND s.otype = 'MaterialSampleRecord'
                            LIMIT 1
                        `);
                        if (isStale()) return;
                        if (detail && detail.length > 0) {
                            updateSampleDetail(detail[0]);
                            populateInMapCardDetail(detail[0]);
                        } else {
                            updateSampleDetail({ description: '' });
                            populateInMapCardDetail(null);
                        }
                    } catch(err) {
                        if (isStale()) return;
                        console.error('Table-row detail query failed:', err);
                        updateSampleDetail(null);
                        populateInMapCardDetail(null);
                    }
                };
                tr.addEventListener('click', activateRow);
                // Keyboard parity for the role="button" title span: Enter
                // and Space activate the row. Scoped to .table-link so
                // Tab through other interactive cells (none today, but
                // future-proofing) isn't hijacked. Space's default
                // page-scroll is suppressed.
                tr.addEventListener('keydown', (ev) => {
                    if (!ev.target.classList || !ev.target.classList.contains('table-link')) return;
                    if (ev.key === 'Enter' || ev.key === ' ' || ev.key === 'Spacebar') {
                        ev.preventDefault();
                        activateRow(ev);
                    }
                });
            });
        }

        // 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}
                  ${searchFilterSQL('pid')}
            `);
            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}
                  ${searchFilterSQL('pid')}
                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...';
        // A1 (#234 Step 4): when a search is committed, the table IS now
        // filtered by it (semi-join on search_pids), so totalRows already
        // counts only `searchTerm ∩ viewport ∩ source/facet`. Report that
        // honestly as "N of M matches in this map view", where M is the
        // global match total stashed on window.__searchFilter. (The probe
        // confirmed every searchable sample has coordinates, so M is also the
        // count of mappable matches — no coordinate-less caveat needed.)
        const sf = (typeof window !== 'undefined') ? window.__searchFilter : null;
        const activeSearch = sf && sf.active ? sf.term : null;
        if (totalRows === 0) {
            return activeSearch
                ? `No "${activeSearch}" matches in this map view (of ${(sf.total || 0).toLocaleString()} total — pan or zoom out).`
                : 'No samples match the current filters.';
        }
        const total = totalRows.toLocaleString();
        const plural = totalRows === 1 ? '' : 's';
        if (activeSearch) {
            const matchTotal = (sf.total || totalRows).toLocaleString();
            return `${total} of ${matchTotal} "${activeSearch}" match${sf.total === 1 ? '' : 'es'} in this map view.`;
        }
        return `${total} sample${plural} 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;

    // A1 (#234 Step 4): accessors for the search-as-global-filter state the
    // search machinery publishes on window.__searchFilter. searchFilterSQL()
    // returns the semi-join predicate (or '' when no search is committed) so
    // the point loader and facet-count queries scope to `searchTerm ∩ …` the
    // same way the samples table does.
    const searchIsActive = () =>
        (typeof window !== 'undefined' && window.__searchFilter && window.__searchFilter.active);
    const searchFilterSQL = (col = 'pid') =>
        searchIsActive() ? ` AND ${col} IN (SELECT pid FROM search_pids)` : '';

    // 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;
        // A1 (#234 Step 4): snapshot the search generation too. `requestId`
        // only orders point loads against each other; it does NOT know that a
        // load was built under a given search filter. Without this, an
        // unfiltered boot load (search not yet built), a stale filtered load,
        // or a post-clear load can render after the search generation changed.
        // Every post-await resume below re-checks BOTH tokens.
        const mySearchToken = (typeof window !== 'undefined' && window.__searchFilter) ? window.__searchFilter.token : 0;
        const isStaleLoad = () => myReqId !== requestId
            || mySearchToken !== ((typeof window !== 'undefined' && window.__searchFilter) ? window.__searchFilter.token : 0);
        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()}
                  ${searchFilterSQL('pid')}
            `;
            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 point load OR a newer search
            // generation superseded this one (A1 #234 Step 4).
            if (isStaleLoad()) {
                window.a1dbg?.('point-load-discard', { myReqId, requestId, mySearchToken, curToken: window.__searchFilter?.token });
                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 (isStaleLoad()) return;  // stale guard (req + search gen)
                    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 (isStaleLoad()) 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');
            window.a1dbg?.('point-load-render', { rendered: samples.length, totalCount, searchActive: searchIsActive(), searchFiltered: !!searchFilterSQL('pid') });
            console.log(`Point mode: rendered ${samples.length} of ${totalCount} samples in ${elapsed.toFixed(0)}ms${capReached ? ' (cap reached)' : ''}`);

        } catch(err) {
            if (isStaleLoad()) 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
            });
        }
    }

    // Single source of truth for marker-layer visibility (#233 phase 3).
    //
    // Cluster dots (h3Points) and individual sample points (samplePoints)
    // are mutually exclusive with the heatmap overlay. When the heatmap is
    // on it IS the density view, so painting the cluster dots on top of it
    // produces the dots-vs-hotspots disagreement RY flagged 2026-05-27 —
    // two layers telling contradictory spatial stories at once. Rule:
    //   heatmap on  ⇒ both marker collections hidden (heatmap stands alone)
    //   heatmap off ⇒ show whichever collection the altitude-driven mode
    //                 calls for (cluster→h3Points, point→samplePoints)
    // Aside from the one-time initializer (samplePoints starts hidden at
    // creation), this is the ONLY place that writes `.show` on the two
    // collections. Call it from every site that flips the mode or the
    // heatmap toggle.
    function applyLayerVisibility() {
        const heat = heatmapEnabled();
        const mode = getMode();
        viewer.h3Points.show = !heat && mode === 'cluster';
        viewer.samplePoints.show = !heat && mode === 'point';
    }

    // --- Mode transitions ---
    // async + awaits loadViewportSamples so callers (notably
    // applySearchFilterChange under A1 #234 Step 4) have one real completion
    // point — otherwise the point load is fire-and-forget and can lose a
    // requestId race to a stale unfiltered load. Fire-and-forget callers can
    // still call it without awaiting; the load just resolves later.
    async function enterPointMode(pushHistory) {
        setExplorerMode('point');
        applyLayerVisibility();
        if (pushHistory !== false) history.pushState(null, '', buildHash(viewer));
        // #facetNote is only meaningful in cluster mode (#234 step 1).
        syncFacetNote();
        console.log('Entered point mode');
        window.a1dbg?.('mode-change', { to: 'point', searchActive: searchIsActive() });
        await loadViewportSamples();
    }

    function exitPointMode(pushHistory) {
        setExplorerMode('cluster');
        viewer.samplePoints.removeAll();
        applyLayerVisibility();
        if (pushHistory !== false) history.pushState(null, '', buildHash(viewer));
        // Returning to cluster mode: surface the honesty note if any
        // facet filter is active (#234 step 1).
        syncFacetNote();

        // 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');
        window.a1dbg?.('mode-change', { to: 'cluster', searchActive: searchIsActive(), via: new Error().stack?.split('\n')[2]?.trim() });
        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).
            await 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,
        };
    }

    // `colPrefix` lets callers qualify column names when the WHERE is going
    // to be used inside a JOIN (B1 bbox-aware path). Defaults to '' so the
    // pre-B1 single-table call sites keep working unchanged.
    function buildCrossFilterWhere(excludeFacet, colPrefix = '') {
        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 `${colPrefix}${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();

        // --- B1 (issue #234 step 3): bbox-aware counts ---
        //
        // Snapshot the viewport state at function entry. If the camera moves
        // after this, a fresh `refreshFacetCounts()` call (from the moveEnd
        // listener) bumps `facetCountsReqId` and supersedes this in-flight
        // request — every `await` resume checks `myReq !== facetCountsReqId`.
        //
        // `isGlobalView()` true → no spatial constraint → cube fast-path and
        // baseline early-return remain valid as before.
        // `isGlobalView()` false → snapshot a bbox SQL fragment scoped to the
        // `lite_url` lat/lon columns (which we JOIN to in the slow path,
        // since `facets_url` carries no coordinates today). Cube fast-path
        // is unconditionally gated off (it is pre-aggregated globally and
        // can't answer viewport-scoped questions).
        //
        // VIEWPORT_PAD_FACTOR (not 0): the facet counts must use the SAME
        // padded viewport as every other "in view" surface — the samples
        // table COUNT (loadCount), the point-mode sample loader, the
        // "samples in view" stat, and the heatmap all pad by
        // VIEWPORT_PAD_FACTOR (0.3). B1 originally shipped this at pad 0
        // (exact viewport), which left the facet count one (or more) low
        // versus the table whenever a matching sample sat in the 30% pad
        // margin — e.g. material=mineral at a Cyprus deep-zoom read 13 on
        // the legend but 14 in "samples match the current filters" (RY,
        // 2026-05-28); at a wide view (alt≈900 km, material=rock over the
        // Red Sea) the same mismatch reads ~166 vs ~481 because the margin
        // is huge. The heatmap hit the identical mismatch earlier and was
        // moved to the padded contract; this aligns the last surface. The
        // deeper fix (one shared "in view" bbox source so these can't drift
        // again) is tracked on #234.
        const isGlobal = isGlobalView();
        const bboxSQL = isGlobal ? null : viewerBboxSQL('l.latitude', 'l.longitude', VIEWPORT_PAD_FACTOR);

        // Baseline early-return only applies when there is no filter AND no
        // spatial constraint. In a non-global view with no facet filter, B1
        // still wants per-value counts scoped to what's visible — fall
        // through to the slow path with `where = '1=1'`.
        // A1 (#234 Step 4): an active search is itself a constraint, so even a
        // global view with no facet filter must take the slow (filtered) path.
        if (!sourceImpossible && activeDims.length === 0 && bboxSQL === null && !searchIsActive()) {
            for (const d of dims) applyFacetCounts(d.key, null);
            return;
        }

        markFacetCountsRecomputing();

        // Cube fast-path: pre-aggregated globally, so it's valid only when
        // the camera is at (or close to) the global view — AND no search is
        // active (A1 #234 Step 4): the cube is pre-aggregated over the whole
        // corpus and cannot be constrained to a free-text pid-set, so a
        // committed search must fall through to the on-the-fly slow path.
        const singleActiveDim = !sourceImpossible
            && activeDims.length === 1 && activeDims[0].values.length === 1
            ? activeDims[0] : null;
        if (singleActiveDim && totalActiveValues === 1 && bboxSQL === null && !searchIsActive()) {
            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) => {
            try {
                let rows;
                if (bboxSQL) {
                    // B1 bbox-scoped slow path: JOIN facets_url to lite_url
                    // on pid so we can filter by lite.latitude / lite.longitude.
                    // facets_url has no coordinates of its own. Per-PR follow-up:
                    // if this JOIN turns out too slow in practice, bake a
                    // pre-joined parquet (decision Q1 in plan).
                    const where = buildCrossFilterWhere(d.key, 'f.');
                    rows = await db.query(`
                        SELECT f.${d.col} AS value, COUNT(*) AS count
                        FROM read_parquet('${facets_url}') f
                        JOIN read_parquet('${lite_url}') l ON l.pid = f.pid
                        WHERE ${where} AND f.${d.col} IS NOT NULL${bboxSQL}${searchFilterSQL('f.pid')}
                        GROUP BY f.${d.col}
                    `);
                } else {
                    const where = buildCrossFilterWhere(d.key);
                    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${searchFilterSQL('pid')}
                        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);
                // Q3 in plan: on bbox-query throw, fall back to global
                // baseline rather than clobber with an error indicator.
                applyFacetCounts(d.key, null);
            }
        }));
    }

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

    // === Heatmap overlay (issue #233 phase 1) ===
    let heatmapInstance = null;
    let heatmapImageryLayer = null;
    let heatmapContainer = null;
    let heatmapReqId = 0;
    let heatmapDebounce = null;
    let heatmapLastKey = null;
    // Last SUCCESSFULLY-rendered view + filter (#233 loop fix, 2026-05-28).
    // refreshHeatmap() dedupes against these with a tolerance so that
    // sub-meaningful viewport jitter does NOT schedule a re-render. Set on
    // render success; cleared in clearHeatmap(), the render-error path, and
    // refreshHeatmap()'s no-bounds path. DELIBERATELY NOT cleared on
    // moveStart (unlike heatmapLastKey): retaining the last-success snapshot
    // across a moveStart/moveEnd cycle is what lets terrain/inertia jitter
    // be measured against the committed overlay and ignored, instead of
    // re-arming the loop. See heatmapViewMeaningfullyChanged().
    let heatmapLastBounds = null;
    let heatmapLastFilterHash = null;
    const HEATMAP_CANVAS_SIZE = 512;

    function heatmapEnabled() {
        return document.getElementById('heatmapToggle')?.checked === true;
    }

    function setHeatmapStatus(text) {
        const el = document.getElementById('heatmapStatus');
        if (!el) return;
        el.textContent = text || '';
        el.style.display = text ? 'block' : 'none';
    }

    function ensureHeatmapContainer() {
        if (heatmapContainer) return heatmapContainer;
        heatmapContainer = document.createElement('div');
        heatmapContainer.id = 'heatmapRenderSurface';
        heatmapContainer.style.cssText = [
            'position:absolute',
            'left:-10000px',
            'top:-10000px',
            `width:${HEATMAP_CANVAS_SIZE}px`,
            `height:${HEATMAP_CANVAS_SIZE}px`,
            'pointer-events:none',
        ].join(';');
        document.body.appendChild(heatmapContainer);
        return heatmapContainer;
    }

    function getHeatmapInstance() {
        if (heatmapInstance) return heatmapInstance;
        if (!window.h337) throw new Error('heatmap.js did not load');
        // maxOpacity caps the rendered alpha so dense areas don't fully
        // wash out the satellite imagery underneath. Without this, world
        // view (35k+ pixel cells with overlapping blur radii) saturates
        // to solid red. RY feedback 2026-05-27 on PR #240 follow-up.
        heatmapInstance = window.h337.create({
            container: ensureHeatmapContainer(),
            radius: 25,
            maxOpacity: 0.6,
        });
        return heatmapInstance;
    }

    // Adaptive per-point radius. heatmap.js applies a Gaussian blur of
    // size `radius` around each data point; overlapping blurs add
    // linearly, so at high cell density (world view: 35k cells on 512²
    // canvas, each cell's default 25-pixel blur covering ~1% of canvas)
    // the sum exceeds 1.0 across most of the canvas and everything
    // saturates to full red regardless of underlying density.
    //
    // Empirical scaling: at world view (35k cells) want ~6 px; at small
    // viewports (~300 cells) want ~30 px to fill space smoothly.
    // sqrt(canvas_pixels / cell_count) gives ~3 at world, ~30 at small —
    // double it and clamp to [6, 30].
    function heatmapRadiusFor(cellCount) {
        const canvasPx = HEATMAP_CANVAS_SIZE * HEATMAP_CANVAS_SIZE;
        const raw = Math.sqrt(canvasPx / Math.max(1, cellCount)) * 2;
        return Math.max(6, Math.min(30, Math.round(raw)));
    }

    function heatmapFilterHash() {
        return JSON.stringify({
            sources: getActiveSources().slice().sort(),
            material: getCheckedValues('materialFilterBody').slice().sort(),
            context: getCheckedValues('contextFilterBody').slice().sort(),
            object_type: getCheckedValues('objectTypeFilterBody').slice().sort(),
            // A1: include the committed search so the heatmap recomputes (and
            // re-keys) when a search is committed or cleared — otherwise the
            // "filtered density" overlay stays unfiltered under search while
            // every other surface filters (Codex review 2026-05-30, #234).
            search: (typeof window !== 'undefined' && window.__searchFilter && window.__searchFilter.active)
                ? window.__searchFilter.token : null,
        });
    }

    function heatmapBboxPredicate(bounds, latCol, lngCol) {
        const lngClause = (bounds.west > bounds.east)
            ? `(${lngCol} BETWEEN ${bounds.west} AND 180 OR ${lngCol} BETWEEN -180 AND ${bounds.east})`
            : `${lngCol} BETWEEN ${bounds.west} AND ${bounds.east}`;
        return `${latCol} BETWEEN ${bounds.south} AND ${bounds.north} AND ${lngClause}`;
    }

    function heatmapStringHash(value) {
        let hash = 0;
        for (let i = 0; i < value.length; i++) {
            hash = ((hash << 5) - hash + value.charCodeAt(i)) | 0;
        }
        return String(hash);
    }

    function heatmapKey(bounds) {
        const bbox = [bounds.south, bounds.north, bounds.west, bounds.east]
            .map(v => Number(v).toFixed(4))
            .join(',');
        return `${bbox}:${heatmapFilterHash()}`;
    }

    // Normalized center + span of a viewport rectangle, antimeridian-aware
    // (mirrors renderHeatmap's `eastNorm` shift). Used by the tolerance
    // dedupe below.
    function heatmapViewMetrics(b) {
        const eastNorm = b.west > b.east ? b.east + 360 : b.east;
        return {
            cLat: (b.north + b.south) / 2,
            cLng: (b.west + eastNorm) / 2,
            spanLat: Math.max(1e-9, b.north - b.south),
            spanLng: Math.max(1e-9, eastNorm - b.west),
        };
    }

    // Did the view change enough to warrant a fresh heatmap render?
    //
    // #233 loop fix (RY 2026-05-28): the heatmap re-renders on `moveEnd`,
    // keyed off `computeViewRectangle`. But that rectangle is sensitive to
    // tiny camera-height changes, and with Cesium World Terrain enabled the
    // camera height keeps settling for a beat after a move (terrain-collision
    // adjustment as tiles stream in) — plus inertial drift after mouse-up.
    // Each tiny settle fired `moveEnd` → re-render → the render's frame
    // nudged terrain again → another `moveEnd`: a self-sustaining refresh
    // loop with no user input. Exact-key equality (`toFixed(4)`, ~11 m) let
    // that jitter through.
    //
    // Fix: only re-render when the view center or span moved by more than a
    // small fraction of the current span. Real pans/zooms blow past this;
    // terrain-settle / inertial micro-jitter stays under it and is ignored.
    const HEATMAP_VIEW_TOLERANCE = 0.02; // 2% of span
    // Shortest angular distance between two longitudes (degrees), result in
    // [0, 180]. Without this, a wrapped bbox near the antimeridian (cLng≈180
    // via the eastNorm +360 shift) compared to a settled non-wrapped bbox
    // (cLng≈-177) would read as a ~357° "move" and wrongly pass the
    // meaningful-change test — preserving the loop exactly at the dateline.
    // Codex review 2026-05-28.
    function lngDelta(a, b) {
        let d = Math.abs(a - b) % 360;
        return d > 180 ? 360 - d : d;
    }
    function heatmapViewMeaningfullyChanged(curr, prev) {
        if (!prev) return true;
        const a = heatmapViewMetrics(curr);
        const b = heatmapViewMetrics(prev);
        const tolLat = a.spanLat * HEATMAP_VIEW_TOLERANCE;
        const tolLng = a.spanLng * HEATMAP_VIEW_TOLERANCE;
        return Math.abs(a.cLat - b.cLat) > tolLat
            || lngDelta(a.cLng, b.cLng) > tolLng
            || Math.abs(a.spanLat - b.spanLat) > tolLat
            || Math.abs(a.spanLng - b.spanLng) > tolLng;
    }

    function clearHeatmap() {
        ++heatmapReqId;
        clearTimeout(heatmapDebounce);
        heatmapLastKey = null;
        heatmapLastBounds = null;
        heatmapLastFilterHash = null;
        setHeatmapStatus('');
        if (heatmapImageryLayer) {
            viewer.imageryLayers.remove(heatmapImageryLayer, true);
            heatmapImageryLayer = null;
        }
        viewer._heatmapOverlay = {
            enabled: false,
            layer: null,
            lastRefreshAt: viewer._heatmapOverlay?.lastRefreshAt || 0,
            lastPointCount: 0,
            lastKey: null,
        };
    }

    async function renderHeatmap(myReq, key, bounds) {
        if (!heatmapEnabled()) return;
        setHeatmapStatus('Rendering heatmap...');
        try {
            // SQL pre-aggregation at pixel resolution (issue #233 phase 1.5).
            //
            // Previous approach: SELECT latitude, longitude LIMIT 100000 then
            // bin per pixel in JS. Two problems:
            //   (1) LIMIT 100000 picks an arbitrary first 100k rows in parquet
            //       storage order — NOT geographic random. At world view, the
            //       heatmap silently showed whichever source happened to be
            //       physically first in the file (likely SESAR).
            //   (2) For sample sets above the cap, the density was unfaithful.
            //
            // This approach: push the binning into DuckDB. The SQL groups by
            // pixel-cell coordinates derived from the bbox + canvas size, so
            // each row returned is one (x, y, count) tuple. Result cardinality
            // is bounded by canvas pixels (≤ 512² = 262k), independent of how
            // many samples the bbox contains. No LIMIT needed — every sample
            // counted into its true pixel bucket.
            //
            // Antimeridian handling: when bbox wraps (west > east), the SQL
            // shifts longitudes < west by +360 so the pixel arithmetic works
            // in a continuous coordinate space, matching what the old JS loop
            // did at line 2976. Same `eastForRectangle` adjustment downstream.
            const width = HEATMAP_CANVAS_SIZE;
            const height = HEATMAP_CANVAS_SIZE;
            const west = bounds.west;
            const eastNorm = bounds.west > bounds.east ? bounds.east + 360 : bounds.east;
            const lngSpan = Math.max(1e-9, eastNorm - west);
            const latSpan = Math.max(1e-9, bounds.north - bounds.south);
            const wraps = bounds.west > bounds.east;
            // SQL-side pixel coordinate computation. CAST(... AS INTEGER) is
            // explicit so DuckDB groups by integer keys, not floats.
            const lngExprBase = `(longitude ${wraps ? `+ CASE WHEN longitude < ${west} THEN 360 ELSE 0 END` : ``})`;
            const xExpr = `CAST(LEAST(${width - 1}, GREATEST(0, FLOOR((${lngExprBase} - ${west}) / ${lngSpan} * ${width}))) AS INTEGER)`;
            const yExpr = `CAST(LEAST(${height - 1}, GREATEST(0, FLOOR((${bounds.north} - latitude) / ${latSpan} * ${height}))) AS INTEGER)`;
            const aggregated = await db.query(`
                SELECT
                    ${xExpr} AS x,
                    ${yExpr} AS y,
                    COUNT(*) AS n
                FROM read_parquet('${lite_url}')
                WHERE ${heatmapBboxPredicate(bounds, 'latitude', 'longitude')}
                  ${sourceFilterSQL('source')}
                  ${facetFilterSQL()}
                  ${(typeof window !== 'undefined' && window.searchFilterSQL) ? window.searchFilterSQL('pid') : ''}
                GROUP BY x, y
            `);
            if (myReq !== heatmapReqId || !heatmapEnabled()) return;

            // SQL did the binning. Convert each row to a heatmap.js point.
            // Log-scale bin weights to defeat supersite max-bias. iSamples
            // data has extreme power-law spatial distribution: at Cyprus
            // medium zoom, one position carries 52,252 co-located samples
            // (likely a museum aggregation) while the median position has
            // 2 — a 26,000× ratio. Linear heatmap.js max-normalization
            // makes the supersite bin full red and everything else
            // essentially invisible (2/52252 = 0.004% intensity). log(1+n)
            // compresses the supersite (log(52253) ≈ 10.86) and lifts the
            // median (log(3) ≈ 1.10), bringing the ratio to ~10× and
            // revealing the actual density distribution the user expects
            // to see. RY feedback 2026-05-27 on PR #240.
            const pointsRaw = [];
            let logMax = 0;
            let totalSamples = 0;
            for (const row of aggregated) {
                const n = Number(row.n);
                totalSamples += n;
                const logVal = Math.log1p(n);
                if (logVal > logMax) logMax = logVal;
                pointsRaw.push({ x: Number(row.x), y: Number(row.y), value: logVal });
            }
            // Adaptive radius: tight at high cell counts (world view) to
            // avoid blur-overlap saturation; wide at low cell counts to
            // fill space smoothly.
            const radius = heatmapRadiusFor(pointsRaw.length);
            const points = pointsRaw.map(p => ({ ...p, radius }));

            const hm = getHeatmapInstance();
            hm.setData({ min: 0, max: logMax, data: points });
            const canvas = heatmapContainer.querySelector('canvas');
            if (!canvas) throw new Error('heatmap.js did not produce a canvas');
            const url = canvas.toDataURL('image/png');
            if (myReq !== heatmapReqId || !heatmapEnabled()) return;

            const eastForRectangle = bounds.west > bounds.east ? bounds.east + 360 : bounds.east;
            const provider = new Cesium.SingleTileImageryProvider({
                url,
                rectangle: Cesium.Rectangle.fromDegrees(bounds.west, bounds.south, eastForRectangle, bounds.north),
            });
            const nextLayer = viewer.imageryLayers.addImageryProvider(provider);
            nextLayer.alpha = 0.65;
            if (heatmapImageryLayer) {
                viewer.imageryLayers.remove(heatmapImageryLayer, true);
            }
            heatmapImageryLayer = nextLayer;
            heatmapLastKey = key;  // success-only — see refreshHeatmap()
            // Snapshot the view + filter this render committed to, for the
            // tolerance dedupe in refreshHeatmap() (#233 loop fix). Same
            // success-only discipline as heatmapLastKey.
            heatmapLastBounds = bounds;
            heatmapLastFilterHash = heatmapFilterHash();
            const refreshedAt = Date.now();
            // With SQL pre-aggregation, every sample in the bbox is counted
            // into its pixel cell — no more arbitrary LIMIT cap. `capped` is
            // kept on the state shape (for spec back-compat) but always
            // false. `lastPointCount` is now the true sample total, not the
            // capped raw-row count.
            viewer._heatmapOverlay = {
                enabled: true,
                layer: heatmapImageryLayer,
                lastRefreshAt: refreshedAt,
                lastPointCount: totalSamples,
                lastBinnedPointCount: points.length,
                lastImageHash: heatmapStringHash(url),
                lastKey: key,
                capped: false,
            };
            setHeatmapStatus(`Heatmap rendered from ${totalSamples.toLocaleString()} samples.`);
        } catch (err) {
            if (myReq !== heatmapReqId) return;
            console.warn('Heatmap refresh failed:', err);
            setHeatmapStatus('Heatmap unavailable for this view.');
            // Clear dedupe state so a retry on the same (viewport, filter)
            // actually re-attempts the render. Codex round-1 review of #240.
            heatmapLastKey = null;
            heatmapLastBounds = null;
            heatmapLastFilterHash = null;
            // Codex round-2 review of #240: also remove the prior imagery
            // layer on failure. Without this, the user sees the OLD heatmap
            // density alongside the "Heatmap unavailable" status — a UI lie
            // that survives until the next successful render. Matches the
            // no-bounds path which does the same.
            if (heatmapImageryLayer) {
                viewer.imageryLayers.remove(heatmapImageryLayer, true);
                heatmapImageryLayer = null;
            }
            viewer._heatmapOverlay = {
                enabled: heatmapEnabled(),
                layer: null,
                lastRefreshAt: viewer._heatmapOverlay?.lastRefreshAt || 0,
                lastPointCount: 0,
                error: String(err && err.message ? err.message : err),
                lastKey: null,
            };
        }
    }

    function refreshHeatmap() {
        if (!heatmapEnabled()) return;
        // Match VIEWPORT_PAD_FACTOR used by the table, point-mode loader,
        // and cluster-mode "Samples in View" stat. Phase-1 plan OQ4 chose
        // exact-viewport (padding=0) on the theory of "what's in the
        // rectangle you see"; but in practice RY (2026-05-27 staging
        // review) noticed the table reports more samples than the heatmap
        // for the same view, which is confusing. Matching the established
        // padded-bbox contract makes the numbers agree across all surfaces
        // that report "in view." Codex review of PR #240, follow-up.
        const bounds = paddedViewportBounds(VIEWPORT_PAD_FACTOR);
        if (!bounds) {
            ++heatmapReqId;
            clearTimeout(heatmapDebounce);
            heatmapLastKey = null;
            heatmapLastBounds = null;
            heatmapLastFilterHash = null;
            if (heatmapImageryLayer) {
                viewer.imageryLayers.remove(heatmapImageryLayer, true);
                heatmapImageryLayer = null;
            }
            setHeatmapStatus('Heatmap unavailable for this view.');
            viewer._heatmapOverlay = {
                enabled: true,
                layer: null,
                lastRefreshAt: viewer._heatmapOverlay?.lastRefreshAt || 0,
                lastPointCount: 0,
                lastKey: null,
            };
            return;
        }
        const key = heatmapKey(bounds);
        // Tolerance dedupe (#233 loop fix, RY 2026-05-28). Re-render only on
        // a filter change OR a meaningful view change. Sub-meaningful
        // viewport jitter (terrain-collision height settling, inertial
        // micro-drift) keeps the same filter and stays within the view
        // tolerance, so it is ignored here instead of driving a render that
        // would nudge terrain and sustain the loop. The previous exact-key
        // equality (`toFixed(4)`, ~11 m) let that jitter through.
        const filterHash = heatmapFilterHash();
        if (filterHash === heatmapLastFilterHash
            && !heatmapViewMeaningfullyChanged(bounds, heatmapLastBounds)) {
            // View only jittered (terrain settle / inertia); the existing
            // overlay is still correct. A moveStart may have flipped the
            // status to "waiting for camera" — restore the truthful
            // "rendered" line so it doesn't get stuck mid-loop. Gate on
            // heatmapLastBounds (set only on a successful render) rather than
            // a truthy count, so a valid ZERO-sample overlay also restores
            // its status instead of sticking at "waiting" (Codex review).
            if (heatmapLastBounds) {
                const n = Number(viewer._heatmapOverlay?.lastPointCount || 0);
                setHeatmapStatus(`Heatmap rendered from ${n.toLocaleString()} samples.`);
            }
            // Test-only signal: count tolerance skips so the regression test
            // can PROVE the skip branch ran (a real moveEnd reached here),
            // rather than relying on the vacuous "lastRefreshAt unchanged"
            // assertion (Codex review 2026-05-28).
            viewer._heatmapSkips = (viewer._heatmapSkips || 0) + 1;
            return;
        }
        // NOTE: heatmapLast{Key,Bounds,FilterHash} are set ONLY after a
        // successful layer swap in renderHeatmap(), and cleared on
        // error/cancellation. Setting them here would let a moveStart-
        // cancellation between the debounce schedule and the actual render
        // leave the dedupe state set without a render having happened — the
        // next moveEnd then early-returns and the overlay is wedged. Codex
        // round-1 review of PR #240.
        clearTimeout(heatmapDebounce);
        const myReq = ++heatmapReqId;
        heatmapDebounce = setTimeout(() => {
            renderHeatmap(myReq, key, bounds);
        }, 250);
    }

    document.getElementById('heatmapToggle')?.addEventListener('change', () => {
        if (heatmapEnabled()) {
            refreshHeatmap();
        } else {
            clearHeatmap();
        }
        // #233 phase 3: heatmap is mutually exclusive with the marker
        // layers, so flip dot visibility and re-evaluate the facet apology
        // note (which is meaningless once the heatmap shows filtered
        // density directly). Both helpers read live state, so order vs the
        // refresh/clear above does not matter.
        applyLayerVisibility();
        syncFacetNote();
    });
    viewer._heatmapOverlay = { enabled: false, layer: null, lastRefreshAt: 0, lastPointCount: 0, lastKey: null };
    viewer._heatmapSkips = 0;  // tolerance-dedupe skip counter (test signal)

    // --- 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;
    // Failsafe so the `progress` cursor (CSS on body.explorer-busy) can NEVER
    // stick. Every busyRelease is already in a `finally`, so a throw can't
    // strand the flag — but a HUNG promise (a load that never settles/rejects)
    // would never reach that finally. This watchdog force-clears the busy
    // state after a window far longer than any real update, incl. cold-cache
    // loads (which the code notes can take 60–90s). It's re-armed on each
    // acquire, so it only ever fires on a genuine leak — and the cursor is
    // purely cosmetic, so an early clear is harmless (the map never freezes).
    let _busyWatchdog = null;
    const BUSY_WATCHDOG_MS = 120000;
    function _clearBusyWatchdog() {
        if (_busyWatchdog) { clearTimeout(_busyWatchdog); _busyWatchdog = null; }
    }
    function busyAcquire() {
        if (_busyDepth === 0) document.body.classList.add('explorer-busy');
        _busyDepth++;
        _clearBusyWatchdog();
        _busyWatchdog = setTimeout(() => {
            _busyDepth = 0;
            document.body.classList.remove('explorer-busy');
            _busyWatchdog = null;
            console.warn('explorer-busy watchdog fired — force-cleared a stuck busy cursor.');
        }, BUSY_WATCHDOG_MS);
    }
    function busyRelease() {
        _busyDepth = Math.max(0, _busyDepth - 1);
        if (_busyDepth === 0) {
            document.body.classList.remove('explorer-busy');
            _clearBusyWatchdog();
        }
    }

    // --- 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();
            refreshHeatmap();
            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, and
    // `syncFacetNote()` for the shared visibility invariant (#234 step 1).
    async function handleFacetFilterChange() {
        busyAcquire();
        try {
            syncFacetNote();
            writeQueryState();
            refreshHeatmap();
            // #267: facet selection must visibly drive the MAP, not just the
            // table/legend. Cluster dots come from pre-aggregated H3 summaries
            // that carry only `dominant_source`, so they cannot honor a
            // material/context/object_type facet. Mirror the committed-search
            // path (applySearchFilterChange / C3): when any such facet is
            // active, FORCE point mode so the map shows the actual filtered
            // dots (which already apply facetFilterSQL()). When facets are
            // cleared, revert to the altitude-appropriate mode — unless a text
            // search is still latching point mode.
            if (hasFacetFilters()) {
                if (getMode() !== 'point') {
                    await enterPointMode(false);   // forces point; awaits filtered viewport load
                } else {
                    await loadViewportSamples();
                }
            } else if (getMode() === 'point') {
                const h = viewer.camera.positionCartographic.height;
                if (!searchIsActive() && h >= EXIT_POINT_ALT) {
                    exitPointMode(false);
                    const target = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
                    if (target !== currentRes) {
                        await loadRes(target, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[target]);
                    }
                } else {
                    await loadViewportSamples();
                }
            }
            refreshFacetCounts();
            await new Promise(r => setTimeout(r, 300));
        } finally {
            busyRelease();
        }
    }

    // A1 (#234 Step 4): push the just-built (or just-cleared) search pid-set
    // through every dynamic surface. Mirrors handleFacetFilterChange, plus
    // the C3 globe-mode rule:
    //   - search active → FORCE point mode. Clusters are pre-aggregated H3
    //     summaries that cannot be text-filtered, so showing them while the
    //     table/legend ARE filtered is the incoherent half-state we must
    //     avoid. Point mode renders the actual filtered samples (capped at
    //     POINT_BUDGET with an honest "showing N — zoom in" note for very
    //     broad terms — that cap is the density-fallback, in lieu of
    //     reverting to dishonest clusters).
    //   - search cleared → restore the mode the current altitude implies.
    // The camera-changed handler keeps point mode latched while a search is
    // active (its targetMode is overridden below), so panning/zooming during
    // a search won't bounce back to clusters.
    async function applySearchFilterChange() {
        window.a1dbg?.('apply-search-change', { active: searchIsActive(), mode: getMode() });
        busyAcquire();
        try {
            syncSearchPanelState();
            syncFacetNote();
            refreshHeatmap();
            // #267: point mode is latched by EITHER an active search OR an
            // active facet — both filter the sample set and can't be shown as
            // clusters. So clearing the search must NOT revert to clusters if a
            // facet is still checked (and vice-versa, handled in
            // handleFacetFilterChange). Use the same forced-point predicate as
            // every other latch.
            const forcePoint = searchIsActive() || hasFacetFilters();
            if (forcePoint) {
                if (getMode() !== 'point') {
                    await enterPointMode(false);   // forces point; awaits filtered viewport load
                } else {
                    await loadViewportSamples();
                }
            } else {
                // Neither search nor facet active: revert to altitude-appropriate mode.
                const h = viewer.camera.positionCartographic.height;
                if (getMode() === 'point' && h >= EXIT_POINT_ALT) {
                    exitPointMode(false);
                    const target = h > 3000000 ? 4 : h > 300000 ? 6 : 8;
                    if (target !== currentRes) {
                        await loadRes(target, { 4: h3_res4_url, 6: h3_res6_url, 8: h3_res8_url }[target]);
                    }
                } else if (getMode() === 'point') {
                    await loadViewportSamples();  // still point altitude — reload now-unfiltered points
                }
            }
            refreshFacetCounts();
            if (typeof window !== 'undefined') window.refreshSamplesTable?.();
        } 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.
            // A1 (#234 Step 4) / C3: while a search is active, latch point
            // mode regardless of altitude — clusters can't be text-filtered,
            // so we keep showing the filtered sample dots even when zoomed out.
            const targetMode = (searchIsActive() || hasFacetFilters()) ? 'point'
                             : h < ENTER_POINT_ALT ? 'point'
                             : h > EXIT_POINT_ALT ? 'cluster'
                             : getMode();

            if (targetMode === 'point' && getMode() !== 'point') {
                if (searchIsActive() || hasFacetFilters()) {
                    // Search or an active facet (#267) forces point mode even
                    // above ENTER_POINT_ALT, where tryEnterPointModeIfNeeded()
                    // would refuse; enter directly so the filtered dots render
                    // at any zoom.
                    await enterPointMode(false);
                } else {
                    // 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.
    // B1 (issue #234 step 3): on the very first sign of a camera move,
    // (a) mark the legend italic-stale so the user sees "checking…" the
    //     moment they grab the globe (instead of waiting moveEnd + 250 ms);
    // (b) bump `facetCountsReqId` and clear the pending debounce so any
    //     in-flight or debounced `updateCrossFilteredCounts` for the
    //     PRE-MOVE viewport is invalidated.
    //
    // Without (b), a query that was already in flight at moveStart could
    // resume after its SELECT lands, pass the stale guard, and call
    // `applyFacetCounts` — which would WRITE OLD COUNTS for a viewport the
    // user has already abandoned AND clear `.recomputing` before moveEnd
    // schedules the new query, leaving the legend looking authoritative
    // (no italic) but stale until moveEnd's 250 ms debounce fires.
    // Codex round-1 review of PR #237 caught this.
    //
    // moveEnd's `refreshFacetCounts()` below will bump `facetCountsReqId`
    // AGAIN — that's intentional and harmless: a second supersession of
    // already-superseded work, debounce coalesced.
    //
    // We skip the mark/bump when there are no facet-count spans rendered
    // yet (initial boot, before facet UI hydrates) to avoid DOM thrash
    // and a no-op debounce reset during the very first camera-position
    // events that fire before the OJS facet cells have settled.
    viewer.camera.moveStart.addEventListener(() => {
        if (!document.querySelector('.facet-count')) return;
        markFacetCountsRecomputing();
        clearTimeout(facetCountsDebounce);
        ++facetCountsReqId;
        if (heatmapEnabled()) {
            clearTimeout(heatmapDebounce);
            ++heatmapReqId;
            // Clear dedupe key — otherwise a moveStart-cancellation between
            // refreshHeatmap()'s setTimeout and renderHeatmap()'s success
            // could leave the key set without a render having happened,
            // causing the next moveEnd to early-return and wedge the
            // overlay. Codex round-1 review of #240.
            heatmapLastKey = null;
            setHeatmapStatus('Heatmap waiting for camera...');
        }
    });

    viewer.camera.moveEnd.addEventListener(() => {
        if (!viewer._suppressHashWrite) {
            history.replaceState(null, '', buildHash(viewer));
        }
        // B1: viewport-aware facet counts. Bouncing through refreshFacetCounts
        // reuses the existing 250ms debounce + facetCountsReqId stale-guard,
        // so bursts of moveEnd (drag-pan, wheel-zoom) coalesce into one query
        // and any in-flight superseded query discards its result on resume.
        refreshFacetCounts();
        refreshHeatmap();
        if (getMode() !== 'point') return;
        const h = viewer.camera.positionCartographic.height;
        // A1 (#234 Step 4) / C3: while a search is active, point mode is
        // LATCHED (clusters can't be text-filtered), so a high-altitude
        // moveEnd must NOT exit to clusters — otherwise the post-search
        // flyTo (200 km, above EXIT_POINT_ALT) would immediately undo the
        // forced point mode and the globe would show unfiltered clusters.
        if (h > EXIT_POINT_ALT && !searchIsActive() && !hasFacetFilters()) {
            // 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(async () => {
            viewer._suppressHashWrite = false;
            const s = readHash();
            // A1 (#234 Step 4): an active search forces point mode regardless
            // of the restored altitude, so the back/forward globe state stays
            // coherent with the (still-filtered) table/legend.
            const wantsPoint = searchIsActive() || hasFacetFilters() || s.mode === 'point' || (s.alt != null && s.alt < ENTER_POINT_ALT);
            if (wantsPoint && getMode() !== 'point') await 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 refreshFacetCountsAfterSearchFlight(searchId) {
        // A world-scope committed search auto-flies to the first result. That
        // camera flight emits its own moveStart/moveEnd count refreshes, which
        // can supersede the search refresh kicked off by applySearchFilterChange.
        // Register this one-shot after the shared moveEnd listener exists; when
        // the flight settles, this runs after the normal moveEnd refresh and
        // becomes the final search-aware facet-count request for the committed
        // search.
        let remove = null;
        let done = false;
        const finish = () => {
            if (done) return;
            done = true;
            if (remove) remove();
            setTimeout(() => {
                if (searchId !== _searchSeq || !searchIsActive()) return;
                window.a1dbg?.('search-flyto-final-facet-refresh', {
                    searchId,
                    token: window.__searchFilter?.token,
                });
                refreshFacetCounts();
            }, 0);
        };
        remove = viewer.camera.moveEnd.addEventListener(finish);
        return () => {
            if (done) return;
            done = true;
            if (remove) remove();
        };
    }

    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);
        }
    }

    // === A1: search-as-global-filter pid-set (#234 Step 4) ===
    //
    // Strategy B: materialize the set of pids matching the committed search
    // term ONCE (one ILIKE scan over facets_url), then let every count
    // surface (table, points, facet legend, stats) constrain itself with a
    // cheap `pid IN (SELECT pid FROM search_pids)` semi-join — instead of
    // re-running the expensive ILIKE per surface per camera move.
    //
    // `search_pids` is a NON-TEMP table: Observable's DuckDBClient opens a
    // fresh connection per db.query(), so a connection-local TEMP table would
    // not survive to the next query(); a regular table in the shared
    // in-memory database persists across those connections (verified by the
    // a1PersistenceProbe cell during development).
    //
    // Build into `search_pids_next` then atomically swap, so a surface
    // refresh can never read a half-built set. `_searchFilterToken` versions
    // each build so a superseded one (newer search fired mid-build) discards
    // its swap. State is published on `window.__searchFilter` so the
    // separate `tableView` OJS cell (and others) can read it; the SQL
    // predicate is exposed as `window.searchFilterSQL(pidCol)`.
    let _searchFilterToken = 0;
    if (typeof window !== 'undefined') {
        // Preserve existing state across an OJS hot re-run of this cell, but
        // ALWAYS (re)install the helper so it can't go missing while
        // __searchFilter persists (Codex review).
        if (!window.__searchFilter) {
            window.__searchFilter = { active: false, term: null, token: 0, total: 0 };
        }
        // Surfaces append this to their WHERE. Empty string when no search is
        // committed, so non-search queries are byte-for-byte unchanged.
        window.searchFilterSQL = (pidCol = 'pid') =>
            (window.__searchFilter && window.__searchFilter.active)
                ? ` AND ${pidCol} IN (SELECT pid FROM search_pids)`
                : '';

        // DEV: deterministic A1 observability, gated behind ?debug=a1 so
        // production users get a clean global namespace and zero overhead.
        // The Playwright harness (a1-verify.mjs) loads with ?debug=a1 to opt
        // in. Every a1dbg?.() call site uses optional chaining, so they are
        // no-ops when this block doesn't run. a1dbg() appends to
        // window.__a1log and stamps window.__a1state[event] so a test can
        // POLL state (and read an optional on-page panel) rather than chase
        // console; __a1globe() exposes just what a coherence assertion needs.
        if (new URLSearchParams(location.search).get('debug') === 'a1') {
            if (!window.a1dbg) {
                window.__a1log = [];
                window.__a1state = {};
                let _a1panel = null;
                if (document.body) {
                    _a1panel = document.createElement('div');
                    _a1panel.id = 'a1DebugPanel';
                    _a1panel.style.cssText = 'position:fixed;bottom:0;right:0;width:520px;max-height:42vh;overflow:auto;background:#111;color:#3f3;font:11px/1.35 monospace;z-index:99999;padding:4px;opacity:.92';
                    document.body.appendChild(_a1panel);
                }
                window.a1dbg = (event, data = {}) => {
                    const row = { t: Math.round(performance.now()), event, ...data };
                    window.__a1log.push(row);
                    window.__a1state[event] = row;
                    if (_a1panel) {
                        const line = document.createElement('div');
                        line.textContent = `[A1] +${row.t}ms ${event} ${JSON.stringify(data)}`;
                        _a1panel.appendChild(line);
                        _a1panel.scrollTop = _a1panel.scrollHeight;
                    }
                };
            }
            // Globe-state accessor for the Playwright harness — exposes just
            // what a coherence assertion needs, not the whole Cesium viewer.
            // Lazily reads `viewer` (in this cell's scope).
            window.__a1globe = () => {
                try {
                    return {
                        mode: viewer._globeState.mode,
                        samplePointsLen: viewer.samplePoints.length,
                        samplePointsShown: viewer.samplePoints.show,
                        h3PointsShown: viewer.h3Points.show,
                    };
                } catch (e) { return { error: String(e) }; }
            };
        }
    }

    async function buildSearchFilter(terms, term) {
        const token = ++_searchFilterToken;
        window.a1dbg?.('search-build-start', { term, token });
        const searchWhere = textSearchWhere(terms, [
            'label',
            'description',
            'CAST(place_name AS VARCHAR)',
        ]);
        // Compute the side-panel relevance score in the SAME scan that builds
        // the pid-set, and materialize the columns doSearch's results list
        // needs (label / source / place_name + score). This lets doSearch read
        // the small search_pids table instead of RE-scanning the 63 MB facets
        // parquet — the old double-scan that pushed broad terms like "pottery"
        // past CI's 90s smoke budget. search_pids stays pid-keyed (one row per
        // unique pid), so every other surface's `pid IN (SELECT pid FROM
        // search_pids)` semi-join and the COUNT(*) total are unchanged.
        const score = textSearchScore(terms, [
            { col: 'label',                       weight: 3 },
            { col: 'description',                 weight: 1 },
            { col: 'CAST(place_name AS VARCHAR)', weight: 2 },
        ]);
        // pid is unique in facets_url (verified in A1 scoping), so the build
        // is naturally one row per pid — no DISTINCT needed. (The previous
        // `SELECT DISTINCT pid` deduped a single column; a 5-column DISTINCT
        // would be both slower and weaker — it dedupes identical full rows,
        // not pids — so we rely on the established uniqueness instead. This
        // keeps COUNT(*) == match count and the side-panel free of dup rows.)
        // Token-scoped staging table: a fixed `search_pids_next` name lets two
        // overlapping searches clobber each other's staging rows, so a later
        // search could swap the EARLIER search's pids into `search_pids` under
        // its own term — the token checks guard the publish, not the shared
        // staging object. Naming the staging table per-token isolates
        // concurrent builds; it's dropped in `finally`. (Codex review 2026-05-30.)
        const staging = `search_pids_next_${token}`;
        try {
            await db.query(`
                CREATE OR REPLACE TABLE ${staging} AS
                SELECT pid, label, source, place_name, (${score}) AS relevance_score
                FROM read_parquet('${facets_url}')
                WHERE pid IS NOT NULL AND ${searchWhere}
            `);
            if (token !== _searchFilterToken) return false;   // superseded mid-build
            await db.query(`CREATE OR REPLACE TABLE search_pids AS
                SELECT pid, label, source, place_name, relevance_score FROM ${staging}`);
            if (token !== _searchFilterToken) return false;
            const cnt = Array.from(await db.query(`SELECT COUNT(*) AS n FROM search_pids`));
            const total = cnt.length ? Number(cnt[0].n) : 0;
            if (token !== _searchFilterToken) return false;
            window.__searchFilter = { active: true, term, token, total, kind: 'text' };
            window.a1dbg?.('search-build-end', { term, token, total });
            return true;
        } finally {
            try { await db.query(`DROP TABLE IF EXISTS ${staging}`); } catch (e) { /* best effort */ }
        }
    }

    // #248 Flavor A: a SECOND producer of `search_pids` — selects samples whose
    // iSamples-vocabulary concept (the URI-valued object_type / material /
    // context columns in sample_facets_v2) exactly matches `uri`. Mirrors
    // buildSearchFilter's token-scoped staging + finally-drop + token guards,
    // sharing the same _searchFilterToken (the pid-set is a singleton). Every
    // surface then filters via the same `pid IN (SELECT pid FROM search_pids)`
    // semi-join, for free. Flavor B (arbitrary external/Getty URIs needing
    // URI→label resolution + free-text) is a follow-up.
    async function buildConceptFilter(uri) {
        const token = ++_searchFilterToken;
        const label = (typeof window !== 'undefined' && window.conceptLabelForUri)
            ? window.conceptLabelForUri(uri) : uri;
        window.a1dbg?.('search-build-start', { term: label, token, kind: 'concept' });
        const u = escSql(uri);
        // Rank object_type matches above material above context, then by label
        // (Codex plan-review suggestion — cheap, no extra scan).
        const rank = `CASE WHEN object_type = '${u}' THEN 3 WHEN material = '${u}' THEN 2 WHEN context = '${u}' THEN 1 ELSE 0 END`;
        const staging = `search_pids_next_${token}`;
        try {
            await db.query(`
                CREATE OR REPLACE TABLE ${staging} AS
                SELECT pid, label, source, place_name, (${rank}) AS relevance_score
                FROM read_parquet('${facets_url}')
                WHERE pid IS NOT NULL
                  AND (object_type = '${u}' OR material = '${u}' OR context = '${u}')
            `);
            if (token !== _searchFilterToken) return false;   // superseded mid-build
            await db.query(`CREATE OR REPLACE TABLE search_pids AS
                SELECT pid, label, source, place_name, relevance_score FROM ${staging}`);
            if (token !== _searchFilterToken) return false;
            const cnt = Array.from(await db.query(`SELECT COUNT(*) AS n FROM search_pids`));
            const total = cnt.length ? Number(cnt[0].n) : 0;
            if (token !== _searchFilterToken) return false;
            window.__searchFilter = { active: true, term: label, token, total, kind: 'concept', uri };
            window.a1dbg?.('search-build-end', { term: label, token, total, kind: 'concept' });
            return true;
        } finally {
            try { await db.query(`DROP TABLE IF EXISTS ${staging}`); } catch (e) { /* best effort */ }
        }
    }

    async function clearSearchFilter() {
        _searchFilterToken++;
        window.__searchFilter = { active: false, term: null, token: _searchFilterToken, total: 0 };
        // Replace search_pids with an EMPTY same-shape table rather than
        // DROPping it. Two readers touch this table without gating on
        // __searchFilter.active: an in-flight semi-join surface query, and
        // doSearch's side-panel SELECT that reads `FROM search_pids` directly.
        // DROP would make those throw on a missing table; simply leaving the old
        // table would let the side panel render the PREVIOUS search's rows under
        // a new/cleared term (Codex review 2026-05-30). An empty table makes
        // both readers safely see zero rows; the next search's
        // CREATE OR REPLACE ... AS SELECT swaps in the real rows.
        try {
            await db.query(`CREATE OR REPLACE TABLE search_pids (
                pid VARCHAR, label VARCHAR, source VARCHAR, place_name VARCHAR, relevance_score DOUBLE
            )`);
        } catch (e) { /* best effort */ }
    }

    async function clearActiveSearchFilter() {
        // Same clear path as an empty search submit, without entering doSearch().
        _searchSeq++;
        if (searchInput) searchInput.value = '';
        if (searchResults) searchResults.textContent = '';
        await clearSearchFilter();
        await applySearchFilterChange();
        writeQueryState({ commitText: '' });
    }

    function renderDescribedByChip() {
        const host = document.getElementById('activeSearchChipHost');
        if (!host) return;

        const sf = (typeof window !== 'undefined') ? window.__searchFilter : null;
        const conceptActive = !!(sf && sf.active && sf.kind === 'concept');
        if (!conceptActive) {
            host.hidden = true;
            host.innerHTML = '';
            return;
        }

        const label = sf.term || sf.uri || '';
        host.hidden = false;
        host.innerHTML = `<div class="described-by-chip" data-filter-kind="concept">
            <span class="described-by-chip-label">Described by: ${escapeHtml(label)}</span>
            <button type="button" class="described-by-chip-clear" data-clear-search-filter aria-label="Clear described-by filter" title="Clear described-by filter">✕</button>
        </div>`;

        const clearBtn = host.querySelector('[data-clear-search-filter]');
        if (clearBtn) clearBtn.addEventListener('click', clearActiveSearchFilter);
    }

    function syncSearchPanelState() {
        renderDescribedByChip();
        const clusterEl = document.getElementById('clusterSection');
        if (clusterEl) clusterEl.hidden = searchIsActive();
    }

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

        // Bump the freshness token FIRST — even for invalid submits
        // (empty / 1-char). Codex review of #236 round 3 caught the gap:
        // if a valid search is in flight and the user clears the box and
        // resubmits, the early-return below used to write "Type at least
        // 2 characters" WITHOUT invalidating the in-flight search. When
        // that older search later rejected, its catch would see
        // `searchId === _searchSeq` and overwrite the "Type at least..."
        // message with `Search error: ...`. Bumping first ensures any
        // submission — valid or not — supersedes prior in-flight work.
        const searchId = ++_searchSeq;

        const term = searchInput.value.trim();
        if (!term || term.length < 2) {
            searchResults.textContent = 'Type at least 2 characters';
            // A1 (#234 Step 4): an empty / too-short submit means no committed
            // search — drop the pid-set filter and refresh every surface
            // (table, points, facet counts) plus revert the globe mode so the
            // page returns to its unfiltered state.
            await clearSearchFilter();
            await applySearchFilterChange();
            writeQueryState({ commitText: '' });   // authoritative clear (#248)
            persistSearchScope(effectiveScope);
            return;
        }
        writeQueryState({ commitText: term });     // authoritative text commit (#248)
        persistSearchScope(effectiveScope);
        // A1 (#234 Step 4): the pid-set filter is built below (after `terms`
        // is parsed) and the dependent surfaces are refreshed against it; the
        // table/legend/points then reflect this search, not just the viewport.
        // Shared, prominent + sticky search-results heading, reused by the
        // success / zero-result / error paths so the side panel ALWAYS
        // reflects the committed search the table meta points at ("…shown in
        // the panel →"). z-index keeps it above scrolled rows. term is the
        // user's own input, rendered as-is to match the prior heading.
        const searchHeadingHTML = (suffix) =>
            `<h4 class="search-results-heading" style="position: sticky; top: 0; z-index: 1; margin: 0 0 6px; padding: 6px 8px; background: #e3f2fd; color: #1565c0; border-radius: 4px;">Search results: "${term}"${suffix}</h4>`;
        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 markStart = `search-${searchId}-start`;
        const markEnd = `search-${searchId}-end`;
        performance.mark(markStart);
        const tStart = performance.now();
        const terms = searchTerms(term);

        // A1 (#234 Step 4): materialize the search pid-set ONCE, then refresh
        // the table (and, in later increments, points / facet counts / stats)
        // so every count surface constrains to this search via a cheap
        // semi-join. One ILIKE scan here warms the text columns in the DuckDB
        // buffer, so the LIMIT-50 side-panel query below reads them warm.
        // (Follow-up: derive the side-panel list from search_pids to drop the
        // second scan entirely.) Failure leaves surfaces unfiltered, not broken.
        const buildingMsg = effectiveScope === 'area'
            ? 'Building search filter for selected areas…'
            : 'Building search filter…';
        searchResults.textContent = buildingMsg;
        // Distinguishes a genuine build failure (DuckDB error) from a real
        // empty result set: clearSearchFilter() leaves search_pids EMPTY, so the
        // side-panel SELECT below returns 0 rows either way; this flag lets the
        // empty-results branch say "Search error" rather than "No results".
        let searchFilterBuildFailed = false;
        try {
            await buildSearchFilter(terms, term);
        } catch (e) {
            console.warn('A1 search-filter build failed; surfaces stay unfiltered:', e);
            searchFilterBuildFailed = true;
            await clearSearchFilter();
        }
        // Superseded by a newer search while building? Bail before mutating UI.
        // Otherwise push the freshly-built filter through every surface: table,
        // points, facet counts, and the globe mode (C3 — switch to filtered
        // point dots, since clusters can't be text-filtered).
        window.a1dbg?.('post-build', { searchId, searchSeq: _searchSeq, active: window.__searchFilter?.active, total: window.__searchFilter?.total });
        if (searchId === _searchSeq) {
            await applySearchFilterChange();
        }

        // Snapshot the filter-state telemetry booleans here, BEFORE the
        // try block, so they remain in scope through `finally`. They
        // reflect the DOM state at search-fire time — independent of
        // any toggles the user makes during the await chain (#167 + #236
        // round 2 review).
        const hadSourceFilter = getActiveSources().length !== SOURCE_VALUES.length;
        const hadFacetFilter = hasFacetFilters();
        let resultsCount = 0;
        let totalCount = null;     // Real count when cap is hit (#232); null otherwise.
        let countMs = 0;           // Duration of the follow-up COUNT scan, ms.
        let wasSuperseded = false; // True when a newer search bumped _searchSeq mid-flight.
        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.
            //
            // The search-term match + relevance score are already materialized
            // in `search_pids` by buildSearchFilter (aliased `s` below), so the
            // results SELECT and the follow-up COUNT both read that small table
            // instead of re-scanning the 63 MB facets parquet — the old
            // double-scan (one in buildSearchFilter, one here) that pushed
            // broad terms like `pottery` past CI's 90s smoke budget. The single
            // remaining facets scan lives in buildSearchFilter.
            //
            // Snapshot the source / facet predicates ONCE per search so the
            // follow-up COUNT(*) at the end of this try block uses the same
            // filter state as the SELECT. Without this snapshot, a user who
            // toggles a source checkbox or material facet while the SELECT
            // is in flight would see a label like "50 of M" where M reflects
            // the NEW filter state, not the rendered 50 rows (Codex review
            // of PR #236 round 1). The string is captured here, before any
            // `db.query` await, and re-used by both the SELECT and the
            // COUNT below.
            const sourceSQL = sourceFilterSQL('s.source');
            const facetSQL = facetFilterSQL();
            // Telemetry-equivalent of the SQL snapshots above (`hadSourceFilter`
            // / `hadFacetFilter`) is declared OUTSIDE this try block so it
            // remains in scope through `finally` — see comment near the
            // function-level `let` declarations.

            // 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.
            //
            // Track which shape actually ran so the follow-up COUNT(*)
            // query for #232 uses the matching WHERE/JOIN. The area-scope
            // path falls back to `world` when `viewerBboxSQL` returns null,
            // so `effectiveScope === 'area'` is NOT a reliable predicate.
            let results;
            let effectiveQueryShape = 'world';
            let effectiveBboxSQL = null;
            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 s.pid, s.label, s.source, l.latitude, l.longitude,
                               s.place_name, s.relevance_score
                        FROM search_pids s
                        INNER JOIN read_parquet('${lite_url}') l USING (pid)
                        WHERE 1=1
                          ${bboxSQL}
                        ${sourceSQL}
                        ${facetSQL}
                        ORDER BY s.relevance_score DESC, s.label
                        LIMIT 50
                    `);
                    effectiveQueryShape = 'area';
                    effectiveBboxSQL = bboxSQL;
                }
            } else {
                results = await runWorldQuery();
            }

            async function runWorldQuery() {
                return db.query(`
                    WITH matches AS (
                        SELECT s.pid, s.label, s.source, s.place_name,
                               s.relevance_score
                        FROM search_pids s
                        WHERE 1=1
                        ${sourceSQL}
                        ${facetSQL}
                        ORDER BY s.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
                `);
            }

            // Stale-search guard (Codex review of PR #236 round 1). A
            // second search the user fires while this SELECT is in flight
            // bumps `_searchSeq`. Without this early guard, the superseded
            // search would still mutate `searchResults.textContent`,
            // repaint `samplesSection`, trigger an unwanted `camera.flyTo`,
            // and launch a wasted COUNT scan — even though a later guard
            // would correctly suppress the COUNT result itself. Bail BEFORE
            // any of that work. The later COUNT-specific guard remains as
            // a second line of defense for the case where supersession
            // happens between this check and the COUNT.
            if (searchId !== _searchSeq) {
                wasSuperseded = true;
                return;
            }
            resultsCount = results.length;
            if (results.length === 0) {
                // A build failure also empties search_pids → 0 rows here, so
                // distinguish a genuine error from a true empty result set.
                searchResults.textContent = searchFilterBuildFailed
                    ? `Search error: couldn't build the filter for "${term}". Please try again.`
                    : `No results for "${term}"`;
                // Honesty fix (#247): the table meta points "→ panel", so the
                // panel must reflect THIS (empty) search rather than whatever
                // it showed before. Without this, a zero-result search left
                // stale prior content under a pointer claiming otherwise.
                const sampEl0 = document.getElementById('samplesSection');
                if (sampEl0) sampEl0.innerHTML = searchHeadingHTML(searchFilterBuildFailed ? '' : ' (0)')
                    + `<div class="empty-state" style="padding: 8px;">${searchFilterBuildFailed ? 'Search failed to build — please try again.' : 'No samples matched this search.'}</div>`;
                return;
            }

            // Initial render. The "+" indicates "more exist" when the cap was
            // hit; if the cap was hit, the follow-up COUNT below replaces
            // this with the real total ("50 of 7,124 results"). This keeps
            // the user informed during cold-cache COUNT scans (where the
            // second query can add a few hundred ms) rather than leaving the
            // bare result-row count visible while the precise total
            // resolves. See issue #232.
            const capReached = results.length === 50;
            searchResults.textContent = capReached
                ? `${results.length}+ results for "${term}"`
                : `${results.length} results for "${term}"`;

            // Show results in the samples panel
            const sampEl = document.getElementById('samplesSection');
            if (sampEl) {
                // Prominent + sticky heading via the shared helper (see its
                // definition above). No page/camera scroll — heading only.
                let h = searchHeadingHTML(` (${results.length})`);
                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) {
                const cancelFinalFacetRefresh = refreshFacetCountsAfterSearchFlight(searchId);
                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,
                    cancel: cancelFinalFacetRefresh,
                });
            }

            // Real-count follow-up (#232). When the SELECT hit `LIMIT 50` we
            // can't know whether the true result set is 51 or 50,000 — the
            // legacy `50+` label hid this entirely. Mirror the pattern used
            // by `loadViewportSamples()` (where this same kind of follow-up
            // turned "Samples in View capped at 5,000" into a real count):
            // re-run the WHERE clause as a `COUNT(*)` only when the cap was
            // hit. Below the cap, `results.length` IS the truth and a second
            // scan would be wasted.
            //
            // Cancellation: a second search the user fires while this COUNT
            // is in flight bumps `_searchSeq`. The guard below ensures a
            // stale COUNT can't overwrite the newer search's result text.
            // We also skip the structured-log `total_count` update on stale
            // returns so the #167 log line still reflects only the live
            // search's measurements.
            //
            // Failure handling: a COUNT error leaves the initial `50+` text
            // in place — better to under-disclose than to clear the line
            // entirely. The cost is logged via `count_ms` so #167 analysis
            // can track when the COUNT path runs.
            if (capReached) {
                // Use the snapshotted `sourceSQL` / `facetSQL` so the COUNT
                // matches the SELECT's filter state byte-for-byte even if
                // the user has toggled source/facet filters during the
                // SELECT await.
                const countSQL = effectiveQueryShape === 'area'
                    ? `
                        SELECT COUNT(*) AS n
                        FROM search_pids s
                        INNER JOIN read_parquet('${lite_url}') l USING (pid)
                        WHERE 1=1
                          ${effectiveBboxSQL}
                        ${sourceSQL}
                        ${facetSQL}
                    `
                    : `
                        SELECT COUNT(*) AS n
                        FROM search_pids s
                        WHERE 1=1
                        ${sourceSQL}
                        ${facetSQL}
                    `;
                const countStart = performance.now();
                try {
                    const countRow = await db.query(countSQL);
                    countMs = performance.now() - countStart;
                    if (searchId !== _searchSeq) {
                        // A newer search owns `searchResults.textContent`
                        // now; leaving `totalCount` null also keeps this
                        // stale COUNT out of the structured log.
                        wasSuperseded = true;
                        return;
                    }
                    const total = Number(countRow[0]?.n ?? results.length);
                    totalCount = total;
                    // When `total === results.length`, the cap happened to
                    // catch exactly the full set — drop the "of N" to
                    // avoid a redundant "50 of 50 results" reading.
                    searchResults.textContent = total > results.length
                        ? `${results.length} of ${total.toLocaleString()} results for "${term}"`
                        : `${results.length} results for "${term}"`;
                } catch(err) {
                    countMs = performance.now() - countStart;
                    if (searchId !== _searchSeq) {
                        wasSuperseded = true;
                        return;
                    }
                    console.warn("Search COUNT(*) failed; keeping '50+' label:", err);
                }
            }
        } catch(err) {
            // Stale-search guard for the error path (Codex review of #236
            // round 2). Without this, a search whose SELECT later rejects
            // would overwrite a newer search's UI with "Search error: …".
            // The freshness-token check matches the success-path guard
            // above so both paths are coherent: a superseded search is
            // recorded in the structured log (with `superseded: true` and
            // the original error captured in `error`) but does NOT mutate
            // user-visible state.
            if (searchId !== _searchSeq) {
                wasSuperseded = true;
                errorMessage = err?.message || String(err);
                console.warn(`Stale search (id=${searchId}) rejected after supersession; suppressing UI write.`, err);
            } else {
                console.error("Search failed:", err);
                searchResults.textContent = `Search error: ${err.message}`;
                errorMessage = err.message || String(err);
                // Honesty fix (#247): keep the side panel consistent with the
                // table meta's "→ panel" pointer on failure too, instead of
                // leaving stale results under a pointer that now lies.
                const sampElErr = document.getElementById('samplesSection');
                if (sampElErr) sampElErr.innerHTML = searchHeadingHTML('')
                    + '<div class="empty-state" style="padding: 8px;">Search failed — please try again.</div>';
            }
        } 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). `total_count`
            // and `count_ms` (added #232): null/0 when the cap wasn't hit
            // or when the COUNT follow-up failed/was superseded; otherwise
            // the real result-set size and the time it took to compute.
            // `elapsed_ms` continues to mark end-of-handler so it still
            // covers SELECT+render+COUNT for end-to-end user-perceived
            // latency.
            //
            // `superseded` (added round 2 of #236): a search whose work was
            // abandoned mid-flight because the user fired a newer search.
            // The log line still emits so downstream perf analysis can see
            // how often this happens, but consumers should generally treat
            // superseded rows as best-effort (results / counts may be
            // partial and the UI never reflected them).
            try {
                console.log(JSON.stringify({
                    event: 'isamples.search',
                    id: searchId,
                    term: term,
                    terms_count: terms.length,
                    scope: effectiveScope,
                    results_count: resultsCount,
                    total_count: totalCount,
                    elapsed_ms: Math.round(elapsedMs),
                    count_ms: Math.round(countMs),
                    bytes_transfer: transferBytes,
                    bytes_body: bodyBytes,
                    seen_urls: seenUrls,
                    has_source_filter: hadSourceFilter,
                    has_facet_filter: hadFacetFilter,
                    superseded: wasSuperseded,
                    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) {}
        }
    }

    // #248 Flavor A: commit a concept-URI filter. This is the SECOND entry
    // point into the shared `search_pids` machinery — `buildConceptFilter`
    // is the producer, `applySearchFilterChange` pushes the result to every
    // surface (table / points / facet counts / globe mode), exactly as a text
    // search does. It deliberately does NOT reuse doSearch's body: doSearch
    // carries A1's text-search stale-guard + COUNT logic shipped in #251, and
    // we keep that hot path untouched (RY decision, 2026-06-01). It renders its
    // own, simpler side panel instead. Mutually exclusive with the free-text
    // search: committing a concept clears the text box and the `search=` param.
    async function doDescribedBy(uri) {
        if (!uri) return;
        // Share doSearch's freshness counter so a text search and a concept
        // filter can't clobber each other's side-panel render mid-flight.
        const searchId = ++_searchSeq;

        // Mutual exclusivity: a committed concept filter OWNS search_pids, so
        // clear the free-text box (and its sidebar mirror) before building.
        if (searchInput) searchInput.value = '';

        if (searchResults) searchResults.textContent = 'Filtering by concept…';

        // Build the pid-set. buildConceptFilter mirrors buildSearchFilter's
        // token-scoped staging + finally-drop guards and publishes the result
        // (label, total, kind:'concept', uri) on window.__searchFilter. A build
        // failure empties search_pids via clearSearchFilter (same as doSearch),
        // so downstream readers see zero rows rather than a missing table.
        let buildFailed = false;
        try {
            await buildConceptFilter(uri);
        } catch (e) {
            console.warn('#248 concept-filter build failed; surfaces stay unfiltered:', e);
            buildFailed = true;
            await clearSearchFilter();
        }
        window.a1dbg?.('concept-post-build', { searchId, searchSeq: _searchSeq, active: window.__searchFilter?.active, total: window.__searchFilter?.total });
        // Superseded during build? Bail before touching ANY shared state. The
        // winning producer owns the surfaces AND the URL (Codex finding #2: a
        // stale producer must not run writeQueryState off another's filter).
        if (searchId !== _searchSeq) return;
        await applySearchFilterChange();
        // Re-check after the async surface refresh, BEFORE writeQueryState: if a
        // newer search/concept superseded us mid-refresh, it — not this stale
        // producer — must be the one that writes the URL.
        if (searchId !== _searchSeq) return;
        // Persist `described-by=` (drops `search=`) now that __searchFilter
        // reflects this concept and we're confirmed the current producer.
        writeQueryState();

        const sf = window.__searchFilter;
        const label = (sf && sf.term) ? sf.term
            : (typeof window !== 'undefined' && window.conceptLabelForUri) ? window.conceptLabelForUri(uri) : uri;
        const total = (sf && sf.active && sf.kind === 'concept') ? sf.total : 0;

        // Sticky heading mirrors doSearch's, recolored (purple) to distinguish a
        // concept filter from a text search. `label` is usually a vocab pref
        // label, but for an unknown URI it falls back to the URI tail — i.e. it
        // can be attacker-controlled via the `described-by=` URL param. Escape
        // it before innerHTML to close the reflected-XSS path (Codex finding #3).
        // `suffix` is internal (counts) and safe.
        const safeLabel = escapeHtml(label);
        const headingHTML = (suffix) =>
            `<h4 class="search-results-heading" style="position: sticky; top: 0; z-index: 1; margin: 0 0 6px; padding: 6px 8px; background: #ede7f6; color: #5e35b1; border-radius: 4px;">Samples described by: ${safeLabel}${suffix}</h4>`;

        if (buildFailed) {
            if (searchResults) searchResults.textContent = `Concept filter failed for "${label}". Please try again.`;
            const sElF = document.getElementById('samplesSection');
            if (sElF) sElF.innerHTML = headingHTML('')
                + '<div class="empty-state" style="padding: 8px;">Filter failed to build — please try again.</div>';
            return;
        }
        if (total === 0) {
            if (searchResults) searchResults.textContent = `No samples described by "${label}"`;
            const sEl0 = document.getElementById('samplesSection');
            if (sEl0) sEl0.innerHTML = headingHTML(' (0)')
                + '<div class="empty-state" style="padding: 8px;">No samples matched this concept.</div>';
            return;
        }

        // Side-panel list: read the LIMIT-50 head straight off search_pids
        // (already built + ranked by buildConceptFilter: object_type > material
        // > context, then label), LEFT JOIN lite for coords so coord-less
        // samples still list (null lat/lng; the click handler guards on null).
        let results;
        try {
            results = await db.query(`
                SELECT s.pid, s.label, s.source, l.latitude, l.longitude,
                       s.place_name, s.relevance_score
                FROM search_pids s
                LEFT JOIN read_parquet('${lite_url}') l USING (pid)
                ORDER BY s.relevance_score DESC, s.label
                LIMIT 50
            `);
        } catch (err) {
            if (searchId !== _searchSeq) return;
            console.error('#248 concept side-panel query failed:', err);
            if (searchResults) searchResults.textContent = `Concept filter error: ${err.message}`;
            return;
        }
        if (searchId !== _searchSeq) return;

        const shown = results.length;
        const ofTotal = total > shown ? `${shown} of ${total.toLocaleString()}` : `${shown}`;
        if (searchResults) searchResults.textContent = total > shown
            ? `${shown} of ${total.toLocaleString()} samples described by "${label}"`
            : `${shown} sample${shown === 1 ? '' : 's'} described by "${label}"`;

        const sampEl = document.getElementById('samplesSection');
        if (sampEl) {
            let h = headingHTML(` (${ofTotal})`);
            for (const s of results) {
                // Escape every interpolated value (Codex finding #3): label/pid
                // come from the parquet, color/name from controlled maps, sUrl
                // into an href attribute — escapeHtml handles both text and
                // attribute contexts (it escapes quotes). lat/lng are numeric.
                const color = escapeHtml(SOURCE_COLORS[s.source] || '#666');
                const name = escapeHtml(SOURCE_NAMES[s.source] || s.source);
                const sUrl = sourceUrl(s.pid);
                const labelText = escapeHtml(s.label || s.pid);
                const pidAttr = escapeHtml(s.pid || '');
                h += `<div class="sample-row" style="cursor: pointer;" data-lat="${s.latitude}" data-lng="${s.longitude}" data-pid="${pidAttr}">
                    <div style="display: flex; align-items: center; gap: 6px;">
                        ${sUrl ? `<a class="sample-label" href="${escapeHtml(sUrl)}" target="_blank" rel="noopener noreferrer" style="color: #1565c0; text-decoration: none;">${labelText}</a>` : `<span class="sample-label">${labelText}</span>`}
                        <span class="source-badge" style="background: ${color}; font-size: 10px;">${name}</span>
                    </div>
                </div>`;
            }
            sampEl.innerHTML = h;

            // Click a concept-result row → same full selection ceremony as a
            // text-search row (freshness bump, card hydration, flight, lazy
            // detail) so a slow prior load can't repaint over the navigation.
            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;

                    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
                    });
                    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("Concept-row detail query failed:", err);
                        updateSampleDetail(null);
                    }
                });
            });
        }

        // Fly to the first LOCATED result (a nudge, not a selection — clear any
        // prior pid/h3 so the URL doesn't carry stale selection across flight).
        // Mirrors doSearch's world-scope auto-flight.
        const firstLocated = results.find(r => r.latitude != null && r.longitude != null);
        if (firstLocated) {
            viewer._globeState.selectedPid = null;
            viewer._globeState.selectedH3 = null;
            viewer.camera.flyTo({
                destination: Cesium.Cartesian3.fromDegrees(firstLocated.longitude, firstLocated.latitude, 200000),
                duration: 1.5
            });
        }
    }
    // Expose for the boot trigger + debug console (mirrors window.conceptLabelForUri).
    if (typeof window !== 'undefined') window.doDescribedBy = doDescribedBy;

    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);
        }
    });

    // (#266) Sidebar search box removed — the in-map #sampleSearch overlay is
    // the single canonical search input. The former sidebar mirror is gone.

    // #248 Flavor A boot: a `described-by=<concept-uri>` deep link commits the
    // concept filter. It WINS over `search=` if a hand-crafted URL carries both
    // (they're mutually exclusive; doDescribedBy clears the text box + param).
    const _describedByUri = new URLSearchParams(location.search).get('described-by');
    if (_describedByUri) {
        doDescribedBy(_describedByUri);
    } else 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 });
    }

    // #267: a shared `?material=`/`?context=`/`?object_type=` deep link must
    // force point mode like `?search=` does — cluster H3 summaries can't honor
    // those facets. The altitude-gated trigger above won't promote a high-alt
    // facet deep link, so enter point mode directly. We read the URL params
    // (not the hydrated checkboxes) so this is independent of facet-loader
    // timing; the latch points (targetMode / moveEnd / wantsPoint) keep it
    // pinned once the checkboxes hydrate.
    const _urlHasFacets = ['material', 'context', 'object_type'].some(p => {
        const v = new URLSearchParams(location.search).get(p);
        return v != null && v.trim() !== '';
    });
    if (_urlHasFacets && getMode() !== 'point') {
        await enterPointMode(false);
    }

    // #233 phase 1: hydrate heatmap overlay from `heatmap=1` URL param.
    // Reported by RY 2026-05-27 on PR #240 staging — toggle state was
    // missing from "Copy Link to Current View." `refreshHeatmap()` lives
    // in a different OJS cell and isn't reachable from here; dispatch a
    // 'change' event so the existing change-listener picks it up.
    if (ih.heatmap) {
        const toggle = document.getElementById('heatmapToggle');
        if (toggle && !toggle.checked) {
            toggle.checked = true;
            toggle.dispatchEvent(new Event('change', { bubbles: true }));
        }
    }

    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